@nusoft/nuos-build-catalogue 0.12.0 → 0.14.1

package/templates/protocols/wu-new.md

@@ -1,52 +1,77 @@
 # wu-new
 
-Create a new work unit (WU) for this NuOS Build Method project.
-
-If arguments are provided (`$ARGUMENTS` for OpenCode/Claude Code, prompt-supplied for Codex), use them as the WU title; otherwise prompt the operator for the title.
-
-The WU template carries the **six-field outcome shape** (per D046): persona link, trigger, walkthrough with failure paths, verification (= acceptance criteria), contracts produced, contracts consumed. For infrastructure WUs (build, publish, hardening, refactors) the persona/trigger/walkthrough fields are marked `N/A — infrastructure WU` and the rest is unchanged.
-
-Steps:
-
-1. **Determine the next available WU number.** Scan `docs/build/work-units/` and `docs/build/work-units/done/` for the maximum 3-digit prefix. The new number is max + 1.
-2. **Slugify the title** — lowercase, dashes for spaces, no special characters, max 60 chars.
-3. **Ask the operator: is this an outcome WU (a user-facing capability) or an infrastructure WU (build, publish, hardening, refactor)?** If outcome, walk the full six-field flow. If infrastructure, skip persona/trigger/walkthrough and ask for the technical artefacts directly.
-4. **Generate the file** at `docs/build/work-units/<NNN>-<slug>.md` from the template at `starter-kit/docs/build/work-units/001-template.md`. Replace placeholders with operator-supplied values.
-5. **Prompt the operator (outcome WU) for:**
-   - **Persona** — which P-NNN persona does this outcome serve? If none exists yet, prompt to run `persona-new` first. For paired outcomes (a customer-side outcome paired with an organiser-side one), capture both persona links.
-   - **Trigger** — the real-world event that makes this outcome necessary. Not a UI click; the event in the persona's life that created the need.
-   - **Outcome** — one paragraph. Apply the single-sentence test: *"What will be true when this is done that is not true now?"* That sentence is the outcome.
-   - **Walkthrough** — numbered steps from the persona's perspective. For each step, surface the **five failure-path injection points**: (1) what if the persona cannot complete this step in one sitting? (2) what if the information is incorrect or missing? (3) what if the system itself fails? (4) what if the persona makes a mistake? (5) what if they realise immediately afterwards they used the wrong information? Failure handling lives inline at each step, not as a separate section.
-   - **Acceptance criteria (= verification)** — 5 to 10 criteria, each phrased as an inspection that passes or fails. Apply the auditor's-question test: *"Can a third-party reader confirm 'yes, this is shipped' by inspection alone?"* Each criterion must be evaluable by a person looking at the running system, not inferred from technical state.
-   - **Contracts produced** — what this WU makes available to other WUs once it lands, in domain language. Not "a row in the bookings table"; "a confirmed booking record, linked to a specific customer and a specific event".
-   - **Contracts consumed** — what must already exist before this WU can run. Each entry should map to another WU's `Contracts produced` field. If something this WU consumes is not produced by any WU in the plan, surface that gap immediately — file it as an open question or a new WU before this one starts.
-   - **Dependencies** — existing WU numbers this depends on (drawn from the contracts-consumed mapping; blank if none).
-   - **Decision implemented** — D-NNN if any (blank for none).
-   - **Forward-compatibility commitments** — if this WU's shape decisions affect later WUs, name them (per Pattern C).
-6. **Prompt the operator (infrastructure WU) for:**
-   - **Outcome** — single-sentence test as above.
-   - **Acceptance criteria** — same discipline.
-   - **Dependencies, decision implemented, forward-compatibility commitments** — same as outcome WU.
-   - **Persona / Trigger / Walkthrough** — auto-filled with `N/A — infrastructure WU.`
-   - **Contracts produced** — list the technical artefacts (e.g., "`@nusoft/nuwiki@0.1.4` published privately on npm").
-   - **Contracts consumed** — list the WUs whose output this WU builds on.
-7. **Apply the four quality traps** to the outcome before saving (operator review, not enforced by tooling today):
-   - **Vagueness:** could this outcome be implemented in more than one way that satisfies its wording but produces different user experiences?
-   - **Technical language:** does any part describe implementation rather than behaviour?
-   - **Happy path only:** does the walkthrough describe only what happens when everything goes right?
-   - **Kitchen sink:** does this WU try to do more than one thing? Could it be split into two outcomes with separate triggers and separate verification?
-
-   Surface any traps that fired and offer to rewrite the affected section before saving.
-8. **Add a row to `docs/build/work-units/_index.md`** in the appropriate phase section, with status `🟢 ready` (or `🔵 proposed` if dependencies aren't met).
-9. **If the WU cites a P-NNN, update that persona's `Used by WUs` list** to include the new WU.
-10. **Surface to the operator:**
-    - The new WU file path (clickable)
-    - The row added to `_index.md`
-    - Any inferred dependencies that should be confirmed
-    - Any quality traps that fired and were addressed (or deferred to a later refinement)
-
-**Discipline:** every acceptance criterion must be checkable by inspection, not described as a feature. *"The login page works"* is not an acceptance criterion. *"When a user submits a valid form, a row appears in `users` and an audit entry in `audit_events`"* is.
-
-**On the six-field shape (per D046):** the planning depth is what makes the catalogue durable. Skipping persona/trigger/walkthrough for an outcome WU produces a feature wearing an outcome-shaped name. Skipping contracts produced/consumed produces an outcome that integrates with nothing. The fields are not bureaucracy; each one closes a category of silent assumption the LLM teammate would otherwise fill in invisibly.
-
-If the operator pushes back on the auto-numbered slug or wants to adjust acceptance criteria, accommodate. The catalogue's strength is that the operator is in charge of the substance; the protocol just makes sure the substance is recorded properly.
+You are filing a new **work unit** for a project that uses the **NuOS Build Method catalogue**. A work unit is one concrete thing the project will build. The catalogue's value compounds as work units accumulate notes — every session adds to the record of what was attempted, what worked, what didn't, what was learned.
+
+**The operator is most likely a domain expert, not a software engineer.** Plain English throughout. Use their words. Define any term you use that isn't obvious from context.
+
+---
+
+## Step 1 — Ask what kind of work unit this is
+
+By default, walk the **simple shape** — four conversational questions. Use it for everyday product work. The full shape (13 fields, infrastructure language, contracts produced/consumed) is opt-in via `--full`; suggest it only if the operator is filing infrastructure work (build pipelines, publishing flow, refactors).
+
+> "Quick check before we file this: is this one piece of user-facing work — a feature, a screen, an outcome someone will use — or is it infrastructure (a build pipeline, a refactor, a publish flow)?"
+
+If user-facing → simple shape. If infrastructure → full shape.
+
+## Step 2 — Walk the four-field simple shape (the default)
+
+Ask in conversation; don't read out the four fields as a list. Weave them.
+
+1. **Title** — *"In five words or so, what's this work unit about?"*
+2. **Outcome** — *"What's true after this ships that isn't true now? Just a sentence."*
+3. **Walkthrough** — *"Tell me a story. Walk me through what [persona name] does when this is in place. What do they see? What do they do? And what could go wrong — what if information's missing, or the system fails, or they make a mistake?"*
+4. **How we'll know it's done** — *"List 3 to 6 things we could check to know this is done. Each one should be either yes or no — not 'better' or 'worse'."*
+
+Also ask:
+
+- **Which persona is this for?** Show them the list from `docs/build/personas/`. If none yet, file a persona first via `/persona-new`.
+
+## Step 3 — Walk the full shape (only when --full or for infrastructure work)
+
+The full shape has the four fields above plus:
+
+- **Trigger** — the real-world event in someone's day that makes them need this
+- **Contracts produced** — what this work unit makes available to other work units once it lands; in everyday language
+- **Contracts consumed** — what must already be in place for this work unit to start
+- **Dependencies** — other work units this depends on
+- **Decision implemented** — D-NNN if this work unit realises a specific decision
+- **Forward-compatibility commitments** — any choices made here that affect later work units
+
+For infrastructure work, persona / trigger / walkthrough are marked `N/A — infrastructure work`.
+
+## Step 4 — File the work unit
+
+1. **Number it.** Scan `docs/build/work-units/` and `docs/build/work-units/done/` for the highest existing 3-digit prefix; new number is max + 1.
+2. **Slugify the title.** Lowercase; dashes for spaces; no special characters; cap at 60 chars.
+3. **Write the file** at `docs/build/work-units/NNN-slug.md`. Use `001-template-simple.md` for the simple shape, `001-template-full.md` for the full shape.
+4. **Add a row** to `docs/build/work-units/_index.md`. Status `🔵 proposed` if dependencies aren't met yet, otherwise `🟡 in flight` (if work is starting now) or leave `🔵 proposed` if it's queued.
+5. **If a persona is cited**, update that persona's "Used by" list to include this work unit.
+
+## Step 5 — Surface to the operator
+
+Tell them in plain English:
+
+- Where the file landed (clickable path)
+- That the index was updated
+- Anything you noticed during the conversation that's worth flagging (e.g. "this work unit and WU 007 both touch the morning briefing — they might depend on each other; do you want to link them?")
+- The next concrete action
+
+## What to watch for
+
+Four quality issues come up during a work-unit conversation. Surface them gently, don't lecture:
+
+- **Vagueness** — *"Could this be built in two different ways and both satisfy what you've said? Worth tightening?"*
+- **Technical language slipping in** — *"You said 'an API endpoint that returns a JSON response' — what does the teacher actually see or do?"*
+- **Only the happy path** — *"What happens if the data isn't ready, or they hit save twice?"*
+- **Too big** — *"This feels like two work units to me. Want to split it?"*
+
+The catalogue's strength is that the operator is in charge of the substance; the protocol just makes sure the substance gets captured properly.
+
+---
+
+## Why this matters
+
+Work units are how the project's work compounds. A work unit filed today is a hook for a future session to add notes against, a contract for other work units to plug into, an entry in the project's audit trail. Sloppy work units rot. Sharp work units accumulate value.
+
+If the operator wants to skip a question because the answer feels obvious, ask one more time gently — and then let them skip. The catalogue doesn't enforce content quality; it enforces *capture*. Captured-but-thin is better than not captured at all.

package/templates/starter-kit/docs/build/GLOSSARY.md

@@ -0,0 +1,115 @@
+# Glossary
+
+Every term this catalogue uses, defined once in plain English. If you see a term you don't recognise in any file, this is where to look.
+
+## Acceptance Criteria
+
+How you'll know a piece of work is done. A short list — usually 3 to 6 lines — where each line is something you can check by looking. Each should be either yes or no, not "better" or "worse". Often abbreviated **AC**.
+
+> Example: "When a teacher opens the morning briefing, they see their three highest-need students at the top of the screen."
+
+## Architecture
+
+The big pieces of your project and how they fit together. Filed in `architecture/`. Different from contracts: architecture is about *what the pieces are*; contracts are about *what they exchange*.
+
+## Catalogue
+
+This whole folder — `docs/build/` — and everything in it. It's your project's memory: who it's for, what's built, what's been decided, what's still unknown. The catalogue is updated at the start and end of every session so future-you (or anyone joining) can pick up without needing to be told.
+
+## Drift (and why we never let it happen)
+
+Drift is when the project's reality diverges from what the catalogue says. Someone makes a decision in conversation and forgets to file it. Someone changes their mind about a persona but the persona file still says the old thing. Two weeks later a new contributor reads the catalogue, builds against what it says, and the work is wrong.
+
+**The no-drift rule is the catalogue's load-bearing commitment.** Every decision made in conversation gets saved to the catalogue before the session ends. Every change to an existing artefact flows through the protocol that keeps the catalogue and its search index in sync. The pre-commit hook blocks modifications to accepted decisions (so you can't edit them silently — you have to file a superseding decision and link forward). The post-commit hook auto-refreshes the search index after every commit, so what the AI finds when you ask "what did we decide about X?" is always current.
+
+If the AI is asked something and the answer would normally come from project memory but the memory hasn't captured something said in conversation, **the AI should pause the conversation and file the missing artefact first**, then resume. Drift isn't a small problem; it's the failure mode that makes the whole catalogue worthless.
+
+## Contract
+
+What a piece of your project guarantees it will provide to other pieces, and what it expects from them in return. Filed one per major piece, in `contracts/`. Written in everyday language — "facts about the world the system now knows" — not database tables or API endpoints.
+
+> Example: "Overnight Consolidation contract — produces a per-student plan for tomorrow, ranked by need. Consumes today's record of every interaction with that student."
+
+## Decision
+
+A choice that's been made and shouldn't drift. Filed in `decisions/` as **D001**, **D002**, etc. Once a decision is accepted, it doesn't get edited — if circumstances change, file a new decision that supersedes the old one and link forward. Decisions are the project's load-bearing commitments.
+
+> When to file one: when you're choosing between two reasonable approaches; when you're adopting a constraint future work must honour; when you're overriding something previously decided.
+
+## Design System
+
+The shared visual and interaction language every part of the user-facing project uses. Filed in `design-system/`. Includes:
+
+- **Tokens** — colour, typography, spacing, radius, shadow, motion — the smallest atomic units
+- **Components** — the buttons, inputs, cards, modals, navigation elements; each with its variants, states, and accessibility commitments
+- **Patterns** — how components combine into recurring layouts (forms, lists, page templates)
+- **Voice & tone** — how the project speaks in writing (microcopy, error messages, empty states)
+- **Accessibility commitments** — what the project promises (e.g. AA contrast minimum, keyboard-navigable, screen-reader-tested)
+
+The design system is end-to-end: every per-surface file in `ui-ux/` references it; every implementation in code consumes it. Changes to design tokens propagate everywhere automatically, so the system stays consistent as it grows.
+
+## Handle
+
+The short identifier for any catalogue item: **WU 001**, **D012**, **Q003**, **P002**, **R005**, **M003**. Letters identify the register (Work Unit, Decision, Open Question, Persona, Risk, Map). Numbers run sequentially as items are filed.
+
+## Map
+
+A picture of where the project is going. Three of them by default:
+
+- **Map 1 — The Horizon**: the whole journey in plain language, written once and updated only when the destination changes
+- **Map 2 — Phases in Detail**: what each phase delivers, with entry and exit conditions
+- **Map 3 — The Near-Term Plan**: what's happening this week or this month
+
+Filed in `maps/`.
+
+## Open Question
+
+Something the project hasn't decided yet but might need to. Filed in `open-questions/` as **Q001**, **Q002**, etc. When an open question gets resolved, it becomes a Decision (or it becomes obvious and gets closed). The open-questions register is where uncertainty lives until it's ready to settle.
+
+## Outcome
+
+What's true after a piece of work ships that wasn't true before. Written as one sentence. The single-sentence test: *can you say what changed in the world?*
+
+> Example: "Teachers can see tomorrow's high-priority students before they go home tonight."
+
+## Persona
+
+One specific person the project serves. Not a market segment ("teachers"), not a demographic ("women aged 30-50") — one person with a name and a situation. Personas are first-class because everything downstream — work units, UI/UX surfaces, contracts — hangs off who specifically you're building for. Filed in `personas/` as **P001**, **P002**, etc.
+
+The seven dimensions of a persona: identity, reality (where they are when they need this), psychology, trigger (what brought them here), history, success (what done looks like for them), constraints (what they cannot or will not do).
+
+## Risk
+
+Something that could go wrong and would matter if it did. Filed in `risks/_index.md`. Severity scale:
+
+- **High** — blocks work or threatens a decision
+- **Medium** — would slow things materially
+- **Low** — worth tracking; not blocking
+
+## Session
+
+A period of focused work — could be an hour, could be an afternoon. Each session starts with `/start-of-session` (which shows you where the project is) and ends with `/end-of-session` (which writes down what just happened). Filed in `sessions/`, one entry per session.
+
+## Surface
+
+A piece of the user-facing experience. A page, a screen, a modal, a command-line prompt, an email the user receives — anything they see or interact with. Each surface gets its own file in `ui-ux/`. Different from a screen mockup: a surface file says *who uses it, what they see, what they do, what happens next, which contracts it touches.*
+
+## Trigger
+
+The real-world event that makes someone need an outcome. Not a UI interaction — the moment in the persona's day or week that creates the need.
+
+> Example trigger for a teacher persona: "It's 4pm on a Tuesday. The teacher is finishing up. Tomorrow's class includes three students with high SEN needs and one new arrival." That's the trigger. "Clicking the planning button" is not.
+
+## UI/UX
+
+Short for "user interface and user experience". The catalogue treats UI/UX as a first-class register at `ui-ux/`. One file per surface (see above). Captures the user-facing shape of the project: what people see, what they do, what happens.
+
+## Walkthrough
+
+A story of what happens, told from the persona's perspective. Numbered steps describing what they do, what they see, what happens next. Walkthroughs include failure paths — what happens if information is missing, if they make a mistake, if the system fails, if they need to come back tomorrow. Walkthroughs are how outcomes get checked: if you can walk through the persona's day with this in place, you understand what you're building.
+
+## Work Unit
+
+One concrete thing the project will build. Filed in `work-units/` as **WU 001**, **WU 002**, etc. Each has a title, an outcome, a walkthrough, and acceptance criteria. Often abbreviated **WU**. Work units are the unit of progress — when one is done, something has changed in the world.
+
+> When to file one: when you're about to start work that you'll want to track. The catalogue's value compounds with accumulated work-unit notes — every session adds to the record of *what was attempted, what worked, what didn't, what was learned.*

