feat: add agent setup and machine-readable CLI reference

README.md

@@ -62,6 +62,69 @@ paths, and links. `--json` prints a result array. Open launches the exact page
 in a browser; `--print` emits its URL instead. These commands use network
 access but do not use your Polymorfa credentials.
 
+## Set up coding agents
+
+Install the [Polymorfa agent kit](https://github.com/polymorfa/agent-kit) in
+coding agents detected on your machine:
+
+```shell
+polymorfa agent setup --dry-run
+polymorfa agent setup
+polymorfa agent setup --client claude --client codex --yes
+```
+
+Setup detects `claude`, `codex`, `gemini`, and `cursor` on PATH. A `~/.cursor`
+directory also detects Cursor. Repeat `--client` to select clients explicitly;
+an unavailable requested client fails. Without `--yes`, setup asks for confirmation
+immediately before the first installation. Instructions and already-installed
+clients need no confirmation. Non-interactive installation requires `--yes`.
+
+| Client      | Installation behavior                                                                                                                                                                          |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Claude Code | Adds `polymorfa/agent-kit` as the `polymorfa` marketplace, then installs `polymorfa@polymorfa`. The repository must contain its marketplace manifest.                                          |
+| Codex       | Checks local help for Git marketplace and plugin installation support, then adds the same marketplace and plugin through the native installer. Older versions receive repository instructions. |
+| Gemini CLI  | Installs the repository through `gemini extensions install`, passing `--consent` after setup confirmation.                                                                                     |
+| Cursor      | Prints instructions to install from the Cursor marketplace or repository.                                                                                                                      |
+
+`--dry-run` prints exact installation commands. It may run Codex help probes,
+but never runs installers or reads installation listings. Setup does not load
+Polymorfa profiles, read credentials, or edit client settings directly. Client
+installers manage their own configuration. Their output is withheld because it
+may contain private local data. Each client gets a separate result; any failure
+makes the command exit with code 1. Manual instructions are reported separately
+and do not claim installation succeeded.
+
+Repeat runs use native plugin or extension listings to report `already installed`
+when the client can identify the kit. Existing marketplaces are retained only
+when their source matches agent-kit; a name conflict fails without replacing it.
+Installation adds skills, plugin manifests, and the public documentation MCP.
+It does not configure authenticated API access. Marketplace publication, native
+client acceptance, and CLI package publication remain separate steps.
+
+## Generate the CLI reference
+
+```shell
+npm run docs:reference
+npm run docs:reference:check
+```
+
+The generator builds the CLI, creates an oclif manifest from compiled commands,
+and writes `contracts/cli-reference.json`. Schema version 1 includes `cliVersion`
+and sorted public commands with space-separated IDs, summaries, descriptions,
+usage arrays, aliases, positional arguments, flags, examples, and command state.
+It excludes hidden commands, aliases, arguments, and flags. Arguments retain
+positional order; commands and flags are sorted by name. Missing optional scalar
+metadata is `null`, missing text is an empty string, and missing lists are empty.
+Examples contain `command` and `description`; plain oclif examples have an empty
+description. Fallback usage includes positional arguments and `[flags]`; flag
+details live in the separate `flags` array.
+
+The docs site can consume this file to build one `/cli` page per command. This
+repository exports the reference; it does not publish those pages. `npm run
+verify` rebuilds the CLI and fails when the committed reference is stale. Regenerate
+it whenever public command metadata or the package version changes. No timestamp
+or local path is included.
+
 ## Authentication profiles
 
 Until the backend exposes a revocable CLI device-authorization flow, login