@nurix/etna 0.1.2 → 0.2.0

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

@@ -0,0 +1,96 @@
+---
+applyTo: "**"
+---
+
+# Technology Choices & Standards
+
+Opinionated technology stack and implementation standards.
+
+## Environment & Versions
+
+### Runtime Versions
+
+- **Node.js:** 22 LTS (latest)
+- **Package manager:** project-determined — detect from lockfile (`pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `package-lock.json` → npm). Use the matching command in scripts; don't hardcode a specific manager.
+- **PostgreSQL:** 17
+- **Redis:** 7.x (latest)
+
+### Recommended Packages
+
+No alternatives. No explanations for obvious choices. Just use these.
+
+| Package                  | Version   | Use                    | Don't use               |
+| ------------------------ | --------- | ---------------------- | ----------------------- |
+| react                    | ^19.2.3   | UI components          | -                       |
+| vite                     | ^8.0.0    | Build tool, dev server | webpack, CRA            |
+| tailwindcss              | ^4.1.18   | Styling                | styled-components       |
+| @vitejs/plugin-react-swc | ^4.2.2    | JSX compilation        | @vitejs/plugin-react    |
+| react-router-dom         | ^7.11.0   | Routing                | -                       |
+| @reduxjs/toolkit         | ^2.11.2   | State management       | zustand, jotai          |
+| react-redux              | ^9.2.0    | Redux React bindings   | -                       |
+| axios                    | ^1.13.2   | HTTP requests          | fetch                   |
+| date-fns                 | ^4.1.0    | Date formatting        | moment, dayjs           |
+| @dnd-kit/core            | ^6.3.1    | Drag and drop          | react-beautiful-dnd     |
+| motion                   | ^12.23.26 | Animations             | react-spring            |
+| sonner                   | ^2.0.7    | Toast notifications    | react-toastify          |
+| react-window             | ^2.2.3    | List virtualization    | react-virtualized       |
+| nanoid                   | ^5.1.6    | ID generation          | uuid                    |
+| express                  | ^5.2.1    | HTTP server            | fastify, koa            |
+| prisma                   | ^7.2.0    | Database ORM           | sequelize, typeorm      |
+| @prisma/client           | ^7.2.0    | Database queries       | -                       |
+| zod                      | ^4.2.1    | Schema validation      | yup, joi                |
+| jose                     | ^6.1.3    | JWT handling           | jsonwebtoken            |
+| microdiff                | ^1.5.0    | JSON object diffing    | deep-diff, just-diff    |
+| react18-json-view        | ^0.2.9    | JSON tree view         | react-json-view         |
+| @tiptap/react            | ^3.11.1   | Rich text editor       | slate, quill, draft-js  |
+| shiki                    | ^3.22.0   | Syntax highlighting    | prism, highlight.js     |
+| lucide-react             | ^0.562.0  | Icons                  | react-icons, heroicons  |
+| @pdfme/generator         | ^5.5.8    | PDF generation         | jspdf, pdfkit           |
+| cmdk                     | ^1.1.1    | Command palette        | kbar, ninja-keys        |
+| @monaco-editor/react     | ^4.7.0    | Code editor            | codemirror, ace         |
+| localforage              | ^1.10.0   | Client-side storage    | idb, dexie              |
+| socket.io-client         | ^4.7.0    | WebSocket client       | native WebSocket, ws    |
+| react-markdown           | ^10.1.0   | Markdown rendering     | marked, markdown-it     |
+| 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                 |
+
+---
+
+## Express 5.x Setup
+
+```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
+- Use Express Router for modular routes
+- Centralized error handler as last middleware
+- Use middleware for auth
+
+---
+
+## API Response Format
+
+```json
+{
+    "status": 1,
+    "message": "Message sent successfully",
+    "data": { "delivered": [{ "user@example.com": 2 }] }
+}
+```
+
+**Error:**
+
+```json
+{
+    "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

@@ -0,0 +1,34 @@
+---
+applyTo: "**"
+---
+
+# Nomenclature Guidelines
+
+## Naming Guidelines
+
+- Use descriptive names that reveal intent, purpose, and usage
+- Names should explain why something exists and how it's used
+- Favor clarity over brevity
+- Maintain consistency within the codebase
+- Avoid abbreviations unless they're universally understood
+
+## Naming Styles
+
+- Variables : Use nouns or noun phrases. Examples: `userData`, `firstName`, `paymentStatus`, `configOptions`
+- Functions & Methods : Use verbs or verb phrases that describe the action. Examples: `calculateTotal`, `getUserInfo`, `validateInput`, `sendNotification`
+- Boolean Variables : Prefix with is**, has**, can**, or should**. Examples: `isValid`, `hasPermission`, `canEdit`, `shouldRefresh`
+- Arrays : Use plural nouns. Examples: `users`, `productList`, `errorMessages`, `activeConnections`
+- Classes & Components : Use singular nouns or noun phrases. Examples: `RequestHandler`, `UserProfile`, `PaymentProcessor`, `DataValidator`
+- Constants : Use uppercase with meaningful names. Examples: `DEFAULT_TIMEOUT`, `API_BASE_URL`, `MAX_RETRY_COUNT`, `COLOR_PRIMARY`
+- Event Handlers : Use Prefix with handle or on. Examples: `handleSubmit`, `onUserLogin`, `handleInputChange`, `onPageLoad`
+- Interfaces & Types : Use Consider prefixing with I for interfaces (if preferred). Examples: `IUserData`, `IConfigOptions`, `AuthResponse`, `RequestParams`
+- Promises & Async Functions : Use Consider using future tense or suffixes like Async. Examples: `fetchUserData`, `getUserProfileAsync`, `loadConfigAsync`, `processPayment`
+- File & Folder Structure : Use lowercase with descriptive names. Group by feature or function type. Example: `auth/login_service.js`
+
+## Casing Styles
+
+- camelCase : Used in Variables, function names, method names, property names. Examples: `userData`, `calculateTotal`, `firstName`, `isValidEmail`
+- PascalCase : Used in Class names, component names, type definitions. Examples: `UserProfile`, `DataService`, `AuthProvider`, `RequestHandler`
+- snake_case : Used in File names, folder names. Examples: `user_service`, `api_utils`, `auth_middleware`, `data_models`
+- UPPER_SNAKE_CASE : Used in Constants, environment variables. Examples: `MAX_RETRY_COUNT`, `API_KEY`, `DEFAULT_TIMEOUT`, `COLOR_PRIMARY`
+- kebab-case : Used in URLs, CSS class names, HTML IDs. Examples: `nav-container`, `user-profile`, `button-primary`, `form-wrapper`

package/data/harnesses/code/scripts/build-ownership-index.sh

@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# scripts/build-ownership-index.sh - Generate docs/OWNERSHIP_INDEX.md from feature doc frontmatter
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+OUTPUT="$REPO_ROOT/docs/OWNERSHIP_INDEX.md"
+FEATURES_DIR="$REPO_ROOT/docs/features"
+TMP_OWNS=$(mktemp)
+TMP_DEPS=$(mktemp)
+TMP_DIRS=$(mktemp)
+trap 'rm -f "$TMP_OWNS" "$TMP_DEPS" "$TMP_DIRS"' EXIT
+
+# Extract YAML frontmatter list field values from a markdown file
+extract_field() {
+    local file="$1" field="$2"
+    awk -v field="$field" '
+        /^---$/ { fm++; next }
+        fm == 1 && $0 ~ "^"field":" {
+            in_field = 1
+            sub("^"field":[ ]*", "")
+            if ($0 != "" && $0 !~ /^\[/) { print $0; in_field = 0 }
+            next
+        }
+        fm == 1 && in_field && /^  +- / {
+            sub("^  +- ", "")
+            gsub(/^[ \t]+|[ \t]+$/, "")
+            print
+            next
+        }
+        fm == 1 && in_field && /^[a-z]/ { in_field = 0 }
+        fm == 1 && in_field && /^---$/ { in_field = 0 }
+        fm >= 2 { exit }
+    ' "$file"
+}
+
+# Collect ownership and dependency data from all feature docs
+find "$FEATURES_DIR" -name "*.md" ! -name "README.md" -print0 | sort -z | while IFS= read -r -d '' file; do
+    rel_path="${file#$REPO_ROOT/}"
+
+    extract_field "$file" "owns" | while IFS= read -r pattern; do
+        [ -z "$pattern" ] && continue
+        printf '%s\t%s\n' "$pattern" "$rel_path" >> "$TMP_OWNS"
+    done
+
+    deps=$(extract_field "$file" "depends_on" | tr '\n' ', ' | sed 's/,$//' | sed 's/, $//')
+    if [ -n "$deps" ]; then
+        printf '%s\t%s\n' "$rel_path" "$deps" >> "$TMP_DEPS"
+    fi
+done
+
+# Collect owned directory prefixes for unowned path detection
+sed 's|/\*\*$||; s|/\*$||; s|/[^/]*$||' "$TMP_OWNS" | awk -F'\t' '{ print $1 }' | sort -u > "$TMP_DIRS"
+
+# Find unowned src/ directories
+unowned=""
+if [ -d "$REPO_ROOT/src" ]; then
+    for dir in "$REPO_ROOT"/src/*/; do
+        [ -d "$dir" ] || continue
+        rel_dir="${dir#$REPO_ROOT/}"
+        rel_dir="${rel_dir%/}"
+        is_owned=0
+        while IFS= read -r owned; do
+            case "$rel_dir" in
+                "$owned"*) is_owned=1; break ;;
+            esac
+            case "$owned" in
+                "$rel_dir"*) is_owned=1; break ;;
+            esac
+        done < "$TMP_DIRS"
+        if [ "$is_owned" -eq 0 ]; then
+            unowned="${unowned}- \`${rel_dir}\`
+"
+        fi
+    done
+fi
+
+# Generate output
+cat > "$OUTPUT" << 'HEADER'
+# Ownership Index
+
+> **Generated file** — do not edit manually.
+> Regenerate with: `bash scripts/build-ownership-index.sh`
+
+Machine-readable lookup table generated from feature doc frontmatter.
+
+---
+
+## By Code Path
+
+| Code Path | Owning Doc |
+|---|---|
+HEADER
+
+sort "$TMP_OWNS" | while IFS=$'\t' read -r pattern doc; do
+    echo "| \`$pattern\` | \`$doc\` |" >> "$OUTPUT"
+done
+
+cat >> "$OUTPUT" << 'SECTION'
+
+---
+
+## Unowned Paths
+
+Top-level `src/` directories with no owning feature doc:
+
+SECTION
+
+if [ -z "$unowned" ]; then
+    echo "_All top-level src/ directories have owners._" >> "$OUTPUT"
+else
+    printf '%s' "$unowned" >> "$OUTPUT"
+fi
+
+cat >> "$OUTPUT" << 'SECTION'
+
+---
+
+## Dependency Graph
+
+Feature docs and their declared `depends_on` relationships:
+
+| Feature Doc | Depends On |
+|---|---|
+SECTION
+
+if [ -s "$TMP_DEPS" ]; then
+    sort "$TMP_DEPS" | while IFS=$'\t' read -r doc deps; do
+        echo "| \`$doc\` | $deps |" >> "$OUTPUT"
+    done
+fi
+
+echo "" >> "$OUTPUT"
+echo "---" >> "$OUTPUT"
+echo "" >> "$OUTPUT"
+echo "_Generated: $(date -u '+%Y-%m-%d %H:%M UTC')_" >> "$OUTPUT"
+
+echo "Generated $OUTPUT"

package/data/harnesses/code/scripts/check-doc-drift.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+# scripts/check-doc-drift.sh - Detect potentially stale docs based on recent code changes
+
+set -euo pipefail
+
+DAYS="${1:-14}"
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+FEATURES_DIR="$REPO_ROOT/docs/features"
+TMP_OWNS=$(mktemp)
+TMP_STALE=$(mktemp)
+TMP_UNOWNED=$(mktemp)
+trap 'rm -f "$TMP_OWNS" "$TMP_STALE" "$TMP_UNOWNED"' EXIT
+
+echo "Checking for doc drift over the last $DAYS days..."
+echo ""
+
+# Extract owns patterns from a markdown file
+extract_owns() {
+    local file="$1"
+    awk '
+        /^---$/ { fm++; next }
+        fm == 1 && /^owns:/ { in_owns = 1; next }
+        fm == 1 && in_owns && /^  +- / {
+            sub("^  +- ", "")
+            gsub(/^[ \t]+|[ \t]+$/, "")
+            print
+            next
+        }
+        fm == 1 && in_owns && /^[a-z]/ { exit }
+        fm >= 2 { exit }
+    ' "$file"
+}
+
+# Get recently changed files
+changed_files=$(cd "$REPO_ROOT" && git log --since="$DAYS days ago" --name-only --pretty=format:"" | sort -u | grep -v '^$' || true)
+
+if [ -z "$changed_files" ]; then
+    echo "No files changed in the last $DAYS days."
+    exit 0
+fi
+
+changed_count=$(echo "$changed_files" | wc -l | tr -d ' ')
+echo "Found $changed_count changed files in the last $DAYS days."
+echo ""
+
+# Build ownership map: pattern\tdoc
+find "$FEATURES_DIR" -name "*.md" ! -name "README.md" -print0 | sort -z | while IFS= read -r -d '' file; do
+    rel_path="${file#$REPO_ROOT/}"
+    extract_owns "$file" | while IFS= read -r pattern; do
+        [ -z "$pattern" ] && continue
+        printf '%s\t%s\n' "$pattern" "$rel_path" >> "$TMP_OWNS"
+    done
+done
+
+# Check each changed file against ownership
+echo "$changed_files" | while IFS= read -r changed_file; do
+    [ -z "$changed_file" ] && continue
+    # Skip non-source files
+    case "$changed_file" in
+        docs/*|.claude/*|.github/*|node_modules/*|package*.json|*.lock*|*.config*) continue ;;
+    esac
+
+    found_owner=0
+    while IFS=$'\t' read -r pattern doc; do
+        prefix="${pattern%%\*\**}"
+        prefix="${prefix%%\**}"
+        case "$changed_file" in
+            ${prefix}*)
+                found_owner=1
+                # Check if the doc was also modified recently
+                if ! echo "$changed_files" | grep -q "^${doc}$"; then
+                    printf '%s\t%s\n' "$doc" "$changed_file" >> "$TMP_STALE"
+                fi
+                break
+                ;;
+        esac
+    done < "$TMP_OWNS"
+
+    if [ "$found_owner" -eq 0 ]; then
+        case "$changed_file" in
+            src/*|app/*|packages/*) echo "$changed_file" >> "$TMP_UNOWNED" ;;
+        esac
+    fi
+done
+
+# Report stale docs
+if [ -s "$TMP_STALE" ]; then
+    echo "## Potentially Stale Docs"
+    echo ""
+    echo "These docs own code that changed recently, but the docs themselves were not updated:"
+    echo ""
+    current_doc=""
+    sort "$TMP_STALE" | while IFS=$'\t' read -r doc file; do
+        if [ "$doc" != "$current_doc" ]; then
+            [ -n "$current_doc" ] && echo ""
+            echo "**$doc**"
+            current_doc="$doc"
+        fi
+        echo "  - $file"
+    done
+    echo ""
+else
+    echo "## No Stale Docs Detected"
+    echo ""
+    echo "All docs whose owned code changed were also updated."
+fi
+
+echo ""
+
+# Report unowned files
+if [ -s "$TMP_UNOWNED" ]; then
+    unowned_count=$(wc -l < "$TMP_UNOWNED" | tr -d ' ')
+    echo "## Unowned Changed Files ($unowned_count)"
+    echo ""
+    echo "These changed source files have no owning feature doc:"
+    echo ""
+    sort -u "$TMP_UNOWNED" | head -30 | while IFS= read -r file; do
+        echo "- $file"
+    done
+    if [ "$unowned_count" -gt 30 ]; then
+        echo "- ... and $((unowned_count - 30)) more"
+    fi
+else
+    echo "## No Unowned Changed Files"
+fi

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

@@ -0,0 +1,238 @@
+---
+name: documentation
+description: Create and maintain technical documentation. Use when the user asks to (1) baseline, audit, or reorganize docs — enforces an opinionated 6-folder structure (architecture, features, operations, history, memory, tests) with ownership frontmatter and scaffold files, (2) document a feature or module, (3) create or update a changelog entry, (4) document data flows or Redux state, (5) add to protected files, (6) create or update guardrails (cascading failure boundaries), (7) record an architecture decision (ADR), (8) create or update the project root README, (9) create or update a plan, or (10) co-author any technical doc. Triggers on "document this", "create docs", "update changelog", "baseline docs", "audit docs", "add to protected files", "guardrails", "ADR", "architecture decision", "root README", "plan".
+---
+
+# Technical Documentation Skill
+
+Document contracts and architecture, not implementation details. Show function signatures and API shapes — never paste full implementations (they rot fast). Use ASCII diagrams over prose for flows. Only document state at persistence boundaries (Redux persistence, DB schemas, API shapes), not component-level or transient state. Mark deprecated fields with `// UNUSED:` comments. Breaking changes belong in changelogs only, not module docs.
+
+**No redirect docs.** When moving a doc to a new location, delete the old file entirely. Update all references (routing, ownership index, memory files, frontmatter `depends_on`, cross-doc links) to point to the new path. Never leave a stub file that says "Moved to X" — redirect docs rot, clutter the repo, and create false search hits.
+
+---
+
+## Decision Tree
+
+```
+User request
+    │
+    ├─ "Baseline/audit docs" ──────────▶ Baseline Audit (below)
+    │
+    ├─ "Document feature/module" ──────▶ Module Template
+    │
+    ├─ "Create/update changelog" ──────▶ Changelog Template
+    │
+    ├─ "Document data flow" ───────────▶ Module Template (Architecture section)
+    │
+    ├─ "Document Redux/state" ─────────▶ Module Template (State section)
+    │
+    ├─ "Add to protected files" ───────▶ Protected Files Template
+    │
+    ├─ "Create/update guardrails" ─────▶ Guardrails Template
+    │
+    ├─ "Record architecture decision" ─▶ ADR Template
+    │
+    ├─ "Create/update root README" ────▶ Project Root README Template
+    │
+    ├─ "Create/update plan" ───────────▶ Plan Template
+    │
+    ├─ "Update existing doc" ──────────▶ Preserve existing structure
+    │
+    └─ No template matches ────────────▶ Co-Authoring Workflow (below)
+```
+
+---
+
+## Baseline Audit
+
+When asked to "baseline", "audit", or "review" docs, enforce the canonical 6-folder documentation structure. This is an opinionated reorganization — the target structure is non-negotiable.
+
+### Target Structure
+
+```
+docs/
+├── README.md              # Documentation root — quick links table, section index
+├── structure.md           # Authority map, folder rules, health log
+├── CODEBASE_MAP.md        # Auto-generated directory map (optional)
+├── faq.md                 # Common issues (optional)
+├── architecture/          # System-wide decisions, patterns, technical references
+│   ├── adr/               # Architecture Decision Records (numbered, immutable)
+│   └── core/              # Core module internals (auth, state, routing)
+├── features/              # Living feature specs with ownership frontmatter
+│   └── {feature}/         # Subfolder for deep features (e.g., editor/)
+├── operations/            # Setup, development, deployment, CI/CD
+│   └── guardrails.md      # Cascading failure boundaries (cross-module contracts)
+├── history/               # Frozen/append-only records
+│   ├── CHANGELOG.md       # Master changelog index
+│   ├── changelog/         # Individual changelog entries
+│   ├── plans/             # Historical implementation plans (Status field required)
+│   └── backlog.md         # Tracked work items by priority (P0-P3)
+├── memory/                # Agent memory files
+└── tests/                 # Test plans and automation docs (optional)
+```
+
+### Workflow
+
+**Step 1: Inventory existing docs**
+
+Glob all markdown files in the repo. Categorize each file:
+
+| Category | Matches | Target |
+|----------|---------|--------|
+| Architecture | System design, patterns, config, API specs, tech decisions | `docs/architecture/` |
+| Features | How a feature works, user-facing behavior, data models | `docs/features/` |
+| Operations | Setup, dev workflow, deployment, CI/CD, runbooks | `docs/operations/` |
+| Plans | Implementation plans, proposals, RFCs | `docs/history/plans/` |
+| Changelogs | Change records, release notes | `docs/history/changelog/` |
+| Backlogs/Tasks | Work items, TODOs, tech debt | Merge into `docs/history/backlog.md` |
+| Stale/Deprecated | Self-marked deprecated, fully superseded, empty docs | Delete |
+| Root docs | `README.md`, `CLAUDE.md`, `AGENTS.md` | Stay in root |
+
+**Step 2: Detect duplicates and overlaps**
+
+For each topic, identify all files covering it. Keep the most complete version as canonical. Extract unique content from others before deleting.
+
+**Step 3: Present reorganization plan**
+
+Present a table to the user:
+
+```
+| File | Action | From | To | Reason |
+```
+
+Actions: `Move`, `Merge into {target}`, `Delete`, `Keep`, `Create`
+
+Ask: "Approve this plan? I'll execute all moves, merges, and deletions."
+
+**Step 4: Execute reorganization**
+
+After approval:
+
+1. Create the full folder structure:
+   - `docs/architecture/`
+   - `docs/features/`
+   - `docs/operations/`
+   - `docs/history/plans/`
+   - `docs/history/changelog/`
+   - `docs/memory/`
+   - `docs/tests/` (if test docs exist)
+2. Move files per the plan
+3. Merge content where specified (extract unique content, append to target)
+4. Delete stale/superseded files
+5. Add `Status: Complete | In Progress | Draft | Abandoned` to all plan files
+6. Add YAML frontmatter to feature docs (see Frontmatter Derivation below)
+7. Merge scattered backlog/task files into `docs/history/backlog.md`
+8. Scaffold standard files if missing:
+   - `docs/README.md` — from template (see `references/templates.md`)
+   - `docs/structure.md` — from template (see `references/templates.md`)
+   - `docs/operations/guardrails.md` — cascading failure boundaries (see `references/templates.md` for what to include/exclude)
+   - `docs/history/CHANGELOG.md` — master changelog index (header + table linking to entries)
+   - `docs/history/backlog.md` — work items by priority (P0-P3 sections, empty if nothing to merge)
+   - `docs/memory/index.md` — agent memory index (empty scaffold with section headers)
+   - `docs/memory/main.md` — main agent project memory (empty header + date marker)
+   - `docs/OWNERSHIP_INDEX.md` — generated table of feature doc ownership. Build it now from the frontmatter you derived in Step 6 (same shape the maintenance agent regenerates each run — see `references/templates.md`)
+   - `README.md` (repo root) — from §11 in `references/templates.md`, filled with concrete details from the repo (real package manager from the lockfile, real scripts, real layout). **Never overwrite an existing root README** — if one is present, leave it untouched.
+9. Fix all internal links broken by moves
+10. Record baseline in `docs/memory/index.md` with today's date (see template)
+
+**Step 5: Verify**
+
+1. Confirm all standard files exist: `docs/README.md`, `docs/structure.md`, `docs/operations/guardrails.md`, `docs/history/CHANGELOG.md`, `docs/history/backlog.md`, `docs/memory/index.md`, `docs/memory/main.md`, `docs/OWNERSHIP_INDEX.md`, `README.md` (repo root — must exist; either pre-existing untouched or freshly scaffolded)
+2. Confirm no dead links in `docs/README.md`
+3. Confirm every plan file has a `Status:` field
+4. Confirm feature docs have ownership frontmatter
+5. Confirm `docs/OWNERSHIP_INDEX.md` rows match the frontmatter on disk (no orphans, no missing entries)
+6. Confirm no docs remain outside the 6-folder structure (except `README.md`, `structure.md`, `CODEBASE_MAP.md`, `faq.md`)
+7. Confirm duplicates are eliminated — each topic has one canonical source
+
+### Rules
+
+- The 6-folder structure is mandatory. No `docs/guides/`, `docs/core/`, `docs/editor/`, `docs/pt/`, or any other top-level folder
+- Guides about how-to-run → `operations/`. Guides about a feature → `features/`
+- Core module docs → `docs/architecture/core/`. Editor module docs → `docs/features/editor/`
+- Only `CLAUDE.md`, `AGENTS.md`, and `README.md` are allowed in the repository root (not inside `docs/`)
+- Root-level `README.md` is for humans. `docs/README.md` is the agent/doc entry point
+- One canonical source per topic — link, don't copy
+- **No redirect docs** — when moving a file, delete the original and fix all references. Never leave a "Moved to X" stub.
+- For 10+ files, use parallel sub-agents (5-8 files each)
+
+### Naming & Lifecycle
+
+- Features: `kebab-case.md` — living reference, status `Active`
+- Plans: `YYYY-MM-DD-kebab-case.md` — frozen after `Complete` or `Abandoned`
+- Changelogs: `YYYY-MM-DD-kebab-case.md` — append-only
+- Memory: `{agent-name}.md` — agent-maintained
+
+---
+
+## Frontmatter Derivation
+
+When creating or updating a feature doc in `docs/features/`, generate `owns`, `touches`, `depends_on` frontmatter from the source code the doc describes.
+
+### When to run
+
+- **Baseline audit Step 6** — for every feature doc missing frontmatter
+- **New feature doc** — when creating a doc via the Module Documentation template
+- **Doc update** — when updating an existing feature doc and the frontmatter is missing or the documented scope changed
+
+### How to derive values
+
+**1. Identify `owns` patterns**
+
+Read the feature doc's content. Extract every source file path referenced in the doc (file listings, function locations, component paths). Group them into the narrowest glob patterns that cover all referenced files without overlapping other features.
+
+| Doc references | `owns` pattern |
+|---|---|
+| Multiple files under one directory | `src/feature/**` |
+| Specific files in a shared directory | List each file explicitly |
+| A single entry-point file | The exact file path |
+
+Verify patterns match real files — glob each pattern against the codebase. Remove any that match nothing.
+
+**2. Identify `touches` patterns**
+
+From the same source files the doc describes, find imports and calls to code outside the `owns` scope. These are files the feature uses but doesn't own.
+
+Common `touches` candidates:
+- Shared Redux slices the feature reads/writes
+- Utility functions from other modules
+- Shared hooks the feature calls
+- API route files the feature's frontend calls
+
+Keep `touches` to direct dependencies only — not transitive ones.
+
+**3. Identify `depends_on` docs**
+
+Check for explicit cross-references to other docs in `docs/features/` or `docs/architecture/`. Also check if the feature's `touches` paths are `owns`-ed by another feature doc — that doc is a dependency.
+
+### Rules
+
+- Every feature doc must have all three fields, even if empty (`depends_on: []`)
+- Use glob patterns for directories, explicit paths for individual files
+- Don't list paths that don't exist in the codebase
+- When a doc covers a deep feature with sub-specs (e.g., `editor/`), each sub-spec gets its own frontmatter — don't duplicate ownership across siblings
+- For baseline audits with 10+ files needing frontmatter, use parallel sub-agents to read and analyze the source files
+
+---
+
+## Co-Authoring Workflow
+
+For docs that don't match templates:
+
+**Stage 1: Context Gathering**
+- Ask: Audience? Purpose? Existing format?
+- Have user dump all context, then ask 5-10 clarifying questions
+
+**Stage 2: Structure & Draft**
+- Propose section structure, draft section by section
+- User indicates changes (don't edit directly — learn their style)
+
+---
+
+## Resources
+
+| File | Use For |
+|------|---------|
+| `references/templates.md` | docs/README.md, structure.md, frontmatter, scaffolds (CHANGELOG, backlog, memory, OWNERSHIP_INDEX), guardrails, feature, changelog, plan, protected files, ADR, project root README templates |
+| `references/style-guide.md` | Writing rules, formatting conventions |
+| `references/examples.md` | Good vs bad documentation examples |