@nusoft/nuos-build-catalogue 0.11.0 → 0.14.0

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.]

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

@@ -1,30 +1,34 @@
 # Decisions
 
-> Architectural commitments made by this project. Each decision lives in its own D-NNN file. Decisions are dated, justified, and have a status (`accepted`, `superseded`, `withdrawn`).
+A **decision** is a choice that's been made and shouldn't drift. Once accepted, a decision isn't edited — if circumstances change, you file a new decision that supersedes the old one and link forward. Decisions are the project's load-bearing commitments: the things future work has to honour. See [the glossary](../GLOSSARY.md#decision) for the full definition.
 
 ## Index
 
 | ID | Title | Status | Date |
 | --- | --- | --- | --- |
-| _none yet — see the template_ | | | |
+| _none yet — file your first one with `/decision-new` or `nuos-catalogue decision create`_ | | | |
 
-## How to add a decision
+## When to file a decision
 
-1. Copy `D001-template.md` to `DNNN-short-title-with-dashes.md` (next available number)
-2. Fill in the template
-3. Add a row to the table above
-4. If the decision affects a work unit's acceptance criteria, link it from the WU
-5. If the decision supersedes a prior one, mark the prior one's status as `superseded` and link forward
+- You're choosing between two reasonable approaches and want the choice to stick
+- You're adopting a constraint future work will need to honour (e.g. "all data stays on-device", "no third-party trackers")
+- You're overriding something previously decided — file the supersede; don't silently shift
+- You're committing to a technology, a deployment target, a major design principle
 
-## When to write a decision
+> Example: "D003 — All overnight processing happens on the school's own server, never in the cloud."
 
-- An architectural commitment is being made
-- Two reasonable approaches are being chosen between
-- A constraint is being adopted that future work will need to honour
-- A prior decision is being overridden (write the supersede; don't silently shift)
+## When NOT to file a decision
 
-## When NOT to write a decision
+- The choice is an implementation detail and easy to reverse
+- It belongs inside a work unit's notes — local to that work unit, not a project-wide commitment
+- The matter is still open and unresolved — file it as an **open question** ([Q-NNN](../open-questions/_index.md)) instead
 
-- The choice is implementation-detail and easy to reverse
-- The work unit's notes are sufficient to capture the rationale
-- The matter is open and unresolved — file it as an open question (Q-NNN), not a decision
+## What never to do
+
+**Never edit an accepted decision file.** The pre-commit hook will block it. If you need to change something material, file a new decision that supersedes the old one — `nuos-catalogue decision supersede D003 --by=D012 --reason="..."`. Typo or link fixes that don't change meaning are the only edits allowed.
+
+## How to file one
+
+Easiest way: run `/decision-new` (or `nuos-catalogue decision create`). The AI walks you through the prompts and files the result with a fresh D-NNN handle.
+
+The file is short — a one-paragraph context, the decision itself in one sentence, why it was made, and what it commits future work to. It doesn't need to be long. It needs to be unambiguous.

package/templates/starter-kit/docs/build/design-system/_index.md

@@ -0,0 +1,57 @@
+# Design System
+
+The **design system** is the shared visual and interaction language every part of {{PROJECT_NAME}}'s user-facing experience uses. End-to-end: design tokens (colour, type, spacing, motion) → components (buttons, cards, navigation) → patterns (form layouts, page templates) → voice (microcopy, error messages) → accessibility commitments. Every per-surface file in `ui-ux/` references this register. See [the glossary](../GLOSSARY.md#design-system) for the full definition.
+
+## Why a design system from the start
+
+Many projects sprout UI/UX surfaces first and add a design system later as a "consistency pass". By then the surfaces are inconsistent, components are duplicated, and harmonising them takes longer than building them in the first place. This catalogue requires a design system to exist before per-surface files are written. Phase C of planning produces both, in parallel.
+
+If a change to a colour, a heading style, a button shape, or an error message tone needs to happen, it happens **here**, once. Every surface that references the design system picks up the change. That's the system's load-bearing job.
+
+## Index
+
+| File | What it captures |
+| --- | --- |
+| `tokens-colour.md` | Colour palette, semantic colour roles |
+| `tokens-typography.md` | Type scale, font families, line heights, weights |
+| `tokens-spacing.md` | Spacing scale, layout grid, breakpoints |
+| `tokens-motion.md` | Easing curves, duration scale, motion principles |
+| `tokens-radius-elevation.md` | Border radii, shadow scale, elevation tokens |
+| `components/_index.md` | Index of components with status |
+| `patterns/_index.md` | Index of recurring page-level patterns |
+| `voice.md` | Voice, tone, microcopy principles |
+| `accessibility.md` | Project-wide accessibility commitments |
+
+Each section is filled in during the UI/UX + Design System phase of planning (phase C).
+
+## What status means for design system pieces
+
+- 🔵 **proposed** — drafted, not yet adopted across surfaces
+- 🟡 **in flight** — being refined; surfaces may reference older + newer simultaneously
+- 🟢 **active** — in use; the canonical version
+- ⚫ **deprecated** — kept for reference but no new surfaces should use it; existing surfaces should migrate
+
+## How design system pieces connect to everything else
+
+- Every UI/UX surface in `ui-ux/` references design-system pieces by name
+- Architecture modules that involve UI reference the surfaces (and thereby the design system)
+- Decisions that materially change a token, component, or voice principle are filed in `decisions/`
+- Work units that ship UI either consume the design system (most cases) or extend it (when a new component or pattern is needed)
+
+## When the design system gets populated
+
+During Phase C of planning (UI/UX + Design System). The AI walks you through:
+
+1. **Voice and tone first** — how does {{PROJECT_NAME}} sound when it speaks?
+2. **Tokens** — colour, type, spacing, motion. The atomic units.
+3. **Components** — the buttons, cards, navigation, forms. Each with variants, states, and accessibility commitments.
+4. **Patterns** — how components combine into recurring page-level layouts.
+5. **Accessibility commitments** — what the project promises end-to-end.
+
+You don't need to design every component upfront. The first pass establishes the language; components get added as work units need them. But the **language exists from the start** — every surface references it from day one.
+
+## How to add a design system piece
+
+During planning: the AI walks you through it.
+
+Outside planning: each piece is a standalone file with its own template (see the relevant subdirectory). For a new component, copy `components/_template.md` to `components/<name>.md`. For a new pattern, copy `patterns/_template.md`. Tokens are edited directly in the `tokens-*.md` files.