← back to Cli Printing Press
docs: update README with Creative Vision Engine, NOI system, and domain archetypes
0c1316fbb997d39d371cfaf4a06d5dcff7234bec · 2026-03-26 10:08:32 -0700 · Matt Van Horn
Rewrites the README to showcase the printing press's creative capabilities:
- Non-Obvious Insight (NOI) section with formula and 6 API examples
- Creativity Ladder (Rungs 1-5) explaining depth vs wrapper distinction
- Domain Archetype table showing auto-generated commands per archetype
- Updated Steinberger Bar to 12 dimensions (added Insight)
- Updated project structure with new files (entity_mapper, schema_builder,
workflow templates, insight templates, noi-examples.md)
- Updated Phase 2/4 descriptions to reflect auto-generation shift
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Files touched
M README.mdA docs/plans/2026-03-26-docs-readme-creative-vision-engine-plan.md
Diff
commit 0c1316fbb997d39d371cfaf4a06d5dcff7234bec
Author: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Date: Thu Mar 26 10:08:32 2026 -0700
docs: update README with Creative Vision Engine, NOI system, and domain archetypes
Rewrites the README to showcase the printing press's creative capabilities:
- Non-Obvious Insight (NOI) section with formula and 6 API examples
- Creativity Ladder (Rungs 1-5) explaining depth vs wrapper distinction
- Domain Archetype table showing auto-generated commands per archetype
- Updated Steinberger Bar to 12 dimensions (added Insight)
- Updated project structure with new files (entity_mapper, schema_builder,
workflow templates, insight templates, noi-examples.md)
- Updated Phase 2/4 descriptions to reflect auto-generation shift
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
README.md | 136 +++++++++++++++------
...3-26-docs-readme-creative-vision-engine-plan.md | 101 +++++++++++++++
2 files changed, 201 insertions(+), 36 deletions(-)
diff --git a/README.md b/README.md
index 6e3eec0b..0662320c 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
# CLI Printing Press
-Give it an API name. Get back the best CLI that has ever existed for it.
+Give it an API name. Get back a CLI that sees what the API's own creators missed.
```bash
/printing-press Discord
@@ -10,65 +10,107 @@ Give it an API name. Get back the best CLI that has ever existed for it.
One command. 8 phases. ~1 hour. Produces a production-ready Go CLI binary + 7 deep analysis documents. REST or GraphQL - it figures it out.
-## Why CLIs Matter Now
+## The Non-Obvious Insight
-CLIs are the native interface for AI agents. When an agent needs to interact with an API, it has two choices: import an SDK and write 15 lines of code (~500 tokens), or run a CLI command (~50 tokens). The CLI wins on every dimension that matters - deterministic, structured JSON output, composable with pipes, zero dependency management.
+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 that gets a CLI becomes instantly accessible to every agent framework - Claude Code, Codex, Gemini CLI, open source agents. No SDK integration. No code generation. Just `--json --select` and pipe.
+The **Non-Obvious Insight (NOI)** is a one-sentence reframe of what the API's data actually IS:
-The printing press is an agent-infrastructure factory. One hour per API, and every agent in the world can use it.
+```
+"[API] isn't just [obvious thing]. It's [non-obvious thing].
+ Every [data point] is a signal about [hidden truth]."
+```
+
+| API | What they think it is | What it actually is |
+|-----|----------------------|---------------------|
+| Discord | A chat app | A **searchable knowledge base**. Every message thread is institutional memory. |
+| Linear | An issue tracker | A **team behavior observatory**. Every state change is a signal about how your team actually works vs. how they think they work. |
+| Stripe | A payment processor | A **business health monitor**. Every failed charge and churn event is a signal about product-market fit. |
+| 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. |
+
+The NOI drives everything downstream - what the store captures, what workflow commands do, what the README says, and what insight commands detect.
+
+Phase 0 cannot complete without an NOI. If the LLM can't write one, the research wasn't deep enough.
+
+## The Creativity Ladder
+
+Most API CLIs stop at Rung 1. The printing press climbs to Rung 5.
+
+| Rung | What It Is | Auto-Generated? | Example |
+|------|-----------|-----------------|---------|
+| 1 | API wrapper commands | Yes (from spec) | `issue create --title "..."` |
+| 2 | Output formatting | Yes (always) | `--json`, `--select`, `--csv`, `--dry-run` |
+| 3 | Local persistence | Yes (conditional) | `sync`, `search`, `export`, `tail` |
+| 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.
+
+## Domain Archetypes
+
+The profiler classifies every API into a domain archetype and auto-generates the right workflow + insight commands:
+
+| 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` |
+| **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.
## 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.
```
-Phase 0 Visionary Research (3-5 min) Who uses this API? What do they build?
-Phase 0.5 Power User Workflows (2-3 min) What compound commands would power users want?
-Phase 0.7 Prediction Engine (15-25 min) What local data layer would make this a 500-star tool?
-Phase 1 Deep Research (5-8 min) What competitors exist? Why should this CLI exist?
-Phase 2 Generate (1-2 min) Produce the Go CLI from the API spec
-Phase 3 Steinberger Audit (5-8 min) Score against the quality bar, plan improvements
-Phase 4 GOAT Build (5-10 min) Build data layer + workflow commands + fixes
+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 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 0: Visionary Research
+### 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 channels." "Audit who banned whom." "Preview a member prune without executing." These workflow commands combine 2+ API calls into single operations.
+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
-This is 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.
+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.
-This is how you build discrawl (12 commands, 540 stars) without knowing discrawl exists.
+### Phase 2: Generate (now with archetype templates)
-### Phase 1: Deep Research
+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.
-Finds the OpenAPI or GraphQL spec, analyzes the top 2 competitors in depth (READMEs, star counts, open issues, user complaints), and answers: "Why should this CLI exist when [competitor] already has [N] stars?"
-
-### Phase 2: Generate
-
-Runs the Go generator against the spec. Produces hundreds of commands with full agent-native features. For GraphQL APIs, produces scaffolding + a GraphQL client wrapper - commands get hand-written in Phase 4.
+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 (11 dimensions, 110 max). Peter Steinberger's gogcli is the 10/10 reference. Each dimension gets: current score, what 10/10 looks like, and specific changes to get there.
+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
+### Phase 4: GOAT Build (shifted focus)
-Builds the product. Priority 0 is the data layer (domain SQLite tables, sync, search, sql command). Priority 1 is workflow commands powered by the local database. Priority 2 is scorecard gap fixes. Priority 3 is polish.
+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 (request construction, response parsing, schema fidelity, example quality, workflow integrity). Auto-fixes issues, re-scores, and writes a report: "Here's what I learned. Here's what to fix. Here's what to make."
-
-Inspired by [Vercel's emulate](https://github.com/vercel-labs/emulate) - production-fidelity API simulation, zero config.
+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
@@ -100,6 +142,21 @@ Plus: doctor health check, TOML config, OAuth2 browser flow, retry with backoff,
- `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.
## 7 Plan Artifacts Per Run
@@ -107,7 +164,7 @@ Plus: doctor health check, TOML config, OAuth2 browser flow, retry with backoff,
Every run produces 7 comprehensive analysis documents in `docs/plans/`:
```
-Phase 0 -> <api>-cli-visionary-research.md API identity, usage patterns, tool landscape
+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
@@ -116,13 +173,11 @@ 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
```
-Each artifact chains into the next. The prediction engine's data layer spec informs Phase 4's implementation. The dogfood report's fix recommendations feed back into the code.
-
## Works With Any API
-**REST APIs** (OpenAPI/Swagger): Full pipeline - generator produces commands, prediction engine adds data layer, dogfood validates everything.
+**REST APIs** (OpenAPI/Swagger): Full pipeline - generator produces commands, archetype templates add workflows, dogfood validates everything.
-**GraphQL APIs** (Linear, Shopify, GitHub GraphQL): Warns about generator limitations, produces scaffolding + GraphQL client wrapper, hand-writes commands in Phase 4. All research, prediction, data layer, and dogfood phases run normally.
+**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.
@@ -130,7 +185,7 @@ The press dynamically detects API type from the spec content - not a hardcoded l
## The Steinberger Bar
-11 dimensions, 110 points max. Grade A = 80%+.
+12 dimensions, 120 points max. Grade A = 80%+.
| Dimension | What 10/10 Looks Like |
|-----------|----------------------|
@@ -145,6 +200,7 @@ The press dynamically detects API type from the spec content - not a hardcoded l
| Breadth | Every API endpoint covered + 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)** |
## Quick Start
@@ -182,15 +238,23 @@ internal/
cli/ CLI commands (generate, scorecard, version)
docspec/ Doc-to-spec generator
generator/ Template engine + quality gates
- templates/ 14 Go templates (root, command, store, sync, search, etc.)
+ 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 analysis (volume, search need, realtime, etc.)
+ 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
```
diff --git a/docs/plans/2026-03-26-docs-readme-creative-vision-engine-plan.md b/docs/plans/2026-03-26-docs-readme-creative-vision-engine-plan.md
new file mode 100644
index 00000000..4fa98cc0
--- /dev/null
+++ b/docs/plans/2026-03-26-docs-readme-creative-vision-engine-plan.md
@@ -0,0 +1,101 @@
+---
+title: "docs: Update README with Creative Vision Engine"
+type: docs
+status: completed
+date: 2026-03-26
+---
+
+# docs: Update README with Creative Vision Engine
+
+## Overview
+
+The README accurately describes the 8-phase pipeline but is missing the Creative Vision Engine - the biggest upgrade to the printing press since launch. The NOI concept, domain archetype detection, auto-generated workflow/insight commands, the schema builder, and the 12-dimension scorecard are all shipped but invisible to anyone reading the README.
+
+## What's Missing
+
+1. **Non-Obvious Insight (NOI)** - The creative soul of every generated CLI. The formula. The examples. The Phase 0 gate. This is the headline feature and it's not mentioned anywhere.
+
+2. **Domain Archetype System** - The profiler now classifies APIs into 8 archetypes (communication, PM, payments, infrastructure, content, CRM, developer-platform, generic). This drives automatic workflow generation. Not mentioned.
+
+3. **Auto-Generated Workflow Commands** - PM APIs now get `stale`, `orphans`, `load` automatically from templates. Communication APIs get `channel-health`, `message-stats`. This is the Rung 4 breakthrough - not mentioned.
+
+4. **Behavioral Insight Commands** - `health` (composite score) and `similar` (FTS5 duplicate detection) generate automatically. These are Rung 5 - not mentioned.
+
+5. **Schema Builder** - Data gravity scoring now drives domain-specific SQLite table generation (extracted columns, FK indexes, FTS5 triggers). The store.go.tmpl uses real columns instead of JSON blobs. Not mentioned.
+
+6. **12-Dimension Scorecard** - Added "Insight" dimension. Now 12 dimensions, 120 max. Grade thresholds unchanged. Not updated in README.
+
+7. **The Creativity Ladder** - The conceptual framework (Rung 1-5) that explains why the press is different. Not mentioned.
+
+## Proposed Changes to README.md
+
+### Section 1: Update the tagline and intro
+
+Change "Give it an API name. Get back the best CLI that has ever existed for it." to something that captures the NOI concept. The press doesn't just make CLIs - it sees the non-obvious insight in every API.
+
+### Section 2: Add NOI section after "How It Works"
+
+New section: "The Non-Obvious Insight" - explain the formula, show 4-5 examples, explain why it matters. This is the hook that makes people go "holy shit."
+
+### Section 3: Add "The Creativity Ladder" section
+
+Explain the 5 rungs:
+1. API wrapper commands (always generated)
+2. Output formatting (always generated)
+3. Local persistence (conditional - sync, search, export)
+4. Domain analytics (NEW - auto-generated from archetype templates)
+5. Behavioral insights (NEW - auto-generated health, similar, etc.)
+
+The press now reaches Rung 5 automatically. Before this update, it stopped at Rung 3.
+
+### Section 4: Update "What Gets Generated" section
+
+Add the new auto-generated commands:
+
+| PM APIs | Communication APIs |
+|---|---|
+| `stale` - items with no updates in N days | `channel-health` - activity analysis |
+| `orphans` - items missing assignment | `message-stats` - volume analytics |
+| `load` - workload distribution | `audit-report` - audit log analysis |
+| `health` - composite workspace score | `health` - composite score |
+| `similar` - FTS5 duplicate detection | `similar` - duplicate detection |
+
+### Section 5: Update Steinberger Bar table
+
+Add 12th dimension: Insight (behavioral insight commands that see patterns humans miss).
+
+### Section 6: Update Project Structure
+
+Add new files:
+- `internal/vision/insight.go` - NOI struct
+- `internal/generator/entity_mapper.go` - Entity role mapping
+- `internal/generator/schema_builder.go` - Data gravity scoring + schema generation
+- `internal/generator/templates/workflows/` - PM workflow templates
+- `internal/generator/templates/insights/` - Behavioral insight templates
+- `skills/printing-press/references/noi-examples.md` - 10+ NOI examples
+
+### Section 7: Add "Domain Archetypes" section
+
+Brief explanation of how the profiler classifies APIs and what templates each archetype gets.
+
+## Acceptance Criteria
+
+- [ ] NOI concept explained with formula and 4+ examples
+- [ ] Creativity Ladder (Rungs 1-5) explained
+- [ ] Auto-generated workflow commands listed by archetype
+- [ ] Behavioral insight commands (health, similar) described
+- [ ] Steinberger Bar updated to 12 dimensions
+- [ ] Project structure updated with new files/directories
+- [ ] Domain archetypes listed with signals
+
+## Files to Modify
+
+- `README.md` - Main update target
+
+## Implementation
+
+Single file edit. Read current README, rewrite sections in place. Keep existing content where it's still accurate (phases, flags, exit codes). Add new sections for NOI, creativity ladder, domain archetypes, auto-generated commands.
+
+### Tone
+
+Match the existing README's energy - direct, confident, specific. Use the NOI examples to create a "holy shit" moment for the reader. The NOI formula should hit like a revelation, not a feature description.
← 63b89f6d feat(generator): add schema builder with data gravity scorin
·
back to Cli Printing Press
·
docs: add agent-native thesis with research-backed token eco b52da339 →