@coldtea/pr-lens-agent-skill 0.1.0 → 0.1.2

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Ohans Emmanuel
+Copyright (c) 2026 Coldtea AI
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,8 +1,8 @@
 # @coldtea/pr-lens-agent-skill
 
-The PR Lens skill for coding agents. It teaches an agent to draw the change it just made: author a graph document from the diff, validate it against the contract, render it, attach it to the pull request — and to fix a repository's map by writing corrections rather than editing generated output.
+The PR Lens skill for coding agents. It teaches an agent to draw the change it just made: author a graph document from the diff, validate it against the contract, render it, attach it to the pull request, and to fix a repository's map by writing corrections rather than editing generated output.
 
-MIT © Ohans Emmanuel.
+MIT © Coldtea AI.
 
 ## Install it
 
@@ -10,21 +10,21 @@ MIT © Ohans Emmanuel.
 npm install --save-dev @coldtea/pr-lens-agent-skill
 ```
 
-**Claude Code** — copy it where skills live, per project or per user:
+**Claude Code**: copy it where skills live, per project or per user:
 
 ```bash
 mkdir -p .claude/skills/pr-lens
 cp -R node_modules/@coldtea/pr-lens-agent-skill/{SKILL.md,references} .claude/skills/pr-lens/
 ```
 
-**Cursor** — the same file works as a rule:
+**Cursor**: the same file works as a rule:
 
 ```bash
 mkdir -p .cursor/rules
 cp node_modules/@coldtea/pr-lens-agent-skill/SKILL.md .cursor/rules/pr-lens.mdc
 ```
 
-**Anything else** — point your agent's instructions file at `SKILL.md`. It is plain markdown with YAML frontmatter, and it assumes nothing beyond a shell and `npx`.
+**Anything else**: point your agent's instructions file at `SKILL.md`. It is plain markdown with YAML frontmatter, and it assumes nothing beyond a shell and `npx`.
 
 ## What is in it
 
@@ -34,7 +34,7 @@ cp node_modules/@coldtea/pr-lens-agent-skill/SKILL.md .cursor/rules/pr-lens.mdc
 | `references/graph-document.md` | the document, field by field, and what the validator will catch |
 | `references/config.md` | `.github/pr-lens.yml` corrections, with recipes |
 
-The agent is usually the model. Rather than spending a provider key to describe a diff it already understands, it writes the document itself and lets `pr-lens validate` hold it to the contract — every failure is a path into the document, so the loop closes without a human in it.
+The agent is usually the model. Rather than spending a provider key to describe a diff it already understands, it writes the document itself and lets `pr-lens validate` hold it to the contract. Every failure is a path into the document, so the loop closes without a human in it.
 
 ## Why this exists
 
@@ -42,4 +42,4 @@ A coding agent that opens a pull request is asking a person to review code the p
 
 ---
 
-Part of [PR Lens](https://prlens.dev) — review what actually matters.
+Part of [PR Lens](https://prlens.dev). Review what actually matters.

package/SKILL.md

@@ -1,36 +1,45 @@
 ---
 name: pr-lens
-description: Draw a code change as an architecture or data-flow diagram with PR Lens — author a graph document from a diff, validate it, render it to SVG, and attach it to a pull request; or correct a repository's map in .github/pr-lens.yml. Use when asked to diagram, visualise or explain the shape of a change, when attaching a diagram to a pull request you opened, or when an existing PR Lens diagram names things wrongly.
+description: Draw a code change as an architecture or data-flow diagram with PR Lens. Author a graph document from a diff, validate it, render it to SVG, and attach it to a pull request; or correct a repository's map in .github/pr-lens.yml. Use when asked to diagram, visualise or explain the shape of a change, when attaching a diagram to a pull request you opened, or when an existing PR Lens diagram names things wrongly.
 ---
 
 # PR Lens
 
-PR Lens turns a diff into one JSON document — lanes, nodes, edges, ordered flows — and renders it as an animated SVG that reads inside a GitHub pull request comment. The document is the whole contract: if it validates, it renders.
+PR Lens turns a diff into one JSON document (lanes, nodes, edges, ordered flows) and renders it as an animated SVG that reads inside a GitHub pull request comment. The document is the whole contract: if it validates, it renders.
 
-You are usually the model. Rather than calling out to a provider, read the diff and write the document yourself, then let the tooling check it.
+You are usually the model. Rather than calling out to a provider, read the diff and write the document yourself, then let the tooling check it. Nothing on this path needs a model key or names a model: whichever one you are running is the one doing the reasoning.
 
 ## The loop
 
 1. **Read the diff.** `git diff --find-renames <base>...<head>`. The base is the merge base, not the tip of the base branch.
-2. **Write the document** to `pr-lens/graph.json`, following `references/graph-document.md`. The authoritative shape is the JSON Schema that ships with the contract:
-   `node_modules/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json`
+2. **Write the document** to `.pr-lens/graph.json`, following `references/graph-document.md`. That page is the whole shape: every field, every enum, every limit, and the four rules a JSON Schema cannot express. `references/example.graph.json` is a document that validates — three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree. Read it before you write your first one. It is quicker than reading the reference.
 3. **Validate, and fix what it names.**
    ```bash
