mishkan-harness 0.2.0 → 0.2.3

package/docs/research/graphify-token-saving-poc.md

@@ -0,0 +1,108 @@
+# Graphify token-saving POC — MISHKAN harness
+
+> Status: **verified** — measured 2026-06-07 on the MISHKAN harness.
+> Closes the D-008 "Out of Scope" item 1: the 71.5× third-party claim
+> needed an instrumented MISHKAN measurement before any agent could
+> cite it. This document IS that measurement.
+
+## Setup
+
+```
+graphify CLI : v0.8.33 (PyPI package: graphifyy, binary: graphify)
+install      : uv tool install graphifyy
+harness rev  : c27d58c (main, package.json v0.2.0)
+scan command : graphify update .
+bench command: graphify benchmark
+host         : AiobiDev, 2026-06-07
+```
+
+The wall clock for the initial AST extraction was **27.8 s** for 205 files
+on a single host with 12 parallel workers. The semantic LLM-enrichment step
+was skipped (no `GEMINI_API_KEY` / `GOOGLE_API_KEY`) because the deterministic
+AST extraction is what produces the token-saving leverage — the LLM step
+adds community naming, not structure.
+
+## Graph stats
+
+```
+files scanned : 205    (.py, .ts, .js, .sh, .md, .yml, .json)
+nodes         : 2,370
+edges         : 2,526
+communities   : 268
+artefacts     : graphify-out/{graph.json, graph.html, GRAPH_REPORT.md, manifest.json}
+```
+
+## Corpus baseline
+
+The "naive full-corpus" baseline is the token cost of feeding every file
+of the harness as raw text into the model context (what an unaided agent
+does when asked a structural question and grep-then-read takes it through
+many files).
+
+```
+total words    : 118,500
+token estimate : ~158,000  (graphify's tokenizer, comparable to Anthropic's)
+```
+
+## Results
+
+Graphify's built-in `benchmark` command issues five canonical structural
+questions and measures the average token cost via the graph-BFS query path
+vs the naive baseline.
+
+| Question | Tokens via Graphify | Reduction factor |
+|---|---:|---:|
+| how does authentication work | ~2,116 | **74.7×** |
+| what is the main entry point | ~1,842 | **85.8×** |
+| how are errors handled | ~1,115 | **141.8×** |
+| what connects the data layer to the api | ~2,278 | **69.4×** |
+| what are the core abstractions | ~1,619 | **97.6×** |
+| **Average** | **~1,793** | **88.1×** |
+
+Spread: **69.4×** (worst) to **141.8×** (best). Variance is driven by how
+localised the answer is in the graph — "core abstractions" pulls many
+small community labels; "error handling" hits a tight cluster.
+
+## Interpretation
+
+The third-party 71.5× claim **lands inside the observed range** and the
+MISHKAN-specific average is **+23 % higher** (88.1× vs 71.5×). The
+harness has more Python and shell than the third-party benchmark corpora,
+and Python's AST shape gives Graphify cleaner structural edges than
+TS/JSX-heavy codebases — that's the plausible explanation.
+
+For the five MISHKAN code-writing specialists (Hizkiah, Salma, Oholiab,
+Nathan, Zadok), this means a single `graphify query` answers a
+structural question at **~1.8k tokens** vs **~158k tokens** to lift the
+full harness into context. The advisory hook D-009 (telemetry-only
+phase 1, advisory phase 2) is justified by this margin even at the
+worst-case 69×.
+
+## What this measurement does NOT cover
+
+- **Production agent workload.** The five benchmark questions are
+  Graphify's own canonical set, chosen to be representative — they are
+  not the full distribution of MISHKAN-agent structural queries.
+  Phase 1 of D-009 (telemetry-only hook) will gather the real
+  production distribution; if it differs materially, the average above
+  needs re-measuring.
+- **Token quality.** The 88.1× is a tokens-spent ratio, not an
+  answer-quality ratio. Graphify's BFS answer is structurally precise
+  but textually sparse; reading raw files gives more prose context.
+  The trade-off is intentional — agents that need prose still Read
+  after a Graphify query narrows the file set.
+- **Re-scan cadence cost.** The 27.8 s initial scan is one-off; the
+  incremental `graphify update .` after a commit is sub-second on the
+  changed files only. POC didn't measure this — assumed negligible.
+- **LLM-enriched semantic step.** Adding `GEMINI_API_KEY` re-runs the
+  community-naming step which produces nicer summaries but costs LLM
+  tokens. POC ran deterministic-only. The token ratios above are for
+  the deterministic path.
+
+## Reference
+
+- D-008 — three-store knowledge surface (Graphify · Cognee work ·
+  Cognee curated). See `docs/design/MISHKAN_decisions.md`.
+- D-009 — graph-first PreToolUse advisory hook for the five code-writing
+  specialists. Same file.
+- Graphify upstream — https://github.com/safishamsi/graphify.