package/templates/starter-kit/docs/build/STATE.md

@@ -1,14 +1,26 @@
-# {{PROJECT_NAME}} — Always-Current State
+# {{PROJECT_NAME}} — where we are right now
 
-> The single snapshot read at the start of every session. If anything important is not here, it is not real. Update this file at the end of every session via the end-of-session protocol.
+> This file is the snapshot read at the start of every session. If anything important about the project's current state is not here, it is not real. The end-of-session protocol updates this file every time work stops.
 
 **Last updated:** {{TODAY}}
-**Active phase:** Phase 0 — bootstrap
-**Active work unit:** WU 001 — [first work unit name]
+
+## Planning progress
+
+This project is at the start of its planning arc. The AI will walk you through five phases before you begin building. Each phase is its own session.
+
+| Phase | What it produces | Status |
+| --- | --- | --- |
+| A — Orientation | Project description, 1-3 personas, the horizon map | 🔵 not yet started |
+| B — Architecture & Contracts | The major pieces of the project and what they exchange | 🔵 not yet started |
+| C — UI/UX + Design System | The user-facing surfaces and the shared visual language | 🔵 not yet started |
+| D — Maps | Phases of work and the near-term plan | 🔵 not yet started |
+| E — Initial Work Units | The first 5-10 things to build, in dependency order | 🔵 not yet started |
+
+When you run `/start-of-session` on this fresh project, the AI will see this tracker and offer to begin Phase A.
 
 ## What is currently in flight
 
