@nurix/etna 0.18.20 → 0.18.22

package/README.md

@@ -29,7 +29,7 @@ your-project/
 └── .claude/
     ├── skills/            ← documentation, boundary, brainstorm, workflow-mapper
     ├── agents/            ← lld-mode, brainstorm, maintenance, change-review, performance-review
-    ├── rules/             ← general.md, nomenclature.md, typescript.md, testing.md
+    ├── rules/             ← general.md, frontend.md, express.md, nomenclature.md, database.md, typescript.md, testing.md
     ├── hooks/             ← generate-ownership-index (SessionStart)
     ├── settings.json      ← the hook is deep-merged in here (your existing keys preserved)
     └── harness.json       ← {version, digest} — the installed-harness sentinel

package/data/harness-index.json

@@ -1,5 +1,5 @@
 {
-    "fingerprint": "1573653d37b0",
+    "fingerprint": "5cb712a2bb9e",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -34,7 +34,7 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 | **LLD** (low-level design) | new feature work | `lld-mode` agent + `documentation` skill | Plan |
 | **Plan** | an LLD is approved | `documentation` skill → `docs/history/plans/YYYY-MM-DD-{slug}.md` | Completion |
 
-> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a bug fix, one button) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: kept records live under `docs/brainstorm/`, harvested doctrine under `docs/architecture/`. Runtimes without slash commands: read `.claude/skills/brainstorm/SKILL.md` and follow it inline. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
+> Brainstorm entry needs a **basis** — a reference document or a one-shot brain dump; drip-sized asks (a bug fix, one button) are too small and get redirected. A **pillar** is a recorded strategic principle from a past brainstorm: in-progress sessions live under `docs/research/`, harvested ones under `docs/history/brainstorms/`, harvested doctrine under `docs/architecture/`. Runtimes without slash commands: read `.claude/skills/brainstorm/SKILL.md` and follow it inline. The LLD is the feature doc itself — `docs/features/{feature}.md`, design intent first, extended in place at Completion.
 
 **On Plan Completion:**
 
@@ -44,8 +44,8 @@ Three peer modes plus a Completion step — enter wherever the user's thinking a
 
 **On Brainstorm Close** (a separate procedure — when a brainstorm session ends, not when a plan completes):
 
-- The session record lives at `docs/brainstorm/{topic}/` (committed, one subfolder per topic) and stays in place as provenance.
-- Harvest conclusions by scope: doctrine, glossary, non-goals, information-architecture changes → `docs/architecture/`; decisions → `docs/architecture/adr/`; backlog items → `docs/history/backlog.md`.
+- The session record lives at `docs/research/{topic}-brainstorming/` (committed) while active; on close + harvest it moves to `docs/history/brainstorms/{topic}/` as provenance — see `docs/structure.md`.
+- Harvest conclusions by scope: doctrine, glossary, non-goals, information-architecture changes → `docs/architecture/`; decisions → `docs/architecture/decisions/` (one AD per subject — revising a recorded subject updates its AD in place); backlog items → `docs/history/backlog.md`.
 - Open questions block close.
 
 ---

package/data/harnesses/code/agents/brainstorm.md

@@ -14,7 +14,7 @@ You are a **thin orchestrator.** Every mechanic — the constant loop, the four
 ## When to offer a session
 
 - An explicit ask to think through a design at a strategic level (not "fix this bug" / "add this button"). This is the user invoking the work; hand it to `/brainstorm start`.
-- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and its `adr/` decision titles. The steering layer lives there; there are no `docs/modules/` or `docs/pillars/` folders. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
+- A user utterance **challenges a loaded pillar headline.** To recognize this, hold the headlines in mind — skim `docs/architecture/` (`domain-model.md`, `glossary.md`, `non-goals.md`, `open-questions.md`) and its `decisions/` AD titles. The steering layer lives there; there are no `docs/modules/` or `docs/pillars/` folders. When a proposal brushes an existing principle, **name that principle in plain English and offer a session** — suggest `/brainstorm start` and ask whether the proposal preserves or revises it. Detection is yours; entry is the user's. **Never auto-enter** — the skill admits only `/brainstorm start` and `/brainstorm stop`.
 
 If none of those steering files exist yet (a freshly-baselined repo), a session still runs from the skill's templates, and the basis gate seeds it from a reference doc or a one-shot brain dump.
 

package/data/harnesses/code/agents/maintenance.md

@@ -127,28 +127,29 @@ docs/
 ├── structure.md           # Authority map + frontmatter `harness-version` (you own this field)
 ├── architecture/          # Cross-module design + steering layer
 │   │                      #   domain-model, glossary, non-goals, references, open-questions
-│   └── adr/               # Architecture Decision Records (numbered, immutable)
+│   └── decisions/         # Architecture Decisions (ADs — one per subject, updated in place; journey in each AD's Decision Changelog)
 ├── features/              # Feature specs — the only first-class doc unit (flat; ownership in each doc's `owns:` frontmatter)
 │   └── {group}/           #   browse-only subfolder for grouping; NEVER a module; may carry a Readme.md
 ├── operations/            # Setup, development, deployment, CI/CD
-├── brainstorm/            # Optional — kept design records, one {topic}/ subfolder per session (state.md + pillars/)
-│   └── {topic}/           #   created by the `brainstorm` skill; NOT scaffolded empty
+├── research/              # Optional — in-progress brainstorm sessions ({topic}-brainstorming/) + standing research; Readme.md is the index
+│   └── {topic}-brainstorming/  #   created by the `brainstorm` skill; NOT scaffolded empty; moves to history/brainstorms/ on harvest
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index
 │   ├── changelog/         # Individual entries
 │   ├── plans/             # Implementation plans (Status field required)