package/docs/usage/09-workflows.md

@@ -1,8 +1,41 @@
 # 09 — Dynamic Workflows
 
 > Goal: explain when MISHKAN reaches for a dynamic workflow vs ordinary
-> Task delegation, the seven workflows shipped, and the cost gate that
-> keeps the count from drifting up.
+> Task delegation, the **18 workflows shipped** (10 org-level + 8 team-
+> level), the cost gate, and how dynamic workflows relate to the 30+
+> craft skills that drive each team's day-to-day work.
+
+## Three layers, not one
+
+MISHKAN has **three** levels of orchestration. Conflating them produces
+wrong tools at the wrong level:
+
+| Layer | Lives in | Owns | Examples |
+|---|---|---|---|
+| **Dynamic workflows** (org-level) | `payload/mishkan/workflows/*.js` | The whole harness | `mishkan-sprint-close`, `mishkan-release-readiness`, `mishkan-codebase-audit` |
+| **Craft skills** (team / agent-level) | `payload/mishkan/skills/<agent>-<role>-craft/` | One agent or one Team Lead | `hizkiah-backend-impl-craft`, `salma-frontend-impl-craft`, `team-lead-craft` |
+| **Task delegations** (single shot) | inline `Task()` call from main session | The caller | "Bezalel, review this ADR" |
+
+**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).
+
+**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
+them today — every specialist (Hizkiah, Salma, Nathan, etc.) has at
+least one craft skill that codifies "this is how I do my job". Team
+Leads additionally load `team-lead-craft` which captures the
+orchestration shape they apply to their team's daily flow (handoff,
+review, escalation, sprint contribution).
+
+**Task delegations** are the one-off escape hatch — when neither a
+workflow nor a craft skill captures the shape, the main session
+spawns one or more subagents inline.
+
+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.
 
 ## What a workflow is, in one paragraph
 
@@ -30,7 +63,41 @@ The gate MISHKAN applies — **yes only if all three**:
 Anything that fails any of the three is better as Task fan-out from
 the main session.
 
-## The seven workflows
+## Team-level workflows — the 8 shipped (ADR D-010)
+
+Each team also has a small set of **team-level workflows** for the
+recurring high-stakes orchestrations that *only that team* runs. Hard
+cap: 4 per team. Co-owned by PM + CTO per ADR D-010. Day-to-day shipping
+flows (feature ship, refactor, review) stay at the craft-skill layer —
+the team-level workflows are reserved for the orchestrations where
+parallelism + adversarial verification actually change the outcome.
+
+| Team | Workflow | What it does |
+|---|---|---|
+| Chosheb | [`chosheb-feature-ship`](../../payload/mishkan/workflows/chosheb-feature-ship.js) | Design → handoff package (DS fit + a11y + assets + QA) |
+| Panim | [`panim-ds-rollout`](../../payload/mishkan/workflows/panim-ds-rollout.js) | Token change propagated to all consumers (worktree + a11y + visual regression) |
+| Yasad | [`yasad-data-migration-wave`](../../payload/mishkan/workflows/yasad-data-migration-wave.js) | Wave of DB migrations, per-table 4-lens review |
+| Yasad | [`yasad-schema-evolution`](../../payload/mishkan/workflows/yasad-schema-evolution.js) | Zero-downtime phased schema change with rollback |
+| Mishmar | [`mishmar-security-gate`](../../payload/mishkan/workflows/mishmar-security-gate.js) | Pre-merge security gate, 3 lenses + adversarial refute |
+| Migdal | [`migdal-infra-change`](../../payload/mishkan/workflows/migdal-infra-change.js) | Infra change validated by 5 lenses |
+| Migdal | [`migdal-dr-drill`](../../payload/mishkan/workflows/migdal-dr-drill.js) | DR drill — enumerate, simulate, verify, RTO/RPO measurement |
+| Sefer | [`sefer-release-notes`](../../payload/mishkan/workflows/sefer-release-notes.js) | Release notes from git log per category, style-guided |
+
+Day-to-day shipping flows that are *not* workflows (and why):
+
+- **Feature ship cycle** (SRS → CONTRACT → impl → tests → review) — sequential
+  with a small parallel window during review only; Task delegation handles
+  it cheaper than a workflow.
+- **PR review** — handled by craft skills (`huram-frontend-lead-craft`,
+  `zerubbabel-backend-lead-craft`) + Task fan-out when needed.
+- **Component build per design** — shape varies per component too much for
+  a stable script (fail rule 3 of the gate).
+
+Adding a team-level workflow requires PM + CTO joint review per ADR D-010
+(`docs/design/MISHKAN_decisions.md#D-010`). Each team has spare slots
+(cap 4) — candidates compete by recurrence + parallelism + repeatability.
+
+## The 10 org-level workflows
 
 | Workflow | Pattern | Invoked by | Args |
 |---|---|---|---|
@@ -41,6 +108,9 @@ the main session.
 | [`mishkan-architecture-panel`](../../payload/mishkan/workflows/mishkan-architecture-panel.js) | judge panel + impact-fanout + synthesis | Bezalel gates wide-answer architecture decisions | `{ decision, context, horizon? }` |
 | [`mishkan-release-readiness`](../../payload/mishkan/workflows/mishkan-release-readiness.js) | barrier + nested workflow | Nehemiah + Bezalel before every prod deploy | `{ project_root, release_tag, verify_commands, audit_security? }` |
 | [`mishkan-init`](../../payload/mishkan/workflows/mishkan-init.js) | pipeline with overlap | `/mishkan-init` | `{ project_name, project_root, raw_intent, stack_hint? }` |
+| [`mishkan-blast-radius`](../../payload/mishkan/workflows/mishkan-blast-radius.js) | Graphify + 3-lens orthogonal | gated by `/plan` | `{ target, depth?, project, min_sites_to_verify? }` |
+| [`mishkan-knowledge-gap-discovery`](../../payload/mishkan/workflows/mishkan-knowledge-gap-discovery.js) | parallel probe + loop-until-dry | sprint close (optional) | `{ concepts[], project }` |
+| [`mishkan-standards-rollout`](../../payload/mishkan/workflows/mishkan-standards-rollout.js) | per-team translate + verify + ratify | new rule lands in `y4nn-standards.md` | `{ rule_text, rule_id?, scope_hint? }` |
 
 ## How invocation actually happens
 
@@ -59,7 +129,7 @@ If a subagent finds itself needing a workflow (e.g. Phinehas wants a
 codebase audit), the subagent's response surfaces the recommendation
 to the main session, which then decides whether to fire.
 
