/printing-press

• The shipcheck verdict is

  ship-with-gaps

• The verify pass rate is below 80%
• The scorecard is below 85
• You want the CLI publish-ready in one pass

~/printing-press/library/

• A short name:

  redfin

  (looks up

  $PRESS_LIBRARY/redfin

  )
• A full name:

  redfin-pp-cli

  (strips suffix, looks up

  $PRESS_LIBRARY/redfin

  )
• A path:

  ~/printing-press/library/redfin

  (used directly)

1. If the argument is an absolute or

   ~

   -prefixed path and exists, use it
2. Try

   $PRESS_LIBRARY/<arg>

   (exact match — works for slug like

   redfin

   )
3. If arg has

   -pp-cli

   suffix, strip it and try

   $PRESS_LIBRARY/<slug>

   (e.g.,

   redfin-pp-cli

   →

   redfin

   )
4. Fuzzy search:

   ls $PRESS_LIBRARY/ | grep -i <arg>

   for close matches

• Standalone (user-invoked,

  /printing-press-polish redfin

  ). The arg is a slug or binary name; resolution lands on

  $PRESS_LIBRARY/<slug>/

  . This is the published copy and the right target.
• Mid-pipeline (main printing-press skill Phase 5.5). The arg is

  $CLI_WORK_DIR

  — an absolute path to

  ~/printing-press/.runstate/.../runs/.../working/<api>-pp-cli/

  . Resolution must hit rule 1. Do not paraphrase this to the slug — Phase 5.5 fires before the working CLI is promoted, so

  $PRESS_LIBRARY/<slug>/

  either doesn't exist or holds the prior run's stale CLI.

printing-press lock

AskUserQuestion

CLI_DIR="<resolved path>"
CLI_NAME="$(basename "$CLI_DIR")"

$CLI_DIR

mvanhorn/printing-press-library

1. Locate the public library clone. Honor

   $PRINTING_PRESS_LIBRARY_PUBLIC

   if set; otherwise scan the user's filesystem however fits this platform. Validate every candidate by checking the git remote points at

   mvanhorn/printing-press-library

   — other directories may share the name (forks, accidental name collisions). If multiple valid clones exist, prefer the most recently modified; ask the user to disambiguate only if still unclear.
2. Locate this CLI inside the clone.

   find <clone>/library -type d -name "<api>-pp-cli"

   or equivalent.
3. Run

   diff -r <public-cli-dir> $CLI_DIR

   with these exclusions, all of which are expected to diverge after publish:

   • .printing-press-tools-polish.json

     (local ledger, not published)

   • go.mod

     and

     go.sum

     — publish rewrites the module path from

     <api>-pp-cli

     to

     github.com/mvanhorn/printing-press-library/library/<category>/<api>

   • All

     .go

     files where the only difference is the rewritten import path (the publish step propagates the new module path through every internal import). When inspecting

     .go

     diffs, scan for substantive changes — anything beyond the module-path prefix swap is real divergence.
   Concretely:

   diff -r --exclude=go.mod --exclude=go.sum --exclude=.printing-press-tools-polish.json <public-cli-dir> $CLI_DIR

   .
   Don't pass

   --exclude='<api>-pp-cli'

   or

   --exclude='<api>-pp-mcp'

   — those names match both the root-level binary files and the

   cmd/<api>-pp-cli/

   and

   cmd/<api>-pp-mcp/

   source directories. Excluding by binary name silently skips the entire

   cmd/

   subtree, hiding real divergence in

   main.go

   . The "Only in $CLI_DIR: <api>-pp-cli" line for the built binary is one row of expected output, not noise worth filtering at the cost of completeness.
4. Surface the result before continuing.

• No clone found → user doesn't have public locally. State this explicitly ("public library not found locally; proceeding on internal as canonical") and continue.
• Clone found but doesn't contain this CLI → never published or under a different name. State this and continue.
• Found and diff is empty → in sync. State this and continue.
• Found and divergent → stop. Do not run Phase 1 diagnostics yet. List the divergent files for the user. Ask via AskUserQuestion: sync public→internal, or proceed without syncing. If the user picks sync, copy public's version of the divergent files into internal, then continue polish on the synced internal copy.

