mishkan-harness 0.1.0

package/docs/usage/02-project-init.md

@@ -0,0 +1,151 @@
+# 02 — Project initialisation
+
+> Goal: take a directory and turn it into a MISHKAN project: rules, deny-list,
+> MCP connections, and a `CLAUDE.md` carrying sprint state.
+
+## When and where to run it
+
+```bash
+cd <project root>
+claude              # opens a Claude Code session
+/mishkan-init       # invokes the init skill
+```
+
+`/mishkan-init` is a **skill** (lives at
+`~/.claude/mishkan/skills/mishkan-init/SKILL.md`) and also exposed as a
+command. It is **not** something an agent should run unprompted — there is an
+explicit precondition check.
+
+## The four artifacts it always writes
+
+| File | Role | Tracked? |
+|---|---|---|
+| `CLAUDE.md` | project state: sprint slot, code orientation, two-store note | yes |
+| `.mcp.json` | declares both cognee MCP servers (`cognee` + `cognee-curated`) | yes |
+| `.claude/settings.json` | deny-list: `git push`, `ssh`, `sudo`, `docker exec` | yes |
+| `.claude/settings.local.json` | local allow-list; gitignored | no (added to `.gitignore` if absent) |
+
+Plus the **7 path-scoped team rules** copied to `.claude/rules/` so they JIT-load
+only on matching files (see [Orchestration](./03-orchestration.md)).
+
+## Scope choice — greenfield vs brownfield
+
+The skill detects whether the repo is empty or already mature and asks how much
+of the spec spine to run. Two common answers:
+
+- **Harness wiring only** — drop the four artifacts + rules, do not generate
+  PRD/SRS/CONTRACT/ARCHITECTURE/THREAT_MODEL. Right for a mature repo with
+  existing docs (the aiobi-mail case during the build).
+- **Full init** — run the documented sequence with the right specialists writing
+  each spec. Right for greenfield. Slow on purpose: nothing is generated without
+  upstream artifacts existing.
+
+The full sequence (when chosen):
+
+1. **Nehemiah** writes `docs/PRD.md`.
+2. **Nathan** (Yasad) writes `docs/SRS.md`.
+3. **Zadok** (Yasad) writes `docs/CONTRACT.md` — *invariants + guarantees*.
+4. **Bezalel + Nathan** write `docs/ARCHITECTURE.md`.
+5. **Benaiah** (Mishmar) writes `docs/THREAT_MODEL.md` (STRIDE).
+6. **Meshullam** (Migdal) writes `docs/diagrams/C4/` (Context, Container, Component).
+7. **Jehoshaphat** (Sefer) scaffolds `docs/README.md`, `docs/adr/`, `docs/runbooks/`.
+8. **Automated** cognee setup (see below).
+9. **Automated** project `CLAUDE.md` write + sprint S0.
+
+Each step that touches a contract requires `/plan` to run first.
+
+## Step 8 in detail: cognee setup at init
+
+Two parts run automatically at init:
+
+1. **Ensure the curated box** (global singleton, shared across projects).
+   `~/.claude/mishkan/scripts/ensure-curated-box.sh` is idempotent: it brings up
+   the curated stack if down, creates `curated_db`, and seeds only if the
+   curated graph is empty. It is safe to run repeatedly.
+
+2. **Selectively seed the work store** for this project, **never bulk-ingest**.
+   `/mishkan-init` runs:
+   ```bash
+   bash ~/.claude/mishkan/scripts/mishkan-ingest.sh --tagged-only
+   ```
+   That walks `./docs/` looking for files with a `mishkan: ingest` YAML
+   frontmatter tag and ingests *only* those. Untagged docs are ignored.
+   The whole point is memory is opt-in: see
+   [Selective ingest](./05-selective-ingest.md) and commit `6213611`.
+
+## What `CLAUDE.md` carries
+
+A lean, dynamic file that loads **after** the user-level identity. It carries:
+
+- Codebase orientation (stack, key directories) — concrete facts the
+  main session needs every turn.
+- Sprint slot — *current sprint*, *what's in flight*, *blockers*. Updated by
+  `/mishkan-resume`, `/sprint-close`, and you.
+- Note that there are two cognee stores (`cognee` = work, `cognee-curated` =
+  reference) and that `cognee-curated` is read-only.
+- A pointer to the existing `docs/` if there is one (does not duplicate).
+
+## Brownfield handling — what does *not* happen
+
+- **No overwrites.** Existing `README.md`, `CLAUDE.md`, and `docs/*` are left
+  alone. If a project `CLAUDE.md` already exists, the agent surfaces it and
+  asks before merging.
+- **No translation.** If the existing docs are in another language (the
+  aiobi-mail repo was largely French), the MISHKAN docs are written in English
+  per rule 12 of `y4nn-standards.md`, alongside the existing corpus.
+- **No reverse-engineered PRD.** If you pick "harness wiring only", no spec
+  spine is fabricated.
+
+## Confirming a clean init
+
+After `/mishkan-init` completes:
+
+```bash
+# the four artifacts
+ls -la .mcp.json CLAUDE.md .claude/settings.json .claude/settings.local.json
+
+# rules installed
+find .claude/rules -type f | sort
+
+# settings.local.json gitignored
+grep -E '\.claude/settings\.local\.json' .gitignore
+
+# the two cognee servers declared
+python3 -c "import json; print(list(json.load(open('.mcp.json'))['mcpServers'].keys()))"
+# expected: ['cognee', 'cognee-curated']
+```
+
+## Verifying the MCP connections (next session)
+
+MCP servers connect **at session start** — so the session that ran
+`/mishkan-init` does *not* yet have `mcp__cognee__*` tools available. Open a new
+session in the same directory:
+
+```bash
+exit          # leave the current session
+claude        # fresh session
+/mcp          # in the session: should list 'cognee' and 'cognee-curated'
+```
+
+## Common edge cases
+
+- **No remote / private repo:** `.mcp.json` is tracked; do not put secrets in
+  it. The cognee MCP URLs point at `http://localhost:7777` and `:7730` — your
+  own host, no third-party endpoints.
+- **Multiple projects on one host:** safe. The curated box is shared
+  (singleton); the work store holds each project as its own dataset, keyed by
+  the project directory basename by default (see
+  [Selective ingest](./05-selective-ingest.md) for the dataset naming
+  rules).
+- **Running init twice:** safe. The four artifacts are not overwritten; the
+  curated ensure step is idempotent; rules are re-copied verbatim.
+
+## See also
+
+- The init skill source: `payload/mishkan/skills/mishkan-init/SKILL.md`
+  (commit `a9a4bf1` wired the curated-box step; commit `6213611` made step 8
+  selective).
+- [Orchestration](./03-orchestration.md) — how the main session routes work
+  once init has run.
+- [Memory layer](./04-memory-layer.md) — the two cognee stores and what they
+  hold.

