@nusoft/nuos-build-catalogue 0.11.0 → 0.14.0

package/templates/starter-kit/docs/build/maps/01-template.md

@@ -1,126 +1,29 @@
-# Map [number] — [title]
+# Map 1 — The Horizon
 
-> **The canonical operational plan for [workstream name].** Sequenced work units from "today" to "[goal state]", each with phase-step decomposition, contracts realised, and verification gates anchored in target-repo files. If a step isn't here, it isn't planned. This map is the single source of truth for [workstream name] — read this before any other planning surface.
+> The whole journey from where we are now to a working {{PROJECT_NAME}}. One picture of the whole forest. No jargon. If you read only one map, read this one.
 
-> Replace the bracketed placeholders. Delete this hint block.
+> *This template is filled in during the Orientation phase of planning. The AI walks you through the questions in conversation; you don't need to write this by hand.*
 
-## How to read this map
+## What this project is
 
-The catalogue's decomposition (which this map operationalises):
+[One paragraph in plain language. Describe what {{PROJECT_NAME}} is for someone who has never heard of it. What does it do? What problem does it solve? Why does it need to exist?]
 
-```
-Contracts                deep-module surfaces — what the system IS
-   │
-   │ realised by
-   ▼
-Maps                     strategic plan — when, in what order, why
-   │
-   │ ordering
-   ▼
-Work units (WUs)         executable units against contract surfaces — what ships
-   │
-   │ decomposed into
-   ▼
-Phases                   sub-units when a WU is too large for one shot
-   │
-   │ decomposed into
-   ▼
-Phase steps              the actual moves; each has acceptance + verification gate
-```
+## Who it's for
 
-Maps own **sequencing and outline**. WU files own **acceptance design and execution log**. Contracts own **the surface specs**. Sessions own **the temporal history**. No other planning artefact.
+[List the personas filed in `personas/`. One line per person, with their P-NNN handle and a sentence about who they are. The personas register has the detail.]
 
-## The five agentic-age patterns this map enforces
+## What "done" looks like
 
