arscontexta 0.6.0

package/README.md

@@ -0,0 +1,683 @@
+# Ars Contexta
+
+**A second brain for agents.**
+
+A Claude Code plugin that generates complete, working knowledge systems from natural conversation. You describe how you think and work. The engine derives a cognitive architecture — folder structure, context files, processing pipeline, automation hooks, navigation maps, and note templates — tailored to your domain and backed by 249 interconnected research claims synthesizing Zettelkasten, evergreen notes, Cornell note-taking, memory palaces, cognitive science, and network theory.
+
+No templates. No configuration forms. Just conversation.
+
+**v0.6.0** — 15 kernel primitives, 26 commands, 17 feature blocks, 249 research claims, 3 presets.
+
+---
+
+## Table of Contents
+
+- [What It Does](#what-it-does)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Prerequisites](#prerequisites)
+- [Architecture](#architecture)
+- [Presets](#presets)
+- [Commands](#commands)
+- [Hooks](#hooks)
+- [Processing Pipeline](#processing-pipeline)
+- [Platform Support](#platform-support)
+- [Semantic Search](#semantic-search)
+- [The Research Graph](#the-research-graph)
+- [Project Structure](#project-structure)
+- [Development](#development)
+- [Philosophy](#philosophy)
+- [License](#license)
+
+---
+
+## What It Does
+
+Most AI tools start every session blank. Ars Contexta changes that by generating a persistent thinking system derived from how you actually work.
+
+**The core concept:** conversation in, complete working knowledge system out. You talk about your domain — what you track, how you think, what matters. The engine maps your signals to eight configuration dimensions backed by cognitive science research, validates coherence, and generates everything you need.
+
+**What you get:**
+
+- **A vault** — a folder of plain markdown files connected by wiki links, forming a traversable knowledge graph. No database, no cloud service, no lock-in.
+- **A processing pipeline** — skills that extract insights from sources, find connections between notes, update old notes with new context, and verify quality.
+- **Automation** — hooks that enforce structure on every file write, detect when maintenance is needed, capture session state, and auto-commit changes.
+- **Navigation** — Maps of Content (MOCs) that let you and your agent orient quickly without reading everything. Hub, domain, and topic levels.
+- **Templates** — note templates with schema definitions (`_schema` blocks) that serve as the single source of truth for validation.
+- **A user manual** — 7 pages of domain-native documentation generated alongside your vault.
+
+**The key differentiator:** derivation, not templating. Every configuration choice traces to specific research claims. The engine doesn't copy a template — it reasons from principles about what your domain needs and why.
+
+### Three-Space Architecture
+
+Every generated system separates content into three spaces with fundamentally different durability profiles:
+
+| Space | Purpose | Growth Pattern |
+|-------|---------|----------------|
+| **self/** | Agent persistent mind — identity, methodology, goals | Slow (tens of files), loaded fully each session |
+| **notes/** | Knowledge graph — the reason the system exists | Steady (10-50 notes/week), progressive disclosure |
+| **ops/** | Operational coordination — queue state, session logs, health reports | Fluctuating, nothing permanent |
+
+The names adapt to your domain (`notes/` might become `reflections/`, `claims/`, or `decisions/`), but the architectural separation is invariant. Conflating any two spaces produces predictable, documented failures.
+
+---
+
+## Installation
+
+### NPM (recommended)
+
+One command installs the plugin into your current project:
+
+```bash
+npx arscontexta
+```
+
+This checks that Claude Code is installed, then copies the plugin into `.claude/plugins/arscontexta/` in your current working directory. After installation:
+
+1. Restart Claude Code (required for plugin activation)
+2. Run `/arscontexta:setup` to begin the conversational onboarding
+
+**How it works:** `npx` downloads the package from npm, runs `bin/cli.mjs`, which copies all plugin directories (skills, hooks, generators, methodology, reference files) into your project's `.claude/plugins/arscontexta/`. Claude Code discovers the plugin on next launch via the `plugin.json` manifest.
+
+### GitHub
+
+```bash
+/install-plugin https://github.com/agenticnotetaking/arscontexta
+```
+
+Or clone and install locally:
+
+```bash
+git clone https://github.com/agenticnotetaking/arscontexta.git
+claude plugin add ./arscontexta
+```
+
+### Local Development
+
+For testing or contributing:
+
+```bash
+git clone https://github.com/agenticnotetaking/arscontexta.git
+claude --plugin-dir ./arscontexta
+```
+
+This loads the plugin for a single session without copying files. Useful for iterating on the plugin itself.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+| Dependency | Required | Purpose |
+|-----------|----------|---------|
+| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v1.0.33+ | Yes | Plugin host |
+| `tree` | Yes | File structure injection at session start |
+| `ripgrep` (`rg`) | Yes | YAML metadata queries, schema validation |
+| Node.js >= 18 | For npx install only | Runs the CLI installer |
+| [qmd](https://github.com/tobi/qmd) | Optional | Semantic search (concept matching across vocabularies) |
+
+### First Run
+
+```
+1. Install the plugin (see Installation above)
+2. Restart Claude Code
+3. Run /arscontexta:setup
+4. Answer 2-4 questions about your domain
+5. The engine generates your complete knowledge system
+6. Restart Claude Code again (to activate generated skills and hooks)
+7. Run /arscontexta:help to see everything available
+```
+
+### The Setup Flow
+
+`/arscontexta:setup` runs a 6-phase process:
+
+1. **Platform Detection** — automatically detects Claude Code, OpenClaw, or minimal environment
+2. **Understanding** — 2-4 conversation turns where you describe your domain naturally
+3. **Derivation** — maps your signals to eight configuration dimensions with confidence scoring
+4. **Proposal** — shows what will be generated and why, in your own vocabulary
+5. **Generation** — produces all files: context file, folder structure, templates, skills, hooks, manual
+6. **Validation** — checks all 15 kernel primitives, runs a pipeline smoke test
+
+The whole process takes about 5 minutes.
+
+For advanced users who want to configure dimensions directly: `/arscontexta:setup --advanced`
+
+---
+
+## Prerequisites
+
+### Required
+
+**Claude Code** v1.0.33 or later. The plugin uses hooks (`SessionStart`, `PostToolUse`, `Stop`), skills with `context: fork`, and the `${CLAUDE_PLUGIN_ROOT}` path variable — all features requiring recent Claude Code versions.
+
+**tree** — Used by the session orientation hook to inject workspace structure at the start of every session. Install: `brew install tree` (macOS) or `apt install tree` (Linux).
+
+**ripgrep (rg)** — Used for YAML metadata queries, schema validation, backlink detection, and graph analysis scripts. The vault treats markdown + YAML + ripgrep as a queryable graph database. Install: `brew install ripgrep` (macOS) or `apt install ripgrep` (Linux).
+
+### Optional
+
+**qmd** — Semantic search engine combining BM25 full-text search with vector embeddings and LLM re-ranking. Enables concept matching across vocabularies (finding notes about "learning friction" when the note says "errors as feedback"). The system works fully without it using grep + MOC traversal.
+
+Install: `brew install tobi/tap/qmd` (macOS). The plugin bundles MCP configuration that connects qmd automatically.
+
+---
+
+## Architecture
+
+### 15 Kernel Primitives
+
+Every generated system includes these primitives regardless of preset or domain. The kernel is constant; the derivation engine varies everything above it.
+
+| # | Primitive | Layer | Enforcement |
+|---|-----------|-------|-------------|
+| 1 | **Markdown + YAML** — notes are plain text with structured metadata | Foundation | Invariant |
+| 2 | **Wiki links** — `[[note title]]` creates navigable graph edges | Foundation | Invariant |
+| 3 | **Filesystem graph database** — markdown nodes, wiki link edges, YAML properties, ripgrep queries | Foundation | Invariant |
+| 4 | **MOC hierarchy** — Maps of Content organize notes into navigable topic areas | Convention | Invariant |
+| 5 | **Tree injection** — agent sees full file structure at session start | Convention | Invariant |
+| 6 | **Description field** — YAML description (~150 chars) enables filter-before-read | Convention | Invariant |
+| 7 | **Topics footer** — every note declares MOC membership | Convention | Invariant |
+| 8 | **Schema enforcement** — templates define required fields, validation checks compliance | Convention | Invariant |
+| 9 | **Self space** — dedicated directory for identity, methodology, goals | Convention | Configurable |
+| 10 | **Session rhythm** — orient, work, persist cycle encoded in context file | Convention | Invariant |
+| 11 | **Semantic search** — meaning-based discovery across vocabularies | Automation | Configurable |
+| 12 | **Discovery-first** — everything optimized for future agent findability | Convention | Invariant |
+| 13 | **Operational learning loop** — accumulate friction signals, periodically review | Convention | Invariant |
+| 14 | **Task stack** — lifecycle backbone with unified pipeline + maintenance queue | Convention | Invariant |
+| 15 | **Session capture** — every session transcript saved automatically | Automation | Invariant |
+
+Primitives form a dependency DAG. Foundation primitives (`markdown-yaml`, `wiki-links`) enable convention primitives (`moc-hierarchy`, `schema-enforcement`), which enable automation primitives (`semantic-search`, `session-capture`). See `reference/kernel.yaml` for the full dependency graph.
+
+### 17 Feature Blocks
+
+Feature blocks are composable modules that get toggled by your configuration and assembled into coherent context files during generation:
+
+| Block | Category | Purpose |
+|-------|----------|---------|
+| `atomic-notes` | Conditional | Note design: one claim per file, prose-as-title |
+| `wiki-links` | Always | Link philosophy, inline links as prose |
+| `mocs` | Conditional | MOC hierarchy, navigation patterns |
+| `processing-pipeline` | Always | The 6 Rs processing approach |
+| `semantic-search` | Conditional | qmd integration, discovery patterns |
+| `schema` | Always | YAML metadata, query patterns |
+| `maintenance` | Always | Health checks, reweaving, condition-based triggers |
+| `self-evolution` | Always | System evolution: architect, reseed, rethink |
+| `methodology-knowledge` | Always | Querying the bundled research graph |
+| `session-rhythm` | Always | Orient, work, persist cycle |
+| `templates` | Always | Template usage and schema enforcement |
+| `ethical-guardrails` | Always | Behavioral constraints and safety |
+| `helper-functions` | Always | Utility scripts |
+| `graph-analysis` | Always | Graph intelligence and query patterns |
+| `personality` | Conditional | Agent voice and identity characteristics |
+| `self-space` | Conditional | Agent persistent memory (self/ directory) |
+| `multi-domain` | Conditional | Cross-domain rules for multi-topic systems |
+
+11 blocks are always included. 6 are toggled based on your derived configuration. The generator composes them sequentially, applies vocabulary transformation, eliminates cross-references to excluded blocks, and produces a cohesive context file.
+
+### 8 Configuration Dimensions
+
+The derivation engine maps conversation signals to positions on eight dimensions:
+
+| Dimension | Spectrum | What It Controls |
+|-----------|----------|-----------------|
+| **Granularity** | Atomic ↔ Coarse | One claim per note vs. per-session compound notes |
+| **Organization** | Flat ↔ Hierarchical | Flat associative network vs. folder-based hierarchy |
+| **Linking** | Explicit ↔ Implicit | Manual typed links vs. semantic similarity discovery |
+| **Processing** | Light ↔ Heavy | Capture-and-file vs. full pipeline with quality gates |
+| **Navigation** | 2-tier ↔ 3-tier | Simple index vs. hub → domain → topic hierarchy |
+| **Maintenance** | Manual ↔ Condition-based | User-triggered vs. automatic threshold detection |
+| **Schema** | Minimal ↔ Dense | Title + description vs. rich typed metadata |
+| **Automation** | Convention ↔ Full | Context-file instructions vs. hooks + pipeline + orchestration |
+
+Dimensions interact — choices in one create pressure on others. The coherence validator catches conflicts (e.g., atomic granularity + 2-tier navigation + high volume = navigational vertigo).
+
+---
+
+## Presets
+
+Three starting points with different defaults tuned for how you'll use the system. All three give you every skill and every capability — the difference is defaults.
+
+### Research
+
+**Optimizes for:** Deep synthesis, cross-domain connection density, long-term knowledge accumulation.
+
+**Closest tradition:** Zettelkasten + Cornell processing phases.
+
+| Dimension | Position |
+|-----------|----------|
+| Granularity | 0.8 (atomic) |
+| Organization | 0.3 (flat-associative) |
+| Linking | 0.7 (explicit + semantic) |
+| Processing | 0.8 (full pipeline) |
+| Navigation | 3-tier |
+| Maintenance | Condition-based |
+| Schema | Moderate |
+| Automation | 0.8 (full) |
+
+**Best for:** Academic research, literature review, knowledge building, tools-for-thought investigation.
+
+### Personal Assistant
+
+**Optimizes for:** Life reflection, pattern detection, personal growth tracking, relationship awareness.
+
+| Dimension | Position |
+|-----------|----------|
+| Granularity | 0.5 (mixed) |
+| Organization | 0.5 (light hierarchy) |
+| Linking | 0.3 (associative) |
+| Processing | 0.7 (full pipeline, personal categories) |
+| Navigation | 3-tier |
+| Maintenance | Condition-based |
+| Schema | Moderate |
+| Automation | 0.6 (semi-automated) |
+
+**Best for:** Life management, personal journaling, relationship tracking, goal tracking, habit awareness.
+
+### Experimental
+
+**Optimizes for:** User co-design, deep understanding of trade-offs, custom configuration.
+
+All dimensions start null — you choose positions during an extended onboarding conversation with research notes surfaced for every design decision.
+
+**Best for:** Novel domains (wine tasting, competitive gaming, legal case tracking), users who want full control, unusual workflows.
+
+Every preset value is overridable during the `/setup` conversation and adjustable post-init via `ops/config.yaml` or `/arscontexta:architect`.
+
+---
+
+## Commands
+
+26 commands organized by category. All use the `/arscontexta:` prefix.
+
+### Onboarding (3 commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:setup` | Conversational onboarding — derive and generate your knowledge system. Use `--advanced` for upfront dimension configuration. |
+| `/arscontexta:help` | Contextual guidance and command discovery |
+| `/arscontexta:tutorial` | Interactive walkthrough for new users |
+
+### Navigation (5 commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:next` | Intelligent next-action recommendation based on vault state. Reconciles maintenance conditions and surfaces the highest-priority work. |
+| `/arscontexta:ask` | Query the bundled 249-note TFT research graph for methodology guidance |
+| `/arscontexta:recommend` | Architecture recommendation without file generation — analysis only |
+| `/arscontexta:stats` | Vault statistics and metrics: note count, link density, MOC coverage, orphans |
+| `/arscontexta:graph` | Knowledge graph visualization and structural analysis |
+
+### Processing (5 commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:reduce` | Extract insights from source material. Domain-native extraction categories with selectivity gates. |
+| `/arscontexta:reflect` | Find connections for new notes. Semantic judgment to identify genuine relationships, update MOCs. |
+| `/arscontexta:reweave` | Update older notes with new connections. The backward pass — "if written today, what would be different?" |
+| `/arscontexta:verify` | Combined quality verification: description quality test, schema compliance, per-note health checks |
+| `/arscontexta:validate` | Schema compliance checking against template `_schema` blocks |
+
+### Orchestration (4 commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:seed` | Create extraction task from source material with duplicate checking |
+| `/arscontexta:ralph` | Queue processing with fresh context per phase. Spawns isolated subagents for quality. |
+| `/arscontexta:pipeline` | End-to-end source processing: seed → reduce → all claims → archive |
+| `/arscontexta:tasks` | View and manage the task queue |
+
+### Growth (2 commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:learn` | Research a topic using available research tools (Exa, web search) and grow your knowledge graph |
+| `/arscontexta:remember` | Mine session artifacts for persistent learnings. Captures operational corrections to `ops/methodology/`. |
+
+### Evolution (6 commands)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:health` | Platform-aware diagnostic health checks |
+| `/arscontexta:architect` | Research-backed evolution advice with implementation steps. Detects configuration drift. |
+| `/arscontexta:reseed` | Principled restructuring when drift becomes systemic — re-derives from updated understanding |
+| `/arscontexta:refactor` | Targeted structural improvements |
+| `/arscontexta:rethink` | Challenge system assumptions against accumulated observations and tensions |
+| `/arscontexta:upgrade` | Apply plugin updates to an existing generated system |
+
+### Domain Management (1 command)
+
+| Command | Purpose |
+|---------|---------|
+| `/arscontexta:add-domain` | Extend an existing system with a new knowledge domain |
+
+### Command Architecture
+
+Commands come from two sources:
+
+- **10 plugin-level commands** in `skills/` — onboarding, navigation, evolution, and domain management. These ship with the plugin and work immediately.
+- **16 generated commands** from `skill-sources/` — processing, orchestration, growth, and diagnostics. These are vocabulary-transformed during `/setup` and written to the user's `.claude/skills/` directory with domain-native names.
+
+Generated commands use domain vocabulary: a therapy vault's `/surface` (reduce) and `/find-patterns` (reflect) do the same thing as a research vault's `/reduce` and `/reflect`, but in language that fits the domain.
+
+---
+
+## Hooks
+
+Four hooks automate quality enforcement and session continuity:
+
+| Hook | Event | What It Does |
+|------|-------|-------------|
+| **Session Orient** | `SessionStart` | Injects workspace tree, loads identity and methodology from self/, surfaces maintenance signals and reminders, provides session orientation |
+| **Write Validate** | `PostToolUse` (Write to notes/) | Schema enforcement on every note write — checks required fields, enum values, description quality |
+| **Auto Commit** | `PostToolUse` (Write, async) | Auto-commits file changes to git. Runs asynchronously so it doesn't block the agent. |
+| **Session Capture** | `Stop` | Persists session state (notes created, modified, discoveries) to `ops/sessions/`, auto-commits artifacts |
+
+Hooks are defined in `hooks/hooks.json` and reference scripts in `hooks/scripts/`. For Claude Code, they fire via the platform's event system. For OpenClaw, equivalent behavior is documented in the generated AGENTS.md.
+
+---
+
+## Processing Pipeline
+
+The vault implements the **6 Rs**, extending Cornell Note-Taking's 5 Rs with a meta-cognitive layer.
+
+### The 6 Rs
+
+| Phase | What Happens | Command |
+|-------|-------------|---------|
+| **Record** | Zero-friction capture. Everything enters through inbox/. Speed beats precision. | Manual capture |
+| **Reduce** | Extract insights from sources. Domain-native categories with selectivity gates. | `/arscontexta:reduce` |
+| **Reflect** | Find connections, update MOCs. Semantic judgment for genuine relationships. | `/arscontexta:reflect` |
+| **Reweave** | Update older notes with new connections. The backward pass. | `/arscontexta:reweave` |
+| **Verify** | Combined quality check: description test + schema validation + health checks. | `/arscontexta:verify` |
+| **Rethink** | Challenge system assumptions against accumulated evidence. | `/arscontexta:rethink` |
+
+### Fresh Context Per Phase
+
+Each processing phase runs in its own context window. This is not a convenience — it's a quality requirement. LLM attention degrades as context fills. By spawning a fresh subagent for each phase, every phase operates in the "smart zone."
+
+The `/arscontexta:ralph` command orchestrates this:
+
+```
+/arscontexta:ralph 5
+  ├── Read queue, find next unblocked task
+  ├── Spawn subagent for that phase (fresh context)
+  │   └── Subagent: runs skill, updates task file, returns handoff
+  ├── Parse handoff, capture learnings
+  ├── Advance phase in queue
+  └── Repeat for 5 tasks
+```
+
+### Queue-Based Orchestration
+
+Every note flows through a lifecycle tracked in `ops/queue/`:
+
+```
+create → reflect → reweave → verify → done
+```
+
+Each phase appends to a per-claim task file. Downstream phases see what upstream phases discovered. If a subagent crashes mid-phase, the queue still shows the failed phase — re-running `/ralph` picks it up automatically.
+
+### End-to-End Processing
+
+For processing a complete source file from start to finish:
+
+```
+/arscontexta:pipeline inbox/article.md
+```
+
+This chains: seed (create task) → reduce (extract claims) → process all claims through reflect/reweave/verify → archive the batch with a summary.
+
+---
+
+## Platform Support
+
+Three platform tiers with different automation ceilings:
+
+| Aspect | Claude Code | OpenClaw | Minimal |
+|--------|------------|----------|---------|
+| Context file | `CLAUDE.md` | `SOUL.md` + `AGENTS.md` | `README.md` |
+| Skills | `.claude/skills/` | `skills/` (external) | None |
+| Hooks | `.claude/hooks/` (bash) | TypeScript hooks | None |
+| Automation ceiling | Full | Partial | Convention only |
+| Session start | Hook auto-injects tree | Must load manually | Agent instructed to `ls` |
+| Three-space architecture | Identical | Identical | Identical |
+
+**The principle:** The three-space architecture (self/, notes/, ops/) is platform-invariant. Only the context file format and automation infrastructure differ. The intellectual workspace is structurally identical across all platforms.
+
+Claude Code is the primary target with the richest automation. OpenClaw support generates appropriate context files and skill formats. Minimal tier generates a self-contained conventions document for environments without hook or skill support.
+
+---
+
+## Semantic Search
+
+### What qmd Provides
+
+[qmd](https://github.com/tobi/qmd) combines BM25 full-text search with vector embeddings and LLM re-ranking. It enables:
+
+- **Concept matching across vocabularies** — find notes about "learning friction" when the note says "errors as feedback"
+- **Duplicate detection** — catch same-idea-different-words before creating redundant notes
+- **Connection discovery** — find genuinely related notes that share no keywords
+
+### Installation
+
+```bash
+# macOS
+brew install tobi/tap/qmd
+
+# Initialize in your vault
+cd your-vault/
+qmd init
+qmd update && qmd embed
+```
+
+The plugin bundles MCP configuration (`.mcp.json`) that connects qmd as an MCP server automatically. Skills use MCP tools (`mcp__qmd__query`, `mcp__qmd__vsearch`, `mcp__qmd__search`) for search operations.
+
+### Without qmd
+
+The system works fully without semantic search. All commands fall back to:
+
+1. **ripgrep** — keyword-based YAML metadata queries, backlink detection
+2. **MOC traversal** — following wiki links through the topic hierarchy
+3. **Graph analysis scripts** — structural queries (orphans, bridges, triangles)
+
+Semantic search adds discovery power but is never a dependency. The dual discovery path (semantic + structural) ensures search failures never block work.
+
+### Search Modes
+
+| Mode | MCP Tool | Speed | Best For |
+|------|----------|-------|----------|
+| Keyword | `mcp__qmd__search` | ~0.2s | Exact terms, filename lookup |
+| Vector | `mcp__qmd__vsearch` | ~5s | Semantic matching, duplicate detection |
+| Hybrid | `mcp__qmd__query` | ~20s | Deep connection finding with LLM reranking |
+
+---
+
+## The Research Graph
+
+The `methodology/` directory contains **249 interconnected research claims** about tools for thought, knowledge management, and agent-native cognitive architecture. These claims back every configuration decision the derivation engine makes.
+
+### What It Synthesizes
+
+- **Zettelkasten** — atomic notes, bidirectional linking, emergent structure
+- **Cornell Note-Taking** — the 5 Rs (Record, Reduce, Recite, Reflect, Review)
+- **Evergreen Notes** — continuous rewriting, composability, note-as-API
+- **PARA** — project/area/resource/archive organization
+- **GTD** — capture, clarify, organize, reflect, engage
+- **Memory Palaces** — spatial organization, navigation as cognition
+- **Cognitive Science** — extended mind thesis, spreading activation, generation effect, working memory limits, attention residue
+- **Network Theory** — small-world topology, betweenness centrality, community detection
+- **Agent Architecture** — context window constraints, session boundaries, multi-agent collaboration
+
+### How Claims Back Decisions
+
+Every kernel primitive includes `cognitive_grounding` linking it to specific research. For example:
+
+- **MOC hierarchy** grounds in context-switching cost research (Leroy 2009) — MOCs reduce the 23-minute reorientation penalty
+- **Description field** grounds in progressive disclosure — each discovery layer reveals more but costs more tokens
+- **Wiki links** ground in spreading activation — reading one note primes related notes through explicit edges
+
+The `/arscontexta:ask` command lets you query this research graph directly: "Why does my system use atomic notes?" returns the relevant claims with reasoning.
+
+---
+
+## Project Structure
+
+```
+arscontexta/
+├── .claude-plugin/
+│   └── plugin.json              # Plugin manifest (name, version, description)
+├── bin/
+│   └── cli.mjs                  # npx installer entry point
+├── skills/                      # 10 plugin-level commands (always available)
+│   ├── setup/                   # Conversational onboarding
+│   ├── help/                    # Contextual guidance
+│   ├── tutorial/                # Interactive walkthrough
+│   ├── ask/                     # Query the research graph
+│   ├── recommend/               # Architecture analysis
+│   ├── architect/               # Evolution advice
+│   ├── reseed/                  # Principled restructuring
+│   ├── upgrade/                 # Apply plugin updates
+│   ├── add-domain/              # Multi-domain extension
+│   └── health/                  # Diagnostic checks
+├── skill-sources/               # 16 generated command templates
+│   ├── reduce/                  # Extract insights
+│   ├── reflect/                 # Find connections
+│   ├── reweave/                 # Update old notes
+│   ├── verify/                  # Combined quality check
+│   ├── validate/                # Schema compliance
+│   ├── seed/                    # Create extraction task
+│   ├── ralph/                   # Queue orchestration
+│   ├── pipeline/                # End-to-end processing
+│   ├── tasks/                   # Queue management
+│   ├── stats/                   # Vault metrics
+│   ├── graph/                   # Graph analysis
+│   ├── next/                    # Next-action recommendation
+│   ├── learn/                   # Research and grow
+│   ├── remember/                # Mine session learnings
+│   ├── rethink/                 # Challenge assumptions
+│   └── refactor/                # Structural improvements
+├── agents/
+│   └── knowledge-guide.md       # Subagent for pipeline work
+├── hooks/
+│   ├── hooks.json               # Hook configuration manifest
+│   └── scripts/                 # Hook implementation scripts
+├── generators/
+│   ├── claude-md.md             # CLAUDE.md generation template
+│   ├── agents-md.md             # AGENTS.md generation template (OpenClaw)
+│   ├── soul-md.md               # SOUL.md generation template (OpenClaw)
+│   └── features/                # 17 composable feature blocks
+│       ├── atomic-notes.md
+│       ├── wiki-links.md
+│       ├── mocs.md
+│       ├── processing-pipeline.md
+│       ├── semantic-search.md
+│       ├── schema.md
+│       ├── maintenance.md
+│       ├── self-evolution.md
+│       ├── methodology-knowledge.md
+│       ├── session-rhythm.md
+│       ├── templates.md
+│       ├── ethical-guardrails.md
+│       ├── helper-functions.md
+│       ├── graph-analysis.md
+│       ├── personality.md
+│       ├── self-space.md
+│       └── multi-domain.md
+├── methodology/                 # 249 interconnected TFT research claims
+├── reference/                   # Core reference documents
+│   ├── kernel.yaml              # 15 kernel primitives
+│   ├── three-spaces.md          # Three-space architecture
+│   ├── use-case-presets.md      # 3 presets with pre-validated configs
+│   ├── interaction-constraints.md  # Dimension coupling rules
+│   ├── failure-modes.md         # 10 failure modes with vulnerability matrix
+│   ├── vocabulary-transforms.md # 6 vocabulary transformation levels
+│   ├── personality-layer.md     # 4 personality dimensions
+│   ├── conversation-patterns.md # 5 worked derivation examples
+│   └── validate-kernel.sh       # Kernel primitive validation script
+├── platforms/                   # Platform-specific adapters
+│   ├── claude-code/
+│   ├── openclaw/
+│   └── shared/
+├── presets/                     # Pre-validated configurations
+│   ├── research/
+│   ├── personal/
+│   └── experimental/
+├── openclaw/                    # OpenClaw-specific files
+├── scripts/                     # Utility scripts
+├── package.json                 # NPM manifest
+└── README.md
+```
+
+---
+
+## Development
+
+### Testing Locally
+
+Load the plugin for a single session without installing:
+
+```bash
+git clone https://github.com/agenticnotetaking/arscontexta.git
+claude --plugin-dir ./arscontexta
+```
+
+This lets you iterate on skills, hooks, generators, and reference files with immediate feedback.
+
+### Validating
+
+```bash
+# Validate plugin structure
+claude plugin validate ./arscontexta
+
+# Run kernel validation on a generated vault
+cd your-test-vault/
+bash .claude/plugins/arscontexta/reference/validate-kernel.sh
+```
+
+### Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make changes — the key directories are `skills/`, `skill-sources/`, `generators/features/`, and `reference/`
+4. Test with `claude --plugin-dir ./` against a fresh vault
+5. Submit a pull request
+
+### Key Files for Contributors
+
+- `reference/kernel.yaml` — the 15 primitives define what every system must include
+- `generators/features/*.md` — feature blocks are the composable units of context file generation
+- `skill-sources/*/SKILL.md` — generated command templates that get vocabulary-transformed
+- `skills/setup/SKILL.md` — the derivation engine (the most complex single file)
+- `reference/use-case-presets.md` — preset definitions with dimension values
+
+---
+
+## Philosophy
+
+The name connects to a tradition. **Ars Combinatoria**, **Ars Memoria**, **Ars Contexta**: the art of context.
+
+Ramon Llull's rotating wheels generated truth through combination. Giordano Bruno's memory wheels created millions of image combinations. They were external thinking systems — tools to think with rather than just store in. The missing piece was that they required a human mind to do the traversing.
+
+Now LLMs can traverse. The wheels can spin again.
+
+### Tools for Thought for Agents
+
+Just as Zettelkasten, evergreen notes, and memory palaces gave humans external structures to think with, Ars Contexta gives agents an external structure to think with. The agent builds structure optimized for retrieval and expansion. The vault extends cognition across sessions.
+
+The methodology transfers because it encodes cognitive science — working memory limits, extended mind thesis, spreading activation, generation effect — not domain specifics. The note structure is universal: prose-title + YAML metadata + body + wiki-links. Only the vocabulary and field names change between research, relationships, learning, therapy, and life management.
+
+### Derivation, Not Templating
+
+Templates give you a folder structure. Derivation gives you a knowledge architecture with every choice justified.
+
+The difference: a template says "put your notes here." A derived system says "your domain has these characteristics, which map to these dimension positions, which produce this specific architecture, because of these research findings." When something doesn't work, you can trace the decision back to its reasoning and adjust the specific dimension — not throw away the whole template and start over.
+
+Built on [Tools for Thought for Agents](https://github.com/agenticnotetaking) research.
+
+---
+
+## License
+
+MIT