package/docs/usage/03-orchestration.md

@@ -0,0 +1,218 @@
+# 03 — Orchestration
+
+> Goal: explain how work actually flows once you've started a session in a
+> MISHKAN-initialised project, with the platform constraints that shape it.
+
+## The single most important fact
+
+**Claude Code has no nested delegation.** A subagent cannot spawn another
+subagent — confirmed in the official subagent docs. The `Task` tool in a
+subagent's frontmatter is **inert** when the subagent runs.
+
+```
+You ──talk──▶  MAIN SESSION  = leadership                ← orchestrator
+                    │
+                    ├─Task→ Team Lead / Specialist       ┐
+                    ├─Task→ project-specific agent       │  one level deep
+                    └─Task→ research pipeline            ┘  siblings, no nesting
+              then main session SYNTHESISES their outputs
+```
+
+Three things follow:
+
+1. **The main session is leadership.** It loads the MISHKAN identity from
+   `~/.claude/CLAUDE.md` and acts as Nehemiah (PM) and Bezalel (CTO)
+   simultaneously. **Do not invoke the `nehemiah` subagent to orchestrate** —
+   a spawned Nehemiah can't delegate either.
+
+2. **Delegation is description-driven**, not config-table driven. There is no
+   "task → agent" YAML. The `Task` tool reads each agent's `description:`
+   frontmatter and picks one, guided by the `## Routing` prose in
+   `~/.claude/CLAUDE.md` and the main session's own judgement.
+
+3. **Team Lead agents (e.g. `eliashib` for Migdal infrastructure) advise and
+   plan**, they don't spawn specialists. The main session calls the Lead for
+   strategy and the specialists for execution.
+
+## The cast (one level deep, all callable by the main session)
+
+**Two orchestrators** — these *inform* the main session's identity via
+CLAUDE.md; you can also call them explicitly as subagents for second opinions.
+
+| Alias | Role |
+|---|---|
+| `nehemiah` | PM — scope, delivery, sprint state |
+| `bezalel` | CTO — technical standards, architecture, quality bar |
+
+**Six teams.** Within each, `Lead → Specialists → QA → Reporter`. QA and
+Reporters are structurally separate from the producing agents — no agent grades
+its own work.
+
+| Team | Domain | Notable agents |
+|---|---|---|
+| **Chosheb** | Design / UX | `aholiab` (lead), `hiram` (UI), `deborah` (cognitive UX) |
+| **Panim** | Frontend | `huram` (lead), `oholiab` (design system), `salma` (impl), `asaph` (a11y), `jahaziel` (QA) |
+| **Yasad** | Backend | `zerubbabel` (lead), `nathan` (architecture), `zadok` (contracts), `hizkiah` (impl), `shallum` (DB), `uriah` (QA) |
+| **Mishmar** | Security (cross-cutting) | `phinehas` (lead), `ira` (code-sec, runs the security hook), `benaiah`, `joab` |
+| **Migdal** | Infrastructure | `eliashib` (lead), `meshullam` (design), `palal` (systems), `meremoth` (devops), `hanun` (devsecops), `rehum` (SRE) |
+| **Sefer** | Documentation (pull-based) | `jehoshaphat` (lead), `seraiah` / `joah` / `shevna` (org/project/team), `jehonathan` (publication) |
+
+**Research pipeline** (6 stages): `jakin` → `ezra` → `caleb` → `shaphan` →
+`shemaiah` → `baruch`. Each stage is a single-purpose agent. The pipeline is
+also a skill (`research-pipeline`) the main session can invoke whole.
+
+Full glossary including each agent's role: [Glossary](./08-glossary.md).
+Naming rationale: [`docs/design/MISHKAN_agent_aliases.md`](../design/MISHKAN_agent_aliases.md).
+
+## Model routing — `model-routing.yaml` is authoritative
+
+Every agent has a Claude model tier (`opus` / `sonnet` / `haiku`). The mapping
+lives in [`payload/mishkan/config/model-routing.yaml`](../../payload/mishkan/config/model-routing.yaml)
+and is **enforced at delegation time** by a `PreToolUse` hook that intercepts
+the `Task` tool call and injects the right `model` via
+`hookSpecificOutput.updatedInput`.
+
+```
+config/model-routing.yaml   ← edit here (single source of truth)
+        ↓
+hooks/model-route.py        ← PreToolUse on Task|Agent
+        ↓
+Task tool input gets `model: <tier>` injected
+        ↓
+subagent runs on the right tier, regardless of its frontmatter
+```
+
+Important nuance baked into the hook (`c6c5645`): it **only injects for agents
+explicitly listed in the YAML**. Foreign agents (e.g. `aiobi-ops`, `Explore`)
+keep their own frontmatter model — never silently downgraded.
+
+Tier rationale (from the YAML header):
+
+| Tier | Who | Why |
+|---|---|---|
+| Opus | orchestrators, Team Leads, knowledge publication | judgement-heavy |
+| Sonnet | senior specialists, anything that **writes code** | precision on the codebase |
+| Haiku | QA (evaluate-only), Reporters (collect-only), pure advisors | cost-sensitive, no risk to code |
+
+To change a tier: **edit the YAML**, not the agent frontmatter. The hook makes
+the YAML win.
+
+## Skills — invoked on demand, never preloaded
+
+Each agent has the `Skill` tool in its `tools:` allowlist. When the agent reads
+a skill name in its prompt and decides it applies, it invokes the skill on the
+fly. **No `skills:` frontmatter preload** is used — that would inject the full
+SKILL.md text into the agent's context on every startup for every preloaded
+skill, across 45 agents. The cost rationale is captured in
+`~/.claude/mishkan/AGENTS_SKILLS.md`.
+
+How an agent knows which skills to reach for: each agent's prompt carries a
+short **"Skills (invoke on demand)"** section listing its specific skills.
+Salma's, for example: `react-modernization`, `nextjs-app-router-patterns`,
+`responsive-design`, `modern-javascript-patterns`.
+
+Skills shipped by MISHKAN itself (orchestrating the 150+ user skills):
+
+| Skill | Purpose |
+|---|---|
+| `mishkan-init` | scaffold a project (see [02](./02-project-init.md)) |
+| `mishkan-ingest` | selectively add docs to the work cognee (see [05](./05-selective-ingest.md)) |
+| `research-pipeline` | run Jakin→Ezra→Caleb→Shaphan→Shemaiah→Baruch |
+| `sprint-report` | a Reporter assembles `team-report.json` at milestone |
+| `cognee-promote` | promote knowledge with blast-radius routing |
+| `cognee-quickstart` | bring cognee up if it's not running yet |
+| `context-compress` | Cognee-offload helper for long sessions |
+| `sefer-pull` | trigger doc updates at milestones or high-blast events |
+| `dependency-vetting` | vet a single dep via the research pipeline |
+| `dependency-audit` | per-project supply-chain audit |
+
+## Hooks — the binding layer
+
+Hooks make the rules deterministic; rules and prompts alone wouldn't be enough.
+
+| Event | Script | What it does |
+|---|---|---|
+| `PreToolUse: Write|Edit|MultiEdit` | `pre-tool-security.sh` (Ira) | scan writes for secrets, eval, SQL string-concat, unsafe execution; block on match |
+| `PreToolUse: Task|Agent` | `model-route.py` | inject the model tier from `model-routing.yaml` |
+| `PreToolUse: Bash` | the existing bun command-validator (preserved) | command validation |
+| `PostToolUse: *` | `post-tool-observe.sh` | append one observability log entry per tool call |
+| `Stop` | `stop-reporter.sh` | if the stopped agent declares `role: reporter`, fire the `sprint-report` skill |
+
+The security hook is the one you'll notice — it caught the Gemini API key during
+the build (commit `e17f2a9` added a documented exception path for runtime
+secret injection into gitignored `.env` files).
+
+## MCP tools in subagents — explicit, not inherited
+
+A real gotcha worth flagging: **Claude Code does not give a subagent access to
+the main session's MCP servers automatically.** A subagent (anything spawned
+via `Task`) can only call MCP tools that appear in its own `tools:` frontmatter
+allowlist. If you see *"MCP tool not in subagent context"* during a research
+run, this is the cause.
+
+Tool names follow the pattern `mcp__<server>__<tool>`. The four MISHKAN agents
+whose job *is* cognee work have the relevant entries pre-wired:
+
+| Agent | Cognee tools in its allowlist |
+|---|---|
+| `ezra` (research formulator) | `mcp__cognee__search`, `mcp__cognee-curated__search` |
+| `shemaiah` (research evaluator) | `mcp__cognee__search`, `mcp__cognee-curated__search` |
+| `baruch` (research reporter) | `mcp__cognee__search`, `mcp__cognee__add`, `mcp__cognee__cognify`, `mcp__cognee__memify` |
+| `jehonathan` (knowledge publication) | `mcp__cognee__search` |
+
+The other 41 agents do not have cognee MCP access by default — they don't need
+it. If you add a new agent whose work depends on cognee, add the specific MCP
+tools to its `tools:` line. Don't grant the whole MCP server unless the agent
+genuinely needs every operation; the principle is the same as the deny-list
+philosophy below.
+
+The fallback pattern when an agent legitimately needs cognee but doesn't have
+the tools: **the main session does the MCP call**. The subagent returns a
+structured payload; the main session reads it and calls `mcp__cognee__add` /
+`mcp__cognee__cognify` itself. Slower than direct access but always available.
+
+## Deny-list and asymmetric delegation
+
+Two layers of "the agent never does this":
+
+- **Project `settings.json`** (seeded by init) — deny: `git push`, `ssh`,
+  `sudo`, `docker exec`.
+- **Standards** (rules layer, baked in) — *"stateful operations stop at the
+  engineer's hands"*: schema-migration execution, log-forensics execution,
+  production access.
+
+These are not soft preferences. They are the boundary between generative work
+(safe to delegate one-shot) and stateful work (one mistake is not reversible
+by re-prompting).
+
+## Routing in practice — a DevOps example
+
+You: *"Get aiobi-mail off the staging stack's stale iptables rules without
+touching production."*
+
+Main session (acting as leadership):
+
+1. Reads the codebase orientation in `CLAUDE.md` for context.
+2. Searches cognee `work` store for past incidents touching this area.
+3. Spawns `eliashib` (Migdal lead) to plan the work — returns a routing
+   recommendation.
+4. Spawns `palal` (systems specialist) to inspect the iptables state — returns
+   findings.
+5. Spawns `aiobi-ops` (your project-specific ops agent) for the staging-stack
+   reality (servers, gotchas, incident history).
+6. Synthesises 3, 4, 5 into a concrete plan with exact commands.
+7. Hands you the commands. You run them.
+
+Migdal agents and `aiobi-ops` did **not** talk to each other — they are
+siblings, one level deep. The synthesis was the main session's job.
+
+## See also
+
+- Plan / decision file behind the model-routing hook: commit `c6c5645`,
+  `payload/mishkan/hooks/model-route.py`.
+- Skill wiring decisions: `~/.claude/mishkan/AGENTS_SKILLS.md` (instance-local).
+- Research pipeline shape:
+  [`docs/design/MISHKAN_harness_design.md`](../design/MISHKAN_harness_design.md)
+  §5.
+- Token economy / context architecture:
+  [`docs/design/MISHKAN_token_optimisation.md`](../design/MISHKAN_token_optimisation.md).

