← back to Cli Printing Press
docs: rewrite README with NOI as hero, discrawl story, gogcli/last30days narrative
307e67c9faa3ccd15d7f3e946bc8022ee34e7e10 · 2026-03-26 10:45:19 -0700 · Matt Van Horn
The README now leads with the story, not the mechanics:
- Opens with "323 commands vs 12 commands" - why discrawl (551 stars)
beats a 323-command API wrapper. The Non-Obvious Insight is why.
- NOI section explains the formula with 6 API examples
- Personal story: Matt's surprise when /last30days recommended gogcli
(6.5K stars) over Google's official Workspace CLI (10K stars)
- Agent/token economics demoted to supporting role - the NOI is the hero
- Credits Peter Steinberger (discrawl, gogcli) and /last30days
- Steinberger Bar renamed to credit its namesake
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Files touched
M README.mdA docs/plans/2026-03-26-docs-readme-noi-storytelling-plan.md
Diff
commit 307e67c9faa3ccd15d7f3e946bc8022ee34e7e10
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu Mar 26 10:45:19 2026 -0700
docs: rewrite README with NOI as hero, discrawl story, gogcli/last30days narrative
The README now leads with the story, not the mechanics:
- Opens with "323 commands vs 12 commands" - why discrawl (551 stars)
beats a 323-command API wrapper. The Non-Obvious Insight is why.
- NOI section explains the formula with 6 API examples
- Personal story: Matt's surprise when /last30days recommended gogcli
(6.5K stars) over Google's official Workspace CLI (10K stars)
- Agent/token economics demoted to supporting role - the NOI is the hero
- Credits Peter Steinberger (discrawl, gogcli) and /last30days
- Steinberger Bar renamed to credit its namesake
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
README.md | 265 ++++++---------------
...2026-03-26-docs-readme-noi-storytelling-plan.md | 100 ++++++++
2 files changed, 174 insertions(+), 191 deletions(-)
diff --git a/README.md b/README.md
index b26d6430..5c9f6865 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# CLI Printing Press
-An agent infrastructure factory. Give it an API name. Get back the CLI that your agents need.
+Just making a CLI is not hard. Making a CLI that understands the power user is extremely hard.
```bash
/printing-press Discord
@@ -8,38 +8,23 @@ An agent infrastructure factory. Give it an API name. Get back the CLI that your
/printing-press Linear
```
-One command. 8 phases. ~1 hour. Produces a production-ready Go CLI binary + 7 deep analysis documents. REST or GraphQL - it figures it out.
+One command. 8 phases. ~1 hour. Produces a production-ready Go CLI + 7 analysis documents. REST or GraphQL.
-## Why Every API Needs a CLI
+## 323 Commands vs. 12 Commands
-In 2026, most code isn't written by humans - it's written by agents under human direction. Agents need to interact with APIs. They have two choices: import an SDK and write 15 lines of code, or run a single CLI command. The CLI wins on every dimension that matters.
+Discord's API has 300+ endpoints. The printing press can generate a CLI that wraps all 323 of them. But [discrawl](https://github.com/steipete/discrawl) - Peter Steinberger's Discord tool - has **12 commands** and **551 stars**.
-**Token economics.** A single MCP server exposes ~93 tools costing [~55,000 tokens](https://manveerc.substack.com/p/mcp-vs-cli-ai-agents) just to load tool definitions. At scale (10,000 sessions/day), that's $1,600/day on definitions alone. A CLI command with `--help` costs ~200 tokens. Full execution cycle: <500 tokens. That's a [100x reduction](https://manveerc.substack.com/p/mcp-vs-cli-ai-agents).
+Why does the 12-command tool win?
-**Training data.** LLMs were trained on enormous volumes of shell interactions. Unix pipe chains are deeply embedded in model weights. [MCP composition patterns have zero training data and zero production hardening](https://manveerc.substack.com/p/mcp-vs-cli-ai-agents). When an agent sees `mycli list --json | jq '.[] | select(.status == "active")'`, it doesn't need to learn anything - it already knows.
+Because discrawl saw something in Discord's data that Discord itself didn't design for: **conversations are institutional knowledge**. Every message thread is a document that should be archived, indexed, and searched. Discrawl mirrors Discord into local SQLite with FTS5 full-text search, and those 12 commands - `sync`, `search`, `messages`, `mentions`, `members`, `sql`, `tail` - are worth more than 323 endpoint wrappers because they embody a deep understanding of what power users actually need.
-**Delegation, not suggestion.** [IDE agents are designed for suggestion. CLI agents are designed for delegation.](https://www.firecrawl.dev/blog/why-clis-are-better-for-agents) Terminal agents run for hours without supervision, coordinate changes across dozens of files, and self-heal on failure. Exit code 1 means "try again." Exit code 0 means "done." No screenshots, no clicking, no fragile UI automation.
-
-**Composability.** `mycli issues list --json --select id,title | jq -r '.[].id' | xargs -I{} mycli issues close {}` - one line, three tools, zero SDK imports. [CLI is the universal interface for both humans and AI agents](https://github.com/HKUDS/CLI-Anything) because text commands match LLM output format and chain into complex workflows.
-
-Every API that gets a CLI becomes instantly accessible to every agent framework - Claude Code, Codex, Gemini CLI, open source agents. No SDK integration. No dependency management. The printing press is the factory that manufactures this interface layer, one API at a time.
-
-### The Human + Agent Model
-
-```
-Power User (architect) --> Agent (operator) --> CLI (interface) --> API
- "Find stale issues" runs the command linear-cli stale GraphQL
- "Who's overloaded?" parses JSON output linear-cli load queries
- "Fix the auth bug" chains 5 commands linear-cli issue... mutations
-```
-
-The human sets direction. The agent executes. The CLI is the reliable, structured, token-efficient bridge between them. The printing press builds that bridge for any API.
+That understanding is the **Non-Obvious Insight**. And until now, discovering it required being Peter Steinberger.
## The Non-Obvious Insight
-Every API has a secret. The data it exposes is useful for something its creators never designed for. The printing press finds that secret and builds a CLI around it.
+Every API has a secret identity. The data it exposes is useful for something its creators never designed for. The printing press finds that secret and builds a CLI around it.
-The **Non-Obvious Insight (NOI)** is a one-sentence reframe of what the API's data actually IS:
+The **Non-Obvious Insight (NOI)** is a one-sentence reframe:
```
"[API] isn't just [obvious thing]. It's [non-obvious thing].
@@ -55,9 +40,23 @@ The **Non-Obvious Insight (NOI)** is a one-sentence reframe of what the API's da
| 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. |
-The NOI drives everything downstream - what the store captures, what workflow commands do, what the README says, and what insight commands detect.
+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 12 commands that matter instead of the 323 that don't.
+
+## 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.
-Phase 0 cannot complete without an NOI. If the LLM can't write one, the research wasn't deep enough.
+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."
+
+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.
+
+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.
+
+-- [Matt Van Horn](https://github.com/mvanhorn)
## The Creativity Ladder
@@ -71,7 +70,28 @@ Most API CLIs stop at Rung 1. The printing press climbs to Rung 5.
| 4 | **Domain analytics** | **Yes (from archetype)** | `stale --days 30`, `orphans`, `load` |
| 5 | **Behavioral insights** | **Yes (from archetype)** | `health` (composite score), `similar` (duplicate detection) |
-Rung 4 is where discrawl lives (12 commands, 540 stars). Rung 5 is where nobody else is yet.
+Rung 3 is table stakes. Rung 4 is where discrawl lives. Rung 5 is where nobody else is yet.
+
+The press generates the 323-command wrapper in Phase 2. Then it generates the discrawl-style commands automatically from domain archetype templates. That's the difference between a spec compiler and an intelligence engine.
+
+## Why CLIs (Not APIs, Not MCP)
+
+The NOI is the creative intelligence. CLIs are the delivery mechanism. Here's why they win for agents:
+
+**100x fewer tokens.** An MCP server loads [~55,000 tokens](https://manveerc.substack.com/p/mcp-vs-cli-ai-agents) of tool definitions per session. A CLI `--help` costs ~200 tokens. At 10K sessions/day, that's $1,600/day saved.
+
+**Training data advantage.** LLMs were trained on millions of shell interactions. When an agent sees `mycli list --json | jq '.[] | select(.status == "active")'`, it already knows. [MCP composition patterns have zero training data](https://manveerc.substack.com/p/mcp-vs-cli-ai-agents).
+
+**Self-healing delegation.** [CLI agents are designed for delegation, not suggestion.](https://www.firecrawl.dev/blog/why-clis-are-better-for-agents) Exit code 0 = done. Exit code 1 = try again. No screenshots, no clicking, no UI fragility.
+
+```
+Power User (architect) --> Agent (operator) --> CLI (interface) --> API
+ "Find stale issues" runs the command linear-cli stale GraphQL
+ "Who's overloaded?" parses JSON output linear-cli load queries
+ "Fix the auth bug" chains 5 commands linear-cli issue... mutations
+```
+
+Every API that gets a CLI becomes instantly accessible to Claude Code, Codex, Gemini CLI, and every open source agent. The printing press is the factory.
## Domain Archetypes
@@ -79,153 +99,58 @@ The profiler classifies every API into a domain archetype and auto-generates the
| Archetype | Detected By | Auto-Generated Commands |
|-----------|------------|------------------------|
-| **Project Management** | issue/task/ticket resources, assignee fields, priority levels, due dates | `stale`, `orphans`, `load`, `health`, `similar` |
-| **Communication** | message/channel/thread resources, threading fields | `channel-health`, `message-stats`, `audit-report`, `health`, `similar` |
+| **Project Management** | issue/task/ticket resources, assignee fields, priority levels | `stale`, `orphans`, `load`, `health`, `similar` |
+| **Communication** | message/channel/thread resources, threading fields | `channel-health`, `message-stats`, `health`, `similar` |
| **Payments** | charge/payment/invoice resources, amount/currency fields | `reconcile`, `revenue`, `health`, `similar` |
| **Infrastructure** | server/deploy/instance resources | `health`, `similar` |
| **Content** | document/page/block resources | `health`, `similar` |
-| **CRM** | contact/deal/lead resources | `health`, `similar` |
-| **Developer Platform** | repo/PR/commit resources | `health`, `similar` |
-The archetype is detected automatically from the spec - no configuration needed. The entity mapper figures out which resource is the "primary entity" (issues for PM, messages for comms, charges for payments) and wires the templates accordingly.
+The archetype is detected automatically from the spec. The entity mapper figures out which resource is the "primary entity" (issues for PM, messages for comms, charges for payments) and wires the templates accordingly.
## How It Works
-The press runs 8 mandatory phases. Each phase writes a comprehensive plan document. The artifacts are the product - the CLI is a side effect.
+8 mandatory phases. Each phase writes a plan document. The artifacts are the product.
```
Phase 0 Visionary Research (3-5 min) NOI + domain identity + usage patterns
Phase 0.5 Power User Workflows (2-3 min) Compound commands power users want
-Phase 0.7 Prediction Engine (15-25 min) Local data layer spec (SQLite + FTS5)
+Phase 0.7 Prediction Engine (15-25 min) SQLite schema + FTS5 + sync strategy
Phase 1 Deep Research (5-8 min) Competitors, strategic justification
-Phase 2 Generate (1-2 min) Produce Go CLI from spec + archetype templates
-Phase 3 Steinberger Audit (5-8 min) Score against quality bar, plan improvements
-Phase 4 GOAT Build (5-10 min) Review generated workflows, add NOI-driven insights
-Phase 4.5 Dogfood Emulation (10-20 min) Test every command against spec-derived mocks
-Phase 5 Final Steinberger (2-3 min) Before/after scoring delta + final report
+Phase 2 Generate (1-2 min) Go CLI from spec + archetype templates
+Phase 3 Steinberger Audit (5-8 min) 12-dimension quality scoring
+Phase 4 GOAT Build (5-10 min) Review workflows, add NOI-driven insights
+Phase 4.5 Dogfood Emulation (10-20 min) Test every command against spec mocks
+Phase 5 Final Steinberger (2-3 min) Before/after delta + report
```
-### Phase 0: Visionary Research (now with NOI gate)
-
-Before generating anything, the press understands the API's domain, users, and ecosystem. It searches GitHub, Reddit, Hacker News, and Stack Overflow for usage patterns, pain points, and existing tools. It classifies every tool it finds - API wrappers, data tools, workflow tools, environment tools - and identifies what's missing.
-
-**New gate:** Phase 0 cannot complete without writing the Non-Obvious Insight. The NOI becomes the creative DNA of the entire CLI.
-
-### Phase 0.5: Power User Workflows
-
-Predicts what compound commands a power user would want - the features that make a tool worth starring. "Find stale issues." "Show workload by team member." "Detect cross-team blockers." These workflow commands combine 2+ API calls into single operations.
-
-### Phase 0.7: Prediction Engine
-
-The differentiator. The press predicts what a developer would build on TOP of the API - without looking at competitors. It classifies every entity (accumulating, reference, append-only, ephemeral), scores them on data gravity (volume, query frequency, join demand, search need, temporal value), and produces a concrete data layer specification: domain-specific SQLite schema, incremental sync strategy with validated cursors, FTS5 full-text search with domain filters, and compound queries.
-
-### Phase 2: Generate (now with archetype templates)
-
-Runs the Go generator against the spec. For APIs with detected archetypes, the generator now automatically produces workflow commands (stale, orphans, load) and insight commands (health, similar) from templates - no Phase 4 hand-writing required.
-
-The **schema builder** uses data gravity scoring to generate domain-specific SQLite tables with extracted columns, FK indexes, and FTS5 triggers. High-gravity entities get proper column extraction instead of generic JSON blobs.
-
-### Phase 3: Steinberger Audit
-
-Scores the generated CLI against the Steinberger bar (12 dimensions, 120 max). Peter Steinberger's gogcli is the 10/10 reference.
-
-### Phase 4: GOAT Build (shifted focus)
-
-Before the Creative Vision Engine, Phase 4 meant hand-writing 7 workflow Go files. Now it means reviewing the auto-generated workflows, customizing SQL queries for unique domain patterns, and writing 2-3 NOI-driven insight commands that embody the Non-Obvious Insight. The LLM's time shifts from mechanical coding to creative domain analysis.
-
-### Phase 4.5: Dogfood Emulation
-
-Tests every command against spec-derived mock responses - no API keys needed. Scores each command on 5 dimensions. Auto-fixes issues, re-scores, and writes a report.
-
-### Phase 5: Final Steinberger
-
-Before/after scoring delta. The proof of work.
-
## What Gets Generated
-Every CLI ships with:
-
-| Feature | Flag | What It Does |
-|---------|------|-------------|
-| JSON output | `--json` | Machine-readable, pipeable to jq |
-| Field filtering | `--select id,name` | Only the fields you want |
-| Dry run | `--dry-run` | Shows the exact API request without sending |
-| Stdin input | `--stdin` | Pipe JSON body: `echo '{}' \| mycli create --stdin` |
-| Response cache | `--no-cache` | GET responses cached 5 min, bypass with flag |
-| Skip confirmation | `--yes` | For agents and scripts on destructive actions |
-| Plain output | `--plain` | Tab-separated for awk/cut |
-| CSV output | `--csv` | For spreadsheets and data tools |
-| Quiet mode | `--quiet` | Bare output, one value per line |
-| Color control | `--no-color` | Respects NO_COLOR, TERM=dumb |
-
-Plus: doctor health check, TOML config, OAuth2 browser flow, retry with backoff, rate limit detection (exit code 7), typed exit codes with actionable hints, idempotent creates/deletes, progress events as NDJSON to stderr.
-
-**Data layer** (when prediction engine identifies high-gravity entities):
-- Domain-specific SQLite tables with proper columns (not JSON blobs)
-- FTS5 full-text search with domain filters (`--channel`, `--author`, `--team`)
-- Incremental sync with validated cursors
-- `sql` command for raw read-only queries
-- `sync`, `search`, `tail`, `export`, `analytics` commands
-
-**Auto-generated workflow commands** (when domain archetype is detected):
-
-| PM APIs | Communication APIs |
-|---------|-------------------|
-| `stale` - items with no updates in N days | `channel-health` - activity analysis |
-| `orphans` - items missing assignment/project | `message-stats` - volume analytics |
-| `load` - workload distribution per assignee | `audit-report` - audit log analysis |
-
-**Auto-generated insight commands** (Rung 5):
-
-| Command | What It Does | When Generated |
-|---------|-------------|----------------|
-| `health` | Composite workspace score (0-100) from stale ratio, orphan ratio, velocity | All archetypes with store |
-| `similar` | FTS5-based duplicate detection across items | All archetypes with FTS5 |
-
-**Exit codes:** `0` success, `2` usage error, `3` not found, `4` auth error, `5` API error, `7` rate limited, `10` config error.
+Every CLI ships with: `--json`, `--select`, `--dry-run`, `--stdin`, `--csv`, `--plain`, `--quiet`, `--yes`, `--no-cache`, `--no-color`. Plus: doctor health check, TOML config, OAuth2, retry with backoff, typed exit codes (`0`=success, `2`=usage, `3`=not found, `4`=auth, `5`=API, `7`=rate limited, `10`=config).
-## 7 Plan Artifacts Per Run
+**Data layer** (high-gravity entities): domain-specific SQLite tables, FTS5 search, incremental sync, `sql` command for raw queries.
-Every run produces 7 comprehensive analysis documents in `docs/plans/`:
+**Workflow commands** (from archetype): `stale`, `orphans`, `load`, `channel-health`, `reconcile`, etc.
-```
-Phase 0 -> <api>-cli-visionary-research.md NOI, API identity, usage patterns, tool landscape
-Phase 0.5 -> <api>-cli-power-user-workflows.md Workflow ideas, scoring, top 7 selected
-Phase 0.7 -> <api>-cli-data-layer-spec.md SQLite schema, sync strategy, search filters
-Phase 1 -> <api>-cli-research.md Competitors, strategic justification
-Phase 3 -> <api>-cli-audit.md Steinberger scores, improvement plan
-Phase 4 -> <api>-cli-goat-build-log.md What was built, what was fixed
-Phase 4.5 -> <api>-cli-dogfood-report.md Per-command scores, hallucination detection
-```
-
-## Works With Any API
-
-**REST APIs** (OpenAPI/Swagger): Full pipeline - generator produces commands, archetype templates add workflows, dogfood validates everything.
-
-**GraphQL APIs** (Linear, Shopify, GitHub GraphQL): Produces scaffolding + GraphQL client wrapper, hand-writes commands in Phase 4. All research, prediction, data layer, and dogfood phases run normally.
-
-**No spec available**: Reads the API docs, writes a spec, generates from it.
-
-The press dynamically detects API type from the spec content - not a hardcoded list.
+**Insight commands** (Rung 5): `health` (composite 0-100 score), `similar` (FTS5 duplicate detection).
## The Steinberger Bar
-12 dimensions, 120 points max. Grade A = 80%+.
+Named after Peter Steinberger, whose CLIs (gogcli, discrawl) set the quality standard. 12 dimensions, 120 points max, Grade A = 80%+.
| Dimension | What 10/10 Looks Like |
|-----------|----------------------|
| Output Modes | --json, --csv, --plain, --select, --quiet, --template |
-| Auth | OAuth browser flow, token storage, multiple profiles, doctor validates |
-| Error Handling | Typed exits, retry with backoff, "did you mean?" suggestions |
-| Terminal UX | Progress spinners, color themes, pager for long output |
-| README | Install, quickstart, every command with example, cookbook, FAQ |
-| Doctor | Validates auth, API version, rate limits, config health |
+| Auth | OAuth browser flow, token storage, multiple profiles |
+| Error Handling | Typed exits, retry with backoff, actionable hints |
+| Terminal UX | Progress spinners, color themes, pager |
+| README | Install, quickstart, every command with example, cookbook |
+| Doctor | Validates auth, API version, rate limits, config |
| Agent-Native | --json, --select, --dry-run, --stdin, idempotent, typed exits |
-| Local Cache | SQLite + FTS5, --no-cache bypass, cache clear |
-| Breadth | Every API endpoint covered + convenience wrappers |
+| Local Cache | SQLite + FTS5, --no-cache bypass |
+| Breadth | Every endpoint + convenience wrappers |
| Vision | Sync + search + tail + export + domain workflows |
| Workflows | Compound commands combining 2+ API calls |
-| **Insight** | **Behavioral commands that see patterns humans miss (health, similar, bottleneck)** |
+| Insight | Behavioral commands that see patterns humans miss |
## Quick Start
@@ -235,60 +160,18 @@ cd cli-printing-press
go build -o ./printing-press ./cmd/printing-press
```
-Then use it as a Claude Code skill:
+Then in Claude Code:
```bash
-# In Claude Code
/printing-press Discord
/printing-press Stripe
/printing-press --spec ./openapi.yaml
```
-Or run the generator directly:
+## Credits
-```bash
-# Generate from an OpenAPI spec
-./printing-press generate --spec https://petstore3.swagger.io/api/v3/openapi.json --output ./petstore-cli --force --lenient --validate
-
-# Score a generated CLI
-./printing-press scorecard --dir ./petstore-cli
-```
-
-## Project Structure
-
-```
-cmd/printing-press/ CLI entry point
-internal/
- catalog/ Catalog schema validator
- cli/ CLI commands (generate, scorecard, version)
- docspec/ Doc-to-spec generator
- generator/ Template engine + quality gates
- entity_mapper.go Entity role detection and field mapping (NEW)
- schema_builder.go Data gravity scoring + domain table generation (NEW)
- templates/ Go templates
- workflows/ PM workflow templates (stale, orphans, load) (NEW)
- insights/ Behavioral insight templates (health, similar) (NEW)
- llm/ LLM runner (claude/codex CLI)
- llmpolish/ LLM polish pass (help, examples, README)
- openapi/ OpenAPI 3.0+ parser (strict + lenient modes)
- pipeline/ Intelligence engine (research, scorecard, dogfood, planner)
- profiler/ API shape + domain archetype analysis (EXTENDED)
- spec/ Internal YAML spec parser
- vision/ Visionary plan types + NOI system (EXTENDED)
- insight.go Non-Obvious Insight struct (NEW)
-catalog/ Known API specs with verified URLs
-skills/printing-press/ Claude Code skill definition (8-phase pipeline)
- references/
- noi-examples.md 10+ NOI examples across all archetypes (NEW)
-docs/plans/ Generated plan artifacts
-```
-
-## Development
-
-```bash
-go build -o ./printing-press ./cmd/printing-press
-go test ./...
-```
+- **Peter Steinberger** ([@steipete](https://github.com/steipete)) - [discrawl](https://github.com/steipete/discrawl) and [gogcli](https://github.com/steipete/gogcli) set the bar. The Steinberger quality scoring system is named after him.
+- **Matt Van Horn** ([@mvanhorn](https://github.com/mvanhorn)) - Author of the printing press and [/last30days](https://github.com/mvanhorn/last30days-skill) recency research skill.
## License
diff --git a/docs/plans/2026-03-26-docs-readme-noi-storytelling-plan.md b/docs/plans/2026-03-26-docs-readme-noi-storytelling-plan.md
new file mode 100644
index 00000000..48679e00
--- /dev/null
+++ b/docs/plans/2026-03-26-docs-readme-noi-storytelling-plan.md
@@ -0,0 +1,100 @@
+---
+title: "docs: Rewrite README around the NOI as the hero, with discrawl and gogcli stories"
+type: docs
+status: completed
+date: 2026-03-26
+---
+
+# docs: Rewrite README around the NOI as the hero
+
+## The Narrative Problem
+
+The README currently has two competing heroes: the agent/token economics section and the NOI section. The agent stuff is the *obvious* insight - everyone knows CLIs are better for agents. The NOI is the *non-obvious* insight about the printing press itself. The README should practice what it preaches.
+
+The user's key insight: "Just making a CLI is not hard. Making a Non-Obvious power-user thoughtful CLI is extremely hard, and that's the magic of this."
+
+## The Story to Tell
+
+### Act 1: The discrawl revelation
+
+Discord has 300+ API endpoints. The printing press can generate a CLI that wraps all 323 of them. But discrawl - Peter Steinberger's Discord tool - has 12 commands and 551 stars. Why?
+
+Because discrawl saw something in Discord's data that Discord itself didn't design for: conversations are institutional knowledge. Every message thread is a document that should be archived, indexed, and searched. The 12 commands that embody that insight are worth more than 323 that don't.
+
+That's the Non-Obvious Insight. And until now, discovering it required Peter Steinberger.
+
+### Act 2: The gogcli vs Google surprise
+
+Matt Van Horn (the author) was deciding which Google Workspace CLI to use. He ran [/last30days](https://github.com/mvanhorn/last30days-skill) - his recency research skill - to compare gogcli (Steinberger's, 6.5K stars) vs Google's official Workspace CLI (10K+ stars in a week). The community data said: use gogcli. The newer, official one with 10x the API coverage lost to the older third-party one.
+
+Why? Because gogcli understands what users actually DO with Google Workspace. Human-friendly flags. Sane defaults. Workflow-oriented commands. The official one wraps every API endpoint but doesn't understand the user.
+
+That's the NOI again. Breadth doesn't beat depth. Understanding the user beats understanding the API.
+
+### Act 3: The printing press automates the insight
+
+The printing press doesn't just wrap APIs. It discovers the NOI automatically:
+
+1. **Profiler** classifies the API's domain archetype (PM, communication, payments...)
+2. **Phase 0** forces the LLM to write the NOI before proceeding
+3. **Entity mapper** identifies which resources are primary vs support
+4. **Data gravity scoring** determines what deserves local SQLite tables vs API-only
+5. **Workflow templates** generate domain-specific commands from the archetype
+6. **Insight templates** generate behavioral analysis commands
+
+The result: a CLI that thinks like discrawl, not like a spec compiler.
+
+## Proposed README Structure
+
+### 1. Rewrite opening tagline
+
+Something that captures: this is the NOI engine, not just a CLI generator.
+
+### 2. Restructure to lead with the story, not the mechanics
+
+Current order:
+1. Tagline
+2. Why CLIs Matter (agent economics)
+3. NOI section
+4. Creativity Ladder
+5. Domain Archetypes
+6. How It Works (phases)
+
+New order:
+1. Tagline (NOI-focused)
+2. **The discrawl story** (323 commands < 12 commands)
+3. **The NOI concept** (the formula, the examples)
+4. **The gogcli surprise** (Matt's personal story with /last30days)
+5. Why CLIs Matter (agent economics - shorter, supporting role)
+6. Creativity Ladder + Domain Archetypes
+7. How It Works (phases)
+
+### 3. Give credit to last30days
+
+Include that the gogcli comparison was done with [last30days](https://github.com/mvanhorn/last30days-skill) - Matt Van Horn's recency research skill that searches Reddit, X, YouTube, and more.
+
+### 4. The discrawl numbers
+
+| | Discord API Wrapper | discrawl |
+|---|---|---|
+| Commands | 323 | 12 |
+| What it wraps | Every endpoint | None (custom) |
+| Local persistence | Generic JSON blobs | Domain-specific SQLite + FTS5 |
+| Stars | ~0 | 551 |
+| The insight | "Discord has channels" | "Discord is a knowledge base" |
+
+The press generates the 323-command wrapper in Phase 2. Then it generates the 12 discrawl-style commands in Phase 4. That's the difference between Rung 1 and Rung 5.
+
+## Acceptance Criteria
+
+- [ ] README leads with the discrawl story (323 vs 12 commands narrative)
+- [ ] NOI section comes immediately after the story, as the explanation
+- [ ] gogcli vs Google Workspace CLI story included with /last30days credit
+- [ ] Agent/token economics section shortened to supporting role (not the lead)
+- [ ] Credit to Peter Steinberger for discrawl and gogcli
+- [ ] Credit to Matt Van Horn and /last30days
+- [ ] The printing press framed as "automates the insight Peter Steinberger does manually"
+
+## Files
+
+- `README.md`
← b52da339 docs: add agent-native thesis with research-backed token eco
·
back to Cli Printing Press
·
feat(generator): Apache 2.0 license on generated CLIs with N 86c5d908 →