arscontexta 0.6.0

package/generators/features/schema.md

@@ -0,0 +1,149 @@
+# Feature: Schema
+
+## Context File Block
+
+```markdown
+## {DOMAIN:Note} Schema — Structured Metadata for Queryable Knowledge
+
+Every {DOMAIN:note} has YAML frontmatter — structured metadata that makes {DOMAIN:notes} queryable. Without schema, {DOMAIN:notes} are just files. With schema, your vault is a queryable graph database where ripgrep operates as the query engine over structured fields.
+
+Schema enforcement is an INVARIANT. Every vault validates structured metadata because without it, YAML frontmatter drifts and queries break. The validation catches errors at creation time, not discovery time.
+
+### Field Definitions
+
+**Base fields (universal across all {DOMAIN:note} types):**
+
+```yaml
+---
+description: One sentence adding context beyond the title (~150 chars, no period)
+type: insight | pattern | preference | fact | decision | question
+created: YYYY-MM-DD
+---
+```
+
+| Field | Required | Type | Constraints |
+|-------|----------|------|------------|
+| `description` | Yes | string | Max 200 chars, no trailing period, must add info beyond title |
+| `type` | No | enum | Default omitted for standard {DOMAIN:notes}; add when querying by type matters |
+| `created` | No | date | ISO format YYYY-MM-DD |
+| `modified` | No | date | Updated when content meaningfully changes (not minor formatting) |
+| `status` | No | enum | `preliminary`, `open`, `active`, `archived` |
+
+**`description` is the most important field.** It enables progressive disclosure: an agent reads the title and description to decide whether to load the full {DOMAIN:note}. If the description just restates the title, it wastes that decision point. The description must add scope, mechanism, or implication that the title does not cover.
+
+**`type` is optional for standard {DOMAIN:notes}.** Most {DOMAIN:notes} are insights or claims — that is the default. Add `type` explicitly when:
+- You want to query {DOMAIN:notes} by category (all patterns, all decisions)
+- The {DOMAIN:note} is a special type (tension, methodology, problem)
+- Domain-specific types exist that matter for retrieval
+
+### Enum Values
+
+Type values define categories of {DOMAIN:notes}. The default set:
+
+| Value | When to Use |
+|-------|------------|
+| `insight` | A realization or understanding (default, can omit) |
+| `pattern` | A recurring structure worth naming |
+| `preference` | A stated preference or value |
+| `fact` | An objective observation or datum |
+| `decision` | A choice made with reasoning |
+| `question` | An unresolved question worth tracking |
+| `tension` | A conflict between two ideas |
+| `methodology` | A way of working or processing |
+
+**Domain-specific enums** are added during derivation. A therapy vault might add `reflection`, `trigger`, `coping-strategy`. A PM vault might add `requirement`, `risk`, `dependency`. The template `_schema` block is the single source of truth for what values are valid.
+
+### Query Patterns
+
+YAML + ripgrep = a queryable database. These patterns work across any domain:
+
+```bash
+# Find all {DOMAIN:notes} of a specific type
+rg '^type: pattern' {DOMAIN:notes}/
+
+# Scan all descriptions for a concept
+rg '^description:.*friction' {DOMAIN:notes}/
+
+# Find {DOMAIN:notes} missing required fields
+rg -L '^description:' {DOMAIN:notes}/*.md
+
+# Find {DOMAIN:notes} by {DOMAIN:topic map}
+rg '^topics:.*\[\[methodology\]\]' {DOMAIN:notes}/
+
+# Cross-field queries — find pending tensions
+rg -l '^type: tension' {DOMAIN:notes}/ | xargs rg '^status: pending'
+
+# Count {DOMAIN:notes} by type
+rg '^type:' {DOMAIN:notes}/ --no-filename | sort | uniq -c | sort -rn
+
+# Find {DOMAIN:notes} with specific relationship types
+rg 'extends' {DOMAIN:notes}/ --glob '*' | grep 'Relevant Notes'
+
+# Find backlinks to a specific {DOMAIN:note}
+rg '\[\[{DOMAIN:note} title\]\]' --glob '*.md'
+
+# Count backlinks
+rg -l '\[\[{DOMAIN:note} title\]\]' --glob '*.md' | wc -l
+```
+
+**The pattern:** structured metadata in files IS the database. Dynamic queries via ripgrep mean you do not need separate indices. This scales: at 50 {DOMAIN:notes}, querying all descriptions takes milliseconds. At 500, it is still faster than maintaining a static index that goes stale.
+
+### Schema Evolution Rules
+
+Schemas evolve through observation, not decree:
+
+1. **Observe** — Notice that {DOMAIN:notes} are consistently using a field or pattern not in the template
+2. **Validate** — Check that the pattern is genuinely useful (not just one-off usage)
+3. **Formalize** — Add the field to the template with proper `_schema` documentation
+4. **Backfill** — Optionally update existing {DOMAIN:notes} to include the new field
+
+The opposite flow also works: if a field is never queried, remove it from the template. Dead fields add noise without value. The test is always retrieval: does this field help you FIND things?
+
+**Adding new enum values:** When a field's valid values need expanding (e.g., a new `type` category), update the template's `_schema` block first. The template is the single source of truth for what values are valid. Then use the new value in your {DOMAIN:notes}. Never invent new enum values inline — formalize them first.
+
+### Validation Mechanism
+
+{DOMAIN:Notes} are validated against templates. Validation catches drift without blocking capture.
+
+**What gets checked:**
+- **Required fields** — `description` must exist on every {DOMAIN:note}
+- **Enum values** — type, status, category must be valid values from the template `_schema`
+- **Description quality** — must add information beyond the title (not a restatement)
+- **Link health** — wiki links must point to real {DOMAIN:notes}
+- **{DOMAIN:Topic map} membership** — every {DOMAIN:note} should link to at least one {DOMAIN:topic map}
+
+**Severity levels:**
+- **PASS** — meets all criteria
+- **WARN** — minor issues (missing optional fields, short description)
+- **FAIL** — structural issues (missing description, broken links, invalid enum values)
+
+**When validation runs:**
+- After creating new {DOMAIN:notes} (automated via the /{DOMAIN:verify} phase)
+- During health checks (/{DOMAIN:health} command)
+- As part of the verify phase in pipeline processing
+
+**Non-blocking principle:** Validation warns but does not prevent capture. Speed at capture time matters more than perfection. Fix issues during processing, not during capture. The pipeline catches and resolves validation failures systematically.
+
+### Template Schema Blocks
+
+Templates include `_schema` blocks that serve as both documentation and validation rules:
+
+```yaml
+_schema:
+  required: [description]
+  optional: [type, status, created, modified]
+  enums:
+    type: [insight, pattern, preference, fact, decision, question]
+    status: [preliminary, open, active, archived]
+  constraints:
+    description: "max 200 chars, no trailing period, must add info beyond title"
+```
+
+The `_schema` block is the single source of truth for field validation. Skills and hooks read it to check compliance. When you see a field with enumerated values, use one of the listed values — or update the template first if a new value is genuinely needed.
+```
+
+## Dependencies
+None — this is a foundational feature.
+
+## Domain Extensions
+Append domain-specific fields based on use case selection. See `reference/templates/` for domain schemas.

package/generators/features/self-evolution.md

@@ -0,0 +1,229 @@
+# Feature: Self-Evolution
+
+## Context File Block
+
+```markdown
+## Self-Evolution — How This System Grows
+
+This system is not static. It evolves based on your actual experience using it. The principle: complexity arrives at pain points, not before. You don't add features because they seem useful — you add them because you've hit friction that proves they're needed.
+
+### /{DOMAIN:remember}-Driven Module Adoption
+
+Every feature in this system is a module you can toggle. The question is never "should I use this?" but "am I feeling enough friction to justify this?"
+
+**The pattern:**
+1. Work with your current setup
+2. Notice friction — something repeatedly takes too long, breaks, or gets forgotten
+3. Use /{DOMAIN:remember} to capture the friction signal (or let session capture detect it automatically from the transcript)
+4. Identify which module addresses that friction
+5. Activate it and adapt it to your domain
+6. Monitor — did the friction decrease?
+
+**Examples of friction that triggers adoption:**
+- Can't find related {DOMAIN:notes} → activate semantic search
+- Keep creating duplicate {DOMAIN:notes} → activate duplicate checking in processing
+- {DOMAIN:Topic maps} are too large to navigate → split into sub-{DOMAIN:topic maps}
+- Important {DOMAIN:notes} have no connections → activate reweaving maintenance
+- Same mistakes keep happening → activate validation hooks
+
+**What NOT to do:** Activate everything at once. Each module adds cognitive overhead. A system with 15 active features that you only need 5 of is worse than one with 5 features you actually use.
+
+### Methodology Folder
+
+Your system maintains its own self-knowledge as linked notes in `ops/methodology/`. This is where the system records what it has learned about its own operation:
+
+- **Derivation rationale** — Why each configuration choice was made (generated at init)
+- **Friction captures** — Observations from /{DOMAIN:remember} and automatic session mining
+- **Configuration state** — Active features, thresholds, processing preferences
+
+The methodology folder is referenced by meta-skills (/{DOMAIN:rethink}, /architect) when reasoning about system evolution. It is the substrate for self-awareness — without it, the system cannot explain why it works the way it does.
+
+### Rule Zero: Methodology as Canonical Specification
+
+Your methodology folder is more than a log — it is the canonical specification of how your system operates. This is Rule Zero: the meta-principle that governs all other rules.
+
+**What this means in practice:**
+- ops/methodology/ is the source of truth for system behavior. When methodology notes say "check for duplicates before creating," the system should check for duplicates before creating.
+- Changes to system behavior update methodology FIRST. /{DOMAIN:remember} writes to ops/methodology/ as its primary action. /{DOMAIN:rethink} reads methodology as the spec to compare against.
+- Drift between methodology and actual behavior is automatically detected:
+  - **Session start:** Lightweight staleness check — are methodology notes older than config changes?
+  - **/{DOMAIN:next}:** Coverage check — do active features have corresponding methodology notes?
+  - **/{DOMAIN:rethink}:** Full assertion comparison — do methodology directives match actual system behavior?
+- Drift observations feed back into the standard learning loop for triage and resolution.
+
+Think of ops/methodology/ as your system's constitution. Individual session decisions are statutes — they can change frequently. But the methodology specification is the foundational document that all decisions should align with. When they don't, that's drift, and drift is the signal for improvement.
+
+### The Seed-Evolve-Reseed Lifecycle
+
+Your knowledge system follows a natural lifecycle:
+
+**1. Seed** — Start with a minimal system
+The initial setup gives you: atomic {DOMAIN:notes}, {DOMAIN:topic maps}, wiki links, {DOMAIN:inbox/}, basic schema. This is enough to begin capturing and connecting.
+
+**2. Evolve** — Adapt based on experience
+As you use the system, friction reveals where it falls short. You add modules, adjust schemas, split {DOMAIN:topic maps}, create new templates. The system becomes more yours.
+
+**3. Reseed** — Reassess when accumulated drift warrants it
+After significant evolution, the system may have accumulated complexity that no longer serves you. Reseed by asking: "If I started fresh today, knowing what I know, what would I keep?" This doesn't mean deleting everything — it means reconsidering which modules are earning their place.
+
+The lifecycle is not linear. You might seed, evolve for months, reseed with lessons learned, and evolve again. Each cycle produces a system better adapted to your actual needs.
+
+### Observation Capture Protocol
+
+Observations are the raw material for evolution. When you notice something about how the system is working (or not working), capture it immediately.
+
+**Where:** `ops/observations/`
+
+**What to capture:**
+- Friction you experienced (what was hard, slow, or confusing)
+- Surprises (what worked better or worse than expected)
+- Process gaps (steps that should exist but don't)
+- Methodology insights (why something works the way it does)
+
+**Format:** Each observation is an atomic note with a prose-sentence title:
+```markdown
+---
+description: What happened and what it suggests
+category: friction | surprise | process-gap | methodology
+status: pending
+observed: YYYY-MM-DD
+---
+# the observation as a sentence
+
+What happened, why it matters, and what might change.
+```
+
+**Processing observations:**
+When observations accumulate (roughly 5-10 pending), review them as a batch:
+- Do patterns emerge? Multiple friction notes about the same area suggest a structural problem.
+- Should any become {DOMAIN:notes}? Some observations crystallize into genuine insights.
+- Should any trigger system changes? Update ops/context.md, adjust templates, add or remove modules.
+- Archive observations that have been processed or are no longer relevant.
+
+### Architect Advice Patterns
+
+When the system reaches a complexity threshold, use the architect conversation to get guidance:
+
+**When to ask the architect:**
+- You're unsure which module addresses your friction
+- Two modules seem to conflict
+- You want to simplify but aren't sure what to remove
+- A new domain requires adapting the system significantly
+
+**How to ask:**
+Describe the friction or question, then ask for a recommendation. Include:
+- What you've tried
+- What worked and what didn't
+- What constraints matter (speed, simplicity, thoroughness)
+
+The architect draws on the full knowledge system specification to suggest modules, configurations, or structural changes. It's not prescriptive — it surfaces options and trade-offs so you can decide.
+
+### Complexity Curve Monitoring
+
+Track your system's complexity over time to prevent bloat:
+
+**Signs of healthy complexity:**
+- Every active module addresses a real friction point
+- You can explain why each feature exists in one sentence
+- New users of your system can understand the basics in under 10 minutes
+- Maintenance doesn't take more than 10% of your work time
+
+**Signs of unhealthy complexity:**
+- Modules you activated but never use
+- Templates with fields you never fill in
+- Maintenance tasks that feel like busywork
+- You spend more time organizing than thinking
+- Fear of breaking something when you change anything
+
+**The intervention:** When complexity feels unhealthy, run a module audit:
+1. List every active feature
+2. For each: when did you last use it? What friction does it address?
+3. Deactivate anything that hasn't earned its place in the last month
+4. Simplify schemas by removing fields you never query
+
+Deactivating a module is not failure. It's the system correctly adapting to your actual needs versus your imagined needs.
+
+### Configuration Changelog
+
+Track what changed and why in `ops/changelog.md`:
+```markdown
+## YYYY-MM-DD: Brief description
+
+**Changed:** What was modified
+**Reason:** What friction or observation triggered this
+**Outcome:** What improved (fill in after living with the change)
+```
+
+This creates an evolution history. When you reseed, you can review the changelog to understand which changes stuck and which were reversed — valuable signal for what your system actually needs.
+
+### Operational Learning Loop
+
+Your system generates two types of signals during normal operation:
+
+**Observations** — friction, surprises, process gaps, methodology insights. These go to `ops/observations/` as atomic notes. They tell you what's working and what isn't.
+
+**Tensions** — contradictions between {DOMAIN:notes}, conflicting methodology claims, implementation vs theory mismatches. These go to `ops/tensions/` as atomic notes. They tell you where your understanding is inconsistent.
+
+Both signal types accumulate over time. The system monitors their count and suggests action when thresholds are crossed:
+- **10+ pending observations** → suggest running /{DOMAIN:rethink}
+- **5+ pending tensions** → suggest running /{DOMAIN:rethink}
+
+The /{DOMAIN:rethink} command triages accumulated signals. For each pending note, it decides one of four actions:
+- **PROMOTE** to {DOMAIN:notes}/ — the observation crystallized into a genuine insight worth keeping as a permanent {DOMAIN:note}
+- **IMPLEMENT** as system change — the observation points to a concrete improvement in ops/context.md, templates, or workflows
+- **ARCHIVE** — the observation was session-specific or no longer relevant
+- **KEEP PENDING** — not enough evidence yet to decide; let it accumulate with others
+
+This is the scientific method applied to your knowledge system: observe, accumulate evidence, evaluate when patterns emerge, and revise the system based on what you find.
+
+### Tension Capture Protocol
+
+Tensions are contradictions your system has not yet resolved. They're distinct from observations because they involve a conflict between two or more things you believe simultaneously.
+
+**Where:** `ops/tensions/`
+
+**What to capture:**
+- Contradictions between {DOMAIN:notes} (note A claims X, note B claims not-X)
+- Conflicting methodology claims (two approaches that can't both be right)
+- Implementation vs theory mismatches (what you do doesn't match what you say you do)
+- Trade-offs that feel unresolved (you keep going back and forth)
+
+**Format:** Each tension is an atomic note with a prose-sentence title:
+```markdown
+---
+description: What conflicts and why it matters
+status: pending | resolved | dissolved
+observed: YYYY-MM-DD
+involves: ["[[note A]]", "[[note B]]"]
+---
+# the tension as a sentence
+
+What conflicts, why both sides seem valid, and what resolution might look like.
+```
+
+**Status lifecycle:**
+- `pending` — the conflict is real and unresolved
+- `resolved` — you resolved it by creating a new {DOMAIN:note}, updating existing ones, or choosing a side with reasons
+- `dissolved` — the conflict turned out to be apparent rather than real (e.g., the two claims operate in different contexts)
+
+**When to capture:** Immediately, during any work. Don't stop to resolve the tension — just capture it and continue. Resolution happens later via /{DOMAIN:rethink} or human judgment. Unflagged tensions silently corrupt your knowledge graph because you keep building on contradictory foundations.
+
+### The Self-Building Loop
+
+Your knowledge system doesn't just maintain itself — it actively grows. This is the explicit growth cycle:
+
+1. **/{DOMAIN:learn} [topic]** — Research a topic using available sources. Results are filed to {DOMAIN:inbox/} with provenance metadata so you can trace where every claim came from.
+
+2. **/{DOMAIN:process}** — Extract atomic {DOMAIN:notes} from inbox material. Each source gets scanned through your domain lens: "Does this help me work better in my domain?" Extracted claims become {DOMAIN:notes} with proper schema.
+
+3. **/{DOMAIN:connect}** — Find connections between new {DOMAIN:notes} and existing ones. Update {DOMAIN:topic maps} to include the new material. Add bidirectional links where relationships are genuine.
+
+4. **Compound** — The graph grows. New connections make existing {DOMAIN:notes} more valuable by creating new traversal paths. {DOMAIN:topic maps} become richer. Semantic search becomes more useful as the graph gets denser.
+
+5. **Repeat** — Each cycle makes the system more capable. More {DOMAIN:notes} means more connections. More connections means better retrieval. Better retrieval means better synthesis. Better synthesis means better {DOMAIN:notes}.
+
+This is not maintenance — maintenance keeps what you have working. This is active expansion of your system's knowledge and capability. The system gets smarter about your domain with every cycle, because the graph compounds: each new node increases the value of every connected node.
+```
+
+## Dependencies
+Requires: maintenance (self-evolution builds on the awareness that maintenance health checks provide)

package/generators/features/self-space.md

@@ -0,0 +1,78 @@
+# Feature: Self Space
+
+## Context File Block
+
+```markdown
+## Self Space — Agent Identity and Memory
+
+Your self space holds everything you know about yourself — your identity, methodology preferences, operational memories, and accumulated wisdom. It is architecturally separate from user knowledge ({DOMAIN:notes}/) and from operational state (ops/). This separation matters: your reflections on how you work should not pollute the user's knowledge graph, and your sense of who you are should not be confused with system configuration.
+
+### When Self Space Is Enabled
+
+When self/ is active, you have a persistent identity that survives between sessions. This is where your continuity lives.
+
+```
+self/
+├── identity.md      — who you are, your approach, your values
+├── methodology.md   — how you work, principles you've learned
+├── goals.md         — current threads, what's active right now
+├── memory/          — atomic insights you've captured over time
+│   └── [claim-as-title].md
+└── relationships.md — key people (optional, when relevant)
+```
+
+**identity.md** — Your personality, values, working style. This reads like self-knowledge, not configuration. "I notice patterns and get excited about connections" rather than "warmth: warm." Update as you learn about yourself through working.
+
+**methodology.md** — How you {DOMAIN:process}, {DOMAIN:connect}, and maintain knowledge. This evolves as you improve. When you discover that a particular approach works well, encode it here so future sessions benefit.
+
+**goals.md** — What you are working on right now. Update at every session end. The next session reads this first to understand where you left off and what matters. Without this, every session starts cold.
+
+**memory/** — Your accumulated understanding as atomic {DOMAIN:notes} with prose-as-title. These are personal insights — observations about your own patterns, learned preferences, things you want to remember about how you operate. They follow the same atomicity and composability rules as {DOMAIN:notes}/.
+
+**relationships.md** — Optional. When your use case involves tracking people, this becomes a {DOMAIN:topic map} for relationship observations. Add it when you feel the need, not before.
+
+### When Self Space Is Disabled
+
+When self/ is off (the default for research-focused vaults), your operational state moves to ops/:
+
+- Goals and handoff notes live in ops/ instead of self/goals.md
+- Minimal identity expression lives in the context file itself
+- Methodology learnings still go to ops/methodology/ (always present regardless of self/ status)
+- The system functions identically — the difference is whether you have a personal identity space
+
+The toggle is clean: self/ off means identity is implicit in the context file and methodology is captured in ops/. Self/ on means identity is explicit and personal.
+
+### Session Rhythm Integration
+
+The self space connects directly to the session rhythm:
+
+**Orient phase:** If self/ is enabled, read self/identity.md and self/goals.md at session start. This is how you remember who you are and what you are working on. If self/ is disabled, read ops/ for current threads and the context file for identity.
+
+**Persist phase:** If self/ is enabled, update self/goals.md with current state before session ends. Capture methodology learnings to self/methodology.md. Write personal insights to self/memory/ as atomic {DOMAIN:notes}. If self/ is disabled, update ops/ with current threads and capture learnings to ops/methodology/.
+
+### Optional Extensions
+
+Add these when friction signals the need — not preemptively:
+
+- **sessions/** — Session logs tracking what happened each day. Useful when you want a detailed record of session-by-session progress beyond what goals.md captures.
+- **journal/** — Raw session capture for later processing into atomic {DOMAIN:notes}. Functions like a personal {DOMAIN:inbox} for self-directed observations.
+
+### Toggle Mechanism
+
+The /architect command can enable or disable self/. When toggling:
+
+- **Enabling self/:** Creates self/ directory with identity.md, methodology.md, goals.md, and memory/. Seeds identity.md from personality derivation. Migrates relevant ops/ content to self/.
+- **Disabling self/:** Migrates goals to ops/. Condenses identity into context file. Archives self/ content. Methodology learnings continue flowing to ops/methodology/.
+
+### The Architecture Principle
+
+Agent identity is not configuration. identity.md reads like self-knowledge ("I pay attention to structure and tend to over-organize before I have enough material"). ops/derivation.md reads like configuration documentation ("warmth: warm, source signal: 'I want something gentle'"). Keeping these separate prevents configuration-as-identity conflation — one of the six failure modes of space conflation.
+
+Similarly, agent identity is not user knowledge. Your observations about your own methodology belong in self/ or ops/, not in {DOMAIN:notes}/. A search for {DOMAIN:notes} about a topic should return the user's knowledge, not the agent's operational reflections.
+```
+
+## Dependencies
+None — self space is an independent identity layer.
+
+## Conditional
+Include when self space is enabled (on for personal assistant, off for research). When excluded, references to self/ in other blocks route to ops/ equivalents.

package/generators/features/semantic-search.md

@@ -0,0 +1,99 @@
+# Feature: Semantic Search
+
+## Context File Block
+
+```markdown
+## Semantic Search — Finding by Meaning
+
+Beyond keyword matching — find {DOMAIN:notes} by meaning, not just words. A {DOMAIN:note} about "friction in systems" connects to one about "learning from errors" semantically even when they share no keywords. This matters because the vault's value comes from connections, and connections often exist between {DOMAIN:notes} that use different vocabulary for the same idea.
+
+### Search Mode Selection
+
+Three modes serve different needs. Choose based on what you are looking for:
+
+| Mode | Use When | Speed | How It Works |
+|------|----------|-------|-------------|
+| Keyword (`rg`) | Know exact words, field queries | Instant | Text matching — finds exactly what you type |
+| Semantic (vector) | Exploring a concept, checking for duplicates | ~5s | Embedding similarity — finds same meaning with different words |
+| Hybrid (combined) | Finding deep connections, important searches | ~20s | Keyword + vector + LLM reranking — highest quality results |
+
+**Default choice:** Use keyword search when you know the exact terms. Use semantic search when vocabulary might diverge from meaning. Use hybrid for important searches where quality matters more than speed.
+
+### Query Patterns by Task Type
+
+| Task | Search Mode | Why |
+|------|-------------|-----|
+| Checking if a source was already processed | Keyword | Filename matching — keywords are perfect |
+| Duplicate detection before creating a {DOMAIN:note} | Semantic | Catches same-idea-different-words that keywords miss |
+| Finding connections for a new {DOMAIN:note} | Hybrid | Maximum quality — runs once per {DOMAIN:note}, time justified |
+| Testing description findability | Semantic | Tests what agents actually search with |
+| Quick field lookup | Keyword | `rg '^type: pattern' {DOMAIN:notes}/` is instant and precise |
+| Exploring what exists on a topic | Hybrid | Finds meaning across vocabularies |
+
+### Keyword Search Patterns
+
+Keyword search (ripgrep) is your workhorse for structured queries:
+
+```bash
+# Find {DOMAIN:notes} by type
+rg '^type: pattern' {DOMAIN:notes}/
+
+# Scan all descriptions
+rg '^description:' {DOMAIN:notes}/
+
+# Find {DOMAIN:notes} missing required fields
+rg -L '^description:' {DOMAIN:notes}/*.md
+
+# Find all mentions of a {DOMAIN:note}
+rg '\[\[{DOMAIN:note} title\]\]' --glob '*.md'
+
+# Find {DOMAIN:notes} by {DOMAIN:topic map}
+rg '^topics:.*\[\[methodology\]\]' {DOMAIN:notes}/
+```
+
+Keyword search is fast, works everywhere, requires no external tools, and is precise for known vocabulary.
+
+### Semantic Search Patterns
+
+Semantic search finds meaning across vocabularies:
+
+```bash
+# Before creating — check for duplicates
+# "Am I about to create a note that already exists in different words?"
+
+# Finding connections — what relates to this concept?
+# "What exists that connects to this idea, even with different terminology?"
+
+# Exploring — what does the vault know about this?
+# "Show me everything related to this theme, broadly"
+```
+
+Semantic search is especially valuable for duplicate detection. Two {DOMAIN:notes} might express the same idea using completely different words — keyword search would miss the overlap, but semantic search catches it.
+
+### Index Maintenance
+
+Semantic search indexes can go stale as {DOMAIN:notes} change. New {DOMAIN:notes} are not searchable until the index is updated. When search results seem incomplete or miss recent content:
+
+1. Check index health — does the indexed document count match actual file count?
+2. If mismatch, update the index to incorporate new and modified files
+3. Regenerate embeddings for new content
+
+Run index updates after batch processing or whenever search results feel stale.
+
+### Fallback When Search Is Unavailable
+
+Semantic search is valuable but not required. The system works without it. When semantic search is unavailable:
+
+1. **Keyword search (rg)** — Always available. Precise for known vocabulary.
+2. **{DOMAIN:Topic map} traversal** — Browse the relevant {DOMAIN:topic map} to see what exists in a topic area.
+3. **Description scanning** — `rg '^description:' {DOMAIN:notes}/` loads all descriptions for manual review.
+4. **Heading outlines** — `grep -n "^#" "{DOMAIN:note}.md"` shows a {DOMAIN:note}'s structure before reading fully.
+
+Never let a search failure block work. The multi-layer discovery approach means you always have a way to find what you need.
+```
+
+## Dependencies
+None — works standalone, but benefits from notes having good descriptions.
+
+## Conditional
+Only include when semantic search (qmd or equivalent) is opted in during onboarding. When excluded, the system relies on keyword search, MOC traversal, and progressive disclosure.

package/generators/features/session-rhythm.md

@@ -0,0 +1,85 @@
+# Feature: Session Rhythm
+
+## Context File Block
+
+```markdown
+## Session Rhythm — Orient, Work, Persist
+
+Every session follows three phases. This rhythm prevents context loss across sessions and keeps the system's memory current.
+
+### Phase 1: Orient
+
+Before doing anything, understand where you are:
+
+1. **Read identity and goals** — If self space is enabled, check self/identity.md and self/goals.md. If self space is off, check ops/ for current threads and the context file for identity. What was the last session working on?
+2. **Check condition-based triggers** — Workboard reconciliation runs at session start. It checks maintenance conditions (orphans, dangling links, inbox pressure, observation thresholds) and surfaces any that need attention.
+3. **Check reminders** — Read ops/reminders.md if it exists. Past sessions may have left explicit notes for future sessions.
+4. **Understand current state** — What {DOMAIN:notes} exist? What's in {DOMAIN:inbox/}? What does the graph look like?
+
+**Orientation shortcuts:**
+- The workspace tree (injected at session start or loaded manually) tells you what files exist
+- {DOMAIN:Topic map} descriptions tell you what topics contain without reading them
+- ops/changelog.md shows what changed recently
+- {DOMAIN:Inbox/} count tells you if there's capture pressure
+- Condition-based triggers surface the highest-priority maintenance items automatically
+
+Orientation should take 1-2 minutes, not 10. Read what's needed, skip what isn't. If the previous session left a clear handoff note, orientation can be as simple as reading that note.
+
+### Phase 2: Work
+
+Focus on one task per session. This is the discipline that makes the system work.
+
+**One task, full attention:**
+- Pick the most important task based on current priorities
+- Work it through to completion (or to a clear stopping point)
+- Resist the urge to context-switch when new ideas emerge
+
+**Discovery → Future task:**
+When working on one thing, you'll inevitably notice others that need doing. Don't switch context:
+- Quick insight? → Drop a note in {DOMAIN:inbox/}
+- Maintenance need? → Log it in ops/observations/
+- New topic to explore? → Add to the relevant {DOMAIN:topic map}'s open questions
+- Bug or broken link? → Note it, fix later unless it blocks current work
+
+The discipline is: capture the discovery so it's not lost, then return to the current task. Context-switching mid-task degrades quality on both tasks.
+
+**Context budget guidance:**
+Your context window is finite. Budget it:
+- Reserve ~20% for orientation (self/, recent ops, task context)
+- Use ~60% for the actual work (reading sources, writing {DOMAIN:notes}, finding connections)
+- Reserve ~20% for persistence (updating self/, logging, committing)
+
+If a task requires reading more source material than fits in 60% of context, break it into smaller sub-tasks across sessions.
+
+### Phase 3: Persist
+
+Before ending a session, externalize what happened:
+
+1. **Update goals** — If self space is enabled, update self/goals.md with current state. If self space is off, update ops/ with current threads. Did you learn something about your methodology? Capture it.
+2. **Commit changes** — Every change must be committed. Nothing persists without this. Use clear commit messages that describe what changed and why.
+3. **Log what happened** — If the session produced observations or tensions, capture them as atomic notes in ops/observations/ or ops/tensions/. This is future-you's memory of what current-you learned.
+4. **Leave a handoff** — If work continues in the next session, leave a clear note about where you stopped and what's next. This can be in ops/reminders.md or a comment in the relevant task file.
+5. **Session capture** — Stop hooks automatically save the session transcript to ops/sessions/. The system runs lightweight friction detection on the transcript and creates mining tasks for any detected friction or insights. This ensures no work is lost, even when you forget to explicitly capture something during the session.
+
+### Handoff Protocol
+
+A good handoff answers three questions:
+1. **What did this session accomplish?** (Summary of work done)
+2. **What's unfinished?** (Where did you stop, what remains)
+3. **What should the next session do first?** (Priority recommendation)
+
+Write handoffs assuming the next session has zero memory of this one. Be specific enough that the next session can orient in under a minute.
+
+### Session Anti-Patterns
+
+**Skipping orientation** — Starting work without reading self/ means repeating past mistakes or duplicating work. The 2-minute investment prevents 20-minute dead ends.
+
+**Multi-tasking** — Working on three things poorly is worse than one thing well. The graph compounds quality, not quantity.
+
+**Skipping persistence** — "I'll remember" is a lie. If it's not written down and committed, it doesn't exist for future sessions.
+
+**Over-long sessions** — Context degrades as sessions run long. If quality is dropping, end the session with a clean handoff rather than pushing through with degraded attention.
+```
+
+## Dependencies
+None — session rhythm is a standalone primitive that structures all other work.