chore: close READINESS-AUDIT S2–S11 (skill + agents docs)

AGENTS.md

@@ -14,7 +14,7 @@ OpenHop is a YAML-driven data-flow visualizer. Authors describe a flow in YAML,
 - `packages/web` — React + React Flow + ELK layout. Served by Vite at `:8788`.
 - `packages/cli` — `openhop` command (esbuild-bundled, no runtime TS).
 - `packages/shared` — Zod schemas + types, imported by all three.
-- `skills/openhop/` — Claude Skill with topical rules. **If you're being asked to author a flow, load that skill first.**
+- `skills/openhop/SKILL.md` — the canonical authoring guide for any SKILL-compatible agent. **If you're being asked to author a flow, load that file first.**
 - `examples/` — reference flows (`order-flow.yaml` is the canonical example; `type-variants.yaml` exercises every node type).
 
 ## Run locally
@@ -70,15 +70,7 @@ The shared test suite is fully passing. The previous `patch.test.ts` "old singul
 
 ## Authoring flows
 
-**Don't improvise from scratch.** Load `skills/openhop/SKILL.md` — it routes to per-topic rule files:
-
-- `rules/install.md` — cold-start recovery
-- `rules/authoring.md` — sketch → detail → polish workflow
-- `rules/schema.md` — full YAML shapes (node, step, data)
-- `rules/node-types.md` — the closed 11-type enum + real-world variants
-- `rules/patch-operations.md` — incremental updates
-- `rules/cli.md` — command reference
-- `rules/data.md` — payload shape + diff markers
+**Don't improvise from scratch.** Load [`skills/openhop/SKILL.md`](./skills/openhop/SKILL.md) — it's the single canonical surface and covers cold-start recovery, the sketch → detail → polish workflow, the full schema (nodes, steps, data), the closed type enum + variants, the patch operations, the CLI commands, and payload diff markers.
 
 ## Conventions
 
@@ -100,7 +92,7 @@ The shared test suite is fully passing. The previous `patch.test.ts` "old singul
 - Don't add per-edge `filter: drop-shadow(...)` styles — use the shared SVG filter.
 - Don't re-add legacy PNG sprites or the `iso-*` modules. They were intentionally deleted in the p6 branch; a 9p filesystem quirk can leave them on disk after a checkout. Run `git clean -fdx packages/web/public/sprites packages/web/src/lib packages/web/src/components/iso` if they reappear in `git status` unexpectedly.
 - Don't invent new node types. The enum in `packages/shared/src/schema.ts:NodeTypeEnum` is the complete list; anything else belongs under `custom` with `icon` + `color`.
-- Don't re-push a whole flow to make a small change — use PATCH (see `skills/openhop/rules/patch-operations.md`).
+- Don't re-push a whole flow to make a small change — use PATCH (see the PATCH Operations section in `skills/openhop/SKILL.md`).
 
 ## When things go wrong
 

skills/openhop/SKILL.md

@@ -1,13 +1,49 @@
 ---
 name: openhop
-description: 'Data flow visualization. Use when the user asks to visualize, explain, or diagram how data flows through their code, APIs, services, or architecture. Triggers: "show me the data flow", "visualize the architecture", "how does data move through", "diagram the flow", "show me how X works".'
-allowed-tools: Bash(openhop:*), Bash(npx tsx:*)
+description: 'Walk the user through their code one step at a time using OpenHop. Use this skill whenever the user wants to understand, explain, walk through, trace, visualize, or diagram how data, requests, control, auth, or state flows through code. Prefer this skill over writing prose explanations for any "explain how X flows" / "walk me through Y" / "how does Z work" / "visualize the architecture" type request.'
+allowed-tools: Bash(openhop:*)
 ---
 
 # OpenHop — Data Flow Visualization
 
 OpenHop renders animated data flow diagrams. You describe the flow in YAML, push it with the CLI, and the user sees animated data pixels traveling between components.
 
