@coldtea/pr-lens-schema 0.1.2 → 0.2.0

package/README.md

@@ -19,7 +19,7 @@ const result = safeParseGraphDoc(json);     // { ok: true, value } | { ok: false
 
 | Document | Purpose | Parser |
 | --- | --- | --- |
-| `GraphDoc` | Lanes, nodes, edges, flows, stats and the drill-down tree for one pull request, or for a stored baseline map | `parseGraphDoc` |
+| `GraphDoc` | Lanes, nodes, edges, flows, stats, the drill-down tree and an optional walkthrough for one pull request, or for a stored baseline map | `parseGraphDoc` |
 | `PatchDoc` | Ordered operations that move a stored graph forward as pull requests merge | `parsePatchDoc` |
 | `Config` | What a repository commits as `.github/pr-lens.yml` | `parseConfig` |
 | `RenderManifest` | The SVGs a render produced, and where they live | `parseRenderManifest` |
@@ -42,6 +42,48 @@ The cap is the worst case, every theme rendered, not what a particular render wo
 
 `architecture` shows blast radius against the existing system. `data-flow` animates an ordered pipeline. There is deliberately no security lens and no findings field: PR Lens is the comprehension layer, and a document that carries findings is rejected rather than quietly stripped. The `Lens` enum is additive: a future contract version may add lenses, so treat one you do not recognise as a view to skip, not as a failure.
 
+## Walkthroughs
+
+A document may carry a `walkthrough`.
+
+```ts
+walkthrough: {
+  steps: [
+    {
+      id: "four-batch-calls",
+      heading: "Postmark now gets 500 emails per call",
+      body: "One call per batch, and Postmark answers with a result for each message.",
+      stage: { kind: "flow", flow: "send-pipeline" },
+      focus: { kind: "selection", messages: ["batch-post", "batch-results"] },
+    },
+    {
+      id: "blast-radius",
+      heading: "4 parts added, 2 removed, across 3 lanes",
+      body: "A 2,000-person broadcast used to make 2,000 calls to Postmark. It now makes 4.",
+      stage: { kind: "view", view: "overview" },
+    },
+  ],
+}
+```
+
+A walkthrough is a short guided tour of the diagrams. It has two to twelve steps. Each step shows one diagram, points at one part of it, and says a few words about it.
+
+Each step has:
+
+- `heading`: the thing and what happened to it, up to 48 characters, in sentence case. For example "Postmark now gets 500 emails per call".
+- `body`: one line under the heading, up to 140 characters, on what the change means for behaviour. For example "One call per batch instead of one call per person". A heading with no body reads as unfinished, so the parser requires one.
+- `stage`: which diagram to show. A document can have several diagrams: its views (the drill-down diagrams) and its flows (the sequence diagrams). `{ "kind": "view", "view": "overview" }` shows the view called `overview`. `{ "kind": "flow", "flow": "send-pipeline" }` shows the flow called `send-pipeline`. Leave `stage` out and the step uses the diagram the reader is already on.
+- `focus`: what to zoom in on inside that diagram. `{ "kind": "all" }` means the whole diagram. A selection means "just these things": name any lanes, nodes, edges or flow steps (`messages`) by id, and the camera zooms to them while everything else dims. A selection must name at least one thing.
+
+The validator checks:
+
+- Every id you name exists in the document. A flow step you name must belong to the flow the stage shows, because flow step ids are only unique inside their own flow.
+- `messages` needs a stage that shows a flow. Leave it out when the stage is an architecture view.
+- Step ids are unique within the walkthrough. Two steps minimum, twelve maximum.
+- A stored map never carries a walkthrough. A map describes the system; a walkthrough tells the story of one change.
+
+When a patch or a correction removes something from the document, the walkthrough follows: a step loses the names that are gone, a step with nothing left to point at or whose diagram is gone is dropped, and if fewer than two steps remain the walkthrough is dropped. `pruneWalkthrough` does this and is exported for anything else that removes parts of a document.
+
 ## Deltas
 
 Every node, edge and flow step declares how it relates to the base commit: `added`, `modified`, `removed` or `unchanged`. `unchanged` elements are the context a reviewer needs to judge blast radius, so they belong in the document rather than being filtered out.
@@ -52,7 +94,7 @@ Parsing runs four things in one pass, and reports every problem it finds rather
 
 1. **Structure**: types, lengths, enums, no unknown keys, and file paths that can actually become a diff permalink (repository-relative, POSIX, no `..` segment).
 2. **Contract version**: below `1.0.0` an exact `major.minor` match; from `1.0.0` on, the same major and a minor no newer than this package's.
-3. **Referential integrity**: every node sits in a declared lane, every edge joins declared nodes, every flow step runs between declared participants, every drill-down view and layout hint names elements that exist, and a document carrying flows declares the `data-flow` lens.
+3. **Referential integrity**: every node sits in a declared lane, every edge joins declared nodes, every flow step runs between declared participants, every drill-down view and layout hint names elements that exist, every walkthrough step stages a diagram the document has and focuses elements it has, and a document carrying flows declares the `data-flow` lens.
 4. **That a render could describe the document**: see below.
 
 A document nested deeper than the stack can walk is reported as a document too deep to read, not thrown: `safeParse*` returns a result whatever it is handed.
@@ -76,6 +118,7 @@ const result = applyPatchDoc(parseGraphDoc(baseline), parsePatchDoc(patch));
 - Operations apply in array order, and the first conflict stops the batch, because a later operation was written against the state an earlier one was supposed to produce.
 - `add_*` refuses an id that is taken; `update_*` and `remove_*` refuse an id that is absent; `update_*` writes only the fields it names.
 - Removing a node takes its edges and flow steps with it, and drops a flow left with fewer than two participants or no steps. Removed ids are pruned out of the drill-down tree and the layout hints, and a view whose selection loses its last element is dropped rather than widened.