+│   ├── brainstorms/       # Harvested brainstorm sessions ({topic}/), kept as provenance; Readme.md is the index
 │   └── backlog.md         # Tracked work items by priority (P0-P3)
 ├── memory/                # index.md, main.md, {agent}.md — project knowledge + per-agent strategy memory
 └── tests/                 # Optional, author-maintained — create only if test docs exist
 ```
 
-There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records are kept design records.
+There is **no `docs/routing.md`**, **no `docs/modules/{m}/`**, **no `docs/pillars/`**, **no `docs/boundaries/`**. Code ownership lives in feature `owns:` frontmatter; a module is a `module:` label, not a folder; boundaries are diagnosed from source; brainstorm records live in `docs/research/` (active) and `docs/history/brainstorms/` (harvested).
 
-> `docs/brainstorm/{topic}/` is **author-created, never scaffolded** — the `brainstorm` skill writes it when a session opens, and it is **kept** (committed) as the provenance the steering pillars distil from. Recognize it as canonical: never flag it as a doc "outside the structure" and never delete it during reconcile.
+> Brainstorm records are **author-created, never scaffolded** — the `brainstorm` skill writes an active session at `docs/research/{topic}-brainstorming/` and moves it to `docs/history/brainstorms/{topic}/` on harvest, kept (committed) as the provenance the steering pillars distil from. Recognize both as canonical: never flag them as docs "outside the structure" and never delete them during reconcile. Each folder carries a `Readme.md` index — keep it in sync with the folders it lists (every session has a row; no stale or missing rows), since the `brainstorm` skill reads the indexes instead of scanning.
 
 ### Step B1 — Inventory and classify
 
-Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/brainstorm/{topic}/` is a **kept design record** — leave it in place untouched; never reclassify its pillars as Architecture/Stale or relocate them.
+Glob every markdown file. Classify each: Architecture, Features, Operations, Plans, Changelogs, Backlog, Brainstorm records (stay), Stale/Deprecated (delete), Root docs (stay). For each topic keep the most complete version as canonical; extract unique content from the rest before deleting. **No redirect stubs** — when you move a file, delete the original and fix every reference (cross-doc links, memory files). Anything already under `docs/research/{topic}-brainstorming/` or `docs/history/brainstorms/{topic}/` is a **kept design record** — leave it in place untouched; never reclassify its pillars as Architecture/Stale or relocate them.
 
 While reading each markdown doc to classify it, if the doc names a code symbol it asserts exists that **statically resolves to nothing**, note it as an observation for the Part A audit — **only** on stacks where static resolution is reliable (stay silent on codegen/reflection/DI/barrel stacks); scoped to docs already being read here, never a whole-repo prose sweep; **docs only**, never code-file comments.
 
@@ -166,7 +167,7 @@ This is what makes baseline more than a fresh scaffold. Detect old-shape artifac
 | `docs/OWNERSHIP_INDEX.md` (legacy derived ownership index) | delete — ownership is the union of feature `owns:` frontmatter, surfaced by the generated index |
 | `docs/operations/guardrails.md` | fold durable contract notes into `docs/architecture/` |
 | `docs/architecture/overview.md` | split into `domain-model.md` / `glossary.md` / `non-goals.md` / `references.md` / `open-questions.md` |
-| a root `brainstorm/` or `brainstorming/` folder (legacy transient/per-harness location) | move each design record into `docs/brainstorm/{topic}/`, kept; delete the root folder |
+| a legacy `docs/brainstorm/{topic}/`, or a root `brainstorm/`/`brainstorming/` folder | move each **active** record to `docs/research/{topic}-brainstorming/` and each **harvested** one to `docs/history/brainstorms/{topic}/` (dropping the suffix); create/refresh both `Readme.md` indexes; delete the emptied folder |
 | no `harness-version` in `structure.md` | stamp it (Step B4) |
 
 ### Step B3 — Present the reconcile plan, then execute

package/data/harnesses/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.1.4",
+  "version": "3.1.6",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "15411f0d9e07"
+  "digest": "e1a1b585018d"
 }

package/data/harnesses/code/rules/database.md

@@ -0,0 +1,38 @@
+# Database
+
+Fixed conventions for relational schemas — table/column/index **names**, the **key vocabulary** (`id` / `slug` / `label`), column types, and Drizzle mirrors — so the same concept carries the same name in **every** Nurix project. This is a cross-project consistency rule: **one concept, one name, everywhere** — never `slug` in one repo and `handle` / `key` / `code` in another. General code naming (variables, files, casing) is [`nomenclature.md`](nomenclature.md); this rule owns the database.
+
+Written for SQLite / Cloudflare D1 + Drizzle (the concrete types below). The **names and key vocabulary are engine-agnostic** — a Postgres project keeps the same column names and semantics with native types (`uuid`, `timestamptz`, `boolean`).
+
+## Keys & the shared vocabulary
+
+Three column roles are fixed across every table and every project:
+
+- **`id`** — the primary key, **always a UUID** (`TEXT PRIMARY KEY` on D1, `uuid` on Postgres). Never a synthetic or natural key (`type_page_button`, `human:default` are ❌). Runtime rows mint a UUIDv7; seed rows derive a deterministic UUIDv5 of the natural key so re-seeds stay stable. Never mix synthetic and UUID ids in one table.
+- **`slug`** — the **stable key other rows reference**: `UNIQUE`, lowercase `snake_case`. **Foreign keys point at `slug`, not `id`.** One concept = one slug name across every table and repo. ❌ Never rename this role `handle`, `key`, `code`, or `name` in a different project — it is always `slug`.
+- **`label`** — the **human display name**. Always `label` — ❌ never `name`, `title`, or `display_name`.
+
+Reference columns name what they point at: `<entity>_id` for a UUID-PK reference (`user_id`, `app_id`), `<entity>_slug` for a slug reference (`source_slug`).
+
+- **Enforced** (the referenced row must exist) → a real `FOREIGN KEY (<x>_slug) REFERENCES <table>(slug)`.
+- **Drift-tolerant** (a controlled-vocabulary value that may fall off-list) → a plain value column, **no** FK, paired with an `is_*` boolean recording whether the value is in the canonical set.
+
+## Naming
+
+- **Tables** — `snake_case`, plural noun for what they hold (`users`, `apps`, `devices`).
+- **Junction (M:N) tables** — `<entityA>_<entityB>_map`, **always**, even when the join carries its own columns; singular stems, owning/anchor entity first (`app_user_map`, `app_device_map`). ❌ Never a "nice" noun (`members`, `installs`, `memberships`, `enrolments`) — the name must read as a join, and a reviewer should know both sides from it.
+- **Columns** — `snake_case`; booleans `is_*` / `has_*`; timestamps `created_at` / `updated_at`; foreign keys `<entity>_id`.
+- **Indexes** — `<table>_<col(s)>_idx`; unique `<table>_<col(s)>_unique`; a junction's composite unique reads `<table>_<colA>_<colB>_unique` (`app_user_map_app_user_unique`).
+- **Drizzle mirror** — the exported object is the camelCase table name (`app_user_map` → `appUserMap`); column props are the camelCase of the column (`created_at` → `createdAt`). The `sqliteTable("…")` string and every index name must match the DDL (`init.sql`) exactly — the schema-parity boundary.
+
+## Column types (SQLite / D1)
+
+- **Timestamps** — `created_at` + `updated_at`, both `TEXT NOT NULL DEFAULT (datetime('now'))`, on **every** table — except append-only logs, which carry only `created_at`.
+- **Booleans** — `INTEGER`, named `is_*` / `has_*` (Drizzle `integer(…, { mode: "boolean" })`).
+- **JSON** — `TEXT` (Drizzle `text(…, { mode: "json" })`).
+
+## Vocabulary / lookup tables
+
+A controlled-vocabulary table (statuses, kinds, categories) follows a fixed shape: `id` (UUID) · `slug` (UNIQUE) · `label` · optional `description` · `status` · timestamps.
+
+- **Seeds are generated, never hand-written** — the source of truth is a CSV or a shared package; a generator emits the `*.seed.sql` with UUIDv5 ids and an idempotent `ON CONFLICT(slug)` upsert that preserves live counts / admin-tuned columns. Hand-editing seed SQL is ❌ — regenerate it.

