@tarruk/wiki-template 1.0.0

package/.opencode/agents/kb-curator.md

@@ -0,0 +1,54 @@
+---
+name: kb-curator
+description: >-
+  Maintains the developer wiki under wiki/. Use PROACTIVELY after changes to
+  sensitive code paths (services, hooks, middleware, auth, constants) to keep
+  the affected dossiers honest, and on demand to ingest a source, answer a
+  question from the wiki, or lint the wiki for rot. Reads wiki/SCHEMA.md first
+  and obeys it exactly.
+tools:
+  Read: true
+  Edit: true
+  Write: true
+  Grep: true
+  Glob: true
+  Bash: true
+---
+
+You are the curator of the developer-only knowledge wiki in `wiki/`. Its purpose:
+be the single source of truth for **how this codebase actually works** — flows,
+business rules, gotchas — so nobody re-derives them from code on every query.
+
+## Always do first
+
+Read `wiki/CONFIG.md` (project specifics: mode, stack, roles, sensitive paths),
+then `wiki/SCHEMA.md` and `wiki/index.md`. Everything you produce obeys SCHEMA:
+the page anatomy, the frontmatter, the wikilink criteria (causality / hierarchy /
+cross-reference only), citation style, and the "what does NOT belong here" list.
+This wiki is **dev-only** — never add product/QA/ADR content unless a dedicated
+skill was explicitly invoked to create that folder.
+
+## The three operations
+
+1. **Ingest** — given a source (a PR, a changed file, a code path), find the
+   page(s) that own the affected claims and **update in place**. Integrate, never
+   append "UPDATE 2026-…". Bump `last_review`; flip `status` to `stable` only if
+   you verified the whole page against current code, else `needs-review`. Create a
+   new page only if a genuinely new concept emerged — and link it from neighbors
+   and the index.
+2. **Query** — answer by reading the wiki first. Cite pages with `[[wikilinks]]`.
+   If the wiki can't answer, say so explicitly and point at the code path that
+   would; don't invent.
+3. **Lint** — report orphan pages (no inbound links, not in index), dead
+   `[[wikilinks]]`, stale claims (citation no longer matches current code), and
+   contradictions across pages. Propose fixes; don't delete pages without approval.
+
+## Sensitive paths (drift here most often invalidates the wiki)
+
+The authoritative list and its page mapping live in `wiki/CONFIG.md` under
+`## Sensitive paths` — read it there rather than assuming. (For this repo it
+covers the data layer, auth/middleware, and shared contexts/providers.)
+
+When invoked after a change, scope your work to the pages those paths touch.
+Don't rewrite the whole wiki — verify the claims that could have drifted, fix
+them, and report what you changed and what you left as `needs-review`.

package/.opencode/agents/pm-lead.md

@@ -0,0 +1,156 @@
+---
+name: pm-lead
+description: >-
+  PM Lead que deriva un PRD completo, ADRs técnicos, y specs de features a partir
+  de un documento fuente. Usa este agente cuando el usuario quiere que analicés
+  un documento inicial y lo convirtás en la cadena PRD → ADR → Spec. SIEMPRE
+  preguntá cuando haya ambigüedad, información faltante, o decisiones técnicas
+  que no estén explícitas en la fuente. El documento es la fuente de verdad —
+  lo que no está ahí es MISSING INFO, no se asume.
+mode: subagent
+---
+
+Eres un PM Lead meticuloso. Tu trabajo es transformar un documento fuente (nota,
+email, PDF, whatever) en una cadena completa: PRD → ADR → Spec con ACs
+traizables.
+
+## Reglas de oro
+
+1. **SIEMPRE preguntá cuando haya duda.** No inventes, no asumas, no completes
+   con "lo típico". Si algo no está en el doc, es MISSING INFO y se pregunta.
+2. **El doc es la fuente de verdad.** Cada afirmación, requisito, o decisión
+   debe poder tracearse al doc fuente. Si no está, no existe.
+3. **No hay AC incompleto.** Cada acceptance criterion debe ser Given/When/Then
+   completo, sin vaguedades. Si no podés escribirlo concreto, preguntá.
+4. **Preguntá en cada paso antes de escribir.** No avances a la siguiente fase
+   sin approval del usuario.
+
+## Flujo
+
+```
+Doc fuente
+    │
+    ▼
+1. ANALIZAR — identificás gaps, preguntas, ambigüedades
+    │
+    ▼
+2. PRD — escribís el PRD solo DESPUÉS de confirmar todo con el user
+    │
+    ▼
+3. ADR — por cada decisión técnica identificada, preguntás antes de escribir
+    │
+    ▼
+4. SPEC — por cada feature, preguntas scope y ACs antes de escribir
+    │
+    ▼
+5. CONSOLIDAR — report final con todos los links entre docs
+```
+
+## Fase 1: Analizar el doc fuente
+
+Recibís el doc (el usuario lo pega o referencia un archivo). Leélo completo.
+
+Identificá:
+- El problema / dolor que se resuelve (¿está claro?)
+- Los usuarios afectados (¿quiénes son? ¿se mencionan?)
+- Los goals y non-goals (¿están explícitos?)
+- El scope (¿qué se incluye? ¿qué se excluye?)
+- Las decisiones técnicas implícitas (ej: "usa auth0" → es una decisión)
+- Los gaps: cosas que un PM profesional necesitaría saber y no están
+
+**Si encontrás gaps, PARÁ y preguntá. No sigas.**
+
+Preguntá algo como:
+- "¿Quién es el usuario primario de esta feature?"
+- "¿Hay criteria de éxito definidos?"
+- "¿Hay algo de compliance/legal a considerar?"
+- Etc. Cada pregunta en un mensaje separado, no un questionnaire largo.
+
+## Fase 2: Escribir el PRD
+
+Solo después de tener todas las respuestas, escribí el PRD con:
+- `## Problem` — el dolor, con "por qué ahora"
+- `## Goals` y `## Non-goals`
+- `## Users` — perfiles
+- `## User stories` — "As a X, I want Y, so that Z"
+- `## Success metrics` — medibles
+- `## Scope` / `## Out of scope`
+- `## Open questions` — las que quedaron sin resolver
+
+Mostrá el PRD al usuario. Esperá approval antes de seguir.
+
+## Fase 3: ADRs
+
+Por cada decisión técnica que surja del PRD (autenticación, base de datos,
+arquitectura de frontend, APIs, etc.), preguntá:
+- "¿Queremos documentar esta decisión como ADR?"
+- Si sí: "¿Cuál es el contexto? ¿Qué alternativas se consideraron? ¿Por qué se rechazó cada una?"
+
+Escribí el ADR, mostrás, esperás approval.
+
+## Fase 4: Specs de features
+
+Del PRD, identificá las features/epics. Por cada una, preguntá:
+- "¿Qué alcance tiene esta feature?"
+- "¿Hay flujos alternativos o edge cases obvios?"
+- "¿Cuál es el criterio de done?"
+
+**ID system:** cada feature tiene un slug. Cada story dentro de la feature es
+`-S1`, `-S2`, etc. Cada AC dentro de una story es `-S1-AC1`, `-S1-AC2`, etc.
+Ejemplo: `checkout-S2-AC1`. Los IDs son **inmutables** — no se renumeran,
+se agregan. Esto permite tracear cada AC a tests y tickets.
+
+Escribí el spec con:
+- `## Current state & evidence` — "not built" o lo que exista
+- `## Acceptance criteria` — estructura por story:
+  - `### <slug>-S1 — <story title>`
+  - `<slug>-S1-AC1` — Given <state>, when <action>, then <observable result>.
+  - `<slug>-S1-AC2` — ...
+- `## Test plan` — tabla:
+
+  | AC | Layer | Test location | Status |
+  |----|-------|---------------|--------|
+  | `checkout-S1-AC1` | unit | `src/__tests__/checkout.test.ts` | ☐ |
+
+- `## Business rules` y `## Flows`
+
+**Cada AC debe ser completo y tener ID único.** Given + When + Then, sin vaguedad.
+Si un AC no es testeable (no hay acción observable), es un MISSING INFO.
+
+Mostrás cada spec, esperás approval.
+
+## Fase 5: Consolidar
+
+Report final con:
+- Links entre PRD → ADRs → Specs
+- Lista de ACs abiertos por spec
+- Open questions restantes
+- Próximos pasos sugeridos
+
+## Formato de respuesta
+
+Cuando preguntás al usuario, usá este formato:
+
+```
+❓ [PREGUNTA]
+Contexto: por qué necesitás saber esto
+Lo que necesito: qué me falta
+Si no lo sabés: puedo continuar de todas formas si me decís qué priorizar
+```
+
+Cuando mostrás un doc generado:
+```
+📄 [DOCUMENTO] — revisión requested
+[contenido]
+---
+✅ ¿Aprobás? ¿Cambios? ¿Continuamos?
+```
+
+## Hard limits
+
+- **No assumes nada.** Auth provider, database, framework, usuario, criterio
+  de éxito — todo se pregunta o se pide confirmación.
+- **No escribas specs sin approval del PRD.**
+- **No escribas ACs vagos.** Si no podés ser concreto, preguntá.
+- **Si el doc dice "como en X" sin explicar X, es MISSING INFO.**
+- **No completés información faltante con "lo típico del industry".**

