@kidlat-dakila/flightplan 0.0.0-stage → 0.1.5

package/LICENSE.md

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 kidlat-dakila
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+# Flight Plan
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Read a pull request the way its author would explain it, instead of as a list of files.
+
+Flight Plan turns a pull request, or a branch with no pull request, into a guided review. Your coding agent writes a
+review artifact through Flight Plan's MCP tools, and a local web app shows it next to the code it describes. A review
+answers four questions a diff does not: why the change exists, how it runs, what it can affect, and where to look.
+
+The structure of a review comes from the code, not from the agent. Flight Plan reads the syntax trees to work out who
+calls what, so the agent cannot leave a caller out or invent one. The agent writes only the prose.
+
+## Running it
+
+```bash
+npx @kidlat-dakila/flightplan
+```
+
+You can also install it once with `npm install -g @kidlat-dakila/flightplan` and then run `flightplan`. The command
+starts one local server for the web app, the API and the MCP endpoint, and opens it in the browser at
+`http://localhost:24747`.
+
+- If Flight Plan is already running, it only opens the browser.
+- If another program holds the port, Flight Plan takes a free one, keeps it for the next runs and points your agents
+  at it.
+- `--port <number>` sets the port. If that port is taken, Flight Plan stops and says so.
+- `--no-open` leaves the browser closed. `--version` and `--help` print the version and the usage.
+
+Flight Plan needs Node.js 22 or later.
+
+## Setup
+
+The first run opens setup, which has four steps:
+
+1. **Agents**: pick the coding agents you use (Claude Code, Codex, Cursor). Flight Plan installs its review skill, its
+   plugin and its MCP server into the folder of each one.
+2. **Forges**: pick how Flight Plan reaches your pull requests, and choose the default.
+   - Plain `git` reads your checkout and needs no CLI, token or network. It reviews branches, but it cannot list pull
+     requests or show reviewers.
+   - The **GitHub CLI** (`gh`) and the **GitLab CLI** (`glab`) use their own sign-in.
+   - **GitHub**, **GitLab** and **Bitbucket** use a token. GitHub Enterprise, self-managed GitLab and Bitbucket Data
+     Center take a base URL.
+3. **Repositories**: add the repositories to review, and the people whose pull requests you follow in each one.
+4. **Configuration**: choose how the agent writes (see [Configurations](#configurations)).
+
+You can change all of these later in **Settings**. Flight Plan acts on your forge as you, so it sees what you can see.
+
+## Reviewing a pull request
+
+1. Open a repository on the homepage, then pick a pull request or a branch.
+2. Make a review request: choose the configuration, the order of the Code Walkthrough and the agent. Flight Plan can
+   start Claude Code for you. With any other agent, copy the prompt it gives you into your own agent session.
+3. Flight Plan builds the structure of the review from the change, and the page opens it at once. Each part fills in as
+   the agent writes it, and the page shows how much is written.
+4. When the agent finishes, the browser notifies you.
+
+A review artifact has these parts:
+
+- **Context**: why the change exists, in a few sentences to read before any code.
+- **Journey Flow Diagram**: how execution reaches the changed code, from whatever starts it.
+- **Blast Diagram**: the files connected to the change through imports, and what the change does to the ones it did
+  not touch.
+- **Code Walkthrough**: the changed code, one file at a time, with each explanation on the lines it is about and
+  findings (risks, questions, fixes) on the code they concern. It states how many of the changed files it covers.
+
+While you read:
+
+- **Reviewed marks** hide a waypoint or a file until its content changes.
+- **Staleness**: the page says so when the pull request moves past the commit the review describes. **Update the Flight
+  Plan** rebuilds the review at the latest commit and keeps what was written for unchanged code. **Regenerate from
+  scratch** keeps nothing.
+- **Comments**: comment on a line or a range, reply to threads, resolve them, and submit a review with a verdict. All
+  of it goes to the forge.
+- **Chat**: talk to the agent that wrote the review. Select code and choose "Ask the agent" to ask about it. The agent
+  can ask you questions, and when Flight Plan started the agent, it asks your permission for tools here. Code links in
+  its messages open the code.
+
+The codegraph reads TypeScript, JavaScript and JSX, Python and Vue.
+
+## Your own pull requests
+
+A branch with no pull request, or a pull request you wrote, opens on the author's page. There you write the Flight
+Plan yourself or start from an agent draft, and edit its segments, contexts, diagrams and walkthrough. When it is
+complete you can share it:
+
+- **In the pull request description.**
+- **As a Claude artifact**: one page with the whole review and the code it shows, which anyone can read without Flight
+  Plan or the repository. A Claude Code session uploads it. Readers can bring it into their own Flight Plan with
+  **Download to Flight Plan**.
+
+A Flight Plan written for a branch moves to the branch's pull request when you mark it as complete.
+
+## Configurations
+
+A configuration decides how the agent writes: the voice of its prose, how each field is worded, and which sections it
+writes. The structure of a review never changes with the configuration.
+
+| Preset | Written for |
+|---|---|
+| **Standard** | A reviewer who knows the codebase and wants the full review. The default. |
+| **Minimal** | The shortest review that still answers its questions. No diagrams and no findings. |
+| **Onboardee** | A reader new to the codebase. It describes the code around the change. |
+| **Unfamiliar territory** | A reviewer who does not know the language or the libraries. It also describes each library and language name in the code shown. |
+
+Under **Settings → Configurations** you can duplicate a preset, edit its instructions one field at a time, and switch
+sections on or off.
+
+## Agent tools
+
+The MCP endpoint is at `/mcp` on the server's address. Its tools are:
+
+| Tool | What it does |
+|---|---|
+| `get-instructions` | Returns how to write each field, for the configuration the reviewer chose |
+| `read`, `nodes` | Read the review artifact, and list the parts still to be written |
+| `update-nodes` | Write the prose of the parts |
+| `complete` | Mark the review artifact complete, after the checks a finished one must pass |
+| `send-message`, `ask-questions` | Send the reviewer a message, or ask one question or a batch |
+| `record-publication`, `record-import` | Record a Flight Plan published to a Claude artifact, or one fetched from it |
+
+Agents write only prose. They cannot change which nodes, files or lines a review covers.
+
+## Privacy
+
+All data stays on your machine, in `~/.flightplan/`. Set `FLIGHT_PLAN_DATA_DIR` to use another directory. Nothing is
+written into the repositories you review. Nothing is sent anywhere except to your forge, when you comment or submit a
+review, and to a Claude artifact, when you publish one.
+
+The server listens on `localhost` and has no sign-in, so any program on your machine can reach it while it runs.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev
+```
+
+`pnpm dev` runs the backend on `http://localhost:3000` (tRPC at `/api/trpc`, MCP at `POST /mcp`) and the frontend on
+`http://localhost:4200`, which proxies `/api` to the backend.
+
+`pnpm install` also installs a pre-commit hook (husky) that runs ESLint and type-checking for the projects a commit
+touches.
+
+`pnpm build:prod` builds the production bundle and puts together the npm package in `dist/package`. Publish it from
+there with `npm publish`. `pnpm start` runs that build the way the `flightplan` command does, without building it
+first.
+
+Run checks through Nx:
+
+```bash
+nx run-many -t eslint:lint typecheck test -p <projects>
+nx affected -t eslint:lint typecheck test
+nx build <project>
+```
+
+| Folder | Content |
+|---|---|
+| `apps/backend` | The Fastify server: the tRPC API, the MCP endpoint, and the `flightplan` command |
+| `apps/frontend` | The React web app |
+| `packages/ui` | Shared components |
+| `packages/configurations` | The shape of a review artifact, its field instructions and the presets |
+| `packages/codegraph` | Traces a change through the code and builds the diagrams and the Code Walkthrough |
+| `packages/git-forge` | The adapters for plain git, GitHub, GitLab and Bitbucket |
+| `plugin` | The Claude Code plugin with the review skill |
+| `tools/npm-package` | Puts together the npm package |
+| `tools/playground-fixtures` | The codegraph's end-to-end cases |
+
+[AGENTS.md](AGENTS.md) holds the rules for working in this repository, and [docs/vocabulary](docs/vocabulary/README.md)
+defines the terms Flight Plan uses.
+
+## License
+
+Flight Plan is licensed under the [Functional Source License, Version 1.1, ALv2 Future License](LICENSE.md)
+(FSL-1.1-ALv2). You may use, change and share it for any purpose except offering it, or something built from it, as
+a commercial product or service that competes with Flight Plan. Two years after each version is released, that version
+is also available under the Apache License, Version 2.0.

package/backend/configurations/default-configurations/minimal/blast.nodes.impactReason.md

@@ -0,0 +1,7 @@
+One or two fragments a reviewer can check against the code.
+
+- `breaks`: what fails, and the case the author did not account for.
+- `behaviour-changes`: what differs now, for whom.
+
+Name the place, link it: "renders units left. Negative number when holds exceed
+stock." Do not restate the impact type. None on an unaffected file.

package/backend/configurations/default-configurations/minimal/blast.nodes.impactType.behaviour-changes.md

@@ -0,0 +1 @@
+Still works. Now does something different the change does not mention.

package/backend/configurations/default-configurations/minimal/blast.nodes.impactType.breaks.md

@@ -0,0 +1 @@
+Logic no longer holds against changed code. Compiler does not say so.

package/backend/configurations/default-configurations/minimal/blast.nodes.impactType.md

@@ -0,0 +1,10 @@
+What the change does to this file. Meaning of each value: given with its option.
+
+Judge logic, not types. Call that no longer type-checks: the compiler's to
+report, never the reason for a value here.
+
+Nobody assessed the file: leave unset. No `unknown`. File of the change: no
+impact type.
+
+`breaks` and `behaviour-changes`: always with `impactReason`, same call.
+`unaffected`: alone, no reason.

package/backend/configurations/default-configurations/minimal/blast.nodes.impactType.unaffected.md

@@ -0,0 +1 @@
+Change reaches it. Nothing it does is different.

package/backend/configurations/default-configurations/minimal/context.md

@@ -0,0 +1,58 @@
+Three parts, this order: opening paragraph, `## Overview`, `## Implementation`.
+
+```markdown
+Basket with item sold out a minute ago still reached payment. Shopper now told
+of every such item before paying.
+
+## Overview
+
+- **When** customer submits basket with two lines out of stock, **then**
+  [error names both lines](code:src/stock/check.ts#hasStock).
+- **When** every line in stock, **then** nothing changes.
+
+## Implementation
+
+**`src/stock/`**
+
+- Modified [`hasStock()`](code:src/stock/check.ts#hasStock): reads every level
+  once, collects every short line.
+```
+
+**Verify every claim against the diff.** Never against the pull request's own
+description.
+
+### Opening paragraph
+
+Why anyone should care. Reader has not seen the code.
+
+**No identifiers, no paths, no links here.** Cannot write it without a symbol:
+you describe implementation, not the change. Say what the reader would see: not
+"size check handles oversized query" but "query over 1 MB now gets error naming
+1 MB limit".
+
+Three fragments at most, even for a large change.
+
+### Overview
+
+What changes from outside the code. List of scenarios. One line each: bold
+**When**, situation, bold **then**, what can be observed.
+
+- **Situation**: reader's terms, one clause. What a person outside the code
+  does, or the state that holds. Not the code path.
+- **Observed**: result a person or another system sees. Not mechanism. Link the
+  code the result comes from.
+- **"nothing changes"**: where a reader would expect a change and there is
+  none. No link.
+
+### Implementation
+
+What changed inside the code, grouped by where it lives. Each group: bold label
+on its own line, then list.
+
+- **Label**: file, or directory when several files inside change. No verb. Group
+  by place, not theme. Groups in the order the tour walks them.
+- **Item**: one change a reader would notice. Verb first, then the code:
+  "Modified `hasStock()`: reads every level once, collects every short line."
+  Link the code.
+- Item naming no code: only for a configuration value, a deleted file, the
+  tests. No link.

package/backend/configurations/default-configurations/minimal/journey.description.md

@@ -0,0 +1,16 @@
+The diagram as text: what a reader knows after following every line of it. Three
+fragments at most. Fewer for a small diagram.
+
+- **Start where paths start.** What sets each path off, reader's terms: "Shopper
+  places order", "Nightly job runs".
+- **Follow each path in drawn order**, left to the changed code. Name steps by
+  what they do: `<Checkout />` calls `placeOrder()`, asks `stockOf()` per cart
+  line.
+- **Say where paths reach the change.** Name the nodes the change touched and
+  how the path arrives. Do not explain the change.
+- **Several paths**: how many, where they meet, one fragment each. Paths that
+  run alike: tell together.
+
+Whole diagram, not one path. No "This diagram shows". Do not count nodes.
+
+`Shopper places order: <Checkout /> calls placeOrder(), asks stockOf() per cart line before charge. Stock badge reaches stockOf() through useStockLevel(). Both end at stockOf(), now subtracts held units.`

package/backend/configurations/default-configurations/minimal/journey.nodes.blockLabels.label.md

@@ -0,0 +1,13 @@
+What this row of the node is for, as a reader of the product: "Promo code
+shopper typed", "Sends order to API". Read the node's code first: label says
+what the block holds or does, not what it is called.
+
+- **Argument or state**: what the value holds: `Cart lines`, not `items`.
+- **Hook**: what it gives the node: `Mutation that applies promo code`.
+- **Effect**: what it does, when: `Clears form after save`.
+- **Call**: what is asked of the code it calls: `Saves renamed user`.
+- **Step**: what the step does: `Returns error for empty title`. Condition: what
+  is checked. Step standing for several statements: what they do together.
+
+No name of the code: row shows it under your label. Same shape and tense on
+every block label of one node.

package/backend/configurations/default-configurations/minimal/journey.nodes.description.md

@@ -0,0 +1,13 @@
+The journey that reaches this node, in drawn order: "{who} {action}: {caller}
+{calls, renders or reads} this {what}." Start with what starts the path, name
+each step between, end on what hands over to it.
+
+`Shopper opens /orders: <OrdersPage /> calls useOrders(status). useOrders() passes this function to useQuery as query function.`
+
+- **Several paths**: one line saying so, then list, one such fragment per path.
+- **Node with trigger labels**: what each event runs and what each fetch feeds,
+  in the words of its trigger label: `Shopper clicks "All": handler calls setStatus(null) on filter store.`
+- **Nothing reaches it yet**: say no code uses it, and what is meant to.
+
+Do not describe the change here: the waypoint does. Do not restate label or
+identifier. Link a step to its code where a reader would open it.

package/backend/configurations/default-configurations/minimal/journey.nodes.label.md

@@ -0,0 +1,10 @@
+What this step does, to what: "Throws when line out of stock". Not "The stock
+check". Never the identifier: node already shows the name of its code. Same
+shape and tense on every node of one diagram. Six words at most.
+
+Component drawn inside another: do not repeat the outer component.
+
+Node of an event, effect, callback, router procedure, store action: read beside
+the node around it. Say what this unit does on its own: "Applies code on form
+submit", "Stores promo on request success". Event has a trigger label for what
+the user does: node says what the handler does.

package/backend/configurations/default-configurations/minimal/journey.nodes.triggerLabels.label.md

@@ -0,0 +1,10 @@
+What happens at this place, as a reader of the product: "Shopper clicks Remove",
+"Account orders loaded". Read the node's code first: label names the element the
+user acts on, or the data fetched.
+
+- **Event**: who acts, the action, what it is on: `Shopper clicks "All"`. No
+  component name, no handler name.
+- **Data fetch**: what is loaded, not how: `Product stock loaded`, not
+  `useQuery runs`.
+
+Same shape and tense on every trigger label of one diagram.

package/backend/configurations/default-configurations/minimal/walkthrough.files.title.md

@@ -0,0 +1,7 @@
+What reviewer is shown in this file, one line: "Rounding moves to subtotal",
+"Stock check now counts held units". It is the file's label on the section rail:
+must tell this file from the others in the change.
+
+Never the path. Never a list of its waypoints.
+
+Present tense, about the code. Six words at most.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.kind.bug.md

@@ -0,0 +1 @@
+Broken behaviour that causes an incident. Proven. Not proven: a `risk`.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.kind.md

@@ -0,0 +1,6 @@
+### Kind
+
+Exactly one kind. Each a different answer, not a different intensity. Meaning of
+each kind: given with its option.
+
+Order a waypoint's findings most severe first: `bug`, `risk`, `nit`, `question`.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.kind.nit.md

@@ -0,0 +1,2 @@
+Anything the author may decline: style, naming, micro-optimisation, every
+improvement. All optional.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.kind.question.md

@@ -0,0 +1,2 @@
+You are not sure. Genuine question, not a suggestion in disguise. No trace, no
+solution.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.kind.risk.md

@@ -0,0 +1,3 @@
+Works but fragile (race, missing null check, swallowed error). Or looks broken
+and you could not demonstrate it. Unsafe path that looks reachable, nobody saw
+it fire.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.md

@@ -0,0 +1,21 @@
+What is wrong with the code this waypoint shows, on the waypoint itself.
+
+**Only what your reading of the code found.** Finding inferred from the diff
+without opening the file: a guess. Verify against the repository, files the
+change never touched too. A check three files away may already cover the case.
+
+**Pick the kind honestly.** `bug`: wrong now. `risk`: goes wrong under
+conditions you can name. `nit`: worth saying, not worth blocking. `question`:
+you do not know. No trace, no fix on a `question`.
+
+Title: what is wrong, one line. Reading: why. Trace: steps that prove it.
+`code:` links throughout: every claim resolves to lines.
+
+**Every `bug`, `risk`, `nit` gets a `solution`**: the lines as they should be.
+String of code replacing the lines this waypoint covers. No path, no position.
+Lines whole: a line left out is a line the fix deletes. Fix needs more than
+these lines: write the part that belongs here, name the other lines in the
+reading.
+
+Card shows one chip, its highest kind. Nit beside a bug is easy to miss: report
+the nit where it belongs.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.reading.md

@@ -0,0 +1,15 @@
+### Reading
+
+The defect, one linked claim per fragment: what code does, why that is wrong.
+Every claim links the exact lines it rests on. Present tense. Three fragments at
+most.
+
+> [`annotateRanges()`](code:src/prose/annotate.ts#L22-31) maps first range only.
+> Later ranges: `undefined`. Panel shows no line numbers.
+
+No hedge. `risk` reported because a suspected bug is not proven: one fragment
+saying what stopped you.
+
+**Improvement says three things**: what code does now and its limit, stated as
+working. Better alternative, exact imported symbol. Why better: fewer lines,
+fewer states, one fewer round trip. Never "cleaner".

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.solution.md

@@ -0,0 +1,10 @@
+### Solution
+
+Every `bug`, `risk`, `nit` carries a solution. A `question` carries none.
+
+The lines as they should be, whole, with the indentation they have in the file.
+Never shortened: code is not prose. Solution replaces every line the finding's
+waypoint covers: a line left out is a line the fix deletes.
+
+Fix needs more than these lines: write the part that belongs to these lines.
+Name the other lines that must change in the reading, with `code:` links.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.title.md

@@ -0,0 +1,5 @@
+### Title
+
+Code, and what it does wrong: "`annotateRanges` drops line mapping for whole
+block". Not "Prose loses its line numbers". Not "A subtle indexing problem".
+Title that fits another finding is not a title. Eight words at most.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.findings.trace.md

@@ -0,0 +1,10 @@
+### Trace
+
+Steps that prove the finding, in the order code runs.
+
+**First step: the trigger.** Action and what makes it fire: parameter, state,
+condition. "Reader selects a sentence", not "selection happens". `POST /orders`
+with `quantity: 0`, not `POST /orders`. User action: no link.
+
+**Every later step: a debugger step**, linked to its place in the code. Proof
+only: no impact, no evidence, no proposal. No trace on a `nit` or a `question`.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.needsAttention.md

@@ -0,0 +1,26 @@
+Mark the few waypoints that carry the change. One or two fragments: why this is
+where the pull request does its work. Leave the field off every other waypoint.
+
+Points at importance. Not a warning.
+
+**Flag where behaviour changes**: new rule, decision code now makes differently,
+data that now goes somewhere new, contract a caller now depends on.
+
+**Leave off the plumbing**: value passed along, constant, comment, formatting,
+styling, type-only edit, rename, test that restates code.
+
+**Not a bug report.** Something wrong or fragile: a finding, on the same card.
+Finding is never the reason for the flag. Only fragment you can write is about
+what might break: write a finding, leave this off.
+
+**Say why the card is central, against what the pull request is for.** "Rule
+the pull request exists for: order now holds stock before card is charged. Other
+cards in this file wire it in." Not "check this carefully", "core logic", "this
+is complex".
+
+**Keep it rare.** One to three in a pull request. Seldom more than one in a
+file. Every card would carry it: none should.
+
+Not a second reading. Reading: what code does. This: why it is the part to read.
+
+Name code with `code:` links.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.reading.md

@@ -0,0 +1,59 @@
+What was done here, and why it matters to the pull request.
+
+**Open: fragments, fixed order.** Verb + kind of code + name. Then effect. No
+"The author".
+
+> Modified `validateQuantity()` condition. `false` over 10, was 20.
+> [`<BasketForm />`](code:src/checkout/BasketForm.tsx#L40-52) calls before
+> submit. 11 to 20 no longer submits.
+
+- **Verb**: one, past tense: _added_, _implemented_, _modified_, _removed_,
+  _moved_, _replaced_.
+- **Kind of code**: plain word from panel: function, method, condition,
+  validation, query, loop, type, component, constant, test. Then its name. Not
+  guard, gate, hook, wiring.
+- **Effect**: what differs now, values named: `false` over 10, was 20. From a
+  throw to a returned reason. Not mechanism.
+- **Operation, not judgement**: returns `false`, throws `RangeError`, returns a
+  400, skips the line. Not _refuses_, _rejects_, _accepts_, _allows_, _blocks_,
+  _protects_.
+
+**Author did the change, code does the rest.** After the opening, code is the
+subject: "`validateQuantity()` returns".
+
+**Several effects: list them.** Opening fragment, colon, one item per effect, in
+the order code does them. No chain of _and_, _then_, commas.
+
+> Added function `reserveStock()`:
+>
+> - one query, stock level of every basket line
+> - one hold per line, lapses after 15 minutes
+> - returns holds. [`placeOrder()`](code:src/checkout/placeOrder.ts#L13-27)
+>   releases them on failed charge
+
+**Do not walk the lines.** Panel shows them. Leave out how code reaches its
+effect, unless that detail is the change.
+
+**End with what it is for.** One fragment tying this piece to the purpose
+`context` states: the consumer and what changes for it. Reviewer reading only
+this card must know why it is in the pull request. Cause not clear from order of
+fragments: write _so_ or _because_.
+
+**Consumer from the Blast Diagram, not a guess.** Where the artifact has one,
+`blast` lists files importing this card's file, with `impactType` and
+`impactReason`. Name the one this card exists for. Link it. Nothing outside the
+change reaches this code: name what inside the pull request uses it. Neither
+shows a reason: say what the change does to its consumer, stop. Never invent the
+author's reason.
+
+**Link code outside the card. Name code inside it.** Card's own identifiers:
+backticks, no link. Everything else mentioned: link, every mention. Link
+resolves only inside files the artifact holds, see `codeLinks`. Code in any
+other file: backticks, with its path.
+
+**Body's reading** (waypoint with children): what was done across the whole
+body. Opening, list of five items at most, one fragment of purpose. **Block's
+reading** (a child): opening about its one block, list only when the block does
+several things, purpose points at its body or its consumer.
+
+**Do not restate the title.** Reading adds values, reason, what it connects to.

package/backend/configurations/default-configurations/minimal/walkthrough.files.waypoints.title.md

@@ -0,0 +1,11 @@
+**What was done, to what.** "Modified file reader to return reason for binary
+content", "Returns null for path outside root". Not a bare noun: "The file
+reader" names which code, not why the reader is shown it.
+
+**Past tense**: Added, Modified, Removed. Never the identifier alone.
+
+**One title, one thing.** Arrow, "and" or three clauses: several waypoints
+crammed into one.
+
+**Child's title: smaller change than its parent's.** Same shape, same tense,
+every level.

package/backend/configurations/default-configurations/minimal/walkthrough.intro.md

@@ -0,0 +1,4 @@
+One optional line framing the whole Code Walkthrough: order files are read in,
+and why. "Stock check first, then query it calls."
+
+Names the tour, not the first file. Leave out when file order speaks for itself.