-[One paragraph describing what work is happening right now. Edit when work changes shape.]
+[Filled in once Phase A is underway. Today, this is a brand-new catalogue with no work in flight yet.]
 
 ## What just shipped
 
@@ -16,7 +28,7 @@ Nothing yet — this catalogue was just adopted on {{TODAY}}.
 
 ## What is next
 
-[The next concrete action. Should be specific enough that an LLM teammate can pick it up and start without further context.]
+Run `/start-of-session` to begin. The AI will read this file and walk you through Phase A of planning.
 
 ## Open questions blocking progress
 
@@ -32,16 +44,18 @@ None currently filed. Filed risks live in [`risks/_index.md`](risks/_index.md).
 | --- | --- | --- |
 | _none yet_ | | |
 
-## Work units in flight
+## Active work units
+
+| Work Unit | Status | Notes |
+| --- | --- | --- |
+| _none yet — phase E of planning produces the first batch_ | | |
 
-| WU | Status | Owner | Notes |
-| --- | --- | --- | --- |
-| WU 001 | 🟡 in flight | — | First work unit |
+## How to read this file
 
-## Status legend
+- **Planning progress** shows where you are in the 5-phase arc that takes a brand-new project to "ready to build"
+- **What is currently in flight** describes ongoing work; updated when work changes shape
+- **What just shipped** notes the most recent completion(s)
+- **What is next** points at the immediate concrete action
+- Below: open questions, risks, decisions, and active work units — pulled from their respective registers for quick scanning
 
