mishkan-harness 0.2.6 → 0.2.7

package/docs/usage/01-installation.md

@@ -88,7 +88,7 @@ Phases:
 6. **Stamp** — record version + timestamp for `status` / `uninstall` to read.
 7. **Observability (opt-in)** — prompts to install `mishkan-watchd` and
    `mishkan-watch` via `uv tool`. Skipped cleanly if `uv` isn't on PATH; you
-   can re-run it later with `npx mishkan-harness observability`.
+   can re-run it later with `npx mishkan-harness observability install`.
 
 ## Verify the install
 
@@ -114,10 +114,22 @@ cat ~/.claude/mishkan/.install-stamp.json 2>/dev/null
 
 ## Bring the cognee memory stack up
 
-The harness ships the memory layer as a Docker Compose stack. Two boxes:
-**work** (per-project knowledge, port `:7777`) and **curated** (shared reference
-library, port `:7730`). See [memory layer](./04-memory-layer.md) for the
-full design.
+The harness ships the memory layer as a Docker Compose stack. Three pillars:
+**per-project work stores** (one isolated Ladybug container per project,
+provisioned at `/mishkan-init`), **cognee-memory** (`:7777`, shared per-client
+session memory), and **cognee-curated** (`:7730`, shared reference library).
+See [memory layer](./04-memory-layer.md) for the full design (D-007 + D-012).
+
+The guided path is one command — it preflights the config, names any gap, then
+brings up the shared stack (base + hardening + selfhosted overlays) and seeds the
+curated box:
+
+```bash
+mishkan knowledge configure        # wizard: LLM_API_KEY + provider profile → .env (see chapter 06)
+mishkan knowledge-stack up         # memory :7777 + curated :7730, idempotent (~5 min cold start)
+```
+
+<details><summary>What <code>knowledge-stack up</code> wraps, if you prefer the manual steps</summary>
 
 ```bash
 cd ~/.claude/mishkan/cognee
@@ -126,8 +138,8 @@ cd ~/.claude/mishkan/cognee
 cp .env.example .env
 # … fill LLM_API_KEY and pick a provider profile (see chapter 06)
 
-# 2. bring up the work stack (always with the hardening overlay)
-docker compose -f docker-compose.yml -f docker-compose.hardening.yml up -d --build
+# 2. bring up the stack (base + hardening + selfhosted overlays)
+docker compose -f docker-compose.yml -f docker-compose.hardening.yml -f docker-compose.selfhosted.yml up -d --build
 
 # 3. bring up the curated box (one-time per host, idempotent helper)
 bash ~/.claude/mishkan/scripts/ensure-curated-box.sh
@@ -136,6 +148,8 @@ bash ~/.claude/mishkan/scripts/ensure-curated-box.sh
 bash ~/.claude/mishkan/scripts/seed-curated-library.sh
 ```
 
+</details>
+
 Health checks:
 
 ```bash
@@ -187,7 +201,7 @@ The installer's phase 7 asks whether to install the cross-session observability
 stack. You can also run it standalone any time:
 
 ```bash