.printing-press.json

$CLI_DIR

/printing-press-publish

• User-visible default: which behavior users get without extra flags or config.
• Compatibility risk: whether existing commands, scripts, MCP tools, or stored config change behavior.
• Verification command: the exact command that proves the default and the non-default escape hatch both work.

1. Read the command file
2. Find

   Args: cobra.ExactArgs(N)

   or similar constraint
3. Remove the

   Args:

   field
4. Add at the top of

   RunE

   :
   go

   if len(args) == 0 {
       return cmd.Help()
   }

5. For commands needing 2+ args, use

   if len(args) < 2

6. Check for dry-run nil-data crashes and add guards:
   go

   if flags.dryRun {
       return nil
   }

1. For each dead function flagged by dogfood, grep all

   .go

   files to verify it's truly unused (not just its definition matching itself)
2. If truly unused: remove the function
3. If used by another helper: leave it (false positive)
4. After removal, remove unused imports
5. Delete stale files (promoted commands not registered in root.go)

1. Read root command

   Short

   in

   internal/cli/root.go

2. If it contains boilerplate ("Reverse-engineered...", raw API title), rewrite: Pattern:

   "<Product> CLI with <capability-1>, <capability-2>, and <capability-3>"

3. Check commands for missing

   Example

   fields. Add realistic examples with domain-specific values.

1. Title: "# <Product Name> CLI" — use the product's real name with correct casing/punctuation (e.g., "Cal.com" not "Cal Com")
2. Subtitle: one sentence describing what the CLI does for the user, matching the root

   Short

   field. NOT a description of the API.
