← back to Cli Printing Press
docs(cli): canonicalize README install block + cross-repo sweep dependency note (#1464)
77b91be63f3f06f6d88c898868d8de8377c5d6f8 · 2026-05-15 13:42:04 -0700 · Trevin Chow
* docs(templates): canonicalize README install block + cross-repo sweep dependency note
Make `internal/generator/templates/readme.md.tmpl` produce the
same canonical install block that the published library now
carries. Fresh prints from this generator land canonical on day
one; the published library's `tools/sweep-canonical/` handles
retrofitting older entries.
## Install block
- Headline names the agent set the bundled skill install reaches:
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, plus a
link to the upstream `skills` CLI for the full list.
- Documents `--cli-only`, `--skill-only`, and `--agent` (repeatable,
single and multi examples) as first-class options below the
default command. The previous template only showed `--cli-only`;
`--skill-only` and `--agent` existed in the installer but weren't
surfaced to readers.
## Section reordering
- `## Use with Claude Desktop` moves from near the bottom of the
README up to live right after `## Install for OpenClaw`. All
alternate install paths are now grouped at the top of the README:
Install → Install for Hermes → Install for OpenClaw → Use with
Claude Desktop (when present).
- `## Use with Claude Code` is removed entirely. Its `npx skills
add` install command is now redundant with the canonical
`## Install` block (which documents `--skill-only` for the same
effect). Its MCP `<details>` subsection lived in an unstructured
spot and inconsistent across CLIs; if Claude Code MCP-registration
guidance turns out to be load-bearing, we can add it back as a
dedicated section rather than buried inside a Claude-Code-only
section.
## Cross-repo dependency note
Adds a "Cross-repo dependency: published-library sweep tool"
section to AGENTS.md that captures the relationship: template
changes that shift canonical published-library shape must be
mirrored in `tools/sweep-canonical/main.go` in
`mvanhorn/printing-press-library` so existing entries can be
retrofitted, or a tracking issue must be filed before the template
PR lands. Without that, fresh prints get the new shape while
existing entries silently drift.
## Tests
- 878 generator tests pass.
- Golden fixtures updated for 3 cases whose README.md output shifts
(generate-golden-api, generate-golden-api-rich-auth,
generate-public-param-names) — diffs verified to match the
intended template change (new install subsections + Claude Desktop
moved up + Claude Code section deleted).
- Removed TestGeneratedOutput_READMEBearerTokenMCPSetup, which
asserted on a `claude mcp add ...` command rendered inside the
now-deleted `## Use with Claude Code` section. The MCP-binary
registration path lives in the Claude Desktop section's manual
JSON config `<details>`; if a separate Claude Code MCP test is
needed later it should target whatever section we add for that.
The matching library sweep landed in mvanhorn/printing-press-library#584.
* fix: address Greptile feedback (#1464)
1. Drop the extra blank line before `### Without Node` in the
rendered README. The new `--agent` subsection's trailing blank
plus the un-trimmed `{{ if .Category}}` directive's preserved
newline produced two consecutive blank lines. Removing the
template-side blank line restores single-blank-line separation.
2. Restore bearer_token README coverage. Removing
`TestGeneratedOutput_READMEBearerTokenMCPSetup` correctly
followed the deletion of `## Use with Claude Code`, but left
the bearer_token branches in the relocated `## Use with Claude
Desktop` section untested. New
`TestGeneratedOutput_READMEBearerTokenClaudeDesktop` exercises
the canonical-env-var-present branch (mirrors the original
test's spec shape) and asserts on the step-3 prompt naming the
env var, the env var in the Manual JSON config block, and the
absence of the canonical-env-var-absent preamble.
3. Update goldens for the blank-line fix (3 README fixtures).
Files touched
M AGENTS.mdM internal/generator/generator_test.goM internal/generator/templates/readme.md.tmplM testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/README.mdM testdata/golden/expected/generate-golden-api/printing-press-golden/README.mdM testdata/golden/expected/generate-public-param-names/public-param-golden/README.md
Diff
commit 77b91be63f3f06f6d88c898868d8de8377c5d6f8
Author: Trevin Chow <trevin@trevinchow.com>
Date: Fri May 15 13:42:04 2026 -0700
docs(cli): canonicalize README install block + cross-repo sweep dependency note (#1464)
* docs(templates): canonicalize README install block + cross-repo sweep dependency note
Make `internal/generator/templates/readme.md.tmpl` produce the
same canonical install block that the published library now
carries. Fresh prints from this generator land canonical on day
one; the published library's `tools/sweep-canonical/` handles
retrofitting older entries.
## Install block
- Headline names the agent set the bundled skill install reaches:
Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, plus a
link to the upstream `skills` CLI for the full list.
- Documents `--cli-only`, `--skill-only`, and `--agent` (repeatable,
single and multi examples) as first-class options below the
default command. The previous template only showed `--cli-only`;
`--skill-only` and `--agent` existed in the installer but weren't
surfaced to readers.
## Section reordering
- `## Use with Claude Desktop` moves from near the bottom of the
README up to live right after `## Install for OpenClaw`. All
alternate install paths are now grouped at the top of the README:
Install → Install for Hermes → Install for OpenClaw → Use with
Claude Desktop (when present).
- `## Use with Claude Code` is removed entirely. Its `npx skills
add` install command is now redundant with the canonical
`## Install` block (which documents `--skill-only` for the same
effect). Its MCP `<details>` subsection lived in an unstructured
spot and inconsistent across CLIs; if Claude Code MCP-registration
guidance turns out to be load-bearing, we can add it back as a
dedicated section rather than buried inside a Claude-Code-only
section.
## Cross-repo dependency note
Adds a "Cross-repo dependency: published-library sweep tool"
section to AGENTS.md that captures the relationship: template
changes that shift canonical published-library shape must be
mirrored in `tools/sweep-canonical/main.go` in
`mvanhorn/printing-press-library` so existing entries can be
retrofitted, or a tracking issue must be filed before the template
PR lands. Without that, fresh prints get the new shape while
existing entries silently drift.
## Tests
- 878 generator tests pass.
- Golden fixtures updated for 3 cases whose README.md output shifts
(generate-golden-api, generate-golden-api-rich-auth,
generate-public-param-names) — diffs verified to match the
intended template change (new install subsections + Claude Desktop
moved up + Claude Code section deleted).
- Removed TestGeneratedOutput_READMEBearerTokenMCPSetup, which
asserted on a `claude mcp add ...` command rendered inside the
now-deleted `## Use with Claude Code` section. The MCP-binary
registration path lives in the Claude Desktop section's manual
JSON config `<details>`; if a separate Claude Code MCP test is
needed later it should target whatever section we add for that.
The matching library sweep landed in mvanhorn/printing-press-library#584.
* fix: address Greptile feedback (#1464)
1. Drop the extra blank line before `### Without Node` in the
rendered README. The new `--agent` subsection's trailing blank
plus the un-trimmed `{{ if .Category}}` directive's preserved
newline produced two consecutive blank lines. Removing the
template-side blank line restores single-blank-line separation.
2. Restore bearer_token README coverage. Removing
`TestGeneratedOutput_READMEBearerTokenMCPSetup` correctly
followed the deletion of `## Use with Claude Code`, but left
the bearer_token branches in the relocated `## Use with Claude
Desktop` section untested. New
`TestGeneratedOutput_READMEBearerTokenClaudeDesktop` exercises
the canonical-env-var-present branch (mirrors the original
test's spec shape) and asserts on the step-3 prompt naming the
env var, the env var in the Manual JSON config block, and the
absence of the canonical-env-var-absent preamble.
3. Update goldens for the blank-line fix (3 README fixtures).
---
AGENTS.md | 12 ++
internal/generator/generator_test.go | 25 ++-
internal/generator/templates/readme.md.tmpl | 219 ++++++++-------------
.../printing-press-rich-auth/README.md | 114 +++++------
.../printing-press-golden/README.md | 114 +++++------
.../public-param-golden/README.md | 106 +++++-----
6 files changed, 262 insertions(+), 328 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 882f0495..e444a469 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -63,6 +63,18 @@ Run `scripts/golden.sh verify` whenever a change may affect CLI command output,
Never update goldens just to make a failing check pass. Run `scripts/golden.sh update` only when the behavior change is intentional, then inspect the diff and explain it in your final response. See [`docs/GOLDEN.md`](docs/GOLDEN.md) for the decision rubric, fixture conventions, and failure handling.
When adding a new deterministic CLI behavior or generated artifact contract, explicitly decide whether the golden suite needs a new or expanded fixture. A passing `scripts/golden.sh verify` on existing cases does not prove coverage for new auth, pagination, MCP, manifest, naming, or similar deterministic generation behavior.
+## Cross-repo dependency: published-library sweep tool
+
+When a change to `internal/generator/templates/readme.md.tmpl` or `skill.md.tmpl` shifts canonical published-library shape — install-block structure, top-of-README section ordering, presence or removal of `## ` sections, frontmatter top-level field set, install command syntax — also update `tools/sweep-canonical/main.go` in [`mvanhorn/printing-press-library`](https://github.com/mvanhorn/printing-press-library) so the already-published CLIs can be retrofitted to match. Fresh prints from this generator will produce the new shape automatically, but every existing entry in the public library silently drifts from canonical shape until the sweep retrofit runs.
+
+If you can't make the matching sweep change in the same session, file a tracking issue at https://github.com/mvanhorn/printing-press-library/issues/new before merging the template PR. The issue should include:
+
+1. A link to the template PR here.
+2. The shape change(s) the sweep needs to handle. Sweep changes must be idempotent (second run produces zero textual diff) — name the heading boundaries, regex anchors, or section markers the sweep can hang off.
+3. Any test additions needed in `tools/sweep-canonical/main_test.go`.
+
+Without the sweep update or a tracking issue, the divergence between fresh prints and existing entries is invisible until someone notices a specific published README looks "old" relative to the rest. The downstream side of this contract (the published library's stance on when to run the sweep, how to scope it, and the `-readme-only` + author-preservation safeties on the sweep tool) is documented in `printing-press-library/AGENTS.md` under "Bulk SKILL.md/README.md retrofits".
+
## Project Structure
- `cmd/printing-press/` - CLI entry point
- `internal/spec/` - Internal YAML spec parser
diff --git a/internal/generator/generator_test.go b/internal/generator/generator_test.go
index 44a82104..3d9d44bb 100644
--- a/internal/generator/generator_test.go
+++ b/internal/generator/generator_test.go
@@ -774,7 +774,14 @@ func TestGenerateOAuth2RefreshTokenMechanism(t *testing.T) {
})
}
-func TestGeneratedOutput_READMEBearerTokenMCPSetup(t *testing.T) {
+// TestGeneratedOutput_READMEBearerTokenClaudeDesktop covers the
+// bearer_token rendering inside the `## Use with Claude Desktop`
+// section (the canonicalEnvVar-present branch). Restored after the
+// earlier `## Use with Claude Code` section — and its dedicated test —
+// were removed; the bearer_token MCP-config branches still need a
+// regression test since neither the api_key nor the rich-auth golden
+// fixtures exercise the bearer_token paths.
+func TestGeneratedOutput_READMEBearerTokenClaudeDesktop(t *testing.T) {
t.Parallel()
apiSpec := &spec.APISpec{
@@ -812,8 +819,20 @@ func TestGeneratedOutput_READMEBearerTokenMCPSetup(t *testing.T) {
readme, err := os.ReadFile(filepath.Join(outputDir, "README.md"))
require.NoError(t, err)
content := string(readme)
- assert.Contains(t, content, "claude mcp add bearer bearer-pp-mcp -e BEARER_TOKEN=<your-token>")
- assert.NotContains(t, content, "bearer-pp-cli auth login\n\nclaude mcp add bearer bearer-pp-mcp")
+
+ // canonicalEnvVar-present branch: step 3 of the install list asks
+ // the user to fill in the env var name when Claude Desktop prompts.
+ assert.Contains(t, content, "Fill in `BEARER_TOKEN` when Claude Desktop prompts you.",
+ "bearer_token + canonical env var must render the step-3 prompt naming the env var")
+
+ // Manual JSON config <details> emits the env var in the mcpServers block.
+ assert.Contains(t, content, `"BEARER_TOKEN": "<your-key>"`,
+ "bearer_token + canonical env var must render the env var in the Manual JSON config block")
+
+ // Negative: the canonicalEnvVar-absent preamble must NOT appear when a
+ // canonical env var is set (that branch is mutually exclusive).
+ assert.NotContains(t, content, "Store your token first if you haven't:",
+ "bearer_token + canonical env var must not emit the auth-set-token preamble")
}
func TestGenerateBearerRefreshDoctorCommand(t *testing.T) {
diff --git a/internal/generator/templates/readme.md.tmpl b/internal/generator/templates/readme.md.tmpl
index 2b8b5edb..18f7c042 100644
--- a/internal/generator/templates/readme.md.tmpl
+++ b/internal/generator/templates/readme.md.tmpl
@@ -22,7 +22,7 @@ Printed by [@{{.Printer}}](https://github.com/{{.Printer}}){{if .PrinterName}} (
## Install
-The recommended path installs both the `{{.Name}}-pp-cli` binary and the `pp-{{.Name}}` agent skill in one shot:
+The recommended path installs both the `{{.Name}}-pp-cli` binary and the `pp-{{.Name}}` agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream [`skills`](https://github.com/vercel-labs/skills) CLI) in one shot:
```bash
npx -y @mvanhorn/printing-press install {{.Name}}
@@ -34,6 +34,18 @@ For CLI only (no skill):
npx -y @mvanhorn/printing-press install {{.Name}} --cli-only
```
+For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):
+
+```bash
+npx -y @mvanhorn/printing-press install {{.Name}} --skill-only
+```
+
+To constrain the skill install to one or more specific agents (repeatable — agent names match the [`skills`](https://github.com/vercel-labs/skills) CLI):
+
+```bash
+npx -y @mvanhorn/printing-press install {{.Name}} --agent claude-code
+npx -y @mvanhorn/printing-press install {{.Name}} --agent claude-code --agent codex
+```
{{ if .Category}}
### Without Node (Go fallback)
@@ -76,6 +88,75 @@ Tell your OpenClaw agent (copy this):
```
Install the pp-{{.Name}} skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-{{.Name}}. The skill defines how its required CLI can be installed.
```
+
+## Use with Claude Desktop
+
+This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
+{{- if or (eq .Auth.Type "cookie") (eq .Auth.Type "composed")}}
+
+The bundle reuses your local browser session — set it up first if you haven't:
+
+```bash
+{{.Name}}-pp-cli auth login --chrome
+```
+{{- else if eq .Auth.Type "oauth2"}}
+
+The bundle reuses your local OAuth tokens — authenticate first if you haven't:
+
+```bash
+{{.Name}}-pp-cli auth login
+```
+{{- else if and (eq .Auth.Type "bearer_token") (not $canonicalEnvVar)}}
+
+Store your token first if you haven't:
+
+```bash
+{{.Name}}-pp-cli auth set-token YOUR_TOKEN_HERE
+```
+{{- end}}
+
+To install:
+
+1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/{{.Name}}-current).
+2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
+{{- if and $canonicalEnvVar (ne .Auth.Type "none") (ne .Auth.Type "cookie") (ne .Auth.Type "composed")}}
+3. Fill in `{{$canonicalEnvVar.Name}}` when Claude Desktop prompts you.
+{{- end}}
+
+Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
+
+<details>
+<summary>Manual JSON config (advanced)</summary>
+
+If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
+
+{{ if .Category}}
+```bash
+go install github.com/mvanhorn/printing-press-library/library/{{.Category}}/{{.Name}}/cmd/{{.Name}}-pp-mcp@latest
+```
+{{- else}}
+Install the MCP binary from this CLI's published public-library entry or pre-built release.
+{{- end}}
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+ "mcpServers": {
+ "{{.Name}}": {
+ "command": "{{.Name}}-pp-mcp"{{- if and $canonicalEnvVar (ne .Auth.Type "none") (ne .Auth.Type "cookie") (ne .Auth.Type "composed")}},
+ "env": {
+{{- range .EndpointTemplateVars}}
+ "{{envName $.Name}}_{{upper .}}": "{{if eq . "shop"}}<your-store>.myshopify.com{{else if eq . "api_version"}}{{$.Version}}{{else}}<{{.}}>{{end}}",
+{{- end}}
+ "{{$canonicalEnvVar.Name}}": "<your-key>"
+ }{{- end}}
+ }
+ }
+}
+```
+
+</details>
{{- if and .Narrative .Narrative.AuthNarrative}}
{{if .Auth.Optional}}## Optional: API Key{{else}}## Authentication{{end}}
@@ -347,142 +428,6 @@ GraphQL path: `{{.GraphQLEndpointPath}}`
{{- end}}
{{- end}}
-## Use with Claude Code
-
-Install the focused skill — it auto-installs the CLI on first invocation:
-
-```bash
-npx skills add mvanhorn/printing-press-library/cli-skills/pp-{{.Name}} -g
-```
-
-Then invoke `/pp-{{.Name}} <query>` in Claude Code. The skill is the most efficient path — Claude Code drives the CLI directly without an MCP server in the middle.
-
-<details>
-<summary>Use as an MCP server in Claude Code (advanced)</summary>
-
-If you'd rather register this CLI as an MCP server in Claude Code, install the MCP binary first:
-
-{{ if .Category}}
-```bash
-go install github.com/mvanhorn/printing-press-library/library/{{.Category}}/{{.Name}}/cmd/{{.Name}}-pp-mcp@latest
-```
-{{- else}}
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-{{- end}}
-
-Then register it:
-{{- if and (eq .Auth.Type "api_key") $canonicalEnvVar}}
-
-```bash
-claude mcp add {{.Name}} {{.Name}}-pp-mcp{{range .EndpointTemplateVars}} -e {{envName $.Name}}_{{upper .}}={{if eq . "shop"}}<your-store>.myshopify.com{{else if eq . "api_version"}}{{$.Version}}{{else}}<{{.}}>{{end}}{{end}} -e {{$canonicalEnvVar.Name}}=<your-key>
-```
-{{- else if or (eq .Auth.Type "cookie") (eq .Auth.Type "composed")}}
-
-```bash
-# Some tools work without auth. For full access, set up auth first:
-{{.Name}}-pp-cli auth login --chrome
-
-claude mcp add {{.Name}} {{.Name}}-pp-mcp
-```
-{{- else if eq .Auth.Type "oauth2"}}
-
-```bash
-# Set up auth first:
-{{.Name}}-pp-cli auth login
-
-claude mcp add {{.Name}} {{.Name}}-pp-mcp
-```
-{{- else if and (eq .Auth.Type "bearer_token") $canonicalEnvVar}}
-
-```bash
-claude mcp add {{.Name}} {{.Name}}-pp-mcp -e {{$canonicalEnvVar.Name}}=<your-token>
-```
-{{- else if eq .Auth.Type "bearer_token"}}
-
-```bash
-# Set up auth first:
-{{.Name}}-pp-cli auth set-token YOUR_TOKEN_HERE
-
-claude mcp add {{.Name}} {{.Name}}-pp-mcp
-```
-{{- else}}
-
-```bash
-claude mcp add {{.Name}} {{.Name}}-pp-mcp
-```
-{{- end}}
-
-</details>
-
-## Use with Claude Desktop
-
-This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
-{{- if or (eq .Auth.Type "cookie") (eq .Auth.Type "composed")}}
-
-The bundle reuses your local browser session — set it up first if you haven't:
-
-```bash
-{{.Name}}-pp-cli auth login --chrome
-```
-{{- else if eq .Auth.Type "oauth2"}}
-
-The bundle reuses your local OAuth tokens — authenticate first if you haven't:
-
-```bash
-{{.Name}}-pp-cli auth login
-```
-{{- else if and (eq .Auth.Type "bearer_token") (not $canonicalEnvVar)}}
-
-Store your token first if you haven't:
-
-```bash
-{{.Name}}-pp-cli auth set-token YOUR_TOKEN_HERE
-```
-{{- end}}
-
-To install:
-
-1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/{{.Name}}-current).
-2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
-{{- if and $canonicalEnvVar (ne .Auth.Type "none") (ne .Auth.Type "cookie") (ne .Auth.Type "composed")}}
-3. Fill in `{{$canonicalEnvVar.Name}}` when Claude Desktop prompts you.
-{{- end}}
-
-Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
-
-<details>
-<summary>Manual JSON config (advanced)</summary>
-
-If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
-
-{{ if .Category}}
-```bash
-go install github.com/mvanhorn/printing-press-library/library/{{.Category}}/{{.Name}}/cmd/{{.Name}}-pp-mcp@latest
-```
-{{- else}}
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-{{- end}}
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
- "mcpServers": {
- "{{.Name}}": {
- "command": "{{.Name}}-pp-mcp"{{- if and $canonicalEnvVar (ne .Auth.Type "none") (ne .Auth.Type "cookie") (ne .Auth.Type "composed")}},
- "env": {
-{{- range .EndpointTemplateVars}}
- "{{envName $.Name}}_{{upper .}}": "{{if eq . "shop"}}<your-store>.myshopify.com{{else if eq . "api_version"}}{{$.Version}}{{else}}<{{.}}>{{end}}",
-{{- end}}
- "{{$canonicalEnvVar.Name}}": "<your-key>"
- }{{- end}}
- }
- }
-}
-```
-
-</details>
-
## Health Check
```bash
diff --git a/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/README.md b/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/README.md
index 97623b75..8edd5ef6 100644
--- a/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/README.md
+++ b/testdata/golden/expected/generate-golden-api-rich-auth/printing-press-rich-auth/README.md
@@ -6,7 +6,7 @@ Printed by [@printing-press-golden](https://github.com/printing-press-golden) (p
## Install
-The recommended path installs both the `printing-press-rich-pp-cli` binary and the `pp-printing-press-rich` agent skill in one shot:
+The recommended path installs both the `printing-press-rich-pp-cli` binary and the `pp-printing-press-rich` agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream [`skills`](https://github.com/vercel-labs/skills) CLI) in one shot:
```bash
npx -y @mvanhorn/printing-press install printing-press-rich
@@ -18,6 +18,18 @@ For CLI only (no skill):
npx -y @mvanhorn/printing-press install printing-press-rich --cli-only
```
+For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):
+
+```bash
+npx -y @mvanhorn/printing-press install printing-press-rich --skill-only
+```
+
+To constrain the skill install to one or more specific agents (repeatable — agent names match the [`skills`](https://github.com/vercel-labs/skills) CLI):
+
+```bash
+npx -y @mvanhorn/printing-press install printing-press-rich --agent claude-code
+npx -y @mvanhorn/printing-press install printing-press-rich --agent claude-code --agent codex
+```
### Without Node
@@ -50,6 +62,43 @@ Tell your OpenClaw agent (copy this):
Install the pp-printing-press-rich skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-printing-press-rich. The skill defines how its required CLI can be installed.
```
+## Use with Claude Desktop
+
+This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
+
+To install:
+
+1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/printing-press-rich-current).
+2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
+3. Fill in `RICH_AUTH_API_KEY` when Claude Desktop prompts you.
+
+Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
+
+<details>
+<summary>Manual JSON config (advanced)</summary>
+
+If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
+
+
+Install the MCP binary from this CLI's published public-library entry or pre-built release.
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+ "mcpServers": {
+ "printing-press-rich": {
+ "command": "printing-press-rich-pp-mcp",
+ "env": {
+ "RICH_AUTH_API_KEY": "<your-key>"
+ }
+ }
+ }
+}
+```
+
+</details>
+
## Quick Start
### 1. Install
@@ -126,69 +175,6 @@ This CLI is designed for AI agent consumption:
Exit codes: `0` success, `2` usage error, `3` not found, `4` auth error, `5` API error, `7` rate limited, `10` config error.
-## Use with Claude Code
-
-Install the focused skill — it auto-installs the CLI on first invocation:
-
-```bash
-npx skills add mvanhorn/printing-press-library/cli-skills/pp-printing-press-rich -g
-```
-
-Then invoke `/pp-printing-press-rich <query>` in Claude Code. The skill is the most efficient path — Claude Code drives the CLI directly without an MCP server in the middle.
-
-<details>
-<summary>Use as an MCP server in Claude Code (advanced)</summary>
-
-If you'd rather register this CLI as an MCP server in Claude Code, install the MCP binary first:
-
-
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-
-Then register it:
-
-```bash
-claude mcp add printing-press-rich printing-press-rich-pp-mcp -e RICH_AUTH_API_KEY=<your-key>
-```
-
-</details>
-
-## Use with Claude Desktop
-
-This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
-
-To install:
-
-1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/printing-press-rich-current).
-2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
-3. Fill in `RICH_AUTH_API_KEY` when Claude Desktop prompts you.
-
-Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
-
-<details>
-<summary>Manual JSON config (advanced)</summary>
-
-If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
-
-
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
- "mcpServers": {
- "printing-press-rich": {
- "command": "printing-press-rich-pp-mcp",
- "env": {
- "RICH_AUTH_API_KEY": "<your-key>"
- }
- }
- }
-}
-```
-
-</details>
-
## Health Check
```bash
diff --git a/testdata/golden/expected/generate-golden-api/printing-press-golden/README.md b/testdata/golden/expected/generate-golden-api/printing-press-golden/README.md
index 9769d117..7b688ed1 100644
--- a/testdata/golden/expected/generate-golden-api/printing-press-golden/README.md
+++ b/testdata/golden/expected/generate-golden-api/printing-press-golden/README.md
@@ -6,7 +6,7 @@ Printed by [@printing-press-golden](https://github.com/printing-press-golden) (p
## Install
-The recommended path installs both the `printing-press-golden-pp-cli` binary and the `pp-printing-press-golden` agent skill in one shot:
+The recommended path installs both the `printing-press-golden-pp-cli` binary and the `pp-printing-press-golden` agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream [`skills`](https://github.com/vercel-labs/skills) CLI) in one shot:
```bash
npx -y @mvanhorn/printing-press install printing-press-golden
@@ -18,6 +18,18 @@ For CLI only (no skill):
npx -y @mvanhorn/printing-press install printing-press-golden --cli-only
```
+For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):
+
+```bash
+npx -y @mvanhorn/printing-press install printing-press-golden --skill-only
+```
+
+To constrain the skill install to one or more specific agents (repeatable — agent names match the [`skills`](https://github.com/vercel-labs/skills) CLI):
+
+```bash
+npx -y @mvanhorn/printing-press install printing-press-golden --agent claude-code
+npx -y @mvanhorn/printing-press install printing-press-golden --agent claude-code --agent codex
+```
### Without Node
@@ -50,6 +62,43 @@ Tell your OpenClaw agent (copy this):
Install the pp-printing-press-golden skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-printing-press-golden. The skill defines how its required CLI can be installed.
```
+## Use with Claude Desktop
+
+This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
+
+To install:
+
+1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/printing-press-golden-current).
+2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
+3. Fill in `PRINTING_PRESS_GOLDEN_API_KEY` when Claude Desktop prompts you.
+
+Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
+
+<details>
+<summary>Manual JSON config (advanced)</summary>
+
+If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
+
+
+Install the MCP binary from this CLI's published public-library entry or pre-built release.
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+ "mcpServers": {
+ "printing-press-golden": {
+ "command": "printing-press-golden-pp-mcp",
+ "env": {
+ "PRINTING_PRESS_GOLDEN_API_KEY": "<your-key>"
+ }
+ }
+ }
+}
+```
+
+</details>
+
## Quick Start
### 1. Install
@@ -147,69 +196,6 @@ This CLI is designed for AI agent consumption:
Exit codes: `0` success, `2` usage error, `3` not found, `4` auth error, `5` API error, `7` rate limited, `10` config error.
-## Use with Claude Code
-
-Install the focused skill — it auto-installs the CLI on first invocation:
-
-```bash
-npx skills add mvanhorn/printing-press-library/cli-skills/pp-printing-press-golden -g
-```
-
-Then invoke `/pp-printing-press-golden <query>` in Claude Code. The skill is the most efficient path — Claude Code drives the CLI directly without an MCP server in the middle.
-
-<details>
-<summary>Use as an MCP server in Claude Code (advanced)</summary>
-
-If you'd rather register this CLI as an MCP server in Claude Code, install the MCP binary first:
-
-
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-
-Then register it:
-
-```bash
-claude mcp add printing-press-golden printing-press-golden-pp-mcp -e PRINTING_PRESS_GOLDEN_API_KEY=<your-key>
-```
-
-</details>
-
-## Use with Claude Desktop
-
-This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
-
-To install:
-
-1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/printing-press-golden-current).
-2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
-3. Fill in `PRINTING_PRESS_GOLDEN_API_KEY` when Claude Desktop prompts you.
-
-Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
-
-<details>
-<summary>Manual JSON config (advanced)</summary>
-
-If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
-
-
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
- "mcpServers": {
- "printing-press-golden": {
- "command": "printing-press-golden-pp-mcp",
- "env": {
- "PRINTING_PRESS_GOLDEN_API_KEY": "<your-key>"
- }
- }
- }
-}
-```
-
-</details>
-
## Health Check
```bash
diff --git a/testdata/golden/expected/generate-public-param-names/public-param-golden/README.md b/testdata/golden/expected/generate-public-param-names/public-param-golden/README.md
index 84ff2e89..558321fc 100644
--- a/testdata/golden/expected/generate-public-param-names/public-param-golden/README.md
+++ b/testdata/golden/expected/generate-public-param-names/public-param-golden/README.md
@@ -6,7 +6,7 @@ Printed by [@printing-press-golden](https://github.com/printing-press-golden) (p
## Install
-The recommended path installs both the `public-param-golden-pp-cli` binary and the `pp-public-param-golden` agent skill in one shot:
+The recommended path installs both the `public-param-golden-pp-cli` binary and the `pp-public-param-golden` agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream [`skills`](https://github.com/vercel-labs/skills) CLI) in one shot:
```bash
npx -y @mvanhorn/printing-press install public-param-golden
@@ -18,6 +18,18 @@ For CLI only (no skill):
npx -y @mvanhorn/printing-press install public-param-golden --cli-only
```
+For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):
+
+```bash
+npx -y @mvanhorn/printing-press install public-param-golden --skill-only
+```
+
+To constrain the skill install to one or more specific agents (repeatable — agent names match the [`skills`](https://github.com/vercel-labs/skills) CLI):
+
+```bash
+npx -y @mvanhorn/printing-press install public-param-golden --agent claude-code
+npx -y @mvanhorn/printing-press install public-param-golden --agent claude-code --agent codex
+```
### Without Node
@@ -50,6 +62,39 @@ Tell your OpenClaw agent (copy this):
Install the pp-public-param-golden skill from https://github.com/mvanhorn/printing-press-library/tree/main/cli-skills/pp-public-param-golden. The skill defines how its required CLI can be installed.
```
+## Use with Claude Desktop
+
+This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
+
+To install:
+
+1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/public-param-golden-current).
+2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
+
+Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
+
+<details>
+<summary>Manual JSON config (advanced)</summary>
+
+If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
+
+
+Install the MCP binary from this CLI's published public-library entry or pre-built release.
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+ "mcpServers": {
+ "public-param-golden": {
+ "command": "public-param-golden-pp-mcp"
+ }
+ }
+}
+```
+
+</details>
+
## Quick Start
### 1. Install
@@ -118,65 +163,6 @@ This CLI is designed for AI agent consumption:
Exit codes: `0` success, `2` usage error, `3` not found, `5` API error, `7` rate limited, `10` config error.
-## Use with Claude Code
-
-Install the focused skill — it auto-installs the CLI on first invocation:
-
-```bash
-npx skills add mvanhorn/printing-press-library/cli-skills/pp-public-param-golden -g
-```
-
-Then invoke `/pp-public-param-golden <query>` in Claude Code. The skill is the most efficient path — Claude Code drives the CLI directly without an MCP server in the middle.
-
-<details>
-<summary>Use as an MCP server in Claude Code (advanced)</summary>
-
-If you'd rather register this CLI as an MCP server in Claude Code, install the MCP binary first:
-
-
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-
-Then register it:
-
-```bash
-claude mcp add public-param-golden public-param-golden-pp-mcp
-```
-
-</details>
-
-## Use with Claude Desktop
-
-This CLI ships an [MCPB](https://github.com/modelcontextprotocol/mcpb) bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).
-
-To install:
-
-1. Download the `.mcpb` for your platform from the [latest release](https://github.com/mvanhorn/printing-press-library/releases/tag/public-param-golden-current).
-2. Double-click the `.mcpb` file. Claude Desktop opens and walks you through the install.
-
-Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (`darwin-arm64`) and Windows (`amd64`, `arm64`); for other platforms, use the manual config below.
-
-<details>
-<summary>Manual JSON config (advanced)</summary>
-
-If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.
-
-
-Install the MCP binary from this CLI's published public-library entry or pre-built release.
-
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
-
-```json
-{
- "mcpServers": {
- "public-param-golden": {
- "command": "public-param-golden-pp-mcp"
- }
- }
-}
-```
-
-</details>
-
## Health Check
```bash
← a9ffa08f fix(cli): research-dir state.json api_name overrides info.ti
·
back to Cli Printing Press
·
docs(skills): document hierarchical resource_type in store-q f354bc7a →