-npx mishkan-harness observability
+npx mishkan-harness observability install
 ```
 
 Requirements: `uv` (https://astral.sh/uv) and Python 3.11+. If `uv` is not on

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

@@ -52,7 +52,20 @@ The full sequence (when chosen):
 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.
+```mermaid
+flowchart TD
+    PRD["1 · Nehemiah<br/>docs/PRD.md"] --> SRS["2 · Nathan<br/>docs/SRS.md"]
+    SRS --> CON["3 · Zadok<br/>docs/CONTRACT.md"]
+    CON --> ARC["4 · Bezalel + Nathan<br/>docs/ARCHITECTURE.md"]
+    ARC --> TM["5 · Benaiah<br/>docs/THREAT_MODEL.md · STRIDE"]
+    TM --> C4["6 · Meshullam<br/>docs/diagrams/C4/"]
+    C4 --> DOCS["7 · Jehoshaphat<br/>README · adr · runbooks"]
+    DOCS --> KN["8 · automated<br/>cognee setup"]
+    KN --> CL["9 · automated<br/>CLAUDE.md + Sprint S0"]
+```
+
+Each step that touches a contract requires `/plan` to run first — nothing is generated
+without its upstream artifact.
 
 ## Step 8 in detail: cognee setup at init
 
@@ -81,8 +94,10 @@ A lean, dynamic file that loads **after** the user-level identity. It carries:
   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.
+- Note that init provisions two project-level MCP aliases (`cognee` = this
+  project's work store, `cognee-curated` = shared reference library; the latter
+  is read-only). The third cognee store — `cognee-memory` (`:7777`, shared
+  session memory) — is a pre-existing singleton, not provisioned here.
 - A pointer to the existing `docs/` if there is one (does not duplicate).
 
 ## Brownfield handling — what does *not* happen
@@ -110,7 +125,8 @@ find .claude/rules -type f | sort
 # settings.local.json gitignored
 grep -E '\.claude/settings\.local\.json' .gitignore
 
-# the two cognee servers declared
+# the two project-level cognee aliases written to .mcp.json
+# (cognee-memory is a shared singleton; it does not appear in per-project .mcp.json)
 python3 -c "import json; print(list(json.load(open('.mcp.json'))['mcpServers'].keys()))"
 # expected: ['cognee', 'cognee-curated']
 ```
@@ -130,13 +146,14 @@ claude        # fresh session
 ## 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).
+  it. The cognee MCP URLs point at local ports on your own host — no
+  third-party endpoints. The per-project work store runs on a dynamically
+  assigned port; `cognee-memory` is `:7777`; `cognee-curated` is `:7730`.
+- **Multiple projects on one host:** safe. Each project has its own physically
+  isolated work store container (`mishkan-work-<slug>`) provisioned by
+  `ensure-work-store.sh`. The curated box and the `cognee-memory` (`:7777`)
+  session-memory box are shared singletons. See [Memory layer](./04-memory-layer.md)
+  for the three-pillar layout (D-012).
 - **Running init twice:** safe. The four artifacts are not overwritten; the
   curated ensure step is idempotent; rules are re-copied verbatim.
 
@@ -147,5 +164,5 @@ claude        # fresh session
   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.
+- [Memory layer](./04-memory-layer.md) — the three cognee stores (work,
+  memory, curated) and what they hold.

package/docs/usage/03-orchestration.md

@@ -9,14 +9,19 @@
 subagent — confirmed in the official subagent docs. The `Task` tool in a
 subagent's frontmatter is **inert** when the subagent runs.
 
+```mermaid
+flowchart TD
+    You(["You — talk"]) --> MS[["MAIN SESSION — leadership / orchestrator<br/>acts as Nehemiah (PM) + Bezalel (CTO)"]]
+    MS -->|Task| A["Team Lead / Specialist"]
+    MS -->|Task| B["project-specific agent (e.g. aiobi-ops)"]
+    MS -->|Task| C["research pipeline"]
+    A --> SYN[["main session SYNTHESISES the outputs"]]
+    B --> SYN
+    C --> SYN
 ```