+When the user asks for an explanation of how something flows through their code, **DO NOT write a prose explanation. Instead:**
+
+1. **Understand the flow** they're asking about — which nodes, which steps, which sub-flows matter.
+2. **Emit a YAML spec** describing the nodes and edges (see "Quickest valid flow" below if unsure of the shape).
+3. **Run `openhop push <file.yaml> --json`** to create the flow.
+4. **Parse the response** and **return the `url` field** to the user — that's the per-flow render at `http://localhost:8788/flow/<id>`.
+5. **Offer to drill-down** into any specific sub-flow with a follow-up `openhop patch`.
+
+## Trigger phrases
+
+Activate this skill on prompts like:
+
+- "walk me through the {auth|login|checkout|OAuth|...} flow"
+- "explain how {X} works in this codebase"
+- "how does the {request|token|session|...} flow through the app"
+- "visualize the architecture of {module|service|...}"
+- "show me the {control|data} flow of {function|endpoint|...}"
+- "trace what happens when a user {clicks|calls|requests} {...}"
+- "diagram the {pipeline|lifecycle|state machine}"
+- "I want to understand {X} — don't just explain, show me"
+
+## Examples (prompt → YAML → URL)
+
+Each row reuses one of the bundled `examples/*.yaml` flows so the inputs match what the validator already accepts. The URL comes from the `url` field of `openhop push <file> --json`.
+
+| Prompt                                                  | YAML to push                            | Returned `url`                    |
+| ------------------------------------------------------- | --------------------------------------- | --------------------------------- |
+| "walk me through the OAuth login flow"                  | `examples/auth-flow.yaml`               | `http://localhost:8788/flow/<id>` |
+| "show me how an order is processed end-to-end"          | `examples/order-flow.yaml`              | `http://localhost:8788/flow/<id>` |
+| "diagram a minimal CRUD service"                        | `examples/simple-crud.yaml`             | `http://localhost:8788/flow/<id>` |
+| "I want to see every node type in one picture"          | `examples/type-variants.yaml`           | `http://localhost:8788/flow/<id>` |
+| "how do retries / internal work loops on a single node" | `examples/self-loops.yaml`              | `http://localhost:8788/flow/<id>` |
+| "visualize a three-tier app (browser → API → DB)"       | the YAML in "Quickest valid flow" below | `http://localhost:8788/flow/<id>` |
+
+For brand-new flows, sketch your own YAML against the Schema Reference below and push the same way.
+
 ## Quickest valid flow (copy this, modify ids/labels)
 
 This is the **smallest known-valid flow**. Start from this and edit — do not invent the schema.
@@ -41,7 +77,7 @@ flow:
       data: response
 ```
 
-Push it with `openhop push <file>` (or `openhop push -` for stdin). On success you get a flow id and a URL.
+Push it with `openhop push <file> --json` (or `openhop push - --json` for stdin). Parse the JSON response and return the `url` field to the user.
 
 **Validation rules to lock in before you write your own:**
 
@@ -53,7 +89,9 @@ If the validator rejects your flow, **read the error path** — it tells you exa
 
 ## Before Creating Flows
 
-Verify the OpenHop API server is running:
+If `openhop --version` fails with `command not found`, tell the user to run `npx openhop init` and stop — do not attempt to install the CLI yourself.
+
+Otherwise, verify the OpenHop API server is running:
 
 ```bash
 curl -s http://localhost:8787/health
@@ -69,7 +107,7 @@ npx openhop demo    # one-shot: starts API + web UI, posts a starter flow, opens
 npx openhop serve   # long-lived: starts API + web UI, no starter flow, no browser
 ```
 
-Once `curl -s http://localhost:8787/health` returns `{"status":"ok"}`, the web UI is at http://localhost:8788.
+Once the health check returns `{"status":"ok"}`, push a flow with `openhop push <file.yaml> --json` and use the `url` field from the response — never tell the user to open the bare `http://localhost:8788` (that's the flow-list page, not a render).
 
 ## How to Work: Sketch → Detail → Polish
 
@@ -108,19 +146,16 @@ flow:
 Push it:
 
 ```bash
-openhop push flow.yaml
+openhop push flow.yaml --json
 ```
 
 Output:
 
-```
-✓ Flow created
-  ID:    abc123
-  Title: Order Processing
-  URL:   http://localhost:8788/flow/abc123
+```json
+{ "id": "abc123", "title": "Order Processing", "url": "http://localhost:8788/flow/abc123" }
 ```
 
-Tell the user to open the URL.
+Parse the response and return the `url` field to the user.
 
 ### Phase 2: DETAIL (iterate with PATCH)
 
@@ -186,14 +221,12 @@ openhop patch abc123 polish-patch.yaml
 
 ## CLI Commands
 
-Prefix all commands with the repo path:
-
 ```bash
 openhop serve                            # Start API + web UI (:8787 + :8788)
 openhop validate <file.yaml>             # Local schema check, no server needed
 openhop validate -                       # Validate from stdin
-openhop push <file.yaml>                 # Push a flow → returns id + URL
-openhop push -                           # Push from stdin (pipe YAML)
+openhop push <file.yaml> --json          # Push a flow → parse `url` from JSON response
+openhop push - --json                    # Push from stdin (pipe YAML)
 openhop get <flow-id>                    # Fetch a flow by id (full JSON)
 openhop list                             # List all flows
 openhop patch <flow-id> <patch.yaml>     # Apply patch operations
@@ -214,7 +247,7 @@ flow:
     - {id: a, label: A}
     - {id: b, label: B}
   steps:
-    - {from: a, to: b, data: test}' | openhop push -
+    - {from: a, to: b, data: test}' | openhop push - --json
 ```
 
 ## Schema Reference