Document Forgejo/tea issue workflow

Add docs/issue-workflow.md covering token setup, listing, implementing, and
closing issues via tea on the self-hosted Forgejo tracker, plus a pointer
from CLAUDE.md. Captures the tea token-scope and --user gotchas discovered
while implementing SB Content Plan Phase 1.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

CLAUDE.md

@@ -71,17 +71,19 @@ to those two and fix the stale doc.
 
 **Implementation status (2026-06-17):** `memory-project` skill now uses assessment-first onboarding: surveys the repo structure, classifies exclude candidates by TYPE (11 categories: fetched deps, build output, caches, VCS internals, editor/AI-tooling dirs, lockfiles, coverage/logs, bulk data, binaries, secrets, graphify-out/ — illustrative names, not fixed templates), generates a per-project `.graphifyignore`, confirms with the user, then extracts the graph using `qwen25-coder-7b-16k` (config.yaml `ollama_model`; 16k-context build of qwen2.5-coder:7b — larger context window cuts chunk count per doc, the main speed lever). Fixes issue where repos with large dependency trees routed non-code files through the Ollama doc pass (see ADR-017).
 
+**Implementation status (2026-06-30):** Phase 1 of the SecondBrain Content Plan complete (`docs/memory-system/09-sb-content-plan.md`, issues #1–#6). `~/Documents/SecondBrain/vault-conventions.md` reconciled to a single authoritative typed frontmatter schema (removed the contradictory block; canonical filenames are slug-only, `source:` is a frontmatter field not a tag, `scope` is a field not a tag). New `memory-template` skill added (`cc-os/plugins/memory/skills/memory-template/SKILL.md`) — routes between template-design (4-step process + injection-economics filter) and new-type creation (9-step lifecycle). Three vault note templates created in `~/Documents/SecondBrain/_templates/` (`howto.md`, `convention.md`, `reference.md`; `reference` carries a four-subtype variant selector — pattern/framework, api-integration, role-definitions, design-rules), each dogfooded against a real note. Four proof-of-concept vault notes patched (cookbook subtype → pattern/framework, glossary de-duped to a wikilink, design-mode scope → project, tags + `last_reviewed` added). Phase 2 (issue #7) remains open as the steady-state migration/onboarding epic (no code). See `docs/memory-system/09-sb-content-plan.md`.
+
 ## Implemented Components
 
 **Global memory plugin** — `cc-os/plugins/memory/` (git-tracked, 2026-06-12); symlinked into `~/.claude/plugins/memory`
 - Hooks: `hooks/` — `session_start.py`, `session_context.py` (project graph path only), `post_tool_use_write.py`, `session_end.py` (vault journal), `memsearch_sync.py` (second SessionEnd hook; memsearch auto-commit+push, 30s timeout), `vault_sync.py` (third SessionEnd hook; vault auto-commit+push to forgejo.swansoncloud.com/jared/SecondBrain, 30s timeout; mirrors memsearch_sync.py)
 - Shared modules: `config.py` (load_config → frozen Config dataclass), `hook_io.py` (read_input → HookInput dataclass), `session_state.py` (record_touch/read_touches; encapsulates `/tmp/claude-vault-touched-$SESSION_ID` contract)
-- Skills: `skills/` — memory-vault, memory-write, memory-reorganize, memory-project (assessment-first onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project `.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per ADR-017)
+- Skills: `skills/` — memory-vault, memory-write, memory-reorganize, memory-project (assessment-first onboarding: surveys repo, classifies excludes by type (11 categories), writes per-project `.graphifyignore`, confirms with user, then extracts using `qwen25-coder-7b-16k` — per ADR-017), memory-template (routes template-design ↔ new-type-creation: 4-step template-design process + injection-economics filter, 9-step new-type lifecycle; backs Phase 1 of the SB Content Plan — see `docs/memory-system/09-sb-content-plan.md`)
 - Config: `config.yaml` — vault path, Ollama model (qwen25-coder-7b-16k), env vars
 - Hook wiring: `~/.claude/settings.json` (hook entries invoke `/usr/bin/python3` with absolute paths into cc-os)
 
 **Graphify** — v0.8.31 at `/home/jared/.local/bin/graphify`
-- Vault graph: `~/Documents/SecondBrain/graphify-out/` — disposable, rebuilt by SessionStart hook
+- Vault graph: `~/Documents/SecondBrain/graphify-out/` — disposable, structural index rebuilt by SessionStart hook; handles relational/graph queries. Distinct from vault-index.json (planned, Plan B Phase 1): a flat `{tag: [{path, title, summary}]}` lookup rebuilt at SessionEnd, queried by the `/memory-find` skill for fast tag-based SB note discovery.
 - Project graph: `<project-root>/graphify-out/` — same pattern; gitignore it in each project repo
 - Vault conventions: `~/Documents/SecondBrain/vault-conventions.md` — frontmatter contract + tag taxonomy (canonical name decided 2026-06-09; formerly referred to as CONVENTIONS.md)
 
@@ -100,6 +102,10 @@ to those two and fix the stale doc.
 
 **Remaining optional items:** SessionStart vault pull (multi-machine sync; push-only is the current design); additional project onboarding (one at a time, per ADR-013); bulk vault migration. All required build steps complete as of 2026-06-15.
 
+## Issue tracking
+
+Issues (created via `/to-issues`) live on self-hosted Forgejo (`jared/cc-os`), queried with the `tea` CLI — not GitHub/`gh`. See `docs/issue-workflow.md` for token setup, listing, implementing, and closing issues.
+
 ## OpenSpec workflow
 
 Changes are managed spec-driven via OpenSpec. Use the matching skills rather than editing spec

docs/issue-workflow.md

@@ -0,0 +1,51 @@
+# Issue workflow (Forgejo + tea)
+
+_Last updated: 2026-06-30._
+
+How issues created by the `/to-issues` skill get tracked and implemented in this repo.
+
+## Tracker
+
+- Issues live on self-hosted **Forgejo**: https://forgejo.swansoncloud.com/jared/cc-os/issues
+- CLI: **`tea`** (`/home/jared/.local/bin/tea`), login name `forgejo`, user `jared`.
+- The repo remote is Forgejo, **not GitHub** — `gh` does not work here.
+
+## Token setup (one-time)
+
+`tea`'s token needs issue + repository scopes. Forgejo tokens are **immutable** — you cannot add scopes to an existing token, so generate a new one:
+
+1. https://forgejo.swansoncloud.com/user/settings/applications -> "Generate New Token".
+2. Select scopes: `read:issue`, `write:issue`, `read:repository`, `write:repository`.
+3. Register it with tea — **drop `--user`** (that flag forces the basic-auth path and fails with `Error: No password set`):
+   ```
+   tea login delete forgejo            # only if re-adding
+   tea logins add --name forgejo --url https://forgejo.swansoncloud.com --token <TOKEN>
+   ```
+
+`tea login delete` is local-only (edits `~/.config/tea/config.yml`); it does not revoke the server-side token. Git push/pull use SSH and are unaffected by API tokens.
+
+## List issues
+
+```
+tea issues list --repo jared/cc-os
+tea issues <N> --repo jared/cc-os     # view one issue's body
+```
+
+## Implement
+
+There is **no auto-trigger and no `/grab` command**. Issues from `/to-issues` are written as independently-grabbable tracer-bullet slices. To implement:
+
+1. Pick the next **unblocked** issue (check the "Blocked by" line in the body — slices often form a linear chain).
+2. Hand it to a coding session: _"implement issue #N from forgejo jared/cc-os"_.
+3. Work the dependency chain in order.
+
+## Close
+
+```
+tea comment <N> "summary of what was done" --repo jared/cc-os
+tea issues close <N> --repo jared/cc-os
+```
+
+## Caveat
+
+The Matt-Pocock `to-issues` / `triage` skills default to **GitHub** and were never wired to this Forgejo/`tea` backend for cc-os (no `docs/agents/` config, no `.scratch/`). Re-running them assumes GitHub. Running `/setup-matt-pocock-skills` and describing the `tea`/Forgejo workflow would wire them to the right tracker.

docs/memory-system/08-sb-active-use-plan.md

@@ -0,0 +1,126 @@
+> **Superseded.** This plan was refactored into two focused plans following a design session on 2026-06-27:
+> - [Plan A — Content](09-sb-content-plan.md): note types, templates, and vault population
+> - [Plan B — Findability](10-sb-findability-plan.md): vault-index.json, /memory-find, SessionStart injection, SessionEnd agent
+>
+> Retain this file for historical reference only.
+
+# SecondBrain Active Use Plan
+
+_Last updated: 2026-06-27_
+_Status: Planning_
+
+## Problem
+
+The Obsidian vault at `~/Documents/SecondBrain` has been dormant for 18 days, with no new notes added despite being positioned as the system's semantic memory layer. Projects and sessions lack clear lightweight triggers for when to write to the vault or query it, causing the vault to feel like a maintenance burden rather than an active tool. Without deliberate, low-friction surfaces that make the vault immediately useful, adoption stalls.
+
+## Design Principles
+
+- **Vault as library, not navigation:** Do not pre-compute "when to read X." Make querying cheap and let the AI decide at the point of need. The vault is a query-driven resource, not a prescribed workflow.
+- **Write-once, reuse-many:** Notes are authored and improved in a single canonical location, shared across projects via tag queries. When `convention/ruby-coding-standards.md` improves, every Ruby project benefits automatically without duplication or sync overhead.
+- **Progressive disclosure:** Start with lightweight tag-based search (one layer). Full notes are opened on-demand, not pre-loaded. Query results surface paths + one-line summaries; the AI reads summaries and decides which notes to fetch.
+- **Minimal injection overhead:** SessionStart hook injection targets ~200 tokens total: a project note (if it exists) plus a 2-3 line instruction on how to use the vault. No embedded links, no pre-computed indexes in the project repo.
+
+## Scope
+
+This plan covers seven implementation pieces:
+
+1. Note type templates and vault-conventions.md updates
+2. High-priority knowledge migration (4–5 notes)
+3. vault-index.json and rebuild hook
+4. `/memory-find` query skill
+5. Project note format and initial project notes
+6. SessionStart hook extension for project note + vault instruction injection
+7. `/memory-audit` skill for ongoing project-to-vault migration discovery
+
+All pieces are self-contained; they build on each other but do not introduce external dependencies (no SQLite, no FTS5 at this stage, no PocketBase).
+
+## Out of Scope
+
+- **Bulk vault migration:** Migrate notes incrementally by type and project (ADR-013 principle). This plan seeds 4–5 high-priority notes; remaining notes migrate project-by-project as `/memory-audit` identifies them.
+- **SQLite or full-text search upgrade:** vault-index.json (JSON mapping tag → metadata) is sufficient for current scale (targeting 200+ notes). Upgrade when measured query latency becomes a bottleneck.
+- **Multi-machine vault pull:** Push-only design is locked (2026-06-15). SessionStart pull for multi-machine sync is explicitly deferred.
+- **memsearch ↔ vault integration:** memsearch (episodic memory) and SecondBrain (semantic memory) remain separate by design (ADR-006, ADR-010). No cross-system queries in this phase.
+
+## Surfaces Touched
+
+- **Vault content:** `~/Documents/SecondBrain/` (notes, templates, vault-conventions.md updates)
+- **Plugin code:** `cc-os/plugins/memory/` (hooks: `session_start.py` extended; new build step for index)
+- **Plugin config:** `config.yaml` — no changes required (log index build status if helpful)
+- **Settings:** `~/.claude/settings.json` — only if new hook is needed; likely already covered by SessionStart
+- **Project repos:** No changes to project CLAUDE.md files. Project notes live in SecondBrain, not in repos.
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| **Index staleness** | Rebuild hook triggers on vault note write (SessionEnd), not on every query. Stale index is acceptable; index is regenerated within one session boundary. |
+| **Tag explosion** | Enforce the six-facet taxonomy strictly during migration. Audit skill flags non-conforming tags and suggests corrections before vault-index.json rebuild. |
+| **Over-querying vault** | `/memory-find` returns unfiltered tag matches. If a tag is too broad (e.g., `tool/ruby` in a large vault), result set is large. AI reads summaries and selects; no hard limit needed yet. Revisit if query result counts consistently exceed 10 matches. |
+| **Project notes feel boilerplate** | Keep project notes minimal: name, 1-sentence description, tags only. No embedded reference links or pre-computed categories. Brevity prevents "maintenance tax" feeling. |
+| **Hook performance** | vault-index.json rebuild is O(n) file scans. For 200 notes, ~500ms. Acceptable at SessionEnd; revisit if rebuild takes >2s. |
+| **Audit skill churn** | `/memory-audit` discovers migration candidates but doesn't auto-migrate. Manual decision gate prevents vault sprawl. Migration is deliberate, not automatic. |
+
+## Build Order
+
+### 1. Templates + vault-conventions updates (Size: S)
+
+Add note type templates and taxonomy guidance to `vault-conventions.md`. Define what each note type contains: howto (steps, prerequisites, gotchas), reference (lookup data, static facts), adr (decision, alternatives, rationale), convention (rule, rationale, exceptions), tool (commands, config, when to use). Update the vault-conventions.md to emphasize the DRY principle and tag-query-first workflow. Templates live in `~/Documents/SecondBrain/templates/` for Obsidian template picker.
+
+### 2. Migrate 4–5 high-priority notes (Size: M)
+
+Using templates and taxonomy guidance, author 4–5 high-value notes that already exist as scattered docs or tribal knowledge. Candidates identified in "High-Priority Migration Candidates" section below. Write in vault using correct tags; commit to SecondBrain git repo.
+
+### 3. vault-index.json + rebuild hook (Size: M)
+
+Create a JSON file at `~/Documents/SecondBrain/vault-index.json` with structure `{tag: [{path, title, summary}]}`. Extend `session_end.py` (or add a dedicated hook if `session_end.py` is already full) to rebuild the index by scanning vault notes (frontmatter tags + first 1–2 sentences as summary). Rebuild only when SessionEnd fires (vault is pushed); no real-time index updates. Save index to vault root so it's tracked in git and pushed with every vault sync.
+
+### 4. `/memory-find` skill (Size: S)
+
+Create a skill in `cc-os/plugins/memory/skills/memory-find.md` that accepts a tag argument, loads vault-index.json, filters for matching tags, and returns results as a bulleted list: path, title, summary. One line per match. No embedded note fetching; AI reads summaries and decides which notes to open with `/memory-recall` or manual Read tool calls.
+
+### 5. Project note format + initial project notes (Size: S)
+
+Define project note format: `project/[name].md` containing project name, one-sentence description, and a bulleted tag list (e.g., `tool/ruby`, `client/acme`, `project/inventory-service`). Create 2–3 pilot project notes for projects already in scope (e.g., cc-os itself, a client project, a tool project). No template links, no category pre-computation. Tags are the interface.
+
+### 6. SessionStart injection (Size: S)
+
+Extend `session_start.py` (or the equivalent hook) to check if a project note exists for the current project (by name). If it exists, inject the project note name + tags into the session context, plus 2–3 lines telling the AI: "SecondBrain is available. Use `/memory-find tag-name` to query notes by tag, then read full notes with `/memory-recall path`. DRY principle: notes are shared across projects." Total injection: ~200 tokens, at the top of the session context so it's visible but not verbose.
+
+### 7. `/memory-audit` skill (Size: M)
+
+Create a skill that scans the current project for knowledge artifacts (CLAUDE.md, README, docs/, ADRs, how-tos, etc.), extracts a brief summary of each, checks vault-index.json to see if equivalent coverage already exists, and reports: "Found 3 docs; 1 is already in vault under `howto/deployment`, suggest migrating 2 others to vault." Returns candidates for manual migration. Skill runs at user request, not automatically. Audit report feeds into step 2 loop: candidate → note template → authored → indexed.
+
+## High-Priority Migration Candidates
+
+These are real, existing documents identified in an audit of active project repos. Ordered by cross-project value.
+
+| Source Path | Proposed Vault Path | Note Type | Rationale |
+|-------------|---------------------|-----------|-----------|
+| `~/dev/hyperthrive_dev/docs/agent-orchestration-patterns.md` | `type/reference/agent-orchestration-patterns.md` | reference | Framework for minimizing context accumulation across multiple agents. Needed in delta-refinery too — already being duplicated. |
+| `~/dev/hyperthrive_dev/docs/agent-orchestration-cookbook.md` | `type/reference/agent-orchestration-cookbook.md` | reference | Companion recipes to patterns doc. Pair as hub note + detail note. |
+| `~/dev/delta-refinery/docs/agent-pre-post-handoff.md` | `type/howto/pre-post-handoff-pattern.md` | howto | Pre/Post/Handoff pattern for multi-level agent coordination. Cross-project pattern currently locked in one repo. |
+| `~/dev/hyperthrive_dev/PROGRESSIVE_DISCLOSURE.md` | `convention/progressive-disclosure.md` | convention | Context management pattern for large codebases. Directly relevant to how this vault itself is designed. |
+| `~/dev/thinkfast/docs/conventions.md` (+ duplicate in `~/dev/verona-vocab/CLAUDE.md`) | `convention/sandi-metz-code-philosophy.md` | convention | Code philosophy derived from POODR/99 Bottles. Already duplicated across two repos — canonical vault note eliminates the copies. |
+| `~/dev/hyperthrive_dev/AGENTS.md` | `type/reference/ai-team-role-hierarchy.md` | reference | CEO→PM→Architect→Dev→QA→Ops role framework for multi-agent projects. Medium priority; useful when spinning up new agent-heavy projects. |
+
+**Not included (kept in-repo by design):** Per-project ADRs stay with their repos — they document project-specific decisions, not generalizable patterns. The memory system ADRs in cc-os similarly stay in `docs/memory-system/03-architecture-decisions.md`. If a decision *generalizes* (e.g., "always use progressive disclosure for large codebases"), it gets distilled into a convention or reference note rather than copying the ADR itself.
+
+## Note Types and Templates Needed
+
+- **howto:** Step-by-step instructions with prerequisites and gotchas. Example: "Running Graphify on a new project," "Debugging a memsearch query," "Deploying llf-schema to staging." Include terminal output / expected outcomes where applicable.
+- **reference:** Lookup data, architecture diagrams (as text or links), static facts that rarely change. Example: "Memory system architecture," "Ruby stdlib conventions," "Client billing codes."
+- **adr:** Architecture Decision Record. Problem statement, alternatives considered, decision, rationale, and deferred items. Links to related ADRs. Replaces inline ADRs in project CLAUDE.md.
+- **convention:** Rules, patterns, and exceptions. Example: "File naming," "Commit message style," "When to use Graphify vs. full-text search." Rarely longer than one page.
+- **tool:** Commands, common config patterns, when to use. Example: "Graphify cheat sheet," "memsearch CLI reference," "Obsidian query syntax for vault."
+
+## Open Questions
+
+1. **Project note auto-generation vs. manual:** Should `/memory-audit` suggest and auto-create project notes, or should they be authored by hand? Current design assumes manual (audit discovers, user confirms and authors). Revisit if manual authoring becomes a bottleneck.
+
+2. **Index rebuild frequency vs. freshness:** Rebuild at SessionEnd only (batched), or on every vault note write? Current design: SessionEnd only (batches multiple edits, reduces hook latency). If vault is edited multiple times in one session and a later hook needs current index, we miss edits within the session. Acceptable risk for now; flag if `/memory-find` starts returning stale results.
+
+3. **Result set size limits:** `/memory-find` returns all matches for a tag. If `tool/ruby` has 20 matches in a 200-note vault, should the skill limit to top 10 by recency/relevance, or return all with summaries and let the AI filter? Current design: return all, let AI filter by reading summaries. Revisit if query result sets consistently exceed 15 items and AI spends significant time skimming.
+
+---
+
+**Next step:** Proceed with step 1 (templates) or sync this plan with the project via ADR if design refinement is needed before build starts.

docs/memory-system/09-sb-content-plan.md

@@ -0,0 +1,356 @@
+# SecondBrain Content Plan (Plan A)
+
+_Status: Phase 1 complete (2026-06-30); Phase 2 ongoing. Last updated: 2026-06-30._
+
+> Plan A of two. Plan A solves the **content problem** — the vault is dormant because it holds
+> too little valuable knowledge to be worth querying. Plan B (separate doc) solves the
+> **findability problem** — infrastructure to surface what exists. Plan A must come first:
+> findability infrastructure built before content exists is scaffolding with nothing to scaffold.
+
+---
+
+## Core Design Principles
+
+### Projects contain product; SecondBrain contains knowledge
+
+Code, configs, and project-specific docs stay in repos. Generalizable knowledge lives in SB.
+When something is learned during a project, the signal gets extracted and written to SB — the
+source document stays in the project repo. The line should be as clear as possible.
+
+### Distill, don't dump
+
+Documents don't move to SB wholesale — knowledge is extracted from them. Source docs may stay
+in project repos; SB gets the lasting signal: the rule, the pattern, the procedure, the
+decision rationale. Volume is not the goal; density of useful signal is.
+
+### Write-once, reuse-many
+
+A convention defined in SB applies to every project that references it. When it improves, every
+project benefits. Notes are authored to be reused across projects, not archived for one.
+
+### Author small from the start
+
+Notes should be focused and use their template structure. Template adherence is the quality
+constraint, not line count. A note that fully answers its question in 20 lines is better than a
+sprawling dump. Splitting bloated notes is Plan C.
+
+### Injection economics govern template design
+
+These notes are injected into AI context mid-task, repeatedly, across every project, indefinitely. Every section that doesn't earn its place is a recurring token tax. The governing rule:
+
+> **The burden of proof is on inclusion. A section exists only if you can name a consumer who acts differently because it's there.**
+
+This applies to every template section decision and every authoring choice.
+
+### Value gate (three dimensions)
+
+Before writing a note, check all three:
+
+1. **Longevity** — still relevant in 6–12 months?
+2. **Reusability** — applies beyond the project that produced it?
+3. **Mutability** — stable knowledge or a mutable fact? Mutable facts (billing rates, client
+   contacts) belong in SB but carry a `last_reviewed` field, not a staleness date.
+
+A note that fails longevity or reusability is probably a project-internal doc. A note that
+captures a mutable fact is fine — just mark it accordingly.
+
+### Experience-driven updates
+
+When a session executes a procedure already documented in SB and finds a discrepancy, update
+the note. Do NOT use date-based staleness review — a howto isn't "old," it's either right or
+it isn't based on what just happened. Howtos flagged as `update_note: experience-driven`
+signal that their steps involve UIs or APIs that change frequently and should be verified at
+execution time.
+
+---
+
+## Two-Layer Write Mechanism
+
+> **Note:** The two-layer mechanism is documented here as design context. Implementation belongs
+> in Plan B.
+
+Two layers determine when AI writes to SB:
+
+### Layer 1 — Inline (during session)
+
+SessionStart hook injects ~100 tokens of global type classification rules. These tell the AI
+what types always go to SB and where. Project-specific exceptions are stored in the project's
+SB note (`project/[name].md`) and injected alongside the global rules at SessionStart for that
+project.
+
+Inline classification works best as opt-out — the AI should assume a type is SB-eligible and skip only when the value gate fails, not the reverse.
+
+### Layer 2 — SessionEnd catch-all
+
+A SessionEnd agent audits the git diff since the last session for knowledge that belongs in SB
+but wasn't written inline. The agent uses judgment:
+
+- If a type doesn't exist globally → it's a global gap; add it to global rules.
+- If the type exists but is specific to this project → it becomes a project-specific exception
+  stored in the project note.
+
+**Implementation note:** The Layer 2 "agent" requires an invocation mechanism decision before Plan B Phase 3 is built. See Plan B (`10-sb-findability-plan.md`) Phase 3 prerequisite note. Until this decision is made and built, Layer 1 is the primary write path.
+
+### The feedback loop
+
+Global rules handle obvious cases inline → SessionEnd catches non-obvious ones → catches that
+are project-specific get stored in the project note → next SessionStart for that project
+injects the exception → SessionEnd has less to catch.
+
+The system gets smarter per-project over time.
+
+---
+
+## Note Types (Plan A)
+
+Three types are defined in this plan. Hub/index and other types (meeting, task, QoL
+opportunities) are deferred — they require content density to be useful.
+
+### `convention`
+
+> **Question:** "When I encounter [situation X], what rule or pattern should I follow, and why?"
+
+- **Stable knowledge** — no review date needed.
+- **When to use:** recurring decisions where consistent behavior matters more than one-off
+  judgment. The test: "would a new collaborator ask this?"
+
+*These sections are illustrative starting points. The Step 2 template-design process applies the injection-economics filter — any section that can't pass "a named consumer acts differently because this is here" gets cut. The Step 2 output is authoritative.*
+
+**Template sections:**
+
+1. **Purpose** (1–2 sentences) — what recurring decision does this govern?
+2. **Core Principles** (3–7) — each principle with rationale. Not just "do X" but "do X
+   because Y."
+3. **Patterns** — how principles manifest in practice. Concrete examples.
+4. **Anti-Patterns** — what this convention specifically forbids and why.
+5. **Exceptions** — known cases where the convention doesn't apply.
+
+---
+
+### `reference`
+
+> **Question:** "What are the established rules, structures, setup requirements, or role
+> definitions I need to know to [make decisions / integrate / understand roles]?"
+
+- **Stable knowledge** (API integration sub-type carries `last_reviewed`).
+- **When to use:** structured facts that are queried, not procedures that are executed.
+
+**Sub-templates:**
+
+| Sub-type | Use when |
+|----------|----------|
+| `pattern/framework` | Decision flowcharts, named patterns, anti-patterns |
+| `api-integration` | Setup, schema, operations, auth (carries `last_reviewed`) |
+| `role-definitions` | Who does what, input/output, phases |
+| `design-rules` | Standards, exceptions, examples |
+| `navigation/index` | Deferred to Plan B (hub/index type) |
+
+---
+
+### `howto`
+
+> **Question:** "How do I accomplish [specific, repeatable task]?"
+
+- **Experience-driven updates** — not date-based. The note is either right or it isn't,
+  based on what happens when you follow it.
+- **When to use:** repeatable procedures where sequencing matters and the steps are non-obvious
+  enough to forget.
+
+*These sections are illustrative starting points. The Step 2 template-design process applies the injection-economics filter — any section that can't pass "a named consumer acts differently because this is here" gets cut. The Step 2 output is authoritative.*
+
+**Template sections:**
+
+1. **Opening** — what this solves; who should read it.
+2. **Prerequisites** — checkbox list of what must be true before starting.
+3. **Steps** — numbered; each step has: context → action → expected result.
+4. **Verification** — how to confirm success.
+5. **Gotchas** — known failure modes and how to recover.
+6. **Related** — companion notes.
+
+Flag as `update_note: experience-driven` when steps involve UIs or APIs that change frequently.
+
+---
+
+## Standard Frontmatter Schema
+
+This schema resolves a contradiction in `vault-conventions.md` (see Phase 1 Step 1). The
+schema below is authoritative.
+
+```yaml
+---
+type: [convention|reference|howto]
+subtype: [pattern/framework|api-integration|role-definitions|design-rules]  # reference only
+title: [Human-readable title]
+summary: [1-2 sentences answering "what question does this note answer?"]
+tags:
+  - type/[convention|reference|howto]
+  - domain/[field]
+  - tool/[tool]       # if tool-specific
+  - client/[client]   # if client-specific
+  - project/[project] # if project-specific
+scope: [global|project|client]
+last_updated: YYYY-MM-DD
+date: YYYY-MM-DD          # creation date — set once, never updated
+last_reviewed: YYYY-MM-DD  # mutable facts only (API integration refs, billing rates)
+update_note: experience-driven  # howtos only, when steps involve changing UIs/APIs
+related:
+  - [note-slug]  # cross-links to companion notes
+source: [project name]  # project that spawned the note (e.g., llf-schema, design-mode, hyperthrive_dev)
+---
+```
+
+**Filenames:** slug-only, no date prefix. **Directories by type:** `convention/`, `reference/`,
+`howto/`.
+
+---
+
+## Build Order
+
+### Phase 1 — Harden the Foundation
+
+**Status: COMPLETE (2026-06-30).** All of Step 1–Step 3 below are done: `vault-conventions.md`
+reconciled to the single authoritative typed schema (issue #1); the `memory-template` skill
+written at `cc-os/plugins/memory/skills/memory-template/SKILL.md` (issue #2); the three
+templates (`howto.md`, `convention.md`, `reference.md`) created in
+`~/Documents/SecondBrain/_templates/` and dogfooded (issues #3–#5); the four proof-of-concept
+notes patched (issue #6). Issue #7 (Phase 2) remains open — see the Phase 2 status note below.
+
+Do these before authoring more notes. They establish the infrastructure that makes new notes
+consistent and useful.
+
+**Step 1: Reconcile `vault-conventions.md`**
+
+Remove the old frontmatter contract: date-prefixed filenames, `source:` as a tag, `scope/global`
+as a tag. The typed schema above is authoritative. Keep all other existing
+content intact. A contradictory conventions doc undermines every note that references it.
+
+**Step 2: Harden the template-design process, then write three template files**
+
+Step 1 (reconciling the frontmatter schema) must be complete before this step — templates sit on top of the frontmatter contract.
+
+**Step 2a — Write the `memory-template` plugin skill**
+
+Location: `cc-os/plugins/memory/skills/memory-template/SKILL.md` — alongside the existing skills (`memory-vault`, `memory-write`, `memory-project`, `memory-reorganize`). It is Graphify-indexed in the cc-os project graph, not the vault graph.
+
+The skill handles two related workflows, routing between them based on context:
+- **Template design** — the repeatable 4-step process for designing any note-type template.
+- **New-type creation** — the full lifecycle of adding a new type to the vault, from recognizing the need through to a working template (delegates to the template-design flow for the template itself).
+
+The 4-step template-design process the skill documents:
+
+1. **Model the consumers** — write who reads this type and the one action each takes. Grab or construct one exemplar (N=1, even synthetic, is enough — the process doesn't require a corpus).
+2. **Extract the minimal body shape** — name 2–4 body sections ordered action-first → why/when → caveats-last. For each candidate section, write one line: "*[consumer] acts differently because this is here.*" No line = cut the section. Add a subtype variant only if a real variant needs a genuinely different core shape.
+3. **Draft the fillable skeleton** — fixed frontmatter block + H1 + each section as a header with a one-line inline instruction (what goes here + target density) + an abbreviated filled example showing target density.
+4. **Dogfood and cut** — fill the template with the exemplar. Cut any empty or padded section; tighten any ambiguous instruction; re-fill. Done when the exemplar fills it with no empty sections and no padding.
+
+The new-type-creation workflow the skill documents:
+1. Recognize the trigger — what signals a type gap? (SessionEnd catch-all surfacing something that doesn't fit; repeated in-session workarounds for the same structural problem; N≥3 real instances exist that share structure)
+2. Collect N≥3 real examples (or construct synthetic ones)
+3. Define the question frame the type answers
+4. Follow the template-design flow above to produce the template
+5. Add the type definition to `vault-conventions.md`
+6. Create the template file in `_templates/`
+7. Author the first 2–3 notes using the template
+8. Dogfood critique (template already bakes this in via Step 4 of the design process)
+9. Refine based on findings
+
+Key design decisions baked in to the template-design flow:
+- Frontmatter (`summary` + tags) already serves the scanning human and the recall AI. The body only needs to serve two consumers: the injected AI mid-task and the executing human. Both want actionable core up front; they differ only in how far they read. One artifact, progressive disclosure, different stopping points.
+- One shared spine (frontmatter → H1 → actionable core → why/when → caveats), three type-specific body shapes. Subtypes are body variants within a template — never separate templates.
+- Anti-patterns the process must guard against: section inflation ("for completeness"), vague headers (`## Notes`, `## Details`), body duplicating frontmatter, paper-good/practice-ignored structure (caught by the dogfood step), convention stated without its boundary, smuggling project narrative (episodic content belongs in memsearch, not SB).
+
+**Step 2b — Write the three template files**
+
+Location: `~/Documents/SecondBrain/_templates/`
+
+Apply the Step 2a process (from the `memory-template` skill) to each type in this order:
+1. `howto.md` — first, because the template-design flow dogfoods it
+2. `convention.md`
+3. `reference.md` — include the sub-template variant selector in the body
+
+Use these existing notes as exemplars for the dogfood step:
+- howto: `howto/airtable-mcp-setup.md`
+- convention: `convention/sandi-metz-code-philosophy.md`
+- reference: `reference/agent-orchestration-patterns.md`
+
+**Step 3: Patch 4 of the 6 proof-of-concept notes (the 2 convention notes required no fixes)**
+
+See the Known Issues table in the next section. Apply all fixes before authoring new notes —
+stale patterns propagate.
+
+---
+
+### Phase 2 — Populate SB (Ongoing)
+
+**Status: OPEN (steady-state epic, issue #7).** The open, no-code epic for ongoing SB
+population; began once Phase 1 landed (2026-06-30).
+
+- Author notes from the migration candidate pool (see below).
+- Each note should refine the process slightly — diminishing marginal returns is the stopping
+  signal for a given type.
+- Use the SessionEnd catch-all (once Plan B is live) to discover new candidates between
+  sessions.
+- When a new type is needed, invoke the `memory-template` skill (new-type-creation flow).
+
+Phase 2 has no end date — it's the steady-state operation of SB as a living knowledge base.
+
+---
+
+## Known Issues in Proof-of-Concept Notes
+
+Patch these in Phase 1, Step 3, before authoring new notes.
+
+| Note | Issue | Fix |
+|------|-------|-----|
+| `reference/agent-orchestration-patterns.md` | Missing `tool/claude-code` tag; contains stale Claude Code tool claims (Task tool behavior) | Add `tool/claude-code` tag; add `last_reviewed` date; caveat tool-specific sections as version-sensitive |
+| `reference/agent-orchestration-cookbook.md` | Same tag gap; stale tool capability claims; glossary duplicates patterns note | Add `tool/claude-code` tag + `last_reviewed`; add caveat; fix non-enum `subtype: cookbook` → remove or replace with valid subtype; replace glossary with pointer to patterns note |
+| `howto/design-mode-workflow.md` | `scope: global` is incorrect (requires design-mode project context); project-internal details retained | Fix scope to `project`; add `project/design-mode` tag; remove future-capability markers and internal file path tables |
+| `howto/airtable-mcp-setup.md` | `update_note` field was undocumented; Step 3 leaks project-specific scaffolding | `update_note` is now documented in the schema above; add inline comment flagging Step 3 as a project-customization point |
+| `vault-conventions.md` | Two contradictory frontmatter schemas coexist | Reconcile — see Phase 1 Step 1 |
+
+---
+
+## Migration Candidate Pool
+
+High-priority candidates from real project files, ordered by cross-project value. Not
+exhaustive — these feed Phase 2.
+
+### Convention
+
+| Source | Target |
+|--------|--------|
+| `hyperthrive_dev/conventions/phlex.md` | `convention/phlex-component-design.md` |
+| `hyperthrive_dev/conventions/testing.md` | `convention/tdd-methodology.md` |
+| `hyperthrive_dev/conventions/ai-rules.md` | `convention/ai-agent-rules.md` |
+
+### Reference
+
+| Source | Target |
+|--------|--------|
+| `delta-refinery/docs/state_machine_reference.md` | `reference/state-machine-pattern.md` |
+| `design-mode/guides/design-color-rules.md` | `reference/design-color-rules.md` |
+
+_Additional candidates to be discovered via Plan B Phase 3 (SessionEnd discovery agent) as projects are onboarded._
+
+### Howto
+
+| Source | Target |
+|--------|--------|
+| `dev/design-mode/docs/devcontainer-guide.md` | `howto/devcontainer-sandbox-setup.md` |
+
+_Additional candidates to be discovered via Plan B Phase 3 (SessionEnd discovery agent) as projects are onboarded._
+
+When migrating: extract the knowledge, don't copy the document. Source file stays in its
+repo; `source:` field in frontmatter records provenance.
+
+---
+
+## Out of Scope for Plan A
+
+| Item | Deferred to |
+|------|-------------|
+| Findability infrastructure (vault-index.json, `/memory-find` skill, SessionStart injection, SessionEnd agent) | Plan B |
+| Hub/index note type | Early Plan B |
+| Meeting, task, QoL opportunity note types | Later (require content density + findability) |
+| Bulk vault migration | Incremental, per ADR-013 |
+| Note splitting and refinement passes | Plan C |

docs/memory-system/10-sb-findability-plan.md

@@ -0,0 +1,129 @@
+# SecondBrain Findability Plan
+
+_Last updated: 2026-06-28_
+_Status: Planning_
+
+## Problem
+
+Plan A (`09-sb-content-plan.md`) populates the vault with typed, templated notes. But notes that exist and cannot be found are no better than notes that do not exist. The vault needs three complementary findability layers: a queryable index so the AI can discover notes by tag without reading every file; session-start injection so the AI knows the vault exists and how to query it from the first prompt; and an end-of-session agent that closes the knowledge loop — creating notes that should have been written, detecting drift between documented and actual procedures, and preventing duplicate notes before they are created. Without these layers, the vault is a write-only system. This plan builds the read and update path.
+
+## Design Principles
+
+- **Vault as library, not navigation:** Don't pre-compute "when to read X." Make querying cheap and let the AI decide at the point of need. Query results surface paths + summaries; AI reads summaries and decides which notes to fetch.
+- **Minimal injection overhead:** SessionStart targets ~200 tokens total for all vault context. No embedded links or pre-computed indexes in project repos.
+- **Projects contain product; SecondBrain contains knowledge:** Project repos contain no SB infrastructure — project notes live in SB, not in repos.
+- **Experience-driven updates:** When a session executes a documented procedure and finds a discrepancy, update the note. Not date-based.
+
+## Scope
+
+This plan covers four phases, strictly sequenced — each phase depends on the previous:
+
+1. Hub/index type + vault-index.json
+2. `/memory-find` skill + SessionStart injection
+3. SessionEnd agent (create + detect + dedup)
+4. Feedback loop hardening
+
+## Out of Scope
+
+- **Atomic note splitting:** Large notes from Plan A that exceed focus — deferred to Plan C and beyond.
+- **SQLite/FTS upgrade:** When vault-index.json query latency becomes measurable (>200 notes or >15 matches per query consistently).
+- **Auto-update without human confirmation:** Deferred until flag-then-confirm is stable and trusted.
+- **SessionStart vault pull:** Multi-machine sync; push-only is the current locked design.
+- **Meeting, task, QoL opportunity note types:** Require findability layer to be useful; define after Plan B is operational.
+- **memsearch ↔ SB integration:** memsearch (episodic) and SB (semantic) remain separate by design (ADR-006, ADR-010).
+
+## Surfaces Touched
+
+- **Plugin code:** `cc-os/plugins/memory/hooks/session_context.py` (extend for Phase 2 injection + Phase 3 queue processing), `cc-os/plugins/memory/hooks/vault_index_rebuild.py` (new), `cc-os/plugins/memory/hooks/session_end.py` (extend for Phase 3 queue writing + git SHA capture)
+- **Skills:** `cc-os/plugins/memory/skills/memory-find.md` (new)
+- **Vault content:** `~/Documents/SecondBrain/vault-index.json` (new), `~/Documents/SecondBrain/project/` directory (new), hub notes as density warrants
+- **Settings:** `~/.claude/settings.json` — add `vault_index_rebuild.py` as fourth SessionEnd hook (separate hook, mirrors `memsearch_sync.py` / `vault_sync.py` pattern)
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| **Index staleness** | Rebuild at SessionEnd only (batched). Stale index is acceptable within a session; regenerated within one session boundary. Stale results are surfaced as a known gap, not a silent failure. |
+| **SessionEnd agent latency** | Phase 3 uses queue-and-defer: SessionEnd writes a candidate queue file (fast Python, <1s), next SessionStart processes it with the already-running LLM. No API call at session close; no terminal blocking. `/memory-audit` skill available for on-demand thorough audits. |
+| **Duplicate notes** | Phase 3 Part C (pre-action deduplication) adds a tag-intersection check before any note creation. Dedup runs before create — not after. |
+| **False positives in discrepancy detection** | Phase 3 Part B flags, does not auto-update. Human confirms before any note change. Auto-update deferred until flag-then-confirm workflow is stable and trusted. |
+| **Hub note timing** | Hub notes should not be created before cluster density exists (3+ related notes). Phase 1 defers hub creation to emergence — noted as a natural byproduct, not a scheduled deliverable. |
+| **Injection token budget** | SessionStart injection targets ~200 tokens total. If project note + global rules exceed budget, truncate global rules, not the project note. Project-specific context is higher signal at the point of use. |
+| **Silent hook failure** | `session_start.py` / `session_context.py`: inject a one-line warning when vault sync or graph rebuild last-success timestamp is older than `stale_threshold_days × 2`. Turn invisible decay into a visible session prompt. |
+
+## Build Order
+
+### Phase 1: Hub/index type + vault-index.json (Size: M)
+
+Two deliverables ship together:
+
+**Hub/index note type**
+Hub notes are deferred from Plan A because their value is relational — they only earn their place once notes are dense enough to navigate between. A hub note is a map, not content: title + one-sentence purpose + bulleted links to member notes with one-line descriptions. Do not create hub notes on a schedule; create them as a natural byproduct when a cluster of 3+ related notes exists. Planned first hubs (after content density warrants): agent-orchestration hub, rails-conventions hub.
+
+**vault-index.json**
+Location: `~/Documents/SecondBrain/vault-index.json`. Structure: `{generated_at: "ISO-8601", tags: {tag: [{path, title, summary}]}}`. Built by scanning vault notes: frontmatter tags + first 1–2 sentences as summary. Rebuilt at SessionEnd — batched, not real-time, not per-note-write. Tracked in git so it is pushed with every vault sync. The `generated_at` field lets `/memory-find` surface staleness (e.g., "index is 3 sessions old") rather than silently serving stale results.
+
+**Rebuild hook**
+Add `vault_index_rebuild.py` as a fourth SessionEnd hook. Hook order at SessionEnd: `session_end.py` → `memsearch_sync.py` → `vault_index_rebuild.py` → `vault_sync.py`. Rebuild runs after vault notes are written but before `vault_sync.py` pushes to Forgejo, so the pushed index is current.
+
+Decision: separate hook (not extending `session_end.py`) — mirrors `memsearch_sync.py` / `vault_sync.py` pattern, cleaner separation of concerns.
+
+### Phase 2: /memory-find skill + SessionStart injection (Size: S)
+
+Prerequisite: Phase 1 complete (vault-index.json exists).
+
+**/memory-find skill**
+Location: `cc-os/plugins/memory/skills/memory-find.md`. Accepts a tag argument. Loads vault-index.json. Filters for matching tags. Returns bulleted list: path, title, summary — one line per match. No embedded note fetching — AI reads summaries and decides which notes to open with Read tool calls or `/memory-recall`. No hard result limit in V1; revisit if queries consistently return 15+ matches.
+
+Trigger: on-demand only. The AI is instructed to call it when it encounters something that might be in SB. Automatic triggering before every action is deferred — too noisy until the index has density.
+
+**SessionStart injection**
+Extend `session_context.py` (the UserPromptSubmit hook — `session_start.py` has no injection output channel) to inject two things at session start (~200 tokens total):
+1. Global type classification rules (~100 tokens): "SecondBrain is your knowledge layer. Types that always go to SB: convention (rule/pattern), reference (lookup/architecture), howto (procedure). Use `/memory-find [tag]` to query. Use `/memory-recall [path]` to read full notes. DRY: if knowledge already exists in SB, reference it — don't duplicate."
+2. Project note (if exists for current project): project name, one-sentence description, tags this project produces. Tells the AI what types to write inline and what to look up. Project note format: `project/[name].md` containing name, one-sentence description, bulleted tag list, and optional `produces:` section for project-specific note types.
+
+### Phase 3: SessionEnd agent (Size: L)
+
+Prerequisite: Phase 1 and Phase 2 complete. Runs after `session_end.py` writes the episodic journal.
+
+> **Invocation model: queue-and-defer.** Python subprocess hooks cannot invoke the Claude model inline — the session has ended, and a direct Anthropic API call from a hook would block the terminal for 30–60+ seconds. The solution: split the work across two hooks.
+> 
+> - **SessionEnd** (`session_end.py`, fast Python only): writes a candidate queue file to `~/.claude/memory-queue/YYYY-MM-DD-{session_id}.json` containing the git diff summary, files changed, and session context. No LLM involved. Takes under 1 second.
+> - **Next SessionStart** (`session_context.py`): if a queue file exists from a prior session, inject it as a task for the already-running LLM. The LLM processes the queue during normal session startup — no separate API call, no blocking.
+> 
+> Trade-off: there is a one-session lag before notes get created. This is acceptable — the knowledge is captured (in the queue file) immediately; only the SB write is deferred. The `/memory-audit` skill remains available for on-demand thorough audits in the current session.
+
+> **Prerequisite (git anchor):** Phase 3 Part A's "audit git diff since last session" requires a session-boundary git SHA. This is not currently stored anywhere. Before implementing Phase 3, add a step to `session_end.py` (or the vault journal entry it writes) to record `git rev-parse HEAD` for the active project. Without this, "since last session" has no anchor and the diff scope is undefined.
+
+**Part A — Create new notes**
+Agent audits git diff since last session for knowledge that belongs in SB but wasn't written inline. Uses value gate (longevity + reusability + mutability) to assess candidates. Agent judgment: global type gap → update global classification rules; project-specific type → add to project note in SB. Creates notes using the appropriate template. Does NOT auto-update existing notes — flag only (see Part B). Cap at 5 candidates per run to stay within latency budget.
+
+**Part B — Detect discrepancies with existing notes**
+When a session executed a procedure already in SB, agent checks actual vs. documented. Three outcomes:
+1. Confirms — process matched the note, nothing to do.
+2. Flags for update — process differed; agent reports the discrepancy and proposed change; human confirms before note is updated.
+3. Flags ambiguity — process differed but unclear which is correct; human resolves before any change.
+Auto-update deferred until flag-then-confirm workflow is stable and trusted.
+
+> **Deferred:** Part B is cut from the initial Phase 3 build. Discrepancy detection is only meaningful when the vault has sufficient procedure note density. It also competes for the same time/token budget as Part A, which has clearer value at this stage. Add Part B when the vault has 25+ howto notes that are actively used.
+
+**Part C — Pre-action deduplication**
+Before creating a new note, agent checks vault-index.json for tag collision: do any existing notes carry the same primary tags? If yes, surface the existing note first — create only if the existing note doesn't cover the case. Implementation: tag intersection query on vault-index.json (fast, no embeddings needed). This closes the "we already have a note for that" gap.
+
+### Phase 4: Feedback loop hardening (Size: S)
+
+Prerequisite: Phase 3 stable.
+
+Project-specific type exceptions discovered by the SessionEnd agent are written to the project's SB note (`project/[name].md`) under a `produces:` section. Next SessionStart for that project injects these exceptions alongside global rules. Over time: global rules handle obvious cases → SessionEnd catches less → per-project notes accumulate correct type exceptions → system approaches self-managing.
+
+This phase is complete when the SessionEnd agent's "create" suggestions drop to near zero for a project — meaning global and per-project rules have absorbed the common cases.
+
+## Open Questions
+
+1. **Queue file format for Phase 3:** The candidate queue file written by SessionEnd needs a schema. Minimum fields: session_id, timestamp, project_root, git_sha (see git anchor prerequisite), files_changed (list), diff_summary (truncated). Design this schema before building Phase 3.
+
+2. **When does /memory-find trigger automatically vs. on-demand?** V1: on-demand only. The AI is instructed to call it when it encounters something that might be in SB. Automatic triggering (before every action) is deferred — too noisy until the index has density.
+
+3. **Project note bootstrapping:** Who creates the initial project note for a new project? Options: (a) user creates manually using template, (b) `/memory-audit` suggests it, (c) `memory-project` skill creates it during onboarding. Current design: option (c) — `memory-project` skill writes a `project/[name].md` to the vault as part of onboarding. Confirm this in the memory-project skill spec.
+
+4. **Queue file retention policy:** How long should unprocessed queue files persist? If the next session is in a different project directory, does `session_context.py` still pick up the queue? Simplest answer: always process any queue file regardless of current project — knowledge extraction is global. Retain queue files until processed; delete on successful processing.

plugins/memory/skills/memory-template/SKILL.md

@@ -0,0 +1,113 @@
+---
+description: Design SecondBrain note-type templates and create new note types — the repeatable 4-step template-design process and the full new-type-creation lifecycle
+---
+
+Use this skill when designing or revising the structure of SecondBrain note types — either
+designing a template for an existing type or introducing a brand-new type to the vault.
+
+These templates govern notes that are injected into AI context mid-task, repeatedly, across
+every project, indefinitely. Every section is a recurring token tax. The governing rule for
+every decision in this skill:
+
+> **The burden of proof is on inclusion. A section exists only if you can name a consumer who
+> acts differently because it's there.**
+
+This is the **injection-economics filter**. A section earns its place only if it pays for the
+tokens it costs when injected. Sections that fail the filter are **removed, not commented out**.
+
+## Routing — pick the workflow
+
+Decide by context:
+
+- **Template design** — you have a note type (existing or just-defined) and need to design or
+  revise its template. → Use the **4-step template-design process** below.
+- **New-type creation** — the vault needs a type that doesn't exist yet. → Use the
+  **new-type-creation lifecycle** below, which delegates to the template-design process for the
+  template itself.
+
+If unsure: if the type already exists in `vault-conventions.md`, you're doing template design.
+If you're recognizing a gap and proposing a new type, you're doing new-type creation.
+
+## Template design — the 4-step process
+
+Run this for any note-type template, new or revised.
+
+### 1. Model the consumers
+
+Write down who reads this type and the one action each takes. Grab or construct one exemplar —
+N=1, even synthetic, is enough; the process does not require a corpus.
+
+### 2. Extract the minimal body shape
+
+Name 2–4 body sections, ordered **action-first → why/when → caveats-last**. For each candidate
+section, write one line:
+
+> *[consumer] acts differently because this section is here.*
+
+**No line = cut the section.** This is the injection-economics filter in practice. Add a subtype
+variant only if a real variant needs a genuinely different core shape.
+
+### 3. Draft the fillable skeleton
+
+Assemble:
+
+- the fixed frontmatter block (per the authoritative schema in `vault-conventions.md`),
+- an H1,
+- each section as a header with a one-line inline instruction (what goes here + target density),
+- an abbreviated filled example showing the target density.
+
+### 4. Dogfood and cut
+
+Fill the template with the exemplar. Cut any empty or padded section; tighten any ambiguous
+instruction; re-fill. **Done when the exemplar fills the template with no empty sections and no
+padding.** This step catches paper-good/practice-ignored structure before it ships.
+
+## New-type creation lifecycle
+
+Adding a new type to the vault. Delegates to the template-design process above for the template
+itself.
+
+1. **Recognize the trigger.** What signals a type gap? The SessionEnd catch-all surfacing
+   something that doesn't fit an existing type; repeated in-session workarounds for the same
+   structural problem; N≥3 real instances exist that share structure.
+2. **Collect N≥3 real examples** (or construct synthetic ones).
+3. **Define the question frame** the type answers (the one-line "When I encounter X, what do I
+   need?" question).
+4. **Follow the template-design process** above to produce the template.
+5. **Add the type definition to `vault-conventions.md`.**
+6. **Create the template file in `_templates/`.**
+7. **Author the first 2–3 notes** using the template.
+8. **Dogfood critique** — the template already bakes this in via Step 4 of the design process.
+9. **Refine based on findings.**
+
+## Key design decisions
+
+These are baked into the process above; keep them in mind when applying it.
+
+- **Frontmatter and body serve different consumers.** Frontmatter (`summary` + tags) serves the
+  **scanning human** and the **recall AI**. The body serves only two consumers: the **injected AI
+  mid-task** and the **executing human**. Both want the actionable core up front; they differ only
+  in how far they read. One artifact, progressive disclosure, different stopping points.
+- **One shared spine, three type-specific body shapes.** Every template follows the same spine:
+  frontmatter → H1 → actionable core → why/when → caveats. The three types (`convention`,
+  `reference`, `howto`) differ only in their body shape on top of that spine.
+- **Subtypes are body variants, never separate templates.** A subtype is a variant within a
+  template's body, not its own template file. Add one only when a real variant needs a genuinely
+  different core shape.
+
+## Anti-patterns
+
+The process must guard against these. Each is something the template-design steps actively
+prevent:
+
+- **Section inflation** — adding sections "for completeness." Every section must pass the
+  injection-economics filter (Step 2). If no consumer acts differently, cut it.
+- **Vague headers** — `## Notes`, `## Details`, and similar. A header must name what it holds.
+- **Body duplicating frontmatter** — the body must not restate `summary` or tags. Frontmatter
+  serves the scanning human and recall AI; the body serves the injected AI and executing human.
+- **Paper-good / practice-ignored structure** — a template that looks clean but doesn't fill
+  cleanly. Caught by the dogfood step (Step 4).
+- **Convention stated without its boundary** — a convention note that gives the rule but not
+  where it stops applying (the exceptions / anti-patterns).
+- **Smuggling project narrative** — episodic, project-specific story content belongs in
+  memsearch, not SecondBrain. Templates should make this hard to do.