@nurix/etna 0.18.19 → 0.18.21

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": "36cfdb5ed4f4",
+    "fingerprint": "e6c7761bdd49",
     "harnesses": {
         "code": {
             "plugin": "code",

package/data/harnesses/code/CLAUDE.md

@@ -45,7 +45,7 @@ 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`.
+- 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,11 +127,11 @@ 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/)
+├── brainstorm/            # Optional — kept design records, one {topic}/ subfolder per session (state.md + flat pillar files + basis/, evidence/)
 │   └── {topic}/           #   created by the `brainstorm` skill; NOT scaffolded empty
 ├── history/
 │   ├── CHANGELOG.md       # Master changelog index

package/data/harnesses/code/harness.json

@@ -1,11 +1,11 @@
 {
   "harness": "code",
   "name": "code",
-  "version": "3.1.3",
+  "version": "3.1.6",
   "files": [
     ".prettierrc.json",
     ".prettierignore",
     ".vscode/settings.json"
   ],
-  "digest": "d078197b0b06"
+  "digest": "14662025ad2d"
 }

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

@@ -132,7 +132,7 @@ The session writes a **kept** design record at `docs/brainstorm/{topic}/` (one s
 
 - **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`.
 

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

@@ -136,7 +136,7 @@ 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.
+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 `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."_
 
 ## Conduct — holds for the whole session

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

@@ -21,7 +21,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,10 +44,10 @@ 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 |

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

@@ -4,7 +4,7 @@
 > 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.
+> `docs/brainstorm/{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,7 +41,7 @@ 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/brainstorm/{topic}/questions.md` if any remain open. Omit if none.]
 
 ---
 

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

@@ -0,0 +1,68 @@
+---
+name: design
+description: Design, build, review, polish, redesign, or introspect internal operator UIs — CRMs, ticket queues, admin panels, analytics dashboards, log viewers, command centers, and any internal/back-office tool an operator, agent, or analyst works in all day. Resolves the project's brand from its design-tokens artifact (design.tokens.json), derives structure from the domain objects, emits a working React + Tailwind UI against @nurix/components or shadcn/ui, and holds it to operator-grade quality across a full sixteen-dimension taxonomy. Triggers on "build a dashboard", "design an admin panel", "review this CRM UI", "polish this queue", "redesign this internal tool", "why does this table feel off", "make it feel like Linear", or any create/improve/introspect request for an internal operator interface. Coverage is the operator pack: marketing sites, landing pages, storefronts, homepages, and mobile-native apps are out of scope — no carried pack covers them, so refuse cleanly and redirect. The machinery is not the limit; the packs are.
+---
+
+# design
+
+The design skill. Its shipped coverage is the **operator pack**: internal tools — CRMs, ticket queues, admin panels, dashboards, log viewers, command centers. It resolves the brand, derives the structure from the domain objects, emits a React + Tailwind UI, and enforces operator-grade quality across the sixteen-dimension taxonomy. This file is a router — it names where to go and what not to do; the knowledge lives in the references and data below, loaded on demand.
+
+## The front gate
+
+**Recognition, by precedence — stop at the first that resolves.**
+
+1. **Project-declared identity wins.** A resolved token artifact whose payload carries `product-traits` decides coverage outright.
+2. **The signal checklist recognizes** when no project artifact speaks: the audience is employees / agents / analysts; the metric is task throughput, not conversion; the surfaces are queues / tables / forms / monitors. The design.md library (`data/design-md/library/`) assists the lookup by resemblance — it never overrides the checklist.
+3. **Refuse with a redirect** when no carried pack covers the brief — marketing sites, landing pages, storefronts, mobile-native. State plainly which pack is missing and point elsewhere; never a degraded attempt. The machinery is artifact-agnostic; the boundary is pack coverage, and it moves only by adding a pack.
+
+**Then the intent digest — infer and confirm.** Build a structured digest — entities, archetype guesses, density tier, substrate — with **every inference marked as inferred**. Present it once for confirmation before any derivation begins. Ask questions only for strategic unknowns whose answers change the design. Nothing auto-runs on silent inference; nothing stalls on a blanket interview.
+
+## Boot order
+
+Before **any** design output, read [`references/hard-rules.md`](references/hard-rules.md) — the boot-loaded floor of 131 rules <!-- count:rules=131 --> (bans, deterministic thresholds, mandatory procedures, each keyed to an anchor id). Then route by workflow. JIT loads never happen at boot — they fire at the gate that needs them.
+
+| Route | Load, when |
+| --- | --- |
+| **create** (nothing exists yet) | [`references/create.md`](references/create.md) at intake; then per phase: [`structure.md`](references/structure.md) at structure, [`personality.md`](references/personality.md) at tokens, [`lifecycle.md`](references/lifecycle.md) + [`interaction.md`](references/interaction.md) at surfaces |
+| **improve** (a UI already exists) | [`references/improve.md`](references/improve.md) + [`references/diagnosis.md`](references/diagnosis.md) |
+| **introspect** (why is it wrong) | [`references/introspect.md`](references/introspect.md) + [`references/diagnosis.md`](references/diagnosis.md) |
+| JIT — archetype exemplar | `data/operator-pack/exemplars/<slug>.tsx` at that archetype's emission gate during surfaces — never at boot |
+| JIT — fixture pair | `data/catalog/fixtures/<id>.{flag,pass}` only when a rule is contested and the contrastive pair teaches it (authoring repo only — pairs are stripped from shipped bundles; when the folder is absent, the finding's exact-fix line carries the teaching) |
+| JIT — combination tables, look | `data/combinations/product-router.csv` at every intake; `typography.csv` / `palettes.csv` / `styles.csv` at intake only when the look resolves to authoring a fresh artifact, typography and palettes again at tokens before any hint resolves — contract: [`data/combinations/Readme.md`](data/combinations/Readme.md) |
+| JIT — combination tables, surface picks | `data/combinations/charts.csv` at the emission gate of any chart-composing surface; `icons.csv` once at the first surface-composition gate — same contract |
+
+A consulted combination table is a **floor** — going off-table is allowed only against a stated reason recorded into what the run produces (the token `$description`, an adjacent code comment, the finding body — sites per the contract); an unrecorded off-table pick is a violation, the same class as skipping a gate.
+
+## The three workflows
+
+**Create** makes taste where nothing exists. It runs **six gated phases** — intake, structure, scaffold, tokens, fixtures, surfaces — and closes on the verification ladder. Each boundary is `phase-gate.mjs <phase>`; the next phase does not open until the gate is green. The object pass is never skipped — a small brief earns a proportionally small pass, never a guessed archetype; every surface takes an archetype from the closed six <!-- count:archetypes=6 --> (`list-detail`, `dashboard`, `entity-detail`, `create-edit`, `log-stream`, `command-center`). Fixtures are seeded and generated **before** surfaces, because realistic data is taste-bearing design material. See [`create.md`](references/create.md).
+
+**Improve** is one engine over a UI that already exists, run at a point on scope × depth × authority; the verbs — review, polish, redesign, typeset — are parameter bindings, never sibling files. Emission is **jailed to the lever manifest** by default: an edit may emit only values inside the project artifact's vocabulary, enforced by the end-of-run verify sweep (`preship-sweep.mjs --files <touched...> --manifest design.tokens.json`). On a foreign UI, **extract a token artifact first** (payload `provenance: extracted`) — record what IS, never what should be. Wrong fundamentals are tier-two (`lever-change`) findings: finish the within-levers work, report them, and offer a consent-gated lever run — never change levers unbidden. At the fix step, a finding that names a chart or icon loads `data/combinations/charts.csv` / `icons.csv` before the edit. See [`improve.md`](references/improve.md) + [`diagnosis.md`](references/diagnosis.md).
+
+**Introspect** explains **why** a UI isn't working; it reads code and never edits it. **Ask the reader question first**, every run, verbatim — designer / developer / PM — never inferred, never a stored default. Diagnose causes-first (Structure → Behavior → Perception), narrate each finding from the felt symptom down to its cause, render it in the reader's register, and **always file a dated report**. When the audited UI renders charts, diagnosis loads `data/combinations/charts.csv`. See [`introspect.md`](references/introspect.md) + [`diagnosis.md`](references/diagnosis.md).
+
+## Scripts
+
+Under `scripts/`; spawn them from this skill directory. All ESM, Node ≥ 22, zero dependencies. **You drive them — nothing hooks them to the session or to your edits; you decide when to run each, at the moments below.** Machine rules fire at the structural boundaries — the phase gates, improve's end-of-run verify, and the pre-ship sweep; the gates are the wall, not your discipline. Exit 1 anywhere means violations: resolve every one — fix now, or classify the inapplicability into the decay ledger; never ignore.
+
+- `phase-gate.mjs <phase> [--project <dir>]` — validates a phase's exit preconditions **and runs the machine catalog + lever-manifest drift check over the project's UI files**; exit non-zero printing the exact fix. Phases: `intake`, `structure`, `scaffold`, `tokens`, `fixtures`, `surfaces`.
+- `preship-sweep.mjs [--project <dir>] [--files <file...>] [--manifest design.tokens.json]` — whole-app catalog sweep + viewport sweep + copy audit + scope cross-check; prints the manual `proc-*` checklist. With `--files`, a scoped verify run over just those files — improve's end-of-run gate.
+- `render-rung.mjs [--project <dir>] [--url <dev-server>]` — render-only rules at 375/768/1024/1440 plus the render instruments (evidence, never gates); a one-line notice and exit 0 when no headless browser is importable.
+- `derive-personality.mjs <artifact-dir> [--check|--emit <outdir>] [--theme light|dark]` — `--check` is the coverage gate over the design-tokens artifact; `--emit` writes `personality.css` + `globals.css`. The gate fails unless all 26 primitives <!-- count:primitives=26 -->, both dials, and every one of the 34 color values (17 semantic <!-- count:semantic-tokens=17 --> + 17 substrate <!-- count:substrate-tokens=17 -->) <!-- count:color-tokens=34 --> is assigned or hinted; emit refuses while any token carries a hint.
+- `scaffold.mjs <structure.md> --out <dir>` — routes, nav, state-shells, and fixture wiring from the entity/surface map.
+- `generate-fixtures.mjs <structure.md> --seed <n> --out <dir>` — seeded, domain-shaped fixture modules.
+- `self-integrity.mjs` — run from `skills/design/`: anchor parity (prose ↔ catalog), stated counts, fixture-pair presence and contrastive validity. CI-owned.
+
+## Project artifacts
+
+The skill writes these into the consumer project; the emitted code and these files are the only design record — no sidecar caches.
+
+- `design.tokens.json` + `design.resolver.json` (+ `design.tokens.dark.json` when the look has dark values) at project root — the canonical look artifact + lever manifest ([schema](data/design-tokens/SCHEMA.md)). Create writes it; improve reads and, on a foreign UI, extracts it. Payload provenance is one of `project | extracted | library | default` (extracted sits at project precedence).
+- `docs/design/structure.md` — the entity/surface map, in a fenced `yaml structure` block; `scaffold.mjs` consumes it.
+- `docs/design/findings/YYYY-MM-DD-<slug>.md` — dated introspect and review reports.
+- `docs/memory/design-decay.md` — the decay ledger: rules skipped or fought, the fix-or-classify classifications, guidance that produced wrong output. Append-only, maintainer-read, human-closed. The skill never self-modifies — it observes decay; the maintainer closes it.
+
+## Substrate and scope
+
+- Substrate is **`@nurix/components` (default) or `shadcn/ui` only** — the Tailwind + shadcn-flavor floor. Import `@nurix/components` by subpath (`@nurix/components/button`); emit `.tsx`, never `.jsx`.
+- The `components` API reference is a **separate skill** — a pure reference, never invoked from here. `design` ships as one skill with zero cross-skill invocation; all its knowledge is lazily-loaded data under `references/` and `data/`.