feat(cli): add proof install-skill so docs stay copy-pasteable

.agents/skills/proof/setup.md

@@ -1,43 +1,28 @@
 # Proof setup
 
-The canonical skill files live in this package. The repository
-`.agents/skills/proof/` directory is an exclusively generated
-projection: do not edit it directly, and stale projected files are deleted by
-`pnpm skills:sync`.
+## 1. Install the matching CLI and skill
 
-## 1. Choose the package manager
-
-Use the nearest `package.json`'s `packageManager` field first. If it is absent,
-inspect lockfiles. Exactly one of `package-lock.json`, `pnpm-lock.yaml`,
-`yarn.lock`, or `bun.lock`/`bun.lockb` must exist. If multiple conflicting
-lockfiles exist, ask the user which manager owns the project.
-
-For an end-user release, read `release.json` next to this file. It is the
-canonical package and tag authority: use its `flatbreadVersion` and `gitTag`
-values exactly. `skills-lock.json` is installation provenance/restore data only;
-do not use its optional ref or version fields as release identity:
+From the project root, with npm, pnpm, Yarn, or Bun:
 
 ```bash
-npx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
-npm install --save-dev flatbread@<flatbreadVersion>
+npx --yes flatbread@latest proof install-skill
 ```
 
-Equivalent commands are:
+That command downloads the latest `flatbread` CLI, adds that exact version as
+a devDependency, and copies the Proof skill that shipped with it into your
+agent skill directories. You do not substitute a version or git tag.
 
-```bash
-pnpm dlx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
-pnpm add -D flatbread@<flatbreadVersion>
+`@latest` only chooses which CLI to run. The installer then pins that CLI's
+exact version in the project — it does not write a floating `latest` range.
+To pin a specific release, replace `@latest` with that version.
 
-yarn dlx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
-yarn add -D flatbread@<flatbreadVersion>
-
-bunx skills add https://github.com/FlatbreadLabs/flatbread/tree/<gitTag>/packages/proof/skills/proof --skill proof
-bun add -d flatbread@<flatbreadVersion>
-```
+The installer detects your package manager from `package.json`'s
+`packageManager` field, then from lockfiles. If several lockfiles conflict
+and `packageManager` is unset, it stops rather than guessing.
 
-Do not use a floating branch, `latest`, or a guessed version. When dogfooding
-the Flatbread monorepo, use its workspace `flatbread` binary and do not install
-Flatbread from npm.
+`release.json` next to this file is lockstep identity for the packaged
+skill. `skills-lock.json` is installation provenance only; do not treat its
+optional ref or version fields as release identity.
 
 ## 2. Review the configuration
 

.flatbread-proof/citations/cit-pr-267-review-maintainer-asides-in-shipped-proof--2ftvd4ph0bh0erbr.md

@@ -0,0 +1,9 @@
+---
+id: cit-pr-267-review-maintainer-asides-in-shipped-proof--2ftvd4ph0bh0erbr
+effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
+title: 'PR 267 review: maintainer asides in shipped Proof setup.md'
+role: evidence
+created_at: '2026-08-24T03:18:39.424Z'
+---
+
+https://github.com/FlatbreadLabs/flatbread/pull/267#discussion_r3840101016

.flatbread-proof/constraints/con-packaged-proof-skill-markdown-must-not-contain-m--a9gse08fkv7zcrxq.md

@@ -0,0 +1,11 @@
+---
+id: con-packaged-proof-skill-markdown-must-not-contain-m--a9gse08fkv7zcrxq
+effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
+title: Packaged Proof skill markdown must not contain maintainer-only asides
+kind: hard
+created_at: '2026-08-24T03:18:48.880Z'
+cites:
+  - cit-pr-267-review-maintainer-asides-in-shipped-proof--2ftvd4ph0bh0erbr
+---
+
+Canonical skill files under packages/proof/skills are the bytes cloud and fresh agents Read. Those agents Read SKILL.md and setup.md before any pack, sync, or install script runs, so git bytes are shipped bytes. Maintainer-only asides (workspace dogfood, generated-projection instructions, pnpm skills:sync) must not appear in that markdown. skills:pack-check is the gate.

.flatbread-proof/decisions/dec-published-proof-skill-bytes-are-consumer-only--9frae0w0nq6wgqm3.md

@@ -0,0 +1,18 @@
+---
+id: dec-published-proof-skill-bytes-are-consumer-only--9frae0w0nq6wgqm3
+effort: eff-effort-graph-memory-and-agent-wedge--szeqvmgqjqnhd002
+title: Published Proof skill bytes are consumer-only
+state: accepted
+created_at: '2026-08-24T03:19:00.581Z'
+derives_from:
+  - con-packaged-proof-skill-markdown-must-not-contain-m--a9gse08fkv7zcrxq
+  - dec-distribute-the-effort-graph-as-a-versioned-agent--8as4sybr34zcqyqh
+cites:
+  - cit-pr-267-review-maintainer-asides-in-shipped-proof--2ftvd4ph0bh0erbr
+---
+
+The distribution Decision still holds: one skill payload, byte-identical local projection. This narrows what that payload may say. It does not supersede it.
+
+Cloud and fresh agents Read SKILL.md then setup.md before any pack, sync, or install script. In-skill deixis such as "this monorepo" and hard prohibitions such as "do not install from npm" bind to the consumer workspace, including other pnpm apps. Maintainer asides therefore leave setup.md. Maintainer workflow lives in AGENTS.md, CONTRIBUTING.md, and the install-skill skipped_workspace path. skills:pack-check is the gate.
+
+Ranked options and the load-order constraint are in the Cursor canvas proof-skill-audience-split.

