Add simlock instructions: the rules an agent must follow, printable and served over MCP #147

Part of #157.

Scope

An agent or operator runs simlock instructions and gets the current rules for using Simlock as one Markdown text, a section per surface, agent-device first. An MCP agent gets the short version of the rules when it connects, and can read the full text as the resource simlock://instructions. The website's "Connect your agent" page points at the command instead of carrying its own copy.

Start from branch origin/feature/157 (commits 525fd53ca, 54e5dde76, 0b29c03a6): src/instructions/index.ts and its tests apply cleanly. The CLI part has to be re-ported to src/cli/tree.ts and src/cli/commands/ (F2), and the text rewritten as below.

In short

simlock instructions prints the rules: what every agent must do, then how to use agent-device, how to build for iOS, the simlock CLI, and MCP. It never contacts a daemon. An MCP client receives the first and last sections as the server instructions on connect, at most 4096 characters long. If it goes wrong, an agent follows a rule Simlock no longer has, or never hears about agent-device.

flowchart LR
  A[Agent or operator] -->|simlock instructions| T[rules text]:::changed
  M[MCP client] -->|connect| S[server instructions]:::changed
  M -->|read simlock://instructions| T
  classDef changed stroke-width:3px

Before and after:

$ simlock instructions
{"error":{"code":"USAGE","message":"Unknown command: instructions (run `simlock --help` for usage)"}}   # exit 2

$ simlock instructions          # after
# Using Simlock to share iOS simulators and Android emulators
...                              # exit 0

$ simlock instructions --json   # after
{"instructions":"# Using Simlock ..."}

What the text says

One Markdown text: a # title, a one-paragraph intro, then these ## sections in this order (the feature's Shared values). Each section says, in plain words, what its "Says" cell lists, and only commands that exist today. The text ends with the line More: https://callstackincubator.github.io/simlock/docs/.

Each section must also contain every string in its "Required strings" cell, word for word (backticks included): the tests check these and nothing else about the wording.

The refusals list, each named in the ## simlock CLI section as written here (F7):

• iOS: each verb of REFUSED_SIMCTL_VERBS as `simlock simctl <verb>`; `simlock simctl shutdown all`; `simlock simctl runtime delete`; the sentence simlock simctl refuses any option before the subcommand, --set and --profiles included.
• Android: `simlock adb kill-server`; each sequence of REFUSED_ADB_SEQUENCES as `simlock adb <sequence>`; the sentence simlock adb refuses any option before the subcommand other than -s, -t, -d or -e; and that on another machine simlock adb shell needs a command to run.

The MCP server instructions are the # title line, ## Rules for every agent, ## MCP, and the line Run `simlock instructions` for the rest: agent-device, iOS builds and the CLI. Both texts are built from the same section strings, so nothing is written twice. Simlock keeps the server instructions at most 4096 characters, so that a client that cuts long server instructions still gets all of it.

Technical spec

Facts

Commit cac23e033 unless noted.

Modules touched

Searches: GATEWAY_EXEMPT_PATHS, COMMANDS, USAGE in src/cli; new McpServer in src; REFUSED_, SHUTDOWN_ALL_TARGET, CALLER_SUPPLIED_SCOPE_FLAGS, "runtime delete" in src/drivers; LEASE_ENDED_MESSAGE; instructions in website/src/content/docs.