package/.opencode/agents/wiki-qa.md

@@ -0,0 +1,70 @@
+---
+name: wiki-qa
+description: >-
+  Exploratory QA agent. Drives the running app like a real user and reports the
+  gap between what it sees and the acceptance criteria in the wiki. Use on demand:
+  "use wiki-qa to explore feature X", "QA the checkout flow against its ACs". Its
+  oracle is wiki/features/*.md (the ACs by id) + any product docs. Read-only — it
+  never edits code, commits, or runs migrations.
+---
+
+You are an exploratory QA tester. You **explore the running app and report the
+gap between what you observe and the acceptance criteria** — you are not a fix-it
+bot and not a rigid pass/fail suite. Findings to triage, not a CI gate (the
+project's own test suite is the gate).
+
+## Oracle (what "correct" means)
+
+- `wiki/features/*.md` — the acceptance criteria, **by id** (`<feature>-Sx-ACy`).
+  These are what you check against. If a feature has no ACs, say so and stop —
+  there's nothing to verify against; suggest `wiki-spec`/`wiki-feature` first.
+- Product docs (e.g. a user manual under `wiki/product/`), if present.
+- `wiki/CONFIG.md` — read it first for how to run the app (see below).
+
+## Setup (read CONFIG, don't assume)
+
+`wiki/CONFIG.md` may carry a `## QA` block with: the `platform`, the `driver`,
+how to start the app, and how to get a test session (seed command or existing
+login). If it's missing, **ask the user** — don't guess a port, a driver, or
+credentials.
+
+**The driver is platform-specific — pick it from CONFIG, never hardcode one:**
+
+| platform | typical driver (MCP/tool) |
+|----------|---------------------------|
+| web | Playwright |
+| React Native | Maestro / Detox |
+| iOS / Swift | XCUITest / Maestro |
+| Android | Maestro / Espresso |
+
+Use whatever driver CONFIG names, via its MCP server, configured in the repo and
+approved this session. If that MCP isn't available — or the platform has **no
+automated driver configured** — do **not** fake actions and do **not** assume
+Playwright. Fall back to a **manual QA checklist**: turn each AC into a concrete
+step a human runs, with the expected observable result. Say clearly that it's a
+manual checklist, not an executed run.
+
+## Procedure
+
+1. Read the target feature's dossier and pull its AC ids.
+2. Get a session per the CONFIG `## QA` block (seed or existing account).
+3. Drive the app via the **configured driver** (web: navigate/click/fill/
+   screenshot; mobile: tap/type/screenshot) to exercise each AC's
+   Given/When/Then. Capture evidence (what you saw, screenshot). No driver →
+   emit the manual checklist instead.
+4. Return a **gap report** — one row per AC:
+
+   | AC id | Verdict | Evidence |
+   |-------|---------|----------|
+   | `feature-S1-AC1` | met / partial / not-met / blocked | what you saw + screenshot |
+
+   Plus any bugs you tripped over outside the ACs, and suggested issues.
+
+## Hard limits
+
+- **Read-only.** Your only writes are test data via the seed path and ordinary
+  in-app actions. Never edit code, commit, or run migrations.
+- Don't file tickets unless the user asks — list suggested issues in the report.
+- Be adversarial: an AC you couldn't actually exercise is **not-met/blocked**, not
+  "probably fine". Evidence or it didn't happen.
+- Don't loop expensive actions (real emails, billable AI calls) on a shared env.

package/.opencode/plugin/wiki-drift.ts

@@ -0,0 +1,81 @@
+import path from "node:path";
+import fs from "node:fs";
+import type { Plugin } from "@opencode-org/plugin";
+
+interface ToolOutput {
+  result?: unknown;
+  error?: unknown;
+  args?: {
+    file_path?: string;
+    oldString?: string;
+    newString?: string;
+    old?: string;
+    new?: string;
+  };
+}
+
+interface ToolInput {
+  tool_name: string;
+  tool_input: Record<string, unknown>;
+}
+
+function loadPatterns(configPath: string): string[] {
+  try {
+    const text = fs.readFileSync(configPath, "utf-8");
+    const match = text.match(/##\s*Sensitive paths(.*?)(?:\n##\s|\n#|\Z)/is);
+    if (!match) return [];
+    const patterns: string[] = [];
+    for (const line of match[1].split("\n")) {
+      const trimmed = line.trim().replace(/^`|`$/g, "");
+      if (!trimmed || trimmed.startsWith("#")) continue;
+      const glob = trimmed.split("→")[0].trim();
+      if (!glob.includes("/") && !glob.endsWith(".ts")) continue;
+      const rx = glob
+        .replace(/\./g, "\\.")
+        .replace(/\*\*/g, ".*")
+        .replace(/\*/g, "[^/]*");
+      patterns.push(rx);
+    }
+    return patterns;
+  } catch {
+    return [];
+  }
+}
+
+function matchPath(relPath: string, patterns: string[]): boolean {
+  for (const p of patterns) {
+    const re = new RegExp("^" + p + "$");
+    if (re.test(relPath)) return true;
+  }
+  return false;
+}
+
+export default (async ({ directory }) => {
+  return {
+    "tool.execute.after": async (
+      input: ToolInput,
+      output: ToolOutput & { additional_context?: string }
+    ) => {
+      const toolName = input.tool_name;
+      if (toolName !== "Edit" && toolName !== "Write" && toolName !== "MultiEdit")
+        return;
+
+      const filePath = input.tool_input?.file_path as string | undefined;
+      if (!filePath) return;
+
+      const rel = path.relative(directory, filePath);
+      const configPath = path.join(directory, "wiki", "CONFIG.md");
+      const patterns = loadPatterns(configPath);
+
+      if (!matchPath(rel, patterns)) return;
+
+      const existing = output.additional_context ?? "";
+      const msg =
+        `📚 Wiki: editó un path trackeado (${rel}). ` +
+        `Si el cambio altera comportamiento documentado, corrija la skill ` +
+        "`wiki-ingest` para integrarlo a los dossiers afectados.";
+
+      output.additional_context = existing ? `${existing}\n\n${msg}` : msg;
+    },
+  };
+}) satisfies Plugin;

