@nurix/etna 0.20.1 → 0.20.3

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

@@ -0,0 +1,57 @@
+---
+name: codegraph
+requires-tool: codegraph
+description: Query the codegraph index before reading source. An LLM-first codebase index (symbols, call references, git history, co-change coupling, ownership) answering whole questions in one call. Use it to localize, scope, and assess blast radius on this repository; use grep/read for string literals, mechanism, and data flow — the skill states which is which. Applies to any task that starts with "where is", "who calls", "what changed", "who owns", "what breaks", or "is this tested".
+---
+
+# codegraph — the index-first method
+
+**If the tool is absent** (`codegraph --version` fails): do not stall. Read `.claude/state/decisions.tsv` for `tool.codegraph`.
+
+- **`declined`** — fall back to the cold method (grep, targeted reads, `git log`) **silently**. Do not mention the tool, do not re-offer. The user has answered.
+- **undecided** (no file, no key, or anything unrecognised) — fall back to the cold method *and* make the offer **once**: this repository would answer "where is / who calls / what changed / who owns" from an index instead of a grep sweep; install with `npm install -g @nurix/codegraph`, then `codegraph index`. **Ask, never act** — a global npm install modifies the machine, and indexing writes to `~/.codegraph`. Record the answer with `recordDecision` either way, so the question is asked at most once per repo per machine.
+- **`accepted` but the binary is gone** — treat as undecided; a failed or removed install is not a standing yes.
+
+**A failed install is `absent`, not an error to retry.** Global installs fail on machines without permission; say so once, fall back, and move on.
+
+**An explicit invocation overrides a stored decline.** If the user asks for this skill by name, honour it and re-offer — "stop asking" must never become "never usable".
+
+**If the repository is not indexed** (a query answers `UNAVAILABLE: this repository has not been indexed yet`), that is the tool degrading correctly, not a failure: offer `codegraph index` under the same ask-first rule. The SessionStart probe deliberately does **not** claim index freshness — it can only see the binary — so this is where index state is actually established.
+
+Everything below assumes the tool is present and the repository indexed.
+
+The `codegraph` CLI is on PATH and defaults to the git root of the working directory — inside this repository, no flags are needed. The index is prebuilt; `codegraph projects` shows freshness (a `[STALE]` marker means HEAD moved since indexing — refresh with `codegraph index --commits 30000`, ~40s). Every answer states its own confidence per section (`CERTAIN` / `INFERRED` / `UNRESOLVED`), announces anything the token budget dropped, and says what an empty section means. Trust those labels.
+
+## The method order
+
+Localize through the index **before** opening any file, in this order; then read only the files it points at.
+
+1. **`codegraph find <fragment>`** — symbols and file paths by name fragment. The entry point when you only have issue vocabulary. Symbol names only — it will never match string literals, dict keys, or SQL fragments (grep for those, without shame).
+2. **`codegraph where-defined <symbol>`** / **`codegraph outline <file>`** — pin the definition; map a big file. `outline` turns a 100+ declaration file into a navigable, line-numbered list — use it instead of reading god files blind. On a large file add `--budget 0` (see traps).
+3. **`codegraph who-calls <symbol>`** / **`codegraph impact <target>`** — callers, and blast radius (static reach + historical co-change reach, reported separately on purpose: they disagree, and the disagreement is information).
+4. **`codegraph churn --days N --path <dir>`** · **`coupling --path <file>`** · **`owners <path>`** · **`tests-covering <file>`** — the history layer: what's hot, what changes together (including *hidden coupling* — co-change with no static reference, the one fact reading code cannot reveal), who knows this area and how recently, which test file historically guards this file.
+5. **`codegraph god-objects --minSymbols 30`** / **`hotspots`** / **`overview`** — repo-scale orientation and risk.
+
+Then read, with `sed -n` ranges at the lines the index gave you. The index does discovery; reading does diagnosis. Add `--json` when a wrapper needs structure.
+
+There is also **`codegraph blame <file> [--line N]`** — the commits behind a file or one specific line, answered by git at query time; **`codegraph refs <name>`** — the data-reference layer: where a name is used as a dict/object key, attribute/field, import, or type annotation, with read/write direction, and a cross-language flag when the same name spans Python and TypeScript files (this answers "who reads `x_axis_sort`" / "who writes `chart.query_context`" in one call — the questions that used to need grep); and **`codegraph drift`** — near-duplicate function bodies crossed with co-change history: similar code whose files never change together is an unfinished refactor waiting to disagree. `who-calls` additionally tabulates which keyword arguments each call site passes, so "which call sites omit this option" is one query.
+
+## The boundary — what the index cannot answer (fall back immediately, don't retry)
+
+- **Free-text string literals** (SQL templates, prose, format strings) — grep. Identifier-shaped keys and fields ARE indexed (`refs <name>`); anything longer or with spaces is not.
+- **Framework reflection** (Marshmallow `@post_load`, signal handlers, `appbuilder.add_api(Cls)` registration) — invisible to call edges. Bare decorator *application* (`@has_access_api`) IS indexed as a reference; what the decorator does and when it runs is not.
+- **Data flow and mechanism** ("does this value reach that function", "what order do these run in") — always reading work.
+
+Indexed symbol forms include statement declarations, `const X = () => {}`, named function expressions inside wrapper calls (`typedMemo(function DataTable() {})`), TS/JS class fields, and Python class-body fields (`is_dttm = Column(...)`); nested members render as `Parent › member` in `outline`.
+
+## Traps (each cost a prior agent real time)
+
+- **Bare-name collision.** Call references match by name, not resolved binding. When a name has several definitions, `who-calls` lists every candidate and says so in its subject line — read that section before trusting the call sites, and pass `--scope <path-fragment>` (also on `find`, `where-defined`, `impact`) to narrow to a package.
+- **`codegraph functions` lists the CLI's own functions**, not the repository's. For repo functions use `find`. An explicit `--limit` lifts the default token budget, so a full `outline` needs no `--budget 0` incantation (an explicit `--budget` still wins).
+- **Churn windows.** `churn --days 180` returning nothing does not mean quiet history — widen the window. Directory-scope churn ranks by raw commit count and buries small-but-critical files; for specific files use `owners`/`coupling` per file.
+- **`tests-covering` is co-change evidence, not executed coverage** — it names the right test file to open; it cannot say the specific scenario is tested.
+- **Coupling on a busy file has a noise tail** — partners at <15% shared commits are usually PR-cohabitation, not real coupling. Verify a partner with a read before adding it to a touch-list.
+
+## Division of truth in this repository
+
+`docs/` is the source of truth for **intent** — what a feature is for, its invariants, decisions, vocabulary. codegraph is the source of truth for **facts** — where things are, who calls what, what changed together, who owns what. Never copy live facts (caller counts, churn numbers) into docs as if permanent; never ask the index for intent.

package/data/harnesses/code/skills/design/components/charts.md

@@ -12,7 +12,7 @@ Three tiers, all consuming the canonical `ChartSeries[]` / `ChartPoint` data con
 
 ## Spark
 
-Tier-0 inline mark — no axes, no chrome. Import from `@nurix/components/spark`.
+Tier-0 inline mark — no axes, no chrome. Import from `@nurix/components/element/spark`.
 
 **Props:** `series` (`ChartSeries[]` or plain `number[]`), `type` [line|bar|pie], `filled`, `fillOpacity`, `strokeWidth` (line), `gap` (bar), `width`, `height`, `useTokens` (default false: self-contained oklch; true: `--chart-N` tokens)
 

package/data/harnesses/code/skills/design/components/collections.md

@@ -47,7 +47,7 @@ Define table columns using the `defineColumn()` helper.
 - `display` - `{ width, sortable }` (width optional — columns are fluid when unset)
 - `cell` - Custom render function `(row) => ReactNode`
 
-For full control, pass your own `cell()` or import a renderer from `@nurix/components/table` (`StatusPill`, `SelectCell`, etc.) as an escape hatch.
+For full control, pass your own `cell()` or import a renderer from `@nurix/components/block/table` (`StatusPill`, `SelectCell`, etc.) as an escape hatch.
 
 ### Metadata options by component
 
@@ -64,7 +64,7 @@ For full control, pass your own `cell()` or import a renderer from `@nurix/compo
 ### Example
 
 ```tsx