+- A walkthrough is pruned once, against the document the operations produced rather than alongside each one. A step names a diagram as well as elements, so it can name a view the tree prune has just dropped, and an update that rewrites a flow's steps takes focus members away without removing anything the other prunes would notice. A step whose stage is gone, or whose focus loses its last element, goes with it, and a tour left with fewer than two steps goes whole. Focused flow steps are measured against the flow the step's own stage draws, never against the document at large.
 - Removing a lane that still holds nodes is a conflict, not a cascade: move its nodes first.
 - `remove_*` deletes an element from the stored graph. That is a different statement from `delta: "removed"`, which says an element still exists but is being deleted by the change under review.
 - A successful result is always a document that would pass `parseGraphDoc`: the candidate is validated as a whole before it is returned.
@@ -91,6 +134,9 @@ A stored map describes a system rather than a change, so everything in it is `un
 schemaVersion: 0.1.0
 lenses: [architecture, data-flow]
 branding: true
+github:
+  comment:
+    collapsed: false
 map:
   rename:
     - match: functions/src/broadcast/sendBroadcastBulk.ts
@@ -107,6 +153,12 @@ map:
 
 A `match` beginning with `id:` addresses one node exactly; anything else is a path glob matched against a node's file paths, so a correction survives the model renaming the node between runs. Corrections are an overlay applied over fresh inference on every run. Inference never writes back into this file.
 
+The hosted App reads `github` settings from the PR's head commit. Other options apply to the CLI.
+
+| Setting | Default | Effect |
+| --- | --- | --- |
+| `github.comment.collapsed` | `false` | Start diagrams and details closed. Drawing still runs automatically. |
+
 ## JSON Schema
 
 `json-schema/*.json` (draft 2020-12) is generated from the zod schemas and published with the package, for producers that do not run TypeScript and for editors validating `.github/pr-lens.yml`:
@@ -117,15 +169,16 @@ A `match` beginning with `id:` addresses one node exactly; anything else is a pa
 
 They describe **what an author may write**: a field with a default is one you may leave out. Rules are carried across wherever JSON Schema can state them: the supported contract versions, the repository-relative path rule, `endLine` requiring `startLine`, an asset needing a `url` or a `path`, a `selection` view having to select something.
 
-Exactly five rules cannot be stated in JSON Schema and stay the parser's job, each of them a comparison the shape alone cannot make:
+Exactly six rules cannot be stated in JSON Schema and stay the parser's job, each of them a comparison the shape alone cannot make:
 
 1. referential integrity between elements,
 2. a line range that ends before it starts,
 3. the agreement between a self message's endpoints,
 4. a patch whose two commits are the same,
-5. more views than a render manifest could describe.
+5. more views than a render manifest could describe,
+6. a walkthrough step focusing flow steps the diagram on its stage does not draw.
 
-The tests run a table of documents through both representations and assert the same verdict, accept and reject alike, including a case per divergence above, so they stay deliberate and cannot quietly grow a fifth.
+The tests run a table of documents through both representations and assert the same verdict, accept and reject alike, including a case per divergence above, so they stay deliberate and cannot quietly grow a seventh.
 
 ## Goldens
 
@@ -137,7 +190,7 @@ import { postmarkRefactorGraph } from "@coldtea/pr-lens-schema/examples";
 
 They tell one story: a real refactor that moved broadcast sending from one Postmark request per recipient to batches of 500:
 
-- **`postmark-refactor.graph.json`** is the canonical document: the pull request itself, across three lanes, exercising all four delta states, a hero edge, a seven-step data flow with returns and a repeated batch step, and a nested drill-down tree. Downstream renderer goldens are measured against it.
+- **`postmark-refactor.graph.json`** is the canonical document: the pull request itself, across three lanes, exercising all four delta states, a hero edge, a seven-step data flow with returns and a repeated batch step, a nested drill-down tree, and a six-step walkthrough that stages both a view and a flow. Downstream renderer goldens are measured against it.
 - **`broadcast-baseline.graph.json`** is the stored map of that subsystem as `main` stood before the change, and **`broadcast-baseline.patch.json`** carries it to the merged state, the transition `applyPatchDoc` performs.
 - **`postmark-refactor.render-manifest.json`** is what rendering the pull-request document produces, **`pr-lens.config.json`** a repository's corrections, and **`minimal.graph.json`** the smallest document that validates.
 

package/dist/config.d.ts

@@ -52,6 +52,11 @@ export declare const Config: z.ZodObject<{
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
     branding: z.ZodDefault<z.ZodBoolean>;
+    github: z.ZodPrefault<z.ZodObject<{
+        comment: z.ZodPrefault<z.ZodObject<{
+            collapsed: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type Config = z.infer<typeof Config>;
 export type ConfigInput = z.input<typeof Config>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,aAIsE,CAAC;AAC5F,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;kBAuBwC,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,kFAAkF;AAClF,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;kBAiBiC,CAAC;AACrD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAC5C,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;GAMG;AACH,eAAO,MAAM,QAAQ,aAIsE,CAAC;AAC5F,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,QAAQ,CAAC,CAAC;AAEhD;;;;GAIG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;kBAuBwC,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AAE5D,kFAAkF;AAClF,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA6BiC,CAAC;AACrD,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAC5C,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC"}

package/dist/config.js

@@ -56,6 +56,18 @@ export const Config = z
         .boolean()
         .default(true)
         .describe("Show the 'Rendered by PR Lens' footer on comments."),
+    github: z
+        .strictObject({
+        comment: z
+            .strictObject({
+            collapsed: z
+                .boolean()
+                .default(false)
+                .describe("Start the hosted App's diagrams and details in a closed disclosure. Drawing still runs automatically."),
+        })
+            .prefault({}),
+    })
+        .prefault({}),
 })
     .describe("Repository configuration for PR Lens.");
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC;KACtB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,CAAC,8EAA8E,CAAC,CAAC;AAG5F;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,YAAY,CAAC;IACZ,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;SACrD,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,6BAA6B,CAAC;IAC1C,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,mEAAmE,CAAC;IAChF,IAAI,EAAE,CAAC;SACJ,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;SACpD,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,kCAAkC,CAAC;IAC/C,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;SACrD,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,6DAA6D,CAAC;CAC3E,CAAC;KACD,QAAQ,CAAC,sDAAsD,CAAC,CAAC;AAGpE,kFAAkF;AAClF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC;KACpB,YAAY,CAAC;IACZ,aAAa,EAAE,kBAAkB,CAAC,QAAQ,CACxC,gGAAgG,CACjG;IACD,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;SACtC,QAAQ,CAAC,uCAAuC,CAAC;IACpD,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC7E,QAAQ,EAAE,CAAC;SACR,OAAO,EAAE;SACT,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,oDAAoD,CAAC;CAClE,CAAC;KACD,QAAQ,CAAC,uCAAuC,CAAC,CAAC"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEtE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC;KACtB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,GAAG,CAAC;KACR,QAAQ,CAAC,8EAA8E,CAAC,CAAC;AAG5F;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC;KAC5B,YAAY,CAAC;IACZ,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;SACrD,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,6BAA6B,CAAC;IAC1C,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,QAAQ,CAAC;SACf,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,mEAAmE,CAAC;IAChF,IAAI,EAAE,CAAC;SACJ,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAC;SACpD,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,kCAAkC,CAAC;IAC/C,KAAK,EAAE,CAAC;SACL,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;SACrD,GAAG,CAAC,GAAG,CAAC;SACR,OAAO,CAAC,EAAE,CAAC;SACX,QAAQ,CAAC,6DAA6D,CAAC;CAC3E,CAAC;KACD,QAAQ,CAAC,sDAAsD,CAAC,CAAC;AAGpE,kFAAkF;AAClF,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC;KACpB,YAAY,CAAC;IACZ,aAAa,EAAE,kBAAkB,CAAC,QAAQ,CACxC,gGAAgG,CACjG;IACD,MAAM,EAAE,CAAC;SACN,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,CAAC,CAAC;SACN,OAAO,CAAC,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC;SACtC,QAAQ,CAAC,uCAAuC,CAAC;IACpD,GAAG,EAAE,cAAc,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;IAC7E,QAAQ,EAAE,CAAC;SACR,OAAO,EAAE;SACT,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,oDAAoD,CAAC;IACjE,MAAM,EAAE,CAAC;SACN,YAAY,CAAC;QACZ,OAAO,EAAE,CAAC;aACP,YAAY,CAAC;YACZ,SAAS,EAAE,CAAC;iBACT,OAAO,EAAE;iBACT,OAAO,CAAC,KAAK,CAAC;iBACd,QAAQ,CAAC,uGAAuG,CAAC;SACrH,CAAC;aACD,QAAQ,CAAC,EAAE,CAAC;KAChB,CAAC;SACD,QAAQ,CAAC,EAAE,CAAC;CAChB,CAAC;KACD,QAAQ,CAAC,uCAAuC,CAAC,CAAC"}

package/dist/examples/index.d.ts

@@ -473,6 +473,11 @@ export declare const exampleConfig: {
         }[];
     };
     branding: boolean;
+    github: {
+        comment: {
+            collapsed: boolean;
+        };
+    };
 };
 export declare const minimalGraph: {
     schemaVersion: string;
@@ -1070,6 +1075,11 @@ export declare const goldenDocuments: {
             }[];
         };
         branding: boolean;
+        github: {
+            comment: {
+                collapsed: boolean;
+            };
+        };
     };
     readonly "minimal.graph.json": {
         schemaVersion: string;

package/dist/examples/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/examples/index.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA4C,CAAC;AAC/E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAqD,CAAC;AAC3F,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA6C,CAAC;AACjF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA6C,CAAC;AACjF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;CAAkC,CAAC;AAC7D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAmC,CAAC;AAE7D,gFAAgF;AAChF,eAAO,MAAM,eAAe;aAC1B,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAC9B,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;aACxC,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAC/B,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAC/B,qBAAqB;;;;;;;;;;;;;;;;;;;;aACrB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CACZ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/examples/index.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA4C,CAAC;AAC/E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAqD,CAAC;AAC3F,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA6C,CAAC;AACjF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAA6C,CAAC;AACjF,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;CAAkC,CAAC;AAC7D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAmC,CAAC;AAE7D,gFAAgF;AAChF,eAAO,MAAM,eAAe;aAC1B,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAC9B,wCAAwC;;;;;;;;;;;;;;;;;;;;;;;;;;;;aACxC,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAC/B,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aAC/B,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;;aACrB,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CACZ,CAAC"}

package/examples/broadcast-baseline.graph.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "graph",
   "id": "bestregards-broadcast-baseline",
   "generatedAt": "2026-08-12T09:02:00.000Z",

package/examples/broadcast-baseline.patch.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "patch",
   "generatedAt": "2026-08-19T18:31:00.000Z",
   "summary": "Fold the batch send path into the baseline map and retire the single-send path.",

package/examples/minimal.graph.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "graph",
   "title": "Touch the health check",
   "lenses": [

package/examples/postmark-refactor.graph.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "graph",
   "generatedAt": "2026-08-19T18:24:00.000Z",
   "title": "Batch broadcast sending through Postmark",
@@ -564,6 +564,111 @@
       "children": []
     }
   ],
+  "walkthrough": {
+    "steps": [
+      {
+        "id": "batches-of-500",
+        "heading": "sendBroadcastBulk and buildBulkPayload added",
+        "body": "Nothing loops over recipients any more. The sender works on a whole batch at a time.",
+        "stage": {
+          "kind": "view",
+          "view": "overview"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [
+            "send-broadcast-bulk",
+            "build-bulk-payload",
+            "postmark"
+          ],
+          "edges": [],
+          "messages": []
+        }
+      },
+      {
+        "id": "suppression-first",
+        "heading": "getSuppressedEmails added before the send",
+        "body": "It pulls the blocked addresses once, before any batch is built.",
+        "stage": {
+          "kind": "view",
+          "view": "new-batch-path"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [
+            "get-suppressed-emails",
+            "postmark"
+          ],
+          "edges": [],
+          "messages": []
+        }
+      },
+      {
+        "id": "old-path-goes-dark",
+        "heading": "processBroadcast and sendSingleEmail removed",
+        "body": "sendBroadcastBulk does their job for whole batches.",
+        "stage": {
+          "kind": "view",
+          "view": "overview"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [
+            "process-broadcast",
+            "send-single-email"
+          ],
+          "edges": [],
+          "messages": []
+        }
+      },
+      {
+        "id": "sequence-start-to-finish",
+        "heading": "The send sequence gained 6 new steps",
+        "body": "The queue write is the only step that was there before, and it now stamps the batch size.",
+        "stage": {
+          "kind": "flow",
+          "flow": "send-pipeline"
+        },
+        "focus": {
+          "kind": "all"
+        }
+      },
+      {
+        "id": "four-batch-calls",
+        "heading": "Postmark now gets 500 emails per call",
+        "body": "One call per batch, and Postmark answers with a result for each message.",
+        "stage": {
+          "kind": "flow",
+          "flow": "send-pipeline"
+        },
+        "focus": {
+          "kind": "selection",
+          "lanes": [],
+          "nodes": [],
+          "edges": [],
+          "messages": [
+            "batch-post",
+            "batch-results"
+          ]
+        }
+      },
+      {
+        "id": "blast-radius",
+        "heading": "4 parts added, 2 removed, across 3 lanes",
+        "body": "A 2,000-person broadcast used to make 2,000 calls to Postmark. It now makes 4.",
+        "stage": {
+          "kind": "view",
+          "view": "overview"
+        },
+        "focus": {
+          "kind": "all"
+        }
+      }
+    ]
+  },
   "layout": {
     "direction": "right",
     "laneOrder": [

package/examples/postmark-refactor.render-manifest.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "kind": "render-manifest",
   "generatedAt": "2026-08-19T18:32:10.000Z",
   "graph": {

package/examples/pr-lens.config.json

@@ -1,5 +1,5 @@
 {
-  "schemaVersion": "0.1.0",
+  "schemaVersion": "0.1.1",
   "lenses": [
     "architecture",
     "data-flow"
@@ -28,5 +28,10 @@
       }
     ]
   },
-  "branding": true
+  "branding": true,
+  "github": {
+    "comment": {
+      "collapsed": false
+    }
+  }
 }

package/json-schema/config.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/config.schema.json",
   "title": "PR Lens repository config",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
@@ -143,6 +143,25 @@
       "default": true,
       "description": "Show the 'Rendered by PR Lens' footer on comments.",
       "type": "boolean"
+    },
+    "github": {
+      "default": {},
+      "type": "object",
+      "properties": {
+        "comment": {
+          "default": {},
+          "type": "object",
+          "properties": {
+            "collapsed": {
+              "default": false,
+              "description": "Start the hosted App's diagrams and details in a closed disclosure. Drawing still runs automatically.",
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
     }
   },
   "required": [

package/json-schema/graph-doc.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/graph-doc.schema.json",
   "title": "PR Lens graph document",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
       "type": "string",
       "pattern": "^0\\.1\\.\\d+$",
-      "description": "Contract version the document targets. Current: 0.1.0."
+      "description": "Contract version the document targets. Current: 0.1.1."
     },
     "kind": {
       "type": "string",
@@ -795,6 +795,225 @@
         "$ref": "#/$defs/View"
       }
     },
+    "walkthrough": {
+      "type": "object",
+      "properties": {
+        "steps": {
+          "minItems": 2,
+          "maxItems": 12,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128,
+                "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                "description": "Stable identifier, unique within its collection in a document."
+              },
+              "heading": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 48,
+                "description": "A step heading. Short enough to read at a glance."
+              },
+              "body": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 140,
+                "description": "A single line under a step heading."
+              },
+              "stage": {
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "view"
+                      },
+                      "view": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                        "description": "Id of the drill-down view to draw."
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "view"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "flow"
+                      },
+                      "flow": {
+                        "type": "string",
+                        "minLength": 1,
+                        "maxLength": 128,
+                        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                        "description": "Id of the flow to draw."
+                      }
+                    },
+                    "required": [
+                      "kind",
+                      "flow"
+                    ],
+                    "additionalProperties": false
+                  }
+                ],
+                "description": "Which diagram a walkthrough step plays over."
+              },
+              "focus": {
+                "default": {
+                  "kind": "all"
+                },
+                "oneOf": [
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "all"
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "additionalProperties": false
+                  },
+                  {
+                    "type": "object",
+                    "properties": {
+                      "kind": {
+                        "type": "string",
+                        "const": "selection"
+                      },
+                      "lanes": {
+                        "default": [],
+                        "maxItems": 64,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      },
+                      "nodes": {
+                        "default": [],
+                        "maxItems": 256,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      },
+                      "edges": {
+                        "default": [],
+                        "maxItems": 512,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      },
+                      "messages": {
+                        "default": [],
+                        "description": "Steps of the flow on the stage.",
+                        "maxItems": 64,
+                        "type": "array",
+                        "items": {
+                          "type": "string",
+                          "minLength": 1,
+                          "maxLength": 128,
+                          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:/-]*$",
+                          "description": "Stable identifier, unique within its collection in a document."
+                        }
+                      }
+                    },
+                    "required": [
+                      "kind"
+                    ],
+                    "additionalProperties": false,
+                    "anyOf": [
+                      {
+                        "properties": {
+                          "lanes": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "lanes"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "nodes": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "nodes"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "edges": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "edges"
+                        ]
+                      },
+                      {
+                        "properties": {
+                          "messages": {
+                            "minItems": 1
+                          }
+                        },
+                        "required": [
+                          "messages"
+                        ]
+                      }
+                    ]
+                  }
+                ],
+                "description": "What stays lit while a walkthrough step plays."
+              }
+            },
+            "required": [
+              "id",
+              "heading",
+              "body"
+            ],
+            "additionalProperties": false,
+            "description": "One stop on the walkthrough: a heading, a line under it, and the part of one diagram it is about."
+          },
+          "description": "Ordered by array position."
+        }
+      },
+      "required": [
+        "steps"
+      ],
+      "additionalProperties": false,
+      "description": "An ordered tour of this document's diagrams."
+    },
     "layout": {
       "type": "object",
       "properties": {

package/json-schema/patch-doc.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/patch-doc.schema.json",
   "title": "PR Lens patch document",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
       "type": "string",
       "pattern": "^0\\.1\\.\\d+$",
-      "description": "Contract version the document targets. Current: 0.1.0."
+      "description": "Contract version the document targets. Current: 0.1.1."
     },
     "kind": {
       "type": "string",

package/json-schema/render-manifest.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/coldteadotai/pr-lens/main/packages/schema/json-schema/render-manifest.schema.json",
   "title": "PR Lens render manifest",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "object",
   "properties": {
     "schemaVersion": {
       "type": "string",
       "pattern": "^0\\.1\\.\\d+$",
-      "description": "Contract version the document targets. Current: 0.1.0."
+      "description": "Contract version the document targets. Current: 0.1.1."
     },
     "kind": {
       "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coldtea/pr-lens-schema",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "The PR Lens contract: versioned schemas for architecture / data-flow graph documents, baseline patches, config and render manifests.",
   "license": "MIT",
   "author": "Coldtea AI",

package/src/apply.ts

@@ -4,6 +4,7 @@ import type { Flow, GraphDoc, GraphEdge, Lane, View } from "./graph.js";
 import { graphSnapshotIssues } from "./integrity.js";
 import { targetDescribesATransition, type PatchDoc, type PatchOp } from "./patch.js";
 import { assertNever } from "./utils.js";
+import { pruneWalkthrough } from "./walkthrough.js";
 
 type Collections = {
   lanes: Lane[];
@@ -298,6 +299,20 @@ export const applyPatch = (graph: GraphDoc, ops: readonly PatchOp[]): Parsed<Gra
     }
   }
 
+  /**
+   * The tour is pruned once, against the document the operations produced,
+   * rather than alongside each removal. A step names a diagram as well as
+   * elements, and an operation that rewrites a flow's steps takes members
+   * away without removing anything the other prunes would notice.
+   */
+  const walkthrough = pruneWalkthrough(graph.walkthrough, {
+    lanes: working.lanes,
+    nodes: working.nodes,
+    edges: working.edges,
+    flows: working.flows,
+    views,
+  });
+
   return safeParseGraphDoc({
     ...graph,
     lanes: working.lanes,
@@ -306,6 +321,7 @@ export const applyPatch = (graph: GraphDoc, ops: readonly PatchOp[]): Parsed<Gra
     flows: working.flows,
     stats: working.stats,
     views,
+    walkthrough,
     layout,
   });
 };