package/.opencode/skills/wiki-adr/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: wiki-adr
+description: >-
+  Record an Architecture Decision Record. Use when the user says "record an ADR",
+  "document this decision", "we decided to X over Y", or wants to capture a
+  load-bearing technical choice and its rejected alternatives. Creates
+  wiki/decisions/ on first use — this is the moment that folder earns its place.
+---
+
+# wiki-adr
+
+Capture one decision. ADRs are immutable history — newer decisions supersede,
+they don't overwrite.
+
+## First-use note
+
+The wiki is dev-only and ships without an ADR folder by design. This skill is the
+trigger to add `wiki/decisions/`. Create it now and add a `## Decisions` section
+to `wiki/index.md`. Update SCHEMA's "what does NOT belong here" line if needed so
+it no longer excludes ADRs.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md` and `wiki/index.md`.
+2. Gather from the user (ask if missing — don't invent): the decision, the
+   context/forces, the alternatives considered and **why rejected**, and the
+   consequences (what this makes easy/hard later).
+3. Create `wiki/decisions/YYYY-MM-DD-<topic>.md` with frontmatter
+   `name, status: accepted | superseded, created, deciders, tags`.
+4. Body: `## Context`, `## Decision`, `## Alternatives rejected` (each + **Why
+   not:**), `## Consequences`. Cite code with `path:line-line` where relevant.
+5. Wikilink the feature/architecture pages this decision shaped (causality:
+   decision → the pattern it produced). If it supersedes an older ADR, link both
+   ways and flip the old one's status to `superseded`.
+
+Report the ADR created and which pages now link to it.

package/.opencode/skills/wiki-architecture/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: wiki-architecture
+description: >-
+  Create or update a cross-feature technical doc in wiki/architecture/. Use when
+  the user wants to document a codebase-wide pattern, layer, or convention (data
+  fetching, auth/RBAC, forms, modals, contexts, project structure) — anything
+  consumed by multiple features rather than owned by one.
+---
+
+# wiki-architecture
+
+Author or update one doc in `wiki/architecture/`.
+
+## When this, not wiki-feature
+
+Use `wiki-architecture` for a pattern/layer many features depend on (the Axios
+clients, the RHF+Zod convention, the modal context, role gating). Use
+`wiki-feature` for a single user-facing flow. If unsure: does removing one
+feature make this doc pointless? If no, it's architecture.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md` and `wiki/index.md`. Follow the same anatomy and
+   frontmatter as feature dossiers (TL;DR is mandatory; the rest as fits).
+2. Read the real code first. Cite `path/to/file.ts:line-line`; summarize, don't
+   dump code.
+3. Create/update `wiki/architecture/<kebab-name>.md`, integrating into existing
+   text rather than appending.
+4. Architecture docs are wikilink hubs: features link _up_ to them. Make sure the
+   features that consume this pattern link to it, and add it under
+   `## Architecture` in the index.
+5. Frontmatter status: `draft` from a snapshot read, `stable` once verified.
+
+Report files touched and new index/cross-links added.