-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
-```
+
+*One level deep, siblings, no nesting* — the main session delegates via `Task`, then
+synthesises. A subagent cannot spawn another: its own `Task` tool is inert.
 
 Three things follow:
 
@@ -57,10 +62,44 @@ its own work.
 | **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) |
 
+```mermaid
+graph TD
+    N[["Nehemiah — PM"]] --- Bz[["Bezalel — CTO"]]
+    Bz --> CH["Chosheb<br/>Design / UX"]
+    Bz --> PA["Panim<br/>Frontend"]
+    Bz --> YA["Yasad<br/>Backend"]
+    Bz --> MI["Migdal<br/>Infrastructure"]
+    Bz --> SE["Sefer<br/>Docs · pull-based"]
+    Bz --> RP["Research pipeline<br/>6 stages · shared"]
+    MM["Mishmar — Security<br/>cross-cutting"]
+    MM -. gates .-> CH
+    MM -. gates .-> PA
+    MM -. gates .-> YA
+    MM -. gates .-> MI
+    MM -. gates .-> SE
+```
+
+*Two orchestrators (the main session embodies both) route to six teams; Mishmar gates
+every team's output; the research pipeline is shared. Within each team: Lead → Specialists
+→ QA → Reporter, with QA and Reporter structurally separate from the producing agents.*
+
 **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.
 
+```mermaid
+flowchart LR
+    J["jakin<br/>clarify"] --> E["ezra<br/>formulate"]
+    E --> Ca["caleb<br/>web research"]
+    Ca --> Sh["shaphan<br/>summarise"]
+    Sh --> Se["shemaiah<br/>evaluate"]
+    Se --> B["baruch<br/>report + Cognee node"]
+    E -. curated library already answers .-> B
+```
+
+*Six single-purpose stages. Ezra short-circuits straight to Baruch when the curated
+library already holds the answer — no web research spent.*
+
 Full glossary including each agent's role: [Glossary](./08-glossary.md).
 Naming rationale: [`docs/design/MISHKAN_agent_aliases.md`](../design/MISHKAN_agent_aliases.md).
 

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

@@ -4,56 +4,96 @@
 > 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
+## Three physically-isolated pillars (decisions D-007 + D-012)
+
+Cognee runs locally on the host as a Docker stack. The current architecture
+has three pillars (D-007 separated work from curated; D-012 further split
+per-project work stores from the shared session-memory box; both documented in
+[`docs/design/MISHKAN_decisions.md`](../design/MISHKAN_decisions.md)):
+
+```mermaid
+flowchart LR
+    OLL[("Ollama<br/>embeddings · local · serves all")]
+    PG[("Postgres server<br/>cognee_db + curated_db")]
+    WORK[("cognee WORK — per-project<br/>mishkan-work-{slug}<br/>embedded Ladybug + LanceDB<br/>own port + volume · isolated")]
+    MEM[("cognee-memory :7777<br/>Neo4j + cognee_db<br/>claude_code_memory · shared · never prune")]
+    CUR[("cognee-curated :7730<br/>own Neo4j + curated_db<br/>curated_library · shared · read-mostly")]
+    OLL -. embeddings .-> WORK
+    OLL -. embeddings .-> MEM
+    OLL -. embeddings .-> CUR
+    PG --- MEM
+    PG --- CUR
 ```
 
-Why two stores and not one?
+*Three physically-isolated pillars (D-007 + D-012). Shared Ollama embeds for all; the
+shared Postgres backs memory + curated; each per-project work store is self-contained
+(embedded Ladybug + LanceDB, own volume) so cross-project reads are impossible by construction.*
+
+Why physical separation and not logical datasets?
 
 - **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).
+  build). The cross-project curated library and session-memory box must stay clean.
+- **`datasets=` filter is advisory-only on Neo4j.** With `ENABLE_BACKEND_ACCESS_CONTROL=false`
+  (the only mode that works against Neo4j Community), cognee ignores the
+  `datasets=` filter and searches the whole graph — verified against cognee
+  v1.1.0 / issue #1023. Logical tags alone do not isolate.
+- **Physical separation = topology.** Each project work store is a separate
+  container + volume + on-disk graph file. Cross-project reads are impossible
+  by construction.
+
+The `claude_code_memory` dataset is the **per-client session memory**, held in
+the `cognee-memory` (`:7777`) box. It is shared across all your work — one
+continuous thing, not re-derivable — and **must never be pruned** (D-012).
+Keep it scrubbed of project-specific secrets and PII because it is
+cross-project by nature.
+
+### Per-project work stores (decision D-012)
+
+D-007 separated *work* from *curated*. **D-012** extends the same physical-
+separation principle one axis further: each project gets its **own** work store,
+not a shared dataset in one box. The trigger was a confidentiality bug — with
+`ENABLE_BACKEND_ACCESS_CONTROL=false` (required on Neo4j) cognee's `datasets=`
+filter is **advisory only**: it is silently ignored and search runs the whole
+graph, so a query scoped to one project returned another project's data (with a
+live API key among it). Verified against cognee v1.1.0 / issue #1023.
+
+The fix: each project runs its own lightweight cognee-mcp container with an
+**embedded Ladybug** graph (no Neo4j) and its own volume — `mishkan-work-<slug>`
+on its own port, provisioned by `ensure-work-store.sh` at `/mishkan-init`.
+Isolation is by topology (container + volume + on-disk graph file), never the
+`datasets=` filter.
+
+Each project's `.mcp.json` then carries **three doorways** (the alias is the
+doorway; the backend behind each differs):
+
+- **`cognee`** → that per-project Ladybug store — isolated project knowledge.
+- **`cognee-memory`** → the **kept** Neo4j box on `:7777`, now holding only
+  `claude_code_memory` — shared per-client session memory, one continuous thing
+  across all your work, not re-derivable, so never fragmented per project or
+  pruned. (Cross-project by nature → keep it scrubbed of project secrets/PII.)
+- **`cognee-curated`** → the shared reference library (`:7730`).
+
+The shared box's old *project* graphs are discarded (re-derivable from tagged
+docs); the box itself is **repurposed** as the session-memory pillar, not retired.
 
 ## 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)
+```mermaid
+flowchart LR
+    subgraph D["docs / project content"]
+      ADD["cognee.add()<br/>stage raw files"] --> CFY["cognify()<br/>LLM extracts entities + relationships"]
+      CFY --> MFY["memify()<br/>embed triplet layer into vector store"]
+      MFY --> SR["search()<br/>retrieval · vector + graph"]
+    end
+    subgraph C["curated resources (small, static)"]
+      ADP["add_data_points()<br/>structured · no LLM"] --> MFY2["memify() (optional)<br/>embeddings only"]
+    end
 ```
 
+*Two write paths into a store: project docs go `add → cognify` (LLM extraction) `→ memify
+→ search`; curated resources are written structurally (`add_data_points`, no LLM — embeddings only).*
+
 Each phase, in words:
 
 - **`add`** stages files for processing. The raw file content is stored under
@@ -62,7 +102,13 @@ Each phase, in words:
 - **`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.