AGENTS.md

@@ -73,6 +73,7 @@ Quality/simplify stays on Composer. See
 - **Native build scripts are approved in `pnpm-workspace.yaml`.** The `onlyBuiltDependencies` list allows esbuild, sharp, @swc/core, etc. to run their postinstall scripts automatically during `pnpm install`.
 - **Vitest packages run in watch mode by default.** Always use `vitest run` (not bare `vitest`) to get a single run and exit.
 - **`flatbread` CLI is not on PATH globally.** From `examples/nextjs`, prefer `pnpm exec flatbread …` (local binary), or `npx flatbread` from a shell. The `pnpm play` script from the root handles this automatically.
+- **Proof skill in this monorepo.** Use the workspace `flatbread` binary. After editing `packages/proof/skills/proof`, run `pnpm skills:sync`. Do not run `proof install-skill` here; the CLI skips it.
 - **Build before test.** All packages must be built (`pnpm build`) before running tests or starting dev servers. `pnpm test` handles this automatically.
 - **`-H, --https` does not make Flatbread serve HTTPS.** The server listens over plain HTTP whatever you pass. From `examples/nextjs`, run `pnpm exec flatbread start -- next dev --turbopack`.
 - **Full local CI parity check:** `pnpm verify` runs lint, typecheck, build, and all tests.

CHANGELOG.md

@@ -2,8 +2,11 @@
 
 ## Unreleased
 
-Notes for the Flatbread release train. Some packages also keep their own
-changelog; this file covers the repository as a whole.
+- `flatbread proof install-skill` installs the Proof skill that shipped with
+  the running CLI and pins that same `flatbread` version as a devDependency.
+  End-user docs now tell people to run
+  `npx --yes flatbread@latest proof install-skill`, so README copy-paste
+  blocks no longer need a version or git tag on every release.
 
 ## 1.1.0
 

CONTRIBUTING.md

@@ -234,17 +234,20 @@ Details:
 Protect release tags in the repository settings so they cannot be moved or
 deleted after publication.
 
-End users install the skill from that release tag and install the matching
-`flatbread` version. Replace `X` with the released version — `1.0.0` for the
-first stable release, so the tag is `v1.0.0`:
+End users do not copy a version or git tag. After a release is on npm they
+run:
 
 ```bash
-npx skills add https://github.com/FlatbreadLabs/flatbread/tree/vX/packages/proof/skills/proof --skill proof
-npm install --save-dev flatbread@X
+npx --yes flatbread@latest proof install-skill
 ```
 
-`skills update` does not advance an immutable tag. To upgrade deliberately,
-install a newer release tag and its matching `flatbread` version.
+That command downloads the published CLI, pins that exact `flatbread`
+version as a devDependency, and copies the Proof skill that shipped inside
+the package. `@latest` only chooses which CLI to run. To pin an older
+release, replace `@latest` with that version.
+
+`skills update` does not advance an immutable install. To upgrade, run the
+installer again from a newer CLI.
 
 ## Troubleshooting
 

packages/flatbread/README.md

@@ -47,17 +47,18 @@ repository, so the next session and your coworkers read the same reasons,
 review them in a pull request, and trace how a choice changed. Nothing lives
 in a private chat log or a hosted store.
 
-The install pins below come from the current
-[Proof release manifest](https://github.com/FlatbreadLabs/flatbread/blob/main/packages/proof/skills/proof/release.json). Use the values in that file exactly; do not substitute a
-floating branch or guessed version.
-
 1. Install the Proof skill and the matching `flatbread` package:
 
    ```bash
-   npx skills add https://github.com/FlatbreadLabs/flatbread/tree/v1.1.0/packages/proof/skills/proof --skill proof
-   npm install --save-dev flatbread@1.1.0
+   npx --yes flatbread@latest proof install-skill
    ```
 
+   That command downloads the latest `flatbread` CLI, pins that exact version
+   as a devDependency, and copies the Proof skill that shipped with it. You
+   do not copy a version number or git tag. `@latest` only chooses which CLI
+   to run; the project then receives that CLI's exact version. To pin an
+   older release, replace `@latest` with that version.
+
 2. Add the Proof content model to `flatbread.config.js`, keeping any content
    entries you already have:
 

packages/flatbread/bin/flatbread.js

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-import { resolve } from 'path';
+import { dirname, resolve } from 'path';
 import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
 
-// In CI/CD, check if the file exists before importing it. This is to prevent some environments from throwing an error before the library is built.
-if (process.env.FLATBREAD_CI) {
-  const cliPath = resolve(
-    process.cwd(),
-    'node_modules',
-    'flatbread',
-    'dist',
-    'cli',
-    'index.js'
-  );
+const cliPath = resolve(
+  dirname(fileURLToPath(import.meta.url)),
+  '../dist/cli/index.js'
+);
 
+// In CI, skip the import when dist is not built yet so the process
+// does not throw before `pnpm build`. Check the file next to this
+// bin, not `cwd/node_modules/flatbread`, because spawned tests and
+// user projects run with a different working directory.
+if (process.env.FLATBREAD_CI) {
   if (existsSync(cliPath)) {
     import('../dist/cli/index.js');
   } else {