@kidlat-dakila/flightplan 0.0.0-stage → 0.1.6

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

@@ -0,0 +1,100 @@
+# How to write it
+
+Prose beside code. Code is referenced, never pasted. Same voice on every field,
+label to reading. This file: the voice. Each field's wording: that field's own
+instruction. Artifact shape: `artifactFormat`.
+
+## The test
+
+Reader has code open beside your words. Write what code does not show: why it
+runs, what goes wrong without it. Anything readable from code: cut.
+
+Second test: **can it be checked?** Claim that names code: checkable. Claim that
+names nothing: never checked. Cut it.
+
+## Voice
+
+Fragments. Payload only. Fewest words that keep every fact.
+
+- **Drop** articles, copulas, connectives, when order stays clear.
+- **One word when one word is enough.**
+- **Each fact once.** No restating, no summary after a list.
+- **One idea per fragment.** Twenty words is long.
+- **Active, present tense**, except where Tense says otherwise.
+- **Plain words.** Verb the code uses.
+- **No ambiguous _it_.** Name the thing again.
+- **No vague verbs**: _handle_, _manage_, _process_, _support_, _orchestrate_,
+  _surface_, _drive_, _deal with_.
+- **No ceremony**: no opener, no hedge, no recap, no closer. No _just_,
+  _really_, _basically_, _actually_, _simply_.
+- **No invented abbreviations** (cfg, impl, fn). Standard acronyms fine: DB,
+  API, HTTP. No arrows.
+
+## Floor: never cut
+
+- Code, identifiers, paths, `code:` links, error strings: verbatim.
+- _not_, _never_, _no_, _only_, _except_, _no longer_.
+- Numbers, units, values.
+- One term per thing.
+
+**Fragment with two readings: write the full sentence.** Step order a fragment
+could scramble: full sentences. Clarity beats compression. Fragment not shorter
+than the sentence: use the sentence.
+
+**Never perform.** No "me think", no mangled verbs, no word added for flavour.
+
+## Code, not metaphor
+
+Name the operation the code has. Reader must find the word in the code.
+
+- Not "climbs the ancestors": `element = element.parentElement`.
+- Not "missing", "never set": `undefined`, `null`, `""`. Name the value.
+- Not "the guard", "the gate", "the wiring": condition, validation, check,
+  function.
+- Not _refuses_, _rejects_, _accepts_, _allows_, _blocks_, _protects_: returns
+  `false`, throws `RangeError`, returns a 400, skips the line.
+
+Codebase's own nouns are fine: reader can search them. Technical verbs with one
+meaning are fine: return, throw, parse, render, call.
+
+**Value, never variable.** `addToBasket({ id: 7 })`, never
+`addToBasket(payload)`. Literal too long: shortest thing that identifies it,
+`<div.fp-interlude>`, `[9 ranges]`.
+
+**Do not narrate the diff.** Prose is about code. Panel marks what changed.
+
+**Invent no nouns.** Name not in codebase: reader cannot search it.
+
+## Tells: fix on sight
+
+- **`-ing` rider**: _ensuring_, _allowing_, _improving_. Make it the main claim
+  with a link, or cut.
+- **Hedge**: _likely_, _presumably_, _appears to_, _typically_. Unresolved: a
+  `question`, or a `risk` whose reading says what stopped you.
+- **Sales adjective**: _robust_, _seamless_, _elegant_, _crucial_.
+- **Vague connection**: _related to_, _tied to_, _works with_. Name it: calls,
+  reads, returns, throws, wraps.
+- **Staging**: "This isn't just a check". Say what it is.
+- **Borrowed authority**: _best practice_, _industry standard_. Cite code, or
+  drop.
+- **Reading restates its title.** Fix one of them.
+
+None of these reach inside code: an identifier, a quoted error string, a value
+and a finding's solution are exempt from every rule here.
+
+Linking code is fixed, always in force. Its rules are served separately.
+
+## Tense
+
+Titles: past tense. _Added_, _Modified_, _Removed_.
+
+Descriptions: present tense. Waypoint reading is the exception: opens with what
+was done, past tense, then present for what code does now.
+
+## Where a reason goes
+
+- `context`: reason the change exists.
+- Node `description`: reason a step is in the path.
+- Waypoint reading: reason for its own piece of the change.
+
+Constraint or trade-off beyond that: one fragment at end of a reading. No more.

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

