[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M78104XVHGZX5AYTZESAQVCS":3,"skill-same:01M78104XVHGZX5AYTZESAQVCS":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":16,"sourceHtmlUrl":17,"categories":18,"keywords":19,"publishedAt":20,"linkOnly":21,"markdownContent":22,"markdownBody":23,"frontMatter":24,"refName":37,"commitSha":38,"skillDirectory":39,"forksCount":40,"repositoryHtmlUrl":41,"repositoryHomepageUrl":6,"ownerHtmlUrl":42,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":43,"install":44,"resources":57},"01M78104XVHGZX5AYTZESAQVCS","printing-press-polish",null,"Polish a generated CLI to pass verification and become publish-ready. Runs diagnostics (dogfood, verify, scorecard, go vet, gosec), automatically fixes all issues (verify failures, static-analysis findings, dead code, descriptions, README, MCP tool quality), reports the before\u002Fafter delta, and offers to publish. Use after any \u002Fprinting-press run, or on any CLI in $PRESS_LIBRARY\u002F. Trigger phrases: \"polish\", \"improve the CLI\", \"fix verify\", \"make it publish-ready\", \"clean up the CLI\", \"get this ready to ship\".","filippolmt\u002Fskills","filippolmt","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F61194571?v=4","01M7808VK1A8QF8ZXGT2DWTKHS","Filippo Merante Caparrotta","01M7808VKN74HC3EZMK8EV35KS",1,"MIT","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: printing-press-polish\ndescription: >\n  Polish a generated CLI to pass verification and become publish-ready. Runs\n  diagnostics (dogfood, verify, scorecard, go vet, gosec), automatically fixes\n  all issues (verify failures, static-analysis findings, dead code,\n  descriptions, README, MCP tool quality), reports the before\u002Fafter delta, and\n  offers to publish. Use after any \u002Fprinting-press run, or on any CLI in\n  $PRESS_LIBRARY\u002F. Trigger phrases: \"polish\", \"improve the CLI\", \"fix verify\",\n  \"make it publish-ready\", \"clean up the CLI\", \"get this ready to ship\".\ncontext: fork\nmin-binary-version: \"4.0.0\"\nallowed-tools:\n  - Bash\n  - Read\n  - Glob\n  - Grep\n  - Write\n  - Edit\n  - AskUserQuestion\ncreated_by: user\n---\n\n# \u002Fprinting-press-polish\n\nPolish a generated CLI so it passes verification and is ready to publish.\n\nThe retro improves the Printing Press. Polish improves the generated CLI. This skill runs in a forked context (`context: fork`) so its diagnostic and fix loop doesn't pollute the caller — the diagnostic spam, fix iterations, and re-diagnose noise stay scoped to the polish session, and the caller receives a clean summary.\n\n```bash\n\u002Fprinting-press-polish redfin\n\u002Fprinting-press-polish redfin-pp-cli\n\u002Fprinting-press-polish \"$PRESS_LIBRARY\u002Fredfin\"\n```\n\n## When to run\n\nAfter any `\u002Fprinting-press` generation, especially when:\n- The shipcheck verdict is `ship-with-gaps`\n- The verify pass rate is below 80%\n- The scorecard is below 85\n- You want the CLI publish-ready in one pass\n\nCan also be run standalone on any CLI in `$PRESS_LIBRARY\u002F`.\n\n## Setup\n\n```bash\n# min-binary-version: 4.0.0\n\nPRESS_HOME=\"${PRINTING_PRESS_HOME:-$HOME\u002Fprinting-press}\"\nPRESS_LIBRARY=\"$PRESS_HOME\u002Flibrary\"\n\n_pp_check_disk_space() {\n  _pp_disk_warn_kb=\"${PRINTING_PRESS_DISK_WARN_KB:-3145728}\"\n  _pp_disk_fail_kb=\"${PRINTING_PRESS_DISK_FAIL_KB:-524288}\"\n  case \"$_pp_disk_warn_kb$_pp_disk_fail_kb\" in\n    \"\"|*[!0-9]*) return 0 ;;\n  esac\n\n  _pp_disk_path=\"$PRESS_HOME\"\n  while [ ! -e \"$_pp_disk_path\" ] && [ \"$_pp_disk_path\" != \"\u002F\" ]; do\n    _pp_disk_path=\"$(dirname \"$_pp_disk_path\")\"\n  done\n\n  _pp_disk_avail_kb=\"$(df -Pk \"$_pp_disk_path\" 2>\u002Fdev\u002Fnull | awk 'BEGIN {\n    if ((getline header) \u003C= 0 || (getline record) \u003C= 0) exit\n    field_count = split(record, fields)\n    if (field_count >= 4) print fields[4]\n  }')\"\n  case \"$_pp_disk_avail_kb\" in\n    \"\"|*[!0-9]*) return 0 ;;\n  esac\n\n  if [ \"$_pp_disk_avail_kb\" -lt \"$_pp_disk_fail_kb\" ]; then\n    echo \"\"\n    echo \"[setup-error] Critically low disk space on the Printing Press workspace volume.\"\n    echo \"PRESS_DISK_PATH=$_pp_disk_path\"\n    echo \"PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb\"\n    echo \"PRESS_DISK_FAIL_KB=$_pp_disk_fail_kb\"\n    echo \"Free disk space or set PRINTING_PRESS_HOME to a volume with more room, then re-run this skill.\"\n    echo \"\"\n    return 1\n  fi\n\n  if [ \"$_pp_disk_avail_kb\" -lt \"$_pp_disk_warn_kb\" ]; then\n    echo \"\"\n    echo \"[low-disk] Printing Press workspace volume is low on free space.\"\n    echo \"PRESS_DISK_PATH=$_pp_disk_path\"\n    echo \"PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb\"\n    echo \"PRESS_DISK_WARN_KB=$_pp_disk_warn_kb\"\n    echo \"This flow may need several GiB for generated files, Go build cache, module downloads, or repository clones.\"\n    echo \"\"\n  fi\n}\n_pp_check_disk_space || { return 1 2>\u002Fdev\u002Fnull || exit 1; }\n\n# Mid-pipeline callers may pass printing_press_bin: \u003Cabs-path> in the args\n# bundle. Prefer it so forked polish runs keep using the parent skill's\n# preflight-selected binary instead of re-resolving through PATH.\nPRINTING_PRESS_BIN=\"${PRINTING_PRESS_BIN:-}\"\nif [ -z \"$PRINTING_PRESS_BIN\" ] && [ -n \"${ARGUMENTS:-}\" ]; then\n  PRINTING_PRESS_BIN=\"$(printf '%s\\n' \"$ARGUMENTS\" | sed -nE 's\u002F^[[:space:]]*printing_press_bin:[[:space:]]*(.+)$\u002F\\1\u002Fp' | head -1)\"\nfi\nif [ -z \"$PRINTING_PRESS_BIN\" ]; then\n  PRINTING_PRESS_BIN=\"$(command -v cli-printing-press 2>\u002Fdev\u002Fnull || true)\"\nfi\n\nif [ -z \"$PRINTING_PRESS_BIN\" ]; then\n  echo \"cli-printing-press binary not found.\"\n  echo \"Install with:  go install github.com\u002Fmvanhorn\u002Fcli-printing-press\u002Fv4\u002Fcmd\u002Fcli-printing-press@latest\"\n  return 1 2>\u002Fdev\u002Fnull || exit 1\nfi\nif ! command -v go >\u002Fdev\u002Fnull 2>&1; then\n  echo \"\"\n  echo \"[setup-error] Go toolchain not found.\"\n  echo \"\"\n  echo \"This Printing Press flow runs Go-based build or validation commands.\"\n  echo \"Install Go 1.26.11 or newer from https:\u002F\u002Fgo.dev\u002Fdl\u002F, then verify with:\"\n  echo \"  go version\"\n  echo \"Then re-run this skill.\"\n  echo \"\"\n  return 1 2>\u002Fdev\u002Fnull || exit 1\nfi\necho \"PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN\"\n\n_pp_semver_lt() {\n  if [ -z \"${PP_SEMVER_A:-}\" ] || [ -z \"${PP_SEMVER_B:-}\" ]; then\n    echo \"[setup-error] semver comparison inputs are missing.\" >&2\n    return 2\n  fi\n  awk -v a=\"${PP_SEMVER_A:-}\" -v b=\"${PP_SEMVER_B:-}\" 'BEGIN {\n    split(a, x, \".\"); split(b, y, \".\")\n    for (i = 1; i \u003C= 3; i++) {\n      if ((x[i] + 0) \u003C (y[i] + 0)) exit 0\n      if ((x[i] + 0) > (y[i] + 0)) exit 1\n    }\n    exit 1\n  }'\n}\n\n_pp_go_version_norm() {\n  printf '%s\\n' \"${PP_GO_VERSION_INPUT:-}\" | sed -nE 's\u002F.*go([0-9]+)\\.([0-9]+)(\\.([0-9]+))?.*\u002F\\1.\\2.\\4\u002Fp' | sed -E 's\u002F\\.$\u002F.0\u002F'\n}\n\n_pp_check_go_currency() {\n  _pp_go_installed=\"$(PP_GO_VERSION_INPUT=\"$(go env GOVERSION 2>\u002Fdev\u002Fnull)\" _pp_go_version_norm)\"\n  _pp_go_required=\"$(PP_GO_VERSION_INPUT=\"$(go version \"$PRINTING_PRESS_BIN\" 2>\u002Fdev\u002Fnull)\" _pp_go_version_norm)\"\n  PP_SEMVER_A=\"$_pp_go_installed\"\n  PP_SEMVER_B=\"$_pp_go_required\"\n  if [ -z \"$_pp_go_installed\" ] || [ -z \"$_pp_go_required\" ] || ! _pp_semver_lt; then\n    return 0\n  fi\n\n  echo \"\"\n  if [ \"${GOTOOLCHAIN:-auto}\" = \"local\" ]; then\n    echo \"[setup-error] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed).\"\n    echo \"GOTOOLCHAIN=local disables automatic toolchain downloads, so later Go quality gates would fail.\"\n    echo \"Install Go $_pp_go_required or newer from https:\u002F\u002Fgo.dev\u002Fdl\u002F, or unset GOTOOLCHAIN.\"\n    echo \"\"\n    return 1\n  fi\n\n  echo \"[go-toolchain-old] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed).\"\n  echo \"PRESS_GO_INSTALLED=$_pp_go_installed\"\n  echo \"PRESS_GO_REQUIRED=$_pp_go_required\"\n  echo \"Default GOTOOLCHAIN behavior may download the required toolchain during Go commands.\"\n  echo \"\"\n  return 0\n}\n_pp_check_go_currency || { return 1 2>\u002Fdev\u002Fnull || exit 1; }\n```\n\nAfter setup, capture `PRINTING_PRESS_BIN=\u003Cabs-path>` and use that absolute path for every `cli-printing-press ...` invocation in this skill. If setup emitted `[go-toolchain-old]` or `[low-disk]`, surface the advisory to the user and continue unless setup also emitted `[setup-error]`. `[go-toolchain-old]` means later Go commands may download the required toolchain or fail when downloads are blocked; `[low-disk]` means this run may need several GiB for generated files, Go build cache, module downloads, or repository clones.\n\nCheck binary version compatibility by reading the `min-binary-version` field from this skill's YAML frontmatter, running `\"$PRINTING_PRESS_BIN\" version --json`, and parsing the version from the output. Compare it to `min-binary-version` using semver rules. If the installed binary is older than the minimum, stop immediately and tell the user: \"cli-printing-press binary vX.Y.Z is older than the minimum required vA.B.C. Run `go install github.com\u002Fmvanhorn\u002Fcli-printing-press\u002Fv4\u002Fcmd\u002Fcli-printing-press@latest` to update.\"\n\n### Public-library hint\n\nIf the user's request includes phrasing like \"polish notion **in the\npublic library**\", \"polish **from the public library**\", or \"polish the\npublished cal-com\" — and the named CLI is **not** in\n`$PRESS_LIBRARY\u002F\u003Cslug>\u002F` — they're asking to polish a CLI that lives\nupstream but not locally. Polish runs against the internal library, so\nthe right move is to import first.\n\nSuggest: `\u002Fprinting-press-import \u003Cslug>` to bring it in, then re-run\npolish. Don't try to polish a CLI that isn't in the internal library.\n\nIf the named CLI **is** already in `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`, the\n\"public library\" phrasing is informational — just proceed with polish\nand let the divergence check (below) handle any drift.\n\n### Resolve CLI\n\nThe argument string can contain a `--standalone` flag plus one positional value\n(a slug, binary name, or path). In standalone slash-command mode, it may also\ncontain a free-text scope after the optional positional value, such as\n`\u002Fprinting-press-polish sculptok review the open PR comments and fix them`.\nThat trailing natural-language text is the user's own trusted user scope. Carry\nit forward into the polish plan and result block; do not classify it as\ninjection or tampering.\n\nIt can also contain a Phase 3 gate bundle and a `printing_press_bin:\n\u003Cabs-path>` line on following lines when invoked by the main printing-press\nskill. The flag may appear before or after the positional value; it is the only\nflag this skill consumes from `args`. Strip it before path resolution.\n\nWhen `args` is multi-line, treat the first non-empty line as the positional\nvalue\u002Fscope line and parse the remaining lines as the optional Phase 3 gate\nbundle. Do not include the bundle text in path resolution.\n\nParse caller modes differently:\n\n- **Standalone slash command (`STANDALONE_MODE=true`).** After stripping\n  `--standalone`, try to resolve the first shell word as a slug, binary name, or\n  path. If it resolves, use it as the positional value and store the remaining\n  words as `USER_SCOPE`. If it does not resolve, treat the whole line as\n  free-text scope; this branch asks which CLI to polish and retains that scope\n  for the chosen CLI. If there is no trailing text after a resolved positional\n  value, run the normal generic polish pass.\n- **Mid-pipeline Skill-tool call.** Keep the strict grammar: one path-like\n  positional value on the first line plus the optional structured bundle on\n  later lines. Unexpected free text in this machine-generated path is not a\n  user scope and should still be rejected or clarified rather than folded into\n  the run.\n\nThe positional value can be:\n- A short name: `redfin` (looks up `$PRESS_LIBRARY\u002Fredfin`)\n- A full name: `redfin-pp-cli` (strips suffix, looks up `$PRESS_LIBRARY\u002Fredfin`)\n- A path: `$PRESS_LIBRARY\u002Fredfin` (used directly)\n\nResolution order for the positional value:\n1. If it is an absolute or `~`-prefixed path and exists, use it\n2. Try `$PRESS_LIBRARY\u002F\u003Carg>` (exact match — works for slug like `redfin`)\n3. If it has `-pp-cli` suffix, strip it and try `$PRESS_LIBRARY\u002F\u003Cslug>` (e.g., `redfin-pp-cli` → `redfin`)\n4. Fuzzy search: `ls $PRESS_LIBRARY\u002F | grep -i \u003Carg>` for close matches\n\n**Caller scenarios and the `--standalone` flag.** Polish has two callers; they invoke it through different mechanisms, and the Publish Offer at the end of this skill fires only when `STANDALONE_MODE` is true. **Determine `STANDALONE_MODE` from the caller mode and the flag, not from the resolved path.**\n\n- **Standalone (user-invoked, `\u002Fprinting-press-polish redfin`).** Invoked via the slash command. Treat as `STANDALONE_MODE=true` unconditionally — the slash-command form is the publish-intent surface, even when the user omits the flag. The arg is a slug or binary name; resolution lands on `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`. This is the published copy and the right target.\n- **Mid-pipeline (main printing-press skill Phase 5.5, hold-path \"Polish to retry\").** Invoked via the Skill tool with `args: \"$CLI_WORK_DIR\"`. The arg is an absolute path to `~\u002Fprinting-press\u002F.runstate\u002F...\u002Fruns\u002F...\u002Fworking\u002F\u003Capi>-pp-cli\u002F`; resolution must hit rule 1. `STANDALONE_MODE=false` by default — main SKILL owns the publish flow on this path, so polish defers. **Do not paraphrase the arg to the slug** — Phase 5.5 fires before the working CLI is promoted, so `$PRESS_LIBRARY\u002F\u003Cslug>\u002F` either doesn't exist or holds the *prior* run's stale CLI.\n- **Skill-tool standalone override.** A non-slash caller that genuinely wants polish to publish must opt in explicitly by including `--standalone` in `args` (e.g., `args: \"--standalone $PRESS_LIBRARY\u002Fredfin\"`). Without that token, polish never publishes from a Skill-tool invocation — even if the resolved path happens to live under `$PRESS_LIBRARY\u002F`. The flag is the contract; the path is not.\n\nThis caller-mode-driven gate replaces the older path-substring heuristic (`*.runstate\u002F*`). The heuristic broke when the main SKILL's Phase 5.5\u002F5.6 ordering inverted, or when polish was invoked from a non-`.runstate` scratch layout: polish would see a `$PRESS_LIBRARY\u002F\u003Cslug>\u002F` path, conclude \"standalone,\" and fire its Publish Offer (fork, global git config, public PR) inside a mid-pipeline run. The flag is unambiguous and the safer default is no-publish.\n\n### Phase 3 gate bundle\n\nMid-pipeline callers pass these fields after the CLI path in `args`:\n\n```yaml\nphase3_transcendence_rows_planned: \u003Cplanned>\nphase3_transcendence_rows_built: \u003Cbuilt>\nphase3_transcendence_rows_missing:\n  - \u003Cmanifest row name or command>\nprior_sub60_reprint: \u003Ctrue|false>\npartial_transcendence_override: \u003Cnone or build-log note path>\n```\n\nParse the bundle before diagnostics and keep the values available for ship\nlogic. Missing bundle fields mean \"no forced Phase 3 hold\"; they do not block\nstandalone polish. If `prior_sub60_reprint: true`,\n`phase3_transcendence_rows_missing` contains any row, and\n`partial_transcendence_override` is empty or `none`, polish must emit\n`ship_recommendation: hold` even if the local diagnostics are otherwise clean.\nAdd the missing rows to `remaining_issues` so the parent skill can show the\nspecific gate that blocked promotion.\n\nThe lock-status check in the next code block is the safety net for the mid-pipeline scenario: if a build lock is held for this CLI (under either name form), polish refuses to run. `cli-printing-press lock` normalizes slug ↔ binary-name internally, so the check works regardless of which form the basename produces.\n\nIf no match or multiple matches, present via `AskUserQuestion`. Show at most 4\nmatches sorted by modification time (most recent first) with human-friendly\nrelative timestamps (e.g., \"generated 2 hours ago\").\n\n```bash\nCLI_DIR=\"\u003Cresolved path>\"\nCLI_NAME=\"$(basename \"$CLI_DIR\")\"\nSTANDALONE_MODE=\"\u003Ctrue|false>\"  # true iff slash-command invocation or --standalone in args; default false for Skill-tool invocations\n\n# Check if there's an active build lock — polish edits would be overwritten\n# when the running build promotes to library.\n_lock_json=$(\"$PRINTING_PRESS_BIN\" lock status --cli \"$CLI_NAME\" --json 2>\u002Fdev\u002Fnull)\nif echo \"$_lock_json\" | grep -q '\"held\".*true'; then\n  if echo \"$_lock_json\" | grep -q '\"stale\".*true'; then\n    echo \"Warning: stale lock exists for $CLI_NAME (build may have crashed).\"\n    echo \"Proceeding with polish. Run '$PRINTING_PRESS_BIN lock release --cli $CLI_NAME' to clear.\"\n  else\n    echo \"An active build is in progress for $CLI_NAME.\"\n    echo \"Polish edits would be overwritten when the build promotes.\"\n    echo \"Wait for the build to finish, then run polish.\"\n    exit 1\n  fi\nfi\n\n# Verify it's a valid Go CLI\nif [ ! -f \"$CLI_DIR\u002Fgo.mod\" ]; then\n  echo \"Not a valid CLI directory: $CLI_DIR\"\n  exit 1\nfi\n\necho \"Polishing: $CLI_NAME\"\necho \"Location: $CLI_DIR\"\n```\n\n### Find spec and research dir\n\n```bash\nAPI_SLUG=\"${CLI_NAME%-pp-cli}\"\nSPEC_PATH=\"\"\nfor f in \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\"\u002F*\u002Fresearch\u002F*.yaml \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\"\u002F*\u002Fresearch\u002F*.json \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"\u002F*\u002Fresearch\u002F*.yaml \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"\u002F*\u002Fresearch\u002F*.json; do\n  if [ -f \"$f\" ]; then\n    SPEC_PATH=\"$f\"\n    break\n  fi\ndone\n\n# Build the spec flag once. Empty when no spec was found — diagnostic\n# commands accept a missing --spec and degrade gracefully.\nSPEC_FLAG=\"\"\nif [ -n \"$SPEC_PATH\" ]; then\n  SPEC_FLAG=\"--spec $SPEC_PATH\"\nfi\n\n# Locate the research dir. dogfood's --research-dir triggers\n# checkNovelFeatures, which writes novel_features_built back into\n# research.json AND syncs the verified list into .printing-press.json.\n# Without this flag, legacy CLIs whose manifest predates the\n# novel_features schema fail publish-validate's transcendence gate.\n#\n# Two layouts to handle, keyed on $CLI_DIR path structure (NOT on the\n# absence of a manuscripts entry — re-generating a previously-published\n# API leaves stale manuscript entries from prior runs that would point\n# scorecard at the wrong research.json):\n#  1. Mid-pipeline polish (invoked from the main printing-press flow\n#     before promote): $CLI_DIR is under $PRESS_RUNSTATE\u002F...\u002Fruns\u002F\u003Cid>\u002Fworking\u002F\u003Ccli>\n#     (i.e. the path contains `.runstate\u002F`), and research.json lives at\n#     $PRESS_RUNSTATE\u002F...\u002Fruns\u002F\u003Cid>\u002Fresearch.json — $CLI_DIR's grandparent.\n#  2. Post-promote (standalone polish): research.json lives at\n#     manuscripts\u002F\u003Capi>\u002F\u003Crun-id>\u002Fresearch.json.\nRESEARCH_DIR=\"\"\nMANIFEST_RUN_ID=\"\"\nif [ -f \"$CLI_DIR\u002F.printing-press.json\" ]; then\n  if command -v jq >\u002Fdev\u002Fnull 2>&1; then\n    MANIFEST_RUN_ID=\"$(jq -r '.run_id \u002F\u002F empty' \"$CLI_DIR\u002F.printing-press.json\" 2>\u002Fdev\u002Fnull || true)\"\n  fi\n  if [ -z \"$MANIFEST_RUN_ID\" ]; then\n    MANIFEST_RUN_ID=\"$(sed -nE 's\u002F.*\"run_id\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*\u002F\\1\u002Fp' \"$CLI_DIR\u002F.printing-press.json\" | head -1)\"\n  fi\nfi\ncase \"$CLI_DIR\" in\n  *.runstate\u002F*)\n    _grandparent=\"$(dirname \"$(dirname \"$CLI_DIR\")\")\"\n    if [ -f \"$_grandparent\u002Fresearch.json\" ]; then\n      RESEARCH_DIR=\"$_grandparent\"\n    fi\n    ;;\n  *)\n    if [ -n \"$MANIFEST_RUN_ID\" ]; then\n      for base in \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\" \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"; do\n        if [ -f \"$base\u002F$MANIFEST_RUN_ID\u002Fresearch.json\" ]; then\n          RESEARCH_DIR=\"$base\u002F$MANIFEST_RUN_ID\"\n          break\n        fi\n      done\n    fi\n    # Match publish package's fallback: API slug first, then CLI name, each\n    # using the lexicographically latest run id when the manifest has none.\n    if [ -z \"$RESEARCH_DIR\" ]; then\n      for base in \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\" \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"; do\n        if [ -d \"$base\" ]; then\n          _latest=\"$(find \"$base\" -mindepth 2 -maxdepth 2 -name research.json -type f 2>\u002Fdev\u002Fnull | sort | tail -1)\"\n          if [ -n \"$_latest\" ]; then\n            RESEARCH_DIR=\"$(dirname \"$_latest\")\"\n            break\n          fi\n        fi\n      done\n    fi\n    ;;\nesac\n\n# Use a bash array so the flag survives paths with spaces (e.g. when\n# $HOME or $PRESS_RUNSTATE resolves through a path containing spaces).\nRESEARCH_ARGS=()\nif [ -n \"$RESEARCH_DIR\" ]; then\n  RESEARCH_ARGS=(--research-dir \"$RESEARCH_DIR\")\nfi\n\n# pii-audit runs against the CLI dir, but publish package later copies the\n# same run archive under .manuscripts\u002F\u003Crun-id> before enforcing the PII gate.\n# Pass the run dir here so polish sees the narrative manuscript files with\n# the same relative paths publish will scan.\nPII_ARGS=()\nif [ -n \"$RESEARCH_DIR\" ]; then\n  PII_ARGS=(--manuscripts-dir \"$RESEARCH_DIR\")\nfi\n```\n\n### Divergence check\n\n**Stop and run this step before Phase 1. Do not skip it. Do not proceed to diagnostics until you have completed the check and resolved any divergence.**\n\nThe internal copy at `$CLI_DIR` can drift from the public library (`mvanhorn\u002Fprinting-press-library`) copy if anyone edited the public repo directly after this CLI was last published. Polishing a stale internal copy and re-publishing later silently overwrites those public-only fixes — a real failure mode that shipped CLIs hit.\n\n**You must:**\n\n1. **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\u002Fprinting-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.\n2. **Locate this CLI inside the clone.** `find \u003Cclone>\u002Flibrary -type d -name \"\u003Capi>-pp-cli\"` or equivalent.\n3. **Run `diff -r \u003Cpublic-cli-dir> $CLI_DIR`** with these exclusions, all of which are expected to diverge after publish:\n   - `.printing-press-tools-polish.json` (local ledger, not published)\n   - `.printing-press-pii-polish.json` (local ledger, not published)\n   - `go.mod` and `go.sum` — publish rewrites the module path from `\u003Capi>-pp-cli` to `github.com\u002Fmvanhorn\u002Fprinting-press-library\u002Flibrary\u002F\u003Ccategory>\u002F\u003Capi>`\n   - 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.\n\n   Concretely: `diff -r --exclude=go.mod --exclude=go.sum --exclude=.printing-press-tools-polish.json --exclude=.printing-press-pii-polish.json \u003Cpublic-cli-dir> $CLI_DIR`.\n\n   Don't pass `--exclude='\u003Capi>-pp-cli'` or `--exclude='\u003Capi>-pp-mcp'` — those names match both the root-level binary files **and** the `cmd\u002F\u003Capi>-pp-cli\u002F` and `cmd\u002F\u003Capi>-pp-mcp\u002F` source directories. Excluding by binary name silently skips the entire `cmd\u002F` subtree, hiding real divergence in `main.go`. The \"Only in $CLI_DIR: \u003Capi>-pp-cli\" line for the built binary is one row of expected output, not noise worth filtering at the cost of completeness.\n4. **Surface the result** before continuing.\n\nOutcomes:\n\n- **No clone found** → user doesn't have public locally. State this explicitly (\"public library not found locally; proceeding on internal as canonical\") and continue.\n- **Clone found but doesn't contain this CLI** → never published or under a different name. State this and continue.\n- **Found and diff is empty** → in sync. State this and continue.\n- **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.\n\nBefore showing the sync prompt, check whether internal has files modified after its `.printing-press.json` timestamp (the user has been polishing locally without publishing). If yes, hedge the prompt explicitly: syncing will overwrite their pending local work. Let them decide whether to keep their local edits or pull public's.\n\nAfter sync (or explicit skip), the rest of polish operates on `$CLI_DIR` as canonical. The eventual `\u002Fprinting-press-publish` step pushes internal back to public; no second divergence check is needed there.\n\n**The check has run only when one of the four outcomes above is explicitly stated in your response.** Silent omission counts as not having run it.\n\n## Phase 1: Baseline diagnostics\n\n```bash\ncd \"$CLI_DIR\"\n\n# Build\ngo build -o \"$CLI_NAME\" .\u002Fcmd\u002F\"$CLI_NAME\" 2>&1\n\n# Diagnostics. SPEC_FLAG and RESEARCH_ARGS are set in the \"Find spec\n# and research dir\" step above. RESEARCH_ARGS enables dogfood to\n# verify novel features and sync them into .printing-press.json\n# (required for publish-validate's transcendence gate).\n\"$PRINTING_PRESS_BIN\" dogfood --dir \"$CLI_DIR\" $SPEC_FLAG \"${RESEARCH_ARGS[@]}\" 2>&1\n\"$PRINTING_PRESS_BIN\" verify --dir \"$CLI_DIR\" $SPEC_FLAG --json 2>&1\n\"$PRINTING_PRESS_BIN\" workflow-verify --dir \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-workflow-verify.json 2>&1 || true\n\"$PRINTING_PRESS_BIN\" verify-skill --dir \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-verify-skill.json 2>&1 || true\n# publish-validate is a publish-readiness gate, not a CLI-readiness gate.\n# Mid-pipeline polish runs before the main SKILL's promote step and before\n# the publish skill packages tools-manifest.json, so its prerequisites\n# (manifest.printer from git config github.user, packaged tools manifest,\n# phase5 acceptance proof relocated under $CLI_DIR\u002F.manuscripts\u002F\u003Crun>\u002Fproofs\u002F)\n# are not yet satisfied. Running publish-validate here would cascade\n# parent-pipeline-owned failures into the polish ship_recommendation,\n# which the main SKILL's Phase 5.5 verdict-override then turns into a\n# CLI-level hold. Only run publish-validate when polish is the publish\n# entry point (slash-command invocation or explicit --standalone).\nif [ \"$STANDALONE_MODE\" = \"true\" ]; then\n  \"$PRINTING_PRESS_BIN\" publish validate --dir \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-publish-validate.json 2>&1 || true\nfi\n# --live-check samples novel-feature outputs and populates\n# live_check.features[].warnings (Wave B entity detection) — required for\n# the \"Output entity warnings\" row below to have data to read.\n# RESEARCH_ARGS points scorecard at the run's research.json when the\n# CLI lives under $PRESS_RUNSTATE\u002Fruns\u002F\u003Cid>\u002Fworking\u002F\u003Ccli> (mid-pipeline\n# polish). Without it, scorecard looks adjacent to the binary, doesn't\n# find research.json, and reports `unable: true`.\n# A bare scorecard and scorecard --write-manifest report the same total.\n# A verify summary already in .printing-press.json is included either way;\n# a Calibration line means that summary raised the total. --spec changes\n# the domain denominator, which human output prints beside the total —\n# compare runs that passed the same spec.\n\"$PRINTING_PRESS_BIN\" scorecard --dir \"$CLI_DIR\" $SPEC_FLAG \"${RESEARCH_ARGS[@]}\" --live-check --json > \u002Ftmp\u002Fpolish-scorecard.json 2>&1 || true\n\"$PRINTING_PRESS_BIN\" scorecard --dir \"$CLI_DIR\" $SPEC_FLAG 2>&1\n\"$PRINTING_PRESS_BIN\" tools-audit \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-tools-audit-before.json 2>&1 || true\n\"$PRINTING_PRESS_BIN\" pii-audit \"$CLI_DIR\" \"${PII_ARGS[@]}\" --json > \u002Ftmp\u002Fpolish-pii-audit-before.json 2>&1 || true\ngo vet .\u002F... 2>&1\n# Released gosec bundles a golang.org\u002Fx\u002Ftools that cannot read newer Go export\n# data, so on a newer toolchain it silently skips packages. polish_gosec uses an\n# installed gosec only when it loads every package; otherwise it builds the\n# pinned gosec against a current x\u002Ftools in a private temp dir. Each block runs\n# in its own shell, so the after-fix scan repeats this definition verbatim.\npolish_gosec() {\n  local out=\"$*\" built\n  if command -v gosec >\u002Fdev\u002Fnull 2>&1; then\n    gosec -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n    [ \"$(jq '(.\"Golang errors\" \u002F\u002F {}) | length' \"$out\" 2>\u002Fdev\u002Fnull || echo 1)\" = 0 ] && return 0\n    echo \"polish_gosec: installed gosec could not load every package; building the pinned fallback\" >&2\n  fi\n  built=$(mktemp -d) || return 1\n  if ! (cd \"$built\" && export GOWORK=off && go mod init polish-gosec && go get github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec@v2.29.0 golang.org\u002Fx\u002Ftools@v0.52.0 && go build -o gosec github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec) >\"$built\u002Fbuild.log\" 2>&1; then\n    echo \"polish_gosec: could not build the gosec fallback:\" >&2\n    tail -n 20 \"$built\u002Fbuild.log\" >&2\n    rm -rf \"$built\"\n    return 1\n  fi\n  \"$built\u002Fgosec\" -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n  rm -rf \"$built\"\n}\npolish_gosec \u002Ftmp\u002Fpolish-gosec-before.json\n```\n\nverify-skill and workflow-verify run alongside dogfood\u002Fverify\u002Fscorecard so polish catches the same class of failures the public-library CI catches. `publish-validate` runs only when `STANDALONE_MODE=true` (slash-command or `--standalone` Skill-tool invocation). The publish-validate leg is a hard ship-gate **for standalone polish**: in that mode polish cannot recommend `ship` or `ship-with-gaps` while `\"$PRINTING_PRESS_BIN\" publish validate` reports `passed: false`. Mid-pipeline polish (`STANDALONE_MODE=false`) skips publish-validate entirely — its prerequisites (manifest.printer from `git config github.user`, packaged `tools-manifest.json`, phase5 acceptance proof relocated under `$CLI_DIR\u002F.manuscripts\u002F\u003Crun>\u002Fproofs\u002F`) are parent-pipeline-owned and not yet satisfied at this point; the main SKILL's Phase 6 publish flow gates on publish-validate at the correct time. See \"Ship logic\" below for how this affects ship_recommendation.\n\n**Live matrix qualifier.** After each `scorecard --live-check --json` run, read `\u002Ftmp\u002Fpolish-scorecard.json` and record whether `live_check` actually exercised live samples. Treat it as `exercised` only when `live_check.unable` is false and at least one feature was evaluated (`passed + failed > 0`, or equivalent feature statuses). Treat `live_check.unable: true`, no `live_check`, no evaluated features, or missing credentials\u002Ftoken as `not_exercised`. A clean mock dogfood\u002Fverify run is still useful, but it is **not** a live matrix pass.\n\n`gosec` runs as the off-the-shelf security static-analysis leg for hand-written Go. Prefer an installed `gosec` binary when present; `polish_gosec` (defined verbatim in both the baseline and after-fix blocks) falls back to building the pinned `github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec@v2.29.0` against `golang.org\u002Fx\u002Ftools@v0.52.0` when no binary is installed or the installed one cannot load every package, so a clean machine on a current Go toolchain still gets a full, reproducible check without a separate setup step. Read `\u002Ftmp\u002Fpolish-gosec-before.json` for the baseline finding count and issue details. If the command fails before writing JSON (including a fallback build failure, which `polish_gosec` reports on stderr with a non-zero return), or the JSON still has a non-empty `\"Golang errors\"` map (packages gosec could not type-check, so their findings are missing), treat the scan as a polish failure: add it to `remaining_issues`, set `ship_recommendation: hold`, and include the stderr or error summary so the next run can distinguish network\u002Ftooling failure from CLI defects. Prioritize findings in hand-authored files: whole files under `internal\u002Fcli\u002F`, `internal\u002Fsyncer\u002F`, and `internal\u002Fstore\u002F` whose first 20 lines lack the `Generated by CLI Printing Press` header are polish-owned novel-feature code. Findings in generator-emitted files are Printing Press retro candidates unless they can be fixed durably by changing the spec and regenerating; do not hand-edit generated files just to silence gosec.\n\n**If Phase 1 baseline reveals the underlying CLI needs re-discovery** — broken HTML\u002FSSR extraction, sparse capture (fewer than 5 unique endpoints in the source manuscript), wrong endpoint shapes, missing GraphQL operation hashes, or any signal that the CLI was generated from incomplete capture — polish does not normally do browser capture itself. When re-discovery is required, use the capture backends the runtime already exposes (Claude chrome-MCP `mcp__claude-in-chrome__*` and computer-use `mcp__computer-use__*`) rather than inventing a new capture flow. Re-discovery from polish is rare but real.\n\nParse findings into categories:\n\n| Category | Source | What to look for |\n|----------|--------|------------------|\n| Verify failures | verify --json | Commands with score \u003C 3 |\n| SKILL static-check failures | verify-skill --json | Any `findings[]` with `severity=error` (flag-names, flag-commands, positional-args, unknown-command, canonical-sections). Hard ship-gate: ship cannot fire while these exist. |\n| Workflow gaps | workflow-verify --json | Verdict `workflow-fail`. Soft gate: surface in `remaining_issues` and downgrade to `hold` when the workflow is the CLI's primary value. |\n| Publish validation failures | publish validate --json | `passed: false`. **Standalone polish only** (runs only when `STANDALONE_MODE=true`); skipped in mid-pipeline polish where publish prerequisites aren't yet satisfied. When it runs, it's a hard ship-gate: ship cannot fire while publish validate fails. If the only failing check is missing phase5 acceptance, report `phase5 acceptance required` with the next-step command: authenticate, then run `\"$PRINTING_PRESS_BIN\" dogfood --dir \"$CLI_DIR\" $SPEC_FLAG --live --level quick --write-acceptance \u003Cproofs-dir>\u002Fphase5-acceptance.json`. Use the proofs directory from the validate error when present. |\n| Security static-analysis failures | gosec JSON | Any `Issues[]` entry, especially G201\u002FG202 SQL construction, G101 credential literals, or unsafe file\u002Fcommand execution. Hard ship-gate when the finding is in hand-authored novel-feature Go. |\n| Dead code | dogfood | Dead functions, dead flags |\n| Stale files | dogfood | Unregistered commands |\n| Description issues | dogfood | Boilerplate root Short |\n| README gaps | scorecard | README score \u003C 8 |\n| Example gaps | dogfood | Commands missing examples |\n| Go vet issues | go vet | Any output |\n| Output entity warnings | scorecard JSON | `live_check.features[].warnings` — raw HTML entities in human output |\n| Output plausibility | Phase 4.85 | Findings from the agentic output review |\n| MCP tool quality | tools-audit | Empty Short, thin Short, missing read-only annotations, thin MCP descriptions |\n| Customer PII | pii-audit | Card last-4, email, phone, ZIP+4, postal-address, and account-identifier shapes in high-risk files (manuscripts, fixtures, README) |\n\n**Environmental failures vs. CLI defects.** Some Phase 1 outputs surface failures that aren't real CLI bugs and should not block ship:\n\n- `scorecard --live-check` reporting `SQLITE_BUSY`, network timeouts, `401` from a mock or expired token, or HTTP errors that depend on the test workspace's permissions\u002Fstate — these are test-environment issues, not CLI defects.\n- `verify` mock-harness flakes on commands with binary output (e.g., `qr` returning a PNG that the substring matcher can't validate) or commands with optional positional args where dry-run output legitimately doesn't contain the verify probe string.\n- Learn-loop commands: the dogfood\u002Fverify matrix now covers the default-on learn surface (`teach`, `recall`, `learnings`, `playbook`). `teach` and `teach-playbook` intentionally exit 2 when invoked bare, declared via `pp:typed-exit-codes`, so `verify` scores that as pass while `dogfood --live` records the `happy_path` and `json_fidelity` checks as skips with reason `declared non-zero exit 2`; neither is a defect and neither is a reason to \"fix\" the exit code. A skipped happy path does not count toward phase5 live coverage, so a novel feature that only ever exits non-zero on its happy path is reported hollow rather than covered. `learnings stats` on a fresh print legitimately reports zeros and empty sections; that is an empty local store, not a defect.\n\nClassify these as environmental in `skipped_findings` with the specific reason; do not spend Phase 2 cycles trying to \"fix\" them. The polish skill's ship logic already excludes live-check failures from gating, but the agent should still annotate them so reviewers can see they were considered and dismissed deliberately.\n\n### Phase 4.85 — Agentic output review (Wave B)\n\nAfter the mechanical diagnostics above complete, invoke the `printing-press-output-review` sub-skill via the Skill tool. The sub-skill carries `context: fork` and owns the dispatch prompt, gate logic, and known blind spots — single source of truth shared with the main printing-press skill.\n\n```\nSkill(\n  skill: \"cli-printing-press:printing-press-output-review\",\n  args: \"$CLI_DIR\"\n)\n```\n\nParse the returned `---OUTPUT-REVIEW-RESULT---` block. `status: WARN` findings flow into the diagnostic categories above so Phase 2 fixes address both rule-based and plausibility issues. `status: SKIP` means the review did not run: record it as skipped, do not count it as a pass, and do not block on it.\n\nWave B gating applies: all findings are warnings, never blockers. Fix if obvious and cheap; document with a short comment if deferred.\n\nRecord baseline scores: scorecard total, verify pass rate, dogfood verdict, live matrix qualifier (`exercised` \u002F `not_exercised`), go vet issue count, gosec finding count, output-review finding count.\n\n## Phase 2: Fix\n\nFix in priority order. After each priority level, update the lock heartbeat:\n\n```bash\n\"$PRINTING_PRESS_BIN\" lock update --cli \"$CLI_NAME\" --phase polish 2>\u002Fdev\u002Fnull\n```\n\n### Runtime variant default checklist\n\nIf a polish fix adds or changes a runtime mode, data-source option, auth tier, transport, or other user-visible default, document this short checklist before selecting the default:\n\n- **User-visible default:** which behavior users get without extra flags or config.\n- **Compatibility risk:** whether existing commands, scripts, MCP tools, or stored config change behavior.\n- **Verification command:** the exact command that proves the default and the non-default escape hatch both work.\n\nKeep the checklist in the polish notes or result block. Skip it for ordinary bug fixes that do not change runtime variants or defaults.\n\n### Cross-cutting API-call instrumentation\n\nWhen polish builds a feature class that must observe every outbound API call,\nsuch as a quota ledger, request log, or audit trail, instrument the generated\nclient middleware in `internal\u002Fclient\u002Fclient.go` instead of individual command\nhandlers. Prefer a shared pre-dispatch hook when one exists; otherwise cover\nboth `do()` and `doRead()`. The `do()` path handles standard endpoint mirrors,\nsync iterations, and novel features that use the generated client, while\n`doRead()` handles read-only operations that ride POST-like transports, such as\nGraphQL queries, JSON-RPC reads, and POST-based searches marked\n`mcp:read-only`.\nPer-command hooks under-count because they only see the commands polish touched.\n\n### Novel-feature data routing\n\nWhen polish adds or fixes a novel command that reads API response data into the\nlocal store, route data through the generated typed schemas instead of writing\nraw response JSON directly into tables:\n\n1. Read `internal\u002Ftypes\u002F\u003Cresource>.go` and `internal\u002Fstore\u002F\u003Cresource>.go` for the\n   resource being cached. Use the typed insert\u002Fupsert helpers those files emit\n   whenever they exist. If helpers are missing for a generated resource, create\n   them before writing any persistence code.\n2. Check the response shape against the spec schema and a real sample response\n   before deciding the insert mapping is correct.\n3. Decode the API response into the typed struct before persistence. Do not\n   build `INSERT INTO ...` statements from untyped `map[string]any` or raw\n   `json.RawMessage` values unless the table is a custom polish-owned table\n   declared in hand-authored migrations; see the raw SQL exception below.\n4. Verify the target table from the resource type, not from whichever query the\n   novel command happened to start with. A command that fetched `\u003Cchild>`\n   records must insert `\u003Cchild>` rows, not parent rows or a convenient adjacent\n   table.\n5. Normalize nested response identifiers before insert. If the API wraps the\n   scalar id inside an object that also contains metadata, extract the scalar id\n   field and store that value; never store the whole id object as a primary key\n   or foreign-key reference.\n\nRaw `database\u002Fsql` writes are acceptable only for custom polish-owned tables\ndeclared in hand-authored migrations. In that case, keep the table schema\nexplicit in `internal\u002Fstore\u002F`, document why the generated resource helper does\nnot apply, and still decode nested identifiers to scalars before persistence.\n\n### Priority 0: MCP surface migration (legacy CLIs)\n\nIf Phase 1's `dogfood` reported `MCP Surface: FAIL` with a parity mismatch, the CLI was generated before the runtime cobratree walker existed and is still on the static `internal\u002Fmcp\u002Ftools.go` surface. The fix is mechanical:\n\n```bash\n\"$PRINTING_PRESS_BIN\" mcp-sync \"$CLI_DIR\"\n```\n\nThat migrates the MCP surface to the runtime walker, regenerates `tools-manifest.json` and `internal\u002Fmcp\u002Ftools.go`, and applies any `mcp-descriptions.json` overrides. If it exits with `mcp-sync refused` and `reprint required`, stop this polish run and hand off to `\u002Fprinting-press-reprint`; the target CLI's generated client is too old for the current MCP handler, so rewriting `tools.go` alone would break its build. Include in the handoff that the reprint flow must run its normal dogfood gate against the regenerated CLI and confirm `MCP Surface: PASS` before shipping. Do not rerun dogfood against the stale `$CLI_DIR`. After a successful `mcp-sync`, re-run `dogfood` here; the parity gate should flip to PASS. Running `mcp-sync` on a compatible CLI already using the runtime walker is a no-op refresh.\n\nSkip this priority on CLIs where dogfood's MCP gate is already passing.\n\n### Priority 1: Security static-analysis failures\n\nFor each gosec finding in `\u002Ftmp\u002Fpolish-gosec-before.json`:\n\n1. Read the cited file and confirm whether it is hand-authored. A whole file\n   under `internal\u002Fcli\u002F`, `internal\u002Fsyncer\u002F`, or `internal\u002Fstore\u002F` whose first\n   20 lines lack `Generated by CLI Printing Press` is polish-owned novel-feature\n   code.\n2. If the finding is in hand-authored code, fix the root cause in source before\n   working lower-priority polish items. Examples: replace SQL string assembly\n   with parameterized queries, avoid shelling out with untrusted args, and move\n   literals that look like credentials into config\u002Fenv plumbing.\n3. If gosec flags generated code, do not hand-edit the generated file. Either\n   fix the upstream spec and regenerate, or add a `skipped_findings` entry that\n   names it as a generator retro candidate with the rule id and file path.\n4. If gosec reports a false positive, keep the suppression narrow and explain\n   it. Prefer a local `\u002F\u002F #nosec G### -- reason` only when the code is actually\n   safe and the reason is durable; otherwise fix the code.\n\nUnresolved gosec findings in hand-authored novel-feature Go are hard blockers:\nthey must appear in `remaining_issues`, force `ship_recommendation: hold`, and\nset `further_polish_recommended: yes` when the fix is plausibly mechanical.\n\n### Priority 2: Verify failures\n\nFor each command that fails verify dry-run or exec:\n\n1. Read the command file\n2. Find `Args: cobra.ExactArgs(N)` or similar constraint\n3. Remove the `Args:` field\n4. Add at the top of `RunE`:\n   ```go\n   if len(args) == 0 {\n       return cmd.Help()\n   }\n   ```\n5. For commands needing 2+ args, use `if len(args) \u003C 2`\n6. Check for dry-run nil-data crashes and add guards:\n   ```go\n   if flags.dryRun {\n       return nil\n   }\n   ```\n\n### Priority 3: Dead code\n\n1. For each dead function flagged by dogfood, grep all `.go` files to verify\n   it's truly unused (not just its definition matching itself)\n2. If truly unused: remove the function\n3. If used by another helper: leave it (false positive)\n4. After removal, remove unused imports\n5. Delete stale files (promoted commands not registered in root.go)\n\n### Priority 4: CLI description and metadata\n\n1. Read root command `Short` in `internal\u002Fcli\u002Froot.go`\n2. If it contains boilerplate (\"Reverse-engineered...\", raw API title), rewrite:\n   Pattern: `\"\u003CProduct> CLI with \u003Ccapability-1>, \u003Ccapability-2>, and \u003Ccapability-3>\"`\n3. Check commands for missing `Example` fields. Add realistic examples with\n   domain-specific values.\n\n### Priority 5: README\n\n**Cardinal rule: run `\u003Ccli> \u003Ccmd> --help` for EVERY command you put in the\nREADME.** Never guess flag names, argument formats, or valid values. If you\nwrite `--start-time` but the flag is `--start`, the README is wrong and\nusers will get errors on their first try.\n\n#### Source-of-truth files for rendered sections\n\nBefore editing README.md, SKILL.md, or `.printing-press.json`, identify whether\nthe section is rendered from a source file. Dogfood and regeneration overwrite\nthese rendered sections, so direct edits there are temporary and should be used\nonly to inspect the current output.\n\n| Rendered section or field | Source-of-truth file::field | Polish workflow |\n| --- | --- | --- |\n| README `## Unique Features` | `research.json::novel_features_built[]` | Edit the underlying `research.json` feature description\u002Fexample, then re-run dogfood with `--research-dir`. |\n| SKILL `## Unique Capabilities` | `research.json::novel_features_built[]` | Edit the underlying `research.json` feature description\u002Fexample, then re-run dogfood with `--research-dir`. |\n| `internal\u002Fmcp\u002Ftools.go` `command_mirror_capabilities` | `research.json::novel_features_built[]` | Dogfood reports a differing on-disk block and leaves it unmodified. Pass `--overwrite-command-mirror` only to replace it from `research.json`. |\n| README Quick Start | `research.json::narrative.quickstart[]` | Edit the command\u002Fcomment in `research.json`, then regenerate or re-run the dogfood\u002Frendering step. |\n| SKILL Recipes | `research.json::narrative.recipes[]` | Edit the recipe title, command, or explanation in `research.json`, then regenerate or re-run the dogfood\u002Frendering step. |\n| README\u002FSKILL Troubleshooting | `research.json::narrative.troubleshoots[]` | Edit the symptom\u002Ffix pair in `research.json`, then regenerate or re-run the dogfood\u002Frendering step. |\n| `.printing-press.json` `homepage` | `research.json::homepage` | Fix it in `research.json`, then correct or remove `homepage` in the working CLI's `.printing-press.json` before regenerating: an existing manifest value wins over research on regenerate. A value already in the library manifest also wins on promote and publish, so correct a published homepage in the library copy too. |\n| `.printing-press.json` `display_name`, `description`, `mcp_*` | `WriteManifestForGenerate`; for description\u002Fdisplay-name overrides, edit the spec (`info.title`, `info.x-display-name`, `info.description`) | Edit the spec or rerun the manifest writer. Do not hand-edit generated manifest metadata unless you are doing temporary diagnosis. |\n\nRecommended loop for these rendered sections: edit the source field, re-run\ndogfood with `--research-dir \"$RESEARCH_DIR\"` or regenerate the CLI as\nappropriate, then run a second pass to confirm the rendered README\u002FSKILL text\nstays fixed. If you edit README.md or SKILL.md directly in one of these\nsections, expect the next dogfood resync or regeneration to clobber the change.\n\nTo find the manuscript source:\n\n```bash\nPRESS_HOME=\"${PRINTING_PRESS_HOME:-$HOME\u002Fprinting-press}\"\nAPI_SLUG=\"${CLI_NAME%-pp-cli}\"\nRESEARCH_JSON=\"\"\nfor f in \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"\u002F*\u002Fresearch.json \\\n         \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\"\u002F*\u002Fresearch.json; do\n  if [ -f \"$f\" ]; then RESEARCH_JSON=\"$f\"; break; fi\ndone\n```\n\nIf `RESEARCH_JSON` exists and a rendered section has bad prose, examples, or\nflag references, fix the corresponding field in that file first. For novel\nfeatures, dogfood verifies `research.json::novel_features[]`, writes the\nsurviving set to `research.json::novel_features_built[]`, and syncs README\n`## Unique Features`, SKILL `## Unique Capabilities`, `.printing-press.json`\n`novel_features`, and root help Highlights from that verified set. A\ndiffering `command_mirror_capabilities` block in `internal\u002Fmcp\u002Ftools.go` is\nleft unmodified unless `--overwrite-command-mirror` is passed.\n\n#### Required sections (must be present and correct)\n\n1. **Title**: \"# \u003CProduct Name> CLI\" — use the product's real name with\n   correct casing\u002Fpunctuation (e.g., \"Cal.com\" not \"Cal Com\")\n2. **Subtitle**: one sentence describing what the CLI does for the user,\n   matching the root `Short` field. NOT a description of the API.\n3. **Install**: correct install command. Use the printing-press-library\n   repo URL, not a per-CLI repo that doesn't exist.\n4. **Authentication**: how to set `\u003CAPI>_API_KEY` env var, where to get\n   a key (link to the provider's settings page), self-hosted URL override\n   if supported. Read `config.go` to find all env vars.\n5. **Quick Start**: 3-5 commands someone will actually run first. Pick\n   commands that are both **most useful** (what you'd run daily) and\n   **show the CLI's value** (why install this over curl). Usually:\n   `doctor` → `sync` → transcendence command (`today`, `health`) →\n   `search`. Avoid raw list commands — they dump data without\n   demonstrating why the CLI exists.\n6. **Commands**: categorized table. Group by domain function (Scheduling,\n   Analytics, Account, Utilities), not by implementation structure.\n7. **Output Formats**: show `--json`, `--select`, `--csv`, `--compact`,\n   `--dry-run`, `--agent`. Use a real command, not a placeholder.\n8. **Agent Usage**: agent-native properties and exit codes.\n9. **Cookbook**: 8-15 recipes using **verified flag names** from `--help`.\n   Show the CLI's unique capabilities: transcendence commands, filters,\n   SQL queries, pipes. Include at least one mutation example.\n10. **Health Check**: show actual `doctor` output, not a placeholder.\n11. **Configuration**: list ALL env vars from config.go with descriptions.\n    Include config file path.\n12. **Troubleshooting**: common errors mapped to exit codes with fixes.\n\n#### Optional sections (add at your discretion)\n\n- **Rate Limits**: if the API has documented limits\n- **Self-Hosting**: if the CLI supports `--api-url` or `BASE_URL` override\n- **Pagination**: if the API has notable pagination behavior\n- **Sources & Inspiration**: credits to community projects (generated by\n  the machine, preserve if present)\n\n### Priority 5.5: SKILL static-check failures (verify-skill)\n\nRead `\u002Ftmp\u002Fpolish-verify-skill.json` for the full finding list. Each finding has a `check` (`flag-names`, `flag-commands`, `positional-args`, `unknown-command`, or `canonical-sections`), a `command` (the path the SKILL claimed), and a `detail` describing the mismatch. Common shapes and fixes:\n\n- **`flag-names`** — SKILL references `--foo` on a `\u003Ccli> ...` invocation but no command in `internal\u002Fcli\u002F*.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\u002Fprinting-press install \u003Capi> --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.\n- **`flag-commands`** — `--foo is declared elsewhere but not on \u003Ccmd>`. The flag exists somewhere but not on the command the SKILL invoked it on. Two fixes:\n  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.\n  2. If the SKILL example is genuinely wrong, fix the example to use a flag the command does declare.\n- **`positional-args`** — `got N positional args; Use: \"\u003Ccmd> \u003Carg>\" expects M-M`. The SKILL recipe passed N positional args but the command's `Use:` declares M required. Two fixes:\n  1. If the command also accepts the value via a `--flag`, change `Use: \"cmd \u003Carg>\"` to `Use: \"cmd [arg]\"` (square brackets = optional). Verify-skill correctly accepts `--flag`-only invocations against an optional positional.\n  2. If the SKILL example is missing a required positional, fix the example.\n- **`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\u002Fgenerator\u002Ftemplates\u002Fskill.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.\n\nWhen editing other parts of SKILL.md, Read the affected section first and Read it again after the Edit. `Edit` replaces a literal string; if the surrounding context has drifted, a single Edit can graft a second copy of a block onto the first instead of replacing it.\n\nAfter fixing, re-run `\"$PRINTING_PRESS_BIN\" verify-skill --dir \"$CLI_DIR\"` and confirm exit 0 before moving on.\n\n### Priority 6: Remaining dogfood issues\n\n- Path validity mismatches\n- Auth protocol mismatches\n- Example drift (examples referencing wrong commands)\n- Data pipeline integrity issues\n\n### Priority 7: MCP tool quality\n\n**Your goal now is to ensure every MCP tool exposed by this CLI carries agent-grade descriptions and correct read\u002Fwrite classifications.** Tool descriptions and classifications are how agents discover and decide whether to call a tool — thin descriptions and missing annotations directly degrade agent UX, and Phase 1's mechanical gates (verify, dogfood) do NOT catch this class of issue.\n\nStop and:\n\n1. Run `\"$PRINTING_PRESS_BIN\" tools-audit \"$CLI_DIR\" --json` to surface mechanical findings (empty Short, thin Short, missing `mcp:read-only` on read-shaped command names).\n2. You must read `references\u002Ftools-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.\n3. **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\u002Ftools-polish.md` \"Marking a finding accepted\" for the full contract.\n\nProceed to \"After all fixes\" only when the audit's summary line reads `no pending findings` with no `incomplete:` block — every gate (pre-decision fields, duplicate rationale, scorecard delta) passes.\n\n### Priority 8: Customer-PII gate\n\n**Your goal now is to clear the PII ledger so promote and publish gates pass.** The PII gate is the deterministic floor that prevents real customer values from reaching published library content. It catches card-last-4, email, US phone, ZIP+4, postal-address, and account-identifier shapes in high-risk files.\n\nStop and:\n\n1. Run `\"$PRINTING_PRESS_BIN\" pii-audit \"$CLI_DIR\" \"${PII_ARGS[@]}\"` to surface pending findings (or read `\u002Ftmp\u002Fpolish-pii-audit-before.json` from Phase 1's baseline). When `RESEARCH_DIR` exists, this includes that run's `research.json` and `research\u002F*.md` with `.manuscripts\u002F\u003Crun-id>\u002F...` paths so accepts carry forward into `publish package`.\n2. You must read `references\u002Fpii-polish.md` and follow its per-finding decision tree — fix real values in source with non-matching placeholders, or accept with the `category` + `evidence_context` pre-decision fields.\n3. **Accepting PII findings carries a strict contract.** Missing fields, 6+ accepts sharing a rationale, or wholesale-accepting ≥10 findings without source fixes all fail the gate. See `references\u002Fpii-polish.md` \"The accept contract\" and \"Forbidden accept patterns\" for the full rules.\n\nProceed to \"After all fixes\" only when `pii-audit` reads `no pending findings` with no `incomplete:` block.\n\n### After all fixes\n\n```bash\ngo build -o \"$CLI_NAME\" .\u002Fcmd\u002F\"$CLI_NAME\"\ngofmt -w .\n```\n\n## Phase 3: Re-diagnose\n\nRe-run the diagnostic sweep on the fixed CLI:\n\n```bash\n# RESEARCH_ARGS must travel with dogfood here too — without it,\n# checkNovelFeatures doesn't re-sync novel_features_built after Phase 2\n# edits, and publish-validate's transcendence gate reads stale state\n# from Phase 1's pass.\n\"$PRINTING_PRESS_BIN\" dogfood --dir \"$CLI_DIR\" $SPEC_FLAG \"${RESEARCH_ARGS[@]}\" 2>&1\n\"$PRINTING_PRESS_BIN\" verify --dir \"$CLI_DIR\" $SPEC_FLAG --json 2>&1\n\"$PRINTING_PRESS_BIN\" workflow-verify --dir \"$CLI_DIR\" --json 2>&1\n\"$PRINTING_PRESS_BIN\" verify-skill --dir \"$CLI_DIR\" --json 2>&1\nif [ \"$STANDALONE_MODE\" = \"true\" ]; then\n  \"$PRINTING_PRESS_BIN\" publish validate --dir \"$CLI_DIR\" --json 2>&1\nfi\n\"$PRINTING_PRESS_BIN\" scorecard --dir \"$CLI_DIR\" $SPEC_FLAG 2>&1\n\"$PRINTING_PRESS_BIN\" tools-audit \"$CLI_DIR\" 2>&1\n\"$PRINTING_PRESS_BIN\" pii-audit \"$CLI_DIR\" \"${PII_ARGS[@]}\" 2>&1\ngo vet .\u002F... 2>&1\npolish_gosec() {\n  local out=\"$*\" built\n  if command -v gosec >\u002Fdev\u002Fnull 2>&1; then\n    gosec -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n    [ \"$(jq '(.\"Golang errors\" \u002F\u002F {}) | length' \"$out\" 2>\u002Fdev\u002Fnull || echo 1)\" = 0 ] && return 0\n    echo \"polish_gosec: installed gosec could not load every package; building the pinned fallback\" >&2\n  fi\n  built=$(mktemp -d) || return 1\n  if ! (cd \"$built\" && export GOWORK=off && go mod init polish-gosec && go get github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec@v2.29.0 golang.org\u002Fx\u002Ftools@v0.52.0 && go build -o gosec github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec) >\"$built\u002Fbuild.log\" 2>&1; then\n    echo \"polish_gosec: could not build the gosec fallback:\" >&2\n    tail -n 20 \"$built\u002Fbuild.log\" >&2\n    rm -rf \"$built\"\n    return 1\n  fi\n  \"$built\u002Fgosec\" -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n  rm -rf \"$built\"\n}\npolish_gosec \u002Ftmp\u002Fpolish-gosec-after.json\n```\n\nRecord the after scores, including the live matrix qualifier from the final `scorecard --live-check --json` output. If the gosec command fails before writing `\u002Ftmp\u002Fpolish-gosec-after.json`, or that report still has a non-empty `\"Golang errors\"` map, treat the missing or partial post-fix scan as a polish failure: add it to `remaining_issues`, set `ship_recommendation: hold`, and include the stderr summary. If verify-skill still has any `severity=error` findings, workflow-verify still reports `workflow-fail`, publish-validate still reports `passed: false` (standalone mode only — mid-pipeline polish doesn't run this check), gosec still reports unresolved findings in hand-authored novel-feature Go, pii-audit still has pending findings or gate failures, or the final live matrix qualifier is `not_exercised`, ship cannot fire (see ship logic below). For a non-exercised live matrix, add a `remaining_issues` item such as `live matrix not exercised (mock-only\u002Fno live token); run the live gate before publish`.\n\n## Ship logic\n\nCompute the ship recommendation:\n\n- **`ship`**: verify >= 80%, scorecard >= 75, no critical failures, **AND** verify-skill exits 0 (no SKILL\u002FCLI mismatches), **AND** workflow-verify is not `workflow-fail`, **AND** (when `STANDALONE_MODE=true`) publish-validate reports `passed: true`, **AND** gosec has zero unresolved findings in hand-authored novel-feature Go, **AND** tools-audit shows zero pending findings (every finding fixed or explicitly accepted with rationale), **AND** pii-audit shows zero pending findings and zero gate failures (every PII finding fixed in source or accepted with valid pre-decision fields). The SKILL\u002Fworkflow\u002Fpublish\u002Fgosec\u002FPII 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; a CLI that publish-validate rejects is not publishable; a CLI with unresolved security static-analysis findings in hand-authored novel-feature code is still reviewer bait; a CLI that fails pii-audit at promote\u002Fpublish gates will halt shipping anyway. The publish-validate gate applies only when polish ran it (standalone mode); mid-pipeline polish defers publish-readiness to the main SKILL's Phase 6.\n- **`ship-with-gaps`**: verify >= 65%, scorecard >= 65, non-critical gaps remain, **AND** the SKILL\u002Fworkflow\u002Fgosec\u002FPII gates above are satisfied, **AND** (when `STANDALONE_MODE=true`) the publish-validate gate is satisfied, **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.\n\n  **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`:\n\n  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.\n  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:\n\n     ```markdown\n     ## Known Gaps\n\n     - **`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.\n     ```\n\n  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`.\n  4. List each Known Gaps write\u002Fupdate in `fixes_applied` so the caller can surface that this happened.\n\n  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.\n- **`hold`**: verify \u003C 65% or scorecard \u003C 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, **OR** (when `STANDALONE_MODE=true`) publish-validate reports `passed: false`, **OR** gosec still reports unresolved findings in hand-authored novel-feature Go, **OR** pii-audit still has pending findings or gate failures, **OR** the Phase 3 gate bundle says this is a prior sub-60 reprint with missing transcendence rows and no accepted `partial_transcendence_override`. Mid-pipeline polish never reaches `hold` because of publish-validate — the check doesn't run in that mode and `publish_validate_*` is emitted as `skipped (mid-pipeline)`.\n\n### Push higher without gaming\n\nThe ship gates are a floor, not a ceiling. After they pass, look at scorecard dimensions still below max and ask whether each gap is real or structural:\n\n1. **Find the underlying deficit, not the score.** The scorecard is a proxy for quality, not the goal itself. A README scoring 8\u002F10 might be missing a Cookbook section or have outdated commands — that's a real, fixable gap. A `mcp_surface_strategy` scoring 2\u002F10 on a 200-endpoint API might be flagging that the surface is mostly endpoint mirrors — also potentially fixable.\n2. **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.\n3. **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.\n4. **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.\n\n#### MCP scorecard dims map to spec fields, not generator code\n\nWhen `mcp_token_efficiency`, `mcp_tool_design`, `mcp_remote_transport`, or `mcp_surface_strategy` are below max, the fix is almost always a spec edit + regenerate (or `regen-merge` from a freshly-generated tree), **not** a generator-template change. Polish CAN address these — do not classify them as \"feature add to a generator-owned file, retro candidate.\" Cobratree shell-out tools already catalog from Short (not operator Long help), so leftover `mcp_token_efficiency` pressure is typed-endpoint descriptions, not framework `--help`.\n\n| Weak dim | Spec field that fixes it | What to add to `spec.yaml`'s `mcp:` block |\n|---|---|---|\n| `mcp_remote_transport` | `mcp.transport` | `transport: [stdio, http]` (small APIs at or under `spec.DefaultRemoteTransportEndpointThreshold` typed endpoints already get this by default; the override is only needed when the spec opted into a narrower list or the API is above the threshold and still wants remote reach) |\n| `mcp_token_efficiency`, `mcp_surface_strategy` | `mcp.endpoint_tools`, `mcp.orchestration` | `endpoint_tools: hidden` + `orchestration: code` (Cloudflare pattern: ~70 raw endpoint tools collapse to `\u003Capi>_search` + `\u003Capi>_read` + `\u003Capi>_execute`; reads use `_read`, and `_execute` previews state-changing calls until `confirm` is boolean `true`) |\n| `mcp_tool_design` | `mcp.intents` | Define multi-step intent compositions for the workflows the API supports |\n| `mcp_description_quality` | `mcp-descriptions.json` (override file at the CLI root) | Per-tool description overrides; thin spec-derived descriptions get richer text without spec edits |\n\nRecommended threshold: at >50 typed endpoints, default to recommending all four (`transport`, `endpoint_tools=hidden`, `orchestration=code`, `intents` for the headline workflows). Small APIs (\u003C= `spec.DefaultRemoteTransportEndpointThreshold`) get the http transport by default already, so `mcp_remote_transport` lands at 10\u002F10 without any spec edit — only call it out if the spec explicitly narrowed the list. The full reference is `docs\u002FSPEC-EXTENSIONS.md`.\n\nAfter editing the spec, regenerate (or `regen-merge` the changes into the published library) so the new `mcp:` block reaches templates. Cobratree-walked novel commands continue to surface as MCP tools either way; they don't need spec changes.\n\nRule of thumb: if your fix would still be valuable if the scorecard didn't exist, do it. If the only motivation is \"to push the score,\" don't.\n\n## Display delta and emit result block\n\nDisplay the delta to the user, then emit the structured `---POLISH-RESULT---` block. The block lets calling skills (e.g., main printing-press Phase 5.5) parse the recommendation and scores reliably; the human-readable table above is for the user.\n\n```\nPolish Results for \u003CCLI_NAME>:\n\n                    Before    After     Delta\n  Scorecard:        XX\u002F100    XX\u002F100    +N\n  Verify:           XX%       XX%       +N%\n  Live matrix:      exercised\u002Fnot_exercised -> exercised\u002Fnot_exercised\n  Tools-audit:      XX        XX        -N pending findings\n\nFixes applied:\n  - \u003Cone-line description of each fix>\n\nSkipped findings:\n  - \u003Cfinding>: \u003Cwhy you chose not to fix it>\n\nRemaining issues:\n  - \u003Cone-line description of each issue you tried to fix but couldn't>\n\n---POLISH-RESULT---\nscorecard_before: \u003CN>\nscorecard_after: \u003CN>\nverify_before: \u003CN>\nverify_after: \u003CN>\ndogfood_before: \u003CPASS|FAIL>\ndogfood_after: \u003CPASS|FAIL>\ndogfood_live_matrix_before: \u003Cexercised|not_exercised|unknown>\ndogfood_live_matrix_after: \u003Cexercised|not_exercised|unknown>\ngovet_before: \u003CN>\ngovet_after: \u003CN>\ngosec_before: \u003CN>\ngosec_after: \u003CN>\ntools_audit_before: \u003CN pending>\ntools_audit_after: \u003CN pending>\npublish_validate_before: \u003CPASS|FAIL|skipped (mid-pipeline)>\npublish_validate_after: \u003CPASS|FAIL|skipped (mid-pipeline)>\nfixes_applied:\n- \u003Cone-line description of each fix>\nskipped_findings:\n- \u003Cfinding>: \u003Cwhy you chose not to fix it>\nremaining_issues:\n- \u003Cone-line description of each issue you tried to fix but couldn't>\nship_recommendation: \u003Cship|ship-with-gaps|hold>\nfurther_polish_recommended: \u003Cyes|no>\nfurther_polish_reasoning: \u003Cone sentence explaining the call>\n---END-POLISH-RESULT---\n```\n\nThe three lists serve different purposes:\n- **fixes_applied**: what changed — the caller displays these\n- **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.\n- **remaining_issues**: issues you tried to fix but couldn't resolve.\n\n**`publish_validate_*` values.** Emit `PASS` or `FAIL` when polish ran publish-validate (standalone mode). Emit the literal string `skipped (mid-pipeline)` when polish skipped it (mid-pipeline invocation, `STANDALONE_MODE=false`). The skipped value is informational only: callers must not treat it as a failure when deciding whether to cascade polish's `ship_recommendation` into a CLI-level hold.\n\n**`dogfood_live_matrix_*` values.** Emit `exercised` only when live-check evaluated at least one real sample. Emit `not_exercised` for mock-only\u002Fno-token\u002Fno-research\u002Fno-evaluated-sample runs. When `dogfood_after: PASS` but `dogfood_live_matrix_after: not_exercised`, the human summary must say `dogfood PASS (mock only; live matrix not exercised — run the live gate before publish)`, and `ship_recommendation` must be `hold` unless the parent caller explicitly owns a later live gate.\n\n**`gosec_*` values.** Emit the post-triage count of gosec findings that are\nstill relevant to this printed CLI after generated-file triage. These values\nare intentionally not the raw `Issues[]` length from `\u002Ftmp\u002Fpolish-gosec-*.json`:\ndo not count generator-emitted findings that were routed to `skipped_findings`\nas retro candidates, but do count unresolved hand-authored findings that force\n`hold`.\n\n### Picking `further_polish_recommended`\n\nYour judgment, not a count of `remaining_issues`. Set `yes` when another polish invocation has a real chance of closing what's left:\n\n- `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.\n- The fixes you did land may have unblocked dependent issues you couldn't reach this pass.\n- A SKILL\u002FCLI mismatch needs a second look after this pass changed the source tree.\n\nSet `no` when another invocation would re-tread the same ground:\n\n- `remaining_issues` are decisions only the user can make (rename a flagship command, choose a default behavior, accept a structural trade-off).\n- You already attempted the fix in two different ways this pass and both failed for the same reason.\n- The blocker is external (API changed shape, rate-limited, missing credential) and not something a fresh polish run sees differently.\n- `remaining_issues` is empty AND `skipped_findings` are all environmental or structural — there is nothing left for polish to do.\n\n`further_polish_reasoning` is one sentence the caller surfaces verbatim. Make it specific (\"verify failures on `analytics export` and `report show` looked closable but I gave up too early\") rather than generic (\"more polish might help\"). Callers use this signal to decide whether to offer \"Polish again\" in their next prompt; a vague reason makes their prompt vague.\n\n## Publish Offer\n\n**Skip this entire section unless `STANDALONE_MODE` is true.** `STANDALONE_MODE` is set in the \"Resolve CLI\" block above based on the caller mode: true for slash-command invocations (`\u002Fprinting-press-polish ...`) or Skill-tool invocations that pass `--standalone` in `args`; false otherwise. When false, polish is being called from main SKILL Phase 5.5 or hold-path \"Polish to retry,\" and the working CLI has not been promoted to library yet. `\u002Fprinting-press-publish \u003Cslug>` would resolve to `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`, which is either empty or holds a stale prior run — invoking publish here would either fail to resolve or ship the wrong copy. The parent skill owns the publish flow on that path; just emit the result block and return.\n\nApply the publish turn-boundary rule: the `AskUserQuestion` answer may authorize only a handoff message, not a same-turn publish. Publishing opens or updates a public-library PR, so it requires a fresh user-authored message after polish completes. See `references\u002Fpublish-turn-boundary.md` for rationale.\n\nA simple check:\n\n```bash\nif [ \"$STANDALONE_MODE\" != \"true\" ]; then\n  echo \"non-standalone caller; skipping Publish Offer\"\n  return\nfi\n```\n\nThe gate is the caller-mode flag, **not** the resolved path. A Skill-tool invocation without `--standalone` defers publish even when the path lives under `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`; this is the safer default, and the only way the inverted Phase 5.5\u002F5.6 failure mode (mid-pipeline run firing a public fork + PR) gets caught at the polish boundary. The previous path-substring heuristic (`*.runstate\u002F*`) is no longer load-bearing here — it has been retained in the research-dir resolution block above because that block is selecting between two real on-disk layouts, which is a different concern from publish gating.\n\nFor standalone invocations, continue with the offer below.\n\nIf `ship` or `ship-with-gaps`:\n\nConstruct the prompt from the result block. The shape is data-driven so the user is never asked to weigh \"Polish again\" against \"Publish\" when polish itself just decided another pass would not help.\n\n### Recommendation\n\nPick the recommended action from the polish result:\n\n- `ship` + `remaining_issues` empty → recommend **Publish**.\n- `ship` + `remaining_issues` non-empty + `further_polish_recommended: yes` → recommend **Polish again**.\n- `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**.\n- `ship-with-gaps` + `further_polish_recommended: yes` → recommend **Polish again**.\n- `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.\n\n### Menu\n\nSuppress the \"Polish again\" option entirely when `further_polish_recommended: no`. Keep \"Publish\" and \"Done\" always available.\n\nSurface `further_polish_reasoning` as context when polish opted out of recommending another pass — the user should see *why* polish is done.\n\nPresent via `AskUserQuestion`. Two example shapes:\n\n**Polish converged clean** (`remaining_issues` empty, `further_polish_recommended: no`):\n\n> \"\u003CCLI_NAME> polished: scorecard XX\u002F100, verify XX%. Polish ran cleanly — nothing more to fix.\n>\n> Recommendation: Publish.\n>\n> 1. **Publish separately** (recommended) — show the publish command for the next user message\n> 2. **Done for now** — CLI is at $PRESS_LIBRARY\u002F\u003Ccli-name>\"\n\n**Polish thinks another pass would help** (`remaining_issues` non-empty, `further_polish_recommended: yes`):\n\n> \"\u003CCLI_NAME> polished: scorecard XX\u002F100, verify XX%. \u003CN> issues remain.\n>\n> Polish notes: '\u003Cfurther_polish_reasoning>'\n>\n> Recommendation: Polish again before publishing.\n>\n> 1. **Polish again** (recommended) — close the remaining \u003CN> issues\n> 2. **Publish separately** — show the publish command to ship as-is in the next user message\n> 3. **Done for now** — CLI is at $PRESS_LIBRARY\u002F\u003Ccli-name>\"\n\nThe recommended option leads, carries the `(recommended)` label, and the leading `Recommendation:` line states the agent's call explicitly. Three reinforcing channels so the user does not have to infer from ordering.\n\n### If \"Publish separately\"\n\nDo not invoke `\u002Fprinting-press-publish \u003Ccli-name>` from this same turn, and do not check or create public-library PRs here. Print a handoff that requires an explicit fresh user-authored message. Include the `--from-polish` marker so publish can offer the same post-publish retro tail that polish used to offer after a successful inline publish:\n\n> \"Publishing requires a separate user confirmation because it can fork `mvanhorn\u002Fprinting-press-library`, push a branch, and open or update a PR.\n>\n> To publish, send this as your next message:\n>\n> `\u002Fprinting-press-publish \u003Ccli-name> --from-polish`\"\n\nAfter printing the handoff, stop. If the user sends the command in a later message, the publish skill owns validation, packaging, public-library PR creation or update, and the `--from-polish` post-publish retro offer.\n\n(When `STANDALONE_MODE` is false this whole section is unreachable — the Publish Offer guard at the top of this section returns early — so no extra check is needed here.)\n\n### If \"Polish again\"\n\nRe-run Phase 1 → Phase 2 → Phase 3 with the same CLI. Maximum 2 additional polish passes (3 total including the first).\n\n### If \"Done for now\"\n\nEnd normally.\n\n## Rules\n\n- Fix everything. Do not ask for approval before fixing — polish is autonomous.\n- Report results honestly. Show what improved and what didn't.\n- Do not add new features. Polish fixes quality issues, not feature gaps.\n- Do not re-run research or generation. Polish works with the CLI as-is.\n- Do not modify the printing-press generator. That's `\u002Fprinting-press-retro`.\n- Do not modify any files outside `$CLI_DIR`.\n- If polish adds or renames a Cobra command, the MCP surface updates automatically through the generated `internal\u002Fmcp\u002Fcobratree` runtime mirror. Update `novel_features` only when README\u002FSKILL highlights or registry display should change; use `cmd.Annotations[\"mcp:hidden\"] = \"true\"` for debug-only commands.\n- Maximum 1 fix-and-rediagnose pass per polish invocation. The \"Polish again\" path runs additional invocations (max 3 total).\n- Prefer mechanical fixes over creative decisions. When a creative decision is needed (like the CLI description), use the research brief from manuscripts if available.\n","# \u002Fprinting-press-polish\n\nPolish a generated CLI so it passes verification and is ready to publish.\n\nThe retro improves the Printing Press. Polish improves the generated CLI. This skill runs in a forked context (`context: fork`) so its diagnostic and fix loop doesn't pollute the caller — the diagnostic spam, fix iterations, and re-diagnose noise stay scoped to the polish session, and the caller receives a clean summary.\n\n```bash\n\u002Fprinting-press-polish redfin\n\u002Fprinting-press-polish redfin-pp-cli\n\u002Fprinting-press-polish \"$PRESS_LIBRARY\u002Fredfin\"\n```\n\n## When to run\n\nAfter any `\u002Fprinting-press` generation, especially when:\n- The shipcheck verdict is `ship-with-gaps`\n- The verify pass rate is below 80%\n- The scorecard is below 85\n- You want the CLI publish-ready in one pass\n\nCan also be run standalone on any CLI in `$PRESS_LIBRARY\u002F`.\n\n## Setup\n\n```bash\n# min-binary-version: 4.0.0\n\nPRESS_HOME=\"${PRINTING_PRESS_HOME:-$HOME\u002Fprinting-press}\"\nPRESS_LIBRARY=\"$PRESS_HOME\u002Flibrary\"\n\n_pp_check_disk_space() {\n  _pp_disk_warn_kb=\"${PRINTING_PRESS_DISK_WARN_KB:-3145728}\"\n  _pp_disk_fail_kb=\"${PRINTING_PRESS_DISK_FAIL_KB:-524288}\"\n  case \"$_pp_disk_warn_kb$_pp_disk_fail_kb\" in\n    \"\"|*[!0-9]*) return 0 ;;\n  esac\n\n  _pp_disk_path=\"$PRESS_HOME\"\n  while [ ! -e \"$_pp_disk_path\" ] && [ \"$_pp_disk_path\" != \"\u002F\" ]; do\n    _pp_disk_path=\"$(dirname \"$_pp_disk_path\")\"\n  done\n\n  _pp_disk_avail_kb=\"$(df -Pk \"$_pp_disk_path\" 2>\u002Fdev\u002Fnull | awk 'BEGIN {\n    if ((getline header) \u003C= 0 || (getline record) \u003C= 0) exit\n    field_count = split(record, fields)\n    if (field_count >= 4) print fields[4]\n  }')\"\n  case \"$_pp_disk_avail_kb\" in\n    \"\"|*[!0-9]*) return 0 ;;\n  esac\n\n  if [ \"$_pp_disk_avail_kb\" -lt \"$_pp_disk_fail_kb\" ]; then\n    echo \"\"\n    echo \"[setup-error] Critically low disk space on the Printing Press workspace volume.\"\n    echo \"PRESS_DISK_PATH=$_pp_disk_path\"\n    echo \"PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb\"\n    echo \"PRESS_DISK_FAIL_KB=$_pp_disk_fail_kb\"\n    echo \"Free disk space or set PRINTING_PRESS_HOME to a volume with more room, then re-run this skill.\"\n    echo \"\"\n    return 1\n  fi\n\n  if [ \"$_pp_disk_avail_kb\" -lt \"$_pp_disk_warn_kb\" ]; then\n    echo \"\"\n    echo \"[low-disk] Printing Press workspace volume is low on free space.\"\n    echo \"PRESS_DISK_PATH=$_pp_disk_path\"\n    echo \"PRESS_DISK_AVAIL_KB=$_pp_disk_avail_kb\"\n    echo \"PRESS_DISK_WARN_KB=$_pp_disk_warn_kb\"\n    echo \"This flow may need several GiB for generated files, Go build cache, module downloads, or repository clones.\"\n    echo \"\"\n  fi\n}\n_pp_check_disk_space || { return 1 2>\u002Fdev\u002Fnull || exit 1; }\n\n# Mid-pipeline callers may pass printing_press_bin: \u003Cabs-path> in the args\n# bundle. Prefer it so forked polish runs keep using the parent skill's\n# preflight-selected binary instead of re-resolving through PATH.\nPRINTING_PRESS_BIN=\"${PRINTING_PRESS_BIN:-}\"\nif [ -z \"$PRINTING_PRESS_BIN\" ] && [ -n \"${ARGUMENTS:-}\" ]; then\n  PRINTING_PRESS_BIN=\"$(printf '%s\\n' \"$ARGUMENTS\" | sed -nE 's\u002F^[[:space:]]*printing_press_bin:[[:space:]]*(.+)$\u002F\\1\u002Fp' | head -1)\"\nfi\nif [ -z \"$PRINTING_PRESS_BIN\" ]; then\n  PRINTING_PRESS_BIN=\"$(command -v cli-printing-press 2>\u002Fdev\u002Fnull || true)\"\nfi\n\nif [ -z \"$PRINTING_PRESS_BIN\" ]; then\n  echo \"cli-printing-press binary not found.\"\n  echo \"Install with:  go install github.com\u002Fmvanhorn\u002Fcli-printing-press\u002Fv4\u002Fcmd\u002Fcli-printing-press@latest\"\n  return 1 2>\u002Fdev\u002Fnull || exit 1\nfi\nif ! command -v go >\u002Fdev\u002Fnull 2>&1; then\n  echo \"\"\n  echo \"[setup-error] Go toolchain not found.\"\n  echo \"\"\n  echo \"This Printing Press flow runs Go-based build or validation commands.\"\n  echo \"Install Go 1.26.11 or newer from https:\u002F\u002Fgo.dev\u002Fdl\u002F, then verify with:\"\n  echo \"  go version\"\n  echo \"Then re-run this skill.\"\n  echo \"\"\n  return 1 2>\u002Fdev\u002Fnull || exit 1\nfi\necho \"PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN\"\n\n_pp_semver_lt() {\n  if [ -z \"${PP_SEMVER_A:-}\" ] || [ -z \"${PP_SEMVER_B:-}\" ]; then\n    echo \"[setup-error] semver comparison inputs are missing.\" >&2\n    return 2\n  fi\n  awk -v a=\"${PP_SEMVER_A:-}\" -v b=\"${PP_SEMVER_B:-}\" 'BEGIN {\n    split(a, x, \".\"); split(b, y, \".\")\n    for (i = 1; i \u003C= 3; i++) {\n      if ((x[i] + 0) \u003C (y[i] + 0)) exit 0\n      if ((x[i] + 0) > (y[i] + 0)) exit 1\n    }\n    exit 1\n  }'\n}\n\n_pp_go_version_norm() {\n  printf '%s\\n' \"${PP_GO_VERSION_INPUT:-}\" | sed -nE 's\u002F.*go([0-9]+)\\.([0-9]+)(\\.([0-9]+))?.*\u002F\\1.\\2.\\4\u002Fp' | sed -E 's\u002F\\.$\u002F.0\u002F'\n}\n\n_pp_check_go_currency() {\n  _pp_go_installed=\"$(PP_GO_VERSION_INPUT=\"$(go env GOVERSION 2>\u002Fdev\u002Fnull)\" _pp_go_version_norm)\"\n  _pp_go_required=\"$(PP_GO_VERSION_INPUT=\"$(go version \"$PRINTING_PRESS_BIN\" 2>\u002Fdev\u002Fnull)\" _pp_go_version_norm)\"\n  PP_SEMVER_A=\"$_pp_go_installed\"\n  PP_SEMVER_B=\"$_pp_go_required\"\n  if [ -z \"$_pp_go_installed\" ] || [ -z \"$_pp_go_required\" ] || ! _pp_semver_lt; then\n    return 0\n  fi\n\n  echo \"\"\n  if [ \"${GOTOOLCHAIN:-auto}\" = \"local\" ]; then\n    echo \"[setup-error] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed).\"\n    echo \"GOTOOLCHAIN=local disables automatic toolchain downloads, so later Go quality gates would fail.\"\n    echo \"Install Go $_pp_go_required or newer from https:\u002F\u002Fgo.dev\u002Fdl\u002F, or unset GOTOOLCHAIN.\"\n    echo \"\"\n    return 1\n  fi\n\n  echo \"[go-toolchain-old] Go $_pp_go_required or newer is required by this cli-printing-press binary (installed: $_pp_go_installed).\"\n  echo \"PRESS_GO_INSTALLED=$_pp_go_installed\"\n  echo \"PRESS_GO_REQUIRED=$_pp_go_required\"\n  echo \"Default GOTOOLCHAIN behavior may download the required toolchain during Go commands.\"\n  echo \"\"\n  return 0\n}\n_pp_check_go_currency || { return 1 2>\u002Fdev\u002Fnull || exit 1; }\n```\n\nAfter setup, capture `PRINTING_PRESS_BIN=\u003Cabs-path>` and use that absolute path for every `cli-printing-press ...` invocation in this skill. If setup emitted `[go-toolchain-old]` or `[low-disk]`, surface the advisory to the user and continue unless setup also emitted `[setup-error]`. `[go-toolchain-old]` means later Go commands may download the required toolchain or fail when downloads are blocked; `[low-disk]` means this run may need several GiB for generated files, Go build cache, module downloads, or repository clones.\n\nCheck binary version compatibility by reading the `min-binary-version` field from this skill's YAML frontmatter, running `\"$PRINTING_PRESS_BIN\" version --json`, and parsing the version from the output. Compare it to `min-binary-version` using semver rules. If the installed binary is older than the minimum, stop immediately and tell the user: \"cli-printing-press binary vX.Y.Z is older than the minimum required vA.B.C. Run `go install github.com\u002Fmvanhorn\u002Fcli-printing-press\u002Fv4\u002Fcmd\u002Fcli-printing-press@latest` to update.\"\n\n### Public-library hint\n\nIf the user's request includes phrasing like \"polish notion **in the\npublic library**\", \"polish **from the public library**\", or \"polish the\npublished cal-com\" — and the named CLI is **not** in\n`$PRESS_LIBRARY\u002F\u003Cslug>\u002F` — they're asking to polish a CLI that lives\nupstream but not locally. Polish runs against the internal library, so\nthe right move is to import first.\n\nSuggest: `\u002Fprinting-press-import \u003Cslug>` to bring it in, then re-run\npolish. Don't try to polish a CLI that isn't in the internal library.\n\nIf the named CLI **is** already in `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`, the\n\"public library\" phrasing is informational — just proceed with polish\nand let the divergence check (below) handle any drift.\n\n### Resolve CLI\n\nThe argument string can contain a `--standalone` flag plus one positional value\n(a slug, binary name, or path). In standalone slash-command mode, it may also\ncontain a free-text scope after the optional positional value, such as\n`\u002Fprinting-press-polish sculptok review the open PR comments and fix them`.\nThat trailing natural-language text is the user's own trusted user scope. Carry\nit forward into the polish plan and result block; do not classify it as\ninjection or tampering.\n\nIt can also contain a Phase 3 gate bundle and a `printing_press_bin:\n\u003Cabs-path>` line on following lines when invoked by the main printing-press\nskill. The flag may appear before or after the positional value; it is the only\nflag this skill consumes from `args`. Strip it before path resolution.\n\nWhen `args` is multi-line, treat the first non-empty line as the positional\nvalue\u002Fscope line and parse the remaining lines as the optional Phase 3 gate\nbundle. Do not include the bundle text in path resolution.\n\nParse caller modes differently:\n\n- **Standalone slash command (`STANDALONE_MODE=true`).** After stripping\n  `--standalone`, try to resolve the first shell word as a slug, binary name, or\n  path. If it resolves, use it as the positional value and store the remaining\n  words as `USER_SCOPE`. If it does not resolve, treat the whole line as\n  free-text scope; this branch asks which CLI to polish and retains that scope\n  for the chosen CLI. If there is no trailing text after a resolved positional\n  value, run the normal generic polish pass.\n- **Mid-pipeline Skill-tool call.** Keep the strict grammar: one path-like\n  positional value on the first line plus the optional structured bundle on\n  later lines. Unexpected free text in this machine-generated path is not a\n  user scope and should still be rejected or clarified rather than folded into\n  the run.\n\nThe positional value can be:\n- A short name: `redfin` (looks up `$PRESS_LIBRARY\u002Fredfin`)\n- A full name: `redfin-pp-cli` (strips suffix, looks up `$PRESS_LIBRARY\u002Fredfin`)\n- A path: `$PRESS_LIBRARY\u002Fredfin` (used directly)\n\nResolution order for the positional value:\n1. If it is an absolute or `~`-prefixed path and exists, use it\n2. Try `$PRESS_LIBRARY\u002F\u003Carg>` (exact match — works for slug like `redfin`)\n3. If it has `-pp-cli` suffix, strip it and try `$PRESS_LIBRARY\u002F\u003Cslug>` (e.g., `redfin-pp-cli` → `redfin`)\n4. Fuzzy search: `ls $PRESS_LIBRARY\u002F | grep -i \u003Carg>` for close matches\n\n**Caller scenarios and the `--standalone` flag.** Polish has two callers; they invoke it through different mechanisms, and the Publish Offer at the end of this skill fires only when `STANDALONE_MODE` is true. **Determine `STANDALONE_MODE` from the caller mode and the flag, not from the resolved path.**\n\n- **Standalone (user-invoked, `\u002Fprinting-press-polish redfin`).** Invoked via the slash command. Treat as `STANDALONE_MODE=true` unconditionally — the slash-command form is the publish-intent surface, even when the user omits the flag. The arg is a slug or binary name; resolution lands on `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`. This is the published copy and the right target.\n- **Mid-pipeline (main printing-press skill Phase 5.5, hold-path \"Polish to retry\").** Invoked via the Skill tool with `args: \"$CLI_WORK_DIR\"`. The arg is an absolute path to `~\u002Fprinting-press\u002F.runstate\u002F...\u002Fruns\u002F...\u002Fworking\u002F\u003Capi>-pp-cli\u002F`; resolution must hit rule 1. `STANDALONE_MODE=false` by default — main SKILL owns the publish flow on this path, so polish defers. **Do not paraphrase the arg to the slug** — Phase 5.5 fires before the working CLI is promoted, so `$PRESS_LIBRARY\u002F\u003Cslug>\u002F` either doesn't exist or holds the *prior* run's stale CLI.\n- **Skill-tool standalone override.** A non-slash caller that genuinely wants polish to publish must opt in explicitly by including `--standalone` in `args` (e.g., `args: \"--standalone $PRESS_LIBRARY\u002Fredfin\"`). Without that token, polish never publishes from a Skill-tool invocation — even if the resolved path happens to live under `$PRESS_LIBRARY\u002F`. The flag is the contract; the path is not.\n\nThis caller-mode-driven gate replaces the older path-substring heuristic (`*.runstate\u002F*`). The heuristic broke when the main SKILL's Phase 5.5\u002F5.6 ordering inverted, or when polish was invoked from a non-`.runstate` scratch layout: polish would see a `$PRESS_LIBRARY\u002F\u003Cslug>\u002F` path, conclude \"standalone,\" and fire its Publish Offer (fork, global git config, public PR) inside a mid-pipeline run. The flag is unambiguous and the safer default is no-publish.\n\n### Phase 3 gate bundle\n\nMid-pipeline callers pass these fields after the CLI path in `args`:\n\n```yaml\nphase3_transcendence_rows_planned: \u003Cplanned>\nphase3_transcendence_rows_built: \u003Cbuilt>\nphase3_transcendence_rows_missing:\n  - \u003Cmanifest row name or command>\nprior_sub60_reprint: \u003Ctrue|false>\npartial_transcendence_override: \u003Cnone or build-log note path>\n```\n\nParse the bundle before diagnostics and keep the values available for ship\nlogic. Missing bundle fields mean \"no forced Phase 3 hold\"; they do not block\nstandalone polish. If `prior_sub60_reprint: true`,\n`phase3_transcendence_rows_missing` contains any row, and\n`partial_transcendence_override` is empty or `none`, polish must emit\n`ship_recommendation: hold` even if the local diagnostics are otherwise clean.\nAdd the missing rows to `remaining_issues` so the parent skill can show the\nspecific gate that blocked promotion.\n\nThe lock-status check in the next code block is the safety net for the mid-pipeline scenario: if a build lock is held for this CLI (under either name form), polish refuses to run. `cli-printing-press lock` normalizes slug ↔ binary-name internally, so the check works regardless of which form the basename produces.\n\nIf no match or multiple matches, present via `AskUserQuestion`. Show at most 4\nmatches sorted by modification time (most recent first) with human-friendly\nrelative timestamps (e.g., \"generated 2 hours ago\").\n\n```bash\nCLI_DIR=\"\u003Cresolved path>\"\nCLI_NAME=\"$(basename \"$CLI_DIR\")\"\nSTANDALONE_MODE=\"\u003Ctrue|false>\"  # true iff slash-command invocation or --standalone in args; default false for Skill-tool invocations\n\n# Check if there's an active build lock — polish edits would be overwritten\n# when the running build promotes to library.\n_lock_json=$(\"$PRINTING_PRESS_BIN\" lock status --cli \"$CLI_NAME\" --json 2>\u002Fdev\u002Fnull)\nif echo \"$_lock_json\" | grep -q '\"held\".*true'; then\n  if echo \"$_lock_json\" | grep -q '\"stale\".*true'; then\n    echo \"Warning: stale lock exists for $CLI_NAME (build may have crashed).\"\n    echo \"Proceeding with polish. Run '$PRINTING_PRESS_BIN lock release --cli $CLI_NAME' to clear.\"\n  else\n    echo \"An active build is in progress for $CLI_NAME.\"\n    echo \"Polish edits would be overwritten when the build promotes.\"\n    echo \"Wait for the build to finish, then run polish.\"\n    exit 1\n  fi\nfi\n\n# Verify it's a valid Go CLI\nif [ ! -f \"$CLI_DIR\u002Fgo.mod\" ]; then\n  echo \"Not a valid CLI directory: $CLI_DIR\"\n  exit 1\nfi\n\necho \"Polishing: $CLI_NAME\"\necho \"Location: $CLI_DIR\"\n```\n\n### Find spec and research dir\n\n```bash\nAPI_SLUG=\"${CLI_NAME%-pp-cli}\"\nSPEC_PATH=\"\"\nfor f in \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\"\u002F*\u002Fresearch\u002F*.yaml \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\"\u002F*\u002Fresearch\u002F*.json \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"\u002F*\u002Fresearch\u002F*.yaml \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"\u002F*\u002Fresearch\u002F*.json; do\n  if [ -f \"$f\" ]; then\n    SPEC_PATH=\"$f\"\n    break\n  fi\ndone\n\n# Build the spec flag once. Empty when no spec was found — diagnostic\n# commands accept a missing --spec and degrade gracefully.\nSPEC_FLAG=\"\"\nif [ -n \"$SPEC_PATH\" ]; then\n  SPEC_FLAG=\"--spec $SPEC_PATH\"\nfi\n\n# Locate the research dir. dogfood's --research-dir triggers\n# checkNovelFeatures, which writes novel_features_built back into\n# research.json AND syncs the verified list into .printing-press.json.\n# Without this flag, legacy CLIs whose manifest predates the\n# novel_features schema fail publish-validate's transcendence gate.\n#\n# Two layouts to handle, keyed on $CLI_DIR path structure (NOT on the\n# absence of a manuscripts entry — re-generating a previously-published\n# API leaves stale manuscript entries from prior runs that would point\n# scorecard at the wrong research.json):\n#  1. Mid-pipeline polish (invoked from the main printing-press flow\n#     before promote): $CLI_DIR is under $PRESS_RUNSTATE\u002F...\u002Fruns\u002F\u003Cid>\u002Fworking\u002F\u003Ccli>\n#     (i.e. the path contains `.runstate\u002F`), and research.json lives at\n#     $PRESS_RUNSTATE\u002F...\u002Fruns\u002F\u003Cid>\u002Fresearch.json — $CLI_DIR's grandparent.\n#  2. Post-promote (standalone polish): research.json lives at\n#     manuscripts\u002F\u003Capi>\u002F\u003Crun-id>\u002Fresearch.json.\nRESEARCH_DIR=\"\"\nMANIFEST_RUN_ID=\"\"\nif [ -f \"$CLI_DIR\u002F.printing-press.json\" ]; then\n  if command -v jq >\u002Fdev\u002Fnull 2>&1; then\n    MANIFEST_RUN_ID=\"$(jq -r '.run_id \u002F\u002F empty' \"$CLI_DIR\u002F.printing-press.json\" 2>\u002Fdev\u002Fnull || true)\"\n  fi\n  if [ -z \"$MANIFEST_RUN_ID\" ]; then\n    MANIFEST_RUN_ID=\"$(sed -nE 's\u002F.*\"run_id\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*\u002F\\1\u002Fp' \"$CLI_DIR\u002F.printing-press.json\" | head -1)\"\n  fi\nfi\ncase \"$CLI_DIR\" in\n  *.runstate\u002F*)\n    _grandparent=\"$(dirname \"$(dirname \"$CLI_DIR\")\")\"\n    if [ -f \"$_grandparent\u002Fresearch.json\" ]; then\n      RESEARCH_DIR=\"$_grandparent\"\n    fi\n    ;;\n  *)\n    if [ -n \"$MANIFEST_RUN_ID\" ]; then\n      for base in \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\" \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"; do\n        if [ -f \"$base\u002F$MANIFEST_RUN_ID\u002Fresearch.json\" ]; then\n          RESEARCH_DIR=\"$base\u002F$MANIFEST_RUN_ID\"\n          break\n        fi\n      done\n    fi\n    # Match publish package's fallback: API slug first, then CLI name, each\n    # using the lexicographically latest run id when the manifest has none.\n    if [ -z \"$RESEARCH_DIR\" ]; then\n      for base in \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\" \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"; do\n        if [ -d \"$base\" ]; then\n          _latest=\"$(find \"$base\" -mindepth 2 -maxdepth 2 -name research.json -type f 2>\u002Fdev\u002Fnull | sort | tail -1)\"\n          if [ -n \"$_latest\" ]; then\n            RESEARCH_DIR=\"$(dirname \"$_latest\")\"\n            break\n          fi\n        fi\n      done\n    fi\n    ;;\nesac\n\n# Use a bash array so the flag survives paths with spaces (e.g. when\n# $HOME or $PRESS_RUNSTATE resolves through a path containing spaces).\nRESEARCH_ARGS=()\nif [ -n \"$RESEARCH_DIR\" ]; then\n  RESEARCH_ARGS=(--research-dir \"$RESEARCH_DIR\")\nfi\n\n# pii-audit runs against the CLI dir, but publish package later copies the\n# same run archive under .manuscripts\u002F\u003Crun-id> before enforcing the PII gate.\n# Pass the run dir here so polish sees the narrative manuscript files with\n# the same relative paths publish will scan.\nPII_ARGS=()\nif [ -n \"$RESEARCH_DIR\" ]; then\n  PII_ARGS=(--manuscripts-dir \"$RESEARCH_DIR\")\nfi\n```\n\n### Divergence check\n\n**Stop and run this step before Phase 1. Do not skip it. Do not proceed to diagnostics until you have completed the check and resolved any divergence.**\n\nThe internal copy at `$CLI_DIR` can drift from the public library (`mvanhorn\u002Fprinting-press-library`) copy if anyone edited the public repo directly after this CLI was last published. Polishing a stale internal copy and re-publishing later silently overwrites those public-only fixes — a real failure mode that shipped CLIs hit.\n\n**You must:**\n\n1. **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\u002Fprinting-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.\n2. **Locate this CLI inside the clone.** `find \u003Cclone>\u002Flibrary -type d -name \"\u003Capi>-pp-cli\"` or equivalent.\n3. **Run `diff -r \u003Cpublic-cli-dir> $CLI_DIR`** with these exclusions, all of which are expected to diverge after publish:\n   - `.printing-press-tools-polish.json` (local ledger, not published)\n   - `.printing-press-pii-polish.json` (local ledger, not published)\n   - `go.mod` and `go.sum` — publish rewrites the module path from `\u003Capi>-pp-cli` to `github.com\u002Fmvanhorn\u002Fprinting-press-library\u002Flibrary\u002F\u003Ccategory>\u002F\u003Capi>`\n   - 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.\n\n   Concretely: `diff -r --exclude=go.mod --exclude=go.sum --exclude=.printing-press-tools-polish.json --exclude=.printing-press-pii-polish.json \u003Cpublic-cli-dir> $CLI_DIR`.\n\n   Don't pass `--exclude='\u003Capi>-pp-cli'` or `--exclude='\u003Capi>-pp-mcp'` — those names match both the root-level binary files **and** the `cmd\u002F\u003Capi>-pp-cli\u002F` and `cmd\u002F\u003Capi>-pp-mcp\u002F` source directories. Excluding by binary name silently skips the entire `cmd\u002F` subtree, hiding real divergence in `main.go`. The \"Only in $CLI_DIR: \u003Capi>-pp-cli\" line for the built binary is one row of expected output, not noise worth filtering at the cost of completeness.\n4. **Surface the result** before continuing.\n\nOutcomes:\n\n- **No clone found** → user doesn't have public locally. State this explicitly (\"public library not found locally; proceeding on internal as canonical\") and continue.\n- **Clone found but doesn't contain this CLI** → never published or under a different name. State this and continue.\n- **Found and diff is empty** → in sync. State this and continue.\n- **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.\n\nBefore showing the sync prompt, check whether internal has files modified after its `.printing-press.json` timestamp (the user has been polishing locally without publishing). If yes, hedge the prompt explicitly: syncing will overwrite their pending local work. Let them decide whether to keep their local edits or pull public's.\n\nAfter sync (or explicit skip), the rest of polish operates on `$CLI_DIR` as canonical. The eventual `\u002Fprinting-press-publish` step pushes internal back to public; no second divergence check is needed there.\n\n**The check has run only when one of the four outcomes above is explicitly stated in your response.** Silent omission counts as not having run it.\n\n## Phase 1: Baseline diagnostics\n\n```bash\ncd \"$CLI_DIR\"\n\n# Build\ngo build -o \"$CLI_NAME\" .\u002Fcmd\u002F\"$CLI_NAME\" 2>&1\n\n# Diagnostics. SPEC_FLAG and RESEARCH_ARGS are set in the \"Find spec\n# and research dir\" step above. RESEARCH_ARGS enables dogfood to\n# verify novel features and sync them into .printing-press.json\n# (required for publish-validate's transcendence gate).\n\"$PRINTING_PRESS_BIN\" dogfood --dir \"$CLI_DIR\" $SPEC_FLAG \"${RESEARCH_ARGS[@]}\" 2>&1\n\"$PRINTING_PRESS_BIN\" verify --dir \"$CLI_DIR\" $SPEC_FLAG --json 2>&1\n\"$PRINTING_PRESS_BIN\" workflow-verify --dir \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-workflow-verify.json 2>&1 || true\n\"$PRINTING_PRESS_BIN\" verify-skill --dir \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-verify-skill.json 2>&1 || true\n# publish-validate is a publish-readiness gate, not a CLI-readiness gate.\n# Mid-pipeline polish runs before the main SKILL's promote step and before\n# the publish skill packages tools-manifest.json, so its prerequisites\n# (manifest.printer from git config github.user, packaged tools manifest,\n# phase5 acceptance proof relocated under $CLI_DIR\u002F.manuscripts\u002F\u003Crun>\u002Fproofs\u002F)\n# are not yet satisfied. Running publish-validate here would cascade\n# parent-pipeline-owned failures into the polish ship_recommendation,\n# which the main SKILL's Phase 5.5 verdict-override then turns into a\n# CLI-level hold. Only run publish-validate when polish is the publish\n# entry point (slash-command invocation or explicit --standalone).\nif [ \"$STANDALONE_MODE\" = \"true\" ]; then\n  \"$PRINTING_PRESS_BIN\" publish validate --dir \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-publish-validate.json 2>&1 || true\nfi\n# --live-check samples novel-feature outputs and populates\n# live_check.features[].warnings (Wave B entity detection) — required for\n# the \"Output entity warnings\" row below to have data to read.\n# RESEARCH_ARGS points scorecard at the run's research.json when the\n# CLI lives under $PRESS_RUNSTATE\u002Fruns\u002F\u003Cid>\u002Fworking\u002F\u003Ccli> (mid-pipeline\n# polish). Without it, scorecard looks adjacent to the binary, doesn't\n# find research.json, and reports `unable: true`.\n# A bare scorecard and scorecard --write-manifest report the same total.\n# A verify summary already in .printing-press.json is included either way;\n# a Calibration line means that summary raised the total. --spec changes\n# the domain denominator, which human output prints beside the total —\n# compare runs that passed the same spec.\n\"$PRINTING_PRESS_BIN\" scorecard --dir \"$CLI_DIR\" $SPEC_FLAG \"${RESEARCH_ARGS[@]}\" --live-check --json > \u002Ftmp\u002Fpolish-scorecard.json 2>&1 || true\n\"$PRINTING_PRESS_BIN\" scorecard --dir \"$CLI_DIR\" $SPEC_FLAG 2>&1\n\"$PRINTING_PRESS_BIN\" tools-audit \"$CLI_DIR\" --json > \u002Ftmp\u002Fpolish-tools-audit-before.json 2>&1 || true\n\"$PRINTING_PRESS_BIN\" pii-audit \"$CLI_DIR\" \"${PII_ARGS[@]}\" --json > \u002Ftmp\u002Fpolish-pii-audit-before.json 2>&1 || true\ngo vet .\u002F... 2>&1\n# Released gosec bundles a golang.org\u002Fx\u002Ftools that cannot read newer Go export\n# data, so on a newer toolchain it silently skips packages. polish_gosec uses an\n# installed gosec only when it loads every package; otherwise it builds the\n# pinned gosec against a current x\u002Ftools in a private temp dir. Each block runs\n# in its own shell, so the after-fix scan repeats this definition verbatim.\npolish_gosec() {\n  local out=\"$*\" built\n  if command -v gosec >\u002Fdev\u002Fnull 2>&1; then\n    gosec -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n    [ \"$(jq '(.\"Golang errors\" \u002F\u002F {}) | length' \"$out\" 2>\u002Fdev\u002Fnull || echo 1)\" = 0 ] && return 0\n    echo \"polish_gosec: installed gosec could not load every package; building the pinned fallback\" >&2\n  fi\n  built=$(mktemp -d) || return 1\n  if ! (cd \"$built\" && export GOWORK=off && go mod init polish-gosec && go get github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec@v2.29.0 golang.org\u002Fx\u002Ftools@v0.52.0 && go build -o gosec github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec) >\"$built\u002Fbuild.log\" 2>&1; then\n    echo \"polish_gosec: could not build the gosec fallback:\" >&2\n    tail -n 20 \"$built\u002Fbuild.log\" >&2\n    rm -rf \"$built\"\n    return 1\n  fi\n  \"$built\u002Fgosec\" -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n  rm -rf \"$built\"\n}\npolish_gosec \u002Ftmp\u002Fpolish-gosec-before.json\n```\n\nverify-skill and workflow-verify run alongside dogfood\u002Fverify\u002Fscorecard so polish catches the same class of failures the public-library CI catches. `publish-validate` runs only when `STANDALONE_MODE=true` (slash-command or `--standalone` Skill-tool invocation). The publish-validate leg is a hard ship-gate **for standalone polish**: in that mode polish cannot recommend `ship` or `ship-with-gaps` while `\"$PRINTING_PRESS_BIN\" publish validate` reports `passed: false`. Mid-pipeline polish (`STANDALONE_MODE=false`) skips publish-validate entirely — its prerequisites (manifest.printer from `git config github.user`, packaged `tools-manifest.json`, phase5 acceptance proof relocated under `$CLI_DIR\u002F.manuscripts\u002F\u003Crun>\u002Fproofs\u002F`) are parent-pipeline-owned and not yet satisfied at this point; the main SKILL's Phase 6 publish flow gates on publish-validate at the correct time. See \"Ship logic\" below for how this affects ship_recommendation.\n\n**Live matrix qualifier.** After each `scorecard --live-check --json` run, read `\u002Ftmp\u002Fpolish-scorecard.json` and record whether `live_check` actually exercised live samples. Treat it as `exercised` only when `live_check.unable` is false and at least one feature was evaluated (`passed + failed > 0`, or equivalent feature statuses). Treat `live_check.unable: true`, no `live_check`, no evaluated features, or missing credentials\u002Ftoken as `not_exercised`. A clean mock dogfood\u002Fverify run is still useful, but it is **not** a live matrix pass.\n\n`gosec` runs as the off-the-shelf security static-analysis leg for hand-written Go. Prefer an installed `gosec` binary when present; `polish_gosec` (defined verbatim in both the baseline and after-fix blocks) falls back to building the pinned `github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec@v2.29.0` against `golang.org\u002Fx\u002Ftools@v0.52.0` when no binary is installed or the installed one cannot load every package, so a clean machine on a current Go toolchain still gets a full, reproducible check without a separate setup step. Read `\u002Ftmp\u002Fpolish-gosec-before.json` for the baseline finding count and issue details. If the command fails before writing JSON (including a fallback build failure, which `polish_gosec` reports on stderr with a non-zero return), or the JSON still has a non-empty `\"Golang errors\"` map (packages gosec could not type-check, so their findings are missing), treat the scan as a polish failure: add it to `remaining_issues`, set `ship_recommendation: hold`, and include the stderr or error summary so the next run can distinguish network\u002Ftooling failure from CLI defects. Prioritize findings in hand-authored files: whole files under `internal\u002Fcli\u002F`, `internal\u002Fsyncer\u002F`, and `internal\u002Fstore\u002F` whose first 20 lines lack the `Generated by CLI Printing Press` header are polish-owned novel-feature code. Findings in generator-emitted files are Printing Press retro candidates unless they can be fixed durably by changing the spec and regenerating; do not hand-edit generated files just to silence gosec.\n\n**If Phase 1 baseline reveals the underlying CLI needs re-discovery** — broken HTML\u002FSSR extraction, sparse capture (fewer than 5 unique endpoints in the source manuscript), wrong endpoint shapes, missing GraphQL operation hashes, or any signal that the CLI was generated from incomplete capture — polish does not normally do browser capture itself. When re-discovery is required, use the capture backends the runtime already exposes (Claude chrome-MCP `mcp__claude-in-chrome__*` and computer-use `mcp__computer-use__*`) rather than inventing a new capture flow. Re-discovery from polish is rare but real.\n\nParse findings into categories:\n\n| Category | Source | What to look for |\n|----------|--------|------------------|\n| Verify failures | verify --json | Commands with score \u003C 3 |\n| SKILL static-check failures | verify-skill --json | Any `findings[]` with `severity=error` (flag-names, flag-commands, positional-args, unknown-command, canonical-sections). Hard ship-gate: ship cannot fire while these exist. |\n| Workflow gaps | workflow-verify --json | Verdict `workflow-fail`. Soft gate: surface in `remaining_issues` and downgrade to `hold` when the workflow is the CLI's primary value. |\n| Publish validation failures | publish validate --json | `passed: false`. **Standalone polish only** (runs only when `STANDALONE_MODE=true`); skipped in mid-pipeline polish where publish prerequisites aren't yet satisfied. When it runs, it's a hard ship-gate: ship cannot fire while publish validate fails. If the only failing check is missing phase5 acceptance, report `phase5 acceptance required` with the next-step command: authenticate, then run `\"$PRINTING_PRESS_BIN\" dogfood --dir \"$CLI_DIR\" $SPEC_FLAG --live --level quick --write-acceptance \u003Cproofs-dir>\u002Fphase5-acceptance.json`. Use the proofs directory from the validate error when present. |\n| Security static-analysis failures | gosec JSON | Any `Issues[]` entry, especially G201\u002FG202 SQL construction, G101 credential literals, or unsafe file\u002Fcommand execution. Hard ship-gate when the finding is in hand-authored novel-feature Go. |\n| Dead code | dogfood | Dead functions, dead flags |\n| Stale files | dogfood | Unregistered commands |\n| Description issues | dogfood | Boilerplate root Short |\n| README gaps | scorecard | README score \u003C 8 |\n| Example gaps | dogfood | Commands missing examples |\n| Go vet issues | go vet | Any output |\n| Output entity warnings | scorecard JSON | `live_check.features[].warnings` — raw HTML entities in human output |\n| Output plausibility | Phase 4.85 | Findings from the agentic output review |\n| MCP tool quality | tools-audit | Empty Short, thin Short, missing read-only annotations, thin MCP descriptions |\n| Customer PII | pii-audit | Card last-4, email, phone, ZIP+4, postal-address, and account-identifier shapes in high-risk files (manuscripts, fixtures, README) |\n\n**Environmental failures vs. CLI defects.** Some Phase 1 outputs surface failures that aren't real CLI bugs and should not block ship:\n\n- `scorecard --live-check` reporting `SQLITE_BUSY`, network timeouts, `401` from a mock or expired token, or HTTP errors that depend on the test workspace's permissions\u002Fstate — these are test-environment issues, not CLI defects.\n- `verify` mock-harness flakes on commands with binary output (e.g., `qr` returning a PNG that the substring matcher can't validate) or commands with optional positional args where dry-run output legitimately doesn't contain the verify probe string.\n- Learn-loop commands: the dogfood\u002Fverify matrix now covers the default-on learn surface (`teach`, `recall`, `learnings`, `playbook`). `teach` and `teach-playbook` intentionally exit 2 when invoked bare, declared via `pp:typed-exit-codes`, so `verify` scores that as pass while `dogfood --live` records the `happy_path` and `json_fidelity` checks as skips with reason `declared non-zero exit 2`; neither is a defect and neither is a reason to \"fix\" the exit code. A skipped happy path does not count toward phase5 live coverage, so a novel feature that only ever exits non-zero on its happy path is reported hollow rather than covered. `learnings stats` on a fresh print legitimately reports zeros and empty sections; that is an empty local store, not a defect.\n\nClassify these as environmental in `skipped_findings` with the specific reason; do not spend Phase 2 cycles trying to \"fix\" them. The polish skill's ship logic already excludes live-check failures from gating, but the agent should still annotate them so reviewers can see they were considered and dismissed deliberately.\n\n### Phase 4.85 — Agentic output review (Wave B)\n\nAfter the mechanical diagnostics above complete, invoke the `printing-press-output-review` sub-skill via the Skill tool. The sub-skill carries `context: fork` and owns the dispatch prompt, gate logic, and known blind spots — single source of truth shared with the main printing-press skill.\n\n```\nSkill(\n  skill: \"cli-printing-press:printing-press-output-review\",\n  args: \"$CLI_DIR\"\n)\n```\n\nParse the returned `---OUTPUT-REVIEW-RESULT---` block. `status: WARN` findings flow into the diagnostic categories above so Phase 2 fixes address both rule-based and plausibility issues. `status: SKIP` means the review did not run: record it as skipped, do not count it as a pass, and do not block on it.\n\nWave B gating applies: all findings are warnings, never blockers. Fix if obvious and cheap; document with a short comment if deferred.\n\nRecord baseline scores: scorecard total, verify pass rate, dogfood verdict, live matrix qualifier (`exercised` \u002F `not_exercised`), go vet issue count, gosec finding count, output-review finding count.\n\n## Phase 2: Fix\n\nFix in priority order. After each priority level, update the lock heartbeat:\n\n```bash\n\"$PRINTING_PRESS_BIN\" lock update --cli \"$CLI_NAME\" --phase polish 2>\u002Fdev\u002Fnull\n```\n\n### Runtime variant default checklist\n\nIf a polish fix adds or changes a runtime mode, data-source option, auth tier, transport, or other user-visible default, document this short checklist before selecting the default:\n\n- **User-visible default:** which behavior users get without extra flags or config.\n- **Compatibility risk:** whether existing commands, scripts, MCP tools, or stored config change behavior.\n- **Verification command:** the exact command that proves the default and the non-default escape hatch both work.\n\nKeep the checklist in the polish notes or result block. Skip it for ordinary bug fixes that do not change runtime variants or defaults.\n\n### Cross-cutting API-call instrumentation\n\nWhen polish builds a feature class that must observe every outbound API call,\nsuch as a quota ledger, request log, or audit trail, instrument the generated\nclient middleware in `internal\u002Fclient\u002Fclient.go` instead of individual command\nhandlers. Prefer a shared pre-dispatch hook when one exists; otherwise cover\nboth `do()` and `doRead()`. The `do()` path handles standard endpoint mirrors,\nsync iterations, and novel features that use the generated client, while\n`doRead()` handles read-only operations that ride POST-like transports, such as\nGraphQL queries, JSON-RPC reads, and POST-based searches marked\n`mcp:read-only`.\nPer-command hooks under-count because they only see the commands polish touched.\n\n### Novel-feature data routing\n\nWhen polish adds or fixes a novel command that reads API response data into the\nlocal store, route data through the generated typed schemas instead of writing\nraw response JSON directly into tables:\n\n1. Read `internal\u002Ftypes\u002F\u003Cresource>.go` and `internal\u002Fstore\u002F\u003Cresource>.go` for the\n   resource being cached. Use the typed insert\u002Fupsert helpers those files emit\n   whenever they exist. If helpers are missing for a generated resource, create\n   them before writing any persistence code.\n2. Check the response shape against the spec schema and a real sample response\n   before deciding the insert mapping is correct.\n3. Decode the API response into the typed struct before persistence. Do not\n   build `INSERT INTO ...` statements from untyped `map[string]any` or raw\n   `json.RawMessage` values unless the table is a custom polish-owned table\n   declared in hand-authored migrations; see the raw SQL exception below.\n4. Verify the target table from the resource type, not from whichever query the\n   novel command happened to start with. A command that fetched `\u003Cchild>`\n   records must insert `\u003Cchild>` rows, not parent rows or a convenient adjacent\n   table.\n5. Normalize nested response identifiers before insert. If the API wraps the\n   scalar id inside an object that also contains metadata, extract the scalar id\n   field and store that value; never store the whole id object as a primary key\n   or foreign-key reference.\n\nRaw `database\u002Fsql` writes are acceptable only for custom polish-owned tables\ndeclared in hand-authored migrations. In that case, keep the table schema\nexplicit in `internal\u002Fstore\u002F`, document why the generated resource helper does\nnot apply, and still decode nested identifiers to scalars before persistence.\n\n### Priority 0: MCP surface migration (legacy CLIs)\n\nIf Phase 1's `dogfood` reported `MCP Surface: FAIL` with a parity mismatch, the CLI was generated before the runtime cobratree walker existed and is still on the static `internal\u002Fmcp\u002Ftools.go` surface. The fix is mechanical:\n\n```bash\n\"$PRINTING_PRESS_BIN\" mcp-sync \"$CLI_DIR\"\n```\n\nThat migrates the MCP surface to the runtime walker, regenerates `tools-manifest.json` and `internal\u002Fmcp\u002Ftools.go`, and applies any `mcp-descriptions.json` overrides. If it exits with `mcp-sync refused` and `reprint required`, stop this polish run and hand off to `\u002Fprinting-press-reprint`; the target CLI's generated client is too old for the current MCP handler, so rewriting `tools.go` alone would break its build. Include in the handoff that the reprint flow must run its normal dogfood gate against the regenerated CLI and confirm `MCP Surface: PASS` before shipping. Do not rerun dogfood against the stale `$CLI_DIR`. After a successful `mcp-sync`, re-run `dogfood` here; the parity gate should flip to PASS. Running `mcp-sync` on a compatible CLI already using the runtime walker is a no-op refresh.\n\nSkip this priority on CLIs where dogfood's MCP gate is already passing.\n\n### Priority 1: Security static-analysis failures\n\nFor each gosec finding in `\u002Ftmp\u002Fpolish-gosec-before.json`:\n\n1. Read the cited file and confirm whether it is hand-authored. A whole file\n   under `internal\u002Fcli\u002F`, `internal\u002Fsyncer\u002F`, or `internal\u002Fstore\u002F` whose first\n   20 lines lack `Generated by CLI Printing Press` is polish-owned novel-feature\n   code.\n2. If the finding is in hand-authored code, fix the root cause in source before\n   working lower-priority polish items. Examples: replace SQL string assembly\n   with parameterized queries, avoid shelling out with untrusted args, and move\n   literals that look like credentials into config\u002Fenv plumbing.\n3. If gosec flags generated code, do not hand-edit the generated file. Either\n   fix the upstream spec and regenerate, or add a `skipped_findings` entry that\n   names it as a generator retro candidate with the rule id and file path.\n4. If gosec reports a false positive, keep the suppression narrow and explain\n   it. Prefer a local `\u002F\u002F #nosec G### -- reason` only when the code is actually\n   safe and the reason is durable; otherwise fix the code.\n\nUnresolved gosec findings in hand-authored novel-feature Go are hard blockers:\nthey must appear in `remaining_issues`, force `ship_recommendation: hold`, and\nset `further_polish_recommended: yes` when the fix is plausibly mechanical.\n\n### Priority 2: Verify failures\n\nFor each command that fails verify dry-run or exec:\n\n1. Read the command file\n2. Find `Args: cobra.ExactArgs(N)` or similar constraint\n3. Remove the `Args:` field\n4. Add at the top of `RunE`:\n   ```go\n   if len(args) == 0 {\n       return cmd.Help()\n   }\n   ```\n5. For commands needing 2+ args, use `if len(args) \u003C 2`\n6. Check for dry-run nil-data crashes and add guards:\n   ```go\n   if flags.dryRun {\n       return nil\n   }\n   ```\n\n### Priority 3: Dead code\n\n1. For each dead function flagged by dogfood, grep all `.go` files to verify\n   it's truly unused (not just its definition matching itself)\n2. If truly unused: remove the function\n3. If used by another helper: leave it (false positive)\n4. After removal, remove unused imports\n5. Delete stale files (promoted commands not registered in root.go)\n\n### Priority 4: CLI description and metadata\n\n1. Read root command `Short` in `internal\u002Fcli\u002Froot.go`\n2. If it contains boilerplate (\"Reverse-engineered...\", raw API title), rewrite:\n   Pattern: `\"\u003CProduct> CLI with \u003Ccapability-1>, \u003Ccapability-2>, and \u003Ccapability-3>\"`\n3. Check commands for missing `Example` fields. Add realistic examples with\n   domain-specific values.\n\n### Priority 5: README\n\n**Cardinal rule: run `\u003Ccli> \u003Ccmd> --help` for EVERY command you put in the\nREADME.** Never guess flag names, argument formats, or valid values. If you\nwrite `--start-time` but the flag is `--start`, the README is wrong and\nusers will get errors on their first try.\n\n#### Source-of-truth files for rendered sections\n\nBefore editing README.md, SKILL.md, or `.printing-press.json`, identify whether\nthe section is rendered from a source file. Dogfood and regeneration overwrite\nthese rendered sections, so direct edits there are temporary and should be used\nonly to inspect the current output.\n\n| Rendered section or field | Source-of-truth file::field | Polish workflow |\n| --- | --- | --- |\n| README `## Unique Features` | `research.json::novel_features_built[]` | Edit the underlying `research.json` feature description\u002Fexample, then re-run dogfood with `--research-dir`. |\n| SKILL `## Unique Capabilities` | `research.json::novel_features_built[]` | Edit the underlying `research.json` feature description\u002Fexample, then re-run dogfood with `--research-dir`. |\n| `internal\u002Fmcp\u002Ftools.go` `command_mirror_capabilities` | `research.json::novel_features_built[]` | Dogfood reports a differing on-disk block and leaves it unmodified. Pass `--overwrite-command-mirror` only to replace it from `research.json`. |\n| README Quick Start | `research.json::narrative.quickstart[]` | Edit the command\u002Fcomment in `research.json`, then regenerate or re-run the dogfood\u002Frendering step. |\n| SKILL Recipes | `research.json::narrative.recipes[]` | Edit the recipe title, command, or explanation in `research.json`, then regenerate or re-run the dogfood\u002Frendering step. |\n| README\u002FSKILL Troubleshooting | `research.json::narrative.troubleshoots[]` | Edit the symptom\u002Ffix pair in `research.json`, then regenerate or re-run the dogfood\u002Frendering step. |\n| `.printing-press.json` `homepage` | `research.json::homepage` | Fix it in `research.json`, then correct or remove `homepage` in the working CLI's `.printing-press.json` before regenerating: an existing manifest value wins over research on regenerate. A value already in the library manifest also wins on promote and publish, so correct a published homepage in the library copy too. |\n| `.printing-press.json` `display_name`, `description`, `mcp_*` | `WriteManifestForGenerate`; for description\u002Fdisplay-name overrides, edit the spec (`info.title`, `info.x-display-name`, `info.description`) | Edit the spec or rerun the manifest writer. Do not hand-edit generated manifest metadata unless you are doing temporary diagnosis. |\n\nRecommended loop for these rendered sections: edit the source field, re-run\ndogfood with `--research-dir \"$RESEARCH_DIR\"` or regenerate the CLI as\nappropriate, then run a second pass to confirm the rendered README\u002FSKILL text\nstays fixed. If you edit README.md or SKILL.md directly in one of these\nsections, expect the next dogfood resync or regeneration to clobber the change.\n\nTo find the manuscript source:\n\n```bash\nPRESS_HOME=\"${PRINTING_PRESS_HOME:-$HOME\u002Fprinting-press}\"\nAPI_SLUG=\"${CLI_NAME%-pp-cli}\"\nRESEARCH_JSON=\"\"\nfor f in \"$PRESS_HOME\u002Fmanuscripts\u002F$CLI_NAME\"\u002F*\u002Fresearch.json \\\n         \"$PRESS_HOME\u002Fmanuscripts\u002F$API_SLUG\"\u002F*\u002Fresearch.json; do\n  if [ -f \"$f\" ]; then RESEARCH_JSON=\"$f\"; break; fi\ndone\n```\n\nIf `RESEARCH_JSON` exists and a rendered section has bad prose, examples, or\nflag references, fix the corresponding field in that file first. For novel\nfeatures, dogfood verifies `research.json::novel_features[]`, writes the\nsurviving set to `research.json::novel_features_built[]`, and syncs README\n`## Unique Features`, SKILL `## Unique Capabilities`, `.printing-press.json`\n`novel_features`, and root help Highlights from that verified set. A\ndiffering `command_mirror_capabilities` block in `internal\u002Fmcp\u002Ftools.go` is\nleft unmodified unless `--overwrite-command-mirror` is passed.\n\n#### Required sections (must be present and correct)\n\n1. **Title**: \"# \u003CProduct Name> CLI\" — use the product's real name with\n   correct casing\u002Fpunctuation (e.g., \"Cal.com\" not \"Cal Com\")\n2. **Subtitle**: one sentence describing what the CLI does for the user,\n   matching the root `Short` field. NOT a description of the API.\n3. **Install**: correct install command. Use the printing-press-library\n   repo URL, not a per-CLI repo that doesn't exist.\n4. **Authentication**: how to set `\u003CAPI>_API_KEY` env var, where to get\n   a key (link to the provider's settings page), self-hosted URL override\n   if supported. Read `config.go` to find all env vars.\n5. **Quick Start**: 3-5 commands someone will actually run first. Pick\n   commands that are both **most useful** (what you'd run daily) and\n   **show the CLI's value** (why install this over curl). Usually:\n   `doctor` → `sync` → transcendence command (`today`, `health`) →\n   `search`. Avoid raw list commands — they dump data without\n   demonstrating why the CLI exists.\n6. **Commands**: categorized table. Group by domain function (Scheduling,\n   Analytics, Account, Utilities), not by implementation structure.\n7. **Output Formats**: show `--json`, `--select`, `--csv`, `--compact`,\n   `--dry-run`, `--agent`. Use a real command, not a placeholder.\n8. **Agent Usage**: agent-native properties and exit codes.\n9. **Cookbook**: 8-15 recipes using **verified flag names** from `--help`.\n   Show the CLI's unique capabilities: transcendence commands, filters,\n   SQL queries, pipes. Include at least one mutation example.\n10. **Health Check**: show actual `doctor` output, not a placeholder.\n11. **Configuration**: list ALL env vars from config.go with descriptions.\n    Include config file path.\n12. **Troubleshooting**: common errors mapped to exit codes with fixes.\n\n#### Optional sections (add at your discretion)\n\n- **Rate Limits**: if the API has documented limits\n- **Self-Hosting**: if the CLI supports `--api-url` or `BASE_URL` override\n- **Pagination**: if the API has notable pagination behavior\n- **Sources & Inspiration**: credits to community projects (generated by\n  the machine, preserve if present)\n\n### Priority 5.5: SKILL static-check failures (verify-skill)\n\nRead `\u002Ftmp\u002Fpolish-verify-skill.json` for the full finding list. Each finding has a `check` (`flag-names`, `flag-commands`, `positional-args`, `unknown-command`, or `canonical-sections`), a `command` (the path the SKILL claimed), and a `detail` describing the mismatch. Common shapes and fixes:\n\n- **`flag-names`** — SKILL references `--foo` on a `\u003Ccli> ...` invocation but no command in `internal\u002Fcli\u002F*.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\u002Fprinting-press install \u003Capi> --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.\n- **`flag-commands`** — `--foo is declared elsewhere but not on \u003Ccmd>`. The flag exists somewhere but not on the command the SKILL invoked it on. Two fixes:\n  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.\n  2. If the SKILL example is genuinely wrong, fix the example to use a flag the command does declare.\n- **`positional-args`** — `got N positional args; Use: \"\u003Ccmd> \u003Carg>\" expects M-M`. The SKILL recipe passed N positional args but the command's `Use:` declares M required. Two fixes:\n  1. If the command also accepts the value via a `--flag`, change `Use: \"cmd \u003Carg>\"` to `Use: \"cmd [arg]\"` (square brackets = optional). Verify-skill correctly accepts `--flag`-only invocations against an optional positional.\n  2. If the SKILL example is missing a required positional, fix the example.\n- **`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\u002Fgenerator\u002Ftemplates\u002Fskill.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.\n\nWhen editing other parts of SKILL.md, Read the affected section first and Read it again after the Edit. `Edit` replaces a literal string; if the surrounding context has drifted, a single Edit can graft a second copy of a block onto the first instead of replacing it.\n\nAfter fixing, re-run `\"$PRINTING_PRESS_BIN\" verify-skill --dir \"$CLI_DIR\"` and confirm exit 0 before moving on.\n\n### Priority 6: Remaining dogfood issues\n\n- Path validity mismatches\n- Auth protocol mismatches\n- Example drift (examples referencing wrong commands)\n- Data pipeline integrity issues\n\n### Priority 7: MCP tool quality\n\n**Your goal now is to ensure every MCP tool exposed by this CLI carries agent-grade descriptions and correct read\u002Fwrite classifications.** Tool descriptions and classifications are how agents discover and decide whether to call a tool — thin descriptions and missing annotations directly degrade agent UX, and Phase 1's mechanical gates (verify, dogfood) do NOT catch this class of issue.\n\nStop and:\n\n1. Run `\"$PRINTING_PRESS_BIN\" tools-audit \"$CLI_DIR\" --json` to surface mechanical findings (empty Short, thin Short, missing `mcp:read-only` on read-shaped command names).\n2. You must read `references\u002Ftools-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.\n3. **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\u002Ftools-polish.md` \"Marking a finding accepted\" for the full contract.\n\nProceed to \"After all fixes\" only when the audit's summary line reads `no pending findings` with no `incomplete:` block — every gate (pre-decision fields, duplicate rationale, scorecard delta) passes.\n\n### Priority 8: Customer-PII gate\n\n**Your goal now is to clear the PII ledger so promote and publish gates pass.** The PII gate is the deterministic floor that prevents real customer values from reaching published library content. It catches card-last-4, email, US phone, ZIP+4, postal-address, and account-identifier shapes in high-risk files.\n\nStop and:\n\n1. Run `\"$PRINTING_PRESS_BIN\" pii-audit \"$CLI_DIR\" \"${PII_ARGS[@]}\"` to surface pending findings (or read `\u002Ftmp\u002Fpolish-pii-audit-before.json` from Phase 1's baseline). When `RESEARCH_DIR` exists, this includes that run's `research.json` and `research\u002F*.md` with `.manuscripts\u002F\u003Crun-id>\u002F...` paths so accepts carry forward into `publish package`.\n2. You must read `references\u002Fpii-polish.md` and follow its per-finding decision tree — fix real values in source with non-matching placeholders, or accept with the `category` + `evidence_context` pre-decision fields.\n3. **Accepting PII findings carries a strict contract.** Missing fields, 6+ accepts sharing a rationale, or wholesale-accepting ≥10 findings without source fixes all fail the gate. See `references\u002Fpii-polish.md` \"The accept contract\" and \"Forbidden accept patterns\" for the full rules.\n\nProceed to \"After all fixes\" only when `pii-audit` reads `no pending findings` with no `incomplete:` block.\n\n### After all fixes\n\n```bash\ngo build -o \"$CLI_NAME\" .\u002Fcmd\u002F\"$CLI_NAME\"\ngofmt -w .\n```\n\n## Phase 3: Re-diagnose\n\nRe-run the diagnostic sweep on the fixed CLI:\n\n```bash\n# RESEARCH_ARGS must travel with dogfood here too — without it,\n# checkNovelFeatures doesn't re-sync novel_features_built after Phase 2\n# edits, and publish-validate's transcendence gate reads stale state\n# from Phase 1's pass.\n\"$PRINTING_PRESS_BIN\" dogfood --dir \"$CLI_DIR\" $SPEC_FLAG \"${RESEARCH_ARGS[@]}\" 2>&1\n\"$PRINTING_PRESS_BIN\" verify --dir \"$CLI_DIR\" $SPEC_FLAG --json 2>&1\n\"$PRINTING_PRESS_BIN\" workflow-verify --dir \"$CLI_DIR\" --json 2>&1\n\"$PRINTING_PRESS_BIN\" verify-skill --dir \"$CLI_DIR\" --json 2>&1\nif [ \"$STANDALONE_MODE\" = \"true\" ]; then\n  \"$PRINTING_PRESS_BIN\" publish validate --dir \"$CLI_DIR\" --json 2>&1\nfi\n\"$PRINTING_PRESS_BIN\" scorecard --dir \"$CLI_DIR\" $SPEC_FLAG 2>&1\n\"$PRINTING_PRESS_BIN\" tools-audit \"$CLI_DIR\" 2>&1\n\"$PRINTING_PRESS_BIN\" pii-audit \"$CLI_DIR\" \"${PII_ARGS[@]}\" 2>&1\ngo vet .\u002F... 2>&1\npolish_gosec() {\n  local out=\"$*\" built\n  if command -v gosec >\u002Fdev\u002Fnull 2>&1; then\n    gosec -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n    [ \"$(jq '(.\"Golang errors\" \u002F\u002F {}) | length' \"$out\" 2>\u002Fdev\u002Fnull || echo 1)\" = 0 ] && return 0\n    echo \"polish_gosec: installed gosec could not load every package; building the pinned fallback\" >&2\n  fi\n  built=$(mktemp -d) || return 1\n  if ! (cd \"$built\" && export GOWORK=off && go mod init polish-gosec && go get github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec@v2.29.0 golang.org\u002Fx\u002Ftools@v0.52.0 && go build -o gosec github.com\u002Fsecurego\u002Fgosec\u002Fv2\u002Fcmd\u002Fgosec) >\"$built\u002Fbuild.log\" 2>&1; then\n    echo \"polish_gosec: could not build the gosec fallback:\" >&2\n    tail -n 20 \"$built\u002Fbuild.log\" >&2\n    rm -rf \"$built\"\n    return 1\n  fi\n  \"$built\u002Fgosec\" -fmt=json -out=\"$out\" .\u002F... 2>&1 || true\n  rm -rf \"$built\"\n}\npolish_gosec \u002Ftmp\u002Fpolish-gosec-after.json\n```\n\nRecord the after scores, including the live matrix qualifier from the final `scorecard --live-check --json` output. If the gosec command fails before writing `\u002Ftmp\u002Fpolish-gosec-after.json`, or that report still has a non-empty `\"Golang errors\"` map, treat the missing or partial post-fix scan as a polish failure: add it to `remaining_issues`, set `ship_recommendation: hold`, and include the stderr summary. If verify-skill still has any `severity=error` findings, workflow-verify still reports `workflow-fail`, publish-validate still reports `passed: false` (standalone mode only — mid-pipeline polish doesn't run this check), gosec still reports unresolved findings in hand-authored novel-feature Go, pii-audit still has pending findings or gate failures, or the final live matrix qualifier is `not_exercised`, ship cannot fire (see ship logic below). For a non-exercised live matrix, add a `remaining_issues` item such as `live matrix not exercised (mock-only\u002Fno live token); run the live gate before publish`.\n\n## Ship logic\n\nCompute the ship recommendation:\n\n- **`ship`**: verify >= 80%, scorecard >= 75, no critical failures, **AND** verify-skill exits 0 (no SKILL\u002FCLI mismatches), **AND** workflow-verify is not `workflow-fail`, **AND** (when `STANDALONE_MODE=true`) publish-validate reports `passed: true`, **AND** gosec has zero unresolved findings in hand-authored novel-feature Go, **AND** tools-audit shows zero pending findings (every finding fixed or explicitly accepted with rationale), **AND** pii-audit shows zero pending findings and zero gate failures (every PII finding fixed in source or accepted with valid pre-decision fields). The SKILL\u002Fworkflow\u002Fpublish\u002Fgosec\u002FPII 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; a CLI that publish-validate rejects is not publishable; a CLI with unresolved security static-analysis findings in hand-authored novel-feature code is still reviewer bait; a CLI that fails pii-audit at promote\u002Fpublish gates will halt shipping anyway. The publish-validate gate applies only when polish ran it (standalone mode); mid-pipeline polish defers publish-readiness to the main SKILL's Phase 6.\n- **`ship-with-gaps`**: verify >= 65%, scorecard >= 65, non-critical gaps remain, **AND** the SKILL\u002Fworkflow\u002Fgosec\u002FPII gates above are satisfied, **AND** (when `STANDALONE_MODE=true`) the publish-validate gate is satisfied, **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.\n\n  **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`:\n\n  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.\n  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:\n\n     ```markdown\n     ## Known Gaps\n\n     - **`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.\n     ```\n\n  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`.\n  4. List each Known Gaps write\u002Fupdate in `fixes_applied` so the caller can surface that this happened.\n\n  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.\n- **`hold`**: verify \u003C 65% or scorecard \u003C 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, **OR** (when `STANDALONE_MODE=true`) publish-validate reports `passed: false`, **OR** gosec still reports unresolved findings in hand-authored novel-feature Go, **OR** pii-audit still has pending findings or gate failures, **OR** the Phase 3 gate bundle says this is a prior sub-60 reprint with missing transcendence rows and no accepted `partial_transcendence_override`. Mid-pipeline polish never reaches `hold` because of publish-validate — the check doesn't run in that mode and `publish_validate_*` is emitted as `skipped (mid-pipeline)`.\n\n### Push higher without gaming\n\nThe ship gates are a floor, not a ceiling. After they pass, look at scorecard dimensions still below max and ask whether each gap is real or structural:\n\n1. **Find the underlying deficit, not the score.** The scorecard is a proxy for quality, not the goal itself. A README scoring 8\u002F10 might be missing a Cookbook section or have outdated commands — that's a real, fixable gap. A `mcp_surface_strategy` scoring 2\u002F10 on a 200-endpoint API might be flagging that the surface is mostly endpoint mirrors — also potentially fixable.\n2. **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.\n3. **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.\n4. **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.\n\n#### MCP scorecard dims map to spec fields, not generator code\n\nWhen `mcp_token_efficiency`, `mcp_tool_design`, `mcp_remote_transport`, or `mcp_surface_strategy` are below max, the fix is almost always a spec edit + regenerate (or `regen-merge` from a freshly-generated tree), **not** a generator-template change. Polish CAN address these — do not classify them as \"feature add to a generator-owned file, retro candidate.\" Cobratree shell-out tools already catalog from Short (not operator Long help), so leftover `mcp_token_efficiency` pressure is typed-endpoint descriptions, not framework `--help`.\n\n| Weak dim | Spec field that fixes it | What to add to `spec.yaml`'s `mcp:` block |\n|---|---|---|\n| `mcp_remote_transport` | `mcp.transport` | `transport: [stdio, http]` (small APIs at or under `spec.DefaultRemoteTransportEndpointThreshold` typed endpoints already get this by default; the override is only needed when the spec opted into a narrower list or the API is above the threshold and still wants remote reach) |\n| `mcp_token_efficiency`, `mcp_surface_strategy` | `mcp.endpoint_tools`, `mcp.orchestration` | `endpoint_tools: hidden` + `orchestration: code` (Cloudflare pattern: ~70 raw endpoint tools collapse to `\u003Capi>_search` + `\u003Capi>_read` + `\u003Capi>_execute`; reads use `_read`, and `_execute` previews state-changing calls until `confirm` is boolean `true`) |\n| `mcp_tool_design` | `mcp.intents` | Define multi-step intent compositions for the workflows the API supports |\n| `mcp_description_quality` | `mcp-descriptions.json` (override file at the CLI root) | Per-tool description overrides; thin spec-derived descriptions get richer text without spec edits |\n\nRecommended threshold: at >50 typed endpoints, default to recommending all four (`transport`, `endpoint_tools=hidden`, `orchestration=code`, `intents` for the headline workflows). Small APIs (\u003C= `spec.DefaultRemoteTransportEndpointThreshold`) get the http transport by default already, so `mcp_remote_transport` lands at 10\u002F10 without any spec edit — only call it out if the spec explicitly narrowed the list. The full reference is `docs\u002FSPEC-EXTENSIONS.md`.\n\nAfter editing the spec, regenerate (or `regen-merge` the changes into the published library) so the new `mcp:` block reaches templates. Cobratree-walked novel commands continue to surface as MCP tools either way; they don't need spec changes.\n\nRule of thumb: if your fix would still be valuable if the scorecard didn't exist, do it. If the only motivation is \"to push the score,\" don't.\n\n## Display delta and emit result block\n\nDisplay the delta to the user, then emit the structured `---POLISH-RESULT---` block. The block lets calling skills (e.g., main printing-press Phase 5.5) parse the recommendation and scores reliably; the human-readable table above is for the user.\n\n```\nPolish Results for \u003CCLI_NAME>:\n\n                    Before    After     Delta\n  Scorecard:        XX\u002F100    XX\u002F100    +N\n  Verify:           XX%       XX%       +N%\n  Live matrix:      exercised\u002Fnot_exercised -> exercised\u002Fnot_exercised\n  Tools-audit:      XX        XX        -N pending findings\n\nFixes applied:\n  - \u003Cone-line description of each fix>\n\nSkipped findings:\n  - \u003Cfinding>: \u003Cwhy you chose not to fix it>\n\nRemaining issues:\n  - \u003Cone-line description of each issue you tried to fix but couldn't>\n\n---POLISH-RESULT---\nscorecard_before: \u003CN>\nscorecard_after: \u003CN>\nverify_before: \u003CN>\nverify_after: \u003CN>\ndogfood_before: \u003CPASS|FAIL>\ndogfood_after: \u003CPASS|FAIL>\ndogfood_live_matrix_before: \u003Cexercised|not_exercised|unknown>\ndogfood_live_matrix_after: \u003Cexercised|not_exercised|unknown>\ngovet_before: \u003CN>\ngovet_after: \u003CN>\ngosec_before: \u003CN>\ngosec_after: \u003CN>\ntools_audit_before: \u003CN pending>\ntools_audit_after: \u003CN pending>\npublish_validate_before: \u003CPASS|FAIL|skipped (mid-pipeline)>\npublish_validate_after: \u003CPASS|FAIL|skipped (mid-pipeline)>\nfixes_applied:\n- \u003Cone-line description of each fix>\nskipped_findings:\n- \u003Cfinding>: \u003Cwhy you chose not to fix it>\nremaining_issues:\n- \u003Cone-line description of each issue you tried to fix but couldn't>\nship_recommendation: \u003Cship|ship-with-gaps|hold>\nfurther_polish_recommended: \u003Cyes|no>\nfurther_polish_reasoning: \u003Cone sentence explaining the call>\n---END-POLISH-RESULT---\n```\n\nThe three lists serve different purposes:\n- **fixes_applied**: what changed — the caller displays these\n- **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.\n- **remaining_issues**: issues you tried to fix but couldn't resolve.\n\n**`publish_validate_*` values.** Emit `PASS` or `FAIL` when polish ran publish-validate (standalone mode). Emit the literal string `skipped (mid-pipeline)` when polish skipped it (mid-pipeline invocation, `STANDALONE_MODE=false`). The skipped value is informational only: callers must not treat it as a failure when deciding whether to cascade polish's `ship_recommendation` into a CLI-level hold.\n\n**`dogfood_live_matrix_*` values.** Emit `exercised` only when live-check evaluated at least one real sample. Emit `not_exercised` for mock-only\u002Fno-token\u002Fno-research\u002Fno-evaluated-sample runs. When `dogfood_after: PASS` but `dogfood_live_matrix_after: not_exercised`, the human summary must say `dogfood PASS (mock only; live matrix not exercised — run the live gate before publish)`, and `ship_recommendation` must be `hold` unless the parent caller explicitly owns a later live gate.\n\n**`gosec_*` values.** Emit the post-triage count of gosec findings that are\nstill relevant to this printed CLI after generated-file triage. These values\nare intentionally not the raw `Issues[]` length from `\u002Ftmp\u002Fpolish-gosec-*.json`:\ndo not count generator-emitted findings that were routed to `skipped_findings`\nas retro candidates, but do count unresolved hand-authored findings that force\n`hold`.\n\n### Picking `further_polish_recommended`\n\nYour judgment, not a count of `remaining_issues`. Set `yes` when another polish invocation has a real chance of closing what's left:\n\n- `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.\n- The fixes you did land may have unblocked dependent issues you couldn't reach this pass.\n- A SKILL\u002FCLI mismatch needs a second look after this pass changed the source tree.\n\nSet `no` when another invocation would re-tread the same ground:\n\n- `remaining_issues` are decisions only the user can make (rename a flagship command, choose a default behavior, accept a structural trade-off).\n- You already attempted the fix in two different ways this pass and both failed for the same reason.\n- The blocker is external (API changed shape, rate-limited, missing credential) and not something a fresh polish run sees differently.\n- `remaining_issues` is empty AND `skipped_findings` are all environmental or structural — there is nothing left for polish to do.\n\n`further_polish_reasoning` is one sentence the caller surfaces verbatim. Make it specific (\"verify failures on `analytics export` and `report show` looked closable but I gave up too early\") rather than generic (\"more polish might help\"). Callers use this signal to decide whether to offer \"Polish again\" in their next prompt; a vague reason makes their prompt vague.\n\n## Publish Offer\n\n**Skip this entire section unless `STANDALONE_MODE` is true.** `STANDALONE_MODE` is set in the \"Resolve CLI\" block above based on the caller mode: true for slash-command invocations (`\u002Fprinting-press-polish ...`) or Skill-tool invocations that pass `--standalone` in `args`; false otherwise. When false, polish is being called from main SKILL Phase 5.5 or hold-path \"Polish to retry,\" and the working CLI has not been promoted to library yet. `\u002Fprinting-press-publish \u003Cslug>` would resolve to `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`, which is either empty or holds a stale prior run — invoking publish here would either fail to resolve or ship the wrong copy. The parent skill owns the publish flow on that path; just emit the result block and return.\n\nApply the publish turn-boundary rule: the `AskUserQuestion` answer may authorize only a handoff message, not a same-turn publish. Publishing opens or updates a public-library PR, so it requires a fresh user-authored message after polish completes. See `references\u002Fpublish-turn-boundary.md` for rationale.\n\nA simple check:\n\n```bash\nif [ \"$STANDALONE_MODE\" != \"true\" ]; then\n  echo \"non-standalone caller; skipping Publish Offer\"\n  return\nfi\n```\n\nThe gate is the caller-mode flag, **not** the resolved path. A Skill-tool invocation without `--standalone` defers publish even when the path lives under `$PRESS_LIBRARY\u002F\u003Cslug>\u002F`; this is the safer default, and the only way the inverted Phase 5.5\u002F5.6 failure mode (mid-pipeline run firing a public fork + PR) gets caught at the polish boundary. The previous path-substring heuristic (`*.runstate\u002F*`) is no longer load-bearing here — it has been retained in the research-dir resolution block above because that block is selecting between two real on-disk layouts, which is a different concern from publish gating.\n\nFor standalone invocations, continue with the offer below.\n\nIf `ship` or `ship-with-gaps`:\n\nConstruct the prompt from the result block. The shape is data-driven so the user is never asked to weigh \"Polish again\" against \"Publish\" when polish itself just decided another pass would not help.\n\n### Recommendation\n\nPick the recommended action from the polish result:\n\n- `ship` + `remaining_issues` empty → recommend **Publish**.\n- `ship` + `remaining_issues` non-empty + `further_polish_recommended: yes` → recommend **Polish again**.\n- `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**.\n- `ship-with-gaps` + `further_polish_recommended: yes` → recommend **Polish again**.\n- `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.\n\n### Menu\n\nSuppress the \"Polish again\" option entirely when `further_polish_recommended: no`. Keep \"Publish\" and \"Done\" always available.\n\nSurface `further_polish_reasoning` as context when polish opted out of recommending another pass — the user should see *why* polish is done.\n\nPresent via `AskUserQuestion`. Two example shapes:\n\n**Polish converged clean** (`remaining_issues` empty, `further_polish_recommended: no`):\n\n> \"\u003CCLI_NAME> polished: scorecard XX\u002F100, verify XX%. Polish ran cleanly — nothing more to fix.\n>\n> Recommendation: Publish.\n>\n> 1. **Publish separately** (recommended) — show the publish command for the next user message\n> 2. **Done for now** — CLI is at $PRESS_LIBRARY\u002F\u003Ccli-name>\"\n\n**Polish thinks another pass would help** (`remaining_issues` non-empty, `further_polish_recommended: yes`):\n\n> \"\u003CCLI_NAME> polished: scorecard XX\u002F100, verify XX%. \u003CN> issues remain.\n>\n> Polish notes: '\u003Cfurther_polish_reasoning>'\n>\n> Recommendation: Polish again before publishing.\n>\n> 1. **Polish again** (recommended) — close the remaining \u003CN> issues\n> 2. **Publish separately** — show the publish command to ship as-is in the next user message\n> 3. **Done for now** — CLI is at $PRESS_LIBRARY\u002F\u003Ccli-name>\"\n\nThe recommended option leads, carries the `(recommended)` label, and the leading `Recommendation:` line states the agent's call explicitly. Three reinforcing channels so the user does not have to infer from ordering.\n\n### If \"Publish separately\"\n\nDo not invoke `\u002Fprinting-press-publish \u003Ccli-name>` from this same turn, and do not check or create public-library PRs here. Print a handoff that requires an explicit fresh user-authored message. Include the `--from-polish` marker so publish can offer the same post-publish retro tail that polish used to offer after a successful inline publish:\n\n> \"Publishing requires a separate user confirmation because it can fork `mvanhorn\u002Fprinting-press-library`, push a branch, and open or update a PR.\n>\n> To publish, send this as your next message:\n>\n> `\u002Fprinting-press-publish \u003Ccli-name> --from-polish`\"\n\nAfter printing the handoff, stop. If the user sends the command in a later message, the publish skill owns validation, packaging, public-library PR creation or update, and the `--from-polish` post-publish retro offer.\n\n(When `STANDALONE_MODE` is false this whole section is unreachable — the Publish Offer guard at the top of this section returns early — so no extra check is needed here.)\n\n### If \"Polish again\"\n\nRe-run Phase 1 → Phase 2 → Phase 3 with the same CLI. Maximum 2 additional polish passes (3 total including the first).\n\n### If \"Done for now\"\n\nEnd normally.\n\n## Rules\n\n- Fix everything. Do not ask for approval before fixing — polish is autonomous.\n- Report results honestly. Show what improved and what didn't.\n- Do not add new features. Polish fixes quality issues, not feature gaps.\n- Do not re-run research or generation. Polish works with the CLI as-is.\n- Do not modify the printing-press generator. That's `\u002Fprinting-press-retro`.\n- Do not modify any files outside `$CLI_DIR`.\n- If polish adds or renames a Cobra command, the MCP surface updates automatically through the generated `internal\u002Fmcp\u002Fcobratree` runtime mirror. Update `novel_features` only when README\u002FSKILL highlights or registry display should change; use `cmd.Annotations[\"mcp:hidden\"] = \"true\"` for debug-only commands.\n- Maximum 1 fix-and-rediagnose pass per polish invocation. The \"Polish again\" path runs additional invocations (max 3 total).\n- Prefer mechanical fixes over creative decisions. When a creative decision is needed (like the CLI description), use the research brief from manuscripts if available.\n",{"name":5,"context":25,"created_by":26,"description":27,"allowed-tools":28,"min-binary-version":36},"fork","user","Polish a generated CLI to pass verification and become publish-ready. Runs diagnostics (dogfood, verify, scorecard, go vet, gosec), automatically fixes all issues (verify failures, static-analysis findings, dead code, descriptions, README, MCP tool quality), reports the before\u002Fafter delta, and offers to publish. Use after any \u002Fprinting-press run, or on any CLI in $PRESS_LIBRARY\u002F. Trigger phrases: \"polish\", \"improve the CLI\", \"fix verify\", \"make it publish-ready\", \"clean up the CLI\", \"get this ready to ship\".\n",[29,30,31,32,33,34,35],"Bash","Read","Glob","Grep","Write","Edit","AskUserQuestion","4.0.0","main","063c0fc3ecc69b02c1ff355a130a3cb53a4bd8e6",".agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish",0,"https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills","https:\u002F\u002Fgithub.com\u002Ffilippolmt","2026-11-14 22:46:00",{"source":8,"skillName":5,"commands":45,"prompt":55,"zipAvailable":56},[46,49,52],{"tool":47,"command":48},"npx","npx skills add filippolmt\u002Fskills --skill printing-press-polish",{"tool":50,"command":51},"bunx","bunx skills add filippolmt\u002Fskills --skill printing-press-polish",{"tool":53,"command":54},"pnpm","pnpm dlx skills add filippolmt\u002Fskills --skill printing-press-polish","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002FSKILL.md",true,[58,62,68,72,76],{"path":59,"resourceType":59,"resourceTypeDesc":60,"sizeBytes":61,"sourceHtmlUrl":16},"LICENSE","许可证",1086,{"path":63,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Fpii-polish.md","REFERENCE","参考文档",9212,"https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002Freferences\u002Fpii-polish.md",{"path":69,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Fpublish-turn-boundary.md",1162,"https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002Freferences\u002Fpublish-turn-boundary.md",{"path":73,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Ftools-polish.md",28448,"https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002Freferences\u002Ftools-polish.md",{"path":77,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":78,"sourceHtmlUrl":79},"SOURCE.md",424,"https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002F.agents\u002Fplugins\u002Fpackages\u002Fprinting-press-polish\u002Fskills\u002Fprinting-press-polish\u002FSOURCE.md",[81,89,98,106,114,122],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":85,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":20},"01M781ZJN9KDK0YY8EAQ8WXPRQ","writing-for-agents","Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-for-agents\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-for-agents\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":93,"licenseFileUrl":94,"sourceHtmlUrl":95,"categories":96,"keywords":97,"publishedAt":20},"01M781ZDZ8CQ30GRY5XNT1RF91","wrangler","Run or troubleshoot Wrangler CLI commands in projects that have a wrangler.jsonc, wrangler.json, or wrangler.toml file, including local development, Previews, deployment, and resource management. For new projects and projects without a Wrangler configuration file, use the cf CLI instead.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwrangler\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwrangler\u002FSKILL.md",[],[],{"skillNo":99,"name":100,"nameZh":6,"description":101,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":93,"licenseFileUrl":102,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":20},"01M781ZA1MB7E7T1R1TE0BTTJS","workers-profiling","Profile or debug CPU usage and memory allocation in deployed Cloudflare Workers and Durable Objects. Then use this information to optimize your code.","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fworkers-profiling\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fworkers-profiling\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":93,"licenseFileUrl":110,"sourceHtmlUrl":111,"categories":112,"keywords":113,"publishedAt":20},"01M781Z52Q7PBMDA2YBC3SCTYM","workers-development","Run, inspect, and debug Cloudflare Workers during local development with cf dev, wrangler dev, or the Cloudflare Vite plugin, using Local Explorer to read and seed binding data and query local traces and logs. Also routes production debugging to Workers observability. Use for debugging requests whether or not the project uses Wrangler.","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fworkers-development\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fworkers-development\u002FSKILL.md",[],[],{"skillNo":115,"name":116,"nameZh":6,"description":117,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":93,"licenseFileUrl":118,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":20},"01M781Z193MG7SHF4DSD1WK583","workers-best-practices","Cloudflare Workers best practices for production applications. Use when writing, reviewing, or configuring Workers.","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fworkers-best-practices\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fworkers-best-practices\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":126,"sourceHtmlUrl":127,"categories":128,"keywords":129,"publishedAt":20},"01M781YT0JB3GVA1HTFZ9QJHM7","wordpress-pro","Develops custom WordPress themes and plugins, creates and registers Gutenberg blocks and block patterns, configures WooCommerce stores, implements WordPress REST API endpoints, applies security hardening (nonces, sanitization, escaping, capability checks), and optimizes performance through caching and query tuning. Use when building WordPress themes, writing plugins, customizing Gutenberg blocks, extending WooCommerce, working with ACF, using the WordPress REST API, applying hooks and filters, or improving WordPress performance and security.","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwordpress-pro\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Ffilippolmt\u002Fskills\u002Fblob\u002Fmain\u002Fskills\u002Fwordpress-pro\u002FSKILL.md",[],[]]