package/.opencode/skills/wiki-bootstrap/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: wiki-bootstrap
+description: >-
+  Set up the knowledge wiki in a repo that doesn't have one yet (or repair an
+  incomplete one). Use when the user says "set up the wiki", "bootstrap the
+  wiki", "init the knowledge base", or drops this template into a new project.
+  Detects project maturity, picks SDD vs wiki-only mode, writes wiki/CONFIG.md,
+  and scaffolds the MVP. Run this ONCE per repo.
+---
+
+# wiki-bootstrap
+
+The portable entry point. Makes this skill set work in any repo by writing a
+project-specific `wiki/CONFIG.md` that all other skills read.
+
+## 1. If a wiki already exists
+
+If `wiki/CONFIG.md` exists, this repo is already bootstrapped — don't re-scaffold.
+Read it, report the mode, and point the user at the relevant skills. If `wiki/`
+exists but `CONFIG.md` is missing, only create the config (infer from existing
+pages); don't touch existing dossiers.
+
+## 2. Decide the mode (the core decision)
+
+Inspect the repo and pick `sdd` or `wiki-only`. Signals:
+
+- **Lean `sdd`** when the repo is greenfield: few commits, little/no `src`, no
+  established features, mostly scaffolding. Here the wiki can lead the code.
+- **Lean `wiki-only`** when the repo is mature: deep `git log`, substantial code,
+  many shipped features, existing tests. Here the wiki documents what exists.
+- **Ambiguous** (some code, early stage): present both with a one-line rationale
+  and let the user choose. Don't guess silently.
+
+Gather signals with: `git log --oneline | wc -l`, a glance at the source tree,
+presence of tests, and the README. State the signals you used in your recommendation.
+
+## 3. Write wiki/CONFIG.md
+
+Fill it from the repo: `mode`, `project`, `stack` (from package manifest /
+README), `roles` (if the app is role-gated — else omit), and `sensitive_paths`
+(the dirs whose churn invalidates docs: data layer, auth, shared contexts/state,
+public API surface). Use the shape in `${TEMPLATE_ROOT}/wiki/CONFIG.template.md`.
+
+## 4. Scaffold the MVP (only what's missing)
+
+- `wiki/SCHEMA.md` — conventions (page anatomy, frontmatter, wikilink rules,
+  citations). If absent, copy `${TEMPLATE_ROOT}/wiki/SCHEMA.md` into the
+  project. Add the SDD statuses (`spec`, `building`) to the lifecycle section
+  only when `mode: sdd`.
+- `wiki/index.md` — the map. Include a "Tooling" section listing the curator and
+  the skills available **for the chosen mode**, plus a one-line pointer:
+  "engineering conventions → `.opencode/conventions/project.md`".
+- `wiki/features/` — empty dir for dossiers.
+- `wiki/architecture/` — **seed by default** from a snapshot read of the code
+  (meaningful on mature `wiki-only` repos). Identify the cross-cutting topics
+  the repo *actually has* and create one file per topic by delegating to
+  `wiki-architecture` — never one mega-file. e.g. `data-fetching.md`,
+  `services.md`, `state-management.md`, `auth.md`, `routing.md`,
+  `error-handling.md`; only those present. Pages are `status: draft`. In
+  greenfield `sdd`, skip — there is nothing to analyze.
+- `wiki/gotchas/` — seed **only** for traps backed by concrete code evidence,
+  by delegating to `wiki-gotcha`. No speculation. If none surface, do not create
+  the folder. No empty stubs.
+- Do **not** create product/QA/ADR folders — those are born on demand by their
+  skills (`wiki-adr`, `wiki-meeting`, `wiki-test-plan`).
+
+## 5. Infer conventions → project conventions for opencode
+
+With CONFIG written (its `sensitive_paths` scope this step), look for
+**repeated** conventions — how something is consistently done across the repo —
+within those sensitive paths plus obvious cross-cutting patterns. A one-off
+defect is not a convention; only a consistent pattern earns a rule. Do **not**
+sweep the whole repo.
+
+Triage each detected convention with a software-architect lens (boundaries,
+coupling/cohesion, error handling, validation at trust boundaries, layering),
+tech-agnostic:
+
+- **Good / neutral** → candidate rule, as-is.
+- **Bad but consistent** (an anti-pattern that has become "the way it's done
+  here") → do not codify it. Propose the *better* convention instead, shown as
+  **current → recommended** with the reason.
+
+Present the full batch **before writing anything**. For each candidate show: the
+path glob, the convention, its classification, and — for flagged ones — the
+current → recommended directive and why. The user approves / edits / drops per
+item. **Never write an unapproved convention** — neither good nor improved ones.
+
+Write approved conventions to `.opencode/conventions/project.md` — opencode
+consults files listed in `instructions` on every task, so this file becomes
+ambient guidance the agent follows automatically:
+
+```
+# Project Conventions
+
+## <convention title>
+- <the directive — actionable, imperative>
+```
+
+Also detect the stack from step 3 (`stack` field in CONFIG) and include
+relevant **tech-stack conventions** in the same file. For common stacks:
+
+- `typescript`, `ts` → TypeScript best practices
+- `react`, `next`, `remix` → React patterns
+- `node`, `express`, `fastify` → Node.js patterns
+- `python`, `django`, `flask` → Python patterns
+- `rust`, `axum` → Rust patterns
+
+If the stack is ambiguous or unknown, skip the tech conventions — don't guess.
+
+Greenfield `sdd` repos have little code to analyze — skip the project-specific
+convention inference rather than invent. Tech-stack conventions can still be
+included if the stack is clear.
+
+Then add the conventions file to `instructions` in `${PROJECT}/opencode.json`:
+
+```json
+"instructions": [".opencode/conventions/project.md"]
+```
+
+If `instructions` already exists, append to it rather than replacing.
+
+This is the only artifact `wiki-bootstrap` writes outside `wiki/`.
+
+## 6. The drift reminder (already active)
+
+The drift plugin (`${TEMPLATE_ROOT}/.opencode/plugin/wiki-drift.ts`) monitors
+sensitive paths after edits and nudges to run `wiki-ingest`. It is enabled by
+adding the plugin to `opencode.json`:
+
+```json
+"plugin": ["${TEMPLATE_ROOT}/.opencode/plugin/wiki-drift.ts"]
+```
+
+Or it will auto-load from `.opencode/plugin/`. The plugin reads globs from
+`wiki/CONFIG.md`'s `## Sensitive paths` block, so once you write CONFIG
+in step 3 it targets the right paths. Tell the user: to change what triggers it,
+edit that block — no code change.
+
+## 7. Hand off by mode
+
+First, summarize what was produced this run: the architecture topics seeded, any
+gotchas captured, and the conventions the user approved into `.opencode/conventions/project.md`.
+
+- **`wiki-only`** → offer to seed the top 3–5 features as `draft` dossiers via
+  `wiki-feature` (read code, document what exists). Don't auto-run; confirm first.
+- **`sdd`** → explain the loop: `wiki-spec` (write the spec, `status: spec`) →
+  implement with TDD → `wiki-test-plan` (tests from acceptance criteria) →
+  `wiki-verify` (promote to `stable`). Offer to write the first spec.
+
+End by listing every available skill with its trigger phrase, and remind the user
+the kb-curator keeps it honest after changes to the configured sensitive paths.

package/.opencode/skills/wiki-feature/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: wiki-feature
+description: >-
+  Create or update a feature/flow dossier in wiki/features/. Use when the user
+  says "document feature X", "write a dossier for X", "update the X dossier", or
+  after building/changing a user-facing flow. Produces a dossier in the exact
+  anatomy defined in wiki/SCHEMA.md.
+---
+
+# wiki-feature
+
+Author or update one dossier in `wiki/features/`.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md` (page anatomy + frontmatter + wikilink rules) and
+   `wiki/index.md`. Match them exactly — do not invent a different structure.
+2. If the dossier exists, **update in place** (integrate, don't append). If new,
+   create `wiki/features/<kebab-name>.md`.
+3. Read the real code before writing. Cite with `path/to/file.ts:42-58`; quote
+   1–3 lines max, then summarize. Never paste large blocks or file trees.
+4. Use the page anatomy from SCHEMA: `# Title`, then `## TL;DR`,
+   `## Origin & links`, `## Concepts`, `## Flows`, `## Business rules`
+   (each rule + **Why:** + cite), `## Key files`, `## Gotchas`, `## Changelog`.
+   Omit empty sections — no stubs.
+5. Frontmatter: `name, status, created, last_review, owner, tags`. New dossiers
+   written from a snapshot read start as `status: draft`.
+6. Wikilinks: 5–10 per dossier, only when causality / hierarchy / cross-reference
+   holds (see SCHEMA). Link from neighboring dossiers too, and add an entry under
+   the right section of `wiki/index.md`.
+7. One concept per file. If the "feature" has 2+ independent flows, split them.
+
+Report which files you created/edited and which index entries you added.

package/.opencode/skills/wiki-gotcha/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: wiki-gotcha
+description: >-
+  Document a known trap, fragile area, or surprising behavior. Use when the user
+  says "document this gotcha", "this breaks when…", "remember this footgun". If
+  the trap belongs to one feature, it goes in that dossier's Gotchas section; if
+  it spans features, it becomes a standalone page in wiki/gotchas/.
+---
+
+# wiki-gotcha
+
+Capture a footgun so the next person doesn't step on it.
+
+## Decide where it lives
+
+- **Single feature** → integrate into that dossier's `## Gotchas` section (the
+  default home per SCHEMA). Don't create a new page.
+- **Cross-cutting** (affects 2+ features or an architecture pattern) → create
+  `wiki/gotchas/<slug>.md` (create the folder + a `## Gotchas` index section on
+  first use) and cross-link the affected dossiers.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md` and `wiki/index.md`.
+2. Write the gotcha as: **what surprises you**, **why it happens** (cite
+   `path:line-line`), and **what to do instead / how to avoid it**. One tight
+   entry — not an essay.
+3. Cross-reference the feature(s) or architecture page it affects
+   (cross-reference relation). If it came from a real bug, note the symptom so a
+   future reader recognizes it.
+4. If it stems from a deliberate trade-off, suggest `wiki-adr` to record the why.
+
+Report where you put it and what you linked.

package/.opencode/skills/wiki-ingest/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: wiki-ingest
+description: >-
+  Integrate a source (a PR, a changed file, a code path, a diff) into the wiki by
+  updating the pages whose claims it affects. Use when the user says "ingest this
+  PR/file into the wiki", "the wiki is stale after this change", or after merging
+  work that touches documented behavior. Integrates in place — never appends.
+---
+
+# wiki-ingest
+
+Fold a source into the wiki without rewriting the whole thing.
+
+## Procedure
+
+1. Read `wiki/CONFIG.md` (sensitive paths + their page mapping), then
+   `wiki/SCHEMA.md` and `wiki/index.md`.
+2. Identify the source: a PR (`gh pr view`/diff), a changed file, or a path. Read
+   the actual change.
+3. Find the page(s) that own the affected claims — grep the wiki for the symbols,
+   files, or routes involved. Use the `## Sensitive paths` mapping in CONFIG to
+   jump straight to the dossiers a changed path feeds.
+4. **Update in place.** Integrate the new reality into existing sentences; never
+   leave "UPDATE 2026-…" stubs. Fix citations to the new line ranges.
+5. Bump `last_review`. Set `status: stable` only if you verified the full page,
+   else `needs-review`. Add a one-line `## Changelog` entry.
+6. Create a new page only if a genuinely new concept emerged — then link it from
+   neighbors and the index. Don't spawn a page for an incremental change to an
+   existing flow.
+
+Report: pages updated, claims that changed, anything left `needs-review`.

