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

[tonyketcham]

Summary of changes

End-user READMEs and the Proof setup skill previously asked people to substitute a git tag and package version, or they hardcoded a release. Those snippets rot on every publish.

This adds flatbread proof install-skill. One copy-paste command, npx --yes flatbread@latest proof install-skill, downloads the latest CLI, pins that exact flatbread version as a devDependency, and copies the Proof skill that shipped with it. @latest only chooses which CLI to run.

The installer detects npm, pnpm, Yarn, or Bun from packageManager or a single lockfile, skips this monorepo, and refuses conflicting lockfiles. Pack checks now reject version placeholders in skill docs.

Users copy one command. Maintainers still keep release.json in lockstep for pack identity.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

• I added doc comments to any new public exports, and inline comments to any hard-to-understand areas
• My changes generate no new console errors locally
• If applicable, try to include a test that fails without this PR but passes with it

Does this introduce any non-backwards compatible changes?

• Yes
• No

Does this include any user config changes?

• Yes
  • If so, I have updated the relevant areas of documentation
• No

The documented install path changes from a versioned snippet to npx --yes flatbread@latest proof install-skill. Existing projects keep working.

  

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bb7a502. Configure here.}

[mergify]

Tick the box to add this pull request to the merge queue (same as @mergifyio queue).

• Queue this pull request

[cursor]

Stale comment

REQUEST_CHANGES

flatbread proof install-skill is the right seam: one copy-paste command, pin the running CLI, copy the skill that shipped with it. The Yarn path is not.

Prior notes closed: none (first review). Skip resolve.

What must change
A Yarn 1 project (yarn.lock, or packageManager: yarn@1.22.22) plans yarn dlx after yarn add has already rewritten the manifest. Yarn Classic has no dlx. managerFromField keeps only the name, so yarn@1.x is treated as Berry. setup.md says Yarn works.

Smallest fix: keep yarn add --dev --exact for the package; run the skill step with npx --yes skills (or route Yarn 1 there). Add a planProofSkillInstall('yarn') test so Classic cannot land on yarn dlx again.

Domain verdicts

• architecture — REQUEST_CHANGES (Yarn Classic vs documented Yarn)
• quality — COMMENT (launcher table / duplicated @latest prose; not blocking)
• proof-journal — APPROVE (no new record; unique signal already lives in CONTRIBUTING, CHANGELOG, pack check, and tests)
• correctness — REQUEST_CHANGES (Yarn dlx; residual Windows bunx.cmd)

Held

• Unpinned skills CLI is the same risk as the old npx skills add path. Not new.
• Workspace skip by name === '@flatbread/monorepo' is good enough for this repo.
• Defaulting to npm with no lockfile is the usual default.

Models
architecture / proof / correctness: inherit (cursor-grok-4.6-high-fast)
quality: composer-2.5

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

Stale comment

REQUEST_CHANGES

flatbread proof install-skill is the right seam, and the last two installer bugs are closed. The remaining block is the file that command copies.

Prior notes closed

• Yarn Classic yarn dlx — fully addressed (npx --yes skills + plan test).
• Windows bunx.cmd — fully addressed (cmd.exe / ComSpec, no .cmd suffix).

What must change
packages/proof/skills/proof/setup.md is the consumer contract. This PR added pnpm skills:sync to the dogfooding paragraph. After copy, a user-project agent can skip npm, look for a workspace flatbread binary, or run pnpm skills:sync. That matches Tony's comment.

Smallest fix: delete the opener (generated .agents/ projection) and the dogfooding paragraph from this single source. Keep maintainer steps in CONTRIBUTING.md, packages/proof/README.md, and the skipped_workspace CLI message. Extend verifyPackPayload to reject pnpm skills:sync and “dogfooding this monorepo” the same way it already rejects the monorepo CLI path. Do not add a second skill source or a pack-time rewrite.

Domain verdicts

• architecture — REQUEST_CHANGES (shipped skill still teaches Flatbread-only workflow)
• quality — COMMENT (same docs defect; other duplication is not blocking)
• proof-journal — APPROVE (no new record; unique signal already lives in CONTRIBUTING, CHANGELOG, pack check, and tests)
• correctness — COMMENT (Yarn/Windows closed; residual is the shipped-skill agent misread)

Held

• Unpinned skills CLI is the same risk as the old npx skills add path. Not new.
• Workspace skip by name === '@flatbread/monorepo' is good enough for this repo.
• Defaulting to npm with no lockfile is the usual default.

Models
architecture / proof / correctness: inherit (latest Cursor Grok)
quality: composer-2.5

  

_{Sent by Cursor Automation: Flatbread PR Review}

[cursor]

APPROVE

091f8b7 closes the last block. The file install-skill copies is consumer-only again.

Prior notes closed

• Shipped setup.md taught workspace flatbread and pnpm skills:sync — fully addressed (those blocks left the canonical skill; maintainer steps live in AGENTS.md, CONTRIBUTING.md, and the skipped_workspace CLI message).
• Pack-check allowed those phrases — fully addressed (forbiddenSkillSubstrings plus a wrap test).

Domain verdicts

• architecture — APPROVE (one skill source; no pack-time rewrite; pack-check is the gate)
• quality — COMMENT (dead version option and repeated @latest prose; not blocking)
• proof-journal — COMMENT (Constraint scores 4/4 on load-order: agents Read setup.md before any pack or sync. Decision is 3/4: alternatives and reversal sit in canvas proof-skill-audience-split, not in the record. Siblings stay proposed. install-skill itself still needs no extra record.)
• correctness — APPROVE (Yarn Classic, Windows cmd.exe, and CI bin path stay closed; both setup.md copies match)

Held

• The pack denylist is four known phrases. A new aside that avoids them can still ship.
• Parent Decision dec-distribute-the-effort-graph-as-a-versioned-agent--8as4sybr34zcqyqh still describes git-tag install. Update later; do not block this PR.
• Unpinned skills CLI, workspace skip by package name, default npm with no lockfile, and Windows %VAR% expansion stay residual.

Models
architecture / proof / correctness: inherit (latest Cursor Grok)
quality: composer-2.5

  

_{Sent by Cursor Automation: Flatbread PR Review}