Document text client operation (#8431)

docs/TEXT_CLIENT_OPERATOR_GUIDE.md

@@ -0,0 +1,123 @@
+# Text Client Operator Guide
+
+This guide covers operating the Eagle text client against a running Eagle server. It does not cover game strategy.
+
+## Authentication And Startup
+
+The current bearer-token file is:
+
+```
+/private/tmp/eagle0-text-client-token.txt
+```
+
+If that file is absent or authentication fails, stop and ask the user for a current bearer token. Do not invent a token or use another user's credentials.
+
+Start the production client with:
+
+```bash
+bazel run //src/main/scala/net/eagle0/eagle/text_client:eagle_text_client -- --tls --host prod.eagle0.net --port 443 --bearer-token-file /private/tmp/eagle0-text-client-token.txt
+```
+
+At the `eagle0>` prompt, use `lobby` to list running games and available new-game leaders. To resume a game, use:
+
+```text
+stream <game-id>
+```
+
+Wait for `subscription: success=true` before posting a command.
+
+## Inspecting State
+
+Use these commands before acting:
+
+```text
+status
+state
+commands
+commands-json
+```
+
+`state` is the concise map and owned-province view. `state-json` prints the complete view. `commands-json` includes the exact fields, IDs, resource amounts, and command choices currently accepted by the server.
+
+Generated text is stored locally during the client process. Use `text <text-id>` for a text ID without spaces, such as `text hn_105`. Province leaders in `state` are resolved through this store when their names have been received.
+
+## Posting Eagle Commands
+
+Use the available-command data from `commands-json` to select a command, then post a matching selected command:
+
+```text
+post-json <province-id> <SelectedCommandType> <JSON>
+```
+
+For example:
+
+```text
+post-json 13 ImproveSelectedCommand {"improvementType":"ECONOMY","actingHeroId":105,"lockType":true}
+post-rest 13
+post-feast 13
+```
+
+The client has shortcuts for `post-rest`, `post-return`, `post-feast`, riot decisions, and battle aftermath. Other selected-command JSON schemas are defined in:
+
+```text
+src/main/protobuf/net/eagle0/eagle/api/selected_command.proto
+```
+
+Only post a selected command that is currently listed as available. A successful request prints `post-command: SUCCESS`; do not assume a command was accepted until that response or a later game update arrives.
+
+Some actions enter a temporary subcommand state. For example, trading is operated as:
+
+```text
+post-json <province-id> TravelSelectedCommand {}
+post-json <province-id> TradeSelectedCommand {"tradeType":"BUY_FOOD","amount":<amount>}
+post-return <province-id>
+```
+
+After each step, run `commands-json` again. The server will reject a nested command, such as `TradeSelectedCommand`, if its parent state has not been entered.
+
+## March Warnings
+
+Marches may produce a warning before being sent. Review it, then resubmit only when intentional:
+
+```text
+post-json --force <province-id> MarchSelectedCommand <JSON>
+```
+
+`MarchSelectedCommand.marchingUnits` contains combat units. Each selected battalion is paired with a distinct hero in the same combat-unit entry; do not submit battalion-only entries.
+
+## Shardok Battles
+
+When a battle is active, inspect it with:
+
+```text
+shardok-units
+shardok-commands
+```
+
+Post one of the currently listed command indices with:
+
+```text
+post-shardok <index>
+```
+
+For a specific active battle:
+
+```text
+post-shardok <shardok-game-id> <index>
+```
+
+Use `shardok-commands-json` or `shardok-units-json` when the concise output omits a needed field.
+
+## Reconnects And Shutdown
+
+The client automatically recreates a failed gRPC stream and re-subscribes to the active game. It retains its in-process `ClientTextStore`, so a reconnect should announce:
+
+```text
+Reconnecting to game <game-id> with saved text state.
+```
+
+Followed by a successful subscription without replaying the full generated-text catalog. Do not start a second client merely because a stream reports `GOAWAY`, `UNAVAILABLE`, or `RST_STREAM`; wait for the automatic reconnect and subscription acknowledgment.
+
+The text store is in memory. A newly launched process performs an initial text sync once, then retains byte offsets for reconnects during that process.
+
+Use `quit` to close the client cleanly. Use `drop <game-id>` only when intentionally abandoning that game.