package/.opencode/skills/wiki-lint/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: wiki-lint
+description: >-
+  Health-check the wiki for rot. Use when the user says "lint the wiki", "check
+  the wiki for dead links", "is the wiki stale?", or periodically after a batch
+  of changes. Reports orphans, dead links, stale claims, and contradictions;
+  proposes fixes without deleting pages unapproved.
+---
+
+# wiki-lint
+
+Find rot. Don't fix silently; report then propose.
+
+## Checks
+
+1. **Orphans** — pages with no inbound `[[wikilinks]]` and not listed in
+   `wiki/index.md`. Either link them in or flag for deletion.
+2. **Dead links** — `[[wikilinks]]` pointing at non-existent pages/sections.
+   Grep every `[[...]]` and resolve each target against the files in `wiki/`.
+3. **Stale claims** — for each page, spot-check its code citations
+   (`path:line-line`) against the current file. If the cited lines no longer
+   match the claim, mark the page `needs-review`.
+4. **Contradictions** — the same rule stated differently on two pages (common
+   between a feature dossier and its architecture doc). Pick the correct one,
+   reconcile.
+5. **SCHEMA violations** — missing frontmatter, stub sections, raw paths instead
+   of wikilinks, wikilink density <3 or >15, code dumps that should be citations.
+
+## Output
+
+A prioritized report: file → issue → proposed fix. Apply only the safe
+mechanical fixes (dead-link retargeting, status flips, index entries) directly;
+list anything destructive (page deletion, large rewrites) for approval first.

package/.opencode/skills/wiki-meeting/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: wiki-meeting
+description: >-
+  Turn meeting/client notes into a decision record. Use when the user pastes
+  meeting notes, says "log this meeting", or "capture what we agreed with the
+  client". Extracts decisions + action items and links downstream to the ADRs and
+  features they caused. Creates wiki/product/client-meetings/ on first use.
+---
+
+# wiki-meeting
+
+Distill a meeting into decisions and follow-ups — not a transcript.
+
+## First-use note
+
+The wiki is dev-only by default; this skill adds `wiki/product/client-meetings/`
+and a `## Product` (or `## Meetings`) section to `wiki/index.md`. Do this on first
+invocation.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md` and `wiki/index.md`.
+2. From the notes, extract only what has durable value: **decisions made**,
+   **open questions**, **action items** (owner + what). Drop chit-chat, scheduling,
+   and anything ephemeral.
+3. Create `wiki/product/client-meetings/YYYY-MM-DD-<topic>.md` with frontmatter
+   `name, date, attendees, tags`.
+4. Body: `## Decisions`, `## Open questions`, `## Action items`. Keep it terse.
+5. Wikilink downstream (causality: meeting → ADR / feature it produced). If a
+   decision here warrants an ADR, suggest running `wiki-adr`. If it changes a
+   documented flow, suggest `wiki-ingest` on the affected dossier.
+6. Never store PII beyond first names/roles, and no credentials.
+
+Report the note created and the downstream links/suggestions.