-These are the load-bearing discipline for agent-led building (codified in [`THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) §post-Phase-3 epistemic discipline):
+[Describe the destination. Not how you'll get there — the place itself. When {{PROJECT_NAME}} is finished, what's true in the world that wasn't true before? Write this as 3-6 short sentences a layperson can read.]
 
-1. **Verification gates anchored in target-repo files** — every phase step names a specific file/grep/test as acceptance proof. Closes the spec-vs-reality drift loop.
-2. **Maps as single canonical plan** — story-level detail lives here, not in side docs. Closes the proliferation loop.
-3. **Contracts as immutable truth** — phase steps cite the contract surface they realise. Closes the "agent makes things up" loop.
-4. **Hedge words as stop signal** — "likely", "presumably", "should be" indicate a missing verification step.
-5. **Design alternatives before implementation** — Ousterhout's "design it twice"; produce at least two fundamentally different designs, evaluate, then pick or hybrid before generating non-trivial implementation. Phase steps that generate implementation carry an implicit prerequisite: design alternatives recorded in WU notes.
+## The shape of the journey
 
-## Where we are now ([date])
+[Two or three paragraphs in plain language describing the major stages — not by name yet, in narrative form. *"First we'll build X so that Y is possible. Once Y is in place, we can do Z, which is what really matters for [persona]. The last stretch is making it reliable enough for real classrooms."* — that kind of writing. The map should read like a story, not a Gantt chart.]
 
-| WU | Title | Status | Repo / branch |
-|---|---|---|---|
-| [WU number] | [title] | [🔵 ready / 🟡 in flight / 🟣 in_review / ✅ done / 🔴 blocked] | [repo + branch] |
+## What's not in scope
 
-## What "[goal state]" means
+[List 3-5 things that *might* be confused with the project but aren't part of it. This is load-bearing — every project has things adjacent to it that people will assume are included. Naming them as out-of-scope prevents drift.]
 
-The workstream is **complete** when all of the following hold simultaneously:
+## How this map changes
 
-1. [Outcome 1]
-2. [Outcome 2]
-3. [Outcome 3]
-4. ...
-
-(List the verifiable end-state of the workstream. Each outcome should be an observable fact about the system, not a process step.)
-
-## Critical path
-
-```
-[diagram of WU sequencing with dependencies — use ASCII art or describe in prose]
-```
-
----
-
-## WU [number] — [title]
-
-| Field | Value |
-|---|---|
-| Contracts realised | [which contract surface(s) this WU fulfils] |
-| Status | [🔵 / 🟡 / 🟣 / ✅ / 🔴] |
-| Repo | [repo + branch] |
-| Estimate | [working days] |
-| Depends on | [upstream WUs / npm publishes / external] |
-
-**Design alternatives considered (Pattern N — before any non-trivial implementation step):**
-
-> If this WU includes any non-trivial architectural choice (schema, migration, integration shape, adapter, RBAC, audit, retention, error-handling), record at least two fundamentally different design candidates here before phase steps that generate implementation. State the chosen one and why. Delete this block if the WU is purely incremental work against an already-decided design.
-
-- **Option A:** [first fundamentally different design]. Trade-offs: [...]. Errors created: [...].
-- **Option B:** [second fundamentally different design]. Trade-offs: [...]. Errors created: [...].
-- *(Option C if useful)*
-- **Chosen:** [A / B / C / hybrid] because [...]. Records as: [WU notes / D-NNN decision file].
-
-| # | Phase step | Acceptance | Verification gate |
-|---|---|---|---|
-| 1 | [what move is being made] | [what proves it produced the intended outcome] | [specific file/grep/test the operator runs to confirm] |
-| 2 | ... | ... | ... |
-
-**Done when:** [the overall WU acceptance — usually "all N steps complete + canonical green line + integration test"].
-
-**Risks:** [anything that could derail the WU; mitigations].
-
----
-
-## WU [number] — [title]
-
-[Repeat the structure above for each WU on the critical path. Each WU with non-trivial design choices gets its own "Design alternatives considered" block; routine incremental WUs can omit it.]
-
----
-
-## What runs in parallel
-
-[List independent workstreams that don't gate the critical path.]
-
-## Trigger conditions for deferred WUs
-
-[List WUs that are deferred and what unblocks them.]
-
-## What this map is not
-
-- It does NOT describe [out-of-scope topic 1] — see [other doc].
-- It does NOT cover [out-of-scope topic 2] — see [other doc].
-
-## How to use this map
-
-- **At session start** — read this map plus the active WU's spec file. The map tells you which phase step is next + the verification gate; the WU spec tells you the deeper acceptance design.
-- **Mid-step** — if you find yourself writing a hedge word ("likely", "presumably", "should be"), stop. Run the verification gate's grep/test/file-read first. Replace the hedge with the result.
-- **At session end** — flip phase-step status here; if scope changed, edit the step description here (not in a side doc).
-- **When a phase completes** — flip the WU's phase status; update STATE.md to reflect; confirm the dependency graph still holds.
-
-## Pointers
-
-- [List relevant WU files, contracts, decisions, prior maps]
+This map is updated **only when the destination changes**. If "done" looks different than it did six months ago, that's a real horizon shift and the map gets rewritten. Day-to-day changes belong in Map 3 (the near-term plan) or in work-unit notes — not here.

package/templates/starter-kit/docs/build/maps/02-template.md

@@ -0,0 +1,52 @@
+# Map 2 — Phases in Detail
+
+> The middle zoom: how the journey from Map 1 breaks into phases, what each phase delivers, and what has to be true to enter or exit each one.
+
+> *This template is filled in during the Maps phase of planning (phase D), after architecture and contracts are in place. The AI walks you through it.*
+
+## Phases at a glance
+
+| # | Phase | What it delivers | Entry condition | Exit condition |
+| --- | --- | --- | --- | --- |
+| 0 | Foundation | The basic scaffolding (project set up, persona established, first decisions filed) | _project started_ | Catalogue has substance: 1+ persona, Map 1 done |
+| 1 | [phase name] | [what's shipped at end of phase] | [what must be true to start] | [what must be true to finish] |
+| 2 | [phase name] | [...] | [...] | [...] |
+| ... | | | | |
+
+[Fill in the phases the AI walks you through. Most projects have 3-6 phases. The last phase usually ends at "ready to ship to first real users".]
+
+## Phase 0 — Foundation
+
+**What ships in this phase:** [the project's basic understanding of itself — persona, horizon, initial architecture]
+
+**Entry condition:** A blank project; nothing yet decided.
+
+**Exit condition:** All of:
+
+- At least one persona filed
+- Map 1 (the horizon) written
+- Architecture and contracts roughed out
+- Initial design system tokens chosen
+- First few work units identified
+
+This phase is the planning arc itself. Phase 1 is where the first real work unit ships.
+
+## Phase 1 — [phase name]
+
+[Each subsequent phase gets a section like this. Include:]
+
+**What ships in this phase:** [end state]
+
+**Entry condition:** [what has to be true to start]
+
+**Exit condition:** [what has to be true to finish — verifiable, not aspirational]
+
+**Work units expected to ship in this phase:** [list of WU handles; the work-units register has the detail]
+
+**Risks during this phase:** [link to R-NNN entries in the risks register that apply specifically here]
+
+## How phases work in practice
+
+Phases are signposts, not gates. Work doesn't strictly stop at a phase boundary — but the catalogue's progress is best measured by which phases have completed. When you finish a phase, update STATE.md, file a session log noting the phase transition, and Map 3 (the near-term plan) gets a fresh outlook for the next phase.
+
+A phase can be revised. If you discover during Phase 2 that an assumption from Phase 1 was wrong, file the open question, file a decision if you've now resolved it, and update Map 2 to reflect what you actually know. The map's job is to match reality, not to be right the first time.

package/templates/starter-kit/docs/build/maps/03-template.md

@@ -0,0 +1,46 @@
+# Map 3 — The Near-Term Plan
+
+> The day-by-day or week-by-week view. What's happening right now and over the next few weeks. This map ages fast and gets updated often.
+
+> *This template is filled in during the Maps phase of planning (phase D), after Map 2 exists. The AI walks you through it.*
+
+## Where we are
+
+**Today's date:** {{TODAY}}
+**Current phase:** Phase 0 — Foundation (per Map 2)
+**Active work unit:** [WU handle and title]
+**Sessions this week:** [count or list]
+
+## This week
+
+[Day-by-day or task-by-task list of what's planned to happen over the next 5-7 days. Be specific. "Build the morning briefing surface" is too vague; "Map 3 row: Tuesday afternoon — write the morning-briefing surface file in ui-ux/, then file 3 work units against it" is the right level of detail.]
+
+| When | What | Who | Status |
+| --- | --- | --- | --- |
+| Mon | [task] | [person or "self"] | 🔵 / 🟡 / ✅ / 🔴 |
+| Tue | [task] | [...] | [...] |
+| Wed | [...] | [...] | [...] |
+| Thu | [...] | [...] | [...] |
+| Fri | [...] | [...] | [...] |
+
+## This month
+
+[Higher-level: the 4-6 outcomes you'd like to see ship by the end of this month. Each should be a WU handle.]
+
+- [WU handle] — [title] — [why this month, what depends on it]
+- [WU handle] — [title] — [...]
+- [...]
+
+## What's at risk this period
+
+[Anything that could derail the plan above. Link to risks in `risks/_index.md`. If a risk is high-severity right now, surface it here even if it's "always" tracked.]
+
+## What follows
+
+[One paragraph: what comes after this period. If this week is the last week of Phase 1, what does the first week of Phase 2 look like? Helps you wind down current work in the right shape.]
+
+## How this map gets updated
+
+Every session, by `/end-of-session`. Anything started, finished, or pushed gets reflected. **The map is the truth about what's happening now; not what we wished was happening.** If reality and the map diverge, the map gets updated to match reality — and any decisions or risks that explain the divergence are filed.
+
+When this week ends, the row table moves to next week. Past weeks land in a session log entry summarising what shipped; no need to keep historical map rows.

package/templates/starter-kit/docs/build/maps/99-template-power-user-operational-plan.md

@@ -0,0 +1,126 @@
+# Map [number] — [title]
+
+> **The canonical operational plan for [workstream name].** Sequenced work units from "today" to "[goal state]", each with phase-step decomposition, contracts realised, and verification gates anchored in target-repo files. If a step isn't here, it isn't planned. This map is the single source of truth for [workstream name] — read this before any other planning surface.
+
+> Replace the bracketed placeholders. Delete this hint block.
+
+## How to read this map
+
+The catalogue's decomposition (which this map operationalises):
+
+```
+Contracts                deep-module surfaces — what the system IS
+   │
+   │ realised by
+   ▼
+Maps                     strategic plan — when, in what order, why
+   │
+   │ ordering
+   ▼
+Work units (WUs)         executable units against contract surfaces — what ships
+   │
+   │ decomposed into
+   ▼
+Phases                   sub-units when a WU is too large for one shot
+   │
+   │ decomposed into
+   ▼
+Phase steps              the actual moves; each has acceptance + verification gate
+```
+
+Maps own **sequencing and outline**. WU files own **acceptance design and execution log**. Contracts own **the surface specs**. Sessions own **the temporal history**. No other planning artefact.
+
+## The five agentic-age patterns this map enforces
+
+These are the load-bearing discipline for agent-led building (codified in [`THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) §post-Phase-3 epistemic discipline):
+
+1. **Verification gates anchored in target-repo files** — every phase step names a specific file/grep/test as acceptance proof. Closes the spec-vs-reality drift loop.
+2. **Maps as single canonical plan** — story-level detail lives here, not in side docs. Closes the proliferation loop.
+3. **Contracts as immutable truth** — phase steps cite the contract surface they realise. Closes the "agent makes things up" loop.
+4. **Hedge words as stop signal** — "likely", "presumably", "should be" indicate a missing verification step.
+5. **Design alternatives before implementation** — Ousterhout's "design it twice"; produce at least two fundamentally different designs, evaluate, then pick or hybrid before generating non-trivial implementation. Phase steps that generate implementation carry an implicit prerequisite: design alternatives recorded in WU notes.
+
+## Where we are now ([date])
+
+| WU | Title | Status | Repo / branch |
+|---|---|---|---|
+| [WU number] | [title] | [🔵 ready / 🟡 in flight / 🟣 in_review / ✅ done / 🔴 blocked] | [repo + branch] |
+
+## What "[goal state]" means
+
+The workstream is **complete** when all of the following hold simultaneously:
+
+1. [Outcome 1]
+2. [Outcome 2]
+3. [Outcome 3]
+4. ...
+
+(List the verifiable end-state of the workstream. Each outcome should be an observable fact about the system, not a process step.)
+
+## Critical path
+
+```
+[diagram of WU sequencing with dependencies — use ASCII art or describe in prose]
+```
+
+---
+
+## WU [number] — [title]
+
+| Field | Value |
+|---|---|
+| Contracts realised | [which contract surface(s) this WU fulfils] |
+| Status | [🔵 / 🟡 / 🟣 / ✅ / 🔴] |
+| Repo | [repo + branch] |
+| Estimate | [working days] |
+| Depends on | [upstream WUs / npm publishes / external] |
+
+**Design alternatives considered (Pattern N — before any non-trivial implementation step):**
+
+> If this WU includes any non-trivial architectural choice (schema, migration, integration shape, adapter, RBAC, audit, retention, error-handling), record at least two fundamentally different design candidates here before phase steps that generate implementation. State the chosen one and why. Delete this block if the WU is purely incremental work against an already-decided design.
+
+- **Option A:** [first fundamentally different design]. Trade-offs: [...]. Errors created: [...].
+- **Option B:** [second fundamentally different design]. Trade-offs: [...]. Errors created: [...].
+- *(Option C if useful)*
+- **Chosen:** [A / B / C / hybrid] because [...]. Records as: [WU notes / D-NNN decision file].
+
+| # | Phase step | Acceptance | Verification gate |
+|---|---|---|---|
+| 1 | [what move is being made] | [what proves it produced the intended outcome] | [specific file/grep/test the operator runs to confirm] |
+| 2 | ... | ... | ... |
+
+**Done when:** [the overall WU acceptance — usually "all N steps complete + canonical green line + integration test"].
+
+**Risks:** [anything that could derail the WU; mitigations].
+
+---
+
+## WU [number] — [title]
+
+[Repeat the structure above for each WU on the critical path. Each WU with non-trivial design choices gets its own "Design alternatives considered" block; routine incremental WUs can omit it.]
+
+---
+
+## What runs in parallel
+
+[List independent workstreams that don't gate the critical path.]
+
+## Trigger conditions for deferred WUs
+
+[List WUs that are deferred and what unblocks them.]
+
+## What this map is not
+
+- It does NOT describe [out-of-scope topic 1] — see [other doc].
+- It does NOT cover [out-of-scope topic 2] — see [other doc].
+
+## How to use this map
+
+- **At session start** — read this map plus the active WU's spec file. The map tells you which phase step is next + the verification gate; the WU spec tells you the deeper acceptance design.
+- **Mid-step** — if you find yourself writing a hedge word ("likely", "presumably", "should be"), stop. Run the verification gate's grep/test/file-read first. Replace the hedge with the result.
+- **At session end** — flip phase-step status here; if scope changed, edit the step description here (not in a side doc).
+- **When a phase completes** — flip the WU's phase status; update STATE.md to reflect; confirm the dependency graph still holds.
+
+## Pointers
+
+- [List relevant WU files, contracts, decisions, prior maps]

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

@@ -1,63 +1,28 @@
-# Maps — index
+# Maps
 
-> Maps are the canonical operational plan for a project running the NuOS Build Method. **Story-level detail lives in maps**, not in fragmented planning docs. If a phase step isn't here, it isn't planned. The maps are the single source of truth for sequencing.
+A **map** is a picture of where the project is going. Three maps cover most projects — each at a different zoom level:
 
-## Why maps matter (the post-Phase-3 evolution)
+- **Map 1 — The Horizon.** The whole journey, in plain language. What this project is, who it serves, what "done" looks like. Written once and updated only when the destination genuinely changes. Read this if you only read one thing.
+- **Map 2 — Phases in Detail.** What each phase delivers, with entry and exit conditions. The mid-zoom view: how the journey breaks into stages.
+- **Map 3 — The Near-Term Plan.** What's happening this week, this month. Day-by-day where possible. Updated frequently — this map ages quickly and that's correct.
 
-The NuOS catalogue has many surfaces — decisions, contracts, work units, sessions, risks, open questions. Maps are what stops planning from sprawling across all of them. Maps own:
+See [the glossary](../GLOSSARY.md#map) for the full definition.
 
-- **Sequencing** — which work unit comes when, with explicit dependencies
-- **Phase-step decomposition** — when a WU is too large for one shot, the phase steps live here, each with acceptance + verification gate
-- **Contracts realised** — every WU on the path cites the contract surface(s) it fulfils
+## Index
 
-This is one of the four agentic-age patterns codified in the NuOS Build Method (see [`docs/THE-NUOS-BUILD-METHOD.md`](https://github.com/DarrenJCoxon/nuos/blob/main/docs/THE-NUOS-BUILD-METHOD.md) §post-Phase-3). The pattern: **maps as single canonical plan** closes the proliferation loop. A fresh session — human or agent — should be able to read STATE.md + the active map and have full operational context.
+| Map | Title | Last updated |
+| --- | --- | --- |
+| _none yet — the planning protocol fills these in during phases A (Map 1) and D (Maps 2 + 3)_ | | |
 
-## Map conventions
+## When maps get written
 
-- **Map 1 — the horizon.** The whole project journey, narrative form. Layperson-readable. If you read only one map, this is it.
-- **Map 2 — phases-in-detail (optional).** When the project has clearly separated phases (e.g., NuOS's Phases 0–F), this map gives mid-level detail per phase.
-- **Map N — canonical operational plan(s).** One per major workstream. Story-level detail with verification gates. This is where the active work lives.
+- **Map 1** is written during the **Orientation** phase of the planning arc (the AI's first conversation with you). It sets the whole-project picture.
+- **Maps 2 and 3** are written during the **Maps** phase (phase D of planning). Map 2 needs Map 1 and the architecture phase to be done first; Map 3 needs Map 2.
 
-A small project may only need Map 1 + Map 2 (canonical plan). A larger project may have several Map N variants for parallel workstreams. The convention: numbered sequentially; the latest is the most operational.
+You don't write maps by hand. The AI walks you through each one during its phase. Once written, maps are updated only by the protocol that updates them — never by silent edit.
 
-## Story-step shape
+## How maps interact with everything else
 
-Every executable phase step in a map has the following shape (per [`01-template.md`](01-template.md)):
+Every work unit gets placed inside Map 2 (which phase does it belong to?) and surfaces in Map 3 (when is it being built?). When the situation changes — a date slips, a phase rescopes — the map gets updated and the change flows to the affected work units via the catalogue's normal mechanisms.
 
-```
-| # | Phase step | Acceptance | Verification gate |
-|---|---|---|---|
-| 1 | <what move is being made> | <what proves it produced the intended outcome> | <specific file/grep/test in the target repo that the operator runs to confirm the gate> |
-```
-
-The **verification gate** is the load-bearing column for agent-led work. *"This works"* is not a gate. *"`grep 'createSensightMisWriteAdapter' apps/web/lib/nuos/nuflow/runtime.ts` returns a hit"* is a gate. Vague gates leave room for plausible-looking work that doesn't match reality; precise gates close that loop.
-
-## Hedge words are a stop signal
-
-If you find yourself writing *"likely"*, *"presumably"*, *"should be"* in a map, stop. The hedge word indicates a verification step you skipped. Replace it with the grep/test/file-read result before the map ships.
-
-## Design alternatives before implementation
-
-For any non-trivial architectural choice — schema, migration, integration shape, adapter design, audit composition, RBAC pattern, error-handling strategy, retention policy — **produce at least two fundamentally different designs, evaluate them, then pick or hybrid before any implementation is generated.** This is Ousterhout's "design it twice" applied to agent-led work.
-
-Two syntactic variations of the same design (e.g., `USING` clause vs `WITH CHECK` clause for the same RLS pattern) do not count. Three fundamentally different designs (e.g., session-variable RLS / Supabase auth.uid() RLS / defense-in-depth + app-side enforcement) do count.
-
-Record the alternatives in the WU's Design notes (or as a D-NNN decision when the choice is durable enough). The audit trail of *"we considered A, B, C; chose B because X"* is catalogue value — future sessions can re-evaluate when context changes.
-
-In maps, any phase step whose work is *"generate non-trivial implementation"* carries an implicit prerequisite: design alternatives recorded in the WU notes. The gate fires before code is written, not after.
-
-## Naming
-
-- `01-the-horizon.md` — the high-level narrative (recommend keep verbatim if adopting unchanged)
-- `02-<name>.md` — phases-in-detail or first canonical operational plan
-- `03-<name>.md`, `04-<name>.md`, etc. — additional canonical plans per workstream
-
-When a map is superseded (e.g., the project's operational shape changes), preserve the old map with a `(HISTORICAL)` header pointing at its replacement. Don't delete — the evolution is part of the audit trail.
-
-## Maps in this catalogue
-
-| File | Title | Purpose |
-|---|---|---|
-| `01-template.md` | Map template | Shape for a canonical operational map (copy + rename) |
-
-Update this list as you add real maps.
+A small project may only need Map 1 and Map 3 (skip the middle layer). A larger project may grow into having multiple operational plans for parallel workstreams; see `99-template-power-user-operational-plan.md` for the structured operational map shape used by mature projects.

package/templates/starter-kit/docs/build/open-questions/_index.md

@@ -1,26 +1,40 @@
-# Open Questions
+# Open questions
 
-> Questions blocking work that have not yet been resolved into decisions. Each question is Q-NNN. Open questions exist in three states: `open` (under deliberation), `resolved` (resolved into a D-NNN — link forward), `withdrawn` (no longer relevant).
+An **open question** is something the project hasn't decided yet but might need to. When an open question gets resolved, it becomes a [decision](../decisions/_index.md) (or it becomes obvious and gets closed). The open-questions register is where uncertainty lives — visibly, with a handle — until it's ready to settle. See [the glossary](../GLOSSARY.md#open-question) for the full definition.
 
 ## Index
 
 | ID | Question | Status | Blocks | Date opened |
 | --- | --- | --- | --- | --- |
-| _none yet_ | | | | |
+| _none yet — file your first one with `/question-new` or `nuos-catalogue question create`_ | | | | |
 
-## How to file an open question
+## When to file an open question
 
-1. Add a new row with Q-NNN (next available number)
-2. If the question warrants detail (multiple options, real trade-offs), write a `Q-NNN-short-title.md` file beside this index laying out the options
-3. Reference the question from any blocked work unit
-4. When the question resolves, file a D-NNN; mark this question `resolved` and link forward
+- You hit something during planning or work that needs a choice, but you can't make it yet
+- You're not sure what the right approach is and want to come back to it
+- A work unit can't start until something gets answered — surface that visibly rather than letting the work stall silently
+- You feel uneasy about something but it's not yet a decision — naming it as a question gives it somewhere to live
 
-## When a question becomes a decision
+> Example: "Q003 — Should the morning briefing run on-device or rely on the school's overnight server?" — both options have real trade-offs; we don't yet know which we'll pick.
 
-A question is "ready to resolve" when:
+## What status means
+
+- 🟡 **open** — under deliberation
+- 🟢 **resolved** — turned into a decision; the resolved row links forward to that D-NNN
+- ⚫ **withdrawn** — no longer relevant (e.g. the work unit it was blocking got cut)
+
+## When an open question becomes a decision
+
+A question is ready to resolve when:
 
 - The trade-offs are clear enough to choose between
-- The information needed to choose is available (or its absence is itself a decision)
-- An active or imminent work unit needs the answer
+- The information needed to choose is available (or you've decided you'll commit anyway)
+- A work unit can't continue until you choose
+
+Resolving too early produces a fragile decision someone has to revisit. Resolving too late produces a work unit that's blocked or built on guesswork. The honest signal that it's time is *something is now blocked or about to be blocked*.
+
+## How to file one
+
+Run `/question-new` (or `nuos-catalogue question create`). The AI walks you through the prompts and files the question with a fresh Q-NNN handle.
 
-Resolving prematurely produces fragile decisions. Resolving late produces blocked work units. The catalogue review walks open questions and forces the choice when blocking begins.
+When a question is resolved, run `nuos-catalogue question resolve Q003 --became=D012 --reason="..."`. This marks the question resolved, links it to the new decision, and moves it to `resolved/`.

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

@@ -1,77 +1,43 @@
-# Personas Index
+# Personas
 
-> Master list of the personas this project's work units serve. Personas are P-NNN-numbered, written along the seven dimensions, and refined with the acid-test. Reusable across multiple WUs — a "paired outcome" (e.g., a customer-side outcome paired with an organiser-side one) cites two personas, both filed here.
+A **persona** is one specific person the project serves. Not a market segment, not a demographic — one person with a name, a situation, and a reason to need what you're building. Personas are first-class in this catalogue because everything downstream — work units, UI/UX surfaces, contracts, decisions — hangs off who specifically you're building for. See [the glossary](../GLOSSARY.md#persona) for the full definition.
 
-## What a persona is
+## Index
 
-A persona is a **specification of who will use an outcome and what situation they will be in when they use it.** It is not a demographic snapshot; it is a design constraint. A persona that does not change a design decision is decoration — rewrite it until it does.
-
-The seven dimensions every persona addresses:
-
-1. **Identity** — who they are in the context of *this system*. Not their age or job title in the abstract — their relationship to this particular system.
-2. **Reality** — physical environment when they use the outcome. Device, connection quality, noise level, time pressure.
-3. **Psychology** — technical confidence, stress level, tolerance for confusion.
-4. **Trigger** — what brought them to this outcome. A real-world event, not a UI click.
-5. **History** — what they have done before arriving at this outcome.
-6. **Success** — what "done" looks like from their perspective. Not what the system logs — what they feel.
-7. **Constraints** — what they cannot or will not do. Defines the outer boundary of acceptable design.
-
-Every persona is then refined into an **acid-test persona** — the hardest legitimate user, with the most demanding combination of real constraints. Design for the acid-test and the standard cases hold.
-
-## How a persona is filed
-
-```
-personas/
-├── _index.md          (this file)
-├── 001-template.md    (the template; copy when filing a new persona)
-├── P001-<slug>.md     (your first persona)
-├── P002-<slug>.md     ...
-└── done/              (when a persona retires — e.g., the user role no longer exists)
-```
-
-Personas are P-NNN-numbered. Numbers are stable: a retired persona moves to `done/` but keeps its number. Cross-WU references use the stable handle (`{repo}:P-NNN` for cross-catalogue references; `[P-NNN](../personas/P-NNN-slug.md)` within the same catalogue).
-
-## Personas — active
-
-| ID | Name | Used by WUs | Status |
+| ID | Name | Status | Used by |
 | --- | --- | --- | --- |
+| _none yet — file your first one with `/persona-new` or `nuos-catalogue persona create`_ | | | |
 
-[Add a row when you file a new persona. Status: `🟢 active`, `🟡 evolving` (the persona shape is being refined), `🟣 paired-with-PNNN` (this persona's outcomes are paired with another), `⚫ retired`.]
+## What status means
 
-## Status legend
+- 🟢 **active** — currently in use; referenced by one or more work units or surfaces
+- 🟡 **evolving** — the persona's shape is still being refined as you learn
+- ⚫ **retired** — no longer in use; lives in `done/` but keeps its handle
 
-- 🟢 `active` — in use; cited by one or more current WUs
-- 🟡 `evolving` — the seven dimensions are being refined as understanding deepens
-- 🟣 `paired-with-PNNN` — this persona pairs with another (e.g., customer + organiser)
-- ⚫ `retired` — no longer in use; moved to `done/`
+## The seven dimensions
 
-## How to write a persona
+When you file a persona, you describe seven things about this specific person:
 
-Use the file format established in `001-template.md`. A persona document has:
+1. **Identity** — who they are *in the context of this project*. Their role, their relationship to what you're building. Not their age in the abstract — their relationship to your project.
+2. **Reality** — where they are when they need this. Their device, their environment, their time pressure.
+3. **Psychology** — how confident they are, how stressed, how patient with confusion.
+4. **Trigger** — what's happening in their day or week that makes them need this. Not a click — a real-world moment.
+5. **History** — what they've already done, tried, or experienced before reaching this point.
+6. **Success** — what "done" looks like *from their perspective*. Not what your system logs; what they feel.
+7. **Constraints** — what they cannot or will not do. The outer edge of what's acceptable for them.
 
-- Identity dimension
-- Reality dimension
-- Psychology dimension
-- Trigger dimension
-- History dimension
-- Success dimension
-- Constraints dimension
-- Acid-test refinement (the worst legitimate combination of constraints)
-- Paired persona (if any) — the persona on the other side of any outcome this persona triggers
-- WUs this persona is cited by
+A persona is sharp when **swapping them for a different person would force at least one design decision to change**. If you can substitute the persona without changing anything, the persona is decorative — refine it until it constrains.
 
-A persona should be small enough to read in two minutes and specific enough that swapping it for a different persona would force at least one design decision to change. If you can substitute the persona without changing anything in the WU, the persona is decorative — rewrite it until it constrains.
+## When to file a persona
 
-## How personas connect to WUs
+You file the first 1-3 personas during the **Orientation** phase of planning. Most projects need 2-3 personas — primary user, secondary user, and sometimes an "operator" or "administrator" persona. More than 5-6 active personas usually means the project is overreaching; consider phasing.
 
-A WU's `Persona` field links the P-NNN that the outcome serves. A WU's `Trigger` field draws from the persona's Trigger dimension but specifies the *moment* (not just the class of event). A WU's `Walkthrough` is written from the persona's perspective, using their reality, psychology, and history to constrain what they need to be told and what they already know.
+Add new personas later if a new kind of user enters scope. Retire old ones (move to `done/`) when a role no longer exists.
 
-If a WU has no clear persona, it is one of two things:
-1. An infrastructure WU (build, publish, hardening) — mark the persona field `N/A — infrastructure WU`.
-2. An unanchored feature — the WU describes a category of capability without a person doing a thing. Rewrite as an outcome with a real persona, or split into smaller outcomes.
+## How to file one
 
-## How personas evolve
+Run `/persona-new` (or `nuos-catalogue persona create`). The AI walks you through each of the seven dimensions as conversation — give them a name, describe their situation, what makes them need this — and files the result with a fresh P-NNN handle.
 
-Personas evolve as understanding deepens. The seven dimensions get sharper; the acid-test gets harder; new constraints surface. Update the persona file in place — but record the *date* of each refinement in the file itself, so a future reader can see how the understanding changed.
+## How personas connect to everything else
 
-If a persona's role in the system changes substantially (e.g., "customer" splits into "registered customer" + "guest customer"), file two new personas with new P-NNN numbers and mark the original `⚫ retired` rather than amending it.
+Every work unit names a persona. Every UI/UX surface names a persona. Every contract is justified by what a persona needs. When you change a persona's reality or constraints, downstream artefacts referencing that persona may need updates — file open questions for any you're not sure about.