package/src/config.ts

@@ -63,6 +63,18 @@ export const Config = z
       .boolean()
       .default(true)
       .describe("Show the 'Rendered by PR Lens' footer on comments."),
+    github: z
+      .strictObject({
+        comment: z
+          .strictObject({
+            collapsed: z
+              .boolean()
+              .default(false)
+              .describe("Start the hosted App's diagrams and details in a closed disclosure. Drawing still runs automatically."),
+          })
+          .prefault({}),
+      })
+      .prefault({}),
   })
   .describe("Repository configuration for PR Lens.");
 export type Config = z.infer<typeof Config>;

package/src/examples/postmark-refactor.ts

@@ -8,7 +8,8 @@ import { SCHEMA_VERSION } from "../version.js";
  * refactor: broadcast sending moved from one Postmark request per recipient
  * to batched requests of 500, behind a shared library. Every downstream
  * renderer golden is measured against this document, so it exercises all
- * four delta states, a hero edge, and a full data-flow sequence.
+ * four delta states, a hero edge, a full data-flow sequence, and a
+ * walkthrough that stages both a drill-down view and a flow.
  */
 export const postmarkRefactorGraphInput: GraphDocInput = {
   schemaVersion: SCHEMA_VERSION,
@@ -393,6 +394,55 @@ export const postmarkRefactorGraphInput: GraphDocInput = {
       scope: { kind: "selection", flows: ["send-pipeline"] },
     },
   ],