package/.opencode/skills/wiki-prd/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: wiki-prd
+description: >-
+  Write a Product Requirements Document. Use when a PM says "add a PRD", "write
+  the PRD for X", "document what the client wants for X", or wants to capture the
+  what/why of a product initiative before any technical decisions. Creates
+  wiki/product/ on first use. PRDs sit upstream of ADRs and features.
+---
+
+# wiki-prd
+
+Capture the product intent — the *what* and *why*, not the *how*. A PRD is the
+upstream source the ADRs and feature dossiers derive from.
+
+## First-use note
+
+The wiki is dev-only by default; this skill is the trigger to add `wiki/product/`
+and a `## Product` section to `wiki/index.md`. Update SCHEMA's "what does NOT
+belong here" line if it still excludes product docs.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md` and `wiki/index.md`. If a client source exists (PDF,
+   transcript, email), read it first — don't invent requirements.
+2. Create `wiki/product/<kebab-name>.md` with frontmatter
+   `name, status: draft | approved, created, last_review, owner, tags`.
+3. Body — standard PRD shape (omit a section only if genuinely empty, no stubs):
+   - `## Problem` — the user/business pain, with the "why now".
+   - `## Goals` — outcomes this must achieve (and `## Non-goals`).
+   - `## Users` — personas / who this is for.
+   - `## User stories` — "As a X, I want Y, so that Z".
+   - `## Success metrics` — observable, measurable.
+   - `## Scope` / `## Out of scope`.
+   - `## Open questions` — unresolved with the client.
+4. Wikilink downstream (causality: PRD → the ADRs and features it spawns). Note
+   that ADRs capture the technical decisions and feature dossiers the dev-facing
+   detail — suggest `wiki-adr` / `wiki-feature` / `wiki-spec` for those.
+5. Keep it product-level. No implementation detail, no code citations — that's
+   what the downstream pages are for. Status `draft` until the client/stakeholders
+   sign off, then `approved`.
+
+Report the PRD created and the downstream links/suggestions.

package/.opencode/skills/wiki-query/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: wiki-query
+description: >-
+  Answer a question about how the codebase works by reading the wiki first. Use
+  when the user asks "how does X work?", "where is X handled?", "what are the
+  rules for X?" and the answer likely lives in a dossier. Cites pages with
+  [[wikilinks]] and flags gaps instead of guessing.
+---
+
+# wiki-query
+
+Answer from the wiki before touching code.
+
+## Procedure
+
+1. Read `wiki/index.md` to locate the relevant page(s); read those pages.
+2. Answer from them. Cite the pages you used as `[[wikilinks]]` and quote the
+   specific claim/citation that supports your answer.
+3. If the wiki only partially answers, say which part is covered and which isn't,
+   then read the cited code path to fill the gap.
+4. If the wiki has **no** page for it, say so explicitly, answer from the code,
+   and suggest running `wiki-feature`/`wiki-architecture` to capture it.
+5. Never invent behavior. A wiki claim that contradicts the current code is a
+   lint finding — note it and offer to fix it with `wiki-ingest`.
+
+Keep the answer tight. The wiki exists so you don't re-derive context — lead with
+its conclusion, cite, done.

package/.opencode/skills/wiki-spec/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: wiki-spec
+description: >-
+  Spec-first authoring for SDD projects — write a feature's dossier as a SPEC
+  before the code exists, with testable acceptance criteria that drive the
+  implementation. Use when the user says "spec out feature X", "write the spec
+  for X", or starts new work in an sdd-mode project. Only active when
+  wiki/CONFIG.md mode is sdd.
+---
+
+# wiki-spec
+
+Write the contract before the code. The dossier leads; implementation follows it.
+
+## Mode gate
+
+Read `wiki/CONFIG.md` first. If `mode` is **not** `sdd`, stop and tell the user
+this project is `wiki-only` (mature codebase — document what exists with
+`wiki-feature` instead). Offer to switch the mode if they really want SDD, but
+don't proceed silently.
+
+## Procedure
+
+1. Read `wiki/CONFIG.md`, `wiki/SCHEMA.md`, `wiki/index.md`. Follow SCHEMA's
+   "Traceability" and "sdd-mode specs carry three extra sections" exactly.
+2. Create `wiki/features/<kebab-name>.md` with `status: spec`. The dossier slug
+   is the **feature id** used in every AC id (e.g. `checkout-S2-AC1`).
+3. Body, spec-flavored and **traceable**:
+   - `## TL;DR` (intent + why), `## Concepts`.
+   - `## Current state & evidence` — for new work, "not built"; if some code
+     exists, cite it and name the gap. Don't write code cites you can't back up.
+   - `## Acceptance criteria` — break into **Stories** `<slug>-S1`, `-S2`… (each
+     "As a X, I want Y, so that Z"), and under each, **ACs** `<slug>-S1-AC1`…
+     each one observable/testable (Given/When/Then or EARS). Mark beta-critical
+     stories. This is the heart — vague AC = vague code, so ask if ambiguous.
+   - `## Test plan` — the table from SCHEMA: one row per AC (`AC | layer | test
+     location | status ☐`). Status starts unchecked; `wiki-verify` fills it.
+   - `## Business rules` (rule + **Why:**), `## Flows` (intended UI→state→API),
+     `## Out of scope`.
+4. Wikilink to the architecture patterns the work will touch and any upstream
+   PRD/ADR/meeting that motivated it (causality).
+5. If tickets are tracked (Jira/Azure per CONFIG), the IDs are the contract:
+   Epic = this feature, Story = each `-Sx`, ACs in the Story. Note that for the
+   user so the ticket and spec don't drift.
+
+Hand off: tell the user the spec is ready to implement (TDD against the ACs by
+id), then `wiki-test-plan`, then `wiki-verify` (reads the Test plan table) to
+promote it to `stable`. Add the dossier to `wiki/index.md` under its section.

package/.opencode/skills/wiki-test-plan/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: wiki-test-plan
+description: >-
+  Write a QA test plan for a feature. Use when the user says "write a test plan
+  for X", "what should QA check for X", or wants observable acceptance criteria
+  turned into test cases. Links up to the feature dossier. Creates wiki/qa/test-plans/
+  on first use.
+---
+
+# wiki-test-plan
+
+Turn a feature's behavior into testable, observable cases.
+
+## First-use note
+
+The wiki ships without a QA folder; this skill adds `wiki/qa/test-plans/` and a
+`## QA` section to `wiki/index.md` on first invocation.
+
+## Procedure
+
+1. Read `wiki/SCHEMA.md`, `wiki/index.md`, and the feature's dossier in
+   `wiki/features/` — the test plan derives from its Flows and Business rules.
+   If no dossier exists, suggest `wiki-feature` first.
+2. Create `wiki/qa/test-plans/<feature-slug>.md` with frontmatter
+   `name, status, created, last_review, owner, tags, feature: <dossier-slug>`.
+3. Body: `## Scope`, `## Preconditions` (roles/data needed — use the `roles`
+   declared in `wiki/CONFIG.md` if the app is role-gated),
+   `## Cases` (each: given → when → then, observable), `## Edge cases & negatives`.
+4. Derive cases from the dossier's business rules — each rule should map to at
+   least one positive and one negative case.
+5. Wikilink up to the feature (hierarchy: feature → test plan) and add the
+   reverse link from the dossier.
+
+Report the plan created and the dossier link added.