-   npx @coldtea/pr-lens-cli validate pr-lens/graph.json
+   npx @coldtea/pr-lens-cli validate .pr-lens/graph.json
    ```
    Each failure is a path into your document, a reason and a code. Fix every one and run it again. Do not render an invalid document; do not "work around" a failure by deleting the element it names.
-4. **Render and attach.**
+4. **Render.**
    ```bash
-   npx @coldtea/pr-lens-cli render pr-lens/graph.json --out pr-lens/
+   npx @coldtea/pr-lens-cli render .pr-lens/graph.json
    ```
-   Commit the SVGs somewhere durable — an orphan branch, or a release asset — and reference them from the pull request body with a `<picture>` pair so the diagram reads in both GitHub themes. `pr-lens comment --graph … --manifest …` composes that markdown for you.
+   The SVGs, the manifest and `drawn.graph.json` land in `.pr-lens/`, which the CLI adds to the repository's .gitignore. Do not commit any of it. These files are a preview, rebuilt from the diff whenever anyone wants them again; the comment on the pull request is the thing you are making.
+5. **Attach.** Put the SVGs somewhere durable — an orphan branch, a release asset — then compose the comment from the document that was drawn:
+   ```bash
+   npx @coldtea/pr-lens-cli comment \
+     --graph .pr-lens/drawn.graph.json \
+     --manifest .pr-lens/manifest.json \
+     --asset-base-url https://raw.githubusercontent.com/<owner>/<repo>/<branch>/<dir>
+   ```
+   The markdown goes to stdout, with each diagram as a `<picture>` pair so it reads in both GitHub themes. Posting it is your business.
+
+   Both flags matter. `--graph` takes `drawn.graph.json`, not the document you wrote: corrections change what the diagrams show, and the CLI refuses a document its manifest does not describe. `--asset-base-url` is where you published the SVGs; leave it out and the markdown points at local paths no reader can fetch.
 
-If the repository has a model key configured and you would rather not author the document yourself, `npx @coldtea/pr-lens-cli analyze --base <ref>` does steps 1 and 2 with the provider of your choice.
+If you would rather not author the document yourself, `npx @coldtea/pr-lens-cli analyze --base <ref>` does steps 1 and 2 by asking a provider — Gemini, OpenAI, or any endpoint speaking `/chat/completions` — with a key of your own. That is the only path here that needs one.
 
 ## What makes a document worth reading
 
 - **Include what did not change.** A diagram of only the changed nodes says nothing about blast radius. The unchanged neighbours a change touches are the context; mark them `delta: "unchanged"`.
-- **Lanes are the reader's mental model** — a runtime, a tier, a boundary — not the folder tree.
+- **Lanes are the reader's mental model** (a runtime, a tier, a boundary), not the folder tree.
 - **One hero edge**, two at the outside: the connection the change is really about.
 - **Add a flow only when there is a sequence** worth animating. One good flow beats three thin ones.
 - **Attach file refs**: they become the permalinks a reviewer clicks.
@@ -43,7 +52,7 @@ Read `references/graph-document.md` before writing. The four failures that accou
 | Code | What you did |
 | --- | --- |
 | `BROKEN_REFERENCE` | an edge, a flow step or a view names an id you never declared |
-| `INVALID_DOCUMENT` | an invented field — the schemas are strict, unknown keys are rejected |
+| `INVALID_DOCUMENT` | an invented field; the schemas are strict, unknown keys are rejected |
 | `DUPLICATE_ID` | two nodes, edges or views sharing an id |
 | `UNSUPPORTED_SCHEMA_VERSION` | `schemaVersion` is not the contract version installed |
 
@@ -51,7 +60,7 @@ Four rules cannot be expressed in JSON Schema and are checked only by the parser
 
 ## Fixing a map instead of writing one
 
-When someone says the diagram is wrong — a node is misnamed, a folder should not be on it, something sits in the wrong lane — do not edit the generated document. It is regenerated on every run. Write the correction into `.github/pr-lens.yml`, which is an overlay applied over fresh inference every time:
+When someone says the diagram is wrong (a node is misnamed, a folder should not be on it, something sits in the wrong lane), do not edit the generated document. It is regenerated on every run. Write the correction into `.github/pr-lens.yml`, which is an overlay applied over fresh inference every time:
 
 ```yaml
 schemaVersion: 0.1.0