-## Patterns the seven scripts use
+## Patterns the 10 scripts use
 
 From the [community patterns catalogue](https://github.com/ray-amjad/claude-code-workflow-creator/blob/main/references/patterns.md)
 and Anthropic's docs:

package/docs/usage/10-observability.md

@@ -13,7 +13,7 @@ Two artefacts that ship as one stack:
   network sources into a single in-memory snapshot. Exposes it on a UNIX
   socket as a snapshot + delta + heartbeat NDJSON stream.
 - **`mishkan-watch`** — Textual TUI client. Connects to the daemon socket,
-  renders 5 tabs and a permanent status bar.
+  renders 8 tabs and a permanent status bar, with a project filter on `p`.
 
 See the design doc [`docs/design/MISHKAN_observability.md`](../design/MISHKAN_observability.md)
 for the full event schema, daemon architecture, and TUI layout.
@@ -43,14 +43,30 @@ uv tool install --from ~/.claude/mishkan/observability/watch  mishkan-watch
 
 ## Run
 
-Two processes, two terminals (or two tmux panes):
+Single command — the TUI auto-starts the daemon if its socket isn't
+present, waits up to 8 s for the bind, then opens. The daemon survives
+the TUI's exit so a second `mishkan-watch` (e.g. in another tmux pane)
+connects instantly.
 
 ```bash
-# terminal 1 — daemon, foreground
+mishkan-watch
+```
+
+Power users who want to manage the daemon explicitly (separate logs,
+custom socket path, attached over SSH from another host) can opt out:
+
+```bash
+# terminal 1 — daemon, foreground (logs in your face)
 mishkan-watchd start
 
-# terminal 2 — TUI
-mishkan-watch
+# terminal 2 — TUI; refuses to fork the daemon
+mishkan-watch --no-autostart
+```
+
+Stop the daemon when you're done:
+
+```bash
+mishkan-watchd stop
 ```
 
 Daemon lifecycle is always manual. Auto-start follow-up:
@@ -67,15 +83,22 @@ mishkan-watchd status              # connect, print current snapshot as JSON
 mishkan-watchd stop                # SIGTERM via the PID file
 ```
 
-## The 5 tabs
+## The 8 tabs
 
-| # | Tab | What it answers |
+| Key | Tab | What it answers |
 |---|---|---|
-| 1 | **Live** | "What is happening *right now*?" Active agents, workflows in-flight, current worktrees, Cognee + MCP rollup, rolling feed of every event. Default tab on launch. |
-| 2 | **Agents** | "What did each agent do?" Sessions tree (left) × agent history `DataTable` (centre) × errors panel (right). Per-session current-agent tracking attributes subagent tool calls to the right agent (sourced via `subagent_tail`). |
-| 3 | **Workflows** | "What did each dynamic workflow run?" Cards list (left) × phase tree with fan-out + cost (right). Populated from `workflow_start` events; phase/agent detail lights up as the `Workflow` tool runs. |
-| 4 | **Knowledge** | "Are my Cognee stores up and growing?" Two cards (work + curated, real-time node counts via neo4j HTTP cypher) × recent ops `DataTable` × MCP server status table covering Cognee + every other configured MCP. |
-| 5 | **Activity** | Unified, filterable event stream. Regex filter + type/agent selects. Errors and blocked permissions break the visual rhythm with a separator line. |
+| `1` | **Live** | "What is happening *right now*?" Active agents (with `alias · role` annotation), workflows in-flight, current worktrees, Cognee + Graphify + MCP rollup, rolling feed of every event. Default tab on launch. |
+| `2` | **Agents** | "What did each agent do?" Sessions tree (left, project paths decoded) × agent history `DataTable` (centre) × errors panel (right). Phantom sessions filtered out at the daemon `_confirmed_alive` gate. |
+| `3` | **Workflows** | "What did each dynamic workflow run, and what's *available* to run?" Recent runs (top) + static catalogue parsed from each script's `meta` block (description, when-to-use, phases). Click an entry for detail. |
+| `4` | **Knowledge** | "Are my stores up and growing?" Three cards (work + curated + graphify, real-time counts) × recent ops `DataTable` × MCP server status table. |
+| `5` | **Activity** | Unified, filterable event stream. Regex filter + type/agent selects. Errors and blocked permissions break the visual rhythm with a separator line. |
+| `6` | **Org-Ref** | Read-only browser of the 45-agent org from `org.json`. Tree by team, click a group → mission / charter / Hebrew name; click an agent → role, source, description. |
+| `7` | **Usage** | Harness-wide tokens in/out/cached, cost, context window estimate, request counts. Per-session table sorted by token volume. Detail panel with per-agent attribution + top tools. |
+| `8` | **Skills** | All installed skills (MISHKAN craft + community + plugin) grouped by origin × category. Right panel cross-references each skill to the CTO decisions (ADRs) that mention it. |
+
+**Project filter (`p`)** — default off; press `p` to scope Live's ACTIVE
+and WORKTREES to the current project only. Current project picked from
+`CLAUDE_PROJECT_DIR` env var or `pwd` at launch.
 
 ## The status bar
 
@@ -109,7 +132,8 @@ Six daemon sources, each independent and fail-open:
 ## Keybindings
 
 ```
-1-5     switch tab (instantaneous)
+1-8     switch tab (instantaneous)
+p       toggle project filter (current ↔ all)
 q       quit
 j/k ↑↓  move focus within current panel
 tab     move focus between panels

package/docs/usage/11-graphify.md

@@ -0,0 +1,264 @@
+# 11 — Graphify (code-structure graph)
+
+> Goal: use Graphify as the **structural** layer of the MISHKAN
+> three-store knowledge stack (Graphify · Cognee work · Cognee curated)
+> so that "who calls X" / "what depends on Y" questions cost ~1.8k
+> tokens instead of lifting the whole repo into context.
+
+## What it is
+
+[Graphify](https://github.com/safishamsi/graphify) is a tree-sitter
+based code-graph extractor with a query path that traverses the graph
+to answer structural questions. MIT, Python, `uv tool install`-able.
+Per D-008 of the MISHKAN decision log, Graphify is the third store of
+the knowledge stack:
+
+| Store | Question it answers | Source |
+|---|---|---|
+| **Graphify** | *How is the code structured?* | tree-sitter AST + optional LLM enrichment, deterministic, re-derivable |
+| **Cognee work** | *Why does this code exist and what did we decide?* | agent-ingested ADRs, runbooks, resolved research |
+| **Cognee curated** | *What did we learn on other projects?* | seeded, read-only from projects |
+
+These are non-overlapping by design: one writer per store, one
+question type per store, no semantic mixing. The crisp test:
+**structure → Graphify, semantics → Cognee work.**
+
+## Install
+
+```bash
+uv tool install "graphifyy>=0.8.33"
+graphify --version
+```
+
+The PyPI package is `graphifyy` (double-y), the binary is `graphify`.
+The `>=0.8.33` pin matters — earlier 0.8.x had a test-file-orphan bug
+(test imports didn't resolve to file-level edges, so test files looked
+disconnected from the source they covered). Fixed in 0.8.33.
+
+Useful soft-breaking change in 0.8.29 to be aware of: project-local
+providers under `./.graphify/providers.json` no longer auto-load by
+default. Set `GRAPHIFY_ALLOW_LOCAL_PROVIDERS=1` if you use per-project
+LLM providers (the deterministic AST path doesn't need this).
+
+## Bring up the graph for a project
+
+From the project root:
+
+```bash
+graphify update .
+```
+
+First run on the MISHKAN harness: **205 files → 2,370 nodes → 27.8 s**.
+Subsequent `graphify update .` runs are incremental and sub-second on
+warm cache.
+
+**Keep the graph fresh — install the git hooks.** The canonical
+maintenance path (recommended by the upstream community, not cron):
+
+```bash
+graphify hook install   # registers post-commit / post-checkout / post-merge / post-rewrite
+                        #   + a `graphify-json` git merge driver so the graph
+                        #     union-merges on parallel branches (no conflicts)
+graphify hook status
+graphify hook uninstall # later, if you want to remove them
+```
+
+Without the hooks the graph drifts vs HEAD silently — symptoms (from
+upstream issues): `graphify query` returns stale `file:line` citations,
+`GRAPHIFY_OUT/GRAPH_REPORT.md` stays at the old node count after a
+refactor. The hooks rebuild incrementally in milliseconds; the merge
+driver makes `graph.json` conflict-free across branches.
+
+Output lives in `<project>/graphify-out/`:
+
+```
+graphify-out/
+├── graph.json          # the AST graph (consumed by `graphify query`)
+├── graph.html          # interactive visualisation, open in a browser
+├── GRAPH_REPORT.md     # god-nodes + anomalies + community summary
+└── manifest.json       # quick stats (nodes / edges / communities)
+```
+
+> `graphify-out/` is gitignored in this repo (project-local artefact,
+> re-derivable). On your own projects, decide per-project whether to
+> commit it; the harness convention is to NOT commit it.
+
+## Querying
+
+```bash
+graphify query "who calls process_payment"
+graphify query "what depends on the User model" --budget 1500
+graphify affected "process_payment" --depth 3
+graphify path "ClassA" "ClassB"
+graphify explain "MishkanWatch"
+```
+
+Default budget is 2000 tokens; the answer is plain text with `file:line`
+citations.
+
+POC numbers on the MISHKAN harness (2026-06-07):
+
+| Question | Tokens | Ratio vs naive baseline |
+|---|---:|---:|
+| how does authentication work | ~2,116 | 74.7× |
+| what is the main entry point | ~1,842 | 85.8× |
+| how are errors handled | ~1,115 | 141.8× |
+| what connects the data layer to the api | ~2,278 | 69.4× |
+| what are the core abstractions | ~1,619 | 97.6× |
+| **average** | **~1,793** | **88.1×** |
+
+Naive baseline = lifting all 118,500 words / ~158,000 tokens of source
+into the model context (Graphify's own README methodology). Full
+method: `docs/research/graphify-token-saving-poc.md`.
+
+> **Important footnote on the 88.1×.** This is a *mixed-corpus,
+> naive-baseline* ratio — the same methodology as Graphify's upstream
+> 71.5× claim. Third-party measurements on *real Claude / Cursor
+> sessions* (where the assistant already scopes) report much smaller
+> reductions: roughly **7-8×** on small targeted sessions, **7-30×**
+> on real codebases. Treat 71.5× / 88.1× as **directional**, not
+> spec-grade: they prove "Graphify costs orders of magnitude less than
+> reading everything" — they don't prove "your next chat session costs
+> 88× fewer tokens." The advisory hook (D-009) keeps emitting telemetry
+> alongside the advisory injection — the firing-vs-graphify-query ratio
+> on real sessions is the data path to tighten this claim.
+
+## How MISHKAN agents use it
+
+Twenty code-touching dev agents across all six teams (per D-009
+amended scope, 2026-06-07) load **graphify-query-craft**: Yasad backend
+(Hizkiah, Nathan, Zadok, Shallum, Uriah) · Panim frontend (Salma,
+Oholiab, Asaph, Jahaziel) · Chosheb UI (Hiram) · Mishmar code-security
+(Ira, Joab, Hushai) · Migdal infra-code (Palal, Meshullam, Meremoth,
+Hanun) · Sefer code-documentation (Joah, Shevna, Jehonathan). Its core
+rule:
+
+> Structure question → `graphify query`.
+> Semantic question → Cognee work.
+
+The PreToolUse hook **`pre-tool-knowledge-route.sh`** (D-009 amendment
+2026-06-07 — Phase 2 shipped) routes the agent to the right knowledge
+surface. On every structural Read / bare-identifier Grep, it does two
+things:
+
+- **Emits telemetry**: a `hook_fire` event on the bus. The Knowledge
+  tab's activity counter records it.
+- **Injects a 4-surface palette** via
+  `hookSpecificOutput.additionalContext` listing every knowledge surface
+  MISHKAN exposes, with pre-formed commands and per-surface signals so
+  the agent picks the right one — not graphify by default.
+
+The four surfaces (D-008 + this amendment):
+
+| Surface | Question it answers |
+|---|---|
+| **CODE STRUCTURE** (Graphify) | "who calls X", "what depends on Y", "path between A and B", impact / blast-radius |
+| **THIS project's MEMORY** (Cognee work) | "why did WE decide X", "what's OUR convention", "what was resolved last sprint" — ADRs, runbooks, past research |
+| **CROSS-PROJECT REFERENCE** (Cognee curated) | "what does the spec say about X", "what did we learn on OTHER projects" — shared read-only library |
+| **Literal file content / text match** (Read or Grep) | "what's in THIS specific file", "every line containing this exact string" |
+
+The advisory carries **real signals** inlined per call, so the agent
+doesn't pick blind:
+
+- Graph node + edge count, last-scan age (with `(stale — /code-graph scan to refresh)` flag when > 1h)
+- For Grep on a bare identifier: a `jq` check on `graph.json` says whether the target is actually a node in the graph. If not, the advisory explicitly warns "don't burn ~1.8k tokens on a seedless query"
+- For Read: the file's line count and an approximate token cost (`~lines × 4`)
+- Cognee work and curated node counts (from the daemon's poll cache at `~/.cache/mishkan/cognee-counts.json`) so "(0 nodes — nothing ingested yet)" replaces a misleading recommendation
+
+The hook never sets `permissionDecision` — purely advisory, the
+Read/Grep still proceeds. When the project has no `graphify-out/`
+directory the CODE STRUCTURE line flips to an install hint; the cognee
+lines stay since the MCP surface is independent of graphify state.
+
+No pre-cooked verdict ("soft" vs "strong") and no invented thresholds.
+Threshold tuning is the D-011 telemetry workflow's job (`hook_fire` vs
+`graphify_query` / `cognee_op` rates, reviewed at `/sprint-close`).
+
+Performance contract for the hook: ≤50 ms p95, fail-open everywhere.
+
+## Knowledge-tab observability
+
+The TUI's **Knowledge** tab surfaces Graphify activity alongside Cognee
+in the "Recent ops" panel:
+
+- `graphify_scan` events fire when `graphify-out/graph.json` mtime
+  changes (i.e. after `graphify update .` completes). The event payload
+  carries `nodes`, `edges`, `communities` from the manifest.
+- `graphify_query` events fire when `graphify save-result` lands a new
+  file under `graphify-out/memory/`. The payload carries the question
+  + a 200-char excerpt of the answer.
+
+Both events come from the daemon source `graphify_tail` (Python
+asyncio, polls every 5 s, fail-open).
+
+## When NOT to use Graphify
+
+Per D-008's "what NOT to do" list:
+
+- Don't use Graphify to answer SEMANTIC questions ("why is this
+  deprecated?"). Those go to Cognee work.
+- Don't use it on a project that doesn't have a `graphify-out/` dir —
+  the cost of an initial scan (~28 s on a 200-file repo) is not paid
+  for a single one-off structural question. Fall back to grep / Read.
+- Don't cite a graph answer without the `file:line` citations from the
+  query output — "according to the graph" without an id is fabrication.
+
+## Known limitations (community-sourced)
+
+- **Dynamic dispatch / reflection** — `getattr`, `eval`,
+  dict-of-callables, runtime monkey-patching are invisible to AST.
+  Recent 0.8.x added cross-language type-reference edges that recover
+  *some* missing links via type context, but the gap stays.
+- **Runtime configuration** (env vars, feature flags, DI containers,
+  Spring-like wiring) — not in the AST. Community recipe: feed the YAML/
+  JSON config files as docs into the same graph; Graphify's multi-modal
+  ingest will surface them as nodes.
+- **`GRAPHIFY_OUT` env var ignored by `query` / `path` / `explain`** —
+  upstream issue still open at research time. If you relocate
+  `graphify-out/`, pass `--graph <path>` explicitly instead.
+- **`./.graphify/providers.json` no longer auto-loads** (0.8.29
+  soft-break). Set `GRAPHIFY_ALLOW_LOCAL_PROVIDERS=1` if you use
+  per-project provider configs.
+
+## Refreshing the graph
+
+Graphify indexing is **manual** — there is no auto-update on file
+changes today. Three equivalent ways to refresh:
+
+```bash
+graphify update .                            # direct CLI
+npx mishkan-harness code-graph scan          # MISHKAN wrapper
+/code-graph scan                             # slash command (same wrapper)
+```
+
+A read-only inspection of the current graph (no rebuild):
+
+```bash
+npx mishkan-harness code-graph status        # nodes / edges / last scan timestamp
+/code-graph status                           # same
+npx mishkan-harness code-graph open          # opens graph.html in the browser
+```
+
+When the advisory hook fires and you suspect the graph is stale, the
+hook's own advisory text reminds you to run `npx mishkan-harness
+code-graph scan` first.
+
+## Project init
+
+`/mishkan-init` (per the updated skill) optionally runs the initial
+`graphify update .` after the spec chain lands, so the project has a
+graph from sprint S0 onwards. Skipped automatically on projects that
+opted out of the structural layer.
+
+## See also
+
+- [D-008](../design/MISHKAN_decisions.md#d-008) — three-store knowledge
+  epistemology.
+- [D-009](../design/MISHKAN_decisions.md#d-009) — graph-first PreToolUse
+  advisory hook (Phase 1 telemetry-only at v0.2.1, Phase 2 advisory
+  injection planned).
+- [POC report](../research/graphify-token-saving-poc.md) — verified
+  88.1× reduction on the MISHKAN harness, 2026-06-07.
+- [Memory layer](./04-memory-layer.md) — the Cognee work and curated
+  stores that complete the three-store stack.
+- Upstream — https://github.com/safishamsi/graphify.