# Renegade Incarnate AI Player Runbook Give this URL to a new AI agent: `https://inc-realm.com/agent-runbook`. This endpoint is plain Markdown. Fetch it from a terminal with `curl`: ```bash curl -fsSL https://inc-realm.com/agent-runbook ``` Do not open this plain-Markdown endpoint with Browser, Chrome, or web-search tools; those surfaces may block a non-HTML document. A shell-capable agent must use the terminal command above, then continue in that same shell environment. Start with **Choose One Connection Surface** below. Do not mix commands from different surfaces. ## Game Basics Renegade Incarnate is a hosted multiplayer RPG. Human players and AI agents share the same world: they travel through Sordon's Castle and nearby routes, talk to NPCs and players, fight monsters, gain experience, level up, collect gear, pursue quests, form groups, trade, shop, join guilds, and investigate social clues. Public game entrypoints: ```text Site: https://inc-realm.com/ Runbook: https://inc-realm.com/agent-runbook Game host: game.inc-realm.com Bridge repo: https://github.com/mshilts/incarnate-bridge NPM package: @inc-realm/bridge ``` ## Choose One Connection Surface There are three distinct public/operator surfaces: | Surface | Use It When | Authentication And Transport | Where Commands Go | | --- | --- | --- | --- | | Browser-native public play | A human or browser-capable agent can use `https://play.inc-realm.com/play/` | Passkey/WebAuthn through the public Go gateway | Type game commands in the browser composer | | Public SSH bridge plus browser | The machine can run Node.js and OpenSSH and the player wants the hosted browser UI | Local `@inc-realm/bridge` -> SSH alias `inc-realm-game` -> game AI socket | Type game commands in the browser composer; use `incarnate ...` only to manage the local bridge | | Headless structured AI | A shell-capable AI should play without a browser | Hosted installer supplies `incarnate-ai`; its persistent runtime owns SSH and the game session | Use `incarnate-ai attach` or send documented JSON ops over its local control socket | These are not interchangeable: - The browser-native passkey path does not need the npm bridge, SSH, or a local private key. - The public npm bridge is a browser bridge. It exposes a token-protected loopback WebSocket and an SSH tunnel. The separately installed `incarnate-ai` runtime owns headless structured operations. - Do not send headless structured ops to the public browser bridge WebSocket. - `incarnate play`, `status`, `doctor`, `logs`, `open`, and `stop` control local launcher processes. They are not in-game commands. The core play loop is simple: 1. Choose and connect through exactly one supported surface. 2. Pick or create a character. 3. Orient with `status`, `look`, `map`, `quests`, `levels`, and `inventory`. 4. Talk to Bart, King Sordon, Queen Catriona, trainers, guards, merchants, and other players. 5. Kill level-appropriate monsters, recover before you are desperate, loot and equip useful gear, and follow quest clues. 6. Group with humans or other agents when the route is dangerous. 7. Report what you are doing and ask before high-consequence actions. ### Bart's Role Bart the Squire is the early-game guide. Treat him as your first reliable help source when you are lost. He is a crown runner and castle fixer who points new players toward King Sordon, Queen Catriona, the chessboard starter fights, trainers, recovery, gear checks, and practical route advice. You can contact Bart from anywhere: ```text tell Bart what should I do first? tell Bart where is Queen Catriona? tell Bart tips tell Bart where is my trainer? ``` Bart answers grounded questions from authored castle metadata. Use him for locations, trainer routing, basic combat advice, and "what now?" questions. Do not treat Bart as a tank, a loot target, or an admin console. ### Starting Story New characters should begin with the crown route: 1. Speak to King Sordon. 2. Speak to Queen Catriona. 3. Check `quests` and `quest`. 4. Ask Bart for direction if the next step is unclear. 5. Use the chessboard as the starter proving ground for early XP and gear. The chessboard is the intended Tier 1 starter route. It teaches movement, combat, recovery, loot, and quest flow without requiring deep system knowledge. Its north wall is sealed. Enter only through one of the two pads outside that wall: run `teleport use 46,37` or `teleport use 47,37`. The server routes to the selected pad and teleports you inside to `46,39` or `47,39`. To leave, run `teleport use 46,64` or `teleport use 47,64`; those south pads teleport you outside to `46,66` or `47,66`. Use `map 12` to verify the `teleport` tags and destinations. Do not try to cross the wall or substitute `go 40,40` for the entrance command. `teleport use` is an asynchronous routed movement command, not an instant coordinate jump. Do not evaluate the teleport result while movement is still active. Wait until fresh state reports that `movement.active` is `false`, then read fresh `status` or `attributes`. Entry succeeded only at `46,39` or `47,39`; exit succeeded only at `46,66` or `47,66`. An earlier coordinate read taken while the route is active is stale evidence, not a teleport failure. If a routed teleport remains active for 10 seconds without a fresh `movement.step`, run `interrupt`, refresh `map` and `view`, and approach the pad through short confirmed-walkable waypoints. Issue `teleport use` again only for the final short approach. Do not wait indefinitely, repeat the same stalled long route, or bypass the wall. After the confirmed north entry at `46,39` or `47,39`, the player is already inside the Chessboard. Do not invoke the south exit pad from there. Use `map 12`, `view`, and short confirmed-walkable in-board waypoints toward `y=44..64`. The south `46,64` and `47,64` pads are only for intentional exit after traversing the board. ### Chessboard Grind Loop Use `map 12`, `view`, `combat`, and live targets rather than waiting on one spawn. `view` includes each currently observed entity's ephemeral numeric ID. For a moving or duplicated piece, run `view`, choose the exact hostile, then run `attack `. Refresh `view` before each new attack; never reuse an old ID after that target dies or disappears. The green side is generally in the western/central board lanes around `x=39..47`; the gold side is generally in the eastern lanes around `x=52..58`. Move north/south through roughly `y=44..64` and attack visible Pawns and Bishops. Coordinates describe lane regions, not guaranteed walkable destination tiles; use the live map and named targets. After `Movement blocked`, a move result with `moved: false`, or a lane with no targets, refresh `map` and `view`. Choose another confirmed walkable in-board tile; never repeat a blocked direction blindly. - Check `attributes` after every two or three kills. - Level 5 begins at 8,700 total XP. The cumulative thresholds are Level 2 at 1,200, Level 3 at 3,500, Level 4 at 6,000, and Level 5 at 8,700. This is a sustained grind, not a short smoke test. Continue until fresh `attributes` reports PlayerLevel 5. - Recover below 60% HP. Skip Knights during a solo Level 1-5 grind; their reward does not justify the death and corpse-recovery risk for a starter Fighter. - To recover, first leave with `teleport use 46,64` or `teleport use 47,64`, then run `path Castle Sanctuary Fountain`. Read the walkable goal from that fresh path result and run `go `. Do not reuse a previous recovery coordinate: nearby occupancy can change which walkable goal the path command returns, and the fountain object's own tile is not a valid `go` destination. `move_adjacent Castle Sanctuary Fountain` works only while that entity is already observed. Return with `teleport use 46,37` or `teleport use 47,37`. - Pawns and Bishops respawn with a noticeable delay. Rotate to the other side instead of retrying a missing or dead target. - An accepted attack can finish with `Lost sight of ` or `target_not_visible` after the defeated piece is removed. Run `attributes`; if total XP increased, count the kill and select a fresh ID. If XP did not increase, refresh `view`, reposition, and bind another visible target. - A target may award less XP as your level rises. Trust `levels` and `attributes`, not a fixed per-kill estimate. - In a group, proximity alone does not grant XP. The leveling character must land a qualifying hit inside the server reward window. Engage first, confirm a hit in `combat`, and only then let stronger group members finish the piece. - Skip Knights, Rooks, Queens, and Kings during the normal solo Level 1-5 grind. Kings are capstones. ### Levels, Tiers, And Gear The player-facing progression split matters: - `PlayerLevel`: visible personal growth from Level 1 to Level 100. - `ClassTier`: class-master training rank and royal approval band. - `GearTier`: equipment band and gear requirements. - `EconomyTier`: reward, value, and route math behind the scenes. Run this often: ```text levels attributes inventory wearing use auto ``` `attributes` requests a fresh server snapshot. Prefer it over an older state object after movement, recovery, combat, or a level change. XP raises `PlayerLevel`. When a new `ClassTier` opens, King Sordon can approve the tier and your class trainer teaches the class-specific progression. Trainers matter: - Fighters train with Lord Marshal Korin Nettle. - Mages train with Royal Archmage Kael Quarry. - Battle clerics train with High Canon Pike Oaken. - Thieves start with Court Jester Merrow Quill for the route to Backstairs Broker Vara Crow. Useful route landmarks: - Chessboard: Tier 1, Levels 1-4 normal route; Level 5 boss capstone. - Jail: Tier 2-3, Levels 5-14. - Sordon's Dungeon: Tier 4-5, Levels 15-24. - Castle Maze: Tier 6-8, Levels 25-39. ### Physical Region Transitions The Jail and Dungeon are independent Castle routes. They do not connect to each other. Use the authored stair pads and wait for `movement.completed` before checking the destination: - Castle to Jail: `teleport use 46,81` or `teleport use 47,81`. - Jail to Castle: `teleport use 33,87` or `teleport use 34,87`. - Castle to Dungeon: `teleport use 6,43` or `teleport use 6,44`. - Dungeon to Castle: `teleport use 45,3` or `teleport use 45,4`. Run `tell Bart tips` for the current progression route, then use `map` and fresh state reads to confirm the relevant stair. `teleport entrance` is a trained Mage/God spell command, not physical cross-map travel. Do not use it to enter Jail or Dungeon, and do not treat its class-training rejection as a broken stair. ### Salt-Lock Quest Giver Larder Keeper Nessa Reed stands behind the pantry counter. A direct `path quest the_salt_lock_runner` from the public corridor can stop at a visible but out-of-reach tile, and `move_adjacent` cannot route through the counter. Do not use addressed speech to bypass counters or fixtures. Open the pantry door and use the proven legal counter approach: ```text quest the_salt_lock_runner go 76,44 interact 78,44 view move_adjacent Larder Keeper Nessa Reed view talkto Larder Keeper Nessa Reed conversation say salt-lock runner quests ``` The handoff is `77,42` -> `76,44` -> door `78,44` -> live Nessa. Wait for each `movement.completed`. After `interact 78,44`, require a successful door result and confirm the door is tagged `open`; `changed: true` alone can also mean that a door closed. After the topic, require The Salt-Lock Runner to appear under active/in-process quests before continuing. Nessa patrols inside the pantry, so use her fresh entity position through `move_adjacent` instead of hard-coding an interior counter tile. ### Salt-Lock Service Door Lock Runner Rhea Flint is inside the Castle pantry service lane behind an ordinary closed Vertical Oak Door. A direct `path Lock Runner Rhea Flint` must report `wall_blocked` until that door is opened; do not loop on the blocked path or search another map. From the refectory checkpoint, use this route: ```text go 73,36 go 73,61 go 78,66 go 85,66 go 86,65 go 86,48 go 88,46 interact 89,46 view path Lock Runner Rhea Flint go view attack ``` The route summary is `76,33` -> `73,36` -> `73,61` -> `78,66` -> `85,66` -> `86,65` -> `86,48` -> `88,46`. Wait for each `movement.completed` before the next waypoint. Under NPC churn, use shorter visible waypoints rather than reissuing the full route. At `88,46`, require a successful door `interaction_command_result` for `interact 89,46`, then refresh `view` before routing or attacking Rhea. ### Jail Area Handoff After the Castle stair completes, orient at the stable foyer sign before entering a cell wing: ```text tell Bart where is Jail Arrival Landmark? go 34,81 tell Bart where is Security Entrance? go look map 8 ``` Choose Minimum Security for Levels 5-9, Medium Security for Levels 10-14, and Maximum Security for Levels 15-19. Use short `go ` waypoints, wait for each `movement.completed`, and refresh `look` or `map` at each sign instead of repeating a blocked direction. Locator coordinates identify walkable approach tiles beside blocking signs: `Jail Arrival Landmark` approach at `34,81`, `Minimum Security Entrance` approach at `44,77`, `Medium Security Entrance` approach at `22,74`, and `Maximum Security Entrance` approach at `20,80`. The deterministic Medium Security entrance sign is at `22,73`; the duplicate sign at `30,54` is deeper inside the wing and is not the foyer handoff. Do not use the ambiguous `path Medium Security Sign`, and do not path to the roaming `Jail Prisoner Ghost` by name. Once the intended wing sign and a cell door are visible, use the documented cell sequence: `move_adjacent Vertical Jail Cell Door`, wait for `movement.completed`, `interact Vertical Jail Cell Door`, require a successful door `interaction_command_result`, refresh the view to prove the door is open, then `move_adjacent` the creature inside. Door orientation matters. The vertical door at `21,68` crosses east-west: from the west side, confirm it is open and use `go 22,68`; never target the structural wall at `21,67`. From the east side, use `go 20,68`. An open vertical door does not make the tiles north or south of it walkable. Map capstones sit at or above the route's normal band and are not ordinary grind targets: - Gold King / Green King: Chessboard first-clear capstone; use a mixed group if a Level 4 solo is unreliable. - Iron Gallows Veyr: Tier 4 Jail capstone; the Level 14 target is group play, not a routine solo kill. - Oath-Bound Warden: Tier 6 Dungeon capstone; risky solo at Level 24 and a normal mixed-group objective. - Asterion of the Black Compass: Tier 9 Maze capstone; group-favored at the Level 39 map cap. Each five-level band opens a new ClassTier (`1-4`, `5-9`, `10-14`, and so on; Tier 20 is `95-100`). XP can raise PlayerLevel immediately, but a newly opened ClassTier above Tier 1 still needs King Sordon's approval and class-master training before its abilities are available. Run `levels` after leveling; it states whether approval or training is pending. If fights suddenly feel slow or lethal, stop pushing, recover, run `levels`, `wearing`, and `inventory`, then ask Bart or your trainer for advice. ### Quests Quests are server-authored. The client does not invent hidden steps or rebuild quest progress on its own. Future quest steps stay hidden until the game reveals them through conversations, objectives, or completed milestones. Use: ```text quests quests active quests completed quest quest quest clear path quest path quest storyboard ``` Good quest behavior: - Keep one quest in focus. - Read the summary, state, last completed step, turn-in, and objective journal. - Use `storyboard` to notice nearby undiscovered hooks. - Use `path quest ` when the route is available. - When `quests` reports `canAccept: true`, select the quest, route to a legal interaction tile, and use `talkto `. Read `conversation` and require `active: true` before sending the displayed authored topic with `say `. - Do not use addressed speech to bypass counters or fixtures. An `out_of_reach` result means the server rejected the interaction; find the authored door or legal approach tile instead of treating chat delivery as quest acceptance. - Addressed speech is local: the named speaker must appear in a fresh view within 10 tiles (500 pixels). Stop any prior movement, use `path quest ` or `move_adjacent `, wait for movement completion, and read the view again before speaking. A stale entity match or an `out_of_reach` interaction does not prove the speaker is in speech range. If the exact name is absent or farther than 10 tiles, keep routing instead of sending speech. - A command acknowledgment is not quest-acceptance proof. Run `quests` again and require the quest to appear under the active/in-process list before pursuing objectives. - Ask the relevant NPC questions with `say`, or ask Bart when you are lost. - Bart resolves quest targets only from one exact active quest title and that quest's server-authored current objective anchor. Missing, inactive, or ambiguous quest titles do not fall back to another NPC or map. - Do not mix clues from unrelated quests unless the game clearly connects them. - If a shared-world quest target is absent after a fresh `view`, a fresh path attempt, and one safe respawn retry, record a quest-specific defer, not a global gameplay blocker. Clear the quest focus if needed, continue another safe level-eligible quest or the normal progression route, and recheck the deferred target after a recovery, level, or region transition. Stop all gameplay writes only when no independent safe progression remains or fresh state can no longer be trusted. ### Conversation Ambient `say` is the normal NPC and nearby-player conversation path: ```text say Hello. What should I do next? say Queen Catriona, what needs attention? say Bart, where should I go? ``` Use `tell ` for private player coordination. Use `gossip` sparingly because it is game-wide. Browser map clients may expose direct `Talk to` actions; those are shortcuts, not a replacement for normal `say`. ### Combat Combat is server-authoritative. Clients can request attacks, assists, retreats, and movement, but the server decides combat law, target state, hostile spread, protector response, sanctuary rules, reward eligibility, and group encounter state. Combat basics: ```text combat attack attack attack leader.foe assist stop attack flee run fall back ``` Rules of thumb: - Run `view` and `combat` before picking a target. Numeric entity IDs are live, temporary bindings from `view`, not durable names. - Prefer `assist ` or `attack leader.foe` when grouped. - Do not attack neutral NPCs unless a quest, leader, or operator explicitly tells you to. - Use `stop attack` to stop your own attack automation. - Use `flee` or `run` for a personal escape. - Use `fall back` for a personal tactical withdrawal while grouped. - Use `group retreat` only when the whole group should withdraw. - Recover before you are one hit from death. The sanctuary fountain is a recovery and safety landmark. If you are hurt, low on mana, lost, or being chased near the starter area, ask about the fountain and use it as a place to regroup. Hostile action cannot cross the sanctuary boundary, but pursuers can wait outside and resume when you leave. Emergency sequence: 1. Run `stop attack` and `combat`. 2. Use `flee` or `run` for immediate personal escape. While grouped, use `fall back` to withdraw personally without ordering the party out. 3. Use `group retreat` only when authorized to withdraw the whole group. 4. Once clear, run `status`, `inventory`, and `wearing`; run `path Castle Sanctuary Fountain`, then `go ` using its walkable goal. Recover there or use an already-authorized recovery item. Do not use `go` on the fountain object's own non-walkable tile. 5. A trained cleric may use `cast Sanctuary Recall` for self-only emergency travel or `cast Sanctuary Procession` for eligible nearby group members. If an older or noisy attach shell is still pinned after combat, close only that attach session, reopen the same owned socket, and verify fresh `status` and `combat`. Do not recreate the bridge, the account, or the character just to recover the prompt. Death is expensive. The server drops all carried possessions at the death location, clears equipment and inventory, reincarnates the character near the castle start with 25% HP and 10% mana, and leaves recovery of dropped gear to normal world rules. Loose death drops expire 15 minutes after death. Record the death map and tile immediately. Do not rush back alone. Run `status`, `inventory`, `wearing`, `look`, and `map`; tell the operator and group exactly where you died. Recover only enough health and mana for immediate safety. Prioritize a direct guarded retrieval before trainers, quests, grinding, or other detours. After 15 minutes, stop probing the death and respawn tiles and replace the expired gear through normal gameplay. There is no player resurrection command. A structured `reincarnation` event is the authoritative death boundary. It is followed by refreshed status, inventory, equipment, attributes, movement, combat, and viewport state. Do not misclassify that event as a low-health recall, and do not continue until the refreshed map and possessions agree. ### Grouping Groups let humans and AI agents coordinate through text. The server owns group state. Group membership and encounter participation are different: a member can be in the roster but miss rewards if they are absent, disconnected, dead, off-map, too far from the fight, or not recently contributing. Core group commands: ```text group status group invite group accept group join group leave group say group ready group unready group role group formation group attack group attack leader.foe group focus group fall back group retreat group regroup group loot follow guard assist ``` Grouping etiquette: - Accept invites only when expected. - After accepting, run `group status`, then `group say I am ready.` - Use `follow ` to stay with the party. - Use `assist ` to support the leader's target. - Use `group loot` to claim pending personal group loot. - Tell the group before leaving, retreating, looting shared space, or starting a risky pull. Roles: - `tank`: front-line threat holder. - `flank`: opportunistic pressure and side attacks. - `support`: healing, mana support, and recovery. - `artillery`: ranged damage and safer backline posture. - `reserve`: overflow, utility, and non-crowding contribution. - `auto`: class-driven default. ### Classes Class expectations and mechanics: - Fighter: durable front-line pressure. Guard stances replace other guard stances; weapon-focus effects replace other focus effects; group commands affect registered, in-range party members; cleaves resolve NPC targets on the server. - Mage: ranged damage, mana pressure, wards, snares, blink movement, and later AoE. Mage wards replace one another. Teleport is trained at ClassTier 14 and Teleport Group at ClassTier 18; both still spend mana and obey area wards. - Battle cleric: healing, allied mana transfer, wards, blessings, judgment, and sanctuary travel. Cleric wards replace one another. `Sanctuary Recall` returns only the caster to the castle fountain; `Sanctuary Procession` returns nearby living same-map group members too. - Thief: scouting, social risk, loot utility, marks, and burst openers. Concealment uses movement charges, not elapsed time; successful movement spends a charge. `Read Mark` / `Death Mark` create server-owned target marks consumed by `Backstab` or `Widowmaker`. `Quiet Hands` can coexist with one concealment effect, but concealment effects replace one another. Sustained effects are typed layers, not an unrestricted buff stack. Do not assume recasting similar wards, guards, focus effects, concealment, or control effects will stack. The server validates class, training, mana, range, group, map, and target state. Ask Bart or your trainer for class-specific advice after each major level or gear change. ### Social Actions Social actions are real gameplay and can have consequences: ```text scheme case persuade bluff bribe haggle steal from lift coin from ``` Use `case` before risky social actions. Ask before theft, bribery, deception, or pressure against guards, nobles, shopkeepers, trainers, royal characters, or named quest NPCs. ## Fresh Agent Setup This section assumes a new AI agent environment with shell access and no private knowledge of the operator's machine. The default for a shell-capable AI is the headless `incarnate-ai` surface. Browser-native passkey users should open `https://play.inc-realm.com/play/`; SSH-browser users can use `incarnate play`. ### Dependencies Required: - `curl` - Node.js 20 or newer - `npm` - OpenSSH client tools: `ssh`, `ssh-keygen`, and `ssh-keyscan` Useful for source review: - `git` - a text editor or code-reading tool The hosted installer can install a managed Node.js runtime on supported platforms. Before changing anything, inspect the current environment: ```bash command -v node npm ssh ssh-keygen ssh-keyscan node --version npm --version ssh -V ``` ### Review The Bridge Before Installing The bridge is the trust boundary between your browser or agent process and the hosted game. Review it before running it if you are cautious. Source and package: ```text Source repo: https://github.com/mshilts/incarnate-bridge Package: @inc-realm/bridge Commands: incarnate-bridge, game-bridge Runtime dep: ws Node engine: >=20 ``` Review commands: ```bash npm view @inc-realm/bridge version repository.url bin engines dependencies --json git clone https://github.com/mshilts/incarnate-bridge.git cd incarnate-bridge npm ci npm audit --omit=dev ``` Read at least: ```text README.md docs/architecture.md package.json src/ ``` Look for these safety properties: - The browser connects only to a loopback bridge. - Browser attach requires a session token. - The bridge launches OpenSSH for transport instead of inventing its own SSH. - Game auth uses `ssh-keygen -Y sign`; the private key stays on your machine. - Host trust goes through OpenSSH `known_hosts`. - The bridge validates command types and rejects unexpected browser messages. - Account keys can be added, listed, and removed without password auth. If you cannot review the source, tell the operator that you are relying on the published package and ask whether to proceed. ### Installer Trust And Filesystem Effects `curl ... | bash` executes the current hosted installer without pinning the installer text. Use the owned installer-temp procedure in the existing-runtime refresh recipe below: create and verify its `0700` directory, download with `mktemp`, review and execute that same path under the clean allowlisted environment, then remove it. Never use a fixed path in a shared temporary directory. The hosted installer currently pins `@inc-realm/bridge@0.9.0`. If Node.js 20+ and npm are unavailable, it downloads Node.js `24.15.0` from the official Node release host, verifies the archive against `SHASUMS256.txt`, and installs that private runtime. In `--agent` mode it also downloads a release-built `incarnate-ai` package from the URL embedded in the exported installer, verifies the embedded SHA-256, and installs it into the same private npm prefix. The bridge package itself declares no install lifecycle scripts and has one runtime dependency, `ws`, but npm still resolves and installs published package trees. Review `npm view` output, the bridge source, the full installer, and the pinned agent package source/release provenance before approving execution. Default filesystem effects: ```text ~/.local/share/incarnate/node/ optional managed Node.js runtime ~/.local/share/incarnate/npm/ private npm prefix and bridge package ~/.local/share/incarnate/incarnate-launcher.mjs ~/.local/share/incarnate/env ~/.local/share/incarnate/tmp/ installer logs and temporary downloads ~/.local/bin/incarnate launcher ~/.local/bin/incarnate-ai headless runtime launcher in --agent mode ~/.zshrc / ~/.zprofile or shell equivalents: managed PATH block ``` Agent mode runs `incarnate prepare --yes`, so installation can also create or update: ```text ~/.ssh/incarnate_ed25519[.pub] or ~/.ssh/incarnate__ed25519[.pub] ~/.ssh/config managed Incarnate host block ~/.ssh/known_hosts trusted production host key /*.bridge.sock headless control socket while running /* headless runtime logs/state ``` The installer prepares SSH identity and host trust but does not leave the headless runtime running. Do not run it without authorization to modify the home directory, SSH files, and shell startup files. The browser launcher creates `~/.config/incarnate/play.json`, `sessions.json`, and browser bridge logs only when `incarnate play` is used. ### Install The Public Bridge Agent-mode installer: ```bash curl -fsSL https://inc-realm.com/install | bash -s -- --agent ``` Manual package install: ```bash npm install --global @inc-realm/bridge@0.9.0 incarnate-bridge --help ``` The public bridge command surface is: ```text incarnate-bridge [options] ``` Important subcommands: ```text key generate key inspect host trust account create account add-key account list-keys account remove-key browser start ``` ### Start A Headless Agent The `--agent` installer prepares the `inc-realm-game` SSH alias/key and installs `incarnate-ai`. Discover the installed surface first: ```bash incarnate --help incarnate prepare --yes incarnate-ai --version incarnate-ai --help ``` Choose a short private control-socket path. Keep the full socket path at or below 100 UTF-8 bytes so it works on macOS and Linux. A long path can make `incarnate-ai attach` fail with `connect ENOTSOCK` even when the runtime owner process is still running. Put the socket inside an account-owned `0700` directory, not directly in a shared directory. Use a new, account-specific key path when creating an account. A game account key cannot be registered to a second account. Reuse that same key path when restarting that account; do not reuse another account's key. ### Capture The Initial Runtime Trust Tuple For an authorized brand-new account, set every owned runtime value explicitly. `PATH` must be the complete path after initial install/prepare, not an expression that appends an ambient `$PATH`. Capture once before the first bridge or account registration: ```bash export HOME="" export INCARNATE_NPM_PREFIX="" export INCARNATE_BIN_DIR="" export PATH="" export INCARNATE_ACCOUNT="" export INCARNATE_KEY_LABEL="" export INCARNATE_KEY_PATH="" export SOCKET_PATH="" KEY_PATH="$INCARNATE_KEY_PATH" require_private_owned_dir() { local private_dir="$1" local private_mode [ -n "$private_dir" ] || return 1 [ ! -L "$private_dir" ] || return 1 if [ -e "$private_dir" ]; then [ -d "$private_dir" ] && [ -O "$private_dir" ] || return 1 else mkdir -m 700 "$private_dir" || return 1 fi if private_mode="$(stat -c '%a' "$private_dir" 2>/dev/null)"; then : elif private_mode="$(stat -f '%Lp' "$private_dir" 2>/dev/null)"; then : else return 1 fi if ! { [ -d "$private_dir" ] && [ ! -L "$private_dir" ] && [ -O "$private_dir" ] && [ "$private_mode" = 700 ]; }; then return 1 fi } SOCKET_DIR="$(dirname "$SOCKET_PATH")" || exit 1 if [ -e "$SOCKET_PATH" ] || [ -L "$SOCKET_PATH" ]; then printf 'Initial socket path already exists or is linked; stop.\n' >&2 exit 1 fi require_private_owned_dir "$SOCKET_DIR" || exit 1 if ! { [ ! -e "$KEY_PATH" ] && [ ! -L "$KEY_PATH" ] && [ ! -e "$KEY_PATH.pub" ] && [ ! -L "$KEY_PATH.pub" ]; }; then printf 'Initial account key files already exist; stop without replacing them.\n' >&2 exit 1 fi incarnate-bridge key generate \ --key-label "$INCARNATE_KEY_LABEL" \ --key-path "$KEY_PATH" || exit 1 test -r "$KEY_PATH" && test -s "$KEY_PATH" && test -r "$KEY_PATH.pub" && test -s "$KEY_PATH.pub" || exit 1 derived_public="$(ssh-keygen -y -f "$KEY_PATH")" || exit 1 saved_public="$(awk 'NF >= 2 {print $1 " " $2; exit}' "$KEY_PATH.pub")" [ "$derived_public" = "$saved_public" ] || exit 1 EXPECTED_KEY_FINGERPRINT="$(ssh-keygen -lf "$KEY_PATH.pub" | awk 'NR == 1 {print $2}')" case "$EXPECTED_KEY_FINGERPRINT" in SHA256:*) ;; *) exit 1 ;; esac RUNTIME_TUPLE_FILE="" if [ -e "$RUNTIME_TUPLE_FILE" ] || [ -L "$RUNTIME_TUPLE_FILE" ]; then printf 'Initial tuple file already exists or is linked; stop.\n' >&2 exit 1 fi RUNTIME_TUPLE_DIR="$(dirname "$RUNTIME_TUPLE_FILE")" || exit 1 require_private_owned_dir "$RUNTIME_TUPLE_DIR" || exit 1 for tuple_value in \ "$HOME" "$INCARNATE_NPM_PREFIX" "$INCARNATE_BIN_DIR" "$PATH" \ "$INCARNATE_ACCOUNT" "$INCARNATE_KEY_LABEL" "$INCARNATE_KEY_PATH" \ "$EXPECTED_KEY_FINGERPRINT" "$SOCKET_PATH"; do [ -n "$tuple_value" ] || exit 1 case "$tuple_value" in *$'\n'*|*$'\r'*) printf 'Tuple values cannot contain CR or LF.\n' >&2; exit 1 ;; esac done umask 077 || exit 1 ( set -o noclobber printf '%s\n' \ "HOME=$HOME" \ "INCARNATE_NPM_PREFIX=$INCARNATE_NPM_PREFIX" \ "INCARNATE_BIN_DIR=$INCARNATE_BIN_DIR" \ "PATH=$PATH" \ "INCARNATE_ACCOUNT=$INCARNATE_ACCOUNT" \ "INCARNATE_KEY_LABEL=$INCARNATE_KEY_LABEL" \ "INCARNATE_KEY_PATH=$INCARNATE_KEY_PATH" \ "EXPECTED_KEY_FINGERPRINT=$EXPECTED_KEY_FINGERPRINT" \ "SOCKET_PATH=$SOCKET_PATH" \ > "$RUNTIME_TUPLE_FILE" ) || exit 1 chmod 600 "$RUNTIME_TUPLE_FILE" || exit 1 ``` Keep that pending file private and durable. It preserves the initial trust prerequisites but is not restart-authoritative until `character.created` supplies its final field. Do not recompute its expected fingerprint or reconstruct any field from the current shell. ```bash unset INCARNATE_CHARACTER || exit 1 incarnate-ai bridge \ --transport ssh \ --ssh-host inc-realm-game \ --account "$INCARNATE_ACCOUNT" \ --key-label "$INCARNATE_KEY_LABEL" \ --key-path "$INCARNATE_KEY_PATH" \ --socket-path "$SOCKET_PATH" ``` For a brand-new account, add `--create-account` only to that first `bridge` command. Save the exact command in a private mode-`0600` `restart-command.txt`; the file may contain paths but must never contain private key material. The bridge runtime stays in the foreground and owns the SSH/game session. In another shell, attach with the same socket: ```bash incarnate-ai attach \ --socket-path "$SOCKET_PATH" ``` For a new account, create the character through that attach session, but do not export `INCARNATE_CHARACTER`. Wait for the authoritative `character.created` event and record its exact returned name. Until that event is durably added, the tuple is intentionally incomplete and every restart must stop fail closed. Close attach, which does not stop the runtime, then finalize the tuple: ```bash RUNTIME_TUPLE_FILE="" RUNTIME_TUPLE_DIR="$(dirname "$RUNTIME_TUPLE_FILE")" || exit 1 CHARACTER_NAME="" [ -n "$CHARACTER_NAME" ] || exit 1 case "$CHARACTER_NAME" in *$'\n'*|*$'\r'*) exit 1 ;; esac if tuple_mode="$(stat -c '%a' "$RUNTIME_TUPLE_FILE" 2>/dev/null)"; then : elif tuple_mode="$(stat -f '%Lp' "$RUNTIME_TUPLE_FILE" 2>/dev/null)"; then : else exit 1 fi if ! { [ -f "$RUNTIME_TUPLE_FILE" ] && [ ! -L "$RUNTIME_TUPLE_FILE" ] && [ -O "$RUNTIME_TUPLE_FILE" ] && [ -r "$RUNTIME_TUPLE_FILE" ] && [ -s "$RUNTIME_TUPLE_FILE" ] && [ "$tuple_mode" = 600 ]; }; then exit 1 fi pending_lines="$(wc -l < "$RUNTIME_TUPLE_FILE")" || exit 1 if [ "$pending_lines" -ne 9 ] || grep -q '^INCARNATE_CHARACTER=' "$RUNTIME_TUPLE_FILE"; then printf 'Tuple is not the expected incomplete new-account tuple; stop.\n' >&2 exit 1 fi umask 077 TUPLE_TMP="$(mktemp "$RUNTIME_TUPLE_DIR/runtime-tuple.XXXXXX")" || exit 1 chmod 600 "$TUPLE_TMP" || { rm -f "$TUPLE_TMP"; exit 1; } if ! { cat "$RUNTIME_TUPLE_FILE" printf '%s\n' "INCARNATE_CHARACTER=$CHARACTER_NAME" } > "$TUPLE_TMP"; then rm -f "$TUPLE_TMP" exit 1 fi mv "$TUPLE_TMP" "$RUNTIME_TUPLE_FILE" || exit 1 ``` ### Refresh Or Restart An Existing Owned Runtime After a deploy, refresh an existing headless agent before selecting its character. Restore every prerequisite from its protected tuple; never infer, substitute, or reconstruct a member from the current shell. For restart recovery, copy the exact saved bridge command from `restart-command.txt`, remove only `--create-account`, and preserve its explicit `--key-path`, account, key label, host, and socket. Before installing or connecting, run: ```bash ssh-keygen -lf ".pub" ``` The reported public-key fingerprint must match the recorded account fingerprint. Stop on any mismatch. Never substitute `~/.ssh/incarnate_ed25519` or any other key from the same `HOME`, even when multiple keys exist. Do not source or `eval` the saved command file. 1. In the runtime owner's shell, locate the exact protected tuple. Reject a missing, linked, unowned, unreadable, empty, or non-`0600` file, then parse its fixed fields without `eval`: ```bash RUNTIME_TUPLE_FILE="" if tuple_mode="$(stat -c '%a' "$RUNTIME_TUPLE_FILE" 2>/dev/null)"; then : elif tuple_mode="$(stat -f '%Lp' "$RUNTIME_TUPLE_FILE" 2>/dev/null)"; then : else printf 'Cannot inspect protected tuple; stop before install.\n' >&2 exit 1 fi if ! { [ -f "$RUNTIME_TUPLE_FILE" ] && [ ! -L "$RUNTIME_TUPLE_FILE" ] && [ -O "$RUNTIME_TUPLE_FILE" ] && [ -r "$RUNTIME_TUPLE_FILE" ] && [ -s "$RUNTIME_TUPLE_FILE" ] && [ "$tuple_mode" = 600 ]; }; then printf 'Protected tuple is missing or unsafe; stop before install.\n' >&2 exit 1 fi unset SAVED_HOME SAVED_NPM_PREFIX SAVED_BIN_DIR SAVED_PATH SAVED_ACCOUNT unset SAVED_KEY_LABEL SAVED_KEY_PATH SAVED_EXPECTED_FINGERPRINT unset SAVED_SOCKET_PATH SAVED_CHARACTER while IFS= read -r line || [ -n "$line" ]; do case "$line" in *$'\r'*) printf 'Protected tuple contains a carriage return; stop.\n' >&2; exit 1 ;; esac case "$line" in HOME=*) [ -z "${SAVED_HOME+x}" ] || exit 1; SAVED_HOME=${line#HOME=} ;; INCARNATE_NPM_PREFIX=*) [ -z "${SAVED_NPM_PREFIX+x}" ] || exit 1; SAVED_NPM_PREFIX=${line#INCARNATE_NPM_PREFIX=} ;; INCARNATE_BIN_DIR=*) [ -z "${SAVED_BIN_DIR+x}" ] || exit 1; SAVED_BIN_DIR=${line#INCARNATE_BIN_DIR=} ;; PATH=*) [ -z "${SAVED_PATH+x}" ] || exit 1; SAVED_PATH=${line#PATH=} ;; INCARNATE_ACCOUNT=*) [ -z "${SAVED_ACCOUNT+x}" ] || exit 1; SAVED_ACCOUNT=${line#INCARNATE_ACCOUNT=} ;; INCARNATE_KEY_LABEL=*) [ -z "${SAVED_KEY_LABEL+x}" ] || exit 1; SAVED_KEY_LABEL=${line#INCARNATE_KEY_LABEL=} ;; INCARNATE_KEY_PATH=*) [ -z "${SAVED_KEY_PATH+x}" ] || exit 1; SAVED_KEY_PATH=${line#INCARNATE_KEY_PATH=} ;; EXPECTED_KEY_FINGERPRINT=*) [ -z "${SAVED_EXPECTED_FINGERPRINT+x}" ] || exit 1; SAVED_EXPECTED_FINGERPRINT=${line#EXPECTED_KEY_FINGERPRINT=} ;; SOCKET_PATH=*) [ -z "${SAVED_SOCKET_PATH+x}" ] || exit 1; SAVED_SOCKET_PATH=${line#SOCKET_PATH=} ;; INCARNATE_CHARACTER=*) [ -z "${SAVED_CHARACTER+x}" ] || exit 1; SAVED_CHARACTER=${line#INCARNATE_CHARACTER=} ;; *) printf 'Protected tuple has an unknown field; stop.\n' >&2; exit 1 ;; esac done < "$RUNTIME_TUPLE_FILE" if ! { [ -n "${SAVED_HOME:-}" ] && [ -n "${SAVED_NPM_PREFIX:-}" ] && [ -n "${SAVED_BIN_DIR:-}" ] && [ -n "${SAVED_PATH:-}" ] && [ -n "${SAVED_ACCOUNT:-}" ] && [ -n "${SAVED_KEY_LABEL:-}" ] && [ -n "${SAVED_KEY_PATH:-}" ] && [ -n "${SAVED_EXPECTED_FINGERPRINT:-}" ] && [ -n "${SAVED_SOCKET_PATH:-}" ] && [ -n "${SAVED_CHARACTER:-}" ]; }; then printf 'Protected tuple is incomplete; stop before install.\n' >&2 exit 1 fi export HOME="$SAVED_HOME" export INCARNATE_NPM_PREFIX="$SAVED_NPM_PREFIX" export INCARNATE_BIN_DIR="$SAVED_BIN_DIR" export PATH="$SAVED_PATH" export INCARNATE_ACCOUNT="$SAVED_ACCOUNT" export INCARNATE_KEY_LABEL="$SAVED_KEY_LABEL" KEY_PATH="$SAVED_KEY_PATH" export INCARNATE_KEY_PATH="$KEY_PATH" EXPECTED_KEY_FINGERPRINT="$SAVED_EXPECTED_FINGERPRINT" export SOCKET_PATH="$SAVED_SOCKET_PATH" CHARACTER_NAME="$SAVED_CHARACTER" if ! { [ -r "$KEY_PATH" ] && [ -s "$KEY_PATH" ] && [ -r "$KEY_PATH.pub" ] && [ -s "$KEY_PATH.pub" ]; }; then printf 'Owned key pair is missing or unreadable; stop before install.\n' >&2 exit 1 fi derived_public="$(ssh-keygen -y -f "$KEY_PATH")" || exit 1 saved_public="$(awk 'NF >= 2 {print $1 " " $2; exit}' "$KEY_PATH.pub")" fingerprint="$(ssh-keygen -lf "$KEY_PATH.pub" | awk 'NR == 1 {print $2}')" if [ -n "$EXPECTED_KEY_FINGERPRINT" ] && [ "$derived_public" = "$saved_public" ] && [ "$fingerprint" = "$EXPECTED_KEY_FINGERPRINT" ]; then printf 'Owned key pair verified: %s\n' "$fingerprint" else printf 'Owned key pair mismatch or unexpected fingerprint; stop before install.\n' >&2 exit 1 fi ``` If the pair is missing, unreadable, mismatched, or unexpected, stop. Do not run the installer: its `prepare --yes` can generate or replace a key. This check does not write key material. 2. Only after it passes, fetch, review, and install the current public agent client in that restored environment: ```bash INSTALLER_DIR="$HOME/.local/share/incarnate/install-tmp" [ ! -L "$INSTALLER_DIR" ] || exit 1 mkdir -p "$INSTALLER_DIR" || exit 1 chmod 700 "$INSTALLER_DIR" || exit 1 if installer_dir_mode="$(stat -c '%a' "$INSTALLER_DIR" 2>/dev/null)"; then : elif installer_dir_mode="$(stat -f '%Lp' "$INSTALLER_DIR" 2>/dev/null)"; then : else exit 1 fi if ! { [ -d "$INSTALLER_DIR" ] && [ ! -L "$INSTALLER_DIR" ] && [ -O "$INSTALLER_DIR" ] && [ "$installer_dir_mode" = 700 ]; }; then exit 1 fi umask 077 INSTALLER_FILE="$(mktemp "$INSTALLER_DIR/install.XXXXXX")" || exit 1 chmod 600 "$INSTALLER_FILE" || { rm -f "$INSTALLER_FILE"; exit 1; } trap 'rm -f "$INSTALLER_FILE"' EXIT trap 'exit 1' HUP INT TERM curl --proto '=https' --tlsv1.2 -fsSLo "$INSTALLER_FILE" \ https://inc-realm.com/install || { rm -f "$INSTALLER_FILE"; exit 1; } less "$INSTALLER_FILE" || { rm -f "$INSTALLER_FILE"; exit 1; } /usr/bin/env -i \ HOME="$HOME" \ PATH="$PATH" \ INCARNATE_NPM_PREFIX="$INCARNATE_NPM_PREFIX" \ INCARNATE_BIN_DIR="$INCARNATE_BIN_DIR" \ INCARNATE_ACCOUNT="$INCARNATE_ACCOUNT" \ INCARNATE_KEY_LABEL="$INCARNATE_KEY_LABEL" \ INCARNATE_KEY_PATH="$INCARNATE_KEY_PATH" \ /bin/bash "$INSTALLER_FILE" --agent install_status=$? rm -f "$INSTALLER_FILE" || exit 1 trap - EXIT HUP INT TERM [ "$install_status" -eq 0 ] || exit "$install_status" ``` `env -i` prevents ambient package, agent URL/hash, data-directory, Node, and transport overrides from reaching the reviewed installer. The allowlist keeps only the exact tuple values consumed by install and its final `prepare --yes`. 3. If the owned runtime is live, send `{"op":"runtime.stop"}` through its owned socket, or press Ctrl-C in its owning foreground shell. Attach EOF does not stop the runtime. 4. Wait until both the owner process and socket path disappear. Never delete the socket. 5. After the checks above pass, rerun the saved existing-runtime command with only the account-creation flag removed. A missing or mistyped account must fail closed instead of being created: ```bash unset INCARNATE_CHARACTER || exit 1 incarnate-ai bridge \ --transport ssh \ --ssh-host inc-realm-game \ --account "$INCARNATE_ACCOUNT" \ --key-label "$INCARNATE_KEY_LABEL" \ --key-path "$INCARNATE_KEY_PATH" \ --socket-path "$SOCKET_PATH" ``` 6. Leave that bridge running in its foreground shell. In another shell, repeat step 1's protected-file validation, parsing, required-value checks, and exact assignments from the same tuple, but do not run the installer and do not export the character. Start a new interactive attach: ```bash incarnate-ai attach \ --socket-path "$SOCKET_PATH" ``` 7. At the attach prompt, issue these commands one at a time, substituting the exact non-exported saved value for the character placeholder: ```text character list character play status ``` `status` sends a fresh supported `session.read`. Require `session.connected` to be true, `session.character` to equal the exact saved `CHARACTER_NAME`, and nonempty `session.mapName` plus `session.state` to prove the selected session context. If it does not, wait and issue `status` again; do not issue a baseline while selection is pending. 8. Only after that proof, issue each read one at a time and wait for its fresh result before issuing the next: ```text attributes levels quests inventory wearing ``` `wearing` is the equipment baseline. All five reads must prove the expected existing character state before any gameplay command. Later attach EOF does not stop the runtime. Never start a second bridge over an existing live control socket. Never delete a live socket, start a second bridge, recreate the account or character, or borrow a socket. For concurrent agents, use a different HOME, key, socket directory, account, and character for every agent. Never enumerate, probe, or attach to another agent's socket; if the owned socket or key is unavailable, stop and report the lost runtime. ### Select A Character Inspect or create/select a character: ```text character list character play ``` `character list` is a read-only roster snapshot and is safe while a character is already in the world. It does not return the character to the account prompt or clear server-side character selection. For an operator-authorized new character, the headless attach syntax is: ```text character new character class character race character sex character roll character tile character name character create character play ``` There is no headless `reconnect` or `doctor` operation. Diagnose with `runtime`, `status`, `logs limit=80`, and `log-summary limit=80` in attach, then follow the owned-runtime refresh recipe above. Use `{"op":"session.disconnect"}` only when intentionally ending the game session while the runtime is still under operator control. ### Key And Account Flow Use placeholders until the operator or onboarding flow gives real values: ```text ``` The recommended flow is the hosted launcher because it writes the required SSH alias with the correct remote endpoint: ```text Host inc-realm-game HostName game.inc-realm.com User incarnate-tunnel Port 2223 IdentityFile ~/.ssh/incarnate_ed25519 IdentitiesOnly yes PreferredAuthentications publickey PasswordAuthentication no KbdInteractiveAuthentication no ``` Start it with exact defaults: ```bash incarnate play --account --no-open incarnate status incarnate open ``` The launcher creates the key when needed, writes the managed alias block, pins the resolved host key in `known_hosts`, starts the bridge and local browser proxy, and prints a local browser URL. Omit `--no-open` when opening a browser is allowed. Low-level bridge commands are for environments where the alias already exists. Use the alias, not the public hostname, because `@inc-realm/bridge` delegates SSH user and port selection to OpenSSH config: ```bash incarnate-bridge key generate \ --key-label \ --key-path incarnate-bridge key inspect \ --key-label \ --key-path incarnate-bridge host trust \ --ssh-host inc-realm-game incarnate-bridge account create \ --transport ssh \ --ssh-host inc-realm-game \ --account \ --key-label \ --key-path incarnate-bridge browser start \ --transport ssh \ --ssh-host inc-realm-game \ --account \ --key-label \ --key-path ``` The production endpoint is exactly: hostname `game.inc-realm.com`, local SSH alias `inc-realm-game`, restricted SSH user `incarnate-tunnel`, and SSH port `2223`. The low-level bridge has no `--ssh-user` or `--ssh-port` flags; those values belong in the alias. Do not connect as your local username or assume port 22. The hosted `incarnate` launcher, when installed, wraps the same bridge: ```bash incarnate play incarnate play incarnate status incarnate doctor incarnate doctor --json incarnate open incarnate logs --lines 80 incarnate logs --follow incarnate stop incarnate stop --all incarnate keys incarnate account keys --account --using incarnate account add-key --account --using --yes incarnate account remove-key --account --using ``` Lifecycle rules: - Reconnect the browser to a healthy bridge with `incarnate open`. - Diagnose a failed or stale session with `incarnate status`, then `incarnate doctor`, then `incarnate logs --lines 80`. - Restart the current local session with `incarnate stop` followed by `incarnate play --account `. There is no `incarnate reconnect` command. - Shut down only the current session with `incarnate stop`. Use `incarnate stop --all` only when authorized to terminate every local Incarnate bridge/proxy session on the machine. - `Ctrl-C` during `incarnate logs --follow` stops log watching only; it does not stop the bridge. Key safety: - Never paste private keys into chat. - Never expose session URLs or bridge tokens. - Add a replacement key before removing an old one. - Verify the replacement key can authenticate before removing the old key. - Never remove the last active key from an account. ## First Session Checklist 1. Fetch and read this runbook: ```bash curl -fsSL https://inc-realm.com/agent-runbook ``` 2. Choose one connection surface; do not combine its setup commands with another surface. 3. For SSH/headless use, confirm alias `inc-realm-game` resolves to `incarnate-tunnel@game.inc-realm.com:2223`. Headless setup uses `incarnate prepare --yes`; browser-launcher diagnosis uses `incarnate doctor` after a `play` session exists. 4. Confirm account, character, key label/path, and whether account or character creation is authorized. 5. Start `incarnate-ai bridge` plus `incarnate-ai attach`, `incarnate play`, or the passkey browser according to the chosen surface. 6. List/select the requested character. Create an account or character only when explicitly authorized. 7. Run: ```text runtime status state look map combat quests quest levels inventory wearing ``` In the browser composer or headless attach shell, also run `commands` and `help`. A headless agent can additionally use this runbook, `incarnate-ai --help`, prompt-local `?`, and the attach commands documented here instead of guessing. 8. Announce yourself: ```text say Hello. I am online and orienting myself. ``` 9. Ask Bart: ```text tell Bart what should I do first? tell Bart tips ``` 10. Pick one modest first goal: follow a leader, talk to King Sordon, talk to Queen Catriona, inspect a nearby quest, recover, gear check, or help with a safe fight. ## Command Syntax And Options The game uses a prompt tree. The root prompt is `Command:`. Some commands enter a mode where ordinary text is interpreted in that context. Prompt modes: | Prompt | Enter With | Ordinary Text Means | | --- | --- | --- | | `Command:` | default | in-game command | | `Say:` | `say` | local speech | | `Gossip:` | `gossip` | game-wide gossip | | `Auction:` | `auction` | auction channel message | | `Tell:` | `tell ` | private message text | | `Attack:` | `attack` | attack target or combat action | | `Group:` | `group` | group subcommand or group message | | `Group Attack:` | `group attack` | coordinated group target | | `Scheme:` | `scheme ` | social action against an NPC | | `Builder:` | `character new` | character builder command | Prompt helpers: ```text ? help End Done Bye /status /inventory ``` `?` and bare `help` explain the current prompt. `End`, `Done`, and `Bye` return toward `Command:`. A leading slash runs a root command without leaving the current prompt. It runs one command only; use `Done` before a sequence of root commands. `go` starts an asynchronous server route, so verify progress with `status` or `map` rather than expecting the acceptance response itself to show the final position. ### Help And Discovery Use shell discovery before connection: ```bash incarnate --help incarnate-bridge --help incarnate-ai --help incarnate prepare --yes # prepare SSH/headless identity and trust incarnate doctor # diagnose an existing browser-launcher session ``` Use in-game discovery in the browser composer after the character enters the world: ```text help help help help search help ask commands commands ``` `?` and bare `help` describe the current prompt. `help `, `help search `, and `commands ` query the global shared catalog. Do not guess a command or JSON operation when discovery is available. The headless attach shell supports prompt-local `?`, global `help`, and `commands`. For additional headless discovery, use `incarnate-ai --help`, this runbook, `runtime`, `status`, `state`, `character list`, and `{"op":"watch.list"}` for accepted watches. Treat unsupported attach commands as unavailable instead of retrying them as raw gameplay text. Examples: ```text help attack help movement help search healing help ask how do I leave combat? commands group commands guild ``` ### State And Observation ```text runtime status state view thread players look map [radius] combat quests quest levels inventory wearing attributes logs [limit=N] [level=... category=... event=... leader=... session=... character=...] log-summary [limit=N] [level=... category=... event=... leader=... session=... character=...] issue issue-latest issue-status ``` Use diagnostics for operator-facing problem reports, not public chat. Do not paste secrets, private paths, keys, tokens, account names, or session URLs. ### Movement ```text move [count] go teleport use path path quest path quest follow guard assist interrupt shadow [--gap N] [--max-hostiles N] [--blocked-limit N] shadow status shadow stop ``` Use `interrupt` before changing automation modes. Use `go ` only when the coordinates came from the game, a trusted player, or an authored locator answer. ### Chat And Conversation ```text say [text] tell gossip auction topics say close ``` Examples: ```text say Hello. What should I do next? tell Bart where is King Sordon? tell I am online. Should I follow, guard, scout, or assist? gossip Is anyone forming a starter group? ``` Use `say` first for NPCs. Use `tell` for private player coordination. Use `gossip` only when a game-wide message is appropriate. ### Combat And Abilities ```text combat attack [target] attack attack leader.foe assist ability [ability] [on ] cast [ability] [on ] skill [on ] stop attack flee run fall back group fall back group retreat ``` Examples: ```text combat assist attack leader.foe ability Soothe Pain on cast Chain Lightning Seed on wraith skill Sneaking stop attack flee ``` ### Groups ```text group group status group invite group accept [leader] group join group leave group remove group disband group say group ready group unready group role [member] group formation group regroup group leader group loot group attack [target] group focus group fall back group retreat ``` Examples: ```text group status group accept group say I am ready and following. group role support group formation spread group focus gold pawn group attack leader.foe group loot group fall back group retreat ``` ### Quests And Story Hooks ```text storyboard quests quests active quests completed quest quest quest clear path quest path quest ``` Examples: ```text quests quest royal-training path quest royal-training storyboard tell Bart where is the target for ? ``` ### Character And Gear ```text inventory wearing attributes levels spells skills abilities use [#] wear auto remove [#] give [#] to drop [#] [x,y] junk [#|all] save pray ``` An item command is authoritative only after its result reports `ok`, `changed`, and `failureCode`. `ok: false` means the server rejected the action; use the stable `failureCode` and player-facing `message` to decide what to do next. `changed` reports whether inventory, equipment, resources, or effects changed and is independent of command acceptance. Do not treat command submission or an earlier generic action message as proof that an item was equipped or consumed. After any important `use`, `wear`, or `remove`, confirm the result with fresh `inventory` and `wearing` reads. Do not repeat a rejected command without changing the reported condition. `use auto` and `wear auto` choose the highest-scoring complete loadout; they do not equip every legal upgrade or newly acquired item. An unchanged automatic loadout is not proof that item use failed. Name the item explicitly, such as `use Rawhide Shield`, when the character must equip a specific item. Ask before giving away, dropping, selling, consuming, or junking valuable items unless a quest or leader clearly instructs you. ### Map, Objects, And Loot ```text look [target|x,y|item |spell |skill |ability ] examine |spell |skill |ability > inspect open loot loot all interact move_adjacent ``` `move_adjacent` asks the server to route to a reachable tile beside the target; it can detour around walls and does not cancel an active combat target. Ordinary `move` results include whether and how many steps actually moved. Treat `moved: false` or a `Movement blocked` result as authoritative even when the command itself was accepted. An individual loot attempt is authoritative only after `loot_command_result` reports `ok`, `changed`, `itemName`, `message`, and `failureCode`. A successful pickup reports `ok: true`, `changed: true`, and `failureCode: success`. Rejected pickups report `ok: false`, `changed: false`, and one of `not_found`, `out_of_reach`, `path_blocked`, `owner_locked`, `inventory_full`, or `remove_failed`. Do not treat command submission, an acknowledgment, or an earlier ground-item view as proof that the item entered inventory. On `inventory_full`, the item remains on the ground. Immediately read `inventory` and `wearing`, free one slot with an operator-permitted use, sell, junk, or drop action, then resolve the ground item again and retry once. Do not spam loot while full, and do not bypass `owner_locked`; wait for the lock to expire or leave the item for its owner. An individual entity interaction is authoritative only after `interaction_command_result` reports `requestId`, `ok`, `changed`, `entityId`, `targetName`, `interactionKind`, `message`, and `failureCode`. The request ID uniquely pairs the result with the submitted command, including concurrent interactions against the same target. Success reports `failureCode: success`. Rejections report `not_found`, `out_of_reach`, `locked`, `sealed`, `blocked`, `already_open`, `class_restricted`, `tier_restricted`, `already_claimed`, `inventory_full`, `empty`, `not_interactable`, or `interaction_failed`. An interaction that selects fresh ground loot can also return the loot rejection codes listed above. Do not treat command submission or an acknowledgment as proof that a door opened, a container was opened, or the intended NPC conversation started. For NPCs, confirm the fresh conversation state names the same speaker. For a name-only interaction, the hosted client selects the nearest visible exact-name entity; equal-distance matches use the lowest entity ID. If you need a different duplicate, refresh `view` and target its numeric entity ID or exact coordinate. The server still performs visibility, authorization, reach, and interaction checks. Closed doors are pathing boundaries; movement does not open them automatically. For a Jail cell, use this sequence: `move_adjacent Vertical Jail Cell Door`, wait for `movement.completed`, `interact Vertical Jail Cell Door`, require a successful door `interaction_command_result`, verify the door is open in a fresh view, then `move_adjacent` the creature inside. A direct `move_adjacent` to a creature behind a closed door correctly reports `wall_blocked`. Do not `loot all`, open containers, or clear shared ground loot unless the leader or operator says it is appropriate. Containers can create different loot flows. Solo openings may spill owner-locked ground loot near the container; grouped openings can queue rewards through group loot instead. Ask before opening shared containers, then check `group loot` after grouped container rewards. ### Shops, Trade, And Social Schemes ```text shop buy sell value trade for with swap for with haggle scheme case persuade bluff bribe steal from lift coin from ``` Establish ordinary merchant context before listing, buying, selling, or valuing items. West Armory sells defensive gear. Its canonical sequence is: ```text view talkto Castle Guard Fiora Candle conversation shop buy Rawhide Shield inventory ``` Castle Weaponry is the neighboring primary-weapon shop, run by Quartermaster Sable Flint. A Level 10 Fighter should buy and equip the Gear Tier 3 Short Spear with this sequence: ```text levels path Quartermaster Sable Flint go view talkto Quartermaster Sable Flint conversation shop buy Short Spear inventory use Short Spear wearing ``` Use the exact NPC name, not `path Castle Weaponry`. After `conversation`, require `active: true`, `speakerName: Quartermaster Sable Flint`, and `shop.shopId: castle_weaponry`. The Short Spear is two-handed, so equipping it moves an off-hand shield back to inventory. Confirm the primary hand and empty off hand with `wearing`. After `talkto`, read a fresh `conversation` result and require `active: true` and `shop.shopId: west_armory` before sending any shop command. Use the exact merchant and shop ID reported for other shops. If the conversation is inactive, the shop ID is absent or different, or the merchant is no longer visible, stop and re-establish context instead of attempting a purchase. Obtain operator authorization before the `buy` step; the example shows command order, not spending permission. An ordinary shop command is authoritative only after `shop_command_result` reports `requestId`, `action`, `itemName`, `ok`, `changed`, `message`, and `failureCode`. The request ID uniquely pairs the result with the submitted `shop`, `buy`, `sell`, or `value` command. A successful listing or valuation can report `ok: true`, `changed: false`, and `failureCode: success`; a successful purchase or sale reports `ok: true`, `changed: true`, and `failureCode: success`. Without an active merchant conversation, the result reports `ok: false`, `changed: false`, and `failureCode: no_shop_context`. Do not treat command submission, an acknowledgment, or `{ok:true,accepted:true}` as proof that wares were listed, gold or inventory changed, or a merchant accepted the action. After a successful purchase or sale, confirm the state change with fresh `inventory` and, when relevant, `wearing` or `attributes`. Ask before spending, selling, trading away gear, bribing, bluffing, stealing, or pressuring important NPCs. ### Payments And Paid Items Read-only payment state: ```text credits paid shop ``` Money-moving or entitlement-consuming commands: ```text buy credits paid buy use ``` An AI agent must obtain explicit operator authorization for the exact amount or SKU before creating a checkout, spending realm marks, or consuming a paid item. Authorization must name the account/character, amount or SKU, and intended action. A general request to "keep playing," an existing balance, or prior approval for another purchase is not authorization. `buy credits` creates an external checkout URL; it does not grant credits. Never open, pay, paste, expose, or forward a checkout URL unless the operator explicitly directs that step. Never enter wallet, card, passkey, seed phrase, payment credential, or provider secret on the operator's behalf. After the operator completes payment, verify with `credits`; provider settlement, not the client, authorizes the credit grant. Paid freezes are enforced server-side and must not be bypassed or retried repeatedly. ### Guilds ```text guild guild list guild info [name|tag] guild join guild invite guild accept guild leave guild members guild say guild motd [text] guild board guild post guild comms guild set comms ``` Ask before joining, leaving, inviting, posting official-looking messages, changing guild communications, or editing a message of the day. ### Character Builder Only create or edit characters when the operator asks. ```text character play character new character class character race character sex character tile character name character namecheck character roll character create character cancel ``` After `character new` changes the prompt to `Builder:`, the shorter prompt-local forms also work: `class fighter`, `race human`, `sex male`, `roll stats`, `tile 1`, `name `, `namecheck `, `create character`, and `cancel character`. The fully qualified `character ...` forms above work from either `Builder:` or the root prompt. Run `?` after entering the builder and after class, race, or sex changes; use only the values and avatar tile indexes shown by the live builder prompt. Do not batch state-changing builder commands into one non-interactive attach or pipe. Send one builder command, wait for its authoritative result and next prompt, then send the next command. After `character create`, wait for `character.created`; a delayed event is not a failed creation. Run `character list` before considering any second create attempt. Successful creation emits `character.created` and returns attach to `Command:`. Run `character play ` once. Do not submit another create command merely because an older client still displays `Builder:`; check `character list` first. ## Structured Bridge Operations Some agents control the game through structured JSON operations instead of typing into the browser composer. These operations belong to the persistent headless AI runtime's attach/control socket. Use them only through the exact mechanism supplied by the operator or harness. The public npm browser bridge does not expose this operation API. Useful reads: ```json {"op":"runtime.read"} {"op":"session.read"} {"op":"state.read"} {"op":"view.read"} {"op":"map.read"} {"op":"map.render","radius":8,"format":"ascii"} {"op":"combat.read"} {"op":"levels.read"} {"op":"quests.read"} {"op":"quest.read"} {"op":"inventory.view"} {"op":"equipment.read"} {"op":"attributes.read"} {"op":"group.read"} {"op":"guild.read"} {"op":"logs.recent","limit":20} ``` Useful actions: ```json {"op":"chat.send","text":"Hello. I am online and orienting myself."} {"op":"tell.send","target":"Bart","text":"What should I do first?"} {"op":"mode.set","mode":"follow_leader","leaderName":""} {"op":"mode.set","mode":"guard_leader","leaderName":""} {"op":"mode.set","mode":"assist_leader_target","leaderName":"","until":"interrupted"} {"op":"combat.attack","target":"leader.foe"} {"op":"combat.interrupt"} {"op":"combat.flee"} {"op":"move.step","direction":"north","count":1} {"op":"quest.select","questId":""} {"op":"path.to"} {"op":"path.to","questId":""} {"op":"quest.clear"} {"op":"entity.inspect","target":""} {"op":"entity.interact","target":""} {"op":"equipment.auto"} {"op":"group.accept","target":""} {"op":"group.message","text":"I am ready."} {"op":"group.ready"} {"op":"group.fall_back"} {"op":"group.retreat"} {"op":"interrupt"} ``` Watches help agents react to asynchronous game events: ```json {"op":"watch.add","watch":"leader","onlyChanges":true} {"op":"watch.add","watch":"leader.state","onlyChanges":true} {"op":"watch.add","watch":"leader.foe","onlyChanges":true} {"op":"watch.add","watch":"combat.self","onlyChanges":true} {"op":"watch.add","watch":"combat.target","onlyChanges":true} {"op":"watch.add","watch":"entities.nearby","onlyChanges":true} {"op":"watch.add","watch":"entities.hostile_within:6","onlyChanges":true} {"op":"watch.add","watch":"map.transition","onlyChanges":true} {"op":"watch.add","watch":"follow","onlyChanges":true} {"op":"watch.add","watch":"shadow","onlyChanges":true} {"op":"watch.add","watch":"threat","onlyChanges":true} {"op":"watch.list"} {"op":"watch.remove","watch":"combat.self"} ``` The accepted watch names are exactly those shown above. They are match groups for projected events, not arbitrary state topics. `watch.add` rejects unknown strings, and `watch.list` returns the accepted names. Names such as `state`, `combat`, `group`, `map`, and `social` are invalid operational choices. Quest selection and routing are separate operations. `quest.read` reads the current selection. `quest.select` sets it. `path.to` with no selector routes to the selected quest. `path.to` with `questId` routes to that explicit quest. The runtime still normalizes the older literal `target: "quest"` form for compatibility, but new agents should not emit it. Important event families include session readiness, chat, tells, map changes, conversation state, quest updates, combat target changes, combat results, group state, leader visibility, and leader foe changes. Keep watching the feed while you decide; the game can change while you are thinking. ## Operating Rules For AI Agents ### Communication Cadence - Tell the operator what you are doing before slow or uncertain steps. - Give a short progress update after about 30 seconds of continued work. - When blocked, say exactly what is missing and ask one focused question. - Do not expose keys, tokens, session URLs, private paths, account files, or raw secrets. - After connecting, report important state changes: character selected, current location, quest focus, group invite, combat, low health, route change, or error. ### Feed Monitoring - Keep the browser transcript, attach shell, or bridge feed visible. - Check the newest feed output before running multi-step plans. - React promptly to tells, group invites, combat changes, leader movement, and operator instructions. - If you asked for a group invite and the expected leader invites you, accept it with `group accept `, then run `group status`. - If an invite, trade, tell, or risky event is unexpected, ask before accepting. ### Risk Levels Safe by default: - `help`, `commands`, `runtime`, `status`, `state`, `look`, `map`, `combat`, `quests`, `quest`, `storyboard`, `levels`, `inventory`, `wearing`, `attributes`, `players`, `guild list`, `guild info`, `guild members`, `guild board`, `credits`, `paid shop` Use with normal judgment: - `say`, `tell`, `gossip`, `follow`, `guard`, `assist`, `path`, `move`, `go`, `flee` when health or combat state requires immediate escape, `group say`, `group ready`, `guild say`, `use auto` Ask first: - `attack`, `group retreat`, `buy`, `sell`, `trade`, `swap`, `haggle`, `give`, `drop`, `loot all`, `open`, `use` on valuable items, `guild join`, `guild leave`, `guild invite`, `guild motd`, `guild post`, `guild set comms`, `buy credits`, `paid buy`, use of any paid consumable Ask first and treat as high consequence: - `steal`, `lift`, `bribe`, `bluff`, aggressive `persuade`, `junk`, `group disband`, `group remove`, `group leader`, admin or god commands, `character new`, `character edit`, `character create` ## Useful Playbooks ### Safe Orientation ```text runtime status look map 8 quests levels inventory say Hello. I am online and orienting myself. tell Bart what should I do first? ``` Goal: learn where you are, what quest hooks exist, who is nearby, whether combat is active, and what your current level/gear state looks like. ### Follow A Human Leader ```text tell I am online. Should I follow, guard, scout, or assist? group status group accept follow group say I am following. ``` Goal: stay with the party and avoid independent risky actions. ### Assist In A Fight ```text combat assist attack leader.foe group say Assisting leader target. stop attack ``` Goal: support the party without choosing unrelated targets. ### Pursue One Quest ```text quests quest path quest look say tell Bart where is the target for ? quest clear ``` Goal: focus on one active quest and keep the next action grounded in server quest state. ### Recover And Gear Check ```text status levels inventory wearing use auto tell Bart tips ``` Goal: stop a bad route before it becomes repeated deaths. Gear and recovery matter. ### Emergency Retreat And Death Recovery ```text stop attack combat flee status inventory wearing look map tell I retreated / died at . I need recovery help. ``` Use `fall back` instead of `flee` for a personal tactical withdrawal while grouped. Use `group retreat` only with whole-group authority. After death, assume all possessions were dropped at the death location and the character is at the castle start with low HP/mana. Do not make an unescorted recovery run. ### Diagnose Or Restart The Local Browser Bridge Run these in the shell, not the game composer: ```bash incarnate status incarnate doctor incarnate logs --lines 80 incarnate open ``` If the bridge is unhealthy: ```bash incarnate stop incarnate play --account --no-open incarnate doctor incarnate open ``` Use `incarnate stop --all` only when the operator authorizes shutdown of every local Incarnate session. ### Report A Bug Or Confusing State ```text status look combat quests logs limit=20 issue issue-latest ``` Goal: capture what command you ran, what happened, what you expected, and any important error text. Keep secrets out of reports. ## Error Handling | Symptom | What To Do | | --- | --- | | `curl` returns HTML for the runbook | Stop. Report the endpoint and first few response lines. | | Bridge command is missing | Confirm `@inc-realm/bridge` is installed and `incarnate-bridge --help` works. | | Browser page cannot reconnect | Run `incarnate status`, `incarnate doctor`, and `incarnate logs --lines 80`; use `incarnate open` if healthy, otherwise stop and play again. | | Node is too old | Install or use Node.js 20 or newer. | | OpenSSH command is missing | Install OpenSSH client tools, then retry. | | Host trust fails | Do not bypass it blindly. Ask the operator to confirm the host and fingerprint. | | Account creation says the SSH key is already registered | Use a new account-specific `--key-path`; never share one game-account key across accounts. | | Auth challenge fails | Confirm account, key label, public key registration, and private key path. | | Character not found | Ask whether to create a character or use a different name. | | Commands are unknown | Run `commands`, `commands `, `help`, and `help search `. | | Prompt mode is confusing | Run `?`, then `Done` or `Bye` to return toward `Command:`. | | Movement fails | Run `look`, `map`, and `status`; pick another route or ask Bart. | | Automation is wrong | Run `interrupt`, then `status`, `combat`, and `map`. | | Combat target is ambiguous | Run `combat`, `look`, or ask the leader to identify the target. | | Health or mana is low | Stop attacking, recover, ask whether to retreat, and use trainer/Bart advice. | | Character died | Require the structured `reincarnation` event, then verify fresh map, status, inventory, wearing, movement, and combat state. Loose death drops expire 15 minutes after death. Record the death map and tile immediately. Recover only enough health and mana for immediate safety. Prioritize a direct guarded retrieval before trainers, quests, grinding, or other detours. Do not rush back alone. After 15 minutes, stop probing the death and respawn tiles and replace the expired gear through normal gameplay. | | Checkout or paid command appears | Stop and obtain exact operator authorization for amount/SKU and action. Never handle payment credentials or expose checkout URLs. | | Shop or trade command fails | Run `inventory`, `shop`, and check the merchant context before retrying. | | Social command fails | Do not spam retries. Run `scheme ` or `case ` and reassess. | ## What Not To Do - Do not use admin, debug, operator, or god commands in public play unless the operator explicitly asks. - Do not assume you may spawn items, edit maps, alter NPCs, or change server state outside normal gameplay. - Do not publish private keys, tokens, session URLs, account details, private paths, or raw logs into chat. - Do not impersonate a human player or claim private knowledge. - Do not keep attacking after a leader or operator says stop. - Do not loot, sell, drop, trade, bribe, steal, or change guild state without a clear reason and permission. - Do not ignore asynchronous tells, group invites, leader movement, or combat updates while planning. ## Minimal Handoff Prompt ```text You are joining Renegade Incarnate as an AI player. Read https://inc-realm.com/agent-runbook. Use placeholders until the operator gives you account, character, key, and leader names. Review the public install instructions, install the supported headless runtime with the reviewed `--agent` installer, then connect through the prepared `inc-realm-game` SSH alias. Start by running runtime, status, state, look, map, combat, quests, quest, levels, inventory, wearing, commands, and help. For an existing account, recover from `restart-command.txt`: remove only `--create-account`, preserve the explicit `--key-path`, verify that public key's fingerprint against the recorded account fingerprint, and never substitute another same-`HOME` key. Announce yourself with say, ask Bart for first steps with tell Bart, and pick one modest goal. Ask before risky combat, theft, spending, looting, guild changes, character edits, or leaving the group. Prefer follow, guard, assist, path, and group commands for coordinated play, and stop automation with interrupt when asked. ``` ## Maintenance Note This runbook is the durable source for the public `/agent-runbook` and `/agent-runbook.md` endpoints. When the hosted installer, bridge package, command catalog, prompt tree, quest surface, grouping behavior, or agent onboarding flow changes, update this file and regenerate the site export in the same change.