-import { defineColumn } from "@nurix/components/table";
+import { defineColumn } from "@nurix/components/block/table";
 
 const columns = [
   defineColumn({
@@ -100,7 +100,7 @@ const columns = [
 
 ## PageHeader
 
-Config-driven page masthead with an optional stat ledger — router-agnostic (the consumer owns navigation). Import from `@nurix/components/page-header`.
+Config-driven page masthead with an optional stat ledger — router-agnostic (the consumer owns navigation). Import from `@nurix/components/block/page-header`.
 
 **Props:** `title`, `eyebrow` (breadcrumb segments — strings or linked `Crumb`s; last is the current page), `description`, `statusSlot`, `actions`, `stats` (`Stat[]` ledger), `back` (`BackLink`), `onBack`, `onNavigate` (fired with a crumb's/stat's `href`), `statsAlign` [left|right], `tall`
 

package/data/harnesses/code/skills/design/components/index.md

@@ -10,49 +10,49 @@ Columns: `concept` (the composable idea) · `category` (which deep reference cov
 
 ```csv
 concept,category,nurix,shadcn,fallback
-button,inputs,Button (button),Button,"native <button>, variants via class, focus-visible ring"
-text-input,inputs,"Input (input) — onSave commit, regex validator",Input,"<input type=text>, commit on blur/Enter"
-number-input,inputs,"NumberInput (number-input) — min/max/step",—,"<input inputmode=numeric>, clamp on commit, Escape reverts"
-textarea,inputs,"Textarea (textarea) — Cmd/Ctrl+Enter commits",Textarea,"<textarea>, blur commits, Escape resets draft"
-checkbox,inputs,Checkbox (checkbox),Checkbox,"<input type=checkbox> + label, indeterminate via JS"
-switch,inputs,Switch (switch),Switch,"role=switch button, aria-checked, Space toggles"
-radio-group,inputs,"RadioGroup + card/segmented variants (radio-group)",RadioGroup,"fieldset of <input type=radio>, arrow-key roving focus"
-select,inputs,"Select — searchable, multi, async (select)","Select; Combobox (Popover + Command)","<select> or listbox popover, typeahead, option objects not raw values"
-native-select,inputs,"Select* Radix family (native-select)",Select,"plain <select> behind a styled trigger"
-date-picker,inputs,DatePicker (date-picker),Date Picker (Calendar + Popover),"<input type=date> or calendar popover, ISO value"
-date-range-picker,inputs,"DateRangePicker — presets sidebar (date-range-picker)",—,"two bound date inputs, partial selection reverts on close"
-calendar,inputs,"Calendar (calendar) — react-day-picker",Calendar,"month grid <table>, arrow-key day navigation"
-slider,inputs,Slider (slider),Slider,"<input type=range> with visible value readout"
-rating,inputs,Rating (rating),—,"radio group of icon buttons, half-step optional"
-toggle,inputs,"Toggle · ToggleGroup (toggle, toggle-group)","Toggle, Toggle Group","aria-pressed buttons, single or multiple selection"
-otp-input,inputs,InputOTP (input-otp),Input OTP,"segmented one-char inputs, paste distributes across slots"
-icon-picker,inputs,"IconPicker · Icon (icon-picker)",—,"searchable icon grid in a popover, categorized"
-file-upload,inputs,MediaFilePicker (media-file-picker),—,"<input type=file> + drop zone, previews, size and count caps"
-form-field,inputs,"Cell — label/content/helper/error slots (cell)",Form + FormField (react-hook-form),"label + control + helper in one block, error slot below control"
+button,inputs,Button (element/button),Button,"native <button>, variants via class, focus-visible ring"
+text-input,inputs,"Input (element/input) — onSave commit, regex validator",Input,"<input type=text>, commit on blur/Enter"
+number-input,inputs,"NumberInput (element/number-input) — min/max/step",—,"<input inputmode=numeric>, clamp on commit, Escape reverts"
+textarea,inputs,"Textarea (element/textarea) — Cmd/Ctrl+Enter commits",Textarea,"<textarea>, blur commits, Escape resets draft"
+checkbox,inputs,Checkbox (element/checkbox),Checkbox,"<input type=checkbox> + label, indeterminate via JS"
+switch,inputs,Switch (element/switch),Switch,"role=switch button, aria-checked, Space toggles"
+radio-group,inputs,"RadioGroup + card/segmented variants (element/radio-group)",RadioGroup,"fieldset of <input type=radio>, arrow-key roving focus"
+select,inputs,"Select — searchable, multi, async (element/select)","Select; Combobox (Popover + Command)","<select> or listbox popover, typeahead, option objects not raw values"
+native-select,inputs,"Select* Radix family (element/native-select)",Select,"plain <select> behind a styled trigger"
+date-picker,inputs,DatePicker (compound/date-picker),Date Picker (Calendar + Popover),"<input type=date> or calendar popover, ISO value"
+date-range-picker,inputs,"DateRangePicker — presets sidebar (compound/date-picker)",—,"two bound date inputs, partial selection reverts on close"
+calendar,inputs,"Calendar (element/calendar) — react-day-picker",Calendar,"month grid <table>, arrow-key day navigation"
+slider,inputs,Slider (element/slider),Slider,"<input type=range> with visible value readout"
+rating,inputs,Rating (element/rating),—,"radio group of icon buttons, half-step optional"
+toggle,inputs,"Toggle · ToggleGroup (element/toggle, element/toggle-group)","Toggle, Toggle Group","aria-pressed buttons, single or multiple selection"
+otp-input,inputs,InputOTP (compound/input-otp),Input OTP,"segmented one-char inputs, paste distributes across slots"
+icon-picker,inputs,"IconPicker · Icon (compound/icon-picker)",—,"searchable icon grid in a popover, categorized"
+file-upload,inputs,MediaFilePicker (compound/media-file-picker),—,"<input type=file> + drop zone, previews, size and count caps"
+form-field,inputs,"Cell — label/content/helper/error slots (compound/cell)",Form + FormField (react-hook-form),"label + control + helper in one block, error slot below control"
 form-validation,inputs,,Form (react-hook-form),"form element with submit-time validation and inline field errors"
 rich-text-editor,inputs,,—,"@tiptap/react editor with toolbar and markdown shortcuts"
 code-editor,inputs,,—,"@monaco-editor/react, mono, optional read-only diff mode"
-modal-dialog,overlays,Dialog (dialog),Dialog,"<dialog> or fixed layer, focus trap, ESC closes, header→body→footer"
-confirm-dialog,overlays,"Dialog variant=danger — non-dismissible (dialog)",Alert Dialog,"modal with explicit confirm/cancel, no outside-click dismiss"
-side-panel,overlays,Sheet (sheet),Sheet,"fixed aside, focus-trapped, ESC closes, interruptible slide"
-bottom-drawer,overlays,Sheet side=bottom (sheet),Drawer (vaul),"fixed bottom panel spanning full width"
-command-palette,overlays,Command (command),Command (cmdk),"filtered list in a dialog, ⌘K opens, arrow-key + Enter"
-dropdown-menu,overlays,DropdownMenu (dropdown-menu),Dropdown Menu,"role=menu under a trigger, arrow-key nav, outside click closes"
-context-menu,overlays,ContextMenu (context-menu),Context Menu,"right-click menu at pointer position"
-popover,overlays,Popover (popover),Popover,"anchored floating panel, dismiss on outside/ESC"
-hover-card,overlays,HoverCard (hover-card),Hover Card,"preview panel on hover intent, delayed open/close"
-tooltip,overlays,Tooltip (tooltip),Tooltip,"short hint on hover/focus, never load-bearing content"
-data-table,collections,"Table + defineColumn (table)","<Table> + TanStack Table","semantic <table>, sticky header, tabular-nums, real pagination, status chips"
-table-primitives,collections,UiTable* family (ui-table),Table,"bare styled <table>/<thead>/<tbody> parts"
-list,collections,"List + ListToolbar + ListPagination (list)",—,"<ul> of rows with toolbar and pager"
-record-header,collections,"Header — config-driven (header)",—,"page-top block: breadcrumbs, title, status bar, actions"
-page-header-stats,collections,"PageHeader — Stat/Crumb/BackLink (page-header)",—,"title row + KPI strip + back link"
+modal-dialog,overlays,Dialog (compound/dialog),Dialog,"<dialog> or fixed layer, focus trap, ESC closes, header→body→footer"
+confirm-dialog,overlays,"Dialog variant=danger — non-dismissible (compound/dialog)",Alert Dialog,"modal with explicit confirm/cancel, no outside-click dismiss"
+side-panel,overlays,Sheet (block/sheet),Sheet,"fixed aside, focus-trapped, ESC closes, interruptible slide"
+bottom-drawer,overlays,Sheet side=bottom (block/sheet),Drawer (vaul),"fixed bottom panel spanning full width"
+command-palette,overlays,Command (compound/command),Command (cmdk),"filtered list in a dialog, ⌘K opens, arrow-key + Enter"
+dropdown-menu,overlays,DropdownMenu (compound/dropdown-menu),Dropdown Menu,"role=menu under a trigger, arrow-key nav, outside click closes"
+context-menu,overlays,ContextMenu (compound/context-menu),Context Menu,"right-click menu at pointer position"
+popover,overlays,Popover (element/popover),Popover,"anchored floating panel, dismiss on outside/ESC"
+hover-card,overlays,HoverCard (element/popover),Hover Card,"preview panel on hover intent, delayed open/close"
+tooltip,overlays,Tooltip (element/tooltip),Tooltip,"short hint on hover/focus, never load-bearing content"
+data-table,collections,"Table + defineColumn (block/table)","<Table> + TanStack Table","semantic <table>, sticky header, tabular-nums, real pagination, status chips"
+table-primitives,collections,UiTable* family (block/ui-table),Table,"bare styled <table>/<thead>/<tbody> parts"
+list,collections,"List + ListToolbar + ListPagination (block/list)",—,"<ul> of rows with toolbar and pager"
+record-header,collections,"Header — config-driven (block/app-header)",—,"page-top block: breadcrumbs, title, status bar, actions"
+page-header-stats,collections,"PageHeader — Stat/Crumb/BackLink (block/page-header)",—,"title row + KPI strip + back link"
 gantt-timeline,collections,GanttChart (activity-timeline),—,"time-scaled task rows, date axis, horizontal scroll"
-changes-feed,collections,ChangesList (changes-list),—,"grouped change-history feed, entity + operation labels"
-message-thread,collections,"Message family + MessageScroller (message, message-scroller)",—,"scrolling feed pinned to bottom, jump-to-new button"
-chat-bubble,collections,BubbleGroup + Bubble (bubble),—,"aligned bubble rows with reactions row"
-attachment,collections,Attachment family (attachment),—,"file card: media, title, actions, error state, dashed idle border"
-thread-marker,collections,"Marker — separator/border variants (marker)",—,"inline separator row with icon and label"
+changes-feed,collections,ChangesList (block/changes-list),—,"grouped change-history feed, entity + operation labels"
+message-thread,collections,"Message family + MessageScroller (compound/message, block/message-scroller)",—,"scrolling feed pinned to bottom, jump-to-new button"
+chat-bubble,collections,BubbleGroup + Bubble (element/bubble),—,"aligned bubble rows with reactions row"
+attachment,collections,Attachment family (compound/attachment),—,"file card: media, title, actions, error state, dashed idle border"
+thread-marker,collections,"Marker — separator/border variants (element/marker)",—,"inline separator row with icon and label"
 json-viewer,collections,,—,"react18-json-view collapsible tree, mono"
 virtualized-list,collections,,—,"react-window fixed-row virtualization for 1k+ rows"
 kanban-board,collections,,—,"flex columns of cards, @dnd-kit drag between columns, per-column count"
@@ -60,29 +60,29 @@ event-calendar,collections,,—,"month/week grid of events, today marker, overfl
 description-list,collections,,—,"<dl> two-column key/value grid, tabular values"
 filter-toolbar,collections,,—,"row of faceted filter chips + clear-all + result count"
 vertical-timeline,collections,,—,"ordered event list with time rail and node markers"
-sidebar,navigation,"Sidebar family + Brand/Switcher/ItemGroup/UserMenu/Callout (sidebar)",Sidebar,"fixed <nav>: brand + icon sections + badges + user footer, collapsible to icons"
-file-tree,navigation,FileTree (sidebar),—,"nested tree with disclosure carets, keyboard nav"
-breadcrumb,navigation,Breadcrumb (breadcrumb),Breadcrumb,"<nav aria-label=breadcrumb>, current page unlinked"
-tabs,navigation,Tabs (tabs),Tabs,"role=tablist, arrow-key switching, one panel per tab"
-pagination,navigation,Pagination (pagination),Pagination,"page buttons + prev/next, aria-current on active page"
-navbar,navigation,Navbar (navbar),—,"horizontal top <nav> with links and actions"
-navigation-menu,navigation,NavigationMenu (navigation-menu),Navigation Menu,"top-level nav with flyout panels"
-menubar,navigation,Menubar (menubar),Menubar,"desktop-app menu strip with full keyboard model"
-slide-out-menu,navigation,SlideOutMenu (slide-out-menu),—,"off-canvas nav panel for narrow viewports"
-icon-rail,navigation,VerticalIconBar (vertical-icon-bar),—,"narrow vertical icon strip with tooltips"
+sidebar,navigation,"Sidebar family + Brand/Switcher/ItemGroup/UserMenu/Callout (block/sidebar)",Sidebar,"fixed <nav>: brand + icon sections + badges + user footer, collapsible to icons"
+file-tree,navigation,FileTree (block/sidebar),—,"nested tree with disclosure carets, keyboard nav"
+breadcrumb,navigation,Breadcrumb (compound/breadcrumb),Breadcrumb,"<nav aria-label=breadcrumb>, current page unlinked"
+tabs,navigation,Tabs (compound/tabs),Tabs,"role=tablist, arrow-key switching, one panel per tab"
+pagination,navigation,Pagination (compound/pagination),Pagination,"page buttons + prev/next, aria-current on active page"
+navbar,navigation,Navbar (block/app-header),—,"horizontal top <nav> with links and actions"
+navigation-menu,navigation,NavigationMenu (compound/navigation-menu),Navigation Menu,"top-level nav with flyout panels"
+menubar,navigation,Menubar (compound/menubar),Menubar,"desktop-app menu strip with full keyboard model"
+slide-out-menu,navigation,SlideOutMenu (block/slide-out-menu),—,"off-canvas nav panel for narrow viewports"
+icon-rail,navigation,VerticalIconBar (block/vertical-icon-bar),—,"narrow vertical icon strip with tooltips"
 stepper,navigation,,—,"ordered steps with done/current/todo states, aria-current=step"
-alert,feedback,Alert (alert),Alert,"role=alert block, tone via border + icon"
-empty-state,feedback,EmptyState (empty-state),Empty,"icon + heading + motivation line + primary action"
-error-boundary,feedback,ErrorBoundary (error-boundary),—,"React boundary rendering a retry block"
-not-found,feedback,NotFound (not-found),—,"404 block with a way back"
-skeleton,feedback,Skeleton (skeleton),Skeleton,"pulsing placeholder matching the final layout"
-loader,feedback,Loader (loader),Spinner,"centered spinner with optional label"
-text-spinner,feedback,"Braille (braille) · spinner frames (inline-spinner)",—,"animated unicode frames inline with text"
-progress,feedback,Progress (progress),Progress,"role=progressbar with aria-valuenow"
-toast,feedback,Toaster (sonner),Sonner,"stacked corner notifications, auto-dismiss, action slot"
-typing-indicator,feedback,TypingIndicator (typing-indicator),—,"three-dot pulse row"
-sparkline,charts,"Spark — line|bar|pie (spark) · Sparkline (sparkline)",—,"inline no-axis SVG mark, token or self-contained color"
-inline-bar,charts,BarGraph (bar-graph),—,"compact bar SVG with skeleton, token colors"
+alert,feedback,Alert (element/alert),Alert,"role=alert block, tone via border + icon"
+empty-state,feedback,EmptyState (compound/empty-state),Empty,"icon + heading + motivation line + primary action"
+error-boundary,feedback,ErrorBoundary (lib/error-boundary),—,"React boundary rendering a retry block"
+not-found,feedback,NotFound (compound/empty-state),—,"404 block with a way back"
+skeleton,feedback,Skeleton (element/skeleton),Skeleton,"pulsing placeholder matching the final layout"
+loader,feedback,Loader (element/loader),Spinner,"centered spinner with optional label"
+text-spinner,feedback,"Braille (braille) · spinner frames (element/loader)",—,"animated unicode frames inline with text"
+progress,feedback,Progress (element/progress),Progress,"role=progressbar with aria-valuenow"
+toast,feedback,Toaster (compound/sonner),Sonner,"stacked corner notifications, auto-dismiss, action slot"
+typing-indicator,feedback,TypingIndicator (element/typing-indicator),—,"three-dot pulse row"
+sparkline,charts,"Spark — line|bar|pie (element/spark) · Sparkline (sparkline)",—,"inline no-axis SVG mark, token or self-contained color"
+inline-bar,charts,BarGraph (element/bar-graph),—,"compact bar SVG with skeleton, token colors"
 inline-line,charts,LineGraph (line-graph),—,"compact line SVG with skeleton"
 pie-donut,charts,"PieGraph — pie|half-pie|doughnut|half-doughnut (pie-graph)",—,"SVG arcs, max ~6 slices, center slot in doughnut"
 segmented-progress,charts,ProgressBar (progress-bar),—,"stacked horizontal segments with legend"
@@ -100,44 +100,44 @@ matrix-heatmap,charts,MatrixHeatmap + legend/tooltip (heatmap),—,"x-by-y cell
 radar,charts,Radar (radar),—,"spider axes with series polygons"
 ring,charts,Ring (ring),—,"segmented circular progress with center info"
 chart-chrome,charts,"ChartEmpty · ChartHoverCard · ChartLegend (chart-primitives)",—,"shared empty/tooltip/legend chrome for inline charts"
-card,layout,Card family (card),Card,"bordered section: header, content, footer"
+card,layout,Card family (block/card),Card,"bordered section: header, content, footer"
 stat-card,layout,Statistics family (statistics),—,"number + comparison + trend + state + door, composable regions"
-accordion,layout,Accordion (accordion),Accordion,"stacked disclosure sections, single or multiple open"
-collapsible,layout,"Collapsible (collapsible) · CollapsiblePanel (collapsible-panel)",Collapsible,"button-controlled region with hidden state"
-split-panes,layout,ResizablePanelGroup (resizable),Resizable,"draggable divider panes, keyboard resize"
-scroll-area,layout,ScrollArea (scroll-area),Scroll Area,"styled overflow container, visible-on-hover scrollbar"
-separator,layout,"Separator (separator) · SeparatorWithText (separator-with-text)",Separator,"<hr>/role=separator, optional centered label"
-aspect-ratio,layout,AspectRatio (aspect-ratio),Aspect Ratio,"CSS aspect-ratio box"
-carousel,layout,Carousel (carousel),Carousel,"scroll-snap track with prev/next controls"
+accordion,layout,Accordion (compound/accordion),Accordion,"stacked disclosure sections, single or multiple open"
+collapsible,layout,"Collapsible (element/collapsible) · CollapsiblePanel (compound/accordion)",Collapsible,"button-controlled region with hidden state"
+split-panes,layout,ResizablePanelGroup (block/resizable),Resizable,"draggable divider panes, keyboard resize"
+scroll-area,layout,ScrollArea (element/scroll-area),Scroll Area,"styled overflow container, visible-on-hover scrollbar"
+separator,layout,"Separator (element/separator) · SeparatorWithText (element/separator)",Separator,"<hr>/role=separator, optional centered label"
+aspect-ratio,layout,AspectRatio (element/aspect-ratio),Aspect Ratio,"CSS aspect-ratio box"
+carousel,layout,Carousel (compound/carousel),Carousel,"scroll-snap track with prev/next controls"
 bento-grid,layout,BentoGrid + BentoCard (bento-grid),—,"asymmetric feature grid with spanning cells"
-editable-card,layout,EditableCard (editable-card),—,"card with edit-in-place body and commit footer"
-drag-reorder,layout,Sortable family (sortable),—,"dnd-kit list reorder, keyboard sortable, drag overlay ghost"
-text,typography,Text (text),Typography,"semantic p/span with size and weight scale"
-badge,typography,Badge (badge),Badge,"small status pill, tokenized tone"
-chip,typography,"Chip (chip) · Option display (select)",—,"removable tag, optional color dot"
-code,typography,Code (code),—,"inline <code>, mono"
-kbd,typography,Kbd (kbd),Kbd,"<kbd> keycap"
-label,typography,Label (label),Label,"<label for> bound to a control"
-link,typography,Link (link),—,"<a> with underline discipline"
+editable-card,layout,EditableCard (compound/editable-card),—,"card with edit-in-place body and commit footer"
+drag-reorder,layout,Sortable family (compound/sortable),—,"dnd-kit list reorder, keyboard sortable, drag overlay ghost"
+text,typography,Text (element/text),Typography,"semantic p/span with size and weight scale"
+badge,typography,Badge (element/badge),Badge,"small status pill, tokenized tone"
+chip,typography,"Chip (element/chip) · Option display (element/select)",—,"removable tag, optional color dot"
+code,typography,Code (element/code),—,"inline <code>, mono"
+kbd,typography,Kbd (element/kbd),Kbd,"<kbd> keycap"
+label,typography,Label (element/label),Label,"<label for> bound to a control"
+link,typography,Link (element/link),—,"<a> with underline discipline"
 secure-text,typography,SecureText (secure-text),—,"masked value with reveal toggle, mono"
-markdown,typography,Markdown (markdown),—,"react-markdown rendering with typographic defaults"
-avatar,media,Avatar (avatar),Avatar,"image with initials fallback, round"
-copy-button,media,CopyButton (copy-button),—,"clipboard write with copied-state swap"
-icon,media,"IconRenderer (icon-renderer) + icons-data (icons-data)",—,"lucide icon by name, consistent stroke and size grid"
-voice-waveform,media,"LiveWaveform (live-waveform) · MicIcon (mic-icon)",—,"animated level bars from mic input"
-brand-logo,media,"Logo — blue-black|white-white|lime-white|blue-white (logo)",—,"inline SVG logo sized by height"
-shine-border,media,ShineBorder (shine-border),—,"animated gradient border wrapper, decorative"
-theme-toggle,media,ThemeToggler (theme-toggler),—,"light/dark switch writing data-theme"
-view-switcher,media,ViewSwitcher (view-switcher),—,"segmented control switching view-type projections"
-animated-number,motion,"AnimatedNumber (animated-number) · SlidingNumber (motion-primitives/sliding-number)",—,"tick-up numerals, renders plain text until JS ready"
-stagger-entrance,motion,AnimatedGroup (motion-primitives/animated-group),—,"staggered child arrival, identity moments only, never on 100×/day actions"
-text-effects,motion,"TextEffect · TextMorph · TextScramble · TextShimmer (motion-primitives/*)",—,"per-character text animation, low-frequency surfaces only"
-morphing-overlay,motion,"MorphingDialog · MorphingPopover (motion-primitives/*)",—,"trigger morphs into overlay, interruptible"
-panel-transitions,motion,"TransitionPanel · Disclosure · motion Accordion (motion-primitives/*) · animated Tabs (animate-ui)",—,"crossfade/slide between sibling panels, height-animated reveal, interruptible"
-decorative-effects,motion,"Spotlight · GlowEffect · AnimatedBackground · InfiniteSlider · Highlight (motion-primitives/*, animate-ui/*)",—,"pointer-tracked washes and loops, decorative only, never on data"
-dynamic-toolbar,motion,ToolbarDynamic (motion-primitives/toolbar-dynamic),—,"toolbar expanding to contextual actions"
-utility-hooks,hooks,"useClickOutside · useFileUpload · useMediaQuery · useIsMobile (hooks/*)",—,"outside-click, file-upload state, matchMedia boolean, <768px boolean"
-class-merge,utils,cn (utils),cn,"clsx + tailwind-merge"
-formatting-utils,utils,"formatDate (format) · generateId (id) · getErrorMessage (handle-error)",—,"Intl date formatting, nanoid ids, error-to-message normalization"
-composition-utils,utils,"getStrictContext (get-strict-context) · composeRefs (compose-refs)",—,"throwing Provider/hook pair, ref composition"
+markdown,typography,Markdown (element/markdown),—,"react-markdown rendering with typographic defaults"
+avatar,media,Avatar (element/avatar),Avatar,"image with initials fallback, round"
+copy-button,media,CopyButton (compound/copy-button),—,"clipboard write with copied-state swap"
+icon,media,"IconRenderer (element/icon-renderer) + icons-data (lib/icons-data)",—,"lucide icon by name, consistent stroke and size grid"
+voice-waveform,media,"LiveWaveform (element/live-waveform) · MicIcon (element/mic-icon)",—,"animated level bars from mic input"
+brand-logo,media,"Logo — blue-black|white-white|lime-white|blue-white (element/logo)",—,"inline SVG logo sized by height"
+shine-border,media,ShineBorder (effect/shine-border),—,"animated gradient border wrapper, decorative"
+theme-toggle,media,ThemeToggler (element/theme-toggler),—,"light/dark switch writing data-theme"
+view-switcher,media,ViewSwitcher (compound/tabs),—,"segmented control switching view-type projections"
+animated-number,motion,"AnimatedNumber (element/animated-number) · SlidingNumber (element/animated-number)",—,"tick-up numerals, renders plain text until JS ready"
+stagger-entrance,motion,AnimatedGroup (effect/animated-group),—,"staggered child arrival, identity moments only, never on 100×/day actions"
+text-effects,motion,"TextEffect · TextMorph · TextScramble · TextShimmer (effect/*)",—,"per-character text animation, low-frequency surfaces only"
+morphing-overlay,motion,"MorphingDialog · MorphingPopover (effect/*)",—,"trigger morphs into overlay, interruptible"
+panel-transitions,motion,"TransitionPanel · Disclosure · motion Accordion (effect/*) · animated Tabs (animate-ui)",—,"crossfade/slide between sibling panels, height-animated reveal, interruptible"
+decorative-effects,motion,"Spotlight · GlowEffect · AnimatedBackground · InfiniteSlider · Highlight (effect/*, effect/*)",—,"pointer-tracked washes and loops, decorative only, never on data"
+dynamic-toolbar,motion,ToolbarDynamic (effect/toolbar-dynamic),—,"toolbar expanding to contextual actions"
+utility-hooks,hooks,"useClickOutside · useFileUpload · useMediaQuery · useIsMobile (lib/*)",—,"outside-click, file-upload state, matchMedia boolean, <768px boolean"
+class-merge,utils,cn (lib/utils),cn,"clsx + tailwind-merge"
+formatting-utils,utils,"formatDate (lib/format) · generateId (lib/id) · getErrorMessage (lib/handle-error)",—,"Intl date formatting, nanoid ids, error-to-message normalization"
+composition-utils,utils,"getStrictContext (lib/get-strict-context) · composeRefs (lib/compose-refs)",—,"throwing Provider/hook pair, ref composition"
 ```

package/data/harnesses/code/skills/design/components/layout.md

@@ -2,7 +2,7 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Content structure and containers. Import each from its own subpath, e.g. `import { Card, CardContent } from "@nurix/components/card";`.
+Content structure and containers. Import each from its own subpath, e.g. `import { Card, CardContent } from "@nurix/components/block/card";`.
 
 ## Statistics
 

package/data/harnesses/code/skills/design/components/media.md

@@ -2,7 +2,7 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Icons, avatars, and media display; import each from its kebab-case subpath, e.g. `import { Avatar } from "@nurix/components/avatar"`.
+Icons, avatars, and media display; import each from its kebab-case subpath, e.g. `import { Avatar } from "@nurix/components/element/avatar"`.
 
 ## Avatar
 

package/data/harnesses/code/skills/design/components/motion.md

@@ -2,7 +2,7 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Animation primitives built on the `motion` library (`motion-primitives/*`) plus a small `animate-ui/*` layer. Compose sparingly — decorative and low-frequency surfaces only; never on data or on actions users repeat dozens of times a day. Import each from its own subpath, e.g. `import { AnimatedGroup } from "@nurix/components/motion-primitives/animated-group"`.
+Animation primitives built on the `motion` library (`motion-primitives/*`) plus a small `animate-ui/*` layer. Compose sparingly — decorative and low-frequency surfaces only; never on data or on actions users repeat dozens of times a day. Import each from its own subpath, e.g. `import { AnimatedGroup } from "@nurix/components/effect/animated-group"`.
 
 ## Animated numbers
 

package/data/harnesses/code/skills/design/components/navigation.md

@@ -4,11 +4,11 @@
 
 Components: Breadcrumb, Menubar, Navbar, NavigationMenu, Pagination, Sidebar, SlideOutMenu, Tabs, VerticalIconBar
 
-Each imports from its own subpath, with compound members alongside, e.g. `import { Tabs, TabsList, TabsTrigger, TabsContent } from "@nurix/components/tabs"`.
+Each imports from its own subpath, with compound members alongside, e.g. `import { Tabs, TabsList, TabsTrigger, TabsContent } from "@nurix/components/compound/tabs"`.
 
 ## Sidebar
 
-App sidebar: full shadcn primitives plus an opinionated layer, all from the single `@nurix/components/sidebar` subpath.
+App sidebar: full shadcn primitives plus an opinionated layer, all from the single `@nurix/components/block/sidebar` subpath.
 
 **Sub-components:** `SidebarProvider`, `Sidebar` (`side` [left|right], `variant` [sidebar|floating|inset], `collapsible` [offcanvas|icon|none]), `SidebarTrigger`, `SidebarHeader`, `SidebarContent`, `SidebarFooter`, `SidebarGroup`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarRail`, `SidebarInset`, `useSidebar`. **Opinionated layer:** `Brand`, `Switcher` (`render` [simple|rich], `options`, `activeId`, `onSelect`), `ItemGroup` (`render` [list|tree|rich], `collapsible`, `compact`, `collapsedLabel` [hide|divider], `items`, `onItemClick`), `UserMenu`, `Callout`, `FileTree`, `SidebarCommandTrigger`.
 

package/data/harnesses/code/skills/design/components/overlays.md

@@ -62,7 +62,7 @@ Side panel overlay with header/body/footer layout.
 
 ## Other Overlays
 
-Standard compound components following the Trigger/Content pattern; import each from its kebab-case subpath (e.g. `@nurix/components/popover`):
+Standard compound components following the Trigger/Content pattern; import each from its kebab-case subpath (e.g. `@nurix/components/element/popover`):
 
 - `Command` (`command`)
 - `ContextMenu` (`context-menu`)

package/data/harnesses/code/skills/design/components/setup.md

@@ -34,7 +34,7 @@ The design skill's token artifact (CSS custom properties emitted from the projec
 Use subpath imports — each published entry maps to one; never import from the root barrel in generated code:
 
 ```tsx
-import { Button } from "@nurix/components/button";
-import { Cell } from "@nurix/components/cell";
-import { defineColumn } from "@nurix/components/table";
+import { Button } from "@nurix/components/element/button";
+import { Cell } from "@nurix/components/compound/cell";
+import { defineColumn } from "@nurix/components/block/table";
 ```

package/data/harnesses/code/skills/design/components/typography.md

@@ -2,7 +2,7 @@
 
 > Generated reference (regen-owned; see [index.md](index.md)). Binds only under `primitives: nurix`.
 
-Import each from its kebab-case subpath, e.g. `import { Badge } from "@nurix/components/badge"`.
+Import each from its kebab-case subpath, e.g. `import { Badge } from "@nurix/components/element/badge"`.
 
 ## Text
 
@@ -43,4 +43,4 @@ Masked display for sensitive values (passwords, API keys, card numbers) with an
 - `kbd` — `Kbd`: keycap; `variant` [default|outline], `size` [sm|default|lg]
 - `label` — `Label`: Radix `Label.Root`, tracks a peer/group's `disabled` state automatically
 - `link` — `Link`: `variant` [default|muted|plain|underline], `size` [sm|default|lg], `asChild`, `external` (forces `target="_blank"` + a trailing icon; also auto-detects `target="_blank"`)
-- `markdown` — `Markdown`: GFM `react-markdown` + `remark-gfm` render with a full element map (headings, lists, code, blockquote, tables) styled on the library's own tokens — no `@tailwindcss/typography` plugin needed; safe to re-render incrementally while streaming. **Props:** `children` (markdown string), `className`
+- `markdown` — `Markdown`: GFM `react-markdown` + `remark-gfm` render with a full element map (headings, lists, element/code, blockquote, tables) styled on the library's own tokens — no `@tailwindcss/typography` plugin needed; safe to re-render incrementally while streaming. **Props:** `children` (markdown string), `className`

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

@@ -122,11 +122,18 @@ The two guarantees are complementary and both break on mixing: a reader holding
 
 **Frontmatter is compulsory on every document this skill authors** — `type:` (the genre) on every
 doc, plus the genre's own keys beside it; a document without its frontmatter fails the skill's
-contract and is not done. A feature doc carries the full ownership set — `owns:` (required),
-`module:` (optional), `keywords:` (required), `status:` (required), optional `last-reviewed:`. An
-acceptance-criteria doc (`docs/acceptance/`) carries `type:` and `status:`. The single sanctioned
-exception is a genre the placement map explicitly marks frontmatter-less (the behavioral checklists
-in `docs/tests/`). Deriving ownership frontmatter from code and keeping it accurate is [`references/frontmatter.md`](references/frontmatter.md) — every feature-doc create or update, and the `maintenance` agent's baseline pass, route there.
+contract and is not done. **There is no frontmatter-less genre.** A feature or UX doc carries the
+full set — `owns:` (required), `module:` (optional), `keywords:` (required), `status:` (required),
+`applies:` (the architecture docs it obeys; omitted when none), optional `last-reviewed:`. A
+behavioral checklist (`docs/tests/`) carries `type: checklist` and `verifies:` — the doc whose
+promises it proves. An acceptance-criteria doc (`docs/acceptance/`) carries `type:` and `status:`.
+
+**The frontmatter is where the docs tree's edges live**, and a doc that declares none is a node
+nothing can reach: no change implicates it, so it rots without the rot being detectable. Deriving
+every edge — `owns:` from code, `verifies:` and `applies:` from the docs they answer to — is
+[`references/frontmatter.md`](references/frontmatter.md), and it carries the rule the whole graph
+rests on: **declare once at the consuming end, generate every inverse.** Every doc create or
+update, and the `maintenance` agent's baseline pass, route there.
 
 ---
 

package/data/harnesses/code/skills/documentation/references/frontmatter.md

@@ -1,8 +1,16 @@
-# Frontmatter Derivation — feature-doc ownership
+# Frontmatter Derivation — the doc graph
 
-Load when: creating a feature doc, updating one whose documented scope moved, or running a baseline/reconcile pass over many docs.
+Load when: creating a doc that declares an edge (a feature doc, a UX doc, a behavioral checklist), updating one whose scope moved, or running a baseline/reconcile pass over many docs.
 
-When creating or updating a feature doc, derive its **`owns:` frontmatter** — the code-path globs it is canonical for — from the source the doc describes. Code ownership lives in each feature doc's `owns:` frontmatter (the SessionStart hook unions them into the injected ownership index); there is no hand-maintained ownership map.
+**A docs tree is a graph, and every edge in it is declared in frontmatter.** Two kinds of edge exist: **doc → code** (`owns:`), and **doc → doc** (`verifies:`, `applies:`). The SessionStart hook reads them all and injects the generated indexes; there is no hand-maintained map of either kind.
+
+## The one rule that keeps the graph honest
+
+**An edge is declared once, at the consuming end. Every inverse is generated, never authored.**
+
+A parent that hand-lists its children is a second thing to forget, and the moment the two directions can disagree nothing says which is right — you have doubled the staleness surface rather than halving it. So a checklist names the feature it verifies; the feature never lists its checklists. A feature names the architecture doc it obeys; the architecture doc never lists its consumers. Both inverses are derived on demand and injected, exactly as the ownership index already is.
+
+The consuming end is also the end that **knows**. A checklist author knows what they are verifying; an architecture doc has no idea who will obey it next year.
 
 ## When to run
 
@@ -34,7 +42,21 @@ The single bounded-context label this feature belongs to, or omit it for a cross
 
 `keywords:` are the discovery terms topic→doc lookup rides. `status:` is `active`, `draft`, or `deprecated` — it steers the model toward live docs and away from draft/deprecated ones.
 
-A doc's dependencies on other docs are expressed inline in its prose (links); cross-cutting contracts are diagnosed by the `boundary` skill from source, not persisted.
+## The doc → doc edges
+
+A prose link is not an edge. It states that one doc mentions another; it never states **why**, so nothing can be derived from it — not who consumes a doctrine, not what to re-read before an edit, not what falls stale when a surface moves. A tree can carry hundreds of prose links and still have no graph. These two keys carry the relationships that matter; everything else stays prose.
+
+**`verifies:`** — on a behavioral checklist (`docs/tests/{feature}.md`), the feature or UX doc(s) whose promises it proves. One value is the norm; several when a checklist spans a capability that two docs decide. A checklist carrying no `verifies:` is an orphan by construction: nothing implicates it when its subject changes, so it rots silently and the rot is undetectable.
+
+**`applies:`** — on a feature or UX doc, the architecture docs it obeys. Not "docs I read" and not "docs I mention" — **obligation**: a doctrine this surface is bound by, such that a change to the doctrine implicates this doc. The narrow reading is the load-bearing one; a key that collects everything consulted degrades into a bibliography and stops meaning anything. A feature bound by nothing cross-cutting omits the key.
+
+Cross-cutting *contracts* remain diagnosed by the `boundary` skill from source, never persisted — `applies:` records which doctrine a surface answers to, not which code it touches.
+
+## What is not frontmatter, deliberately
+
+**`Pinned:` stays a section-level line inside a checklist**, naming the suite tests that guard that section. It is already typed and already resolved mechanically by the `maintenance` agent. Hoisting it into frontmatter would flatten per-section detail into a doc-level list and duplicate what the sections already say — the exact double-declaration the one rule above forbids.
+
+That edge has a property the others lack, and it is worth naming: **a `Pinned:` reference terminates.** A test file exists or it does not, so the edge is falsifiable by a resolver sweep with no judgement. An `owns:` glob is only falsifiable at the dangling end — a glob that resolves says nothing about whether the doc still describes what the code does. Terminal edges get resolver sweeps; non-terminal edges need a human or an agent to read both ends. Do not build a checker that pretends otherwise.
 
 ## Rules
 
@@ -42,3 +64,6 @@ A doc's dependencies on other docs are expressed inline in its prose (links); cr
 - Use glob patterns for directories, explicit paths for individual files. At `active`, never list paths that don't exist in the codebase; a `draft`'s projected paths are confirmed at `active`.
 - When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec owns its own globs — don't duplicate a path across siblings.
 - For baseline/reconcile with many docs, use parallel sub-agents to read source and propose `owns:` globs.
+- **Never author an inverse.** No doc lists its verifiers, its consumers, or its dependents — those are generated. A hand-written "consumed by" table is a defect to delete, not a convention to follow.
+- **Every edge value is a repo-relative doc path** (`docs/architecture/common/security.md`), never a bare filename and never a display title — the resolver is a path lookup, and a title changes without the file moving.
+- **A dangling edge is a block, not a warning.** `verifies:` or `applies:` naming a doc that does not exist is a typo or a deletion; either way the graph is lying. Resolve at authoring time.

package/data/harnesses/code/skills/documentation/templates/behavioral-checklist.md

@@ -1,6 +1,23 @@
 # Behavioral Checklist (docs/tests/{feature}.md)
 
-Truth document. Use for: **how to verify one feature's promised behavior by driving the real product** — the browser, the CLI binary, HTTP against the running service. One file per feature, named for the feature doc that owns the code (`docs/features/auth.md` → `docs/tests/auth.md`). No frontmatter; a checklist owns no code.
+Truth document. Use for: **how to verify one feature's promised behavior by driving the real product** — the browser, the CLI binary, HTTP against the running service. One file per feature, named for the feature doc that owns the code (`docs/features/auth.md` → `docs/tests/auth.md`).
+
+**Frontmatter is two keys, and `verifies:` is the load-bearing one:**
+
+```yaml
+---
+type: checklist                            # required tooling key — genre stamp
+verifies: [docs/features/auth.md]          # required — the doc(s) whose promises this proves
+---
+```
+
+A checklist owns no code, so it carries no `owns:`. What it carries instead is the edge back to
+its subject. **The filename convention is not the edge** — a same-named file is a coincidence a
+resolver cannot trust, it breaks the moment a checklist spans two docs or a feature is renamed, and
+it leaves nothing to implicate this file when its subject changes. Without `verifies:` a checklist
+is unreachable: no change reaches it, so it goes stale and the staleness is undetectable. Several
+values are correct where one checklist proves promises two docs decide; the inverse — which
+checklists cover a feature — is generated, never listed in the feature doc.
 
 **This is the driving script, and it is the source the suite is drawn from.** At the verification gate it does double duty: rung 1 drives the real surface *against these steps*, and rung 2 pins the durable subset *of these assertions* as suite tests. Writing it is therefore not a report written afterwards — it is authored or updated **before** the driving, so the gate has something to execute and the tests have something to be derived from. Which assertions earn a permanent test is decided by the `testing` skill (gate mode) § What earns a suite test, and each section records the answer on its `Pinned:` line.
 

package/data/harnesses/code/skills/documentation/templates/feature.md

@@ -12,6 +12,7 @@ owns: ["src/feature/**", "src/other/file.ts"]   # required — code-path globs t
 module: billing                                  # optional — single bounded-context label; omit if cross-cutting
 keywords: [invoice, pdf]                         # required — discovery terms
 status: active                                   # required — active | draft | deprecated
+applies: [docs/architecture/common/security.md]  # optional — architecture docs this surface is BOUND by (obligation, not a bibliography); omit when none
 last-reviewed: YYYY-MM-DD                        # optional tooling key — stamped on substantive review/update; the maintenance agent ranks audit priority by it (metadata, never narrated in the body)
 type: feature                                    # required tooling key — genre stamp (generator-written or authored; enum = the template names), read by tooling (UI grouping, protected-file mapping); preserve on edits, never narrate
 ---

package/data/harnesses/code/skills/documentation/templates/plan.md

@@ -4,6 +4,8 @@ Record. Use for: every implementation plan. Plans are created here directly with
 
 The `boundary` skill parses the **Proposed Changes** sections to check boundary impact before execution, and the `testing` skill (plan-gate mode) writes a **Test Obligations** section into the plan at the same gate. Keep that structure stable — section headings and bullet shape are load-bearing for the parsers, and the Test Obligations table is the ledger the verification gate discharges before the plan may reach `Status: Complete`.
 
+**Both ledgers are read by a wall, so their cells obey a table's grammar.** A literal pipe inside a cell is written `\|` — the parser splits on unescaped pipes and unescapes what survives, so an escaped one is safe, and an unescaped one silently adds a column and shifts every later cell left. Prefer rephrasing (`` `install` or `update` ``) over escaping where the sentence allows it: the cell then reads the same to a person and to the wall.
+
 **Doc Obligations is the one ledger the plan's author writes.** Deriving tests from behavior is judgment, which is why `testing` owns that section and it is marked never-hand-author; resolving Proposed Changes' file paths to the feature docs that own them is a **lookup** against the ownership index already injected at session start. Different work, different rule — fill it yourself, while the touch list is fresh.
 
 The **`Gates:`** line carries one machine-read segment. The compliance hook greps **`Boundary:`** — implementation edits inside the plan's scope are blocked while it reads `Boundary: pending`; the `boundary` skill rewrites it to `Boundary: passed YYYY-MM-DD` or `Boundary: blocked YYYY-MM-DD`. The other two gates are enforced by **section presence**: a plan with no `## Test Obligations` or no `## Doc Obligations` section blocks the same edits — the sections are the artifacts, and the gate derives from them, not from a claim about them. Never hand-edit the line to skip a gate.

package/data/harnesses/code/skills/documentation/templates/ux-behavior.md

@@ -2,7 +2,7 @@
 
 **Truth document.** States what a person sees and can do on a surface, and what the surface promises never to do. Present tense, like every truth document.
 
-**`type: ux`.**
+**`type: ux`**, plus `applies:` — the architecture docs this surface is bound by (the state vocabulary, the routing doctrine, the information architecture it answers to). Same key and same narrow reading as a feature doc's: obligation, not a reading list.
 
 **Why this genre exists.** A feature doc (LLD) states what a feature is, how its data flows, and which contracts it honours — all of which stay plausibly true through a rewrite of the surface. Nothing else in the repo states what a person *observes*. So a change to the wire lands, the interface absorbs it, and the absorption reads as maintenance: no test fails, no lint fires, no document is contradicted. This document is the thing a silent change contradicts.