Add REFERENCE.md with auto-generated CLI help documentation

.github/workflows/ci.yml

@@ -31,6 +31,13 @@ jobs:
       - name: Build
         run: pnpm run build
 
+      - name: Check REFERENCE.md is up to date
+        # REFERENCE.md is captured from the CLI's own --help output, so any change to
+        # help text has to be regenerated and committed with it. Node version does not
+        # affect the output, so one column of the matrix is enough.
+        if: matrix.node-version == 24
+        run: pnpm run check:reference
+
       - name: Unit tests
         run: pnpm run test:unit
 

.github/workflows/release.yml

@@ -121,6 +121,10 @@ jobs:
         if: inputs.type == 'release'
         run: pnpm run build:readme
 
+      - name: Update REFERENCE.md
+        if: inputs.type == 'release'
+        run: pnpm run build:reference
+
       - name: Report install size
         id: install-size
         # Measures the tarball/unpacked/full-install size of what will be
@@ -288,7 +292,7 @@ jobs:
           NEW_VERSION="${{ steps.release.outputs.version }}"
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add package.json pnpm-lock.yaml CHANGELOG.md README.md
+          git add package.json pnpm-lock.yaml CHANGELOG.md README.md REFERENCE.md
           git commit -m "v${NEW_VERSION}"
           git tag -a "v${NEW_VERSION}" -m "Release v${NEW_VERSION}"
           git push origin main

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- New [REFERENCE.md](REFERENCE.md) with the full `--help` output of every mcpc command, generated from the CLI itself so it always matches the release.
+
 ## [0.6.0] - 2026-08-02
 
 ### Added

CLAUDE.md

@@ -161,7 +161,7 @@ mcpc/
 - `mcpc clean [sessions|profiles|logs|all ...]` - Clean up mcpc data
 - `mcpc help [command]` - Show help for a specific command (`--skill` prints the agent guide)
 
-Run `mcpc --help` and `mcpc help <command>` for the authoritative, always-current inventory — the usage block in README.md is generated from it.
+Run `mcpc --help` and `mcpc help <command>` for the authoritative, always-current inventory — the usage block in README.md and the whole of REFERENCE.md are generated from it.
 
 **Server formats for `connect`, `login`, `logout`:**
 
@@ -638,6 +638,8 @@ For any non-trivial change (new feature, bug fix, behaviour change, or notable r
 
 Whenever a change touches the user-facing CLI surface — adding, renaming, or removing commands or flags, changing argument syntax, defaults, session states, or workflows — check the agent skill at `skills/mcpc/SKILL.md` (printed by `mcpc help --skill`) and update it so it keeps matching the actual CLI behaviour and README. The skill is a curated guide, not an exhaustive reference: it must never contradict the CLI, but it doesn't need to enumerate every flag — keep it concise and only add features that matter to agents. Purely internal changes don't need a skill update; as a rule of thumb, any change that warrants a `CHANGELOG.md` entry also warrants a quick skill check.
 
+Any change to help text — a description, an option, an `addHelpText` section, a new command — also changes `REFERENCE.md`, which is captured verbatim from `mcpc --help` and `mcpc help <command>`. Never edit it by hand: run `pnpm run build:reference` and commit the result. CI runs `pnpm run check:reference` and fails when the committed file has drifted from the CLI, so this is not optional.
+
 Keep the MCP conformance tests up to date the same way you keep the e2e tests up to date. Whenever a change touches protocol behaviour, the OAuth/authentication flows, or transport handling, check `test/conformance/` in the same PR: update the adapter (`test/conformance/client.mjs`) if the change alters what a scenario observes, and wire up a matching upstream scenario when a new feature has one. Run the affected scenario locally before finishing — see `test/conformance/README.md` for the command, the current coverage table, and the list of scenarios that are not covered yet. A deliberate behaviour change that breaks the adapter must be fixed in the PR that makes the change, not discovered later when a release is gated on it.
 
 Keep each changelog entry to one or two short sentences focused on the user-visible behaviour. Do not enumerate implementation details, internal class names, or step-by-step breakdowns — readers want to know what changed for them, not how it was built. If an entry needs subheadings or its own bulleted breakdown, it's too long.
@@ -785,7 +787,7 @@ Before releasing:
 2. Ensure your branch is clean, up-to-date with `origin/main`, and all CI checks pass
 3. Run `pnpm run release` (or `pnpm run release:minor` / `pnpm run release:major`)
 
-The script validates preconditions locally (including `pnpm run check:deps-age`, see below), then triggers the `release.yml` GitHub Actions workflow which handles: dependency-age gate, lint, build, test, version bump, changelog update, README update, git commit/tag/push, npm publish (with provenance), and GitHub release creation.
+The script validates preconditions locally (including `pnpm run check:deps-age`, see below), then triggers the `release.yml` GitHub Actions workflow which handles: dependency-age gate, lint, build, test, version bump, changelog update, README and REFERENCE update, git commit/tag/push, npm publish (with provenance), and GitHub release creation.
 
 ### Dependency-age gate
 

CONTRIBUTING.md

@@ -29,6 +29,10 @@ If your change touches the user-facing CLI surface (commands, flags, argument sy
 or workflows), also update the built-in agent skill at [`skills/mcpc/SKILL.md`](./skills/mcpc/SKILL.md)
 (printed by `mcpc help --skill`) so it keeps matching the CLI and README.
 
+If your change touches any help text, regenerate [`REFERENCE.md`](./REFERENCE.md) with
+`pnpm run build:reference` and commit it — it is captured verbatim from `mcpc --help` and
+`mcpc help <command>`, and CI fails when it has drifted (`pnpm run check:reference`).
+
 ## Development setup
 
 This repo uses [pnpm](https://pnpm.io/) 10 (pinned via `packageManager` in `package.json`). If you
@@ -115,8 +119,8 @@ pnpm run release:major    # major version bump (0.1.2 → 1.0.0)
 
 The script validates preconditions locally (clean branch, up-to-date with `origin/main`, dependency
 age), then triggers the `release.yml` GitHub Actions workflow which handles lint, build, test, version
-bump, changelog update, README update, git commit/tag/push, npm publish (with provenance), and
-GitHub release creation.
+bump, changelog update, README and REFERENCE update, git commit/tag/push, npm publish (with
+provenance), and GitHub release creation.
 
 ## Architecture
 

README.md

@@ -189,6 +189,9 @@ Run "mcpc --json" to get the same data as `{ sessions: [...], profiles: [...] }`
 Agent guide: mcpc help --skill
 ```
 
+For the full `--help` output of every command, see [REFERENCE.md](REFERENCE.md)
+(also available in your terminal via `mcpc help <command>`).
+
 ### General actions
 
 With no arguments, `mcpc` lists all active sessions and saved OAuth profiles: