@connextar/house 0.1.1 → 0.3.0

package/dist/ux/use-optimistic-list.js

@@ -0,0 +1,115 @@
+"use client";
+import * as React from "react";
+import { errorMessage } from "./errors.js";
+import { useActionReporter } from "./feedback.js";
+import { applyPatches, nextPatchId, reconcile, settlePatch, supersede, tempKey, } from "./optimistic.js";
+const NO_PATCHES = [];
+/**
+ * A list the screen can change before the server has agreed.
+ *
+ * `base` is whatever the server last said — a server component's prop, or
+ * state filled by a fetch. Never write to it: the hook keeps its changes
+ * beside it and folds them in on render, which is what lets fresh rows take
+ * over cleanly whenever they turn up. See `optimistic.ts` for the rules.
+ *
+ * ```tsx
+ * const list = useOptimisticList(tasks, { key: (t) => t.id, onSettled: router.refresh });
+ *
+ * <Checkbox
+ *   checked={task.done}
+ *   disabled={list.isPending(task.id)}
+ *   onCheckedChange={(done) =>
+ *     list.update(task.id, { done }, () => commitApi(`/api/tasks/${task.id}`, { method: "PATCH", … }))
+ *   }
+ * />
+ * ```
+ */
+export function useOptimisticList(base, options) {
+    const report = useActionReporter();
+    const [patches, setPatches] = React.useState(NO_PATCHES);
+    // Everything the asynchronous half needs, read at the time it runs.
+    const latest = React.useRef({ base, options, report });
+    React.useEffect(() => {
+        latest.current = { base, options, report };
+    });
+    // What is still worth applying, worked out fresh on every render rather than
+    // stored. A settled patch knows what the rows said when it landed, so
+    // `reconcile` can tell "nothing has refetched yet" from "new rows are here"
+    // without this hook having to watch the array — and it must not watch it:
+    // `useOptimisticList(rows.filter(…), …)` hands it a different array every
+    // render, and any state keyed on that identity renders forever.
+    const live = reconcile(patches, base, options.key);
+    const write = React.useCallback(async (batch, commit, per) => {
+        // Queued at the end, where it wins on render, and *without* clearing
+        // what is already held for these rows. An earlier change that succeeded
+        // is still true: rolling this one back must not take it down too.
+        //
+        // Reconciling here as well is the only pruning the stored queue gets.
+        // Render works out what to apply without touching state — it has to, or
+        // a caller passing `rows.filter(…)` would render forever — so this is
+        // where changes the rows have caught up with are actually let go of.
+        setPatches((previous) => [...reconcile(previous, latest.current.base, latest.current.options.key), ...batch]);
+        const ids = new Set(batch.map((patch) => patch.id));
+        const { options: opts, report: tell } = latest.current;
+        try {
+            const result = (await commit());
+            // A single write may be answered with the row as the server has it; a
+            // batch has no one row to be answered with.
+            const answer = batch.length === 1 ? (result ?? undefined) : undefined;
+            setPatches((previous) => {
+                const { base: rows, options: current } = latest.current;
+                const landed = previous
+                    .filter((held) => ids.has(held.id))
+                    .map((held) => settlePatch(held, answer, rows, current.key));
+                // Now that this one has landed it supersedes what was already held
+                // for the same rows. Writes still in flight are left: each has a
+                // request of its own that can still come back refused.
+                const keys = new Set(landed.map((held) => held.key));
+                const kept = supersede(previous.filter((held) => !ids.has(held.id)), keys);
+                return [...kept, ...landed];
+            });
+            if (per?.success)
+                tell({ tone: "success", title: per.success });
+            if (!per?.silentSettle)
+                opts.onSettled?.();
+            return true;
+        }
+        catch (thrown) {
+            // Roll back: the rows go back to whatever the server last said, which
+            // `base` still holds untouched.
+            setPatches((previous) => previous.filter((held) => !ids.has(held.id)));
+            tell({
+                tone: "error",
+                title: per?.error ?? opts.error ?? "That didn't save",
+                description: errorMessage(thrown),
+            });
+            return false;
+        }
+    }, []);
+    const insert = React.useCallback((row, commit, per) => {
+        const key = latest.current.options.key(row);
+        return write([{ id: nextPatchId(), kind: "insert", key, row, at: "end", settled: false }], commit, per);
+    }, [write]);
+    const update = React.useCallback((key, fields, commit, per) => write([{ id: nextPatchId(), kind: "update", key, fields, settled: false }], commit, per), [write]);
+    const remove = React.useCallback((key, commit, per) => write([{ id: nextPatchId(), kind: "remove", key, settled: false }], commit, per), [write]);
+    const move = React.useCallback((key, before, commit, per) => write([{ id: nextPatchId(), kind: "move", key, before, settled: false }], commit, per), [write]);
+    const bulk = React.useCallback((changes, commit, per) => write(changes.map(({ key, fields }) => ({
+        id: nextPatchId(),
+        kind: "update",
+        key,
+        fields,
+        settled: false,
+    })), commit, per), [write]);
+    const items = applyPatches(base, live, options.key);
+    const busy = React.useMemo(() => {
+        const keys = new Set();
+        for (const patch of live)
+            if (!patch.settled)
+                keys.add(patch.key);
+        return keys;
+    }, [live]);
+    const isPending = React.useCallback((key) => busy.has(key), [busy]);
+    return { items, isPending, pending: busy.size > 0, insert, update, remove, move, bulk };
+}
+export { tempKey };
+//# sourceMappingURL=use-optimistic-list.js.map

package/dist/ux/use-optimistic-list.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-list.js","sourceRoot":"","sources":["../../src/ux/use-optimistic-list.ts"],"names":[],"mappings":"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"}

package/dist/ux/use-optimistic-value.d.ts

@@ -0,0 +1,40 @@
+export interface OptimisticValueOptions {
+    /** Heading for the toast when the write fails. */
+    error?: string;
+    /** Run after the write lands — usually `router.refresh()`. */
+    onSettled?: () => void;
+}
+export interface OptimisticValue<T> {
+    /** What to render: the change if one is held, otherwise the server's value. */
+    value: T;
+    /** A write is in flight. */
+    pending: boolean;
+    /**
+     * Show `next` now, then commit it. The commit may resolve with the value as
+     * the server has it — and must resolve with **that value's own shape** or
+     * nothing at all. A write route often answers with some other record
+     * entirely, which would replace the value with something that is not one:
+     * `async () => { await save(); }` is the right wrapper in that case.
+     */
+    set: (next: T, commit: () => Promise<T | void>, options?: {
+        success?: string;
+        error?: string;
+    }) => Promise<boolean>;
+    /** The same for an object value: lay these fields over it. */
+    merge: (fields: Partial<T>, commit: () => Promise<T | void>, options?: {
+        success?: string;
+        error?: string;
+    }) => Promise<boolean>;
+}
+/**
+ * One value the screen can change before the server has agreed: a switch, a
+ * status, a counter, a settings record.
+ *
+ * Same rules as `useOptimisticList` and for the same reasons — the change is
+ * held beside the server's value rather than replacing it, so a failure rolls
+ * back to something real and a refresh always wins. A switch is the case where
+ * getting this wrong is most obvious: flipping back a second after it was
+ * flipped, with no explanation, is worse than not moving at all.
+ */
+export declare function useOptimisticValue<T>(base: T, options?: OptimisticValueOptions): OptimisticValue<T>;
+//# sourceMappingURL=use-optimistic-value.d.ts.map

package/dist/ux/use-optimistic-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-value.d.ts","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"AAQA,MAAM,WAAW,sBAAsB;IACrC,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,+EAA+E;IAC/E,KAAK,EAAE,CAAC,CAAC;IACT,4BAA4B;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;;OAMG;IACH,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACpH,8DAA8D;IAC9D,KAAK,EAAE,CACL,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,MAAM,EAAE,MAAM,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,KAC3C,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,GAAE,sBAA2B,GAAG,eAAe,CAAC,CAAC,CAAC,CA8DvG"}

package/dist/ux/use-optimistic-value.js

@@ -0,0 +1,68 @@
+"use client";
+import * as React from "react";
+import { errorMessage } from "./errors.js";
+import { useActionReporter } from "./feedback.js";
+import { sameRow } from "./optimistic.js";
+/**
+ * One value the screen can change before the server has agreed: a switch, a
+ * status, a counter, a settings record.
+ *
+ * Same rules as `useOptimisticList` and for the same reasons — the change is
+ * held beside the server's value rather than replacing it, so a failure rolls
+ * back to something real and a refresh always wins. A switch is the case where
+ * getting this wrong is most obvious: flipping back a second after it was
+ * flipped, with no explanation, is worse than not moving at all.
+ */
+export function useOptimisticValue(base, options = {}) {
+    const report = useActionReporter();
+    // `witness` is what the server's value was when the write landed. A settled
+    // hold stands until that changes, which is how "nothing has refreshed yet"
+    // is told apart from "the server now says something else". Worked out on
+    // each render rather than stored, so an object rebuilt by the parent on
+    // every render cannot start a render loop.
+    const [held, setHeld] = React.useState(null);
+    const latest = React.useRef({ options, report });
+    React.useEffect(() => {
+        latest.current = { options, report };
+    });
+    // Nothing is stored when this flips: the next `set` replaces the hold
+    // anyway, and clearing it from an effect would only add a render.
+    const overtaken = held !== null && held.settled && !sameRow(held.witness, base);
+    const value = held && !overtaken ? held.value : base;
+    const valueRef = React.useRef(value);
+    const baseRef = React.useRef(base);
+    React.useEffect(() => {
+        valueRef.current = value;
+        baseRef.current = base;
+    });
+    const set = React.useCallback(async (next, commit, per) => {
+        setHeld({ value: next, settled: false });
+        const { options: opts, report: tell } = latest.current;
+        try {
+            const result = (await commit());
+            // The server's own value where it sent one, so a clamped or normalised
+            // answer shows now rather than after the next refresh.
+            setHeld({
+                value: result === undefined || result === null ? next : result,
+                settled: true,
+                witness: baseRef.current,
+            });
+            if (per?.success)
+                tell({ tone: "success", title: per.success });
+            opts.onSettled?.();
+            return true;
+        }
+        catch (thrown) {
+            setHeld(null);
+            tell({
+                tone: "error",
+                title: per?.error ?? opts.error ?? "That didn't save",
+                description: errorMessage(thrown),
+            });
+            return false;
+        }
+    }, []);
+    const merge = React.useCallback((fields, commit, per) => set({ ...valueRef.current, ...fields }, commit, per), [set]);
+    return { value, pending: held !== null && !held.settled, set, merge };
+}
+//# sourceMappingURL=use-optimistic-value.js.map

package/dist/ux/use-optimistic-value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-optimistic-value.js","sourceRoot":"","sources":["../../src/ux/use-optimistic-value.ts"],"names":[],"mappings":"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"}

package/docs/ReleaseProcess.md

