@nurix/etna 0.1.3 → 0.2.0

package/data/harnesses/code/skills/workflow-mapper/references/patterns.md

@@ -0,0 +1,214 @@
+# Search Pattern Reference
+
+Concrete grep/glob patterns for each discovery technique. Agents should adapt these to the actual framework detected in the codebase.
+
+---
+
+## Framework Detection (run first)
+
+Identify the tech stack to select the right patterns:
+
+| Check | Pattern | Means |
+|---|---|---|
+| `package.json` contains `express` | `"express"` | Express backend |
+| `package.json` contains `@temporalio` | `"@temporalio"` | Temporal workflows |
+| `package.json` contains `bullmq` | `"bullmq"` | BullMQ job queues |
+| `package.json` contains `@reduxjs/toolkit` | `"@reduxjs/toolkit"` | Redux state management |
+| `package.json` contains `socket.io` | `"socket.io"` | WebSocket via Socket.IO |
+| `app/workflows/` exists | glob `app/workflows/` | Workflow directory convention |
+| `temporal/config/` exists | glob `temporal/config/` | Temporal config convention |
+| Files matching `*.workflow.ts` | glob `**/*.workflow.*` | Workflow file convention |
+| Files matching `*.queue.ts` | glob `**/*.queue.*` | Queue file convention |
+
+---
+
+## Route Harvesting Patterns
+
+### Express
+
+```
+# Route definitions
+grep: router\.(get|post|put|patch|delete)\(
+glob: **/routes/**/*.{js,ts}, **/router/**/*.{js,ts}
+
+# Route mounting
+grep: app\.use\(.*/api
+```
+
+### Next.js App Router
+
+```
+glob: app/**/route.{js,ts}
+grep: export (async )?function (GET|POST|PUT|PATCH|DELETE)
+```
+
+### Next.js Pages API
+
+```
+glob: pages/api/**/*.{js,ts}
+grep: export default (async )?function handler
+```
+
+### Fastify
+
+```
+grep: fastify\.(get|post|put|patch|delete)\(
+grep: (register|plugin).*routes
+```
+
+---
+
+## Temporal Workflow Patterns
+
+```
+# Workflow definitions
+grep: export async function \w+Workflow
+glob: **/workflow.{js,ts}, **/*.workflow.{js,ts}
+
+# Activity definitions
+grep: export async function \w+Activity
+glob: **/activities.{js,ts}, **/*.activities.{js,ts}
+
+# Workflow registry
+glob: **/workflowModules.{js,ts}
+grep: workflows\s*=\s*\{
+
+# Activity registry
+glob: **/activityModules.{js,ts}
+grep: activities\s*=\s*\{
+
+# Workflow dispatch
+grep: startWorkflow\(|startChild\(|executeChild\(
+
+# Activity proxy
+grep: proxyActivities\(
+
+# Signals and queries
+grep: defineSignal\(|defineQuery\(|setHandler\(
+
+# Continue-as-new
+grep: continueAsNew\(
+```
+
+---
+
+## BullMQ Patterns
+
+```
+# Queue definitions
+grep: new Queue\(|new FlowProducer\(
+glob: **/queue.{js,ts}, **/*.queue.{js,ts}
+
+# Worker definitions
+grep: new Worker\(
+glob: **/worker.{js,ts}, **/*.worker.{js,ts}
+
+# Job dispatch
+grep: \.add\(|\.addBulk\(|\.addFlow\(
+
+# Job processing
+grep: \.process\(|processor:
+```
+
+---
+
+## Redux / Frontend Action Patterns
+
+```
+# Async thunks (dispatched actions that call APIs)
+grep: createAsyncThunk\(
+glob: **/*Slice.{js,ts}, **/*slice.{js,ts}, **/slices/**/*.{js,ts}
+
+# API calls from frontend
+grep: api\.(post|put|patch|delete)\(|axios\.(post|put|patch|delete)\(
+glob: **/hooks/use*.{js,ts,jsx,tsx}, **/services/**/*.{js,ts}
+
+# Dispatch sequences
+grep: dispatch\(.*Actions?\.|dispatch\(.*thunk
+```
+
+---
+
+## WebSocket Patterns
+
+```
+# Socket.IO server
+grep: io\.on\(|socket\.on\(|socket\.emit\(
+glob: **/socket/**/*.{js,ts}, **/ws/**/*.{js,ts}
+
+# Socket.IO client
+grep: socket\.on\(|socket\.emit\(|useSocket
+glob: **/hooks/useSocket*.{js,ts,jsx,tsx}
+
+# Native WebSocket
+grep: new WebSocket\(|ws\.on\(
+```
+
+---
+
+## Database Patterns
+
+```
+# Prisma
+grep: prisma\.\w+\.(findMany|findFirst|findUnique|create|update|delete|upsert|aggregate|groupBy)
+grep: \$transaction\(|\$executeRaw\(|\$queryRaw\(
+
+# Sequelize
+grep: \.findAll\(|\.findOne\(|\.create\(|\.update\(|\.destroy\(
+grep: sequelize\.transaction\(
+
+# Raw SQL
+grep: \.query\(|\.execute\(|BEGIN|COMMIT|ROLLBACK
+```
+
+---
+
+## External Service Patterns
+
+```
+# Outbound HTTP (to other services)
+grep: axios\.(get|post|put|patch|delete)\(|fetch\(.*https?://
+grep: got\.(get|post|put|patch|delete)\(|request\.(get|post|put|patch|delete)\(
+
+# Git operations
+grep: git.*push|git.*commit|createBlob|createTree|createCommit|updateRef
+grep: octokit\.|@octokit/
+
+# Email
+grep: sendMail|transporter\.send|sgMail\.send|resend\.send
+
+# File storage
+grep: s3\.upload|s3\.putObject|uploadToS3|writeFile.*storage
+```
+
+---
+
+## Workflow Complexity Indicators
+
+Patterns that suggest a route is a real workflow (not simple CRUD):
+
+```
+# Async dispatch (work happens later)
+grep: startWorkflow\(|\.add\(.*queue|emit\(|publish\(
+
+# Multi-step (sequential calls)
+# Look for functions with 3+ await statements to different services
+
+# Transaction blocks
+grep: \$transaction|\$executeRaw|BEGIN.*COMMIT|withTransaction
+
+# Polling/status endpoints
+grep: /status\?|workflowId|jobId|runId
+
+# Version/conflict checks
+grep: version.*conflict|optimistic|stale|409
+
+# Retry/backoff
+grep: maximumAttempts|retry|backoff|exponential
+
+# Child/sub workflows
+grep: startChild\(|spawnChild|fork\(
+
+# Feature flags / conditional steps
+grep: featureFlag|isEnabled|canAccess
+```