-- 🔵 **proposed** — written down, not yet started
-- 🟡 **in flight** — actively being worked on
-- 🟣 **built / awaiting review** — implementation done, review pending
-- ✅ **merged / shipped** — complete and integrated
-- 🔴 **blocked** — cannot proceed; see notes for blocker
+This file is the project's executive summary. The detail lives in the register files; this is the one-screen view that says where the project is.

package/templates/starter-kit/docs/build/WELCOME.md

@@ -0,0 +1,79 @@
+# Welcome — what this catalogue is, and how it works
+
+You're looking at the **catalogue** for {{PROJECT_NAME}}. It's your project's memory. Read this once and you'll understand the whole shape. It takes five minutes.
+
+## What the catalogue is for
+
+A real project — one that handles real complexity — has more moving parts than anyone can hold in their head. Who's it for? What does each piece do? What did we decide last month? What are we still unsure about? What's at risk? Without a place to keep all of this, you end up rebuilding the same understanding over and over, every time you sit down to work, every time someone new joins, every time you open a fresh chat with an AI.
+
+The catalogue solves that. Everything load-bearing about your project lives here in plain Markdown files, organised into ten **registers**. The catalogue stays current through two protocols — `/start-of-session` and `/end-of-session` — that run at the bookends of every period of work.
+
+You don't have to remember any of it. The catalogue does.
+
+## The principle that makes it work
+
+**Project memory never drifts from project reality.** Every decision made in conversation gets saved before the session ends. Every change to an existing piece flows through a protocol that keeps the catalogue and its search index in sync. The pre-commit hook blocks silent edits to accepted decisions. The post-commit hook auto-refreshes the search index after every commit. The AI you're working with reads from the catalogue and writes back to it; what it finds when you ask "what did we decide about X?" is always current.
+
+If anything ever feels out of date, that's a bug, not a feature. The repair is to file the missing piece before continuing.
+
+## How a project gets built
+
+A project starts with a 5-phase **planning arc** the AI walks you through. Each phase is its own session. By the end of the arc, the catalogue has the substrate that makes everything downstream coherent.
+
+1. **Orientation** (~30 min) — what is this project, who's it for. You'll describe the project in your own words and name 1-3 specific people it serves.
+
+2. **Architecture & Contracts** (~60-90 min) — what are the major pieces, what does each one provide to the others. The shape of the system in everyday language.
+
+3. **UI/UX + Design System** (~60-90 min) — every page, screen, modal, or command the user touches, plus the complete design system (colour, typography, spacing, components, patterns, voice, accessibility commitments) that every surface uses. End-to-end: a surface in `ui-ux/` references components in `design-system/`; a component carries tokens; tokens propagate everywhere. The system stays consistent as it grows because everything references one shared language.
+
+4. **Maps** (~45 min) — the journey from now to done. Phases. What's happening this week, this month.
+
+5. **Initial Work Units** (~60 min) — the first 5 to 10 concrete things to build, ordered by what depends on what.
+
+After phase 5, you start building. Every session from then on follows the same shape: `/start-of-session` shows where you are, you work, `/end-of-session` writes down what just happened.
+
+## The eleven registers
+
+| Register | What lives here | Handle |
+| --- | --- | --- |
+| **personas/** | One file per specific person the project serves | P001, P002… |
+| **maps/** | The horizon, the phases, the near-term plan | M001, M002, M003 |
+| **architecture/** | What the major pieces are and how they relate | (per-module files) |
+| **contracts/** | What each piece provides to the others | (per-contract files) |
+| **ui-ux/** | Every user-facing surface (page, screen, command, email) | (per-surface files) |
+| **design-system/** | The shared visual + interaction language every surface uses (tokens, components, patterns, voice) | (per-piece files) |
+| **decisions/** | Choices made and not to be drifted from | D001, D002… |
+| **open-questions/** | Things we haven't decided yet | Q001, Q002… |
+| **work-units/** | Concrete things being built | WU 001, WU 002… |
+| **risks/** | Things that could go wrong | R001, R002… |
+| **sessions/** | A log of every period of work | one file per session |
+
+The full vocabulary lives in [`GLOSSARY.md`](GLOSSARY.md). Read it once; come back when you need it.
+
+## The three commands you need
+
+Everything else is automatic.
+
+```text
+npx @nusoft/nuos-build-catalogue init   — once, when starting a new project
+/start-of-session                       — every time you begin working
+/end-of-session                         — every time you stop
+```
+
+`/start-of-session` reads where you are, what just happened, what's next, and surfaces any blockers. If this is the very first session on a fresh project, it routes you into the orientation phase of the planning arc.
+
+`/end-of-session` writes down what was attempted, what worked, what didn't, what was learned. It commits. The catalogue's search index updates in the background.
+
+That's it. The catalogue handles the rest.
+
+## What never to do
+
+- **Never close a session without `/end-of-session`.** Work that isn't written down is work that's lost.
+- **Never edit an accepted decision file.** If something changes, file a new decision that supersedes the old one. The pre-commit hook will block silent edits.
+- **Never make an architectural decision in conversation without filing it.** If the AI says "let's go with X" and you agree, file it as a decision *before moving on*. Drift is the failure mode that makes the catalogue worthless.
+
+## Where to go from here
+
+- **Brand new project?** Run `/start-of-session`. The AI will walk you through phase 1 of planning. By the end of today you'll have the project oriented.
+- **Returning to existing work?** Same — `/start-of-session` reads STATE.md, the latest session log, and the active work unit. You'll be told where you are and what's next within a minute.
+- **Want to look around first?** Open [`STATE.md`](STATE.md) for the current snapshot, [`maps/01-the-horizon.md`](maps/01-the-horizon.md) for the whole-project picture, or [`GLOSSARY.md`](GLOSSARY.md) for any term you don't recognise.

package/templates/starter-kit/docs/build/architecture/_index.md

@@ -0,0 +1,39 @@
+# Architecture
+
+The **architecture** register describes the major pieces of {{PROJECT_NAME}} and how they relate. Each major piece (module, service, surface, area of responsibility) gets its own file. The architecture is *what the pieces are*; the [contracts register](../contracts/_index.md) is *what they exchange*. See [the glossary](../GLOSSARY.md#architecture) for the full definition.
+
+## Index
+
+| Module | Purpose | Status |
+| --- | --- | --- |
+| _none yet — populated during the Architecture phase of planning (phase B)_ | | |
+
+## What goes in this register
+
+For each major piece of your project:
+
+- **What it does** — a paragraph in plain language
+- **Who's responsible for it** — which persona or role uses it most directly
+- **What it depends on** — other modules, external services, hardware
+- **What depends on it** — what would break if this module went away
+- **Open questions about it** — anything unresolved about its shape
+- **Links to relevant contracts** — what this module produces and consumes
+
+Architecture files are *what's true about each piece*; they're not implementation specs. Implementation lives in code; this register lives in the catalogue.
+
+## When the architecture register gets populated
+
+During the **Architecture & Contracts** phase of planning (phase B), after the orientation phase. The AI walks you through identifying the major pieces of your project — usually 3-7 modules for a starting project — and helps you file one architecture entry per module.
+
+## How architecture connects to everything else
+
+- Every work unit names which module it lives in
+- Every contract belongs to exactly one module (the one that owns it)
+- Every UI/UX surface references which modules it talks to
+- Architecture changes (a module splits, two modules merge, a new module enters scope) get filed as decisions
+
+## How to add a module
+
+During planning: the AI does this for you via `nuos-catalogue architecture create`.
+
+Outside planning: copy `module-template.md` to `<short-module-name>.md`, fill it in, and add a row to the table above. Use `nuos-catalogue architecture create` if you want the interactive prompts.

package/templates/starter-kit/docs/build/architecture/module-template.md

@@ -0,0 +1,47 @@
+# [Module name]
+
+> *Replace bracketed placeholders. Delete this hint block once filled in.*
+
+**Status:** 🔵 proposed / 🟡 in flight / 🟢 active / ⚫ retired
+**Owner:** [persona handle and name — or "infrastructure" if not user-facing]
+**Last updated:** {{TODAY}}
+
+## What this module does
+
+[One paragraph in plain language. Avoid implementation language. Describe the responsibility, not the code.]
+
+> Example: "The Overnight Consolidation module processes every interaction with a student during a school day and produces, by morning, a per-student plan ranked by need."
+
+## Who uses it directly
+
+[List the personas who interact with this module via UI/UX surfaces. Each as `[P001](../personas/P001-name.md)` with a one-line note on how they use it.]
+
+## What it depends on
+
+- **Other modules:** [list with links to their architecture files]
+- **External services:** [APIs, vendors, hardware]
+- **Hardware or infrastructure:** [if relevant]
+
+## What depends on it
+
+[What would break if this module went away or returned wrong results? List the affected modules + the affected user-facing surfaces.]
+
+## Contracts this module owns
+
+[List the contracts in `contracts/` that this module produces. One per row.]
+
+| Contract | What it provides |
+| --- | --- |
+| [contract handle/file] | [one-line description] |
+
+## Open questions about this module
+
+[Link to Q-NNN entries in `open-questions/` that affect this module specifically. If none yet, write _none currently_.]
+
+## Decisions specific to this module
+
+[Link to D-NNN entries that affect just this module. Cross-cutting decisions can stay in the decisions register without being linked here.]
+
+## Notes
+
+[Date-stamped notes about how this module has evolved. Use this section the way you'd use a work unit's notes section — what was tried, what worked, what didn't.]

package/templates/starter-kit/docs/build/contracts/_index.md

@@ -0,0 +1,39 @@
+# Contracts
+
+A **contract** is what one piece of the project guarantees it will provide to other pieces — and what it expects from them in return. Written in everyday language: "facts about the world the system now knows", not database tables or API endpoints. The contracts register is where the project commits to what each piece is responsible for. See [the glossary](../GLOSSARY.md#contract) for the full definition.
+
+## Index
+
+| Contract | Owner module | Status |
+| --- | --- | --- |
+| _none yet — populated during the Architecture phase of planning (phase B)_ | | |
+
+## What a contract captures
+
+For each major module, one contract describes:
+
+- **What this module produces** — the facts, capabilities, or guarantees other modules can rely on. *"After Overnight Consolidation runs, every active student has a tomorrow-plan ranked by need."*
+- **What this module consumes** — what must already be in place for this module to do its job. *"Overnight Consolidation needs today's interaction records for every active student."*
+- **What it does not provide** — things adjacent that someone might assume are included but aren't. Naming the negative space prevents drift.
+- **How it fails** — what happens if its inputs are missing, late, or wrong; what downstream modules can rely on as the failure behaviour.
+
+Contracts are **load-bearing commitments**. They're the boundaries between modules — and they don't drift silently. If a contract changes, that's an architectural decision that gets filed.
+
+## When the contracts register gets populated
+
+During the **Architecture & Contracts** phase of planning (phase B). The AI walks you through one contract per module. Each contract gets filed as you go.
+
+After planning, contracts evolve. Adding a new produced fact, or relaxing a consumed precondition, is usually a decision — file it in the decisions register and update the contract to match.
+
+## How contracts connect to everything else
+
+- Every contract belongs to exactly one module (the architecture file in `architecture/`)
+- Every work unit names which contract(s) it produces or consumes
+- Every UI/UX surface references the contracts it talks to
+- Contract changes get filed as decisions
+
+## How to add a contract
+
+During planning: the AI does this for you via `nuos-catalogue contract create`.
+
+Outside planning: copy `contract-template.md` to `<short-name>.md`, fill it in, and add a row to the table above. Or use `nuos-catalogue contract create` for the interactive prompts.

package/templates/starter-kit/docs/build/contracts/contract-template.md

@@ -0,0 +1,64 @@
+# Contract: [module name]
+
+> *Replace bracketed placeholders. Delete this hint block once filled in.*
+
+**Owner module:** [link to the architecture file for this module]
+**Status:** 🔵 proposed / 🟡 in flight / 🟢 active / ⚫ retired
+**Last updated:** {{TODAY}}
+
+## In one sentence
+
+[What does this module make true in the world? One sentence. *"Overnight Consolidation produces, by morning, a per-student plan ranked by need."*]
+
+## What this module produces
+
+[What facts, capabilities, or guarantees can other parts of the system rely on, once this module is in place? Use everyday language. Bullet list.]
+
+- [fact 1]
+- [fact 2]
+- ...
+
+## What this module consumes
+
+[What must already be true (data, signals, services) before this module can do its job? Bullet list, with links to other contracts where the input is produced.]
+
+- [input 1] — produced by [contract link]
+- [input 2] — produced by [contract link or "external — [source]"]
+- ...
+
+## What this module does not provide
+
+[The negative space. Things adjacent that someone might assume are included but aren't. Naming these prevents downstream confusion.]
+
+- [thing it doesn't do, despite proximity]
+- ...
+
+## How it fails
+
+[What happens when inputs are missing, late, or wrong? What can downstream modules rely on as the failure behaviour? *"If today's interaction records are missing, Overnight Consolidation skips that student in tomorrow's plan and surfaces a flag in the morning briefing."*]
+
+## Personas this contract serves
+
+[The personas whose outcomes depend on this contract. Linked to their P-NNN files.]
+
+## Work units that produce this contract
+
+[As work units ship that fulfil this contract, link them here. During planning this list is empty; it fills in as the project builds.]
+
+| WU | Status |
+| --- | --- |
+
+## Work units that consume this contract
+
+[Work units elsewhere in the project that rely on this contract being in place.]
+
+| WU | Status |
+| --- | --- |
+
+## Decisions that shaped this contract
+
+[Link to D-NNN files that materially shaped what this contract is. Examples: "D003 — All overnight processing happens on-device".]
+
+## Notes
+
+[Date-stamped notes about how this contract has evolved.]