/printing-press

/printing-press Notion
/printing-press Discord codex
/printing-press --spec ./openapi.yaml
/printing-press --har ./capture.har --name MyAPI
/printing-press https://postman.com/explore
/printing-press https://postman.com

What Changed In v2

• 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

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

Modes

Default

Codex Mode

codex

--codex

• writing store/data-layer code
• writing workflow commands
• fixing dead flags / dead code / path issues
• README cookbook edits

• research and product positioning
• choosing which gaps matter
• verification results and ship decisions

Polish Mode (Standalone Skill)

/printing-press-polish redfin

printing-press-polish

Rules

• Do not ship a CLI that hasn't been behaviorally tested against real targets.

  go build

  and

  verify

  pass-rate are structural signals, not correctness signals. Phase 5's mechanical test matrix runs every subcommand +

  --json

  + 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.
• Bugs found during dogfood are fix-before-ship, not "file for v0.2". If a 1-3 file edit resolves it, do it now.

  ship-with-gaps

  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.
• Features approved in Phase 1.5 are shipping scope. 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.
• Do not quote human-time estimates for sub-tasks ("~15-30 min", "~1 hour", "quick fix") in

  AskUserQuestion

  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 (

  go install

  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.
• Optimize for time-to-ship, not time-to-document.
• Reuse prior research whenever it is already good enough.
• Do not split one idea across multiple mandatory artifacts.
• Durable files produced by this skill go under

  $PRESS_RUNSTATE/

  (working state) or

  $PRESS_MANUSCRIPTS/

  (archived). Short-lived command captures may use

  /tmp/printing-press/

  and must be removed after use.
• Do not create a separate narrative phase for dogfood, dead-code audit, runtime verification, and final score. Treat them as one shipcheck block.
• Run cheap, high-signal checks early.
• Fix blockers and high-leverage failures first.
• Reuse the same spec path across

  generate

  ,

  dogfood

  ,

  verify

  , and

  scorecard

  .
• YAML, JSON, local paths, and URLs are all valid spec inputs for the verification tools.
• Maximum 2 verification fix loops unless the user explicitly asks for more.

Secret & PII Protection (Cardinal Rules)

STEAM_API_KEY

"your-key-here"

• Exact-value scanning and auto-redaction of artifacts
• HAR auth stripping (headers, query strings, cookies)
• API key handling rules during the run
• Session state cleanup ordering

Preflight

AskUserQuestion

references/setup-checks.md

# min-binary-version: 0.3.0

# Derive scope first — needed for local build detection
_scope_dir="$(git rev-parse --show-toplevel 2>/dev/null || echo "$PWD")"
_scope_dir="$(cd "$_scope_dir" && pwd -P)"

# Prefer local build when running from inside the printing-press repo.
# The lefthook build hook keeps ./printing-press current after every commit/pull,
# so it's always newer than the go-install version.
if [ -x "$_scope_dir/printing-press" ] && [ -d "$_scope_dir/cmd/printing-press" ]; then
  export PATH="$_scope_dir:$PATH"
  echo "Using local build: $_scope_dir/printing-press"
elif ! command -v printing-press >/dev/null 2>&1; then
  # Augment PATH if the binary is in ~/go/bin but not on the user's interactive PATH.
  if [ -x "$HOME/go/bin/printing-press" ]; then
    export PATH="$HOME/go/bin:$PATH"
  else
    # Refuse: the printing-press binary is required and we will not auto-install
    # it. The README's two-step install (binary + plugin) is the source of truth;
    # silent auto-install hides failure modes (GOPRIVATE auth, network, wrong
    # GOPATH) inside an opaque skill invocation.
    echo ""
    echo "[setup-error] printing-press binary not found."
    echo ""
    if command -v go >/dev/null 2>&1; then
      echo "Install it in your terminal:"
      echo "  GOPRIVATE=github.com/mvanhorn/* go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest"
      echo ""
      echo "(GOPRIVATE is required while the repo is private. The plain command works after the public launch.)"
    else
      echo "Go 1.22+ is also not installed. Install Go from https://go.dev/dl/, then:"
      echo "  GOPRIVATE=github.com/mvanhorn/* go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest"
    fi
    echo ""
    echo "Verify with: printing-press --version"
    echo "Then re-run /printing-press."
    return 1 2>/dev/null || exit 1
  fi
fi

PRESS_BASE="$(basename "$_scope_dir" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9_-]/-/g; s/^-+//; s/-+$//')"
if [ -z "$PRESS_BASE" ]; then
  PRESS_BASE="workspace"
fi

PRESS_SCOPE="$PRESS_BASE-$(printf '%s' "$_scope_dir" | shasum -a 256 | cut -c1-8)"
PRESS_HOME="$HOME/printing-press"
PRESS_RUNSTATE="$PRESS_HOME/.runstate/$PRESS_SCOPE"
PRESS_LIBRARY="$PRESS_HOME/library"
PRESS_MANUSCRIPTS="$PRESS_HOME/manuscripts"
PRESS_CURRENT="$PRESS_RUNSTATE/current"

mkdir -p "$PRESS_RUNSTATE" "$PRESS_LIBRARY" "$PRESS_MANUSCRIPTS" "$PRESS_CURRENT"

# --- Latest-version advisory (throttled, fail-open) ---
# Once per 24h, check whether a newer printing-press release exists and print a
# one-line notice if so. Uses `go list` so it works for private modules via
# GOPRIVATE and public modules via the proxy. Runs in every context — devs
# ahead of latest stay silent (comparison handles it), devs behind latest get
# the same nudge anyone else does.
PRESS_VERCHECK_FILE="$PRESS_HOME/.version-check"
PRESS_VERCHECK_TTL=86400
_now_ts=$(date +%s)
_should_check=true
if [ -f "$PRESS_VERCHECK_FILE" ] && [ -z "$PRESS_VERCHECK_FORCE" ]; then
  _last_ts=$(awk -F= '/^last_check=/{print $2}' "$PRESS_VERCHECK_FILE" 2>/dev/null)
  if [ -n "$_last_ts" ] && [ "$((_now_ts - _last_ts))" -lt "$PRESS_VERCHECK_TTL" ]; then
    _should_check=false
  fi
fi

if [ "$_should_check" = "true" ] && command -v go >/dev/null 2>&1; then
  _installed=$(printing-press version --json 2>/dev/null | sed -nE 's/.*"version"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p')
  _latest=$(GOPRIVATE=github.com/mvanhorn/* go list -m -versions github.com/mvanhorn/cli-printing-press/v4 2>/dev/null | awk '{print $NF}' | sed 's/^v//')

  if [ -n "$_installed" ] && [ -n "$_latest" ] && [ "$_installed" != "$_latest" ]; then
    # sort -V is not fully semver-aware: it ranks "3.0.0-rc1" above "3.0.0" instead of below.
    # Acceptable today (we don't ship pre-release tags); revisit if we ever do.
    _newer=$(printf "v%s\nv%s\n" "$_installed" "$_latest" | sort -V | tail -1 | sed 's/^v//')
    if [ "$_newer" = "$_latest" ]; then
      # Marker for the skill prose below to detect and offer an interactive upgrade.
      # The skill reads PRESS_UPGRADE_AVAILABLE / PRESS_UPGRADE_INSTALLED from this output.
      echo ""
      echo "[upgrade-available] printing-press v$_latest is available (you have v$_installed)"
      echo "PRESS_UPGRADE_AVAILABLE=$_latest"
      echo "PRESS_UPGRADE_INSTALLED=$_installed"
      echo ""
    fi
  fi

  printf "last_check=%s\nlatest=%s\n" "$_now_ts" "${_latest:-unknown}" > "$PRESS_VERCHECK_FILE" 2>/dev/null || true
fi

# --- Codex mode detection (must run as part of setup, not a separate step) ---
# Codex mode: opt-in only. User must pass "codex" or "--codex" to enable.
if echo "$ARGUMENTS" | grep -qiE '(^| )(--?codex|codex)( |$)'; then
  CODEX_MODE=true
else
  CODEX_MODE=false
fi

# Environment guard: don't delegate if already inside a Codex sandbox
if [ "$CODEX_MODE" = "true" ]; then
  if [ -n "$CODEX_SANDBOX" ] || [ -n "$CODEX_SESSION_ID" ]; then
    CODEX_MODE=false
  fi
fi

# Health check: verify codex binary exists
if [ "$CODEX_MODE" = "true" ]; then
  if command -v codex >/dev/null 2>&1; then
    # Model and reasoning effort inherit from ~/.codex/config.toml. Do not pin -m / -c here.
    CODEX_MODEL=$(grep -E '^model[[:space:]]*=' ~/.codex/config.toml 2>/dev/null | head -1 | sed -E 's/^model[[:space:]]*=[[:space:]]*"?([^"]+)"?.*$/\1/')
    [ -z "$CODEX_MODEL" ] && CODEX_MODEL="codex default"
    echo "Codex mode enabled (model: $CODEX_MODEL). Code-writing tasks will be delegated to Codex."
  else
    echo "Codex CLI not found - running in standard mode."
    CODEX_MODE=false
  fi
fi

# Circuit breaker state
CODEX_CONSECUTIVE_FAILURES=0

[setup-error]

[upgrade-available]

AskUserQuestion

[setup-error]

[upgrade-available]

Orientation & Briefing

No Arguments: Orientation

/printing-press

--spec

--har

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.

By the end, you'll have a working CLI in

~/printing-press/library/

that you can use for yourself, ship on your own, or apply to add to the printing-press library.

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.

AskUserQuestion

/printing-press Notion
/printing-press Discord codex
/printing-press --spec ./openapi.yaml
/printing-press --har ./capture.har --name MyAPI
/printing-press https://postman.com

AskUserQuestion

• question:

  "What API would you like to build a CLI for?"

• header:

  "API target"

• multiSelect:

  false

• options:
  1. label:

     "Type it (recommended)"

     — description:

     "Provide an API name, URL, spec path, or HAR file via the 'Other' option below."

  2. label:

     "Browse existing CLIs first"

     — description:

     "Visit the public library to see what's already been printed before deciding what to build."

echo ""
echo "Public library: https://github.com/mvanhorn/printing-press-library"
echo "(If you have the Printing Press Library plugin, you can also run /ppl in Claude Code.)"
echo ""
command -v open >/dev/null 2>&1 && open https://github.com/mvanhorn/printing-press-library

/printing-press <api>

With Arguments: Briefing

--spec

--har

Very well. Setting the type for

<API>

.

Here is how this will proceed:

1. I shall research

   <API>

   across the internet: official docs, community wrappers, competing CLIs, MCP servers, and npm/PyPI packages
2. I shall catalog every feature that exists in any tool, then devise novel features of my own that no existing tool offers
3. 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
4. I shall generate a Go CLI, build every feature from the plan, then verify quality through dogfood, runtime verification, and scoring

What you will have at the end: A fully functional CLI at

~/printing-press/library/<api>

that you can use yourself, ship on your own, or apply to add to the printing-press library.

Time: 30-60 minutes depending on API complexity.

Things that help if you have them:

• An API key (for live smoke testing at the end)
• A logged-in browser session (for discovering authenticated endpoints)
• A spec file or HAR capture (skips discovery)

--spec

--har

AskUserQuestion

• question:

  "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?"

• header:

  "Briefing"

• multiSelect:

  false

• options:
  1. label:

     "Let's go (recommended)"

     — description:

     "Start research now. I'll ask about API keys, browser auth, or other context when I need them."

  2. label:

     "I have context to share"

     — description:

     "Tell me your vision, specific features, or auth context (API key, logged-in browser session) before research starts."

USER_BRIEFING_CONTEXT

• Vision / specific features — captured as-is. This context will be:
  • Added to the Phase 1 Research Brief under a

    ## User Vision

    section
  • 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?"
  • 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?"
• Auth context — if the user mentions an API key, env var, or logged-in browser session, set the corresponding

  AUTH_CONTEXT

  fields so the API Key Gate (Phase 0.5) and Pre-Browser-Sniff Auth Intelligence (Phase 1.6) do not re-ask.

Multi-Source Priority Gate

USER_BRIEFING_CONTEXT

AskUserQuestion

"You mentioned <Source A>, <Source B>, and <Source C>. I'll treat <Source A> as the primary — it gets the headline commands, the top of the README, and the first-run experience. Is that the right order?"

1. Yes, that order is correct — Proceed with

   SOURCE_PRIORITY=[A, B, C]

   captured to run state.
2. Different order — User provides the correct ordering; capture it.
3. They're peers, no primary — Rare; capture as equal weighting but warn the user that one will still lead the README.

$API_RUN_DIR/source-priority.json

{
  "sources": ["google-flights", "kayak-direct", "flightaware"],
  "confirmed_at": "<ISO timestamp>",
  "raw_user_phrasing": "<verbatim text that established the order>"
}

## Source Priority

"The primary source (<Source A>) is free, but the default path would require a <paid key> for the headline commands because <reason>. 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."

source-priority.json

auth_scoping

Run Initialization

<api>

RUN_ID="$(date +%Y%m%d-%H%M%S)"
API_RUN_DIR="$PRESS_RUNSTATE/runs/$RUN_ID"
RESEARCH_DIR="$API_RUN_DIR/research"
PROOFS_DIR="$API_RUN_DIR/proofs"
PIPELINE_DIR="$API_RUN_DIR/pipeline"
DISCOVERY_DIR="$API_RUN_DIR/discovery"
CLI_WORK_DIR="$API_RUN_DIR/working/<api>-pp-cli"
STAMP="$(date +%Y-%m-%d-%H%M%S)"

mkdir -p "$RESEARCH_DIR" "$PROOFS_DIR" "$PIPELINE_DIR" "$CLI_WORK_DIR"
STATE_FILE="$API_RUN_DIR/state.json"

$STATE_FILE

/printing-press-score

{
  "api_name": "<api>",
  "run_id": "$RUN_ID",
  "working_dir": "$CLI_WORK_DIR",
  "output_dir": "$CLI_WORK_DIR",
  "spec_path": "<absolute spec path if known>"
}

run_id

YYYYMMDD-HHMMSS

RUN_ID="$(date +%Y%m%d-%H%M%S)"

--research-dir

$API_RUN_DIR

$RUN_ID

state.json

/printing-press-score

run_id

printing-press dogfood --live --write-acceptance

go.work

$CLI_WORK_DIR

go

go build

go test

• $PRESS_RUNSTATE/

  — mutable working state for the current run (research, proofs, pipeline artifacts, plans, intermediate docs)

• $PRESS_LIBRARY/

  — published CLIs (

  <api-slug>/

  subdirectories)

• $PRESS_MANUSCRIPTS/

  — archived run evidence (research, proofs, discovery)

/tmp/printing-press/

mktemp

• ~/printing-press/library/notion/

  — published CLI directory (keyed by API slug)

• notion-pp-cli

  — the binary name inside the directory

• /printing-press emboss notion

  — emboss accepts both slug and CLI name

• discord-pp-cli/internal/store/store.go

  — internal source paths still use CLI name

• linear-pp-cli stale --days 30 --team ENG

  — binary invocations use CLI name

• github.com/mvanhorn/discord-pp-cli

  — Go module paths use CLI name

Outputs

$PRESS_MANUSCRIPTS/<api-slug>/<run-id>/

1. research/<stamp>-feat-<api>-pp-cli-brief.md

2. research/<stamp>-feat-<api>-pp-cli-absorb-manifest.md

3. proofs/<stamp>-fix-<api>-pp-cli-build-log.md

4. proofs/<stamp>-fix-<api>-pp-cli-shipcheck.md

5. proofs/<stamp>-fix-<api>-pp-cli-live-smoke.md

   (only if live testing runs)

Phase 0: Resolve And Reuse

1. Resolve the spec source.
   URL Detection — If the argument contains

   ://

   , it's a URL. Determine whether it's a spec or a website before proceeding.
   Step 1: Content probe. Fetch the URL (light GET via

   WebFetch

   ) and inspect the response:
   • Check the

     Content-Type

     header and the first few lines of the body.
   • If the fetch fails (timeout, 404, DNS error), skip to Step 2 — treat it as a website.
   If the content starts with

   openapi:

   ,

   swagger:

   , or is valid JSON containing an

   "openapi"

   or

   "swagger"

   key → it's a spec. Treat as

   --spec

   and proceed directly. No disambiguation needed.
   If the content is a HAR file (JSON with

   "log"

   and

   "entries"

   keys) → treat as

   --har

   and proceed directly.
   Step 2: Disambiguation. If the content is HTML or the probe failed, ask the user what they want. Extract the site name from the hostname (e.g.,

   postman.com

   → "Postman",

   app.linear.app

   → "Linear"). Derive

   <api>

   from the site name using the same

   cleanSpecName

   normalization the generator uses.
   Use

   AskUserQuestion

   with:
   • question:

     "What kind of CLI do you want for <SiteName>?"

   • header:

     "CLI target"

   • multiSelect:

     false

   • options:
     1. label:

        "<SiteName>'s official API"

        — description:

        "Build a CLI for <SiteName>'s documented API (e.g. REST endpoints, webhooks, OAuth)"

     2. label:

        "The <SiteName> website itself"

        — description:

        "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"

   The user can also pick the automatic "Other" option to describe what they're after in free text.
   Routing after disambiguation:
   • "<SiteName>'s official API" → use

     <api>

     as the argument, proceed with normal discovery (Phase 1 research, then Phase 1.7 browser-sniff gate evaluates independently as usual)
   • "The <SiteName> website itself" → use

     <api>

     as the argument, set

     BROWSER_SNIFF_TARGET_URL=<url>

     . 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

     BROWSER_SNIFF_TARGET_URL

     as the starting URL for browser capture. The printed CLI must still use a replayable runtime surface; do not ship a resident browser transport.
   • "Other" → read the user's free-form response and adapt
   End of URL detection. The remaining spec resolution rules apply when the argument is NOT a URL:
   • If the user passed

     --har <path>

     , this is a HAR-first run. Run

     printing-press browser-sniff --har <path> --name <api> --output "$RESEARCH_DIR/<api>-browser-sniff-spec.yaml" --analysis-output "$DISCOVERY_DIR/traffic-analysis.json"

     to generate a spec and traffic analysis from captured traffic. 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).
   • If the user passed

     --spec

     , use it directly (existing behavior).
   • Otherwise, proceed with normal discovery (catalog, KnownSpecs, apis-guru, web search).
2. Check for prior research in:

   • $PRESS_MANUSCRIPTS/<api-slug>/*/research/*

3. Reuse good prior work instead of redoing it.
4. Library Check — 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.
   First, check lock status to detect active builds:
   bash

   LOCK_STATUS=$(printing-press lock status --cli <api>-pp-cli --json 2>/dev/null)
   LOCK_HELD=$(echo "$LOCK_STATUS" | grep -o '"held"[[:space:]]*:[[:space:]]*[a-z]*' | head -1 | sed 's/.*: *//')
   LOCK_STALE=$(echo "$LOCK_STATUS" | grep -o '"stale"[[:space:]]*:[[:space:]]*[a-z]*' | head -1 | sed 's/.*: *//')
   LOCK_PHASE=$(echo "$LOCK_STATUS" | grep -o '"phase"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"phase"[[:space:]]*:[[:space:]]*"//;s/"//')
   LOCK_AGE=$(echo "$LOCK_STATUS" | grep -o '"age_seconds"[[:space:]]*:[[:space:]]*[0-9]*' | head -1 | sed 's/.*: *//')

   Then check the library directory:
   bash

   CLI_DIR="$PRESS_LIBRARY/<api>"
   HAS_LIBRARY=false
   HAS_GOMOD=false
   if [ -d "$CLI_DIR" ]; then
     HAS_LIBRARY=true
     if [ -f "$CLI_DIR/go.mod" ]; then
       HAS_GOMOD=true
     fi
     # Read manifest if available
     MANIFEST="$CLI_DIR/.printing-press.json"
     if [ -f "$MANIFEST" ]; then
       PRESS_VERSION=$(cat "$MANIFEST" | grep -o '"printing_press_version"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"printing_press_version"[[:space:]]*:[[:space:]]*"//;s/"//')
       GENERATED_AT=$(cat "$MANIFEST" | grep -o '"generated_at"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*"generated_at"[[:space:]]*:[[:space:]]*"//;s/"//')
     fi
     # Get directory modification time as fallback
     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)
   fi

   Decision matrix:

   Library dir?	Lock?	Stale?	Has go.mod?	Action
   No	No	N/A	N/A	Proceed normally
   No	Yes	No	N/A	Warn: "Actively being built (phase: <phase> , <age> seconds ago). Wait, use a different name, or pick a different API."
   No	Yes	Yes	N/A	Offer reclaim: "Interrupted build detected (stale since <age> s ago). Reclaim and start fresh?"
   Yes	No	N/A	Yes	Existing "Found existing" flow (see below)
   Yes	No	N/A	No	Debris: "Found <api> directory in library but it appears incomplete (no go.mod). Clean up and start fresh?" If user approves, rm -rf "$CLI_DIR" and proceed normally.
   Yes	Yes	No	Any	Warn: "Actively being rebuilt (phase: <phase> , <age> seconds ago). Wait, use a different name, or pick a different API."
   Yes	Yes	Yes	Any	Offer reclaim: "Interrupted rebuild detected (stale since <age> s ago). Reclaim and start fresh?"

   If actively locked (not stale): Present via

   AskUserQuestion

   with options to wait, pick a different API, or force-reclaim (

   printing-press lock acquire --cli <api>-pp-cli --scope "$PRESS_SCOPE" --force

   ).
   If stale lock: Reclaiming is automatic on

   lock acquire

   in Phase 2. If user approves, proceed normally — the lock acquire in Phase 2 will auto-reclaim the stale lock.
   If library exists with go.mod and no lock (completed CLI): Display context and present options using

   AskUserQuestion

   :

   Found existing

   <api>

   in library (last modified

   <date>

   ).

   If

   PRESS_VERSION

   is available, append:

   Built with printing-press v<version>.

   If prior research was also found (step 2), include the research summary alongside the library info.
   Then ask:
   1. "Generate a fresh CLI" — Re-runs the Printing Press into a working directory, overwrites generated code, then rebuilds transcendence features. Prior research is reused if recent.
   2. "Improve existing CLI" — Keeps all current code, audits for quality gaps, implements top improvements. The Printing Press is not re-run.
   3. "Review prior research first" — Show the full research brief and absorb manifest before deciding.
   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

   /printing-press-polish <api>

   to improve the existing CLI. If the user picks option 3, display the prior research, then re-present options 1 and 2.
   MANDATORY when re-using prior research after a binary upgrade. If the user picks "Generate a fresh CLI" (option 1) AND

   PRESS_VERSION

   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.
   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

   docs/CHANGELOG.md

   (or run

   git log --oneline v<PRESS_VERSION>..v<CURRENT> -- internal/

   ) and tag each notable change to one of these buckets:

   Category	Affects prior-brief assumption about...
   Transport / reachability	Which sources are reachable, what auth/clearance is needed, which clients (stdlib, Surf, browser-clearance) the brief assumed
   Scoring rubrics	What Phase 1.5/scorecard dimensions the brief targets, whether prior "high-priority" features still rank as such
   Auth modes	Whether brief's auth choice (api-key, cookie, composed, oauth) is still the right pick, whether new modes unlock new endpoints
   MCP surface	Whether brief's MCP shape (endpoint-mirror vs intent vs code-orchestration) matches the latest emit defaults
   Discovery	Whether browser-sniff / crowd-sniff workflows changed, whether prior gate decisions are still valid

   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.

   "The prior

   <api>

   was generated with printing-press v

   <PRESS_VERSION>

   . The current binary is v

   <CURRENT>

   . Categories where the machine has changed since then:

   <applicable buckets>

   . Each can invalidate prior research assumptions. Re-validate the prior brief against the current machine before reusing it?"

   Options:
   1. Yes, re-validate the prior research — 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.
   2. No, reuse the prior research as-is — proceed with the brief verbatim, even if the underlying machine assumptions are stale.
   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.
   If no CLI exists in the library and no lock is active, skip this step and proceed normally.
5. API Key Gate — Check whether this API requires authentication, then handle accordingly.

• The spec has no

  security

  or

  securityDefinitions

  section → likely no auth needed
• 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
• No env var matching the API name exists AND no known token pattern applies
• Community docs or npm/PyPI wrappers describe the API as "no auth required"

<API>

• GitHub:

  GITHUB_TOKEN

  ,

  GH_TOKEN

  , or

  gh auth token

• Discord:

  DISCORD_TOKEN

  ,

  DISCORD_BOT_TOKEN

• Linear:

  LINEAR_API_KEY

• Notion:

  NOTION_TOKEN

• Stripe:

  STRIPE_SECRET_KEY

• Generic:

  API_KEY

  ,

  API_TOKEN

Found

<ENV_VAR>

in your environment. This key will be used only 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?

• If the user approves → proceed with the key available for Phase 5.
• 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."

No API key detected for

<API>

. You can provide one now for read-only live smoke testing in Phase 5, or continue without it.

Set it with

export <ENV_VAR>=<your-key>

or paste the key here.

• If the user provides a key → proceed with the key available for Phase 5.
• 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."

Phase 1: Research Brief

BROWSER_SNIFF_TARGET_URL

printing-press catalog show <api> --json 2>/dev/null

spec_url

"<API> is in the built-in catalog (spec: <spec_url>). Use the catalog config to skip discovery, or run full discovery?"

• If catalog config: use the spec_url from the catalog entry, skip the research/discovery phase
• If full discovery: proceed with the normal research workflow

spec_url

wrapper_libraries

AskUserQuestion

"<API> has no official spec. The catalog knows about these community-maintained implementations:"

wrapper_libraries

google-flights

• krisukox/google-flights-api (Go, native, MIT) — Pure Go, importable; single-binary CLI with no runtime deps.
• punitarani/fli (Python, subprocess, MIT) — broader feature coverage (multi-leg, cabin class); requires Python 3.10+ at runtime.

$API_RUN_DIR/state.json

implementation

{ "library": "<name>", "url": "<url>", "integration_mode": "native|subprocess|html-scrape" }

go get

catalog/

wrapper_libraries

1. What is this API actually used for?
2. What are the top 3-5 power-user workflows?
3. What are the top table-stakes competitor features?
4. What data deserves a local store?
5. Why would someone install this CLI instead of the incumbent?
6. What is the product name and thesis?

• Find the spec or docs source
• Find the top 1-2 competitors
• Check GitHub issues on the top wrapper/SDK repo for "403", "blocked", "broken", "deprecated", "rate limit". 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.
• Find official and popular SDK wrappers on npm (

  site:npmjs.com

  ) and PyPI (

  site:pypi.org

  )
• Find 2-3 concrete user pain points
• Identify the highest-gravity entities
• Pick the top 3-5 commands that matter most

• workflow ideation
• parity audit
• data-layer prediction
• product thesis

$RESEARCH_DIR/<stamp>-feat-<api>-pp-cli-brief.md

# <API> CLI Brief

## API Identity
- Domain:
- Users:
- Data profile:

## Reachability Risk
- [None / Low / High] [evidence: e.g., "6 open issues on reteps/redfin about 403 errors since 2025"]

## Top Workflows
1. ...

## Table Stakes
- ...

## Data Layer
- Primary entities:
- Sync cursor:
- FTS/search:

## Codebase Intelligence
- [DeepWiki findings if available, otherwise omit this section]
- Source: DeepWiki analysis of {owner}/{repo}
- Auth: [token type, header, env var pattern]
- Data model: [primary entities and relationships]
- Rate limiting: [limits and behavior]
- Architecture: [key insight about internal design]

## User Vision
- [USER_BRIEFING_CONTEXT if provided, otherwise omit this section]

## Source Priority
- [Only present for combo CLIs. Copy the confirmed ordering from `source-priority.json`.]
- Primary: <Source A> — [spec state: official / community-wrapper / no-spec-browser-sniff-required] — [auth: free / paid]
- Secondary: <Source B> — [...]
- Tertiary: <Source C> — [...]
- **Economics:** [e.g., "Primary is free; paid key for <Source B> is scoped to its own commands only."]
- **Inversion risk:** [e.g., "Primary has no OpenAPI; secondary has 53-endpoint spec. Do NOT let spec completeness invert the ordering."]

## Product Thesis
- Name:
- Why it should exist:

## Build Priorities
1. ...
2. ...
3. ...

--spec

--har

browser-browser-sniff-gate.json

Phase 1.6: Pre-Browser-Sniff Auth Intelligence

AUTH_CONTEXT

STRIPE_SECRET_KEY

Authorization: Bearer

security

<API>

<site>

• Phase 1 brief's "Data profile" and "Top Workflows" sections
• Phase 1.5a MCP source code analysis (auth patterns, token formats)
• Community wrapper README "auth" or "authentication" sections
• The API Key Gate's token detection (Phase 0.5) — if it already found a key, don't re-ask

AskUserQuestion

"Do you have an API key for

<API>

? It will be used for read-only live smoke testing in Phase 5."

1. Yes — user provides the key or confirms it's in the environment
2. No, continue without it — skip live smoke testing

AUTH_CONTEXT

AskUserQuestion

"

<API>

has authenticated endpoints ([list features]). Are you logged in to

<site>

in your browser? If so, the generated CLI will support

auth login --chrome

— you'll be able to authenticate just by being logged into the site in Chrome. No API key needed."

1. Yes, I'm logged in — I'll use your session during browser-sniff and enable browser auth in the CLI
2. No, but I can log in — I'll help you log in before browser-sniffing
3. No, skip authenticated endpoints — browser-sniff only public endpoints

AUTH_SESSION_AVAILABLE=true

Phase 1.7: Browser-Sniff Gate

mcp__claude-in-chrome__*

mcp__computer-use__*

AskUserQuestion

"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

$DISCOVERY_DIR/

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."

Enforcement: the browser-browser-sniff-gate.json marker file

$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json

{
  "run_id": "20260411-000903",
  "sources": [
    {
      "source_name": "<exact name from briefing, e.g., kayak-direct>",
      "decision": "approved | declined | skip-silent | pre-approved",
      "reason": "<one-line justification>",
      "asked_at": "2026-04-11T00:10:00Z"
    }
  ]
}

• approved

  — user selected a browser-sniff option via

  AskUserQuestion

  . Proceed to "If user approves browser-sniff".

• declined

  — user explicitly declined browser-sniff via

  AskUserQuestion

  . Proceed to "If user declines browser-sniff".

• skip-silent

  — gate was silently skipped per the decision matrix (spec complete,

  --har

  provided,

  --spec

  provided, or login required with

  AUTH_SESSION_AVAILABLE=false

  ). The

  reason

  field names which.

• pre-approved

  — user already chose "The website itself" in Phase 0, where the prompt disclosed temporary Chrome/browser capture during generation, so

  BROWSER_SNIFF_TARGET_URL

  was set and the question was answered there.

asked_at

AskUserQuestion

Banned skip reasons

AskUserQuestion

• "The target is client-rendered and needs Playwright" — 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.
• "Direct HTTP/curl got 403, 429, Cloudflare, Vercel, WAF, DataDome, or bot-detection HTML" — 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.
• "The 3-minute time budget looks tight" — 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.
• "We have a substitute data source from another API" — 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.
• "Installing browser-use or agent-browser is friction" — the browser-sniff capture reference already documents the install path. Tooling friction is not a valid skip reason. Ask.
• "The documentation looks thorough enough" — 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.
• "The user said 'let's go' earlier and implicitly approved everything" — "let's go" at the briefing stage is consent to proceed with research, not standing approval for every future decision. Ask each gate individually.
• "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" — this is exactly when the chrome-MCP and computer-use fallback options enter, when the runtime exposes them. Step 1 of

  references/browser-sniff-capture.md

  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.

AskUserQuestion

Combo CLIs: per-source enforcement

source_name

kayak-direct

google-flights

flightaware

AskUserQuestion

flightaware

skip-silent

spec-complete

google-flights

fli

AskUserQuestion

kayak-direct

AskUserQuestion

Skip this gate entirely when

skip-silent

• User passed

  --spec

  and the spec is the canonical source for every named source → marker:

  { "source_name": "<api>", "decision": "skip-silent", "reason": "user-provided-spec" }

• User passed

  --har

  → marker:

  { "source_name": "<api>", "decision": "skip-silent", "reason": "user-provided-har" }

• BROWSER_SNIFF_TARGET_URL

  is set from Phase 0 (user chose "The website itself") → marker:

  { "source_name": "<api>", "decision": "pre-approved", "reason": "phase-0-website-choice" }

  , then go directly to "If user approves browser-sniff"

Direct HTTP challenge rule

403

429

cf-mitigated: challenge

x-vercel-mitigated: challenge

x-vercel-challenge-token

printing-press probe-reachability "<url>" --json

probe-reachability

1. Runtime probe (silent) —

   probe-reachability

   runs without prompting. The user already opted into "the website itself" or equivalent in Phase 0; running an HTTP request needs no further consent.
2. Browser-sniff offer (intent prompt) — 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.
3. Chrome attach (separate consent if escalation happens) — when the agent actually needs to open or attach to Chrome (because the discovery flow requires a real browser, or because

   mode: browser_clearance_http

   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

   browser_http

   and the spec is complete enough to skip discovery — there is no Chrome attach to announce in that path.

• Runtime (does the printed CLI need browser-compatible HTTP, a clearance cookie, or live page-context execution?) — settled entirely by

  probe-reachability

  .
• Discovery (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.

standard_http | browser_http | browser_clearance_http | unknown

mode

• mode: standard_http

  — runtime is plain HTTP (the original probe was transient). Continue Phase 1.7 normally; the discovery decision is unchanged.

• mode: browser_http

  — runtime is settled: ship Surf transport (

  UsesBrowserHTTPTransport

  will be set in the generator's traffic-analysis hints). The printed CLI will not include

  auth login --chrome

  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 not add clearance-cookie language to those prompts.

• mode: browser_clearance_http

  — 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

  references/browser-sniff-capture.md

  already disclose what's about to happen and may ask the user to solve a challenge. Note in the brief that runtime is provisionally

  browser_clearance_http

  pending capture results.

• mode: unknown

  — 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.

browser_clearance_http

unknown

• Do not offer alternate CLI shapes (RSS-first, official API, docs-only, narrower scope, "try anyway") before a real browser capture has been attempted.
• Do not write the brief as if browser-sniff is complete after only curl/direct HTTP probes.
• If browser automation tooling is unavailable, offer the user a manual HAR path before offering any scope pivot.

references/browser-sniff-capture.md

Time budget

• If a spec already exists (enrichment mode): "Browser-Sniff failed after 3 minutes — proceeding with existing spec."
• If no spec exists (primary mode): "Browser-Sniff failed after 3 minutes — falling back to --docs generation."
• If browser-sniff was approved or pre-approved and direct HTTP showed challenge/bot-protection evidence, do not auto-fall back to docs/official API, even when

  BROWSER_SNIFF_TARGET_URL

  is unset. Ask whether the user wants to provide a HAR manually, retry cleared-browser capture, or discuss alternate CLI scope.

When to offer browser-sniff

decision: skip-silent

AUTH_SESSION_AVAILABLE=true

AUTH_SESSION_AVAILABLE=false

--docs

decision: skip-silent

reason: login-required-no-session

AskUserQuestion

skip-silent

skip-silent

• browser discovery may open or attach to Chrome during generation,
• it may ask the user to log in or solve a challenge,
• it may request permission to install or upgrade browser-use/agent-browser if missing,
• the printed CLI will only ship if discovery finds a replayable surface and will not keep a browser running as normal command transport.

Browser-Sniff as enrichment (spec exists but has gaps)

AskUserQuestion

"Found a spec with N endpoints, but research shows the live API likely has more (competitors reference M+ features). Want me to use temporary browser discovery on

<url>

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."

Options:

1. Yes — browser-sniff and merge (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.)
2. No — use existing spec (proceed with what we have)

Browser-Sniff as primary (no spec found)

AskUserQuestion

AUTH_SESSION_AVAILABLE=true

"No OpenAPI spec found for

<API>

. Want me to browser-sniff

<likely-url>

to discover the API from live traffic?"

Options:

1. Yes — authenticated browser-sniff (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.) (Only show when

   AUTH_SESSION_AVAILABLE=true

   )
2. Yes — browser-sniff the live site (temporarily browse

   <url>

   anonymously, capture API/HTML traffic, and generate a spec only from replayable surfaces. Ask before installing capture tools.)
3. No — use docs instead (attempt

   --docs

   generation from documentation pages)
4. No — I'll provide a spec or HAR (user will supply input manually)

AUTH_SESSION_AVAILABLE=false

If user approves browser-sniff

{
  "source_name": "<normalized name from briefing>",
  "decision": "approved",
  "reason": "<which option they picked, e.g., 'authenticated browser-sniff' or 'browser-sniff and merge'>",
  "asked_at": "<current ISO8601 timestamp>"
}

$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json

Step 0: Identify the User Goal

• Domino's: "Order a pizza for delivery"
• Linear: "Create an issue and assign it to a sprint"
• Stripe: "Create a payment intent and confirm it"
• ESPN: "Check today's scores and standings"
• Notion: "Create a page and organize it in a database"

If user declines browser-sniff

{
  "source_name": "<normalized name from briefing>",
  "decision": "declined",
  "reason": "<which option they picked, e.g., 'use existing spec' or 'use docs instead'>",
  "asked_at": "<current ISO8601 timestamp>"
}

$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json

--docs

Before leaving Phase 1.7

browser-browser-sniff-gate.json

Phase 1.8: Crowd-Sniff Gate

--spec

printing-press crowd-sniff

• If a spec already exists: "Crowd-sniff failed — proceeding with existing spec."
• If no spec exists: "Crowd-sniff failed — falling back to --docs generation."

When to offer crowd-sniff

--docs

Crowd-sniff as enrichment (spec exists but has gaps)

AskUserQuestion

"Found a spec with N endpoints, but research shows the live API likely has more. Want me to search npm packages and GitHub code for

<api>

to discover additional endpoints? This typically takes 5-10 minutes."

Options:

1. Yes — crowd-sniff and merge (search npm SDKs and GitHub code, merge discovered endpoints with the existing spec)
2. No — use existing spec (proceed with what we have)

Crowd-sniff as primary (no spec found)

AskUserQuestion

"No OpenAPI spec found for

<API>

. Want me to search npm packages and GitHub code to discover the API from community usage? This typically takes 5-10 minutes."

Options:

1. Yes — crowd-sniff the community (search npm SDKs and GitHub code, generate a spec from discovered endpoints)
2. No — use docs instead (attempt

   --docs

   generation from documentation pages)
3. No — I'll provide a spec or HAR (user will supply input manually)

If user approves crowd-sniff

If user declines crowd-sniff

--docs

Phase 1.5: Ecosystem Absorb Gate

Pre-flight check: browser-sniff-gate marker

$PRESS_RUNSTATE/runs/$RUN_ID/browser-browser-sniff-gate.json

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.

Browser-Sniff Gate missing decision for source

<name>

. Return to Phase 1.7 and evaluate the decision matrix for that source.

state.json

Step 1.5a: Search for every tool that touches this API

1. WebSearch:

   "<API name>" Claude Code plugin site:github.com

2. WebSearch:

   "<API name>" MCP server model context protocol

3. WebSearch:

   "<API name>" Claude skill SKILL.md site:github.com

4. WebSearch:

   "<API name>" CLI tool site:github.com

   (competing CLIs)
5. WebSearch:

   "<API name>" CLI site:npmjs.com

   (npm packages)
6. WebFetch: Check

   github.com/anthropics/claude-plugins-official/tree/main/external_plugins

   for official plugin
7. WebSearch:

   "<API name>" MCP site:lobehub.com OR site:mcpmarket.com OR site:fastmcp.me

8. WebSearch:

   "<API name>" automation script workflow site:github.com

9. WebSearch:

   "<API name>" SDK wrapper site:npmjs.com

10. WebSearch:

    "<API name>" client library site:pypi.org

Step 1.5a.5: Read MCP source code (if found)

1. Identify the main source file. WebFetch the repo root to find the entry point — typically

   src/index.ts

   ,

   server.ts

   ,

   server.py

   ,

   main.go

   , or a

   tools/

   directory. MCP servers are usually small (one main file + tool definitions).
2. Extract three things:
   • API endpoint paths: Look for HTTP client calls (

     fetch(

     ,

     axios.

     ,

     requests.

     ,

     http.Get

     ,

     client.

     ) and extract the URL paths (e.g.,

     GET /v1/issues

     ,

     POST /graphql

     ). These are the endpoints the MCP maintainer proved work.
   • Auth patterns: Look for how the MCP constructs auth headers — token format (

     Bearer

     ,

     Bot

     ,

     Basic

     ), header name (

     Authorization

     ,

     X-API-Key

     ), environment variable names. This informs our auth setup guidance.
   • Response field selections: Look for which fields are extracted from API responses — these are the high-gravity fields that power users actually need.
3. Feed into absorb manifest. In step 1.5b, endpoints extracted from source get attributed as

   <MCP name> (source)

   in the "Best Source" column, distinguishing them from README-derived features. Source-extracted endpoints are high-confidence signals — the maintainer verified they work.
4. Feed auth patterns into research brief. If the MCP source reveals token format (e.g.,

   xoxp-

   for Slack,

   sk_live_

   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.

• No MCP repos were found in 1.5a
• MCP repos are private or archived
• The MCP is a monorepo where the relevant server is hard to locate within 3 minutes

Step 1.5a.6: DeepWiki Codebase Analysis (if GitHub repos found)

• No GitHub repos were discovered during Phase 1 or Step 1.5a
• The API is trivially simple (1-2 endpoints, no auth)

Step 1.5b: Catalog every feature into the absorb manifest

## Absorb Manifest

### Absorbed (match or beat everything that exists)
| # | Feature | Best Source | Our Implementation | Added Value |
|---|---------|-----------|-------------------|-------------|
| 1 | Search issues by text | Linear MCP search_issues | FTS5 offline search | Works offline, regex, SQL composable |
| 2 | Create issue | Linear MCP create_issue | --stdin batch, --dry-run | Agent-native, scriptable, idempotent |
| 3 | Sprint board view | jira-cli sprint view | SQLite-backed sprint query | Historical velocity, offline |

Status

(stub)

Step 1.5c: Identify transcendence features

### Survivors

### Transcendence (only possible with our approach)
| # | Feature | Command | Why Only We Can Do This |
|---|---------|---------|------------------------|
| 1 | Bottleneck detection | bottleneck | Requires local join across issues + assignees + cycle data |
| 2 | Velocity trends | velocity --weeks 4 | Requires historical cycle snapshots in SQLite |
| 3 | What did I miss | since 2h | Requires time-windowed aggregation no single API call provides |

Step 1.5c.5: Auto-Suggest Novel Features (subagent)

• hand-curate the transcendence list from a prior manifest, even when the prior looks complete. Prior

  research.json

  is INPUT to Pass 2(d), never a substitute for the spawn.
• fall back to inline brainstorming inside the SKILL.
• skip on cost grounds. With a strong prior the subagent confirms or reframes; with no prior it generates from scratch. Run it either way.
• treat disclosure as authorization. Announcing a skip in the gate showcase does not make the skip legal.

ls

none

Step 1.5d: Write the manifest artifact

$RESEARCH_DIR/<stamp>-feat-<api>-pp-cli-absorb-manifest.md

Step 1.5e: Write research.json for README credits

$API_RUN_DIR/research.json

ResearchResult

loadResearchSources()

alternatives

1. Have a GitHub URL (not npm/PyPI landing pages)
2. Actually contributed features to the absorb manifest
3. Are capped at 8 entries, ordered by number of absorbed features (then by stars)

cat > "$API_RUN_DIR/research.json" <<REOF
{
  "api_name": "<api>",
  "novelty_score": 0,
  "alternatives": [
    {"name": "<tool1>", "url": "<github-url>", "language": "<Go|JavaScript|Python|etc>", "stars": <N>, "command_count": <N>},
    ...
  ],
  "novel_features": [
    {
      "name": "<Feature Name>",
      "command": "<cli-subcommand>",
      "description": "<One sentence: what the user gets>",
      "rationale": "<One sentence: why only possible with our approach>",
      "example": "<ready-to-run invocation with realistic args, e.g. 'yahoo-finance-pp-cli portfolio perf --agent'>",
      "why_it_matters": "<One sentence aimed at AI agents: when should they reach for this?>",
      "group": "<Theme name clustering similar features, e.g. 'Local state that compounds'>"
    },
    ...
  ],
  "narrative": {
    "display_name": "<Canonical prose name, exact brand casing/spaces, e.g. Product Hunt, GitHub, YouTube, Cal.com>",
    "headline": "<Bold one-sentence value prop: what makes this CLI worth using>",
    "value_prop": "<2-3 sentence expansion rendered beneath the title>",
    "auth_narrative": "<API-specific auth story; omit for simple API-key auth>",
    "quickstart": [
      {"command": "<cli> <real-command-with-real-args>", "comment": "<why this comes first>"},
      ...
    ],
    "troubleshoots": [
      {"symptom": "<user-visible error or symptom>", "fix": "<actionable one-liner>"},
      ...
    ],
    "when_to_use": "<2-4 sentences describing ideal use cases; rendered in SKILL.md only>",
    "recipes": [
      {"title": "<Recipe name>", "command": "<cli> <invocation>", "explanation": "<one-line paragraph>"},
      ...
    ],
    "trigger_phrases": ["<natural phrase that should invoke this CLI's skill>", ...]
  },
  "gaps": [],
  "patterns": [],
  "recommendation": "proceed",
  "researched_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
REOF

language

novel_features

1. Include all transcendence features from the manifest that scored >= 5/10. Order by score descending.

2. description

   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."

3. rationale

   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."

4. command

   must match the actual CLI subcommand that will be built in Phase 3. For subcommands of a resource (e.g.,

   issues stale

   ), use the full command path.

5. example

   is a ready-to-run invocation an agent can copy-paste. Use realistic arguments from the API's domain (e.g.

   AAPL

   ,

   customer_42

   ), not

   <placeholder>

   . Include the

   --agent

   flag when the feature benefits from structured output.

6. why_it_matters

   is a single agent-facing sentence answering "when should I pick this over a generic API call?"

7. group

   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

   group

   string verbatim across features that belong together — exact matches drive README grouping. Leave

   group

   empty if the CLI has too few novel features to warrant clustering.
8. If no transcendence features scored >= 5/10, omit the

   novel_features

   field entirely.
9. Do not add a feature to

   novel_features

   merely to expose it through MCP. Any user-facing Cobra command becomes an MCP tool automatically unless it sets

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

   .

narrative

1. display_name

   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.

2. headline

   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."

3. value_prop

   expands the headline to 2–3 sentences. Name specific novel features by command where helpful.

4. auth_narrative

   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.

5. quickstart

   is a 3–6 step flow using REAL arguments (symbols, IDs, resource names an agent can actually pass). Each step's

   comment

   explains why it runs. This replaces the generic "resource list" first-command fallback.

6. troubleshoots

   captures API-specific failure modes (rate-limit mitigation, cookie expiry, paginated quirks). Each

   fix

   must be actionable — a command or a concrete setting change.

7. when_to_use

   is SKILL-only narrative. 2–4 sentences describing the kinds of agent tasks this CLI is the right choice for. Not rendered in README.

8. recipes

   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. At least one recipe must pair

   --agent

   with

   --select

   — using dotted paths (e.g.

   --select events.shortName,events.competitions.competitors.team.displayName

   ) when the response is deeply nested. APIs like ESPN, HubSpot, and Linear return tens of KB per call; without a

   --select

   recipe, agents burn context parsing verbose payloads. Pick a command known to return a large or deeply nested response and show the narrowing pattern. Regex literals must double-escape backslashes — write

   \\b

   not

   \b

   (and

   \\t

   ,

   \\f

   , etc.) inside any

   command

   ,

   fix

   , or other JSON string field. JSON parses

   \b

   as backspace (0x08),

   \f

   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.

9. trigger_phrases

   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 <api-name>", "run <api-name>"). Domain verbs vary — don't just template "use X" variants.
10. All

    narrative

    fields are optional. Omit fields you can't populate honestly rather than emit filler. The generator falls back to generic content gracefully.
11. Avoid hardcoded counts in narrative copy when the count tracks a runtime list. A number embedded in

    headline

    or

    value_prop

    ("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

    which.go

    — 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.

$API_RUN_DIR/discovery/browser-sniff-report.md

Priority inversion check (combo CLIs only)

source-priority.json

• If the primary source has fewer commands than any secondary source, this is a priority inversion — the free/primary-intent source got demoted because the secondary had more spec coverage.
• If the primary source has zero commands (all its features were dropped because it lacked a spec), this is a hard inversion — the primary was silently replaced.

⚠ Priority inversion detected.

The confirmed primary is <Source A> but the manifest gives it <N> commands vs <Source B> (secondary) with <M> 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.

The user said <Source A> is the headline. Shipping this manifest would invert their stated priority.

AskUserQuestion

1. Re-run discovery for <Source A> — loop back to Phase 1.7 browser-sniff or Phase 1.8 crowd-sniff for the primary source specifically.
2. Accept the inversion — the user explicitly confirms they're fine with the secondary leading. Record this in

   source-priority.json

   as

   inversion_accepted: true

   .
3. Drop <Source B> — remove the secondary from the manifest so it can't overshadow the primary.

Phase Gate 1.5

AskUserQuestion

AskUserQuestion

1. Scope — how many features absorbed across which tools, how many novel on top, how that stacks up against the best existing tool.
2. Per-novel-feature readout — one line each: feature name, what the user gets, and the specific evidence or persona that makes it worth building.
3. Anything the user should worry about before approving — stubs, risky dependencies, expensive endpoints, low-confidence ideas.

"Ready to generate with the full [N+M]-feature manifest? Or do you have ideas to add?"

1. Approve — generate now — Start CLI generation with the full manifest
2. I have ideas to add — Tell me features from your experience, then we'll generate
3. Review full manifest — Show me every absorbed and novel feature before deciding
4. Trim scope — The feature count is too ambitious, let's focus on a subset

1. "Beyond the [M] ideas above, what workflows do YOU use

   <API>

   for that we might have missed?"
2. "What frustrates YOU about this API that the research didn't surface?"
3. "What's YOUR killer feature — something only you'd think of?"

USER_BRIEFING_CONTEXT

Phase 1.9: API Reachability Gate

$DISCOVERY_DIR/traffic-analysis.json

reachability.mode

browser_clearance_http

browser_http

curl

• the browser-sniff capture contains useful non-challenge traffic (real API, SSR data, structured HTML, RSS/feed data, or page-context fetch evidence), and
• Phase 2 will pass

  --traffic-analysis "$DISCOVERY_DIR/traffic-analysis.json"

  so the generator can emit browser-compatible HTTP transport and, for

  browser_clearance_http

  , Chrome cookie import.

browser_required

response_format: html

The Check

curl -s -o /dev/null -w "%{http_code}" -m 10 "<base_url>/<simplest_get_path>" 2>/dev/null

WebFetch

probe-reachability

printing-press probe-reachability "<base_url>" --json

probe-reachability

mode

Decision Matrix

probe-reachability

browser_http

browser_http

browser_http

browser_clearance_http

browser_required

probe-reachability

browser_clearance_http

unknown

On HARD STOP

AskUserQuestion

"WARNING:

<API>

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."

1. Try anyway - proceed knowing the CLI may not work against the live API
2. Pick a different API - start over
3. Done - stop here

On WARN

AskUserQuestion

"The API returned [error]. This might be temporary, or it might mean programmatic access is blocked. Want to proceed?"

1. Yes - proceed - generate the CLI anyway
2. No - stop - pick a different API or provide a spec manually

On PASS

Phase 2: Generate

Pre-Generation Auth Enrichment

• For internal YAML specs: look for

  auth:

  section with

  type:

  not equal to

  "none"

• For OpenAPI specs: look for

  components.securitySchemes

  or

  security

  sections

type: none

1. Check the research brief for auth mentions (Bearer, API key, token, cookie, OAuth)
2. Check Phase 1.5a MCP source code analysis for auth patterns (header names, token formats)
3. Check Phase 1.6 Pre-Browser-Sniff Auth Intelligence results (if the user confirmed auth)

auth:
  type: bearer_token    # or api_key, depending on what research found
  header: Authorization # or the specific header from MCP source
  in: header
  env_vars:
    - <API_NAME>_TOKEN  # bearer_token → _TOKEN, api_key → _API_KEY

env_vars

x-auth-env-vars

x-auth-vars

docs/SPEC-EXTENSIONS.md

components:
  securitySchemes:
    slackBot:
      type: apiKey
      in: header
      name: Authorization
      x-auth-vars:
        - name: SLACK_BOT_TOKEN
          kind: per_call
          required: false
          sensitive: true
          description: Set this OR `SLACK_USER_TOKEN` for workspace API calls.
        - name: SLACK_USER_TOKEN
          kind: per_call
          required: false
          sensitive: true
          description: Set this OR `SLACK_BOT_TOKEN` for user-scoped API calls.

kind

• per_call

  is the default user-supplied credential used by normal commands.

• auth_flow_input

  is only needed during

  auth login

  .

• harvested

  is populated by the auth login flow into local config.

sensitive: true

sensitive: false

client_id

required

description

required: false

required: true

harvested

client_credentials

auth_flow_input

x-auth-vars

info.description

inferDescriptionAuth

Auth.*

Public Parameter Name Enrichment

flag_name

aliases

tools-manifest.json

printing-press public-param-audit --spec <spec-or-overlay-output> --ledger <runstate>/public-param-audit.json --strict

• Author

  flag_name

  and compatibility

  aliases

  in the spec or overlay, then rerun the audit so the finding becomes resolved from the spec itself.
• Record

  decision: "skip"

  in the ledger with

  source_evidence

  and

  skip_reason

  when source material shows no public rename is warranted.

decision: "flag_name"

proposed_flag_name

• Explicit parameter descriptions, vendor docs, or SDK argument names.
• Browser-sniff form/input labels and the interaction that produced the request.
• Traffic-analysis context tying the parameter to a specific endpoint workflow.
• Existing manuscript notes or reviewed examples that use the same task-level term.

• A one-letter name alone.
• Generic descriptions such as "query parameter" or "string value".
• Ambiguous sample values with no endpoint context.
• Global assumptions such as "

  s

  means search" or "

  c

  means city".

s

Street address

c

City, state, zip

params:
  - name: s
    flag_name: address
    aliases: [s]
    description: Street address
  - name: c
    flag_name: city
    aliases: [c]
    description: City, state, zip

s

c

address

city

flag_name

Free/Paid Tier Routing Enrichment

• Research or source-priority notes say the primary source is free but a secondary source needs a paid/API key.
• Some endpoints are documented as public while adjacent enrichment endpoints are documented as paid, partner, premium, or quota-gated.
• Browser/crowd sniffing found public endpoints and SDK/MCP research found a separate credential for expanded coverage.

• Internal YAML: add

  tier_routing

  plus

  tier

  on the affected resource or endpoint.
• OpenAPI: add

  x-tier-routing

  at the root or under

  info

  , and add

  x-tier

  to the path item or operation.
• Use

  auth.type: none

  for the free tier.
• Use only

  api_key

  or

  bearer_token

  for credential tiers in v1.
• If a credential tier uses a different

  base_url

  , it must be HTTPS and same host-family unless

  allow_cross_host_auth: true

  records explicit review.
• Do not combine

  no_auth: true

  or OpenAPI

  security: []

  with a credential tier.

• All useful commands require the same credential.
• The paid source would become the primary headline surface instead of enrichment.
• The auth split requires OAuth, cookie, composed, or session-handshake tier auth; handle that as a normal auth-mode decision for now.

tier_routing:
  default_tier: free
  tiers:
    free:
      auth: {type: none}
    paid:
      auth:
        type: api_key
        in: query
        header: api_key
        env_vars: [EXAMPLE_PAID_KEY]
resources:
  search:
    tier: free
    endpoints:
      list:
        method: GET
        path: /search
      enrich:
        method: GET
        path: /paid/search
        tier: paid

Tagging endpoints

no_auth: true

(composed/cookie auth APIs)

auth.type

cookie

composed

session_handshake

no_auth: false

no_auth: true

• Auth-flow primitives: login, registration, password-reset, email-confirm, refresh-token, OAuth callback. The user isn't authenticated when calling these — they ARE the auth flow.
• Public discovery: store/location finder, menu browse, public catalog, category listing, public search, public product detail.
• Health/metadata: health checks, version probes, capability flags, sitemap.

no_auth

no_auth: true

mcp_ready: cli-only

no_auth: false

resources:
  account:
    endpoints:
      register:
        method: POST
        path: /account/register
        no_auth: true   # registering means you're not yet authenticated
      login:
        method: POST
        path: /account/login
        no_auth: true   # the auth flow itself
      profile:
        method: GET
        path: /account/profile
        # no_auth defaults to false — needs auth to view your own profile
  stores:
    endpoints:
      find:
        method: GET
        path: /stores/near
        no_auth: true   # public store finder
  cart:
    endpoints:
      checkout:
        method: POST
        path: /cart/checkout
        # no_auth defaults to false — placing an order needs auth

Pre-Generation MCP Enrichment

mcp:

main.go

tools.go

intents.go

code_orch.go

tools-manifest.json

1. Typed endpoints — count

   endpoints

   across all

   resources

   (and

   sub_resources

   ) in the spec. These become per-endpoint MCP tools at generate-time.
2. Cobratree-walked tools — the runtime walker registers user-facing Cobra commands as MCP tools. Estimate as:

   extra_commands

   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.

mcp.transport: [stdio, http]

mcp.intents

mcp:

generate

mcp:
  transport: [stdio, http]    # remote-capable; reaches hosted agents
  orchestration: code         # thin <api>_search + <api>_execute pair
  endpoint_tools: hidden      # suppress raw per-endpoint mirrors
  intents:                    # optional; named multi-step intents
    - name: <intent_name>
      description: <agent-facing intent description>
      params: [...]
      steps: [...]

mcp.transport: [stdio, http]

mcp.orchestration: code

mcp.endpoint_tools: hidden

• Just want remote reach?

  mcp.transport: [stdio, http]

  alone is fine.
• Have 3–5 obvious multi-step workflows but <50 endpoints? Add

  mcp.intents

  without code orchestration; leave

  endpoint_tools

  at default (visible).

mcp_remote_transport

mcp_tool_design

mcp_surface_strategy

Lock and Generate

printing-press lock acquire --cli <api>-pp-cli --scope "$PRESS_SCOPE"

printing-press generate \
  --spec <spec-path-or-url> \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --force --lenient --validate

printing-press generate \
  --spec <original-spec-path-or-url> \
  --spec "$RESEARCH_DIR/<api>-browser-sniff-spec.yaml" \
  --name <api> \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --spec-source browser-sniffed \
  --traffic-analysis "$DISCOVERY_DIR/traffic-analysis.json" \
  --force --lenient --validate
# If proxy pattern was detected during browser-sniff, add:
#   --client-pattern proxy-envelope

printing-press generate \
  --spec "$RESEARCH_DIR/<api>-browser-sniff-spec.yaml" \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --spec-source browser-sniffed \
  --traffic-analysis "$DISCOVERY_DIR/traffic-analysis.json" \
  --force --lenient --validate
# If proxy pattern was detected during browser-sniff, add:
#   --client-pattern proxy-envelope

printing-press generate \
  --spec <original-spec-path-or-url> \
  --spec "$RESEARCH_DIR/<api>-crowd-spec.yaml" \
  --name <api> \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --force --lenient --validate

printing-press generate \
  --spec "$RESEARCH_DIR/<api>-crowd-spec.yaml" \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --force --lenient --validate

printing-press generate \
  --spec <original-spec-path-or-url> \
  --spec "$RESEARCH_DIR/<api>-browser-sniff-spec.yaml" \
  --spec "$RESEARCH_DIR/<api>-crowd-spec.yaml" \
  --name <api> \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --traffic-analysis "$DISCOVERY_DIR/traffic-analysis.json" \
  --force --lenient --validate

printing-press generate \
  --docs <docs-url> \
  --name <api> \
  --output "$CLI_WORK_DIR" \
  --research-dir "$API_RUN_DIR" \
  --force --validate

• Generate scaffolding only in Phase 2
• Build real commands in Phase 3 using a GraphQL client wrapper

Short: