← back to Cli Printing Press
docs(cli): comprehensive README rewrite reflecting current product (#75)
cc28b36fbb610e1be135d6d5e2289668cf62ed0c · 2026-03-30 14:04:00 -0700 · Matt Van Horn
Rewrites every section to cover capabilities shipped in the last 4 days:
web sniffing (any website → CLI), publishing pipeline, codex delegation,
smart-default output, proxy-envelope pattern, adaptive rate limiting,
URL auto-detection, novel feature suggestions, 18-API catalog, source
credits in generated READMEs, and discovery provenance.
Removes stale "What's New in v2" section — there is no v2, this is
pre-v1. Purges all v1/v2 references. Adds Library section showcasing
ESPN and Linear as shipped CLIs. Adds ESPN to NOI table. Updates phase
table to match current SKILL.md. Updates GitHub About description.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Files touched
M README.mdA docs/plans/2026-03-30-003-refactor-readme-comprehensive-rewrite-plan.md
Diff
commit cc28b36fbb610e1be135d6d5e2289668cf62ed0c
Author: Matt Van Horn <mvanhorn@users.noreply.github.com>
Date: Mon Mar 30 14:04:00 2026 -0700
docs(cli): comprehensive README rewrite reflecting current product (#75)
Rewrites every section to cover capabilities shipped in the last 4 days:
web sniffing (any website → CLI), publishing pipeline, codex delegation,
smart-default output, proxy-envelope pattern, adaptive rate limiting,
URL auto-detection, novel feature suggestions, 18-API catalog, source
credits in generated READMEs, and discovery provenance.
Removes stale "What's New in v2" section — there is no v2, this is
pre-v1. Purges all v1/v2 references. Adds Library section showcasing
ESPN and Linear as shipped CLIs. Adds ESPN to NOI table. Updates phase
table to match current SKILL.md. Updates GitHub About description.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
README.md | 166 ++++++++-------
...3-refactor-readme-comprehensive-rewrite-plan.md | 231 +++++++++++++++++++++
2 files changed, 324 insertions(+), 73 deletions(-)
diff --git a/README.md b/README.md
index edd62b7a..b116913e 100644
--- a/README.md
+++ b/README.md
@@ -2,16 +2,18 @@
Just making a CLI is not hard. Making a CLI that understands the power user is extremely hard. And the power user in 2026 is an AI agent.
-Claude Code, Codex, Gemini CLI, Cursor - they call CLIs thousands of times a day. Every printing press CLI is designed for agents first: `--json` by default when piped, typed exit codes for self-correction, `--compact` for token efficiency, `--dry-run` for safe exploration. Humans get the same great experience, but agents are the primary design target.
+Claude Code, Codex, Gemini CLI, Cursor — they call CLIs thousands of times a day. Every printing press CLI is designed for agents first: `--json` by default when piped, typed exit codes for self-correction, `--compact` for token efficiency, `--dry-run` for safe exploration. Humans get the same great experience, but agents are the primary design target.
```bash
-/printing-press Discord
-/printing-press Stripe
-/printing-press Linear
-/printing-press emboss notion # Second pass: improve an existing CLI
+/printing-press Discord # From the catalog (18 APIs ready)
+/printing-press --spec ./openapi.yaml # From a local spec
+/printing-press --har ./capture.har --name ESPN # From captured browser traffic
+/printing-press https://postman.com/explore # From a URL (auto-detects intent)
+/printing-press Discord codex # Codex mode — 60% fewer Opus tokens
+/printing-press emboss notion # Second pass: improve an existing CLI
```
-One command. Lean loop. Produces a Go CLI + MCP server that absorbs every feature from every competing tool, then transcends with compound use cases only possible with local data. REST or GraphQL.
+One command. Lean loop. Produces a Go CLI + MCP server that absorbs every feature from every competing tool, then transcends with compound use cases only possible with local data. REST, GraphQL, or sniffed traffic — no OpenAPI spec required.
### Get it
@@ -35,15 +37,19 @@ Most generators wrap endpoints and stop. Printing Press generates CLIs that **un
**Compound commands no wrapper can do.** Once data lives in SQLite, commands like `stale`, `health`, `bottleneck`, and `reconcile` become possible — they join across resources and analyze history. A stateless API wrapper literally cannot do this.
-**Agent-native by default.** Auto-JSON when piped. `--compact` drops to high-gravity fields only (60-80% fewer tokens). Typed exit codes (`0`/`2`/`3`/`4`/`5`/`7`) let agents self-correct without parsing error text. `--dry-run` for safe exploration. Every flag exists because an AI agent will call it thousands of times a day.
+**Agent-native by default.** Human-friendly tables when you're in a terminal. Auto-JSON when piped — no `--json` flag needed. `--compact` drops to high-gravity fields only (60-80% fewer tokens). Typed exit codes (`0`/`2`/`3`/`4`/`5`/`7`) let agents self-correct without parsing error text. `--dry-run` for safe exploration. Every flag exists because an AI agent will call it thousands of times a day.
+
+**No spec? No problem.** Don't have an OpenAPI spec? Point the press at a website. It launches a browser, captures traffic, reverse-engineers the API, and generates the spec for you. ESPN, Postman Explore, internal tools — if you can click through it, the press can build a CLI for it.
**Dual interface from one spec.** Every API gets a Cobra CLI (`<api>-pp-cli`) and an MCP server (`<api>-pp-mcp`). Same client, same store, same auth. Shell agents use the CLI. IDE agents use MCP. Zero code duplication.
**Verified, not vibes.** Four mechanical checks — scorecard, dogfood, proof-of-behavior, live API smoke test — catch hallucinated paths, dead flags, auth mismatches, and broken data pipelines before you ship.
+**Credits its sources.** Every generated README includes a Sources & Inspiration section that credits the ecosystem tools studied during research. We built on giants' shoulders and we say so.
+
## Every Endpoint. Every Insight. One Command.
-Discord's API has 300+ endpoints. Most generators stop there - wrap every endpoint, ship it, done. But [discrawl](https://github.com/steipete/discrawl) - Peter Steinberger's Discord tool - ignores most of them. It ships 11 commands: `sync`, `search`, `sql`, `tail`, `mentions`, `members`. **583 stars.**
+Discord's API has 300+ endpoints. Most generators stop there — wrap every endpoint, ship it, done. But [discrawl](https://github.com/steipete/discrawl) — Peter Steinberger's Discord tool — ignores most of them. It ships 11 commands: `sync`, `search`, `sql`, `tail`, `mentions`, `members`. **583 stars.**
Why does the 11-command tool win? Because Steinberger saw something Discord's own API designers didn't: **conversations are institutional knowledge.** Every message thread is a document that should be archived, indexed, and searched locally. Those 11 commands embody that insight. The 300 endpoint wrappers don't.
@@ -53,9 +59,9 @@ Until now, you had to choose: breadth (wrap every endpoint) or depth (understand
The GOAT CLI isn't built by finding gaps. It's built by stealing every good idea and compounding on top.
-**Layer 1 - Absorb:** Before generating, Phase 1.5 catalogs every feature from every Claude Code plugin, MCP server, community skill, competing CLI, and automation script. Every feature becomes a row in the absorb manifest - something our CLI must match AND beat with offline support, agent-native output, and SQLite persistence.
+**Layer 1 — Absorb:** Before generating, the ecosystem absorb gate catalogs every feature from every Claude Code plugin, MCP server, community skill, competing CLI, and automation script for your API. Every feature becomes a row in the absorb manifest — something our CLI must match AND beat with offline support, agent-native output, and SQLite persistence. The system even auto-suggests novel features it thinks are missing from the ecosystem before you approve the manifest.
-**Layer 2 - Transcend:** Once you have everything in SQLite, compound use cases emerge that no stateless tool can do. Velocity tracking requires historical cycle data. Churn risk requires joining charges + subscriptions. Bottleneck detection requires the full issue relationship graph. These are the Non-Obvious Insight commands - and they only work because Layer 1 put everything in a local database.
+**Layer 2 — Transcend:** Once you have everything in SQLite, compound use cases emerge that no stateless tool can do. Velocity tracking requires historical cycle data. Churn risk requires joining charges + subscriptions. Bottleneck detection requires the full issue relationship graph. These are the Non-Obvious Insight commands — and they only work because Layer 1 put everything in a local database.
The GOAT = everything everyone else does + everything nobody else thought of.
@@ -78,22 +84,19 @@ The **Non-Obvious Insight (NOI)** is a one-sentence reframe:
| GitHub | A code host | An **engineering culture fingerprint**. Every review turnaround and merge pattern is a signal about how your team ships. |
| Notion | A doc editor | A **knowledge decay detector**. Every stale page and orphaned database is a signal about what your team has forgotten. |
| Slack | Messaging | An **organizational nervous system**. Every response time and channel silence is a signal about team health. |
+| ESPN | Sports data | A **betting intelligence terminal**. Every injury report, lineup change, and odds movement is a signal about game outcomes. |
The NOI is the creative DNA of every CLI the press generates. Phase 0 cannot complete without one. If the LLM can't write an NOI, the research wasn't deep enough.
-The printing press automates what Steinberger does intuitively: look at an API, see what power users actually do with it, and build the commands that matter - then also wrap every endpoint for completeness.
+The printing press automates what Steinberger does intuitively: look at an API, see what power users actually do with it, and build the commands that matter — then also wrap every endpoint for completeness.
## How I Knew This Was Real
-I was deciding which Google Workspace CLI to use. Peter Steinberger's [gogcli](https://github.com/steipete/gogcli) (6.5K+ stars, Go) or Google's official [Workspace CLI](https://github.com/googleworkspace/cli) (10K+ stars in a week, Rust, dynamically generated from Google's Discovery Service).
-
-I ran [/last30days](https://github.com/mvanhorn/last30days-skill) - my recency research skill that searches Reddit, X, YouTube, and the web for what people actually say about tools. It searched 34 X posts (1,437 likes), 5 YouTube videos (57K views), and 10 web sources.
-
-The verdict surprised me: **use gogcli**. The newer, official tool with 10x the API coverage lost to the older third-party one. As [@7dyhn4542y put it on X](https://x.com): "my preference is 100% gogcli since I have my agent working a lot with Google Docs and sheets, and gogcli just makes him able to do what he needs to do."
+I was choosing between Peter Steinberger's [gogcli](https://github.com/steipete/gogcli) (6.5K+ stars, Go) and Google's official [Workspace CLI](https://github.com/googleworkspace/cli) (10K+ stars in a week, Rust). I ran [/last30days](https://github.com/mvanhorn/last30days-skill) — my recency research skill — across 34 X posts, 5 YouTube videos, and 10 web sources.
-Google's CLI wraps every endpoint but doesn't understand the user. Steinberger's CLI understands what people actually do with Gmail, Calendar, and Sheets - and builds human-friendly commands around those workflows. Setup is `brew install gogcli` vs. a multi-step Google Cloud Console OAuth dance.
+The verdict: **use gogcli**. The newer, official tool with 10x the API coverage lost to the older third-party one. As one user put it: "my preference is 100% gogcli since I have my agent working a lot with Google Docs and sheets, and gogcli just makes him able to do what he needs to do."
-That's the NOI again. Breadth doesn't beat depth. Understanding the user beats understanding the API. And /last30days saw it in the community data before I could see it myself.
+Breadth doesn't beat depth. Understanding the user beats understanding the API.
## The Creativity Ladder
@@ -109,20 +112,20 @@ Most API CLIs stop at Rung 1. The printing press climbs to Rung 5.
Rung 3 is table stakes. Rung 4 is where discrawl lives. Rung 5 is where nobody else is yet.
-The press generates the API wrapper in Phase 2 (Rung 1-2). Then it generates the discrawl-style data layer and workflow commands in Phase 4 (Rung 3-5) from domain archetype templates. Both in one run.
+The press generates the API wrapper in Phase 2 (Rung 1-2). Then it generates the discrawl-style data layer and workflow commands in Phase 3 (Rung 3-5) from domain archetype templates. Both in one run.
-## Why Not Just CLIs - CLIs + MCP
+## Why Not Just CLIs — CLIs + MCP
The NOI is the creative intelligence. The printing press generates **both interfaces** from one spec:
-- **`<api>-pp-cli`** - cobra CLI for humans + shell agents (Claude Code, Codex, Gemini CLI)
-- **`<api>-pp-mcp`** - MCP server for Claude Desktop, Cursor, Windsurf, Cline
+- **`<api>-pp-cli`** — Cobra CLI for humans + shell agents (Claude Code, Codex, Gemini CLI)
+- **`<api>-pp-mcp`** — MCP server for Claude Desktop, Cursor, Windsurf, Cline — auto-discovered, no shell needed
Same `internal/client`, same `internal/store`, same auth. Two binaries, zero code duplication.
**CLIs win for agents:** 100x fewer tokens than MCP tool definitions. LLMs were trained on shell interactions. Exit code 0 = done. `--json | jq` is a first-class composition pattern.
-**MCP wins for IDE integration:** Claude Desktop and Cursor discover tools automatically via MCP. No shell needed. The MCP server exposes the same operations as the CLI - including the data layer (sync, search, sql).
+**MCP wins for IDE integration:** Claude Desktop and Cursor discover tools automatically via MCP. No shell needed. The MCP server exposes the same operations as the CLI — including the data layer (sync, search, sql).
```
One spec --> printing-press generate --> <api>-pp-cli (cobra) + <api>-pp-mcp (MCP server)
@@ -151,15 +154,22 @@ The archetype is detected automatically from the spec. The entity mapper figures
The fast path is a lean loop. Artifacts still matter, but only when they directly improve the next phase.
```
-Phase 0 Resolve + Reuse (1-3 min) Reuse prior research, detect tokens, lock the spec source
+Phase 0 Resolve + Reuse (1-3 min) Reuse research, detect tokens, resolve spec or URL
Phase 1 Research Brief (5-10 min) API identity, competitors, data layer, product thesis
-Phase 1.5 Ecosystem Absorb Gate (5-10 min) Catalog every MCP/skill/CLI feature -> absorb manifest
+Phase 1.5 Ecosystem Absorb Gate (5-10 min) Catalog every MCP/skill/CLI feature → absorb manifest + novel suggestions
+Phase 1.7 Sniff Gate (if needed) (2-5 min) Browser capture, HAR import, discovery provenance
Phase 2 Generate (1-2 min) Go CLI + MCP server from spec with validation
Phase 3 Build The GOAT (10-20 min) ALL absorbed features + transcendence commands
-Phase 4 Shipcheck (3-8 min) dogfood + verify --fix + scorecard as one verification block
+Phase 4 Shipcheck (3-8 min) Dogfood + verify --fix + scorecard as one verification block
Phase 5 Live Smoke (optional) (2-5 min) Read-only API smoke + data-flow check
```
+**Three entry paths.** Got an OpenAPI spec? Use `--spec`. Got a URL to a website with no docs? The sniff gate launches a browser, captures traffic, and generates the spec. Got a HAR file from DevTools? Pass `--har`. The press handles all three.
+
+**18 APIs in the catalog.** Asana, DigitalOcean, Discord, Front, GitHub, HubSpot, LaunchDarkly, Pipedrive, Plaid, Postman, SendGrid, Sentry, Square, Stripe, Stytch, Telegram, Twilio — plus Petstore for testing. Each pre-verified with spec URL, auth type, and category.
+
+**Discovery provenance.** When the press sniffs a website, it archives everything — pages visited, endpoints discovered, response samples, rate limiting events — into a `discovery/` manuscript alongside the research and proofs. Full audit trail.
+
### Codex Mode (opt-in)
```bash
@@ -167,7 +177,7 @@ Phase 5 Live Smoke (optional) (2-5 min) Read-only API smoke + data-fl
/printing-press Discord # Standard Opus mode (default)
```
-When you add `codex`, Phase 3's code generation tasks are delegated to Codex CLI. Claude stays the brain (research, planning, scoring, review). Codex does the hands (writing Go code from scoped prompts). Same quality, 60% fewer Opus tokens.
+When you add `codex`, Phase 3's code generation tasks are delegated to Codex CLI. Claude stays the brain (research, planning, scoring, review). Codex does the hands (writing Go code from scoped prompts). Same quality, 60% fewer Opus tokens. If Codex fails 3 times in a row, the press falls back to doing it locally — no manual intervention needed.
### Emboss Mode (second pass)
@@ -177,19 +187,19 @@ When you add `codex`, Phase 3's code generation tasks are delegated to Codex CLI
/printing-press emboss ~/printing-press/library/notion-pp-cli # By full path
```
-Already generated a CLI? Emboss runs a 30-minute improvement cycle: audit baseline (verify + scorecard), re-research what's changed, identify top 5 improvements, build them, re-verify, report the delta. The binary handles the bookkeeping (`printing-press emboss --audit-only`), the skill handles the creative work.
+Already generated a CLI? Emboss runs a focused improvement cycle: audit baseline (verify + scorecard), re-research what's changed, identify top 5 improvements, build them, re-verify, report the delta. Offered at the end of every run — never triggered automatically.
## What Gets Generated
-**Designed for AI agents.** Every flag, every output format, every exit code is chosen because an agent will consume it. `--json` is automatic when piped. `--compact` drops to high-gravity fields only (id, name, status, timestamps) - 60-80% fewer tokens. Typed exit codes (`0`=success, `2`=usage, `3`=not found, `4`=auth, `5`=API, `7`=rate limited) let agents self-correct in one retry without parsing error text. `--dry-run` lets agents explore safely. `--stdin` enables batch operations. Humans benefit from all of this too - agent-native design is just good CLI design taken seriously.
+**Designed for AI agents.** Every flag, every output format, every exit code is chosen because an agent will consume it. Human-friendly table output in the terminal. Auto-JSON when piped — no flag needed. `--compact` drops to high-gravity fields only (id, name, status, timestamps) — 60-80% fewer tokens. Typed exit codes (`0`=success, `2`=usage, `3`=not found, `4`=auth, `5`=API, `7`=rate limited) let agents self-correct in one retry without parsing error text. `--dry-run` lets agents explore safely. Humans benefit from all of this too — agent-native design is just good CLI design taken seriously.
**Agent-first flags** (every command): `--json`, `--select`, `--dry-run`, `--stdin`, `--csv`, `--compact`, `--quiet`, `--yes`, `--no-input`, `--no-cache`, `--no-color`. Auto-JSON when piped (no `--json` needed). Typed exit codes (`0`=success, `2`=usage, `3`=not found, `4`=auth, `5`=API, `7`=rate limited).
**Actionable errors**: errors include the specific flag/arg that's wrong, the correct usage pattern, and the command path. Agents self-correct in one retry.
-**Bounded output**: list commands show "Showing N results. To narrow: add --limit, --json --select, or filter flags." Token-conscious `--compact` mode returns only high-gravity fields (id, name, status, timestamps) - 60-80% fewer tokens.
+**Bounded output**: list commands show "Showing N results. To narrow: add --limit, --json --select, or filter flags." Token-conscious `--compact` mode returns only high-gravity fields — 60-80% fewer tokens.
-**Table stakes features** (from Phase 0.6): every feature the top competitor has, classified and built before novel features. If schpet/linear-cli has `start` (git branch from issue), you get it. If 4ier/notion-cli has human-friendly filters, you get it. Anti-gaming rules prevent scorecard optimization over real features.
+**Table stakes features** (from the absorb gate): every feature the top competitor has, classified and built before novel features. If schpet/linear-cli has `start` (git branch from issue), you get it. If 4ier/notion-cli has human-friendly filters, you get it. Anti-gaming rules prevent scorecard optimization over real features.
**Data layer** (high-gravity entities): domain-specific SQLite tables with proper columns (not JSON blobs), FTS5 full-text search, incremental sync with cursor tracking, `sql` command for raw queries, domain-specific `UpsertX()` and `SearchX()` methods.
@@ -199,7 +209,15 @@ Already generated a CLI? Emboss runs a 30-minute improvement cycle: audit baseli
**Command name normalization**: generated names like `retrieve-a` become `get`, `post` becomes `create`, `patch` becomes `update`. Clean names, not operationId garbage.
-**Tests**: minimum 1 test file per package (store, cli). Table-driven tests for data layer queries and workflow commands. No more shipping with 0 test files.
+**Provenance manifest**: every generated CLI includes a `.printing-press.json` with spec source, generation timestamp, press version, category, and run ID. Self-describing even in isolation.
+
+**Source credits**: the generated README includes a "Sources & Inspiration" section crediting the ecosystem tools and competing projects studied during research.
+
+**Proxy-envelope support**: for APIs that wrap all requests in a POST envelope (like Postman's `_api/ws/proxy`), the press detects the pattern during sniffing and generates a specialized client.
+
+**Adaptive rate limiting**: sniffed APIs get conservative pacing — start slow, ramp up on success, back off on 429s. Never aborts, always recovers.
+
+**Tests**: minimum 1 test file per package (store, cli). Table-driven tests for data layer queries and workflow commands.
**Distribution scaffold**: `.goreleaser.yaml`, Homebrew formula, GitHub Actions CI. A CLI that can only be `go install`'d is not a real CLI.
@@ -209,11 +227,11 @@ Already generated a CLI? Emboss runs a 30-minute improvement cycle: audit baseli
**Sync performance** (discrawl-inspired): Cursor-based pagination, batch SQLite transactions, tuned pragmas (`synchronous=NORMAL`, `mmap_size=256MB`), `--since` incremental sync, `--concurrency` parallel workers, progress reporting to stderr.
-## Quality Scoring (v2 - Three Benchmarks)
+## Quality Scoring — Three Benchmarks
Three benchmarks, not one. All must pass:
-1. **Architecture** (discrawl benchmark): Does it have a real data layer - domain-specific SQLite, FTS5, incremental sync, workflow commands?
+1. **Architecture** (discrawl benchmark): Does it have a real data layer — domain-specific SQLite, FTS5, incremental sync, workflow commands?
2. **Quality** (gogcli benchmark): Does the code have proper output modes, typed errors, agent-native flags, doctor, README with cookbook?
3. **Features** (competitor benchmark): Would a user of the top competitor switch to this CLI?
@@ -221,7 +239,7 @@ Architecture without features is a toy. Features without architecture is a thin
Inspired by Peter Steinberger's [gogcli](https://github.com/steipete/gogcli). Two tiers, 100 points max, weighted 50/50. Grade A = 85+.
-**Tier 1: Infrastructure** (50 points) - does the skeleton have the right patterns?
+**Tier 1: Infrastructure** (50 points) — does the skeleton have the right patterns?
| Dimension | What It Checks |
|-----------|---------------|
@@ -231,7 +249,7 @@ Inspired by Peter Steinberger's [gogcli](https://github.com/steipete/gogcli). Tw
| Agent-Native | --json, --select, --dry-run, --stdin, --no-input, --compact, --yes |
| + 5 more | Terminal UX, README, Doctor, Local Cache, Breadth |
-**Tier 2: Domain Correctness** (50 points) - does the code actually work?
+**Tier 2: Domain Correctness** (50 points) — does the code actually work?
| Dimension | What It Checks |
|-----------|---------------|
@@ -242,7 +260,9 @@ Inspired by Peter Steinberger's [gogcli](https://github.com/steipete/gogcli). Tw
| Type Fidelity | String IDs (not int), required params marked, quality descriptions |
| Dead Code | No unwired flags, no uncalled functions, no ghost tables |
-**Why two tiers?** The original scorecard tested syntax (does this string exist in the file?) not semantics (does this code actually work?). Generated CLIs scored Grade A and failed on the first real API call. The v2 scorecard catches that.
+**Why two tiers?** A scorecard that only checks syntax ("does this string exist in the file?") misses semantics ("does this code actually work?"). The two-tier system forces both breadth and depth.
+
+Anti-gaming rules prevent optimizing for score instead of features. Table stakes (features competitors have) are Priority 1. Scorecard optimization is Priority 4.
```bash
# Runtime verification: tests every command against real API or mock server
@@ -258,6 +278,17 @@ printing-press scorecard --dir ./discord-pp-cli --spec /tmp/discord-spec.json
printing-press dogfood --dir ./discord-pp-cli --spec /tmp/discord-spec.json
```
+## Library
+
+Published CLIs live in [printing-press-library](https://github.com/mvanhorn/printing-press-library), organized by category.
+
+| CLI | Category | API | Install |
+|-----|----------|-----|---------|
+| `espn-pp-cli` | Media & Entertainment | ESPN sports data — scores, stats, standings across 17 sports and 139 leagues | `go install github.com/mvanhorn/printing-press-library/library/media-and-entertainment/espn-pp-cli/...@latest` |
+| `linear-pp-cli` | Project Management | Linear — issues, cycles, teams, projects with GraphQL | `go install github.com/mvanhorn/printing-press-library/library/project-management/linear-pp-cli/...@latest` |
+
+Each published CLI includes research manuscripts, verification proofs, and a `.printing-press.json` provenance manifest. The full catalog has **18 APIs** ready to generate — run `/printing-press-catalog` to browse.
+
## Quick Start
### Install
@@ -281,25 +312,35 @@ No repo checkout needed. The binary embeds its own catalog data and the plugin p
### Run It
```bash
-/printing-press Discord # Full Opus run - CLI + MCP server
-/printing-press Stripe codex # Codex mode - 60% fewer Opus tokens
-/printing-press --spec ./openapi.yaml # From local spec file
+/printing-press Discord # From the catalog
+/printing-press --spec ./openapi.yaml # From a local spec
+/printing-press --har ./capture.har --name ESPN # From captured browser traffic
+/printing-press https://postman.com/explore # From a URL (auto-detects intent)
+/printing-press Stripe codex # Codex mode — 60% fewer Opus tokens
```
-Each run produces two binaries (`<api>-pp-cli` + `<api>-pp-mcp`), 8 analysis documents, and a Quality Score.
+Each run produces two binaries (`<api>-pp-cli` + `<api>-pp-mcp`), research documents, verification proofs, and a Quality Score.
By default, active and published output are separated:
- Active managed runs work in `~/printing-press/.runstate/<scope>/runs/<run-id>/working/<api>-pp-cli`
- Published CLIs go to `~/printing-press/library/<api>-pp-cli`
- Archived manuscripts go to `~/printing-press/manuscripts/<api>/<run-id>/`
-- Manuscripts are split into `research/`, `proofs/`, and `pipeline/`
+- Manuscripts are split into `research/`, `proofs/`, `discovery/`, and `pipeline/`
`<scope>` is derived from the current git checkout path, so parallel worktrees do not stomp on each other. If you pass `--output`, that overrides the generated CLI location for that command.
+### Publish
+
+When you're happy with a CLI, publish it to the library:
+
+```bash
+/printing-press-publish linear # Validates, packages, creates PR
+```
+
## Verification Tools
-Four layers of mechanical validation - no vibes, no self-assessment.
+Four layers of mechanical validation — no vibes, no self-assessment.
```bash
# Quality Scorecard: two-tier scoring (infrastructure + domain correctness)
@@ -309,9 +350,9 @@ printing-press scorecard --dir ./my-pp-cli --spec ./openapi.json
printing-press dogfood --dir ./my-pp-cli --spec ./openapi.json
```
-### Proof of Behavior (Phase 4.7)
+### Proof of Behavior
-The v1 scorecard checked string presence ("does sync.go exist?"). The Proof of Behavior checks data flow ("does sync.go actually call UpsertMessage on a table that search.go queries?").
+The scorecard checks structure. Proof of Behavior checks data flow — does `sync.go` actually call `UpsertMessage` on a table that `search.go` queries?
Four behavioral proofs:
- **Path Proof**: Every URL in generated commands exists in the OpenAPI spec
@@ -321,9 +362,9 @@ Four behavioral proofs:
If any proof fails, auto-remediation removes dead code and re-verifies. Hallucinated paths and auth mismatches are hard FAIL gates.
-### Live API Testing (Phase 5.5)
+### Live API Testing
-When you provide an API key at the start, Phase 5.5 runs read-only tests against the real API:
+When you provide an API key at the start, Phase 5 runs read-only tests against the real API:
```
LIVE API TEST RESULTS
@@ -339,32 +380,10 @@ Verdict: PASS - CLI works against real API
Safety: GET only, --limit 1, 10s timeout, stops on 401. Never creates, posts, or deletes anything.
-### Ship Loop (Phase 5.7)
+### Ship Loop
"Is this shippable?" triggers a fix cycle: identify top 3 issues, fix them, re-score. Max 3 iterations. No more dead-end assessments.
-## What's New in v2 (2026-03-27)
-
-Synthesized from post-mortems on Notion and Linear runs. 14 changes to the skill.
-
-**The problem:** v1 did excellent competitive research, then ignored it to chase scorecard numbers. Every CLI came out as a discrawl clone with cute names nobody asked for.
-
-**The fix:** Three root problems addressed:
-
-| Problem | v1 | v2 |
-|---------|----|----|
-| Scorecard-driven development | Priority 2: "raise the scorecard number" | Priority 4 with anti-gaming rules. Table stakes are Priority 1. |
-| Same architecture for every API | discrawl clone: SQLite + 8 insight commands regardless of domain | Phase 0.6 Feature Parity Audit: build what competitors have FIRST |
-| Names nobody asked for | "noto" (Notion), "lz" (Linear) | `<api>-pp-cli` by default. Discoverable, branded, no confusion. |
-
-**New phases:** 0.6 (Feature Parity Audit), 5.9 (Offer Emboss)
-
-**New Phase 4 priorities:** P0 Data Layer, P1 Table Stakes (NEW), P2 Workflows, P3 Command Name Normalization (NEW), P4 Scorecard with anti-gaming, P5 Tests (NEW), P6 Distribution (NEW), P7 Polish
-
-**New validations:** Module path (2.0b), API version header (2.7), data pipeline smoke test (5.5g), 8 new anti-shortcut rules
-
-**Emboss:** Now opt-in only. Offered at end of run, never triggered automatically.
-
## Development
After cloning, install git hooks so lint errors are caught before they reach CI:
@@ -388,9 +407,10 @@ go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
## Credits
-- **Peter Steinberger** ([@steipete](https://github.com/steipete)) - [discrawl](https://github.com/steipete/discrawl) and [gogcli](https://github.com/steipete/gogcli) set the bar. The quality scoring system is inspired by his work. discrawl v0.2.0's sync architecture directly influenced the printing press templates.
-- **Trevin Chow** ([@trevin](https://x.com/trevin)) - [7 Principles for Agent-Friendly CLIs](https://x.com/trevin/status/2037250000821059933) shaped the agent-first template design.
-- **Ramp** ([@tryramp](https://github.com/ramp-public/ramp-cli)) - Their agent-first CLI inspired auto-JSON piping, --no-input, and --compact output.
+- **Peter Steinberger** ([@steipete](https://github.com/steipete)) — [discrawl](https://github.com/steipete/discrawl) and [gogcli](https://github.com/steipete/gogcli) set the bar. The quality scoring system is inspired by his work. discrawl's sync architecture directly influenced the printing press templates.
+- **Trevin Chow** ([@trevin](https://x.com/trevin)) — [7 Principles for Agent-Friendly CLIs](https://x.com/trevin/status/2037250000821059933) shaped the agent-first template design. Co-builder shipping PRs daily.
+- **Ramp** ([@tryramp](https://github.com/ramp-public/ramp-cli)) — Their agent-first CLI inspired auto-JSON piping, --no-input, and --compact output.
+
## License
MIT
diff --git a/docs/plans/2026-03-30-003-refactor-readme-comprehensive-rewrite-plan.md b/docs/plans/2026-03-30-003-refactor-readme-comprehensive-rewrite-plan.md
new file mode 100644
index 00000000..15646d63
--- /dev/null
+++ b/docs/plans/2026-03-30-003-refactor-readme-comprehensive-rewrite-plan.md
@@ -0,0 +1,231 @@
+---
+title: "refactor: Comprehensive README rewrite + About + Library README"
+type: refactor
+status: active
+date: 2026-03-30
+---
+
+# refactor: Comprehensive README rewrite + About + Library README
+
+## Overview
+
+Rewrite the CLI Printing Press README, GitHub About description, and printing-press-library README to reflect the current product after 32 merged PRs in 4 days. Keep the narrative voice and sales energy — this still needs to sell the "crazy hidden insights" concept — but make every section accurate to what the product actually does today.
+
+## Problem Frame
+
+The README was written during rapid early development. Since then, the product has gained: web sniffing (any website becomes a CLI), a publishing pipeline, codex delegation, smart-default output, proxy-envelope client pattern, adaptive rate limiting, URL auto-detection, novel feature auto-suggestions, 18 catalog entries, 2 shipped CLIs in the library, source credits in generated READMEs, discovery provenance, and more. The README still has a stale "What's New in v2" section that references internal iteration history — there is no v2, the product hasn't shipped v1 yet. Everything described is the current pre-v1 product being refined. The README doesn't mention half the current capabilities. The library repo README exists but only has 2 CLIs to showcase. The GitHub About description needs to match.
+
+## Requirements Trace
+
+- R1. README covers all major current capabilities (sniffing, publishing, codex, smart defaults, source credits, catalog of 18 APIs, library of 2 shipped CLIs, URL auto-detection, proxy-envelope, adaptive rate limiting, novel feature suggestions)
+- R2. Keep the narrative structure and sales voice — hook, Steinberger story, NOI, absorb & transcend, creativity ladder, etc.
+- R3. Remove stale "What's New in v2" section entirely — there is no v2, the product is pre-v1. Fold any still-relevant points into the body as "how it works" descriptions.
+- R4. Add web sniffing story prominently — "any website becomes a CLI, no spec needed" is a major differentiator
+- R5. Add publishing pipeline and library as proof of production
+- R6. Update GitHub About description for cli-printing-press repo
+- R7. Update printing-press-library README to reflect current state (2 CLIs, ESPN + Linear)
+- R8. All version references, counts, code examples use current values (v0.4.0, 18 catalog entries, 2 library CLIs)
+- R9. Update phase table to match current SKILL.md (sniff gate, absorb gate with novel features, discovery archiving)
+
+## Scope Boundaries
+
+- README.md, GitHub About, and library README only — no code changes
+- Not restructuring the fundamental narrative arc
+- Not writing tutorials or getting-started guides beyond what exists
+- Not updating SKILL.md or catalog entries
+
+## Key Technical Decisions
+
+- **Keep narrative structure, update content**: The README story arc works. Don't restructure — update in place, section by section.
+- **Delete "What's New in v2" entirely**: There is no v2 — this is all pre-v1 work. The scorecard anti-gaming, feature parity audit, etc. are just how the product works. Fold any still-useful points into the relevant sections as current behavior, not changelog.
+- **Sniffing gets prominent placement**: Add to hero section examples and expand in "How It Works" as an alternative entry path. This is the biggest unlock — no OpenAPI spec needed.
+- **Publishing + library = credibility**: Mention ESPN and Linear as shipped examples throughout. The library repo link adds proof.
+- **Keep the gogcli/discrawl story but trim**: The anecdote is long. Condense to the essential insight — keep Steinberger as the benchmark figure.
+- **Update hero code block**: Show the full range of invocations including sniffing, URLs, codex
+
+## Open Questions
+
+### Resolved During Planning
+
+- **Should we add a "Library" section to the main README?** Yes, brief — link to library repo, mention ESPN + Linear as examples, show install command.
+- **Keep or cut the "How I Knew This Was Real" section?** Keep but condense. The /last30days research angle is still unique and compelling.
+
+### Deferred to Implementation
+
+- **Exact wording for the sniffing pitch**: Must match existing voice. Short, punchy, "impossible" angle.
+- **Whether to restructure the "What Gets Generated" section**: It's dense. Implementer decides if grouping changes help.
+
+## Implementation Units
+
+- [ ] **Unit 1: Rewrite cli-printing-press README.md**
+
+ **Goal:** Comprehensive rewrite of README.md reflecting all current capabilities while preserving narrative voice.
+
+ **Requirements:** R1-R5, R8-R9
+
+ **Dependencies:** None
+
+ **Files:**
+ - Modify: `README.md`
+
+ **Approach:**
+
+ Section-by-section rewrite plan:
+
+ **Hero (lines 1-14):** Update code examples to show full range — sniffing (`--har`), URL auto-detection, codex mode, emboss. Add mention of "no spec needed" angle. Keep the agent-first framing.
+
+ **"Get it" (lines 16-28):** Keep as-is, verify install commands are current.
+
+ **"Why These CLIs Win" (lines 30-43):** Add smart-default output (auto-table for humans, auto-JSON when piped). Mention source credits in generated READMEs. Keep agent-native, local-first, dual-interface, verified points.
+
+ **"Every Endpoint. Every Insight. One Command." (lines 44-84):** Keep Steinberger/discrawl story as the anchor. This section is the soul of the README. Trim lightly if needed.
+
+ **"Absorb & Transcend" (lines 52-61):** Add novel feature auto-suggestions (PR #50) — the system now suggests features before the absorb gate. Mention the 18-API catalog as context.
+
+ **"The Non-Obvious Insight" (lines 62-84):** Keep the NOI table and explanation. This is timeless.
+
+ **"How I Knew This Was Real" (lines 86-96):** Condense the gogcli vs Google Workspace story to ~50% of current length. Keep the /last30days hook.
+
+ **"The Creativity Ladder" (lines 98-112):** Keep as-is — the rung concept is clear and stable.
+
+ **"Why Not Just CLIs - CLIs + MCP" (lines 114-133):** Keep. Maybe add note about MCP being auto-discovered by Claude Desktop.
+
+ **"Domain Archetypes" (lines 135-147):** Keep. Stable concept.
+
+ **"How It Works" (lines 149-170):** Major update needed:
+ - Update phase table to match current SKILL.md phases
+ - Add sniff gate (Phase 1.7) — browser-use capture, HAR import, discovery provenance
+ - Add absorb gate with novel feature suggestions
+ - Add discovery/ archiving
+ - Add publishing pipeline as the final step
+ - Update Codex mode description with 3-strike fallback
+ - Keep Emboss mode
+
+ **"What Gets Generated" (lines 182-208):** Update:
+ - Add smart-default output (human tables / auto-JSON when piped)
+ - Add source credits section in generated READMEs
+ - Add `.printing-press.json` manifest
+ - Add proxy-envelope client pattern mention
+ - Add adaptive rate limiting for sniffed APIs
+ - Keep all existing agent-native flags
+
+ **"Quality Scoring" (lines 212-258):** Keep structure. Remove all "v2" framing — there is no v2, this is the product. No "v1 did X, now we do Y" comparisons. Just describe how scoring works. Verify dimension lists are current.
+
+ **"Quick Start" (lines 261-298):** Update examples to show:
+ - Sniffing: `/printing-press --har ./capture.har --name ESPN`
+ - URL: `/printing-press https://postman.com/explore`
+ - Publishing: `/printing-press-publish linear`
+ - Library install: `go install github.com/mvanhorn/printing-press-library/library/project-management/linear-pp-cli@latest`
+
+ **"Verification Tools" (lines 300-344):** Keep. Verify commands are current.
+
+ **DELETE "What's New in v2" (lines 346-364):** Remove entirely. There is no v2 — this is pre-v1. Any still-useful points (scorecard anti-gaming, feature parity audit, command naming) should already be described in the relevant body sections. Don't reference internal iteration history in a public README.
+
+ **ADD "Library" section (new):** Brief section with:
+ - Link to printing-press-library repo
+ - ESPN (media-and-entertainment) and Linear (project-management) as shipped examples
+ - Install command for library CLIs
+ - Link to full catalog (18 APIs)
+
+ **"Development" (lines 368-387):** Keep as-is.
+
+ **"Credits" (lines 389-394):** Update. Verify all contributors are current. Add any new inspirations.
+
+ **Reference materials for implementer:**
+ - Current SKILL.md for phase descriptions
+ - PRs #43-#74 for feature details
+ - `catalog/*.yaml` for full catalog list (18 entries)
+ - `~/printing-press/library/` for shipped CLIs
+ - `internal/websniff/` for sniffing capabilities
+ - `internal/cli/root.go` for URL auto-detection
+ - `internal/generator/templates/readme.md.tmpl` for source credits
+
+ **Patterns to follow:**
+ - Existing README voice: short sentences, bold claims, specifics over generalities
+ - Steinberger as recurring benchmark figure
+ - Code blocks showing real commands with real APIs (Discord, Linear, ESPN, Notion)
+
+ **Critical: Purge ALL v1/v2 references.** The current README has v1/v2 in at least 6 places:
+ - Line 212: "Quality Scoring (v2 - Three Benchmarks)" → just "Quality Scoring"
+ - Line 245: "The v2 scorecard catches that" → rephrase without version reference
+ - Line 314: "The v1 scorecard checked..." → rephrase as "Earlier iterations checked..." or remove the comparison entirely
+ - Lines 346-364: entire "What's New in v2" section → delete
+ - Line 350: "v1 did excellent competitive research..." → delete with section
+ - Line 354: v1/v2 comparison table → delete with section
+
+ There is no v1 or v2. This is the product, pre-launch. Describe what it does, not what it used to do.
+
+ **Verification:**
+ - All R1 capabilities mentioned
+ - Zero references to "v1" or "v2" anywhere in the README
+ - No "What's New" changelog section
+ - Phase table matches SKILL.md
+ - All code examples work with current command syntax
+ - Narrative energy matches existing pitch style
+
+- [ ] **Unit 2: Update GitHub About description**
+
+ **Goal:** Set the cli-printing-press repo's About description to a concise, compelling one-liner.
+
+ **Requirements:** R6
+
+ **Dependencies:** None
+
+ **Files:**
+ - GitHub repo settings (via `gh` CLI)
+
+ **Approach:**
+ - Use `gh repo edit` to set the description
+ - The user provided the description: "Every API has a secret identity. This finds it, absorbs every feature from every competing tool, then builds the GOAT CLI on top — designed for AI agents first, with SQLite sync, offline search, and compound insight commands."
+ - Trim to fit GitHub's 350-char limit if needed
+
+ **Verification:**
+ - `gh repo view --json description` shows updated description
+
+- [ ] **Unit 3: Update printing-press-library README**
+
+ **Goal:** Update the library repo README to showcase ESPN and Linear, reflect current state.
+
+ **Requirements:** R7
+
+ **Dependencies:** None
+
+ **Files:**
+ - Modify: `~/printing-press-library/README.md`
+
+ **Approach:**
+ - Read current README
+ - Update to highlight ESPN (media-and-entertainment) and Linear (project-management) as shipped examples
+ - Add brief descriptions of each CLI with install commands
+ - Ensure category list and directory structure reflect current state
+ - Keep existing Contributing section and registry.json documentation
+ - Update any stale descriptions or counts
+ - Link back to cli-printing-press repo as the generator
+
+ **Verification:**
+ - README mentions both ESPN and Linear CLIs
+ - Install commands are correct
+ - Category list matches actual directories
+ - Link to cli-printing-press repo is present
+
+## Risks & Dependencies
+
+| Risk | Mitigation |
+|------|------------|
+| Losing the sales energy in rewrite | Keep paragraphs that work, only update stale content |
+| README becomes too long | Integrate new features into existing sections; condense "How I Knew" |
+| Inaccurate feature descriptions | Cross-reference SKILL.md, PR bodies, and actual Go code |
+| GitHub description too long | 350-char limit — trim if needed |
+
+## Sources & References
+
+- Current README: `README.md` (394 lines)
+- Current library README: `~/printing-press-library/README.md`
+- Skill definition: `skills/printing-press/SKILL.md`
+- Recent PRs: #43-#74 on mvanhorn/cli-printing-press
+- Catalog: `catalog/*.yaml` (18 entries: asana, digitalocean, discord, front, github, hubspot, launchdarkly, petstore, pipedrive, plaid, postman-explore, sendgrid, sentry, square, stripe, stytch, telegram, twilio)
+- Library: ESPN (media-and-entertainment), Linear (project-management)
+- Web sniffing: `internal/websniff/` (~2400 lines)
+- URL detection: `internal/cli/root.go`
+- Publishing: publish skill + `internal/cli/publish.go`
+- Plugin version: v0.4.0
← 89ca2ffd feat(skills): add browser-use version compatibility check to
·
back to Cli Printing Press
·
docs(cli): replace emdashes with regular dashes in README 7a49df71 →