printing-press

name	printing-press
description	Set up a new integration, connector, or CLI binding for any API. Wrap or generate a ship-ready Go CLI from an OpenAPI, HAR, or Postman spec via the lean research -> generate -> build -> shipcheck loop. Use when the user says build a CLI, wrap this API, set up a new integration, add a connector, integrate with a service, or names an API by domain.
version	2.0.0
min-binary-version	4.0.0
allowed-tools	["Bash","Read","Write","Edit","Glob","Grep","WebFetch","WebSearch","AskUserQuestion","Agent"]
created_by	user

/printing-press

Generate the best useful CLI for an API without burning an hour on phase theater.

/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

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 the next step.

Modes

Default

Normal mode. Claude does research, generation orchestration, implementation, and verification.

Codex Mode

If the arguments include codex or --codex, offload pure code-writing tasks to Codex CLI.

Use Codex for:

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

Keep on Claude:

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

If Codex fails 3 times in a row, stop delegating and finish locally.

Polish Mode (Standalone Skill)

For second-pass improvements to an existing CLI, use the standalone polish skill:

/printing-press-polish redfin

See the printing-press-polish skill for details. It runs diagnostics, fixes verify failures, removes dead code, cleans up descriptions and README, and offers to publish.

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.
• Use raw captures for contract research. 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 references/fetch-docs.md and use its fetch-docs.sh helper. Reserve WebFetch for quick TL;DR reads where losing field-level details is acceptable.
• 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.

Secret & PII Protection (Cardinal Rules)

These rules are non-negotiable. They apply at ALL times during a run.

API key values, token values, passwords, and session cookies must NEVER appear in any artifact: source code, manuscripts, proofs, READMEs, HARs, or anything committed to git. Env var names (e.g., STEAM_API_KEY) and placeholders (e.g., "your-key-here") are safe.

During Phase 5.6 (archiving) and before publishing, read and apply references/secret-protection.md for:

• 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

This section MUST run before any user-facing prompt — including the Orientation and Briefing flow below. A missing binary or available upgrade is information the user needs before they commit to an API. Do not invoke AskUserQuestion, print the orientation prose, or otherwise engage the user until preflight has completed and any signals from references/setup-checks.md have been handled.

# min-binary-version: 4.0.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)"

_press_repo=false
if [ -d "$_scope_dir/cmd/cli-printing-press" ] && [ -f "$_scope_dir/go.mod" ]; then
  _press_repo=true
fi

_resolve_press_bin() {
  if command -v cli-printing-press >/dev/null 2>&1; then
    command -v cli-printing-press
    return 0
  fi
  if command -v printing-press >/dev/null 2>&1 && printing-press version --json >/dev/null 2>&1; then
    command -v printing-press
    return 0
  fi
  return 1
}

# Strict-older semver compare on the first three components. Pre-release
# suffixes collapse to their GA counterpart (acceptable: we ship no pre-release
# tags).
_semver_lt() {
  if [ -z "${PP_SEMVER_A:-}" ] || [ -z "${PP_SEMVER_B:-}" ]; then
    echo "[setup-error] semver comparison inputs are missing." >&2
     2
  
  awk -v a= -v b= 
}

() {
  sed -nE  \
     2>/dev/null |  -n 1
}