package/data/harnesses/code/rules/express.md

@@ -0,0 +1,28 @@
+# Express & API Format
+
+Express 5.x server setup and the JSON response envelope every Nurix HTTP service returns — backend only. Package versions live in [`general.md`](general.md); web-frontend conventions in [`frontend.md`](frontend.md).
+
+## Express 5.x
+
+```javascript
+app.use(cors({ origin: process.env.FRONTEND_URL }));
+app.use(compression());
+app.use(express.json({ limit: '10mb' }));
+app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
+```
+
+- Middleware order: body parsers → custom middleware → routes → error handlers (centralized, last). Auth via middleware. Use Express Router for modular routes.
+
+## API Response Format
+
+```json
+{
+  "status": 1,
+  "message": "Message sent successfully",
+  "data": { "delivered": [{ "user@example.com": 2 }] }
+}
+```
+
+Error: `{ "status": 0, "message": "Error description", "data": null }`
+
+HTTP codes: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`

package/data/harnesses/code/rules/frontend.md

@@ -0,0 +1,14 @@
+# Frontend
+
+Tailwind v4 + shadcn-based UI conventions for **web** apps — styling, the `@nurix/components` library, personality tokens, and design-skill routing. Package versions live in [`general.md`](general.md); the Express server and API envelope in [`express.md`](express.md); React Native styling is out of scope — that's [`react-native.md`](react-native.md).
+
+- **Build every UI through the `design` skill** — route the brief through it instead of hand-rolling layouts; it owns the archetype, personality tokens, and `@nurix/components` wiring.
+- **Light mode is the default** — design for the light theme as the default; dark mode is opt-in, never the default.
+- **@nurix/\* are restricted-scope npm packages** — installed from the npm registry, auto-authed by a read token in `~/.npmrc`. Just attempt the install; the token authenticates you automatically. Don't pre-empt or second-guess it. If the install actually fails, flag it to the user — never reach for alternatives, a substitute package, or `npm login`.
+- **@nurix/components** — the UI component library (restricted-scope npm package, pre-built); import by subpath, e.g. `@nurix/components/button`.
+- No components.json / shadcn CLI scaffold (.tsx, not .jsx) — consume the prebuilt library; never `npx shadcn add`.
+- Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin react / react-dom / react/jsx-runtime / react/jsx-dev-runtime to the app's single copy via `resolve.alias` (@nurix/\* ship nested react — keep one hook dispatcher).
+- Tailwind v4, CSS-only (no tailwind.config.js, no PostCSS): styling runs through the `@tailwindcss/vite` plugin.
+- CSS entry `globals.css`, imports in order — `@import "./personality.css"` (token source) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
+- Tokens: CSS vars in `:root, :root[data-theme="light"]` + the archetype selector `[data-style="…"]` (personality.css), consumed as semantic Tailwind tokens (bg-card, text-foreground). Honor the archetype's radius/theme decisions (e.g. re-assert `--radius-*` to 0 for a flat archetype; add `@custom-variant dark` only if the project opts into dark mode, and keep light as the default). The library bundles class-variance-authority, clsx, tailwind-merge.
+- Plus general styling rules (spacing in 2/4/6/8, object-cover, truncate, motion, color tokens — never hardcoded hex in components).

package/data/harnesses/code/rules/general.md

@@ -1,5 +1,7 @@
 # General Standards
 
+Runtime versions and the canonical package list — the workspace baseline every Nurix code harness loads. Web-frontend/styling conventions are [`frontend.md`](frontend.md); the Express server and the API response envelope are [`express.md`](express.md).
+
 ## Runtime Versions
 
 - **Node.js:** 22 LTS (latest)
@@ -45,43 +47,3 @@ No alternatives. Just use these.
 | fast-deep-equal          | ^3.1.3    | Deep equality checks   | lodash.isEqual             |
 | @ngneat/falso            | latest    | Fake data generation   | @faker-js/faker, chance    |
 | pino                     | ^10.1.0   | Logging                | winston                    |
-
-## Frontend
-
-Tailwind v4 + shadcn-based UI; conventions below.
-
-- **Build every UI through the `design` skill** — route the brief through it instead of hand-rolling layouts; it owns the archetype, personality tokens, and `@nurix/components` wiring.
-- **Light mode is the default** — design for the light theme as the default; dark mode is opt-in, never the default.
-- **@nurix/\* are restricted-scope npm packages** — installed from the npm registry, auto-authed by a read token in `~/.npmrc`. Just attempt the install; the token authenticates you automatically. Don't pre-empt or second-guess it. If the install actually fails, flag it to the user — never reach for alternatives, a substitute package, or `npm login`.
-- **@nurix/components** — the UI component library (restricted-scope npm package, pre-built); import by subpath, e.g. `@nurix/components/button`.
-- No components.json / shadcn CLI scaffold (.tsx, not .jsx) — consume the prebuilt library; never `npx shadcn add`.
-- Vite: `@tailwindcss/vite` + `@vitejs/plugin-react-swc`. Pin react / react-dom / react/jsx-runtime / react/jsx-dev-runtime to the app's single copy via `resolve.alias` (@nurix/\* ship nested react — keep one hook dispatcher).
-- Tailwind v4, CSS-only (no tailwind.config.js, no PostCSS): styling runs through the `@tailwindcss/vite` plugin.
-- CSS entry `globals.css`, imports in order — `@import "./personality.css"` (token source) → `@import "tailwindcss"` → the library's `styles.css` — then `@theme inline {…}` mapping vars to tokens.
-- Tokens: CSS vars in `:root, :root[data-theme="light"]` + the archetype selector `[data-style="…"]` (personality.css), consumed as semantic Tailwind tokens (bg-card, text-foreground). Honor the archetype's radius/theme decisions (e.g. re-assert `--radius-*` to 0 for a flat archetype; add `@custom-variant dark` only if the project opts into dark mode, and keep light as the default). The library bundles class-variance-authority, clsx, tailwind-merge.
-- Plus general styling rules (spacing in 2/4/6/8, object-cover, truncate, motion, color tokens — never hardcoded hex in components).
-
-## Express 5.x
-
-```javascript
-app.use(cors({ origin: process.env.FRONTEND_URL }));
-app.use(compression());
-app.use(express.json({ limit: '10mb' }));
-app.use(rateLimit({ windowMs: 15 * 60 * 1000, max: 100 }));
-```
-
-- Middleware order: body parsers → custom middleware → routes → error handlers (centralized, last). Auth via middleware. Use Express Router for modular routes.
-
-## API Response Format
-
-```json
-{
-  "status": 1,
-  "message": "Message sent successfully",
-  "data": { "delivered": [{ "user@example.com": 2 }] }
-}
-```
-
-Error: `{ "status": 0, "message": "Error description", "data": null }`
-
-HTTP codes: `200`, `201` (created), `400`, `401` (not authenticated), `403` (not authorized), `404`, `500`

package/data/harnesses/code/rules/nomenclature.md

@@ -31,11 +31,4 @@
 
 ## Database
 
-Naming for D1 tables, columns, indexes, and their Drizzle mirrors. (For column **types** — PK shape, timestamp columns — see the Cloudflare D1 Schema rule, not here; this section governs names only.)
-
-- **Tables** : snake_case. Entity / hub tables use the plural noun for the thing they hold. Examples: `users`, `apps`, `devices`, `services`.
-- **Junction (M:N) tables** : name a many-to-many join `<entityA>_<entityB>_map` — **always**, even when the join carries its own columns (a `role`, a secret, a status). The `_map` suffix is the signal that a row is a relationship, not an entity; extra attributes on the join do **not** earn it a standalone noun. Use the **singular** stem of each side, owning/anchor entity first (mirror the existing tables — `app_*`). Examples: `app_user_map` (apps ⨯ users), `app_device_map` (apps ⨯ devices), `app_service_map` (apps ⨯ services).
-  - ❌ Don't invent a "nice" noun for a junction — no `members`, `installs`, `memberships`, `enrolments`. A reviewer should read the table name and know both sides and that it's a join.
-- **Columns** : snake_case. Foreign keys are `<entity>_id` (`user_id`, `app_id`, `device_id`, `service_id`). Booleans follow the boolean rule (`is_*`/`has_*`); timestamps are `created_at` / `updated_at`.
-- **Indexes** : `<table>_<col(s)>_idx`; unique indexes `<table>_<col(s)>_unique`. The composite unique on a junction reads `<table>_<colA>_<colB>_unique` — e.g. `app_user_map_app_user_unique`, `app_device_map_device_app_unique`.
-- **Drizzle mirror** : the exported table object is the camelCase of the snake_case table name (`app_user_map` → `appUserMap`); column TS properties are the camelCase of the column (`created_at` → `createdAt`, `service_key` → `serviceKey`). The snake_case string passed to `sqliteTable("…")` and every index name must match `seed/init.sql` exactly (the G1 schema-parity boundary).
+Table, column, index, and key naming for relational schemas — the `id` / `slug` / `label` vocabulary, junction `_map` tables, and Drizzle mirrors — lives in [`database.md`](database.md), the cross-project database conventions rule. Kept there, not here, so there is one canonical home and the same concept carries the same name in every project.

package/data/harnesses/code/rules/nustack.md

@@ -0,0 +1,150 @@
+# Nustack — `@nurix/*` Packages: naming, monorepo layout, and publishing
+
+How a `@nurix/*` multi-package repo is **named**, **structured**, and **shipped**. For consuming an already-published `@nurix/*` package (auth, install, imports), see the Consuming section of [`typescript.md`](typescript.md).
+
+---
+
+## 1. Package naming
+
+Every workspace package is scoped to **`@nurix/`**. The segment after the scope encodes **intent** — the dot vs. hyphen is semantic, not cosmetic:
+
+| Form                                            | Meaning                                                                                                                                                                                  | Examples                                                                                                           |
+| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `@nurix/workflows-sdk` (hyphen, single segment) | The **published, externally-destined** surface. A clean `@nurix/*` name is a published _contract_ — changing an export or peer dep is a breaking change for consumers outside this repo. | `@nurix/workflows-sdk`                                                                                             |
+| `@nurix/workflows.<name>` (dot separator)       | **Internal** to the workflows product — `private: true`, refactor freely, no external consumers.                                                                                         | `@nurix/workflows.agent-core`, `.worker`, `.gateway`, `.secrets`, `.connector`, `.playground`, `.playground-tests` |
+| `@nurix/<name>` (plain, no `workflows` prefix)  | Cross-repo **shared libs** owned _elsewhere_ and merely consumed here — never renamed.                                                                                                   | `@nurix/contracts`, `@nurix/components`                                                                            |
+
+- The `<name>` segment is always **kebab-case** (`agent-core`, `playground-tests`).
+- The dot is **not** a path separator, so subpath exports still resolve: `@nurix/workflows.agent-core/nodes`.
+- The dot tracks "internal product package," not the `private` flag exactly — `@nurix/workflows.secrets` is `private: false` because it's extraction-bound (slated to move to a sibling repo/namespace), yet still wears the dotted internal name. Today `-sdk` is the only clean published form.
+
+**Naming a new package:** internal to this repo? → `@nurix/workflows.<thing>`, `private: true`, kebab-case `<thing>` (the default). Externally consumed contract? → clean `@nurix/<thing>` (rare). Shared lib from another repo? → keep its existing `@nurix/<name>`.
+
+---
+
+## 2. Monorepo & package boundaries
+
+One `tsconfig.base.json` at the repo root is the **single owner of TS policy** — the strict set (see [`typescript.md`](typescript.md)), `target`, and any option uniform across packages (here, `module`/`moduleResolution`). Each package's `tsconfig.json` is thin: it `extends` the base, then adds only its own *coordinates* (`rootDir`/`outDir`/`include`) and genuine *environment* overrides (`lib`/`types`/`jsx`, plus `module`/`moduleResolution` when a package's module system genuinely differs — a Worker, browser, or NodeNext package). That is environment, not policy. Never re-declare or weaken a *policy* option locally (no per-package `strict: false`, no widening `noUncheckedIndexedAccess`). A framework that owns its own base (e.g. an Astro app on `astro/tsconfigs/strict`) is the one allowed exception.
+
+- **Internal packages are source-first.** A `private: true` workspace package exposes its API through the `exports` field pointing at TypeScript source (`"types"`/`"default"` → `./src/index.ts`) — consumed across the workspace with **no build step**. Prefer the `exports` field; don't add a bare `main`/`module` to new packages. Add one typed subpath per public surface (`"./nodes": { "types": "./src/nodes/index.ts", "default": "./src/nodes/index.ts" }`); consumers import the subpath, **never** a deep relative path into another package's `src/`.
+- **Published packages build to `dist` — never ship raw `src`.** The moment a package crosses a publish boundary (`private: false`), it compiles with `tsc` (`declaration: true`, `declarationMap: true` from the base), ships `files: ["dist"]`, and points `exports`/`types` at `./dist/*` (use `publishConfig.exports` to swap source→dist on publish if the dev entry stays on source). `prepublishOnly` runs the build.
+- **Declare host singletons as `peerDependencies`** on published libraries (`react`, `react-dom`, the framework client) so consumers keep one copy; never bundle them. Apps depend on them directly.
+- **Single-source shared dep versions with pnpm `catalog:`** — `typescript`, `zod`, `vitest`, `react`, type packages. One version per dependency across the workspace so every package's types resolve identically; no per-manifest version drift.
+- **Reach for TS project references only when it hurts** — adopt `references` once the typecheck/build graph is slow enough to feel. Until then, `pnpm -r typecheck` over independent `extends` configs is the correct default.
+
+---
+
+## 3. Publishing & the release pipeline
+
+`@nurix/*` packages publish to **npmjs.org with `restricted` access** — only npm users with read rights to the `nurix` org can install them. Reference implementations: `~/dev/components` (`@nurix/components`, library) and `~/dev/etna/packages/cli` (`@nurix/etna`, CLI).
+
+### 3.1 Prerequisites (one-time, org-wide)
+
+1. **npm org `nurix`** exists and you're a member with publish rights — <https://www.npmjs.com/settings/nurix/packages>.
+2. **An npm automation token** with `Read and write` for the `nurix` scope — npm → Generate New Token → Automation.
+3. **The token added as a GitHub Actions secret** named `NPM_PUBLISH_TOKEN` on every publishing repo. `NPM_PUBLISH_TOKEN` is the convention; pick another name only with a strong reason.
+
+### 3.2 `package.json` — required fields
+
+```jsonc
+{
+  "name": "@nurix/<package-name>", // The scope makes it discoverable to org members.
+  "version": "0.1.0",              // Start at 0.1.0; the workflow bumps from here.
+  "private": false,                // MUST be false (or omitted). `npm publish` refuses if true.
+  "publishConfig": { "access": "restricted" }, // Scoped + private: only org members can install.
+  "files": ["dist"]                // Whitelist of what ships. Anything outside is excluded.
+}
+```
+
+- **`publishConfig.access`** — `"restricted"` (recommended): visible only to `nurix`-org readers. `"public"`: world-readable (free, but only if you mean it). Omitting it on a scoped package defaults to `restricted`; be explicit anyway.
+- **`files`** — without it, npm publishes everything not in `.gitignore`, **including source**. Library → `["dist"]`; CLI (etna) → `["bin/", "data/", "README.md"]`. Don't list `package.json`/`README.md` — npm always includes them.
+- **Build hooks** — `prepack` for build steps that must produce files in `files` (also runs on install-as-git-dep); `prepublishOnly` for publish-only steps. Either alone is fine; `@nurix/components` runs both.
+- **Other useful fields** — `type: "module"`, `engines.node`, `bin` (CLIs), `main`/`module`/`types`/`exports` (libraries), `sideEffects: ["**/*.css"]`, `repository` (with `directory` for monorepos), `license: "UNLICENSED"`.
+
+### 3.3 The publish workflow (generic template)
+
+The dual-trigger pattern: a push to the default branch auto-ships a patch; a manual dispatch picks minor/major.
+
+```yaml
+name: Publish to npm
+on:
+  push:
+    branches: [dev]               # your default branch
+    paths:                        # ONLY paths that change what ships — else every README edit publishes
+      - 'src/**'
+      - 'scripts/**'
+      - 'package.json'
+      - 'package-lock.json'
+      - '.github/workflows/publish.yml'
+  workflow_dispatch:
+    inputs:
+      bump: { description: 'Version bump', type: choice, options: [patch, minor, major], default: patch }
+permissions: { contents: write }  # push the version-bump commit + tag
+concurrency: { group: publish, cancel-in-progress: false }  # monorepo: group: publish-<pkg>
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+        with: { fetch-depth: 0, token: '${{ secrets.GITHUB_TOKEN }}' }
+      - uses: actions/setup-node@v5
+        with: { node-version: 22, registry-url: 'https://registry.npmjs.org' }  # writes .npmrc using $NODE_AUTH_TOKEN
+      - run: npm ci                 # skip ONLY if the build is pure-Node with no deps (e.g. @nurix/etna)
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+      - run: npm version ${{ inputs.bump || 'patch' }} -m "chore: release v%s [skip ci]"
+      - run: npm publish            # prepublishOnly / prepack runs the build
+        env: { NODE_AUTH_TOKEN: '${{ secrets.NPM_PUBLISH_TOKEN }}' }
+      - run: git push --follow-tags # pushes the bump commit AND the v<version> tag npm created
+```
+
+**Why dual-trigger is safe** — three safeguards prevent an infinite publish loop: (1) `paths:` scopes the push trigger to artifact-affecting files; (2) `[skip ci]` in the bump commit makes GitHub skip the workflow that bump would otherwise re-trigger; (3) `concurrency: cancel-in-progress: false` queues near-simultaneous merges instead of racing for a version number.
+
+**`registry-url` is load-bearing** — without `registry-url: https://registry.npmjs.org` on `setup-node`, it never writes the `.npmrc` line that uses `$NODE_AUTH_TOKEN`, and the publish falls back to anonymous auth and fails.
+
+### 3.4 The three ways to ship
+
+- **A. Auto on merge (common).** Land on the default branch; if a `paths:`-filtered file changed, the workflow fires and ships a patch.
+- **B. Manual dispatch (minor/major).** **Actions → Publish to npm → Run workflow**, pick `bump = minor|major`.
+- **C. Local (CI down / one-off):** `npm version <patch|minor|major>` → `npm publish` → `git push --follow-tags`.
+
+Local auth uses two tokens, two homes: a **read** token in `~/.npmrc` (`//registry.npmjs.org/:_authToken=…`) for `npm install`, and `NPM_PUBLISH_TOKEN` as an env var (sourced from `~/.zsh_secrets` or equivalent, **not** in `.npmrc` or the repo) for `npm publish`.
+
+> **Agent guard — if `NPM_PUBLISH_TOKEN` isn't in the environment, do not work around it.** No `npm login` to swap the user's auth, no rewriting `~/.npmrc`, no substituting the read token (it lacks publish rights → `403`), no `--registry` overrides, no temp-file token. Instead **stop and report**: "This repo can't publish locally — `NPM_PUBLISH_TOKEN` isn't set. Source `~/.zsh_secrets` (or wherever you keep it) and re-run, or trigger the CI workflow." Some users publish exclusively from CI — that's the default path for a reason.
+
+Verify after any flow: `https://www.npmjs.com/package/@nurix/<name>` and a clean-dir `npx @nurix/<name>@latest`.
+
+### 3.5 Monorepo deviations
+
+When the package lives in `packages/<pkg>/` of a multi-package repo:
+
+- **`working-directory: packages/<pkg>`** on the bump and publish steps so they operate on the right `package.json`.
+- **Scoped concurrency** — `group: publish-<pkg>` lets sibling packages publish in parallel.
+- **Tag prefix — only with multiple tagging packages.** `npm version --tag-version-prefix="<pkg>-v"` (→ `<pkg>-v0.2.0`) is worth it only when more than one package cuts release tags, so they don't collide. A single publishable package (etna's case, even though it's laid out as a monorepo) uses plain `v0.2.0`.
+
+A repo with one publishable package only needs `working-directory`; skip the prefix, and concurrency scoping is optional.
+
+### 3.6 Common pitfalls
+
+- **402 Payment Required** — `access: "public"` on an org without a plan for free public scoped packages. Use `"restricted"` (or upgrade the plan).
+- **403 Forbidden** — `NPM_PUBLISH_TOKEN` missing/wrong, or its user lacks `nurix` write access, or it's a read-only (not Automation) token.
+- **"Cannot publish over previously published version x.y.z"** — a bump ran but publish failed and was re-run without rebasing. `git reset` the bump and let CI re-bump, or `npm version patch && git push --follow-tags && npm publish`.
+- **Publish succeeds but `npx @nurix/foo` is "command not found"** — no `bin` field, or `bin` points outside `files`, or the script is missing its `#!/usr/bin/env node` shebang.
+- **"Git working directory not clean" on `npm version`** — the checkout has untracked/modified files; build only into `.gitignore`d paths (the components repo builds into `dist/`).
+- **Published tarball contains source** — missing `files` in `package.json`. Add `["dist"]` and republish.
+- **Auto-publish fires too often** — no `paths:` filter or one that's too broad. Tighten it to artifact-affecting files, or drop the push trigger for `workflow_dispatch`-only.
+- **Workflow loops forever** — the bump commit lacks `[skip ci]`. Invoke `npm version` with `-m "chore: release v%s [skip ci]"`.
+- **A normal commit silently skips its own push** — the inverse trap. GitHub scans the head commit's **whole message** (subject _and_ body) for skip directives (`[skip ci]`, `[ci skip]`, `[no ci]`, `[skip actions]`, `***NO_CI***`). If any hand-written commit merely _mentions_ the literal token in prose, the entire push is skipped and the publish never fires (symptom: branch moved, paths matched, Actions on — yet zero runs for the SHA). Never write the literal token in a commit message or PR body unless you mean it; to ship a push that carried it by accident, re-trigger via **Run workflow** / `gh workflow run … --ref dev`.
+
+---
+
+## 4. Quick checklist for a new `@nurix/*` package
+
+- [ ] `package.json`: `name: "@nurix/X"`, `version: "0.1.0"`, `private: false`, `publishConfig.access: "restricted"`, `files: [...]`
+- [ ] Build step wired into `prepack` (or `prepublishOnly`)
+- [ ] Name follows §1; if it's a workspace member, boundaries follow §2
+- [ ] `.github/workflows/publish.yml` from §3.3
+- [ ] `NPM_PUBLISH_TOKEN` secret added to the repo
+- [ ] First publish from local (`npm publish`) to verify the pipeline, then a no-op commit to verify CI
+- [ ] README notes the `@nurix` scope so consumers know they need org access

package/data/harnesses/code/skills/brainstorm/README.md

@@ -128,13 +128,13 @@ The writing posture is a **mode** chosen at intake, folded into `build.md`:
 
 ## Exit artifacts
 
-The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one subfolder per topic). At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
+The session writes a design record at `docs/research/{topic}-brainstorming/` (one folder per topic), moved to `docs/history/brainstorms/{topic}/` on harvest. At `stop`, after the final five-source sync (self-containment included — the record is verified standalone-readable exactly when it's about to become the only survivor of the session), the skill _offers_ what to **publish** from it (`AskUserQuestion`, multi-select — a session can emit more than one):
 
 - **Source of truth** — one consolidated, README-style canonical doc for the thing designed (`templates/source-of-truth.md`); lands in the repo's feature/architecture doc home, else a topic `Readme.md`.
 - **Plans** — one or more executable plan docs → `docs/history/plans/` (Status: Draft).
-- **Harvest into the living docs** — conclusions dispersed by scope into ADRs, the domain model, and the backlog.
+- **Harvest into the living docs** — conclusions dispersed by scope into ADs (architecture decisions), the domain model, and the backlog.
 
-The `docs/brainstorm/{topic}/` record is **kept** whichever you pick — never deleted; it is the provenance every artifact traces back to. See `exit-artifacts.md`.
+The session record is **kept** whichever you pick — never deleted; on harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance every artifact traces back to. See `exit-artifacts.md`.
 
 ---
 
@@ -159,4 +159,4 @@ brainstorm/                  # the skill (in .claude/skills/)
 └── templates/        # pillar templates + evidence.md + source-of-truth.md, used in the record and at stop
 ```
 
-The session itself is written to `docs/brainstorm/{topic}/` (kept, committed) — not here.
+The session itself is written to `docs/research/{topic}-brainstorming/` (committed; moved to `docs/history/brainstorms/{topic}/` on harvest) — not here.

package/data/harnesses/code/skills/brainstorm/SKILL.md

@@ -42,6 +42,8 @@ Write as if the transcript is already deleted — it will be. The folder must le
 
 ## `start`
 
+First, consult the two indexes — never scan folders. `docs/research/Readme.md` lists **active** sessions; `docs/history/brainstorms/Readme.md` lists **harvested** ones. Match the topic against both: an active match → resume it (§3, reusing its folder); a harvested match → surface that prior exploration and ask whether to reopen it (move the folder back to `docs/research/{topic}-brainstorming/`) or branch a fresh topic; no match → a new session. Then:
+
 ### 1. The entry gate
 
 A session needs substance before it opens. Ask for a **basis**: a reference document (path or URL), or a one-shot brain dump of the whole idea, right now, in prose.
@@ -62,7 +64,7 @@ Then propose the **aspect map**: the thinking dimensions for _this specific idea
 
 ### 3. Bootstrap
 
-Session folder: `docs/brainstorm/{topic}/` — a **committed, kept** design record, one subfolder per design topic (slug the topic; confirm it in one line). Resume an existing topic by reusing its folder if it already holds a `state.md`. The record stays in the repo after the exit artifacts publish (it is the provenance they distil from — see `exit-artifacts.md`), so it lives under `docs/` like any other durable project knowledge, not at the repo root. Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
+Session folder: `docs/research/{topic}-brainstorming/` — a **committed** design record, one folder per design topic (slug the topic; confirm it in one line). Add a row to the `docs/research/Readme.md` index. Resume an existing topic by reusing its folder if it already holds a `state.md`. The record lives here while the session is active; on close **and** harvest it moves to `docs/history/brainstorms/{topic}/` as the provenance the exit artifacts distil from (see `stop` and `exit-artifacts.md`). Create only the pillars the complexity calls for, from `templates/` (never overwrite existing files; if a template is missing, create the file from the field lists in **Pillars**). `basis/` holds the frozen inputs; `evidence/` materializes on the first session-produced analysis (memory contract, rule 3). Write top-level `state.md`:
 
 ```
 STATE: open
@@ -136,8 +138,8 @@ Zero means _"audited against the five sources and clean"_ — never _"nothing ca
 
 1. Run a final sync (wait for any in-flight sync first). It audits all five sources — self-containment included, so the record is verified standalone-readable exactly when it is about to become the only survivor of the session.
 2. **Coherent** → say so and proceed. **Questions open** → list them plainly (English first, codes in parentheses) and offer per question: resolve now (mini-converge) / park explicitly (backlog or non-goals, with reason) / leave open and stop anyway — the folder keeps full state and resumes exactly where it left off. Flag parked **self-containment** gaps distinctly: parking one means the record ships not fully standalone.
-3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADRs, the domain model, the backlog). The `docs/brainstorm/{topic}/` record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
-4. Write `STATE: closed` + one-line reason. Print: _"Run `/brainstorm start` to resume."_
+3. **Publish exit artifacts** — see `exit-artifacts.md`. Offer the choice (`AskUserQuestion`, multi-select): a **source of truth** (one consolidated README-style doc — the standing reference for the thing designed), **plans** (executable work → `docs/history/plans/`), and/or **harvest into the living docs** (conclusions dispersed by scope into ADs — architecture decisions — the domain model, the backlog). The session record is **kept** (committed) whichever you pick — it is the provenance every artifact traces back to and the seed the next session resumes from.
+4. Write `STATE: closed` + one-line reason. If the harvest is complete (conclusions dispersed into the living docs), **move** the folder from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/` and update both indexes — drop its row from `docs/research/Readme.md`, add it to `docs/history/brainstorms/Readme.md`. If the session is only paused (questions parked, more to come), leave it in `docs/research/` and update its index row's status. Print: _"Run `/brainstorm start` to resume."_
 
 ## Conduct — holds for the whole session
 

package/data/harnesses/code/skills/brainstorm/exit-artifacts.md

@@ -1,8 +1,9 @@
 # Exit artifacts
 
-What `/brainstorm stop` publishes from a closed session. The `docs/brainstorm/{topic}/` record is **kept
+What `/brainstorm stop` publishes from a closed session. The session record is **kept
 either way** — committed provenance, never a scratchpad. Exit artifacts copy the session's _conclusions_
-outward into the form the work needs; the record stays as the source they trace back to.
+outward into the form the work needs; the record stays as the source they trace back to — and, once
+harvested, moves from `docs/research/{topic}-brainstorming/` to `docs/history/brainstorms/{topic}/`.
 
 At `stop`, after the final sync, **offer the artifact choice** (`AskUserQuestion`, multi-select — a session
 can publish more than one):
@@ -21,7 +22,7 @@ does; pick it too if you want both the one-doc reference and the integrated head
 
 One consolidated, README-style document — the canonical reference for the thing designed. Distil every
 pillar into it: `thesis.md` → what it is; `domain-model.md` → how it works + parts; `decisions.md` →
-present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADRs);
+present-tense rationale (no `D-N` codes, no options-considered — those stay in the record and ADs);
 `non-goals.md` + accepted tradeoffs → constraints; still-open questions → a one-line pointer back to the
 record. Template: `templates/source-of-truth.md`.
 
@@ -44,19 +45,22 @@ not folders — a finding scoped to one module still lands in `docs/architecture
 
 | Session source | Destination |
 | --- | --- |