@@ -68,16 +77,18 @@ map:
 
 `references/config.md` has the full format and the recipes. Validate it the same way: `npx @coldtea/pr-lens-cli validate .github/pr-lens.yml`.
 
-A `match` beginning with `id:` addresses one node exactly; anything else is a path glob matched against a node's file paths — prefer the glob, because it keeps holding when the next run names the node differently. A lane pin may name a lane the document never declared: the band is created, and takes the id for its label, so give it one a reader would want to see.
+A `match` beginning with `id:` addresses one node exactly; anything else is a path glob matched against a node's file paths. Prefer the glob, because it keeps holding when the next run names the node differently. A lane pin may name a lane the document never declared: the band is created, and takes the id for its label, so give it one a reader would want to see.
 
-`pr-lens render` says so when a correction matched nothing, which is how a config that has drifted — the file it named moved or was deleted — becomes visible instead of quietly doing nothing.
+`pr-lens render` says so when a correction matched nothing, which is how a config that has drifted, because the file it named moved or was deleted, becomes visible instead of quietly doing nothing.
 
-## Reference documents
+## What ships with this skill
 
-The contract ships worked examples. `postmark-refactor.graph.json` is the realistic one — three lanes, all four delta states, a hero edge, a seven-step flow, a nested drill-down tree — and `minimal.graph.json` is the smallest document that validates:
+Everything you need is beside this page. Nothing here asks you to install a package first.
 
-```bash
-ls node_modules/@coldtea/pr-lens-schema/examples/
-```
+| | |
+| --- | --- |
+| `references/graph-document.md` | the document, field by field: enums, limits, and where documents actually go wrong |
+| `references/config.md` | `.github/pr-lens.yml`, the correction overlay, in full |
+| `references/example.graph.json` | one complete document that validates, to read and to copy the shape of |
 
-Read the realistic one before authoring your first document. It is faster than reading the schema.
+The same document ships as `postmark-refactor.graph.json` in `@coldtea/pr-lens-schema`, and the JSON Schema the validator enforces is published at `https://unpkg.com/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json`. Neither is something you need to fetch to write a document.

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@coldtea/pr-lens-agent-skill",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "The PR Lens skill for coding agents: author a graph document from a diff, validate it, render it, and correct a repository's map.",
   "license": "MIT",
-  "author": "Ohans Emmanuel",
+  "author": "Coldtea AI",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/coldteadotai/pr-lens.git",
@@ -30,13 +30,15 @@
   },
   "devDependencies": {
     "@types/node": "^20.19.0",
+    "tsx": "4.23.12",
     "typescript": "7.0.2",
     "vitest": "4.1.11",
     "yaml": "^2.8.1",
-    "@coldtea/pr-lens-renderer": "^0.1.0",
-    "@coldtea/pr-lens-schema": "^0.1.0"
+    "@coldtea/pr-lens-renderer": "^0.1.2",
+    "@coldtea/pr-lens-schema": "^0.1.2"
   },
   "scripts": {
+    "skill:sync": "tsx scripts/sync.ts",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   }

package/references/config.md

@@ -1,4 +1,4 @@
-# Correcting the map — `.github/pr-lens.yml`
+# Correcting the map: `.github/pr-lens.yml`
 
 The generated document is regenerated on every run, so editing it is pointless. Corrections live in `.github/pr-lens.yml`, an overlay applied over fresh inference every time. Inference never writes back into this file, which is why a correction keeps holding as the code moves.
 
@@ -21,15 +21,15 @@ map:
       group: broadcast-lib
 ```
 
-Every field except `schemaVersion` is optional, and the file itself is optional. The JSON Schema for editor autocomplete ships with the contract:
+Every field except `schemaVersion` is optional, and the file itself is optional. For editor autocomplete, point at the published JSON Schema — no install needed:
 
 ```jsonc