@@ -0,0 +1,315 @@
+# Release Process
+
+> How every Connextar app is versioned, how to decide whether a change is a **major**, **minor** or **patch** release, and the runbook for cutting one. Shared by the cohort and shipped inside `@connextar/house`; each app keeps a short `docs/operations/ReleaseProcess.md` that says only what is its own.
+
+_First written for AltEd on 2026-09-12 and generalised for the cohort in `@connextar/house` 0.2.0._
+
+---
+
+## 0. What each app's own document says
+
+This document is the process. An app's `docs/operations/ReleaseProcess.md` links here and adds four things nobody else can write:
+
+1. **Its public API** — the people, links, data and systems outside the repository that a change can break (§2).
+2. **The trigger documents** — the status documents whose change means a release is due (§1).
+3. **Where the changelog is shown** — the route, and the production address to check after a deploy.
+4. **Its history note** — when it adopted this process, whether earlier releases were reconstructed, and the first tagged version (§7).
+
+Worked examples from the app's own history belong there too; they teach the rules better than generic ones.
+
+---
+
+## 1. What a release is
+
+A **deploy** puts code on the servers; a **release** is the numbered, dated, announced unit people can point to — "that came in 0.14.0". A deploy does not need a release, and a release deploys nothing by itself.
+
+A release is four records that must agree:
+
+| Where                                                             | What it holds                                                          | Kept honest by                                                                      |
+| ----------------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `version` in `package.json` and `package-lock.json`               | The current version                                                    | The release guard test (§4)                                                         |
+| `CHANGELOG` in `lib/changelog.ts`, newest first                   | What changed, written for the people who use the app; shown in the app | The release guard test — matches `package.json`, one step at a time, dates in order |
+| An annotated git tag `vX.Y.Z` on the release commit               | Where the release sits in history                                      | Runbook step 8                                                                      |
+| The _Last updated_ line of the status documents, and the work log | Which work the release shipped                                         | Runbook step 6                                                                      |
+
+### When to cut one
+
+**Cut a release for every change set that touches the app's trigger documents** — the status documents where the delivery workflow records shipped work (usually `docs/ImplementationStatus.md`, and a marketing status document where there is one). Touching them is the signal. That covers feature work, security audit rounds, documentation pruning rounds, marketing-only work and fixes.
+
+- **One change set, one release.** Don't hold work back to share a number; numbers cost nothing, and a version that means "everything since last week" means nothing.
+- A change set that touches neither document (a local tooling tweak, say) rides along in the next release. If it changes what anyone experiences, it should have touched the documents in the first place.
+
+---
+
+## 2. Choosing the version
+
+Versions follow [Semantic Versioning 2.0.0](https://semver.org): `MAJOR.MINOR.PATCH`, with no pre-release or build suffix. Tags are `v` plus the version (`v0.16.2`); the `version` field and the changelog carry the bare number (`0.16.2`).
+
+### The public API
+
+Semver is defined by what a change breaks, so first be clear who can be broken. For an app that is everything people and systems outside the repository rely on. The app's own document lists them; the categories are always these:
+
+- **People** — the features they use, what their plan includes, and behaviour they have learnt.
+- **Links people keep** — shared and tokenised links, calendar or data feeds, public marketing and guide URLs, bookmarks into the app.
+- **Data people own** — their records, uploads and exports.
+- **Systems** — webhook contracts, payment products and prices, scheduled endpoints, public APIs other services call.
+
+Internal code — modules, API routes only the app's own UI calls, the database schema — is not the public API. Changing it is not breaking unless someone on the list feels it.
+
+### MAJOR — someone has to change what they do
+
+- A feature is removed or withdrawn.
+- A plan includes less for people already on it, or prices rise for existing subscribers.
+- A link people keep stops working without a redirect.
+- Existing data is lost, hidden for good, or needs someone to act before it can be used again.
+- A system contract changes incompatibly.
+- Everyone must sign in again, or re-register passkeys.
+
+### MINOR — something new, nothing broken
+
+- A new feature, screen or capability.
+- More people may do something they couldn't.
+- A plan includes more.
+- A new public route: a free tool, a landing page, a guide for a new feature.
+- A new option on an existing feature that changes nothing for anyone who ignores it.
+
+### PATCH — the same product, working better
+
+- Bug fixes, including security fixes that stop something nobody was meant to be able to do.
+- Copy, guides, marketing layout and presentation.
+- Performance, accessibility and reliability improvements with no new capability.
+- Refactors, tests, tooling, dependency updates nobody notices.
+- Documentation-only work.
+
+### Deciding a change set that mixes classes
+
+1. **List the changes** from the work-log entry and the diff since the last release (runbook step 1).
+2. **Classify each one** using the lists above.
+3. **The release takes the highest class present.** One new feature and six fixes is a minor release.
+4. **When unsure between two classes, choose the higher one** and say why in the work log.
+
+| Situation                                                                                                       | Class                                                                                |
+| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| A security fix closes a gap nobody was meant to use, even if a few accounts lose access they shouldn't have had | PATCH — describe the rule now enforced, never the exploit                            |
+| A security fix removes something people legitimately relied on                                                  | MAJOR — an owner decision                                                            |
+| A limit shows less but deletes nothing                                                                          | MAJOR if it reduces what existing accounts see; MINOR if it only applies to new ones |
+| An additive database migration                                                                                  | Nothing by itself — classify the feature it serves                                   |
+| A migration that needs someone to act, or loses data                                                            | MAJOR                                                                                |
+| A dependency upgrade                                                                                            | PATCH, unless people notice — then classify by what they notice                      |
+| A page or guide renamed with a permanent redirect                                                               | PATCH                                                                                |
+
+### While the version is 0.x — early access
+
+Semver treats `0.x` as a period when anything may change. Classify every change the same way, with one difference in how the number moves:
+
+| Class of change | Before 1.0.0                                                                               | From 1.0.0 |
+| --------------- | ------------------------------------------------------------------------------------------ | ---------- |
+| MAJOR           | Bump **MINOR**, and the release must carry a `changed` entry saying what people need to do | Bump MAJOR |
+| MINOR           | Bump MINOR                                                                                 | Bump MINOR |
+| PATCH           | Bump PATCH                                                                                 | Bump PATCH |
+
+`nextVersion(current, kind)` from `@connextar/house/release` applies exactly this rule.
+
+- **`1.0.0` is the owner's decision** — the moment the app leaves early access — and never an agent's.
+- **From `1.0.0`, an agent does not cut a major release without the owner's explicit approval** in the conversation or the task prompt.
+- Before 1.0.0, a MAJOR-class change is usually an owner decision anyway. Confirm that decision is recorded — in the prompt or the status document — before shipping it.
+
+---
+
+## 3. Writing the release notes
+
+The release is added to the top of `CHANGELOG` in `lib/changelog.ts`, typed as `ChangelogRelease` from `@connextar/house/release`:
+
+| Field      | Rule                                                                                                                                                                                 |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `version`  | The new version, no `v`                                                                                                                                                              |
+| `date`     | The UK calendar date the release is cut, `YYYY-MM-DD`                                                                                                                                |
+| `title`    | The headline in a few words — what someone would tell a friend                                                                                                                       |
+| `summary`  | One sentence on why the release matters                                                                                                                                              |
+| `sections` | Changes grouped under a **heading** named the way people name that part of the app. Most important first; **Fixes**, then **Behind the scenes**, last. Each heading once per release |
+
+Each change has a `type`, a `title` and a `text`:
+
+| `type`     | Use it for                                                                            |
+| ---------- | ------------------------------------------------------------------------------------- |
+| `new`      | Something that didn't exist                                                           |
+| `improved` | Something that works better                                                           |
+| `changed`  | Something that works differently in a way someone may need to act on — say what to do |
+| `fixed`    | Something that was wrong                                                              |
+
+- **`title`** — a short headline, sentence case, no full stop. The page shows it in bold, so it has to carry the change on its own.
+- **`text`** — one to three sentences on what a person can now do and where to find it, using the app's real labels. `**Label**` renders in bold.
+
+Writing rules:
+
+- **UK English, plain words.** Write for the people who use the app, not for developers.
+- **No internal names.** No tranches, epics, files, routes, schema, model or infrastructure names, and no exploit detail for security fixes.
+- **Release notes are dated facts; marketing copy is evergreen.** A release may say what shipped that day. Marketing copy describes the capability and must not list things that will change.
+- **Behind-the-scenes releases get one short line.** A pruning round is "Behind the scenes · Tidier documentation", not an essay.
+- **Never renumber a released version.** Edit an old release only to correct a factual error.
+
+---
+
+## 4. The pieces in code
+
+`@connextar/house` carries everything that must behave identically in every app. The app keeps its data and its page chrome.
+
+**The changelog data** — `lib/changelog.ts`:
+
+```ts
+import type { ChangelogRelease } from "@connextar/house/release";
+
+export const CHANGELOG: ChangelogRelease[] = [
+  {
+    version: "0.17.0",
+    date: "2026-09-13",
+    title: "Tables in guides",
+    summary: "Troubleshooting sections read as tables instead of rows of pipes.",
+    sections: [
+      {
+        heading: "Help centre",
+        changes: [{ type: "fixed", title: "Tables render properly", text: "Every guide table now shows as a table." }],
+      },
+    ],
+  },
+  // …older releases
+];
+```
+
+**The guard test** — `lib/release.test.ts`:
+
+```ts
+import { releaseHistoryProblems } from "@connextar/house/release";
+import { describe, expect, it } from "vitest";
+
+import lock from "../package-lock.json";
+import pkg from "../package.json";
+import { CHANGELOG } from "./changelog";
+
+describe("release history", () => {
+  it("agrees with package.json, moves one step at a time, and is dated in order", () => {
+    expect(releaseHistoryProblems(CHANGELOG, { pkg, lock })).toEqual([]);
+  });
+});
+```
+
+Each problem is a sentence that says what to fix ("package.json declares 0.17.0 but the newest release is 0.16.2").
+
+**The page** — the app's `/changelog` route draws its own hero and calls to action around the shared body:
+
+```tsx
+import { Changelog } from "@connextar/house/changelog";
+
+import { CHANGELOG } from "@lib/changelog";
+
+export default function ChangelogPage() {
+  return <Changelog releases={CHANGELOG} />;
+}
+```
+
+Each release shows its version, whether it was a major, minor or patch release, its date and summary; changes sit under their headings with a bold headline. A list of releases sits beside the content on wide screens and becomes a scrolling strip on a phone. `tagClassNames` maps the four change types onto the app's own palette.
+
+---
+
+## 5. Runbook
+
+Run it at the end of the change set, once the work and its documentation are done, and before the final report.
+
+**1. Gather what changed.**
+
+```bash
+git describe --tags --abbrev=0
+```
+
+That prints the last release tag. If there is none, use the newest version in `CHANGELOG`. Then read what has changed since it (substituting the tag):
+
+```bash
+git log --oneline v0.16.2..HEAD
+```
+
+```bash
+git diff --stat v0.16.2
+```
+
+Include uncommitted work (`git status`), and read the work-log entry for the change set.
+
+**2. Classify.** List each change, classify it (§2), and take the highest class.
+
+**3. Work out the next version** from the newest version in `CHANGELOG`:
+
+| Class (before 1.0.0) | From `0.16.2` |
+| -------------------- | ------------- |
+| PATCH                | `0.16.3`      |
+| MINOR or MAJOR-class | `0.17.0`      |
+
+**4. Bump the version.** This updates `package.json` and `package-lock.json` together, and creates no commit or tag:
+
+```bash
+npm version 0.17.0 --no-git-tag-version
+```
+
+**5. Write the release notes** at the top of `CHANGELOG` (§3).
+
+**6. Record the version.**
+
+- Start the new _Last updated_ line in whichever status document the work touched with the version: `_Last updated: 2026-09-13 — **v0.17.0 (minor)** — …_`.
+- Add `- Release: v0.17.0 (minor — <one-line reason>)` to the work-log entry's notes.
+
+**7. Verify** by exit status, not by reading the output:
+
+```bash
+npx vitest run lib/release.test.ts
+```
+
+Then the app's full gate set (`npm run check`, `npm test`, `npm run build`). When a dev server is running, open the changelog page and confirm the release is at the top with its sections.
+
+**8. Commit and tag** — only in a session that is committing its work. Put the version in the commit body (`Release: v0.17.0 (minor)`), then tag the commit on `main`:
+
+```bash
+git tag -a v0.17.0 -m "v0.17.0 — <release title>"
+```
+
+```bash
+git push origin main --follow-tags
+```
+
+In a session that leaves its work uncommitted, stop after step 7, and say in the final report that the version is prepared and its tag is owed when the work is committed.
+
+**9. Deploy** as usual. Once the release is live, check the production changelog page shows it.
+
+### Concurrent work
+
+Two worktrees can both prepare `0.17.0`. **The change set that merges second renumbers.** It recomputes its version against what is now on `main` (by its own class — `0.18.0` or `0.17.1`), moves its release above the other one in `CHANGELOG`, re-runs `npm version`, and re-runs the guard test. Never fold two releases into one version. Tags are only ever created on `main`, after the merge.
+
+### Hotfixes
+
+A fix for something broken in production is a PATCH on top of the latest version, cut with the same runbook. There are no release branches: `main` is the only line.
+
+---
+
+## 6. Checklist
+
+Copy into the work-log entry and tick off:
+
+- [ ] Changes listed and classified; release class is the highest present
+- [ ] Next version computed from the newest `CHANGELOG` release (0.x rule applied)
+- [ ] `npm version <x.y.z> --no-git-tag-version` run
+- [ ] Release added to the top of `CHANGELOG` — title, summary, sections, typed changes
+- [ ] No internal names; nothing dated leaked into marketing copy
+- [ ] Status document _Last updated_ line and work-log entry name the version
+- [ ] Release guard test, `npm run check`, `npm test`, `npm run build` exit 0
+- [ ] Committed with `Release: vX.Y.Z` and tagged — or the owed tag noted in the final report
+
+---
+
+## 7. Adopting this in an app with an older changelog
+
+Most apps had a flat changelog — dated entries, some with a type per item, none with a version. Adopting the process converts it once:
+
+1. **Keep every entry, oldest first.** The oldest becomes `0.1.0`.
+2. **Classify each later entry by §2** and step the version from the one before it with `nextVersion`. The guard test accepts nothing else.
+3. **Give each a title and a summary, and group its items under headings** the way §3 describes. Where an old item carries no type, choose the one that fits; where it named internal work, rewrite it for the reader.
+4. **Set `package.json` to the newest reconstructed version** with `npm version <x.y.z> --no-git-tag-version`.
+5. **Record it in the app's own document**: the date history was reconstructed, the range it covers, and that tags start at the first release cut under this process — reconstructed versions are untagged, because no single commit marks each one.
+
+Never invent releases to fill gaps, and never merge two old entries into one version: the history is a record, not a narrative.