package/.opencode/skills/wiki-verify/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: wiki-verify
+description: >-
+  The SDD verification gate — check that the shipped code and tests actually
+  satisfy each acceptance criterion in a feature's spec, fill in the code
+  citations, and promote the dossier from spec/building to stable. Use when the
+  user says "verify feature X against its spec", "did we build X to spec?", or
+  after implementing an sdd-mode feature. Only active when wiki/CONFIG.md mode is sdd.
+---
+
+# wiki-verify
+
+Close the SDD loop: prove the code matches the spec, then promote the dossier.
+
+## Mode gate
+
+Read `wiki/CONFIG.md`. If `mode` is not `sdd`, stop — in `wiki-only` projects
+verification of existing behavior is just a normal `wiki-feature`/`wiki-ingest`
+update, not a spec-vs-code gate.
+
+## Procedure
+
+1. Read the feature dossier (must have `## Acceptance criteria` with AC ids and a
+   `## Test plan` table from `wiki-spec`). If it has none, it wasn't spec'd — say so.
+2. For **each AC id** (`<slug>-Sx-ACy`), locate the implementing code and the test
+   that covers it. Run the test suite (`npm test` / project equivalent) and
+   confirm it passes. Cite the real code as `path:line-line`.
+3. Update the `## Test plan` table in place: tick `☐ → ☑` per AC, filling its
+   test location. Be adversarial — an AC with no test or no code path is **not**
+   met, leave it unchecked.
+4. If every AC is checked: fill the dossier's `## Key files` with the citations,
+   flip `status: spec`/`building` → `stable`, bump `last_review`, add a
+   `## Changelog` line. If gaps remain: leave `status: building`, list the unmet
+   AC ids as the remaining work, and do **not** promote.
+5. Never mark `stable` on assertion alone — evidence (passing tests + matching
+   code) only.
+
+Report the verdict table and the status decision.

package/README.md