-{ "$ref": "node_modules/@coldtea/pr-lens-schema/json-schema/config.schema.json" }
+{ "$ref": "https://unpkg.com/@coldtea/pr-lens-schema/json-schema/config.schema.json" }
 ```
 
 ## Selectors
 
-A `match` beginning with `id:` addresses exactly one node — `id:build-bulk-payload`. Anything else is a repository-relative path glob matched against the node's file paths.
+A `match` beginning with `id:` addresses exactly one node, as in `id:build-bulk-payload`. Anything else is a repository-relative path glob matched against the node's file paths.
 
 **Prefer the glob.** Ids come from inference and may change when the code does; a path correction survives that. Reach for `id:` only when no path distinguishes the node, or when the node has no files at all (an external service, a queue).
 
@@ -42,7 +42,7 @@ A `match` beginning with `id:` addresses exactly one node — `id:build-bulk-pay
 | `lane` | moves matching nodes into a lane, **creating it** when the document declares no such id |
 | `group` | clusters matching nodes under a sub-group inside their lane |
 
-Up to 128 of each. They are about intent rather than structure: there is no way to add a node or draw an edge here, and the one thing a correction can bring into existence is a lane — a band a repository wants that inference did not find. It takes the id for its label, because the id is the only name this file carries, so write `lane: infrastructure` rather than `lane: l3`. If the map is wrong in a way corrections cannot express, the fix belongs in the analysis, not in this file.
+Up to 128 of each. They are about intent rather than structure: there is no way to add a node or draw an edge here, and the one thing a correction can bring into existence is a lane, a band a repository wants that inference did not find. It takes the id for its label, because the id is the only name this file carries, so write `lane: infrastructure` rather than `lane: l3`. If the map is wrong in a way corrections cannot express, the fix belongs in the analysis, not in this file.
 
 ## Recipes
 
