@widnyana/design-thinking 0.0.20 → 0.1.0

package/references/{protocol.md → output-format.md}

@@ -1,15 +1,18 @@
-# Graph Protocol
+# Design Thinking: Output Format
 
-The notation spec for **Design Graphs**. A Design Graph is the annotated call graph
-of a concrete problem: nodes are functions, edges are data flow, and every node
-carries annotations for data (A), cardinality, failure (E), and requirements (R).
+How a [Design Thinking](design-thinking.md) result is written down: the
+annotated call graph of a concrete problem. Nodes are functions, edges are
+data flow, and every node carries annotations for data (A), cardinality,
+failure (E), and requirements (R).
 
-The Protocol is stack-agnostic. A graph written for Go, Rust, Python, TypeScript,
+The format is stack-agnostic. A graph written for Go, Rust, Python, TypeScript,
 SQL, or a spreadsheet renders identically. Only the vocabulary inside the
 annotations changes (e.g. what "retry" means in your language).
 
 Every tool in this package (`/cg`, `/cg-plan`, `/cg-review`, `/cg-map`, and the
-`/dt` active mode) MUST emit output in the format below.
+`/dt` active mode) MUST emit output in the format below. Interface work uses
+the [Design Graph](design-graph.md) skeleton instead; delegation to agents adds
+the [Graph Protocol](graph-protocol.md) blocks.
 
 ---
 
@@ -21,7 +24,7 @@ empty for the problem at hand (say so: `SCOPE: none`), never to skip thinking.
 ```
 PROBLEM: <one-line statement of what you're building or examining>
 
-X → DesignGraph<A, E, R>
+X → Graph → Effect<A, E, R>
 │              │   │  │  │
 │              │   │  │  └─ R: what each node needs      (§5)
 │              │   │  └──── E: where the graph breaks    (§4)
@@ -52,7 +55,7 @@ The header names the problem and anchors the three channels. `X` is your problem
 everything after it is the graph you build.
 
 ```
-X → DesignGraph<A, E, R>
+X → Graph → Effect<A, E, R>
 │              │   │  │  │
 │              │   │  │  └─ R: what each node needs      (§5)
 │              │   │  └──── E: where the graph breaks    (§4)
@@ -194,7 +197,7 @@ produced which error. Mark it clearly; it should be rare.
 ```
 PROBLEM: sync a list of URLs to local files, resumable, with a status line
 
-X → DesignGraph<A, E, R>
+X → Graph → Effect<A, E, R>
 │              │   │  │  │
 │              │   │  │  └─ R: Http, Clock, Logger      (§5)
 │              │   │  └──── E: NetErr, DiskErr          (§4)
@@ -225,4 +228,83 @@ VERDICT:     happy path reads as the pipeline above; all NetErr handling lives a
 ```
 
 Note the stack vocabulary: `context manager` for scope, exceptions caught at