+  that costs LLM tokens and runs into rate caps. Each work store attaches the
+  **MISHKAN ontology** (`ontology.ttl`, the machine form of `ontology.md` — ADR
+  D-013) to cognify via the container's env config (`ONTOLOGY_FILE_PATH` +
+  `rdflib`/`fuzzy`, staged by `ensure-work-store`): entities whose extracted type
+  matches a schema class are validated (`ontology_valid: true`) and enriched with
+  parent-class / object-property edges. Fails open — a missing ontology ingests
+  unconstrained.
 - **`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
@@ -77,63 +123,76 @@ by enrichment, never manually.
 
 ## The MCP — how agents reach memory
 
-Every MISHKAN-initialised project declares **both** servers in `.mcp.json`:
+Every MISHKAN-initialised project declares **three** servers in `.mcp.json`
+(written by `ensure-work-store.sh` at `/mishkan-init`):
 
 ```json
 {
   "mcpServers": {
-    "cognee":          { "type": "http", "url": "http://localhost:7777/mcp" },
-    "cognee-curated":  { "type": "http", "url": "http://localhost:7730/mcp" }
+    "cognee":         { "type": "http", "url": "http://localhost:<per-project-port>/mcp" },
+    "cognee-memory":  { "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:
+The `<per-project-port>` is assigned by `ensure-work-store.sh` at init time
+and recorded in the project's `.mcp.json`. It is NOT `:7777`.
+
+So when an agent searches, it targets the right pillar explicitly:
 
-- `cognee` — read+write the project's own graph (typical).
+- `cognee` — read+write the project's own isolated Ladybug graph (typical for
+  project knowledge retrieval and ingest).
+- `cognee-memory` — read+write per-client session memory (`claude_code_memory`)
+  shared across all work. Use when the agent needs to recall or record
+  cross-session context.
 - `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 — a label inside a store, NOT an isolation boundary
 
-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:
+Within a single store, `datasets` is cognee's logical *label* — by convention the
+project dir name (plus `claude_code_memory` for per-client session memory). It is
+**not a security boundary**: with access control off (the only mode that works on
+Neo4j), `datasets=[...]` on `cognee.search` is **advisory only** — cognee ignores
+it and searches the whole graph (verified, cognee v1.1.0 / issue #1023). Do not
+rely on it to keep one project's retrieval clean of another's.
 
-```
-datasets (work / cognee_db)
-├── aiobi-mail              (14 docs, project knowledge)
-├── claude_code_memory      (per-client session memory)
-└── <next-project>          (created on its first ingest)
-```
+Real isolation is **physical — separate stores**:
 
-In the curated store there is one dataset (`curated_library`) — the cross-project
-reference seed.
+- Curated is a separate store from work (**D-007**).
+- Each project is a separate work store from every other (**D-012** — per-project
+  embedded Ladybug containers).
 
-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.
+So with per-project stores, a project's `cognee` store contains only that
+project's data; the dataset label is cosmetic and a cross-project read is
+impossible by construction. The curated store holds one dataset
+(`curated_library`), the cross-project reference seed.
 
 ## Visualising the graph
 
 Two ways for each store:
 
+Per-project work stores use an embedded Ladybug graph (no Neo4j, no UI).
+The Neo4j-backed pillars (`cognee-memory` and `cognee-curated`) have UIs:
+
 ### Cognee Graph Explorer UI
 
-- **Work**: `http://localhost:7724`, backend `:7737`.
+- **cognee-memory** (`:7777`, session memory): `http://localhost:7724`, backend `:7737`.
   Login = `DEFAULT_USER_EMAIL` / `DEFAULT_USER_PASSWORD` from `.env`.
-- **Curated**: `http://localhost:7734`, backend `:7733` (added in commit `751f95e`).
+- **cognee-curated** (`:7730`, reference library): `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 |
+| Pillar | 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` |
+| cognee-memory (`:7777`) | `http://localhost:7716` | `bolt://localhost:7709` | `neo4j` + work `GRAPH_DATABASE_PASSWORD` |
+| cognee-curated (`:7730`) | `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
@@ -163,6 +222,12 @@ 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.
 
+**Per-project work stores have no web UI to tunnel.** They use an embedded
+Ladybug graph (a file, no server) — there is no Graph Explorer or Neo4j browser
+for them. The ports above are the shared **`cognee-memory`** (`:77xx`) and
+**`cognee-curated`** (`:773x`) UIs only. To inspect a project's own graph, use
+cognee's static-HTML `visualize_graph("./graph.html")` export on the host.
+
 ## What gets written when, and what to back up
 
 | Layer | Where | Persistence | Back up? |
@@ -177,8 +242,9 @@ volume lives. Standard restic / rsync covers it.
 
 ## Configuration anchors
 
-- Work box env: `~/.claude/mishkan/cognee/.env` (gitignored, mode 600).
+- `cognee-memory` box (`:7777`) env: `~/.claude/mishkan/cognee/.env` (gitignored, mode 600).
 - Curated box env: `~/.claude/mishkan/cognee/.env.curated` (gitignored, mode 600).
+- Per-project work store provisioner: `scripts/ensure-work-store.sh` (run at `/mishkan-init`; idempotent).
 - Compose entrypoint: `docker-compose.yml` + overlays (`hardening`, `selfhosted`,
   `ui`, `curated`, `curated-ui`).
 - Curated singleton helper: `scripts/ensure-curated-box.sh` (idempotent).
@@ -187,8 +253,8 @@ volume lives. Standard restic / rsync covers it.
 
 ## See also
 
-- The two-store rationale: [D-007](../design/MISHKAN_decisions.md) and
-  commit `418d10a`.
+- The three-pillar rationale: [D-007](../design/MISHKAN_decisions.md) (work vs curated split),
+  [D-012](../design/MISHKAN_decisions.md) (per-project work stores), commit `418d10a`.
 - Curated UI overlay: commit `751f95e`.
 - Storage persistence fix: commit `e24fabf`.
 - Curated structured ingestion (low-level): commit `086e80e`,

package/docs/usage/06-llm-providers.md

@@ -25,7 +25,8 @@ provider choices.
 
 | Store | Contains | Provider recommendation | Why |
 |---|---|---|---|
-| **Work** (`:7777`) | project knowledge, may contain PII | **Local Ollama LLM** (private, no quota), or paid/no-train cloud, or a free cloud you accept training on | every free cloud tier trains on prompts; PII shouldn't leak |
+| **Per-project work store** (per-project port, Ladybug) | project knowledge, may contain PII | **Local Ollama LLM** (private, no quota), or paid/no-train cloud, or a free cloud you accept training on | every free cloud tier trains on prompts; PII shouldn't leak |
+| **cognee-memory** (`:7777`, session memory) | per-client session memory (`claude_code_memory`) | Local Ollama recommended; treat the same as project work — may reference PII indirectly | cross-session memory accumulates project context |
 | **Curated** (`:7730`) | public reference resources, no PII | Any free cloud (Gemini, NVIDIA catalog, OpenRouter named-free) is fine | nothing sensitive |
 
 **Embeddings should be local** in both stores. Bulk ingest fires many embedding

package/docs/usage/07-troubleshooting.md

@@ -137,6 +137,29 @@ docker run --rm -u 0 -v mishkan-cognee_cognee_data:/v busybox \
 docker compose ... up -d --force-recreate cognee-mcp
 ```
 
+## Per-project work store (Ladybug) — reset or stuck pipeline
+
+The cognify / lock / Postgres fixes above target the shared **`cognee-memory`**
+box (`mishkan-cognee-*`, Postgres-backed). **Per-project work stores (ADR D-012)
+are different:** each is a `mishkan-work-<slug>` container with an embedded
+Ladybug graph + SQLite + LanceDB — no Postgres, no shared graph. So:
+
+- The Postgres `DATASET_PROCESSING_STARTED` lock fix does **not** apply — a stuck
+  per-project pipeline lives in that store's own SQLite, inside its own volume.
+- To **reset** a project's work store cleanly (it is re-derivable from tagged
+  docs), tear it down, drop its volume, re-provision, and re-ingest:
+
+```bash
+cd ~/theY4NN/<project>
+docker compose -p mishkan-work-<slug> \
+  -f ~/.claude/mishkan/cognee/docker-compose.work.yml down -v    # -v drops the volume
+WORK_PORT=$(~/.claude/mishkan/scripts/ensure-work-store.sh)      # re-provision (fresh graph)
+bash ~/.claude/mishkan/scripts/mishkan-ingest.sh --tagged-only   # re-ingest
+```
+
+Never do this to `cognee-memory` (`:7777`) — `claude_code_memory` is **not**
+re-derivable (D-012).
+
 ## Curated library is showing inside the work UI
 
 **Symptom** — the Cognee UI at `:7724` (work backend) shows `CuratedResource`

package/docs/usage/08-glossary.md

@@ -108,9 +108,17 @@ Each stage is a single-purpose agent. The pipeline is also a skill
 | Haiku | 14 | QA, Reporters, pure advisors, research summarise/evaluate/report |
 | **Total** | **45** | |
 
-The mapping is authoritative in
+> *Fable tier dormant.* Claude Fable 5 was briefly assigned to the 8 Migdal+Mishmar
+> specialists (D-002 amend, 2026-06-11) but **suspended 2026-06-12** by an
+> export-control directive; those agents reverted to Sonnet. The routing layer still
+> accepts `fable` as a valid value, so it can be re-enabled if access is restored.
+
+The shipped mapping lives in
 [`payload/mishkan/config/model-routing.yaml`](../../payload/mishkan/config/model-routing.yaml);
 the hook `payload/mishkan/hooks/model-route.py` injects it at delegation time.
+**You can re-tier any agent** with `mishkan model set <agent|team|all> <tier>` (D-017) —
+overrides land in a `model-routing.local.yaml` overlay that survives updates, take effect
+on the next delegation, and win over the shipped defaults above.
 
 ## Key terms
 
@@ -123,9 +131,10 @@ the hook `payload/mishkan/hooks/model-route.py` injects it at delegation time.
 | **Cognify** | the LLM-heavy step that extracts entities + relationships from a document and writes them into the graph. |
 | **Memify** | the enrichment step that runs after cognify and embeds the triplet/edge layer into the vector store. |
 | **Search** | cognee's retrieval, exposed via MCP. Always pass `datasets=[...]` to scope it. |
-| **Work store** | the per-project cognee box (`cognee`, `:7777`). |
+| **Work store** | a per-project cognee-mcp container running an embedded Ladybug graph (no Neo4j), on its own port and volume (`mishkan-work-<slug>`). Provisioned by `ensure-work-store.sh` at `/mishkan-init`. Reached via the `cognee` MCP alias. NOT port `:7777`. |
 | **Curated store** | the cross-project reference cognee box (`cognee-curated`, `:7730`). Read-mostly. |
-| **`claude_code_memory`** | the per-client memory dataset auto-created by cognee-mcp when Claude Code connects to the work store. Never prune it. |
+| **`cognee-memory` (`:7777`)** | the kept Neo4j-backed cognee box repurposed (D-012) to hold only `claude_code_memory` — shared per-client session memory. Reached via the `cognee-memory` MCP alias. |
+| **`claude_code_memory`** | the per-client memory dataset held in the `cognee-memory` (`:7777`) box. Shared across all projects; never prune it. |
 | **`mishkan: ingest`** | the YAML frontmatter tag that marks a doc as eligible for the work store. |
 | **Throttle** | the in-process LLM rate limiter (`LLM_RATE_LIMIT_*` in `.env`). Per-minute only; does not help with daily caps. |
 | **Asymmetric delegation** | the rule that stateful ops (`git push`, `ssh`, `sudo`, production `docker exec`, schema migrations, log forensics) stop at the engineer's hands — never executed by an agent. |

package/docs/usage/09-workflows.md

@@ -1,7 +1,7 @@
 # 09 — Dynamic Workflows
 
 > Goal: explain when MISHKAN reaches for a dynamic workflow vs ordinary
-> Task delegation, the **18 workflows shipped** (10 org-level + 8 team-
+> Task delegation, the **20 workflows shipped** (10 org-level + 10 team-
 > level), the cost gate, and how dynamic workflows relate to the 30+
 > craft skills that drive each team's day-to-day work.
 
@@ -18,8 +18,9 @@ wrong tools at the wrong level:
 
 **Dynamic workflows** orchestrate dozens of agents in parallel with
 typed contracts, adversarial verification, and judge panels. They are
-expensive and bounded — hard cap at 10 in the harness. The gate to
-add one is high (recurrence + parallelism + repeatable shape).
+expensive and bounded — **20 shipped today: 10 org-level (hard cap 10)
++ 10 team-level (cap 4 per team, 6 teams)**. The gate to add one is high
+(recurrence + parallelism + repeatable shape).
 
 **Craft skills** are how each agent ships day-to-day work. They are
 markdown documents loaded into the agent's context. There are 30+ of
@@ -33,6 +34,17 @@ review, escalation, sprint contribution).
 workflow nor a craft skill captures the shape, the main session
 spawns one or more subagents inline.
 
+```mermaid
+graph TD
+    MS[["main session"]]
+    MS --> WF["Dynamic workflows · org + team<br/>workflows/*.js — 20 shipped (10 org + 10 team)<br/>dozens of agents · typed contracts"]
+    MS --> CS["Craft skills · team / agent-level<br/>(agent)-(role)-craft/ — 30+<br/>how each agent ships day-to-day"]
+    MS --> TD["Task delegation · single shot<br/>inline Task() — the one-off escape hatch"]
+```
+
+*Three orchestration layers — reach for a dynamic workflow only when recurrence +
+parallelism + a repeatable shape all hold; otherwise a craft skill or a one-off Task.*
+
 If you find yourself asking "is THIS a workflow?", apply the gate
 below. If it doesn't pass all three, it's probably a craft skill
 addition or a one-shot Task.