@@ -87,4 +87,4 @@ lenses: [architecture]
 npx @coldtea/pr-lens-cli validate .github/pr-lens.yml
 ```
 
-`pr-lens render` reports any correction that changed nothing about the document it drew — that is a config that has drifted out of date, usually because the file a selector named has moved or gone. It is not an error and nothing stops, but it is worth fixing: a correction that matches nothing is a correction nobody is getting.
+`pr-lens render` reports any correction that changed nothing about the document it drew. That is a config that has drifted out of date, usually because the file a selector named has moved or gone. It is not an error and nothing stops, but it is worth fixing: a correction that matches nothing is a correction nobody is getting.

package/references/example.graph.json

@@ -0,0 +1,580 @@
+{
+  "schemaVersion": "0.1.0",
+  "kind": "graph",
+  "generatedAt": "2026-08-19T18:24:00.000Z",
+  "title": "Batch broadcast sending through Postmark",
+  "summary": "Broadcast delivery moves from one Postmark request per recipient to batched requests of 500, with suppression filtering pulled in front of the send and the payload builder extracted into a shared library.",
+  "lenses": [
+    "architecture",
+    "data-flow"
+  ],
+  "provenance": {
+    "repo": {
+      "owner": "ohansemmanuel",
+      "name": "bestregards",
+      "host": "github.com"
+    },
+    "base": {
+      "sha": "3f5c1ab9d24e7f08c6b1a5d3e9074c2b8a6f1d40",
+      "ref": "main"
+    },
+    "head": {
+      "sha": "b71e0d4c8a92f5361de7c0b4a8f2593d6c1e8a77",
+      "ref": "batch-broadcast-send"
+    },
+    "pullRequest": {
+      "number": 128,
+      "title": "Send broadcasts in batches of 500",
+      "url": "https://github.com/ohansemmanuel/bestregards/pull/128"
+    },
+    "generator": {
+      "name": "pr-lens-examples",
+      "version": "0.1.0"
+    }
+  },
+  "lanes": [
+    {
+      "id": "web",
+      "label": "Next.js",
+      "subtitle": "Vercel",
+      "order": 0
+    },
+    {
+      "id": "functions",
+      "label": "Cloud Functions",
+      "subtitle": "Firebase",
+      "order": 1
+    },
+    {
+      "id": "external",
+      "label": "External",
+      "subtitle": "Postmark",
+      "order": 2
+    }
+  ],
+  "nodes": [
+    {
+      "id": "broadcast-composer",
+      "label": "Broadcast composer",
+      "kind": "ui",
+      "delta": "unchanged",
+      "lane": "web",
+      "subtitle": "app/broadcasts/new",
+      "summary": "Where an author writes a broadcast and hits send. Untouched by this change.",
+      "files": [
+        {
+          "path": "app/broadcasts/new/page.tsx"
+        }
+      ],
+      "badges": []
+    },
+    {
+      "id": "queue-route",
+      "label": "POST /api/broadcasts/queue",
+      "kind": "route",
+      "delta": "modified",
+      "lane": "web",
+      "summary": "Writes the queue document. Now stamps the recipient count and batch size the sender will use instead of leaving batching to the worker.",
+      "files": [
+        {
+          "path": "app/api/broadcasts/queue/route.ts",
+          "startLine": 24,
+          "endLine": 96
+        }
+      ],
+      "badges": [
+        "+38 / -12"
+      ]
+    },
+    {
+      "id": "broadcast-queue",
+      "label": "broadcastQueue",
+      "kind": "datastore",
+      "delta": "modified",
+      "lane": "functions",
+      "subtitle": "Firestore collection",
+      "summary": "Queue documents gained batchSize and suppressedCount fields, and results are now written back per batch rather than per recipient.",
+      "files": [
+        {
+          "path": "functions/src/broadcast/schema.ts",
+          "startLine": 12,
+          "endLine": 48
+        }
+      ],
+      "badges": []
+    },
+    {
+      "id": "send-broadcast-bulk",
+      "label": "sendBroadcastBulk",
+      "kind": "function",
+      "delta": "added",
+      "lane": "functions",
+      "subtitle": "onWrite trigger",
+      "summary": "New trigger handler. Fetches suppressions once, builds batched payloads, and posts them to Postmark in chunks of 500.",
+      "files": [
+        {
+          "path": "functions/src/broadcast/sendBroadcastBulk.ts",
+          "startLine": 1,
+          "endLine": 142
+        }
+      ],
+      "badges": [
+        "new"
+      ]
+    },
+    {
+      "id": "build-bulk-payload",
+      "label": "buildBulkPayload",
+      "kind": "function",
+      "delta": "added",
+      "lane": "functions",
+      "summary": "Turns a broadcast and its recipient slice into a Postmark batch request body.",
+      "files": [
+        {
+          "path": "packages/broadcast-lib/src/buildBulkPayload.ts",
+          "startLine": 1,
+          "endLine": 74
+        }
+      ],
+      "badges": []
+    },
+    {
+      "id": "get-suppressed-emails",
+      "label": "getSuppressedEmails",
+      "kind": "function",
+      "delta": "added",
+      "lane": "functions",
+      "summary": "Pulls the Postmark suppression dump once per broadcast so suppressed addresses are filtered before any batch is sent.",
+      "files": [
+        {
+          "path": "packages/broadcast-lib/src/getSuppressedEmails.ts",
+          "startLine": 1,
+          "endLine": 58
+        }
+      ],
+      "badges": []
+    },
+    {
+      "id": "broadcast-lib",
+      "label": "broadcast-lib",
+      "kind": "package",
+      "delta": "added",
+      "lane": "functions",
+      "subtitle": "packages/broadcast-lib",
+      "summary": "New shared package so the queue route and the sender agree on payload shape and batch size.",
+      "files": [
+        {
+          "path": "packages/broadcast-lib/src/index.ts"
+        }
+      ],
+      "badges": [
+        "new package"
+      ]
+    },
+    {
+      "id": "process-broadcast",
+      "label": "processBroadcast",
+      "kind": "function",
+      "delta": "removed",
+      "lane": "functions",
+      "subtitle": "onWrite trigger",
+      "summary": "The per-recipient loop this change replaces.",
+      "files": [
+        {
+          "path": "functions/src/broadcast/processBroadcast.ts",
+          "startLine": 1,
+          "endLine": 118,
+          "revision": "base"
+        }
+      ],
+      "badges": []
+    },
+    {
+      "id": "send-single-email",
+      "label": "sendSingleEmail",
+      "kind": "function",
+      "delta": "removed",
+      "lane": "functions",
+      "summary": "One Postmark request per recipient. Gone with the loop that called it.",
+      "files": [
+        {
+          "path": "functions/src/broadcast/sendSingleEmail.ts",
+          "startLine": 1,
+          "endLine": 46,
+          "revision": "base"
+        }
+      ],
+      "badges": []
+    },
+    {
+      "id": "postmark",
+      "label": "Postmark",
+      "kind": "external",
+      "delta": "modified",
+      "lane": "external",
+      "subtitle": "Email API",
+      "summary": "Same provider, different endpoints: the batch endpoint and the suppression dump replace repeated single sends.",
+      "files": [],
+      "badges": []
+    }
+  ],
+  "edges": [
+    {
+      "id": "composer-to-queue",
+      "from": "broadcast-composer",
+      "to": "queue-route",
+      "kind": "http",
+      "delta": "unchanged",
+      "label": "send broadcast",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "queue-to-firestore",
+      "from": "queue-route",
+      "to": "broadcast-queue",
+      "kind": "data",
+      "delta": "modified",
+      "label": "enqueue job",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "queue-to-lib",
+      "from": "queue-route",
+      "to": "broadcast-lib",
+      "kind": "dependency",
+      "delta": "added",
+      "label": "batch size",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "firestore-to-bulk",
+      "from": "broadcast-queue",
+      "to": "send-broadcast-bulk",
+      "kind": "event",
+      "delta": "added",
+      "label": "onWrite",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "firestore-to-process",
+      "from": "broadcast-queue",
+      "to": "process-broadcast",
+      "kind": "event",
+      "delta": "removed",
+      "label": "onWrite",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "process-to-single",
+      "from": "process-broadcast",
+      "to": "send-single-email",
+      "kind": "call",
+      "delta": "removed",
+      "label": "per recipient",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "single-to-postmark",
+      "from": "send-single-email",
+      "to": "postmark",
+      "kind": "http",
+      "delta": "removed",
+      "label": "POST /email · 1 msg/call",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "bulk-to-payload",
+      "from": "send-broadcast-bulk",
+      "to": "build-bulk-payload",
+      "kind": "call",
+      "delta": "added",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "bulk-to-suppressions",
+      "from": "send-broadcast-bulk",
+      "to": "get-suppressed-emails",
+      "kind": "call",
+      "delta": "added",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "bulk-to-lib",
+      "from": "send-broadcast-bulk",
+      "to": "broadcast-lib",
+      "kind": "dependency",
+      "delta": "added",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    },
+    {
+      "id": "suppressions-to-postmark",
+      "from": "get-suppressed-emails",
+      "to": "postmark",
+      "kind": "http",
+      "delta": "added",
+      "label": "GET suppression dump",
+      "emphasis": "normal",
+      "animated": true,
+      "files": []
+    },
+    {
+      "id": "bulk-to-postmark",
+      "from": "send-broadcast-bulk",
+      "to": "postmark",
+      "kind": "http",
+      "delta": "added",
+      "label": "500 msgs/call",
+      "emphasis": "hero",
+      "animated": true,
+      "summary": "The change in one edge: a broadcast to 10,000 recipients drops from 10,000 requests to 20.",
+      "files": []
+    },
+    {
+      "id": "bulk-to-firestore",
+      "from": "send-broadcast-bulk",
+      "to": "broadcast-queue",
+      "kind": "data",
+      "delta": "added",
+      "label": "write results",
+      "emphasis": "normal",
+      "animated": false,
+      "files": []
+    }
+  ],
+  "flows": [
+    {
+      "id": "send-pipeline",
+      "title": "Sending a broadcast",
+      "summary": "The path a queued broadcast takes now, from enqueue to per-message results.",
+      "delta": "modified",
+      "participants": [
+        {
+          "node": "queue-route",
+          "label": "queue route"
+        },
+        {
+          "node": "broadcast-queue",
+          "label": "Firestore"
+        },
+        {
+          "node": "send-broadcast-bulk",
+          "label": "sendBroadcastBulk"
+        },
+        {
+          "node": "postmark",
+          "label": "Postmark"
+        }
+      ],
+      "messages": [
+        {
+          "id": "enqueue",
+          "from": "queue-route",
+          "to": "broadcast-queue",
+          "label": "enqueue broadcast job",
+          "kind": "async",
+          "delta": "modified",
+          "animated": true,
+          "files": []
+        },
+        {
+          "id": "trigger",
+          "from": "broadcast-queue",
+          "to": "send-broadcast-bulk",
+          "label": "onWrite trigger",
+          "kind": "async",
+          "delta": "added",
+          "animated": true,
+          "files": []
+        },
+        {
+          "id": "suppressions-request",
+          "from": "send-broadcast-bulk",
+          "to": "postmark",
+          "label": "GET suppression dump",
+          "kind": "sync",
+          "delta": "added",
+          "animated": true,
+          "files": []
+        },
+        {
+          "id": "suppressions-response",
+          "from": "postmark",
+          "to": "send-broadcast-bulk",
+          "label": "suppressed addresses",
+          "kind": "return",
+          "delta": "added",
+          "animated": true,
+          "note": "Fetched once per broadcast, not once per recipient.",
+          "files": []
+        },
+        {
+          "id": "batch-post",
+          "from": "send-broadcast-bulk",
+          "to": "postmark",
+          "label": "POST /email/batch · 500 msgs",
+          "kind": "sync",
+          "delta": "added",
+          "animated": true,
+          "repeat": 4,
+          "note": "One request per 500 recipients; four for this 2,000-recipient broadcast.",
+          "files": []
+        },
+        {
+          "id": "batch-results",
+          "from": "postmark",
+          "to": "send-broadcast-bulk",
+          "label": "per-message results",
+          "kind": "return",
+          "delta": "added",
+          "animated": true,
+          "files": []
+        },
+        {
+          "id": "write-results",
+          "from": "send-broadcast-bulk",
+          "to": "broadcast-queue",
+          "label": "write results",
+          "kind": "async",
+          "delta": "added",
+          "animated": true,
+          "files": []
+        }
+      ]
+    }
+  ],
+  "stats": {
+    "filesChanged": 14,
+    "additions": 486,
+    "deletions": 212,
+    "chips": [
+      {
+        "label": "Postmark calls",
+        "value": "500× fewer",
+        "tone": "hero"
+      },
+      {
+        "label": "New",
+        "value": "4 units",
+        "tone": "added"
+      },
+      {
+        "label": "Retired",
+        "value": "2 units",
+        "tone": "removed"
+      }
+    ]
+  },
+  "views": [
+    {
+      "id": "overview",
+      "title": "Architecture — blast radius",
+      "lens": "architecture",
+      "summary": "Everything this change touches, across all three lanes.",
+      "scope": {
+        "kind": "all"
+      },
+      "defaultOpen": true,
+      "children": [
+        {
+          "id": "new-batch-path",
+          "title": "The new batch path",
+          "lens": "architecture",
+          "summary": "What replaced the per-recipient loop.",
+          "scope": {
+            "kind": "selection",
+            "lanes": [],
+            "nodes": [
+              "send-broadcast-bulk",
+              "build-bulk-payload",
+              "get-suppressed-emails",
+              "broadcast-lib",
+              "postmark"
+            ],
+            "edges": [
+              "bulk-to-payload",
+              "bulk-to-suppressions",
+              "bulk-to-lib",
+              "suppressions-to-postmark",
+              "bulk-to-postmark",
+              "bulk-to-firestore"
+            ],
+            "flows": []
+          },
+          "defaultOpen": false,
+          "children": []
+        },
+        {
+          "id": "retired-path",
+          "title": "What was retired",
+          "lens": "architecture",
+          "summary": "The single-send path, kept visible so a reviewer can confirm nothing else called it.",
+          "scope": {
+            "kind": "selection",
+            "lanes": [],
+            "nodes": [
+              "process-broadcast",
+              "send-single-email"
+            ],
+            "edges": [
+              "firestore-to-process",
+              "process-to-single",
+              "single-to-postmark"
+            ],
+            "flows": []
+          },
+          "defaultOpen": false,
+          "children": []
+        }
+      ]
+    },
+    {
+      "id": "send-pipeline-view",
+      "title": "Data flow — sending a broadcast",
+      "lens": "data-flow",
+      "scope": {
+        "kind": "selection",
+        "lanes": [],
+        "nodes": [],
+        "edges": [],
+        "flows": [
+          "send-pipeline"
+        ]
+      },
+      "defaultOpen": false,
+      "children": []
+    }
+  ],
+  "layout": {
+    "direction": "right",
+    "laneOrder": [
+      "web",
+      "functions",
+      "external"
+    ],
+    "rank": {
+      "queue-route": 0,
+      "send-broadcast-bulk": 1,
+      "postmark": 2
+    }
+  }
+}

package/references/graph-document.md

@@ -1,8 +1,10 @@
 # Authoring a graph document
 
-The authoritative shape is `node_modules/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json`. This page is what that schema cannot tell you: which parts matter, and where documents actually go wrong.
+This page is the whole shape, and what a schema cannot tell you besides: which parts matter, and where documents actually go wrong. `references/example.graph.json` is one document that validates, if you would rather read than be told.
 
-Every schema here is **strict** — an unknown key is a rejection, not a warning. A field with a default may be left out.
+The validator enforces the same thing from a JSON Schema, published at `https://unpkg.com/@coldtea/pr-lens-schema/json-schema/graph-doc.schema.json` if you want it machine-readable.
+
+Every schema here is **strict**: an unknown key is a rejection, not a warning. A field with a default may be left out.
 
 ## The document
 
