@kidlat-dakila/flightplan 0.1.5 → 0.1.7

package/README.md

@@ -1,21 +1,29 @@
 # Flight Plan
 
-Read a pull request the way its author would explain it, instead of as a list of files.
+[![CI](https://github.com/kidlat-dakila/flight-plan/actions/workflows/ci.yml/badge.svg)](https://github.com/kidlat-dakila/flight-plan/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/kidlat-dakila/flight-plan/actions/workflows/codeql.yml/badge.svg)](https://github.com/kidlat-dakila/flight-plan/actions/workflows/codeql.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kidlat-dakila/flight-plan/badge)](https://scorecard.dev/viewer/?uri=github.com/kidlat-dakila/flight-plan)
+[![Socket](https://socket.dev/api/badge/npm/package/@kidlat-dakila/flightplan)](https://socket.dev/npm/package/@kidlat-dakila/flightplan)
 
-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.
+An offline-first code review tool that helps you understand and navigate the changes in a pull request.
 
-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.
+Flight Plan reads the code of a pull request, or of a branch with no pull request, and lays the change out as a guided
+review in a local web app, next to the code it describes. It shows how the change runs, what it can affect, and where to
+look. It works from your local git checkout, and connects to GitHub, GitLab or Bitbucket for their pull requests,
+comments and reviews.
+
+Flight Plan builds the review from the code itself, with no model involved. It reads the syntax trees to work out who
+calls what, then draws the diagrams and lays out the walkthrough from them. A coding agent can fill in the prose through
+Flight Plan's MCP tools: why the change exists, the labels, the explanations and the findings. It writes only that
+prose, so it cannot leave a caller out or invent one.
 
 ## Running it
 
 ```bash
-npx @kidlat-dakila/flightplan
+npx @kidlat-dakila/flightplan@latest
 ```
 
-You can also install it once with `npm install -g @kidlat-dakila/flightplan` and then run `flightplan`. The command
+You can also install it once with `npm install -g @kidlat-dakila/flightplan@latest` 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`.
 
@@ -49,14 +57,14 @@ You can change all of these later in **Settings**. Flight Plan acts on your forg
 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.
+3. Flight Plan builds the review from the change, and the page opens it at once, ready to read. The prose of 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.
+- **Trace 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
@@ -134,15 +142,22 @@ 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 dev` runs the backend on `http://localhost:3000` (tRPC at `/api/trpc`, MCP at `POST /mcp`), the frontend on
+`http://localhost:4200`, which proxies `/api` to the backend, and the site on `http://localhost:4400`.
 
 `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.
+`pnpm build:prod` builds the production bundle and puts together the npm package in `dist/package`. `pnpm start` runs
+that build the way the `flightplan` command does, without building it first.
+
+To release, bump `version` in `package.json`, then build the package and publish it to npm from your machine:
+
+```bash
+pnpm prod:release
+```
+
+It publishes the version that `package.json` holds, so log in with `npm login` first.
 
 Run checks through Nx:
 

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

@@ -1,58 +1,13 @@
-Three parts, this order: opening paragraph, `## Overview`, `## Implementation`.
+One or two sentences starting "This segment": what the segment's change does.
+Nothing else. Flight Plan lists what the segment adds, modifies and removes in
+the Change Overview under it: no list, no accordion, no code links.
 
 ```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.
+This segment checks stock of every basket line before payment. A basket with an
+item sold out a minute ago gets an error naming each one.
 ```
 
-**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.
+- Check every claim against the diff, never the pull request's description.
+- Say what someone would see. No identifiers, paths or links.
+- This segment's files only. With segments off, the first segment's context is
+  the whole change's: start "This change".

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

@@ -0,0 +1,19 @@
+What this row of the node does, as a reader of the product: a verb first,
+present tense: "Queries every Pokemon ordered by name", "Sends order to API".
+Read the node's code first: label says what the block does, not what it is or
+what it is called. "Queries every Pokemon ordered by name", not "Query of every
+Pokemon".
+
+- **Argument**: what the node does with it: `Filters Pokemon by this trainer`,
+  not `Trainer to filter by`.
+- **State**: what the node keeps in it: `Keeps cart lines`, not `Cart lines`.
+- **Hook**: what the node gets from it: `Gets 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`.
+- **Value**: what the code that makes it does: `Queries every Pokemon ordered by
+  name`.
+- **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: each starts with a verb.

package/backend/configurations/default-configurations/minimal/{journey.nodes.description.md → traceDiagram.nodes.description.md}

@@ -1,4 +1,4 @@
-The journey that reaches this node, in drawn order: "{who} {action}: {caller}
+The trace 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.
 

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

@@ -40,7 +40,7 @@ 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
+`blastDiagram` 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

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

@@ -1,70 +1,24 @@
-Write three parts, in this order: an opening paragraph, then `## Overview`, then
-`## Implementation`.
+Write one or two sentences that start with "This segment" and say what the
+segment's change does. That is the whole context. Flight Plan lists every piece
+of code the segment adds, modifies and removes under it, in the Change Overview,
+so the context holds no list of changes, no accordion and no code links.
 
 ```markdown
-A basket with an item that sold out a minute ago could still reach payment. The
-shopper now hears about every such item before paying.
-
-## Overview
-
-- **When** a customer submits a basket with two lines out of stock, **then**
-  [the error names both lines](code:src/stock/check.ts#hasStock).
-- **When** every line is in stock, **then** nothing changes.
-
-## Implementation
-
-**`src/stock/`**
-
-- Modified [`hasStock()`](code:src/stock/check.ts#hasStock) to read every level
-  once and collect every short line.
+This segment checks the stock of every basket line before payment, so a basket
+with an item that sold out a minute ago gets an error naming each sold-out item
+and never reaches payment.
 ```
 
-**Verify every claim against the diff**, never against a pull request's own
+Check every claim against the diff, never against the pull request's own
 description.
 
-### The opening paragraph
-
-Say why anyone should care, to a reader who has not seen the code.
-
-**This paragraph bans identifiers, paths and links.** If you cannot write it
-without naming a symbol, you are describing the implementation rather than the
-change. That ban is what makes it the easiest place to hide a vague verb, so say
-what the reader would see: not "the size check handles an oversized query" but
-"a query over 1 MB now gets an error that names the 1 MB limit".
-
-Five sentences, and no more even when the change is large.
-
-### Overview
-
-What changes from outside the code, as a list of scenarios. Each item is one
-sentence: a bold **When**, the situation, a bold **then**, what can be observed.
-
-The situation is in the reader's terms — one clause. Name what a person outside
-the code does, or the state that holds: "a customer submits a basket with two
-lines out of stock", "every line is in stock". Write the situation, not the code
-path that answers it.
-
-What can be observed is the result a person or another system sees, not the
-mechanism: "the error message names both out-of-stock lines". Link the code the
-result comes from where there is code to name.
-
-Say "nothing changes" when a reader would reasonably expect a change and there
-is none; that line stops a reviewer hunting for a regression that is not there.
-A "nothing changes" scenario carries no link.
-
-### Implementation
-
-What changed inside the code, grouped by where it lives. Each group is a bold
-label on its own line, then a list of the changes there.
-
-The label is the place the changes live — a file, or a directory when several
-inside it are touched. It takes no verb. Group by where the code lives, not by
-theme, and put the groups in the order the tour walks them.
+### What the sentences say
 
-Each item is one change a reader would notice, as one sentence: the verb first,
-then the code it names. "Modified `hasStock()` to read every level once and
-collect every short line." Link the code the claim is about.
+Say what the segment's change does for a reader who has not seen the code. Name
+no identifiers, paths or links. Say what someone would see: "a query over 1 MB
+now gets an error that names the limit" tells the reader more than "the size
+check handles large queries".
 
-An item that names no code is usually one that has not been thought through. The
-exceptions are rare — a configuration value, a deleted file, the tests — and
-they carry no link.
+Write about the files of this segment only. When the reviewer turned segments
+off, the first segment's context is the one Context of the whole change: start
+it with "This change" and say what the whole change does.

package/backend/configurations/default-configurations/onboardee/traceDiagram.description.md

@@ -0,0 +1,16 @@
+Write a caption for the diagram: what the reader is looking at, before they follow its lines. Two sentences at most.
+
+- **The first sentence says what the diagram starts from.** Open with "This diagram shows how", name the page, the component, the job or the route the paths start at, and say what it does when it opens, loads or runs: `This diagram shows how the edit page loads an order and renders it in the form.` Use the verb of the code for what it does, such as renders, loads or requests, so that "shows" is not written twice.
+- **The second sentence follows the user's actions.** The actions are the events on the diagram: a submit, a click, a pick, a typed value. Open with "It also shows what happens when the user", name the action as the user would, then say where its data ends up: the request it sends, the store it writes, the page it opens. `It also shows what happens when the user saves the order, and how the changed order reaches the API through updateOrder().`
+- **Several actions.** Name them together, in the order the diagram draws them: `It also shows what happens when the user picks a customer, picks a product, types a quantity or submits the form.`
+- **A path nobody clicks.** A request, a schedule or another system starts it: name that in place of the user. `It also shows what happens when a request reaches POST /orders, and how the order reaches the database.`
+- **No action on the diagram.** Leave the second sentence out, and never write "It also shows" with nothing after it.
+- **Shared code that other segments call.** Say what the diagram holds and what reaches it: `This diagram shows how the route table opens the order pages, and how each hook loads or sends orders through its request.`
+
+Name where the data ends up, not the steps on the way: the labels and the descriptions of the nodes carry the steps, and the reader follows them on the board. Do not explain the change: the Context Section and the waypoints do.
+
+| The diagram | Its caption |
+|---|---|
+| A page that loads a record and saves it | This diagram shows how the edit page loads an order and renders it in the form. It also shows what happens when the user saves the order, and how the changed order reaches the API through `updateOrder()`. |
+| A page that creates a record | This diagram shows how the create page opens with an empty draft in the form. It also shows what happens when the user submits the form, and how the new order reaches the API through `createOrder()`. |
+| A page with no action on its paths | This diagram shows how the orders list loads the orders and renders them in a table. |

package/backend/configurations/default-configurations/onboardee/traceDiagram.nodes.blockLabels.label.md

@@ -0,0 +1,11 @@
+Say what this row of the node does, as a reader of the product would. Start with a verb in the present tense: "Queries every Pokemon ordered by name", "Sends the order to the API". Read the code of the node first, so the label says what the block does, not what it is or what it is called: "Queries every Pokemon ordered by name", not "The query of every Pokemon".
+
+- **An argument.** Say what the node does with the value it is given: `Filters the Pokemon by this trainer`, not `The trainer to filter by`.
+- **A state.** Say what the node keeps in it: `Keeps the lines of the cart`, not `The lines of the cart`.
+- **A hook.** Say what the node gets from it: `Gets the mutation that applies a promo code`.
+- **An effect.** Say what it does and when: `Clears the form after a save`.
+- **A call.** Say what is asked of the code it calls: `Saves the renamed user`.
+- **A value.** Say what the code that makes it does: `Queries every Pokemon ordered by name`, not `The query of every Pokemon`.
+- **A step.** Say what the step does: `Returns an error for an empty title`. For a condition, say what is checked: `Checks whether a trainer is given`. A step can stand for several statements that follow each other, listed by the first: say what they do together, `Renames the chosen user`.
+
+Leave the name of the code out: the row shows it under your label. Keep the same shape and tense on every block label of one node: each one starts with a verb.

package/backend/configurations/default-configurations/onboardee/{journey.nodes.description.md → traceDiagram.nodes.description.md}

@@ -1,4 +1,4 @@
-Tell the journey that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
+Tell the trace that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
 
 - **Several paths.** A node that more than one path reaches opens with one line that says so, then a list with one such sentence per path.
 - **A node with trigger labels.** Say what each event runs and what each fetch feeds, in the words of its trigger label: `When a shopper clicks "All", the handler calls setStatus(null) on the filter store.`

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

@@ -43,7 +43,7 @@ sort order, the option merge, the loop — unless that detail is the change itse
 change to the purpose `context` states, usually with _so that_ or _because_. A reviewer who reads
 only this card should know why it is in the pull request.
 
-**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blast` lists the files
+**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blastDiagram` lists the files
 that import the file this card is in, and what the change does to each: its `impactType` and its `impactReason`. Name the one this card exists
 for — the form that no longer submits, the route that now returns something else, the caller that now
 depends on the new value — and link it. Where nothing outside the change reaches this code, name

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

@@ -1,70 +1,24 @@
-Write three parts, in this order: an opening paragraph, then `## Overview`, then
-`## Implementation`.
+Write one or two sentences that start with "This segment" and say what the
+segment's change does. That is the whole context. Flight Plan lists every piece
+of code the segment adds, modifies and removes under it, in the Change Overview,
+so the context holds no list of changes, no accordion and no code links.
 
 ```markdown
-A basket with an item that sold out a minute ago could still reach payment. The
-shopper now hears about every such item before paying.
-
-## Overview
-
-- **When** a customer submits a basket with two lines out of stock, **then**
-  [the error names both lines](code:src/stock/check.ts#hasStock).
-- **When** every line is in stock, **then** nothing changes.
-
-## Implementation
-
-**`src/stock/`**
-
-- Modified [`hasStock()`](code:src/stock/check.ts#hasStock) to read every level
-  once and collect every short line.
+This segment checks the stock of every basket line before payment, so a basket
+with an item that sold out a minute ago gets an error naming each sold-out item
+and never reaches payment.
 ```
 
-**Verify every claim against the diff**, never against a pull request's own
+Check every claim against the diff, never against the pull request's own
 description.
 
-### The opening paragraph
-
-Say why anyone should care, to a reader who has not seen the code.
-
-**This paragraph bans identifiers, paths and links.** If you cannot write it
-without naming a symbol, you are describing the implementation rather than the
-change. That ban is what makes it the easiest place to hide a vague verb, so say
-what the reader would see: not "the size check handles an oversized query" but
-"a query over 1 MB now gets an error that names the 1 MB limit".
-
-Five sentences, and no more even when the change is large.
-
-### Overview
-
-What changes from outside the code, as a list of scenarios. Each item is one
-sentence: a bold **When**, the situation, a bold **then**, what can be observed.
-
-The situation is in the reader's terms — one clause. Name what a person outside
-the code does, or the state that holds: "a customer submits a basket with two
-lines out of stock", "every line is in stock". Write the situation, not the code
-path that answers it.
-
-What can be observed is the result a person or another system sees, not the
-mechanism: "the error message names both out-of-stock lines". Link the code the
-result comes from where there is code to name.
-
-Say "nothing changes" when a reader would reasonably expect a change and there
-is none; that line stops a reviewer hunting for a regression that is not there.
-A "nothing changes" scenario carries no link.
-
-### Implementation
-
-What changed inside the code, grouped by where it lives. Each group is a bold
-label on its own line, then a list of the changes there.
-
-The label is the place the changes live — a file, or a directory when several
-inside it are touched. It takes no verb. Group by where the code lives, not by
-theme, and put the groups in the order the tour walks them.
+### What the sentences say
 
-Each item is one change a reader would notice, as one sentence: the verb first,
-then the code it names. "Modified `hasStock()` to read every level once and
-collect every short line." Link the code the claim is about.
+Say what the segment's change does for a reader who has not seen the code. Name
+no identifiers, paths or links. Say what someone would see: "a query over 1 MB
+now gets an error that names the limit" tells the reader more than "the size
+check handles large queries".
 
-An item that names no code is usually one that has not been thought through. The
-exceptions are rare — a configuration value, a deleted file, the tests — and
-they carry no link.
+Write about the files of this segment only. When the reviewer turned segments
+off, the first segment's context is the one Context of the whole change: start
+it with "This change" and say what the whole change does.

package/backend/configurations/default-configurations/standard/traceDiagram.description.md

@@ -0,0 +1,16 @@
+Write a caption for the diagram: what the reader is looking at, before they follow its lines. Two sentences at most.
+
+- **The first sentence says what the diagram starts from.** Open with "This diagram shows how", name the page, the component, the job or the route the paths start at, and say what it does when it opens, loads or runs: `This diagram shows how the edit page loads an order and renders it in the form.` Use the verb of the code for what it does, such as renders, loads or requests, so that "shows" is not written twice.
+- **The second sentence follows the user's actions.** The actions are the events on the diagram: a submit, a click, a pick, a typed value. Open with "It also shows what happens when the user", name the action as the user would, then say where its data ends up: the request it sends, the store it writes, the page it opens. `It also shows what happens when the user saves the order, and how the changed order reaches the API through updateOrder().`
+- **Several actions.** Name them together, in the order the diagram draws them: `It also shows what happens when the user picks a customer, picks a product, types a quantity or submits the form.`
+- **A path nobody clicks.** A request, a schedule or another system starts it: name that in place of the user. `It also shows what happens when a request reaches POST /orders, and how the order reaches the database.`
+- **No action on the diagram.** Leave the second sentence out, and never write "It also shows" with nothing after it.
+- **Shared code that other segments call.** Say what the diagram holds and what reaches it: `This diagram shows how the route table opens the order pages, and how each hook loads or sends orders through its request.`
+
+Name where the data ends up, not the steps on the way: the labels and the descriptions of the nodes carry the steps, and the reader follows them on the board. Do not explain the change: the Context Section and the waypoints do.
+
+| The diagram | Its caption |
+|---|---|
+| A page that loads a record and saves it | This diagram shows how the edit page loads an order and renders it in the form. It also shows what happens when the user saves the order, and how the changed order reaches the API through `updateOrder()`. |
+| A page that creates a record | This diagram shows how the create page opens with an empty draft in the form. It also shows what happens when the user submits the form, and how the new order reaches the API through `createOrder()`. |
+| A page with no action on its paths | This diagram shows how the orders list loads the orders and renders them in a table. |

package/backend/configurations/default-configurations/standard/traceDiagram.nodes.blockLabels.label.md

@@ -0,0 +1,11 @@
+Say what this row of the node does, as a reader of the product would. Start with a verb in the present tense: "Queries every Pokemon ordered by name", "Sends the order to the API". Read the code of the node first, so the label says what the block does, not what it is or what it is called: "Queries every Pokemon ordered by name", not "The query of every Pokemon".
+
+- **An argument.** Say what the node does with the value it is given: `Filters the Pokemon by this trainer`, not `The trainer to filter by`.
+- **A state.** Say what the node keeps in it: `Keeps the lines of the cart`, not `The lines of the cart`.
+- **A hook.** Say what the node gets from it: `Gets the mutation that applies a promo code`.
+- **An effect.** Say what it does and when: `Clears the form after a save`.
+- **A call.** Say what is asked of the code it calls: `Saves the renamed user`.
+- **A value.** Say what the code that makes it does: `Queries every Pokemon ordered by name`, not `The query of every Pokemon`.
+- **A step.** Say what the step does: `Returns an error for an empty title`. For a condition, say what is checked: `Checks whether a trainer is given`. A step can stand for several statements that follow each other, listed by the first: say what they do together, `Renames the chosen user`.
+
+Leave the name of the code out: the row shows it under your label. Keep the same shape and tense on every block label of one node: each one starts with a verb.

package/backend/configurations/default-configurations/standard/{journey.nodes.description.md → traceDiagram.nodes.description.md}

@@ -1,4 +1,4 @@
-Tell the journey that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
+Tell the trace that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
 
 - **Several paths.** A node that more than one path reaches opens with one line that says so, then a list with one such sentence per path.
 - **A node with trigger labels.** Say what each event runs and what each fetch feeds, in the words of its trigger label: `When a shopper clicks "All", the handler calls setStatus(null) on the filter store.`

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

@@ -43,7 +43,7 @@ sort order, the option merge, the loop — unless that detail is the change itse
 change to the purpose `context` states, usually with _so that_ or _because_. A reviewer who reads
 only this card should know why it is in the pull request.
 
-**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blast` lists the files
+**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blastDiagram` lists the files
 that import the file this card is in, and what the change does to each: its `impactType` and its `impactReason`. Name the one this card exists
 for — the form that no longer submits, the route that now returns something else, the caller that now
 depends on the new value — and link it. Where nothing outside the change reaches this code, name

package/backend/configurations/default-configurations/unfamiliar-territory/context.md

@@ -1,70 +1,24 @@
-Write three parts, in this order: an opening paragraph, then `## Overview`, then
-`## Implementation`.
+Write one or two sentences that start with "This segment" and say what the
+segment's change does. That is the whole context. Flight Plan lists every piece
+of code the segment adds, modifies and removes under it, in the Change Overview,
+so the context holds no list of changes, no accordion and no code links.
 
 ```markdown
-A basket with an item that sold out a minute ago could still reach payment. The
-shopper now hears about every such item before paying.
-
-## Overview
-
-- **When** a customer submits a basket with two lines out of stock, **then**
-  [the error names both lines](code:src/stock/check.ts#hasStock).
-- **When** every line is in stock, **then** nothing changes.
-
-## Implementation
-
-**`src/stock/`**
-
-- Modified [`hasStock()`](code:src/stock/check.ts#hasStock) to read every level
-  once and collect every short line.
+This segment checks the stock of every basket line before payment, so a basket
+with an item that sold out a minute ago gets an error naming each sold-out item
+and never reaches payment.
 ```
 
-**Verify every claim against the diff**, never against a pull request's own
+Check every claim against the diff, never against the pull request's own
 description.
 
-### The opening paragraph
-
-Say why anyone should care, to a reader who has not seen the code.
-
-**This paragraph bans identifiers, paths and links.** If you cannot write it
-without naming a symbol, you are describing the implementation rather than the
-change. That ban is what makes it the easiest place to hide a vague verb, so say
-what the reader would see: not "the size check handles an oversized query" but
-"a query over 1 MB now gets an error that names the 1 MB limit".
-
-Five sentences, and no more even when the change is large.
-
-### Overview
-
-What changes from outside the code, as a list of scenarios. Each item is one
-sentence: a bold **When**, the situation, a bold **then**, what can be observed.
-
-The situation is in the reader's terms — one clause. Name what a person outside
-the code does, or the state that holds: "a customer submits a basket with two
-lines out of stock", "every line is in stock". Write the situation, not the code
-path that answers it.
-
-What can be observed is the result a person or another system sees, not the
-mechanism: "the error message names both out-of-stock lines". Link the code the
-result comes from where there is code to name.
-
-Say "nothing changes" when a reader would reasonably expect a change and there
-is none; that line stops a reviewer hunting for a regression that is not there.
-A "nothing changes" scenario carries no link.
-
-### Implementation
-
-What changed inside the code, grouped by where it lives. Each group is a bold
-label on its own line, then a list of the changes there.
-
-The label is the place the changes live — a file, or a directory when several
-inside it are touched. It takes no verb. Group by where the code lives, not by
-theme, and put the groups in the order the tour walks them.
+### What the sentences say
 
-Each item is one change a reader would notice, as one sentence: the verb first,
-then the code it names. "Modified `hasStock()` to read every level once and
-collect every short line." Link the code the claim is about.
+Say what the segment's change does for a reader who has not seen the code. Name
+no identifiers, paths or links. Say what someone would see: "a query over 1 MB
+now gets an error that names the limit" tells the reader more than "the size
+check handles large queries".
 
-An item that names no code is usually one that has not been thought through. The
-exceptions are rare — a configuration value, a deleted file, the tests — and
-they carry no link.
+Write about the files of this segment only. When the reviewer turned segments
+off, the first segment's context is the one Context of the whole change: start
+it with "This change" and say what the whole change does.

package/backend/configurations/default-configurations/unfamiliar-territory/traceDiagram.description.md

@@ -0,0 +1,16 @@
+Write a caption for the diagram: what the reader is looking at, before they follow its lines. Two sentences at most.
+
+- **The first sentence says what the diagram starts from.** Open with "This diagram shows how", name the page, the component, the job or the route the paths start at, and say what it does when it opens, loads or runs: `This diagram shows how the edit page loads an order and renders it in the form.` Use the verb of the code for what it does, such as renders, loads or requests, so that "shows" is not written twice.
+- **The second sentence follows the user's actions.** The actions are the events on the diagram: a submit, a click, a pick, a typed value. Open with "It also shows what happens when the user", name the action as the user would, then say where its data ends up: the request it sends, the store it writes, the page it opens. `It also shows what happens when the user saves the order, and how the changed order reaches the API through updateOrder().`
+- **Several actions.** Name them together, in the order the diagram draws them: `It also shows what happens when the user picks a customer, picks a product, types a quantity or submits the form.`
+- **A path nobody clicks.** A request, a schedule or another system starts it: name that in place of the user. `It also shows what happens when a request reaches POST /orders, and how the order reaches the database.`
+- **No action on the diagram.** Leave the second sentence out, and never write "It also shows" with nothing after it.
+- **Shared code that other segments call.** Say what the diagram holds and what reaches it: `This diagram shows how the route table opens the order pages, and how each hook loads or sends orders through its request.`
+
+Name where the data ends up, not the steps on the way: the labels and the descriptions of the nodes carry the steps, and the reader follows them on the board. Do not explain the change: the Context Section and the waypoints do.
+
+| The diagram | Its caption |
+|---|---|
+| A page that loads a record and saves it | This diagram shows how the edit page loads an order and renders it in the form. It also shows what happens when the user saves the order, and how the changed order reaches the API through `updateOrder()`. |
+| A page that creates a record | This diagram shows how the create page opens with an empty draft in the form. It also shows what happens when the user submits the form, and how the new order reaches the API through `createOrder()`. |
+| A page with no action on its paths | This diagram shows how the orders list loads the orders and renders them in a table. |

package/backend/configurations/default-configurations/unfamiliar-territory/traceDiagram.nodes.blockLabels.label.md

@@ -0,0 +1,11 @@
+Say what this row of the node does, as a reader of the product would. Start with a verb in the present tense: "Queries every Pokemon ordered by name", "Sends the order to the API". Read the code of the node first, so the label says what the block does, not what it is or what it is called: "Queries every Pokemon ordered by name", not "The query of every Pokemon".
+
+- **An argument.** Say what the node does with the value it is given: `Filters the Pokemon by this trainer`, not `The trainer to filter by`.
+- **A state.** Say what the node keeps in it: `Keeps the lines of the cart`, not `The lines of the cart`.
+- **A hook.** Say what the node gets from it: `Gets the mutation that applies a promo code`.
+- **An effect.** Say what it does and when: `Clears the form after a save`.
+- **A call.** Say what is asked of the code it calls: `Saves the renamed user`.
+- **A value.** Say what the code that makes it does: `Queries every Pokemon ordered by name`, not `The query of every Pokemon`.
+- **A step.** Say what the step does: `Returns an error for an empty title`. For a condition, say what is checked: `Checks whether a trainer is given`. A step can stand for several statements that follow each other, listed by the first: say what they do together, `Renames the chosen user`.
+
+Leave the name of the code out: the row shows it under your label. Keep the same shape and tense on every block label of one node: each one starts with a verb.

package/backend/configurations/default-configurations/unfamiliar-territory/{journey.nodes.description.md → traceDiagram.nodes.description.md}

@@ -1,4 +1,4 @@
-Tell the journey that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
+Tell the trace that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
 
 - **Several paths.** A node that more than one path reaches opens with one line that says so, then a list with one such sentence per path.
 - **A node with trigger labels.** Say what each event runs and what each fetch feeds, in the words of its trigger label: `When a shopper clicks "All", the handler calls setStatus(null) on the filter store.`

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

@@ -43,7 +43,7 @@ sort order, the option merge, the loop — unless that detail is the change itse
 change to the purpose `context` states, usually with _so that_ or _because_. A reviewer who reads
 only this card should know why it is in the pull request.
 
-**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blast` lists the files
+**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blastDiagram` lists the files
 that import the file this card is in, and what the change does to each: its `impactType` and its `impactReason`. Name the one this card exists
 for — the form that no longer submits, the route that now returns something else, the caller that now
 depends on the new value — and link it. Where nothing outside the change reaches this code, name