-layer joins for E, plain functions for nodes. Protocol unchanged.
+layer joins for E, plain functions for nodes. Format unchanged.
+
+---
+
+## Call graph block (`/cg`, architecture traces, "how does X work")
+
+When the answer is a trace of existing code, the GRAPH section uses this
+block. Plain text only, no rendered diagrams.
+
+````
+graph: <short title>
+
+Production:
+```ts
+EntryPoint
+  → ComponentA
+    → ComponentA.method
+      → [condition] ComponentB
+        → {queue_or_store}
+```
+
+Tests:
+```ts
+TestEntryPoint
+  → ComponentATestLayer
+    → ComponentA.method
+      → ComponentBTestLayer
+```
+
+src:
+  EntryPoint → path/to/file.ts:LINE
+  ComponentA → path/to/component.ts:LINE
+  ComponentA.method → path/to/component.ts:LINE
+  ComponentB → path/to/other.ts:LINE
+````
+
+Rules:
+
+- `ts` fence for every stack (it renders arrows well), two-space-indented `→`
+  children. The root has no arrow; indentation is the call hierarchy.
+- Use the real functions, methods, services, jobs, queues, and stores.
+- Production always. Tests only when the test graph differs (that difference
+  IS the swapped R from §9). Never invent a test graph.
+- `src:` gives verified `path:line` evidence for every unique node. Never
+  guess paths, symbols, callers, or line numbers.
+- Mark planned nodes `[new]`; never invent future line numbers.
+- Skip the graph for a trivial single-fact question (a port, a version).
+
+---
+
+## Completeness checklist
+
+A result is complete when all of the following hold:
+
+- [ ] Every node has a cardinality marker — `(1)`, `(N)`, or `(T)`.
+- [ ] Every node lists its `R:` — even if `R: none` (that is a feature: the
+      node is runnable standalone).
+- [ ] Every edge crossing a trust boundary is marked `🔒 unknown → trusted`.
+- [ ] Every failure mode has a strategy — `⟳retry`, `↯escape(alt)`, or
+      `☠die`. No unmarked breaks, no silent swallowing.
+- [ ] Every layer scopes its E before handing off (inner errors translated,
+      never leaked).
+- [ ] Every resource has an acquire point and a structural release point.
+- [ ] BEHAVIOR lists only layers that can be removed without touching the
+      happy path.
+- [ ] TEST LAYERS shows a full R substitution — if it can't, the graph has
+      hidden dependencies.
+- [ ] VERDICT explicitly answers whether code and graph match, and names the
+      mismatches.
+
+## The three uses
+
+1. **Plan** (`/cg-plan`) — draw the graph first. Code is written only after
+   the VERDICT has a target to be checked against. If code contradicts the
+   graph, fix the graph or fix the code; never let them drift silently.
+2. **Extract** (`/cg`) — reconstruct the graph the code *actually*
+   implements, not the one the author intended.
+3. **Review** (`/cg-review`) — render the implemented graph, diff it against
+   the intended graph (or this checklist), group findings by § number, end
+   with a VERDICT line.

package/skills/design-graph/SKILL.md

@@ -1,102 +1,223 @@
 ---
 name: design-graph
 description: >
-  Design Graph — the artifact: annotated call graph of a concrete problem;
-  nodes = functions, edges = data flow; every node annotated with A,
-  cardinality, E, R. Use when drawing a graph before writing code or
-  reconstructing and diffing one against existing code. Includes the
-  completeness checklist.
+  Design Graph: the interface method. Job → Flow → Surface<C, V, N>:
+  surfaces, content (C), void states (V: empty, loading, partial, error,
+  denied), needs (N), field boundaries, motion layers, attention scope, proof
+  by swapping N. Use when designing or reviewing screens, flows, or components.
 disable-model-invocation: true
 ---
 