@@ -25,7 +27,7 @@ Every schema here is **strict** — an unknown key is a rejection, not a warning
 
 `lenses` declares what the document carries enough detail to draw: `architecture`, `data-flow`, or both. A document carrying flows must declare `data-flow`.
 
-`provenance` is where the document came from: the repository, the base and head commit shas (lowercase hex, 7–40 characters), optionally the pull request and the generator. When you produce a document through the CLI these are filled in from the repository — do not invent them.
+`provenance` is where the document came from: the repository, the base and head commit shas (lowercase hex, 7-40 characters), optionally the pull request and the generator. When you produce a document through the CLI these are filled in from the repository, so do not invent them.
 
 ## Ids
 
@@ -45,7 +47,7 @@ Every node, edge, flow and flow step declares one: `added`, `modified`, `removed
 { "id": "functions", "label": "Cloud Functions", "subtitle": "Node 20", "order": 1 }
 ```
 
-`order` (0–64) places lanes left to right; ties fall back to array order. Give a lane a `delta` only when the lane itself is new or gone.
+`order` (0-64) places lanes left to right; ties fall back to array order. Give a lane a `delta` only when the lane itself is new or gone.
 
 ## Nodes
 
@@ -68,7 +70,7 @@ Every node, edge, flow and flow step declares one: `added`, `modified`, `removed
 
 `kind` is one of `service app module function route job queue datastore cache external ui config test package other`. It drives the card's icon and shape and nothing else; when in doubt, `other` still renders.
 
-`group` clusters nodes inside a lane — a package, a folder that means something. `files` (up to 64) become diff permalinks. `badges` (up to 6) are extra chips; the delta badge is drawn for you, so do not restate it.
+`group` clusters nodes inside a lane: a package, a folder that means something. `files` (up to 64) become diff permalinks. `badges` (up to 6) are extra chips; the delta badge is drawn for you, so do not restate it.
 
 ## Edges
 
@@ -87,7 +89,7 @@ Up to 512.
 }
 ```
 