() {
   [  !=  ] || [ ! -x  ]; 
     0
  

  _local_v=.*/\1/ps interactive PATH.
   [ -x  ]; 
     PATH=
   [ -x  ] &&  version --json >/dev/null 2>&1; 
     PATH=
  
    
    
    
    
     
     
     
      -v go >/dev/null 2>&1; 
       
       
    
       
       
    
     
     
     
     1 2>/dev/null ||  1
  







 !  -v go >/dev/null 2>&1; 
   
   
   
   
   
   
   
   
   1 2>/dev/null ||  1






_go_smoke_root=
 !  -p ; 
   
   
   
   
   1 2>/dev/null ||  1

_go_smoke_dir=
 [ -z  ]; 
   
   
   
   
   1 2>/dev/null ||  1

 >  <<
module pp-go-stdlib-smoke

go 1.20
__PP_GO_SMOKE_MOD__
 >  <<
package main

import (
	
	
	
	
	
	
)

func () {
	ctx := context.Background()
	payload, err := json.Marshal(map[string]string{: })
	 err != nil {
		panic(err)
	}
	 !regexp.MustCompile(`ok`).Match(payload) {
		panic()
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, , nil)
	 err != nil {
		panic(err)
	}
	_, _ = fmt.Fprint(io.Discard, req.Method)
}
__PP_GO_SMOKE_MAIN__
 ! (  && GOFLAGS= GOWORK=off go run . >/dev/null 2>); 
  _go_smoke_output=
   -rf 
   
   
   
   [ -n  ]; 
     
     
      
  
   
   1 2>/dev/null ||  1

 -rf 








 [  =  ] && [ -x  ]; 
  PRINTING_PRESS_BIN=

  PRINTING_PRESS_BIN=

 
 

() {
     | sed -nE  | sed -E 
}

() {
   [ -z  ] || !  -v go >/dev/null 2>&1; 
     0
  

  _pp_go_installed=
  _pp_go_required=
  PP_SEMVER_A=
  PP_SEMVER_B=
   [ -z  ] || [ -z  ] || ! _semver_lt; 
     0
  

   
   [  =  ]; 
     
     
     
     
     1
  

   
   
   
   
   
   0
}
_pp_check_go_currency || {  1 2>/dev/null ||  1; }





 [  =  ] && [ -x  ]; 
  _global_bin=
   _candidate       ; 
     [ -x  ] && [  !=  ] &&  version --json >/dev/null 2>&1; 
      _global_bin=
      
    
  
   [ -n  ]; 
    _local_v=.*/\1/ps/.*[[:space:]]*:[[:space:]]*]+)
     [ -n  ] && [ -n  ] && [  !=  ]; 
       
       
       
       
       
       
    
  


PRESS_BASE=
 [ -z  ]; 
  PRESS_BASE=


PRESS_SCOPE=
PRESS_HOME=
PRESS_RUNSTATE=
PRESS_LIBRARY=
PRESS_MANUSCRIPTS=
PRESS_CURRENT=

() {
  _pp_disk_warn_kb=
  _pp_disk_fail_kb=
    
    |*[!0-9]*)  0 ;;
  

  _pp_disk_path=
   [ ! -e  ] && [  !=  ]; 
    _pp_disk_path=
  

  _pp_disk_avail_kb=
    
    |*[!0-9]*)  0 ;;
  

   [  -lt  ]; 
     
     
     
     
     
     
     
     1
  

   [  -lt  ]; 
     
     
     
     
     
     
     
  
}
_pp_check_disk_space || {  1 2>/dev/null ||  1; }

 -p    




PRESS_VERCHECK_FILE=
PRESS_VERCHECK_TTL=86400
_now_ts=$( +%s)

_should_check=
 [ -f  ] && [ -z  ]; 
  _last_ts=$(sed -nE   2>/dev/null |  -n 1)
   [ -n  ] && [  -lt  ]; 
    _should_check=
  


 [  =  ]; 
  
  
   git -C  remote get-url origin >/dev/null 2>&1 &&
     git -C  fetch --quiet origin main >/dev/null 2>&1; 
    _head_rev=$(git -C  rev-parse HEAD 2>/dev/null || )
    _main_rev=$(git -C  rev-parse origin/main 2>/dev/null || )
    _skipped_repo_main=
     [ -f  ] && [ -z  ]; 
      _skipped_repo_main=$(sed -nE   2>/dev/null |  -n 1)
    
     [ -n  ] && [ -n  ] &&
       [  !=  ] &&
       [  !=  ] &&
       git -C  merge-base --is-ancestor   2>/dev/null; 
       
       
       
       
       
       
    

         >  2>/dev/null || 
  
 [  =  ] &&  -v go >/dev/null 2>&1; 
  _installed=$( version --json 2>/dev/null | sed -nE )
  _latest=

   [ -n  ]; 
    _latest=$(go list -m -json github.com/mvanhorn/cli-printing-press/v4@latest 2>/dev/null | sed -nE  |  -n 1)
  

  
  
  
  
  _min_supported=
  _min_reason=
    -v curl >/dev/null 2>&1; 
    _floor_doc=$(curl -fsSL --max-time 5 \
      https://raw.githubusercontent.com/mvanhorn/cli-printing-press/main/supported-versions.txt 2>/dev/null || )
     [ -n  ]; 
      _min_supported=$(   | sed -nE  |  -n 1)
      _min_reason=$(   | sed -nE  |  -n 1)
    
  

  PP_SEMVER_A=
  PP_SEMVER_B=
   [ -n  ] && [ -n  ] && _semver_lt; 
    
    
     
     
     
     
     
  

    \
        >  2>/dev/null || 









 [  !=  ] && [ -f  ]; 
  _floor_min=$(sed -nE   2>/dev/null |  -n 1)
  _floor_latest=$(sed -nE   2>/dev/null |  -n 1)
  _floor_reason=$(sed -nE   2>/dev/null |  -n 1)
  _floor_installed=$( version --json 2>/dev/null | sed -nE )
   [ -n  ] && [ -n  ] && [ -n  ] &&
     PP_SEMVER_A= PP_SEMVER_B= _semver_lt &&
     ! PP_SEMVER_A= PP_SEMVER_B= _semver_lt; 
     
     
     
     
     
     
  









_browser_use_missing=
_agent_browser_missing=





  -v browser-use >/dev/null 2>&1; 
  _browser_use_missing=

  -v agent-browser >/dev/null 2>&1; 
  _agent_browser_missing=


 [  =  ] || [  =  ]; 
   
   
   
   
   




   | grep -qiE ; 
  CODEX_MODE=

  CODEX_MODE=



 [  =  ]; 
   [ -n  ] || [ -n  ]; 
    CODEX_MODE=
  



 [  =  ]; 
    -v codex >/dev/null 2>&1; 
    
    CODEX_MODEL=$(grep -E  ~/.codex/config.toml 2>/dev/null |  -1 | sed -E )
    [ -z  ] && CODEX_MODEL=
     
  
     
    CODEX_MODE=
  



CODEX_CONSECUTIVE_FAILURES=0

MANDATORY: Read and apply references/setup-checks.md immediately after the setup contract bash block runs, before any other action. It handles the contract output signals: [setup-error] (refuse to run, surface the install instructions), optional [local-binary-stale] / [local-binary-rebuilt] repo-mode rebuild markers, [go-toolchain-old] / [low-disk] advisories, [repo-upgrade-available] (interactive AskUserQuestion prompt + optional repo pull), PRESS_REPO_MODE=<true|false> plus the targeted global open-agent-skills freshness check, the min-binary-version compatibility check (hard stop if binary is too old), [upgrade-required] (hard gate below the published currency floor — interactive upgrade-or-abort, no skip), [upgrade-available] (interactive AskUserQuestion prompt + optional standalone binary upgrade), [browser-tools-missing] (interactive AskUserQuestion prompt + optional install of browser-use and/or agent-browser), and the PRINTING_PRESS_BIN=<abs-path> marker plus optional [binary-shadow] 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-library installer on PATH shadowed the local build. Do not skip.

Absolute-path rule. The preflight contract always emits PRINTING_PRESS_BIN=<absolute path> to stdout. Capture this value and substitute it (the resolved absolute path, not the literal $PRINTING_PRESS_BIN token) for every subsequent cli-printing-press ... invocation in this skill, references, and any sub-skill you delegate to. The export PATH=... line inside the contract only affects the single Bash tool call it runs in; later Bash tool calls open fresh shells and resolve bare cli-printing-press against the user's default PATH, where a stale globally-installed binary ($HOME/go/bin/cli-printing-press, Homebrew copy, etc.) will silently shadow the local build the preflight just chose. Bash code examples below are written cli-printing-press generate ... for readability — replace cli-printing-press with the captured absolute path each time you actually run one.

Only after preflight completes successfully (no [setup-error]; no [upgrade-required] left unresolved — the user either upgraded or the run was aborted; no global skill update that requires restart; any [repo-upgrade-available], [upgrade-available], or [browser-tools-missing] was offered to the user; PRINTING_PRESS_BIN is captured) should you proceed to the Orientation & Briefing section below.

Orientation & Briefing

After preflight has completed, check whether the user provided arguments. Handle two cases:

No Arguments: Orientation

If the user typed /printing-press with no arguments (no API name, no --spec, no --har, no URL), print an orientation and ask what they'd like to build:

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

Print these example invocations as plain text BEFORE the AskUserQuestion call (so they appear as context above the question, not as competing menu options):

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

Then ask via 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."

Do not add additional options — 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.

If the user picks "Type it (recommended)", they will provide their answer via the auto "Other" field. Set their input as the argument and proceed to the briefing below.

If the user picks "Browse existing CLIs first", 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:

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

After printing, end the skill cleanly. Do not proceed to briefing or research — the user is exploring, not building yet. They can re-invoke /printing-press <api> once they've decided.

With Arguments: Briefing

When the user provided an argument (API name, --spec, --har, or URL), print a brief process overview. This sets expectations and collects any upfront context. (Preflight has already run at this point.)

Print as prose, matching the style of the example below:

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 $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)