3. Install: correct install command. Use the printing-press-library repo URL, not a per-CLI repo that doesn't exist.
4. Authentication: how to set

   <API>_API_KEY

   env var, where to get a key (link to the provider's settings page), self-hosted URL override if supported. Read

   config.go

   to find all env vars.
5. Quick Start: 3-5 commands someone will actually run first. Pick commands that are both most useful (what you'd run daily) and show the CLI's value (why install this over curl). Usually:

   doctor

   →

   sync

   → transcendence command (

   today

   ,

   health

   ) →

   search

   . Avoid raw list commands — they dump data without demonstrating why the CLI exists.
6. Commands: categorized table. Group by domain function (Scheduling, Analytics, Account, Utilities), not by implementation structure.
7. Output Formats: show

   --json

   ,

   --select

   ,

   --csv

   ,

   --compact

   ,

   --dry-run

   ,

   --agent

   . Use a real command, not a placeholder.
8. Agent Usage: agent-native properties and exit codes.
9. Cookbook: 8-15 recipes using verified flag names from

   --help

   . Show the CLI's unique capabilities: transcendence commands, filters, SQL queries, pipes. Include at least one mutation example.
10. Health Check: show actual

    doctor

    output, not a placeholder.
11. Configuration: list ALL env vars from config.go with descriptions. Include config file path.
12. Troubleshooting: common errors mapped to exit codes with fixes.

• Rate Limits: if the API has documented limits
• Self-Hosting: if the CLI supports

  --api-url

  or

  BASE_URL

  override
• Pagination: if the API has notable pagination behavior
• Sources & Inspiration: credits to community projects (generated by the machine, preserve if present)

/tmp/polish-verify-skill.json

check

flag-names

flag-commands

positional-args

unknown-command

canonical-sections

command

detail

• flag-names

  — SKILL references

  --foo

  on a

  <cli> ...

  invocation but no command in

  internal/cli/*.go

  declares it. Either the example is wrong (fix the SKILL or remove the recipe) or the flag was deleted (decide if it should come back). Out of scope: flags on lines that invoke other tools (e.g.

  npx -y @mvanhorn/printing-press install <api> --cli-only

  ,

  gh pr create --base ...

  ,

  go install ...

  ). The recipe-scoped flag-names check ignores those by design — never strip an external-tool flag to make verify-skill exit 0, and never replace the install instructions with a fabricated slash command. If the finding is firing on an external-tool flag anyway, that is a verify-skill bug, not a SKILL bug; report it instead of editing the SKILL.

• flag-commands

  —

  --foo is declared elsewhere but not on <cmd>

  . The flag exists somewhere but not on the command the SKILL invoked it on. Two fixes:
  1. If the flag is added via a shared helper like

     addXxxFlags(cmd, ...)

     , inline the

     cmd.Flags().StringVar(...)

     declaration directly in the affected command's source file. The verify-skill grep cannot follow function-call indirection.
  2. If the SKILL example is genuinely wrong, fix the example to use a flag the command does declare.

• positional-args

  —

  got N positional args; Use: "<cmd> <arg>" expects M-M

  . The SKILL recipe passed N positional args but the command's

  Use:

  declares M required. Two fixes:
  1. If the command also accepts the value via a

     --flag

     , change

     Use: "cmd <arg>"

     to

     Use: "cmd [arg]"

     (square brackets = optional). Verify-skill correctly accepts

     --flag

     -only invocations against an optional positional.
  2. If the SKILL example is missing a required positional, fix the example.

• canonical-sections

  —

  install section drift: hand-edit detected in a generator-owned section

  . The

  ## Prerequisites: Install the CLI

  block has been edited away from what the generator would emit for this CLI today. Do not hand-edit the install section. It's templated from

  internal/generator/templates/skill.md.tmpl

  parameterized on

  (api_name, category, uses_browser_http_transport)

  ; any drift means an automation step or person modified text the machine owns. Resolve by regenerating the printed CLI (run

  printing-press regen

  against this directory, or for a published CLI, regenerate from the spec and re-publish). If the canonical text itself is wrong (e.g., a real change to the install instructions is needed), fix the template, not the printed CLI.

Edit

printing-press verify-skill --dir "$CLI_DIR"

• Path validity mismatches
• Auth protocol mismatches
• Example drift (examples referencing wrong commands)
• Data pipeline integrity issues

1. Run

   printing-press tools-audit "$CLI_DIR" --json

   to surface mechanical findings (empty Short, thin Short, missing

   mcp:read-only

   on read-shaped command names).
2. You must read

   references/tools-polish.md

   and follow its instructions to address the findings AND run a judgment pass over every command — regardless of whether the audit flagged it. The audit catches mechanical issues; description quality and borderline classification (read-only vs. local-write) always require agent reasoning. You must not skip this.
3. Accepting MCP-description findings carries a stricter contract.

   thin-mcp-description

   and

   empty-mcp-description

   accepts require three pre-decision fields (

   spec_source_material

   ,

   target_description

   ,

   gap_analysis

   ) populated per finding. The binary rejects bulk accepts (>5 findings sharing one rationale) and runs that "complete" without lifting MCPDescriptionQuality. Fix via override or generator improvement is the expected path; accept is rare. See

   references/tools-polish.md

   "Marking a finding accepted" for the full contract.

no pending findings

incomplete:

• ship

  : verify >= 80%, scorecard >= 75, no critical failures, AND verify-skill exits 0 (no SKILL/CLI mismatches), AND workflow-verify is not

  workflow-fail

  , AND tools-audit shows zero pending findings (every finding fixed or explicitly accepted with rationale). The SKILL/workflow gates are hard requirements: a CLI that ships with a SKILL that lies about it (verify-skill findings) gives agents broken instructions; a CLI whose primary workflow fails verification has not actually shipped.

• ship-with-gaps

  : verify >= 65%, scorecard >= 65, non-critical gaps remain, AND the SKILL/workflow gates above hold, AND the README has a

  ## Known Gaps

  block that lists the user-facing gaps. Reserved for the rare case where a refactor or external-dependency blocker prevents a clean fix.
  README Known Gaps is mandatory for ship-with-gaps. The published library copy is what downstream users see; if the verdict claims gaps exist but the README hides them, downstream users meet a CLI that misbehaves with no disclosure. Before emitting

  ship_recommendation: ship-with-gaps

  :
  1. Read the CLI's

     README.md

     . If a

     ## Known Gaps

     section already exists (e.g., the main SKILL Phase 4 wrote it before polish ran), confirm it covers the user-facing items in

     remaining_issues

     . Add bullets for any newly surfaced user-facing gap polish discovered.
  2. If

     ## Known Gaps

     is missing, write it — placed after

     ## Quick Start

     (or before

     ## Usage

     ) to mirror the

     ## Unique Features

     placement convention. One bullet per user-facing item from

     remaining_issues

     . Phrase from the user's perspective: what command misbehaves, what the workaround is. Example:
     markdown

     ## Known Gaps
     
     - **`analytics export --csv`** returns truncated rows on workspaces with >10k events. Use `--json` and pipe to `jq` as a workaround until the underlying export endpoint is paginated.

  3. Filter

     remaining_issues

     for user-facing entries when populating the section. Internal items (verify drift on a deprecated flag, MCP description tuning, polish-internal notes) do not belong in the public Known Gaps. If the agent cannot identify any user-facing gap from

     remaining_issues

     , the verdict is

     ship

     , not

     ship-with-gaps

     .
  4. List each Known Gaps write/update in

     fixes_applied

     so the caller can surface that this happened.
  If polish cannot responsibly populate Known Gaps from the available evidence (e.g.,

  remaining_issues

  is all internal jargon with no user-facing reading), downgrade the verdict to

  hold

  rather than ship without disclosure.

• hold

  : verify < 65% or scorecard < 65 or critical failures, OR verify-skill has unresolved findings, OR workflow-verify reports

  workflow-fail

  and the workflow is the CLI's primary value.

1. Find the underlying deficit, not the score. The scorecard is a proxy for quality, not the goal itself. A README scoring 8/10 might be missing a Cookbook section or have outdated commands — that's a real, fixable gap. A

   mcp_surface_strategy

   scoring 2/10 on a 200-endpoint API might be flagging that the surface is mostly endpoint mirrors — also potentially fixable.
2. If there's a real, agent-grade improvement available, make it. Better description, missing flag doc, weak README section, an example that doesn't reflect actual usage. The CLI gets better and the score follows.
3. If the deficit is structural, document and accept. Some dimensions assume capabilities the CLI's domain doesn't have (a read-only API scored against write-workflow dimensions, a CLI with no auth scored on auth dimensions, a small API penalized on

   surface_strategy

   thresholds calibrated for large APIs). Note the reason in

   skipped_findings

   and move on.
4. Never add scaffolding to satisfy the scorer. Fake commands, fake tests, fake flags, or boilerplate prose written purely to nudge a number — those degrade the CLI to satisfy the proxy. The scorer is imperfect by design (the "scoring may be imperfect" caveat in AGENTS.md applies). Trust the underlying judgment, not the number.

---POLISH-RESULT---

Polish Results for <CLI_NAME>:

                    Before    After     Delta
  Scorecard:        XX/100    XX/100    +N
  Verify:           XX%       XX%       +N%
  Tools-audit:      XX        XX        -N pending findings

Fixes applied:
  - <one-line description of each fix>

Skipped findings:
  - <finding>: <why you chose not to fix it>

Remaining issues:
  - <one-line description of each issue you tried to fix but couldn't>

---POLISH-RESULT---
scorecard_before: <N>
scorecard_after: <N>
verify_before: <N>
verify_after: <N>
dogfood_before: <PASS|FAIL>
dogfood_after: <PASS|FAIL>
govet_before: <N>
govet_after: <N>
tools_audit_before: <N pending>
tools_audit_after: <N pending>
fixes_applied:
- <one-line description of each fix>
skipped_findings:
- <finding>: <why you chose not to fix it>
remaining_issues:
- <one-line description of each issue you tried to fix but couldn't>
ship_recommendation: <ship|ship-with-gaps|hold>
further_polish_recommended: <yes|no>
further_polish_reasoning: <one sentence explaining the call>
---END-POLISH-RESULT---

• fixes_applied: what changed — the caller displays these
• skipped_findings: issues you found but deliberately did not fix, with reasoning (e.g., "verify classifies

  stale

  as read — scorer bug, not a CLI problem", "thin-short on

  version

  accepted as-is — accurate and brief"). The caller surfaces these so the user can decide whether to address them manually.
• remaining_issues: issues you tried to fix but couldn't resolve.

remaining_issues

yes

• remaining_issues

  includes verify or dogfood failures you ran out of time on and a fresh pass with more attention per failure could plausibly resolve.
• The fixes you did land may have unblocked dependent issues you couldn't reach this pass.
• A SKILL/CLI mismatch needs a second look after this pass changed the source tree.

no

• remaining_issues

  are decisions only the user can make (rename a flagship command, choose a default behavior, accept a structural trade-off).
• You already attempted the fix in two different ways this pass and both failed for the same reason.
• The blocker is external (API changed shape, rate-limited, missing credential) and not something a fresh polish run sees differently.

• remaining_issues

  is empty AND

  skipped_findings

  are all environmental or structural — there is nothing left for polish to do.

further_polish_reasoning

analytics export

report show

• ship

  +

  remaining_issues

  empty → recommend Publish.

• ship

  +

  remaining_issues

  non-empty +

  further_polish_recommended: yes

  → recommend Polish again.

• ship

  +

  remaining_issues

  non-empty +

  further_polish_recommended: no

  → recommend Publish if the remaining issues do not touch the CLI's headline commands, otherwise surface the trade-off and let the user decide between Publish (as-is; README is not auto-updated for

  ship

  verdicts) and Done.

• ship-with-gaps

  +

  further_polish_recommended: yes

  → recommend Polish again.

• ship-with-gaps

  +

  further_polish_recommended: no

  → recommend Publish (the gap is already in README's

  ## Known Gaps

  because polish's ship logic enforces that for

  ship-with-gaps

  — see "Ship logic" above) or Done if the gap is publish-blocking — agent judgment.

further_polish_recommended: no

further_polish_reasoning

AskUserQuestion

remaining_issues

further_polish_recommended: no

"<CLI_NAME> polished: scorecard XX/100, verify XX%. Polish ran cleanly — nothing more to fix.

Recommendation: Publish.

1. Publish now (recommended) — validate, package, and open a PR
2. Done for now — CLI is at ~/printing-press/library/<cli-name>"

remaining_issues

further_polish_recommended: yes

"<CLI_NAME> polished: scorecard XX/100, verify XX%. <N> issues remain.

Polish notes: '<further_polish_reasoning>'

Recommendation: Polish again before publishing.

1. Polish again (recommended) — close the remaining <N> issues
2. Publish now — ship as-is
3. Done for now — CLI is at ~/printing-press/library/<cli-name>"

(recommended)

Recommendation:

gh pr list --repo mvanhorn/printing-press-library --head "feat/$CLI_NAME" --state open --author @me --json number,url --jq '.[0]' 2>/dev/null

/printing-press-publish <cli-name>

/printing-press

AskUserQuestion

"PR opened: <PR_URL>. Run a retro? It surfaces systemic gaps from this session (generator misses, scorer bugs, skill-doc drift) as a GitHub issue for the Printing Press maintainers. Every retro filed raises the floor for the next CLI — and your session context is freshest right now."

1. No — I'm done (default)
2. Yes — run retro now

/printing-press-retro

• Fix everything. Do not ask for approval before fixing — polish is autonomous.
• Report results honestly. Show what improved and what didn't.
• Do not add new features. Polish fixes quality issues, not feature gaps.
• Do not re-run research or generation. Polish works with the CLI as-is.
• Do not modify the printing-press generator. That's

  /printing-press-retro

  .
• Do not modify any files outside

  $CLI_DIR

  .
• If polish adds or renames a Cobra command, the MCP surface updates automatically through the generated

  internal/mcp/cobratree

  runtime mirror. Update

  novel_features

  only when README/SKILL highlights or registry display should change; use

  cmd.Annotations["mcp:hidden"] = "true"

  for debug-only commands.
• Maximum 1 fix-and-rediagnose pass per polish invocation. The "Polish again" path runs additional invocations (max 3 total).
• Prefer mechanical fixes over creative decisions. When a creative decision is needed (like the CLI description), use the research brief from manuscripts if available.