printing-press — Skillopedia

/printing-press Generate the best useful CLI for an API without burning an hour on phase theater. What Changed In v2 The old skill inflated the path to ship: - too many mandatory research documents before code existed - too many separate late-stage validation phases after code existed - too many chances to discover obvious failures late This version uses one lean loop: 1. Resolve the spec and write one research brief 2. Generate 3. Build the highest-value gaps 4. Run one shipcheck block 5. Optionally run live API smoke tests Artifacts are still written, but only the ones that materially help…

status=%{http_code}\\ncontent_type=%{content_type}\\neffective_url=%{url_effective}\\n'\nif ! CURL_META=\"$(curl -sS -L --compressed --connect-timeout 10 --max-time 30 \\\n -D \"$HEADER_TMP\" -o \"$BODY_TMP\" -w \"$CURL_WRITE\" \"$URL\" 2>&1)\"; then\n echo \"fetch-docs: curl failed for $URL\" >&2\n printf '%s\\n' \"$CURL_META\" >&2\n exit 1\nfi\n\nstatus=\"$(printf '%s\\n' \"$CURL_META\" | awk -F= '$1 == \"status\" {print substr($0, index($0, \"=\") + 1)}')\"\ncontent_type=\"$(printf '%s\\n' \"$CURL_META\" | awk -F= '$1 == \"content_type\" {print substr($0, index($0, \"=\") + 1)}')\"\neffective_url=\"$(printf '%s\\n' \"$CURL_META\" | awk -F= '$1 == \"effective_url\" {print substr($0, index($0, \"=\") + 1)}')\"\n[[ -n \"$status\" ]] || status=\"000\"\n\next=\"$(extension_for \"$effective_url\" \"$content_type\")\"\nRAW_FILE=\"$BASE.$ext\"\nmv \"$BODY_TMP\" \"$RAW_FILE\"\nBODY_TMP=\"\"\n\nif [[ \"$status\" != \"200\" ]]; then\n {\n printf 'path=%s\\n' \"$RAW_FILE\"\n printf 'status=%s\\n' \"$status\"\n printf 'content_type=%s\\n' \"$content_type\"\n printf 'effective_url=%s\\n' \"$effective_url\"\n } > \"$META_FILE\"\n echo \"fetch-docs: HTTP $status for $URL (body: $RAW_FILE, final: $effective_url)\" >&2\n exit 22\nfi\n\nOUT_FILE=\"$RAW_FILE\"\nif [[ \"$WANT_MD\" == \"true\" && \"$ext\" != \"md\" && \"$ext\" != \"mdx\" ]]; then\n MD_FILE=\"$BASE.md\"\n if command -v readability-cli >/dev/null 2>&1 && command -v turndown-cli >/dev/null 2>&1; then\n if readability-cli \"$effective_url\" \u003c \"$RAW_FILE\" | turndown-cli > \"$MD_FILE\"; then\n OUT_FILE=\"$MD_FILE\"\n content_type=\"text/markdown; converted-from=$content_type\"\n else\n echo \"fetch-docs: markdown conversion failed; keeping raw capture $RAW_FILE\" >&2\n rm -f \"$MD_FILE\"\n fi\n elif command -v npx >/dev/null 2>&1; then\n if npx --yes readability-cli \"$effective_url\" \u003c \"$RAW_FILE\" | npx --yes turndown-cli > \"$MD_FILE\"; then\n OUT_FILE=\"$MD_FILE\"\n content_type=\"text/markdown; converted-from=$content_type\"\n else\n echo \"fetch-docs: npx markdown conversion failed; keeping raw capture $RAW_FILE\" >&2\n rm -f \"$MD_FILE\"\n fi\n else\n echo \"fetch-docs: --md requested but readability-cli/turndown-cli or npx are unavailable; keeping raw capture $RAW_FILE\" >&2\n fi\nfi\n\n{\n printf 'path=%s\\n' \"$OUT_FILE\"\n printf 'status=%s\\n' \"$status\"\n printf 'content_type=%s\\n' \"$content_type\"\n printf 'effective_url=%s\\n' \"$effective_url\"\n} > \"$META_FILE\"\n\nprint_result \"$OUT_FILE\" \"$status\" \"$content_type\" \"$effective_url\"\n","content_type":"application/x-sh; charset=utf-8","language":"bash","size":6451,"content_sha256":"ca33719dc5b05be25fd70152b3e715fd2ff6f9e4d28519fa254c62151da022ae"},{"filename":"references/known-specs.md","content":"# Known OpenAPI Specs\n\nAPIs with verified, publicly accessible OpenAPI specifications. The printing-press skill checks this registry before searching the web.\n\n## How to use\n\n1. Search this file for the API name\n2. If found, download the spec URL directly\n3. If not found, proceed to web search\n\n## Registry\n\n| API | Spec URL | Format | OpenAPI Version | Verified |\n|-----|----------|--------|-----------------|----------|\n| Petstore | https://petstore3.swagger.io/api/v3/openapi.yaml | YAML | 3.0.x | Yes |\n| Stytch | https://raw.githubusercontent.com/stytchauth/stytch-openapi/main/openapi.yml | YAML | 3.0.x | Yes |\n| Discord | https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json | JSON | 3.1.0 | Yes |\n| Stripe | https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json | JSON | 3.0.x | Yes |\n| Twilio | https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/json/twilio_api_v2010.json | JSON | 3.0.x | Yes |\n| SendGrid | https://raw.githubusercontent.com/twilio/sendgrid-oai/main/spec/json/sendgrid_oai.json | JSON | 3.0.x | Yes |\n| GitHub | https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.2022-11-28.yaml | YAML | 3.0.x | Yes |\n| GitLab | Skipped (no stable public raw OpenAPI spec URL confirmed) | N/A | N/A | No |\n| DigitalOcean | https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml | YAML | 3.0.x | Yes |\n| Asana | https://raw.githubusercontent.com/Asana/openapi/main/defs/asana_oas.yaml | YAML | 3.0.x | Yes |\n| Square | https://raw.githubusercontent.com/square/square-openapi/master/openapi.json | JSON | 3.0.x | Yes |\n| Notion | Skipped (official public OpenAPI spec URL not confirmed) | N/A | N/A | No |\n| Linear | https://raw.githubusercontent.com/linear/linear/master/packages/sdk/src/schema.graphql | GraphQL SDL | N/A | Yes |\n| HubSpot | https://raw.githubusercontent.com/HubSpot/HubSpot-public-api-spec-collection/main/PublicApiSpecs/CRM/Contacts/Rollouts/424/v3/contacts.json | JSON | 3.0.x | Yes |\n| Front | https://raw.githubusercontent.com/frontapp/front-api-specs/main/core-api/core-api.json | JSON | 3.0.x | Yes |\n\n## Notes\n- All URLs are raw file URLs (not HTML pages)\n- Verified means the URL was confirmed accessible and the spec parses correctly\n- Some specs are very large (Discord: 1MB+) - the parser handles this with resource/endpoint limits\n- This environment blocks direct shell network egress (`curl -sI` returns `000`), so URL checks were completed via repository/raw URL validation instead of local `curl`\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2611,"content_sha256":"4e8ceb8786393bb3d05359c7cde33fa79ef18ed71563cccd7d37f74d36414f2f"},{"filename":"references/noi-examples.md","content":"# Non-Obvious Insight (NOI) Formula\n\n## Formula\n\n`[API] isn't just [Obvious Frame]. It's [Insight Frame]. [Signal Sentence].`\n\nThe NOI reframes what an API does from its surface-level description into a deeper\ninsight about how power users actually leverage it. This drives CLI feature selection\ntoward workflows that matter rather than CRUD wrappers.\n\n## Examples by Domain Archetype\n\n### Project Management\n\n1. **Linear**: Linear isn't just an issue tracker. It's a velocity sensor for engineering teams. Every sprint boundary reveals whether a team is accelerating or decelerating before managers notice.\n\n2. **Jira**: Jira isn't just a ticket system. It's an organizational memory of every decision and tradeoff. The comment threads on old tickets contain the rationale that onboarding docs never capture.\n\n3. **Asana**: Asana isn't just a task manager. It's a dependency graph that exposes bottlenecks. When three projects share the same blocked task, it reveals the single person everyone is waiting on.\n\n4. **GitHub Issues**: GitHub Issues isn't just a bug tracker. It's a public roadmap signal. The ratio of feature requests to bug reports tells you whether users want more or want better.\n\n### Communication\n\n5. **Slack**: Slack isn't just a messaging app. It's an attention allocator. The channels with the highest unread counts reveal the topics your organization cares about but hasn't staffed.\n\n6. **Discord**: Discord isn't just a chat platform. It's a community health monitor. Thread reply depth and reaction diversity predict whether a community is growing or hollowing out.\n\n7. **Twilio**: Twilio isn't just an SMS API. It's a delivery reliability surface. The gap between sent and delivered timestamps exposes carrier routing problems before customers complain.\n\n### Payments\n\n8. **Stripe**: Stripe isn't just a payment processor. It's a revenue pattern detector. Subscription churn clusters around specific billing cycle days, revealing pricing sensitivity windows.\n\n9. **Square**: Square isn't just a POS system. It's a foot traffic sensor. Transaction timestamps and amounts map customer behavior patterns that no survey captures.\n\n10. **Plaid**: Plaid isn't just a banking connector. It's a financial behavior classifier. Transaction categorization patterns reveal spending personalities that credit scores miss.\n\n### Infrastructure\n\n11. **AWS EC2**: EC2 isn't just a compute service. It's a capacity planning oracle. Instance type migration patterns across an org reveal which workloads are growing before the bills spike.\n\n12. **Cloudflare**: Cloudflare isn't just a CDN. It's a traffic intent classifier. The ratio of cached to uncached requests reveals whether your users are browsing or building.\n\n### Content\n\n13. **Notion**: Notion isn't just a wiki. It's a knowledge decay detector. Pages with high view counts but stale edit dates are the documentation traps that cause the most onboarding friction.\n\n14. **WordPress**: WordPress isn't just a CMS. It's a content performance lab. The correlation between publish timing, word count, and engagement reveals the format your audience actually wants.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":3128,"content_sha256":"afe81fb67bbd8c5566e09cec5fbde560990e0c6c5fca97e4067d9ee73a112d50"},{"filename":"references/novel-features-subagent.md","content":"# Novel Features Subagent\n\n> **When to read:** This file is referenced by Phase 1.5 Step 1.5c.5 of the\n> printing-press skill. It owns the input bundle contract, the Task subagent\n> invocation, the subagent prompt template, and the output parsing rules for\n> novel-feature brainstorming.\n\n## Invariants\n\nThe subagent spawns once per absorb step, in every cli-printing-press run. The\nonly legal non-spawn outcome is the pre-flight HALT defined below.\n\n- A missing prior `research.json` is a first print, not a skip signal — the\n subagent still spawns; only Pass 2(d) (reprint reconciliation) is omitted.\n- A complete-looking prior manifest is not a skip signal either — Pass 2(d)\n re-scores prior features against the current personas, which is the\n entire reason the reprint case exists. Strong priors make the spawn more\n valuable, not less.\n- Hand-curating from a prior manifest, falling back to inline brainstorming\n in SKILL.md, or disclosing a skip in the gate showcase are violations of\n this contract, not exits from it.\n- Run the prior-research discovery snippet below as written. Do not\n substitute a hand-eyeballed `ls` of the manuscripts directory; the\n snippet's path (`$PRESS_MANUSCRIPTS/\u003capi-slug>/*/research.json`) is at the\n run-id level, not inside the `research/` subdirectory.\n\n## Pre-flight check\n\nBefore spawning, confirm the Phase 1 brief has both:\n- a populated `Users` section with concrete user types, AND\n- a populated `Top Workflows` section with named rituals.\n\nIf either is missing or pro-forma (\"developers\", \"general users\", \"anyone using\nthe API\"), do NOT spawn the subagent. The brainstorm will fabricate plausible\npersonas instead of grounding in research. Loop back to Phase 1 user research\nand return here.\n\n## Input bundle\n\nAssemble these values before spawning. Substitute into the prompt template\nbelow.\n\n| Variable | Value |\n|----------|-------|\n| `${BRIEF_PATH}` | `$RESEARCH_DIR/\u003cstamp>-feat-\u003capi>-pp-cli-brief.md` — also embeds DeepWiki findings (`## Codebase Intelligence`) and user briefing (`## User Vision`) when present |\n| `${ABSORB_MANIFEST_CONTENT}` | Inline markdown: the absorbed-features table built in Step 1.5b. The on-disk manifest at `\u003cstamp>-feat-\u003capi>-pp-cli-absorb-manifest.md` is not written until Step 1.5d, so paste the table content directly into the prompt. |\n| `${RUBRIC_PATH}` | Absolute path to `references/absorb-scoring.md` (the scoring rubric) |\n| `${API_SPEC_SUMMARY}` | Inline 1-paragraph summary: API surface (endpoint families), auth shape, NOI domain |\n| `${PRIOR_RESEARCH_PATH}` | Result of the prior-research discovery snippet below, or the literal string `none` |\n\n**Prior-research discovery.** Run before assembling the bundle to set\n`${PRIOR_RESEARCH_PATH}`:\n\n```bash\nPRIOR_RESEARCH=none\nif [ -f \"$PRESS_LIBRARY/\u003capi>/research.json\" ]; then\n PRIOR_RESEARCH=\"$PRESS_LIBRARY/\u003capi>/research.json\"\nelif [ -d \"$PRESS_MANUSCRIPTS/\u003capi-slug>\" ]; then\n CANDIDATE=$(ls -1t \"$PRESS_MANUSCRIPTS/\u003capi-slug>\"/*/research.json 2>/dev/null | head -1)\n [ -n \"$CANDIDATE\" ] && PRIOR_RESEARCH=\"$CANDIDATE\"\nfi\n```\n\nUser vision and DeepWiki findings are not separate variables — they live\ninside the brief. The subagent detects their presence by checking for the\n`## User Vision` and `## Codebase Intelligence` sections in\n`${BRIEF_PATH}`.\n\n## Subagent invocation\n\nOne Task tool call. Do not split passes across multiple invocations — the cut\npass must see the candidates it generated.\n\n```\nAgent({\n description: \"Novel-features brainstorm + adversarial cut\",\n subagent_type: \"general-purpose\",\n prompt: \u003cSubagent prompt template below, with ${...} placeholders substituted>\n})\n```\n\n## Subagent prompt template\n\n````\nYou are a novel-features brainstorming agent for the Printing Press, a system\nthat generates CLIs for APIs. Your job is to propose the differentiating\nfeatures for ONE printed CLI and then ruthlessly cut the weak ones.\n\nYou will run THREE PASSES IN ORDER. The third pass is not optional and is not\na polish pass — it is the cut.\n\n## Inputs (read these before Pass 1)\n\n- Brief (read from disk): ${BRIEF_PATH}\n- Scoring rubric (read): ${RUBRIC_PATH} (kill/keep checks, score dimensions, table format, reprint verdicts)\n- Prior research.json: ${PRIOR_RESEARCH_PATH} (read from disk if real path; literal `none` means first print)\n- API spec summary: ${API_SPEC_SUMMARY} (inline)\n\nInline absorb manifest (features ALREADY covered — do not re-propose):\n\n${ABSORB_MANIFEST_CONTENT}\n\nThe brief may contain `## User Vision` and `## Codebase Intelligence`\nsections. Detect their presence after reading the brief; they gate Pass 2\nsources (e) and (f).\n\nIf `${PRIOR_RESEARCH_PATH}` is a real path, this is a REPRINT and Pass 2 step\n(d) is mandatory.\n\n## Pass 1: Customer pass\n\nWrite down WHO the user of this CLI is BEFORE proposing any features. Output\nunder heading `## Customer model`.\n\n- 2-4 named personas. NOT \"developers\" or \"users\" — concrete people with\n concrete habits drawn from the brief's Users + Top Workflows sections.\n Good: \"Someone who checks HN every morning before standup.\"\n Good: \"A hiring manager scanning Who's Hiring threads monthly.\"\n Bad: \"API users.\"\n- For each persona, write three short paragraphs:\n - **Today (without this CLI):** What do they do today to accomplish their\n weekly ritual with this API? What tabs do they have open? What scripts do\n they re-run? What questions can they NOT answer?\n - **Weekly ritual:** The repeated workflow that defines their relationship\n with this service.\n - **Frustration:** The single most tedious or impossible part of the ritual.\n\nIf you cannot do this from the brief alone — if you find yourself inventing\npersonas to keep going — STOP and return ONLY:\n\n```\n## Failure: brief lacks user research\n\nThe Phase 1 brief does not contain enough Users / Top Workflows detail to\nground a customer model. Re-run Phase 1 user research before spawning this\nsubagent again.\n```\n\nDo not proceed to Pass 2 with fabricated personas.\n\n## Pass 2: Generate pass\n\nOutput under heading `## Candidates (pre-cut)`. Generate ~2× the features you\nexpect to ship — aim for 8-16 candidates total.\n\nSources for candidates (label each candidate with its source):\n\n(a) **Persona-driven:** For each persona's frustration from Pass 1, propose\n the one-command feature that resolves it.\n\n(b) **Service-specific content patterns:** What unique content types or\n workflows define this service's identity (e.g., HN's Show HN / Ask HN /\n Who's Hiring; Spotify's Discover Weekly / Wrapped; GitHub's\n Discussions; TMDb's Collections / Watch Providers)? Propose features\n that exploit each.\n\n(c) **Cross-entity local queries:** What joins across synced tables produce\n insights no single API call can?\n\n(d) **Reprint reconciliation** (only if `${PRIOR_RESEARCH_PATH}` is a real\n path): Load the prior `novel_features` and `novel_features_built`\n arrays. For each prior feature, score it against the current personas\n using the rubric. Add to candidates with verdict tag `prior-keep`,\n `prior-reframe`, or `prior-drop`. The prior list is candidate input,\n not gospel and not noise.\n\n(e) **User briefing** (only if the brief contains a `## User Vision`\n section): Propose features that directly serve the user's stated vision\n but are not already covered by the absorb manifest.\n\n(f) **DeepWiki** (only if the brief contains a `## Codebase Intelligence`\n section): Propose features that exploit internal data relationships,\n queue/worker patterns, or event systems that the public API docs don't\n suggest.\n\nFor each candidate capture: name, command, one-line description, persona\nserved, source label from the list above, and `Long Description` (`none`\nunless the overlap rule below applies).\n\nWhen 2+ compound-tool candidates could plausibly match the same natural-language\nrequest because their input surfaces overlap (for example, user UPN, market ID,\ncustomer email, or recipe name), plan each overlapping command's `Long:`\ndescription with an explicit scope redirect:\n\n```text\nUse this command for \u003cmatching intent>.\nDo NOT use this command for \u003cnearby but wrong intent>; use '\u003csibling-command>' instead.\n```\n\nOnly skip this pattern for single-tool CLIs or candidates whose inputs and\noperator intent do not overlap with sibling tools. A slightly longer `Long:`\ndescription is acceptable when it prevents an agent from choosing the wrong\ncompound tool.\n\nApply the rubric's kill/keep checks (LLM dependency, external service, auth\ngap, scope creep, verifiability, reimplementation) inline. Reframe or cut\nobvious failures NOW so they don't waste Pass 3 attention.\n\n## Framework command flags\n\nThe generated framework commands have stable flag vocabularies. Use these\nverbatim in `narrative.quickstart`, `narrative.recipes`, and any example that\ncalls a framework command:\n\n- `sync`: `--resources \u003ccsv>`, `--since \u003cduration like 7d/24h/1w/30m>`, `--full`, `--latest-only`, `--max-pages \u003cint>`, `--param key=value`, `--resource-param resource:key=value`, `--global-param key=value`, `--db \u003cpath>`\n- `search`: `--type \u003csingle resource>`, `--limit \u003cint>`, `--db \u003cpath>`\n- `analytics`: `--type \u003csingle resource>`, `--group-by \u003cfield>`, `--limit \u003cint>`, `--db \u003cpath>`\n- `tail`: `--resource \u003csingle resource>`, `--interval \u003cduration>`, `--since \u003ctimestamp>`, `--follow`\n- global output flags on any command: `--json`, `--agent`, `--select \u003cfields>`, `--compact`, `--quiet`, `--plain`, `--csv`\n\nDo not invent plausible variants such as `--entities`, `--types`, `--query`, or\nabsolute dates for `sync --since`. If you need multiple resources, use\n`sync --resources customers,charges`. If you need search scoped to one resource,\nuse `search \"term\" --type customers`. Do not use `search --entities`.\n\nHand-written novel commands that read from the local store must call the\ngenerated sync hint helpers before returning local results:\n\n```go\nif !hintIfUnsynced(cmd, db, \"\u003cresource>\") {\n hintIfStale(cmd, db, \"\u003cresource>\", flags.maxAge)\n}\n```\n\nUse `\"\"` for commands that scan all local resources. The helpers write only to\nstderr, so JSON/stdout output stays stable; `--max-age 0` disables stale-read\nhints.\n\nEvery hand-written novel command must also declare its data-source strategy in\nthe command source file:\n\n```go\n// pp:data-source local\n```\n\nUse exactly one of:\n- `auto` for commands that honor `--data-source auto|local|live` by choosing\n live data with local fallback.\n- `local` for commands that only read synced/local SQLite data. These commands\n must reject `--data-source live` with a clear \"no live equivalent\" error.\n- `live` for commands that only call the remote API. These commands must reject\n `--data-source local` with a clear \"no local data source\" error.\n\nDogfood reports hand-written novel commands that omit the annotation or use an\nunknown strategy.\n\n## Pass 3: Adversarial cut pass\n\nThis is the pass that exists because brainstorms without it produce flabby\nlists. Output under heading `## Survivors and kills`.\n\nFor EVERY surviving candidate, force-answer these in writing:\n\n1. **Weekly use:** Would the named persona actually run this command at\n least weekly? \"Monthly\", \"occasionally\", or \"depends\" is a soft kill.\n2. **Wrapper vs leverage:** Is this a thin renaming of one API endpoint\n the user could call directly with a generic client? If yes, kill it —\n wrappers do not justify transcendence rows.\n3. **Transcendence proof:** Does this feature get its power from local\n SQLite, a cross-source join, agent-shaped output, or a service-specific\n content pattern? If the answer is \"none of the above\", it is not\n transcendent.\n4. **Sibling kill:** Name the closest candidate you killed and why. If\n you cannot, you didn't generate enough candidates — return to Pass 2\n and add more.\n5. **Buildability:** Will the generator auto-emit this from the spec, or\n will the agent need to hand-write a Cobra file plus `root.go` wiring\n after generate? Tag exactly one value:\n - `spec-emits` — the feature reuses an endpoint already in the spec\n and the generator's emit path (endpoint mirror or `extra_commands`)\n produces a working command without hand-edits.\n - `hand-code` — the feature requires SQLite joins, cross-source\n synthesis, custom output shapes, or any Go code beyond what the\n generator emits today (~50-150 LoC per feature plus `root.go`\n wiring). This is the default for transcendence features; most\n candidates fall here.\n6. **Long-description validity:** If the survivor has a planned `Long\n Description`, confirm every named sibling command still survives with that\n exact command name. If Pass 3 killed or renamed the sibling, revise the\n redirect to point at the surviving command, or clear it to `none` when no\n accurate sibling remains.\n\nDrop ~half. Target output: 4-8 survivors. Score survivors with the rubric's\n4-dimension score; only keep features scoring >= 5/10.\n\nFor every killed candidate, record a one-sentence kill reason. Killed\ncandidates are PART of the output, not silent.\n\n## Output contract\n\nReturn a single markdown document with these top-level sections, in this\norder:\n\n1. `## Customer model` — personas from Pass 1.\n2. `## Candidates (pre-cut)` — full Pass 2 list with source labels,\n `Long Description` (`none` when not needed), and inline kill/keep verdicts\n from the rubric.\n3. `## Survivors and kills`\n - `### Survivors` — features scoring >= 5/10, formatted as a\n transcendence table matching the rubric's \"Transcendence Table\n Format\" section (which includes the **Buildability** column,\n `spec-emits` or `hand-code` per Pass 3 question 5). Include score,\n persona-served, the one-sentence buildability proof per the rubric,\n the buildability tag, and `Long Description` (`none` when not needed).\n Any non-`none` `Long Description` MUST reference only surviving command\n names after Pass 3.\n - `### Killed candidates` — table with columns: feature, kill reason,\n closest-surviving-sibling.\n4. `## Reprint verdicts` (REPRINT ONLY) — per-prior-feature: keep / reframe\n / drop, with one-line justification, per the rubric's reprint verdict\n rules.\n\nDo not include any other sections. Do not summarize. Do not editorialize.\nDo not propose follow-up work.\n````\n\n## Output handling in SKILL.md\n\nAfter the subagent returns:\n\n1. **Parse `### Survivors`** — these become the transcendence rows in the\n absorb manifest (Step 1.5d). The score, buildability proof, and\n `Buildability` tag flow into the transcendence table; the persona-served\n column is the audit trail. Preserve non-`none` `Long Description` values\n in the manifest row so Phase 3 hand-code uses them as the Cobra `Long`\n text instead of losing them in the brainstorm audit trail. The\n `Buildability` column drives Phase Gate 1.5's hand-code count: rows tagged\n `hand-code` are the agent's post-generate scope commitment, rows tagged\n `spec-emits` are not.\n2. **Parse `## Reprint verdicts`** (if present) — record dropped prior features\n under the transcendence table per the rubric's reprint surface rule, so the\n user can override drops at the Phase 1.5 gate review.\n3. **Audit trail** — save the full subagent response (including `## Customer\n model`, `## Candidates (pre-cut)`, `### Killed candidates`) to\n `$RESEARCH_DIR/\u003cstamp>-novel-features-brainstorm.md`. The Customer model and\n Killed candidates do NOT go into the manifest, but they MUST be persisted\n for retro/dogfood debugging.\n4. **Failure handling** — if the subagent returned the `## Failure: brief lacks\n user research` envelope, HALT Phase 1.5 immediately. Do not fall back to\n inline brainstorming. Surface the failure to the user and re-run Phase 1\n user research.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":15861,"content_sha256":"d7ad6d3753f01af5000feedb530901a2281a344772d6c9723a25c21a62d336f9"},{"filename":"references/per-source-rate-limiting.md","content":"# Per-source rate limiting\n\nHand-written clients in sibling internal packages (`internal/source/\u003cname>/`,\n`internal/recipes/`, `internal/phgraphql/`, etc.) MUST use\n`cliutil.AdaptiveLimiter` and surface `*cliutil.RateLimitError` from public\nmethods when 429 retries are exhausted. Returning empty results on throttle is\nsilent corruption: downstream queries cannot tell \"the source has no data\" from\n\"the source rate-limited us.\"\n\n## Reference shape\n\n```go\nimport (\n \"context\"\n \"errors\"\n \"net/http\"\n\n \"\u003cmodulePath>/internal/cliutil\"\n)\n\ntype Client struct {\n HTTP *http.Client\n limiter *cliutil.AdaptiveLimiter\n}\n\nfunc New() *Client {\n return &Client{\n HTTP: &http.Client{},\n limiter: cliutil.NewAdaptiveLimiter(2.0),\n }\n}\n\nfunc (c *Client) Fetch(ctx context.Context, url string) ([]byte, error) {\n c.limiter.Wait()\n req, err := http.NewRequestWithContext(ctx, \"GET\", url, nil)\n if err != nil {\n return nil, err\n }\n resp, err := c.HTTP.Do(req)\n if err != nil {\n return nil, err\n }\n defer resp.Body.Close()\n if resp.StatusCode == http.StatusTooManyRequests {\n c.limiter.OnRateLimit()\n return nil, &cliutil.RateLimitError{\n URL: url,\n RetryAfter: cliutil.RetryAfter(resp),\n }\n }\n c.limiter.OnSuccess()\n // ... read + return body ...\n return nil, nil\n}\n```\n\n## Higher-level fanout commands\n\nAggregations that fan out N filings/items MUST `errors.As(err, &rateErr)` and\npropagate the failure rather than `continue`-ing past it:\n\n```go\nfor _, item := range items {\n detail, err := c.FetchDetail(ctx, item.ID)\n if err != nil {\n var rateErr *cliutil.RateLimitError\n if errors.As(err, &rateErr) {\n return nil, err\n }\n continue // other errors are still skippable\n }\n out = append(out, detail)\n}\n```\n\n## Enforcement\n\n`cli-printing-press dogfood` runs `source_client_check`, which scans every\n`internal/\u003cpkg>/*.go` file outside the generator-emitted set. A file that\nmakes outbound HTTP calls but lacks a limiter signal or a typed-error signal\nproduces a finding.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2151,"content_sha256":"4e0750cf1ca71a247f4fb4170da0fcaf41a3d4494843aed932f1620c36bc7d79"},{"filename":"references/scorecard-patterns.md","content":"# Steinberger Scorecard - Exact Scoring Patterns\n\nThis table maps each scorecard dimension to the exact file and string patterns measured by `internal/pipeline/scorecard.go`. Use this to target Phase 4 fixes at patterns that actually score points.\n\n## Scoring Algorithm\n\nEach dimension is 0-10. Total is 0-90. Grade: A >= 80%, B >= 65%, C >= 50%, D >= 35%, F \u003c 35%.\n\nRun the scorecard: `cli-printing-press scorecard --dir ./\u003capi>-cli`\n\n## Dimension Reference\n\n| Dimension | File Checked | Patterns (points each) | Max |\n|-----------|-------------|----------------------|-----|\n| Output Modes | `internal/cli/root.go` | `json`(+2) `plain`(+2) `select`(+2) `table`(+2) `csv`(+2) | 10 |\n| Auth | `internal/config/config.go` + file existence | `os.Getenv` count: 1 call = 5pts, 2+ calls = 8pts. `internal/cli/auth.go` exists = +2pts | 10 |\n| Error Handling | `internal/cli/helpers.go` | `hint:` or `Hint:` present = +5. Count of `code:` occurrences (1pt each, max 5) | 10 |\n| Terminal UX | `internal/cli/helpers.go` | `colorEnabled`(+5) `NO_COLOR`(+3) `isatty`(+2) | 10 |\n| README | `README.md` | Exact section strings: `Quick Start`(+2) `Output Formats`(+2) `Agent Usage`(+2) `Troubleshooting`(+2) `Doctor`(+2) | 10 |\n| Doctor | `internal/cli/doctor.go` | Count HTTP patterns x2: `http.Get`, `http.Head`, `http.NewRequest`, `http.Client`, `httpClient.Get`, `httpClient.Head`, `httpClient.Do` | 10 |\n| Agent Native | `internal/cli/root.go` + `helpers.go` | `json`(+2) `select`(+2) `dry-run`/`dryRun`/`dry_run`(+2) `non-interactive`/`nonInteractive`(+1) `stdin`(+1) `\"yes\"`(+1) `409`/`already exists`(+1) `human-friendly`/`humanFriendly`(+1) | 10 |\n| Local Cache | `internal/client/client.go` + `internal/cache/cache.go` | `cacheDir`/`readCache`/`writeCache`(+5) `no-cache`/`NoCache`(+2) `sqlite`/`bolt`/`badger` in cache.go or store.go(+3) | 10 |\n| Breadth | `internal/cli/*.go` file count | Excludes: helpers.go, root.go, doctor.go, auth.go. Thresholds: \u003c5=0, 5-10=3, 11-20=5, 21-40=7, 41-60=9, 60+=10 | 10 |\n| Workflows | `internal/cli/*.go` registered commands | Workflow filename prefixes, direct store use, package-local store helpers, or 2+ client API calls | 10 |\n| Insight | `internal/cli/*.go` registered commands | Insight filename prefixes, store use plus aggregation patterns (`COUNT(`, `SUM(`, `GROUP BY`, rates), or manifest novel-feature hints | 10 |\n\n## Key Gotchas\n\n- README scorecard checks for **exact string** `\"Doctor\"` (capital D), not `\"Health Check\"` or `\"doctor\"`\n- Agent Native checks root.go + helpers.go ONLY - `stdin` in command files doesn't count\n- Auth gives +2 just for `auth.go` existing as a file, regardless of content\n- Local Cache gives +3 for `sqlite`/`bolt`/`badger` strings in `internal/cache/cache.go` or `internal/store/store.go`\n- Breadth counts files, not commands - one file per endpoint beats one file per resource\n- Workflow scoring follows registered Cobra commands and recognizes package-local helpers that reach the store\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2969,"content_sha256":"5700406bd44cc8c8d0fc92ea3a1b41cdd7bffea3d6acce18fb3572f9a5263c1a"},{"filename":"references/secret-protection.md","content":"# Secret & PII Protection — Implementation Details\n\nRead this file during Phase 5.5 (Archive Manuscripts) and before any publish step.\nThe cardinal rules in SKILL.md apply at all times. This file has the implementation.\n\n## Exact-value scan before archiving\n\nThe skill knows the API key if the user provided one. Before archiving manuscripts,\nscan all artifacts for the exact key value. This has zero false positives — it checks\nfor the specific string, not guessed patterns.\n\nUse `grep -F` (fixed string) and `awk` for replacement — NOT bare `grep`/`sed` —\nbecause API keys often contain regex metacharacters (`+`, `/`, `.`, `=`) that would\ncause `grep` to match wrong text and `sed` to corrupt files.\n\n```bash\n# Guard: skip if key is empty or too short (\u003c 16 chars). Short strings\n# would over-redact legitimate content. Real API keys are 20+ chars.\nif [ -n \"$API_KEY_VALUE\" ] && [ ${#API_KEY_VALUE} -ge 16 ]; then\n LEAK_FOUND=false\n for dir in \"$RESEARCH_DIR\" \"$PROOFS_DIR\" \"$DISCOVERY_DIR\"; do\n if [ -d \"$dir\" ] && grep -rF \"$API_KEY_VALUE\" \"$dir\" 2>/dev/null; then\n LEAK_FOUND=true\n fi\n done\n if [ \"$LEAK_FOUND\" = true ]; then\n echo \"BLOCKING: API key value found in manuscript artifacts. Auto-redacting.\"\n REDACT_TO=\"\\${API_KEY_ENV_VAR:-API_KEY}\"\n for dir in \"$RESEARCH_DIR\" \"$PROOFS_DIR\" \"$DISCOVERY_DIR\"; do\n [ -d \"$dir\" ] || continue\n find \"$dir\" -type f -print0 | while IFS= read -r -d '' f; do\n if grep -qF \"$API_KEY_VALUE\" \"$f\" 2>/dev/null; then\n # Use python for truly literal replacement — awk's gsub and perl's\n # s/// both interpret regex metacharacters (+, ., /) in the key,\n # which breaks on JWT tokens and base64-encoded secrets.\n REDACT_OLD=\"$API_KEY_VALUE\" REDACT_NEW=\"$REDACT_TO\" python3 -c \"\nimport sys, os\nold, new, path = os.environ['REDACT_OLD'], os.environ['REDACT_NEW'], sys.argv[1]\nwith open(path) as f: content = f.read()\nwith open(path, 'w') as f: f.write(content.replace(old, new))\n\" \"$f\"\n fi\n done\n done\n echo \"Auto-redacted. Verify before proceeding.\"\n fi\nfi\n```\n\n## Strip auth from HAR captures before archiving\n\nCredentials can appear in four locations within HAR files:\n- **Request headers:** `Authorization: Bearer \u003ctoken>`, `Cookie: session=...`\n- **Response headers:** `Set-Cookie: session=\u003ctoken>` (from auth flows)\n- **Query strings:** `?key=\u003cvalue>`, `?api_key=\u003cvalue>`, `?access_token=\u003cvalue>`\n- **Cookies:** session tokens, auth cookies (both request and response)\n\nThe archive step must strip all four, plus response bodies (for size):\n\n```bash\njq 'del(.log.entries[].response.content.text) |\n # Remove auth headers from requests\n (.log.entries[].request.headers) |= [.[] |\n select(.name | test(\"^(Authorization|Cookie|Set-Cookie|X-API-Key|X-Auth-Token)$\"; \"i\") | not)\n ] |\n # Remove Set-Cookie from responses (contains session tokens from auth flows)\n (.log.entries[].response.headers) |= [.[] |\n select(.name | test(\"^(Set-Cookie)$\"; \"i\") | not)\n ] |\n # Redact auth-like query string params\n (.log.entries[].request.queryString) |= [.[] |\n if (.name | test(\"^(key|api_key|apikey|token|secret|access_token|password)$\"; \"i\"))\n then .value = \"\u003cREDACTED>\"\n else . end\n ] |\n # Remove cookies entirely (they often contain session tokens)\n (.log.entries[].request.cookies) |= [] |\n (.log.entries[].response.cookies) |= []\n ' \"$har\" > \"${har}.stripped\" 2>/dev/null && mv \"${har}.stripped\" \"$har\"\n```\n\n## API key handling during the run\n\nWhen the user provides an API key (Phase 0 API Key Gate or inline):\n- Store it only in a shell variable, never in a file\n- Pass it to commands via environment variable, not via flags visible in process lists\n- In dry-run output, the key may appear in query params — this is expected for\n debugging but must NOT be captured in proof artifacts\n- When writing live smoke results to proofs, write the test outcomes (PASS/FAIL)\n but never the request URLs that contain the key in query params\n\n## Workspace & organization PII redaction\n\nLive dogfood testing (Phase 5) naturally surfaces workspace-specific data: organization\nnames, team names, team member names, and email addresses. This data must NEVER appear\nin any public artifact: acceptance reports, shipcheck proofs, manuscripts archived to\nthe library repo, PR descriptions, or READMEs.\n\n**When reporting live test results, use generic descriptions:**\n- \"the workspace\" not the actual org name\n- \"5 overloaded members\" not their names or emails\n- \"12 users synced\" not \"synced [email protected], [email protected]\"\n- \"team ESP\" is OK (team keys are structural, not PII) but \"Esper Labs\" is not\n\n**Before archiving manuscripts (Phase 5.6):** Scan acceptance reports and shipcheck\nproofs for organization names, email addresses, and full names. The exact-value scan\nfor API keys (above) catches secrets; this step catches PII that the user's live\nworkspace naturally produces.\n\n**When persisting live-check samples:** `scorecard --live-check` and live-dogfood\nsample captures scrub `output_sample` text before it is stored in JSON/proof\nartifacts. Treat archive-time and publish-time scans as defense in depth, not as\npermission to write raw customer names, emails, addresses, invoice numbers, or\ncard tails into the run directory.\n\n**Before creating publish PRs:** The publish skill constructs PR descriptions from\nmanuscripts and test results. Any live test data quoted in the PR body must be\nscrubbed of workspace PII. The library repo is public.\n\n## PII pattern scanning\n\nThe prose guidance above tells the agent how to compose published artifacts safely.\nThis section defines a mechanical sweep that runs before publishing to catch the\nPII the agent missed. Two prior PII leaks happened despite the prose guidance — a\nmechanical defense layer is required.\n\n**Run order:** exact-value scan (above) → HAR auth strip → PII pattern scanning.\n\n**File scope.** Sweep all text-readable files in the staging directory. Detect by\ncontent, not extension — a `.yaml` HAR variant or a `.txt` proof matters as much as\na `.md`. Use this Go-equivalent helper to classify:\n\n```bash\n# Treat as text if no NULL byte in the first 8 KiB\nisText() { head -c 8192 \"$1\" | grep -L -q

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

\\x00' \"$1\" 2>/dev/null; }\n```\n\n(In Bash, `file --mime-type` works on macOS and GNU `file` portably enough.)\n\n### Tier 1: vendor-anchored auto-redact\n\nAuto-redact ONLY when the pattern includes a vendor-specific prefix anchor. These\nhave near-zero false-positive rate. Auto-redact silently — no user prompt, no\nrecovery prompt. Pattern set:\n\n```bash\nPII_AUTO_REDACT=(\n 'openrouter-api-key|sk-or-v1-[A-Za-z0-9_-]{24,}|\u003cREDACTED:openrouter-api-key>'\n 'bearer-stripe-live|Bearer sk_live_[A-Za-z0-9]{20,}|Bearer \u003cREDACTED:stripe-live-token>'\n 'bearer-stripe-test|Bearer sk_test_[A-Za-z0-9]{20,}|Bearer \u003cREDACTED:stripe-test-token>'\n 'bearer-cal-live|Bearer cal_live_[A-Za-z0-9]{20,}|Bearer \u003cREDACTED:cal-live-token>'\n 'bearer-cal-test|Bearer cal_test_[A-Za-z0-9]{20,}|Bearer \u003cREDACTED:cal-test-token>'\n 'bearer-github-pat|Bearer ghp_[A-Za-z0-9]{36,}|Bearer \u003cREDACTED:github-pat>'\n 'bearer-github-oauth|Bearer gho_[A-Za-z0-9]{36,}|Bearer \u003cREDACTED:github-oauth>'\n 'bearer-github-server|Bearer ghs_[A-Za-z0-9]{36,}|Bearer \u003cREDACTED:github-server-token>'\n 'bearer-github-fine|Bearer github_pat_[A-Za-z0-9_]{60,}|Bearer \u003cREDACTED:github-fine-grained-pat>'\n 'slack-user-token|xoxp-[A-Za-z0-9-]{40,}|\u003cREDACTED:slack-user-token>'\n 'slack-bot-token|xoxb-[A-Za-z0-9-]{40,}|\u003cREDACTED:slack-bot-token>'\n 'slack-app-token|xapp-[A-Za-z0-9-]{32,}|\u003cREDACTED:slack-app-token>'\n 'google-api-key|AIza[A-Za-z0-9_-]{20,}|\u003cREDACTED:google-api-key>'\n)\n\nfor entry in \"${PII_AUTO_REDACT[@]}\"; do\n IFS='|' read -r name regex tag \u003c\u003c\u003c \"$entry\"\n for f in $(find \"$STAGING_DIR\" -type f); do\n isText \"$f\" || continue\n if grep -qE \"$regex\" \"$f\" 2>/dev/null; then\n perl -i -pe \"s|$regex|$tag|g\" \"$f\"\n echo \"Auto-redacted $name in ${f#$STAGING_DIR/}\"\n fi\n done\ndone\n```\n\nDo not add a simple `AKIA[0-9A-Z]{16}` shell auto-redaction rule here. AWS\naccess keys have the same shape as AWS's canonical documentation placeholder,\nso the binary publish scan handles them with a placeholder allowlist instead.\n\nThese patterns are vendor-anchored and the prefix character class is restrictive\nenough that the false-positive rate is effectively zero. Adding a new vendor\npattern is safe — extend the list when shipping a new printed CLI for a vendor\nwith a known token format.\n\n### Tier 2: warn-by-default with allowlist\n\nEverything else gets WARN behavior. The user sees the matches, decides whether to\nredact each one. This includes generic emails, generic bearer tokens (without a\nvendor prefix), and capitalized name patterns. Designed cost asymmetry:\nfalse-positive auto-redaction loses information irreversibly; false-positive\nwarning costs only a prompt.\n\n```bash\nPII_WARN=(\n 'email|[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}|email address'\n 'bearer-generic|Bearer [A-Za-z0-9._\\-+/=]{20,}|generic bearer token (no vendor prefix)'\n 'name-pattern|\\b[A-Z][a-z]{2,}\\s+[A-Z][a-z]{2,}\\b|capitalized first+last name'\n)\n```\n\n**Allowlist (suppress matches against this set):**\n\nBuild at scan time from three sources:\n\n1. **Spec-derived terms.** Capitalized two-word phrases extracted from the spec's\n operation summaries, descriptions, tag names, and parameter descriptions. This\n catches \"Event Types\", \"Booking Links\", \"Webhook Triggers\" automatically — they\n look like name patterns but are API vocabulary.\n\n2. **CLI-help-derived terms.** Walk `\u003ccli> --help` recursively and extract\n capitalized two-word phrases from command Short/Long fields. Catches command\n group names that the spec might not mention by exact phrasing.\n\n3. **Universal allowlist.** A small static list of terms that appear across\n APIs and would otherwise produce noise:\n\n ```\n \"Open Source\", \"Pull Request\", \"Bearer Token\", \"API Key\", \"Access Token\",\n \"Refresh Token\", \"GitHub Actions\", \"Cloud Run\", \"Service Account\",\n \"Rate Limit\", \"Time Zone\", \"Web Hook\", \"Personal Access\", \"Application Token\"\n ```\n\nA match is suppressed if it matches any allowlist entry by:\n- Exact case-insensitive equality, OR\n- Case-insensitive `contains` against the allowlist entry\n\nEmail pattern allowlist: any address whose domain matches `example.com`,\n`example.org`, `example.net`, `placeholder.com`, or starts with `noreply@`.\n\n### Tier 2 user interaction\n\nWhen Tier 2 finds matches, present them in a single batched prompt (NOT one\nper finding — that creates rubber-stamp fatigue). Per-finding format:\n\n```\nPII review (3 findings):\n\n proofs/acceptance.md:42 email [email protected]\n proofs/acceptance.md:48 email [email protected]\n proofs/dogfood.md:108 name Henry Claw\n\nAction:\n [a] Auto-redact all\n [s] Skip all (proceed without redacting)\n [q] Quit and review staging dir at /tmp/.../staging.pre-pii-scrub\n```\n\nPre-scrub copy: before any Tier 1 or Tier 2 mutation runs, copy the staging\ndirectory to `\u003cstaging>.pre-pii-scrub/`. This gives the user a recoverable\ncheckpoint if a redaction was wrong.\n\n### Why warn-by-default\n\nThe first design draft auto-redacted emails (permissive pattern) and warned on\nnames (constrained pattern). Two reviewers independently called this cost-\nasymmetry inverted: false-positive auto-redaction permanently corrupts a\nmanuscript artifact, while false-positive warning costs only a prompt. The\ncorrect policy is the inverse — warn on patterns where any false positive would\nlose information; auto-redact only on vendor-prefix-anchored patterns where the\nfalse-positive rate is structurally near-zero.\n\n### Worked examples\n\n**Example 1: vendor token in a proof file.** Input proof file contains:\n```\nAuthorization: Bearer cal_live_7d8911769f5c3d63811e36d95d873a16\n```\nTier 1 matches `bearer-cal-live`. Auto-redacts to:\n```\nAuthorization: Bearer \u003cREDACTED:cal-live-token>\n```\nNo user prompt.\n\n**Example 2: real attendee in a dogfood report.** Input proof file contains:\n```\nReturned 1 real booking (Henry Claw 15-min meeting, attendee [email protected]).\n```\nTier 2 matches `email` and `name-pattern`. The email's domain (`gmail.com`) is\nnot in the allowlist; \"Henry Claw\" is not in spec-derived terms. Both surface in\nthe batched prompt. User picks `[a]` Auto-redact all → both redacted.\n\n**Example 3: API vocabulary that looks like a name.** Input README contains:\n```\nThe `Event Types` resource lists every bookable meeting type.\n```\nTier 2 `name-pattern` matches \"Event Types\". Spec-derived allowlist includes\n\"Event Types\" (extracted from `tag: \"Event Types\"` in the spec). Match is\nsuppressed. No prompt.\n\n**Example 4: clean staged dir.** No matches in either tier. No prompt, publish\nproceeds.\n\n## Session state cleanup\n\nSession state files (`session-state.json`) contain live browser cookies and auth\ntokens captured during an authenticated browser-sniff run. The containment model\nis **by location**, not by archive-time cleanup: `SESSION_STATE_FILE` (set in\nSKILL.md's \"Run Initialization\") points at\n`${TMPDIR:-/tmp}/printing-press-$(id -u)/session/$RUN_ID/session-state.json`, outside\n`$DISCOVERY_DIR`. The Phase 5.5 archive `cp -r \"$DISCOVERY_DIR\"` therefore cannot\npick it up, regardless of operator action. After the archive completes, the\nPhase 5.5 block also wipes `$SESSION_DIR` so back-to-back runs do not accumulate\nsession state.\n\nA no-op `rm -f \"$DISCOVERY_DIR/session-state.json\"` remains in the archive\nblock as a safety net for in-flight runs carried over from a pre-isolation\nskill version; it is not load-bearing for new runs.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":13692,"content_sha256":"89261c2d5d2238c98bdc7853efd954b84b99e8b8007e26b8c36e9f2829274ab5"},{"filename":"references/setup-checks.md","content":"# Setup Checks\n\nPost-contract checks the skill must run after executing the bash setup contract block in `SKILL.md`. These handle the contract output signals: `[setup-error]`, `[repo-upgrade-available]`, the always-emitted `PRINTING_PRESS_BIN=\u003cabs-path>` and `PRESS_REPO_MODE=\u003ctrue|false>` markers, the global open-agent-skills freshness check, the `min-binary-version` compatibility check, `[upgrade-available]`, `[browser-tools-missing]`, and optional `[binary-shadow]` advisory.\n\nApply these in order. The preamble below runs unconditionally; each numbered section after it is conditional — do nothing if its trigger isn't present.\n\n## Preamble: Capture the absolute binary path (unconditional)\n\nBefore applying any numbered section below, capture the `PRINTING_PRESS_BIN=\u003cabsolute path to the binary>` line the contract emitted to stdout. Every generator invocation referenced anywhere below — including the `version --json` calls in sections 4 and 5 — must be made using that absolute path (substitute the captured value, not the literal `$PRINTING_PRESS_BIN` token). The contract's `export PATH=...` line only affects the single Bash tool call it runs in; later Bash tool calls open fresh shells where bare `cli-printing-press` or legacy bare `printing-press` resolves against the user's default `PATH`, and a stale globally-installed binary (`$HOME/go/bin/cli-printing-press` from an earlier `go install`, a Homebrew copy, etc.) or the public catalog installer can silently shadow the local repo build the contract selected. Using the absolute path eliminates the shadow.\n\nAlso capture `PRESS_REPO_MODE=\u003ctrue|false>`. When it is `true`, the current session is running from a repo checkout/plugin-dir and should use the checkout's skill files, not mutate the user's global skill install as part of this run. When it is `false`, run the global open-agent-skills freshness check in section 3, but treat a missing global open-agent-skills entry as a non-blocking signal that this skill may have been loaded from another install surface.\n\nIf `PRINTING_PRESS_BIN` was emitted as an empty value (`PRINTING_PRESS_BIN=`), the contract was unable to resolve a binary; this should have already been surfaced as `[setup-error]` (handled in section 1 below). Treat an empty value here as a setup-error fallback and stop.\n\nThis rule applies to *all* generator command references in the rest of this document. Where sections below write `cli-printing-press version --json` or similar, read that as shorthand for `\u003cPRINTING_PRESS_BIN> version --json` with the captured value substituted.\n\n## 1. Refusal: missing prerequisite\n\nIf the setup contract output contains a line starting with `[setup-error]`, a required prerequisite is missing (the cli-printing-press binary or the Go toolchain) and the contract has already exited non-zero.\n\n**Stop the skill immediately.** Do not proceed to research, generation, or any other work. Surface the message the contract printed (it includes the exact install command or download URL) verbatim to the user.\n\nThe user must install the missing prerequisite in their terminal before re-running. Do not offer to auto-install — the README's install flow is the source of truth for the binary, and silent auto-install hides failure modes (network, wrong GOPATH, no Go toolchain) inside an opaque skill invocation.\n\n## 2. Interactive repo upgrade prompt\n\nIf the setup contract output contains a line starting with `[repo-upgrade-available]`, parse the follow-up lines:\n\n- `PRESS_REPO_DIR=\u003cabsolute repo path>`\n- `PRESS_REPO_HEAD=\u003ccurrent HEAD sha>`\n- `PRESS_REPO_MAIN=\u003corigin/main sha>`\n\nThen ask the user via `AskUserQuestion` before continuing setup:\n\n- **question:** `\"origin/main has newer Printing Press changes. Pull the latest main now? After this, reload the skill with /reload-plugin.\"`\n- **header:** `\"Update repo\"`\n- **multiSelect:** `false`\n- **options:**\n 1. **Yes — pull main** — `\"Run git pull --ff-only origin main in the Printing Press repo, then stop so you can reload the skill.\"`\n 2. **Skip — keep current checkout** — `\"Continue with the current checkout.\"`\n\nIf the user picks **Yes**, run:\n\n```bash\ngit -C \"$PRESS_REPO_DIR\" pull --ff-only origin main\n```\n\nAfter it completes, tell the user:\n\n> \"Updated the Printing Press checkout. Run `/reload-plugin`, then re-run `/printing-press` so the refreshed skill and rebuilt local binary are used.\"\n\nThen stop the skill immediately. Do not continue the current run, because the skill text that is executing may now be stale.\n\nIf the pull fails, surface the failure to the user and continue with the current checkout. Do not attempt a non-fast-forward merge, rebase, reset, stash, or branch switch from the skill preflight.\n\nIf the user picks **Skip**, record the skipped target SHA so the same update is not prompted again:\n\n```bash\nPRESS_HOME=\"${PRINTING_PRESS_HOME:-$HOME/printing-press}\"\nmkdir -p \"$PRESS_HOME\"\nprintf \"last_check=%s\\nmode=repo\\nskipped_repo_main=%s\\n\" \"$(date +%s)\" \"$PRESS_REPO_MAIN\" > \"$PRESS_HOME/.version-check\"\n```\n\nPrompt again only when `origin/main` advances to a different SHA.\n\nIf no `[repo-upgrade-available]` line was emitted, skip this section entirely.\n\n## 3. Global open-agent-skills freshness check\n\nIf `PRESS_REPO_MODE=true`, skip this section entirely. The repo checkout/plugin-dir is the source of truth for skill files in that mode, and section 2 already handles updating the checkout from `origin/main`.\n\nIf `PRESS_REPO_MODE=false`, run the targeted global open-agent-skills updater before continuing:\n\n```bash\n# PRINTING_PRESS_SKILL_UPDATE_START\nnpx -y skills@latest update -g \\\n printing-press \\\n printing-press-amend \\\n printing-press-catalog \\\n printing-press-import \\\n printing-press-output-review \\\n printing-press-polish \\\n printing-press-publish \\\n printing-press-reprint \\\n printing-press-retro \\\n printing-press-score\n# PRINTING_PRESS_SKILL_UPDATE_END\n```\n\nInterpret the output as follows:\n\n- If it reports `✓ Updated N skill(s)` with `N > 0`, stop immediately. Tell the user:\n\n > \"Updated N Printing Press skill(s) on disk. This agent session may still have the old skill text loaded. Restart the agent session, then re-run `/printing-press` before continuing.\"\n\n Do not proceed to research, generation, scoring, publishing, or any other workflow after a skill update.\n- If it reports `All global skills are up to date` or otherwise completes without an updated-skill summary, continue.\n- If it reports `No installed skills found matching: ...`, continue without blocking. The current skill is already running, so absence from the global open-agent-skills registry usually means this session was loaded from another install surface, such as the Claude Code plugin/marketplace channel, a project-scoped skill install, or a local plugin directory. Do not tell the user to reinstall through `npx skills` as a prerequisite. If they explicitly ask how to move to the global open-agent-skills install path, give them the skills-only installer command so they do not have to name individual skills:\n\n ```bash\n curl -fsSL https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/scripts/install.sh | bash -s -- --skills-only\n ```\n\n Then tell them to restart the agent session.\n- If it reports one or more `Failed to update ...` lines or exits non-zero, stop and surface the failure. For manual repair, tell the user to run the skills-only installer command below, then restart the agent session. Do not continue with potentially mixed skill files.\n\n ```bash\n curl -fsSL https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/scripts/install.sh | bash -s -- --skills-only\n ```\n\nThis command mutates global skill files, so never run it silently after user work has started. It belongs in preflight before any user-facing prompt.\n\n## 4. Min-binary-version compatibility\n\nCheck binary version compatibility against the skill's declared minimum. Read the `min-binary-version` field from the skill's YAML frontmatter. Run `\u003cPRINTING_PRESS_BIN> version --json` (using the absolute path captured in the preamble — not bare `cli-printing-press` or legacy bare `printing-press`, which would resolve against the user's default `PATH` and could interrogate a stale global or the public catalog installer) and parse the version from the output. Compare it to `min-binary-version` using semver rules.\n\nIf the installed binary is older than the minimum, stop the skill immediately and tell the user:\n\n> \"cli-printing-press binary vX.Y.Z is older than the minimum required vA.B.C. Run `go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest` to update.\"\n\nDo not proceed to research, scoring, publishing, or any other workflow when the binary is below `min-binary-version`. This is the compatibility floor, not a freshness advisory.\n\n## 5. Interactive standalone binary upgrade prompt\n\nIf the setup contract output contains a line starting with `[upgrade-available]`, parse the two follow-up lines for the version values:\n\n- `PRESS_UPGRADE_AVAILABLE=\u003clatest>`\n- `PRESS_UPGRADE_INSTALLED=\u003cinstalled>`\n\nThen ask the user via `AskUserQuestion` before continuing setup:\n\n- **question:** `\"printing-press v\u003clatest> is available (you have v\u003cinstalled>). Upgrade now? Takes about 10 seconds.\"`\n- **header:** `\"Update available\"`\n- **multiSelect:** `false`\n- **options:**\n 1. **Yes — upgrade now** — `\"Run go install and use the latest released binary for this session.\"`\n 2. **Skip — keep current version** — `\"Continue with the current binary.\"`\n\nIf the user picks **Yes**, run:\n\n```bash\ngo install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest\n```\n\nAfter `go install` completes, **re-resolve `PRINTING_PRESS_BIN`** before confirming. `go install` writes to `$(go env GOBIN)` if set, otherwise `$(go env GOPATH)/bin` — which may not be the same path the contract originally captured (e.g. when the pre-upgrade binary was the legacy `/opt/homebrew/bin/printing-press` or `/usr/local/bin/printing-press`, the new binary lives at `$GOPATH/bin/cli-printing-press` and the old one is unchanged). Run this re-resolution in a single Bash call so its stdout becomes the new captured value:\n\n```bash\n_gobin=\"$(go env GOBIN 2>/dev/null)\"\n[ -z \"$_gobin\" ] && _gobin=\"$(go env GOPATH 2>/dev/null)/bin\"\nif [ -x \"$_gobin/cli-printing-press\" ]; then\n echo \"PRINTING_PRESS_BIN=$_gobin/cli-printing-press\"\nelif command -v cli-printing-press >/dev/null 2>&1; then\n echo \"PRINTING_PRESS_BIN=$(command -v cli-printing-press)\"\nelif [ -x \"$_gobin/printing-press\" ] && \"$_gobin/printing-press\" version --json >/dev/null 2>&1; then\n echo \"PRINTING_PRESS_BIN=$_gobin/printing-press\"\nelse\n echo \"PRINTING_PRESS_BIN=$(command -v cli-printing-press 2>/dev/null || true)\"\nfi\n```\n\nCapture the new `PRINTING_PRESS_BIN=\u003cabs-path>` value and use it for every subsequent generator invocation in the rest of this run, overriding the value captured in the preamble. Then confirm with `\u003cPRINTING_PRESS_BIN> version --json` and tell the user `\"Upgraded to v\u003cnew>.\"` **Continue this current setup run with the freshly installed binary on disk — do not stop, do not reload the session, do not skip the remaining checks (min-binary-version compatibility, etc.).** Skill freshness was already handled by section 3, so this binary-only update does not require a session restart.\n\nIf the upgrade command fails (network error, auth error, etc.), surface the failure to the user and continue with the current binary — do not block the run on a failed upgrade. The user can re-run later.\n\nIf no `[upgrade-available]` line was emitted, skip this section entirely.\n\n## 6. Interactive browser-sniff backend install prompt\n\nIf the setup contract output contains a line starting with `[browser-tools-missing]`, parse the follow-up lines:\n\n- `PRESS_BROWSER_USE_MISSING=\u003ctrue|false>`\n- `PRESS_AGENT_BROWSER_MISSING=\u003ctrue|false>`\n\nThen ask the user via `AskUserQuestion` before continuing setup. The prompt fires every run when either tool is missing — there is no decline cache. Re-prompting is intentional: browser-use and agent-browser are the preferred Phase 1.7 backends, and mid-flight install gates during generation are more disruptive than one short preflight prompt.\n\n- **question** (compose based on which are missing — pick the matching row):\n - Both missing: `\"browser-use and agent-browser are not installed. These are the preferred Phase 1.7 browser-sniff backends — broadly useful for future runs and avoids mid-flight install prompts. (chrome-MCP is a narrow-case fallback, not a substitute.) Install now?\"`\n - Only `browser-use` missing: `\"browser-use is not installed. It is the preferred Phase 1.7 browser-sniff primary backend — broadly useful for future runs and avoids mid-flight install prompts. Install now?\"`\n - Only `agent-browser` missing: `\"agent-browser is not installed. It is the secondary browser-sniff backend (used for cookie capture from running Chrome) — broadly useful for future runs and avoids mid-flight install prompts. Install now?\"`\n- **header:** `\"Browser-sniff backends\"`\n- **multiSelect:** `false`\n- **options:** compose based on which are missing — see below.\n\n**Option composition.**\n\n- Both missing → (1) **Install both** (Recommended), (2) **Install browser-use only**, (3) **Install agent-browser only**, (4) **Skip for this run**.\n- Only `browser-use` missing → (1) **Install browser-use** (Recommended), (2) **Skip for this run**.\n- Only `agent-browser` missing → (1) **Install agent-browser** (Recommended), (2) **Skip for this run**.\n\n**Install commands.**\n\nFor `browser-use`:\n\n```bash\n# Use `uv tool install` (not `uv pip install`). `uv pip install` targets the\n# active venv and won't put the binary in PATH outside it; `uv tool install`\n# creates an isolated env and symlinks the entry-point into `~/.local/bin`.\nif command -v uv >/dev/null 2>&1; then\n uv tool install browser-use\nelif command -v pip >/dev/null 2>&1; then\n pip install browser-use\nelse\n echo \"Neither uv nor pip found. Install Python first: https://www.python.org/downloads/\"\nfi\n```\n\nFor `agent-browser`:\n\n```bash\nif command -v brew >/dev/null 2>&1; then\n brew install agent-browser\nelif command -v npm >/dev/null 2>&1; then\n npm install -g agent-browser\nelse\n echo \"Neither brew nor npm found. Install Node.js first: https://nodejs.org/\"\nfi\n```\n\nAfter installing `agent-browser` through brew or npm, complete its browser-binary setup as a user-run step:\n\n```text\n! agent-browser install\n```\n\nThe leading `!` is intentional: surface the command for the user to run manually instead of invoking it through the agent's shell tool. Some harness classifiers block installer subcommands from a newly installed tool when the agent runs them directly. Do not treat `command -v agent-browser` alone as a complete install after the package-manager step; the `agent-browser install` step must complete before browser-sniff flows rely on it. Only do this post-install step when this section just installed `agent-browser`; if `PRESS_AGENT_BROWSER_MISSING=false`, skip redundant setup for the already-present binary. This preflight does not launch agent-browser to prove browser-cache readiness for pre-existing installs; if a later browser-sniff step reports missing browser binaries, surface `! agent-browser install` then and use a fallback backend until the user confirms it completed.\n\nAfter install, verify `browser-use` with `command -v browser-use`. If this section just installed `agent-browser`, verify it with both `command -v agent-browser` and confirmation that the user-run `agent-browser install` step completed. If the user declines the manual step, it fails, or completion is unclear, do not run it through the agent shell; surface the incomplete setup and continue without treating `agent-browser` as available for browser-sniff. If `PRESS_AGENT_BROWSER_MISSING=false`, do not require post-install confirmation for the already-installed binary. Then confirm successful installs to the user: `\"Installed \u003ctool>.\"` **Continue this current setup run with the newly available tools — do not stop, do not skip the remaining checks (min-binary-version compatibility, etc.).**\n\nIf an install command fails (no Python, no Node.js, network error), surface the failure to the user and continue without the missing backend. Do not block the run on a failed install — runs using vendor specs, `--spec`, or `--har` do not need these tools, and the lazy Step 1b prompt in `browser-sniff-capture.md` remains as a fallback if browser-sniff is later invoked.\n\nIf the user picks **Skip for this run**, continue without prompting further this run. The decision is not cached — the prompt re-fires on the next run if the tool is still missing.\n\nIf no `[browser-tools-missing]` line was emitted, skip this section entirely.\n\n## 7. Optional shadow advisory\n\nIf the setup contract output contains a line starting with `[binary-shadow]`, parse the follow-up lines:\n\n- `PRESS_BIN_LOCAL_VERSION=\u003cversion reported by the local build>`\n- `PRESS_BIN_GLOBAL_VERSION=\u003cversion reported by the differing global on PATH>`\n- `PRESS_BIN_GLOBAL_PATH=\u003cabsolute path to the differing global>`\n\nSurface a single-line note to the user before continuing — informational only, do not prompt:\n\n> \"Note: a global printing-press v`\u003cglobal>` is installed at `\u003cpath>` but the local repo build is v`\u003clocal>`. This run will use the local build (the absolute path the preflight selected); the global is unchanged.\"\n\nThen continue. Do not modify or remove the global. The note exists so the user can reconcile the divergence on their own time (typically with `go install ...@latest` once they want the new version everywhere).\n\nIf no `[binary-shadow]` line was emitted, skip the advisory and continue.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":17809,"content_sha256":"4912fe536e5d97faa710300dc28c8c82fb92234cba508321652c8290597a3906"},{"filename":"references/spec-format.md","content":"# Internal YAML Spec Format Reference\n\nUse this format when no OpenAPI spec is available.\n\n## 1. Complete Schema Reference\n\n```yaml\n# Root object (APISpec)\nname: my-api # string (REQUIRED) CLI binary prefix, e.g. \"my-api\"\ndescription: \"My API CLI\" # string shown in command help\nversion: \"0.1.0\" # string baked into generated binary\nbase_url: \"https://api.example.com/v1\" # string (REQUIRED) default base API URL\nhttp_transport: standard # string optional: standard | browser-http | browser-chrome | browser-chrome-h3\nhealth_check_path: \"/health\" # string optional doctor reachability path; defaults to /\nrequired_headers: # []RequiredHeader optional headers sent on every request\n - name: User-Agent\n value: \"Mozilla/5.0 ...\"\n\nauth: # object (AuthConfig)\n type: api_key # string: api_key | oauth2 | oauth2_refresh | bearer_token | none\n header: \"Authorization\" # string header name to set\n format: \"Bearer {token}\" # string format template for auth header value\n oauth2_grant: device_code # string optional: authorization_code | client_credentials | device_code\n device_authorization_url: \"https://login.example.com/device\" # required for device_code\n token_url: \"https://login.example.com/token\" # OAuth token/refresh endpoint\n scopes: [\"read\"] # []string optional OAuth scopes\n default_client_id: \"public-client-id\" # string optional public OAuth client id\n env_vars: # []string env vars used for auth material\n - EXAMPLE_API_TOKEN\n scheme: bearerAuth # string optional OpenAPI security scheme name\n in: header # string optional: header | query | cookie\nauth_warnings: # []string optional sniffed-auth rejection notes\n\nconfig: # object (ConfigSpec)\n format: toml # string config format: toml | yaml (other values fall back to json tags)\n path: \"~/.config/my-api/config.toml\" # string config file path\n\nresources: # map[string]Resource (REQUIRED: at least one key)\n users: # resource key becomes top-level command: \u003cname>-cli users\n description: \"Manage users\" # string resource help text\n base_url: \"https://directory.example.com/v1\" # string optional override for this resource and inherited sub-resources\n endpoints: # map[string]Endpoint (REQUIRED: at least one key)\n list: # endpoint key becomes subcommand: users list\n method: GET # string (REQUIRED) must be one of GET | POST | PUT | DELETE\n path: \"/users\" # string (REQUIRED) API path; supports {param} placeholders\n base_url: \"https://search.example.com/v1\" # string optional override for this endpoint only\n description: \"List users\" # string endpoint help text\n params: # []Param query/path parameters\n - name: limit # string upstream wire key; request serialization always uses this value\n flag_name: page-size # string optional public CLI/MCP/docs name; agent-authored from evidence\n aliases: [] # []string optional hidden compatibility flag spellings\n type: int # string type: string | int | bool | float\n required: false # bool whether Cobra marks the flag required\n positional: false # bool true => consumes positional CLI arg and fills {name} in path\n default: 100 # any default value (type should match param type)\n description: \"Max results\" # string flag description\n fields: [] # []Param nested fields for object-like params\n enum: [] # []string optional enum hints/constraints\n format: \"\" # string optional format hint (date-time, email, uri, etc.)\n body: # []Param request body fields, or object schema with properties\n - name: email\n # flag_name and aliases are optional here too; omit unless evidence supports them\n type: string\n required: true\n positional: false\n default: null\n description: \"User email\"\n fields: []\n enum: []\n format: email\n # Alternative object-schema form for richer JSON bodies:\n # body:\n # properties:\n # query:\n # type: string\n # required: true\n # variables:\n # type: object\n # serializerSettings:\n # type: object\n # properties:\n # includeNulls:\n # type: bool\n # queries:\n # type: array\n # items:\n # type: object\n # properties:\n # query:\n # type: string\n response: # object (ResponseDef)\n type: array # string response shape: object | array\n item: User # string type name referenced from `types`\n pagination: # object (Pagination) optional\n type: cursor # string pagination style: cursor | offset | page_token\n cursor_field: cursor # string response field containing next cursor\n has_more_field: data.has_more # string response field indicating more results\n response_format: json # string optional: json | csv | html | binary; defaults to json\n html_extract: # object optional, only with response_format: html\n mode: page # string optional: page | links | embedded-json\n link_prefixes: [] # []string optional for links; path-segment-anchored prefixes\n script_selector: \"\" # string optional for embedded-json; defaults to script#__NEXT_DATA__\n json_path: \"\" # string optional for embedded-json; empty returns the full JSON\n response_path: data # string optional path to extract list payload from wrapper response\n\ntypes: # map[string]TypeDef named response/body models\n User: # type name referenced by response.item\n fields: # []TypeField\n - name: user_id # string field name\n type: string # string field type (typically string/int/bool/float)\n```\n\nFor OAuth2 refresh-token rotation without an interactive browser flow, use\n`auth.type: oauth2_refresh` with `auth.token_url`. When `env_vars` is omitted,\nthe generator defaults to `\u003cAPI>_CLIENT_ID`, `\u003cAPI>_CLIENT_SECRET`, and\n`\u003cAPI>_REFRESH_TOKEN`; access tokens are refreshed automatically before API\ncalls.\n\n**`response_format` must be one of `json`, `csv`, `html`, or `binary`.** Use `json`\nwhen the response body is JSON and can be parsed directly. Use `html` only for\nGET/HEAD HTML documents, including HTML pages with embedded JSON such as\nNext.js `__NEXT_DATA__` or schema.org JSON-LD; prefer `html_extract` modes\n`page`, `links`, or `embedded-json` before writing custom extraction code. Use\n`csv` for CSV responses that novel commands may parse through\n`cliutil.ParseCSV`, and `binary` for opaque byte payloads.\n\n**`html_extract.link_prefixes` are path-segment anchored.** In `mode: links`, a\nprefix such as `/items` keeps links whose path is exactly `/items` or starts\nwith `/items/`. It does not keep `/items123.html`, `/items-archive`, or other\nsame-string-prefix leaf paths where the next character is not `/`.\n\nThe one exception is `/@`, which uses simple string-prefix matching so\nsocial-media-style handle paths such as `/@alice` and `/@bob` are kept.\n\nTo keep all links under a subtree regardless of the leaf segment shape, choose\nthe parent directory as the prefix. For paths like `/items/123.html` and\n`/items/456.html`, use `link_prefixes: [\"/items\"]`. Do not use a partial leaf\nprefix such as `/items/1` unless the target path is exactly `/items/1` or has a\nslash boundary after it.\n\n**`types.X.fields` is a list, not a map.** Each field is an item with\n`- name: \u003cfield-name>` followed by `type:`, `description:`, and other field\nmetadata. Map shape such as `field-name: {type: string}` fails to parse with\n`cannot unmarshal !!map into []spec.TypeField`.\n\n## 2. Annotated Example (`testdata/stytch.yaml`)\n\n```yaml\nname: stytch # CLI binary prefix => stytch-cli\ndescription: \"Stytch authentication API CLI\" # Root help text and README summary\nversion: \"0.1.0\" # Printed by `stytch-cli version`\nbase_url: \"https://api.stytch.com/v1\" # Default base URL endpoint paths are joined against\nhealth_check_path: \"/sessions\" # Optional doctor reachability path; omit to probe /\n\nauth:\n type: api_key # Uses API key style auth\n header: \"Authorization\" # Header key set on outgoing requests\n format: \"Basic {project_id}:{secret}\" # Expected auth value format\n env_vars:\n - STYTCH_PROJECT_ID # Credential source env var #1\n - STYTCH_SECRET # Credential source env var #2\n\nconfig:\n format: toml # Generated config struct tags use TOML\n path: \"~/.config/stytch-cli/config.toml\" # Default config file location\n\nresources:\n users: # Creates `stytch-cli users ...`\n description: \"Manage Stytch users\"\n endpoints:\n list: # Creates `stytch-cli users list`\n method: GET # Generates a query-parameter style command\n path: \"/users\"\n description: \"List all users\"\n params:\n - name: limit # Exposed as `--limit`\n type: int\n default: 100 # Default flag value\n description: \"Max users to return\"\n - name: cursor # Exposed as `--cursor`\n type: string\n description: \"Pagination cursor\"\n response:\n type: array # Command expects a list-like response\n item: User # Rows map to `types.User`\n pagination:\n type: cursor # Enables cursor pagination helpers\n cursor_field: \"cursor\" # Field that contains next cursor token\n has_more_field: \"results.has_more\" # Field used to detect continuation\n\n get: # Creates `stytch-cli users get \u003cuser_id>`\n method: GET\n path: \"/users/{user_id}\" # Placeholder filled from positional arg\n description: \"Get a user by ID\"\n params:\n - name: user_id\n type: string\n required: true\n positional: true # Required so CLI arg is mapped into `{user_id}`\n description: \"User ID\"\n response:\n type: object\n item: User\n\n create: # Creates `stytch-cli users create --email ...`\n method: POST # Generates body-field flags\n path: \"/users\"\n description: \"Create a new user\"\n body:\n - name: email\n type: string\n description: \"User email\"\n - name: phone_number\n type: string\n description: \"User phone number\"\n response:\n type: object\n item: User\n\n delete: # Creates `stytch-cli users delete \u003cuser_id>`\n method: DELETE\n path: \"/users/{user_id}\"\n params:\n - name: user_id\n type: string\n required: true\n positional: true\n description: \"User ID\"\n\n sessions: # Creates `stytch-cli sessions ...`\n description: \"Manage user sessions\"\n endpoints:\n list: # Creates `stytch-cli sessions list --user_id ...`\n method: GET\n path: \"/sessions\"\n description: \"List sessions for a user\"\n params:\n - name: user_id\n type: string\n required: true\n description: \"User ID\"\n response:\n type: array\n item: Session\n\n revoke: # Creates `stytch-cli sessions revoke --session_id ...`\n method: POST\n path: \"/sessions/revoke\"\n description: \"Revoke a session\"\n body:\n - name: session_id\n type: string\n required: true\n description: \"Session ID to revoke\"\n\ntypes:\n User: # Referenced by response.item: User\n fields:\n - name: user_id\n type: string\n - name: email\n type: string\n - name: phone_number\n type: string\n - name: status\n type: string\n - name: created_at\n type: string\n\n Session: # Referenced by response.item: Session\n fields:\n - name: session_id\n type: string\n - name: user_id\n type: string\n - name: started_at\n type: string\n - name: expires_at\n type: string\n```\n\n## 3. Public Parameter Names\n\n`name` is the upstream wire key by default and the parameter's public identity\nwhen no override is set. The generator uses it for path substitution and, unless\n`url_name` or `body_name` says otherwise, query strings and request-body keys.\nDo not change `name` just to make a prettier CLI.\n\n`url_name` is an optional query-string wire override. Use it when the CLI/MCP\ninput should keep the `name` spelling but the URL key must differ.\n\n`body_name` is an optional request-body wire override. Use it when the CLI/MCP\ninput should keep the `name` spelling but the JSON, form, or multipart body key\nmust differ.\n\n`flag_name` is the preferred public name shown in generated CLI flags, examples,\ntyped MCP schemas, and `tools-manifest.json`. Add it only when source evidence\nmakes the meaning clear. Valid values are lowercase kebab-case.\n\n`aliases` are accepted Cobra flag spellings for compatibility. They bind to the\nsame backing variable as `flag_name` and are hidden from generated help. Do not\ncopy raw wire keys into `aliases` unless they are already valid lowercase\nkebab-case public flags.\n\nExample:\n\n```yaml\nparams:\n - name: s\n flag_name: address\n aliases: [s]\n type: string\n required: true\n description: Street address\n - name: c\n flag_name: city\n aliases: [c]\n type: string\n required: true\n description: City, state, zip\n```\n\nHere `--address` and `--city` are the generated public names, `--s` and `--c`\nremain compatibility aliases, and requests still send upstream keys `s` and `c`.\n\nFor body fields where the public cursor name and accepted body key diverge,\nkeep the public identity in `name` and set `body_name` to the observed wire key:\n\n```yaml\nbody:\n - name: startAfter\n body_name: searchAfter\n type: array\n description: Pagination cursor\n```\n\nFor richer JSON bodies, `body` may instead be an object schema with\n`properties`. The parser accepts either `body.properties` directly or a\n`body.schema.properties` wrapper when copying from OpenAPI-like notes:\n\n```yaml\nbody:\n properties:\n query:\n type: string\n required: true\n description: GraphQL document\n variables:\n type: object\n description: GraphQL variables JSON\n serializerSettings:\n type: object\n properties:\n includeNulls:\n type: bool\n queries:\n type: array\n items:\n type: object\n properties:\n query:\n type: string\n```\n\nTop-level scalars become typed flags. Object properties with their own\n`properties` become nested, parent-prefixed flags. Object and array properties\nwithout expandable scalar children remain JSON-string flags so the command can\npass nested payloads without hand-written Go.\n\n## 4. Validation Rules\n\nValidation in `spec.Validate()` enforces:\n\n- `name` is required\n- root `base_url` is required unless `base_path` is supplied\n- at least one `resources` entry is required\n- every resource must have at least one endpoint\n- every endpoint must have both `method` and `path`\n- `resources.\u003cname>.base_url` is allowed for resources that live on another host; sub-resources inherit the parent override unless they set their own `base_url`\n- `resources.\u003cname>.endpoints.\u003cname>.base_url` is allowed for a single endpoint that lives on another host; it wins over resource and sub-resource overrides\n- resource or endpoint `base_url` overrides cannot be combined with `client_pattern: proxy-envelope`, because proxy-envelope clients POST every request to the root `base_url`\n- `flag_name` and `aliases` must be lowercase kebab-case, non-empty when present, and collision-free within their command surface\n\n## 5. Common Mistakes\n\nThese commonly cause generation/build failures or incorrect CLI behavior:\n\n- Missing required fields (`name`, root `base_url`, resource endpoints, endpoint `method`, endpoint `path`)\n- Invalid `method` values (generator templates only handle `GET`, `POST`, `PUT`, `DELETE`)\n- Missing `path` on endpoints\n- Defining `body` params on `GET` endpoints (allowed in YAML, but ignored by GET command generation)\n- Forgetting `positional: true` for params used in `/{path_placeholders}`\n- Using parameter types outside supported scalar set: `string`, `int`, `bool`, `float`\n- Putting a website/feed host in the root `base_url` just to make one endpoint work; keep the root API host as the default and use a resource or endpoint `base_url` override for the outlier surface\n\n## 5. Type Mapping\n\n| YAML Type | Go Type | Cobra Flag | Zero Value |\n|-----------|---------|------------|------------|\n| `string` | `string` | `StringVar` | `\"\"` |\n| `int` | `int` | `IntVar` | `0` |\n| `bool` | `bool` | `BoolVar` | `false` |\n| `float` | `float64` | `Float64Var` | `0.0` |\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":17448,"content_sha256":"242959eaf970ebd8717e0710fc7f73ead55da7e4ddc7201e2567a01744085eae"},{"filename":"references/ws-primary-pattern.md","content":"# WebSocket-Primary Sync Pattern\n\nUse this pattern when the target API's primary facts arrive over WebSocket and a REST endpoint supplies descriptive metadata needed for local queries.\n\n## Spec Shape\n\n```yaml\nstreaming:\n transport: websocket\n url: \"wss://api.example.com/v1/ws\"\n subscribe_shape: '{\"type\":\"subscribe\",\"channels\":[\"events\"]}'\n framing: newline_delimited_json\n metadata:\n endpoint: \"/v1/events\"\n refresh_cadence: 30s\n statuses: [live, pending]\n primary_key: event_id\n```\n\n`framing` may be `single_object_per_frame` or `newline_delimited_json`. When `metadata.statuses` is omitted, the generator polls both `live` and `pending`.\n\n## Emitted Surface\n\nThe generator emits:\n\n- `live ws sync` for WebSocket-primary ingest.\n- `live rest sync` as the REST polling fallback, reusing the generated `sync` command.\n- `internal/wsclient` with dial, subscribe, frame splitting, reconnect-with-backoff, and lifecycle event callbacks.\n- Local SQLite tables `\u003capi>_stream_frames`, `\u003capi>_stream_metadata`, and `\u003capi>_rebase_log`.\n\nThe WebSocket scaffold stores raw JSON facts and raw metadata rows. Per-API novel code may add typed normalizers beside the generated files, but it should not reimplement the WebSocket lifecycle, metadata-status polling, or rebase-log mechanics.\n\n## Authoring Rules\n\n- Poll every configured metadata status. Default to both `live` and `pending`; polling only `live` misses rows that become live after the frame arrives.\n- Use `newline_delimited_json` whenever a vendor can send multiple JSON objects in one WebSocket message. The generated splitter feeds each line separately to `json.Unmarshal`.\n- Record reconnect, disconnect, subscribe, metadata, and parse events in `\u003capi>_rebase_log` so operators can diagnose stream gaps.\n- Coordinate store writes through the generated live command's shared mutex. Per-API handlers that write additional dimension or fact tables should reuse that pattern.\n- Frame normalizers must use `cliutil.ExtractNumber` and `cliutil.ExtractInt` for numeric wire fields that may be JSON strings.\n","content_type":"text/markdown; charset=utf-8","language":"markdown","size":2071,"content_sha256":"6886a7391a8bb400b20e5a326d086035ca0769f7279aad4a50ab7ab84d1b4614"}],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"/printing-press","type":"text"}]},{"type":"paragraph","content":[{"text":"Generate the best useful CLI for an API without burning an hour on phase theater.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"/printing-press Notion\n/printing-press Discord codex\n/printing-press --spec ./openapi.yaml\n/printing-press --har ./capture.har --name MyAPI\n/printing-press https://postman.com/explore\n/printing-press https://postman.com","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"What Changed In v2","type":"text"}]},{"type":"paragraph","content":[{"text":"The old skill inflated the path to ship:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"too many mandatory research documents before code existed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"too many separate late-stage validation phases after code existed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"too many chances to discover obvious failures late","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This version uses one lean loop:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve the spec and write one research brief","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build the highest-value gaps","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run one shipcheck block","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optionally run live API smoke tests","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Artifacts are still written, but only the ones that materially help the next step.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Modes","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Default","type":"text"}]},{"type":"paragraph","content":[{"text":"Normal mode. Claude does research, generation orchestration, implementation, and verification.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Codex Mode","type":"text"}]},{"type":"paragraph","content":[{"text":"If the arguments include ","type":"text"},{"text":"codex","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"--codex","type":"text","marks":[{"type":"code_inline"}]},{"text":", offload pure code-writing tasks to Codex CLI.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use Codex for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"writing store/data-layer code","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"writing workflow commands","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fixing dead flags / dead code / path issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"README cookbook edits","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Keep on Claude:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"research and product positioning","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"choosing which gaps matter","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"verification results and ship decisions","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If Codex fails 3 times in a row, stop delegating and finish locally.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Polish Mode (Standalone Skill)","type":"text"}]},{"type":"paragraph","content":[{"text":"For second-pass improvements to an existing CLI, use the standalone polish skill:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"/printing-press-polish redfin","type":"text"}]},{"type":"paragraph","content":[{"text":"See the ","type":"text"},{"text":"printing-press-polish","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill for details. It runs diagnostics, fixes verify failures, removes dead code, cleans up descriptions and README, and offers to publish.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Rules","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not ship a CLI that hasn't been behaviorally tested against real targets.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"go build","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" pass-rate are structural signals, not correctness signals. Phase 5's mechanical test matrix runs every subcommand + ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":" + error paths; if that matrix was not executed, the CLI is not shippable. Quick Check is the floor; Full Dogfood is required when the user asks for thoroughness.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bugs found during dogfood are fix-before-ship, not \"file for v0.2\".","type":"text","marks":[{"type":"strong"}]},{"text":" If a 1-3 file edit resolves it, do it now. ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" is deprecated as a default verdict (see Phase 4). Context is freshest in-session; a v0.2 backlog that may never be revisited ships known-broken CLIs.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Features approved in Phase 1.5 are shipping scope.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not downgrade a shipping-scope feature to a stub mid-build. If implementation becomes infeasible, return to Phase 1.5 with a revised manifest and get explicit re-approval.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not quote human-time estimates for sub-tasks","type":"text","marks":[{"type":"strong"}]},{"text":" (\"~15-30 min\", \"~1 hour\", \"quick fix\") in ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" options, phase descriptions, or reference docs. The agent does the work, not the user; agent-fabricated estimates are notoriously bad and train users to distrust the prompt. Describe scope instead (lines of code, files touched, relative size). The carve-outs are wall-clock estimates for genuinely time-bound things: the whole-CLI run (set the user's expectation up front — most CLIs take 30+ minutes), tool installs (","type":"text"},{"text":"go install","type":"text","marks":[{"type":"code_inline"}]},{"text":" takes ~10 seconds), and printing-press subcommands that do network-bound work (crowd-sniff scans npm + GitHub, ~5-10 minutes). Anything bounded by agent reasoning time is not time-bound — describe scope.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use raw captures for contract research.","type":"text","marks":[{"type":"strong"}]},{"text":" When reading official docs, auth/error/rate-limit pages, endpoint references, OpenAPI/Postman links, or source pages whose exact identifiers affect the generated CLI, read ","type":"text"},{"text":"references/fetch-docs.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fetch-docs.md","title":null}}]},{"text":" and use its ","type":"text"},{"text":"fetch-docs.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" helper. Reserve ","type":"text"},{"text":"WebFetch","type":"text","marks":[{"type":"code_inline"}]},{"text":" for quick TL;DR reads where losing field-level details is acceptable.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Optimize for time-to-ship, not time-to-document.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reuse prior research whenever it is already good enough.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not split one idea across multiple mandatory artifacts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Durable files produced by this skill go under ","type":"text"},{"text":"$PRESS_RUNSTATE/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (working state) or ","type":"text"},{"text":"$PRESS_MANUSCRIPTS/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (archived). Short-lived command captures may use ","type":"text"},{"text":"/tmp/printing-press/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and must be removed after use.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not create a separate narrative phase for dogfood, dead-code audit, runtime verification, and final score. Treat them as one shipcheck block.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run cheap, high-signal checks early.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Fix blockers and high-leverage failures first.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reuse the same spec path across ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"verify","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"scorecard","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"YAML, JSON, local paths, and URLs are all valid spec inputs for the verification tools.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Maximum 2 verification fix loops unless the user explicitly asks for more.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Secret & PII Protection (Cardinal Rules)","type":"text"}]},{"type":"paragraph","content":[{"text":"These rules are non-negotiable. They apply at ALL times during a run.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"API key ","type":"text"},{"text":"values","type":"text","marks":[{"type":"strong"}]},{"text":", token ","type":"text"},{"text":"values","type":"text","marks":[{"type":"strong"}]},{"text":", passwords, and session cookies must NEVER appear in any artifact: source code, manuscripts, proofs, READMEs, HARs, or anything committed to git. Env var ","type":"text"},{"text":"names","type":"text","marks":[{"type":"strong"}]},{"text":" (e.g., ","type":"text"},{"text":"STEAM_API_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":") and placeholders (e.g., ","type":"text"},{"text":"\"your-key-here\"","type":"text","marks":[{"type":"code_inline"}]},{"text":") are safe.","type":"text"}]},{"type":"paragraph","content":[{"text":"During Phase 5.6 (archiving) and before publishing, read and apply ","type":"text"},{"text":"references/secret-protection.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/secret-protection.md","title":null}}]},{"text":" for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Exact-value scanning and auto-redaction of artifacts","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"HAR auth stripping (headers, query strings, cookies)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"API key handling rules during the run","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Session state cleanup ordering","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Preflight","type":"text"}]},{"type":"paragraph","content":[{"text":"This section MUST run before any user-facing prompt — including the Orientation and Briefing flow below.","type":"text","marks":[{"type":"strong"}]},{"text":" A missing binary or available upgrade is information the user needs ","type":"text"},{"text":"before","type":"text","marks":[{"type":"em"}]},{"text":" they commit to an API. Do not invoke ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":", print the orientation prose, or otherwise engage the user until preflight has completed and any signals from ","type":"text"},{"text":"references/setup-checks.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" have been handled.","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003c!-- PRESS_SETUP_CONTRACT_START -->","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# min-binary-version: 4.0.0\n\n# Derive scope first — needed for local build detection\n_scope_dir=\"$(git rev-parse --show-toplevel 2>/dev/null || echo \"$PWD\")\"\n_scope_dir=\"$(cd \"$_scope_dir\" && pwd -P)\"\n\n_press_repo=false\nif [ -d \"$_scope_dir/cmd/cli-printing-press\" ] && [ -f \"$_scope_dir/go.mod\" ]; then\n _press_repo=true\nfi\n\n_resolve_press_bin() {\n if command -v cli-printing-press >/dev/null 2>&1; then\n command -v cli-printing-press\n return 0\n fi\n if command -v printing-press >/dev/null 2>&1 && printing-press version --json >/dev/null 2>&1; then\n command -v printing-press\n return 0\n fi\n return 1\n}\n\n# Prefer local build when running from inside the printing-press repo.\n# The lefthook build hook keeps ./cli-printing-press current after every commit/pull,\n# so it's always newer than the go-install version.\nif [ \"$_press_repo\" = \"true\" ] && [ -x \"$_scope_dir/cli-printing-press\" ]; then\n export PATH=\"$_scope_dir:$PATH\"\n echo \"Using local build: $_scope_dir/cli-printing-press\"\nelif ! _resolve_press_bin >/dev/null; then\n # Augment PATH if the binary is in ~/go/bin but not on the user's interactive PATH.\n if [ -x \"$HOME/go/bin/cli-printing-press\" ]; then\n export PATH=\"$HOME/go/bin:$PATH\"\n elif [ -x \"$HOME/go/bin/printing-press\" ] && \"$HOME/go/bin/printing-press\" version --json >/dev/null 2>&1; then\n export PATH=\"$HOME/go/bin:$PATH\"\n else\n # Refuse: the cli-printing-press binary is required and we will not auto-install\n # it. The README's install flow is the source of truth;\n # silent auto-install hides failure modes (network, wrong GOPATH) inside an\n # opaque skill invocation.\n echo \"\"\n echo \"[setup-error] cli-printing-press binary not found.\"\n echo \"\"\n if command -v go >/dev/null 2>&1; then\n echo \"Install it in your terminal:\"\n echo \" go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest\"\n else\n echo \"Go 1.26.3 or newer is also not installed. Install Go from https://go.dev/dl/, then:\"\n echo \" go install github.com/mvanhorn/cli-printing-press/v4/cmd/cli-printing-press@latest\"\n fi\n echo \"\"\n echo \"Verify with: cli-printing-press --version\"\n echo \"Then re-run /printing-press.\"\n return 1 2>/dev/null || exit 1\n fi\nfi\n\n# Verify the Go toolchain is on PATH. Generation runs Go-based quality gates\n# (go mod tidy, go vet, etc.) after writing thousands of lines of scaffolding,\n# so a missing `go` only surfaces 5+ minutes in. Fail-fast costs one command -v\n# call when Go is present and converts a late, opaque failure into a 30-second\n# actionable abort.\nif ! command -v go >/dev/null 2>&1; then\n echo \"\"\n echo \"[setup-error] Go toolchain not found.\"\n echo \"\"\n echo \"The Printing Press generator runs Go-based quality gates after generation.\"\n echo \"Install Go 1.26.3 or newer from https://go.dev/dl/, then verify with:\"\n echo \" go version\"\n echo \"Then re-run /printing-press.\"\n echo \"\"\n return 1 2>/dev/null || exit 1\nfi\n\n# Verify the installed Go tree can compile and run common standard library\n# imports. A truncated Go extraction can leave the binary working enough for\n# `go version` while missing packages under $GOROOT/src, which otherwise fails\n# deep into generation during later Go quality gates.\n_go_smoke_root=\"${PRINTING_PRESS_GO_SMOKE_DIR:-$HOME/.printing-press-smoke}\"\nif ! mkdir -p \"$_go_smoke_root\"; then\n echo \"\"\n echo \"[setup-error] Unable to create Go smoke-test workspace at $_go_smoke_root.\"\n echo \"Set PRINTING_PRESS_GO_SMOKE_DIR to a writable non-temp directory and retry.\"\n echo \"\"\n return 1 2>/dev/null || exit 1\nfi\n_go_smoke_dir=\"$(mktemp -d \"$_go_smoke_root/stdlib.XXXXXX\" 2>/dev/null || true)\"\nif [ -z \"$_go_smoke_dir\" ]; then\n echo \"\"\n echo \"[setup-error] Unable to create Go smoke-test workspace under $_go_smoke_root.\"\n echo \"Set PRINTING_PRESS_GO_SMOKE_DIR to a writable non-temp directory and retry.\"\n echo \"\"\n return 1 2>/dev/null || exit 1\nfi\ncat > \"$_go_smoke_dir/go.mod\" \u003c\u003c'__PP_GO_SMOKE_MOD__'\nmodule pp-go-stdlib-smoke\n\ngo 1.20\n__PP_GO_SMOKE_MOD__\ncat > \"$_go_smoke_dir/main.go\" \u003c\u003c'__PP_GO_SMOKE_MAIN__'\npackage main\n\nimport (\n\t\"context\"\n\t\"encoding/json\"\n\t\"fmt\"\n\t\"io\"\n\t\"net/http\"\n\t\"regexp\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tpayload, err := json.Marshal(map[string]string{\"status\": \"ok\"})\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\tif !regexp.MustCompile(`ok`).Match(payload) {\n\t\tpanic(\"regexp mismatch\")\n\t}\n\treq, err := http.NewRequestWithContext(ctx, http.MethodGet, \"https://example.com\", nil)\n\tif err != nil {\n\t\tpanic(err)\n\t}\n\t_, _ = fmt.Fprint(io.Discard, req.Method)\n}\n__PP_GO_SMOKE_MAIN__\nif ! (cd \"$_go_smoke_dir\" && GOFLAGS= GOWORK=off go run . >/dev/null 2>\"$_go_smoke_dir/error.log\"); then\n _go_smoke_output=\"$(sed -n '1,12p' \"$_go_smoke_dir/error.log\" 2>/dev/null || true)\"\n rm -rf \"$_go_smoke_dir\"\n echo \"\"\n echo \"[setup-error] Go std library is incomplete (truncated or corrupted install).\"\n echo \"Reinstall Go from https://go.dev/dl/ and verify with the smoke test before retrying.\"\n if [ -n \"$_go_smoke_output\" ]; then\n echo \"\"\n echo \"Go smoke test output:\"\n printf '%s\\n' \"$_go_smoke_output\"\n fi\n echo \"\"\n return 1 2>/dev/null || exit 1\nfi\nrm -rf \"$_go_smoke_dir\"\n\n# Resolve and emit the absolute path the agent must use for every later\n# `cli-printing-press` invocation. `export PATH` above only affects this one\n# Bash tool call; subsequent calls open a fresh shell and resolve bare\n# `cli-printing-press` against the user's default PATH. When a global is\n# installed at a stale version, that silently shadows the local build the\n# preflight just chose. Handing the agent an absolute path eliminates the\n# shadow.\nif [ \"$_press_repo\" = \"true\" ] && [ -x \"$_scope_dir/cli-printing-press\" ]; then\n PRINTING_PRESS_BIN=\"$_scope_dir/cli-printing-press\"\nelse\n PRINTING_PRESS_BIN=\"$(_resolve_press_bin 2>/dev/null || true)\"\nfi\necho \"PRINTING_PRESS_BIN=$PRINTING_PRESS_BIN\"\necho \"PRESS_REPO_MODE=$_press_repo\"\n\n# Shadow detector (advisory). When a local build is in use, surface any\n# differing global so the user can see at a glance that the two binaries\n# disagree. Detect-only: the absolute path emitted above is the one the\n# agent will actually invoke; this warning does not change selection.\nif [ \"$_press_repo\" = \"true\" ] && [ -x \"$_scope_dir/cli-printing-press\" ]; then\n _global_bin=\"\"\n for _candidate in \"$HOME/go/bin/cli-printing-press\" \"/usr/local/bin/cli-printing-press\" \"/opt/homebrew/bin/cli-printing-press\" \"$HOME/go/bin/printing-press\" \"/usr/local/bin/printing-press\" \"/opt/homebrew/bin/printing-press\"; do\n if [ -x \"$_candidate\" ] && [ \"$_candidate\" != \"$_scope_dir/cli-printing-press\" ] && \"$_candidate\" version --json >/dev/null 2>&1; then\n _global_bin=\"$_candidate\"\n break\n fi\n done\n if [ -n \"$_global_bin\" ]; then\n _local_v=\"$(\"$_scope_dir/cli-printing-press\" version --json 2>/dev/null | sed -nE 's/.*\"version\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/p')\"\n _global_v=\"$(\"$_global_bin\" version --json 2>/dev/null | sed -nE 's/.*\"version\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/p')\"\n if [ -n \"$_local_v\" ] && [ -n \"$_global_v\" ] && [ \"$_local_v\" != \"$_global_v\" ]; then\n echo \"\"\n echo \"[binary-shadow] local build v$_local_v differs from global v$_global_v at $_global_bin\"\n echo \"PRESS_BIN_LOCAL_VERSION=$_local_v\"\n echo \"PRESS_BIN_GLOBAL_VERSION=$_global_v\"\n echo \"PRESS_BIN_GLOBAL_PATH=$_global_bin\"\n echo \"\"\n fi\n fi\nfi\n\nPRESS_BASE=\"$(basename \"$_scope_dir\" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9_-]/-/g; s/^-+//; s/-+$//')\"\nif [ -z \"$PRESS_BASE\" ]; then\n PRESS_BASE=\"workspace\"\nfi\n\nPRESS_SCOPE=\"$PRESS_BASE-$(printf '%s' \"$_scope_dir\" | shasum -a 256 | cut -c1-8)\"\nPRESS_HOME=\"${PRINTING_PRESS_HOME:-$HOME/printing-press}\"\nPRESS_RUNSTATE=\"$PRESS_HOME/.runstate/$PRESS_SCOPE\"\nPRESS_LIBRARY=\"$PRESS_HOME/library\"\nPRESS_MANUSCRIPTS=\"$PRESS_HOME/manuscripts\"\nPRESS_CURRENT=\"$PRESS_RUNSTATE/current\"\n\nmkdir -p \"$PRESS_RUNSTATE\" \"$PRESS_LIBRARY\" \"$PRESS_MANUSCRIPTS\" \"$PRESS_CURRENT\"\n\n# --- Latest-version advisory (fail-open) ---\n# Repo checkouts track origin/main because their skills and local binary come\n# from the checkout. Standalone installs track the latest released Go module.\nPRESS_VERCHECK_FILE=\"$PRESS_HOME/.version-check\"\nPRESS_VERCHECK_TTL=86400\n_now_ts=$(date +%s)\n_should_check=true\nif [ -f \"$PRESS_VERCHECK_FILE\" ] && [ -z \"$PRESS_VERCHECK_FORCE\" ]; then\n _last_ts=$(awk -F= '/^last_check=/{print $2}' \"$PRESS_VERCHECK_FILE\" 2>/dev/null)\n if [ -n \"$_last_ts\" ] && [ \"$((_now_ts - _last_ts))\" -lt \"$PRESS_VERCHECK_TTL\" ]; then\n _should_check=false\n fi\nfi\n\nif [ \"$_press_repo\" = \"true\" ]; then\n # Repo mode checks origin/main every run because the checkout and local build\n # move quickly; skipped_repo_main suppresses repeated prompts for one SHA.\n if git -C \"$_scope_dir\" remote get-url origin >/dev/null 2>&1 &&\n git -C \"$_scope_dir\" fetch --quiet origin main >/dev/null 2>&1; then\n _head_rev=$(git -C \"$_scope_dir\" rev-parse HEAD 2>/dev/null || true)\n _main_rev=$(git -C \"$_scope_dir\" rev-parse origin/main 2>/dev/null || true)\n _skipped_repo_main=\"\"\n if [ -f \"$PRESS_VERCHECK_FILE\" ] && [ -z \"$PRESS_VERCHECK_FORCE\" ]; then\n _skipped_repo_main=$(awk -F= '/^skipped_repo_main=/{value=$2} END{print value}' \"$PRESS_VERCHECK_FILE\" 2>/dev/null)\n fi\n if [ -n \"$_head_rev\" ] && [ -n \"$_main_rev\" ] &&\n [ \"$_head_rev\" != \"$_main_rev\" ] &&\n [ \"$_skipped_repo_main\" != \"$_main_rev\" ] &&\n git -C \"$_scope_dir\" merge-base --is-ancestor \"$_head_rev\" \"$_main_rev\" 2>/dev/null; then\n echo \"\"\n echo \"[repo-upgrade-available] origin/main has newer Printing Press changes\"\n echo \"PRESS_REPO_DIR=$_scope_dir\"\n echo \"PRESS_REPO_HEAD=$_head_rev\"\n echo \"PRESS_REPO_MAIN=$_main_rev\"\n echo \"\"\n fi\n\n printf \"last_check=%s\\nlatest=%s\\nmode=repo\\nskipped_repo_main=%s\\n\" \"$_now_ts\" \"${_main_rev:-unknown}\" \"$_skipped_repo_main\" > \"$PRESS_VERCHECK_FILE\" 2>/dev/null || true\n fi\nelif [ \"$_should_check\" = \"true\" ] && command -v go >/dev/null 2>&1; then\n _installed=$(\"$PRINTING_PRESS_BIN\" version --json 2>/dev/null | sed -nE 's/.*\"version\"[[:space:]]*:[[:space:]]*\"([^\"]+)\".*/\\1/p')\n _latest=\"\"\n\n if [ -n \"$_installed\" ]; then\n _latest=$(go list -m -json github.com/mvanhorn/cli-printing-press/v4@latest 2>/dev/null | awk '\n /\"Version\":/ {\n version=$2\n gsub(/[\",]/, \"\", version)\n sub(/^v/, \"\", version)\n print version\n exit\n }\n ')\n fi\n\n if [ -n \"$_installed\" ] && [ -n \"$_latest\" ] &&\n awk -v installed=\"$_installed\" -v latest=\"$_latest\" 'BEGIN {\n split(installed, a, \".\")\n split(latest, b, \".\")\n # Integer truncation means pre-release suffixes (e.g. \"4.0.0-rc.1\") are\n # treated as equal to their GA counterpart. Acceptable while we do not\n # ship pre-release tags; revisit if that changes.\n for (i = 1; i \u003c= 3; i++) {\n if ((a[i] + 0) \u003c (b[i] + 0)) exit 0\n if ((a[i] + 0) > (b[i] + 0)) exit 1\n }\n exit 1\n }'; then\n # Marker for the skill prose below to detect and offer an interactive upgrade.\n # The skill reads PRESS_UPGRADE_AVAILABLE / PRESS_UPGRADE_INSTALLED from this output.\n echo \"\"\n echo \"[upgrade-available] printing-press v$_latest is available (you have v$_installed)\"\n echo \"PRESS_UPGRADE_AVAILABLE=$_latest\"\n echo \"PRESS_UPGRADE_INSTALLED=$_installed\"\n echo \"\"\n fi\n\n printf \"last_check=%s\\nlatest=%s\\nmode=standalone\\n\" \"$_now_ts\" \"${_latest:-$_installed}\" > \"$PRESS_VERCHECK_FILE\" 2>/dev/null || true\nfi\n\n# --- Browser-sniff backend advisory (fail-open, every-run) ---\n# browser-use and agent-browser are the preferred Phase 1.7 browser-sniff\n# backends. They are not hard requirements — vendor-spec, --spec, and --har\n# runs never invoke them — but when discovery does need them, mid-flight\n# install prompts are disruptive. Emit a marker every run so setup-checks.md\n# can strongly offer install. No decline caching: a run that didn't need them\n# yesterday may need them today, and the prompt cost is small.\n_browser_use_missing=true\n_agent_browser_missing=true\n# Use `command -v` only. Do NOT use `uvx browser-use --help` as a fallback\n# probe: when uvx exists but browser-use doesn't, that command silently\n# downloads and caches the package, which would be an unconsented install.\n# Downstream capture commands also invoke `browser-use` directly (not via\n# uvx), so a uvx-cache-only state would lie to the detection.\nif command -v browser-use >/dev/null 2>&1; then\n _browser_use_missing=false\nfi\nif command -v agent-browser >/dev/null 2>&1; then\n _agent_browser_missing=false\nfi\n\nif [ \"$_browser_use_missing\" = \"true\" ] || [ \"$_agent_browser_missing\" = \"true\" ]; then\n echo \"\"\n echo \"[browser-tools-missing] one or more browser-sniff backends not installed\"\n echo \"PRESS_BROWSER_USE_MISSING=$_browser_use_missing\"\n echo \"PRESS_AGENT_BROWSER_MISSING=$_agent_browser_missing\"\n echo \"\"\nfi\n\n# --- Codex mode detection (must run as part of setup, not a separate step) ---\n# Codex mode: opt-in only. User must pass \"codex\" or \"--codex\" to enable.\nif echo \"$ARGUMENTS\" | grep -qiE '(^| )(--?codex|codex)( |$)'; then\n CODEX_MODE=true\nelse\n CODEX_MODE=false\nfi\n\n# Environment guard: don't delegate if already inside a Codex sandbox\nif [ \"$CODEX_MODE\" = \"true\" ]; then\n if [ -n \"$CODEX_SANDBOX\" ] || [ -n \"$CODEX_SESSION_ID\" ]; then\n CODEX_MODE=false\n fi\nfi\n\n# Health check: verify codex binary exists\nif [ \"$CODEX_MODE\" = \"true\" ]; then\n if command -v codex >/dev/null 2>&1; then\n # Model and reasoning effort inherit from ~/.codex/config.toml. Do not pin -m / -c here.\n CODEX_MODEL=$(grep -E '^model[[:space:]]*=' ~/.codex/config.toml 2>/dev/null | head -1 | sed -E 's/^model[[:space:]]*=[[:space:]]*\"?([^\"]+)\"?.*$/\\1/')\n [ -z \"$CODEX_MODEL\" ] && CODEX_MODEL=\"codex default\"\n echo \"Codex mode enabled (model: $CODEX_MODEL). Code-writing tasks will be delegated to Codex.\"\n else\n echo \"Codex CLI not found - running in standard mode.\"\n CODEX_MODE=false\n fi\nfi\n\n# Circuit breaker state\nCODEX_CONSECUTIVE_FAILURES=0","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003c!-- PRESS_SETUP_CONTRACT_END -->","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY: Read and apply ","type":"text","marks":[{"type":"strong"}]},{"text":"references/setup-checks.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/setup-checks.md","title":null}},{"type":"strong"}]},{"text":" immediately after the setup contract bash block runs, before any other action.","type":"text","marks":[{"type":"strong"}]},{"text":" It handles the contract output signals: ","type":"text"},{"text":"[setup-error]","type":"text","marks":[{"type":"code_inline"}]},{"text":" (refuse to run, surface the install instructions), ","type":"text"},{"text":"[repo-upgrade-available]","type":"text","marks":[{"type":"code_inline"}]},{"text":" (interactive ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" prompt + optional repo pull), ","type":"text"},{"text":"PRESS_REPO_MODE=\u003ctrue|false>","type":"text","marks":[{"type":"code_inline"}]},{"text":" plus the targeted global open-agent-skills freshness check, the min-binary-version compatibility check (hard stop if binary is too old), ","type":"text"},{"text":"[upgrade-available]","type":"text","marks":[{"type":"code_inline"}]},{"text":" (interactive ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" prompt + optional standalone binary upgrade), ","type":"text"},{"text":"[browser-tools-missing]","type":"text","marks":[{"type":"code_inline"}]},{"text":" (interactive ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" prompt + optional install of browser-use and/or agent-browser), and the ","type":"text"},{"text":"PRINTING_PRESS_BIN=\u003cabs-path>","type":"text","marks":[{"type":"code_inline"}]},{"text":" marker plus optional ","type":"text"},{"text":"[binary-shadow]","type":"text","marks":[{"type":"code_inline"}]},{"text":" warning (capture the path; use it for every subsequent generator invocation). Skipping the reference will cause the skill to proceed with a missing or out-of-date binary, run with stale global skill text when the session is managed by open-agent-skills, hit a mid-flight install prompt if browser-sniff is later needed, or invoke the wrong binary because a stale global or the public catalog installer on ","type":"text"},{"text":"PATH","type":"text","marks":[{"type":"code_inline"}]},{"text":" shadowed the local build. Do not skip.","type":"text"}]},{"type":"paragraph","content":[{"text":"Absolute-path rule.","type":"text","marks":[{"type":"strong"}]},{"text":" The preflight contract always emits ","type":"text"},{"text":"PRINTING_PRESS_BIN=\u003cabsolute path>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to stdout. Capture this value and substitute it (the resolved absolute path, not the literal ","type":"text"},{"text":"$PRINTING_PRESS_BIN","type":"text","marks":[{"type":"code_inline"}]},{"text":" token) for every subsequent ","type":"text"},{"text":"cli-printing-press ...","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocation in this skill, references, and any sub-skill you delegate to. The ","type":"text"},{"text":"export PATH=...","type":"text","marks":[{"type":"code_inline"}]},{"text":" line inside the contract only affects the single Bash tool call it runs in; later Bash tool calls open fresh shells and resolve bare ","type":"text"},{"text":"cli-printing-press","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the user's default ","type":"text"},{"text":"PATH","type":"text","marks":[{"type":"code_inline"}]},{"text":", where a stale globally-installed binary (","type":"text"},{"text":"$HOME/go/bin/cli-printing-press","type":"text","marks":[{"type":"code_inline"}]},{"text":", Homebrew copy, etc.) will silently shadow the local build the preflight just chose. Bash code examples below are written ","type":"text"},{"text":"cli-printing-press generate ...","type":"text","marks":[{"type":"code_inline"}]},{"text":" for readability — replace ","type":"text"},{"text":"cli-printing-press","type":"text","marks":[{"type":"code_inline"}]},{"text":" with the captured absolute path each time you actually run one.","type":"text"}]},{"type":"paragraph","content":[{"text":"Only after preflight completes successfully (no ","type":"text"},{"text":"[setup-error]","type":"text","marks":[{"type":"code_inline"}]},{"text":"; no global skill update that requires restart; any ","type":"text"},{"text":"[repo-upgrade-available]","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"[upgrade-available]","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"[browser-tools-missing]","type":"text","marks":[{"type":"code_inline"}]},{"text":" was offered to the user; ","type":"text"},{"text":"PRINTING_PRESS_BIN","type":"text","marks":[{"type":"code_inline"}]},{"text":" is captured) should you proceed to the Orientation & Briefing section below.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Orientation & Briefing","type":"text"}]},{"type":"paragraph","content":[{"text":"After preflight has completed, check whether the user provided arguments. Handle two cases:","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"No Arguments: Orientation","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user typed ","type":"text"},{"text":"/printing-press","type":"text","marks":[{"type":"code_inline"}]},{"text":" with no arguments (no API name, no ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":", no ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":", no URL), print an orientation and ask what they'd like to build:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"The Printing Press generates a fully functional CLI for any API. You give it an API name, a spec file, or a URL. It researches the landscape, catalogs every feature that exists in any competing tool, invents novel features of its own, then generates a Go CLI that matches and beats everything out there — with offline search, agent-native output, and a local SQLite data layer.","type":"text"}]},{"type":"paragraph","content":[{"text":"By the end, you'll have a working CLI in ","type":"text"},{"text":"$PRESS_LIBRARY/","type":"text","marks":[{"type":"code_inline"}]},{"text":" that you can use for yourself, ship on your own, or apply to add to the printing-press library.","type":"text"}]},{"type":"paragraph","content":[{"text":"The process takes 30-60 minutes depending on API complexity. Simple APIs with official specs (Stripe, GitHub) are faster. Undocumented APIs that need discovery (ESPN, Domino's) take longer.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Print these example invocations as plain text BEFORE the ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" call (so they appear as context above the question, not as competing menu options):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"/printing-press Notion\n/printing-press Discord codex\n/printing-press --spec ./openapi.yaml\n/printing-press --har ./capture.har --name MyAPI\n/printing-press https://postman.com","type":"text"}]},{"type":"paragraph","content":[{"text":"Then ask via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"question:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"What API would you like to build a CLI for?\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"header:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"API target\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"multiSelect:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"options:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"label:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Type it (recommended)\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Provide an API name, URL, spec path, or HAR file via the 'Other' option below.\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"label:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Browse existing CLIs first\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Visit the public library to see what's already been printed before deciding what to build.\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Do not add additional options","type":"text","marks":[{"type":"strong"}]},{"text":" — no \"Show me popular options\", no pre-populated buttons for Notion / Stripe / GitHub / Linear / Discord. The example invocations above already cover the common shapes, and most popular APIs are already in the public library (offering to re-print them is noise). The two options above plus the automatic \"Other\" field is the entire interface.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user picks ","type":"text"},{"text":"\"Type it (recommended)\"","type":"text","marks":[{"type":"strong"}]},{"text":", they will provide their answer via the auto \"Other\" field. Set their input as the argument and proceed to the briefing below.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user picks ","type":"text"},{"text":"\"Browse existing CLIs first\"","type":"text","marks":[{"type":"strong"}]},{"text":", print the public library URL prominently and try to open it in the browser, then end the skill so the user can browse before deciding:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"echo \"\"\necho \"Public library: https://github.com/mvanhorn/printing-press-library\"\necho \"(If you have the Printing Press Library plugin, you can also run /ppl in Claude Code.)\"\necho \"\"\ncommand -v open >/dev/null 2>&1 && open https://github.com/mvanhorn/printing-press-library","type":"text"}]},{"type":"paragraph","content":[{"text":"After printing, end the skill cleanly. Do not proceed to briefing or research — the user is exploring, not building yet. They can re-invoke ","type":"text"},{"text":"/printing-press \u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" once they've decided.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"With Arguments: Briefing","type":"text"}]},{"type":"paragraph","content":[{"text":"When the user provided an argument (API name, ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":", or URL), print a brief process overview. This sets expectations and collects any upfront context. (Preflight has already run at this point.)","type":"text"}]},{"type":"paragraph","content":[{"text":"Print as prose, matching the style of the example below:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Very well. Setting the type for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Here is how this will proceed:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"I shall research ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":" across the internet: official docs, community wrappers, competing CLIs, MCP servers, and npm/PyPI packages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"I shall catalog every feature that exists in any tool, then devise novel features of my own that no existing tool offers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"I shall present what I found and what I invented — you will have a chance to add your own ideas or adjust the plan before I build","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"I shall generate a Go CLI, build every feature from the plan, then verify quality through dogfood, runtime verification, and scoring","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"What you will have at the end:","type":"text","marks":[{"type":"strong"}]},{"text":" A fully functional CLI at ","type":"text"},{"text":"$PRESS_LIBRARY/\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" that you can use yourself, ship on your own, or apply to add to the printing-press library.","type":"text"}]},{"type":"paragraph","content":[{"text":"Time:","type":"text","marks":[{"type":"strong"}]},{"text":" 30-60 minutes depending on API complexity.","type":"text"}]},{"type":"paragraph","content":[{"text":"Things that help if you have them:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"An API key (for live smoke testing at the end)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A logged-in browser session (for discovering authenticated endpoints)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A spec file or HAR capture (skips discovery)","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"If the user provided ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":", adapt: \"You have provided a spec, so I shall skip discovery and proceed directly to analysis and generation. Should be faster.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user provided ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":", adapt: \"You have provided a HAR capture, so I shall generate a spec from your traffic and skip browser browser-sniffing.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Then ask via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"question:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Anything you want me to know before I begin? A vision for what this CLI should do, specific features you care about, or auth context I should have?\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"header:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Briefing\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"multiSelect:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"options:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"label:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Let's go (recommended)\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Start research now. I'll ask about API keys, browser auth, or other context when I need them.\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"label:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"I have context to share\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Tell me your vision, specific features, or auth context (API key, logged-in browser session) before research starts.\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Do not add additional options","type":"text","marks":[{"type":"strong"}]},{"text":" — auth is already handled by Phase 0.5 (API Key Gate) and Phase 1.6 (Pre-Browser-Sniff Auth Intelligence) downstream. A user who wants to volunteer auth context can do so via option 2's free-text response. The two options above plus the automatic \"Other\" field is the entire interface.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user picks ","type":"text"},{"text":"\"Let's go (recommended)\"","type":"text","marks":[{"type":"strong"}]},{"text":", proceed to the Multi-Source Priority Gate (or, for single-source runs, directly to Phase 0).","type":"text"}]},{"type":"paragraph","content":[{"text":"If the user picks ","type":"text"},{"text":"\"I have context to share\"","type":"text","marks":[{"type":"strong"}]},{"text":", capture their free-text response as ","type":"text"},{"text":"USER_BRIEFING_CONTEXT","type":"text","marks":[{"type":"code_inline"}]},{"text":". The response may include:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Vision / specific features","type":"text","marks":[{"type":"strong"}]},{"text":" — captured as-is. This context will be:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Added to the Phase 1 Research Brief under a ","type":"text"},{"text":"## User Vision","type":"text","marks":[{"type":"code_inline"}]},{"text":" section","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Used as a 4th self-brainstorm question in Phase 1.5c.5: \"Based on the user's stated vision, what features directly serve their stated goals that the absorbed features don't cover?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Referenced at the Phase Gate 1.5 absorb gate: \"You mentioned [summary] at the start. Want to add more, or does the manifest already cover it?\"","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auth context","type":"text","marks":[{"type":"strong"}]},{"text":" — if the user mentions an API key, env var, or logged-in browser session, set the corresponding ","type":"text"},{"text":"AUTH_CONTEXT","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields so the API Key Gate (Phase 0.5) and Pre-Browser-Sniff Auth Intelligence (Phase 1.6) do not re-ask.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Multi-Source Priority Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"After the briefing question resolves, inspect the user's original argument AND any ","type":"text"},{"text":"USER_BRIEFING_CONTEXT","type":"text","marks":[{"type":"code_inline"}]},{"text":" they provided. If together they name ","type":"text"},{"text":"two or more distinct services, sites, or APIs","type":"text","marks":[{"type":"strong"}]},{"text":" (e.g., \"Google Flights and Kayak\", \"Notion + Linear combo CLI\", \"flightgoat: Google Flights, Kayak.com/direct, and FlightAware\"), this is a combo CLI and priority ordering MUST be confirmed before Phase 1 research.","type":"text"}]},{"type":"paragraph","content":[{"text":"Why this gate exists:","type":"text","marks":[{"type":"strong"}]},{"text":" Phase 1 research defaults to the first resolvable spec as the primary source. When the user listed services in a specific order, that order is their intent — but the generator's spec-first bias will silently invert it (picking a well-documented paid API over a free reverse-engineered one the user actually wanted as the headline feature). This has caused real user-visible failures where the CLI shipped with the wrong primary and required a paid API key for what the user intended as the free primary command.","type":"text"}]},{"type":"paragraph","content":[{"text":"Parse the order from the prose.","type":"text","marks":[{"type":"strong"}]},{"text":" Use the user's wording verbatim. Commas, \"then\", \"and\", explicit \"primary/secondary\", or numbered lists all signal ordering. If the user wrote \"Google Flights, Kayak, FlightAware\" — that is the order. Do not reorder by spec availability, tier, or ease of generation.","type":"text"}]},{"type":"paragraph","content":[{"text":"Confirm via ","type":"text","marks":[{"type":"strong"}]},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":":","type":"text","marks":[{"type":"strong"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"You mentioned ","type":"text"},{"text":"\u003cSource A>","type":"text","marks":[{"type":"strong"}]},{"text":", ","type":"text"},{"text":"\u003cSource B>","type":"text","marks":[{"type":"strong"}]},{"text":", and ","type":"text"},{"text":"\u003cSource C>","type":"text","marks":[{"type":"strong"}]},{"text":". I'll treat ","type":"text"},{"text":"\u003cSource A>","type":"text","marks":[{"type":"strong"}]},{"text":" as the primary — it gets the headline commands, the top of the README, and the first-run experience. Is that the right order?\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes, that order is correct","type":"text","marks":[{"type":"strong"}]},{"text":" — Proceed with ","type":"text"},{"text":"SOURCE_PRIORITY=[A, B, C]","type":"text","marks":[{"type":"code_inline"}]},{"text":" captured to run state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Different order","type":"text","marks":[{"type":"strong"}]},{"text":" — User provides the correct ordering; capture it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"They're peers, no primary","type":"text","marks":[{"type":"strong"}]},{"text":" — Rare; capture as equal weighting but warn the user that one will still lead the README.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Write the confirmed ordering to ","type":"text"},{"text":"$API_RUN_DIR/source-priority.json","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"sources\": [\"google-flights\", \"kayak-direct\", \"flightaware\"],\n \"confirmed_at\": \"\u003cISO timestamp>\",\n \"raw_user_phrasing\": \"\u003cverbatim text that established the order>\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Phase 1 MUST consult this file.","type":"text","marks":[{"type":"strong"}]},{"text":" When selecting a spec source, the primary source wins even if it has no spec and a later source has a clean OpenAPI. When the primary has no official spec, flag that openly in the brief under ","type":"text"},{"text":"## Source Priority","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see template below) and route to the browser-sniff/docs path for the primary — do not promote a secondary source just because its spec is cleaner.","type":"text"}]},{"type":"paragraph","content":[{"text":"Economics check.","type":"text","marks":[{"type":"strong"}]},{"text":" If the confirmed primary source is free (no API key required) AND the generator's default path would make the primary CLI commands require a paid key (because the auth applies broadly or because a paid secondary source is bleeding into the primary path), surface the tradeoff explicitly before generating:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"The primary source (","type":"text"},{"text":"\u003cSource A>","type":"text","marks":[{"type":"strong"}]},{"text":") is free, but the default path would require a ","type":"text"},{"text":"\u003cpaid key>","type":"text","marks":[{"type":"strong"}]},{"text":" for the headline commands because \u003creason>. Options: (1) keep primary free, gate only the secondary commands on the paid key; (2) require the paid key for everything; (3) drop the paid source.\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Default to option 1 unless the user overrides. Record the decision in ","type":"text"},{"text":"source-priority.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" under ","type":"text"},{"text":"auth_scoping","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Single-source runs:","type":"text","marks":[{"type":"strong"}]},{"text":" If only one service is named, skip this gate entirely — no ordering to confirm.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Run Initialization","type":"text"}]},{"type":"paragraph","content":[{"text":"After you know ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (from the Orientation & Briefing flow above; preflight already ran at the top), initialize the run-scoped artifact paths:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"RUN_ID=\"$(date +%Y%m%d-%H%M%S)\"\nAPI_RUN_DIR=\"$PRESS_RUNSTATE/runs/$RUN_ID\"\nRESEARCH_DIR=\"$API_RUN_DIR/research\"\nPROOFS_DIR=\"$API_RUN_DIR/proofs\"\nPIPELINE_DIR=\"$API_RUN_DIR/pipeline\"\nDISCOVERY_DIR=\"$API_RUN_DIR/discovery\"\nCLI_WORK_DIR=\"$API_RUN_DIR/working/\u003capi>-pp-cli\"\nSTAMP=\"$(date +%Y-%m-%d-%H%M%S)\"\n\n# Session state (live cookies, CSRF tokens captured during authenticated\n# browser-sniff) lives OUTSIDE $API_RUN_DIR so the Phase 5.5 archive\n# `cp -r \"$DISCOVERY_DIR\"` cannot pick it up. Containment by location, not by\n# manual rm-before-archive.\n#\n# Base prefix is user-scoped (`printing-press-$(id -u)`) so that on a Linux\n# host with a shared /tmp, the umask-077 subshell below does not lock the\n# top-level `printing-press` directory to a single user. macOS already gives\n# us a per-user $TMPDIR; the $(id -u) suffix keeps semantics identical there.\nSESSION_BASE=\"${TMPDIR:-/tmp}/printing-press-$(id -u)\"\nSESSION_DIR=\"$SESSION_BASE/session/$RUN_ID\"\nSESSION_STATE_FILE=\"$SESSION_DIR/session-state.json\"\n\nmkdir -p \"$RESEARCH_DIR\" \"$PROOFS_DIR\" \"$PIPELINE_DIR\" \"$CLI_WORK_DIR\"\n# Create $SESSION_DIR inside a subshell with a tight umask so it lands at 0700\n# at creation, not after a follow-up chmod. The two-step `mkdir; chmod` form\n# leaves a TOCTOU window where a concurrent process could open the directory\n# (and any session-state.json written into it) while perms are still\n# umask-derived (typically 0755 on Linux). The umask propagates to every\n# directory `mkdir -p` creates; the user-scoped $SESSION_BASE above is what\n# keeps that from blocking other users on the same host.\n(umask 077 && mkdir -p \"$SESSION_DIR\")\nSTATE_FILE=\"$API_RUN_DIR/state.json\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Maintain a lightweight state file at ","type":"text"},{"text":"$STATE_FILE","type":"text","marks":[{"type":"code_inline"}]},{"text":" so ","type":"text"},{"text":"/printing-press-score","type":"text","marks":[{"type":"code_inline"}]},{"text":" can rediscover the current run. It should always contain:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"api_name\": \"\u003capi>\",\n \"run_id\": \"$RUN_ID\",\n \"working_dir\": \"$CLI_WORK_DIR\",\n \"output_dir\": \"$CLI_WORK_DIR\",\n \"spec_path\": \"\u003cabsolute spec path if known>\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"run_id","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the same ","type":"text"},{"text":"YYYYMMDD-HHMMSS","type":"text","marks":[{"type":"code_inline"}]},{"text":" value computed earlier as ","type":"text"},{"text":"RUN_ID=\"$(date +%Y%m%d-%H%M%S)\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". The generator's manifest writer derives the same value from the ","type":"text"},{"text":"--research-dir","type":"text","marks":[{"type":"code_inline"}]},{"text":" basename when generate is invoked through the canonical ","type":"text"},{"text":"$API_RUN_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" (whose basename equals ","type":"text"},{"text":"$RUN_ID","type":"text","marks":[{"type":"code_inline"}]},{"text":"); persisting it in ","type":"text"},{"text":"state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" here keeps ","type":"text"},{"text":"/printing-press-score","type":"text","marks":[{"type":"code_inline"}]},{"text":" and any future state-loading consumer in sync. Without ","type":"text"},{"text":"run_id","type":"text","marks":[{"type":"code_inline"}]},{"text":" in either path, ","type":"text"},{"text":"cli-printing-press dogfood --live --write-acceptance","type":"text","marks":[{"type":"code_inline"}]},{"text":" refuses to write the gate marker.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not create a ","type":"text"},{"text":"go.work","type":"text","marks":[{"type":"code_inline"}]},{"text":" file in ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":". Generated modules must build and test as standalone modules; a mismatched workspace ","type":"text"},{"text":"go","type":"text","marks":[{"type":"code_inline"}]},{"text":" directive can break Go 1.25+ toolchains and lefthook checks. Editor/gopls workspace noise is cosmetic and must not be traded for broken ","type":"text"},{"text":"go build","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"go test","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"There are exactly three durable writable locations. Every generated artifact this skill preserves goes to one of them:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"$PRESS_RUNSTATE/","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — mutable working state for the current run (research, proofs, pipeline artifacts, plans, intermediate docs)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"$PRESS_LIBRARY/","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — published CLIs (","type":"text"},{"text":"\u003capi-slug>/","type":"text","marks":[{"type":"code_inline"}]},{"text":" subdirectories)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"$PRESS_MANUSCRIPTS/","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — archived run evidence (research, proofs, discovery)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Short-lived command captures may use ","type":"text"},{"text":"/tmp/printing-press/","type":"text","marks":[{"type":"code_inline"}]},{"text":" with unique ","type":"text"},{"text":"mktemp","type":"text","marks":[{"type":"code_inline"}]},{"text":" paths and must be deleted after use.","type":"text"}]},{"type":"paragraph","content":[{"text":"Examples of the current naming/layout:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"$PRESS_LIBRARY/notion/","type":"text","marks":[{"type":"code_inline"}]},{"text":" — published CLI directory (keyed by API slug)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"notion-pp-cli","type":"text","marks":[{"type":"code_inline"}]},{"text":" — the binary name inside the directory","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"/printing-press emboss notion","type":"text","marks":[{"type":"code_inline"}]},{"text":" — emboss accepts both slug and CLI name","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"discord-pp-cli/internal/store/store.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" — internal source paths still use CLI name","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"linear-pp-cli stale --days 30 --team ENG","type":"text","marks":[{"type":"code_inline"}]},{"text":" — binary invocations use CLI name","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"github.com/mvanhorn/discord-pp-cli","type":"text","marks":[{"type":"code_inline"}]},{"text":" — Go module paths use CLI name","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Outputs","type":"text"}]},{"type":"paragraph","content":[{"text":"Every run writes up to 5 concise artifacts under the current managed run and archives them to ","type":"text"},{"text":"$PRESS_MANUSCRIPTS/\u003capi-slug>/\u003crun-id>/","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"research/\u003cstamp>-feat-\u003capi>-pp-cli-brief.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"research/\u003cstamp>-feat-\u003capi>-pp-cli-absorb-manifest.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"proofs/\u003cstamp>-fix-\u003capi>-pp-cli-build-log.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"proofs/\u003cstamp>-fix-\u003capi>-pp-cli-shipcheck.md","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"proofs/\u003cstamp>-fix-\u003capi>-pp-cli-live-smoke.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (only if live testing runs)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"These do not need to be 200+ lines. Keep them dense, evidence-backed, and directly useful.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 0: Resolve And Reuse","type":"text"}]},{"type":"paragraph","content":[{"text":"Before new research:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resolve the spec source.","type":"text"}]},{"type":"paragraph","content":[{"text":"URL Detection","type":"text","marks":[{"type":"strong"}]},{"text":" — If the argument contains ","type":"text"},{"text":"://","type":"text","marks":[{"type":"code_inline"}]},{"text":", it's a URL. Determine whether it's a spec or a website before proceeding.","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 1: Content probe.","type":"text","marks":[{"type":"strong"}]},{"text":" Fetch the URL with the raw docs helper from ","type":"text"},{"text":"references/fetch-docs.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fetch-docs.md","title":null}}]},{"text":" and inspect the response status, ","type":"text"},{"text":"Content-Type","type":"text","marks":[{"type":"code_inline"}]},{"text":", and first few lines of the returned file:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check the ","type":"text"},{"text":"Content-Type","type":"text","marks":[{"type":"code_inline"}]},{"text":" header and the first few lines of the body.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the fetch fails (timeout, 404, DNS error), record the exact status/error, then skip to Step 2 — treat it as a website.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the content starts with ","type":"text"},{"text":"openapi:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"swagger:","type":"text","marks":[{"type":"code_inline"}]},{"text":", or is valid JSON containing an ","type":"text"},{"text":"\"openapi\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"\"swagger\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" key → it's a spec. Treat as ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" and proceed directly. No disambiguation needed.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the content is a HAR file (JSON with ","type":"text"},{"text":"\"log\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"\"entries\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" keys) → treat as ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":" and proceed directly.","type":"text"}]},{"type":"paragraph","content":[{"text":"Step 2: Disambiguation.","type":"text","marks":[{"type":"strong"}]},{"text":" If the content is HTML or the probe failed, ask the user what they want. Extract the site name from the hostname (e.g., ","type":"text"},{"text":"postman.com","type":"text","marks":[{"type":"code_inline"}]},{"text":" → \"Postman\", ","type":"text"},{"text":"app.linear.app","type":"text","marks":[{"type":"code_inline"}]},{"text":" → \"Linear\"). Derive ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" from the site name using the same ","type":"text"},{"text":"cleanSpecName","type":"text","marks":[{"type":"code_inline"}]},{"text":" normalization the generator uses.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" with:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"question:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"What kind of CLI do you want for \u003cSiteName>?\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"header:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"CLI target\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"multiSelect:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"false","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"options:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"label:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"\u003cSiteName>'s official API\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Build a CLI for \u003cSiteName>'s documented API (e.g. REST endpoints, webhooks, OAuth)\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"label:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"The \u003cSiteName> website itself\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"\"Build from the website itself — I may open or attach to Chrome during generation to capture site traffic, then generate a lightweight CLI from replayable HTTP/HTML surfaces\"","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]}]},{"type":"paragraph","content":[{"text":"The user can also pick the automatic \"Other\" option to describe what they're after in free text.","type":"text"}]},{"type":"paragraph","content":[{"text":"Routing after disambiguation:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"\u003cSiteName>'s official API\" → use ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the argument, proceed with normal discovery (Phase 1 research, then Phase 1.7 browser-sniff gate evaluates independently as usual)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The \u003cSiteName> website itself\" → use ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the argument, set ","type":"text"},{"text":"BROWSER_SNIFF_TARGET_URL=\u003curl>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Proceed to Phase 1 research. When Phase 1.7 is reached, skip the browser-sniff gate decision and go directly to \"If user approves browser-sniff\" (the user already approved temporary browser discovery in Phase 0 — do not re-ask). Use ","type":"text"},{"text":"BROWSER_SNIFF_TARGET_URL","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the starting URL for browser capture. The printed CLI must still use a replayable runtime surface; do not ship a resident browser transport.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Other\" → read the user's free-form response and adapt","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"End of URL detection.","type":"text","marks":[{"type":"strong"}]},{"text":" The remaining spec resolution rules apply when the argument is NOT a URL:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user passed ","type":"text"},{"text":"--har \u003cpath>","type":"text","marks":[{"type":"code_inline"}]},{"text":", this is a HAR-first run. Run ","type":"text"},{"text":"cli-printing-press browser-sniff --har \u003cpath> --name \u003capi> --output \"$RESEARCH_DIR/\u003capi>-browser-sniff-spec.yaml\" --analysis-output \"$DISCOVERY_DIR/traffic-analysis.json\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" to generate a spec and traffic analysis from captured traffic. If ","type":"text"},{"text":"$API_RUN_DIR/source-priority.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists with two or more sources, add ","type":"text"},{"text":"--preserve-hosts","type":"text","marks":[{"type":"code_inline"}]},{"text":" so combo-CLI captures retain peer API hosts with per-endpoint ","type":"text"},{"text":"base_url","type":"text","marks":[{"type":"code_inline"}]},{"text":" overrides instead of collapsing them into secondary evidence. Use the generated spec as the primary spec source for the rest of the pipeline. Skip the browser-sniff gate in Phase 1.7 (browser-sniff already ran).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user passed ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":", use it directly (existing behavior).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Otherwise, proceed with normal discovery (catalog, KnownSpecs, apis-guru, web search).","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Directory spec-source guard","type":"text"}]},{"type":"paragraph","content":[{"text":"If any resolved spec source is a local directory, do not pass the directory itself to ","type":"text"},{"text":"cli-printing-press generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" and do not silently pick the first file. Enumerate candidate specs first:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"find \"$SPEC_SOURCE_DIR\" -type f \$ -iname '*.json' -o -iname '*.yaml' -o -iname '*.yml' \$ | sort","type":"text"}]},{"type":"paragraph","content":[{"text":"Keep only files whose head looks like an OpenAPI or Swagger root document (","type":"text"},{"text":"openapi:","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"swagger:","type":"text","marks":[{"type":"code_inline"}]},{"text":", or JSON with a top-level ","type":"text"},{"text":"\"openapi\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"\"swagger\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" key). Ignore unrelated JSON/YAML config files.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the filtered candidate list is empty, abort with: ","type":"text"},{"text":"No OpenAPI/Swagger spec found under \u003cdirectory>. Pass --spec \u003cfile> directly.","type":"text","marks":[{"type":"code_inline"}]},{"text":" Do not continue with the raw directory as the spec source.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the directory contains exactly one candidate, use that file as the spec source and write it to ","type":"text"},{"text":"state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" as ","type":"text"},{"text":"spec_path","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"When the directory contains more than one candidate:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Print a prominent warning before generation: ","type":"text"},{"text":"N OpenAPI/Swagger specs found under \u003cdirectory>; no single file represents the whole API surface.","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"List every candidate when ","type":"text"},{"text":"N \u003c= 20","type":"text","marks":[{"type":"code_inline"}]},{"text":"; otherwise list the first 20 sorted paths and print ","type":"text"},{"text":"...and N-20 more","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Record the directory and candidates in ","type":"text"},{"text":"$STATE_FILE","type":"text","marks":[{"type":"code_inline"}]},{"text":" before continuing: ","type":"text"},{"text":"spec_path","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the directory and ","type":"text"},{"text":"spec_candidates","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the sorted list.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ask the user to choose one spec, several specs, or all specs. If this runtime cannot ask a blocking question, stop after printing the warning and tell the user to re-run with explicit ","type":"text"},{"text":"--spec \u003cfile>","type":"text","marks":[{"type":"code_inline"}]},{"text":" arguments. This is the minimum safe floor: never let a directory run finish while hiding that additional specs were ignored.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"After the user confirms the selection, update ","type":"text"},{"text":"$STATE_FILE","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"selected_spec_paths","type":"text","marks":[{"type":"code_inline"}]},{"text":" set to the list that will be generated.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For multiple selected specs, default to one independent printed CLI per spec using a derived ","type":"text"},{"text":"\u003capi>-\u003cspec-slug>","type":"text","marks":[{"type":"code_inline"}]},{"text":" name and a distinct working directory under ","type":"text"},{"text":"$API_RUN_DIR/working/","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not merge all selected specs into one CLI unless the user explicitly asks for a combined surface and provides the umbrella name for ","type":"text"},{"text":"--name","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check for prior research in:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"$PRESS_MANUSCRIPTS/\u003capi-slug>/*/research/*","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reuse good prior work instead of redoing it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Library Check","type":"text","marks":[{"type":"strong"}]},{"text":" — Check if a CLI for this API already exists in the library or is actively being built, and present the user with context and options.","type":"text"}]},{"type":"paragraph","content":[{"text":"First, check lock status to detect active builds:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"LOCK_STATUS=$(cli-printing-press lock status --cli \u003capi>-pp-cli --json 2>/dev/null)\nLOCK_HELD=$(echo \"$LOCK_STATUS\" | grep -o '\"held\"[[:space:]]*:[[:space:]]*[a-z]*' | head -1 | sed 's/.*: *//')\nLOCK_STALE=$(echo \"$LOCK_STATUS\" | grep -o '\"stale\"[[:space:]]*:[[:space:]]*[a-z]*' | head -1 | sed 's/.*: *//')\nLOCK_PHASE=$(echo \"$LOCK_STATUS\" | grep -o '\"phase\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | head -1 | sed 's/.*\"phase\"[[:space:]]*:[[:space:]]*\"//;s/\"//')\nLOCK_AGE=$(echo \"$LOCK_STATUS\" | grep -o '\"age_seconds\"[[:space:]]*:[[:space:]]*[0-9]*' | head -1 | sed 's/.*: *//')","type":"text"}]},{"type":"paragraph","content":[{"text":"Then check the library directory:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"CLI_DIR=\"$PRESS_LIBRARY/\u003capi>\"\nHAS_LIBRARY=false\nHAS_GOMOD=false\nPRIOR_STEINBERGER_SCORE=\"\"\nPRIOR_SUB60_REPRINT=false\nif [ -d \"$CLI_DIR\" ]; then\n HAS_LIBRARY=true\n if [ -f \"$CLI_DIR/go.mod\" ]; then\n HAS_GOMOD=true\n fi\n # Read manifest if available\n MANIFEST=\"$CLI_DIR/.printing-press.json\"\n if [ -f \"$MANIFEST\" ]; then\n PRESS_VERSION=$(cat \"$MANIFEST\" | grep -o '\"printing_press_version\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | head -1 | sed 's/.*\"printing_press_version\"[[:space:]]*:[[:space:]]*\"//;s/\"//')\n GENERATED_AT=$(cat \"$MANIFEST\" | grep -o '\"generated_at\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | head -1 | sed 's/.*\"generated_at\"[[:space:]]*:[[:space:]]*\"//;s/\"//')\n PRIOR_STEINBERGER_SCORE=$(jq -r '.scorecard.steinberger.percentage // empty' \"$MANIFEST\" 2>/dev/null || true)\n if [ -n \"$PRIOR_STEINBERGER_SCORE\" ] && awk \"BEGIN { exit !($PRIOR_STEINBERGER_SCORE \u003c 60) }\"; then\n PRIOR_SUB60_REPRINT=true\n fi\n fi\n # Get directory modification time as fallback\n CLI_MTIME=$(stat -f \"%Sm\" -t \"%Y-%m-%d\" \"$CLI_DIR\" 2>/dev/null || stat -c \"%y\" \"$CLI_DIR\" 2>/dev/null | cut -d' ' -f1)\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"Decision matrix:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Library dir?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Lock?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Stale?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Has go.mod?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Proceed normally","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Warn: \"Actively being built (phase: ","type":"text"},{"text":"\u003cphase>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cage>","type":"text","marks":[{"type":"code_inline"}]},{"text":" seconds ago). Wait, use a different name, or pick a different API.\"","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Offer reclaim: \"Interrupted build detected (stale since ","type":"text"},{"text":"\u003cage>","type":"text","marks":[{"type":"code_inline"}]},{"text":"s ago). Reclaim and start fresh?\"","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Existing \"Found existing\" flow (see below)","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Debris: \"Found ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory in library but it appears incomplete (no go.mod). Clean up and start fresh?\" If user approves, ","type":"text"},{"text":"rm -rf \"$CLI_DIR\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and proceed normally.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Warn: \"Actively being rebuilt (phase: ","type":"text"},{"text":"\u003cphase>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cage>","type":"text","marks":[{"type":"code_inline"}]},{"text":" seconds ago). Wait, use a different name, or pick a different API.\"","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Offer reclaim: \"Interrupted rebuild detected (stale since ","type":"text"},{"text":"\u003cage>","type":"text","marks":[{"type":"code_inline"}]},{"text":"s ago). Reclaim and start fresh?\"","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"If actively locked (not stale):","type":"text","marks":[{"type":"strong"}]},{"text":" Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" with options to wait, pick a different API, or force-reclaim (","type":"text"},{"text":"cli-printing-press lock acquire --cli \u003capi>-pp-cli --scope \"$PRESS_SCOPE\" --force","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]},{"type":"paragraph","content":[{"text":"If stale lock:","type":"text","marks":[{"type":"strong"}]},{"text":" Reclaiming is automatic on ","type":"text"},{"text":"lock acquire","type":"text","marks":[{"type":"code_inline"}]},{"text":" in Phase 2. If user approves, proceed normally — the lock acquire in Phase 2 will auto-reclaim the stale lock.","type":"text"}]},{"type":"paragraph","content":[{"text":"If library exists with go.mod and no lock (completed CLI):","type":"text","marks":[{"type":"strong"}]},{"text":" Display context and present options using ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Found existing ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" in library (last modified ","type":"text"},{"text":"\u003cdate>","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"PRESS_VERSION","type":"text","marks":[{"type":"code_inline"}]},{"text":" is available, append: ","type":"text"},{"text":"Built with printing-press v\u003cversion>.","type":"text","marks":[{"type":"code_inline"}]},{"text":" If ","type":"text"},{"text":"PRIOR_SUB60_REPRINT=true","type":"text","marks":[{"type":"code_inline"}]},{"text":", append: ","type":"text"},{"text":"Prior Steinberger score: \u003cscore>%. Reprint will require all approved transcendence rows to ship unless you explicitly accept partial coverage.","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"If prior research was also found (step 2), include the research summary alongside the library info.","type":"text"}]},{"type":"paragraph","content":[{"text":"Then ask:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Generate a fresh CLI\"","type":"text","marks":[{"type":"strong"}]},{"text":" — Re-runs the Printing Press into a working directory, overwrites generated code, then rebuilds transcendence features. Prior research is reused if recent.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Improve existing CLI\"","type":"text","marks":[{"type":"strong"}]},{"text":" — Keeps all current code, audits for quality gaps, implements top improvements. The Printing Press is not re-run.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Review prior research first\"","type":"text","marks":[{"type":"strong"}]},{"text":" — Show the full research brief and absorb manifest before deciding.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the user picks option 1, proceed to Phase 1 (research) and then Phase 2 (generate) as normal. If the user picks option 2, invoke ","type":"text"},{"text":"/printing-press-polish \u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to improve the existing CLI. If the user picks option 3, display the prior research, then re-present options 1 and 2.","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY when re-using prior research after a binary upgrade.","type":"text","marks":[{"type":"strong"}]},{"text":" If the user picks \"Generate a fresh CLI\" (option 1) AND ","type":"text"},{"text":"PRESS_VERSION","type":"text","marks":[{"type":"code_inline"}]},{"text":" from the manifest differs from the current binary's version (parse both via semver and compare; only fire when the leading minor or major segment changed — patch-level deltas don't trigger this), prompt the user once before kicking off Phase 1 research.","type":"text"}]},{"type":"paragraph","content":[{"text":"Construct the prompt's \"what changed\" list from these category buckets — the categories are stable across versions; the specific machine deltas inside each category are not. Read ","type":"text"},{"text":"docs/CHANGELOG.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or run ","type":"text"},{"text":"git log --oneline v\u003cPRESS_VERSION>..v\u003cCURRENT> -- internal/","type":"text","marks":[{"type":"code_inline"}]},{"text":") and tag each notable change to one of these buckets:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Category","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Affects prior-brief assumption about...","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Transport / reachability","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Which sources are reachable, what auth/clearance is needed, which clients (stdlib, Surf, browser-clearance) the brief assumed","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Scoring rubrics","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"What Phase 1.5/scorecard dimensions the brief targets, whether prior \"high-priority\" features still rank as such","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Auth modes","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Whether brief's auth choice (api-key, cookie, composed, oauth) is still the right pick, whether new modes unlock new endpoints","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MCP surface","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Whether brief's MCP shape (endpoint-mirror vs intent vs code-orchestration) matches the latest emit defaults","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Discovery","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Whether browser-sniff / crowd-sniff workflows changed, whether prior gate decisions are still valid","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"For the prompt itself, list only the buckets that have at least one notable change between the two versions. If the CHANGELOG / git log is unavailable, list all five buckets generically and let the user decide.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"The prior ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" was generated with printing-press v","type":"text"},{"text":"\u003cPRESS_VERSION>","type":"text","marks":[{"type":"code_inline"}]},{"text":". The current binary is v","type":"text"},{"text":"\u003cCURRENT>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Categories where the machine has changed since then: ","type":"text"},{"text":"\u003capplicable buckets>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Each can invalidate prior research assumptions. Re-validate the prior brief against the current machine before reusing it?\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes, re-validate the prior research","type":"text","marks":[{"type":"strong"}]},{"text":" — fold the validation into Phase 1 (briefly re-probe reachability for previously-blocked sources, confirm scoring still classifies the prior CLI's pattern correctly, etc.) before reusing the brief.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No, reuse the prior research as-is","type":"text","marks":[{"type":"strong"}]},{"text":" — proceed with the brief verbatim, even if the underlying machine assumptions are stale.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The prompt forces the user to acknowledge the version delta and explicitly accept (or refuse) re-validation. Skip it entirely on first generation, on same-version regenerations, or when no prior manifest exists.","type":"text"}]},{"type":"paragraph","content":[{"text":"If no CLI exists in the local library and no lock is active, run the ","type":"text"},{"text":"Public-library check","type":"text","marks":[{"type":"strong"}]},{"text":" below before proceeding to Phase 1.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Public-library check (registry.json)","type":"text"}]},{"type":"paragraph","content":[{"text":"The local library check above only sees CLIs this machine has already printed. A user on a fresh checkout — or one who typed a slightly different name than the published slug (","type":"text"},{"text":"Slack","type":"text","marks":[{"type":"code_inline"}]},{"text":" vs ","type":"text"},{"text":"slack-bot","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Cal","type":"text","marks":[{"type":"code_inline"}]},{"text":" vs ","type":"text"},{"text":"cal-com","type":"text","marks":[{"type":"code_inline"}]},{"text":"), or who described what they wanted in their own words (","type":"text"},{"text":"Hacker News reader","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Notion clone","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"prediction market","type":"text","marks":[{"type":"code_inline"}]},{"text":") — will miss CLIs that already exist in the public library. Scan ","type":"text"},{"text":"mvanhorn/printing-press-library/registry.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" to catch those cases before Phase 1 research begins (the expensive 30-60-minute portion of the pipeline).","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip this check entirely when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The local-library check above already prompted (mutual exclusion — do not double-ask).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"BROWSER_SNIFF_TARGET_URL","type":"text","marks":[{"type":"code_inline"}]},{"text":" is set (the user is building a from-website CLI; the registry indexes API CLIs and naming collisions are unlikely and intentional).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The user passed ","type":"text"},{"text":"--har \u003cpath>","type":"text","marks":[{"type":"code_inline"}]},{"text":" with an explicit ","type":"text"},{"text":"--name \u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a private capture.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Fetch the registry.","type":"text","marks":[{"type":"strong"}]},{"text":" Match the pattern ","type":"text"},{"text":"/printing-press-import","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"/printing-press-reprint","type":"text","marks":[{"type":"code_inline"}]},{"text":" already use:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"REGISTRY=$(mktemp)\nif ! gh api -H \"Accept: application/vnd.github.v3.raw\" \\\n repos/mvanhorn/printing-press-library/contents/registry.json \\\n > \"$REGISTRY\" 2>/dev/null; then\n echo \"Public-library check skipped: registry.json unreachable. Proceeding to Phase 1.\"\n rm -f \"$REGISTRY\"\n REGISTRY=\"\"\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not block on a network failure. After step 4 finishes, clean up the tempfile only if the fetch succeeded: ","type":"text"},{"text":"[ -n \"$REGISTRY\" ] && rm -f \"$REGISTRY\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". The failure branch above already removed it and set ","type":"text"},{"text":"REGISTRY=\"\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", so an unconditional ","type":"text"},{"text":"rm -f \"$REGISTRY\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" would run ","type":"text"},{"text":"rm -f \"\"","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Read the registry and reason about matches","type":"text","marks":[{"type":"strong"}]},{"text":" — do not gate on string equality alone. The file is small (~88 KB, ~135 entries today); read it directly and use judgment. Each entry has fields ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":" (slug), ","type":"text"},{"text":"category","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"api","type":"text","marks":[{"type":"code_inline"}]},{"text":" (brand display), ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"path","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"printer","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The user's argument may arrive in many shapes, and only some are catchable by deterministic match:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Slug or near-slug","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"Notion","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"notion-cli","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"notion-pp-cli","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Brand with punctuation","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"Cal.com","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Customer.io","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Archive.today","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Trigger.dev","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Concept or category","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"Hacker News reader","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Notion clone","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"prediction market","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"prediction-market CLI","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Adjacent product","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"Polymarket","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the registry has ","type":"text"},{"text":"kalshi","type":"text","marks":[{"type":"code_inline"}]},{"text":" (peer prediction market)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Genuinely novel","type":"text","marks":[{"type":"strong"}]},{"text":" — no useful overlap","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Classify the best match at three confidence levels and act only on the top two:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"High","type":"text","marks":[{"type":"strong"}]},{"text":" — same product under a different name (slug variant, brand vs slug form, ","type":"text"},{"text":"-cli","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"-pp-cli","type":"text","marks":[{"type":"code_inline"}]},{"text":" suffix variant, well-known alias). Examples: ","type":"text"},{"text":"Cal.com","type":"text","marks":[{"type":"code_inline"}]},{"text":" ↔ ","type":"text"},{"text":"cal-com","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Notion","type":"text","marks":[{"type":"code_inline"}]},{"text":" ↔ ","type":"text"},{"text":"notion-cli","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"slack","type":"text","marks":[{"type":"code_inline"}]},{"text":" ↔ ","type":"text"},{"text":"slack-bot","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Medium","type":"text","marks":[{"type":"strong"}]},{"text":" — same category and overlapping function; a reasonable user would want to know before building. Examples: ","type":"text"},{"text":"prediction market","type":"text","marks":[{"type":"code_inline"}]},{"text":" finds ","type":"text"},{"text":"kalshi","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Hacker News reader","type":"text","marks":[{"type":"code_inline"}]},{"text":" finds ","type":"text"},{"text":"hackernews","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Polymarket","type":"text","marks":[{"type":"code_inline"}]},{"text":" surfaces ","type":"text"},{"text":"kalshi","type":"text","marks":[{"type":"code_inline"}]},{"text":" as a peer.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Low","type":"text","marks":[{"type":"strong"}]},{"text":" — vaguely adjacent (e.g. \"payment gateway\" finding every payment-related CLI). Skip silently — false-positive prompts get dismissed reflexively at this gate.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Resist over-matching on ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" keywords. Most descriptions mention several adjacent concepts; matching liberally on description text produces noise. Use the description to ","type":"text"},{"text":"confirm","type":"text","marks":[{"type":"em"}]},{"text":" a name-or-category candidate, not to ","type":"text"},{"text":"discover","type":"text","marks":[{"type":"em"}]},{"text":" candidates from scratch.","type":"text"}]},{"type":"paragraph","content":[{"text":"Combo CLIs.","type":"text","marks":[{"type":"strong"}]},{"text":" When ","type":"text"},{"text":"SOURCE_PRIORITY","type":"text","marks":[{"type":"code_inline"}]},{"text":" is set (from the Multi-Source Priority Gate above), skip the single-source High/Medium/No-match branches below. Classify matches per source, then present a single combined prompt rather than asking N times. For combo runs the existing single-source CLIs are usually ","type":"text"},{"text":"informational","type":"text","marks":[{"type":"em"}]},{"text":" — the user came here to build a combo, so the recommended default is to continue with the combo rather than reprint a component standalone.","type":"text"}]},{"type":"paragraph","content":[{"text":"Cap displayed reprint options at 2 across all sources combined","type":"text","marks":[{"type":"strong"}]},{"text":" so the prompt fits the 4-option ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" limit (2 reprints + continue + abort). Pick the 2 best candidates by judgment in this order: (1) High over Medium, (2) primary-source over secondary-source (the first entry in ","type":"text"},{"text":"SOURCE_PRIORITY","type":"text","marks":[{"type":"code_inline"}]},{"text":" wins ties), (3) canonical slug over variant. If additional matches exist beyond the displayed 2, append \"(plus N other source matches)\" to the prompt body so the user knows the list is truncated. Omit sources with no match rather than listing them as empty rows. If no source has any match at High or Medium, print nothing and proceed to Phase 1.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Found matches across the sources you listed:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003csource1>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\u003centry1.name>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"\u003centry1.api>","type":"text","marks":[{"type":"code_inline"}]},{"text":") [High] — same product as ","type":"text"},{"text":"\u003csource1>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003csource2>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\u003centry2.name>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"\u003centry2.api>","type":"text","marks":[{"type":"code_inline"}]},{"text":") [Medium] — similar/adjacent","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is informational — these components already exist as single-source CLIs. Continue building the combo, switch to reprinting one standalone, or abort?","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue with the combo as planned (recommended)","type":"text","marks":[{"type":"strong"}]},{"text":" — the combo itself is the value-add; proceed to Phase 1 with all sources.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry1.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" standalone instead","type":"text","marks":[{"type":"strong"}]},{"text":" — invoke ","type":"text"},{"text":"/printing-press-reprint \u003centry1.name>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (abandons the combo for now).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry2.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" standalone instead","type":"text","marks":[{"type":"strong"}]},{"text":" — same, for the second candidate.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Abort","type":"text","marks":[{"type":"strong"}]},{"text":" — stop here.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"[High]","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"[Medium]","type":"text","marks":[{"type":"code_inline"}]},{"text":" tags surface the confidence so the user can distinguish \"this is literally the thing you named\" from \"this is adjacent.\" Tag in the bullet, not the option label, to keep options scannable.","type":"text"}]},{"type":"paragraph","content":[{"text":"Single-source CLIs.","type":"text","marks":[{"type":"strong"}]},{"text":" When ","type":"text"},{"text":"SOURCE_PRIORITY","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not set, use the branches below.","type":"text"}]},{"type":"paragraph","content":[{"text":"High match — prompt strongly.","type":"text","marks":[{"type":"strong"}]},{"text":" Under Claude Code, use ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":"; under another harness, use the equivalent native prompt primitive. The option set is the same either way.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Found ","type":"text"},{"text":"\u003centry.api>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in the public library (printed by ","type":"text"},{"text":"@","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry.printer>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", path ","type":"text"},{"text":"\u003centry.path>","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003centry.description>","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"URL: ","type":"text"},{"text":"https://github.com/mvanhorn/printing-press-library/tree/main/\u003centry.path>","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"This CLI already exists. What would you like to do?","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint with the current Printing Press (recommended)","type":"text","marks":[{"type":"strong"}]},{"text":" — end this run and invoke ","type":"text"},{"text":"/printing-press-reprint \u003centry.name>","type":"text","marks":[{"type":"code_inline"}]},{"text":". That skill pulls the existing CLI, carries prior research and post-publish patches into reconciliation, and regenerates under the current binary. Almost always the right choice when a user discovers the CLI exists.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue and build a fresh one anyway","type":"text","marks":[{"type":"strong"}]},{"text":" — proceed with the current run from scratch. Rare; appropriate only for a deliberate fork or variant.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Abort","type":"text","marks":[{"type":"strong"}]},{"text":" — stop here.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Multiple High matches — present each candidate, do not use the Medium-match phrasing.","type":"text","marks":[{"type":"strong"}]},{"text":" Rare — typically only happens when the user's argument is ambiguous between siblings like ","type":"text"},{"text":"slack","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"slack-bot","type":"text","marks":[{"type":"code_inline"}]},{"text":". Cap displayed candidates at 2 to stay within the 4-option prompt limit alongside continue/abort. If 3+ High candidates somehow qualify, pick the 2 best by judgment (typically the canonical slug match plus the next-most-likely alternative) and note \"(plus N other close matches)\" in the prompt body so the user knows the list is truncated.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Found multiple matches for ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in the public library — each appears to be the same product under a different name:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003centry1.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (","type":"text"},{"text":"\u003centry1.api>","type":"text","marks":[{"type":"code_inline"}]},{"text":") — ","type":"text"},{"text":"\u003centry1.description>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003centry2.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (","type":"text"},{"text":"\u003centry2.api>","type":"text","marks":[{"type":"code_inline"}]},{"text":") — ","type":"text"},{"text":"\u003centry2.description>","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Pick one to reprint, or continue/abort.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry1.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — invoke ","type":"text"},{"text":"/printing-press-reprint \u003centry1.name>","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry2.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — same, for the second candidate.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue and build a fresh one anyway","type":"text","marks":[{"type":"strong"}]},{"text":" — rare; appropriate only for a deliberate fork or variant.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Abort","type":"text","marks":[{"type":"strong"}]},{"text":" — stop here.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Medium match — present alternatives.","type":"text","marks":[{"type":"strong"}]},{"text":" Cap candidates at 2 to stay within the 4-option prompt limit alongside continue/abort.","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Found similar entries in the public library that don't exactly match ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" but may overlap:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003centry1.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (","type":"text"},{"text":"\u003centry1.api>","type":"text","marks":[{"type":"code_inline"}]},{"text":") — ","type":"text"},{"text":"\u003centry1.description>","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003centry2.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (","type":"text"},{"text":"\u003centry2.api>","type":"text","marks":[{"type":"code_inline"}]},{"text":") — ","type":"text"},{"text":"\u003centry2.description>","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Continue with ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" as planned, or reprint one of these instead?","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Continue with ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" as planned","type":"text","marks":[{"type":"strong"}]},{"text":" — proceed to Phase 1.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry1.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" instead","type":"text","marks":[{"type":"strong"}]},{"text":" — invoke ","type":"text"},{"text":"/printing-press-reprint \u003centry1.name>","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Reprint ","type":"text","marks":[{"type":"strong"}]},{"text":"\u003centry2.name>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" instead","type":"text","marks":[{"type":"strong"}]},{"text":" — same, for the second candidate.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Abort","type":"text","marks":[{"type":"strong"}]},{"text":" — stop here.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"No High or Medium match:","type":"text","marks":[{"type":"strong"}]},{"text":" print nothing, proceed to Phase 1.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"API Key Gate","type":"text","marks":[{"type":"strong"}]},{"text":" — Check whether this API requires authentication, then handle accordingly.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"First, determine if the API needs auth.","type":"text","marks":[{"type":"strong"}]},{"text":" Use these signals:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The spec has no ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"securityDefinitions","type":"text","marks":[{"type":"code_inline"}]},{"text":" section → likely no auth needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The API's endpoints are accessible without authentication (e.g., ESPN's undocumented endpoints, weather APIs, public data feeds) — note: \"no auth required\" does NOT mean the service has an official public API","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No env var matching the API name exists AND no known token pattern applies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Community docs or npm/PyPI wrappers describe the API as \"no auth required\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If no auth is required","type":"text","marks":[{"type":"strong"}]},{"text":", skip the key gate entirely. Proceed with: \"No authentication required for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":" — skipping API key gate.\" Do NOT call it \"a public API\" unless the service officially publishes one. Many services (ESPN, etc.) have unauthenticated endpoints without having an official API. Live smoke testing in Phase 5 will work without a key.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the API DOES require auth","type":"text","marks":[{"type":"strong"}]},{"text":", run the key gate:","type":"text"}]},{"type":"paragraph","content":[{"text":"Token detection order:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub: ","type":"text"},{"text":"GITHUB_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"GH_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"gh auth token","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discord: ","type":"text"},{"text":"DISCORD_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"DISCORD_BOT_TOKEN","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Linear: ","type":"text"},{"text":"LINEAR_API_KEY","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Notion: ","type":"text"},{"text":"NOTION_TOKEN","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stripe: ","type":"text"},{"text":"STRIPE_SECRET_KEY","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generic: ","type":"text"},{"text":"API_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"API_TOKEN","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"If a token IS found","type":"text","marks":[{"type":"strong"}]},{"text":", stop and explain:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Found ","type":"text"},{"text":"\u003cENV_VAR>","type":"text","marks":[{"type":"code_inline"}]},{"text":" in your environment. This key will be used ","type":"text"},{"text":"only","type":"text","marks":[{"type":"strong"}]},{"text":" for read-only live smoke testing in Phase 5 — listing, fetching, and health checks. It will never be used for write operations (create, update, delete). OK to use it?","type":"text"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user approves → proceed with the key available for Phase 5.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user declines → proceed without the key and display: \"Live smoke testing (Phase 5) will be skipped. The CLI will still be generated and verified against mock responses.\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If no token is found","type":"text","marks":[{"type":"strong"}]},{"text":", stop and ask:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"No API key detected for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":". You can provide one now for read-only live smoke testing in Phase 5, or continue without it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Set it with ","type":"text"},{"text":"export \u003cENV_VAR>=\u003cyour-key>","type":"text","marks":[{"type":"code_inline"}]},{"text":" or paste the key here.","type":"text"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user provides a key → proceed with the key available for Phase 5.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the user declines → proceed without the key and display: \"Live smoke testing (Phase 5) will be skipped. The CLI will still be generated and verified against mock responses.\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Resolve the API key gate (or skip it for public APIs) before moving to Phase 1.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1: Research Brief","type":"text"}]},{"type":"paragraph","content":[{"text":"When ","type":"text","marks":[{"type":"strong"}]},{"text":"BROWSER_SNIFF_TARGET_URL","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is set:","type":"text","marks":[{"type":"strong"}]},{"text":" Skip the catalog check, spec/docs search, and SDK wrapper search — none of these exist for an undocumented website feature. Focus research on understanding what the site/feature does, who uses it, what workflows it supports, and what competitors offer similar functionality. The spec will come from browser-sniffing in Phase 1.7.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before reading documentation, read ","type":"text"},{"text":"references/fetch-docs.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fetch-docs.md","title":null}}]},{"text":". Use ","type":"text"},{"text":"fetch-docs.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the API's primary docs, OpenAPI/Postman links, auth guides, error handling, rate limits, pagination, webhooks, and any per-endpoint reference page. Preserve exact status codes and inspect the returned local file directly so enum values, field constraints, casing, examples, and nav/link variants are not lost through summarization.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before starting research, check if the API has a built-in catalog entry:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press catalog show \u003capi> --json 2>/dev/null","type":"text"}]},{"type":"paragraph","content":[{"text":"If the catalog has an entry for this API, branch on the entry type:","type":"text"}]},{"type":"paragraph","content":[{"text":"Spec-based entry","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"spec_url","type":"text","marks":[{"type":"code_inline"}]},{"text":" populated) — present the user with a choice:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003cAPI> is in the built-in catalog (spec: \u003cspec_url>). Use the catalog config to skip discovery, or run full discovery?\"","type":"text"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If catalog config: use the spec_url from the catalog entry, skip the research/discovery phase","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If full discovery: proceed with the normal research workflow","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Wrapper-only entry","type":"text","marks":[{"type":"strong"}]},{"text":" (no ","type":"text"},{"text":"spec_url","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"wrapper_libraries","type":"text","marks":[{"type":"code_inline"}]},{"text":" populated) — this is a reverse-engineered API that has no official spec but has known community libraries. The catalog entry is a ","type":"text"},{"text":"discovery aid only","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"cli-printing-press generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" requires ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" and does not consume wrapper-library metadata, so there is no direct generation path from a wrapper-only entry today. Tell the user this up front via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003cAPI> has no official spec. The catalog knows about these community-maintained wrappers, but the Printing Press cannot generate a CLI directly from a wrapper. The next step has to be browser-sniffing the upstream to author an internal YAML spec, browser-sniffing or HAR-capturing the dominant source first and then using the multi-source aggregator pattern for secondary hand-authored sources, or hand-writing a Go module that imports the wrapper. Which path do you want?\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Present each ","type":"text"},{"text":"wrapper_libraries","type":"text","marks":[{"type":"code_inline"}]},{"text":" entry alongside the question with language, integration mode, and notes so the user can see what implementation backing exists. Example for ","type":"text"},{"text":"google-flights","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"krisukox/google-flights-api","type":"text","marks":[{"type":"strong"}]},{"text":" (Go, native, MIT) — Pure Go, importable; single-binary CLI with no runtime deps.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Record the user's choice (and the selected wrapper, when relevant) in ","type":"text"},{"text":"$API_RUN_DIR/state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" under an ","type":"text"},{"text":"implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" field so later phases can read it. For wrapper or hand-written-module paths, use ","type":"text"},{"text":"{ \"kind\": \"wrapper\", \"library\": \"\u003cname>\", \"url\": \"\u003curl>\", \"integration_mode\": \"native|subprocess|html-scrape\", \"next_step\": \"browser-sniff|hand-written-module\" }","type":"text","marks":[{"type":"code_inline"}]},{"text":". For the aggregator path, use ","type":"text"},{"text":"{ \"kind\": \"aggregator-pattern\", \"dominant_source\": \"\u003csource>\", \"spec_source\": \"browser-sniff|har|provided-spec\", \"spec_path\": \"\u003cpath-to-generated-spec>\", \"secondary_sources\": [\"\u003csource>\"], \"next_step\": \"aggregator-pattern\" }","type":"text","marks":[{"type":"code_inline"}]},{"text":"; do not populate ","type":"text"},{"text":"library","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"integration_mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" unless a specific secondary source is backed by a wrapper. This field is for skill bookkeeping; the generator does not currently read it. If the user picks browser-sniff, route into the Phase 1.7 browser-sniff path to produce a spec, then run ","type":"text"},{"text":"generate --spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" against it. If the user picks the aggregator path, first route the dominant source through Phase 1.7 browser-sniff or HAR capture to produce the primary spec, then read and apply ","type":"text"},{"text":"references/aggregator-pattern.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/aggregator-pattern.md","title":null}}]},{"text":": generate from that spec, then hand-author the secondary source clients and ","type":"text"},{"text":"sources","type":"text","marks":[{"type":"code_inline"}]},{"text":" command tree. If the user picks a hand-written module, stop the press here and hand off — there is no generator path to drop them into.","type":"text"}]},{"type":"paragraph","content":[{"text":"No catalog hit","type":"text","marks":[{"type":"strong"}]},{"text":" — proceed normally without mentioning the catalog.","type":"text"}]},{"type":"paragraph","content":[{"text":"Adding new wrapper-only APIs:","type":"text","marks":[{"type":"strong"}]},{"text":" drop a YAML file in ","type":"text"},{"text":"catalog/","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"wrapper_libraries","type":"text","marks":[{"type":"code_inline"}]},{"text":" populated and rebuild the binary. No skill changes needed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write one build-driving brief, not a stack of phase essays.","type":"text"}]},{"type":"paragraph","content":[{"text":"The brief must answer:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What is this API actually used for?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What are the top 3-5 power-user workflows?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What are the top table-stakes competitor features?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What data deserves a local store?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Why would someone install this CLI instead of the incumbent?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"What is the product name and thesis?","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Research checklist:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Find the spec or docs source. For docs pages whose details affect generation, fetch the raw page with ","type":"text"},{"text":"fetch-docs.sh","type":"text","marks":[{"type":"code_inline"}]},{"text":", then read/grep the returned path directly.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Find the top 1-2 competitors","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check GitHub issues on the top wrapper/SDK repo for \"403\", \"blocked\", \"broken\", \"deprecated\", \"rate limit\".","type":"text","marks":[{"type":"strong"}]},{"text":" If multiple issues report the API is inaccessible or broken, flag this in the research brief as a reachability risk. This is critical for unofficial/reverse-engineered APIs.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Find official and popular SDK wrappers on npm (","type":"text"},{"text":"site:npmjs.com","type":"text","marks":[{"type":"code_inline"}]},{"text":") and PyPI (","type":"text"},{"text":"site:pypi.org","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Find 2-3 concrete user pain points","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify the highest-gravity entities","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pick the top 3-5 commands that matter most","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not produce separate mandatory documents for:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"workflow ideation","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"parity audit","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"data-layer prediction","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"product thesis","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Put them in the one brief.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write:","type":"text"}]},{"type":"paragraph","content":[{"text":"$RESEARCH_DIR/\u003cstamp>-feat-\u003capi>-pp-cli-brief.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Suggested shape:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"# \u003cAPI> CLI Brief\n\n## API Identity\n- Domain:\n- Users:\n- Data profile:\n\n## Reachability Risk\n- [None / Low / High] [evidence: e.g., \"6 open issues on reteps/redfin about 403 errors since 2025\"]\n- Tier/permission hints from 4xx body: [omit when absent; otherwise quote the matched bounded line(s) from Phase 1.9]\n- Probe-safe endpoint used: [omit when absent; otherwise \"\u003cMETHOD> \u003cpath>\" from `x-pp-safe-probe`]\n\n## Top Workflows\n1. ...\n\n## Table Stakes\n- ...\n\n## Data Layer\n- Primary entities:\n- Sync cursor:\n- FTS/search:\n\n## Codebase Intelligence\n- [DeepWiki findings if available, otherwise omit this section]\n- Source: DeepWiki analysis of {owner}/{repo}\n- Auth: [token type, header, env var pattern]\n- Data model: [primary entities and relationships]\n- Rate limiting: [limits and behavior]\n- Architecture: [key insight about internal design]\n\n## User Vision\n- [USER_BRIEFING_CONTEXT if provided, otherwise omit this section]\n\n## Source Priority\n- [Only present for combo CLIs. Copy the confirmed ordering from `source-priority.json`.]\n- Primary: \u003cSource A> — [spec state: official / community-wrapper / no-spec-browser-sniff-required] — [auth: free / paid]\n- Secondary: \u003cSource B> — [...]\n- Tertiary: \u003cSource C> — [...]\n- **Economics:** [e.g., \"Primary is free; paid key for \u003cSource B> is scoped to its own commands only.\"]\n- **Inversion risk:** [e.g., \"Primary has no OpenAPI; secondary has 53-endpoint spec. Do NOT let spec completeness invert the ordering.\"]\n\n## Product Thesis\n- Name:\n- Why it should exist:\n\n## Build Priorities\n1. ...\n2. ...\n3. ...","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY: Before proceeding to Phase 1.5 (Absorb Gate), you MUST evaluate Phase 1.6 (Pre-Browser-Sniff Auth Intelligence), Phase 1.7 (Browser-Sniff Gate), and Phase 1.8 (Crowd-Sniff Gate) below.","type":"text","marks":[{"type":"strong"}]},{"text":" If no spec source has been resolved yet (no ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":", no ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":", no catalog spec URL), the browser-sniff gate decision matrix MUST be evaluated. Do not skip to Phase 1.5.","type":"text"}]},{"type":"paragraph","content":[{"text":"Phase 1.5 will refuse to proceed without a ","type":"text","marks":[{"type":"strong"}]},{"text":"browser-browser-sniff-gate.json","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" marker file.","type":"text","marks":[{"type":"strong"}]},{"text":" Phase 1.7 writes this file with one entry per source (one entry for single-source CLIs, one entry per named source for combo CLIs). Missing marker = HARD STOP back to Phase 1.7. See Phase 1.7 \"Enforcement\" below for the contract.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.6: Pre-Browser-Sniff Auth Intelligence","type":"text"}]},{"type":"paragraph","content":[{"text":"After Phase 1 research completes, analyze findings to proactively assess what auth context the user could provide. This step uses research intelligence to ask the right question before browser-sniffing starts, rather than waiting for the user to volunteer \"I logged in.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip this step if:","type":"text","marks":[{"type":"strong"}]},{"text":" The briefing (Orientation & Briefing section) already captured auth context (","type":"text"},{"text":"AUTH_CONTEXT","type":"text","marks":[{"type":"code_inline"}]},{"text":" is set from the user selecting \"I have an API key or I'm logged in\").","type":"text"}]},{"type":"paragraph","content":[{"text":"Classify the API's auth profile from research findings:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Signal from research","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Auth profile","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"What to ask","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Community wrappers use API keys (e.g., ","type":"text"},{"text":"STRIPE_SECRET_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":"), MCP source shows ","type":"text"},{"text":"Authorization: Bearer","type":"text","marks":[{"type":"code_inline"}]},{"text":" headers, spec has ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" section","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"API key auth","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"Do you have an API key for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":"?\"","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Site has user accounts, research found auth-only features (order history, saved items, rewards, account settings), login pages exist","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Browser session auth","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\"This API has authenticated endpoints ([list specific features from research, e.g., order history, saved addresses, rewards]). Are you logged in to ","type":"text"},{"text":"\u003csite>","type":"text","marks":[{"type":"code_inline"}]},{"text":" in your browser? The browser-sniff will find more endpoints if you are.\"","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Endpoints accessible without auth, no login-gated features found, community wrappers describe API as \"no auth required\"","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No auth needed","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip this step silently","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Both API key AND browser session features found","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Dual auth","type":"text","marks":[{"type":"strong"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ask about both: API key for smoke testing, browser session for browser-sniff","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Name the specific features the user would unlock.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not say \"auth would help.\" Say \"This API has order history, saved addresses, and rewards that require a logged-in session.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Where signals come from:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Phase 1 brief's \"Data profile\" and \"Top Workflows\" sections","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Phase 1.5a MCP source code analysis (auth patterns, token formats)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Community wrapper README \"auth\" or \"authentication\" sections","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The API Key Gate's token detection (Phase 0.5) — if it already found a key, don't re-ask","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For API key auth:","type":"text","marks":[{"type":"strong"}]},{"text":" Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"Do you have an API key for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":"? It will be used for read-only live smoke testing in Phase 5.\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes","type":"text","marks":[{"type":"strong"}]},{"text":" — user provides the key or confirms it's in the environment","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No, continue without it","type":"text","marks":[{"type":"strong"}]},{"text":" — skip live smoke testing","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"If the user provides a key, set it in ","type":"text"},{"text":"AUTH_CONTEXT","type":"text","marks":[{"type":"code_inline"}]},{"text":" so the API Key Gate (Phase 0.5) does not re-ask.","type":"text"}]},{"type":"paragraph","content":[{"text":"For browser session auth:","type":"text","marks":[{"type":"strong"}]},{"text":" Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":" has authenticated endpoints ([list features]). Are you logged in to ","type":"text"},{"text":"\u003csite>","type":"text","marks":[{"type":"code_inline"}]},{"text":" in your browser? If so, the generated CLI will support ","type":"text"},{"text":"auth login --chrome","type":"text","marks":[{"type":"code_inline"}]},{"text":" — you'll be able to authenticate just by being logged into the site in Chrome. No API key needed.\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes, I'm logged in","type":"text","marks":[{"type":"strong"}]},{"text":" — I'll use your session during browser-sniff and enable browser auth in the CLI","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No, but I can log in","type":"text","marks":[{"type":"strong"}]},{"text":" — I'll help you log in before browser-sniffing","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No, skip authenticated endpoints","type":"text","marks":[{"type":"strong"}]},{"text":" — browser-sniff only public endpoints","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Set ","type":"text"},{"text":"AUTH_SESSION_AVAILABLE=true","type":"text","marks":[{"type":"code_inline"}]},{"text":" if the user selects option 1 or 2. The Browser-Sniff Gate (Phase 1.7) will use this flag. After traffic capture, Step 2d in ","type":"text"},{"text":"references/browser-sniff-capture.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/browser-sniff-capture.md","title":null}}]},{"text":" validates that cookie replay works before enabling browser auth in the generated CLI.","type":"text"}]},{"type":"paragraph","content":[{"text":"For dual auth:","type":"text","marks":[{"type":"strong"}]},{"text":" Ask about both in sequence — API key first (simple env var check), then browser session.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.7: Browser-Sniff Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"After Phase 1 research, evaluate whether browser-sniffing the live site would improve the spec. This phase MUST produce a decision marker file for every source named in the briefing before Phase 1.5 can proceed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Browser discovery is temporary discovery, not a printed-CLI runtime.","type":"text","marks":[{"type":"strong"}]},{"text":" Use browser-use, agent-browser, the Claude chrome-MCP (","type":"text"},{"text":"mcp__claude-in-chrome__*","type":"text","marks":[{"type":"code_inline"}]},{"text":", when the runtime exposes it), or a manual HAR (optionally augmented with computer-use screenshots for visual guidance, when ","type":"text"},{"text":"mcp__computer-use__*","type":"text","marks":[{"type":"code_inline"}]},{"text":" is exposed) to learn the hidden web contract: URLs, methods, persisted GraphQL hashes, BFF envelopes, response shapes, cookies, CSRF/header construction, HTML/SSR/RSS/JSON-LD surfaces, and whether replay is viable. The final printed CLI must use replayable HTTP, Surf/browser-compatible HTTP, browser-clearance cookie import plus replay, or structured HTML/SSR/RSS extraction. If the only working path requires live page-context execution, HOLD or pivot scope — do not generate a resident browser sidecar transport.","type":"text"}]},{"type":"paragraph","content":[{"text":"Automatic offer, explicit consent.","type":"text","marks":[{"type":"strong"}]},{"text":" The Printing Press decides when browser discovery should be offered, but opening Chrome, attaching to a browser session, installing browser-use/agent-browser, asking the user to solve a challenge, or driving the user's logged-in Chrome via the chrome-MCP requires explicit user approval through the Phase 0 website choice or the Phase 1.7 ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" prompt. ","type":"text"},{"text":"Approval at Phase 1.7 covers the full fallback set","type":"text","marks":[{"type":"strong"}]},{"text":" including chrome-MCP and computer-use when Step 2c.5's recovery menu later offers them — picking chrome-MCP at the recovery menu is a refinement of the Phase 1.7 consent, not a new consent surface. The disclosure language used at the Phase 1.7 prompt MUST enumerate these possibilities so the user understands what they are approving:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"Approving browser-sniff means the agent may run browser-use, agent-browser, ask you for a manual DevTools HAR export, or — if the default backends get blocked by an anti-bot gate and your runtime exposes them — drive your already-running Chrome via the chrome-MCP browser extension, or take read-only screenshots of your DevTools window via computer-use to guide you through the HAR export. Capture artifacts are written to ","type":"text"},{"text":"$DISCOVERY_DIR/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and credential headers are stripped at write time. The chrome-MCP option uses your real logged-in Chrome session in a fresh capture tab; the agent never navigates your existing tabs.\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"If chrome-MCP picks up later in Step 2c.5's recovery menu, do NOT re-fire a per-invocation consent prompt — Phase 1.7's pre-approval covers it. The recovery menu lists chrome-MCP as one of the fallback options the user already pre-approved; the user's selection in the menu is a backend choice, not a new consent step.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Enforcement: the browser-browser-sniff-gate.json marker file","type":"text"}]},{"type":"paragraph","content":[{"text":"Phase 1.7 is a hard gate. Phase 1.5 reads a marker file and refuses to proceed without it. The model cannot skip this phase by reasoning around it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Marker file location:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Marker file shape:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"run_id\": \"20260411-000903\",\n \"sources\": [\n {\n \"source_name\": \"\u003cexact name from briefing, e.g., kayak-direct>\",\n \"decision\": \"approved | declined | skip-silent | pre-approved\",\n \"reason\": \"\u003cone-line justification>\",\n \"asked_at\": \"2026-04-11T00:10:00Z\"\n }\n ]\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Decision values:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"approved","type":"text","marks":[{"type":"code_inline"}]},{"text":" — user selected a browser-sniff option via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":". Proceed to \"If user approves browser-sniff\".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"declined","type":"text","marks":[{"type":"code_inline"}]},{"text":" — user explicitly declined browser-sniff via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":". Proceed to \"If user declines browser-sniff\".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":" — gate was silently skipped per the decision matrix (spec complete, ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":" provided, ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" provided, or login required with ","type":"text"},{"text":"AUTH_SESSION_AVAILABLE=false","type":"text","marks":[{"type":"code_inline"}]},{"text":"). The ","type":"text"},{"text":"reason","type":"text","marks":[{"type":"code_inline"}]},{"text":" field names which.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"pre-approved","type":"text","marks":[{"type":"code_inline"}]},{"text":" — user already chose \"The website itself\" in Phase 0, where the prompt disclosed temporary Chrome/browser capture during generation, so ","type":"text"},{"text":"BROWSER_SNIFF_TARGET_URL","type":"text","marks":[{"type":"code_inline"}]},{"text":" was set and the question was answered there.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Every path through Phase 1.7 MUST write a marker entry","type":"text","marks":[{"type":"strong"}]},{"text":" — approve, decline, and every silent-skip case. There is no code path that proceeds to Phase 1.5 without writing the marker.","type":"text"}]},{"type":"paragraph","content":[{"text":"asked_at","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is mandatory.","type":"text","marks":[{"type":"strong"}]},{"text":" It must reflect the actual time ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" was invoked (or the time the silent-skip decision was made). Fabricated timestamps are a plan violation.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Banned skip reasons","type":"text"}]},{"type":"paragraph","content":[{"text":"The following rationales are NOT valid reasons to skip the browser-sniff gate. If any of these apply, you MUST still ask the user via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" and record their answer in the marker file:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The target is client-rendered and needs Playwright\"","type":"text","marks":[{"type":"strong"}]},{"text":" — browser capture tools (browser-use, agent-browser) exist specifically to handle client-rendered sites. A hard-to-browser-sniff target is not the same as an impossible one. Ask.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Direct HTTP/curl got 403, 429, Cloudflare, Vercel, WAF, DataDome, or bot-detection HTML\"","type":"text","marks":[{"type":"strong"}]},{"text":" — direct HTTP reachability failure is exactly when browser capture is valuable. Do not pivot to RSS, docs-only, official API, or a smaller product shape before attempting the approved browser-sniff. Route to cleared-browser capture instead.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Direct HTTP/curl got HTTP ","type":"text","marks":[{"type":"strong"}]},{"text":"200","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" but only a content-less shell, interstitial, or deterministic-size truncation\"","type":"text","marks":[{"type":"strong"}]},{"text":" — a 200-served shell is a clearance or JavaScript challenge, not a clean response. Do not conclude ","type":"text"},{"text":"IP-blocked","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"rate-limited","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"wait it out","type":"text","marks":[{"type":"code_inline"}]},{"text":" from this shape. Before declaring the target unreachable, climb the ladder: probe-reachability body-check, curl-impersonate/TLS check, real-browser cookie-warm via the cleared-browser path or chrome-MCP when available, then ask the user. Use chrome-MCP to understand the wall even when it cannot export cookie values.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The 3-minute time budget looks tight\"","type":"text","marks":[{"type":"strong"}]},{"text":" — the time budget applies AFTER the user approves browser-sniff, not before. You do not pre-judge whether a browser-sniff will fit the budget. Ask. If the budget blows after the user approves, fall back per the Time Budget rules below.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"We have a substitute data source from another API\"","type":"text","marks":[{"type":"strong"}]},{"text":" — substituting one source for another is the user's call, not yours. If the user named a specific site or feature (e.g., Kayak /direct), they chose it deliberately. Ask about that exact source. Offering a different data source is a separate conversation AFTER the gate, not a reason to skip it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Installing browser-use or agent-browser is friction\"","type":"text","marks":[{"type":"strong"}]},{"text":" — the browser-sniff capture reference already documents the install path. Tooling friction is not a valid skip reason. Ask.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The documentation looks thorough enough\"","type":"text","marks":[{"type":"strong"}]},{"text":" — the decision matrix already handles this case explicitly. If research found that competitors or community projects reference more endpoints than the spec covers, that IS a gap and you MUST ask.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The user said 'let's go' earlier and implicitly approved everything\"","type":"text","marks":[{"type":"strong"}]},{"text":" — \"let's go\" at the briefing stage is consent to proceed with research, not standing approval for every future decision. Ask each gate individually.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The default browser-use / agent-browser path got hard-blocked by a WAF, so the only remaining option is to pivot scope or fall back to RSS/docs\"","type":"text","marks":[{"type":"strong"}]},{"text":" — this is exactly when the chrome-MCP and computer-use fallback options enter, when the runtime exposes them. Step 1 of ","type":"text"},{"text":"references/browser-sniff-capture.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" detects which fallback MCPs are available; Step 2c.5 composes the recovery menu including those fallbacks; the gate is \"ask before giving up,\" not \"auto-pivot when blocked.\" Do NOT skip the Step 2c.5 menu. Do NOT pivot scope or substitute an alternate target without first asking the user via that menu.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"These banned reasons all fired at once in a past combo-CLI run and caused a user-critical source to be silently swapped out. The marker file exists so this cannot happen again. If you find yourself writing a phrase like \"skipping browser-sniff because X\" where X is one of the above, stop and call ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Combo CLIs: per-source enforcement","type":"text"}]},{"type":"paragraph","content":[{"text":"When the briefing names multiple sources (e.g., \"Google Flights + Kayak + FlightAware\"), each named source is evaluated independently. The marker file has one entry per source. All entries must be present before Phase 1.5 can proceed.","type":"text"}]},{"type":"paragraph","content":[{"text":"Source identification rule:","type":"text","marks":[{"type":"strong"}]},{"text":" source names come from the briefing, verbatim. Use the user's exact wording as the ","type":"text"},{"text":"source_name","type":"text","marks":[{"type":"code_inline"}]},{"text":" (normalized to kebab-case is fine: \"Kayak /direct\" → ","type":"text"},{"text":"kayak-direct","type":"text","marks":[{"type":"code_inline"}]},{"text":", \"Google Flights\" → ","type":"text"},{"text":"google-flights","type":"text","marks":[{"type":"code_inline"}]},{"text":", \"FlightAware\" → ","type":"text"},{"text":"flightaware","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Do not merge sources. Do not drop one in favor of another.","type":"text"}]},{"type":"paragraph","content":[{"text":"Per-source decision flow:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"For each named source, run the \"When to offer browser-sniff\" decision matrix independently, using the research findings for THAT source. Each source produces its own ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" call or its own silent-skip marker entry.","type":"text"}]},{"type":"paragraph","content":[{"text":"Combo CLI example","type":"text","marks":[{"type":"strong"}]},{"text":" (flightgoat pattern — directional guidance, not prescription):","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Source","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Spec state","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Expected decision","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"flightaware","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Documented OpenAPI spec found (53 endpoints, appears complete)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":" with reason ","type":"text"},{"text":"spec-complete","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"google-flights","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No official spec, but community wrapper exists (","type":"text"},{"text":"krisukox/google-flights-api","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ask via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" → record user's answer","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"kayak-direct","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No spec, no wrapper, user named this as a key feature","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ask via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" → record user's answer","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"The marker file for this run would contain three entries. Phase 1.5 would HALT if any were missing.","type":"text"}]},{"type":"paragraph","content":[{"text":"When the user cares about only one source:","type":"text","marks":[{"type":"strong"}]},{"text":" you still ask for all sources that trigger the gate. The user can decline the others. Asking is cheap. Skipping silently breaks the contract.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Skip this gate entirely when","type":"text"}]},{"type":"paragraph","content":[{"text":"These are the only cases where Phase 1.7 is bypassed as a whole (not just skipped for one source). Even in these cases, a marker file with a single ","type":"text"},{"text":"skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":" entry is written to satisfy Phase 1.5's check:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User passed ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the spec is the canonical source for every named source → marker: ","type":"text"},{"text":"{ \"source_name\": \"\u003capi>\", \"decision\": \"skip-silent\", \"reason\": \"user-provided-spec\" }","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"User passed ","type":"text"},{"text":"--har","type":"text","marks":[{"type":"code_inline"}]},{"text":" → marker: ","type":"text"},{"text":"{ \"source_name\": \"\u003capi>\", \"decision\": \"skip-silent\", \"reason\": \"user-provided-har\" }","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"BROWSER_SNIFF_TARGET_URL","type":"text","marks":[{"type":"code_inline"}]},{"text":" is set from Phase 0 (user chose \"The website itself\") → marker: ","type":"text"},{"text":"{ \"source_name\": \"\u003capi>\", \"decision\": \"pre-approved\", \"reason\": \"phase-0-website-choice\" }","type":"text","marks":[{"type":"code_inline"}]},{"text":", then go directly to \"If user approves browser-sniff\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Direct HTTP challenge rule","type":"text"}]},{"type":"paragraph","content":[{"text":"If a reachability probe during Phase 1 research returns bot-protection evidence (","type":"text"},{"text":"403","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"429","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cf-mitigated: challenge","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"x-vercel-mitigated: challenge","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"x-vercel-challenge-token","type":"text","marks":[{"type":"code_inline"}]},{"text":", AWS WAF, DataDome, PerimeterX, CAPTCHA, \"Just a moment\", \"access denied\"), ","type":"text"},{"text":"run the no-browser reachability probe before announcing any browser escalation","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press probe-reachability \"\u003curl>\" --json","type":"text"}]},{"type":"paragraph","content":[{"text":"This is non-negotiable. ","type":"text"},{"text":"Do not present transport tiers as a peer menu for the user to choose between.","type":"text","marks":[{"type":"strong"}]},{"text":" Phrases like \"Browser-sniff + clearance cookie\", \"Browser-sniff with Surf-only\", \"Try without browser at all\", or \"Browser-sniff, prefer Surf\" route the user through implementation choices (Surf vs cookie vs full browser) they don't have context to make. The classifier is ","type":"text"},{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":"; the agent runs it and decides. Intent-level menus are fine — \"Browser-sniff or HOLD?\", \"Browser-sniff or pick a different API?\", or the standard yes/no browser-sniff offers below all ask about goals, not transport, and remain available.","type":"text"}]},{"type":"paragraph","content":[{"text":"Escalate consent in the order the agent actually needs it, not bundled up-front:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runtime probe (silent)","type":"text","marks":[{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":" runs without prompting. The user already opted into \"the website itself\" or equivalent in Phase 0; running an HTTP request needs no further consent.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Browser-sniff offer (intent prompt)","type":"text","marks":[{"type":"strong"}]},{"text":" — Phase 1.7's normal \"Browser-Sniff as enrichment\" / \"Browser-Sniff as primary\" prompts ask whether to do browser-sniff at all. These are intent-level. Show them when the discovery matrix says to.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Chrome attach (separate consent if escalation happens)","type":"text","marks":[{"type":"strong"}]},{"text":" — when the agent actually needs to open or attach to Chrome (because the discovery flow requires a real browser, or because ","type":"text"},{"text":"mode: browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" means the runtime needs cookie capture), surface that as its own moment so the user knows they may need to solve a challenge or sign in. The user-facing prompts at lines below already disclose Chrome attach as a possibility; that is the right place to confirm. Do not pre-announce Chrome attach when the probe has already settled the runtime as ","type":"text"},{"text":"browser_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the spec is complete enough to skip discovery — there is no Chrome attach to announce in that path.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Two concerns are decided here, separately:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Runtime","type":"text","marks":[{"type":"strong"}]},{"text":" (does the printed CLI need browser-compatible HTTP, a clearance cookie, or live page-context execution?) — settled entirely by ","type":"text"},{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Discovery","type":"text","marks":[{"type":"strong"}]},{"text":" (does Phase 1.7 need to capture XHR traffic via a real browser to learn endpoints?) — settled by Phase 1.7's normal \"When to offer browser-sniff\" decision matrix above. Independent of runtime.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The probe runs stdlib HTTP, then Surf with a Chrome TLS fingerprint, and emits one of ","type":"text"},{"text":"standard_http | browser_http | browser_clearance_http | unknown","type":"text","marks":[{"type":"code_inline"}]},{"text":". Apply ","type":"text"},{"text":"mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the ","type":"text"},{"text":"runtime","type":"text","marks":[{"type":"strong"}]},{"text":" decision:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"mode: standard_http","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — runtime is plain HTTP (the original probe was transient). Continue Phase 1.7 normally; the discovery decision is unchanged.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"mode: browser_http","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — ","type":"text"},{"text":"runtime is settled: ship Surf transport","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"UsesBrowserHTTPTransport","type":"text","marks":[{"type":"code_inline"}]},{"text":" will be set in the generator's traffic-analysis hints). The printed CLI will not include ","type":"text"},{"text":"auth login --chrome","type":"text","marks":[{"type":"code_inline"}]},{"text":" for clearance cookies — Surf alone clears the challenge. Continue Phase 1.7's discovery decision normally; the existing \"Browser-Sniff as enrichment\" / \"Browser-Sniff as primary\" prompts (above) are framed around endpoint discovery and are correct as-written. Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" add clearance-cookie language to those prompts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"mode: browser_clearance_http","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — both probes hit protection signals. The runtime needs more than Surf (clearance cookie or live page-context execution; the probe cannot distinguish), so a real browser capture is required to find out. Proceed through Phase 1.7's normal browser-sniff offer (intent-level yes/no). The consent for Chrome attach happens at the moment the agent actually opens/attaches, where the user-facing prompts in ","type":"text"},{"text":"references/browser-sniff-capture.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" already disclose what's about to happen and may ask the user to solve a challenge. Note in the brief that runtime is provisionally ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" pending capture results.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"mode: unknown","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — probes failed at the transport layer (DNS/timeout/5xx). Fall through to the existing browser-sniff offer; the user decides whether to retry or pivot.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When browser-sniff is approved or pre-approved AND the probe says ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"unknown","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" offer alternate CLI shapes (RSS-first, official API, docs-only, narrower scope, \"try anyway\") before a real browser capture has been attempted.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" write the brief as if browser-sniff is complete after only curl/direct HTTP probes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If browser automation tooling is unavailable, offer the user a manual HAR path before offering any scope pivot.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Only after the browser capture attempt fails by the criteria in ","type":"text"},{"text":"references/browser-sniff-capture.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" may you ask whether to pivot to RSS, official API, docs-only, or a smaller CLI scope.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Time budget","type":"text"}]},{"type":"paragraph","content":[{"text":"The browser-sniff gate should complete within 3 minutes of the user approving browser-sniff. If browser automation tooling fails to produce results after 3 minutes of attempts, fall back immediately:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a spec already exists (enrichment mode): \"Browser-Sniff failed after 3 minutes — proceeding with existing spec.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If no spec exists (primary mode): \"Browser-Sniff failed after 3 minutes — falling back to --docs generation.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If browser-sniff was approved or pre-approved and direct HTTP showed challenge/bot-protection evidence, do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" auto-fall back to docs/official API, even when ","type":"text"},{"text":"BROWSER_SNIFF_TARGET_URL","type":"text","marks":[{"type":"code_inline"}]},{"text":" is unset. Ask whether the user wants to provide a HAR manually, retry cleared-browser capture, or discuss alternate CLI scope.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do NOT spend time debugging tool integration issues. Browser-sniff is a temporary discovery aid, not the product runtime. If the first approach fails, fall back to the next option — do not retry the same broken approach.","type":"text"}]},{"type":"paragraph","content":[{"text":"The time budget applies AFTER the user approves.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not use it as a reason to skip the gate before asking.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When to offer browser-sniff","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Spec found?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Research shows gaps?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Auth required?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes — docs or competitors show significantly more endpoints than the spec","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MUST offer browser-sniff as enrichment","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No — spec appears complete","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip silently (write marker with ","type":"text"},{"text":"decision: skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Community docs exist (e.g., Public-ESPN-API)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MUST offer browser-sniff OR --docs","type":"text","marks":[{"type":"strong"}]},{"text":" — present both options so the user decides","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No docs found either","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"MUST offer browser-sniff as primary discovery","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes (login) + ","type":"text"},{"text":"AUTH_SESSION_AVAILABLE=true","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Offer authenticated browser-sniff","type":"text","marks":[{"type":"strong"}]},{"text":" — the user confirmed a session in Phase 1.6","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"N/A","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes (login) + ","type":"text"},{"text":"AUTH_SESSION_AVAILABLE=false","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip — fall back to ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]},{"text":" (write marker with ","type":"text"},{"text":"decision: skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"reason: login-required-no-session","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Gap detection heuristic:","type":"text","marks":[{"type":"strong"}]},{"text":" If Phase 1 research found documentation, competitor tools, or community projects that reference significantly more endpoints or features than the resolved spec covers, that's a gap signal. Example: \"The Zuplo OpenAPI spec has 42 endpoints, but the Public-ESPN-API docs describe 370+.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"When the decision matrix says \"Offer browser-sniff\", you MUST ask the user via ","type":"text","marks":[{"type":"strong"}]},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" Skipping the question and writing a ","type":"text"},{"text":"skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":" marker is a contract violation — ","type":"text"},{"text":"skip-silent","type":"text","marks":[{"type":"code_inline"}]},{"text":" is only valid when the matrix says \"Skip silently\" or one of the Banned Skip Reasons is the only thing holding you back (in which case, you should be asking anyway).","type":"text"}]},{"type":"paragraph","content":[{"text":"Every browser-sniff approval prompt must make the consent boundary explicit:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"browser discovery may open or attach to Chrome during generation,","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"it may ask the user to log in or solve a challenge,","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"it may request permission to install or upgrade browser-use/agent-browser if missing,","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"the printed CLI will only ship if discovery finds a replayable surface and will not keep a browser running as normal command transport.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Browser-Sniff as enrichment (spec exists but has gaps)","type":"text"}]},{"type":"paragraph","content":[{"text":"Present to the user via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"Found a spec with ","type":"text"},{"text":"N endpoints","type":"text","marks":[{"type":"strong"}]},{"text":", but research shows the live API likely has more (competitors reference M+ features). Want me to use temporary browser discovery on ","type":"text"},{"text":"\u003curl>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to find replayable endpoints the spec missed? I may open or attach to Chrome during generation, and I will ask before installing or upgrading browser-use/agent-browser.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — browser-sniff and merge","type":"text","marks":[{"type":"strong"}]},{"text":" (temporarily open or attach to Chrome during generation, capture traffic, then merge only replayable discovered endpoints with the existing spec. Ask before installing capture tools.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — use existing spec","type":"text","marks":[{"type":"strong"}]},{"text":" (proceed with what we have)","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Browser-Sniff as primary (no spec found)","type":"text"}]},{"type":"paragraph","content":[{"text":"Present to the user via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"If ","type":"text","marks":[{"type":"strong"}]},{"text":"AUTH_SESSION_AVAILABLE=true","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", include an authenticated browser-sniff option:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"No OpenAPI spec found for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Want me to browser-sniff ","type":"text"},{"text":"\u003clikely-url>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to discover the API from live traffic?\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — authenticated browser-sniff","type":"text","marks":[{"type":"strong"}]},{"text":" (temporarily open or attach to Chrome during generation, use your browser session to discover public and authenticated traffic, and generate only replayable CLI surfaces. Recommended since you confirmed a session.) ","type":"text"},{"text":"(Only show when ","type":"text","marks":[{"type":"em"}]},{"text":"AUTH_SESSION_AVAILABLE=true","type":"text","marks":[{"type":"code_inline"},{"type":"em"}]},{"text":")","type":"text","marks":[{"type":"em"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — browser-sniff the live site","type":"text","marks":[{"type":"strong"}]},{"text":" (temporarily browse ","type":"text"},{"text":"\u003curl>","type":"text","marks":[{"type":"code_inline"}]},{"text":" anonymously, capture API/HTML traffic, and generate a spec only from replayable surfaces. Ask before installing capture tools.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — use docs instead","type":"text","marks":[{"type":"strong"}]},{"text":" (attempt ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]},{"text":" generation from documentation pages)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — I'll provide a spec or HAR","type":"text","marks":[{"type":"strong"}]},{"text":" (user will supply input manually)","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"AUTH_SESSION_AVAILABLE=false","type":"text","marks":[{"type":"code_inline"}]},{"text":", show only options 2-4 (the existing 3-option prompt).","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If user approves browser-sniff","type":"text"}]},{"type":"paragraph","content":[{"text":"Before doing anything else, write the marker entry","type":"text","marks":[{"type":"strong"}]},{"text":" for this source:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"source_name\": \"\u003cnormalized name from briefing>\",\n \"decision\": \"approved\",\n \"reason\": \"\u003cwhich option they picked, e.g., 'authenticated browser-sniff' or 'browser-sniff and merge'>\",\n \"asked_at\": \"\u003ccurrent ISO8601 timestamp>\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Append it to ","type":"text"},{"text":"$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" (create the file if it doesn't exist).","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Step 0: Identify the User Goal","type":"text"}]},{"type":"paragraph","content":[{"text":"Before building the capture plan, answer one question: ","type":"text"},{"text":"What does the end user of this CLI actually want to do?","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Read the research brief's Top Workflows. The #1 workflow IS the primary browser-sniff goal. State it in one sentence:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Domino's: \"Order a pizza for delivery\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Linear: \"Create an issue and assign it to a sprint\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stripe: \"Create a payment intent and confirm it\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ESPN: \"Check today's scores and standings\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Notion: \"Create a page and organize it in a database\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the API is read-only (news, weather, data feeds), the primary goal is \"fetch and filter data\" and the flow is search/filter/paginate rather than a multi-step transaction.","type":"text"}]},{"type":"paragraph","content":[{"text":"The browser-sniff will walk through this goal as an interactive user flow. Secondary workflows become secondary browser-sniff passes if time permits.","type":"text"}]},{"type":"paragraph","content":[{"text":"State the goal explicitly before proceeding: \"Primary browser-sniff goal: [goal]. I will walk through this as a user flow.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Then read and follow ","type":"text"},{"text":"references/browser-sniff-capture.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/browser-sniff-capture.md","title":null}}]},{"text":" for the complete browser-sniff implementation: tool detection, installation, session transfer, browser-use/agent-browser/manual HAR capture, replayability analysis, and discovery report writing.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If user declines browser-sniff","type":"text"}]},{"type":"paragraph","content":[{"text":"Write the marker entry","type":"text","marks":[{"type":"strong"}]},{"text":" for this source before proceeding:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"source_name\": \"\u003cnormalized name from briefing>\",\n \"decision\": \"declined\",\n \"reason\": \"\u003cwhich option they picked, e.g., 'use existing spec' or 'use docs instead'>\",\n \"asked_at\": \"\u003ccurrent ISO8601 timestamp>\"\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Append it to ","type":"text"},{"text":"$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Proceed with whatever spec source exists. If no spec was found, fall back to ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ask the user to provide a spec/HAR manually.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Before leaving Phase 1.7","type":"text"}]},{"type":"paragraph","content":[{"text":"Every source named in the briefing must have exactly one entry in ","type":"text"},{"text":"browser-browser-sniff-gate.json","type":"text","marks":[{"type":"code_inline"}]},{"text":". Before proceeding to Phase 1.8, re-read the marker file and verify the count matches the number of named sources from the briefing. If a source is missing, return to the decision matrix for that source. Phase 1.5 will HALT if this check fails.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.8: Crowd-Sniff Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"After Phase 1.7 (Browser-Sniff Gate), evaluate whether mining community signals (npm SDKs and GitHub code search) would improve the spec. Skip this gate entirely if the user already passed ","type":"text"},{"text":"--spec","type":"text","marks":[{"type":"code_inline"}]},{"text":" (spec source is already resolved and appears complete).","type":"text"}]},{"type":"paragraph","content":[{"text":"Time budget:","type":"text","marks":[{"type":"strong"}]},{"text":" The crowd-sniff gate should complete within 10 minutes. If ","type":"text"},{"text":"cli-printing-press crowd-sniff","type":"text","marks":[{"type":"code_inline"}]},{"text":" fails or times out, fall back immediately:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a spec already exists: \"Crowd-sniff failed — proceeding with existing spec.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If no spec exists: \"Crowd-sniff failed — falling back to --docs generation.\"","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When to offer crowd-sniff","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Spec found?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Research shows gaps?","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes — competitors or community projects reference more endpoints","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Offer crowd-sniff as enrichment","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Yes","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No — spec appears complete","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip silently","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Community SDKs exist on npm","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Offer crowd-sniff as primary discovery","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No SDKs or code found","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip — fall back to ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Crowd-sniff as enrichment (spec exists but has gaps)","type":"text"}]},{"type":"paragraph","content":[{"text":"Present to the user via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"Found a spec with ","type":"text"},{"text":"N endpoints","type":"text","marks":[{"type":"strong"}]},{"text":", but research shows the live API likely has more. Want me to search npm packages and GitHub code for ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" to discover additional endpoints? This typically takes 5-10 minutes.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — crowd-sniff and merge","type":"text","marks":[{"type":"strong"}]},{"text":" (search npm SDKs and GitHub code, merge discovered endpoints with the existing spec)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — use existing spec","type":"text","marks":[{"type":"strong"}]},{"text":" (proceed with what we have)","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Crowd-sniff as primary (no spec found)","type":"text"}]},{"type":"paragraph","content":[{"text":"Present to the user via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"No OpenAPI spec found for ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Want me to search npm packages and GitHub code to discover the API from community usage? This typically takes 5-10 minutes.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Options:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — crowd-sniff the community","type":"text","marks":[{"type":"strong"}]},{"text":" (search npm SDKs and GitHub code, generate a spec from discovered endpoints)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — use docs instead","type":"text","marks":[{"type":"strong"}]},{"text":" (attempt ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]},{"text":" generation from documentation pages)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — I'll provide a spec or HAR","type":"text","marks":[{"type":"strong"}]},{"text":" (user will supply input manually)","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If user approves crowd-sniff","type":"text"}]},{"type":"paragraph","content":[{"text":"Read and follow ","type":"text"},{"text":"references/crowd-sniff.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/crowd-sniff.md","title":null}}]},{"text":" for the crowd-sniff command, provenance capture, and discovery report writing.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If user declines crowd-sniff","type":"text"}]},{"type":"paragraph","content":[{"text":"Proceed with whatever spec source exists. If no spec was found, fall back to ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ask the user to provide a spec/HAR manually.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.5: Ecosystem Absorb Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"THIS IS A MANDATORY STOP GATE. Do not generate until this is complete and approved.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-flight check: browser-sniff-gate marker","type":"text"}]},{"type":"paragraph","content":[{"text":"Before any absorb work, verify ","type":"text"},{"text":"$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists and contains an entry for every source named in the briefing.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the file is missing:","type":"text","marks":[{"type":"strong"}]},{"text":" HARD STOP. Print:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Phase 1.7 Browser-Sniff Gate did not record a decision. Return to Phase 1.7 and evaluate the browser-sniff gate for every source named in the briefing.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Do not proceed to Step 1.5a until the file exists.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the file exists but is missing an entry for a named source:","type":"text","marks":[{"type":"strong"}]},{"text":" HARD STOP. Print:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Browser-Sniff Gate missing decision for source ","type":"text"},{"text":"\u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Return to Phase 1.7 and evaluate the decision matrix for that source.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Do not proceed until every briefing source has a marker entry.","type":"text"}]},{"type":"paragraph","content":[{"text":"Resume leniency:","type":"text","marks":[{"type":"strong"}]},{"text":" If the run was started by an older version of the skill that didn't write markers, warn and continue — do not hard-fail on legacy resumes. Distinguish by checking whether ","type":"text"},{"text":"state.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" predates the marker contract (the marker file didn't exist before 2026-04-11). New runs always hard-fail on a missing marker.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pre-check (existing):","type":"text","marks":[{"type":"strong"}]},{"text":" If no spec or HAR file has been resolved by this point and Phase 1.7 (Browser-Sniff Gate) was not evaluated, STOP. Go back and run the browser-sniff gate decision matrix. The absorb manifest depends on knowing the API surface, which requires a spec.","type":"text"}]},{"type":"paragraph","content":[{"text":"The GOAT CLI doesn't \"find gaps.\" It absorbs EVERY feature from EVERY tool and then transcends with compound use cases nobody thought of. This phase builds the absorb manifest.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5a: Search for every tool that touches this API","type":"text"}]},{"type":"paragraph","content":[{"text":"Run these searches in parallel:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" Claude Code plugin site:github.com","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" MCP server model context protocol","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" Claude skill SKILL.md site:github.com","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" CLI tool site:github.com","type":"text","marks":[{"type":"code_inline"}]},{"text":" (competing CLIs)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" CLI site:npmjs.com","type":"text","marks":[{"type":"code_inline"}]},{"text":" (npm packages)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Raw fetch","type":"text","marks":[{"type":"strong"}]},{"text":": Check ","type":"text"},{"text":"github.com/anthropics/claude-plugins-official/tree/main/external_plugins","type":"text","marks":[{"type":"code_inline"}]},{"text":" for official plugins with the helper from ","type":"text"},{"text":"references/fetch-docs.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fetch-docs.md","title":null}}]},{"text":", or with ","type":"text"},{"text":"gh api","type":"text","marks":[{"type":"code_inline"}]},{"text":" when it can return the file/listing directly.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" MCP site:lobehub.com OR site:mcpmarket.com OR site:fastmcp.me","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" automation script workflow site:github.com","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" SDK wrapper site:npmjs.com","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"WebSearch","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"\"\u003cAPI name>\" client library site:pypi.org","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5a.5: Read MCP source code (if found)","type":"text"}]},{"type":"paragraph","content":[{"text":"If step 1.5a discovered MCP server repos with public source code on GitHub, read the actual source to extract ground-truth API usage — not just README feature descriptions.","type":"text"}]},{"type":"paragraph","content":[{"text":"Time budget:","type":"text","marks":[{"type":"strong"}]},{"text":" Max 3 minutes total. If extraction is unproductive, fall back to README-only research.","type":"text"}]},{"type":"paragraph","content":[{"text":"For the top 1-2 MCP repos found:","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Identify the main source file.","type":"text","marks":[{"type":"strong"}]},{"text":" Use ","type":"text"},{"text":"gh api","type":"text","marks":[{"type":"code_inline"}]},{"text":", raw GitHub URLs, or the helper from ","type":"text"},{"text":"references/fetch-docs.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/fetch-docs.md","title":null}}]},{"text":" to inspect the repo tree and source files without a summarization layer. Find the entry point — typically ","type":"text"},{"text":"src/index.ts","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"server.ts","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"server.py","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"main.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", or a ","type":"text"},{"text":"tools/","type":"text","marks":[{"type":"code_inline"}]},{"text":" directory. MCP servers are usually small (one main file + tool definitions).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extract three things:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"API endpoint paths","type":"text","marks":[{"type":"strong"}]},{"text":": Look for HTTP client calls (","type":"text"},{"text":"fetch(","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"axios.","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"requests.","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"http.Get","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"client.","type":"text","marks":[{"type":"code_inline"}]},{"text":") and extract the URL paths (e.g., ","type":"text"},{"text":"GET /v1/issues","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"POST /graphql","type":"text","marks":[{"type":"code_inline"}]},{"text":"). These are the endpoints the MCP maintainer proved work.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auth patterns","type":"text","marks":[{"type":"strong"}]},{"text":": Look for how the MCP constructs auth headers — token format (","type":"text"},{"text":"Bearer","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Bot","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Basic","type":"text","marks":[{"type":"code_inline"}]},{"text":"), header name (","type":"text"},{"text":"Authorization","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"X-API-Key","type":"text","marks":[{"type":"code_inline"}]},{"text":"), environment variable names. This informs our auth setup guidance.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Response field selections","type":"text","marks":[{"type":"strong"}]},{"text":": Look for which fields are extracted from API responses — these are the high-gravity fields that power users actually need.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Feed into absorb manifest.","type":"text","marks":[{"type":"strong"}]},{"text":" In step 1.5b, endpoints extracted from source get attributed as ","type":"text"},{"text":"\u003cMCP name> (source)","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the \"Best Source\" column, distinguishing them from README-derived features. Source-extracted endpoints are high-confidence signals — the maintainer verified they work.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Feed auth patterns into research brief.","type":"text","marks":[{"type":"strong"}]},{"text":" If the MCP source reveals token format (e.g., ","type":"text"},{"text":"xoxp-","type":"text","marks":[{"type":"code_inline"}]},{"text":" for Slack, ","type":"text"},{"text":"sk_live_","type":"text","marks":[{"type":"code_inline"}]},{"text":" for Stripe), credential setup steps, or required scopes, note them in the Phase 1 brief's auth section. These hints improve the generated CLI's auth onboarding.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Skip this step when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No MCP repos were found in 1.5a","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"MCP repos are private or archived","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The MCP is a monorepo where the relevant server is hard to locate within 3 minutes","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5a.6: DeepWiki Codebase Analysis (if GitHub repos found)","type":"text"}]},{"type":"paragraph","content":[{"text":"If Phase 1 or Step 1.5a discovered GitHub repos for the API (SDK repos, server repos, MCP server repos), query DeepWiki for a semantic understanding of how the API works - architecture, auth flows, data models, error handling. This complements crowd-sniff (endpoints) and MCP source reading (auth headers) with \"how things actually work\" context.","type":"text"}]},{"type":"paragraph","content":[{"text":"Time budget:","type":"text","marks":[{"type":"strong"}]},{"text":" 2 minutes max. If DeepWiki is slow or unavailable, skip silently.","type":"text"}]},{"type":"paragraph","content":[{"text":"Run in parallel","type":"text","marks":[{"type":"strong"}]},{"text":" with Steps 1.5a through 1.5a.5 when possible. DeepWiki queries do not depend on MCP source reading results.","type":"text"}]},{"type":"paragraph","content":[{"text":"Read and follow ","type":"text"},{"text":"references/deepwiki-research.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/deepwiki-research.md","title":null}}]},{"text":" for the query procedure: wiki structure fetch, targeted section extraction (auth, data model, architecture), and synthesis into the research brief and absorb manifest.","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip this step when:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No GitHub repos were discovered during Phase 1 or Step 1.5a","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The API is trivially simple (1-2 endpoints, no auth)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5b: Catalog every feature into the absorb manifest","type":"text"}]},{"type":"paragraph","content":[{"text":"For EACH tool found, list EVERY feature/tool/command it provides. Then define how our CLI matches AND beats it:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Absorb Manifest\n\n### Absorbed (match or beat everything that exists)\n| # | Feature | Best Source | Our Implementation | Added Value |\n|---|---------|-----------|-------------------|-------------|\n| 1 | Search issues by text | Linear MCP search_issues | \u003capi>-pp-cli search | Works offline, regex, SQL composable |\n| 2 | Create issue | Linear MCP create_issue | \u003capi>-pp-cli issue create --stdin --dry-run | Agent-native, scriptable, idempotent |\n| 3 | Sprint board view | jira-cli sprint view | \u003capi>-pp-cli sprint view | Historical velocity, offline |","type":"text"}]},{"type":"paragraph","content":[{"text":"Every row = a feature we MUST build. No exceptions. If someone else has it, we have it AND it works offline, with --json, --dry-run, typed exit codes, and SQLite persistence.","type":"text"}]},{"type":"paragraph","content":[{"text":"SDK wrapper methods should be treated as features to absorb — each public method/function is a feature the CLI should match.","type":"text"}]},{"type":"paragraph","content":[{"text":"Our Implementation must start with a parseable disposition.","type":"text","marks":[{"type":"strong"}]},{"text":" Use one of these prefixes so Phase 3 can verify the row mechanically:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003capi>-pp-cli \u003cclean command path>","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a promoted or hand-built Cobra command path that must resolve via ","type":"text"},{"text":"\u003cbinary> \u003cpath> --help","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"(generated endpoint) \u003cresource> \u003cendpoint>","type":"text","marks":[{"type":"code_inline"}]},{"text":" for generator-emitted typed endpoint commands that retain the upstream resource shape and are covered by the generated endpoint surface.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"(behavior in \u003capi>-pp-cli \u003ccommand path>) ...","type":"text","marks":[{"type":"code_inline"}]},{"text":" for features implemented as flags, modes, output shapes, or store behavior inside another command. The named command path still must resolve; the prose after the closing parenthesis explains the behavior to verify later.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"(stub) ...","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for explicitly approved stubs per the rule below.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not leave ","type":"text"},{"text":"Our Implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" as freeform prose like ","type":"text"},{"text":"FTS5 offline search","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"SQLite-backed sprint query","type":"text","marks":[{"type":"code_inline"}]},{"text":". If the row maps to a clean user-facing command, put that command path first. If it does not, choose the explicit disposition that explains why Phase 3 should not treat the whole cell as a new command path.","type":"text"}]},{"type":"paragraph","content":[{"text":"Stubs must be explicit.","type":"text","marks":[{"type":"strong"}]},{"text":" If any row in the manifest will ship as a stub (placeholder implementation that emits \"not yet wired\" / \"wip\" messaging), start ","type":"text"},{"text":"Our Implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"(stub)","type":"text","marks":[{"type":"code_inline"}]},{"text":" plus a one-line reason why the full implementation is deferred (e.g., \"(stub - requires paid API)\", \"(stub - requires headless Chrome)\"). If the manifest also has a ","type":"text"},{"text":"Status","type":"text","marks":[{"type":"code_inline"}]},{"text":" column, set that value to ","type":"text"},{"text":"(stub)","type":"text","marks":[{"type":"code_inline"}]},{"text":" too, but the ","type":"text"},{"text":"Our Implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" prefix is the Phase 3 gate's source of truth. Do NOT quietly ship stubs for features the user approved as shipping scope.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Phase Gate 1.5 prose showcase (below) MUST read out stub items separately so the user explicitly approves the stub list. After approval, Phase 3 builds shipping-scope features fully and stubs with honest messaging; no mid-build downgrade from shipping-scope to stub is permitted. If an agent discovers during Phase 3 that a shipping-scope feature cannot be implemented in-session, they must return to Phase 1.5 with a revised manifest — not unilaterally downgrade to a stub.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5c: Identify transcendence features","type":"text"}]},{"type":"paragraph","content":[{"text":"Start with the users, not the technology. The best features come from understanding who uses this service, what their rituals are, and what questions they can't answer today. \"What can SQLite do?\" is the wrong question. \"What would make a power user say 'I need this'?\" is the right one.","type":"text"}]},{"type":"paragraph","content":[{"text":"The actual brainstorming runs as a Task subagent in Step 1.5c.5 below — customer model → 2× candidates → adversarial cut. Step 1.5c is the motivation; do not generate transcendence features inline here.","type":"text"}]},{"type":"paragraph","content":[{"text":"The transcendence table in the manifest (Step 1.5d) renders rows in this shape, which mirrors the subagent's ","type":"text"},{"text":"### Survivors","type":"text","marks":[{"type":"code_inline"}]},{"text":" output. The ","type":"text"},{"text":"Buildability","type":"text","marks":[{"type":"code_inline"}]},{"text":" column tags each row ","type":"text"},{"text":"spec-emits","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"hand-code","type":"text","marks":[{"type":"code_inline"}]},{"text":" per ","type":"text"},{"text":"references/novel-features-subagent.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/novel-features-subagent.md","title":null}}]},{"text":" so the Phase Gate 1.5 hand-code count has a source of truth in the manifest. The optional ","type":"text"},{"text":"Long Description","type":"text","marks":[{"type":"code_inline"}]},{"text":" column carries agent-facing disambiguation text for Phase 3 Cobra ","type":"text"},{"text":"Long","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields; use ","type":"text"},{"text":"none","type":"text","marks":[{"type":"code_inline"}]},{"text":" when no sibling redirect is needed:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"### Transcendence (only possible with our approach)\n| # | Feature | Command | Buildability | Why Only We Can Do This | Long Description |\n|---|---------|---------|--------------|------------------------|------------------|\n| 1 | Bottleneck detection | bottleneck | hand-code | Requires local join across issues + assignees + cycle data | Use this command to find cross-team work blockage. Do NOT use it for personal recency checks; use 'since' instead. |\n| 2 | Velocity trends | velocity --weeks 4 | hand-code | Requires historical cycle snapshots in SQLite | none |\n| 3 | What did I miss | since 2h | hand-code | Requires time-windowed aggregation no single API call provides | Use this command for recent personal changes. Do NOT use it for backlog bottlenecks; use 'bottleneck' instead. |","type":"text"}]},{"type":"paragraph","content":[{"text":"Minimum 5 transcendence features. These are the commands that differentiate the CLI.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5c.5: Auto-Suggest Novel Features (subagent)","type":"text"}]},{"type":"paragraph","content":[{"text":"Always spawn the subagent — first prints and reprints alike.","type":"text","marks":[{"type":"strong"}]},{"text":" The subagent is the only path that produces this step's outputs (customer model, candidate list, adversarial cut, killed-candidate audit trail). There is no manual fallback. Specifically, do not:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hand-curate the transcendence list from a prior manifest, even when the prior looks complete. Prior ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" is INPUT to Pass 2(d), never a substitute for the spawn.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fall back to inline brainstorming inside the SKILL.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skip on cost grounds. With a strong prior the subagent confirms or reframes; with no prior it generates from scratch. Run it either way.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"treat disclosure as authorization. Announcing a skip in the gate showcase does not make the skip legal.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Read ","type":"text"},{"text":"references/novel-features-subagent.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/novel-features-subagent.md","title":null}}]},{"text":" for the prior-research discovery snippet, input bundle, prompt template, and output contract. Run the discovery snippet as written — do not substitute an ","type":"text"},{"text":"ls","type":"text","marks":[{"type":"code_inline"}]},{"text":" of the manuscripts directory. The snippet's ","type":"text"},{"text":"none","type":"text","marks":[{"type":"code_inline"}]},{"text":" branch (no prior research) is a first print, not a skip signal.","type":"text"}]},{"type":"paragraph","content":[{"text":"The only legitimate non-spawn outcome is the pre-flight HALT (brief lacks user research) defined in the reference file.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5d: Write the manifest artifact","type":"text"}]},{"type":"paragraph","content":[{"text":"Write to ","type":"text"},{"text":"$RESEARCH_DIR/\u003cstamp>-feat-\u003capi>-pp-cli-absorb-manifest.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"The manifest now includes compound use cases (Step 1.5c) and auto-suggested + auto-brainstormed features (Step 1.5c.5) in the transcendence table.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1.5e: Write research.json for README credits","type":"text"}]},{"type":"paragraph","content":[{"text":"After writing the absorb manifest, also write ","type":"text"},{"text":"$API_RUN_DIR/research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" so the generator can credit community projects in the README. This file MUST match the ","type":"text"},{"text":"ResearchResult","type":"text","marks":[{"type":"code_inline"}]},{"text":" JSON schema that ","type":"text"},{"text":"loadResearchSources()","type":"text","marks":[{"type":"code_inline"}]},{"text":" expects.","type":"text"}]},{"type":"paragraph","content":[{"text":"Populate the ","type":"text"},{"text":"alternatives","type":"text","marks":[{"type":"code_inline"}]},{"text":" array from the absorb manifest's source tools list. Include only tools that:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Have a GitHub URL (not npm/PyPI landing pages)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Actually contributed features to the absorb manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Are capped at 8 entries, ordered by number of absorbed features (then by stars)","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cat > \"$API_RUN_DIR/research.json\" \u003c\u003cREOF\n{\n \"api_name\": \"\u003capi>\",\n \"novelty_score\": 0,\n \"alternatives\": [\n {\"name\": \"\u003ctool1>\", \"url\": \"\u003cgithub-url>\", \"language\": \"\u003cGo|JavaScript|Python|etc>\", \"stars\": \u003cN>, \"command_count\": \u003cN>},\n ...\n ],\n \"auth\": {\n \"canonical_env_var\": \"\u003cCANONICAL_ENV_VAR, omit when unknown>\"\n },\n \"novel_features\": [\n {\n \"name\": \"\u003cFeature Name>\",\n \"command\": \"\u003ccli-subcommand>\",\n \"description\": \"\u003cOne sentence: what the user gets>\",\n \"rationale\": \"\u003cOne sentence: why only possible with our approach>\",\n \"example\": \"\u003cready-to-run invocation with realistic args, e.g. 'yahoo-finance-pp-cli portfolio perf --agent'>\",\n \"why_it_matters\": \"\u003cOne sentence aimed at AI agents: when should they reach for this?>\",\n \"group\": \"\u003cTheme name clustering similar features, e.g. 'Local state that compounds'>\"\n },\n ...\n ],\n \"narrative\": {\n \"display_name\": \"\u003cCanonical prose name, exact brand casing/spaces, e.g. Product Hunt, GitHub, YouTube, Cal.com>\",\n \"headline\": \"\u003cBold one-sentence value prop: what makes this CLI worth using>\",\n \"value_prop\": \"\u003c2-3 sentence expansion rendered beneath the title>\",\n \"auth_narrative\": \"\u003cAPI-specific auth story; omit for simple API-key auth>\",\n \"quickstart\": [\n {\"command\": \"\u003ccli> \u003creal-command-with-real-args>\", \"comment\": \"\u003cwhy this comes first>\"},\n ...\n ],\n \"troubleshoots\": [\n {\"symptom\": \"\u003cuser-visible error or symptom>\", \"fix\": \"\u003cactionable one-liner>\"},\n ...\n ],\n \"when_to_use\": \"\u003c2-4 sentences describing ideal use cases; rendered in SKILL.md only>\",\n \"anti_triggers\": [\"\u003ctask boundary this CLI should not handle>\", ...],\n \"recipes\": [\n {\"title\": \"\u003cRecipe name>\", \"command\": \"\u003ccli> \u003cinvocation>\", \"explanation\": \"\u003cone-line paragraph>\"},\n ...\n ],\n \"trigger_phrases\": [\"\u003cnatural phrase that should invoke this CLI's skill>\", ...]\n },\n \"gaps\": [],\n \"patterns\": [],\n \"recommendation\": \"proceed\",\n \"researched_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"\n}\nREOF","type":"text"}]},{"type":"paragraph","content":[{"text":"For each tool, fill in what you know from the research. Stars and command_count are optional (use 0 if unknown). The ","type":"text"},{"text":"language","type":"text","marks":[{"type":"code_inline"}]},{"text":" field should match the primary implementation language. Skip tools that were found during search but contributed zero features to the manifest.","type":"text"}]},{"type":"paragraph","content":[{"text":"Novel features rules","type":"text","marks":[{"type":"strong"}]},{"text":" (the ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" array populates the README's \"Unique Features\" section and SKILL.md's \"Unique Capabilities\" block; MCP exposure comes from the runtime Cobra-tree mirror, not this list):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Include all transcendence features from the manifest that scored >= 5/10. Order by score descending.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" should be user-benefit language, not implementation detail. Good: \"See which team members are overloaded before sprint planning.\" Bad: \"Requires local join across issues + assignees + cycle data.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"rationale","type":"text","marks":[{"type":"code_inline"}]},{"text":" should explain why this is only possible with our approach. Good: \"Requires correlating bookings, schedules, and staff data that only exists together in the local store.\" Bad: \"Cal.com Insights is paid-tier only.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"command","type":"text","marks":[{"type":"code_inline"}]},{"text":" must match the actual CLI subcommand that will be built in Phase 3. For subcommands of a resource (e.g., ","type":"text"},{"text":"issues stale","type":"text","marks":[{"type":"code_inline"}]},{"text":"), use the full command path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"example","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a ready-to-run invocation an agent can copy-paste. Use realistic arguments from the API's domain (e.g. ","type":"text"},{"text":"AAPL","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"customer_42","type":"text","marks":[{"type":"code_inline"}]},{"text":"), not ","type":"text"},{"text":"\u003cplaceholder>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Include the ","type":"text"},{"text":"--agent","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag when the feature benefits from structured output.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"why_it_matters","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a single agent-facing sentence answering \"when should I pick this over a generic API call?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"group","type":"text","marks":[{"type":"code_inline"}]},{"text":" clusters related features under a theme name. Pick 2–5 themes total (e.g. \"Local state that compounds\", \"Agent-native plumbing\", \"Reachability mitigation\"). Use the same ","type":"text"},{"text":"group","type":"text","marks":[{"type":"code_inline"}]},{"text":" string verbatim across features that belong together — exact matches drive README grouping. Leave ","type":"text"},{"text":"group","type":"text","marks":[{"type":"code_inline"}]},{"text":" empty if the CLI has too few novel features to warrant clustering.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the manifest row has a non-","type":"text"},{"text":"none","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"Long Description","type":"text","marks":[{"type":"code_inline"}]},{"text":", keep that text with the feature implementation notes and use it as the Cobra ","type":"text"},{"text":"Long","type":"text","marks":[{"type":"code_inline"}]},{"text":" field during Phase 3 hand-code. Do not squeeze redirect prose into ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" stays one-line user-benefit text.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If no transcendence features scored >= 5/10, omit the ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" field entirely.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not add a feature to ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" merely to expose it through MCP. Any user-facing Cobra command becomes an MCP tool automatically unless it sets ","type":"text"},{"text":"cmd.Annotations[\"mcp:hidden\"] = \"true\"","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Auth research rule","type":"text","marks":[{"type":"strong"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"auth.canonical_env_var","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the single-token credential env var discovered from vendor docs, MCP/source analysis, or dominant SDK/CLI convention (for example ","type":"text"},{"text":"APIFY_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"GITHUB_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"STRIPE_SECRET_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Omit it when no canonical name is known, when auth is HTTP Basic or another credential pair, or when the auth flow needs richer metadata. Fresh generation reads this env var first and keeps the parser-derived name as a fallback automatically.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Narrative rules","type":"text","marks":[{"type":"strong"}]},{"text":" (the ","type":"text"},{"text":"narrative","type":"text","marks":[{"type":"code_inline"}]},{"text":" object drives README headline, Quick Start, Auth, Troubleshooting, and the entire SKILL.md):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"display_name","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the canonical prose name, discovered during research, with exact brand casing and spacing. This is agentic/research-owned, not slug-inferred by Go code. Good: \"Product Hunt\", \"GitHub\", \"YouTube\", \"Cal.com\". Bad: \"Producthunt\", \"Github\", \"Youtube\", \"Cal Com\". Use the slug only for binary names, directories, module paths, config paths, and env-var prefixes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"headline","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the bold one-liner rendered beneath the CLI title. Should name the differentiator, not restate the API. Good: \"Every Notion feature, plus sync, search, and a local database no other Notion tool has.\" Bad: \"A CLI for the Notion API.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"value_prop","type":"text","marks":[{"type":"code_inline"}]},{"text":" expands the headline to 2–3 sentences. Name specific novel features by command where helpful.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"auth_narrative","type":"text","marks":[{"type":"code_inline"}]},{"text":" tells the real auth story for this API (crumb handshake, cookie session, OAuth device flow). Omit for standard API-key auth where the generic branch is fine.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"quickstart","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a 3–6 step flow using REAL arguments (symbols, IDs, resource names an agent can actually pass). Each step's ","type":"text"},{"text":"comment","type":"text","marks":[{"type":"code_inline"}]},{"text":" explains ","type":"text"},{"text":"why","type":"text","marks":[{"type":"em"}]},{"text":" it runs. This replaces the generic \"resource list\" first-command fallback.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Step 1 of ","type":"text"},{"text":"quickstart","type":"text","marks":[{"type":"code_inline"}]},{"text":" should usually be verify-safe: it should exit 0 when ","type":"text"},{"text":"validate-narrative --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" appends ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" in a no-credentials environment.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"\u003ccli> doctor --dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" as step 1 (health check, works without auth). Do not use ","type":"text"},{"text":"\u003ccli> auth set-token \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":" as step 1 because it requires a positional token and is not a verify-safe runnable first step. Auth setup instructions belong in ","type":"text"},{"text":"auth_narrative","type":"text","marks":[{"type":"code_inline"}]},{"text":" prose only, not as an executable quickstart command.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"troubleshoots","type":"text","marks":[{"type":"code_inline"}]},{"text":" captures API-specific failure modes (rate-limit mitigation, cookie expiry, paginated quirks). Each ","type":"text"},{"text":"fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" must be actionable — a command or a concrete setting change.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"when_to_use","type":"text","marks":[{"type":"code_inline"}]},{"text":" is SKILL-only narrative. 2–4 sentences describing the kinds of agent tasks this CLI is the right choice for. Not rendered in README.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"anti_triggers","type":"text","marks":[{"type":"code_inline"}]},{"text":" is SKILL-only narrative. List common task boundaries that should make an agent choose another tool, official SDK, web UI, or human workflow instead of this CLI. Write concrete \"do not use this CLI for X\" cases, not vague limitations. Omit the field only when no honest boundary is known.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"recipes","type":"text","marks":[{"type":"code_inline"}]},{"text":" are 3–5 worked examples rendered in SKILL.md. Each has a title, a real command, and a one-line explanation. Prefer recipes that exercise novel features. ","type":"text"},{"text":"At least one recipe must pair ","type":"text","marks":[{"type":"strong"}]},{"text":"--agent","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" with ","type":"text","marks":[{"type":"strong"}]},{"text":"--select","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — using dotted paths (e.g. ","type":"text"},{"text":"--select events.shortName,events.competitions.competitors.team.displayName","type":"text","marks":[{"type":"code_inline"}]},{"text":") when the response is deeply nested. APIs like ESPN, HubSpot, and Linear return tens of KB per call; without a ","type":"text"},{"text":"--select","type":"text","marks":[{"type":"code_inline"}]},{"text":" recipe, agents burn context parsing verbose payloads. Pick a command known to return a large or deeply nested response and show the narrowing pattern. ","type":"text"},{"text":"Regex literals must double-escape backslashes","type":"text","marks":[{"type":"strong"}]},{"text":" — write ","type":"text"},{"text":"\\\\b","type":"text","marks":[{"type":"code_inline"}]},{"text":" not ","type":"text"},{"text":"\\b","type":"text","marks":[{"type":"code_inline"}]},{"text":" (and ","type":"text"},{"text":"\\\\t","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\\\\f","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.) inside any ","type":"text"},{"text":"command","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"fix","type":"text","marks":[{"type":"code_inline"}]},{"text":", or other JSON string field. JSON parses ","type":"text"},{"text":"\\b","type":"text","marks":[{"type":"code_inline"}]},{"text":" as backspace (0x08), ","type":"text"},{"text":"\\f","type":"text","marks":[{"type":"code_inline"}]},{"text":" as form feed (0x0C), and so on, which then leak into the rendered SKILL.md as control bytes that render as nothing in most viewers. The generator's render-time scanner rejects these with a clear offset; double-escape from the start to avoid the error.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"trigger_phrases","type":"text","marks":[{"type":"code_inline"}]},{"text":" are natural-language phrases a user might say that should invoke this CLI's skill. Include 3–5 domain-specific phrases (e.g. for a finance CLI: \"quote AAPL\", \"check my portfolio\", \"options for TSLA\") and 2 generic phrases (\"use \u003capi-name>\", \"run \u003capi-name>\"). Domain verbs vary — don't just template \"use X\" variants.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All ","type":"text"},{"text":"narrative","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields are optional. Omit fields you can't populate honestly rather than emit filler. The generator falls back to generic content gracefully.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Avoid hardcoded counts in narrative copy when the count tracks a runtime list.","type":"text","marks":[{"type":"strong"}]},{"text":" A number embedded in ","type":"text"},{"text":"headline","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"value_prop","type":"text","marks":[{"type":"code_inline"}]},{"text":" (\"across N trusted sources\", \"from N retailers\", \"queries N vendors\") propagates into root.go's Short/Long, the README, the SKILL, the MCP tools description, and ","type":"text"},{"text":"which.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" — every output surface that reads the narrative. When the underlying registry grows or shrinks, the count goes stale across all of those surfaces simultaneously, and a single-line edit to add a source requires hunting down ~10 hardcoded copies. Prefer plural-without-count phrasing (\"across the major sources\", \"from a curated set of retailers\") or describe the breadth qualitatively (\"dozens of vendors\") rather than committing to a specific integer. If a count is load-bearing for the value prop, keep the brief's narrative count-free and have the printed-CLI's README/SKILL author write the count once into a single hand-edited paragraph after generation — accepting that it will need a manual update whenever the registry changes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use side-effectful examples only when they are the truthful workflow.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"validate-narrative --strict --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" classifies ","type":"text"},{"text":"auth login","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"auth set-token","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"auth logout","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"auth setup","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--launch","type":"text","marks":[{"type":"code_inline"}]},{"text":", and mutating ","type":"text"},{"text":"--apply","type":"text","marks":[{"type":"code_inline"}]},{"text":" examples as side-effectful (see ","type":"text"},{"text":"isSideEffectfulNarrativeExample","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"internal/narrativecheck/narrativecheck.go","type":"text","marks":[{"type":"code_inline"}]},{"text":") and reports each as an ","type":"text"},{"text":"UNSUPPORTED","type":"text","marks":[{"type":"code_inline"}]},{"text":" warning instead of executing it. These warnings do not fail strict aggregation, so it is valid to show an auth or apply command when that is the honest onboarding or bulk-operation shape. Prefer ","type":"text"},{"text":"doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" or another read-only invocation as ","type":"text"},{"text":"quickstart[0]","type":"text","marks":[{"type":"code_inline"}]},{"text":" when it teaches the same workflow, but do not strip a real auth or apply step just to appease shipcheck. Non-side-effect unsupported examples still fail strict mode when they cannot dry-run, and missing commands, empty command paths, and failed full examples remain failures.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Pre-render framework-command check.","type":"text","marks":[{"type":"strong"}]},{"text":" Before running ","type":"text"},{"text":"generate --research-dir","type":"text","marks":[{"type":"code_inline"}]},{"text":", validate the framework command examples already present in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":". This catches stable template vocabulary mistakes while the fix is still a single-file ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" edit, before README.md, SKILL.md, ","type":"text"},{"text":".printing-press.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", root help, and other generated surfaces consume the bad narrative.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press validate-narrative --strict --framework-only \\\n --research \"$API_RUN_DIR/research.json\"","type":"text"}]},{"type":"paragraph","content":[{"text":"If this reports ","type":"text"},{"text":"sync --entities","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"search --entities","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"search --types","type":"text","marks":[{"type":"code_inline"}]},{"text":", an absolute date for ","type":"text"},{"text":"sync --since","type":"text","marks":[{"type":"code_inline"}]},{"text":", or another framework-command flag mismatch, fix ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" now and rerun this check before generation. This is a cheap floor, not a replacement for Phase 4 shipcheck: after the CLI exists, ","type":"text"},{"text":"shipcheck","type":"text","marks":[{"type":"code_inline"}]},{"text":" still runs ","type":"text"},{"text":"validate-narrative --strict --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the built binary to catch API-specific command paths, generated endpoint flags, and runtime dry-run failures.","type":"text"}]},{"type":"paragraph","content":[{"text":"Also write discovery pages if browser-sniff was used. The generator reads these from ","type":"text"},{"text":"$API_RUN_DIR/discovery/browser-sniff-report.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" (which the browser-sniff gate already writes there). No additional action needed for discovery pages -- they are already in the right location.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Priority inversion check (combo CLIs only)","type":"text"}]},{"type":"paragraph","content":[{"text":"Only runs when ","type":"text","marks":[{"type":"strong"}]},{"text":"source-priority.json","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" exists from the Multi-Source Priority Gate.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Before Phase Gate 1.5, tally the commands/features the manifest attributes to each named source. Compare against the confirmed priority ordering:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the primary source has ","type":"text"},{"text":"fewer","type":"text","marks":[{"type":"strong"}]},{"text":" commands than any secondary source, this is a ","type":"text"},{"text":"priority inversion","type":"text","marks":[{"type":"strong"}]},{"text":" — the free/primary-intent source got demoted because the secondary had more spec coverage.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the primary source has ","type":"text"},{"text":"zero","type":"text","marks":[{"type":"strong"}]},{"text":" commands (all its features were dropped because it lacked a spec), this is a ","type":"text"},{"text":"hard inversion","type":"text","marks":[{"type":"strong"}]},{"text":" — the primary was silently replaced.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When an inversion is detected, HALT before Phase Gate 1.5 and print:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"⚠ ","type":"text"},{"text":"Priority inversion detected.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The confirmed primary is ","type":"text"},{"text":"\u003cSource A>","type":"text","marks":[{"type":"strong"}]},{"text":" but the manifest gives it \u003cN> commands vs ","type":"text"},{"text":"\u003cSource B>","type":"text","marks":[{"type":"strong"}]},{"text":" (secondary) with \u003cM> commands. This usually means the primary's discovery path (browser-sniff, community wrapper, HTML parser) didn't land, and the secondary's clean spec took over.","type":"text"}]},{"type":"paragraph","content":[{"text":"The user said \u003cSource A> is the headline. Shipping this manifest would invert their stated priority.","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Then ask via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Re-run discovery for \u003cSource A>","type":"text","marks":[{"type":"strong"}]},{"text":" — loop back to Phase 1.7 browser-sniff or Phase 1.8 crowd-sniff for the primary source specifically.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Accept the inversion","type":"text","marks":[{"type":"strong"}]},{"text":" — the user explicitly confirms they're fine with the secondary leading. Record this in ","type":"text"},{"text":"source-priority.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" as ","type":"text"},{"text":"inversion_accepted: true","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Drop \u003cSource B>","type":"text","marks":[{"type":"strong"}]},{"text":" — remove the secondary from the manifest so it can't overshadow the primary.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not proceed to the prose showcase until this is resolved.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase Gate 1.5","type":"text"}]},{"type":"paragraph","content":[{"text":"STOP.","type":"text","marks":[{"type":"strong"}]},{"text":" Present the absorb manifest to the user in two parts: a prose showcase, then a question.","type":"text"}]},{"type":"paragraph","content":[{"text":"The prose showcase and the ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" are two separate turns. Print the showcase as a plain text reply with every novel feature spelled out, then call ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":" with four short options whose descriptions fit on one line each. The question text is one sentence; the user reads the showcase to decide and the options to act. Cramming the feature list into an option description collapses both turns into one and is the failure mode this gate exists to prevent.","type":"text"}]},{"type":"paragraph","content":[{"text":"Part 1: Prose showcase (print before the AskUserQuestion)","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The showcase exists so the user can decide approve / trim / add ideas without asking a follow-up. Cover four things:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Scope","type":"text","marks":[{"type":"strong"}]},{"text":" — how many features absorbed across which tools, how many novel on top, how that stacks up against the best existing tool.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Per-novel-feature readout","type":"text","marks":[{"type":"strong"}]},{"text":" — one line each: feature name, what the user gets, and the specific evidence or persona that makes it worth building.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Hand-code commitment","type":"text","marks":[{"type":"strong"}]},{"text":" — of the M novel features, K will require hand-written Go after generate (each ~50-150 LoC plus ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" wiring). State the hand-code count and the auto-emitted count, then list the names of the hand-code features. The manifest transcendence table's ","type":"text"},{"text":"Buildability","type":"text","marks":[{"type":"code_inline"}]},{"text":" column (populated from the subagent per ","type":"text"},{"text":"references/novel-features-subagent.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/novel-features-subagent.md","title":null}}]},{"text":" \"Output contract\") is the source of truth: count rows tagged ","type":"text"},{"text":"hand-code","type":"text","marks":[{"type":"code_inline"}]},{"text":"; ","type":"text"},{"text":"spec-emits","type":"text","marks":[{"type":"code_inline"}]},{"text":" rows are excluded from the hand-code total. Approving commits the agent to that scope, so the user must see it explicitly before the AskUserQuestion.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Anything else the user should worry about before approving","type":"text","marks":[{"type":"strong"}]},{"text":" — stubs, risky dependencies, expensive endpoints, low-confidence ideas.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Show every novel feature that scored ≥5/10. Group by theme if there are more than ~12; never hide features behind \"Plus N more\" or \"see full manifest.\" If zero qualified, say so plainly: \"No novel features scored high enough to recommend. The absorbed features cover the landscape well.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Format is otherwise yours — markdown headings, prose, a numbered list, whatever reads cleanly. The must-haves are the four things above and the ≥5/10 coverage rule.","type":"text"}]},{"type":"paragraph","content":[{"text":"Part 2: AskUserQuestion","type":"text","marks":[{"type":"strong"}]}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"Ready to generate with the full [N+M]-feature manifest? Or do you have ideas to add?\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Options (each description must be one short line — the showcase already did the explaining):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Approve — generate now","type":"text","marks":[{"type":"strong"}]},{"text":" — Start CLI generation with the full manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"I have ideas to add","type":"text","marks":[{"type":"strong"}]},{"text":" — Tell me features from your experience, then we'll generate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review full manifest","type":"text","marks":[{"type":"strong"}]},{"text":" — Show me every absorbed and novel feature before deciding","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Trim scope","type":"text","marks":[{"type":"strong"}]},{"text":" — The feature count is too ambitious, let's focus on a subset","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If user selects ","type":"text"},{"text":"\"I have ideas to add\"","type":"text","marks":[{"type":"strong"}]},{"text":", ask 3 structured questions targeting personal knowledge the research couldn't surface:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"Beyond the [M] ideas above, what workflows do YOU use ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":" for that we might have missed?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"What frustrates YOU about this API that the research didn't surface?\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"What's YOUR killer feature — something only you'd think of?\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"USER_BRIEFING_CONTEXT","type":"text","marks":[{"type":"code_inline"}]},{"text":" is non-empty, acknowledge it: \"You mentioned [summary of their vision] at the start. Want to add more, or does the manifest already cover it?\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Each answer that produces a concrete feature → score and add to the transcendence table. After the brainstorm, return to this gate with the updated manifest. WAIT for approval. Do NOT generate until approved.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 1.9: API Reachability Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY. Do NOT skip this phase. Do NOT proceed to Phase 2 without running this check.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Before spending tokens on generation, verify the API actually responds to programmatic requests. One real HTTP call. If it fails, STOP.","type":"text"}]},{"type":"paragraph","content":[{"text":"Exception for browser-clearance/browser-sniffed website CLIs:","type":"text","marks":[{"type":"strong"}]},{"text":" If Phase 1.7 produced a successful browser capture and ","type":"text"},{"text":"$DISCOVERY_DIR/traffic-analysis.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" reports ","type":"text"},{"text":"reachability.mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" as ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"browser_http","type":"text","marks":[{"type":"code_inline"}]},{"text":", a plain ","type":"text"},{"text":"curl","type":"text","marks":[{"type":"code_inline"}]},{"text":" 403/429 is expected evidence, not a hard stop. In that case the reachability gate passes only if:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"the browser-sniff capture contains useful non-challenge traffic (real API, SSR data, structured HTML, RSS/feed data, or page-context fetch evidence), and","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Phase 2 will pass ","type":"text"},{"text":"--traffic-analysis \"$DISCOVERY_DIR/traffic-analysis.json\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" so the generator can emit browser-compatible HTTP transport and, for ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":", Chrome cookie import.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not treat a persistent browser sidecar as a shippable CLI runtime. Browsers are allowed for Printing Press discovery and reusable auth/clearance capture; ordinary printed CLI commands must replay through direct HTTP, Surf/browser-compatible HTTP, or stored reusable auth state. If traffic analysis reports ","type":"text"},{"text":"browser_required","type":"text","marks":[{"type":"code_inline"}]},{"text":", return to discovery to find a replayable HTTP/HTML/RSS/SSR surface or HOLD the run.","type":"text"}]},{"type":"paragraph","content":[{"text":"Useful same-site HTML document pages count as a replayable surface when they return real content, not challenge/login pages. Browser-sniff can promote these into ","type":"text"},{"text":"response_format: html","type":"text","marks":[{"type":"code_inline"}]},{"text":" endpoints so generated commands extract page metadata and filtered links through Surf/direct HTTP instead of keeping a browser sidecar alive.","type":"text"}]},{"type":"paragraph","content":[{"text":"When hand-authoring a ","type":"text"},{"text":"response_format: html","type":"text","marks":[{"type":"code_inline"}]},{"text":" spec with ","type":"text"},{"text":"html_extract.mode: links","type":"text","marks":[{"type":"code_inline"}]},{"text":", document and choose ","type":"text"},{"text":"link_prefixes","type":"text","marks":[{"type":"code_inline"}]},{"text":" as path-segment prefixes. A prefix ","type":"text"},{"text":"/items","type":"text","marks":[{"type":"code_inline"}]},{"text":" matches ","type":"text"},{"text":"/items","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"/items/...","type":"text","marks":[{"type":"code_inline"}]},{"text":", but not ","type":"text"},{"text":"/items123.html","type":"text","marks":[{"type":"code_inline"}]},{"text":"; use the parent directory prefix when the leaf segment has embedded IDs or suffixes. See ","type":"text"},{"text":"skills/printing-press/references/spec-format.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the exact contract.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the browser capture contained only challenge/login/error pages, this exception does not apply.","type":"text"}]},{"type":"paragraph","content":[{"text":"Exception for LAN-only / mDNS-discovered APIs:","type":"text","marks":[{"type":"strong"}]},{"text":" If the resolved spec's ","type":"text"},{"text":"base_url","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a localhost or loopback placeholder (","type":"text"},{"text":"http://localhost:\u003cport>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"http://127.0.0.1:\u003cport>","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"http://[::1]:\u003cport>","type":"text","marks":[{"type":"code_inline"}]},{"text":"), or Phase 1 research explicitly identifies the API as LAN-only / SSDP / mDNS-discovered with no stable global origin, do not run the generic curl/WebFetch reachability probe. A probe from the generation host would test the agent's loopback or current network, not the user's appliance, speaker, bridge, or local service.","type":"text"}]},{"type":"paragraph","content":[{"text":"For this case, record a Phase 1.9 PASS carve-out in the research brief:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Reachability Gate\n- Decision: PASS (carve-out)\n- Reason: lan-only-no-global-url\n- Evidence: \u003cbase_url or research line showing localhost, loopback, SSDP, mDNS, or LAN-only discovery>","type":"text"}]},{"type":"paragraph","content":[{"text":"Then proceed to Phase 2. Do not write a freeform manual proof for this case, do not call it a missing-API-key skip, and do not use this carve-out for normal public/cloud origins such as ","type":"text"},{"text":"https://api.example.com","type":"text","marks":[{"type":"code_inline"}]},{"text":"; those still run the reachability probe and decision matrix below.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"The Check","type":"text"}]},{"type":"paragraph","content":[{"text":"Prefer the spec's ","type":"text"},{"text":"auth.verify_path","type":"text","marks":[{"type":"code_inline"}]},{"text":" when it is set; otherwise pick the simplest GET endpoint from the resolved spec (no required params, no auth if possible). If no such endpoint exists, use the spec's base URL. Run one HTTP request and preserve the response body when the server returns a 4xx:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"body_file=\"$(mktemp \"${TMPDIR:-/tmp}/pp-reachability-body.XXXXXX\")\"\ntrap 'rm -f \"$body_file\"' EXIT\nstatus=\"$(curl -s --max-filesize 65536 -o \"$body_file\" -w \"%{http_code}\" -m 10 \"\u003cbase_url>/\u003csimplest_get_path>\" 2>/dev/null || true)\"\ncase \"$status\" in\n [0-9][0-9][0-9]) ;;\n *) status=\"000\" ;;\nesac\nprintf '%s\\n' \"$status\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Or use ","type":"text"},{"text":"WebFetch","type":"text","marks":[{"type":"code_inline"}]},{"text":" if curl is unavailable. Record the response status and, for any 4xx response body, run the same tier/permission keyword scan against the captured WebFetch body text before deciding. The goal is one real response code plus any 4xx body evidence the API chose to return.","type":"text"}]},{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"status","type":"text","marks":[{"type":"code_inline"}]},{"text":" is any 4xx, inspect the body before deciding. Search it case-insensitively for tier or permission terms:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"grep -Ei 'tier|allowed|permitted|subscription|quota|plan|scope|limit|permission|forbidden|unauthorized|upgrade|trial' \"$body_file\" | head -20","type":"text"}]},{"type":"paragraph","content":[{"text":"When matched lines are present, add them to the Phase 1 research brief under:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"markdown"},"content":[{"text":"## Reachability Risk\n- Tier/permission hints from 4xx body: \"\u003cmatched line, truncated if needed>\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Keep the evidence bounded: include only the lines that explain the access model, trim each line to a readable length, and do not paste bearer tokens, API keys, cookies, or unrelated full response dumps. If the GET returns 2xx/3xx, omit this tier-hint subsection.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not probe arbitrary mutation endpoints to discover tier limits. A generic \"try a PUT/POST/PATCH/DELETE\" rule can create accounts, send messages, capture payments, or mutate user data. Mutation probing is allowed only when the resolved spec or OpenAPI operation explicitly marks that endpoint as probe-safe with ","type":"text"},{"text":"x-pp-safe-probe: true","type":"text","marks":[{"type":"code_inline"}]},{"text":"; the endpoint must be idempotent or otherwise harmless for the real account being used. If no endpoint has that explicit marker, stop after the GET body capture above.","type":"text"}]},{"type":"paragraph","content":[{"text":"If one or more probe-safe endpoints are declared and the user provided credentials, run exactly one declared probe-safe endpoint as a second reachability probe and apply the same 4xx body capture and tier-keyword extraction. When more than one exists, choose the lowest-risk declared endpoint by preferring methods in this order: HEAD/OPTIONS/GET, then PUT/PATCH, then POST, then DELETE only if it is the only declared safe option. Break ties by choosing the endpoint with the fewest required parameters and avoiding paths with account, billing, payment, deletion, or notification terms when any safer declared option exists. Record which endpoint was probe-safe in the brief so later phases know the evidence came from an opt-in safe probe.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"OAuth2 Grant Probe","type":"text"}]},{"type":"paragraph","content":[{"text":"If the resolved spec declares ","type":"text"},{"text":"auth.type: oauth2","type":"text","marks":[{"type":"code_inline"}]},{"text":" and has an interactive authorization URL (","type":"text"},{"text":"authorizationCode","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"implicit","type":"text","marks":[{"type":"code_inline"}]},{"text":" flow in OpenAPI, or an equivalent internal YAML auth field), the generic reachability check is not enough. After the base URL check would otherwise pass, verify the OAuth grant entry point with the user's real public OAuth input before Phase 2. This probe is read-only: it stops at the provider's consent, login, or error page and does not exchange a code, request a token, or ask the user to approve consent.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not run this grant probe for OAuth2 ","type":"text"},{"text":"client_credentials","type":"text","marks":[{"type":"code_inline"}]},{"text":" flows that only have a token URL. Those are server-to-server credentials, not browser grant flows, and probing the token endpoint would require secret material or a write-like auth attempt. The base reachability check plus later mock/live auth verification cover that shape.","type":"text"}]},{"type":"paragraph","content":[{"text":"Required inputs:","type":"text","marks":[{"type":"strong"}]},{"text":" Use the ","type":"text"},{"text":"client_id","type":"text","marks":[{"type":"code_inline"}]},{"text":" env var or public auth-flow input already resolved during Phase 0.5 and Pre-Generation Auth Enrichment. If the spec exposes ","type":"text"},{"text":"x-auth-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":", prefer the entry with ","type":"text"},{"text":"kind: auth_flow_input","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"sensitive: false","type":"text","marks":[{"type":"code_inline"}]},{"text":", and a name or description identifying it as the OAuth ","type":"text"},{"text":"client_id","type":"text","marks":[{"type":"code_inline"}]},{"text":". If the real client id is missing, HOLD before generation and tell the user exactly which env var to set. Do not substitute a fake client id; fake ids can produce provider-specific errors that look like transport quirks.","type":"text"}]},{"type":"paragraph","content":[{"text":"Build the authorize URL from the resolved spec, not from a guessed provider default:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"client_id","type":"text","marks":[{"type":"code_inline"}]},{"text":": the real public client id from the env var above.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"redirect_uri","type":"text","marks":[{"type":"code_inline"}]},{"text":": the redirect URI declared in the spec or auth metadata.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"response_type=code","type":"text","marks":[{"type":"code_inline"}]},{"text":" for authorization-code grants, or the spec's documented response type for implicit grants.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For authorization-code grants, include a safe probe PKCE pair using ","type":"text"},{"text":"S256","type":"text","marks":[{"type":"code_inline"}]},{"text":". Use ","type":"text"},{"text":"probe_reachability_check_pkce_probe_literal","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the code verifier and compute the URL-safe SHA-256 challenge from it. The verifier is 43 unreserved characters, satisfying the RFC 7636 minimum; providers that do not require PKCE ignore these params, and providers that enforce PKCE should advance to the login or consent page instead of returning a false ","type":"text"},{"text":"invalid_request","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scope","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"audience","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tenant","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"state","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"prompt","type":"text","marks":[{"type":"code_inline"}]},{"text":", or other provider-required params when the spec or vendor docs require them. Use a benign probe value for ","type":"text"},{"text":"state","type":"text","marks":[{"type":"code_inline"}]},{"text":" if required.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use a redirect-limited GET and inspect the final URL, response body, and response class:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"PKCE_VERIFIER=\"probe_reachability_check_pkce_probe_literal\"\nPKCE_CHALLENGE=$(printf \"%s\" \"$PKCE_VERIFIER\" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')\nAUTH_URL=\"\u003cauthorization_url_with_required_query_params>\"\n# Add code_challenge_method=S256 and code_challenge=$PKCE_CHALLENGE to AUTH_URL.\nPROBE_BODY_AND_META=$(curl -sS -L --max-redirs 10 -m 15 -w \"\\n%{http_code} %{url_effective}\" -o - \"$AUTH_URL\" 2>/dev/null)\nPROBE_META=$(printf \"%s\\n\" \"$PROBE_BODY_AND_META\" | tail -n 1)\nPROBE_BODY=$(printf \"%s\\n\" \"$PROBE_BODY_AND_META\" | sed '$d')\nprintf \"%s\\n\" \"$PROBE_META\"\nprintf \"%s\\n\" \"$PROBE_BODY\" | head -c 8000\nprintf \"\\n\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Interpret the result before Phase 2:","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"OAuth probe result","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HTTP status is ","type":"text"},{"text":"2xx","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"3xx","type":"text","marks":[{"type":"code_inline"}]},{"text":", final URL stays on the provider's authorization/login/consent host, does not include ","type":"text"},{"text":"error=","type":"text","marks":[{"type":"code_inline"}]},{"text":", and the response body does not contain an OAuth error code (","type":"text"},{"text":"invalid_request","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"invalid_client","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"unauthorized_client","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PASS","type":"text","marks":[{"type":"strong"}]},{"text":" - the grant entry point is reachable; proceed to Phase 2","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Final URL or response body reports ","type":"text"},{"text":"invalid_request","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"invalid_client","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"redirect_uri_mismatch","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"unauthorized_client","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"unsupported_response_type","type":"text","marks":[{"type":"code_inline"}]},{"text":", or equivalent","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HARD STOP","type":"text","marks":[{"type":"strong"}]},{"text":" - OAuth config is misconfigured; surface the provider error and point the user to the mismatched client id, redirect URI, app type, tenant, or required scope","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HTTP status is ","type":"text"},{"text":"4xx","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"5xx","type":"text","marks":[{"type":"code_inline"}]},{"text":" without a recognizable OAuth error code","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WARN","type":"text","marks":[{"type":"strong"}]},{"text":" - flag provider-specific routing or login-shell behavior for manual review before generation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Final URL lands on a generic non-OAuth error page, marketing page, or unrelated login landing page","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WARN","type":"text","marks":[{"type":"strong"}]},{"text":" - flag endpoint ambiguity or provider-specific routing for manual review before generation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Timeout/DNS/connection refused or HTTP status ","type":"text"},{"text":"000","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WARN","type":"text","marks":[{"type":"strong"}]},{"text":" - same handling as the generic reachability WARN","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"On HARD STOP, do not generate. Present a specific, provider-neutral message:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"WARNING: ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s OAuth authorize probe failed before generation. The provider returned ","type":"text"},{"text":"\u003cerror_or_final_url>","type":"text","marks":[{"type":"code_inline"}]},{"text":". Check that the spec's ","type":"text"},{"text":"authorization_url","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"redirect_uri","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"response_type","type":"text","marks":[{"type":"code_inline"}]},{"text":", client id env var, app type, tenant, and required scopes match the registered OAuth application.\"","type":"text"}]}]},{"type":"paragraph","content":[{"text":"This OAuth probe is additive to the base reachability gate. Non-OAuth APIs (","type":"text"},{"text":"api_key","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"bearer_token","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"cookie","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"composed","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"session_handshake","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"none","type":"text","marks":[{"type":"code_inline"}]},{"text":") skip it entirely.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the check returns 403/429 with bot-protection evidence and ","type":"text","marks":[{"type":"strong"}]},{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" has not already run for this URL during Phase 1.7's Direct HTTP challenge rule, run it now before consulting the decision matrix:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press probe-reachability \"\u003cbase_url>\" --json","type":"text"}]},{"type":"paragraph","content":[{"text":"The matrix below references ","type":"text"},{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the bot-detection rows. If the probe already ran in Phase 1.7, reuse that result; do not re-probe.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Decision Matrix","type":"text"}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Result","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Browser capture result","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Traffic-analysis reachability","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"2xx/3xx","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PASS","type":"text","marks":[{"type":"strong"}]},{"text":" - proceed to Phase 2","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"401 (no key provided)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PASS","type":"text","marks":[{"type":"strong"}]},{"text":" - expected when API needs auth and user declined key gate","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"403/429 with HTML/bot detection","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":" returned ","type":"text"},{"text":"browser_http","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"runtime is ","type":"text"},{"text":"browser_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" (Surf)","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PASS","type":"text","marks":[{"type":"strong"}]},{"text":" - the printed CLI will ship Surf transport which clears the protection. No clearance cookie capture in the printed CLI, regardless of whether browser-sniff also ran for endpoint discovery","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"403/429 with HTML/bot detection","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Successful useful capture","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"browser_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"PASS","type":"text","marks":[{"type":"strong"}]},{"text":" - proceed with browser-compatible HTTP / clearance strategy","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Capture only works through a live page context","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"browser_required","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HOLD","type":"text","marks":[{"type":"strong"}]},{"text":" - find a lighter replayable surface before Phase 2","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"403/429 with HTML/bot detection","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No browser capture attempted but browser-sniff approved/pre-approved AND ","type":"text"},{"text":"probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":" returned ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"unknown","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"RETURN TO PHASE 1.7","type":"text","marks":[{"type":"strong"}]},{"text":" - attempt cleared-browser capture before pivoting scope","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"403/429 with HTML/bot detection","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Capture contains only challenge/error pages","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HARD STOP","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"403","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No successful useful capture","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Research found 403 issues","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"HARD STOP","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"403","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No successful useful capture","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"No 403 research issues","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WARN","type":"text","marks":[{"type":"strong"}]},{"text":" - ask user","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Timeout/DNS/connection refused","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Any","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"WARN","type":"text","marks":[{"type":"strong"}]},{"text":" - ask user","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"On HARD STOP","type":"text"}]},{"type":"paragraph","content":[{"text":"Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"WARNING: ","type":"text"},{"text":"\u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":" appears to block programmatic access. [what failed: e.g., 'HTTP 403 with HTML error page', 'browser-sniff gate failed with bot detection', 'reteps/redfin has 6+ issues about 403 errors']. Building a CLI against an unreachable API wastes time and tokens.\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Try anyway","type":"text","marks":[{"type":"strong"}]},{"text":" - proceed knowing the CLI may not work against the live API","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pick a different API","type":"text","marks":[{"type":"strong"}]},{"text":" - start over","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Done","type":"text","marks":[{"type":"strong"}]},{"text":" - stop here","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"On WARN","type":"text"}]},{"type":"paragraph","content":[{"text":"Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"The API returned [error]. This might be temporary, or it might mean programmatic access is blocked. Want to proceed?\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes - proceed","type":"text","marks":[{"type":"strong"}]},{"text":" - generate the CLI anyway","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No - stop","type":"text","marks":[{"type":"strong"}]},{"text":" - pick a different API or provide a spec manually","type":"text"}]}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"On PASS","type":"text"}]},{"type":"paragraph","content":[{"text":"Proceed silently to Phase 2.","type":"text"}]},{"type":"hr","attrs":{"markup":"---"}},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 2: Generate","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-Generation Category Enrichment","type":"text"}]},{"type":"paragraph","content":[{"text":"Before generating a non-catalog CLI, set the spec's top-level ","type":"text"},{"text":"category","type":"text","marks":[{"type":"code_inline"}]},{"text":" before running ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":". The category must come from the Phase 1 research brief's domain judgment, mapped to the public catalog enum documented in ","type":"text"},{"text":"docs/CATALOG.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Non-catalog means the run is based on browser-sniffed traffic, HAR capture, docs-derived specs, or a hand-authored internal spec rather than ","type":"text"},{"text":"cli-printing-press generate \u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":" using a built-in catalog entry. For internal YAML specs, add:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"category: \u003ccatalog-category>","type":"text"}]},{"type":"paragraph","content":[{"text":"If the source is an OpenAPI file and the workflow has an editable overlay or derived internal spec, carry the same top-level category into that generated spec artifact before the final ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocation. If there is no editable spec artifact, such as direct ","type":"text"},{"text":"--docs","type":"text","marks":[{"type":"code_inline"}]},{"text":" generation, pass ","type":"text"},{"text":"--category \u003ccatalog-category>","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the final ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocation. Do not add the category after generation just to satisfy publish; the generated manifest, README, and SKILL install section must all come from the same category-aware spec, or ","type":"text"},{"text":"verify-skill canonical-sections","type":"text","marks":[{"type":"code_inline"}]},{"text":" can drift.","type":"text"}]},{"type":"paragraph","content":[{"text":"Catalog-mode runs skip this step: keep the built-in catalog entry's category unchanged, even if Phase 1 research would classify the API differently.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-Generation Cache Enrichment","type":"text"}]},{"type":"paragraph","content":[{"text":"Before generating, decide whether the spec should opt into generator-owned cache freshness. The generator already has the freshness helpers and auto-refresh hook, but it emits them only when the spec declares ","type":"text"},{"text":"cache.enabled: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the CLI has a real sync path. Stateful catalog-shaped CLIs otherwise serve local data exactly as it was last synced, which caps the cache freshness score and can leave agents reading stale SQLite rows without a warning.","type":"text"}]},{"type":"paragraph","content":[{"text":"Enable cache freshness only when the resolved spec, profiler output, or absorb manifest shows at least one covered read path backed by a syncable resource that ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"code_inline"}]},{"text":" can refresh from the upstream API before serving. Do not enable it from Phase 1 research notes or scorecard goals alone. Leave it disabled for stateless read-through wrappers and for local stores that are primarily per-user working state, such as carts, drafts, or other session-owned data where a pre-read refresh could replace the user's local state with a different snapshot. Also leave it disabled for quota-metered, paid, rate-limited, or expensive bulk refresh APIs unless the refresh path is cheap, bounded, and clearly valuable; those CLIs should rely on manual ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"code_inline"}]},{"text":" plus the generated ","type":"text"},{"text":"doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" cache report instead of surprising users with pre-read upstream calls.","type":"text"}]},{"type":"paragraph","content":[{"text":"Catalog-mode runs skip this step: keep the built-in catalog entry's cache settings unchanged. Do not pass a flag or patch generated files after the fact; cache freshness must come from the spec that drives generation.","type":"text"}]},{"type":"paragraph","content":[{"text":"For internal YAML specs, add the cache block before the final ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocation only when at least one generated syncable resource read command will be covered automatically, or ","type":"text"},{"text":"cache.commands","type":"text","marks":[{"type":"code_inline"}]},{"text":" will register a real hand-authored store-reading command:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"cache:\n enabled: true\n stale_after: 168h # choose a domain-appropriate default\n refresh_timeout: 30s # optional; blank uses the generated runtime default","type":"text"}]},{"type":"paragraph","content":[{"text":"Generated resource list/get/search commands are covered automatically from the syncable resources profile. Use ","type":"text"},{"text":"cache.commands","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for hand-authored novel commands that read the local store and are not generated resource commands. The command ","type":"text"},{"text":"name","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the Cobra path without the binary name, and every listed resource must be declared in ","type":"text"},{"text":"resources:","type":"text","marks":[{"type":"code_inline"}]},{"text":" and classified as syncable.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"cache:\n enabled: true\n stale_after: 168h # choose a domain-appropriate default\n commands:\n - name: \u003cnovel-read-command>\n resources: [\u003cresource-name>]","type":"text"}]},{"type":"paragraph","content":[{"text":"Pick ","type":"text"},{"text":"stale_after","type":"text","marks":[{"type":"code_inline"}]},{"text":" from the domain's update cadence: shorter for live feeds or rapidly changing inventory, longer for reference catalogs and archival data. Do not enable cache just to satisfy the scorecard if there is no upstream refresh path or no user value in pre-read freshness; the generator intentionally skips the helpers when they would be dead code.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-Generation Auth Enrichment","type":"text"}]},{"type":"paragraph","content":[{"text":"Before generating, check whether the resolved spec has auth. This matters most for browser-sniffed and crowd-sniffed specs where the mechanical auth detection may have failed (e.g., session expired during browser-sniff, SDK didn't expose auth patterns).","type":"text"}]},{"type":"paragraph","content":[{"text":"Check the spec:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For internal YAML specs: look for ","type":"text"},{"text":"auth:","type":"text","marks":[{"type":"code_inline"}]},{"text":" section with ","type":"text"},{"text":"type:","type":"text","marks":[{"type":"code_inline"}]},{"text":" not equal to ","type":"text"},{"text":"\"none\"","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For OpenAPI specs: look for ","type":"text"},{"text":"components.securitySchemes","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":" sections","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If auth is missing","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"type: none","type":"text","marks":[{"type":"code_inline"}]},{"text":" or no auth section) AND Phase 1 research found auth signals, enrich the spec before generation:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check the research brief for auth mentions (Bearer, API key, token, cookie, OAuth)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check Phase 1.5a MCP source code analysis for auth patterns (header names, token formats)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check Phase 1.6 Pre-Browser-Sniff Auth Intelligence results (if the user confirmed auth)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If any source identified auth, ","type":"text"},{"text":"edit the spec YAML","type":"text","marks":[{"type":"strong"}]},{"text":" to add the auth section before running generate. Catalog-mode runs (","type":"text"},{"text":"cli-printing-press generate \u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":" where ","type":"text"},{"text":"\u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":" is in ","type":"text"},{"text":"catalog/","type":"text","marks":[{"type":"code_inline"}]},{"text":") can skip the spec edit when the catalog entry declares ","type":"text"},{"text":"auth_env_vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" — those canonical names are applied automatically and the parser's name-derived default name is retained as a trailing fallback so operators on existing setups don't need a rename. For internal YAML specs:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"auth:\n type: bearer_token # or api_key, depending on what research found\n header: Authorization # or the specific header from MCP source\n in: header\n env_vars:\n - \u003cAPI_NAME>_TOKEN # bearer_token → _TOKEN, api_key → _API_KEY","type":"text"}]},{"type":"paragraph","content":[{"text":"When research or source metadata names a real single-token env var, record it in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" as ","type":"text"},{"text":"auth.canonical_env_var","type":"text","marks":[{"type":"code_inline"}]},{"text":"; fresh generation reads that name first and keeps the parser-derived env var as a trailing fallback. When you are editing an internal YAML spec directly, use only the canonical name in ","type":"text"},{"text":"env_vars","type":"text","marks":[{"type":"code_inline"}]},{"text":"; do not add guessed slug-based aliases.","type":"text"}]},{"type":"paragraph","content":[{"text":"For OpenAPI specs, choose the security scheme by wire format, not by whether the token feels like an API key. Use ","type":"text"},{"text":"type: http","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"scheme: bearer","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the upstream API sends ","type":"text"},{"text":"Authorization: Bearer \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":", including PAT-shaped tokens such as Slack ","type":"text"},{"text":"xoxp","type":"text","marks":[{"type":"code_inline"}]},{"text":", Notion integration tokens, Linear API keys, and GitHub PATs. Use ","type":"text"},{"text":"type: apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when the API sends the configured value as the raw header or query value, such as ","type":"text"},{"text":"X-API-Key: \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"Authorization: \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":" with no scheme prefix. The generator adds the ","type":"text"},{"text":"Bearer ","type":"text","marks":[{"type":"code_inline"}]},{"text":" prefix for ","type":"text"},{"text":"http","type":"text","marks":[{"type":"code_inline"}]},{"text":" bearer schemes; ","type":"text"},{"text":"apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":" sends exactly the configured value and will not add a prefix.","type":"text"}]},{"type":"paragraph","content":[{"text":"Quick test: if upstream docs or live traffic show ","type":"text"},{"text":"Authorization: Bearer \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":", model it as ","type":"text"},{"text":"http","type":"text","marks":[{"type":"code_inline"}]},{"text":" bearer. If they show ","type":"text"},{"text":"X-API-Key: \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"?api_key=\u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"Authorization: \u003ctoken>","type":"text","marks":[{"type":"code_inline"}]},{"text":" with no scheme prefix, model it as ","type":"text"},{"text":"apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"For OpenAPI specs, prefer ","type":"text"},{"text":"x-auth-env-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the selected security scheme when the wrapper slug differs from the underlying API brand.","type":"text"}]},{"type":"paragraph","content":[{"text":"If auth IS present","type":"text","marks":[{"type":"strong"}]},{"text":" in the spec but Phase 1 evidence shows the slug-derived env var will differ from the canonical name users have already set for this API, enrich the spec with the canonical name before generation. The slug-derivation rule (security-scheme slug uppercased plus ","type":"text"},{"text":"_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"_API_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"_OAUTH2","type":"text","marks":[{"type":"code_inline"}]},{"text":" per type) rarely matches the canonical name for established APIs. Common shapes:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stripe (bearer): canonical ","type":"text"},{"text":"STRIPE_SECRET_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":", not slug-derived ","type":"text"},{"text":"STRIPE_OAUTH2","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"HubSpot (bearer): canonical ","type":"text"},{"text":"HUBSPOT_PRIVATE_APP_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", not slug-derived ","type":"text"},{"text":"HUBSPOT_API_KEY","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Twilio (HTTP Basic, two-var pair): canonical ","type":"text"},{"text":"TWILIO_ACCOUNT_SID","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"TWILIO_AUTH_TOKEN","type":"text","marks":[{"type":"code_inline"}]},{"text":", not slug-derived ","type":"text"},{"text":"TWILIO_USERNAME","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"TWILIO_PASSWORD","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keap (OAuth2 authorization-code): canonical ","type":"text"},{"text":"KEAP_SERVICE_ACCOUNT_KEY","type":"text","marks":[{"type":"code_inline"}]},{"text":", not slug-derived ","type":"text"},{"text":"KEAP_OAUTH2","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Walk through:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Compute the slug-derived env var the generator will pick (security-scheme slug, uppercased, plus the type-suffix above; HTTP Basic produces a ","type":"text"},{"text":"_USERNAME","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"_PASSWORD","type":"text","marks":[{"type":"code_inline"}]},{"text":" pair; OAuth2 ","type":"text"},{"text":"client_credentials","type":"text","marks":[{"type":"code_inline"}]},{"text":" produces a ","type":"text"},{"text":"_CLIENT_ID","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"_CLIENT_SECRET","type":"text","marks":[{"type":"code_inline"}]},{"text":" pair).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Check Phase 1 research, Phase 1.5a MCP source code analysis, and community wrapper READMEs for a canonical env var name documented by the vendor or in widespread use.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If they differ and the canonical name is a single-token credential, record it in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" as ","type":"text"},{"text":"auth.canonical_env_var","type":"text","marks":[{"type":"code_inline"}]},{"text":". The generator will read the canonical name first and retain the slug-derived form as a fallback. If you are editing the source spec directly instead, add ","type":"text"},{"text":"x-auth-env-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the selected security scheme (OpenAPI) or set ","type":"text"},{"text":"auth.env_vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the canonical name (internal YAML). Use only the canonical name in the spec edit; do not retain guessed aliases there. For HTTP Basic, supply the full two-entry canonical pair (username position first, password position second) via ","type":"text"},{"text":"x-auth-env-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":". For OAuth2 ","type":"text"},{"text":"client_credentials","type":"text","marks":[{"type":"code_inline"}]},{"text":", the parser silently re-applies the ","type":"text"},{"text":"CLIENT_ID","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"CLIENT_SECRET","type":"text","marks":[{"type":"code_inline"}]},{"text":" default when ","type":"text"},{"text":"x-auth-env-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" has fewer than two entries (see ","type":"text"},{"text":"applyAuthEnvVarDefaults","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"internal/openapi/parser.go","type":"text","marks":[{"type":"code_inline"}]},{"text":"); if the canonical secret is a single service-account token for a ","type":"text"},{"text":"client_credentials","type":"text","marks":[{"type":"code_inline"}]},{"text":" flow, use ","type":"text"},{"text":"x-auth-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead (next section) so the override is preserved.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If research surfaces no canonical name distinct from the slug-derived form, do nothing. The slug-derived name is fine, and a spurious ","type":"text"},{"text":"x-auth-env-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" would just shadow it with the same value.","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# Bearer / API-key single-token case (Stripe, HubSpot, Keap on\n# authorization-code grant, most apiKey schemes).\ncomponents:\n securitySchemes:\n keapOAuth2:\n type: oauth2\n flows:\n authorizationCode: { ... }\n x-auth-env-vars:\n - KEAP_SERVICE_ACCOUNT_KEY","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# HTTP Basic two-var canonical pair (Twilio).\ncomponents:\n securitySchemes:\n basicAuth:\n type: http\n scheme: basic\n x-auth-env-vars:\n - TWILIO_ACCOUNT_SID\n - TWILIO_AUTH_TOKEN","type":"text"}]},{"type":"paragraph","content":[{"text":"Skipping this step pushes the agent into hand-patching ","type":"text"},{"text":"internal/config/config.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" Load and ","type":"text"},{"text":"internal/cli/doctor.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" env-var checks after a ","type":"text"},{"text":"doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" FAIL against the operator's real environment. Enriching the spec avoids that round-trip.","type":"text"}]},{"type":"paragraph","content":[{"text":"For OpenAPI bearer-token specs that need richer env-var metadata (kind classification, optional credentials, OR-group relationships), keep the security scheme as ","type":"text"},{"text":"http","type":"text","marks":[{"type":"code_inline"}]},{"text":" bearer and put ","type":"text"},{"text":"x-auth-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" on that scheme. Do not switch to ","type":"text"},{"text":"apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":" just to attach the richer metadata.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"components:\n securitySchemes:\n bearerAuth:\n type: http\n scheme: bearer\n bearerFormat: xoxp\n x-auth-vars:\n - name: SLACK_BOT_TOKEN\n kind: per_call\n required: false\n sensitive: true\n description: Set this OR `SLACK_USER_TOKEN` for workspace API calls.\n - name: SLACK_USER_TOKEN\n kind: per_call\n required: false\n sensitive: true\n description: Set this OR `SLACK_BOT_TOKEN` for user-scoped API calls.","type":"text"}]},{"type":"paragraph","content":[{"text":"For OpenAPI raw-key schemes that need richer env-var metadata, keep ","type":"text"},{"text":"apiKey","type":"text","marks":[{"type":"code_inline"}]},{"text":" and place ","type":"text"},{"text":"x-auth-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the raw-key scheme.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"components:\n securitySchemes:\n rawHeaderKey:\n type: apiKey\n in: header\n name: X-API-Key\n x-auth-vars:\n - name: \u003cAPI_NAME>_API_KEY\n kind: per_call\n required: true\n sensitive: true\n description: Raw API key header value.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"docs/SPEC-EXTENSIONS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the canonical ","type":"text"},{"text":"x-auth-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" schema.","type":"text"}]},{"type":"paragraph","content":[{"text":"kind","type":"text","marks":[{"type":"code_inline"}]},{"text":" controls who supplies the value:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"per_call","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the default user-supplied credential used by normal commands.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"auth_flow_input","type":"text","marks":[{"type":"code_inline"}]},{"text":" is only needed during ","type":"text"},{"text":"auth login","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"harvested","type":"text","marks":[{"type":"code_inline"}]},{"text":" is populated by the auth login flow into local config.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"sensitive: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" means credential material that must be redacted in logs and agent context. Use ","type":"text"},{"text":"sensitive: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" for public configuration, such as an OAuth ","type":"text"},{"text":"client_id","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Encode AND/OR relationships with each var's ","type":"text"},{"text":"required","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag plus ","type":"text"},{"text":"description","type":"text","marks":[{"type":"code_inline"}]},{"text":" text. There is no first-class group syntax. For OR cases, mark each alternative ","type":"text"},{"text":"required: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" and name the other option in the description. For AND cases, mark each required member ","type":"text"},{"text":"required: true","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"The parser auto-classifies cookie schemes as ","type":"text"},{"text":"harvested","type":"text","marks":[{"type":"code_inline"}]},{"text":" and OAuth2 ","type":"text"},{"text":"client_credentials","type":"text","marks":[{"type":"code_inline"}]},{"text":" inputs as ","type":"text"},{"text":"auth_flow_input","type":"text","marks":[{"type":"code_inline"}]},{"text":". Add ","type":"text"},{"text":"x-auth-vars","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when overriding those defaults or resolving multi-scheme ambiguity.","type":"text"}]},{"type":"paragraph","content":[{"text":"For OpenAPI specs, add an ","type":"text"},{"text":"info.description","type":"text","marks":[{"type":"code_inline"}]},{"text":" mention if one doesn't exist — the parser's ","type":"text"},{"text":"inferDescriptionAuth","type":"text","marks":[{"type":"code_inline"}]},{"text":" will detect it automatically.","type":"text"}]},{"type":"paragraph","content":[{"text":"Why enrich before generation, not after:","type":"text","marks":[{"type":"strong"}]},{"text":" The generator's templates (config, client, doctor, auth, README) all read ","type":"text"},{"text":"Auth.*","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields from the spec. Patching config.go after generation only fixes env var support — it misses the doctor auth check, client auth header, README auth section, and auth command setup. Enriching the spec means every template produces correct auth from the start.","type":"text"}]},{"type":"paragraph","content":[{"text":"When to skip:","type":"text","marks":[{"type":"strong"}]},{"text":" If the API genuinely doesn't need auth (ESPN public endpoints, weather APIs, public data feeds), don't invent auth. The signal must come from research — not from guessing. No research mention of auth = no enrichment.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Public Parameter Name Enrichment","type":"text"}]},{"type":"paragraph","content":[{"text":"Before generating, inspect endpoint params and body fields whose API names would make poor CLI or MCP inputs, especially one-letter keys, punctuation-heavy keys, or names that only make sense inside the upstream protocol. When clear evidence shows the user-facing meaning, author ","type":"text"},{"text":"flag_name","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the internal spec or overlay and add ","type":"text"},{"text":"aliases","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for compatibility spellings.","type":"text"}]},{"type":"paragraph","content":[{"text":"This is an agent judgment step, not a generator inference step. The skill uses research, docs, SDK/source names, browser-sniff form labels, traffic-analysis request context, and endpoint workflow evidence to decide the semantic name. The Printing Press CLI validates and propagates that authored data through Cobra flags, generated examples, typed MCP schemas, and ","type":"text"},{"text":"tools-manifest.json","type":"text","marks":[{"type":"code_inline"}]},{"text":"; it must not guess that a cryptic key always means the same thing across APIs.","type":"text"}]},{"type":"paragraph","content":[{"text":"Run the deterministic inventory before generation when a spec may contain cryptic wire names:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press public-param-audit --spec \u003cspec-or-overlay-output> --ledger \u003crunstate>/public-param-audit.json --strict","type":"text"}]},{"type":"paragraph","content":[{"text":"The command does not decide that every finding needs a public flag. It identifies parameters that need an agent decision. For each pending finding, either:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Author ","type":"text"},{"text":"flag_name","type":"text","marks":[{"type":"code_inline"}]},{"text":" and compatibility ","type":"text"},{"text":"aliases","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the spec or overlay, then rerun the audit so the finding becomes resolved from the spec itself.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Record ","type":"text"},{"text":"decision: \"skip\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the ledger with ","type":"text"},{"text":"source_evidence","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"skip_reason","type":"text","marks":[{"type":"code_inline"}]},{"text":" when source material shows no public rename is warranted.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A ledger entry with ","type":"text"},{"text":"decision: \"flag_name\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"proposed_flag_name","type":"text","marks":[{"type":"code_inline"}]},{"text":" is only a note to the agent; it is not complete until the spec or overlay actually contains the public name. Strict mode fails on unreviewed findings, not on evidence-backed skips. A one-letter wire name alone is enough to enter the inventory, but not enough to author a rename.","type":"text"}]},{"type":"paragraph","content":[{"text":"Good evidence:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Explicit parameter descriptions, vendor docs, or SDK argument names.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Browser-sniff form/input labels and the interaction that produced the request.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Traffic-analysis context tying the parameter to a specific endpoint workflow.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Existing manuscript notes or reviewed examples that use the same task-level term.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Bad evidence:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A one-letter name alone.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generic descriptions such as \"query parameter\" or \"string value\".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ambiguous sample values with no endpoint context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Global assumptions such as \"","type":"text"},{"text":"s","type":"text","marks":[{"type":"code_inline"}]},{"text":" means search\" or \"","type":"text"},{"text":"c","type":"text","marks":[{"type":"code_inline"}]},{"text":" means city\".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Prefer concise task-level names an agent would naturally use on that command. For a store-locator endpoint with ","type":"text"},{"text":"s","type":"text","marks":[{"type":"code_inline"}]},{"text":" described as ","type":"text"},{"text":"Street address","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"c","type":"text","marks":[{"type":"code_inline"}]},{"text":" described as ","type":"text"},{"text":"City, state, zip","type":"text","marks":[{"type":"code_inline"}]},{"text":", author:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"params:\n - name: s\n flag_name: address\n aliases: [s]\n description: Street address\n - name: c\n flag_name: city\n aliases: [c]\n description: City, state, zip","type":"text"}]},{"type":"paragraph","content":[{"text":"The upstream wire keys remain ","type":"text"},{"text":"s","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"c","type":"text","marks":[{"type":"code_inline"}]},{"text":"; generated users and agents see ","type":"text"},{"text":"address","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"city","type":"text","marks":[{"type":"code_inline"}]},{"text":". If the evidence is unclear after research, leave ","type":"text"},{"text":"flag_name","type":"text","marks":[{"type":"code_inline"}]},{"text":" unset, record the reviewed source material and evidence gap in the audit ledger, and preserve the gap in the manuscript rather than inventing a friendly name.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Free/Paid Tier Routing Enrichment","type":"text"}]},{"type":"paragraph","content":[{"text":"If Phase 1 finds that the headline commands should stay free but secondary enrichment needs a paid key, declare tier routing in the spec before generation. Do this only when research identifies a real split; do not invent tiers for a single-auth API.","type":"text"}]},{"type":"paragraph","content":[{"text":"Detection signals:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Research or source-priority notes say the primary source is free but a secondary source needs a paid/API key.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Some endpoints are documented as public while adjacent enrichment endpoints are documented as paid, partner, premium, or quota-gated.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Browser/crowd sniffing found public endpoints and SDK/MCP research found a separate credential for expanded coverage.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Sniffed specs carry per-endpoint ","type":"text"},{"text":"observed_auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" (a list of lowercased request header names observed during capture, e.g. ","type":"text"},{"text":"[authorization]","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"[x-api-key]","type":"text","marks":[{"type":"code_inline"}]},{"text":"). An empty or missing ","type":"text"},{"text":"observed_auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" on an endpoint is evidence that the request went anonymously; a populated list is evidence the endpoint required auth. The same per-endpoint signal is mirrored on ","type":"text"},{"text":"TrafficAnalysis.endpoint_clusters[].observed_auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the traffic-analysis sidecar. Treat both as observation-only — not a security scheme declaration — and corroborate with documentation before declaring a tier.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Action:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Internal YAML: add ","type":"text"},{"text":"tier_routing","type":"text","marks":[{"type":"code_inline"}]},{"text":" plus ","type":"text"},{"text":"tier","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the affected resource or endpoint.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"OpenAPI: add ","type":"text"},{"text":"x-tier-routing","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the root or under ","type":"text"},{"text":"info","type":"text","marks":[{"type":"code_inline"}]},{"text":", and add ","type":"text"},{"text":"x-tier","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the path item or operation.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"auth.type: none","type":"text","marks":[{"type":"code_inline"}]},{"text":" for the free tier.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use only ","type":"text"},{"text":"api_key","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"bearer_token","type":"text","marks":[{"type":"code_inline"}]},{"text":" for credential tiers in v1.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If a credential tier uses a different ","type":"text"},{"text":"base_url","type":"text","marks":[{"type":"code_inline"}]},{"text":", it must be HTTPS and same host-family unless ","type":"text"},{"text":"allow_cross_host_auth: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" records explicit review.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not combine ","type":"text"},{"text":"no_auth: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" or OpenAPI ","type":"text"},{"text":"security: []","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a credential tier.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Skip when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"All useful commands require the same credential.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The paid source would become the primary headline surface instead of enrichment.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The auth split requires OAuth, cookie, composed, or session-handshake tier auth; handle that as a normal auth-mode decision for now.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Example:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"tier_routing:\n default_tier: free\n tiers:\n free:\n auth: {type: none}\n paid:\n auth:\n type: api_key\n in: query\n header: api_key\n env_vars: [EXAMPLE_PAID_KEY]\nresources:\n search:\n tier: free\n endpoints:\n list:\n method: GET\n path: /search\n enrich:\n method: GET\n path: /paid/search\n tier: paid","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Tagging endpoints ","type":"text"},{"text":"no_auth: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" (composed/cookie auth APIs)","type":"text"}]},{"type":"paragraph","content":[{"text":"For APIs whose ","type":"text"},{"text":"auth.type","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"cookie","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"composed","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"session_handshake","type":"text","marks":[{"type":"code_inline"}]},{"text":" — i.e., auth that requires interactive setup (browser cookie capture, multi-step token exchange) — audit each endpoint individually for whether it actually needs authentication. The default of ","type":"text"},{"text":"no_auth: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" means \"auth required\"; flip it to ","type":"text"},{"text":"no_auth: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" for endpoints that work without credentials.","type":"text"}]},{"type":"paragraph","content":[{"text":"Typical unauthenticated endpoints worth tagging:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auth-flow primitives:","type":"text","marks":[{"type":"strong"}]},{"text":" login, registration, password-reset, email-confirm, refresh-token, OAuth callback. The user isn't authenticated when calling these — they ARE the auth flow.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Public discovery:","type":"text","marks":[{"type":"strong"}]},{"text":" store/location finder, menu browse, public catalog, category listing, public search, public product detail.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Health/metadata:","type":"text","marks":[{"type":"strong"}]},{"text":" health checks, version probes, capability flags, sitemap.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Why this matters: the ","type":"text"},{"text":"no_auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" count drives downstream decisions. Specifically, a composed-auth API with zero ","type":"text"},{"text":"no_auth: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" tags previously got labeled ","type":"text"},{"text":"mcp_ready: cli-only","type":"text","marks":[{"type":"code_inline"}]},{"text":" and was suppressed from MCPB manifest emission, which broke the Claude Desktop install path entirely. The current generator (post-2.5) ships a manifest regardless, but the readiness label, scorecard breadth dimension, and SKILL.md prose all read better when the count reflects reality.","type":"text"}]},{"type":"paragraph","content":[{"text":"If unsure whether an endpoint requires auth, the safe default is ","type":"text"},{"text":"no_auth: false","type":"text","marks":[{"type":"code_inline"}]},{"text":" (auth required) — over-tagging can mislead users to expect tools that won't work.","type":"text"}]},{"type":"paragraph","content":[{"text":"Example for a composed-auth pizza-ordering API:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"resources:\n account:\n endpoints:\n register:\n method: POST\n path: /account/register\n no_auth: true # registering means you're not yet authenticated\n login:\n method: POST\n path: /account/login\n no_auth: true # the auth flow itself\n profile:\n method: GET\n path: /account/profile\n # no_auth defaults to false — needs auth to view your own profile\n stores:\n endpoints:\n find:\n method: GET\n path: /stores/near\n no_auth: true # public store finder\n cart:\n endpoints:\n checkout:\n method: POST\n path: /cart/checkout\n # no_auth defaults to false — placing an order needs auth","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Cookie/composed HTML transport","type":"text"}]},{"type":"paragraph","content":[{"text":"For specs with ","type":"text"},{"text":"auth.type: cookie","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"auth.type: composed","type":"text","marks":[{"type":"code_inline"}]},{"text":" and any ","type":"text"},{"text":"response_format: html","type":"text","marks":[{"type":"code_inline"}]},{"text":" endpoint, treat browser fingerprint compatibility as the safe default. The generator emits Surf-backed Chrome transport for that shape unless the spec explicitly says ","type":"text"},{"text":"http_transport: standard","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Before setting an explicit standard opt-out, run ","type":"text"},{"text":"cli-printing-press probe-reachability","type":"text","marks":[{"type":"code_inline"}]},{"text":" against a representative HTML GET endpoint. If the probe returns ","type":"text"},{"text":"standard_http","type":"text","marks":[{"type":"code_inline"}]},{"text":", record ","type":"text"},{"text":"http_transport: standard","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the spec. If it returns ","type":"text"},{"text":"browser_http","type":"text","marks":[{"type":"code_inline"}]},{"text":", leave the default or set ","type":"text"},{"text":"http_transport: browser-chrome","type":"text","marks":[{"type":"code_inline"}]},{"text":". If it returns ","type":"text"},{"text":"browser_clearance_http","type":"text","marks":[{"type":"code_inline"}]},{"text":", return to the browser-clearance flow above so the generated CLI has both browser-compatible HTTP and reusable browser auth proof.","type":"text"}]},{"type":"paragraph","content":[{"text":"For cookie/composed-auth CLIs, recommend the ","type":"text"},{"text":"press-auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" companion binary — it captures cookies once via a controlled Chrome window and serves them to generated CLIs on demand, avoiding the on-disk session-cookie blind spot that breaks ","type":"text"},{"text":"auth login --chrome","type":"text","marks":[{"type":"code_inline"}]},{"text":" against a daily Chrome profile. See ","type":"text"},{"text":"references/auth-companion.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/auth-companion.md","title":null}}]},{"text":" for the recommendation flow, install command, and debug playbook.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-Generation MCP Enrichment","type":"text"}]},{"type":"paragraph","content":[{"text":"Before generating, count the spec's MCP tool surface and decide whether to opt into the spec's ","type":"text"},{"text":"mcp:","type":"text","marks":[{"type":"code_inline"}]},{"text":" enrichment fields. This matters most for medium-to-large APIs (>30 tools) where the default endpoint-mirror surface scores poorly on the scorecard's MCP architectural dimensions and burns agent context at runtime.","type":"text"}]},{"type":"paragraph","content":[{"text":"Why before generation, not after:","type":"text","marks":[{"type":"strong"}]},{"text":" the generator emits the MCP server's ","type":"text"},{"text":"main.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tools.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"intents.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"code_orch.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tools-manifest.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", and README MCP section from the spec at generate-time. Patching after generation fragments across 4+ files, won't be byte-identical, and the polish skill cannot fix it (polish doesn't re-run generation). Enriching the spec means every template emits the right surface from the start.","type":"text"}]},{"type":"paragraph","content":[{"text":"Count the tool surface.","type":"text","marks":[{"type":"strong"}]},{"text":" Two parts:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Typed endpoints","type":"text","marks":[{"type":"strong"}]},{"text":" — count ","type":"text"},{"text":"endpoints","type":"text","marks":[{"type":"code_inline"}]},{"text":" across all ","type":"text"},{"text":"resources","type":"text","marks":[{"type":"code_inline"}]},{"text":" (and ","type":"text"},{"text":"sub_resources","type":"text","marks":[{"type":"code_inline"}]},{"text":") in the spec. These become per-endpoint MCP tools at generate-time.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Cobratree-walked tools","type":"text","marks":[{"type":"strong"}]},{"text":" — the runtime walker registers user-facing Cobra commands as MCP tools. Estimate as: ","type":"text"},{"text":"extra_commands","type":"text","marks":[{"type":"code_inline"}]},{"text":" count + ~13 framework tools that ship by default (sql, search, context, sync, stale, doctor, reconcile, etc., minus framework-skipped). When novel features are planned, add their estimated command count.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The total is what an agent loads at MCP server start.","type":"text"}]},{"type":"paragraph","content":[{"text":"Decision table:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Total tools","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Action","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"\u003c30","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Skip — default endpoint-mirror surface is fine.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"30–50","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Ask the user. Suggest ","type":"text"},{"text":"mcp.transport: [stdio, http]","type":"text","marks":[{"type":"code_inline"}]},{"text":" for remote reach; suggest ","type":"text"},{"text":"mcp.intents","type":"text","marks":[{"type":"code_inline"}]},{"text":" if there are clear multi-step workflows.","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":">50","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"The generator auto-applies the Cloudflare pattern (transport + code orchestration + hidden endpoint tools) unless ","type":"text"},{"text":"mcp.orchestration","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"x-mcp.orchestration","type":"text","marks":[{"type":"code_inline"}]},{"text":" is explicitly set.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Mandatory >50 endpoint-tools confirmation.","type":"text","marks":[{"type":"strong"}]},{"text":" If the pre-generation count predicts more than 50 endpoint tools, expect ","type":"text"},{"text":"generate","type":"text","marks":[{"type":"code_inline"}]},{"text":" to print an informational line beginning ","type":"text"},{"text":"info: applied Cloudflare MCP pattern","type":"text","marks":[{"type":"code_inline"}]},{"text":". This is the intended default and does not require a blocking question. Before verification, polish, dogfood, or publish, confirm the generated MCP surface is the thin ","type":"text"},{"text":"\u003capi>_search","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"\u003capi>_execute","type":"text","marks":[{"type":"code_inline"}]},{"text":" pair. If the user explicitly wants raw endpoint tools past the threshold, set ","type":"text"},{"text":"mcp.orchestration: endpoint-mirror","type":"text","marks":[{"type":"code_inline"}]},{"text":" (internal YAML) or ","type":"text"},{"text":"x-mcp.orchestration: endpoint-mirror","type":"text","marks":[{"type":"code_inline"}]},{"text":" (OpenAPI) before regenerating.","type":"text"}]},{"type":"paragraph","content":[{"text":"The Cloudflare pattern","type":"text","marks":[{"type":"strong"}]},{"text":" (default for large surfaces without explicit orchestration) — the generator applies this shape automatically. Add the spec block only when you need to make the choice explicit or preserve it across older generator versions:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"mcp:\n transport: [stdio, http] # remote-capable; reaches hosted agents\n orchestration: code # thin \u003capi>_search + \u003capi>_execute pair\n endpoint_tools: hidden # suppress raw per-endpoint mirrors\n intents: # optional; named multi-step intents\n - name: fetch_and_summarize\n description: Fetch an item then summarize it\n params:\n - name: item_id\n type: string\n required: true\n description: item identifier\n steps:\n - endpoint: items.get\n bind:\n id: ${input.item_id}\n capture: item\n - endpoint: items.summarize\n bind:\n body: ${item.body}\n capture: summary\n returns: summary","type":"text"}]},{"type":"paragraph","content":[{"text":"mcp.transport: [stdio, http]","type":"text","marks":[{"type":"code_inline"}]},{"text":" adds HTTP streamable transport so cloud-hosted agents (Managed Agents, web clients) can connect. ","type":"text"},{"text":"mcp.orchestration: code","type":"text","marks":[{"type":"code_inline"}]},{"text":" emits the thin search+execute pair that covers the full surface in ~1K tokens. ","type":"text"},{"text":"mcp.endpoint_tools: hidden","type":"text","marks":[{"type":"code_inline"}]},{"text":" removes the raw per-endpoint tools that would otherwise still show up alongside the orchestration pair.","type":"text"}]},{"type":"paragraph","content":[{"text":"For OpenAPI input specs, declare these fields under ","type":"text"},{"text":"x-mcp:","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the document root (OpenAPI 3.0 ","type":"text"},{"text":"x-*","type":"text","marks":[{"type":"code_inline"}]},{"text":" vendor extensions). The shape is identical to the internal-YAML ","type":"text"},{"text":"mcp:","type":"text","marks":[{"type":"code_inline"}]},{"text":" block above — same field names, just nested under a vendor-extension key. See ","type":"text"},{"text":"docs/SPEC-EXTENSIONS.md","type":"text","marks":[{"type":"link","attrs":{"href":"../../docs/SPEC-EXTENSIONS.md","title":null}},{"type":"code_inline"}]},{"text":" for the canonical schema and ","type":"text"},{"text":"info","type":"text","marks":[{"type":"code_inline"}]},{"text":"-level placement option.","type":"text"}]},{"type":"paragraph","content":[{"text":"Smaller-surface variants:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Just want remote reach? Small APIs (at or under ","type":"text"},{"text":"spec.DefaultRemoteTransportEndpointThreshold","type":"text","marks":[{"type":"code_inline"}]},{"text":" typed endpoints) get ","type":"text"},{"text":"[stdio, http]","type":"text","marks":[{"type":"code_inline"}]},{"text":" by default — no spec edit needed. Set ","type":"text"},{"text":"mcp.transport: [stdio, http]","type":"text","marks":[{"type":"code_inline"}]},{"text":" explicitly only when the API is above the threshold and still wants remote reach.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Have 3–5 obvious multi-step workflows but \u003c50 endpoints? Add ","type":"text"},{"text":"mcp.intents","type":"text","marks":[{"type":"code_inline"}]},{"text":" without code orchestration; leave ","type":"text"},{"text":"endpoint_tools","type":"text","marks":[{"type":"code_inline"}]},{"text":" at default (visible).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When to skip entirely:","type":"text","marks":[{"type":"strong"}]},{"text":" small APIs (\u003c30 tools), one-shot specs that won't be installed as MCP servers, or APIs where the user explicitly opts out of MCP enrichment.","type":"text"}]},{"type":"paragraph","content":[{"text":"Verifying after generation:","type":"text","marks":[{"type":"strong"}]},{"text":" the scorecard's ","type":"text"},{"text":"mcp_remote_transport","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"mcp_tool_design","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"mcp_surface_strategy","type":"text","marks":[{"type":"code_inline"}]},{"text":" dimensions reflect the choices above. A correctly enriched spec for a >50 tool API should score 10/10 on all three. If polish later reports these dims weak, that's a sign this enrichment step was skipped — re-run generation with the enriched spec rather than trying to fix it in polish.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Lock and Generate","type":"text"}]},{"type":"paragraph","content":[{"text":"Before running any generate command, acquire the build lock:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock acquire --cli \u003capi>-pp-cli --scope \"$PRESS_SCOPE\"","type":"text"}]},{"type":"paragraph","content":[{"text":"If acquire fails (another session holds a fresh lock), present the lock status to the user and let them decide: wait, use a different CLI name, force-reclaim, or pick a different API.","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"--category \u003ccatalog-category>","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag shown below is for non-catalog runs whose category was not already authored into an editable spec. Omit it for catalog-config runs; the built-in catalog category is authoritative there.","type":"text"}]},{"type":"paragraph","content":[{"text":"--lenient","type":"text","marks":[{"type":"code_inline"}]},{"text":" stubs missing local ","type":"text"},{"text":"#/components/schemas/\u003cName>","type":"text","marks":[{"type":"code_inline"}]},{"text":" refs as permissive object schemas with warnings so converted OpenAPI specs can still generate. Add ","type":"text"},{"text":"--strict-refs","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when a run must fail instead of accepting those local schema stubs; it does not change the rest of lenient cleanup.","type":"text"}]},{"type":"paragraph","content":[{"text":"OpenAPI / internal YAML:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --spec \u003cspec-path-or-url> \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --force --lenient --validate","type":"text"}]},{"type":"paragraph","content":[{"text":"Browser-browser-sniff-enriched (original spec + browser-sniff-discovered spec):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --spec \u003coriginal-spec-path-or-url> \\\n --spec \"$RESEARCH_DIR/\u003capi>-browser-sniff-spec.yaml\" \\\n --name \u003capi> \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --spec-source browser-sniffed \\\n --traffic-analysis \"$DISCOVERY_DIR/traffic-analysis.json\" \\\n --force --lenient --validate\n# If proxy pattern was detected during browser-sniff, add:\n# --client-pattern proxy-envelope","type":"text"}]},{"type":"paragraph","content":[{"text":"Sniff-only (no original spec, browser-sniff was the primary source):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --spec \"$RESEARCH_DIR/\u003capi>-browser-sniff-spec.yaml\" \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --spec-source browser-sniffed \\\n --traffic-analysis \"$DISCOVERY_DIR/traffic-analysis.json\" \\\n --force --lenient --validate\n# If proxy pattern was detected during browser-sniff, add:\n# --client-pattern proxy-envelope","type":"text"}]},{"type":"paragraph","content":[{"text":"Crowd-browser-sniff-enriched (original spec + crowd-discovered spec):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --spec \u003coriginal-spec-path-or-url> \\\n --spec \"$RESEARCH_DIR/\u003capi>-crowd-spec.yaml\" \\\n --name \u003capi> \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --force --lenient --validate","type":"text"}]},{"type":"paragraph","content":[{"text":"Crowd-sniff-only (no original spec, crowd-sniff was the primary source):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --spec \"$RESEARCH_DIR/\u003capi>-crowd-spec.yaml\" \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --force --lenient --validate","type":"text"}]},{"type":"paragraph","content":[{"text":"Both browser-sniff + crowd-sniff (merged with original):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --spec \u003coriginal-spec-path-or-url> \\\n --spec \"$RESEARCH_DIR/\u003capi>-browser-sniff-spec.yaml\" \\\n --spec \"$RESEARCH_DIR/\u003capi>-crowd-spec.yaml\" \\\n --name \u003capi> \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --traffic-analysis \"$DISCOVERY_DIR/traffic-analysis.json\" \\\n --force --lenient --validate","type":"text"}]},{"type":"paragraph","content":[{"text":"Docs-only:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press generate \\\n --docs \u003cdocs-url> \\\n --name \u003capi> \\\n --output \"$CLI_WORK_DIR\" \\\n --research-dir \"$API_RUN_DIR\" \\\n --category \u003ccatalog-category> \\\n --force --validate","type":"text"}]},{"type":"paragraph","content":[{"text":"GraphQL-only APIs:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generate scaffolding only in Phase 2","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build real commands in Phase 3 using a GraphQL client wrapper","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"After generation:","type":"text"}]},{"type":"paragraph","content":[{"text":"Verify the CLI description across every surface.","type":"text","marks":[{"type":"strong"}]},{"text":" A single curated one-liner is rendered into five files: ","type":"text"},{"text":"internal/cli/root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"Short:","type":"text","marks":[{"type":"code_inline"}]},{"text":"), ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" frontmatter (","type":"text"},{"text":"description:","type":"text","marks":[{"type":"code_inline"}]},{"text":"), ","type":"text"},{"text":".goreleaser.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"brews:","type":"text","marks":[{"type":"code_inline"}]},{"text":" description), ","type":"text"},{"text":"internal/cli/agent_context.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"Description:","type":"text","marks":[{"type":"code_inline"}]},{"text":"), and ","type":"text"},{"text":"internal/mcp/tools.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" (the ","type":"text"},{"text":"handleContext","type":"text","marks":[{"type":"code_inline"}]},{"text":" response's ","type":"text"},{"text":"\"description\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" key). Each resolves from the authored sources (","type":"text"},{"text":"narrative.headline","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"cli_description:","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the spec) when set. ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s ","type":"text"},{"text":"Short:","type":"text","marks":[{"type":"code_inline"}]},{"text":" has a safe generic fallback (","type":"text"},{"text":"\"Manage \u003capi> resources via the \u003capi> API\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"); the other four fall through to the spec's raw ","type":"text"},{"text":"info.description","type":"text","marks":[{"type":"code_inline"}]},{"text":" — which is often the upstream OpenAPI blob leading with a Markdown heading like ","type":"text"},{"text":"# Introduction","type":"text","marks":[{"type":"code_inline"}]},{"text":" followed by API-shaped paragraphs. Eyeballing only ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" will miss the failure mode because ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the only surface that's structurally immune.","type":"text"}]},{"type":"paragraph","content":[{"text":"Open at least the ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" frontmatter ","type":"text"},{"text":"description:","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the ","type":"text"},{"text":".goreleaser.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"brews:","type":"text","marks":[{"type":"code_inline"}]},{"text":" block in addition to ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s ","type":"text"},{"text":"Short:","type":"text","marks":[{"type":"code_inline"}]},{"text":". If any reads as API documentation rather than user-facing CLI purpose (\"AeroAPI is a simple, query-based API…\"), or contains a bare Markdown heading, the authored sources are missing. Fix at the source: set ","type":"text"},{"text":"narrative.headline","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" to a single-sentence differentiator (name what makes this CLI worth using, don't restate the API), or add a ","type":"text"},{"text":"cli_description:","type":"text","marks":[{"type":"code_inline"}]},{"text":" line to the spec. Then regenerate. Do not hand-edit the printed files — they revert on the next regen.","type":"text"}]},{"type":"paragraph","content":[{"text":"REQUIRED: Preserve README sections.","type":"text","marks":[{"type":"strong"}]},{"text":" The generated README contains 5 standard sections that the scorecard checks for: Quick Start, Agent Usage, Health Check, Troubleshooting, and Cookbook. When rewriting the README for this API during Phase 3, ","type":"text"},{"text":"preserve all 5 sections","type":"text","marks":[{"type":"strong"}]},{"text":". You may add additional sections that help users of this specific API (e.g., \"Rate Limits\", \"Pagination\", \"Authentication Setup\"), but never remove the standard ones.","type":"text"}]},{"type":"paragraph","content":[{"text":"REQUIRED: Verify auth was generated.","type":"text","marks":[{"type":"strong"}]},{"text":" Check if the generated ","type":"text"},{"text":"config.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" has auth env var support (look for ","type":"text"},{"text":"os.Getenv","type":"text","marks":[{"type":"code_inline"}]},{"text":" calls for API key variables). If the pre-generation auth enrichment ran correctly, this should already be present. If not (enrichment was missed or the spec was ambiguous), this is the safety net: check the Phase 1 research brief for auth requirements and manually add env var support to ","type":"text"},{"text":"config.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" using the pattern: add ","type":"text"},{"text":"APIKey","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"APIKeySource","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields to the Config struct, and ","type":"text"},{"text":"os.Getenv(\"\u003cAPI>_API_KEY\")","type":"text","marks":[{"type":"code_inline"}]},{"text":" in the Load function.","type":"text"}]},{"type":"paragraph","content":[{"text":"Validate narrative ","type":"text","marks":[{"type":"strong"}]},{"text":"command","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" strings before publishing examples.","type":"text","marks":[{"type":"strong"}]},{"text":" The LLM (or human) authoring ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" can name commands that don't actually exist in the generated CLI — ","type":"text"},{"text":"\u003ccli> stats","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the real shape is ","type":"text"},{"text":"\u003ccli> reports stats","type":"text","marks":[{"type":"code_inline"}]},{"text":", or a command that was dropped because its endpoint had a complex body. It can also write a real command path with a bogus flag or positional shape. Without a check, the broken commands ship to the README's Quick Start (","type":"text"},{"text":"narrative.quickstart","type":"text","marks":[{"type":"code_inline"}]},{"text":") and the SKILL's recipes (","type":"text"},{"text":"narrative.recipes","type":"text","marks":[{"type":"code_inline"}]},{"text":"); users copy-paste them and hit failures on the very first invocation.","type":"text"}]},{"type":"paragraph","content":[{"text":"cli-printing-press shipcheck","type":"text","marks":[{"type":"code_inline"}]},{"text":" now runs ","type":"text"},{"text":"validate-narrative --strict --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" automatically after ","type":"text"},{"text":"verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" builds the CLI binary. The standalone command is still useful immediately after editing ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":": it walks every ","type":"text"},{"text":"narrative.quickstart[].command","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"narrative.recipes[].command","type":"text","marks":[{"type":"code_inline"}]},{"text":", strips the binary name and trailing arguments, and runs ","type":"text"},{"text":"\u003cbinary> \u003cwords> --help","type":"text","marks":[{"type":"code_inline"}]},{"text":" for each. With ","type":"text"},{"text":"--full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":", it also runs the complete example under ","type":"text"},{"text":"PRINTING_PRESS_VERIFY=1","type":"text","marks":[{"type":"code_inline"}]},{"text":", appending ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the command advertises it. This catches bad flags and argument shapes without making live API calls.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"QUICKSTART_BINARY=\"$CLI_WORK_DIR/\u003capi>-pp-cli\"\ngo build -o \"$QUICKSTART_BINARY\" \"$CLI_WORK_DIR/cmd/\u003capi>-pp-cli\"\n\ncli-printing-press validate-narrative --strict --full-examples \\\n --research \"$API_RUN_DIR/research.json\" \\\n --binary \"$QUICKSTART_BINARY\"","type":"text"}]},{"type":"paragraph","content":[{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" exits non-zero on any missing command, empty subcommand-words entry, or empty narrative (both sections omitted). With ","type":"text"},{"text":"--full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":", it also fails on full examples that cannot dry-run or whose full invocation fails. Side-effectful auth, launch, and mutating apply examples are reported as ","type":"text"},{"text":"UNSUPPORTED","type":"text","marks":[{"type":"code_inline"}]},{"text":" warnings and do not fail strict aggregation. Drop ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" to get a warn-only report, omit ","type":"text"},{"text":"--full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when you intentionally want the old offline path check, or add ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":" for machine-readable output.","type":"text"}]},{"type":"paragraph","content":[{"text":"If any commands are reported missing, fix them in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" before continuing. Common causes:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Resource was renamed during generation (typically the spec uses ","type":"text"},{"text":"users","type":"text","marks":[{"type":"code_inline"}]},{"text":" but the LLM wrote ","type":"text"},{"text":"user","type":"text","marks":[{"type":"code_inline"}]},{"text":" in research.json).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The endpoint exists but is hidden (had a complex body and was dropped from the promoted-command surface; reach it via the typed ","type":"text"},{"text":"\u003cresource> \u003cendpoint>","type":"text","marks":[{"type":"code_inline"}]},{"text":" form).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The command name is a placeholder (","type":"text"},{"text":"\u003ccli> example","type":"text","marks":[{"type":"code_inline"}]},{"text":") that should have been replaced with a real path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The path exists but the example uses a flag/argument shape the command does not accept; fix the concrete example in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" before it renders into README and SKILL prose.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"narrative.quickstart","type":"text","marks":[{"type":"code_inline"}]},{"text":" drives the README Quick Start and ","type":"text"},{"text":"narrative.recipes","type":"text","marks":[{"type":"code_inline"}]},{"text":" drives the SKILL.md recipes; getting either wrong silently ships copy-paste-broken examples to users. The ","type":"text"},{"text":"--help","type":"text","marks":[{"type":"code_inline"}]},{"text":"-walk check is the cheapest catch and runs offline against the just-built binary — no live API access needed.","type":"text"}]},{"type":"paragraph","content":[{"text":"After the description rewrite, update the lock heartbeat:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase generate","type":"text"}]},{"type":"paragraph","content":[{"text":"Then:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"note skipped complex body fields","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fix only blocking generation failures here","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"do not start broad polish work yet","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If generation fails:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fix the specific blocker","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"retry at most 2 times","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"prefer generator fixes over manual generated-code surgery when the failure is systemic","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"if retries are exhausted, release the lock and stop:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock release --cli \u003capi>-pp-cli","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 3: Build The GOAT","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003c!-- CODEX_PHASE3_START --> When ","type":"text"},{"text":"CODEX_MODE","type":"text","marks":[{"type":"code_inline"}]},{"text":" is true, read ","type":"text"},{"text":"references/codex-delegation.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/codex-delegation.md","title":null}}]},{"text":" for the delegation pattern, task type templates, and circuit breaker logic.","type":"text"}]},{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"CODEX_MODE","type":"text","marks":[{"type":"code_inline"}]},{"text":" is false, skip this section. \u003c!-- CODEX_PHASE3_END -->","type":"text"}]},{"type":"paragraph","content":[{"text":"Build comprehensively. The absorb manifest from Phase 1.5 IS the feature list.","type":"text"}]},{"type":"paragraph","content":[{"text":"First Phase 3 build-log line:","type":"text","marks":[{"type":"strong"}]},{"text":" Before writing code, count the shipping-scope transcendence rows in the Phase 1.5 absorb manifest and write this as the first line of ","type":"text"},{"text":"$PROOFS_DIR/\u003cstamp>-fix-\u003capi>-pp-cli-build-log.md","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"text"},"content":[{"text":"Manifest transcendence rows: \u003cplanned> planned, 0 built. Phase 3 will not pass until all \u003cplanned> ship.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use only rows that Phase 3 is expected to build: include approved transcendence rows with concrete ","type":"text"},{"text":"Command","type":"text","marks":[{"type":"code_inline"}]},{"text":" values, exclude rows whose implementation starts with ","type":"text"},{"text":"(stub)","type":"text","marks":[{"type":"code_inline"}]},{"text":", and keep ","type":"text"},{"text":"spec-emits","type":"text","marks":[{"type":"code_inline"}]},{"text":" rows out of the hand-code count while still tracking whether their approved command path exists. Update the build log's built count as rows are completed. If ","type":"text"},{"text":"PRIOR_SUB60_REPRINT=true","type":"text","marks":[{"type":"code_inline"}]},{"text":", this line is also the strict-gate budget: partial transcendence coverage is a hold by default.","type":"text"}]},{"type":"paragraph","content":[{"text":"macOS framework access:","type":"text","marks":[{"type":"strong"}]},{"text":" When the plan or manifest specifies macOS framework APIs (ScreenCaptureKit, CoreGraphics, CoreAudio, Vision, Shortcuts, etc.), use the Swift subprocess bridge pattern - Go shells out to ","type":"text"},{"text":"swift -e '\u003cinline script>'","type":"text","marks":[{"type":"code_inline"}]},{"text":". Swift is always available with Xcode CLT. Do NOT attempt Python+PyObjC - it requires separate installation and is unreliable across Python distributions. Reference ","type":"text"},{"text":"agent-capture-pp-cli/internal/capture/cgwindow.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the canonical example of this pattern.","type":"text"}]},{"type":"paragraph","content":[{"text":"Priority 0 (foundation):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"data layer for ALL primary entities from the manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sync/search/SQL path - this is what makes transcendence possible","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"After completing Priority 0, update the lock heartbeat:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase build-p0","type":"text"}]},{"type":"paragraph","content":[{"text":"Priority 1 (absorb - match everything):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ALL absorbed features from the Phase 1.5 manifest","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every feature from every competing tool, matched and beaten with agent-native output","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"This is NOT \"top 3-5\" - it is the FULL manifest","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Lock heartbeat rule for long priority levels:","type":"text","marks":[{"type":"strong"}]},{"text":" If Priority 1 has more than 5 features, update the lock heartbeat after every 3-5 features to prevent the 30-minute staleness threshold from triggering mid-build:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase build-p1-progress","type":"text"}]},{"type":"paragraph","content":[{"text":"Priority 2 (transcend - build what nobody else has):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ALL transcendence features from Phase 1.5","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The NOI commands that only work because everything is in SQLite","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"These are the commands that make someone say \"I need this\"","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Lock heartbeat rule for Priority 2:","type":"text","marks":[{"type":"strong"}]},{"text":" Same rule as Priority 1 — if Priority 2 has more than 3 transcendence features, update the heartbeat after every 2-3 features:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase build-p2-progress","type":"text"}]},{"type":"paragraph","content":[{"text":"After completing Priority 2, update the lock heartbeat:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase build-p2","type":"text"}]},{"type":"paragraph","content":[{"text":"Priority 3 (polish):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skipped complex request bodies that block important commands","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"naming cleanup for ugly operationId-derived commands","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"tests for non-trivial store/workflow logic","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"enrich terse flag descriptions: review generated command flags. If any description is under 5 words or is generic spec-derived text (e.g., \"access key\", \"The player\"), improve it using the research brief. For example, change \"access key\" to \"Steam API key (get one at steamcommunity.com/dev/apikey)\". Focus on auth keys, IDs, and filter parameters.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Agent Build Checklist (per command)","type":"text"}]},{"type":"paragraph","content":[{"text":"After building each command in Priority 1 and Priority 2, verify these 12 principles are met. These map 1:1 to what Phase 4.9's agent readiness reviewer will check - apply them now so the review becomes a confirmation, not a catch-all.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Non-interactive","type":"text","marks":[{"type":"strong"}]},{"text":": No TTY prompts, no ","type":"text"},{"text":"bufio.Scanner(os.Stdin)","type":"text","marks":[{"type":"code_inline"}]},{"text":", works in CI without a terminal","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Structured output","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":" produces valid JSON, ","type":"text"},{"text":"--select","type":"text","marks":[{"type":"code_inline"}]},{"text":" filters fields correctly. Hand-written novel commands that build a Go-typed slice/struct and emit JSON should use the generated receiver-style helper, ","type":"text"},{"text":"flags.printJSON(cmd, v)","type":"text","marks":[{"type":"code_inline"}]},{"text":", or call ","type":"text"},{"text":"printJSONFiltered(cmd.OutOrStdout(), v, flags)","type":"text","marks":[{"type":"code_inline"}]},{"text":" directly. Both route through ","type":"text"},{"text":"printOutputWithFlags","type":"text","marks":[{"type":"code_inline"}]},{"text":", picking up ","type":"text"},{"text":"--select","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--compact","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--csv","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"--quiet","type":"text","marks":[{"type":"code_inline"}]},{"text":" for free. Verify with ","type":"text"},{"text":"\u003ccli> \u003cnovel> --json --select \u003cfield> | jq 'keys'","type":"text","marks":[{"type":"code_inline"}]},{"text":" returning only the requested fields.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Progressive help","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"--help","type":"text","marks":[{"type":"code_inline"}]},{"text":" shows realistic examples with domain-specific values (not \"abc123\"). ","type":"text"},{"text":"Use ","type":"text","marks":[{"type":"strong"}]},{"text":"Example: strings.Trim(\\","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"...`, \"","type":"text","marks":[{"type":"strong"}]},{"type":"br","marks":[{"type":"strong"}]},{"text":"\")","type":"text","marks":[{"type":"strong"}]},{"text":"(preserves leading 2-space indent) NOT","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"strings.TrimSpace(`...`)` (strips it).","type":"text","marks":[{"type":"strong"}]},{"text":" TrimSpace makes the first example line unindented; dogfood's example-detection parser is tolerant of this in current versions, but the indented form renders correctly across every Cobra version and is the convention used by every generated command.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Actionable errors","type":"text","marks":[{"type":"strong"}]},{"text":": Error messages name the specific flag/arg that's wrong and the correct usage","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Safe retries","type":"text","marks":[{"type":"strong"}]},{"text":": Mutation commands support ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":", idempotent where possible","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Composability","type":"text","marks":[{"type":"strong"}]},{"text":": Exit codes are typed (0/2/3/4/5/7/10 as applicable), output pipes to ","type":"text"},{"text":"jq","type":"text","marks":[{"type":"code_inline"}]},{"text":" cleanly","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Bounded responses","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"--compact","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns only high-gravity fields, list commands have ","type":"text"},{"text":"--limit","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verify-friendly RunE","type":"text","marks":[{"type":"strong"}]},{"text":": Hand-written commands MUST NOT use ","type":"text"},{"text":"Args: cobra.MinimumNArgs(N)","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"MarkFlagRequired(...)","type":"text","marks":[{"type":"code_inline"}]},{"text":". Cobra evaluates both before RunE runs, so a ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" guard inside RunE cannot reach if those gates fail. Verify probes commands with ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" and expects exit 0; commands with hard arg/flag gates fail those probes. Instead: validate inside RunE, fall through to ","type":"text"},{"text":"cmd.Help()","type":"text","marks":[{"type":"code_inline"}]},{"text":" only for unambiguous help-only invocations (no args and no flags), short-circuit on ","type":"text"},{"text":"dryRunOK(flags)","type":"text","marks":[{"type":"code_inline"}]},{"text":" before any IO, and return ","type":"text"},{"text":"usageErr(...)","type":"text","marks":[{"type":"code_inline"}]},{"text":" with exit 2 when required input is missing in real mode.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use string for \"positional OR flag\" commands","type":"text","marks":[{"type":"strong"}]},{"text":": when a command accepts a positional ","type":"text"},{"text":"\u003cx>","type":"text","marks":[{"type":"code_inline"}]},{"text":" OR a flag ","type":"text"},{"text":"--y","type":"text","marks":[{"type":"code_inline"}]},{"text":" as alternatives (e.g., ","type":"text"},{"text":"snapshot \u003cco>","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"snapshot --domain example.com","type":"text","marks":[{"type":"code_inline"}]},{"text":"), declare ","type":"text"},{"text":"Use: \"\u003ccmd> [x]\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"square brackets","type":"text","marks":[{"type":"strong"}]},{"text":" (optional), not ","type":"text"},{"text":"\u003cx>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (required). Validate \"exactly one of x or --y\" inside RunE. Required positionals declared with angle brackets break verify-skill recipes that use the flag-only form.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Declare verifier fixture inputs when generic values are not enough","type":"text","marks":[{"type":"strong"}]},{"text":": if the command needs realistic positional values or required flags to pass the verifier's happy path, add ","type":"text"},{"text":"Annotations: map[string]string{\"pp:happy-args\": \"\u003citem>=example-id;--query=example\"}","type":"text","marks":[{"type":"code_inline"}]},{"text":" or assign a whole initialized ","type":"text"},{"text":"cmd.Annotations","type":"text","marks":[{"type":"code_inline"}]},{"text":" map after construction. The verifier consumes semicolon-separated tokens in order: ","type":"text"},{"text":"\u003clabel>=value","type":"text","marks":[{"type":"code_inline"}]},{"text":" tokens overlay synthesized positional args, and ","type":"text"},{"text":"--flag=value","type":"text","marks":[{"type":"code_inline"}]},{"text":" tokens overlay or add flag/value pairs. Commands without the annotation keep the generic synthesized inputs.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Side-effect commands stay quiet under verify","type":"text","marks":[{"type":"strong"}]},{"text":": Any hand-written command that performs a visible side effect (opens a browser tab, sends a notification, plays audio, dials out to an OS handler) MUST follow both halves of the convention:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Print by default; opt in to the action.","type":"text","marks":[{"type":"strong"}]},{"text":" The default behavior prints what would happen (","type":"text"},{"text":"would launch: \u003curl>","type":"text","marks":[{"type":"code_inline"}]},{"text":"); a flag like ","type":"text"},{"text":"--launch","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--send","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--play","type":"text","marks":[{"type":"code_inline"}]},{"text":" is required to actually do it. food52's ","type":"text"},{"text":"open","type":"text","marks":[{"type":"code_inline"}]},{"text":" command is the reference shape — see ","type":"text"},{"text":"internal/cli/open.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" after retro #337.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Short-circuit when ","type":"text","marks":[{"type":"strong"}]},{"text":"cliutil.IsVerifyEnv()","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" returns true.","type":"text","marks":[{"type":"strong"}]},{"text":" The Printing Press verifier sets ","type":"text"},{"text":"PRINTING_PRESS_VERIFY=1","type":"text","marks":[{"type":"code_inline"}]},{"text":" in every mock-mode subprocess; commands that ignore it can spam the user's environment during a verify pass even with the print-by-default flag pattern. The helper is generated into every CLI's ","type":"text"},{"text":"internal/cliutil/verifyenv.go","type":"text","marks":[{"type":"code_inline"}]},{"text":". Pattern:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"if cliutil.IsVerifyEnv() {\n fmt.Fprintln(cmd.OutOrStdout(), \"would launch:\", url)\n return nil\n}","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"This is defense-in-depth: the verifier also runs a heuristic side-effect classifier, but it can miss commands whose ","type":"text"},{"text":"--help","type":"text","marks":[{"type":"code_inline"}]},{"text":" text and source don't match the heuristics. The env-var check is the floor.","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Long-running commands curtail work under live-dogfood.","type":"text","marks":[{"type":"strong"}]},{"text":" Any hand-written command whose happy path is an expensive network operation (full sync loops, content crawlers, bulk archive walks) MUST check ","type":"text"},{"text":"cliutil.IsDogfoodEnv()","type":"text","marks":[{"type":"code_inline"}]},{"text":" and curtail work to fit inside the matrix's flat 30s per-command timeout. ","type":"text"},{"text":"cli-printing-press dogfood --live","type":"text","marks":[{"type":"code_inline"}]},{"text":" sets ","type":"text"},{"text":"PRINTING_PRESS_DOGFOOD=1","type":"text","marks":[{"type":"code_inline"}]},{"text":" in every subprocess. Pattern:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"if cliutil.IsDogfoodEnv() {\n return crawl(ctx, opts.WithMaxPages(1))\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Distinct from ","type":"text"},{"text":"IsVerifyEnv","type":"text","marks":[{"type":"code_inline"}]},{"text":": dogfood is a real-API matrix, so curtail work (paginate once, smaller ","type":"text"},{"text":"--limit","type":"text","marks":[{"type":"code_inline"}]},{"text":"), never substitute mock data for real calls.","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Per-source rate limiting","type":"text","marks":[{"type":"strong"}]},{"text":": any hand-written client in a sibling internal package (","type":"text"},{"text":"internal/source/\u003cname>/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/recipes/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/phgraphql/","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc. — anything not generator-emitted) that makes outbound HTTP calls MUST use ","type":"text"},{"text":"cliutil.AdaptiveLimiter","type":"text","marks":[{"type":"code_inline"}]},{"text":" and surface ","type":"text"},{"text":"*cliutil.RateLimitError","type":"text","marks":[{"type":"code_inline"}]},{"text":" when 429 retries are exhausted. Empty-on-throttle is indistinguishable from \"no data exists\" and silently corrupts downstream queries. Read ","type":"text"},{"text":"references/per-source-rate-limiting.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/per-source-rate-limiting.md","title":null}}]},{"text":" when authoring a sibling client. Enforced at generation time by dogfood's ","type":"text"},{"text":"source_client_check","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Parallel-fetch partial failures","type":"text","marks":[{"type":"strong"}]},{"text":": any command that fans out N API calls and computes an aggregate (averages, rollups, comparisons, cross-source merges, digest summaries) MUST preserve each fetch error through the result channel and exclude error-tagged entries from totals and denominators. Failed fetches may still appear in the response so the caller can see the gap, but they must not become zero-valued phantom rows that dilute averages or counts. Surface the partial failure explicitly with:","type":"text"}]}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a stderr warning that names the failed count and the actual aggregation denominator, for example ","type":"text"},{"text":"warning: 2 of 10 fetches failed; averages computed over the remaining 8 items","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a ","type":"text"},{"text":"fetch_failures","type":"text","marks":[{"type":"code_inline"}]},{"text":" field in the JSON response envelope listing the failed entries and error messages","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Silently averaging phantom zeros is worse than reporting a partial result. 12. ","type":"text"},{"text":"Scan-and-filter caps","type":"text","marks":[{"type":"strong"}]},{"text":": any hand-written transcendence command that scans a paginated or otherwise unsorted endpoint, filters locally, and then keeps matching rows MUST bound scan effort separately from output size. This is the \"list, filter locally, fan out to detail\" shape: the API cannot filter on the dimension the command needs, so the command pages through broad results and applies the real predicate in Go. ","type":"text"},{"text":"--limit","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not enough because it bounds matches kept, not records scanned.","type":"text"}]},{"type":"paragraph","content":[{"text":"Required elements for every scan-and-filter command:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"--max-scan-pages int","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":", or a unit-specific equivalent such as ","type":"text"},{"text":"--max-scan-batches","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--max-scan-records","type":"text","marks":[{"type":"code_inline"}]},{"text":", with a conservative default. Five pages is a reasonable starting point for typical paginated APIs (~250 records at 50/page). Lower it under ","type":"text"},{"text":"cliutil.IsDogfoodEnv()","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the happy path would otherwise risk the live-dogfood 30s timeout.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scanned_\u003cunit>","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in the JSON envelope","type":"text","marks":[{"type":"strong"}]},{"text":", for example ","type":"text"},{"text":"scanned_orders","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"scanned_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":", so downstream agents can tell whether an empty result examined 20 records or 2,000.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"note","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in zero-match JSON output","type":"text","marks":[{"type":"strong"}]},{"text":", explaining that the scan cap was hit without finding a match and naming the flag that widens the search.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Clear separation between output and scan caps","type":"text","marks":[{"type":"strong"}]},{"text":": ","type":"text"},{"text":"--limit","type":"text","marks":[{"type":"code_inline"}]},{"text":" controls how many matches are returned; ","type":"text"},{"text":"--max-scan-pages","type":"text","marks":[{"type":"code_inline"}]},{"text":" controls how many list pages or records the command is allowed to examine.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Use this pattern when the endpoint ordering is unrelated to the local predicate: search-by-property over relevance-ranked search results, issues by a weakly server-filtered custom field, pull requests by reviewer from an endpoint with no reviewer filter, rental orders by date from a broad order list, and similar cases.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"type scanFilterView struct {\n\tItems []yourEntryType `json:\"items\"`\n\tScannedItems int `json:\"scanned_items\"`\n\tMaxScanPages int `json:\"max_scan_pages\"`\n\tNote string `json:\"note,omitempty\"`\n}\n\nfunc newScanFilterCmd(flags *rootFlags) *cobra.Command {\n\tvar limit int\n\tvar maxScanPages int\n\tvar status string\n\tcmd := &cobra.Command{\n\t\tUse: \"find-by-status\",\n\t\tShort: \"Find matching items by scanning the list endpoint\",\n\t\tAnnotations: map[string]string{\n\t\t\t\"mcp:read-only\": \"true\",\n\t\t},\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\tif len(args) == 0 && cmd.Flags().NFlag() == 0 {\n\t\t\t\treturn cmd.Help()\n\t\t\t}\n\t\t\tif dryRunOK(flags) {\n\t\t\t\tfmt.Fprintf(cmd.OutOrStdout(), \"would scan up to %d pages for matching items\\n\", maxScanPages)\n\t\t\t\treturn nil\n\t\t\t}\n\t\t\tif status == \"\" {\n\t\t\t\t_ = cmd.Usage()\n\t\t\t\treturn usageErr(fmt.Errorf(\"--status is required\"))\n\t\t\t}\n\t\t\tif cliutil.IsDogfoodEnv() && maxScanPages > 1 {\n\t\t\t\tmaxScanPages = 1\n\t\t\t}\n\t\t\tc, err := flags.newClient()\n\t\t\tif err != nil {\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tvar matches []yourEntryType\n\t\t\tscanned := 0\n\t\t\tscanCapHit := true\n\t\t\tfor page := 1; page \u003c= maxScanPages && len(matches) \u003c limit; page++ {\n\t\t\t\tdata, err := c.Get(\"/api/v1/items\", map[string]string{\n\t\t\t\t\t\"page\": strconv.Itoa(page),\n\t\t\t\t\t\"pageSize\": \"50\",\n\t\t\t\t})\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn fmt.Errorf(\"fetching items page %d: %w\", page, err)\n\t\t\t\t}\n\t\t\t\titems, err := parseItems(data)\n\t\t\t\tif err != nil {\n\t\t\t\t\treturn fmt.Errorf(\"parsing items page %d: %w\", page, err)\n\t\t\t\t}\n\t\t\t\tfor _, item := range items {\n\t\t\t\t\tscanned++\n\t\t\t\t\tif item.Status != status {\n\t\t\t\t\t\tcontinue\n\t\t\t\t\t}\n\t\t\t\t\tmatches = append(matches, item)\n\t\t\t\t\tif len(matches) >= limit {\n\t\t\t\t\t\tbreak\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tif len(items) == 0 {\n\t\t\t\t\tscanCapHit = false\n\t\t\t\t\tbreak\n\t\t\t\t}\n\t\t\t}\n\t\t\tview := scanFilterView{\n\t\t\t\tItems: matches,\n\t\t\t\tScannedItems: scanned,\n\t\t\t\tMaxScanPages: maxScanPages,\n\t\t\t}\n\t\t\tif len(matches) == 0 && scanCapHit {\n\t\t\t\tview.Note = fmt.Sprintf(\"scanned %d items across up to %d pages without finding status %q; raise --max-scan-pages to widen the search\", scanned, maxScanPages, status)\n\t\t\t}\n\t\t\tenc := json.NewEncoder(cmd.OutOrStdout())\n\t\t\tenc.SetIndent(\"\", \" \")\n\t\t\treturn enc.Encode(view)\n\t\t},\n\t}\n\tcmd.Flags().IntVar(&limit, \"limit\", 10, \"maximum matching items to return\")\n\tcmd.Flags().IntVar(&maxScanPages, \"max-scan-pages\", 5, \"maximum list pages to scan before returning partial or empty results\")\n\tcmd.Flags().StringVar(&status, \"status\", \"\", \"status to match\")\n\treturn cmd\n}","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"Verify-friendly RunE template","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this shape for every hand-written transcendence command. The generator emits the ","type":"text"},{"text":"dryRunOK","type":"text","marks":[{"type":"code_inline"}]},{"text":" helper into ","type":"text"},{"text":"internal/cli/helpers.go","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"RunE: func(cmd *cobra.Command, args []string) error {\n if len(args) == 0 && cmd.Flags().NFlag() == 0 {\n return cmd.Help()\n }\n if dryRunOK(flags) {\n return nil\n }\n if \u003crequired input missing> {\n _ = cmd.Usage()\n return usageErr(fmt.Errorf(\"\u003cflag-or-arg> is required\"))\n }\n // ... real work ...\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Why each branch exists: the ","type":"text"},{"text":"len(args) == 0 && cmd.Flags().NFlag() == 0","type":"text","marks":[{"type":"code_inline"}]},{"text":" branch handles an interactive ","type":"text"},{"text":"\u003ccli> mycommand","type":"text","marks":[{"type":"code_inline"}]},{"text":" help-only invocation without treating help as an error. The ","type":"text"},{"text":"dryRunOK","type":"text","marks":[{"type":"code_inline"}]},{"text":" branch handles verify's ","type":"text"},{"text":"\u003ccli> mycommand \u003cfixture> --dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" probes before network or filesystem IO. The required-input branch handles non-help invocations where a mode or output flag is present (","type":"text"},{"text":"--no-input","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--agent","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":") but the required ID, query, path, or other command input is still missing. Missing required input must print usage and return ","type":"text"},{"text":"usageErr(...)","type":"text","marks":[{"type":"code_inline"}]},{"text":" so callers get exit code 2 instead of a silent rc=0 skip.","type":"text"}]},{"type":"paragraph","content":[{"text":"Multi-positional commands (N >= 2 required args) must use a two-check shape so only the bare help probe returns exit 0:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"if len(args) == 0 && cmd.Flags().NFlag() == 0 {\n\treturn cmd.Help() // bare invocation help probe\n}\nif len(args) \u003c N {\n\t_ = cmd.Usage()\n\treturn usageErr(fmt.Errorf(\"missing required positional argument\"))\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"This preserves verify-friendly help behavior for 0 args while making partial positional input (","type":"text"},{"text":"1..N-1","type":"text","marks":[{"type":"code_inline"}]},{"text":") fail with exit 2 in dogfood ","type":"text"},{"text":"error_path","type":"text","marks":[{"type":"code_inline"}]},{"text":". Single-positional commands can keep the single required-input check. If a multi-positional command supports ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":", place its ","type":"text"},{"text":"dryRunOK(flags)","type":"text","marks":[{"type":"code_inline"}]},{"text":" branch after the ","type":"text"},{"text":"len(args) \u003c N","type":"text","marks":[{"type":"code_inline"}]},{"text":" gate (once all N positionals are present), so the dry-run probe still short-circuits.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not collapse the first and third branches into ","type":"text"},{"text":"if len(args) == 0 || \u003cflag empty> { return cmd.Help() }","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"cmd.Help()","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns ","type":"text"},{"text":"nil","type":"text","marks":[{"type":"code_inline"}]},{"text":", so agents and scripts cannot distinguish \"help was requested\" from \"the command skipped required work.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"For commands with no required inputs, omit the ","type":"text"},{"text":"usageErr(...)","type":"text","marks":[{"type":"code_inline"}]},{"text":" branch entirely and keep the help-only plus dry-run branches.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the command reads a file or directory (","type":"text"},{"text":"os.ReadFile","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"os.ReadDir","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"os.Stat","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"os.Open","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"os.OpenFile","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"os.Lstat","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"filepath.Walk","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"filepath.WalkDir","type":"text","marks":[{"type":"code_inline"}]},{"text":", or any other filesystem access), the read MUST come after ","type":"text"},{"text":"dryRunOK()","type":"text","marks":[{"type":"code_inline"}]},{"text":", not before. Filesystem reads before ","type":"text"},{"text":"dryRunOK()","type":"text","marks":[{"type":"code_inline"}]},{"text":" cause ","type":"text"},{"text":"validate-narrative --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" to fail with a missing-file error rather than a clean dry-run exit 0.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 3 delegation: require feature-level acceptance","type":"text"}]},{"type":"paragraph","content":[{"text":"When Phase 3 implementation is delegated to a sub-agent (via ","type":"text"},{"text":"Agent","type":"text","marks":[{"type":"code_inline"}]},{"text":" tool or Codex), the delegation prompt MUST require behavioral acceptance tests per major feature, not just \"does the command build and run.\" Agents consistently over-report success when the contract is only \"command executes without error.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Required in every Phase 3 delegation prompt:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Per-feature acceptance assertions","type":"text","marks":[{"type":"strong"}]},{"text":" that check output content, not just exit codes. Examples the prompt should make concrete:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Search/ranker: \"After ","type":"text"},{"text":"\u003ccli> goat 'brownies'","type":"text","marks":[{"type":"code_inline"}]},{"text":", assert at least 3 of the top 5 results contain 'brown' in their title or URL. If fewer, the extractor is broken.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Lookup: \"After ","type":"text"},{"text":"\u003ccli> sub buttermilk --json","type":"text","marks":[{"type":"code_inline"}]},{"text":", assert the parsed JSON is an array of objects with ","type":"text"},{"text":"substitute","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"ratio","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"context","type":"text","marks":[{"type":"code_inline"}]},{"text":" fields.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Transform: \"After ","type":"text"},{"text":"\u003ccli> recipe get \u003cknown-url> --servings 6","type":"text","marks":[{"type":"code_inline"}]},{"text":", assert the output ingredient quantities differ from the ","type":"text"},{"text":"--servings 4","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocation (scaling actually ran).\"","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Absence-of-correctness tests","type":"text","marks":[{"type":"strong"}]},{"text":" for every feature whose correct answer can be empty or complete:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Calendar/window commands: \"Given ","type":"text"},{"text":"--days N","type":"text","marks":[{"type":"code_inline"}]},{"text":", assert exactly N rows are returned, including zero-count days.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Drift/diff commands: \"Given only one snapshot or no changed values, assert the command returns ","type":"text"},{"text":"[]","type":"text","marks":[{"type":"code_inline"}]},{"text":" rather than fabricating drift.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Alert/watch commands: \"Given no matching records, assert empty output plus an honest reason, not stale or unrelated data.\"","type":"text"}]}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Negative tests","type":"text","marks":[{"type":"strong"}]},{"text":" per filter/search command: run with a deliberately-mismatching query and assert the result set does NOT contain irrelevant items.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No parent-command delegation without flags.","type":"text","marks":[{"type":"strong"}]},{"text":" If a parent command delegates to a leaf command's ","type":"text"},{"text":"RunE","type":"text","marks":[{"type":"code_inline"}]},{"text":", the parent must declare every flag the delegate accepts. Prefer group parents that show help over aliasing a parent to a child.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Structured pass/fail report","type":"text","marks":[{"type":"strong"}]},{"text":" in the agent's response (raw output of each assertion, not a summary).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"A Phase 3 delegation that reports PASS without behavioral assertions is treated as untrusted — re-run acceptance tests before accepting the result.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Search Dedup Rule","type":"text"}]},{"type":"paragraph","content":[{"text":"When building cross-entity search commands, use per-table FTS search methods individually. Do NOT combine per-table search with the generic ","type":"text"},{"text":"db.Search()","type":"text","marks":[{"type":"code_inline"}]},{"text":" — this causes duplicate results because the same entities exist in both ","type":"text"},{"text":"resources_fts","type":"text","marks":[{"type":"code_inline"}]},{"text":" and per-table FTS indexes.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Priority 1 Review Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"After completing ALL Priority 1 (absorbed) features, BEFORE starting Priority 2 (transcendence):","type":"text"}]},{"type":"paragraph","content":[{"text":"Pick 3 random commands from Priority 1. Run each with:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"\u003ccli> \u003ccommand> --help # Does it show realistic examples?\n\u003ccli> \u003ccommand> --dry-run # Does it show the request without sending?\n\u003ccli> \u003ccommand> --json # Does it produce valid JSON?","type":"text"}]},{"type":"paragraph","content":[{"text":"If any of the 3 fail, there's a systemic issue. Fix it across all commands before proceeding. This catches problems like \"--dry-run not wired\" or \"--json outputs table instead of JSON\" early, when they're cheap to fix.","type":"text"}]},{"type":"paragraph","content":[{"text":"After passing the Priority 1 Review Gate, update the lock heartbeat:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase build-p1","type":"text"}]},{"type":"paragraph","content":[{"text":"Get Priority 0 and 1 working first (the foundation and absorbed features), pass the review gate, then build Priority 2 (transcendence), then verify.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/\u003cstamp>-fix-\u003capi>-pp-cli-build-log.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Include:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"what was built","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"what was intentionally deferred","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skipped body fields that remain","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"any generator limitations found","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Phase 3 Completion Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY. Do NOT proceed to Phase 4 until this gate passes.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Before moving to shipcheck, verify the build log against the absorb manifest. Counting alone is not enough: a build that replaces an approved ","type":"text"},{"text":"keywords-data google-ads search-volume --auto-mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a self-contained wrapper ","type":"text"},{"text":"keywords volume","type":"text","marks":[{"type":"code_inline"}]},{"text":" keeps the count right while shipping a different command than what Phase 1.5 approved. The gate must verify the ","type":"text"},{"text":"specific approved command path","type":"text","marks":[{"type":"strong"}]},{"text":" for each row that declares one.","type":"text"}]},{"type":"paragraph","content":[{"text":"Sub-60 reprint strictness:","type":"text","marks":[{"type":"strong"}]},{"text":" If this run is reprinting an existing library CLI whose prior ","type":"text"},{"text":".printing-press.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" had ","type":"text"},{"text":"scorecard.steinberger.percentage \u003c 60","type":"text","marks":[{"type":"code_inline"}]},{"text":" (","type":"text"},{"text":"PRIOR_SUB60_REPRINT=true","type":"text","marks":[{"type":"code_inline"}]},{"text":" from Phase 0), partial transcendence implementation is a HOLD by default. The Phase 3 Completion Gate may not use ","type":"text"},{"text":"partial-implementation OK","type":"text","marks":[{"type":"code_inline"}]},{"text":" semantics while any shipping-scope transcendence row is missing. To override, write an explicit ","type":"text"},{"text":"partial_transcendence_override","type":"text","marks":[{"type":"code_inline"}]},{"text":" note in the build log that names each missing row, explains why it is intentionally deferred, and states that the user accepted the sub-60 reprint shipping with partial novel coverage. Without that note, any missing approved transcendence row blocks Phase 4.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Per-row Cobra resolution check.","type":"text","marks":[{"type":"strong"}]},{"text":" Read approved command paths from ","type":"text"},{"text":"$RESEARCH_DIR/\u003cstamp>-feat-\u003capi>-pp-cli-absorb-manifest.md","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every transcendence row's ","type":"text"},{"text":"Command","type":"text","marks":[{"type":"code_inline"}]},{"text":" value.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every absorbed row whose ","type":"text"},{"text":"Our Implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" value starts with ","type":"text"},{"text":"\u003capi>-pp-cli \u003cclean command path>","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every absorbed row whose ","type":"text"},{"text":"Our Implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" value starts with ","type":"text"},{"text":"(behavior in \u003capi>-pp-cli \u003ccommand path>)","type":"text","marks":[{"type":"code_inline"}]},{"text":". For these rows, first extract the text between the literal prefix ","type":"text"},{"text":"(behavior in ","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the first closing ","type":"text"},{"text":")","type":"text","marks":[{"type":"code_inline"}]},{"text":", producing ","type":"text"},{"text":"\u003capi>-pp-cli \u003ccommand path>","type":"text","marks":[{"type":"code_inline"}]},{"text":", then apply the same binary-strip and flag-strip rules to that extracted command text.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skip rows that start with ","type":"text"},{"text":"(generated endpoint)","type":"text","marks":[{"type":"code_inline"}]},{"text":" because the generator-emitted typed endpoint surface already covers those commands.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Skip rows that start with ","type":"text"},{"text":"(stub)","type":"text","marks":[{"type":"code_inline"}]},{"text":" because the Phase Gate 1.5 stub approval list is their source of truth; stubs are intentionally unresolved implementation placeholders and must not be counted as built commands.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not infer command paths from freeform prose. Any absorbed row whose ","type":"text"},{"text":"Our Implementation","type":"text","marks":[{"type":"code_inline"}]},{"text":" value does not start with ","type":"text"},{"text":"\u003capi>-pp-cli \u003cclean command path>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"(behavior in \u003capi>-pp-cli \u003ccommand path>)","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"(generated endpoint)","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"(stub)","type":"text","marks":[{"type":"code_inline"}]},{"text":" is an invalid manifest row; return to Phase 1.5 and normalize it before proceeding.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For each approved path, including command text extracted from ","type":"text"},{"text":"(behavior in \u003capi>-pp-cli \u003ccommand path>)","type":"text","marks":[{"type":"code_inline"}]},{"text":" rows, strip any leading binary name, then strip flag tokens and quoted args to get the leaf command path (drop everything from the first ","type":"text"},{"text":"-","type":"text","marks":[{"type":"code_inline"}]},{"text":" token onward; ","type":"text"},{"text":"bottleneck","type":"text","marks":[{"type":"code_inline"}]},{"text":" stays ","type":"text"},{"text":"bottleneck","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"velocity --weeks 4","type":"text","marks":[{"type":"code_inline"}]},{"text":" becomes ","type":"text"},{"text":"velocity","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"compare \"LeBron\" \"Curry\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" becomes ","type":"text"},{"text":"compare","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"keywords-data google-ads search-volume --auto-mode","type":"text","marks":[{"type":"code_inline"}]},{"text":" becomes ","type":"text"},{"text":"keywords-data google-ads search-volume","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Then run:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"./\u003capi>-pp-cli \u003cleaf path> --help","type":"text"}]},{"type":"paragraph","content":[{"text":"Assert (a) exit code 0 AND (b) the help output's ","type":"text"},{"text":"Usage:","type":"text","marks":[{"type":"code_inline"}]},{"text":" spec line is ","type":"text"},{"text":"\u003cbinary> \u003cleaf path> [flags]","type":"text","marks":[{"type":"code_inline"}]},{"text":" — i.e., the line ","type":"text"},{"text":"immediately before","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":" [flags]","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the full leaf path you requested. Cobra falls through to the parent's help when a subcommand is unknown — same exit 0, but the Usage spec line is ","type":"text"},{"text":"\u003cbinary> \u003cparent> [command]","type":"text","marks":[{"type":"code_inline"}]},{"text":" instead of ","type":"text"},{"text":"\u003cbinary> \u003cparent> \u003cleaf> [flags]","type":"text","marks":[{"type":"code_inline"}]},{"text":". The grep-able signal is ","type":"text"},{"text":"\u003cleaf> [flags]","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a real command vs ","type":"text"},{"text":"[command]","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a parent fall-through; the leaf appearing only under ","type":"text"},{"text":"Available Commands:","type":"text","marks":[{"type":"code_inline"}]},{"text":" is also a fall-through.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"HALT on any miss.","type":"text","marks":[{"type":"strong"}]},{"text":" If any approved row fails (a) or (b), STOP and name the manifest section plus row number or source line in the miss message, e.g. ","type":"text"},{"text":"Absorbed row 3: timeline did not resolve as a Cobra command","type":"text","marks":[{"type":"code_inline"}]},{"text":". Either build the approved command path now, or return to Phase 1.5 with a revised manifest for explicit re-approval per the existing \"no mid-build downgrade\" rule. Do not invent a wrapper command and silently update the manifest. Do not classify the feature as \"documentation-only\" because integration touches many files.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Deterministic backstop.","type":"text","marks":[{"type":"strong"}]},{"text":" After the per-row walk, run the same machine-checked equivalent so a manifest-vs-","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" drift cannot mask a miss:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press dogfood --dir \"$CLI_WORK_DIR\" --research-dir \"$API_RUN_DIR\" --json \\\n | jq -e '.novel_features_check | .found == .planned and (.missing // []) == [] and (.skipped // false) == false'","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"novel_features_check","type":"text","marks":[{"type":"code_inline"}]},{"text":" block reports planned/found/missing against ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":"; an exit-0 here plus a clean per-row walk means both sources agree the build matches Phase 1.5 approval. ","type":"text"},{"text":"skipped: true","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" is a HALT, not a pass at this gate.","type":"text","marks":[{"type":"strong"}]},{"text":" Dogfood marks the check skipped only when ","type":"text"},{"text":"--research-dir","type":"text","marks":[{"type":"code_inline"}]},{"text":" is missing or ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" has no ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" key — both conditions mean the gate has no source of truth to verify against, which is exactly the silent-bypass path the gate was designed to prevent. If you reach this gate with no ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" in ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" but the absorb manifest lists transcendence rows, re-derive ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" from the manifest (per Step 1.5e) before re-running. If ","type":"text"},{"text":"dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":" reports missing features that the manifest still lists, either ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" was edited mid-build (re-derive it from the manifest) or the build is genuinely incomplete (return to step 1).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Test presence for pure-logic novel packages.","type":"text","marks":[{"type":"strong"}]},{"text":" Every Go package you created under ","type":"text"},{"text":"internal/","type":"text","marks":[{"type":"code_inline"}]},{"text":" for novel-feature logic (parsers, matchers, scalers, scrapers — anything that isn't command wiring) must have a ","type":"text"},{"text":"_test.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" with at least one table-driven happy-path test per exported function. ","type":"text"},{"text":"cli-printing-press dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":" surfaces violations as structural issues: pure-logic packages with zero tests fail shipcheck; packages with fewer than 3 test functions are flagged as warnings for Phase 4.85's agentic review. Trivial placeholder tests pass the file-presence check but are the wrong shape — write real assertions or the review catches you.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The check is structural — no judgment about whether each command does \"enough.\" Behavioral correctness remains dogfood's and scorecard's job in Phase 4.","type":"text"}]},{"type":"paragraph","content":[{"text":"The generator handles Priority 0 (data layer) and most of Priority 1 (absorbed API endpoints). Priority 2 (transcendence) is always hand-built — the generator does not produce these. If you skip Priority 2, the CLI ships without the features that differentiate it from every other tool.","type":"text"}]},{"type":"paragraph","content":[{"text":"Starter templates for novel commands.","type":"text","marks":[{"type":"strong"}]},{"text":" Cobra wiring is mechanical and consistent across novel features; the actual feature work lives in the RunE body. Copy the wrapper below and one of the RunE skeletons that follows, fill in the placeholders from the absorb manifest's transcendence row (","type":"text"},{"text":"Name","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Command","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Description","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"Example","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"WhyItMatters","type":"text","marks":[{"type":"code_inline"}]},{"text":"), and replace the body comments with your implementation. Dogfood, verify, and scorecard still apply to the result — the templates raise the floor without changing what shipcheck checks.","type":"text"}]},{"type":"paragraph","content":[{"text":"Helpers already emitted by the generator.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not reinvent these helpers in novel command files. They live in ","type":"text"},{"text":"internal/cli/helpers.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" after generation and are available to every hand-written command in package ","type":"text"},{"text":"cli","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"printJSONFiltered(w io.Writer, v any, flags *rootFlags) error","type":"text","marks":[{"type":"code_inline"}]},{"text":" - apply ","type":"text"},{"text":"--select","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--compact","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--csv","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"--quiet","type":"text","marks":[{"type":"code_inline"}]},{"text":" while writing JSON from a Go value.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"printAutoTable(w io.Writer, items []map[string]any) error","type":"text","marks":[{"type":"code_inline"}]},{"text":" - render JSON-like rows as the generated human table format.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"defaultDBPath(name string) string","type":"text","marks":[{"type":"code_inline"}]},{"text":" - resolve the local SQLite database path for ","type":"text"},{"text":"\u003cname>","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dryRunOK(flags *rootFlags) bool","type":"text","marks":[{"type":"code_inline"}]},{"text":" - detect verify-friendly ","type":"text"},{"text":"--dry-run","type":"text","marks":[{"type":"code_inline"}]},{"text":" short-circuits before network, store, or filesystem work.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"filterFields(data json.RawMessage, fields string) json.RawMessage","type":"text","marks":[{"type":"code_inline"}]},{"text":" - apply ","type":"text"},{"text":"--select","type":"text","marks":[{"type":"code_inline"}]},{"text":" to a JSON blob.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"compactFields(data json.RawMessage) json.RawMessage","type":"text","marks":[{"type":"code_inline"}]},{"text":" - apply ","type":"text"},{"text":"--compact","type":"text","marks":[{"type":"code_inline"}]},{"text":" to a JSON blob.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"isTerminal(w io.Writer) bool","type":"text","marks":[{"type":"code_inline"}]},{"text":" - detect terminal output versus pipes.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"wantsHumanTable(w io.Writer, flags *rootFlags) bool","type":"text","marks":[{"type":"code_inline"}]},{"text":" - detect when output should use the generated human table instead of machine JSON.","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"// internal/cli/\u003ccommand>.go — replace \u003ccommand> with the kebab leaf\n// of NovelFeature.Command (e.g., \"issues stale\" → \"issues_stale.go\").\npackage cli\n\nimport (\n\t\"github.com/spf13/cobra\"\n\t// add: \"encoding/json\", \"fmt\", \"\u003cmodule>/internal/store\", etc. as needed\n)\n\nfunc newXxxCmd(flags *rootFlags) *cobra.Command {\n\tcmd := &cobra.Command{\n\t\tUse: \"\u003cleaf-of-Command>\", // e.g. \"stale\" for \"issues stale\"\n\t\tShort: \"\u003cNovelFeature.Description, one line>\", // truncate to ~70 chars\n\t\tLong: \"\u003coptional: manifest Long Description, or Description + WhyItMatters>\", // omit if Short is enough\n\t\tExample: \" \u003ccli>-pp-cli \u003cCommand> --json\", // from NovelFeature.Example\n\t\tAnnotations: map[string]string{\n\t\t\t// Set \"mcp:read-only\": \"true\" only when the command does NOT mutate\n\t\t\t// external state (lookups, comparisons, aggregations, render views).\n\t\t\t// Omit the whole map for commands that mutate (post, delete, write file).\n\t\t\t\"mcp:read-only\": \"true\",\n\t\t},\n\t\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\t\t// Pick the matching RunE skeleton below (API-call or store-query),\n\t\t\t// then implement the feature-specific path/query/parsing/formatting.\n\t\t\treturn nil\n\t\t},\n\t}\n\t// cmd.Flags().StringVar(...) — add flags from the planned --flag list, if any\n\treturn cmd\n}\n\n// Multi-word Commands like \"issues stale\": this constructor is registered as\n// a child of the matching spec-resource parent (newIssuesCmd) — wire the\n// AddCommand call inside root.go via local-variable capture:\n// issuesCmd := newIssuesCmd(flags)\n// issuesCmd.AddCommand(newIssuesStaleCmd(flags))\n// rootCmd.AddCommand(issuesCmd)\n// Leaf commands must declare every non-root flag used in their examples.\n// Use kebab-case flag names, such as --max-age instead of --maxAge, so the\n// generated CLI convention and verify-skill flag scanner stay aligned.\n// Do not rely on parent-local flags like --org or --project being accepted by\n// child commands unless the parent registered them with PersistentFlags().\n// Single-word Commands register directly: rootCmd.AddCommand(newXxxCmd(flags)).","type":"text"}]},{"type":"paragraph","content":[{"text":"RunE skeleton — API-call shape","type":"text","marks":[{"type":"strong"}]},{"text":" (live data via the generated client):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"RunE: func(cmd *cobra.Command, args []string) error {\n\tif len(args) == 0 && cmd.Flags().NFlag() == 0 {\n\t\treturn cmd.Help()\n\t}\n\tif dryRunOK(flags) {\n\t\tfmt.Fprintln(cmd.OutOrStdout(), \"would fetch \u003cresource>\")\n\t\treturn nil\n\t}\n\tif \u003crequired input missing> {\n\t\t_ = cmd.Usage()\n\t\treturn usageErr(fmt.Errorf(\"\u003cflag-or-arg> is required\"))\n\t}\n\tc, err := flags.newClient()\n\tif err != nil {\n\t\treturn err\n\t}\n\t// Replace path with the absorbed endpoint or hand-rolled URL. Use\n\t// cliutil.FanoutRun for any --site/--source/--region CSV fan-out;\n\t// re-implementing fanout inline is the recipe-goat silent-drop bug.\n\tdata, err := c.Get(\"/api/v1/path\", nil)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"fetching \u003cresource>: %w\", err)\n\t}\n\t// If the API returns CSV (`response_format: csv` in any spec endpoint),\n\t// wrap raw client data with cliutil.ParseCSV(data) before embedding it in a JSON envelope.\n\t// Parse data into your feature's view. Use cliutil.CleanText for any\n\t// text extracted from HTML or schema.org JSON-LD; re-implementing\n\t// HTML-entity unescape inline is the ' bug class.\n\tvar view yourViewType // = parse(data)\n\tif flags.asJSON || (!isTerminal(cmd.OutOrStdout()) && !humanFriendly) {\n\t\tenc := json.NewEncoder(cmd.OutOrStdout())\n\t\tenc.SetIndent(\"\", \" \")\n\t\treturn enc.Encode(view)\n\t}\n\t// Human/terminal output (table or pretty print).\n\treturn nil\n},","type":"text"}]},{"type":"paragraph","content":[{"text":"RunE skeleton — parallel-fetch aggregation shape","type":"text","marks":[{"type":"strong"}]},{"text":" (live fan-out with partial-failure accounting):","type":"text"}]},{"type":"paragraph","content":[{"text":"Use this shape when a novel command fetches multiple items concurrently and computes a rollup, average, comparison, digest, or cross-source merge. The key invariant is that ","type":"text"},{"text":"err","type":"text","marks":[{"type":"code_inline"}]},{"text":" travels with each result until aggregation, and error-tagged entries are excluded from all totals and denominators.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"RunE: func(cmd *cobra.Command, args []string) error {\n\tif len(args) == 0 && cmd.Flags().NFlag() == 0 {\n\t\treturn cmd.Help()\n\t}\n\tif dryRunOK(flags) {\n\t\tfmt.Fprintln(cmd.OutOrStdout(), \"would fetch \u003cresource> details\")\n\t\treturn nil\n\t}\n\tif \u003crequired input missing> {\n\t\t_ = cmd.Usage()\n\t\treturn usageErr(fmt.Errorf(\"\u003cflag-or-arg> is required\"))\n\t}\n\tc, err := flags.newClient()\n\tif err != nil {\n\t\treturn err\n\t}\n\ttype fetchResult struct {\n\t\tidx int\n\t\tid string\n\t\tentry yourEntryType\n\t\terr error\n\t}\n\tids := []string{} // derive from args, flags, or an initial list endpoint\n\tresults := make(chan fetchResult, len(ids))\n\tvar wg sync.WaitGroup\n\tfor idx, id := range ids {\n\t\twg.Add(1)\n\t\tgo func() {\n\t\t\tdefer wg.Done()\n\t\t\tdata, err := c.Get(\"/api/v1/resource/\"+url.PathEscape(id), nil)\n\t\t\tif err != nil {\n\t\t\t\tresults \u003c- fetchResult{idx: idx, id: id, err: err}\n\t\t\t\treturn\n\t\t\t}\n\t\t\tentry, err := parseEntry(data)\n\t\t\tresults \u003c- fetchResult{idx: idx, id: id, entry: entry, err: err}\n\t\t}()\n\t}\n\tgo func() {\n\t\twg.Wait()\n\t\tclose(results)\n\t}()\n\tordered := make([]yourEntryType, len(ids))\n\tfetchErrors := make([]error, len(ids))\n\tfor r := range results {\n\t\tordered[r.idx] = r.entry\n\t\tif r.err != nil {\n\t\t\tfetchErrors[r.idx] = r.err\n\t\t}\n\t}\n\tfailures := make([]fetchFailure, 0) // empty marshals as [] not null\n\tsuccessfulItems := make([]yourEntryType, 0) // empty marshals as [] not null\n\tvar total float64\n\tvar denominator int\n\tfor idx, entry := range ordered {\n\t\tif fetchErrors[idx] != nil {\n\t\t\tfailures = append(failures, fetchFailure{\n\t\t\t\tID: ids[idx],\n\t\t\t\tError: fetchErrors[idx].Error(),\n\t\t\t})\n\t\t\tcontinue\n\t\t}\n\t\tsuccessfulItems = append(successfulItems, entry)\n\t\ttotal += entry.Metric\n\t\tdenominator++\n\t}\n\tif len(failures) > 0 {\n\t\tfmt.Fprintf(cmd.ErrOrStderr(), \"warning: %d of %d fetches failed; averages computed over the remaining %d items\\n\", len(failures), len(ids), denominator)\n\t}\n\tview := yourAggregateView{\n\t\tItems: successfulItems,\n\t\tAverageMetric: safeAverage(total, denominator),\n\t\tFetchFailures: failures, // json tag: `json:\"fetch_failures,omitempty\"`\n\t}\n\tif flags.asJSON || (!isTerminal(cmd.OutOrStdout()) && !humanFriendly) {\n\t\tenc := json.NewEncoder(cmd.OutOrStdout())\n\t\tenc.SetIndent(\"\", \" \")\n\t\treturn enc.Encode(view)\n\t}\n\t// Human/terminal output, including a visible partial-failure note.\n\tfor _, entry := range view.Items {\n\t\tfmt.Fprintf(cmd.OutOrStdout(), \"%s\\t%.2f\\n\", entry.Name, entry.Metric)\n\t}\n\tif len(failures) > 0 {\n\t\tfmt.Fprintf(cmd.OutOrStdout(), \"\\npartial results: %d of %d fetches failed; average computed over %d items\\n\", len(failures), len(ids), denominator)\n\t}\n\treturn nil\n},","type":"text"}]},{"type":"paragraph","content":[{"text":"RunE skeleton — store-query shape","type":"text","marks":[{"type":"strong"}]},{"text":" (offline data via the local SQLite):","type":"text"}]},{"type":"paragraph","content":[{"text":"The generic ","type":"text"},{"text":"resources","type":"text","marks":[{"type":"code_inline"}]},{"text":" table is keyed by ","type":"text"},{"text":"resource_type","type":"text","marks":[{"type":"code_inline"}]},{"text":". Flat resources synced from ","type":"text"},{"text":"/\u003cresource>","type":"text","marks":[{"type":"code_inline"}]},{"text":" land as ","type":"text"},{"text":"resource_type='\u003cresource>'","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"Hierarchical resources","type":"text","marks":[{"type":"strong"}]},{"text":" synced from ","type":"text"},{"text":"/\u003cparents>/{id}/\u003cresource>","type":"text","marks":[{"type":"code_inline"}]},{"text":" land as ","type":"text"},{"text":"resource_type='\u003cparent>_\u003cresource>'","type":"text","marks":[{"type":"code_inline"}]},{"text":" — e.g., ","type":"text"},{"text":"projects_tasks","type":"text","marks":[{"type":"code_inline"}]},{"text":" (Asana), ","type":"text"},{"text":"repos_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"repos_pulls","type":"text","marks":[{"type":"code_inline"}]},{"text":" (GitHub) — ","type":"text"},{"text":"not","type":"text","marks":[{"type":"em"}]},{"text":" the bare ","type":"text"},{"text":"\u003cresource>","type":"text","marks":[{"type":"code_inline"}]},{"text":" name. A novel feature that filters by the bare name returns zero rows against a real DB. Use ","type":"text"},{"text":"IN (...)","type":"text","marks":[{"type":"code_inline"}]},{"text":" to catch both shapes so the same code works whether the API exposes the resource flat or only parent-scoped.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"// Declare these alongside the cmd literal, before return cmd:\n// var dbPath string\n// cmd.Flags().StringVar(&dbPath, \"db\", \"\", \"Database path\")\n\nRunE: func(cmd *cobra.Command, args []string) error {\n\tif len(args) == 0 && cmd.Flags().NFlag() == 0 {\n\t\treturn cmd.Help()\n\t}\n\tif dryRunOK(flags) {\n\t\tfmt.Fprintln(cmd.OutOrStdout(), \"would query local store\")\n\t\treturn nil\n\t}\n\tif \u003crequired input missing> {\n\t\t_ = cmd.Usage()\n\t\treturn usageErr(fmt.Errorf(\"\u003cflag-or-arg> is required\"))\n\t}\n\tif dbPath == \"\" {\n\t\tdbPath = defaultDBPath(\"\u003ccli>-pp-cli\") // replace \u003ccli> with the API slug\n\t}\n\tdb, err := store.OpenWithContext(cmd.Context(), dbPath)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"opening database: %w\", err)\n\t}\n\tdefer db.Close()\n\t// Filter resources by both the flat and hierarchical naming so the\n\t// query catches rows synced via /\u003cresource> AND rows synced via\n\t// /\u003cparents>/{id}/\u003cchildren>. Drop the parent-scoped entry if the\n\t// API only exposes the resource flat; add a \u003cresource_singular>\n\t// entry for APIs that toggle plural/singular casing. SQL must be\n\t// SELECT-only; the search/sql gates reject mutating statements.\n\trows, err := db.DB().QueryContext(cmd.Context(), `\n\t\tSELECT id, data FROM resources\n\t\tWHERE resource_type IN ('\u003cresource>', '\u003cparent>_\u003cresource>')\n\t\t AND ...`)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"query: %w\", err)\n\t}\n\tdefer rows.Close()\n\t// Scan each row. id/data on the resources table are NOT NULL so bare\n\t// strings are safe; ANY optional field selected via json_extract or\n\t// pulled from a typed FTS/upsert table can be NULL — use sql.Null*\n\t// scan targets (or COALESCE in the SQL) for those, see the NULL-safe\n\t// scans paragraph below.\n\tresults := make([]yourRowType, 0) // scan rows into this slice; make([]T, 0) keeps empty JSON as [] not null\n\t// (loop over rows here: results = append(results, scannedRow))\n\tif flags.asJSON || (!isTerminal(cmd.OutOrStdout()) && !humanFriendly) {\n\t\tenc := json.NewEncoder(cmd.OutOrStdout())\n\t\tenc.SetIndent(\"\", \" \")\n\t\treturn enc.Encode(results)\n\t}\n\t// Human/terminal output.\n\treturn nil\n},","type":"text"}]},{"type":"paragraph","content":[{"text":"For flat-only resources, the typed FTS/upsert tables the generator emits (e.g., ","type":"text"},{"text":"tasks_fts","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"projects","type":"text","marks":[{"type":"code_inline"}]},{"text":") work too — ","type":"text"},{"text":"SELECT id, data FROM \u003ctyped-table>","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the fast path. The ","type":"text"},{"text":"IN (...)","type":"text","marks":[{"type":"code_inline"}]},{"text":" pattern above is the safe default whenever the resource may be hierarchical; ","type":"text"},{"text":"cli-printing-press dogfood --json","type":"text","marks":[{"type":"code_inline"}]},{"text":" shows the actual ","type":"text"},{"text":"resource_type","type":"text","marks":[{"type":"code_inline"}]},{"text":" distribution so you can confirm without running raw SQL.","type":"text"}]},{"type":"paragraph","content":[{"text":"For features that combine both (cache an API response in the store, or fall through to live when the local store is stale), nest one skeleton inside the other and use the ","type":"text"},{"text":"--data-source auto/local/live","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag pattern from the generated ","type":"text"},{"text":"sync","type":"text","marks":[{"type":"code_inline"}]},{"text":" command.","type":"text"}]},{"type":"paragraph","content":[{"text":"Shared helpers available to novel code:","type":"text","marks":[{"type":"strong"}]},{"text":" The generator emits ","type":"text"},{"text":"internal/cliutil/","type":"text","marks":[{"type":"code_inline"}]},{"text":" in every CLI. When authoring novel commands, prefer ","type":"text"},{"text":"cliutil.FanoutRun","type":"text","marks":[{"type":"code_inline"}]},{"text":" for any aggregation command (any ","type":"text"},{"text":"--site","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"--source","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"--region","type":"text","marks":[{"type":"code_inline"}]},{"text":" CSV fan-out) and ","type":"text"},{"text":"cliutil.CleanText","type":"text","marks":[{"type":"code_inline"}]},{"text":" for any text extracted from HTML or schema.org JSON-LD. Re-implementing these inline is how recipe-goat's trending silent-drop and ","type":"text"},{"text":"'","type":"text","marks":[{"type":"code_inline"}]},{"text":" entity bugs shipped.","type":"text"}]},{"type":"paragraph","content":[{"text":"Hand-coded duration flags MUST use ","type":"text","marks":[{"type":"strong"}]},{"text":"cliutil.ParseDurationLoose","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" with a ","type":"text","marks":[{"type":"strong"}]},{"text":"StringVar","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" flag (not ","type":"text","marks":[{"type":"strong"}]},{"text":"DurationVar","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":").","type":"text","marks":[{"type":"strong"}]},{"text":" Go's ","type":"text"},{"text":"time.ParseDuration","type":"text","marks":[{"type":"code_inline"}]},{"text":" rejects the ","type":"text"},{"text":"7d","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"30d","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"1w","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"4w","type":"text","marks":[{"type":"code_inline"}]},{"text":" day/week shorthand that the framework's ","type":"text"},{"text":"sync --since","type":"text","marks":[{"type":"code_inline"}]},{"text":" already accepts, so a ","type":"text"},{"text":"DurationVar","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag fails at runtime on input agents and users reasonably expect. Declare the flag as a ","type":"text"},{"text":"StringVar","type":"text","marks":[{"type":"code_inline"}]},{"text":", then post-parse with ","type":"text"},{"text":"cliutil.ParseDurationLoose","type":"text","marks":[{"type":"code_inline"}]},{"text":", which adds ","type":"text"},{"text":"d","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"w","type":"text","marks":[{"type":"code_inline"}]},{"text":" suffix support and otherwise defers to ","type":"text"},{"text":"time.ParseDuration","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"OData v3 datetime fields MUST be decoded with ","type":"text","marks":[{"type":"strong"}]},{"text":"cliutil.ParseODataDate","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" OData v3 APIs (Exact Online, Microsoft Dynamics 365 Business Central, Dynamics NAV) return dates as ","type":"text"},{"text":"/Date(1715731200000)/","type":"text","marks":[{"type":"code_inline"}]},{"text":" string literals that no standard parser accepts, so the raw value passes straight through to JSON output and agents cannot parse ","type":"text"},{"text":"created_at","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"due_date","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"cliutil.ParseODataDate(s) (time.Time, bool)","type":"text","marks":[{"type":"code_inline"}]},{"text":" decodes the literal to a UTC ","type":"text"},{"text":"time.Time","type":"text","marks":[{"type":"code_inline"}]},{"text":" and falls back to RFC3339, so callers need not dispatch on format. Re-implementing this inline per command is how the same regex ships inconsistently across OData CLIs.","type":"text"}]},{"type":"paragraph","content":[{"text":"Streaming frame normalizers MUST use ","type":"text","marks":[{"type":"strong"}]},{"text":"cliutil.ExtractNumber","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" / ","type":"text","marks":[{"type":"strong"}]},{"text":"cliutil.ExtractInt","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" rather than raw ","type":"text","marks":[{"type":"strong"}]},{"text":"float64","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":"/","type":"text","marks":[{"type":"strong"}]},{"text":"int64","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" struct fields.","type":"text","marks":[{"type":"strong"}]},{"text":" Real-world WebSocket and streaming JSON feeds (Binance, Coinbase, Kraken, Stripe ","type":"text"},{"text":"*_decimal","type":"text","marks":[{"type":"code_inline"}]},{"text":", vendor-specific market-data feeds) commonly encode numeric values as JSON-encoded strings (","type":"text"},{"text":"\"price\":\"1.91\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"). ","type":"text"},{"text":"json.Unmarshal","type":"text","marks":[{"type":"code_inline"}]},{"text":" of a JSON string into a ","type":"text"},{"text":"float64","type":"text","marks":[{"type":"code_inline"}]},{"text":" field returns no error and silently leaves the field at 0; combined with NULL-on-zero patterns this discards the entire numeric feed with no error signal anywhere in the pipeline. The helpers accept both shapes (JSON number or JSON-encoded string), report ","type":"text"},{"text":"ok=false","type":"text","marks":[{"type":"code_inline"}]},{"text":" on missing/null/unparseable, and are the canonical extraction path for ","type":"text"},{"text":"map[string]json.RawMessage","type":"text","marks":[{"type":"code_inline"}]},{"text":" decoders. Re-implementing this inline as a ","type":"text"},{"text":"float64","type":"text","marks":[{"type":"code_inline"}]},{"text":" struct field is the silent-aggregation-failure bug class.","type":"text"}]},{"type":"paragraph","content":[{"text":"WebSocket-primary APIs SHOULD declare ","type":"text","marks":[{"type":"strong"}]},{"text":"streaming:","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" and use the generated live scaffold.","type":"text","marks":[{"type":"strong"}]},{"text":" When the API's facts arrive over WebSocket and REST supplies metadata, follow ","type":"text"},{"text":"references/ws-primary-pattern.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not reimplement dial/subscribe/reconnect, newline-delimited JSON splitting, metadata status polling, or rebase-log writes in novel code unless the API genuinely breaks the generated lifecycle contract.","type":"text"}]},{"type":"paragraph","content":[{"text":"NULL-safe SQL scans MUST use ","type":"text","marks":[{"type":"strong"}]},{"text":"sql.Null*","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" scan targets (or ","type":"text","marks":[{"type":"strong"}]},{"text":"COALESCE(\u003ccol>, \u003czero>)","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in the query) for any column that can be NULL.","type":"text","marks":[{"type":"strong"}]},{"text":" SQLite returns NULL for any absent JSON field selected via ","type":"text"},{"text":"json_extract(data, '$.optional_field')","type":"text","marks":[{"type":"code_inline"}]},{"text":", for any nullable column in a typed FTS/upsert table the generator emits, and for any field the API omits from a particular response. ","type":"text"},{"text":"database/sql","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s ","type":"text"},{"text":"rows.Scan","type":"text","marks":[{"type":"code_inline"}]},{"text":" into a bare ","type":"text"},{"text":"string","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"int64","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"float64","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns a non-nil error on NULL (","type":"text"},{"text":"Scan error on column index N: converting NULL to string is unsupported","type":"text","marks":[{"type":"code_inline"}]},{"text":") — and the surrounding ","type":"text"},{"text":"for rows.Next()","type":"text","marks":[{"type":"code_inline"}]},{"text":" loop typically ","type":"text"},{"text":"continue","type":"text","marks":[{"type":"code_inline"}]},{"text":"s on scan error, silently dropping every row. The result: queries return zero records, no error reaches the caller, the feature looks healthy because the API call succeeded. Use ","type":"text"},{"text":"var v sql.NullString","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"NullInt64","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"NullFloat64","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"NullTime","type":"text","marks":[{"type":"code_inline"}]},{"text":") as the scan target and copy ","type":"text"},{"text":".String","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":".Int64","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":".Float64","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":".Time","type":"text","marks":[{"type":"code_inline"}]},{"text":" into your row struct, accepting the zero value as the missing-field representation. Re-implementing this inline as bare-string scans is the silent-row-drop bug class.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"go"},"content":[{"text":"// Wrong — every NULL column kills the row.\nvar name string\nif err := rows.Scan(&id, &name); err != nil { continue }\n\n// Right — NULL becomes the zero value, no row is lost.\nvar name sql.NullString\nif err := rows.Scan(&id, &name); err != nil { continue }\nresult.Name = name.String","type":"text"}]},{"type":"paragraph","content":[{"text":"Also right: push the default into the query so the scan target stays bare.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"sql"},"content":[{"text":"SELECT id, COALESCE(json_extract(data, '$.name'), '') FROM resources WHERE ...","type":"text"}]},{"type":"paragraph","content":[{"text":"Typed exit-code verification:","type":"text","marks":[{"type":"strong"}]},{"text":" If a novel command intentionally returns a non-zero code for a non-error control-flow result, add ","type":"text"},{"text":"cmd.Annotations[\"pp:typed-exit-codes\"] = \"0,\u003ccode>\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or the equivalent ","type":"text"},{"text":"Annotations: map[string]string{...}","type":"text","marks":[{"type":"code_inline"}]},{"text":" literal) and document the same command-specific codes in its help. Do not list the global failure palette in command help unless those exits should count as a verify pass for that command; keep general exit-code troubleshooting in README/SKILL prose.","type":"text"}]},{"type":"paragraph","content":[{"text":"Dogfood error-path opt-out:","type":"text","marks":[{"type":"strong"}]},{"text":" If a real API returns HTTP 200 plus an empty success envelope for unknown IDs, and the command cannot distinguish bad input from a valid empty result without inventing API-specific semantics, annotate the Cobra command with ","type":"text"},{"text":"cmd.Annotations[\"pp:no-error-path-probe\"] = \"true\"","type":"text","marks":[{"type":"code_inline"}]},{"text":". Dogfood will still run help, happy-path, and JSON-fidelity checks, but it will skip ","type":"text"},{"text":"error_path","type":"text","marks":[{"type":"code_inline"}]},{"text":" with reason ","type":"text"},{"text":"no-error-path-probe annotation","type":"text","marks":[{"type":"code_inline"}]},{"text":". Do not add local \"empty means not found\" heuristics only to satisfy dogfood unless the upstream API contract actually defines that as an error.","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003ca id=\"hand-edit-durability\">\u003c/a> ","type":"text"},{"text":"Hand-edits must be regen-mergeable.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"cli-printing-press generate --force","type":"text","marks":[{"type":"code_inline"}]},{"text":" snapshots the existing tree, emits a fresh tree, then runs the same AST-aware reconciliation used by ","type":"text"},{"text":"cli-printing-press regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":". Whole hand-authored files and lost ","type":"text"},{"text":"AddCommand","type":"text","marks":[{"type":"code_inline"}]},{"text":" wiring are preserved automatically; straightforward hand-edits to generated Go files (added declarations, literal drift, body drift) are classified and carried forward when the merge can do so safely. For risky edits, use the standalone ","type":"text"},{"text":"regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" command first when you want a previewable report before applying.","type":"text"}]},{"type":"paragraph","content":[{"text":"For an extension to be durable, put it in its own file beside the emitted one:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Custom config fields:","type":"text","marks":[{"type":"strong"}]},{"text":" create ","type":"text"},{"text":"internal/config/\u003capi>_config.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" exporting accessors your novel code reads directly. Do not add fields to the emitted ","type":"text"},{"text":"Config","type":"text","marks":[{"type":"code_inline"}]},{"text":" struct.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Custom request headers","type":"text","marks":[{"type":"strong"}]},{"text":" (vendor fingerprint, ","type":"text"},{"text":"X-CSRF","type":"text","marks":[{"type":"code_inline"}]},{"text":", app-version, signed timestamps): create ","type":"text"},{"text":"internal/client/\u003capi>_headers.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" exporting a func that builds the header map; novel code passes that map to ","type":"text"},{"text":"client.GetWithHeaders","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"PostWithHeaders","type":"text","marks":[{"type":"code_inline"}]},{"text":" when it calls the API. The generated ","type":"text"},{"text":"client.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" has no global request mutator, so this pattern only covers requests made directly from novel code — it does not intercept calls from generated endpoint commands. Do not edit the templated header block in ","type":"text"},{"text":"client.go","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Custom auth flow","type":"text","marks":[{"type":"strong"}]},{"text":" (browser-sniffed sessions, vendor SSO, refresh hooks beyond OAuth2): create ","type":"text"},{"text":"internal/cli/\u003capi>_auth.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" (package ","type":"text"},{"text":"cli","type":"text","marks":[{"type":"code_inline"}]},{"text":", same as the generated ","type":"text"},{"text":"auth.go","type":"text","marks":[{"type":"code_inline"}]},{"text":") with the API-specific token capture or refresh, and wire it from a novel command rather than editing the templated ","type":"text"},{"text":"auth.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" constructor functions (","type":"text"},{"text":"newAuthLoginCmd","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"newAuthSetupCmd","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Extended store schema","type":"text","marks":[{"type":"strong"}]},{"text":" (typed tables beyond ","type":"text"},{"text":"resources","type":"text","marks":[{"type":"code_inline"}]},{"text":", vendor JSON columns, full-text indexes): create ","type":"text"},{"text":"internal/store/\u003capi>_migrations.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" running its own ","type":"text"},{"text":"CREATE TABLE ... IF NOT EXISTS","type":"text","marks":[{"type":"code_inline"}]},{"text":" from a lazy init invoked by the novel commands that need it. Do not edit the migration slice in ","type":"text"},{"text":"store.go","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"New novel command:","type":"text","marks":[{"type":"strong"}]},{"text":" put the command body in its own ","type":"text"},{"text":"internal/cli/\u003cfeature>.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" file — it survives regen as a whole hand-authored unit. The ","type":"text"},{"text":"AddCommand","type":"text","marks":[{"type":"code_inline"}]},{"text":" call wiring it into the Cobra tree still goes in ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" per the Phase 3 novel-command skeleton above; ","type":"text"},{"text":"cli-printing-press generate --force","type":"text","marks":[{"type":"code_inline"}]},{"text":" re-injects it via the lost-registration merge path. Use standalone ","type":"text"},{"text":"regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" when you want to inspect the merge report before applying. Spec-declared commands are picked up by the generator's typed-tool path and need no hand-wired ","type":"text"},{"text":"AddCommand","type":"text","marks":[{"type":"code_inline"}]},{"text":" at all.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If an extension genuinely cannot live in a separate file (a ","type":"text"},{"text":"case","type":"text","marks":[{"type":"code_inline"}]},{"text":" branch in a templated method switch, an inline modification to a generated handler with no registry hook), file a generator issue requesting the hook rather than depending on repeated conflict-prone merges. The ","type":"text"},{"text":"AddCommand","type":"text","marks":[{"type":"code_inline"}]},{"text":" case above is covered by the merge path.","type":"text"}]},{"type":"paragraph","content":[{"text":"MCP exposure:","type":"text","marks":[{"type":"strong"}]},{"text":" The generator emits ","type":"text"},{"text":"internal/mcp/cobratree/","type":"text","marks":[{"type":"code_inline"}]},{"text":", and the MCP binary mirrors the Cobra tree at startup. When you add, rename, or remove a user-facing Cobra command, the MCP surface follows automatically. Two annotations control how each command appears as an MCP tool:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"cmd.Annotations[\"mcp:hidden\"] = \"true\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — exclude the command from the MCP surface entirely. Use only for debug/internal commands that should not become agent tools.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"cmd.Annotations[\"mcp:read-only\"] = \"true\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — declare that this command does not modify external state. The MCP server attaches ","type":"text"},{"text":"readOnlyHint: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" to the resulting tool, so hosts like Claude Desktop don't bucket it under \"write/delete tools\" and demand permission per call. Apply this to every novel command whose only effect is reading from the API or the local store: lookups, comparisons, aggregations, render-only views, status checks. Skip it for commands that mutate external state (orders, posts, deletes) or write to user-visible files outside the local cache.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Endpoint-mirror tools the generator emits from the spec already get the right annotations automatically (","type":"text"},{"text":"GET","type":"text","marks":[{"type":"code_inline"}]},{"text":" → read-only, ","type":"text"},{"text":"DELETE","type":"text","marks":[{"type":"code_inline"}]},{"text":" → destructive, etc.) — ","type":"text"},{"text":"mcp:read-only","type":"text","marks":[{"type":"code_inline"}]},{"text":" is only needed on hand-authored Cobra commands the spec doesn't cover.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not rationalize skipping transcendence features because \"the CLI already works for live API interaction.\" The absorb manifest was approved by the user. Build what was approved.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4: Shipcheck","type":"text"}]},{"type":"paragraph","content":[{"text":"Run one combined verification block via the ","type":"text"},{"text":"shipcheck","type":"text","marks":[{"type":"code_inline"}]},{"text":" umbrella, which runs all six legs (dogfood, verify, workflow-verify, verify-skill, validate-narrative, scorecard) in canonical order, propagates exit codes, and prints a per-leg verdict summary. The umbrella is the canonical Phase 4 invocation; running the legs individually is supported but not recommended (operators have skipped legs that way and shipped broken CLIs).","type":"text"}]},{"type":"paragraph","content":[{"text":"Before running shipcheck, update the lock heartbeat:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase shipcheck","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press shipcheck \\\n --dir \"$CLI_WORK_DIR\" \\\n --spec \u003csame-spec> \\\n --research-dir \"$API_RUN_DIR\"","type":"text"}]},{"type":"paragraph","content":[{"text":"The umbrella defaults to ","type":"text"},{"text":"verify --fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" (auto-repair common failures), ","type":"text"},{"text":"validate-narrative --strict --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" (README/SKILL narrative command validation), and ","type":"text"},{"text":"scorecard --live-check","type":"text","marks":[{"type":"code_inline"}]},{"text":" (sample novel-feature output against real targets). When Go sources under ","type":"text"},{"text":"cmd/\u003ccli>/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"internal/","type":"text","marks":[{"type":"code_inline"}]},{"text":" are newer than ","type":"text"},{"text":"build/stage/bin/\u003ccli>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"scorecard --live-check","type":"text","marks":[{"type":"code_inline"}]},{"text":" rebuilds the staged binary before sampling and reports the refresh action in human and JSON output. Use ","type":"text"},{"text":"--no-fix","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a read-only pass, ","type":"text"},{"text":"--no-live-check","type":"text","marks":[{"type":"code_inline"}]},{"text":" to skip live sampling, or ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a structured envelope (suppresses per-leg output for clean piping). Pass ","type":"text"},{"text":"--api-key","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"--env-var","type":"text","marks":[{"type":"code_inline"}]},{"text":" through to verify when live testing needs a credential, or ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" to make verify-skill treat likely-false-positive findings as failures.","type":"text"}]},{"type":"paragraph","content":[{"text":"If a leg fails, re-run that one leg standalone (e.g., ","type":"text"},{"text":"cli-printing-press verify-skill --dir \u003cCLI_WORK_DIR>","type":"text","marks":[{"type":"code_inline"}]},{"text":") for focused iteration; once it passes, re-run the full ","type":"text"},{"text":"shipcheck","type":"text","marks":[{"type":"code_inline"}]},{"text":" umbrella to confirm no regression in the others.","type":"text"}]},{"type":"paragraph","content":[{"text":"Interpretation:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":" catches dead flags, dead helpers, invalid paths, example drift, broken data wiring, command tree/config field wiring bugs, stale static MCP surfaces, and novel features that were planned but not built","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" catches runtime breakage and runs the auto-fix loop for common failures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"workflow-verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" tests the primary workflow end-to-end using the verification manifest (workflow_verify.yaml). Three verdicts: workflow-pass, workflow-fail, unverified-needs-auth","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"verify-skill","type":"text","marks":[{"type":"code_inline"}]},{"text":" checks that every ","type":"text"},{"text":"--flag","type":"text","marks":[{"type":"code_inline"}]},{"text":" and command path in SKILL.md actually exists in the shipped CLI source. Catches bogus examples invented by the absorb LLM (e.g., ","type":"text"},{"text":"search --max-time","type":"text","marks":[{"type":"code_inline"}]},{"text":" when ","type":"text"},{"text":"--max-time","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a ","type":"text"},{"text":"tonight","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag). Exit 1 = findings to fix; exit 0 = SKILL is honest.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"validate-narrative","type":"text","marks":[{"type":"code_inline"}]},{"text":" checks that every README/SKILL narrative command path, flag, and argument shape in research.json resolves against the built CLI under ","type":"text"},{"text":"PRINTING_PRESS_VERIFY=1","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scorecard","type":"text","marks":[{"type":"code_inline"}]},{"text":" is the structural quality snapshot, not the source of truth by itself","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Fix order (update heartbeat between each fix category to prevent stale lock during long fix loops):","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"generation blockers or build breaks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"invalid paths and auth mismatches","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dead flags / dead functions / ghost tables","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"broken dry-run and runtime command failures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"missing novel features (see below)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scorecard-only polish gaps","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"When category 4 includes narrative examples, rerun ","type":"text"},{"text":"cli-printing-press validate-narrative --strict --full-examples","type":"text","marks":[{"type":"code_inline"}]},{"text":" after the fix. The path-only mode is not enough before publishing because it cannot catch bad flags on an otherwise valid command.","type":"text"}]},{"type":"paragraph","content":[{"text":"Missing novel features fix (step 5):","type":"text","marks":[{"type":"strong"}]},{"text":" Dogfood writes ","type":"text"},{"text":"novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":" to research.json — only features whose commands actually exist. The original ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" (aspirational list from absorb) is preserved for the audit trail. Dogfood also syncs the generated ","type":"text"},{"text":".printing-press.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"## Unique Features","type":"text","marks":[{"type":"code_inline"}]},{"text":" block, ","type":"text"},{"text":"SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"## Unique Capabilities","type":"text","marks":[{"type":"code_inline"}]},{"text":" block, and ","type":"text"},{"text":"internal/cli/root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"--help","type":"text","marks":[{"type":"code_inline"}]},{"text":" Highlights block from ","type":"text"},{"text":"novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":"; if none survived, it removes the rendered README/SKILL/root help blocks. Dogfood prints ","type":"text"},{"text":"dogfood: synced ... from novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":" for every rendered artifact it changes. After dogfood:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inspect the dogfood planned-vs-built delta","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Build missing approved features when they are still in scope","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Rerun dogfood so research.json, ","type":"text"},{"text":".printing-press.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", README.md, SKILL.md, and root ","type":"text"},{"text":"--help","type":"text","marks":[{"type":"code_inline"}]},{"text":" Highlights are all synced from the verified set","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Audit surrounding README/SKILL/root help prose, recipes, trigger phrases, and examples for indirect references to dropped features","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Log which features were dropped (planned vs built delta)","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"After fixing each category, update the heartbeat:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock update --cli \u003capi>-pp-cli --phase shipcheck-fixing","type":"text"}]},{"type":"paragraph","content":[{"text":"\u003c!-- CODEX_PHASE4_START --> When ","type":"text"},{"text":"CODEX_MODE","type":"text","marks":[{"type":"code_inline"}]},{"text":" is true, read ","type":"text"},{"text":"references/codex-delegation.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/codex-delegation.md","title":null}}]},{"text":" for the Phase 4 fix delegation pattern.","type":"text"}]},{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"CODEX_MODE","type":"text","marks":[{"type":"code_inline"}]},{"text":" is false, fix bugs directly. \u003c!-- CODEX_PHASE4_END -->","type":"text"}]},{"type":"paragraph","content":[{"text":"Ship threshold (the umbrella's verdict is the canonical signal — all of these must hold for ","type":"text"},{"text":"shipcheck","type":"text","marks":[{"type":"code_inline"}]},{"text":" to exit 0):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"shipcheck","type":"text","marks":[{"type":"code_inline"}]},{"text":" exits 0. The umbrella's per-leg summary table shows every leg PASS. A non-zero exit is a fix-before-ship blocker, period — do not ship if the umbrella is red.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdict is ","type":"text"},{"text":"PASS","type":"text","marks":[{"type":"code_inline"}]},{"text":" or high ","type":"text"},{"text":"WARN","type":"text","marks":[{"type":"code_inline"}]},{"text":" with 0 critical failures","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":" no longer fails because of spec parsing, binary path, or skipped examples","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":" wiring checks pass (no unregistered commands, no config field mismatches)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"workflow-verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdict is ","type":"text"},{"text":"workflow-pass","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"unverified-needs-auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" (not ","type":"text"},{"text":"workflow-fail","type":"text","marks":[{"type":"code_inline"}]},{"text":"). Exception: if the spec or traffic analysis marks browser-session/browser-clearance auth as required, ","type":"text"},{"text":"unverified-needs-auth","type":"text","marks":[{"type":"code_inline"}]},{"text":" is a ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdict until ","type":"text"},{"text":"auth login --chrome","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"doctor --json","type":"text","marks":[{"type":"code_inline"}]},{"text":", and a read-only browser-session proof pass against the real site.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"verify-skill","type":"text","marks":[{"type":"code_inline"}]},{"text":" exits 0 (no mechanical mismatches between SKILL.md and CLI source). Treat non-zero as a fix-before-ship blocker — the SKILL is what agents read; if it lies about the CLI, the lie ships.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"scorecard","type":"text","marks":[{"type":"code_inline"}]},{"text":" is at least 65 and ","type":"text"},{"text":"no flagship or approved-in-Phase-1.5 feature returns wrong/empty output","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"paragraph","content":[{"text":"Behavioral correctness is part of the ship threshold, not just structural quality.","type":"text","marks":[{"type":"strong"}]},{"text":" A Grade A scorecard with a broken flagship feature (e.g., ","type":"text"},{"text":"goat \"brownies\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" returning a chili recipe) does NOT pass the ship threshold. Run a sample invocation of every novel-feature command before declaring shipcheck complete.","type":"text"}]},{"type":"paragraph","content":[{"text":"Per-source row for combo CLIs (synthetic spec, multiple data sources).","type":"text","marks":[{"type":"strong"}]},{"text":" For every named source in a combo CLI (","type":"text"},{"text":"internal/source/\u003cname>/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/recipes/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/phgraphql/","type":"text","marks":[{"type":"code_inline"}]},{"text":", etc.) the dogfood test matrix MUST add one row per source: with the source's limiter exhausted (or the upstream genuinely throttling), assert that the user-facing command surfaces a typed ","type":"text"},{"text":"*cliutil.RateLimitError","type":"text","marks":[{"type":"code_inline"}]},{"text":" referencing the source — not empty JSON / ","type":"text"},{"text":"0 results","type":"text","marks":[{"type":"code_inline"}]},{"text":". A passing row says: \"the CLI distinguishes 'no data' from 'we got rate-limited' for this source.\" The matrix-builder derives rows from the command tree by default; for combo CLIs, also derive rows from the source list. ","type":"text"},{"text":"source_client_check","type":"text","marks":[{"type":"code_inline"}]},{"text":" catches the static signal that throttling is silently swallowed; only the runtime row proves the user-visible behavior.","type":"text"}]},{"type":"paragraph","content":[{"text":"Maximum 2 shipcheck loops by default.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/\u003cstamp>-fix-\u003capi>-pp-cli-shipcheck.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Include:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"command outputs and scores","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"top blockers found","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"fixes applied","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"before/after verify pass rate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"before/after scorecard total","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"final ship recommendation: ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]}]}]}]},{"type":"paragraph","content":[{"text":"Verdict rules:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":": all ship-threshold conditions met AND no known functional bugs in shipping-scope features.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":": one or more conditions missing, OR functional bugs exist that cannot be fixed in-session.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" is deprecated as a default verdict. It is NOT valid for bugs that require only 1-3 file edits; those MUST be fixed before ship. It is only acceptable when (a) a bug genuinely requires a refactor, external dependency change, or API access not available in-session, AND (b) the bug is clearly documented with a ","type":"text"},{"text":"## Known Gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" block in both the shipcheck report and the generated README. If an agent cannot meet both (a) and (b), the verdict is ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":", not ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"If the final verdict is ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":", release the lock without promoting to library:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock release --cli \u003capi>-pp-cli","type":"text"}]},{"type":"paragraph","content":[{"text":"The working copy remains in ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" for potential future retry. Proceed to Phase 5.6 to archive manuscripts (archiving still happens on hold).","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4.7: Sync Param-Drop Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"Runs after shipcheck, before Phase 4.8.","type":"text","marks":[{"type":"strong"}]},{"text":" Generated endpoint commands are param-cardinality-checked mechanically by ","type":"text"},{"text":"cobratree","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the spec — hand-authored sync / transcendence code is not. When the printed CLI's ","type":"text"},{"text":"internal/syncer/","type":"text","marks":[{"type":"code_inline"}]},{"text":" calls ","type":"text"},{"text":"client.Get(\u003cpath>, params)","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"Post","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"Put","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"Patch","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"Delete","type":"text","marks":[{"type":"code_inline"}]},{"text":" with body params) against an endpoint the browser-sniff capture also observed, the gate compares the passed-key set against the captured-key set and flags any call where the capture is a strict superset of the code. Same JSON structure on both sides; only cardinality drift catches the \"5 params here, 11 on the live site\" failure mode.","type":"text"}]},{"type":"paragraph","content":[{"text":"Skip the gate when there's no ","type":"text"},{"text":"traffic-analysis.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" for this CLI (catalog wrapper-only entries, vendor-spec CLIs without a browser-sniff phase). Otherwise:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"printing-press sync-param-drop \\\n --dir \"$CLI_WORK_DIR\" \\\n --traffic-analysis \"$API_RUN_DIR/\u003capi>-traffic-analysis.json\" \\\n --strict","type":"text"}]},{"type":"paragraph","content":[{"text":"The same diff also runs as part of ","type":"text"},{"text":"printing-press dogfood","type":"text","marks":[{"type":"code_inline"}]},{"text":" when you pass ","type":"text"},{"text":"--traffic-analysis","type":"text","marks":[{"type":"code_inline"}]},{"text":"; shipcheck's dogfood leg will surface findings as a WARN-level dogfood issue automatically. Running the standalone subcommand with ","type":"text"},{"text":"--strict","type":"text","marks":[{"type":"code_inline"}]},{"text":" during fix iteration gives a focused exit code without re-running the full dogfood matrix.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Failure handling","type":"text"}]},{"type":"paragraph","content":[{"text":"A finding tells the reviewer exactly three things: ","type":"text"},{"text":"\u003cfile>:\u003cline>: \u003cMETHOD> \u003cpath> — dropped params: \u003ckey1>, \u003ckey2>, ...","type":"text","marks":[{"type":"code_inline"}]},{"text":". The fix is one of:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Add the missing params to the sync call.","type":"text","marks":[{"type":"strong"}]},{"text":" This is the default — the live site captured them, so the printed CLI should too. The dropped keys are almost always required for the response shape the CLI's domain commands expect (Factor75: passing ","type":"text"},{"text":"week, country, locale, subscription, product-sku","type":"text","marks":[{"type":"code_inline"}]},{"text":" returns a generic plan preselect; the live site additionally passes ","type":"text"},{"text":"servings, delivery-option, postcode, preference, customerPlanId, include-future-feedback","type":"text","marks":[{"type":"code_inline"}]},{"text":" to get the user's actual cart). Widening the call is the only fix that resolves the underlying bug.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Annotate the call with an evidence-backed opt-out.","type":"text","marks":[{"type":"strong"}]},{"text":" Add ","type":"text"},{"text":"// pp:sync-params-intentional-subset reason=\u003cwhy>","type":"text","marks":[{"type":"code_inline"}]},{"text":" on the line immediately above the call when the subset is genuinely intentional — for example, a logged-out endpoint that doesn't accept the session-bound keys, or a deliberately broader query the CLI surfaces as a separate command. The ","type":"text"},{"text":"reason=","type":"text","marks":[{"type":"code_inline"}]},{"text":" text is preserved in the audit trail; the gate counts suppressed sites separately so unbounded growth surfaces as its own smell.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The gate does not introspect response content. A passing gate proves request-key parity with the captured site, not response correctness — Phase 4.85's agentic output review remains the layer that catches \"wrong response shape, right request shape.\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Scope boundary","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The gate inspects ","type":"text"},{"text":"internal/syncer/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/sync/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/transcend/","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"internal/transcendence/","type":"text","marks":[{"type":"code_inline"}]},{"text":". Generated endpoint command files under ","type":"text"},{"text":"internal/cli/","type":"text","marks":[{"type":"code_inline"}]},{"text":" are already covered by ","type":"text"},{"text":"cobratree","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s mechanical endpoint-surface check and are intentionally skipped to avoid double-flagging.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Paths the capture never observed (synthetic / transcendence-only endpoints) are not flagged — the gate's question is \"does the live site call this path with more keys,\" and absence of capture is a no-flag state.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A call that passes a key the capture never observed (extra-keys-from-code) is not flagged — exotic-mode params the public UI never exercised are out of scope.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4.8: Agentic SKILL Review","type":"text"}]},{"type":"paragraph","content":[{"text":"Runs after shipcheck, before Phase 5.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"verify-skill","type":"text","marks":[{"type":"code_inline"}]},{"text":" (Phase 4) is a mechanical check — it catches wrong flags on wrong commands, undeclared flags, and positional-arg count mismatches. It cannot catch ","type":"text"},{"text":"semantic","type":"text","marks":[{"type":"strong"}]},{"text":" issues that only a reader notices:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A trigger phrase promises behavior the CLI doesn't have (\"plan dinners for the week\" when there's no ","type":"text"},{"text":"meal-plan suggest","type":"text","marks":[{"type":"code_inline"}]},{"text":", only manual ","type":"text"},{"text":"meal-plan set","type":"text","marks":[{"type":"code_inline"}]},{"text":")","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A novel-feature description says the feature does X; the actual command does Y","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The AuthNarrative mentions ","type":"text"},{"text":"auth login --chrome","type":"text","marks":[{"type":"code_inline"}]},{"text":" when the CLI's auth subcommands are only ","type":"text"},{"text":"set-token","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"logout","type":"text","marks":[{"type":"code_inline"}]},{"text":"/","type":"text"},{"text":"status","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Novel features shipped as stubs aren't labeled as such in the SKILL (contradicts Phase 1.5 stub-marking rule)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recipes/worked examples produce output that doesn't match their prose claims","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Trigger phrases sound agent-natural or sound like marketing copy","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Dispatch","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the Agent tool (general-purpose or a dedicated reviewer) with this prompt contract:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Review the SKILL.md at ","type":"text"},{"text":"$CLI_WORK_DIR/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the shipped CLI. You have these ground-truth sources:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\u003ccli> --help","type":"text","marks":[{"type":"code_inline"}]},{"text":" output — enumerate it recursively if needed.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The absorb manifest in ","type":"text"},{"text":"$RESEARCH_DIR/\u003cstamp>-feat-\u003capi>-pp-cli-absorb-manifest.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" (planned) and ","type":"text"},{"text":"novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":" (verified) fields.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The README at ","type":"text"},{"text":"$CLI_WORK_DIR/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"For each of these semantic checks, report findings under 50 words each:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Trigger phrases match capabilities.","type":"text","marks":[{"type":"strong"}]},{"text":" Does every trigger phrase in the SKILL's description frontmatter correspond to something the CLI can actually do? Flag phrases that imply missing capabilities.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Verified-set alignment.","type":"text","marks":[{"type":"strong"}]},{"text":" The SKILL's \"Unique Capabilities\" commands must exactly match ","type":"text"},{"text":"novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":" from research.json. Planned-only features from ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" must not appear there after dogfood sync. Any extra or missing command is a finding.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Novel-feature descriptions match commands.","type":"text","marks":[{"type":"strong"}]},{"text":" For each feature in the \"Unique Capabilities\" section, run ","type":"text"},{"text":"\u003ccli> \u003ccommand> --help","type":"text","marks":[{"type":"code_inline"}]},{"text":" and verify the description matches the actual behavior. Mismatches are findings.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stub/gated disclosure.","type":"text","marks":[{"type":"strong"}]},{"text":" If a feature that remains in ","type":"text"},{"text":"novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":" is intentionally stubbed, CF-gated, unavailable without external setup, or returns a known-gap response, the SKILL must label that limitation where an agent decides whether to use the command. Unlabeled limitations are findings.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auth narrative accuracy.","type":"text","marks":[{"type":"strong"}]},{"text":" Read the auth section. Does every ","type":"text"},{"text":"auth login/set-token/status","type":"text","marks":[{"type":"code_inline"}]},{"text":" invocation mentioned actually exist on the CLI? Does the narrative match the CLI's auth type (api_key vs cookie vs session_handshake)?","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Recipe output claims.","type":"text","marks":[{"type":"strong"}]},{"text":" For the worked examples, does the prose claim match what the command actually produces? (Not the exact output — the shape and intent.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Marketing-copy smell.","type":"text","marks":[{"type":"strong"}]},{"text":" Does the SKILL read like ad copy (\"comprehensive\", \"seamless\", \"powerful\") instead of concrete capability descriptions? Those phrases are findings.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Return a list of findings. For each: check name, severity (error/warning), line number, one-sentence fix. If SKILL passes all seven checks, return \"PASS — no findings.\"","type":"text"}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Gate","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the reviewer returns PASS, proceed to Phase 5.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the reviewer returns findings of severity ","type":"text"},{"text":"error","type":"text","marks":[{"type":"code_inline"}]},{"text":", fix them before Phase 5. Same fix-now contract as other shipcheck findings.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If the reviewer returns only ","type":"text"},{"text":"warning","type":"text","marks":[{"type":"code_inline"}]},{"text":" findings, surface them to the user and proceed if they approve.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Why agentic vs template-only","type":"text"}]},{"type":"paragraph","content":[{"text":"A template-level check would require every possible semantic mismatch to be pattern-matchable against source. Many aren't — \"does this trigger phrase correspond to what the CLI does\" is an LLM-shaped question. Accept the token cost for the catch.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Known blind spots","type":"text"}]},{"type":"paragraph","content":[{"text":"The agent can't verify runtime behavior without running commands; stick to help-text and source-based claims. For runtime-behavior claims (e.g., \"returns 5 matching recipes\"), Phase 5 dogfood is the right gate.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4.9: README/SKILL/AGENTS Correctness Audit","type":"text"}]},{"type":"paragraph","content":[{"text":"Runs after Phase 4.8, before Phase 5.","type":"text","marks":[{"type":"strong"}]},{"text":" Phase 4.8 reviews whether the SKILL's trigger phrases and major claims match shipped behavior. Phase 4.9 reviews the user-facing artifacts as documents: README.md, SKILL.md, and AGENTS.md must not contain boilerplate that does not apply to this CLI.","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the Agent tool or review directly with this prompt contract:","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"Audit ","type":"text"},{"text":"$CLI_WORK_DIR/README.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"$CLI_WORK_DIR/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"$CLI_WORK_DIR/AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" for factual correctness against the shipped CLI. Ground truth is ","type":"text"},{"text":"\u003ccli> --help","type":"text","marks":[{"type":"code_inline"}]},{"text":" recursively, ","type":"text"},{"text":"$CLI_WORK_DIR/internal/cli/*.go","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"$RESEARCH_DIR/research.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", and the absorb manifest.","type":"text"}]},{"type":"paragraph","content":[{"text":"Check:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every command, subcommand, flag, exit code, config path, and example resolves to the printed CLI.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"README ","type":"text"},{"text":"## Unique Features","type":"text","marks":[{"type":"code_inline"}]},{"text":" and SKILL ","type":"text"},{"text":"## Unique Capabilities","type":"text","marks":[{"type":"code_inline"}]},{"text":" match ","type":"text"},{"text":"novel_features_built","type":"text","marks":[{"type":"code_inline"}]},{"text":"; planned-only features from ","type":"text"},{"text":"novel_features","type":"text","marks":[{"type":"code_inline"}]},{"text":" are not claimed after dogfood sync.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Surrounding prose, recipes, trigger phrases, and examples do not indirectly promise planned features that dogfood dropped.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No placeholder literals remain in executable examples (","type":"text"},{"text":"\u003ccli>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003ccommand>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cresource>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cCLI>","type":"text","marks":[{"type":"code_inline"}]},{"text":").","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Boilerplate matches the CLI shape: no CRUD/retry/create-stdin/delete/cache/auth/async-job claims unless the CLI actually implements them.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Read-only CLIs say they are read-only and do not imply create/update/delete support.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No-auth CLIs omit auth troubleshooting and auth exit-code claims unless the binary can raise them.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Stubbed, CF-gated, or unavailable commands are disclosed where an agent decides whether to use the CLI.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The SKILL has anti-triggers: common requests this CLI should not handle.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Brand/display names use the canonical prose name from research, not only the slug.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Marketing phrases map to real commands; invented feature names are findings.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Return findings with file, line, severity, and fix. If both files are correct, return ","type":"text"},{"text":"PASS — README/SKILL correctness verified","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]},{"type":"paragraph","content":[{"text":"Gate:","type":"text","marks":[{"type":"strong"}]},{"text":" Any error finding is fix-before-Phase-5. Warnings may proceed only when they are explicitly explained in the acceptance report.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4.85: Agentic Output Review","type":"text"}]},{"type":"paragraph","content":[{"text":"Runs after Phase 4.8, before Phase 4.95.","type":"text","marks":[{"type":"strong"}]},{"text":" Phase 4.8 reviews SKILL.md prose against the shipped CLI. Phase 4.85 reviews the CLI's ","type":"text"},{"text":"actual command output","type":"text","marks":[{"type":"strong"}]},{"text":" for plausibility bugs that rule-based checks can't encode (substring-match relevance failures, format bugs, silent source drops, ranking failures). The dispatch prompt, gate logic, and known blind spots live in the ","type":"text"},{"text":"printing-press-output-review","type":"text","marks":[{"type":"code_inline"}]},{"text":" sub-skill — single source of truth shared with the polish skill (which runs the same review during its diagnostic loop).","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoke the sub-skill via the Skill tool:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Skill(\n skill: \"cli-printing-press:printing-press-output-review\",\n args: \"$CLI_WORK_DIR\"\n)","type":"text"}]},{"type":"paragraph","content":[{"text":"The sub-skill carries ","type":"text"},{"text":"context: fork","type":"text","marks":[{"type":"code_inline"}]},{"text":" so the reviewer agent's diagnostic chatter stays isolated from this generation flow. It returns a ","type":"text"},{"text":"---OUTPUT-REVIEW-RESULT---","type":"text","marks":[{"type":"code_inline"}]},{"text":" block with ","type":"text"},{"text":"status: PASS|WARN|SKIP","type":"text","marks":[{"type":"code_inline"}]},{"text":" and a list of findings.","type":"text"}]},{"type":"paragraph","content":[{"text":"Wave B rollout policy:","type":"text","marks":[{"type":"strong"}]},{"text":" all findings surface as ","type":"text"},{"text":"warnings","type":"text","marks":[{"type":"strong"}]},{"text":", not blockers. Shipcheck does not fail on Phase 4.85 findings. Log the findings to ","type":"text"},{"text":"manuscripts/\u003capi>/\u003crun>/proofs/phase-4.85-findings.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" and surface them to the user. The user decides case by case whether to fix before shipping. Wave B calibrates false-positive rates before Wave C flips errors to blocking.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 4.95: Local Code Review","type":"text"}]},{"type":"paragraph","content":[{"text":"Runs after Phase 4.85, before Phase 5.","type":"text","marks":[{"type":"strong"}]},{"text":" Reviews the printed CLI source for security and correctness issues ","type":"text"},{"text":"before","type":"text","marks":[{"type":"em"}]},{"text":" any PR exists. This is the cheapest fix window in the pipeline — session context is hot, no PR feedback round-trip, no CI comments to chase. Catching issues here means they never become PR-time review comments, which is the wrong fix window for the same problems.","type":"text"}]},{"type":"paragraph","content":[{"text":"Target.","type":"text","marks":[{"type":"strong"}]},{"text":" The generated CLI and MCP source under ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":". In scope: ","type":"text"},{"text":"internal/cli/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/mcp/","type":"text","marks":[{"type":"code_inline"}]},{"text":" (excluding ","type":"text"},{"text":"cobratree/","type":"text","marks":[{"type":"code_inline"}]},{"text":"), ","type":"text"},{"text":"internal/store/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/client/","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"cmd/","type":"text","marks":[{"type":"code_inline"}]},{"text":". ","type":"text"},{"text":"Out of scope:","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"internal/cliutil/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"internal/mcp/cobratree/","type":"text","marks":[{"type":"code_inline"}]},{"text":" — these are generator-reserved packages. Any finding there is a machine bug; route to retro, do not patch in place.","type":"text"}]},{"type":"paragraph","content":[{"text":"Tool selection — pick what's installed, do not name-match.","type":"text","marks":[{"type":"strong"}]},{"text":" This phase needs ","type":"text"},{"text":"a","type":"text","marks":[{"type":"em"}]},{"text":" code review, not a specific named command. Survey the review-shaped capabilities the current harness has and pick the best fit. Plausible candidates (names drift across harnesses and plugin sets; treat this as an example list, not a closed set):","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"A standalone, working-dir-shaped code review skill that runs against ","type":"text"},{"text":"git diff","type":"text","marks":[{"type":"code_inline"}]},{"text":" and a file list without needing an open PR (e.g., ","type":"text"},{"text":"compound-engineering:ce-code-review","type":"text","marks":[{"type":"code_inline"}]},{"text":", or similar).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Codex's built-in code-review mode (","type":"text"},{"text":"/codex:review","type":"text","marks":[{"type":"code_inline"}]},{"text":"), which reviews the current diff or target directly.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Direct reviewer-subagent dispatch via the Agent tool.","type":"text","marks":[{"type":"strong"}]},{"text":" Spawn ","type":"text"},{"text":"correctness","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"security","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"maintainability","type":"text","marks":[{"type":"code_inline"}]},{"text":" reviewers (always-on) plus any conditional reviewers warranted by the diff (","type":"text"},{"text":"api-contract","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"data-migrations","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"reliability","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"performance","type":"text","marks":[{"type":"code_inline"}]},{"text":") against the in-scope paths. This is the universal fallback: any harness that runs the press skill has the Agent tool, so this path is always available. When dispatching multiple reviewers, a \"round\" (per the autofix loop below) means re-running ","type":"text"},{"text":"all","type":"text","marks":[{"type":"em"}]},{"text":" spawned reviewers in parallel and merging their findings into a single set before autofix; convergence is the merged set being empty, not any individual reviewer clearing. Do not re-run only the reviewer whose prior findings were touched — every round must include every reviewer so cascading or newly-introduced issues surface.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Do not invoke Claude Code's ","type":"text","marks":[{"type":"strong"}]},{"text":"/review","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" for this phase.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"/review","type":"text","marks":[{"type":"code_inline"}]},{"text":" is PR-shaped — it fetches an open GitHub PR and comments back via ","type":"text"},{"text":"gh","type":"text","marks":[{"type":"code_inline"}]},{"text":". There is no PR yet at Phase 4.95; the CLI is in a working dir that has not been promoted or published. Reaching for ","type":"text"},{"text":"/review","type":"text","marks":[{"type":"code_inline"}]},{"text":", bouncing off its shape, and claiming \"harness has no code review\" is the failure mode this section is written to prevent.","type":"text"}]},{"type":"paragraph","content":[{"text":"Autofix policy.","type":"text","marks":[{"type":"strong"}]},{"text":" Session context is hot, no PR feedback round-trip, no publish decision in flight. The default is fix. Surfacing to the user is the exception, not the rule. Severity is informational, not gating: a low-severity nil-deref is a 30-second fix; close it the same as a high-severity one.","type":"text"}]},{"type":"paragraph","content":[{"text":"Fix without asking when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The fix is mechanical (parameterized query, input validation, error wrapping, missing nil check, dead code removal, obvious refactor).","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The fix is small-scope and behavior-preserving from the README's point of view.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"There is no plausible competing implementation a reasonable user would prefer over the chosen one.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Surface to the user only when the fix requires a real tradeoff they have to make. Real tradeoffs look like:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Shipping scope shrinks.","type":"text","marks":[{"type":"strong"}]},{"text":" Closing the finding cleanly means dropping or significantly degrading a Phase 1.5-approved feature. (Per the Rules section, scope changes route back to Phase 1.5 for re-approval, not a silent shrink here.)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Two materially different valid fixes","type":"text","marks":[{"type":"strong"}]},{"text":" with different cost, surface, or dependency profiles, and either is defensible.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The finding implies a Phase 1 research miss","type":"text","marks":[{"type":"strong"}]},{"text":" — wrong primary source, wrong auth model, wrong transport — that the agent cannot resolve from in-session context.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"The fix re-triggers a long phase","type":"text","marks":[{"type":"strong"}]},{"text":" (re-running browser-sniff, regen from spec, etc.).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Treat agent judgment as sufficient here — these categories are distinguishable on inspection. Conservatism is the failure mode, not over-fixing. Drafting an AskUserQuestion because \"the user might want to know\" is premature; fix the issue and note it in the shipcheck report.","type":"text"}]},{"type":"paragraph","content":[{"text":"Re-run the review after each autofix round until findings clear. Cap at 3 rounds; if findings persist after round 3, stop and surface — autofix is not converging. Findings in out-of-scope paths (","type":"text"},{"text":"internal/cliutil/","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"internal/mcp/cobratree/","type":"text","marks":[{"type":"code_inline"}]},{"text":") file as retro-candidates and do not count toward the convergence check or the 3-round cap; the convergence check applies only to in-scope findings.","type":"text"}]},{"type":"paragraph","content":[{"text":"Findings artifact.","type":"text","marks":[{"type":"strong"}]},{"text":" Log to ","type":"text"},{"text":"manuscripts/\u003capi>/\u003crun>/proofs/phase-4.95-findings.md","type":"text","marks":[{"type":"code_inline"}]},{"text":". Skip the per-finding enumeration for fixed-in-place items — the commits and diffs are already the authoritative record. Specifically:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Autofix summary (one line).","type":"text","marks":[{"type":"strong"}]},{"text":" \"N findings autofixed in-place across M rounds; see commits ","type":"text"},{"text":"\u003chash>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003chash>","type":"text","marks":[{"type":"code_inline"}]},{"text":", …\" Do not enumerate the fixed findings.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Template-shape retro candidates (full detail).","type":"text","marks":[{"type":"strong"}]},{"text":" Each finding's file:line, severity, the template path it appears to come from, and why it was filed instead of fixed. Not fixed in-place, so the log is the only record.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Out-of-scope retro candidates (full detail).","type":"text","marks":[{"type":"strong"}]},{"text":" Findings in ","type":"text"},{"text":"internal/cliutil/","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"internal/mcp/cobratree/","type":"text","marks":[{"type":"code_inline"}]},{"text":". Same shape as template-shape entries.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Surface-to-user findings (full detail).","type":"text","marks":[{"type":"strong"}]},{"text":" Each finding's file:line, severity, the real-tradeoff category it falls into, and the user's decision once they make one. Pending between turns; the log is what carries them.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Convergence outcome (one line).","type":"text","marks":[{"type":"strong"}]},{"text":" \"Findings cleared at round N\" or \"stopped at round 3 with N findings outstanding — see surface-to-user list.\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Review path chosen (one line).","type":"text","marks":[{"type":"strong"}]},{"text":" Skill name + invocation form, or \"direct subagent dispatch\" with the persona list. Lets a retro audit tool-selection drift across runs.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The retro skill scans the template-shape and out-of-scope sections for candidates worth filing against the machine.","type":"text"}]},{"type":"paragraph","content":[{"text":"Rollout posture.","type":"text","marks":[{"type":"strong"}]},{"text":" Unlike Phase 4.85, this phase starts without a warnings-only calibration period. Local code review is a well-understood surface — calibration risk is low. The 3-round autofix cap is the safety net for runaway findings, and the template-shape escape hatch routes systemic issues to retro instead of patching in place.","type":"text"}]},{"type":"paragraph","content":[{"text":"Template-shape escape hatch.","type":"text","marks":[{"type":"strong"}]},{"text":" Even if a finding lives in an in-scope path, if it appears to come from a generator template (recurs across files in identical shape, sits in a path matched by ","type":"text"},{"text":"internal/generator/templates/","type":"text","marks":[{"type":"code_inline"}]},{"text":"'s emit set, or duplicates a known prior template bug), file as retro-candidate and surface to the user rather than autofixing. Patching the printed CLI hides the machine bug from the next CLI.","type":"text"}]},{"type":"paragraph","content":[{"text":"Post-fix simplification (Claude Code only).","type":"text","marks":[{"type":"strong"}]},{"text":" After the review + autofix loop converges, the printed CLI has fresh edits from the autofix passes — typically defensive guards, sanitization helpers, and near-duplicate fixes across sibling files. Run ","type":"text"},{"text":"/simplify","type":"text","marks":[{"type":"code_inline"}]},{"text":" scoped to the same in-scope paths to consolidate duplication, remove dead code, and tighten the autofix output before dogfood. ","type":"text"},{"text":"/simplify","type":"text","marks":[{"type":"code_inline"}]},{"text":" is Claude Code-only; skip on Codex and other harnesses (they have no built-in equivalent, and the press skill explicitly avoids custom simplification logic — same rule as the review path above).","type":"text"}]},{"type":"paragraph","content":[{"text":"Harness exemption — narrow.","type":"text","marks":[{"type":"strong"}]},{"text":" Skipping this phase is legitimate only when the current harness has ","type":"text"},{"text":"neither","type":"text","marks":[{"type":"em"}]},{"text":" a working-dir-shaped review skill ","type":"text"},{"text":"nor","type":"text","marks":[{"type":"em"}]},{"text":" the Agent/subagent capability needed for the direct-dispatch fallback. In practice this is almost never true — any harness that runs the press skill has access to subagents. The following rationales are ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" acceptable for skipping:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"The first tool name I tried (e.g., ","type":"text"},{"text":"/review","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"code-review:code-review","type":"text","marks":[{"type":"code_inline"}]},{"text":") didn't fit, so the harness must have no review path.\" Survey the catalog before claiming exemption; if no skill fits, dispatch reviewer subagents directly via the Agent tool.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"There's no PR yet, so code review can't run here.\" Pre-PR is the ","type":"text"},{"text":"point","type":"text","marks":[{"type":"em"}]},{"text":" of this phase. CI-time PR review is too late.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"\"PR-time CI review will catch it.\" That defeats the purpose of running review in the cheapest fix window.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If a skip is genuinely warranted, the shipcheck report must state which review-shaped capabilities were searched and why none fit — not just \"harness exemption.\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 5: Dogfood Testing","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY when an API key is available. Do NOT skip or shortcut this phase.","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"Shipcheck verified commands start and return exit codes. Dogfood verifies the CLI produces correct, useful output for real workflows. These are different checks.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 1: Ask the user for depth","type":"text"}]},{"type":"paragraph","content":[{"text":"Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"Shipcheck passed. How thoroughly should I test against the live API?\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Full dogfood (recommended)","type":"text","marks":[{"type":"strong"}]},{"text":" — Complete mechanical test matrix across every leaf subcommand, including help, happy-path, JSON parse validation, output-mode fidelity, and error paths. Includes write-side lifecycle only with an approved disposable fixture/sandbox plan.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quick check","type":"text","marks":[{"type":"strong"}]},{"text":" — A compromise subset when the user explicitly wants speed or full dogfood would consume unapproved real-world cost/side effects.","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Recommendation rule:","type":"text","marks":[{"type":"strong"}]},{"text":" Full dogfood is the default recommendation. Do not downgrade because of ordinary time cost; a few extra minutes is cheap compared with the generation run and the cost of shipping a broken CLI. Recommend Quick only when the user asks for speed or when full live testing would create unapproved real-world cost/side effects (paid credits, outbound messages, public posts, real orders, irreversible deletes, invites, bookings, charges). Potential mutation is not itself a reason to downgrade: if the user approves a test account/workspace/calendar/project or the CLI can create and clean up disposable fixtures, Full dogfood remains recommended.","type":"text"}]},{"type":"paragraph","content":[{"text":"There is no skip option when an API key is available. Phase 5 auto-skips ONLY when the API requires auth AND no key is available: display \"No API key available — skipping live dogfood testing. The CLI was verified against exit codes and dry-run only.\"","type":"text"}]},{"type":"paragraph","content":[{"text":"For APIs with ","type":"text"},{"text":"auth.type: none","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or no auth section in the spec), Phase 5 is MANDATORY — the API is freely testable without any credentials. Do not skip testing just because no API key was detected. No-auth APIs are the easiest to test and the most embarrassing to ship untested.","type":"text"}]},{"type":"paragraph","content":[{"text":"LAN-only no-auth carve-out.","type":"text","marks":[{"type":"strong"}]},{"text":" Some no-auth APIs are real hardware or private-network APIs that are testable only from the user's LAN (SSDP, mDNS, RFC1918/private hostnames, localhost-shaped appliance endpoints). If Phase 5 cannot reach the hardware because the generation host is not on that LAN, do not fabricate an API-key skip and do not hand-author ","type":"text"},{"text":"phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]},{"text":". Ask the user whether to hold the CLI or skip live dogfood and promote anyway. Only when the user explicitly chooses the skip/promote path, write ","type":"text"},{"text":"phase5-skip.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" with ","type":"text"},{"text":"skip_reason: \"lan-unreachable-from-generation-host\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"auth_context.type: \"none\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"auth_context.local_network_only: true","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"Do NOT proceed without asking. Do NOT substitute an ad-hoc smoke test. If some commands cannot be exercised because fixture values are missing, classify them as ","type":"text"},{"text":"BLOCKED_FIXTURE","type":"text","marks":[{"type":"code_inline"}]},{"text":" and file/fix the machine gap; do not use that as a reason to recommend Quick.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 2: Run the binary-owned test matrix","type":"text"}]},{"type":"paragraph","content":[{"text":"Full dogfood is not a judgment call about \"enough.\"","type":"text","marks":[{"type":"strong"}]},{"text":" Run the Printing Press-owned live matrix so command enumeration, exit-code capture, JSON parsing, and acceptance-marker writing are deterministic:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press dogfood --live \\\n --dir \"$CLI_WORK_DIR\" \\\n --level full \\\n --json \\\n --write-acceptance \"$PROOFS_DIR/phase5-acceptance.json\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"--level quick","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when the user selected Quick Check in Step 1.","type":"text"}]},{"type":"paragraph","content":[{"text":"The live dogfood runner enumerates the CLI's ","type":"text"},{"text":"agent-context","type":"text","marks":[{"type":"code_inline"}]},{"text":" command tree, runs help, happy-path, JSON-fidelity, and error-path checks where applicable, captures subprocess exit codes directly without shell pipes, and emits a structured report with pass/fail/skipped counts. Save the JSON report to:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/\u003cstamp>-dogfood-results.json","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"If the command exits non-zero, inspect the structured failures, fix the CLI, and rerun live dogfood. The runner writes ","type":"text"},{"text":"phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" on every outcome (","type":"text"},{"text":"status: \"pass\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" on success, ","type":"text"},{"text":"status: \"fail\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" with a ","type":"text"},{"text":"failure_summary","type":"text","marks":[{"type":"code_inline"}]},{"text":" block on failure), so the Phase 5.6 gate always has a marker to read. Do not hand-edit ","type":"text"},{"text":"phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]},{"text":"; it must come from the runner.","type":"text"}]},{"type":"paragraph","content":[{"text":"Quick check (auto-selected test subset):","type":"text","marks":[{"type":"strong"}]}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":" — auth valid, API reachable.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"3-5 list commands — return data, not empty.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"sync --full","type":"text","marks":[{"type":"code_inline"}]},{"text":" → data appears in local store.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"search \"\u003cterm from synced data>\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — finds results.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"One list command with ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--select \u003cfields>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"--csv","type":"text","marks":[{"type":"code_inline"}]},{"text":" — all produce correct output.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"One transcendence command — produces output that relates to the query (not just non-empty: verify relevance by checking output content contains query tokens or expected shape).","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Full dogfood adds to the matrix:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Every approved feature in the Phase 1.5 manifest gets a sample invocation with domain-realistic args.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For every command that takes an arg, one error-path test.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For every command that supports ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":", one JSON parse validation.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"For write-side commands (when API key + user consent): create test entity with obviously-test data, verify in subsequent list/get, test one mutation, verify change.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 3: Fix issues inline","type":"text"}]},{"type":"paragraph","content":[{"text":"When a test fails, fix it immediately — do not accumulate failures. Tag each fix:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CLI fix","type":"text","marks":[{"type":"strong"}]},{"text":" — specific to this printed CLI","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Printing Press issue","type":"text","marks":[{"type":"strong"}]},{"text":" — should be fixed in the Printing Press (note for retro)","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Step 4: Report and gate","type":"text"}]},{"type":"paragraph","content":[{"text":"Write a structured acceptance report and a machine-readable gate marker. The JSON marker is ","type":"text"},{"text":"required","type":"text","marks":[{"type":"strong"}]},{"text":" — Phase 5.6 and ","type":"text"},{"text":"publish validate","type":"text","marks":[{"type":"code_inline"}]},{"text":" check for it before promoting or publishing.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Acceptance Report: \u003capi>\n Level: Quick Check / Full Dogfood\n Tests: N/M passed\n Failures:\n - [command]: expected [X], got [Y]\n Fixes applied: K\n - [each fix]\n Printing Press issues: J\n - [each issue for retro]\n Gate: PASS / FAIL","type":"text"}]},{"type":"paragraph","content":[{"text":"Redact PII while authoring the report.","type":"text","marks":[{"type":"strong"}]},{"text":" When live API responses include an organization or workspace name, user email, assignee/collaborator name, or any other human-identifying string, describe the result generically instead of quoting the literal value:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"organization or workspace name -> \"the test workspace\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"authenticated user email/name -> \"the authenticated viewer\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"assignees or collaborators -> \"the highest-loaded assignee\" / \"the project lead\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"team identifiers such as ","type":"text"},{"text":"ENG","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"T2","type":"text","marks":[{"type":"code_inline"}]},{"text":" are OK when they are structural keys","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"The Phase 5.6 manuscript scan and publish-skill PII scan are defense in depth; keep PII out of the acceptance report from the moment you write it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Acceptance threshold:","type":"text","marks":[{"type":"strong"}]}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Quick Check: 5/6 core tests must pass. Auth (","type":"text"},{"text":"doctor","type":"text","marks":[{"type":"code_inline"}]},{"text":") or sync failure is automatic FAIL.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Full Dogfood: every mandatory test in the matrix must pass. A single broken flagship feature is automatic FAIL. Auth/sync failures are automatic FAIL.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Bugs surfaced in Phase 5 must be fixed now, not deferred.","type":"text","marks":[{"type":"strong"}]},{"text":" Do not offer the user a \"ship as-is and file for v0.2\" option when the fix is a 1-3 file edit. Present a \"Fix now\" (default), \"Fix critical only\", \"Hold (don't ship)\" set. Deferring bugs to a v0.2 backlog is an anti-pattern — context is freshest in-session, and a backlog that may never be revisited ships known-broken CLIs.","type":"text"}]},{"type":"paragraph","content":[{"text":"Gate = PASS:","type":"text","marks":[{"type":"strong"}]},{"text":" proceed to Phase 5.5 (Polish).","type":"text"}]},{"type":"paragraph","content":[{"text":"Gate = FAIL:","type":"text","marks":[{"type":"strong"}]},{"text":" fix issues inline (Step 3) and re-run failing tests, up to 2 fix loops. If the gate still fails after 2 loops, put the CLI on hold:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock release --cli \u003capi>-pp-cli","type":"text"}]},{"type":"paragraph","content":[{"text":"The working copy remains in ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":". Proceed to Phase 5.6 to archive manuscripts (archiving still happens on hold). Tag the failure reason in the acceptance report so the next run can learn from it.","type":"text"}]},{"type":"paragraph","content":[{"text":"See ","type":"text"},{"text":"references/dogfood-testing.md","type":"text","marks":[{"type":"link","attrs":{"href":"references/dogfood-testing.md","title":null}}]},{"text":" for additional guidance on common failure patterns and what NOT to test.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/\u003cstamp>-fix-\u003capi>-pp-cli-acceptance.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"For every outcome (PASS or FAIL), the runner writes:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"schema_version\": 1,\n \"api_name\": \"\u003capi>\",\n \"run_id\": \"\u003crun-id>\",\n \"status\": \"pass\",\n \"level\": \"quick|full\",\n \"matrix_size\": 42,\n \"tests_passed\": 42,\n \"tests_failed\": 0,\n \"auth_context\": {\n \"type\": \"none|api_key|bearer_token|cookie|composed|session_handshake\",\n \"api_key_available\": true,\n \"browser_session_available\": false\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"On ","type":"text"},{"text":"Gate: FAIL","type":"text","marks":[{"type":"code_inline"}]},{"text":" the same path is written with ","type":"text"},{"text":"status: \"fail\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" and a ","type":"text"},{"text":"failure_summary","type":"text","marks":[{"type":"code_inline"}]},{"text":" block grouping failures by category (","type":"text"},{"text":"transport_error","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"http_4xx","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"http_5xx","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"exit_nonzero","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"output_mismatch","type":"text","marks":[{"type":"code_inline"}]},{"text":" / ","type":"text"},{"text":"other","type":"text","marks":[{"type":"code_inline"}]},{"text":") plus the list of contributing commands. The Phase 5.6 gate routes this marker to the hold path; do not promote.","type":"text"}]},{"type":"paragraph","content":[{"text":"For ","type":"text"},{"text":"level: \"quick\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tests_failed","type":"text","marks":[{"type":"code_inline"}]},{"text":" may be ","type":"text"},{"text":"1","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when the Quick Check threshold still passed (","type":"text"},{"text":"matrix_size: 6","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tests_passed >= 5","type":"text","marks":[{"type":"code_inline"}]},{"text":") and the miss was not auth or sync related. For ","type":"text"},{"text":"level: \"full\"","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"tests_failed","type":"text","marks":[{"type":"code_inline"}]},{"text":" must be ","type":"text"},{"text":"0","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]},{"type":"paragraph","content":[{"text":"If Phase 5 is legitimately skipped because the API requires API-key or bearer auth and no credential was available, write:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/phase5-skip.json","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"schema_version\": 1,\n \"api_name\": \"\u003capi>\",\n \"run_id\": \"\u003crun-id>\",\n \"status\": \"skip\",\n \"level\": \"none\",\n \"skip_reason\": \"auth_required_no_credential\",\n \"auth_context\": {\n \"type\": \"api_key|bearer_token|oauth2\",\n \"api_key_available\": false,\n \"browser_session_available\": false\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"If Phase 5 is legitimately skipped because a no-auth API is LAN-only and the generation host cannot reach the user's LAN hardware, write:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/phase5-skip.json","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"schema_version\": 1,\n \"api_name\": \"\u003capi>\",\n \"run_id\": \"\u003crun-id>\",\n \"status\": \"skip\",\n \"level\": \"none\",\n \"skip_reason\": \"lan-unreachable-from-generation-host\",\n \"auth_context\": {\n \"type\": \"none\",\n \"api_key_available\": false,\n \"browser_session_available\": false,\n \"local_network_only\": true\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" write a skip marker for ordinary ","type":"text"},{"text":"auth.type: none","type":"text","marks":[{"type":"code_inline"}]},{"text":" cloud/public APIs. No-auth APIs are testable and require ","type":"text"},{"text":"phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" unless they match the LAN-only carve-out above. Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" use missing API key as the skip reason for cookie, composed, or session-handshake auth; those require browser session proof or a hold decision.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 5.5: Polish","type":"text"}]},{"type":"paragraph","content":[{"text":"Always runs.","type":"text","marks":[{"type":"strong"}]},{"text":" Invoke the ","type":"text"},{"text":"printing-press-polish","type":"text","marks":[{"type":"code_inline"}]},{"text":" skill to run diagnostics, fix quality issues, and return a delta. The polish skill carries ","type":"text"},{"text":"context: fork","type":"text","marks":[{"type":"code_inline"}]},{"text":" in its frontmatter, so its diagnostic-fix-rediagnose loop runs in a forked context — diagnostic spam, fix iterations, and re-audits stay scoped to the polish session and don't pollute this generation flow. The skill is autonomous — no user input needed. The goal is to ship the best CLI possible, not the fastest.","type":"text"}]},{"type":"paragraph","content":[{"text":"Before invoking polish, collect the Phase 3 transcendence gate state and include it in the polish input bundle:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"phase3_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>","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoke via the Skill tool (","type":"text"},{"text":"foreground","type":"text","marks":[{"type":"strong"}]},{"text":" — must complete before promoting). Pass ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" as the first line of ","type":"text"},{"text":"args","type":"text","marks":[{"type":"code_inline"}]},{"text":", followed by the Phase 3 bundle:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Skill(\n skill: \"cli-printing-press:printing-press-polish\",\n args: \"$CLI_WORK_DIR\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)","type":"text"}]},{"type":"paragraph","content":[{"text":"Polish must treat ","type":"text"},{"text":"prior_sub60_reprint: true","type":"text","marks":[{"type":"code_inline"}]},{"text":" plus any missing row as ","type":"text"},{"text":"ship_recommendation: hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" unless ","type":"text"},{"text":"partial_transcendence_override","type":"text","marks":[{"type":"code_inline"}]},{"text":" names the accepted exception. This keeps mid-pipeline polish from recommending ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" for a reprint that regressed from the approved manifest before Phase 6 sees the artifact.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pass ","type":"text","marks":[{"type":"strong"}]},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (the absolute working-dir path), not the API slug.","type":"text","marks":[{"type":"strong"}]},{"text":" Phase 5.5 fires before Phase 5.6 promotes the working CLI to the library, so ","type":"text"},{"text":"$PRESS_LIBRARY/\u003cslug>/","type":"text","marks":[{"type":"code_inline"}]},{"text":" either doesn't exist yet or contains the ","type":"text"},{"text":"prior","type":"text","marks":[{"type":"em"}]},{"text":" run's CLI. If you paraphrase the args to the slug (e.g., ","type":"text"},{"text":"args: \"producthunt\"","type":"text","marks":[{"type":"code_inline"}]},{"text":"), polish silently operates on the stale library copy.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not pass ","type":"text","marks":[{"type":"strong"}]},{"text":"--standalone","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in ","type":"text","marks":[{"type":"strong"}]},{"text":"args","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" Polish's Publish Offer is gated on caller mode (see polish SKILL.md \"Publish Offer\"): slash-command invocations or Skill-tool invocations carrying ","type":"text"},{"text":"--standalone","type":"text","marks":[{"type":"code_inline"}]},{"text":" run the offer; everything else defers. Phase 5.5 is mid-pipeline — main SKILL owns the publish flow at Phase 6 — so this invocation must remain flag-free. Passing ","type":"text"},{"text":"--standalone","type":"text","marks":[{"type":"code_inline"}]},{"text":" here would re-introduce the failure mode the flag was added to prevent: polish forks the public library, sets global git config, and opens a real PR before the working CLI has been promoted.","type":"text"}]},{"type":"paragraph","content":[{"text":"The polish skill runs the full diagnostic-fix-rediagnose loop including MCP tool quality polish (via ","type":"text"},{"text":"cli-printing-press tools-audit","type":"text","marks":[{"type":"code_inline"}]},{"text":" plus the playbook at ","type":"text"},{"text":"references/tools-polish.md","type":"text","marks":[{"type":"code_inline"}]},{"text":") and ends its response with a ","type":"text"},{"text":"---POLISH-RESULT---","type":"text","marks":[{"type":"code_inline"}]},{"text":" block containing scorecard/verify/tools-audit before/after, fixes applied, and a ship recommendation.","type":"text"}]},{"type":"paragraph","content":[{"text":"Parse the result block. Display the delta to the user:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Polish pass:\n Verify: 86% → 93% (+7%)\n Scorecard: 92 → 94 (+2)\n Tools-audit: 76 → 0 pending findings\n Fixed: [summary of fixes_applied from result]","type":"text"}]},{"type":"paragraph","content":[{"text":"Verdict override:","type":"text","marks":[{"type":"strong"}]},{"text":" If the polish skill's ","type":"text"},{"text":"ship_recommendation","type":"text","marks":[{"type":"code_inline"}]},{"text":" is ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the Phase 4 verdict was ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":", downgrade to ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":". Release the lock without promoting.","type":"text"}]},{"type":"paragraph","content":[{"text":"Mid-pipeline polish does ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" run ","type":"text"},{"text":"publish-validate","type":"text","marks":[{"type":"code_inline"}]},{"text":" — that gate is the publish skill's responsibility at Phase 6, where the prerequisites it checks (manifest.printer from ","type":"text"},{"text":"git config github.user","type":"text","marks":[{"type":"code_inline"}]},{"text":", packaged ","type":"text"},{"text":"tools-manifest.json","type":"text","marks":[{"type":"code_inline"}]},{"text":", phase5 acceptance proof under ","type":"text"},{"text":"$CLI_DIR/.manuscripts/\u003crun>/proofs/","type":"text","marks":[{"type":"code_inline"}]},{"text":") are actually satisfied. Polish emits ","type":"text"},{"text":"publish_validate_before: skipped (mid-pipeline)","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"publish_validate_after: skipped (mid-pipeline)","type":"text","marks":[{"type":"code_inline"}]},{"text":" in this invocation; treat those values as informational, never as a hold signal. A first-time user without ","type":"text"},{"text":"git config github.user","type":"text","marks":[{"type":"code_inline"}]},{"text":" set will no longer see their CLI-level run downgraded to ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" because of a publish prerequisite that the press itself owns satisfying.","type":"text"}]},{"type":"paragraph","content":[{"text":"Write the polish skill's full response to:","type":"text"}]},{"type":"paragraph","content":[{"text":"$PROOFS_DIR/\u003cstamp>-fix-\u003capi>-pp-cli-polish.md","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 5.6: Promote and Archive","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Acceptance gate check","type":"text"}]},{"type":"paragraph","content":[{"text":"Before promoting, verify the Phase 5 JSON gate marker:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"$PROOFS_DIR/phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists with ","type":"text"},{"text":"status: \"pass\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" → proceed to promote.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"$PROOFS_DIR/phase5-acceptance.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists with ","type":"text"},{"text":"status: \"fail\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" → CLI is on hold. Do NOT promote. Proceed to Archive Manuscripts.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If ","type":"text"},{"text":"$PROOFS_DIR/phase5-skip.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" exists and the auth-aware skip is valid → proceed to promote.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"If neither JSON marker exists → Phase 5 was skipped or not recorded. Go back and run it, or write the valid skip marker. Do NOT promote without one.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Promote to Library","type":"text"}]},{"type":"paragraph","content":[{"text":"If the shipcheck verdict is ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"or","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":", promote the verified CLI from the working directory to the library. This must happen BEFORE archiving — the CLI in the library is the primary deliverable, and Phase 6's publish path expects ","type":"text"},{"text":"$PRESS_LIBRARY/\u003capi>/","type":"text","marks":[{"type":"code_inline"}]},{"text":" to hold the current run.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pick the promote path by whether the library already holds hand-authored content.","type":"text","marks":[{"type":"strong"}]},{"text":" ","type":"text"},{"text":"lock promote --dir","type":"text","marks":[{"type":"code_inline"}]},{"text":" performs an ","type":"text"},{"text":"atomic swap","type":"text","marks":[{"type":"strong"}]},{"text":" of ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" over ","type":"text"},{"text":"$PRESS_LIBRARY/\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" — every file in the library that is not in the fresh tree is gone after the swap. Whole hand-authored files (a separate ","type":"text"},{"text":"internal/syncer/","type":"text","marks":[{"type":"code_inline"}]},{"text":" package, novel-feature command files under ","type":"text"},{"text":"internal/cli/","type":"text","marks":[{"type":"code_inline"}]},{"text":" without the ","type":"text"},{"text":"// Generated by ...","type":"text","marks":[{"type":"code_inline"}]},{"text":" header, hand-built migration files under ","type":"text"},{"text":"internal/store/","type":"text","marks":[{"type":"code_inline"}]},{"text":") survive a ","type":"text"},{"text":"cli-printing-press regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" pass but are wiped by a bare swap. This is the same preservation dynamic called out under ","type":"text"},{"text":"Hand-edits must be regen-mergeable.","type":"text","marks":[{"type":"link","attrs":{"href":"#hand-edit-durability","title":null}},{"type":"strong"}]},{"text":"; the orchestration here must honor it.","type":"text"}]},{"type":"paragraph","content":[{"text":"Detect hand-authored content in the existing library:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"LIB_TARGET=\"$PRESS_LIBRARY/\u003capi>\"\nNOVEL_COUNT=0\nif [ -d \"$LIB_TARGET\" ]; then\n MANIFEST=\"$LIB_TARGET/.printing-press.json\"\n HAS_NOVEL_FIELD=false\n if [ -f \"$MANIFEST\" ]; then\n # `novel_features` is the canonical count when the field is present.\n # Distinguish absent (older manifest predating the field) from explicit zero —\n # `jq '.novel_features // [] | length'` collapses both to 0, which would\n # silently route older CLIs through the destructive Path A swap.\n HAS_NOVEL_FIELD=$(jq 'has(\"novel_features\")' \"$MANIFEST\" 2>/dev/null || echo false)\n fi\n if [ \"$HAS_NOVEL_FIELD\" = \"true\" ]; then\n NOVEL_COUNT=$(jq -r '.novel_features | length' \"$MANIFEST\" 2>/dev/null || echo 0)\n else\n # File probe fallback fires in three cases: manifest missing entirely\n # (interrupted run, restored-from-backup state, much older CLI), manifest\n # present but predates the `novel_features` field, and manifest present\n # but corrupt-enough that `jq has()` errored. Any *.go file under\n # internal/cli/, internal/syncer/, or internal/store/ whose first 20\n # lines lack the \"Generated by CLI Printing Press\" header is hand-authored;\n # one such file is enough to route through Path B.\n for dir in \"$LIB_TARGET/internal/cli\" \"$LIB_TARGET/internal/syncer\" \"$LIB_TARGET/internal/store\"; do\n [ -d \"$dir\" ] || continue\n while IFS= read -r f; do\n if ! head -n 20 \"$f\" 2>/dev/null | grep -q \"Generated by CLI Printing Press\"; then\n NOVEL_COUNT=1\n break 2\n fi\n done \u003c \u003c(find \"$dir\" -type f -name '*.go')\n done\n fi\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"The presence check (","type":"text"},{"text":"jq 'has(\"novel_features\")'","type":"text","marks":[{"type":"code_inline"}]},{"text":") and the manifest existence check are independent. A library can exist with a hand-authored layer but no manifest at all (interrupted run, restored-from-backup state, much older CLI), so gating the file-probe fallback behind ","type":"text"},{"text":"[ -f manifest ]","type":"text","marks":[{"type":"code_inline"}]},{"text":" would leave that case routing through the destructive Path A swap.","type":"text"}]},{"type":"paragraph","content":[{"text":"Path A — first print or no hand-authored content (","type":"text","marks":[{"type":"strong"}]},{"text":"! -d \"$LIB_TARGET\"","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" or ","type":"text","marks":[{"type":"strong"}]},{"text":"NOVEL_COUNT == 0","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":").","type":"text","marks":[{"type":"strong"}]},{"text":" Use the destructive swap. Fast path; no library content to preserve:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Atomic swap: copies working dir, writes manifest, updates run pointer, releases lock.\ncli-printing-press lock promote --cli \u003capi>-pp-cli --dir \"$CLI_WORK_DIR\"","type":"text"}]},{"type":"paragraph","content":[{"text":"The ","type":"text"},{"text":"promote","type":"text","marks":[{"type":"code_inline"}]},{"text":" command handles the full sequence: stages the working directory, atomically swaps it into ","type":"text"},{"text":"$PRESS_LIBRARY/\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" (slug-keyed), writes the ","type":"text"},{"text":".printing-press.json","type":"text","marks":[{"type":"code_inline"}]},{"text":" manifest, updates the ","type":"text"},{"text":"CurrentRunPointer","type":"text","marks":[{"type":"code_inline"}]},{"text":", and releases the lock — all in one step. The ","type":"text"},{"text":"--cli","type":"text","marks":[{"type":"code_inline"}]},{"text":" flag accepts the CLI binary name; the Go code translates to the slug-keyed library path internally.","type":"text"}]},{"type":"paragraph","content":[{"text":"Path B — reprint over a library with hand-authored content (","type":"text","marks":[{"type":"strong"}]},{"text":"-d \"$LIB_TARGET\"","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" AND ","type":"text","marks":[{"type":"strong"}]},{"text":"NOVEL_COUNT > 0","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":").","type":"text","marks":[{"type":"strong"}]},{"text":" Use ","type":"text"},{"text":"regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" to fold the fresh tree into the live library before promotion. ","type":"text"},{"text":"regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" classifies every Go file under ","type":"text"},{"text":"internal/","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"cmd/","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the fresh tree, overwrites safely-templated files, re-injects ","type":"text"},{"text":"AddCommand","type":"text","marks":[{"type":"code_inline"}]},{"text":" calls in ","type":"text"},{"text":"root.go","type":"text","marks":[{"type":"code_inline"}]},{"text":" and resource-parents that the fresh tree lacks, and leaves files with hand-edited additions (","type":"text"},{"text":"TEMPLATED-WITH-ADDITIONS","type":"text","marks":[{"type":"code_inline"}]},{"text":") untouched for human review. ","type":"text"},{"text":"--apply","type":"text","marks":[{"type":"code_inline"}]},{"text":" writes via stage-and-swap-with-recovery, so partial failure can never lose data.","type":"text"}]},{"type":"paragraph","content":[{"text":"regen-merge --apply","type":"text","marks":[{"type":"code_inline"}]},{"text":" exits 0 even when it leaves ","type":"text"},{"text":"TEMPLATED-WITH-ADDITIONS","type":"text","marks":[{"type":"code_inline"}]},{"text":" files (the human-review verdicts are reported, not raised as errors). The halt condition must be checked explicitly against the report — capture ","type":"text"},{"text":"--json","type":"text","marks":[{"type":"code_inline"}]},{"text":" and inspect the verdict counts:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"REGEN_REPORT=\"$PROOFS_DIR/regen-merge-report.json\"\nif ! cli-printing-press regen-merge \"$LIB_TARGET\" \\\n --fresh \"$CLI_WORK_DIR\" --apply --json > \"$REGEN_REPORT\"; then\n # Real error (input error, apply failure). Release the lock — it was\n # acquired upstream by the press pipeline; regen-merge does not own it —\n # and surface the failure to the user.\n cli-printing-press lock release --cli \u003capi>-pp-cli\n echo \"regen-merge --apply failed; see $REGEN_REPORT\" >&2\n exit 1\nfi\n\n# Halt on review-required verdicts before promoting. regen-merge exits 0\n# in these cases; the JSON report is the source of truth.\nNEEDS_REVIEW=$(jq '[.files[] | select(.verdict == \"TEMPLATED-WITH-ADDITIONS\"\n or .verdict == \"TEMPLATED-BODY-DRIFT\"\n or .verdict == \"TEMPLATED-VALUE-DRIFT\"\n or .verdict == \"NOVEL-COLLISION\")] | length' \"$REGEN_REPORT\")\nif [ \"$NEEDS_REVIEW\" -gt 0 ]; then\n # Release the lock so the next reprint of this CLI is not blocked until\n # timeout. lock promote would have released it; the halt path must too.\n cli-printing-press lock release --cli \u003capi>-pp-cli\n echo \"regen-merge flagged $NEEDS_REVIEW file(s) for human review. \" \\\n \"Inspect $REGEN_REPORT, resolve inline hand-edits, then re-run.\" >&2\n exit 1\nfi","type":"text"}]},{"type":"paragraph","content":[{"text":"After ","type":"text"},{"text":"regen-merge","type":"text","marks":[{"type":"code_inline"}]},{"text":" succeeds with no review-required verdicts, the live library directory is the new run. Do ","type":"text"},{"text":"not","type":"text","marks":[{"type":"strong"}]},{"text":" then call ","type":"text"},{"text":"lock promote --dir \"$CLI_WORK_DIR\"","type":"text","marks":[{"type":"code_inline"}]},{"text":" — that would atomically swap the working dir over the just-merged library and undo the preservation. Promote in place: point ","type":"text"},{"text":"lock promote --dir","type":"text","marks":[{"type":"code_inline"}]},{"text":" at the library itself so the manifest write, run-pointer update, and lock release still run. Two extra steps are required compared to Path A:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Copy the current run's PII-polish ledger into ","type":"text"},{"text":"$LIB_TARGET","type":"text","marks":[{"type":"code_inline"}]},{"text":" before promote. ","type":"text"},{"text":"lock promote --dir","type":"text","marks":[{"type":"code_inline"}]},{"text":" internally runs ","type":"text"},{"text":"validatePIIGateForPromote","type":"text","marks":[{"type":"code_inline"}]},{"text":" against the target directory, which reads ","type":"text"},{"text":"$LIB_TARGET/.printing-press-pii-polish.json","type":"text","marks":[{"type":"code_inline"}]},{"text":". After ","type":"text"},{"text":"regen-merge --apply","type":"text","marks":[{"type":"code_inline"}]},{"text":" the generator-emitted Go files have fresh line numbers, so the prior reprint's ledger (still sitting in ","type":"text"},{"text":"$LIB_TARGET","type":"text","marks":[{"type":"code_inline"}]},{"text":" from the last atomic swap) has stale ","type":"text"},{"text":"{file, line, kind, span}","type":"text","marks":[{"type":"code_inline"}]},{"text":" identity keys for those files and previously-accepted findings re-surface as pending — the gate fails before the swap and the lock stays held. Bringing the current run's ledger over fixes the identity match for generator-emitted files; hand-authored files with new findings still surface correctly as pending.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Guard the promote with an explicit lock-release on failure. Unlike Path A, where a promote-gate failure simply leaves the working dir alone, a Path B failure leaves the lock held on the live library because the gate fires before the swap and before ","type":"text"},{"text":"ReleaseLock","type":"text","marks":[{"type":"code_inline"}]},{"text":". Mirror the lock-release guards from the regen-merge error branches above.","type":"text"}]}]}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"if [ -f \"$CLI_WORK_DIR/.printing-press-pii-polish.json\" ]; then\n cp \"$CLI_WORK_DIR/.printing-press-pii-polish.json\" \"$LIB_TARGET/.printing-press-pii-polish.json\"\nelse\n # Current run produced no PII findings (clean API or polish skipped).\n # Remove the stale prior-reprint ledger so the gate sees a clean state\n # — otherwise the old identity keys would replay against freshly\n # line-shifted generator files and surface false-positive pendings.\n rm -f \"$LIB_TARGET/.printing-press-pii-polish.json\"\nfi\ncli-printing-press lock promote --cli \u003capi>-pp-cli --dir \"$LIB_TARGET\" || {\n cli-printing-press lock release --cli \u003capi>-pp-cli\n echo \"lock promote failed for $LIB_TARGET; lock released. \" \\\n \"Inspect the PII gate output above and resolve before re-running.\" >&2\n exit 1\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"TEMPLATED-WITH-ADDITIONS","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the other review verdicts represent inline hand-edits to generator-emitted files that need human review (see ","type":"text"},{"text":"Hand-edits must be regen-mergeable.","type":"text","marks":[{"type":"link","attrs":{"href":"#hand-edit-durability","title":null}},{"type":"strong"}]},{"text":" for the separate-file pattern that avoids this in future). The dry-run report (omit ","type":"text"},{"text":"--apply","type":"text","marks":[{"type":"code_inline"}]},{"text":") is the right tool for inspection once the halt path fires.","type":"text"}]},{"type":"paragraph","content":[{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" is promoted (on either path) because the verdict means \"the CLI is shippable with documented, non-blocking gaps\" — the gaps are recorded in the README's ","type":"text"},{"text":"## Known Gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" block and the user opts in via Phase 6's publish prompt. Treating ship-with-gaps as un-promotable would strand the verified working copy and leave the library on a stale prior run.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the shipcheck verdict is ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":", the lock was already released in Phase 4. Do NOT promote on either path. The working copy stays in ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" and is not copied to the library.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Archive Manuscripts","type":"text"}]},{"type":"paragraph","content":[{"text":"Archive the run's research, proofs, and discovery artifacts to ","type":"text"},{"text":"$PRESS_MANUSCRIPTS/","type":"text","marks":[{"type":"code_inline"}]},{"text":" ","type":"text"},{"text":"unconditionally","type":"text","marks":[{"type":"strong"}]},{"text":" after promotion (or after lock release for ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdicts). This happens regardless of the shipcheck verdict — even a ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" run produces research and proofs that future runs should be able to reuse.","type":"text"}]},{"type":"paragraph","content":[{"text":"Archiving and publishing are separate concerns. Archiving preserves research for future ","type":"text"},{"text":"/printing-press","type":"text","marks":[{"type":"code_inline"}]},{"text":" runs on the same API. Publishing ships the CLI to the library repo. A run that isn't ready to publish still produces valuable research.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Archive under API slug (e.g., steam-web), matching the slug-keyed library layout.\nAPI_SLUG=\"\u003capi>\"\nmkdir -p \"$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID\"\ncp -r \"$RESEARCH_DIR\" \"$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/research\" 2>/dev/null || true\ncp -f \"$API_RUN_DIR/research.json\" \"$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/research.json\" 2>/dev/null || true\ncp -r \"$PROOFS_DIR\" \"$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/proofs\" 2>/dev/null || true\n\n# Archive discovery artifacts (browser-sniff captures, URL lists, traffic analysis, browser-sniff report).\n# Session state lives outside $DISCOVERY_DIR (see Run Initialization), so the\n# archive cannot pick it up. The legacy rm is a no-op safety net for an\n# in-flight $DISCOVERY_DIR carried over from a pre-isolation run.\nrm -f \"$DISCOVERY_DIR/session-state.json\" 2>/dev/null || true\n\n# Strip response bodies from HAR before archiving to control size.\nif [ -d \"$DISCOVERY_DIR\" ]; then\n for har in \"$DISCOVERY_DIR\"/browser-sniff-capture.har \"$DISCOVERY_DIR\"/browser-sniff-capture.json; do\n if [ -f \"$har\" ] && command -v jq >/dev/null 2>&1; then\n jq 'del(.log.entries[].response.content.text)' \"$har\" > \"${har}.stripped\" 2>/dev/null && mv \"${har}.stripped\" \"$har\" || rm -f \"${har}.stripped\"\n fi\n done\n cp -r \"$DISCOVERY_DIR\" \"$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/discovery\" 2>/dev/null || true\nfi\n\n# Wipe live-auth scratch dir now that the run is archived. The directory lives\n# under ${TMPDIR:-/tmp}, so OS-level tmp reaping is the long-tail fallback, but\n# we clean explicitly so back-to-back runs do not accumulate session state.\nrm -rf \"$SESSION_DIR\" 2>/dev/null || true","type":"text"}]},{"type":"paragraph","content":[{"text":"MANDATORY: After archiving, you MUST proceed to Phase 6 below. Do not print a summary and stop. Do not treat archiving as the end of the run. The run ends when the user has been asked about next steps via the ship-path or hold-path menu.","type":"text","marks":[{"type":"strong"}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Phase 6: Next Steps","type":"text"}]},{"type":"paragraph","content":[{"text":"This phase is NOT optional.","type":"text","marks":[{"type":"strong"}]},{"text":" Every run MUST reach this point — both ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" and ","type":"text"},{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdicts get a menu. Do not skip it.","type":"text"}]},{"type":"paragraph","content":[{"text":"After archiving, offer the user the next action. The menu shape is determined by the shipcheck verdict and (for ship runs) by polish's self-assessment.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Gate","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the most recent shipcheck verdict:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"if Phase 5 reran shipcheck after a live-smoke fix, use that rerun verdict","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"otherwise use the Phase 4 verdict","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"if Phase 5.5 polish downgraded the verdict (","type":"text"},{"text":"ship_recommendation: hold","type":"text","marks":[{"type":"code_inline"}]},{"text":"), use the downgraded verdict","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"Route to the menu shape:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" or ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"ship-path menu","type":"text","marks":[{"type":"strong"}]},{"text":" (below)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"hold","type":"text","marks":[{"type":"code_inline"}]},{"text":" → ","type":"text"},{"text":"hold-path menu","type":"text","marks":[{"type":"strong"}]},{"text":" (below). The CLI did not promote to library; the working copy stays in ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":".","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Check for existing PR (ship-path only)","type":"text"}]},{"type":"paragraph","content":[{"text":"Run a lightweight check for your own open publish PR. The ","type":"text"},{"text":"--author @me","type":"text","marks":[{"type":"code_inline"}]},{"text":" filter avoids matching someone else's PR for the same API slug.","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"gh pr list --repo mvanhorn/printing-press-library --head \"feat/\u003capi>\" --state open --author @me --json number,url --jq '.[0]' 2>/dev/null","type":"text"}]},{"type":"paragraph","content":[{"text":"If this fails (gh not authenticated, network error, etc.), continue without PR context — the publish skill will handle auth in its own Step 1.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Ship-path menu","type":"text"}]},{"type":"paragraph","content":[{"text":"Read the polish result block emitted by Phase 5.5. The menu and recommendation are data-driven so the user is never asked to weigh \"Polish again\" against \"Publish\" when polish itself just decided another pass would not help.","type":"text"}]},{"type":"paragraph","content":[{"text":"Pick the recommended action:","type":"text","marks":[{"type":"strong"}]}]},{"type":"table","attrs":{"layout":null},"content":[{"type":"tr","content":[{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Polish state","type":"text"}]}]},{"type":"th","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Recommendation","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" empty","type":"text"}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Publish","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" non-empty + ","type":"text"},{"text":"further_polish_recommended: yes","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Polish again","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" non-empty + ","type":"text"},{"text":"further_polish_recommended: no","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Publish","type":"text","marks":[{"type":"strong"}]},{"text":" if the remaining issues do not touch the CLI's headline commands; surface the trade-off and let the user pick between ","type":"text"},{"text":"Publish","type":"text","marks":[{"type":"strong"}]},{"text":" (as-is; README is not auto-updated) and ","type":"text"},{"text":"Done","type":"text","marks":[{"type":"strong"}]},{"text":" otherwise","type":"text"}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"further_polish_recommended: yes","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Polish again","type":"text","marks":[{"type":"strong"}]}]}]}]},{"type":"tr","content":[{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" + ","type":"text"},{"text":"further_polish_recommended: no","type":"text","marks":[{"type":"code_inline"}]}]}]},{"type":"td","attrs":{"colspan":1,"rowspan":1,"colwidth":null,"alignment":""},"content":[{"type":"paragraph","content":[{"text":"Publish","type":"text","marks":[{"type":"strong"}]},{"text":" (gaps already in README's ","type":"text"},{"text":"## Known Gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":"; polish's ship logic enforces this for ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":") or ","type":"text"},{"text":"Done","type":"text","marks":[{"type":"strong"}]},{"text":" — agent judgment from the actual gap content","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Suppress \"Polish again\" entirely when ","type":"text","marks":[{"type":"strong"}]},{"text":"further_polish_recommended: no","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" Polish has already decided another pass would not help; offering the option anyway is friction. Surface ","type":"text"},{"text":"further_polish_reasoning","type":"text","marks":[{"type":"code_inline"}]},{"text":" as context so the user sees the call.","type":"text"}]},{"type":"paragraph","content":[{"text":"Always available:","type":"text","marks":[{"type":"strong"}]},{"text":" Publish, Done. Retro is not on this menu — it is offered as a post-publish tail (see \"If Publish now\" below).","type":"text"}]},{"type":"paragraph","content":[{"text":"Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":". The recommended option leads, carries the ","type":"text"},{"text":"(recommended)","type":"text","marks":[{"type":"code_inline"}]},{"text":" label, and a leading ","type":"text"},{"text":"Recommendation:","type":"text","marks":[{"type":"code_inline"}]},{"text":" line states the call explicitly. Three reinforcing channels so the user does not have to infer from ordering.","type":"text"}]},{"type":"paragraph","content":[{"text":"Substitute placeholders before showing the prompt.","type":"text","marks":[{"type":"strong"}]},{"text":" The example prompts below use ","type":"text"},{"text":"\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cN>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cscore>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cpass-rate>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cPR_URL>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"\u003cfurther_polish_reasoning>","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"$PRESS_LIBRARY/\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" as fill-ins. Replace each with the concrete value (the API slug, the actual count, the parsed polish-result string, the expanded shell-variable path, etc.) so the user sees real names and paths, not literal placeholder text. The same rule applies to the hold-path menu below.","type":"text"}]},{"type":"paragraph","content":[{"text":"If an existing open PR was found:","type":"text","marks":[{"type":"strong"}]}]},{"type":"paragraph","content":[{"text":"The existing-PR branch still honors polish's ","type":"text"},{"text":"further_polish_recommended","type":"text","marks":[{"type":"code_inline"}]},{"text":" signal. When polish thinks another pass would help, offer it as the recommended action ahead of the PR update — pushing a CLI with closable issues into an existing PR is no better than into a new one.","type":"text"}]},{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"further_polish_recommended: yes","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003capi> passed shipcheck. There's an open publish PR (#\u003cPR-number>). Polish flagged \u003ctype-qualified summary of remaining issues> as closable — '\u003cfurther_polish_reasoning>'.","type":"text"}]},{"type":"paragraph","content":[{"text":"Recommendation: Polish again before updating the PR.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polish again","type":"text","marks":[{"type":"strong"}]},{"text":" (recommended) — close the remaining issues, then update the PR","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Update PR #\u003cPR-number>","type":"text","marks":[{"type":"strong"}]},{"text":" — push this version to the existing PR as-is","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — I'm done","type":"text","marks":[{"type":"strong"}]},{"text":"\"","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"When ","type":"text"},{"text":"further_polish_recommended: no","type":"text","marks":[{"type":"code_inline"}]},{"text":" (or ","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" empty):","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003capi> passed shipcheck. There's an open publish PR (#\u003cPR-number>). Want to update it with this version?\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — update PR #\u003cPR-number>","type":"text","marks":[{"type":"strong"}]},{"text":" (recommended) — re-validate, re-package, and push to the existing PR","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — I'm done","type":"text","marks":[{"type":"strong"}]},{"text":"\"","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"Polish converged clean","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" empty, ","type":"text"},{"text":"further_polish_recommended: no","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003capi> passed shipcheck (\u003cscore>/100, verify \u003cpass-rate>%). Polish ran cleanly — nothing more to fix.","type":"text"}]},{"type":"paragraph","content":[{"text":"Recommendation: Publish.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Publish now","type":"text","marks":[{"type":"strong"}]},{"text":" (recommended) — validate, package, and open a PR","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Done for now","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Polish thinks another pass would help","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"further_polish_recommended: yes","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"paragraph","content":[{"text":"When summarizing remaining issues to the user, type-qualify the count instead of just printing ","type":"text"},{"text":"\u003cN> issues","type":"text","marks":[{"type":"code_inline"}]},{"text":". Pull the categories from the polish result block (","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" entries usually carry their type — verify failure, README gap, MCP description, etc.). For example: \"2 verify failures and 1 README gap remain\" rather than \"3 issues remain.\"","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003capi> passed shipcheck (\u003cscore>/100, verify \u003cpass-rate>%). \u003ctype-qualified summary of remaining issues>.","type":"text"}]},{"type":"paragraph","content":[{"text":"Polish notes: '\u003cfurther_polish_reasoning>'","type":"text"}]},{"type":"paragraph","content":[{"text":"Recommendation: Polish again before publishing.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polish again","type":"text","marks":[{"type":"strong"}]},{"text":" (recommended) — close the remaining issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Publish now","type":"text","marks":[{"type":"strong"}]},{"text":" — ship as-is","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Done for now","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Polish opted out of recommending more polish","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":" non-empty, ","type":"text"},{"text":"further_polish_recommended: no","type":"text","marks":[{"type":"code_inline"}]},{"text":"):","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003capi> passed shipcheck (\u003cscore>/100, verify \u003cpass-rate>%). \u003ctype-qualified summary of remaining issues> — polish could not auto-resolve these.","type":"text"}]},{"type":"paragraph","content":[{"text":"Polish notes: '\u003cfurther_polish_reasoning>'","type":"text"}]},{"type":"paragraph","content":[{"text":"Recommendation: \u003cPublish | Done — your call from the gap content>.","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Publish now","type":"text","marks":[{"type":"strong"}]},{"text":" — ship as-is. The remaining issues are not auto-added to README; if any are user-facing, you'll need to update the README's ","type":"text"},{"text":"## Known Gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" section in the publish PR before merging","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Done for now","type":"text","marks":[{"type":"strong"}]},{"text":" — leave the CLI in \u003cexpanded $PRESS_LIBRARY/\u003capi> path> and address remaining issues manually before any later publish","type":"text"}]}]}]}]},{"type":"paragraph","content":[{"text":"This prompt fires only for ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdicts (not ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":"), so polish has not auto-written ","type":"text"},{"text":"## Known Gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":". Polish auto-writes the section only when the verdict is ","type":"text"},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" (see polish SKILL.md \"Ship logic\"). On a ","type":"text"},{"text":"ship","type":"text","marks":[{"type":"code_inline"}]},{"text":" verdict with non-empty ","type":"text"},{"text":"remaining_issues","type":"text","marks":[{"type":"code_inline"}]},{"text":", polish has judged those issues acceptable to publish without a verdict bump — but the user may still want to surface user-facing items in README before merging the PR.","type":"text"}]},{"type":"paragraph","content":[{"text":"If the shipcheck report contains a ","type":"text"},{"text":"## Known Gaps","type":"text","marks":[{"type":"code_inline"}]},{"text":" block, prepend: \"Note: shipcheck documented known gaps (see the shipcheck report above).\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If \"Publish now\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoke ","type":"text"},{"text":"/printing-press-publish \u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":". The publish skill handles everything from there — fork, branch, manifest checks, ","type":"text"},{"text":"cli-skills/pp-\u003capi-slug>/SKILL.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" regen, push, and PR creation.","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not improvise the publish flow.","type":"text","marks":[{"type":"strong"}]},{"text":" Even though the publish skill itself runs ","type":"text"},{"text":"gh repo fork","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"git push","type":"text","marks":[{"type":"code_inline"}]},{"text":", and ","type":"text"},{"text":"gh pr create --repo mvanhorn/printing-press-library …","type":"text","marks":[{"type":"code_inline"}]},{"text":" internally, running those commands by hand from this phase skips the preflight checks (printer sentinel validation, manifest shape, vendor-spec PII scope, govulncheck on the changed module) and the public library's own ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" requirements that the skill mirrors. The CWD here is ","type":"text"},{"text":"cli-printing-press","type":"text","marks":[{"type":"code_inline"}]},{"text":", so the public library's ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" is not loaded — the skill is the only entry point that brings those rules into context. If the publish skill fails, fix the underlying issue (or report it as a machine bug); do not bypass it. See ","type":"text"},{"text":"AGENTS.md","type":"text","marks":[{"type":"link","attrs":{"href":"AGENTS.md","title":null}},{"type":"code_inline"}]},{"text":" \"Publishing to the Public Library\" for the full rule.","type":"text"}]},{"type":"paragraph","content":[{"text":"After publish returns success","type":"text","marks":[{"type":"strong"}]},{"text":", offer retro as a soft tail — ","type":"text"},{"text":"unless a retro proof already exists for this run","type":"text","marks":[{"type":"strong"}]},{"text":" (","type":"text"},{"text":"ls \"$PRESS_MANUSCRIPTS/$API_SLUG/$RUN_ID/proofs/\"*-retro-*.md","type":"text","marks":[{"type":"code_inline"}]},{"text":" matches, the on-disk artifact ","type":"text"},{"text":"/printing-press-retro","type":"text","marks":[{"type":"code_inline"}]},{"text":" writes when it runs), in which case skip the offer and end normally. Anchor the skip on that file rather than memory — it survives a context-window roll or a mid-session resume, so the decision is the same whether or not the earlier retro is still in context. The publish skill drives its PR to stable green and hands back without offering anything itself; this tail is the only place the ship-path offers retro. It has no business being a peer of publish on the headline menu, but a post-publish optional offer lets users compound learnings without forcing the choice up front. Retro at this point sees the publish step as part of the session it analyzes.","type":"text"}]},{"type":"paragraph","content":[{"text":"Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"PR opened: \u003cPR_URL>. Run a retro? It surfaces systemic gaps from this session (generator misses, scorer bugs, skill-doc drift) as a GitHub issue for the Printing Press maintainers. Every retro filed raises the floor for the next CLI — and your session context is freshest right now.\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No — I'm done","type":"text","marks":[{"type":"strong"}]},{"text":" (default)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Yes — run retro now","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"If the user picks yes, invoke ","type":"text"},{"text":"/printing-press-retro","type":"text","marks":[{"type":"code_inline"}]},{"text":". The retro skill analyzes the session for generator improvements.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If \"Polish again\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoke ","type":"text"},{"text":"/printing-press-polish \u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":". The polish skill runs another diagnostic-fix-rediagnose pass, reports the delta, and offers its own publish at the end with the same data-driven shape used here.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"If \"Done for now\"","type":"text"}]},{"type":"paragraph","content":[{"text":"End normally. The CLI is in ","type":"text"},{"text":"$PRESS_LIBRARY/\u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" and the user can run ","type":"text"},{"text":"/printing-press-publish","type":"text","marks":[{"type":"code_inline"}]},{"text":", ","type":"text"},{"text":"/printing-press-polish","type":"text","marks":[{"type":"code_inline"}]},{"text":", or ","type":"text"},{"text":"/printing-press-retro","type":"text","marks":[{"type":"code_inline"}]},{"text":" later.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Hold-path menu","type":"text"}]},{"type":"paragraph","content":[{"text":"The CLI did not promote to library. The working copy is at ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":"; manuscripts and proofs are archived. Hold runs are the highest-value retro signal — something blocked the machine from reaching ship, and that signal is most valuable while session context is fresh.","type":"text"}]},{"type":"paragraph","content":[{"text":"Present via ","type":"text"},{"text":"AskUserQuestion","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"blockquote","content":[{"type":"paragraph","content":[{"text":"\"\u003capi> couldn't pass shipcheck — \u003cone-line reason from the shipcheck report or polish result>. The working copy is at \u003cexpanded $CLI_WORK_DIR path> and was not added to the library. What do you want to do?\"","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Run retro","type":"text","marks":[{"type":"strong"}]},{"text":" (recommended) — capture what blocked ship so the Printing Press maintainers can fix it for the next CLI you generate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polish to retry","type":"text","marks":[{"type":"strong"}]},{"text":" — run another polish pass and try again to reach ship","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Done for now","type":"text","marks":[{"type":"strong"}]}]}]}]}]},{"type":"paragraph","content":[{"text":"Default the recommendation to ","type":"text"},{"text":"Run retro","type":"text","marks":[{"type":"strong"}]},{"text":". Override to ","type":"text"},{"text":"Polish to retry","type":"text","marks":[{"type":"strong"}]},{"text":" when the polish result block specifically says another pass is likely to close the gap (","type":"text"},{"text":"further_polish_recommended: yes","type":"text","marks":[{"type":"code_inline"}]},{"text":") — that signal means the CLI is on hold not because the machine is structurally short, but because the last polish pass ran out of time on issues it can plausibly close.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"If \"Run retro\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoke ","type":"text"},{"text":"/printing-press-retro","type":"text","marks":[{"type":"code_inline"}]},{"text":". The retro skill analyzes the session for generator improvements.","type":"text"}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"If \"Polish to retry\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Invoke polish via the Skill tool with ","type":"text","marks":[{"type":"strong"}]},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" as the arg:","type":"text","marks":[{"type":"strong"}]}]},{"type":"code_block","attrs":{"wrap":false,"language":""},"content":[{"text":"Skill(\n skill: \"cli-printing-press:printing-press-polish\",\n args: \"$CLI_WORK_DIR\"\n)","type":"text"}]},{"type":"paragraph","content":[{"text":"Three reasons for this exact form, all mirroring Phase 5.5:","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pass ","type":"text","marks":[{"type":"strong"}]},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" (absolute path), not the slug.","type":"text","marks":[{"type":"strong"}]},{"text":" Hold runs leave the CLI in the working directory because Phase 5.6 did not promote — ","type":"text"},{"text":"$PRESS_LIBRARY/\u003cslug>/","type":"text","marks":[{"type":"code_inline"}]},{"text":" either does not exist or holds a stale prior run, and a slug-form invocation would polish that stale copy.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use the Skill tool (forked context), not the ","type":"text","marks":[{"type":"strong"}]},{"text":"/printing-press-polish","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" slash command.","type":"text","marks":[{"type":"strong"}]},{"text":" This matches Phase 5.5's invocation pattern — same shape, same expectations. Slash-command invocations auto-enable polish's standalone mode (Publish Offer fires); the Skill tool form defers to the parent unless ","type":"text"},{"text":"--standalone","type":"text","marks":[{"type":"code_inline"}]},{"text":" is passed explicitly. Main SKILL owns the menu on this path.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Do not include ","type":"text","marks":[{"type":"strong"}]},{"text":"--standalone","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" in ","type":"text","marks":[{"type":"strong"}]},{"text":"args","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":".","type":"text","marks":[{"type":"strong"}]},{"text":" The flag is what polish gates its Publish Offer on (see polish SKILL.md \"Publish Offer\"). On the hold path the CLI has not been promoted; firing the offer would open a public PR for an un-promoted, un-shipped working copy.","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"After polish returns, parse the result block and act on the new ","type":"text"},{"text":"ship_recommendation","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polish landed on ","type":"text","marks":[{"type":"strong"}]},{"text":"ship","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" or ","type":"text","marks":[{"type":"strong"}]},{"text":"ship-with-gaps","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — the verdict transitioned out of hold. The working copy is still un-promoted; the library is stale. Run promote, then route to the ship-path menu (above):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"cli-printing-press lock promote --cli \u003capi>-pp-cli --dir \"$CLI_WORK_DIR\"","type":"text"}]},{"type":"paragraph","content":[{"text":"Then re-enter the ship-path menu using polish's new result block. Skip the Phase 5.6 acceptance-gate JSON check — that gate was already satisfied when this run originally reached Phase 5.6, and polish does not regenerate it.","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Polish still on ","type":"text","marks":[{"type":"strong"}]},{"text":"hold","type":"text","marks":[{"type":"code_inline"},{"type":"strong"}]},{"text":" — re-show this hold-path menu so the user can pick again. Do not loop polish automatically; the user may want retro or to give up after a failed retry.","type":"text"}]}]}]},{"type":"heading","attrs":{"level":4},"content":[{"text":"If \"Done for now\"","type":"text"}]},{"type":"paragraph","content":[{"text":"End normally. The working copy stays in ","type":"text"},{"text":"$CLI_WORK_DIR","type":"text","marks":[{"type":"code_inline"}]},{"text":" for potential future retry.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Fast Guidance","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When to use ","type":"text"},{"text":"cli-printing-press print","type":"text","marks":[{"type":"code_inline"}]}]},{"type":"paragraph","content":[{"text":"Use ","type":"text"},{"text":"cli-printing-press print \u003capi>","type":"text","marks":[{"type":"code_inline"}]},{"text":" only when the user explicitly wants a resumable on-disk pipeline with phase seeds. It is optional.","type":"text"}]},{"type":"paragraph","content":[{"text":"The fast path for ","type":"text"},{"text":"/printing-press \u003cAPI>","type":"text","marks":[{"type":"code_inline"}]},{"text":" is:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"brief","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"generate","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"build","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"shipcheck","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"When to stop researching","type":"text"}]},{"type":"paragraph","content":[{"text":"Stop when you can answer:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"what to build first","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"what data to persist","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"what incumbent features cannot be missing","type":"text"}]}]}]},{"type":"paragraph","content":[{"text":"If the next research step does not change those answers, stop and generate.","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What not to do","type":"text"}]},{"type":"paragraph","content":[{"text":"Do not:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"write 5 separate mandatory research documents","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"defer all workflows to \"future work\"","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skip verification because the CLI compiles","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"treat scorecard alone as ship proof","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"discover YAML/URL spec incompatibility late and manually convert specs if the tools can already consume them","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"rerun the whole late-phase gauntlet for cosmetic README polish","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"skip features because \"the MCP already handles that\" (absorb everything, beat it with offline + agent-native)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"build only \"top 3-5 workflows\" when the absorb manifest has 15+ (build them ALL, then transcend)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"generate before the Phase 1.5 Ecosystem Absorb Gate is approved","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"call a CLI \"GOAT\" without matching every feature the best competitor has","type":"text"}]}]}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"What counts as success","type":"text"}]},{"type":"paragraph","content":[{"text":"Success is:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a generated CLI that gets to shipcheck without generator blockers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"verification tools working against the same spec the user generated from","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"one or two fix loops, not a maze of re-entry phases","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"a CLI that is plausibly shippable today, not a perfect design memo","type":"text"}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"printing-press","author":"@skillopedia","source":{"stars":2764,"repo_name":"cli-printing-press","origin_url":"https://github.com/mvanhorn/cli-printing-press/blob/HEAD/skills/printing-press/SKILL.md","repo_owner":"mvanhorn","body_sha256":"131413ef3c7268432fe8112abb1f675e4ba9d4f3b15f248764bd6a4b2cec7617","cluster_key":"a369d551467abd25677ceae3e92de20dfe763e20f8bda176f2a1cce8ca086a63","clean_bundle":{"format":"clean-skill-bundle-v1","source":"mvanhorn/cli-printing-press/skills/printing-press/SKILL.md","attachments":[{"id":"07e0e0e2-b82c-5119-beb7-6fa19b2e23e7","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/07e0e0e2-b82c-5119-beb7-6fa19b2e23e7/attachment.md","path":"references/absorb-scoring.md","size":7025,"sha256":"b0c9bfcf8941b9a51b45f3c98e59a824369f0889112c12bb901434877148354f","contentType":"text/markdown; charset=utf-8"},{"id":"01e30a50-016e-5a1b-9942-e31e394a5bc6","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/01e30a50-016e-5a1b-9942-e31e394a5bc6/attachment.md","path":"references/aggregator-pattern.md","size":5295,"sha256":"cecd8137b8f038e721ea85b3641f974cc5d637ba9a2f68a41d998f02e59e9137","contentType":"text/markdown; charset=utf-8"},{"id":"21e47446-b0b7-537c-b801-b87046a9f851","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/21e47446-b0b7-537c-b801-b87046a9f851/attachment.md","path":"references/auth-companion.md","size":11476,"sha256":"baeb5ba55486a1f4772a2dce0537996ec6162a220930badf05f73137e8b57f8e","contentType":"text/markdown; charset=utf-8"},{"id":"25b037a3-e4da-5e27-917f-b1c761405791","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/25b037a3-e4da-5e27-917f-b1c761405791/attachment.md","path":"references/browser-sniff-capture.md","size":86707,"sha256":"62ab759f91aaa5522b14e69adeac803fac3e49b9f518bf7abedb830833bf057e","contentType":"text/markdown; charset=utf-8"},{"id":"0d8a8b5d-9534-5f7c-b70f-13a88949d99c","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0d8a8b5d-9534-5f7c-b70f-13a88949d99c/attachment.md","path":"references/codex-delegation.md","size":12360,"sha256":"96aac277db7ab449c6809e084513d4babb353d5b5565faaf9d133ed9b3422fe1","contentType":"text/markdown; charset=utf-8"},{"id":"d946486d-2d67-5d4b-9935-4dbd2f470f91","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d946486d-2d67-5d4b-9935-4dbd2f470f91/attachment.md","path":"references/crowd-sniff.md","size":2827,"sha256":"d7182230180607ff5edb90c288a959b55d18e8b4844ce05c938df4c941943f8f","contentType":"text/markdown; charset=utf-8"},{"id":"14c5c1ba-0fdd-50e7-995f-1ea3fdccee2d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/14c5c1ba-0fdd-50e7-995f-1ea3fdccee2d/attachment.md","path":"references/deepwiki-research.md","size":5548,"sha256":"79b808655e374d194fbd0cabe0fb5a8d45abd98caa542cf2df76f76a2634b82e","contentType":"text/markdown; charset=utf-8"},{"id":"4bff32cf-0553-59af-924e-6763411e683b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/4bff32cf-0553-59af-924e-6763411e683b/attachment.md","path":"references/dogfood-testing.md","size":1792,"sha256":"863b0e1b54dad98ca6bd720e326a6cadb852ab28a77ca8110a321c0a64778420","contentType":"text/markdown; charset=utf-8"},{"id":"7c2b3631-10c5-5d36-a4cd-7f4f915605ee","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/7c2b3631-10c5-5d36-a4cd-7f4f915605ee/attachment.md","path":"references/fetch-docs.md","size":2642,"sha256":"aac617c46e400e96e712954fafe8f05ad25cfdd83cbd8786ca6de1d9eeb9896f","contentType":"text/markdown; charset=utf-8"},{"id":"c419bce2-3206-5793-b860-33565d42c5f5","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/c419bce2-3206-5793-b860-33565d42c5f5/attachment.sh","path":"references/fetch-docs.sh","size":6451,"sha256":"ca33719dc5b05be25fd70152b3e715fd2ff6f9e4d28519fa254c62151da022ae","contentType":"application/x-sh; charset=utf-8"},{"id":"0813917a-193f-5596-b3f2-8d00e6ca0530","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/0813917a-193f-5596-b3f2-8d00e6ca0530/attachment.md","path":"references/known-specs.md","size":2611,"sha256":"4e8ceb8786393bb3d05359c7cde33fa79ef18ed71563cccd7d37f74d36414f2f","contentType":"text/markdown; charset=utf-8"},{"id":"1e67aced-f84b-547b-a4f6-91ac38baba50","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/1e67aced-f84b-547b-a4f6-91ac38baba50/attachment.md","path":"references/noi-examples.md","size":3128,"sha256":"afe81fb67bbd8c5566e09cec5fbde560990e0c6c5fca97e4067d9ee73a112d50","contentType":"text/markdown; charset=utf-8"},{"id":"2c910e26-1f76-5199-b9ac-c8cc0abc864e","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/2c910e26-1f76-5199-b9ac-c8cc0abc864e/attachment.md","path":"references/novel-features-subagent.md","size":15861,"sha256":"d7ad6d3753f01af5000feedb530901a2281a344772d6c9723a25c21a62d336f9","contentType":"text/markdown; charset=utf-8"},{"id":"6168f3d4-ddf2-5f67-9f14-6301511436d4","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/6168f3d4-ddf2-5f67-9f14-6301511436d4/attachment.md","path":"references/per-source-rate-limiting.md","size":2151,"sha256":"4e0750cf1ca71a247f4fb4170da0fcaf41a3d4494843aed932f1620c36bc7d79","contentType":"text/markdown; charset=utf-8"},{"id":"926b0610-cacf-5e9d-8a06-4894c3d54238","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/926b0610-cacf-5e9d-8a06-4894c3d54238/attachment.md","path":"references/scorecard-patterns.md","size":2969,"sha256":"5700406bd44cc8c8d0fc92ea3a1b41cdd7bffea3d6acce18fb3572f9a5263c1a","contentType":"text/markdown; charset=utf-8"},{"id":"b852dbcf-e179-513a-81a3-1bbe9b336a6b","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/b852dbcf-e179-513a-81a3-1bbe9b336a6b/attachment.md","path":"references/secret-protection.md","size":13692,"sha256":"89261c2d5d2238c98bdc7853efd954b84b99e8b8007e26b8c36e9f2829274ab5","contentType":"text/markdown; charset=utf-8"},{"id":"d2714405-c7a6-56d8-9ec2-4f0d0ecfed15","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/d2714405-c7a6-56d8-9ec2-4f0d0ecfed15/attachment.md","path":"references/setup-checks.md","size":17809,"sha256":"4912fe536e5d97faa710300dc28c8c82fb92234cba508321652c8290597a3906","contentType":"text/markdown; charset=utf-8"},{"id":"727f503a-4c90-595e-a784-6adb40610440","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/727f503a-4c90-595e-a784-6adb40610440/attachment.md","path":"references/spec-format.md","size":17448,"sha256":"242959eaf970ebd8717e0710fc7f73ead55da7e4ddc7201e2567a01744085eae","contentType":"text/markdown; charset=utf-8"},{"id":"a7400d3f-5715-5a78-a284-ed256e915c4d","key":"uploads/10433ee7-ad12-4ae0-b34e-97553e46c6c8/a7400d3f-5715-5a78-a284-ed256e915c4d/attachment.md","path":"references/ws-primary-pattern.md","size":2071,"sha256":"6886a7391a8bb400b20e5a326d086035ca0769f7279aad4a50ab7ab84d1b4614","contentType":"text/markdown; charset=utf-8"}],"bundle_sha256":"614c902ad968ff9ee7e7c4dc354f10af3d25c6737937b970987de9a9611c6433","attachment_count":19,"text_attachments":19,"attachment_storage":"skillopedia-attachments-v1","binary_attachments":0,"excluded_attachments":[]},"cluster_size":1,"skill_md_path":"skills/printing-press/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"web-development","category_label":"Web"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"web-development","import_tag":"clean-skills-v1","description":"Generate a ship-ready CLI for an API with a lean research -> generate -> build -> shipcheck loop.","allowed-tools":["Bash","Read","Write","Edit","Glob","Grep","WebFetch","WebSearch","AskUserQuestion","Agent"],"min-binary-version":"4.0.0"}},"renderedAt":1782980889951}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.