+  walkthrough: {
+    steps: [
+      {
+        id: "batches-of-500",
+        heading: "sendBroadcastBulk and buildBulkPayload added",
+        body: "Nothing loops over recipients any more. The sender works on a whole batch at a time.",
+        stage: { kind: "view", view: "overview" },
+        focus: {
+          kind: "selection",
+          nodes: ["send-broadcast-bulk", "build-bulk-payload", "postmark"],
+        },
+      },
+      {
+        id: "suppression-first",
+        heading: "getSuppressedEmails added before the send",
+        body: "It pulls the blocked addresses once, before any batch is built.",
+        stage: { kind: "view", view: "new-batch-path" },
+        focus: { kind: "selection", nodes: ["get-suppressed-emails", "postmark"] },
+      },
+      {
+        id: "old-path-goes-dark",
+        heading: "processBroadcast and sendSingleEmail removed",
+        body: "sendBroadcastBulk does their job for whole batches.",
+        stage: { kind: "view", view: "overview" },
+        focus: { kind: "selection", nodes: ["process-broadcast", "send-single-email"] },
+      },
+      {
+        id: "sequence-start-to-finish",
+        heading: "The send sequence gained 6 new steps",
+        body: "The queue write is the only step that was there before, and it now stamps the batch size.",
+        stage: { kind: "flow", flow: "send-pipeline" },
+        focus: { kind: "all" },
+      },
+      {
+        id: "four-batch-calls",
+        heading: "Postmark now gets 500 emails per call",
+        body: "One call per batch, and Postmark answers with a result for each message.",
+        stage: { kind: "flow", flow: "send-pipeline" },
+        focus: { kind: "selection", messages: ["batch-post", "batch-results"] },
+      },
+      {
+        id: "blast-radius",
+        heading: "4 parts added, 2 removed, across 3 lanes",
+        body: "A 2,000-person broadcast used to make 2,000 calls to Postmark. It now makes 4.",
+        stage: { kind: "view", view: "overview" },
+        focus: { kind: "all" },
+      },
+    ],
+  },
   layout: {
     direction: "right",
     laneOrder: ["web", "functions", "external"],

package/src/graph.ts

@@ -1,5 +1,16 @@
 import { z } from "zod";
-import { Delta, FileRef, Id, Label, Lens, SchemaVersionField, Sha, Summary } from "./primitives.js";
+import {
+  Beat,
+  Delta,
+  FileRef,
+  Id,
+  Label,
+  Lens,
+  Line,
+  SchemaVersionField,
+  Sha,
+  Summary,
+} from "./primitives.js";
 
 /**
  * Coarse on purpose: this drives the card icon and shape, never analysis.
@@ -255,6 +266,92 @@ export const View: z.ZodType<View, ViewInput> = z.lazy(() =>
     .describe("A drill-down section; children nest as further <details> blocks."),
 );
 
+/**
+ * The picture a step plays over: one of the document's drill-down views, or
+ * one of its flows drawn on its own.
+ *
+ * Leaving it out means the picture the reader is already looking at. Which
+ * one that is belongs to the surface showing the document, not to the
+ * contract, so the contract says nothing about it.
+ */
+export const StepStage = z
+  .discriminatedUnion("kind", [
+    z.strictObject({
+      kind: z.literal("view"),
+      view: Id.describe("Id of the drill-down view to draw."),
+    }),
+    z.strictObject({
+      kind: z.literal("flow"),
+      flow: Id.describe("Id of the flow to draw."),
+    }),
+  ])
+  .describe("Which diagram a walkthrough step plays over.");
+export type StepStage = z.infer<typeof StepStage>;
+
+/**
+ * What a step points at inside its stage. The same two states a view scope
+ * has, and for the same reason: a step that loses the last element it named
+ * must never quietly become a step about everything.
+ *
+ * `messages` names steps of a flow, so it only means anything when the stage
+ * draws that flow. That pairing is the parser's to check.
+ */
+export const StepFocus = z
+  .discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("all") }),
+    z
+      .strictObject({
+        kind: z.literal("selection"),
+        lanes: z.array(Id).max(64).default([]),
+        nodes: z.array(Id).max(256).default([]),
+        edges: z.array(Id).max(512).default([]),
+        messages: z.array(Id).max(64).default([]).describe("Steps of the flow on the stage."),
+      })
+      .meta({
+        anyOf: [
+          { properties: { lanes: { minItems: 1 } }, required: ["lanes"] },
+          { properties: { nodes: { minItems: 1 } }, required: ["nodes"] },
+          { properties: { edges: { minItems: 1 } }, required: ["edges"] },
+          { properties: { messages: { minItems: 1 } }, required: ["messages"] },
+        ],
+      })
+      .refine(
+        (focus) =>
+          focus.lanes.length + focus.nodes.length + focus.edges.length + focus.messages.length > 0,
+        { message: "a selection must name at least one element" },
+      ),
+  ])
+  .describe("What stays lit while a walkthrough step plays.");
+export type StepFocus = z.infer<typeof StepFocus>;
+
+export const WalkthroughStep = z
+  .strictObject({
+    id: Id,
+    heading: Beat,
+    body: Line,
+    stage: StepStage.optional(),
+    focus: StepFocus.default({ kind: "all" }),
+  })
+  .describe(
+    "One stop on the walkthrough: a heading, a line under it, and the part of one diagram it is about.",
+  );
+export type WalkthroughStep = z.infer<typeof WalkthroughStep>;
+
+/**
+ * An ordered tour of the document's diagrams, authored alongside them.
+ *
+ * Two steps is the floor because one step is a caption, and twelve is the
+ * ceiling because a reader scrolling a rail loses the thread long before
+ * that. A document that carries one has already decided what a reader should
+ * see first; a surface playing it only reads.
+ */
+export const Walkthrough = z
+  .strictObject({
+    steps: z.array(WalkthroughStep).min(2).max(12).describe("Ordered by array position."),
+  })
+  .describe("An ordered tour of this document's diagrams.");
+export type Walkthrough = z.infer<typeof Walkthrough>;
+
 /**
  * Hints, not instructions: the renderer owns final placement so that layout
  * stays deterministic for a given document. A hint is a floor rather than an
@@ -324,6 +421,7 @@ export const GraphDoc = z
     flows: z.array(Flow).max(16).default([]),
     stats: Stats.optional(),
     views: z.array(View).max(32).default([]),
+    walkthrough: Walkthrough.optional(),
     layout: LayoutHints.optional(),
   })
   .describe("A PR Lens graph document.");

package/src/index.ts

@@ -1,6 +1,7 @@
 export { SCHEMA_VERSION, type SchemaVersion } from "./version.js";
 
 export {
+  Beat,
   Delta,
   DELTAS,
   FileRef,
@@ -9,6 +10,7 @@ export {
   Label,
   Lens,
   LENSES,
+  Line,
   MAX_RENDER_ASSETS,
   MAX_VIEWS,
   Theme,
@@ -34,8 +36,12 @@ export {
   Provenance,
   StatChip,
   Stats,
+  StepFocus,
+  StepStage,
   View,
   ViewScope,
+  Walkthrough,
+  WalkthroughStep,
   type GraphDocInput,
   type ViewInput,
 } from "./graph.js";
@@ -79,4 +85,6 @@ export {
 
 export { applyPatch, applyPatchDoc } from "./apply.js";
 
+export { pruneWalkthrough, type WalkthroughSubject } from "./walkthrough.js";
+
 export { assertNever } from "./utils.js";

package/src/integrity.ts

@@ -2,6 +2,7 @@ import type { SchemaIssue } from "./errors.js";
 import type { GraphDoc, View } from "./graph.js";
 import { FullSha, MAX_VIEWS, THEMES, type Delta } from "./primitives.js";
 import { assertNever } from "./utils.js";
+import { indexViews, stagedMessages } from "./walkthrough.js";
 
 const duplicates = (ids: readonly string[]): string[] => {
   const seen = new Set<string>();
@@ -135,6 +136,82 @@ export const graphIntegrityIssues = (doc: GraphDoc): SchemaIssue[] => {
     }
   }
 
+  if (doc.walkthrough) {
+    const viewsById = indexViews(doc.views);
+
+    for (const id of duplicates(doc.walkthrough.steps.map((step) => step.id)))
+      duplicate("walkthrough.steps", `duplicate step id '${id}'`);
+
+    doc.walkthrough.steps.forEach((step, index) => {
+      const at = `walkthrough.steps[${index}]`;
+
+      if (step.stage !== undefined) {
+        switch (step.stage.kind) {
+          case "view":
+            if (!viewsById.has(step.stage.view))
+              broken(`${at}.stage.view`, `step '${step.id}' stages unknown view '${step.stage.view}'`);
+            break;
+          case "flow":
+            if (!flowIds.has(step.stage.flow))
+              broken(`${at}.stage.flow`, `step '${step.id}' stages unknown flow '${step.stage.flow}'`);
+            break;
+          default:
+            assertNever(step.stage, "Unhandled step stage");
+        }
+      }
+
+      switch (step.focus.kind) {
+        case "all":
+          break;
+        case "selection": {
+          const focus = step.focus;
+          const focused: [keyof Omit<typeof focus, "kind" | "messages">, string, ReadonlySet<string>][] = [
+            ["lanes", "lane", laneIds],
+            ["nodes", "node", nodeIds],
+            ["edges", "edge", edgeIds],
+          ];
+          for (const [collection, singular, known] of focused) {
+            focus[collection].forEach((id, memberIndex) => {
+              if (!known.has(id))
+                broken(
+                  `${at}.focus.${collection}[${memberIndex}]`,
+                  `step '${step.id}' focuses unknown ${singular} '${id}'`,
+                );
+            });
+          }
+
+          const onStage = stagedMessages(step.stage, doc.flows, viewsById);
+          switch (onStage.kind) {
+            case "messages":
+              focus.messages.forEach((id, memberIndex) => {
+                if (!onStage.ids.has(id))
+                  broken(
+                    `${at}.focus.messages[${memberIndex}]`,
+                    `step '${step.id}' focuses '${id}', which no flow on its stage carries`,
+                  );
+              });
+              break;
+            case "no-stage":
+              if (focus.messages.length > 0)
+                issues.push({
+                  code: "INVALID_DOCUMENT",
+                  path: `${at}.focus.messages`,
+                  message: `step '${step.id}' focuses flow steps but names no stage to draw them on`,
+                });
+              break;
+            case "unknown-stage":
+              break;
+            default:
+              assertNever(onStage, "Unhandled staged messages");
+          }
+          break;
+        }
+        default:
+          assertNever(step.focus, "Unhandled step focus");
+      }
+    });
+  }
+
   if (doc.layout) {
     doc.layout.laneOrder.forEach((id, index) => {
       if (!laneIds.has(id)) broken(`layout.laneOrder[${index}]`, `unknown lane '${id}'`);
@@ -167,6 +244,14 @@ export const graphSnapshotIssues = (doc: GraphDoc): SchemaIssue[] => {
       message: "a stored map needs an id, so a patch can say which map it targets",
     });
 
+  if (doc.walkthrough !== undefined)
+    issues.push({
+      code: "NOT_A_SNAPSHOT",
+      path: "walkthrough",
+      message:
+        "a stored map carries a walkthrough, but a walkthrough narrates a change and a map describes a system",
+    });
+
   for (const side of ["base", "head"] as const) {
     if (!FullSha.safeParse(doc.provenance[side].sha).success)
       issues.push({

package/src/primitives.ts

@@ -38,6 +38,27 @@ export const Summary = z
   .max(2000)
   .describe("One or two sentences of plain prose. No markdown headings.");
 
+/**
+ * A walkthrough step's heading. The cap is part of the contract rather than
+ * advice: the rail shows one line per step, so a heading long enough to wrap
+ * turns the tour into a wall of text, and no producer can pad its way past it.
+ */
+export const Beat = z
+  .string()
+  .min(1)
+  .max(48)
+  .describe("A step heading. Short enough to read at a glance.");
+
+/**
+ * The one line of body under a step's heading. Required: a heading with
+ * nothing under it reads as a step someone started and never finished.
+ */
+export const Line = z
+  .string()
+  .min(1)
+  .max(140)
+  .describe("A single line under a step heading.");
+
 export const Sha = z
   .string()
   .regex(/^[0-9a-f]{7,40}$/, "must be a lowercase hex git object name")

