Move REFERENCE.md to docs/ directory and relax supply-chain gate

.github/workflows/release.yml

@@ -292,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 REFERENCE.md
+          git add package.json pnpm-lock.yaml CHANGELOG.md README.md docs/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

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### 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.
+- New [REFERENCE.md](docs/REFERENCE.md) with the full `--help` output of every mcpc command, generated from the CLI itself so it always matches the release.
 - `mcpc @session` and `server-discover` now show the description and website URL a server advertises about itself, right below its name.
 
 ### Fixed

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 and the whole of REFERENCE.md are 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 docs/REFERENCE.md are generated from it.
 
 **Server formats for `connect`, `login`, `logout`:**
 
@@ -638,7 +638,7 @@ 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.
+Any change to help text — a description, an option, an `addHelpText` section, a new command — also changes `docs/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.
 

CONTRIBUTING.md

@@ -29,7 +29,7 @@ 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
+If your change touches any help text, regenerate [`docs/REFERENCE.md`](./docs/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`).
 
@@ -57,8 +57,8 @@ pnpm link --global
 mcpc --help
 ```
 
-As a supply-chain hardening measure, `pnpm-workspace.yaml` sets `minimumReleaseAge: 7200`, so newly
-published third-party packages aren't installed until they're at least 5 days old. If a fresh
+As a supply-chain hardening measure, `pnpm-workspace.yaml` sets `minimumReleaseAge: 4320`, so newly
+published third-party packages aren't installed until they're at least 3 days old. If a fresh
 dependency bump seems "stuck," that's why — wait it out, or add a targeted exclusion in
 `minimumReleaseAgeExclude` if you have a justified reason.
 

README.md

@@ -189,7 +189,7 @@ 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)
+For the full `--help` output of every command, see [REFERENCE.md](docs/REFERENCE.md)
 (also available in your terminal via `mcpc help <command>`).
 
 ### General actions

REFERENCE.md → docs/REFERENCE.md

@@ -6,7 +6,7 @@ Complete `--help` output for every `mcpc` command, in the order the commands are
 by `mcpc --help`. It is generated from the CLI itself, so it always matches the installed
 version — run `mcpc help <command>` to get the same text in your terminal.
 
-New to mcpc? Start with the [README](README.md), or run `mcpc help --skill` for the agent guide.
+New to mcpc? Start with the [README](../README.md), or run `mcpc help --skill` for the agent guide.
 
 - [`mcpc connect`](#mcpc-connect)
 - [`mcpc close`](#mcpc-close)

pnpm-workspace.yaml

@@ -1,24 +1,13 @@
 # Supply-chain protection: require packages to be at least X days old before pnpm will install them.
 # Mitigates compromised npm packages discovered and yanked within the first day (shai-hulud worm,
-# nx self-replicator, etc.). 7200 minutes = 5 days.
-minimumReleaseAge: 7200
-
-# The MCP TypeScript SDK ships fast and mcpc tracks it closely (the
-# 2026-07-28 protocol support depends on the latest release), so exempt the SDK
-# packages from the release-age gate. Scoped to the official
-# @modelcontextprotocol org only; everything else keeps the 5-day quarantine.
-# Remove entries once the pinned version is older than the age limit.
+# nx self-replicator, etc.). 4320 minutes = 3 days.
 #
 # Note: pnpm 10 applies minimumReleaseAge only when *resolving*, and does not re-check an
 # existing lockfile on a --frozen-lockfile install (that landed in pnpm 11). The release
-# gate in scripts/check-dependency-age.mjs enforces it over the committed lockfile, and
-# holds the packages below to a 48-hour floor rather than exempting them outright.
-minimumReleaseAgeExclude:
-  - "@modelcontextprotocol/client"
-  - "@modelcontextprotocol/core"
-  - "@modelcontextprotocol/server"
-  - "@modelcontextprotocol/node"
-  - "@modelcontextprotocol/sdk"
+# gate in scripts/check-dependency-age.mjs enforces the same threshold over the committed
+# lockfile at release time. If a package ever needs a justified exemption, add it to
+# minimumReleaseAgeExclude — the release gate still holds excluded packages to a 48-hour floor.
+minimumReleaseAge: 4320
 
 # @napi-rs/keyring ships a native node binding that needs to be built/copied
 # into place on install. Without this entry pnpm v10 refuses to run its

scripts/generate-reference.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Generates REFERENCE.md — the `--help` output of every mcpc command, in the order
+ * Generates docs/REFERENCE.md — the `--help` output of every mcpc command, in the order
  * the commands appear in `mcpc --help`.
  *
  * The CLI's help text is mcpc's primary documentation surface (see CLAUDE.md), so the
@@ -9,8 +9,8 @@
  * committed file has drifted from the CLI.
  *
  * Usage:
- *   node scripts/generate-reference.mjs          Write REFERENCE.md
- *   node scripts/generate-reference.mjs --check  Verify REFERENCE.md is up to date
+ *   node scripts/generate-reference.mjs          Write docs/REFERENCE.md
+ *   node scripts/generate-reference.mjs --check  Verify docs/REFERENCE.md is up to date
  */
 
 import { execFileSync } from 'node:child_process';
@@ -21,7 +21,7 @@ import { fileURLToPath } from 'node:url';
 
 const PROJECT_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
 const CLI = join(PROJECT_ROOT, 'bin', 'mcpc');
-const OUTPUT_FILE = join(PROJECT_ROOT, 'REFERENCE.md');
+const OUTPUT_FILE = join(PROJECT_ROOT, 'docs', 'REFERENCE.md');
 
 /**
  * Placeholder session name used for the session command help screens. The CLI accepts it
@@ -205,7 +205,7 @@ Complete \`--help\` output for every \`mcpc\` command, in the order the commands
 by \`mcpc --help\`. It is generated from the CLI itself, so it always matches the installed
 version — run \`mcpc help <command>\` to get the same text in your terminal.
 
-New to mcpc? Start with the [README](README.md), or run \`mcpc help --skill\` for the agent guide.
+New to mcpc? Start with the [README](../README.md), or run \`mcpc help --skill\` for the agent guide.
 
 ${toc}
 
@@ -226,13 +226,13 @@ if (checkOnly) {
   const current = existsSync(OUTPUT_FILE) ? readFileSync(OUTPUT_FILE, 'utf8') : '';
   if (current !== generated) {
     console.error(
-      'ERROR: REFERENCE.md is out of date with the CLI help output.\n' +
+      'ERROR: docs/REFERENCE.md is out of date with the CLI help output.\n' +
         '       Run "pnpm run build:reference" and commit the result.'
     );
     process.exit(1);
   }
-  console.log('REFERENCE.md is up to date.');
+  console.log('docs/REFERENCE.md is up to date.');
 } else {
   writeFileSync(OUTPUT_FILE, generated);
-  console.log(`REFERENCE.md updated (${generated.split('\n').length} lines).`);
+  console.log(`docs/REFERENCE.md updated (${generated.split('\n').length} lines).`);
 }