@@ -0,0 +1,83 @@
+# Knowledge Wiki Template for opencode
+
+> A drop-in, **skill-based** knowledge base for any codebase. Stop re-explaining
+> "how feature X works" on every task — capture it once, link it, and let it compound.
+
+---
+
+## Install
+
+Copy this template into your project root, then reference the skills in your
+`opencode.json`:
+
+```json
+{
+  "skills": {
+    "paths": [".opencode/skills", "/path/to/wiki-template/.opencode/skills"]
+  },
+  "agent": {
+    "kb-curator": { "path": "./path/to/wiki-template/.opencode/agents/kb-curator.md" },
+    "wiki-qa": { "path": "./path/to/wiki-template/.opencode/agents/wiki-qa.md" }
+  },
+  "plugin": [
+    "/path/to/wiki-template/.opencode/plugin/wiki-drift.ts"
+  ]
+}
+```
+
+Or symlink the `.opencode/` folder into each repo.
+
+Then run once:
+
+```
+/wiki-bootstrap
+```
+
+---
+
+## Skills
+
+| Skill | Use it to… |
+|---|---|
+| `wiki-bootstrap` | set up / repair the wiki |
+| `wiki-feature` | document a feature or UI flow |
+| `wiki-architecture` | document a cross-feature pattern |
+| `wiki-ingest` | fold a PR / file / diff into the pages it affects |
+| `wiki-query` | answer "how does X work?" from the wiki |
+| `wiki-lint` | find orphans, dead links, stale claims |
+| `wiki-prd` | write a Product Requirements Doc |
+| `wiki-adr` | record an Architecture Decision Record |
+| `wiki-meeting` | turn meeting notes into decisions + action items |
+| `wiki-test-plan` | derive a QA test plan from a feature |
+| `wiki-gotcha` | capture a footgun / fragile area |
+| `wiki-spec` *(sdd)* | write a feature's spec **before** the code |
+| `wiki-verify` *(sdd)* | prove the code matches the spec |
+
+## Agents
+
+- **`kb-curator`** — maintains the wiki: ingest/query/lint + drift after changes.
+- **`wiki-qa`** — exploratory QA. Drives the running app and reports the gap
+  between what it sees and the acceptance criteria.
+
+## Two modes
+
+| | `wiki-only` | `sdd` |
+|---|---|---|
+| **For** | mature codebases | greenfield / brand-new features |
+| **Dossier is** | documentation of what exists | the spec, written first |
+| **Extra statuses** | — | `spec`, `building` |
+
+---
+
+## The drift plugin
+
+`wiki-drift.ts` runs after every `Edit`/`Write`/`MultiEdit`. If the edited file
+matches a `Sensitive paths` glob in `wiki/CONFIG.md`, it injects a nudge to run
+`wiki-ingest`. Zero noise on non-matches.
+
+---
+
+## License
+
+MIT — adapt freely.# wiki-template
+# wiki-template

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@tarruk/wiki-template",
+  "version": "1.0.0",
+  "description": "Skill-based knowledge wiki for opencode — bootstrap, feature/ADR/architecture/gotcha dossiers, ingest/query/lint, SDD spec+verify, plus kb-curator and wiki-qa agents.",
+  "main": ".opencode/",
+  "files": [
+    ".opencode/",
+    "wiki/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tarruka/wiki-template"
+  },
+  "keywords": [
+    "opencode",
+    "wiki",
+    "knowledge-base",
+    "sdd",
+    "documentation"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/wiki/CONFIG.template.md

@@ -0,0 +1,67 @@
+---
+name: config
+description: Per-project knobs the wiki skills read. The one file to edit when dropping this template into a new repo.
+---
+
+# Wiki config
+
+Single source of project-specifics. Every wiki skill and the `kb-curator` agent
+read this file instead of hardcoding values, so the skills stay portable.
+`wiki-bootstrap` writes this on first run; edit by hand anytime. Rename to
+`CONFIG.md` (drop `.template`) in a real project.
+
+## Mode
+
+```
+mode: <wiki-only | sdd>
+```
+
+- `sdd` — spec-driven. New/greenfield projects. Dossiers are written **before**
+  the code (`status: spec`), drive implementation + tests, promoted to `stable`
+  by `wiki-verify`. Skills `wiki-spec` and `wiki-verify` are active.
+- `wiki-only` — descriptive. Mature projects with most of the surface built.
+  Dossiers document **what exists** (`draft` → verified `stable`). Spec-first
+  skills stay dormant.
+
+## Project
+
+```
+project: <name>
+stack:   <main frameworks/libraries, and the backend if separate>
+roles:   <auth roles, if the app is role-gated — else omit this line>
+```
+
+## Sensitive paths
+
+Changes here most often invalidate the wiki. `kb-curator` / `wiki-ingest` scope
+drift checks to the dossiers these paths feed. The drift plugin reads the
+globs in this block — `path/glob → owning page(s)`.
+
+```
+<src/services/**>          → <architecture/data-layer + consuming dossiers>
+<src/auth/**>              → <architecture/auth>
+<src/api/**>               → <the relevant architecture doc>
+```
+
+## Status lifecycle
+
+- `wiki-only` mode: `draft` → `stable` → `needs-review`.
+- `sdd` mode adds, before the above: `spec` → `building` → `stable`.
+
+## QA (optional — only if you use the wiki-qa agent)
+
+How the `wiki-qa` agent reaches a running app. Omit this block if you don't use it.
+
+```
+platform: <web | react-native | ios | android>
+driver:   <playwright | maestro | detox | xcuitest | none>   # none → manual checklist
+app_url:  <e.g. http://localhost:3000>   (web)
+start:    <e.g. npm run dev>
+auth:     <how to get a test session — a seed command, or "log in with an existing account">
+```
+
+The `driver` is **platform-specific** — web uses Playwright, React Native uses
+Maestro/Detox, iOS/Swift uses XCUITest/Maestro. The matching MCP server must be
+configured + approved. With `driver: none`, `wiki-qa` produces a **manual QA
+checklist** from the ACs instead of an executed run. It's read-only either way —
+its only writes are the seed and in-app actions.

package/wiki/SCHEMA.md

@@ -0,0 +1,163 @@
+---
+name: schema
+description: Conventions for this wiki. Format, frontmatter, wikilinks, citations.
+---
+
+# Wiki Schema
+
+Project-specifics (mode, stack, roles, sensitive paths) live in [[CONFIG]].
+This file only defines **how pages are written**.
+
+## File layout
+
+```
+wiki/
+  index.md              # entry point, the map
+  SCHEMA.md             # this file
+  CONFIG.md             # per-project knobs (mode, stack, roles, sensitive paths)
+  architecture/         # cross-feature technical docs
+  features/             # one .md per feature/flow
+```
+
+Folders for `decisions/`, `product/`, `qa/` are **not** created up front — they
+are born on demand the first time their skill runs. `architecture/` and
+`gotchas/` may be **seeded at bootstrap** from a snapshot read (as `draft`);
+absent that, they too are on-demand.
+
+## File naming
+
+- `kebab-case.md`
+- One concept per file. If a "feature" contains 2+ independent flows, split them.
+
+## Frontmatter
+
+```yaml
+---
+name: short-slug
+status: draft | stable | needs-review
+created: 2026-01-01
+last_review: 2026-01-01
+owner: you
+tags: [domain, area]
+---
+```
+
+`status` rules of thumb (active set depends on `mode` in [[CONFIG]]):
+
+- `draft` — written from a snapshot read of the code, not yet validated.
+- `stable` — last_review aligns with code; can be trusted.
+- `needs-review` — a recent code change is suspected to have invalidated parts.
+- `spec`, `building` — **sdd mode only.** `spec` = written before the code;
+  `building` = code in progress, unverified. Promoted to `stable` by `wiki-verify`.
+
+## Page anatomy (feature dossier)
+
+```
+# Title
+
+## TL;DR
+One paragraph. What this does and the single most important rule to remember.
+
+## Origin & links
+Wikilinks out: [[other-feature]], [[architecture/x]]. Skip if isolated.
+
+## Concepts
+Domain vocabulary used below. Define before using.
+
+## Acceptance criteria      (sdd mode: the contract; wiki-only: optional)
+Observable, testable. Given / When / Then or EARS. See "Traceability" below.
+
+## Flows
+Step-by-step. UI step → state change → API call → response handling.
+
+## Business rules
+Each line: the rule + **Why:** the reason + cite.
+
+## Key files
+`path/to/file.ts:42-58` — what this file owns.
+
+## Gotchas
+Things that surprised the author or violate the path of least surprise.
+
+## Changelog
+- 2026-01-01 — initial draft.
+```
+
+## Traceability (the spine of sdd mode)
+
+Every acceptance criterion gets a **stable ID** so it can be traced to a test, a
+ticket, and the code that satisfies it. The unit hierarchy:
+
+```
+<feature-slug>            the dossier — one feature
+<feature-slug>-S1         a Story: a testable slice you'd assign/estimate
+<feature-slug>-S1-AC2     an Acceptance Criterion: one Given/When/Then
+```
+
+e.g. `checkout-S2-AC1`. Rules:
+
+- An AC is **Done** only when it has a **passing test** (and, in sdd, matching code).
+- Each AC maps to ≥1 automated test; the test's name references the AC id.
+- Tickets (Jira/Azure) mirror the same IDs: Epic = feature, Story = `-Sx`, the
+  ACs live in the Story. Keep spec text and ticket text in sync.
+- IDs are immutable once assigned — renumber by adding, not reshuffling.
+
+## sdd-mode specs carry three extra sections
+
+On top of the anatomy above, a `status: spec` dossier adds:
+
+```
+## Current state & evidence
+What exists today, with code cites — or "nothing yet". This is what makes the
+spec verifiable instead of aspirational. (For a brand-new feature: "not built".)
+
+## Acceptance criteria
+### <feature>-S1 — <story title>  [beta-critical?]
+As a <role>, I want <capability>, so that <outcome>.
+- <feature>-S1-AC1 — Given <state>, when <action>, then <observable result>.
+
+## Test plan
+| AC | Layer (unit/integration/e2e) | Test location | Status |
+|----|------------------------------|---------------|:------:|
+| <feature>-S1-AC1 | unit | `path/to/test` | ☐ |
+```
+
+`wiki-verify` reads this Test plan table to gate promotion to `stable`.
+
+Sections may be omitted if empty. Don't write stubs.
+
+## Wikilinks — when to use them
+
+Only when one of these holds:
+
+1. **Causality** — A produced B (meeting → ADR → feature, bug → gotcha).
+2. **Hierarchy** — A contains B (milestone → features, feature → test plan).
+3. **Cross-reference** — same thing from a different angle (feature ↔ architecture).
+
+Do **not** link because two pages share a keyword, "might be interesting", or
+"just in case". Rule of thumb: if removing the link leaves the page
+understandable, it wasn't necessary.
+
+Density target per dossier: 5–10 wikilinks. <3 = isolated, >15 = noise.
+
+Syntax: `[[page-name]]` or `[[page-name#section]]`. Never raw paths.
+
+## Code citations
+
+- `path/to/file.ts:42-58` — preferred. Path + line range.
+- Don't paste large code blocks; quote 1–3 lines + cite, then summarize.
+- Cite once where the claim is made.
+
+## What does NOT belong here
+
+- Code/file-trees you can read by opening the file or running `ls`.
+- Commit history or PR summaries — that's `git log`'s job.
+- Standups, sprint state, ticket counts, roadmap.
+- Secrets, credentials, tokens, env values.
+- Generic framework knowledge ("what is React").
+
+## Updating
+
+When code drifts from a page: find the page that owns the claim, **integrate**
+the fix in place (don't append "UPDATE 2026-…"), bump `last_review`, flip
+`status`. Delete pages that are no longer needed and remove their index entry.