-| Decisions (any scope) | one ADR per cohesive theme → `docs/architecture/adr/NNN-{slug}.md` (`documentation` skill ADR template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the ADR's Options Considered table) |
+| Decisions (any scope) | one AD per decision subject → `docs/architecture/decisions/AD-NNN-{slug}.md` (`documentation` skill AD template; `status:` frontmatter is the lifecycle source of truth; rejected alternatives → the AD's Options Considered table). A decision that revises an already-recorded subject does **not** mint a new AD — update that AD's body in place and append the revision to its Decision Changelog |
 | `domain-model.md` | `docs/architecture/domain-model.md`; note any IA / cross-cutting contract change there — the `boundary` skill reads it from source at the next plan check |
-| Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant ADR |
-| `tech.md` deviations | `docs/architecture/references.md` or the relevant ADR |
+| Doctrine / glossary / rejected | `docs/architecture/{domain-model,glossary}.md`, or the relevant AD |
+| `tech.md` deviations | `docs/architecture/references.md` or the relevant AD |
 | `non-goals.md` / `references.md` | `docs/architecture/{non-goals,references}.md` |
 | `backlog.md` | `docs/history/backlog.md` (P0–P3) |
 | Still-open questions | `docs/architecture/open-questions.md`, each with a _Resolution lands in_ pointer |
 
 Append a changelog entry at `docs/history/changelog/YYYY-MM-DD-brainstorm-{slug}.md` listing what was published where.
 
-## After publishing — keep the record
+## After publishing — move the record to history
 
-**Keep `docs/brainstorm/{topic}/` — never delete it.** The exit artifacts now carry the distilled
-conclusions, but the record stays committed as their provenance: a traceable source for every published
-headline, and the seed the next `/brainstorm start` on this topic resumes from. Retire a topic's folder
-by hand only when the design line is truly dead.
+**Move `docs/research/{topic}-brainstorming/` → `docs/history/brainstorms/{topic}/`, and update both
+`Readme.md` indexes** (drop the row from `docs/research/Readme.md`, add it to
+`docs/history/brainstorms/Readme.md`). The exit artifacts now carry the distilled conclusions; the record
+itself is **kept** — never deleted — but as harvested provenance it belongs under `docs/history/brainstorms/`:
+a traceable source for every published headline, and the seed the next `/brainstorm start` on this topic
+resumes from. A session that is only **paused** (not harvested) stays in `docs/research/`. Retire a topic's
+folder by hand only when the design line is truly dead.

package/data/harnesses/code/skills/brainstorm/templates/source-of-truth.md

@@ -3,8 +3,8 @@
 > This is a **source-of-truth doc**: the standing, canonical reference for [thing]. Write it like a
 > README — present tense, reader-first, the thing described as it _is_. It is **not a plan** (no steps,
 > status, or sequencing — those go to `docs/history/plans/`) and **not the brainstorm record** (no
-> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in
-> `docs/brainstorm/{topic}/` and any ADRs). One document; if a section outgrows it, link out, don't sprawl.
+> `Q-N`/`D-N` codes, no "Why / How to apply" ledger, no rejected alternatives — those stay in the harvested
+> record at `docs/history/brainstorms/{topic}/` and any ADs). One document; if a section outgrows it, link out, don't sprawl.
 >
 > **Placement.** In a repo with a feature-doc system this lands as `docs/features/{slug}.md` and carries
 > that system's frontmatter (`owns:` / `module:` / `keywords:` / `status:`). Cross-cutting → `docs/architecture/{slug}.md`.
@@ -31,7 +31,7 @@ reader-first description. Prose and tables; a diagram only if it earns its token
 
 [The load-bearing decisions, folded into present-tense rationale — "the index is single-writer because
 concurrent writes corrupted it," not "we decided X over Y." No decision codes, no options-considered
-table. The full rationale and the roads not taken live in the brainstorm record and ADRs — cite them,
+table. The full rationale and the roads not taken live in the brainstorm record and ADs — cite them,
 don't reproduce them.]
 
 ## Constraints & non-goals
@@ -41,9 +41,9 @@ and what is explicitly out of scope.]
 
 ## Open questions
 
-[One line pointing at `docs/brainstorm/{topic}/pillars/questions.md` if any remain open. Omit if none.]
+[One line pointing at `docs/history/brainstorms/{topic}/questions.md` if any remain open. Omit if none.]
 
 ---
 
-_Distilled from `docs/brainstorm/{topic}/`. That record holds the rationale, the rejected alternatives,
+_Distilled from `docs/history/brainstorms/{topic}/`. That record holds the rationale, the rejected alternatives,
 and the provenance for everything above._