-`kind` is one of `call http rpc event queue data dependency render other`. `emphasis` is `normal` (default), `hero` or `muted`. More than one or two heroes and the emphasis stops meaning anything. `from` and `to` must be node ids you declared — this is the single most common failure.
+`kind` is one of `call http rpc event queue data dependency render other`. `emphasis` is `normal` (default), `hero` or `muted`. More than one or two heroes and the emphasis stops meaning anything. `from` and `to` must be node ids you declared. This is the single most common failure.
 
 ## Flows
 
@@ -108,7 +110,7 @@ Up to 16, for the data-flow lens.
 ```
 
 - 2 to 12 participants, ordered by array position; each names a node id.
-- 1 to 64 messages. **Step order is array order** — there is no step number field, so a document cannot disagree with its own animation.
+- 1 to 64 messages. **Step order is array order**: there is no step number field, so a document cannot disagree with its own animation.
 - `kind` is `sync`, `async`, `return` or `self`. `self` requires `from === to`, and no other kind may have them equal.
 - Both endpoints must be participants of that flow, not merely nodes of the document.
 - `repeat` says a step happens more than once per run, e.g. 4 batched requests.
@@ -145,7 +147,7 @@ The drill-down tree in the comment: up to 32 at the root, nesting up to 32 child
 { "direction": "right", "laneOrder": ["api", "functions", "external"], "rank": { "send-broadcast-bulk": 2 } }
 ```
 
-Hints, not instructions — the renderer owns final placement so a diagram stays deterministic and a stale hint cannot break it. Absolute coordinates are not expressible. Omitting `layout` entirely is normal.
+Hints, not instructions: the renderer owns final placement, so a diagram stays deterministic and a stale hint cannot break it. Absolute coordinates are not expressible. Omitting `layout` entirely is normal.
 
 ## File references
 
@@ -157,12 +159,12 @@ Repository-relative POSIX paths: no leading `/`, no drive letter, no backslash,
 
 ## Length limits
 
-Labels 120 characters, summaries 2000, chip values 32. They are display fields — a label that needs 120 characters is a label the diagram cannot draw.
+Labels 120 characters, summaries 2000, chip values 32. They are display fields: a label that needs 120 characters is a label the diagram cannot draw.
 
 ## Then validate
 
 ```bash
-npx @coldtea/pr-lens-cli validate pr-lens/graph.json
+npx @coldtea/pr-lens-cli validate .pr-lens/graph.json
 ```
 
 Every problem is reported at once, with a path into the document. Fix them all and run it again until it is clean.