-# Design Graph — The Artifact
+> **Source**: Design Graph by [r17x](https://github.com/r17x), from
+> https://gist.github.com/r17x/90eb2f7be93932b5693753aedb09c01a (`OPT_DESIGN_GRAPH.md`).
+> Method text bundled as-is. The output skeleton at the end is added by this package.
 
-A **Design Graph** is the annotated call graph of a concrete problem. It is
-what you produce when you apply Design Thinking (see the `design-method` skill) to
-something, and it is written in Graph Protocol notation (see the `graph-protocol` skill).
+# Design Graph
 
-Nodes are functions. Edges are data flow. The annotations answer, for every
-node: what flows through it (A), how many times it runs (cardinality), where
-and how it can fail (E), and what it needs to exist (R) — plus the global
-concerns: trust boundaries, behavior layers, resource scope, and test layers.
+The same method, turned on the interface. A screen is not a picture — it is a node with three channels, and the layout you draw is the graph the user walks.
 
-A Design Graph is not documentation written after the fact. It is drawn
-**before** implementation (planning), **reconstructed** from implementation
-(review), and **compared** against implementation (verdict). The graph is the
-contract; the code is one instantiation of it.
-**Hard gate:** when a turn will produce code or file edits, the graph comes
-first — render it (and any clarifying questions), get the user's approval,
-and only then write code that matches it.
+Design Thinking answers what flows through the program. Design Graph answers what the person in front of it can be looking at. Same three-channel discipline: one channel for the content, one for every way the content can be absent, one for what the surface needs before it may exist.
+
+```
+Job → Flow → Surface<C, V, N>
+│      │      │  │  │
+│      │      │  │  └─ what the surface needs to exist   (§5)
+│      │      │  └──── every way the content is absent   (§4)
+│      │      └─────── what the person reads and does    (§2)
+│      │
+│      └─ nodes = surfaces, edges = the moves between them
+│
+└─ the job: what the person came here to get done
+
+§1  Surfaces     the nouns: screens, panes, rows, fields, controls
+§2  C            happy path as flow graph
+§3  Cardinality  one record (Detail) or many (List / live)
+§4  V            void states: empty, loading, partial, error, denied
+§5  N            needs: data, permission, prior step, viewport
+§6  Boundary     validate at the field, not at submit
+§7  Behavior     motion and feedback wrap a surface, never reshape it
+§8  Scope        attention is acquired and must be released
+§9  Proof        swap N, same flow shape
+§10 Craft        markup = C, state styles = V
+```
+
+Read the job. Draw the moves as a flow graph. Build an interface that IS the graph. If a surface can render a state the graph cannot name, the interface is lying.
+
+## 1. Name the surfaces
+
+What are the things a person can look at? Before opening a layout tool, define the interface language.
+
+- **Surfaces** -- the addressable places. A rail, a list, a detail pane, a drawer. Each one has a name and an owner.
+- **Units** -- the repeated shape inside a surface. A row, a field, a metric. Named once, reused everywhere.
+- **States** -- what a unit can be. Rest, hover, selected, disabled, stale. Enumerated, not improvised at build time.
+- **Moves** -- what the person can do to get somewhere else. Open, select, dismiss, commit, undo.
+
+These are the nouns. The moves are the verbs. A design system that names colours but not surfaces has no vocabulary — only a palette.
+
+## 2. Think C first
+
+Map the successful job as a flow graph before drawing a single frame. Nodes are surfaces, edges are the moves between them.
+
+```
+Rail(scope) -> List(C) -> Detail(C) -> Commit
+```
+
+This graph is the information architecture. Every screen that does not appear on it is a screen nobody asked for. If two nodes need the same surface, that surface is a component; if a node has one edge in and one edge out, it may not need to be a screen at all.
+
+## 3. One or many?
+
+Decide the cardinality of each node before its layout. Getting this wrong is the most expensive mistake in the graph, because it changes the shape of the surface, not its styling.
+
+- **One record** -- a detail surface. Reading measure, full metadata, one primary action.
+- **Many records** -- a list surface. Scannable, uniform rows, selection as a wash. Must survive 0, 1, and 10,000.
+- **Live** -- values that change while being read. Show the timestamp, never move the row under the cursor.
+
+Do not let a list masquerade as a card, and never let a live value pretend to be static. A surface designed for the average case has no design for the real one.
+
+## 4. Think V second
+
+V is the void channel: every way the content can fail to be there. Each node enumerates its own, and each one is a designed surface, not a fallback.
+
+- **Empty** -- nothing yet, and that is fine. One grey sentence saying what will appear here.
+- **Loading** -- the shape is known, the values are not. A flat skeleton in the layout the content will occupy.
+- **Partial** -- some of it arrived. Show what you have and mark what is missing — never block the whole surface for one field.
+- **Error** -- it broke, and the person can act. Say what failed, in their words, next to the thing that failed.
+- **Denied** -- they may not see it. Prefer never routing them here over explaining the refusal.
+
+A surface with one designed state and four undesigned ones is 20% designed. The void states are where the interface earns trust, because they are the states the person meets on their worst day.
+
+## 5. Think N third
+
+Mark what each surface needs before it is allowed to exist. "We cannot show X if we do not have Y."
+
+N is the interface's version of compile-time proof. A surface declares its needs — a signed-in user, a selected record, a permission, a minimum viewport, a completed prior step — and the graph must satisfy them on the edge that reaches it.
+
+- **Data** -- a record must be selected. No selection is a different node, not an empty pane.
+- **Permission** -- if they cannot act, do not draw the affordance. A disabled button is a last resort.
+- **Prior step** -- step 3 requires step 2. Unreachable is better than reachable and broken.
+- **Viewport** -- three panes need width. Below it, the graph re-routes — the detail becomes a drawer, not a squeeze.
+
+If a screen can be reached without its needs met, the flow graph has a hole. That hole is a bug in the design, not a case for the engineer to handle.
+
+## 6. Trust at boundary
+
+Where does the person's own input enter the graph? Fields, uploads, pastes, drags, URLs they typed themselves.
+
+Validate at the field, not at submit. The boundary of the interface is the control they are touching — that is where unknown becomes trusted, and where the message belongs. One definition of a field gives the label, the constraint and the error sentence together.
+
+Trust nothing at the boundary. Trust everything past it. A form that only fails on submit has moved its boundary to the wrong place, and made the person pay for the move.
+
+## 7. Layer behavior
+
+What wraps a surface without changing what it says? Motion, focus, feedback, density, keyboard affordance, reduced-motion.
+
+These are layers around a node, never edits to it. A wash on hover, a reveal on entry, a ring on focus — the content graph is identical with them and without them. If removing the animation changes what the person can learn from the screen, the animation was carrying content and the layout was underbuilt.
+
+The graph says WHAT the surface is. The layers say HOW it responds to being used.
+
+## 8. Scope attention
+
+Which surfaces acquire the person's attention? Modals, drawers, menus, toasts, anything that takes the viewport or the focus ring.
+
+Attention is a resource with acquire and release. Whatever takes focus returns it to where it came from — on confirm, on cancel, on escape, on interrupt. Whatever covers the graph must name the single move that uncovers it.
+
+An overlay with no defined release is a leak. The person is left holding a surface the graph has forgotten about.
+
+## 9. Swap N to prove it
+
+The flow graph does not change between the demo and the first real account. Only N changes.
+
+Same nodes. Same C flowing through. Same V possible. Different context behind N. Run the graph four times and see whether it still holds:
+
+- **Day one** -- nothing in the account. Every list is empty; the graph must still be legible.
+- **Year three** -- 40,000 records, titles twice as long as the mock. Nothing may reflow into nonsense.
+- **Least access** -- the read-only member. Which affordances vanish, and does the layout survive their absence?
+- **Small and slow** -- one hand, poor network, reduced motion on. The graph re-routes; it does not degrade.
+
+If the design only works with ideal data, it is not a design — it is a screenshot. This is the payoff of separating C, V and N: you prove the interface by swapping what is behind N and watching the graph hold its shape.
+
+## 10. Markup is C, state styles are V
+
+The separation of C (§2) and V (§4) maps directly to how the interface is built:
+
+- **the component tree** -- the happy path. Every element is content flowing through the graph. No state branching inside.
+- **the recipe variants** -- the complete V enumeration. Before writing them, read the actual states the surface can be in. Every one is named and styled — none is left to the browser default.
+
+This is not a stylistic preference. If state handling lives inside the tree, the content path and the void path are tangled — you cannot read the layout without wading through conditionals, and no one can tell which states were designed and which were merely reached.
+
+The tree IS the flow graph from §2. The variants ARE the void enumeration from §4.
+
+### One method, two materials
+
+The mapping is exact by construction. Anywhere the two columns disagree, one of the two graphs is wrong — most often the interface, because it is the one that gets drawn before it is thought.
+
+| § | DESIGN THINKING | DESIGN GRAPH |
+|---|-----------------|--------------|
+| X | the problem to build | the job to get done |
+| graph | functions and data flow | surfaces and moves |
+| 1 | records, IDs, variants, errors | surfaces, units, states, moves |
+| 2 | A — what flows | C — what is read and done |
+| 3 | Effect or Stream | detail, list, or live |
+| 4 | E — retry, escape, die | V — empty, loading, partial, error, denied |
+| 5 | R — dependencies, proven | N — needs, satisfied on the edge |
+| 6 | parse at the transport edge | validate at the field |
+| 7 | pipe wraps the node | motion wraps the surface |
+| 8 | scope the resource | scope the attention |
+| 9 | swap R in tests | swap N in review |
+| 10 | gen body = A, pipe = E | tree = C, variants = V |
 
 ---
 
-## What a complete Design Graph contains
+## The Craft Pipeline
 
 ```
-PROBLEM: <one line>
-
-X → DesignGraph<A, E, R>
-│              │   │  │  │
-│              │   │  │  └─ R: what each node needs      (§5)
-│              │   │  └──── E: where the graph breaks    (§4)
-│              │   └─────── A: what flows through nodes  (§2)
-│              │
-│              └─ nodes = functions, edges = data flow
-│
-└─ the problem
-
-SHAPES:  …        every noun the graph needs
-GRAPH:  …        ascii call graph with inline R:/E:/🔒/(n) annotations
-CARDINALITY: …   every node marked (1) (N) or (T)
-BOUNDARIES: …    every unknown → trusted crossing
-BEHAVIOR: …      every orthogonal layer and what it wraps
-SCOPE: …         every resource with acquire@x → release@x
-TEST LAYERS: …   the R tests provide — same GRAPH, zero code change
-VERDICT: …       code matches graph? A and E structurally separated?
+JOB
+  -> "What are the surfaces?"                      -> define the interface language
+  -> "What is the successful path?"                -> draw the flow graph (C)
+  -> "One record, many, or live?"                  -> mark cardinality per surface
+  -> "How can the content be absent?"              -> annotate void states (V)
+  -> "What must be true to show this?"             -> annotate needs on the edges (N)
+  -> "Where does their input enter?"               -> validate at the field
+  -> "What wraps a surface without reshaping it?"  -> layer motion and feedback
+  -> "What takes attention, and how is it given back?" -> scope every overlay
+  -> "Does it hold on day one and year three?"     -> swap N and re-walk the graph
+  -> "Does the build separate C from V?"           -> tree = C, variants = V
+  -> INTERFACE                                     -> the interface IS the graph
 ```
 
-## Completeness checklist
-
-A Design Graph is complete when all of the following hold:
-
-- [ ] Every node has a cardinality marker — `(1)`, `(N)`, or `(T)`.
-- [ ] Every node lists its `R:` — even if `R: none` (that is a feature: the
-      node is runnable standalone).
-- [ ] Every edge crossing a trust boundary is marked `🔒 unknown → trusted`.
-- [ ] Every failure mode has a strategy — `⟳retry`, `↯escape(alt)`, or
-      `☠die`. No unmarked breaks, no silent swallowing.
-- [ ] Every layer scopes its E before handing off (inner errors translated,
-      never leaked).
-- [ ] Every resource has an acquire point and a structural release point.
-- [ ] BEHAVIOR lists only layers that can be removed without touching the
-      happy path.
-- [ ] TEST LAYERS shows a full R substitution — if it can't, the graph has
-      hidden dependencies.
-- [ ] VERDICT explicitly answers whether code and graph match, and names the
-      mismatches.
-
-## The three uses
-
-### 1. Plan (`/cg-plan`)
-Draw the graph first. Code is written only after the VERDICT question — "does
-my code match this?" — has a target to be checked against. If a code
-suggestion contradicts the graph, fix the graph or fix the code; never let
-them drift silently.
-
-### 2. Extract (`/cg`)
-Given existing code, reconstruct the graph the code *actually* implements —
-not the one the author intended. The reconstructed graph is the ground truth
-for review and refactoring.
-
-### 3. Review (`/cg-review`)
-Render the implemented graph, then diff it against the intended graph (or
-against the method's completeness checklist when no intended graph exists).
-Every mismatch is a finding, grouped by § number. The review ends with a
-VERDICT line.
+**If a surface can render a state the graph cannot name, the design is wrong.**
 
 ---
 
-## Worked example
+## Output skeleton
+
+Interface work renders in this fixed order, the UI twin of the
+[Design Thinking output format](../../references/output-format.md). Same markers where the
+meaning carries over (`(1)` detail, `(N)` list, `(T)` live, `🔒` field
+boundary, `⛈` behavior layer).
 
-See the end of the `graph-protocol` skill for a complete, non-TS worked
-example (a resumable URL-sync CLI in Python) with all sections filled.
+```
+JOB: <one line: what the person came here to get done>
+
+Job → Flow → Surface<C, V, N>
+│      │      │  │  │
+│      │      │  │  └─ N: what the surface needs to exist   (§5)
+│      │      │  └──── V: every way the content is absent   (§4)
+│      │      └─────── C: what the person reads and does    (§2)
+│      │
+│      └─ nodes = surfaces, edges = the moves between them
+│
+└─ the job
+
+SURFACES:    surfaces · units · states · moves
+FLOW:        ascii flow graph, annotated inline:
+             N: needs · V: empty|loading|partial|error|denied · 🔒 field → trusted
+CARDINALITY: surface (1) detail · (N) list · (T) live
+VOID:        every surface × its designed void states
+NEEDS:       data · permission · prior step · viewport, satisfied on the edge
+BOUNDARY:    every field where input becomes trusted, with its error sentence
+BEHAVIOR:    motion, focus, feedback layers that wrap a surface without reshaping it
+ATTENTION:   overlays: acquire@move → release@confirm|cancel|escape
+PROOF:       day one · year three · least access · small and slow
+VERDICT:     does every rendered state have a name on the graph?
+```

package/skills/{design-method → design-thinking}/SKILL.md

@@ -1,35 +1,37 @@
 ---
-name: design-method
+name: design-thinking
 description: >
-  Design Thinking — the §1–§10 problem-first pipeline: shapes → graph(A) →
-  cardinality → break points (E: ⟳ ↯ ☠) → requirements (R) → boundaries →
-  behavior layers → scope → test layers → verdict. Stack-agnostic. Use when
-  planning, designing, or refactoring any feature or system.
+  Design Thinking: the code method. X → Graph → Effect<A, E, R>, the §1-§10
+  pipeline: shapes, happy path (A), cardinality, break points (E: ⟳ ↯ ☠),
+  requirements (R), boundaries, behavior layers, scope, test layers, code.
+  Stack-agnostic. Use when planning, designing, reviewing, or refactoring code.
+  Output format lives in references/output-format.md.
 disable-model-invocation: true
 ---
 
-# Design Thinking — The Method
+# Design Thinking
 
-A stack-agnostic design methodology. Read the problem. Draw the data flow as a
-call graph (the **Design Graph**). Write code that IS the graph. If the code
-doesn't match the graph, something is wrong.
+The code method. Read the problem. Draw the data flow as a call graph. Write
+code that IS the graph. If the code doesn't match the graph, something is wrong.
+
+One of three methods with the same shape (see [design-graph.md](../../references/design-graph.md)
+for the interface, [graph-protocol.md](../../references/graph-protocol.md) for delegation to
+agents). The original is written in Effect-TS ([effect-ts.md](../../references/effect-ts.md)).
+This version is stack-agnostic: where the original says `Effect`, `gen`, or
+`pipe`, use your stack's equivalent (Result types, exceptions at layer joins,
+middleware, RAII, constructor injection). The discipline never changes, only
+the vocabulary.
 
-The method is language-neutral. Where it says "Effect", "gen", or "pipe" in the
-Effect-TS appendix (`effect-ts.md`), substitute your stack's equivalent: Result
-types, exceptions at layer joins, middleware, RAII, constructor injection —
-whatever your language provides. The discipline never changes, only the vocabulary.
 **Hard gate — applies in every harness (pi, omp, Claude Code, any agent):**
 When the user asks for a feature, change, fix, or refactor — or when any turn
-will end in proposed code or file edits — you MUST render the Design Graph
-(Graph Protocol) and any clarifying questions BEFORE touching any file, and
-implement only after the user approves the design. Reading and exploring code
-first is fine; the FIRST edit is not allowed before the graph. This rule is
-not optional and not stack-dependent.
-
-Render every result in Graph Protocol format (see the `graph-protocol` skill).
+will end in proposed code or file edits — you MUST render the graph (in the
+[output format](../../references/output-format.md)) and any clarifying questions BEFORE
+touching any file, and implement only after the user approves the design.
+Reading and exploring code first is fine; the FIRST edit is not allowed
+before the graph. This rule is not optional and not stack-dependent.
 
 ```
-X → DesignGraph<A, E, R>
+X → Graph → Effect<A, E, R>
 │              │   │  │  │
 │              │   │  │  └─ what each node needs     (§5)
 │              │   │  └──── where the graph breaks   (§4)
@@ -48,9 +50,12 @@ X → DesignGraph<A, E, R>
 §7  Behavior     orthogonal layers wrap without changing the graph
 §8  Scope        acquire/release tied to lifecycle
 §9  Test         swap R, same graph shape
-§10 Structure    happy path = A, failure handling = E, never tangled
+§10 Code         happy path body = A, failure join points = E
 ```
 
+`Effect<A, E, R>` names any computation: it succeeds with A, fails with E,
+and needs R to run.
+
 ## 1. Name the shapes
 
 What are the things? Before drawing a graph, define the domain language.
@@ -64,7 +69,7 @@ What are the things? Before drawing a graph, define the domain language.
 These are the nouns. The graph is the verbs. You cannot draw the graph until
 you know what flows through it.
 
-→ *Protocol section: SHAPES.*
+→ *Output section: SHAPES.*
 
 ## 2. Think A first
 
@@ -78,7 +83,7 @@ What is the success data flow? What goes in, what comes out, what transforms
 happen in between? This graph IS your program structure. Draw it first. The
 code follows.
 
-→ *Protocol section: GRAPH (edges) + header tree (A).*
+→ *Output section: GRAPH (edges) + header tree (A).*
 
 ## 3. One or many?
 
@@ -93,7 +98,7 @@ Is each node one-shot or a flow?
 Same three channels (A, E, R) in all cases. Different cardinality. Mark it on
 the graph so the code matches.
 
-→ *Protocol section: CARDINALITY.*
+→ *Output section: CARDINALITY.*
 
 ## 4. Think E second
 
@@ -112,7 +117,7 @@ that as Result types, checked exceptions, error returns, or a strict rule that
 exceptions only cross at layer joins. You decide at each node: retry, escape,
 or propagate. Only `die` when the program's assumptions are violated.
 
-→ *Protocol section: GRAPH (E annotations) + VERDICT.*
+→ *Output section: GRAPH (E annotations) + VERDICT.*
 
 ## 5. Think R third
 
@@ -126,7 +131,7 @@ database connection, a config value, an HTTP client. R shrinks as you provide
 layers. When R is empty, the program can run. If R is not empty, the compiler
 or the wiring tells you exactly what's missing.
 
-→ *Protocol section: GRAPH (R annotations) + TEST LAYERS.*
+→ *Output section: GRAPH (R annotations) + TEST LAYERS.*
 
 ## 6. Trust at boundary
 
@@ -140,7 +145,7 @@ transformer. Define it once, use it everywhere.
 Trust nothing at the boundary. Trust everything inside. The boundary is the
 only place you parse. After that, the types guarantee shape.
 
-→ *Protocol section: BOUNDARIES.*
+→ *Output section: BOUNDARIES.*
 
 ## 7. Layer behavior
 
@@ -153,7 +158,7 @@ without wading through retry logic and timeout configuration. Behavior is
 composed orthogonally. The graph says WHAT happens. The layers say HOW it
 behaves under pressure.
 
-→ *Protocol section: BEHAVIOR.*
+→ *Output section: BEHAVIOR.*
 
 ## 8. Scope resources
 
@@ -164,7 +169,7 @@ Acquire/release must be structurally bound: RAII, `defer`, context managers,
 `try/finally` at the owning node — even on error, even on interrupt. Cleanup
 is structural, not a TODO comment you hope someone remembers.
 
-→ *Protocol section: SCOPE.*
+→ *Output section: SCOPE.*
 
 ## 9. Swap R to prove it
 
@@ -178,9 +183,9 @@ doing too much.
 This is the payoff of separating A, E, and R — you prove the graph correct by
 swapping what's behind R.
 
-→ *Protocol section: TEST LAYERS.*
+→ *Output section: TEST LAYERS.*
 
-## 10. Separate A from E structurally
+## 10. Happy path is A, join points are E
 
 The separation of A (§2) and E (§4) maps directly onto code structure, in any
 language:
@@ -207,7 +212,7 @@ storage errors and produces a domain error. Auth catches domain errors and
 produces an access error. The handler catches access errors and produces the
 declared interface error. Each layer's handling is a complete enumeration of
 what IT received — not what originated three layers down. Consumers never see
-implementation errors from deeper layers. *(See protocol.md for the diagram.)*
+implementation errors from deeper layers. *(See [output-format.md](../../references/output-format.md) for the diagram.)*
 
 ### Divergent strategies
 
@@ -242,6 +247,5 @@ PROBLEM
 
 ---
 
-*The original Effect-TS instantiation of this method ships verbatim in the
-package at `references/effect-ts.md` — for attribution and Effect-TS users
-only. Everything above is stack-agnostic.*
+*For the original Effect-TS instantiation of this method, see
+[effect-ts.md](../../references/effect-ts.md).*