docs(onboarding): clarify that /printing-press skill is the primary entry point

430d60955d9a615e5b5056c218d3e7e7bc6840f5 · 2026-03-27 16:01:58 -0700 · Trevin Chow

Add "How It's Used" section and reorder Primary Flows so the
skill-driven pipeline comes first and direct generation is framed
as the lower-level escape hatch.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Files touched

M ONBOARDING.md

Diff

commit 430d60955d9a615e5b5056c218d3e7e7bc6840f5
Author: Trevin Chow <trevin@trevinchow.com>
Date:   Fri Mar 27 16:01:58 2026 -0700

    docs(onboarding): clarify that /printing-press skill is the primary entry point
    
    Add "How It's Used" section and reorder Primary Flows so the
    skill-driven pipeline comes first and direct generation is framed
    as the lower-level escape hatch.
    
    Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 ONBOARDING.md | 34 +++++++++++++++++++++-------------
 1 file changed, 21 insertions(+), 13 deletions(-)

diff --git a/ONBOARDING.md b/ONBOARDING.md
index b1fd9d50..1e685092 100644
--- a/ONBOARDING.md
+++ b/ONBOARDING.md
@@ -8,6 +8,14 @@ This is built as a Claude Code skill. You run `/printing-press Discord` inside C
 
 ---
 
+## How It's Used
+
+The primary entry point for users is the **`/printing-press` Claude Code skill** (defined in `skills/printing-press/`). A user types `/printing-press <API name>` inside Claude Code and the skill drives the entire pipeline. Everything else in this repo -- the Go binary, the parsers, the templates, the profiler -- exists to serve that skill.
+
+Developers working on this codebase build and test the Go binary directly (`go build`, `go test`), but the thing you're ultimately shipping is the skill-driven experience.
+
+---
+
 ## How Is It Organized?
 
 ```
@@ -76,9 +84,20 @@ This project has no external service dependencies. It's a pure Go binary that re
 
 ## Primary Flows
 
-### Flow 1: Direct Generation (`printing-press generate`)
+### Flow 1: Pipeline Orchestration (`/printing-press` skill -> `printing-press print`)
+
+This is the flow users hit. The `/printing-press` Claude Code skill invokes `printing-press print`:
 
-For one-shot generation from a spec file:
+1. `internal/cli/root.go` (`newPrintCmd`) calls `pipeline.Init()` with the API name
+2. `pipeline.Init()` calls `DiscoverSpec()` which looks up the API in `catalog/` entries
+3. Seeds are written for each of the 8 phases into `docs/plans/<api>-pipeline/`
+4. `state.json` is created to track progress across sessions
+5. The user runs `/ce:work` on each phase plan sequentially
+6. `CompleteAndPlanNext()` dynamically generates the next phase's plan using outputs from completed phases
+
+### Flow 2: Direct Generation (`printing-press generate`)
+
+Lower-level escape hatch for one-shot generation from a spec file:
 
 ```
 printing-press generate --spec ./openapi.yaml
@@ -114,17 +133,6 @@ Quality gates (if --validate)
   -> binary --help -> version -> doctor
 ```
 
-### Flow 2: Pipeline Orchestration (`printing-press print`)
-
-For the full multi-phase experience used by the Claude Code skill:
-
-1. `internal/cli/root.go` (`newPrintCmd`) calls `pipeline.Init()` with the API name
-2. `pipeline.Init()` calls `DiscoverSpec()` which looks up the API in `catalog/` entries
-3. Seeds are written for each of the 8 phases into `docs/plans/<api>-pipeline/`
-4. `state.json` is created to track progress across sessions
-5. The user runs `/ce:work` on each phase plan sequentially
-6. `CompleteAndPlanNext()` dynamically generates the next phase's plan using outputs from completed phases
-
 ### Flow 3: Docs-to-Spec (`--docs`)
 
 When no spec file exists, `--docs https://api.example.com/docs` scrapes the docs page via `internal/docspec/`, extracts endpoints using regex (or LLM if available), and produces an `APISpec` that feeds into the standard generation path.

← 66abf782 fix(skill): Phase 0.1 must WAIT for API key answer before pr · back to Cli Printing Press · feat(generator): route generated CLI output to shelf/ direct 34e646c2 →