• src/instructions/index.ts (new): the section strings, AGENT_INSTRUCTIONS (all sections), MCP_SERVER_INSTRUCTIONS (title, Rules for every agent, MCP, pointer line), renderInstructions(format: "text" | "json"). The only copy of the text. src/instructions/AGENTS.md (new manual) and its row in docs/internal/ARCHITECTURE.md.
• src/cli/tree.ts: an instructions node; src/cli/commands/instructions.ts (new): [--json], --help, any other argument USAGE. Never connects to a daemon.
• src/cli/index.ts: instructions in the USAGE banner and in GATEWAY_EXEMPT_PATHS.
• src/contract/errors.ts (exported through src/contract/index.ts): LEASE_LOST_EXIT_CODE = 14 moves here from src/cli/commands/lease.ts, which imports it; behaviour unchanged (F8).
• src/mcp/server.ts: instructions: MCP_SERVER_INSTRUCTIONS in the server options; registerResource of simlock://instructions (text/markdown, AGENT_INSTRUCTIONS). No new tool.
• src/drivers/ios/index.ts, src/drivers/android/index.ts: export the refusal constants (and a runtime delete constant in place of the inline literal) for the test; behaviour unchanged.
• src/agent-device/shared/replies.ts: export LEASE_ENDED_MESSAGE (through the module's index) for the test.
• src/cli/AGENTS.md, src/mcp/AGENTS.md: Uses gains instructions; the MCP manual names the resource and server instructions; the CLI manual's exempt list gains instructions.
• Tests: src/instructions/index.test.ts, e2e/agent-instructions.test.ts (new, from the branch), e2e/mcp-session.test.ts, src/cli/index.test.ts.
• Website: reference/cli.mdx (commands table row, ## simlock instructions section, instructions added to the exempt list at line 60, worded without a count), getting-started/connect-your-agent.mdx (the hand-written block at lines 43-63 becomes "run simlock instructions and paste its output", the MCP part says the server sends the rules on connect).

flowchart LR
  CLI[cli/commands/instructions]:::changed --> I[instructions]:::changed
  MCP[mcp/server]:::changed --> I
  T[instructions tests] -.-> D[drivers constants]:::changed
  T -.-> AD[agent-device replies]:::changed
  classDef changed stroke-width:3px

Surface and extension points

src/instructions/index.ts exports constants and one pure function; no factory, no handle. No second implementation.

Contract and event changes

None after a search of src/contract and docs/internal/EVENTS.md: no daemon operation, no event, no config key, no protocol bump. Moving LEASE_LOST_EXIT_CODE into src/contract/errors.ts changes no wire shape, so its commit carries the Protocol-bump: none (<reason>) trailer toolchain.md asks for. The MCP initialize result gains instructions and the resources capability; no tool changes.

Other code on the same state

None: the task adds static text and reads no state. Searched instructions and registerResource in src (0 hits on main).

Failure modes

None: no call crosses a process or another tool, and the task writes no state. The MCP resource read is answered in process.

Rules in play

• Documentation rule 3, "Nothing the running tool prints or returns ever names a file path in this repository": the text points only at the website URL. A test proves it.
• Documentation rule 9, "A change to the public surface updates the website in the same change": the two pages above.
• Architecture rule 8, "The daemon owns all state; the CLI is a thin client": the text is static and lives in the frontends; the daemon never learns it.
• src/cli/AGENTS.md, router files "import no component for a value": instructions is reached only from commands/instructions.ts.
• Testing rule 10: a claim of "every" names its cases; the refused verbs and exit codes are read from their definitions, not copied.

Tests

Seams: e2e/agent-instructions.test.ts (fast lane, model origin/feature/157:e2e/agent-instructions.test.ts), src/instructions/index.test.ts, src/cli/index.test.ts, e2e/mcp-session.test.ts.

• A user runs simlock instructions and gets the rules text, no daemon: plain → AGENT_INSTRUCTIONS on stdout, stderr empty, exit 0, no socket under the home; --json → one line, { instructions } equal to the plain output; --bogus and a positional → USAGE, exit 2, stdout empty; --help → Usage: simlock instructions [--json], exit 0.
• A user passes --gateway or --local to simlock instructions on a machine with no gateway and still gets the text: --gateway; --local; and simlock --help lists instructions (unit, src/cli/index.test.ts).
• A reader of the rules text finds every section and required item: the five headings in order; each "Required strings" entry inside its own section; each refusal of the refusals list, the iOS verbs and Android sequences built from the exported driver constants; 10, 11, 13 from ERROR_TABLE and 14 from LEASE_LOST_EXIT_CODE; LEASE_ENDED_MESSAGE; the last line is the website URL.
• The rules text names no path in this repository: with every https:// URL removed first, AGENT_INSTRUCTIONS and MCP_SERVER_INSTRUCTIONS hold no top-level directory of git ls-files followed by /, and no *.md name other than AGENTS.md and CLAUDE.md (adapt the branch's test, which also matched the URL).
• An MCP client connects and gets the server instructions, and reads the resource: getInstructions() equals MCP_SERVER_INSTRUCTIONS, starts with the title, holds ## Rules for every agent and ## MCP, and is at most 4096 characters; listResources holds simlock://instructions with text/markdown; readResource equals simlock instructions output; every name from listTools appears in the text.

Done when

• simlock instructions and simlock instructions --json behave as above, verified by pnpm test:e2e e2e/agent-instructions.test.ts.
• simlock --help lists instructions.
• An MCP client gets the server instructions and can read simlock://instructions, verified by pnpm test:e2e e2e/mcp-session.test.ts.
• reference/cli.mdx documents the command and lists it among the exempt commands; connect-your-agent.mdx has no hand-written rules block and points at simlock instructions.
• pnpm check is green.

Out of scope

• Generating the text from the live catalog or config; it is static.
• Describing simlock run holds a lease around one command, and a detached lease follows the agent process #944, simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948, MCP: a run_on_device tool runs simctl, adb or devicectl against the session's lease #949, agent-device on the same Mac works with no operator step: loopback session identity and on-by-default #950: each updates its section when it ships.
• agent-device open --physical (F13): the text teaches phones through simlock lease --physical.
• An MCP prompt primitive or a new MCP tool.
• simlock setup: One command installs the agent rules where agent tools read them #620.

Depends on

Written by an agent.