If the user provided --spec, adapt: "You have provided a spec, so I shall skip discovery and proceed directly to analysis and generation. Should be faster."

If the user provided --har, adapt: "You have provided a HAR capture, so I shall generate a spec from your traffic and skip browser browser-sniffing."

Then ask via 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."

Do not add additional options — 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.

If the user picks "Let's go (recommended)", proceed to the Multi-Source Priority Gate (or, for single-source runs, directly to Phase 0).

If the user picks "I have context to share", capture their free-text response as USER_BRIEFING_CONTEXT. The response may include:

• 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

After the briefing question resolves, inspect the user's original argument AND any USER_BRIEFING_CONTEXT they provided. If together they name two or more distinct services, sites, or APIs (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.

Why this gate exists: 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.

Parse the order from the prose. 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.

Confirm via AskUserQuestion:

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

Options:

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.

Write the confirmed ordering to $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>"
}

Phase 1 MUST consult this file. 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 ## Source Priority (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.

Economics check. 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:

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

Default to option 1 unless the user overrides. Record the decision in source-priority.json under auth_scoping.

Single-source runs: If only one service is named, skip this gate entirely — no ordering to confirm.

---

Run Initialization

After you know <api> (from the Orientation & Briefing flow above; preflight already ran at the top), initialize the run-scoped artifact paths:

mkdir -p "$PRESS_RUNSTATE/runs"
RUN_ID=""
API_RUN_DIR=""
for attempt in 1 2 3 4 5; do
  RUN_SUFFIX="$(LC_ALL=C tr -dc 'a-f0-9' </dev/urandom 2>/dev/null | head -c 8 || true)"
  if [ -z "$RUN_SUFFIX" ]; then
    RUN_SUFFIX="pid$$-$attempt"
  fi
  CANDIDATE_RUN_ID="$(date +%Y%m%d-%H%M%S)-$RUN_SUFFIX"
  CANDIDATE_RUN_DIR="$PRESS_RUNSTATE/runs/$CANDIDATE_RUN_ID"
  if mkdir "$CANDIDATE_RUN_DIR" 2>/dev/null; then
    RUN_ID="$CANDIDATE_RUN_ID"
    API_RUN_DIR="$CANDIDATE_RUN_DIR"
    break
  fi
done
if [ -z "$RUN_ID" ]; then
  echo "could not allocate a unique run directory under $PRESS_RUNSTATE/runs" >&2
  exit 1
fi
RESEARCH_DIR="$API_RUN_DIR/research"
PROOFS_DIR="$API_RUN_DIR/proofs"
PIPELINE_DIR="$API_RUN_DIR/pipeline"
DISCOVERY_DIR="/discovery"
CLI_WORK_DIR=
STAMP=










SESSION_BASE=
SESSION_DIR=
SESSION_STATE_FILE=

 -p    







( 077 &&  -p )
STATE_FILE=

Maintain a lightweight state file at $STATE_FILE so /printing-press-score can rediscover the current run. It should always contain:

{
  "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 is the unique value allocated above from the wall-clock stamp plus a short random suffix. mkdir "$CANDIDATE_RUN_DIR" is the collision guard: if another run already owns a candidate directory, allocate another ID instead of reusing the directory. Persisting this value in state.json makes the state file the source of truth for generate, dogfood acceptance, promote, /printing-press-score, and future state-loading consumers. Without run_id in either state or legacy path fallback, cli-printing-press dogfood --live --write-acceptance refuses to write the gate marker.

Do not create a go.work file in $CLI_WORK_DIR. Generated modules must build and test as standalone modules; a mismatched workspace go directive can break Go 1.25+ toolchains and lefthook checks. Editor/gopls workspace noise is cosmetic and must not be traded for broken go build or go test. The generated test gate is go test -count=1 ./... so a warm Go test cache cannot satisfy a fresh proof.

There are exactly three durable writable locations. Every generated artifact this skill preserves goes to one of them:

• $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)

Short-lived command captures may use /tmp/printing-press/ with unique mktemp paths and must be deleted after use.

Examples of the current naming/layout:

• $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

Every run writes up to 5 concise artifacts under the current managed run and archives them to $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)

These do not need to be 200+ lines. Keep them dense, evidence-backed, and directly useful.

Phase 0: Resolve And Reuse

Before new research:

1. Resolve the spec source.

   Local physical device detection. If the user's target is a local Bluetooth/BLE-controlled physical device (for example an appliance, toy, light, sensor, exercise machine, lock, or other device controlled from a phone app over Bluetooth), do not route it through browser-sniff as the primary discovery path. Read and apply references/device-sniff-ble.md. Use device-sniff ble for normalized BLE evidence and bluetooth-sniff as the discoverable alias. Community libraries, docs, Android logs, Wireshark/nRF captures, and manual action journals are evidence inputs; they are not a reason to hardcode a vendor-specific generator path.

   BLE mapping research gate. A BLE scan/inspect/read/subscribe pass only discovers identity, services, characteristics, and telemetry candidates; it does not by itself discover what write payloads mean. Before generating callable control commands or running any live write, establish a command mapping from at least one concrete source: user-provided mapping, official docs, community protocol/library code, Android/iOS/Bluetooth logs, Wireshark/nRF captures, or an operator action journal that correlates a real user action with observed writes. If no mapping source is found, generate only read/status/capability metadata or stop and ask the user for mapping evidence. Do not invent mutating payloads or brute-force probe a physical device.

   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 with the raw docs helper from references/fetch-docs.md and inspect the response status, Content-Type, and first few lines of the returned file:

   • Check the Content-Type header and the first few lines of the body.
   • If the fetch fails (timeout, 404, DNS error), record the exact status/error, then 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", → "Linear"). Derive from the site name using the same normalization the generator uses.

First, determine if the API needs auth. Use these signals:

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

If no auth is required, skip the key gate entirely. Proceed with: "No authentication required for <API> — 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.

If the API DOES require auth, run the key gate:

Token detection order:

• 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

If a token IS found, stop and explain:

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

If no token is found, stop and ask:

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

Resolve the API key gate (or skip it for public APIs) before moving to Phase 1.

Phase 1: Research Brief

When BROWSER_SNIFF_TARGET_URL is set: Skip 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.

Before reading documentation, read references/fetch-docs.md. Use fetch-docs.sh 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.

There is no built-in catalog lookup in this repo. New CLIs start from researched specs, documentation, browser/crowd/device discovery, or a reprint of an existing local/public-library artifact. If the target already exists in the public library, use the reprint/publish workflow rather than adding source metadata here.

Write one build-driving brief, not a stack of phase essays.

The brief must answer:

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?

Research checklist:

• Find the spec or docs source. For docs pages whose details affect generation, fetch the raw page with fetch-docs.sh, then read/grep the returned path directly.
• 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

Do not produce separate mandatory documents for:

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

Put them in the one brief.

Write:

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

Suggested shape:

# <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"]
- Tier/permission hints from 4xx body: [omit when absent; otherwise quote the matched bounded line(s) from Phase 1.9]
- Probe-safe endpoint used: [omit when absent; otherwise "<METHOD> <path>" from `x-pp-safe-probe`]

## 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:  — [...]
 Tertiary:  — [...]