@@ -0,0 +1,8 @@
+Write one or two sentences a reviewer can check against the code.
+
+- On `breaks`: what fails, and the case the author did not account for.
+- On `behaviour-changes`: what is different now, and for whom.
+
+Name the place and link it: "renders the units left, and now renders a negative
+number when holds exceed the stock". Do not restate the impact type. Write none
+on an unaffected file.

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

@@ -0,0 +1 @@
+It still works, and now does something different that the change does not mention.

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

@@ -0,0 +1 @@
+Its logic no longer holds against the changed code, and the compiler does not say so.

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

@@ -0,0 +1,11 @@
+Set the impact type to what the change does to this file. What each value means
+is given with its option.
+
+Judge the logic, not the types. A call that no longer type-checks is the
+compiler's to report, and is never the reason for a value here.
+
+Leave it unset when nobody has assessed the file. There is no `unknown`. A file
+of the change takes no impact type at all.
+
+`breaks` and `behaviour-changes` never travel alone: write the `impactReason` in the
+same call. `unaffected` is written alone, with no reason.

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

@@ -0,0 +1 @@
+The change reaches it, and nothing it does is different.

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

@@ -0,0 +1,70 @@
+Write three parts, in this order: an opening paragraph, then `## Overview`, then
+`## Implementation`.
+
+```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.
+```
+
+**Verify every claim against the diff**, never against a 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.
+
+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.
+
+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.

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

@@ -0,0 +1,62 @@
+Write for an engineer who has never opened this repository. They know the language. They do not
+know this codebase's words, its product, or where anything is used. They opened this code by
+hovering its name, and they see the code under your words.
+
+**A function's description is three sentences, in this order:**
+
+> `{name}({arguments})` is a {what it is} that {what it does}. It takes {each argument, with its
+> type and what it stands for} and returns {what the caller gets back}. It is used in {where} to
+> {what that code needs it for}.
+
+> `validateAge(user)` is a validation function that checks whether a user is old enough to hold an
+> account. It takes `user: User`, the person signing up or editing their details, and returns
+> `true` when their `birthDate` is 18 years ago or more, and `false` otherwise. It is used in the
+> [registration page](code:src/account/RegisterPage.tsx#RegisterPage) and the
+> [update profile page](code:src/account/ProfilePage.tsx#ProfilePage) to stop the form before it
+> is sent.
+
+- **What it is**: the kind of function, in two or three words: a utility function, a validation
+  function, a query function, an event handler, a hook, a server procedure.
+- **What it does**: its job, in plain words. One clause. Do not walk the lines.
+- **Arguments**: write each as `name: type`, then what the value stands for in the product. Say
+  which can be left out.
+- **Returns**: the type and what it stands for. Say what comes back when there is nothing to
+  return, and what it throws, where it does either.
+- **Where it is used**: the pages, routes or functions that call it, by the name a user of the
+  product would know them. Take them from the `usedBy` the item is handed out with, not from a
+  guess. Where many use it, name three and say how many there are.
+- **What for**: the reason that code needs it, in the product's words.
+
+**A component's description is the same three sentences**, with its props for the arguments, what
+it shows for what it returns, and the pages that render it for where it is used:
+
+> `<EmptyState />` is a placeholder component that a page shows in place of a list when there is
+> nothing to list. It takes `title: string`, the main line, `hint: string`, a smaller line under it
+> that can be left out, and `action: { label, href }`, an optional button. It is used in the
+> [orders page](code:src/orders/OrdersPage.tsx#OrdersPage), the
+> [basket page](code:src/checkout/BasketPage.tsx#BasketPage) and 6 other pages to tell a shopper
+> why the page is empty and what to do next.
+
+**Any other code** (a type, a constant, a table, a router) is two sentences: what it is and what
+it holds, then where it is used and what for.
+
+> `orderRouter` is a router that holds every operation a browser can ask the server to do with
+> orders: `list`, `byId` and `cancel`. It is used in
+> [`appRouter`](code:src/server/api/root.ts#appRouter), the one list of every router of the
+> server, so that the page can call `api.order.list`.
+
+**Define a word of this codebase the first time you use it**, in one clause: a hold, a line, a
+procedure. The reader has not met it.
+
+**Link every place it is used that the artifact holds.** A link resolves only inside the files the
+artifact holds. Name code in any other file in backticks, with its path.
+
+**Describe the code as it is, not the pull request.** The description is shown wherever the name
+is hovered, in any file, so do not say _here_, _this caller_ or _the change_. A waypoint's reading
+says what the author changed.
+
+**Do not explain the language or a library.** Name a library function the code is built on, and
+say in one clause what this code gets from it.
+
+**Do not tell history the code does not show.** Why it was built and what it replaced are not in
+the code, unless a comment or a name says so.

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

@@ -0,0 +1,10 @@
+Tell the diagram as text: what a reader would know after following every line of it. Five sentences at most, and fewer for a small diagram.
+
+- **Start where the paths start.** Say what sets each path off, in the reader's terms: "When a shopper places an order", "When the nightly job runs".
+- **Follow each path in the order the diagram draws it**, from the left to the changed code, naming the steps by what they do: `<Checkout />` calls `placeOrder()`, which asks `stockOf()` for every line of the cart.
+- **Say where the paths reach the change.** Name the nodes the change touched and how the path arrives at each. Do not explain the change: the Context Section and the waypoints do.
+- **Several paths.** Say how many there are and where they meet, then tell each in one sentence. Tell paths that run alike together.
+
+Cover the whole diagram, not one path of it. A large diagram is told by its paths and the steps they share, not node by node. Do not open with "This diagram shows", and do not count the nodes.
+
+`When a shopper places an order, <Checkout /> calls placeOrder(), which asks stockOf() for every line of the cart before it charges the card. The stock badge reaches stockOf() as well, through useStockLevel(). Both paths end at stockOf(), which now subtracts the held units.`

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

@@ -0,0 +1,9 @@
+Say what this row of the node is for, as a reader of the product would: "The promo code the shopper typed", "Sends the order to the API". Read the code of the node first, so the label says what the block holds or does, not what it is called.
+
+- **An argument or a state.** Say what the value holds: `The lines of the cart`, not `items`.
+- **A hook.** Say what it gives the node: `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 step.** Say what the step does: `Refuses an empty title`. For a condition, say what is checked. 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.

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

@@ -0,0 +1,7 @@
+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.`
+
+- **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.`
+- **Nothing reaches it yet.** Say that no code uses it, and what is meant to.
+
+Do not describe the change here. The waypoint of the code says what changed, and the side panel shows that waypoint above the code. Do not restate the label or the identifier, which the node already shows. Link a step to its code where a reader would want to open it.

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

@@ -0,0 +1,5 @@
+Say what this step does, and to what — "Throws when a line is out of stock", not "The stock check" and not the identifier. A bare noun tells a reader which code this is and nothing about why they are being shown it. The identifier is never the label: the node already carries the name of its code. Keep the same shape and tense on every node of one diagram.
+
+A component drawn inside another is read inside its frame, so do not repeat the outer component in its label.
+
+A node of an event, an effect or a callback inside a component, of a procedure of a router and of an action of a store is read beside the node around it, so say what this unit does on its own: "Applies the code when the form is submitted", "Stores the promo when the request succeeds". An event has a trigger label too, which says what the user does, so the node says what the handler does.

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

@@ -0,0 +1,6 @@
+Say what happens at this place, as a reader of the product would: "A shopper clicks Remove", "The orders of the account are loaded". Read the code of the node first, so the label names the element the user acts on or the data that is fetched.
+
+- **An event.** Start with who acts, then the action and what it is on: `A shopper clicks "All"`. Leave the name of the component and of the handler out: the row shows the name of the code under your label.
+- **A data fetch.** Say what is loaded, not how: `The stock of the product is loaded`, not `useQuery runs`.
+
+Keep the same shape and tense on every trigger label of one diagram.

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

@@ -0,0 +1,7 @@
+Say what the reviewer is being shown in this file, in one line — "Rounding moves
+to the subtotal", "The stock check now counts held units". It is the file's
+label on the section rail, so it has to tell this file apart from the others in
+the change. Never the path, which the section already shows, and never a list of
+every waypoint under it.
+
+Present tense, about the code. Keep it under about eight words.

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

@@ -0,0 +1,2 @@
+Broken behaviour that will cause an incident, and proven. Do not report a bug
+until you have proven it; an unproven one is a `risk`.

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

@@ -0,0 +1,7 @@
+### Kind
+
+Choose exactly one kind. Each is a different answer, not a different intensity.
+What each kind means is given with its option.
+
+Order a waypoint's findings most severe first: `bug`, then `risk`, then `nit`, then
+`question`.

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

@@ -0,0 +1,3 @@
+Anything the author may decline: style, naming, a micro-optimisation, and every
+improvement. All of it is optional, which is the one thing the reader needs to
+know at a glance.

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

@@ -0,0 +1,2 @@
+You are not sure. A genuine question, not a suggestion in disguise. Carries no
+trace and no solution.

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

@@ -0,0 +1,3 @@
+The code is fragile though it works (a race, a missing null check, a swallowed
+error), or it looks broken and you could not demonstrate it. Both are an unsafe
+path that looks reachable and that nobody has seen fire.

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

@@ -0,0 +1,30 @@
+Report what is wrong with the code this waypoint shows, on the waypoint itself.
+A reviewer meets the claim with the code it is about rather than in a list at
+the end, which is the whole reason this is here rather than there.
+
+Report only what your reading of the code found. A finding you inferred from the
+diff without opening the file is a guess with a chip on it, and the reviewer
+cannot tell the difference. Verify it against the repository, including files
+the change never touched — a guard three files away may already handle the case
+you are about to report.
+
+Pick the kind honestly. `bug` is something that is wrong now. `risk` is
+something that will go wrong under conditions you can name. `nit` is worth
+saying and not worth blocking on. `question` is you not knowing — a genuine
+question, not a suggestion in disguise, and it carries no trace and no fix.
+
+The title says what is wrong in one line, the reading says why, and the trace is
+the steps that prove it. Name code with `code:` links throughout, so every claim
+resolves to lines a reader can check.
+
+Give every `bug`, `risk` and `nit` a `solution`: the lines as they should be.
+It is a string of code that replaces the lines this waypoint covers — no path,
+no position, because the waypoint is the position — and the reader can preview
+it against the real file.
+Write the lines whole, since a line left out of the body is a line the fix
+deletes. If the fix needs more than these lines, write the part that belongs
+here and name the other lines in the reading.
+
+A card shows one chip, the highest kind it carries, so a bug beside a nit reads
+as a bug. That is right, and it is also why a nit reported on the same card as a
+bug is easy to miss: report the nit where it belongs.

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

@@ -0,0 +1,14 @@
+### Reading
+
+Explain the defect in the reader's file, one linked claim at a time: what the
+code does, and why that is wrong. Every claim links the exact lines it rests on,
+so the reader can open each one. Present tense, a few sentences at most.
+
+Do not hedge — a reading that hedges is a reading nobody opened the file for.
+Where you report a `risk` because you could not prove a suspected bug, the
+reading says in one sentence what stopped you.
+
+**An improvement says three things**: what the code does now and its limitation,
+stated plainly as working; the better alternative, with the exact imported
+symbol; and why it is better — fewer lines, fewer states, one fewer round trip.
+Never "cleaner".

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

@@ -0,0 +1,12 @@
+### Solution
+
+Every `bug`, `risk` and `nit` carries a solution. A `question` carries none: it
+is not a claim.
+
+Write the lines as they should be, whole, with the indentation they have in the
+file. The solution replaces every line the finding's waypoint covers, so a line
+you leave out of it is a line the fix deletes.
+
+If the fix needs more than these lines, write the part that belongs to these
+lines and name the other lines that must change in the reading, with `code:`
+links. The waypoint says where the defect is, and the solution follows it.

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

@@ -0,0 +1,6 @@
+### Title
+
+Name the code and what it does wrong — "`annotateRanges` drops the line mapping
+for the whole block", not "Prose loses its line numbers" and not "A subtle
+indexing problem". A title that could belong to a different finding is not a
+title. About ten words.

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

@@ -0,0 +1,12 @@
+### Trace
+
+The steps that prove the finding, in the order the code runs.
+
+The first step is the trigger: name the action and what makes it fire — the
+parameter, the state, the condition. "A reader selects a sentence", not
+"selection happens"; `POST /orders` with `quantity: 0`, not `POST /orders`. That
+step names a user action, so it carries no link.
+
+Every step after it is a debugger step, linked to where it is in the code. A
+trace carries the proof and nothing else — no impact, no evidence, no proposal
+step. A `nit` and a `question` carry no trace.

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

@@ -0,0 +1,36 @@
+Mark the few waypoints that carry the change: the cards a reviewer should spend
+their time on. Write one or two sentences saying why this is where the pull
+request does its work, and leave the field off every other waypoint.
+
+A pull request mixes the change with what the change drags along: a value
+threaded through three signatures, an import moved, a class renamed, a style
+adjusted, a type widened so the new code compiles, a fixture updated. A reviewer
+with forty cards and an hour has to know which three are the change. That is
+all this flag says. It points at importance. It is not a warning.
+
+**Flag the waypoint where the behaviour changes**: the new rule, the decision
+the code now makes differently, the data that now goes somewhere it did not,
+the contract a caller will now depend on. **Leave it off the plumbing**: wiring
+that passes the new value along, a constant, a comment, formatting and styling,
+a type-only edit, a rename, a test that restates the code.
+
+**It is not a bug report.** Something you believe is wrong, or could go wrong,
+is a finding — a `bug` or a `risk` — on the same card. A card can carry both,
+and a finding is never the reason for the flag. If the only sentence you can
+write is about what might break, you are writing a finding, so write one and
+leave this off.
+
+**Say why the card is central, against what the pull request is for.** "This is
+the rule the pull request exists for: an order now holds its stock before the
+card is charged, and the other cards in this file wire it in." Not "check this
+carefully", "core logic" or "this is complex": they name no reason, and a
+reviewer can see complexity without being told.
+
+**It works by contrast, so keep it rare.** One to three in a pull request is
+usual, and seldom more than one in a file. If every card would carry it, none
+should: the flag has nothing left to point at.
+
+It is not a second reading. The reading says what the code does; this says why
+it is the part to read.
+
+Name code the way every other field does, with `code:` links.

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

@@ -0,0 +1,68 @@
+Write the reading as the engineer who read the change, telling a colleague what the author did here
+and why it matters to the pull request.
+
+**Open with one sentence of a fixed shape**: _The author_ + what they did + what kind of code + what
+the change does.
+
+> The author modified a condition in `validateQuantity()` that now returns `false` for a quantity
+> over 10, down from 20. [`<BasketForm />`](code:src/checkout/BasketForm.tsx#L40-52) calls it before
+> it submits, so the form no longer submits a quantity of 11 to 20.
+
+- **What they did** is one verb, past tense: _added_, _implemented_, _modified_, _removed_,
+  _moved_, _replaced_.
+- **What kind of code** is the thing the reader will find in the panel, in the plain word for it:
+  a function, a method, a condition, a validation, a query, a loop, a type, a component, a
+  constant, a test. Then its name. Not review jargon — not a guard, a gate, a hook or wiring —
+  because the reader has to translate it back into the code they are looking at.
+- **What the change does** is the effect, not the mechanism. Say what is different now — the value
+  that moved, the input that now gets an error, the result that is now returned — and name the
+  values: from 20 to 10, from a throw to a returned reason.
+- **Say what the code does, not a judgement of it.** Not _refuses_, _rejects_, _accepts_, _allows_,
+  _blocks_ or _protects_, but the operation: returns `false`, throws `RangeError`, returns a 400,
+  skips the line. A verb of judgement hides which of these it is.
+
+**The author is the subject of the change, never of the code.** "The author reads every row" is
+wrong: the author read nothing, the code does. After the opening, the code is the subject: "It
+reads…", "`validateQuantity()` returns…".
+
+**When the change does more than one thing, list them.** Open with the sentence up to _that_, then
+one item per effect, in the order the code does them. Do not chain effects into one sentence with
+_and_, _then_ and commas.
+
+> The author added a function `reserveStock()` that:
+>
+> - reads the stock level of every line in the basket in one query
+> - writes one hold per line, which lapses after 15 minutes
+> - returns the holds, so that [`placeOrder()`](code:src/checkout/placeOrder.ts#L13-27) can release
+>   them when the charge fails
+
+**Do not walk the lines.** The panel shows them. Leave out how the code reaches its effect — the
+sort order, the option merge, the loop — unless that detail is the change itself.
+
+**Then say what it is for, against the pull request.** Every reading connects its piece of the
+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
+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
+what inside the pull request uses it. Where neither the Blast Diagram nor `context` shows a reason,
+say what the change does to its consumer and stop: the author's reason is not yours to invent.
+
+**Link code outside the card; name code inside it.** The panel already shows the card's own lines,
+so a link to them points at what the reader is looking at. Write those identifiers in backticks
+without a link. Link everything else the reading mentions — the caller, the consumer, the type, the
+test, the other half of the change in another file — and link every such mention, not the first one.
+A link resolves only inside the files the artifact holds, which `codeLinks` lists how to find; name
+code in any other file in backticks, with its path.
+
+**A body's reading** (a waypoint with children) says what the author did across the whole body and
+why: the opening sentence, a list of at most five items where it does several things, and one
+sentence of purpose. **A block's reading** (a child) is the opening sentence about its one block,
+with a list only if that block does several things, and its _so that_ points at the body it sits
+in or the code that consumes it.
+
+**Do not restate the title.** The title names the change; the reading adds the values, the reason
+and what the change connects to. A reading that says the title again at greater length means the
+title needs work, not the reading.

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

@@ -0,0 +1,12 @@
+**Say what was done, and to what** — "Modified the file reader to return a reason
+for binary content", "Returns null for a path outside the root". Not a bare noun
+like "The file reader" or "The error path": a noun names which code this is about but not why
+the reader is shown it, which is the one thing a title is for.
+
+**Past tense** — Added, Modified, Removed. Never the identifier on its own.
+
+**One title, one thing.** An arrow, an "and", or three clauses means several
+waypoints crammed into one.
+
+**A child's title is a smaller change than its parent's**, not a different kind
+of thing: same shape, same tense, at every level.

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

@@ -0,0 +1,5 @@
+One optional line that frames the whole Code Walkthrough: the order the files are read in,
+and why — "The stock check first, then the query it calls."
+
+It names the tour, not the first file. Leave it out when the file order speaks
+for itself.