package/docs/usage/04-memory-layer.md

@@ -0,0 +1,201 @@
+# 04 — Memory layer (cognee)
+
+> Goal: explain what the harness stores, where, how it gets there, and how
+> agents query it. This is the layer that makes MISHKAN *accumulate* rather
+> than just function.
+
+## Two physically-isolated stores (decision D-007)
+
+Cognee runs locally on the host as a Docker stack. The core architectural
+choice (introduced in commit `418d10a`, documented in
+[`docs/design/MISHKAN_decisions.md`](../design/MISHKAN_decisions.md) §D-007):
+
+```
+        shared Ollama (embeddings, local) ─┐ stateless, serves both
+        shared Postgres server ────────────┤ separate databases
+                                            │
+  WORK box  :7777  (cognee)                 CURATED box  :7730  (cognee-curated)
+  own Neo4j + cognee_db                     own Neo4j + curated_db
+  ── per-project knowledge ──               ── cross-project reference ──
+  • aiobi-mail        (project dataset)     • curated_library (96 nodes seed)
+  • claude_code_memory (per-client memory)  • read-mostly
+  UI :7724 · Neo4j :7716/:7709              UI :7734 · Neo4j :7731/:7732
+```
+
+Why two stores and not one?
+
+- **PII isolation.** Project ingestion pulls in code and docs that can contain
+  PII (real email addresses in incident reports were the trigger during the
+  build). The cross-project curated library must stay clean.
+- **Logical tags aren't enough on Neo4j Community.** Community Edition allows
+  only one database per Neo4j instance, and with cognee's access control
+  disabled (the only mode that works against Neo4j today) all datasets share
+  one graph. So logical dataset tags commingle in one store. Physical
+  separation = a separate Neo4j container.
+
+The `claude_code_memory` dataset is the **per-client session memory**, created
+on demand by cognee-mcp when Claude Code connects. **It belongs in the work
+store and must never be pruned** (D-007 calls this out explicitly).
+
+## The data flow
+
+```
+docs / project content                          curated resources (small, static)
+       │                                                  │
+       ▼                                                  ▼
+   cognee.add()    ← raw files staged              add_data_points()  ← structured
+       │                                                  │
+   cognify()       ← LLM extracts entities          (no LLM — embeddings only)
+       │             + relationships                     │
+       ▼                                                  ▼
+   memify()        ← embeds the triplet layer       memify() optional
+       │             into the vector store
+       ▼
+   search()        ← retrieval (vector + graph)
+```
+
+Each phase, in words:
+
+- **`add`** stages files for processing. The raw file content is stored under
+  the cognee data root (must be on a volume — see [Troubleshooting](./07-troubleshooting.md)
+  and commit `e24fabf`).
+- **`cognify`** is the LLM-heavy step. It chunks each document, calls the LLM
+  to extract entities and relationships as structured output (instructor mode),
+  embeds chunks + entities, and writes to Neo4j + pgvector. This is the step
+  that costs LLM tokens and runs into rate caps.
+- **`memify`** is the enrichment step that runs **after** cognify. The default
+  enrichment embeds the **edge / triplet** layer into the vector store
+  (`EdgeType_relationship_name` and `graph_relationship_ledger` tables in
+  pgvector). After memify, retrieval becomes **relationship-aware** — graph
+  topology in Neo4j is unchanged; the vector store gains the triplet index.
+- **`search`** retrieves (vector + optionally graph) and is exposed via the
+  cognee MCP. Agents call it.
+
+The session's wiring commit (`210f92b`) makes `cognify → memify` automatic in
+the curated seed and in `/mishkan-init` step 8 — extraction is always followed
+by enrichment, never manually.
+
+## The MCP — how agents reach memory
+
+Every MISHKAN-initialised project declares **both** servers in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "cognee":          { "type": "http", "url": "http://localhost:7777/mcp" },
+    "cognee-curated":  { "type": "http", "url": "http://localhost:7730/mcp" }
+  }
+}
+```
+
+So when an agent searches, it can target either store explicitly:
+
+- `cognee` — read+write the project's own graph (typical).
+- `cognee-curated` — read the cross-project reference library (typical for
+  Shemaiah cross-referencing curated resources).
+
+MCP servers connect at **session start**. A fresh session is needed for
+`/mishkan-init`-written `.mcp.json` to take effect.
+
+## Datasets — the logical layer inside each store
+
+Datasets are cognee's logical partitioning. In the work store, every project
+gets its own dataset (named after the project directory by convention). A
+typical work store after a few projects:
+
+```
+datasets (work / cognee_db)
+├── aiobi-mail              (14 docs, project knowledge)
+├── claude_code_memory      (per-client session memory)
+└── <next-project>          (created on its first ingest)
+```
+
+In the curated store there is one dataset (`curated_library`) — the cross-project
+reference seed.
+
+To query a specific dataset, pass `datasets=[...]` to `cognee.search`. This is
+the only way to keep retrieval *logically* clean within a store; the *physical*
+isolation between work and curated is by separate Neo4j containers.
+
+## Visualising the graph
+
+Two ways for each store:
+
+### Cognee Graph Explorer UI
+
+- **Work**: `http://localhost:7724`, backend `:7737`.
+  Login = `DEFAULT_USER_EMAIL` / `DEFAULT_USER_PASSWORD` from `.env`.
+- **Curated**: `http://localhost:7734`, backend `:7733` (added in commit `751f95e`).
+  Login = `DEFAULT_USER_EMAIL` / `DEFAULT_USER_PASSWORD` from `.env.curated`.
+
+### Neo4j Browser (raw graph)
+
+| Store | HTTP | Bolt | Credentials |
+|---|---|---|---|
+| Work | `http://localhost:7716` | `bolt://localhost:7709` | `neo4j` + work `GRAPH_DATABASE_PASSWORD` |
+| Curated | `http://localhost:7731` | `bolt://localhost:7732` | `neo4j` + curated `GRAPH_DATABASE_PASSWORD` |
+
+Important: use the `bolt://` scheme in the browser's connect URL, **not**
+`neo4j://`. The `neo4j://` scheme triggers routing discovery that fails over an
+SSH tunnel — a real gotcha from the build (see
+[Troubleshooting](./07-troubleshooting.md)).
+
+A good Cypher to render the curated structure:
+
+```cypher
+MATCH (t:Team)-[r:resources]->(c:CuratedResource) RETURN t, r, c
+```
+
+## Tunnelling from a remote host
+
+If cognee runs on a remote VPS, forward the relevant ports:
+
+```bash
+tsh ssh -N \
+  -L 7724:127.0.0.1:7724 -L 7737:127.0.0.1:7737 \
+  -L 7716:127.0.0.1:7716 -L 7709:127.0.0.1:7709 \
+  -L 7734:127.0.0.1:7734 -L 7733:127.0.0.1:7733 \
+  -L 7731:127.0.0.1:7731 -L 7732:127.0.0.1:7732 \
+  <user>@<host>
+```
+
+Only what you want to look at. The MCP itself doesn't need a tunnel — the
+agent runs on the host where cognee is, and the cognee MCP listens on
+`127.0.0.1` already.
+
+## What gets written when, and what to back up
+
+| Layer | Where | Persistence | Back up? |
+|---|---|---|---|
+| Graph (Neo4j) | volumes `cognee_neo4j_data`, `curated_neo4j_data` | docker volume | yes (high value) |
+| Vector + relational (Postgres) | volume `cognee_pgdata` | docker volume | yes |
+| Raw ingested files + cognee system metadata | volume `cognee_data` (mounted at `/app/cognee-mcp/.cognee_system`) | docker volume | yes (commit `e24fabf` made this volume-backed; before that, every `up --force-recreate` wiped the raw files) |
+| Ollama models | volume `ollama_models` | docker volume | re-pullable |
+
+`docker volume inspect mishkan-cognee_cognee_data` shows where on disk the
+volume lives. Standard restic / rsync covers it.
+
+## Configuration anchors
+
+- Work box env: `~/.claude/mishkan/cognee/.env` (gitignored, mode 600).
+- Curated box env: `~/.claude/mishkan/cognee/.env.curated` (gitignored, mode 600).
+- Compose entrypoint: `docker-compose.yml` + overlays (`hardening`, `selfhosted`,
+  `ui`, `curated`, `curated-ui`).
+- Curated singleton helper: `scripts/ensure-curated-box.sh` (idempotent).
+- Selective seeding from a project: `scripts/mishkan-ingest.sh` (see
+  [chapter 05](./05-selective-ingest.md)).
+
+## See also
+
+- The two-store rationale: [D-007](../design/MISHKAN_decisions.md) and
+  commit `418d10a`.
+- Curated UI overlay: commit `751f95e`.
+- Storage persistence fix: commit `e24fabf`.
+- Curated structured ingestion (low-level): commit `086e80e`,
+  `payload/mishkan/cognee/ingest-curated.py`.
+- Ontology definitions:
+  [`docs/design/MISHKAN_ontology.md`](../design/MISHKAN_ontology.md).
+- LLM/embedding strategy:
+  [LLM provider profiles](./06-llm-providers.md).
+- How to add knowledge: [Selective ingest](./05-selective-ingest.md).
+- When things break: [Troubleshooting](./07-troubleshooting.md).