package/src/version.ts

@@ -6,7 +6,7 @@
  * with semver semantics: patch/minor releases only ever add optional fields
  * or widen an enum, a major release may remove or retype a field.
  */
-export const SCHEMA_VERSION = "0.1.0" as const;
+export const SCHEMA_VERSION = "0.1.1" as const;
 
 export type SchemaVersion = typeof SCHEMA_VERSION;
 

package/src/walkthrough.ts

@@ -0,0 +1,146 @@
+import type { Flow, GraphEdge, GraphNode, Lane, StepStage, View, Walkthrough } from "./graph.js";
+import { assertNever } from "./utils.js";
+
+const NOTHING: ReadonlySet<string> = new Set();
+
+export const indexViews = (views: readonly View[]): Map<string, View> =>
+  new Map(views.flatMap((view) => [[view.id, view] as const, ...indexViews(view.children)]));
+
+/**
+ * A flow step is only ever identified within its own flow, so the stage rather
+ * than the document decides which one a focus meant. Two flows may each carry
+ * a step called `retry`, and neither document is wrong for it.
+ *
+ * `unknown-stage` is its own answer rather than an empty set, so a stage that
+ * names a view or flow the document lacks is reported once, as the broken
+ * reference it is, instead of again for every step underneath it.
+ */
+export type StagedMessages =
+  | { kind: "messages"; ids: ReadonlySet<string> }
+  | { kind: "no-stage" }
+  | { kind: "unknown-stage" };
+
+const messageIdsOf = (flows: readonly Flow[]): Set<string> =>
+  new Set(flows.flatMap((flow) => flow.messages.map((message) => message.id)));
+
+export const stagedMessages = (
+  stage: StepStage | undefined,
+  flows: readonly Flow[],
+  views: ReadonlyMap<string, View>,
+): StagedMessages => {
+  if (stage === undefined) return { kind: "no-stage" };
+
+  switch (stage.kind) {
+    case "flow": {
+      const flow = flows.find(({ id }) => id === stage.flow);
+      return flow === undefined
+        ? { kind: "unknown-stage" }
+        : { kind: "messages", ids: messageIdsOf([flow]) };
+    }
+    case "view": {
+      const view = views.get(stage.view);
+      if (view === undefined) return { kind: "unknown-stage" };
+
+      switch (view.scope.kind) {
+        case "all":
+          return { kind: "messages", ids: messageIdsOf(flows) };
+        case "selection": {
+          const scoped = view.scope.flows;
+          return {
+            kind: "messages",
+            ids: messageIdsOf(flows.filter((flow) => scoped.includes(flow.id))),
+          };
+        }
+        default:
+          return assertNever(view.scope, "Unhandled view scope");
+      }
+    }
+    default:
+      return assertNever(stage, "Unhandled step stage");
+  }
+};
+
+/**
+ * The document that survived, rather than the ids that went: a step names a
+ * diagram as well as elements, and a flow step means nothing outside the flow
+ * that carries it.
+ */
+export type WalkthroughSubject = {
+  lanes: readonly Lane[];
+  nodes: readonly GraphNode[];
+  edges: readonly GraphEdge[];
+  flows: readonly Flow[];
+  views: readonly View[];
+};
+
+const stageSurvives = (
+  stage: StepStage,
+  flows: ReadonlySet<string>,
+  views: ReadonlyMap<string, View>,
+): boolean => {
+  switch (stage.kind) {
+    case "view":
+      return views.has(stage.view);
+    case "flow":
+      return flows.has(stage.flow);
+    default:
+      return assertNever(stage, "Unhandled step stage");
+  }
+};
+
+const focusable = (staged: StagedMessages): ReadonlySet<string> => {
+  switch (staged.kind) {
+    case "messages":
+      return staged.ids;
+    case "no-stage":
+    case "unknown-stage":
+      return NOTHING;
+    default:
+      return assertNever(staged, "Unhandled staged messages");
+  }
+};
+
+/**
+ * A step that loses the last element it focused is dropped rather than left
+ * to widen into a step about everything. A tour of one step is a caption, so
+ * a walkthrough cut below two steps goes whole.
+ */
+export const pruneWalkthrough = (
+  walkthrough: Walkthrough | undefined,
+  subject: WalkthroughSubject,
+): Walkthrough | undefined => {
+  if (walkthrough === undefined) return undefined;
+
+  const lanes = new Set(subject.lanes.map((lane) => lane.id));
+  const nodes = new Set(subject.nodes.map((node) => node.id));
+  const edges = new Set(subject.edges.map((edge) => edge.id));
+  const flows = new Set(subject.flows.map((flow) => flow.id));
+  const views = indexViews(subject.views);
+
+  const steps = walkthrough.steps.flatMap((step) => {
+    if (step.stage !== undefined && !stageSurvives(step.stage, flows, views)) return [];
+
+    switch (step.focus.kind) {
+      case "all":
+        return [step];
+      case "selection": {
+        const onStage = focusable(stagedMessages(step.stage, subject.flows, views));
+        const focus = {
+          kind: "selection",
+          lanes: step.focus.lanes.filter((id) => lanes.has(id)),
+          nodes: step.focus.nodes.filter((id) => nodes.has(id)),
+          edges: step.focus.edges.filter((id) => edges.has(id)),
+          messages: step.focus.messages.filter((id) => onStage.has(id)),
+        } as const;
+
+        const focused =
+          focus.lanes.length + focus.nodes.length + focus.edges.length + focus.messages.length;
+        return focused === 0 ? [] : [{ ...step, focus }];
+      }
+      default:
+        return assertNever(step.focus, "Unhandled step focus");
+    }
+  });
+
+  return steps.length < 2 ? undefined : { ...walkthrough, steps };
+};