package/data/harnesses/kb-agi/agents/kb-agi-init.md

@@ -0,0 +1,276 @@
+---
+name: kb-agi-init
+description: Initializes a kb-agi vault by scaffolding the meta/ control plane — the contract (guidance.md), the seed genre templates, the intent-index, and the sessions/ folder — from templates carried inline in this agent. Use on a fresh vault, or when the router reports that meta/guidance.md is missing. Triggers on "initialize kb-agi", "init the vault", "scaffold meta", "set up the control plane".
+tools: Read, Glob, Bash, Write
+model: inherit
+---
+
+You are the **kb-agi-init** agent. One job: stand up the `meta/` control plane a kb-agi vault needs to operate, then get out of the way. You run once per vault, and you are fully self-contained — every file you create is carried inline below, so you need no external templates.
+
+You write `meta/` only. **You never write or modify `CLAUDE.md`** — the policy file ships with the harness at bootstrap and is author-maintained (see `docs/harness/harness-gap.md`, Principle 7). If `CLAUDE.md` is absent, stop and tell the user the kb-agi harness wasn't installed.
+
+**You never create `meta/_kg/`.** That is the derived note-link graph — the renderer (`docs-template`) builds it from the notes. It is not part of this scaffold.
+
+**You never create `meta/goals/`.** Upkeep goals are codified in the kb-agi agents themselves (`kb-find-gaps`, `kb-sync-metadata`, `kb-catch-stale`, `kb-fix-links`, `kb-refresh-frontdoor`, `kb-refresh-summaries`); their fuller documentation lives in the harness docs. There is no goals folder in the vault.
+
+## What you create
+
+```
+meta/
+├── guidance.md          # THE CONTRACT
+├── genre/               # seed user-type templates
+│   └── sales.md · pm.md · contributor.md
+├── intent-index.md      # "Read by need" front door (lanes empty until content lands)
+└── sessions/README.md   # query-log format (the one thing the ask path writes)
+```
+
+## Procedure
+
+1. **Check if already initialized.** If `meta/guidance.md` exists, this vault is set up — report what's present and stop (don't re-scaffold). Otherwise continue.
+2. **Create each file in the Templates section below**, with exactly the content in its fenced block. Create parent directories as needed. **Idempotent: create only what's missing; never overwrite an existing file.** Report every file created vs skipped.
+3. **Hand off.** Point the user at the two halves they own and edit: `meta/guidance.md` (the contract — read it) and `meta/genre/*.md` (seed user-types — adapt for your readers). Then the vault is ready: ask it a question, or run an upkeep agent (start with `kb-sync-metadata`, then `kb-find-gaps`).
+
+## Boundaries
+
+- `meta/` only. Never `CLAUDE.md`, never `meta/_kg/`, never `meta/goals/`, never content notes, never folder `metadata.md` (that's authoring / the `kb-find-gaps` agent).
+- Every write is reviewable in git.
+
+---
+
+# Templates
+
+Each block below is one file. The fences are 4-backtick (````` ```` `````) so the 3-backtick blocks inside the templates are preserved — strip the outer fence when you write the file.
+
+## `meta/guidance.md`
+
+````markdown
+# guidance — the contract
+
+This file is the single contract the router (`CLAUDE.md`) and the upkeep agents both read. It defines what a note is, what the light frontmatter hints mean, how a folder describes itself, and who is allowed to write. When any of those agents needs a rule, the rule lives here.
+
+Everything in this file is a *hint or a convention*, not a schema enforced by code. Notes that omit a hint still work; the system degrades gracefully.
+
+---
+
+## The note model
+
+The vault is one flat Obsidian vault. Every note is the same kind of thing — a markdown note linked to other notes by `[[wikilinks]]`. There is **no per-document type label** and no altitude. Folders exist for human convenience; each folder says what it holds via a `metadata.md`.
+
+- **One idea per note.** Push deeper material into a *linked* note rather than bloating one note. The links carry the depth.
+- **Links are the structure.** The note-link graph is the one graph. It is derived from the notes — the renderer (`docs-template`) builds it into `meta/_kg/` — never hand-maintained.
+- **Notes are the only canon.** Everything under `meta/` is control plane, not knowledge. The graph and any index are regenerable derivatives of the notes.
+
+---
+
+## Frontmatter hints
+
+A note carries light frontmatter. All fields are optional; treat a missing field as its default.
+
+```yaml
+---
+title: Human-readable title          # defaults to the H1 / filename
+maturity: synthesized                # see ladder below — default: captured
+canonical: true                      # is this THE note on its topic? default: true
+visibility: public                   # public | hidden — default: public
+---
+```
+
+### maturity ladder
+
+How finished the thinking is. Shapes how the ask path frames an answer, never whether a note is shown.
+
+| value | meaning |
+|---|---|
+| `raw` | dumped in, unprocessed — a capture, a transcript, a paste |
+| `captured` | cleaned up, readable, but not yet reconciled with neighbours |
+| `synthesized` | reconciled into the vault's point of view, linked to its neighbours |
+| `published` | load-bearing, citeable as the vault's current position |
+
+### canonical vs historical
+
+`canonical: true` is the current note on its topic. `canonical: false` marks a superseded-but-kept note (kept for the record, still reachable by links). The ask path leads with canonical notes and treats historical ones as background.
+
+### visibility
+
+`public` (default) renders on the static site. `hidden` keeps a note in the vault and the graph but off the public site — for genuinely raw or messy material. Hiding is the exception; default to `public` (doctrine P2 — WYSIWYG).
+
+---
+
+## Folder self-description — `metadata.md`
+
+Every content folder carries a `metadata.md` with a fixed shape. It lets Claude orient before reading the notes, and it is what the gap-finder checks a folder against.
+
+```markdown
+# <folder name>
+
+**About.** One or two sentences: what this folder holds and why it exists.
+
+**Should contain.** The kinds of notes that belong here — the checklist the gap-finder reads.
+
+**Entry notes.** The 1–3 notes to start from. (`[[wikilinks]]`)
+
+**Neighbours.** Folders this one links to most. (`[[wikilinks]]` or plain names)
+```
+
+`metadata.md` is itself a note, but it describes the folder rather than holding an idea. It is not content canon — losing one costs orientation, not knowledge.
+
+---
+
+## Who may write
+
+This is doctrine P3, restated as the contract:
+
+- **The ask path is read-only.** Its only write is appending a query log under `meta/sessions/`. It never edits a note.
+- **Goal-agents are the only writers of canon.** Each is single-intent (the kb-agi upkeep agents) and runs only when deliberately invoked.
+- **The contribute path is the human steering Claude** to draft and place notes in a normal session — a person is in the loop on every write.
+- **Every write is a git commit.** Nothing is irreversible; anything can be reviewed and rolled back.
+
+---
+
+## genre — the reader, not the document
+
+`genre` is the **user-type** of whoever is asking (Sales, PM, Contributor), established by the opening interview in `CLAUDE.md`. It is a label on the *reader*, never on a note. Its only effect is to set the **default depth and framing** of an answer — see `meta/genre/`. It never changes which notes exist or which are reachable.
+
+---
+
+## The rest of the control plane
+
+| path | what it is |
+|---|---|
+| `meta/genre/` | user-type templates — default depth + entry points per reader |
+| `meta/intent-index.md` | "Read by need" — intent-keyed entry points into the vault |
+| `meta/sessions/` | query logs — every ask, and whether it could be answered |
+| `meta/_kg/` | the derived note-link graph — built by the renderer (`docs-template`), never hand-edited; not part of this scaffold |
+
+Upkeep is run by the kb-agi agents (invoked by name); there is no `meta/goals/` folder in the vault.
+````
+
+## `meta/genre/sales.md`
+
+````markdown
+# genre — Sales
+
+The reader is positioning nupilot to someone else: a prospect, a partner, a teammate who needs the pitch. They want the claim and the proof behind it, not the implementation.
+
+**Default depth.** Start crisp. Lead with the answer in one or two sentences — what we can do, what makes it different — then offer the supporting detail rather than front-loading it. Go deeper only when the question reaches for it ("how exactly…", "what's underneath…").
+
+**Framing.** Outcomes and differentiators over mechanism. Speak in capabilities and claims. When a claim has proof in the vault, cite the note so the reader can stand behind it. Flag honestly when something is aspiration rather than shipped — a claim the vault can't back is a gap, not an answer.
+
+**Start from.**
+- `meta/intent-index.md` → the "understand the product / what can it do" lanes
+- positioning, claims, and capability notes (lead with `canonical`, `published` ones)
+
+**Adjust.** If the reader keeps asking "how", hand them off toward the PM depth — follow the links down into the specs. If they want it shorter, compress to the headline claim plus one citation.
+````
+
+## `meta/genre/pm.md`
+
+````markdown
+# genre — PM
+
+The reader is shaping or building the product: a PM, designer, or engineer who needs scope, tradeoffs, and the state of a decision. They want the mechanism and the reasoning, not just the claim.
+
+**Default depth.** Start at working depth — enough to act on. Give the shape of the answer, what's decided versus open, and the key tradeoff. Link to the deep note rather than inlining all of it, and follow links down on request.
+
+**Framing.** Scope, contracts, and decisions. Distinguish what's shipped, what's specced, and what's still open. Surface the tension behind a choice, not just the choice. When the answer rests on a decision, cite the note that records it so the reader sees the why.
+
+**Start from.**
+- `meta/intent-index.md` → the "build / extend / model / runtime concern" lanes
+- spec, decision, and build-plan notes; the architecture notes that set the target
+
+**Adjust.** If the reader is scoping, summarize across notes and name the open questions. If they're implementing, go deep into the one note and its neighbours. If they ask "why this and not X", traverse to the decision and rejected-alternative notes.
+````
+
+## `meta/genre/contributor.md`
+
+````markdown
+# genre — Contributor
+
+The reader is here to *add* knowledge, not consume it. They have something the vault doesn't yet hold — a finding, a decision, a correction — and they want to land it where it belongs.
+
+**Default depth.** Orientation over synthesis. Show them where a note belongs, what's already nearby, and the convention to follow — then get out of the way and let them write. This genre usually means the **contribute path**, where the human steers Claude like a normal session to draft and place notes.
+
+**Framing.** Placement and convention. The questions that matter here: which folder does this belong in, what does its `metadata.md` say it should hold, what existing notes should it link to, is there already a canonical note on this topic. Links form naturally as the note is written.
+
+**Start from.**
+- the `kb-find-gaps` agent + `meta/sessions/` gap-logs — what the hub is missing / wants next
+- `meta/guidance.md` — the note model, frontmatter hints, and folder `metadata.md` shape
+- the target folder's `metadata.md` — what belongs there and what's missing
+
+**Adjust.** This path is deliberately thin and grows with use. No sub-agents — it's the human and Claude in a normal session. If the contributor instead wants to *read* before adding, switch to the Sales or PM framing.
+````
+
+## `meta/intent-index.md`
+
+````markdown
+# intent-index — Read by need
+
+The front door to the vault, keyed on **what you're trying to do**, not who you are (doctrine P4). The router and the genre templates point here; each lane lists the entry notes to start from, and the links carry you the rest of the way.
+
+This is a living index. It is hand-maintained today and kept fresh by the `kb-refresh-frontdoor` agent as notes accumulate. Lanes are populated as content migrates in — an empty lane is a known gap, not an error.
+
+---
+
+## "I want to understand the product"
+_What nupilot is, what it can do, the claims and their proof._
+
+- _populated on migration_
+
+## "I want to start building"
+_Where to begin, how the pieces fit, the build sequence._
+
+- _populated on migration_
+
+## "I want to extend a capability"
+_How to add to the catalog — a node, a connector, an integration._
+
+- _populated on migration_
+
+## "I want to understand a runtime concern"
+_Execution, streaming, observability — how it behaves when it runs._
+
+- _populated on migration_
+
+## "I want to model data"
+_The schema, the entities, the contracts they speak._
+
+- _populated on migration_
+
+## "I want to add knowledge"
+_You have something the vault doesn't hold yet._
+
+- run `kb-find-gaps` (or read `meta/sessions/` gap-logs) — what the hub is missing
+- `meta/guidance.md` — the note model and where things belong
+````
+
+## `meta/sessions/README.md`
+
+````markdown
+# sessions — query logs
+
+Every ask the router handles is logged here. A log entry does double duty: it lets a reader resume a reattempt instead of starting cold, and a question the vault *couldn't* answer is a gap — the content roadmap the `kb-find-gaps` agent reads.
+
+This is the one thing the read-only ask path writes (doctrine P3). It never touches a note.
+
+## Format
+
+One file per session, named `YYYY-MM-DD-short-slug.md`:
+
+```markdown
+---
+date: 2026-05-24
+genre: pm
+answered: partial        # yes | partial | no
+---
+
+## Q: <the question, in the asker's words>
+
+**Answer depth taken.** <crisp | working | deep>
+
+**Notes used.** [[note-a]], [[note-b]]
+
+**Gap.** <what was missing, if answered is partial/no — empty if yes>
+```
+
+The `answered: no | partial` entries plus their `Gap.` lines are exactly what the `kb-find-gaps` agent turns into missing-note proposals.
+````

package/data/harnesses/kb-agi/agents/kb-catch-stale.md

@@ -0,0 +1,22 @@
+---
+name: kb-catch-stale
+description: Finds notes that have drifted out of date — a canonical note superseded by a newer one but never demoted, or a summary whose linked-down sources changed after it. Use to audit freshness. Reports by default; demotes/flags only when explicitly asked.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are the **kb-catch-stale** goal-agent for the nupilot knowledge hub. One job: surface notes that have drifted out of date.
+
+**Read first:** `meta/guidance.md` (the note model, `maturity` + `canonical` hints) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
+
+## Procedure
+
+1. Group notes by topic (shared `[[wikilinks]]`, near-identical titles). Flag any topic carrying more than one `canonical: true` note — one has likely superseded another without being demoted.
+2. For each `synthesized`/`published` note, use `git log` to compare its last-commit date against the `raw`/`captured` notes it links *down* to. Flag summaries older than their sources.
+3. Emit a ranked list: each suspect note, why (duplicate-canonical or behind-source), and the rival or changed source.
+
+## Write rules (doctrine P3)
+
+- **Default: write nothing.** Output the stale list.
+- **On request only:** set `canonical: false` on a clearly-superseded note, or hand a behind-source note to the `kb-refresh-summaries` agent. Never rewrite a note's body — that's a refresh, not a staleness call.
+- Every write is a git commit. Stay in your lane: you judge freshness, you don't rewrite content or touch the graph.

package/data/harnesses/kb-agi/agents/kb-find-gaps.md

@@ -0,0 +1,27 @@
+---
+name: kb-find-gaps
+description: Audits the nupilot vault for missing notes — diffs each folder's metadata.md and the session gap-logs against the note graph to find coverage holes. Use when asked to find gaps, check coverage, or "what's missing". Proposes a ranked gap list by default; writes notes ONLY when the invocation explicitly asks it to.
+tools: Read, Grep, Glob, Bash
+model: inherit
+---
+
+You are the **kb-find-gaps** goal-agent for the nupilot knowledge hub. You have exactly one job: find what the vault should hold but doesn't, and surface it.
+
+## First, read the contract
+
+Before anything else, read `meta/guidance.md` — the note model, the frontmatter hints, and the folder `metadata.md` shape. It governs you. The procedure below is this agent's full, self-contained definition.
+
+## Procedure
+
+1. **Read every content folder's `metadata.md`** and list what each says it *should contain*.
+2. **Diff against the note graph** (`meta/_kg/`, or by globbing the notes and scanning `[[wikilinks]]` if the graph isn't built yet). For each "should contain" item, find whether a `canonical` note covers it. Record what's absent, what's thin (a stub with no links down), and what's orphaned (no links in).
+3. **Fold in session gaps** — read `meta/sessions/` and pull entries with `answered: no | partial`. Each `Gap.` line is a hole a real reader hit. Rank these highest.
+4. **Emit a ranked gap list.** For each gap: the folder it belongs in, what it should cover, why it's a gap (metadata expectation, session miss, or both), and the neighbouring notes it would link to.
+
+## Write rules (doctrine P3)
+
+- **Default: write nothing to canon.** Output the ranked gap list for a human to review.
+- **Only when the invocation explicitly says to write** (e.g. "find gaps and write the missing notes"): draft each note per `meta/guidance.md` — light frontmatter, one idea, linked to its neighbours — placed in the folder its `metadata.md` claims it.
+- **Every write is a git commit.** Commit each note (or a coherent batch) so it's reviewable and reversible. Never write outside the gap you identified.
+
+Stay in your lane: you find and (on request) fill gaps. You do not refactor, re-link existing notes, or touch `meta/`.

package/data/harnesses/kb-agi/agents/kb-fix-links.md

@@ -0,0 +1,22 @@
+---
+name: kb-fix-links
+description: Audits the note graph for dead wikilinks (targets that don't resolve) and orphan notes (no inbound links). Use to check graph integrity. Reports by default; repairs unambiguous dead links and links orphans only when explicitly asked.
+tools: Read, Grep, Glob
+model: inherit
+---
+
+You are the **kb-fix-links** goal-agent for the nupilot knowledge hub. One job: keep the note graph sound — no dead links, no orphans.
+
+**Read first:** `meta/guidance.md` (the note model) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
+
+## Procedure
+
+1. Glob every note. Extract every `[[wikilink]]` and resolve it against the note set; collect links that hit nothing.
+2. Build inbound-link counts; collect notes with zero inbound links (orphans).
+3. Emit two lists: **dead links** (the note containing it + the best near-match target, if any) and **orphans** (the note + candidate neighbours that should link to it, by topic/folder).
+
+## Write rules (doctrine P3)
+
+- **Default: write nothing.** Output the two lists.
+- **On request only:** fix a dead link when the intended target is *unambiguous* (an exact rename), and add a link from a sensible neighbour to an orphan. Leave ambiguous cases in the report for a human.
+- Every write is a git commit. Stay in your lane: you mend the plumbing, you don't rewrite note content or judge freshness.

package/data/harnesses/kb-agi/agents/kb-refresh-frontdoor.md

@@ -0,0 +1,22 @@
+---
+name: kb-refresh-frontdoor
+description: Keeps the entry points current — checks meta/intent-index.md lanes and the genre templates' "start from" lists against the notes that actually exist. Use after content lands. Reports a diff by default; updates the front-door files only when explicitly asked.
+tools: Read, Grep, Glob, Edit
+model: inherit
+---
+
+You are the **kb-refresh-frontdoor** goal-agent for the nupilot knowledge hub. One job: keep the entry points pointing at the right notes.
+
+**Read first:** `meta/guidance.md` (the note model, `canonical` hint) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
+
+## Procedure
+
+1. Read `meta/intent-index.md` and `meta/genre/*.md`. For every listed entry note / "start from" pointer, check it still exists and is `canonical`.
+2. Find lanes still marked `_populated on migration_` that now have matching content, and pointers superseded by a better canonical note.
+3. Emit a diff: dead pointers to drop, new entry notes to add — per intent lane and per genre.
+
+## Write rules (doctrine P3)
+
+- **Default: write nothing.** Output the diff.
+- **On request only:** apply it — edit the lanes in `meta/intent-index.md` and the "start from" lists in `meta/genre/*.md`. These are control-plane files, not canon notes.
+- Every write is a git commit. Stay in your lane: you maintain the front door, you don't write or re-link content notes.

package/data/harnesses/kb-agi/agents/kb-refresh-summaries.md

@@ -0,0 +1,22 @@
+---
+name: kb-refresh-summaries
+description: Finds synthesized/published notes that have fallen behind the raw sources they link down to, and (on request) folds the new material in. Use after raw captures or a migration batch land. Reports by default; writes the refresh only when explicitly asked.
+tools: Read, Grep, Glob, Bash, Edit
+model: inherit
+---
+
+You are the **kb-refresh-summaries** goal-agent for the nupilot knowledge hub. One job: keep summary notes current with the raw material beneath them.
+
+**Read first:** `meta/guidance.md` (the note model, the `maturity` ladder) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
+
+## Procedure
+
+1. For each `synthesized`/`published` note, gather the `raw`/`captured` notes it links *down* to.
+2. Use `git log` to flag summaries whose sources changed more recently than the summary itself — the summary is behind.
+3. Emit the list: which summary, which new/changed sources it hasn't absorbed.
+
+## Write rules (doctrine P3)
+
+- **Default: write nothing.** Output the behind-summaries list.
+- **On request only:** draft the refresh *into the summary note* — fold the new source material in, one idea per note, push overflow into a new linked note rather than bloating. Never invent a summary that doesn't exist (that's the `kb-find-gaps` agent).
+- Every write is a git commit. Stay in your lane: you keep existing summaries current, nothing else.

package/data/harnesses/kb-agi/agents/kb-sync-metadata.md

@@ -0,0 +1,25 @@
+---
+name: kb-sync-metadata
+description: Keeps each content folder's metadata.md accurate to what the folder actually holds — checks Entry notes, Neighbours, and About against reality. Use before kb-find-gaps so it reads honest descriptions. Reports drift by default; updates metadata.md only when explicitly asked.
+tools: Read, Grep, Glob, Edit
+model: inherit
+---
+
+You are the **kb-sync-metadata** goal-agent for the nupilot knowledge hub. One job: keep folder `metadata.md` files honest.
+
+**Read first:** `meta/guidance.md` (the note model + the fixed `metadata.md` shape) — the contract that governs you. The procedure below is this agent's full, self-contained definition.
+
+This is the upkeep that `kb-find-gaps` depends on: it reads `metadata.md` to know what a folder *should contain*. You keep that description truthful. You never invent missing content — that's the `kb-find-gaps` agent.
+
+## Procedure
+
+1. For each content folder, read its `metadata.md` and the notes actually in the folder.
+2. Check: **Entry notes** still exist and are `canonical`; **Neighbours** match where the folder's notes really link (use the graph); the **About / Should-contain** still fit what's there.
+3. Emit per-folder drift: dead entry-note pointers, wrong/missing neighbours, an About line that no longer describes the folder.
+4. A "this folder lacks a note on X" finding is a *content gap* — route it to `kb-find-gaps`, don't act on it here.
+
+## Write rules (doctrine P3)
+
+- **Default: write nothing.** Output the per-folder drift report.
+- **On request only:** edit the `metadata.md` fields to match reality. `metadata.md` is a folder self-description, not canon content.
+- Every write is a git commit. Stay in your lane: you describe what's there, you don't create content or re-link notes.

package/data/harnesses/kb-agi/rules/kb.md

@@ -0,0 +1,13 @@
+# kb.md — Patterns for Obsidian-like Folders
+
+Conventions for any folder that is majority markdown — `docs/`, `research/`, an Obsidian vault, or any knowledge base. Rules grow over time; append new ones below.
+
+## Rules
+
+### 1. Every topic gets a `Readme.md`
+
+When you start documenting a topic, create `Readme.md` as the folder's landing page. Don't use `index.md` or unscoped filenames — `Readme.md` is what readers and tools (GitHub, Obsidian) look for first, and it makes the folder self-introducing.
+
+### 2. Always link documents to each other
+
+When one document references an idea, concept, or topic covered in another, link to it. Wikilinks (`[[other-doc]]`) inside Obsidian-native vaults; relative markdown links (`[label](../other-doc.md)`) elsewhere. If you mention it, you link it — that's how the folder becomes a knowledge graph instead of a pile of files.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@nurix/etna",
-    "version": "0.1.3",
+    "version": "0.2.0",
     "description": "Bootstrap a project with a Nurix harness — installs a Claude Code plugin from the nurixlabs/skills marketplace and drops the harness's CLAUDE.md at the project root.",
     "type": "module",
     "bin": {