# MuseHub Roadmap

**Program:** Knowtation domain — vault-native VCS intelligence for agent knowledge systems.

**Authority:** This document governs work in the **MUSE_HUB workspace** (`gabriel-muse`, `musehub`, and related repos). It is **separate** from Scooling's `docs/ROADMAP.md`. Scooling consumes Knowtation via REST/MCP adapters in parallel; it does not block this track.

**Source spec:** [gabriel/muse issue #2](https://staging.musehub.ai/gabriel/muse/issues/2) (frozen phase order — each phase unlocks the next for *new* work; local code may span multiple phases).

**Handover relay:** `docs/MUSEHUB-OVERSEER-HANDOVER.md` — paste the **NEXT SESSION** block into a fresh chat.

---

## Phase Model Key

| Label | Meaning |
| --- | --- |
| **Thinking** | Contract, architecture, open-question resolution, test matrix — freeze spec before build |
| **Auto** | Mechanical implementation against a frozen spec; run tests; Muse commit on feature branch |
| **Thinking → Auto** | Split into `{step}a` (Thinking) then `{step}b` (Auto) in the handover doc |
| **Operator + Auto** | Tier 3 human authorization for staging push / live gate; Auto for implementation |

**Handover rule:** Every next-step table and paste block **must** include **`Model:`**.

---

## Next step at a glance (2026-07-10)

| Item | Status |
| --- | --- |
| **Active track** | Knowtation domain — staging push + attestation verification |
| **Plugin code (Phases 1–4, 7, KD-5b)** | **DONE locally** — `gabriel-muse/muse/plugins/knowtation/` + `muse/mcp/` (36 MCP tests, 1606 knowtation tests green) |
| **Staging plugin repo** | **DONE** — `aaronrene/gabriel-muse` @ `sha256:660fcac1…` (2026-06-21) — **pre-KD-5b**; re-push needed |
| **Marketplace registration** | **DONE** — `@aaronrene/knowtation` on staging (2026-07-05); `viewer_type: generic` (optional fix) |
| **Vault activation smoke** | **DONE** — `knowtation-vault-smoke` (5 PASS / 3 PARTIAL — see handover matrix) |
| **Open questions (KD-OQ)** | **DONE** (2026-07-10) — all 5 issue #2 questions resolved (see table below) |
| **MCP surface (KD-5b)** | **DONE** (2026-07-10) — 9 tools / 8 resources / 4 prompts at `muse/mcp/`; activation gate; 7-tier + Claude Desktop stdio integration green on `knowtation-vault-smoke` |
| **Vault UI contract (KD-6a)** | **DONE** (2026-07-10) — §KD-6a frozen: 4 page groups (landing, note detail, proposals, vault search), routes, MCP read-mapping, error enums, 7-tier matrix + Playwright E2E |
| **Vault UI (KD-6b)** | **DONE** (2026-07-10) — `knowtation_view` adapter, `ui_vault.py`, templates/SCSS, harmony diff, 7-tier + Playwright E2E green locally |
| **NEXT** | **KD-STAGING** — Tier 3 push gabriel-muse (KD-5b) + musehub (KD-6b) to staging; KD-7 attestation smoke on staging vault |
| **Parked** | — |
| **Parallel (Scooling)** | Phase 9A overseer gates — independent |

---

## Build status table

| ID | Phase | Repo(s) | Model | Status |
| --- | --- | --- | --- | --- |
| **KD-0** | Recovery + rc14 re-baseline | gabriel-muse | Auto | **DONE** (2026-06-20) — corrupt rc3 history discarded; code intact; 1570 tests green |
| **KD-SD8-PUSH** | Push plugin to staging | gabriel-muse | Auto (Tier 3) | **DONE** (2026-06-21) — `aaronrene/gabriel-muse` @ `660fcac1…` |
| **KD-SD8-REG** | Marketplace registration | musehub (API) | Auto (Tier 3) | **DONE** (2026-07-05) — `@aaronrene/knowtation`; `viewer_type: generic` (fix optional) |
| **KD-1** | Domain foundation (detector, parser, plugin, symbols, domain-info) | gabriel-muse | Auto | **DONE** — proven on vault smoke (domain-info PASS; symbols CLI PARTIAL) |
| **KD-2** | Semantic diff & harmony merge | gabriel-muse | Auto | **DONE** — differ/merger API proven; CLI merge/diff PARTIAL (see handover) |
| **KD-3** | Code intelligence (deps, impact, hotspots, dead, clones, entangle, velocity) | gabriel-muse | Auto | **DONE** — deps/impact/hotspots/dead PASS on test vault |
| **KD-4** | Memory timeline (event schema, symbol-log, consolidation hook, prime) | gabriel-muse | Auto | **DONE** — log event_type PASS; prime_context API PASS (no CLI hook) |
| **KD-7** | Attestation & ICP push hook | gabriel-muse | Auto | **DONE** (local; attestation smoke post-activation) |
| **KD-ACTIVATE** | Vault activation + Phase 1–4 smoke | gabriel-muse + test vault | **Auto** | **DONE** (2026-07-10) — `knowtation-vault-smoke`; 5 PASS / 3 PARTIAL |
| **KD-OQ** | Resolve issue #2 open questions (5 items) | gabriel-muse + musehub | **Thinking** | **DONE** (2026-07-10) — 5/5 resolved with source-backed rationale; gate cleared for KD-5a |
| **KD-5a** | MCP domain surface — contract + test matrix | gabriel-muse + musehub | **Thinking** | **DONE** (2026-07-10) — contract frozen (§KD-5a); open items (a)–(e) resolved; 7-tier matrix + Claude Desktop integration test specified |
| **KD-5b** | MCP domain surface — implementation (9 tools, 8 resources, 4 prompts) | gabriel-muse + musehub | Auto | **DONE** (2026-07-10) — `muse/mcp/` server + namespace; 36 MCP tests + stdio E2E green on `knowtation-vault-smoke` |
| **KD-6a** | MuseHub vault UI — contract + test matrix | musehub | **Thinking** | **DONE** (2026-07-10) — contract frozen (§KD-6a); 4 page groups, routes, MCP read-mapping, error enums, 7-tier matrix + Playwright E2E specified |
| **KD-6b** | MuseHub vault UI — implementation | musehub | Auto | **DONE** (2026-07-10) — `knowtation_view` adapter, `ui_vault.py`, vault templates/SCSS, harmony diff, 7-tier + Playwright E2E green locally |
| **KD-STAGING** | Staging push (KD-5b plugin + KD-6b musehub) + KD-7 attestation smoke | gabriel-muse + musehub | **Operator + Auto** (Tier 3) | **NEXT** |

---

## Repo boundaries

| Repo | Role in this program | VCS |
| --- | --- | --- |
| **gabriel-muse** | Canonical home of `muse/plugins/knowtation/` — detector, parser, merger, code intel, attestation | Muse; staging remote `aaronrene/gabriel-muse` |
| **musehub** | Marketplace API, domain registration, Phase 6 vault-centric UI, MCP server mount | Muse / git per repo convention |
| **knowtation** (product) | Vault store, Hub API, MCP — **not** the Muse domain plugin | Separate; Scooling adapter target |
| **knowtation-vault-smoke** | KD-ACTIVATE test vault — **not** product repo | Local Muse repo; `domain=knowtation` |
| **scooling** | Consumer UI — parallel track; wires domain features **after** KD-5/KD-6 land | See Scooling governance docs |

**Important:** The Knowtation **product repo** (`.museattributes` → `domain = "code"`) is not a vault repo. Activation uses a **vault repo** — Markdown notes with Knowtation frontmatter (`source_type`, `source_id`, `project`, `tags`, `entity`).

---

## Phase detail (frozen from issue #2)

### KD-1 — Domain Foundation

**Goal:** Muse recognises Knowtation vault files as a distinct domain and introspects them structurally.

**Deliverables (verified in tree):**

- `detector.py`, `parser.py`, `plugin.py`, `symbols.py`, `stats.py`
- `defaults.museattributes` snippet
- `muse domain-info --json` shape; `muse code symbols --file note.md`

**Exit criteria:** KD-ACTIVATE smoke PASS on a real vault repo — **MET** (domain-info PASS; symbols CLI routes through code AST — gap recorded).

---

### KD-2 — Semantic Diff & Harmony Merge

**Goal:** Section-aware diff; policy-based merge for tags, entities, source_id conflicts.

**Deliverables (verified in tree):**

- `differ.py`, `merger.py`, `policies.py`, `strategies.py`, `rerere.py`
- Harmony policies for tag union, entity union, prefer-newer-date, §Summary escalation

**Exit criteria:** `muse merge` resolves tag/entity conflicts without raw-text panics — **PARTIAL** (`merge_notes` union PASS; `muse merge` CLI file-conflict on tag-only divergence).

---

### KD-3 — Code Intelligence

**Goal:** `muse code deps`, `impact`, `hotspots`, `gravity`, `dead`, `clones`, `entangle`, `velocity` on vault repos.

**Deliverables (verified in tree):**

- `link_index.py`, `code_intel.py`, `note_metrics.py`, `cli_hooks.py`

**Exit criteria:** All six commands return meaningful JSON on test vault — **MET** (deps, impact, hotspots, dead verified).

---

### KD-4 — Memory Timeline

**Goal:** Memory event types in commit metadata; symbol-log as memory replay; prime bootstrap from commit graph.

**Deliverables (verified in tree):**

- `events.py` (15 event kinds, schema locked v1.0.0)
- `hooks.py` (consolidation pre-merge)
- `prime_context.py` (`knowtation://prime` from commit graph)

**Exit criteria:** `muse log --json` surfaces `event_type`; prime JSON smoke PASS — **MET** (log PASS; prime via `build_prime_context` API, no CLI).

---

### KD-5 — MCP Domain Surface (KD-5a contract frozen; KD-5b implementation DONE)

**Status (KD-5b):** **DONE** (2026-07-10). Server at `muse/mcp/`; 9 tools / 8 resources / 4 prompts; activation gate on `repo.json domain==knowtation`; 36 MCP tests + stdio E2E green on `knowtation-vault-smoke`.

**Goal:** Knowtation domain ops via Muse MCP (`knowtation/search`, `get-note`, `history`, `consolidate`, `impact`, `dead`, `prime`, `propose`, `attest` — 9 tools + 8 resources + 4 prompts per issue #2 Phase 5).

**Entry criteria:** KD-ACTIVATE PASS; KD-OQ resolved. **Both MET (2026-07-10).**

**Frozen inputs from KD-OQ:** search backend = Muse structural index + Knowtation live vector index
(OQ2); `knowtation/consolidate` = async dispatch, non-blocking (OQ3); `knowtation/attest` = generic
`MuseAttestationProvider` reusing the ICP canister (OQ4); no `agent.md` merge (OQ5); detection =
frontmatter-primary with optional marker (OQ1).

**Model:** Thinking → Auto (KD-5a Thinking **DONE** — contract frozen below; KD-5b Auto is NEXT).

---

## KD-5a Contract — Muse MCP Domain Surface (`knowtation` namespace) — FROZEN 2026-07-10

**Status:** DONE (Thinking). This section is the **frozen spec** KD-5b (Auto) implements against.
Do not redesign during Build. Interfaces below are the contract; the seven-tier test matrix is
in §KD-5a.F. Implementation-only (KD-5b) items are tagged **[KD-5b new work]**.

**Authority chain:** issue #2 Phase 5 tables (9 tools / 8 resources / 4 prompts) + KD-OQ frozen
decisions (OQ1–OQ5). The prompt count is **4** (issue #2 §5.3 lists 3 and adds
`vault/knowledge-gaps` in its deliverables line; the corrected count is 4 — see change log
2026-07-10).

### KD-5a.0 — Transport, envelope & shared conventions

- **Protocol:** JSON-RPC 2.0 per MCP (`tools/list`, `tools/call`, `resources/list`,
  `resources/read`, `prompts/list`, `prompts/get`).
- **Tool names:** `knowtation/<verb>` (slash-namespaced). **Resource URIs:** `knowtation://…` scheme.
  **Prompt names:** `vault/<name>`.
- **Repo binding:** every call operates on the server's bound repo root (the process CWD's
  `.muse/`); no tool takes a filesystem root argument (prevents path-escape and cross-repo reads).
- **`ref` grammar (shared):** `HEAD` | branch name | full/abbrev sha256 commit id. Resolved via
  `muse.core.store.resolve_commit_ref`; unknown ref → `REF_NOT_FOUND`.
- **`path` grammar (shared):** vault-relative POSIX path. Reject absolute paths, `..` segments,
  and any resolved path escaping the repo root → `PATH_INVALID` (reuses the
  `link_index._normalise_rel_path` escape check). Non-`.md`/`.markdown`/`.mdx` → `NOT_A_NOTE`.
- **Error envelope:** JSON-RPC error `{code, message, data:{reason, detail?}}` where `reason` is a
  stable UPPER_SNAKE token (enumerated per tool). Human `detail` is control-char sanitised
  (`sanitize_display`). **No stack traces, no secrets, no absolute host paths** in `message`/`data`.
- **Determinism:** read tools are pure/idempotent; write/dispatch tools (`consolidate`, `propose`,
  `attest`) are the only side-effecting members and are individually gated (see below).
- **Bounds (DoS):** every commit walk is capped (`max`/`max_commits`, clamp `1..100000`, default
  per tool); every note body read reuses the 16 MiB cap (`link_index._MAX_NOTE_BYTES`); every HTTP
  response is byte-capped (attestation 64 KiB; hub calls 256 KiB).

### KD-5a.A — Resolution of the five open contract items (a)–(e)

**(a) `knowtation/search` fan-out — FROZEN.**
Two backends, merged by the server:
1. **Muse lexical/structural** (owned by Muse, OQ2): live-vault content grep + `build_link_index`
   title/heading/frontmatter hits. **[KD-5b new work]** — no `content_grep` helper exists in the
   plugin today; KD-5b adds `muse/plugins/knowtation/search.py::lexical_search(root, query, *, top_k)`
   returning `[{path, score∈[0,1], section_address?, snippet}]`.
2. **Knowtation vector** (canonical for semantic at HEAD, OQ2): HTTP `GET` to the local hub
   (`http://localhost:<KNOWTATION_HUB_PORT>/api/v1/search?q=…&k=…`) — Muse **never** rebuilds or
   versions `data/`. **[KD-5b new work]** — thin client, SSRF-guarded port validation reused verbatim
   from `hooks._resolve_port`.

- **Merge/rank:** normalise each backend's score to `[0,1]`; combined
  `score = w_lex·lex + w_vec·vec` with **frozen weights `w_lex=0.4`, `w_vec=0.6`** (semantic favoured
  at HEAD, per OQ2). A result present in only one backend uses that backend's normalised score with
  the missing side treated as `0`.
- **Dedupe key:** vault-relative `path` (case-insensitive basename collision resolved the same way
  `link_index` resolves it — first walk-order path wins; the other is dropped and counted in
  `deduped`). When both backends return the same `path`, scores are combined (not summed twice).
- **Tie-breakers (stable):** higher combined `score` → then more recent HEAD mtime → then
  lexicographic `path`.
- **Fallback / timeout:** vector call timeout **2.0 s**; on timeout/connection-refused/non-200 the
  server returns lexical-only results with `degraded=true`, `backends.vector="unavailable"`, and a
  populated `index_freshness` (or `null`) — **never an error**. If the lexical side raises, return
  vector-only with `backends.lexical="error"`. Both down → `results:[]`, `degraded=true` (still a
  success response so agents can proceed).

**(b) `knowtation/consolidate` return schema — FROZEN.**
The tool wraps `KnowtationMergeHook.pre_merge_hook` (OQ3, fire-and-forget). Output is the
**dispatch receipt** exactly mirroring `hooks.hook_result_to_json`:
`{hook_name:string, fired:bool, out_of_band:bool, message:string, error:string|null,
dispatched_at:iso8601, hub_port:int}`.
- **Async completion is NOT observable through this tool** (by design — merge never blocks). The
  agent observes completion out-of-band via `knowtation://memory/recent` (a later commit with
  `event_type∈{consolidation,consolidation_pass}`) or `knowtation/history`. This is documented in the
  tool description so agents do not poll.
- Port-validation failure and dispatch failure are returned in `error` with `fired=false` — **the
  tool never raises** for hub-side problems (parity with the hook contract).

**(c) `knowtation/attest` runtime wiring — FROZEN.**
- **Who registers:** the **MCP server bootstrap** registers both providers when the bound repo's
  active domain is `knowtation` — it calls `attestation.register_knowtation_attestation_provider(cfg)`
  and `icp_push_hook.register_knowtation_icp_push_hook()` at server start. Today only the *merge*
  hook auto-registers in `plugins/knowtation/__init__.py`; the attest/ICP registration is
  **[KD-5b new work]** (a `bootstrap_knowtation_mcp(root)` call — it must **not** be moved into
  `__init__.py`, to keep import side-effect-free per OQ4).
- **Required vs optional mode:** driven by `.muse/air.yaml` `air.required` (loaded via
  `attestation.load_air_config`). The tool accepts an optional `required?:bool` that overrides for
  this call only. `required=true` + endpoint unreachable → `AttestationRequiredError` surfaced as
  error `reason=ATTESTATION_REQUIRED`. `required=false` → placeholder record returned with
  `anchored=false` (never an error).
- **Provider unregistered:** the tool returns a structured error `reason=PROVIDER_UNREGISTERED`
  (never a silent success, never a placeholder masquerading as real). ICP anchoring is out-of-band
  (`out_of_band=true`) and its failure is reported in `anchor` as `null` with `anchor_error`, never
  failing the tool.

**(d) `.museignore data/` — FROZEN: YES (ignore for snapshots; keep readable on disk).**
KD-5b adds a `[domain.knowtation]` section to `.museignore` with `patterns = ["data/", ".obsidian/"]`
so Muse **never snapshots/versions Knowtation's vector/sqlite index** (consistent with OQ2 "not
rebuilt/versioned by Muse"). This is a *snapshot-exclusion* rule only: `stats.collect_vault_stats`
still `stat()`s `data/` on the live filesystem for `index_freshness` (a filesystem read, unaffected
by `.museignore`), and `link_index`/`code_intel` already skip non-`.md` files so the vector store is
never parsed as a note. `.knowtation` remains an always-ignored marker via
`plugin._ALWAYS_IGNORE_DIRS`; `data/` is domain-scoped ignore (only when active domain is knowtation).

**(e) MCP-scope activation semantics — FROZEN: explicit `repo.json` domain, detector is advisory.**
The `knowtation/*` namespace mounts/advertises **only when `.muse/repo.json` `domain == "knowtation"`**
(explicit activation via `muse init --domain knowtation`). `detector.classify_repo` is **advisory
only**: the server MAY surface `detected_domain` + `confidence` as a capability hint (so a
misconfigured repo can be diagnosed) but **never auto-mounts** vault tools on a repo whose active
domain is `code`/`mist`. This prevents a code repo containing a few notes from exposing vault
write/attest surfaces. When domain≠knowtation the server returns an empty `knowtation/*` tool list.

### KD-5a.B — Tool contracts (9)

Legend: **Backing** = existing plugin/CLI API the tool wraps; **[KD-5b new work]** = no backing API,
implement in KD-5b. All inputs validated against §KD-5a.0 grammars before dispatch.

| # | Tool | Input (JSON-RPC params) | Output (result) | Backing API | Error reasons |
| --- | --- | --- | --- | --- | --- |
| 1 | `knowtation/search` | `{query:string!, top_k?:int=10 (1..100), project?:string, mode?:"hybrid"\|"lexical"\|"semantic"="hybrid", ref?:string="HEAD"}` | `{query, mode, results:[{path, score, source:"muse-lexical"\|"knowtation-vector"\|"both", snippet, section_address?, frontmatter:{project,tags,source_type}}], index_freshness:string\|null, degraded:bool, deduped:int, backends:{lexical:"ok"\|"error", vector:"ok"\|"unavailable"}}` | lexical **[KD-5b new work]** (`search.lexical_search`) + `link_index` + hub vector client **[KD-5b new work]**; `stats.collect_vault_stats` for freshness | `QUERY_INVALID`, `REF_NOT_FOUND` (never errors on backend outage — see A(a)) |
| 2 | `knowtation/get-note` | `{path:string!, ref?:string="HEAD", format?:"json"\|"raw"="json"}` | `{path, ref, exists:bool, frontmatter:object, body:string, symbols:[symbol…], content_hash:string}` | `muse cat`@ref (`core.store` manifest+object read) + `symbols.extract_symbols` | `PATH_INVALID`, `NOT_A_NOTE`, `NOTE_NOT_FOUND`, `REF_NOT_FOUND` |
| 3 | `knowtation/history` | `{address:string!, from_ref?:string="HEAD", max?:int=500 (1..100000)}` | `{address, start_ref, total_commits_scanned, truncated, events:[{event, commit_id, message, committed_at, address, detail, new_address, event_type, agent_id, model_id}]}` | `cli/commands/symbol_log.py` (`_find_events_in_commit` + `walk_commits_bfs`) — **existing** | `ADDRESS_INVALID`, `REF_NOT_FOUND` |
| 4 | `knowtation/consolidate` | `{branch?:string, ours_ref?:string, theirs_ref?:string}` (metadata passthrough; hook ignores today) | dispatch receipt (see A(b)): `{hook_name, fired, out_of_band, message, error, dispatched_at, hub_port}` | `hooks.KnowtationMergeHook.pre_merge_hook` + `hook_result_to_json` — **existing** | (never raises; failures in `error`) |
| 5 | `knowtation/impact` | `{path:string!, direction?:"reverse"\|"forward"="reverse", depth?:int=0 (>=0), include_attachments?:bool=true}` | `{note, direction, depth_limit, by_depth, total, include_attachments}` | `code_intel.impact_for_note`/`note_impact` — **existing** | `PATH_INVALID`, `NOTE_NOT_FOUND`, `DEPTH_NEGATIVE` |
| 6 | `knowtation/dead` | `{use_mtime?:bool=true, mtime_days_threshold?:int=180 (>=0), project?:string}` | `{total_notes_indexed, dead_count, dead_notes:[{path, mtime?}]}` | `note_metrics.note_dead` (+ `build_link_index`) — **existing** | `NOT_KNOWTATION_REPO` |
| 7 | `knowtation/prime` | `{max_commits?:int=100 (1..100000), hot_note_count?:int=10 (1..100)}` | `PrimeContext.to_dict`: `{schema_version, source, commits_scanned, last_consolidation, hot_notes}` (+ `active_projects`, `suggested_next` enrichment) | `prime_context.build_prime_context` — **existing**; `active_projects`/`suggested_next` via `stats` **[KD-5b new work]** | (never fatal; partial on graph-read error) |
| 8 | `knowtation/propose` | `{path:string!, title:string!, proposed_body?:string, proposed_frontmatter?:object, base_ref?:string="HEAD", scope?:"personal"\|"project"\|"org"="personal", rationale?:string}` | `{proposal_id, status:"created", hub_url, path, base_ref, scope}` | `muse hub proposal create` → Knowtation Hub proposal endpoint — **[KD-5b new work]** (no proposal API in plugin today) | `PATH_INVALID`, `NOTE_NOT_FOUND`, `HUB_UNREACHABLE`, `SCOPE_UNAUTHORIZED`, `VALIDATION_FAILED` |
| 9 | `knowtation/attest` | `{commit_id:string!, action?:string="write", required?:bool}` | `{record:{id, action, path, timestamp, content_hash, algorithm, provider_id, sig?}, anchored:bool, anchor:{tx_id, anchor_url, provider_id}\|null, anchor_error?:string, provider_registered:bool}` | `attestation.KnowtationHmacAttestationProvider` (compute+anchor) + `icp_push_hook` — **existing**; runtime registration **[KD-5b new work]** (see A(c)) | `PROVIDER_UNREGISTERED`, `COMMIT_NOT_FOUND`, `ATTESTATION_REQUIRED` |

**Write/side-effect gating:** tools 4, 8, 9 are the only non-read members. `propose` is
review-before-write (scope enforced server-side, per Scooling boundary rules); `consolidate`/`attest`
are dispatch/opt-in. Read tools (1,2,3,5,6,7) have zero durable side effects.

### KD-5a.C — Resource contracts (8)

| # | Resource URI | Content (result) | Backing API | Notes |
| --- | --- | --- | --- | --- |
| 1 | `knowtation://vault` | `{notes:[{path, title, project, tags, source_type}], stats:VaultStats}` | `stats.collect_vault_stats` + note-level walk (`parse_frontmatter`/`extract_symbols`) — listing walk **[KD-5b new work]** | Root listing + frontmatter summary |
| 2 | `knowtation://vault/{path}` | note at HEAD — same body as `knowtation/get-note` (ref=HEAD) | `get-note` core | `{path}` obeys shared path grammar |
| 3 | `knowtation://vault/{path}@{ref}` | note at `{ref}` — same body as `knowtation/get-note` | `get-note` core | URI-template `@{ref}` parsed then validated |
| 4 | `knowtation://prime` | `PrimeContext.to_dict` | `prime_context.build_prime_context` — **existing** | Mirrors `knowtation/prime` (no args) |
| 5 | `knowtation://graph` | `{notes_indexed, forward:{src:[edge…]}, backward:{tgt:[edge…]}, broken_links:[edge…], entities:{label:[path…]}}` | `link_index.build_link_index` + JSON serializer **[KD-5b new work]** (LinkIndex has no `to_json` today) | Edge = `describe_link` shape |
| 6 | `knowtation://memory/recent` | `{events:[{commit_id, committed_at, message, event_type, agent_id, model_id}], count}` (last 20) | `walk_commits_bfs` + filter `metadata.event_type` present — composition **[KD-5b new work]** | Event kinds validated against `events.MemoryEventKind` |
| 7 | `knowtation://projects` | `{projects:[{project, note_count, last_modified}]}` | `stats.collect_vault_stats.projects` + `_query.group_by_project` + mtime — composition **[KD-5b new work]** | |
| 8 | `knowtation://hotspots` | `note_hotspots` JSON: `{commits_analysed, total_notes_touched, ranking:[{path, changes}]}` (top 10) | `note_metrics.note_hotspots` + `make_snapshot_loader` — **existing** | `top=10` fixed for the resource |

### KD-5a.D — Prompt contracts (4)

MCP prompts return `messages[]`; each composes the tools/resources above (no new backend).

| # | Prompt | Arguments | Composition (backing) | Output |
| --- | --- | --- | --- | --- |
| 1 | `vault/daily-brief` | `{since_hours?:int=24 (1..168), project?:string}` | `walk_commits_bfs` filtered to window + `knowtation://memory/recent` | Prompt messages summarising last-24h commits/projects |
| 2 | `vault/search-synthesis` | `{query:string!, top_k?:int=5 (1..20)}` | `knowtation/search` (top_k) → format top-5 + synthesis instruction | Prompt messages: results + synthesis directive |
| 3 | `vault/memory-session` | `{project?:string}` | `knowtation/prime` + `knowtation://memory/recent` | Prompt messages: prime + recent events to resume session |
| 4 | `vault/knowledge-gaps` | `{}` | `knowtation/dead` × `link_index.entity_index` cross-reference | Prompt messages: dead notes joined with entity coverage gaps |

### KD-5a.E — Namespace mount point (gabriel-muse) & musehub hosting

- **Server home [KD-5b new work]:** `gabriel-muse/muse/mcp/` — no MCP server exists today (confirmed:
  no `muse/mcp/` tree; `prime_context.py` only *anticipates* Phase 5). KD-5b scaffolds
  `muse/mcp/server.py` (a `MuseMCPServer` with a namespace registry) + `muse/mcp/namespaces/knowtation.py`
  (registers the 9 tools / 8 resources / 4 prompts under the `knowtation/` tool prefix and
  `knowtation://` resource scheme).
- **Activation gate (A(e)):** on start, the server reads `.muse/repo.json`; it registers the
  `knowtation` namespace **iff `domain == "knowtation"`**. It then calls
  `bootstrap_knowtation_mcp(root)` which registers the attestation provider + ICP push hook (A(c)).
  When domain≠knowtation, `tools/list` returns no `knowtation/*` entries.
- **musehub hosting:** `musehub` launches the Muse MCP server **per repo** — **stdio** transport for
  local MCP clients (Claude Desktop, Cursor), and a hosted **HTTP+SSE** transport for remote agents.
  The server process runs with the repo root as CWD so all binding is implicit (no path args cross
  the wire). The marketplace listing `@aaronrene/knowtation` (already registered, KD-SD8-REG) gains
  its MCP capability descriptor in KD-5b; the vault UI is KD-6.
- **Secret hygiene at the mount:** the server never echoes `MUSE_AIR_HMAC_KEY`, `air.endpoint`,
  `MUSE_ICP_IDENTITY_PEM`, `KNOWTATION_HUB_PORT` internals, or absolute host paths in any
  tool/resource/prompt result, log line, or error `data`. Attestation `sig` (an HMAC *output*, not
  key material) MAY be returned; the HMAC *key* MUST NOT.

### KD-5a.F — Seven-tier test matrix (per group + Claude Desktop integration)

All tiers run in `gabriel-muse` (`pytest tests/test_knowtation_mcp_*.py` — new files in KD-5b) against
`~/MUSE_HUB/knowtation-vault-smoke`. Each row is the **required** minimum for KD-5b Definition of Done.

| Tier | Tools (1–9) | Resources (1–8) | Prompts (1–4) |
| --- | --- | --- | --- |
| **1 Unit** | Each tool's input-schema validation (grammar A.0), output serialization shape, error-reason mapping; per-tool arg defaults/clamps | Each resource URI parse (incl. `@{ref}` template), output shape, empty-vault case | Argument schema + message assembly for each prompt (mocked tool outputs) |
| **2 Integration** | Tool → backing API on the smoke vault (search fan-out both backends; get-note@ref; history events; consolidate receipt; impact/dead/prime/hotspots real JSON; propose→hub stub; attest→provider stub) | Resource → backing on smoke vault; `graph`/`memory/recent`/`projects` composition correctness | Prompt → real tool chain on smoke vault (search-synthesis, memory-session) |
| **3 E2E** | `tools/list`+`tools/call` over JSON-RPC through the mounted server (domain=knowtation) | `resources/list`+`resources/read` round-trip | `prompts/list`+`prompts/get` round-trip |
| **4 Stress** | 5k-note vault: search/impact/dead/hotspots within perf budget; `max` clamps honoured; vector-backend timeout path under load | `graph` on 5k notes; `vault` listing pagination bound | daily-brief over 500-commit window; knowledge-gaps over large entity index |
| **5 Data-integrity** | `history`/`memory/recent` event_type parity vs `events.EVENTS_SCHEMA_HASH`; get-note `content_hash` matches store; attest `id` determinism (`compute_attestation_id`) | resource payloads round-trip; `graph` edges match `describe_link`; `index_freshness` == `data/` mtime | prompt outputs cite only real notes (no fabricated paths) |
| **6 Performance** | search < 2 s hybrid (lexical budget < 1 s + vector timeout 2 s); impact/dead/hotspots < 2 s on 5k vault (reuse §3.3 budgets); prime < 1 s / 100 commits | `graph` build < 10 s / 5k (reuse `link_index` budget) | prompt assembly < 500 ms excluding model call |
| **7 Security** | path-traversal reject (get-note/impact/propose); SSRF-guard on search-vector + consolidate port + attest endpoint + ICP canister-id (reuse existing regex guards); **no secret in any result/log/error**; `air.required` rejection; `PROVIDER_UNREGISTERED` never silent-success; sensitive-key scan (`events._has_sensitive_keys`) on surfaced note `data`; activation gate blocks `knowtation/*` on domain≠knowtation | resource path-escape reject; `memory/recent` strips sensitive metadata | prompt injection: note bodies are data-not-instructions; control-char sanitised |

**Claude Desktop integration test (required, Tier 3/E2E):** register the KD-5b server in Claude
Desktop's MCP config bound to `knowtation-vault-smoke`; verify `tools/list` shows the 9 tools,
`resources/list` shows the 8 resources, `prompts/list` shows the 4 prompts, and one live
`knowtation/search` + `knowtation://prime` round-trip returns valid payloads. Evidence captured in the
KD-5b handover matrix.

### KD-5a.G — Security invariants (frozen)

1. **No secrets anywhere on the wire:** HMAC key, AIR endpoint, identity PEM path, hub port internals,
   absolute host paths are never in results, logs, or error `data` (§E).
2. **Reuse existing guards:** `_normalise_rel_path` (path escape), `hooks._resolve_port` +
   `attestation._validate_endpoint_url` + `icp_push_hook._is_valid_canister_id` (SSRF), body/response
   byte caps, `events._has_sensitive_keys` (payload scrub).
3. **Misuse-resistant verification:** attest never returns a placeholder as if real; `verify`
   partial-failures are hard errors (per `core.attestation` contract).
4. **Bounded everything:** commit walks, note reads, HTTP responses all capped (§0).
5. **Activation gate is a security control**, not a convenience: it prevents non-vault repos from
   exposing vault write/attest tools (A(e)).

### KD-5a.H — KD-5b new-work summary (no backing API today)

- `knowtation/search` lexical helper (`search.lexical_search`) + hub vector client + fan-out merge.
- `knowtation/propose` → `muse hub proposal create` + Knowtation Hub proposal endpoint wiring.
- Attestation/ICP **runtime registration** (`bootstrap_knowtation_mcp`) — not in `__init__.py`.
- `.museignore` `[domain.knowtation]` section (`data/`, `.obsidian/`).
- Resource serializers: `knowtation://graph`, `://memory/recent`, `://projects`, `://vault` listing.
- `prime` enrichment (`active_projects`, `suggested_next`).
- The **MCP server scaffold** itself: `muse/mcp/server.py` + `muse/mcp/namespaces/knowtation.py`.

Everything else (tools 2,3,5,6,7 and resources 2,3,4,8) maps to **existing, tested** plugin/CLI APIs.

---

### KD-6 — MuseHub UI for Vault Repos (KD-6a contract frozen; KD-6b implementation TODO)

**Goal:** Domain-aware repo landing, note detail page, knowledge proposals UI, vault search.

**Entry criteria:** KD-1 symbols + KD-2 diff available on staging vault; KD-5 MCP tools **landed** (KD-5b DONE). **All MET (2026-07-10).**

**Repo:** `musehub/` primarily.

**Model:** Thinking → Auto (KD-6a Thinking **DONE** — contract frozen in §KD-6a below; KD-6b Auto is NEXT).

---

## KD-6a Contract — MuseHub Vault UI (`musehub`) — FROZEN 2026-07-10

**Status:** DONE (Thinking). This section is the **frozen spec** KD-6b (Auto) implements against.
Do not redesign during Build. Interfaces below are the contract; the seven-tier test matrix is
in §KD-6a.F. Implementation-only (KD-6b) items are tagged **[KD-6b new work]**. The KD-5b MCP
surface (9 tools / 8 resources / 4 prompts) is a **read dependency** consumed as-is — **do not
redesign KD-5 MCP interfaces** (hard stop).

**Authority chain:** issue #2 Phase 6 (vault-centric UI) + KD-5a frozen MCP contract (§KD-5a) +
existing MuseHub UI conventions verified in tree (`api/routes/musehub/ui_*.py`,
`templates/musehub/pages/`, `src/scss/`). Boundary rules from Scooling `CROSS-REPO-COORDINATION.md`
apply: **MuseHub enriches (version/provenance/marketplace); it does not own note bodies**;
Knowtation is the canonical vault store + permission authority; review-before-write; scope is
authorization enforced **server-side**.

### KD-6a.0 — Surface conventions & shared contract

- **URL scheme (reuse, do not fork):** vault pages are **domain-conditional branches of the existing
  repo route tree** `/{owner}/{repo_slug}/…` (`api/routes/musehub/ui_repo.py::repo_page` +
  siblings), **not** a new `/vault/…` tree. Ref selection reuses the existing `?ref=<branch|sha>`
  query param.
- **Domain activation gate (mirrors KD-5a.E — security control, not convenience):** a page renders
  its **vault variant iff the repo's active marketplace domain resolves to `knowtation`**
  (`_nav_ctx._resolve_repo_domain` / `_resolve_domain_viewer_type` → domain `@aaronrene/knowtation`).
  A `code`/`mist` repo that merely contains a few notes **never** shows vault tabs, the note-detail
  variant, or the knowledge-proposal write surface. `detector.classify_repo` is **advisory only**
  (may power a "looks like a vault — activate?" hint), never auto-mounts.
- **Content negotiation (frozen, reuse verbatim):** `?format=json` **or** `Accept: application/json`
  → structured JSON (camelCase, `by_alias`); `HX-Request: true` → bare HTMX fragment (partial swap
  target); default → full SSR page. Canonical machine-readable REST lives under `/api/…`; UI routes
  are the same-URL negotiated surface (established pattern in `ui_repo.py`, `ui_domains.py`).
- **Read surface split (frozen):**
  1. **Note bodies, tree, commits, diffs, refs** are served from **MuseHub's own versioned snapshot
     store** (`services/musehub_repository`, `muse_cli/snapshot.py`) — exactly as code repos are
     today. This is *versioned enrichment*, not body ownership; the canonical body still lives in the
     Knowtation vault.
  2. **Domain intelligence** (hybrid search, backlinks/impact, dead notes, link graph, prime, memory
     timeline, hotspots, history) is read from the **mounted Muse domain MCP `knowtation/*` surface
     (KD-5b)** — the 9 tools / 8 resources / 4 prompts, consumed as-is.
- **Adapter boundary (frozen):** **no Jinja template or route handler calls an MCP tool / provider
  SDK inline.** All MCP reads go through a hub-side **`services/knowtation_view` adapter**
  **[KD-6b new work]** that (i) resolves the mounted per-repo Muse MCP server (stdio for local,
  hosted HTTP+SSE per KD-5a.E), (ii) issues `tools/call` + `resources/read`, (iii) normalises the
  JSON-RPC envelope into hub view-models, and (iv) maps MCP error `reason` tokens → UI states
  (§KD-6a.E). This is the KD-6 analog of the Scooling "no component calls a provider directly" rule.
- **Write surface (frozen — review-before-write):** knowledge-proposal **creation** dispatches to
  `knowtation/propose` (→ Knowtation Hub proposal endpoint; scope `personal|project|org` enforced
  **server-side**). MuseHub **renders, lists, threads, and reviews** proposals via the existing
  proposals surface (`ui_proposals.py`, `MusehubProposal`); it **never writes note bodies directly**
  and never enforces scope in the UI layer.
- **Resilience / degradation (frozen):** the MuseHub-owned data path (bodies/tree/history from the
  snapshot store) is **independent** of the MCP path. If the mounted MCP server is unavailable or a
  tool returns `degraded=true`, vault-intel panels render a **non-fatal** "domain intelligence
  unavailable" / "semantic search unavailable — showing lexical results" state; the page still
  renders bodies, tree, and history. A domain-intel outage is **never a 5xx**.
- **Error envelope:** HTML → standard hub error pages (403/404/410/500) with domain-aware empty
  states; JSON → existing hub error shape `{error:{code,message}}`; MCP-sourced problems surface as
  the UI-state enum in §KD-6a.E, not as raw JSON-RPC errors.
- **Bounds & determinism:** reuse hub cursor pagination for lists; note-body render reuses the 16 MiB
  cap; search/impact/history reuse the MCP tool clamps (KD-5a.0); no unbounded walks initiated from
  the UI.
- **Secret hygiene:** never render `KNOWTATION_HUB_PORT` internals, `air.endpoint`, `MUSE_AIR_HMAC_KEY`,
  `MUSE_ICP_IDENTITY_PEM`, or absolute host paths in any HTML, JSON, `data-*` attribute, OG tag, or
  JSON-LD block. Attestation `sig` (an HMAC *output*) MAY render; key material MUST NOT.

### KD-6a.A — Resolution of the five open UI contract items (a)–(e)

**(a) Note-body rendering & sanitisation — FROZEN: server-side render, sanitised, wikilinks resolved.**
Markdown → HTML is rendered **server-side** reusing the hub's existing renderer path (the
README/blob pipeline behind `_ui_helpers._fetch_readme` + `blob.html`), extended **[KD-6b new work]**
with a Knowtation post-processor that (i) resolves `[[wikilinks]]` and `[[wikilink#section]]` to
`/{owner}/{repo_slug}/note/{path}` (broken links get a `broken` class, never a raw link), and (ii)
renders frontmatter as a **metadata panel**, never executed or reflected into script context. Raw
inline HTML in note bodies is **sanitised** (allowlist; no `<script>`/event handlers) — bodies are
**data, not instructions** (parity with KD-5a.G prompt-injection stance). Attachments/images resolve
through the existing blob route; external URLs are not fetched server-side.

**(b) Vault search backend — FROZEN: `knowtation/search` hybrid, not hub DB `global_search`.**
The **vault search page** calls the Muse domain MCP `knowtation/search` (hybrid: `w_lex=0.4`,
`w_vec=0.6`, KD-5a.A(a)) through the `knowtation_view` adapter, with `project?` filter and `mode`
toggle (`hybrid|lexical|semantic`). It does **not** reuse `musehub_repository.global_search` (which is
commit-message keyword search, cross-repo). On `degraded=true` (vector backend down) the page shows
lexical-only results with a banner and `index_freshness`. Cross-repo global search (`/api/search`,
`global_search.html`) is unchanged and remains hub-DB keyword search.

**(c) Proposals UI ownership split — FROZEN: MuseHub renders/reviews; Knowtation owns create+scope.**
MuseHub owns proposal **listing, detail, review threads, comments, and section-aware diff display**
(reuse `ui_proposals.py` + `proposal_detail.html`; the diff panel renders the **KD-2 section-aware
harmony diff** — tag/entity/`§Summary` semantics — rather than a raw text diff **[KD-6b new work]**:
a differ-output → HTML view). Proposal **creation and scope authorization** are Knowtation-canonical
via `knowtation/propose`; the "Propose edit" affordance on the note-detail page opens a form that
POSTs to a thin hub route which delegates to the adapter's `propose` call. Scope
(`personal|project|org`) is displayed as a badge but **enforced server-side** by Knowtation.

**(d) Domain-intel freshness & failure isolation — FROZEN.**
Every vault-intel panel surfaces the MCP-reported `index_freshness` (or `null`). The MCP read path is
**isolated** from the snapshot-store read path (§KD-6a.0 resilience): a mounted-server outage degrades
only intel panels. The repo-landing intel strip reuses `_ui_helpers._load_intel_strip`'s slot,
populated for vault repos by `dead`/`hotspots`/`prime` **[KD-6b new work]** instead of the code-intel
loaders.

**(e) Activation semantics & `viewer_type` — FROZEN: gate on active domain; `vault` viewer_type optional.**
The vault UI variant mounts **iff active domain == `knowtation`** (as (§KD-6a.0) — the same gate as
KD-5a.E), independent of the marketplace `viewer_type`. The existing `ViewerType` enum
(`symbol_graph|piano_roll|generic`, `api/routes/musehub/domains.py`) currently classes
`@aaronrene/knowtation` as `generic`. Adding a first-class **`vault`** `viewer_type` is an **optional,
deferred palette change** (musehub#117 lineage) — KD-6b MUST NOT block on it and MUST NOT force an
enum migration; the domain gate is the source of truth.

### KD-6a.B — Page contracts (4 groups)

Legend: **Store** = MuseHub snapshot/DB read; **MCP** = `knowtation_view` adapter → KD-5b surface;
**[KD-6b new work]** = net-new template/route/adapter code.

| # | Page group | Purpose | Primary sections | Data sources |
| --- | --- | --- | --- | --- |
| 1 | **Vault repo landing** (variant of `repo_home.html`) | Domain-aware home for a `knowtation` repo | Vault header (note count, projects, `index_freshness`); note tree (folders); recent memory timeline; intel strip (dead / hotspots); prime "resume here" card; clone/MCP-connect hints | **Store:** tree, recent commits, README. **MCP:** `knowtation://vault` (listing+stats), `knowtation://projects`, `knowtation://memory/recent`, `knowtation://hotspots`, `knowtation/dead`, `knowtation://prime` |
| 2 | **Note detail** (`note_detail.html` **[KD-6b new work]**) | Rendered note @ref with provenance & graph | Rendered body (A(a)); frontmatter panel; symbol outline (headings/wikilinks/entities); backlinks / forward-links (impact); change history timeline; provenance/attestation strip; "Propose edit" affordance | **Store:** body/manifest @ref, commit list. **MCP:** `knowtation/get-note`, `knowtation/impact` (reverse+forward), `knowtation/history`, `knowtation://graph` (neighbourhood), `knowtation/attest` (read-only provenance strip — no new attest issued from UI) |
| 3 | **Knowledge proposals** (reuse `proposal_list.html` + `proposal_detail.html`) | List/review vault-note proposals; section-aware diff | Proposal list (scope badges, status); detail with **KD-2 harmony diff** (tag/entity/§Summary); review threads/comments; scope badge; create form → `propose` | **Store:** `MusehubProposal` rows, review/comment threads, base/proposed manifests. **MCP:** `knowtation/propose` (create only); KD-2 differ output rendered for the diff panel |
| 4 | **Vault search** (`vault_search.html` **[KD-6b new work]**) | Hybrid vault search with project filter | Query box + `mode` toggle (hybrid/lexical/semantic) + `project` filter; result cards (path, snippet, section address, score, source badge lexical/vector/both); `degraded`/`index_freshness` banner | **MCP:** `knowtation/search` (A(b)); optional `vault/search-synthesis` prompt for an agent "synthesise" action (deferred, not required for KD-6b DoD) |

### KD-6a.C — Route / API contracts

All routes are content-negotiated (§KD-6a.0). New HTML routes live in a new
`api/routes/musehub/ui_vault.py` **[KD-6b new work]**; proposals reuse `ui_proposals.py`.

| # | Method + Route | Handler (module) | Response (HTML / JSON) | Notes |
| --- | --- | --- | --- | --- |
| 1 | `GET /{owner}/{repo_slug}` | `ui_repo.py::repo_page` (existing; **branch on domain** **[KD-6b new work]**) | vault `repo_home.html` variant / `RepoResponse`+vault meta | Reuses existing route; adds vault landing branch when domain==knowtation |
| 2 | `GET /{owner}/{repo_slug}/note/{path:path}` | `ui_vault.py::note_detail_page` **[KD-6b new work]** | `note_detail.html` / `{path, ref, frontmatter, body_html, symbols, backlinks, forward_links, history, provenance, freshness}` | `?ref=`; `{path}` obeys the KD-5a.0 path grammar (reject `..`/absolute/non-`.md`) |
| 3 | `GET /{owner}/{repo_slug}/vault/search` | `ui_vault.py::vault_search_page` **[KD-6b new work]** | `vault_search.html` / `{query, mode, results[], degraded, index_freshness, backends}` | `?q=&mode=&project=&top_k=`; rate-limited (reuse `SEARCH_LIMIT`) |
| 4 | `GET /{owner}/{repo_slug}/vault/graph` | `ui_vault.py::vault_graph_fragment` **[KD-6b new work]** | HTMX fragment / `knowtation://graph` JSON | Backlink/neighbourhood panel; lazy `hx-get` from note detail & landing |
| 5 | `GET /{owner}/{repo_slug}/vault/memory` | `ui_vault.py::vault_memory_fragment` **[KD-6b new work]** | HTMX fragment / `knowtation://memory/recent` JSON | Recent memory timeline strip |
| 6 | `GET /{owner}/{repo_slug}/proposals` · `/proposals/{id}` | `ui_proposals.py` (existing; **vault diff renderer** **[KD-6b new work]**) | `proposal_list.html` / `proposal_detail.html` | Domain-aware diff panel (KD-2 section-aware) for vault repos |
| 7 | `POST /{owner}/{repo_slug}/proposals/new` (vault) | `ui_vault.py::create_note_proposal` **[KD-6b new work]** | redirect / `{proposal_id, status, hub_url, scope}` | Thin delegate → adapter `propose`; CSRF-protected (reuse hub session/MSign); scope enforced server-side |

**No new canonical REST namespace is introduced** for domain intelligence — the machine-readable
surface for those reads is already the **Muse domain MCP** (`knowtation/*`, KD-5b). The hub UI's JSON
negotiation exists for its own SSR data; agents that want raw domain intel use MCP directly.

### KD-6a.D — MCP tool/resource → UI mapping (read surfaces, KD-5b consumed as-is)

| KD-5b surface | Kind | Consumed by (page/panel) | UI use |
| --- | --- | --- | --- |
| `knowtation/search` | tool | Vault search (B4) | Hybrid results, `mode` toggle, `degraded` banner |
| `knowtation/get-note` | tool | Note detail (B2) | Body @ref cross-check + symbols/`content_hash` (bodies primarily from store) |
| `knowtation/history` | tool | Note detail history timeline (B2) | Per-address event timeline (`event_type`, agent/model) |
| `knowtation/impact` | tool | Note detail backlinks/forward (B2) | Reverse + forward link neighbourhood by depth |
| `knowtation/dead` | tool | Landing intel strip (B1) | Dead-note count + list panel |
| `knowtation/prime` | tool | Landing "resume here" card (B1) | Hot notes, active projects, suggested next |
| `knowtation/propose` | tool | Proposal create (B3, C7) | Review-before-write creation only |
| `knowtation/attest` | tool | Note/commit provenance strip (B2) | **Read-only** render of existing attestation record; UI issues no new attest |
| `knowtation/consolidate` | tool | (not surfaced in KD-6b UI) | Out-of-band; observed via memory timeline — no UI trigger in KD-6 |
| `knowtation://vault` | resource | Landing note tree + stats (B1) | Listing + `VaultStats` |
| `knowtation://vault/{path}[@{ref}]` | resource | Note detail (B2) | Note payload at ref (parity with `get-note`) |
| `knowtation://prime` | resource | Landing (B1) | Prime card (no-arg) |
| `knowtation://graph` | resource | Graph fragment (C4), note detail neighbourhood | Forward/backward edges, broken links, entities |
| `knowtation://memory/recent` | resource | Memory fragment (C5), landing (B1) | Last-20 memory events |
| `knowtation://projects` | resource | Landing projects panel (B1) | Project → note-count/last-modified |
| `knowtation://hotspots` | resource | Landing intel strip (B1) | Top-10 churn ranking |
| `vault/daily-brief`, `vault/search-synthesis`, `vault/memory-session`, `vault/knowledge-gaps` | prompts | Optional agent affordances (deferred) | Not required for KD-6b DoD; wired only as opt-in "ask an agent" buttons if time permits |

### KD-6a.E — UI error / empty-state enum (stable tokens)

The `knowtation_view` adapter maps MCP `reason` tokens + hub HTTP outcomes into these **stable UI
states** (each renders a specific empty/banner/error template, never a stack trace or secret):

| UI state token | Trigger (MCP reason / hub) | Rendered as |
| --- | --- | --- |
| `VAULT_DOMAIN_INACTIVE` | active domain ≠ knowtation | 404-style "no vault view for this repo" (gate) |
| `NOTE_NOT_FOUND` | `NOTE_NOT_FOUND` / store miss | 404 note page with tree fallback |
| `REF_NOT_FOUND` | `REF_NOT_FOUND` | Inline "unknown ref" notice, default to HEAD |
| `PATH_INVALID` / `NOT_A_NOTE` | `PATH_INVALID`, `NOT_A_NOTE` | 400 "invalid note path" (path grammar reject) |
| `DOMAIN_INTEL_UNAVAILABLE` | mounted MCP server unreachable / tool timeout | Non-fatal panel banner; body/tree/history still render |
| `SEARCH_DEGRADED` | search `degraded=true` | "Semantic search unavailable — lexical results" banner |
| `PROPOSAL_SCOPE_UNAUTHORIZED` | `SCOPE_UNAUTHORIZED` | 403 on create; badge + reason, no write |
| `PROPOSE_HUB_UNREACHABLE` | `HUB_UNREACHABLE` | Retryable "proposal service unavailable" notice |
| `PROPOSE_VALIDATION_FAILED` | `VALIDATION_FAILED` | Inline form validation errors |
| `PROVENANCE_UNAVAILABLE` | `PROVIDER_UNREGISTERED` / `COMMIT_NOT_FOUND` | Provenance strip shows "not attested" (never fake) |

### KD-6a.F — Seven-tier test matrix (per page group + browser E2E)

All UI tiers run in `musehub` (`pytest tests/…` + `vitest`/Playwright for browser E2E) against a
`knowtation`-domain fixture repo mirroring `~/MUSE_HUB/knowtation-vault-smoke`. Each row is the
**required** minimum for KD-6b Definition of Done.

| Tier | Landing (B1) | Note detail (B2) | Proposals (B3) | Vault search (B4) |
| --- | --- | --- | --- | --- |
| **1 Unit** | Domain-gate branch selects vault variant; view-model assembly from mocked adapter; empty-vault render | Wikilink/frontmatter render + sanitisation (A(a)); symbol outline; path-grammar validation | Scope-badge render; harmony-diff view-model from mocked KD-2 differ; create-form validation | Query/mode/project param parse; result-card view-model; `degraded` banner logic |
| **2 Integration** | Route → `knowtation_view` adapter → live KD-5b tools on fixture (`vault`/`projects`/`memory`/`hotspots`/`dead`/`prime`) | `note/{path}` → store body + `get-note`/`impact`/`history`/`graph` compose correctly | list/detail → `MusehubProposal` + KD-2 diff; create → adapter `propose` (stubbed hub) | search page → `knowtation/search` hybrid on fixture; project filter |
| **3 E2E (browser)** | Playwright: load vault landing, tree + intel strip visible | Navigate note → backlinks → linked note; history expands | Open proposal → diff renders → add review comment | Type query → results render → click result → note detail |
| **4 Stress** | 5k-note vault landing within perf budget; tree pagination bound | note detail with 500-commit history + large backlink set | proposal list pagination; large section-aware diff | search over 5k vault; rapid query debounce; vector-timeout path |
| **5 Data-integrity** | tree/stats match store; `index_freshness` == MCP report | rendered body `content_hash` matches store; history `event_type` parity vs `events.EVENTS_SCHEMA_HASH`; provenance record matches attest | diff reflects true base↔proposed; scope badge matches server decision | results cite only real note paths (no fabricated); scores in `[0,1]` |
| **6 Performance** | landing SSR < 2 s on 5k vault (reuse repo-home budget) | note detail < 2 s incl. impact/history | proposal detail render < 2 s | search round-trip < 2 s hybrid (lexical < 1 s + 2 s vector timeout) |
| **7 Security** | activation gate blocks vault tabs on domain≠knowtation; no secret in HTML/JSON/OG/JSON-LD | path-traversal reject on `note/{path}`; markdown/wikilink XSS-sanitised; bodies-as-data | scope enforced server-side (UI cannot bypass); CSRF on create; review actions authz | rate-limit (`SEARCH_LIMIT`); query injection-safe; `degraded` never leaks internals |

**Browser integration test (required, Tier 3/E2E):** a Playwright run against the fixture vault repo
that (i) loads the vault landing and asserts tree + intel strip + prime card, (ii) opens a note detail
and asserts rendered body + backlinks + history, (iii) runs a vault search and clicks through a
result, and (iv) opens a knowledge proposal and asserts the section-aware diff renders. Evidence
captured in the KD-6b handover matrix (analog to the KD-5b Claude Desktop test).

### KD-6a.G — Security invariants (frozen)

1. **Activation gate is a security control:** vault write/proposal/attest surfaces never appear on a
   non-`knowtation` repo (§KD-6a.0, .A(e)).
2. **Bodies are data, not instructions:** server-side markdown sanitisation (allowlist), wikilink
   resolution never emits executable content, frontmatter never reflected into script context
   (A(a)).
3. **No secrets on the wire:** hub port internals, AIR endpoint, HMAC key, identity PEM path, absolute
   host paths never in HTML/JSON/`data-*`/OG/JSON-LD (§KD-6a.0). Attestation `sig` MAY render; key
   material MUST NOT.
4. **Scope is server-side authorization:** the UI displays scope but never enforces it; `propose`
   scope + all durable writes are authorised by Knowtation (`SCOPE_UNAUTHORIZED` → 403).
5. **Path grammar reuse:** `note/{path}` reuses the KD-5a.0 path escape rules (reject `..`, absolute,
   non-note extensions) before any store/MCP read.
6. **CSRF + rate limits:** proposal-create POST is CSRF-protected via the existing hub session/MSign
   path; search reuses `SEARCH_LIMIT`.
7. **Failure isolation:** a mounted-MCP outage degrades intel panels only and never a 5xx (§KD-6a.0);
   provenance never renders a placeholder as if real (`PROVENANCE_UNAVAILABLE`).

### KD-6a.H — KD-6b new-work summary (net-new vs reused)

**Net-new [KD-6b new work]:**
- `services/knowtation_view` adapter (MCP mount resolution + envelope normalisation + error mapping).
- `api/routes/musehub/ui_vault.py` (note detail, vault search, graph/memory fragments, proposal-create delegate).
- `templates/musehub/pages/note_detail.html` + `vault_search.html`; vault variant of `repo_home.html`; SCSS (`_note-detail.scss`, `_vault.scss`; reuse `_repo-home.scss`, `_search.scss`, `_diff.scss`, `_proposals.scss`).
- Markdown+wikilink+frontmatter Knowtation post-processor with sanitisation (A(a)).
- KD-2 section-aware harmony-diff → HTML renderer for the vault proposal detail (A(c)).
- Vault intel-strip loader (dead/hotspots/prime) filling the existing `_load_intel_strip` slot (A(d)).
- Playwright browser E2E fixture + suite (§KD-6a.F).

**Reused as-is:** repo route tree + content negotiation (`ui_repo.py`); domain resolution
(`_nav_ctx`); proposals list/detail/threads (`ui_proposals.py`, `MusehubProposal`); snapshot/manifest
store (`services/musehub_repository`, `muse_cli`); blob/README render pipeline; rate limits; the entire
KD-5b MCP surface (9 tools / 8 resources / 4 prompts — **not** redesigned).

---

### KD-7 — Attestation (done locally, verification pending)

**Goal:** HMAC attestation, ICP push hook, verify-commit --attest, provenance strip on Hub.

**Deliverables (verified in tree):** `attestation.py`, `icp_push_hook.py`, `quorum.py`

**Exit criteria:** Attestation smoke on staging vault with `--attest` flag (post KD-ACTIVATE).

---

## Open questions (issue #2 — resolved in KD-OQ, 2026-07-10)

All five closed. Each decision is grounded in shipped plugin source (not a guess); the
"Evidence" column cites the file that already implements or constrains the choice.

| # | Question | Options (summary) | Decision | Evidence |
| --- | --- | --- | --- | --- |
| 1 | Vault detection boundary | Frontmatter-only vs require `.knowtation` / `config/local.yaml` marker | **DECIDED — Detector is frontmatter fingerprint primary; `.knowtation` marker is an optional override (not required).** Note (verified): the detector *classifies*; a repo's *active* domain is still set explicitly via `muse init --domain knowtation` → `.muse/repo.json`, so detection informs classification rather than auto-activating a repo. Marker is an escape hatch for sparse-frontmatter vaults. | `detector.py` `classify_note` rules 1–4 (frontmatter) + `classify_repo` rule A (marker, conf 1.0) → rule B (majority ≥0.50) → rule C (mist); activation via `repo.json` |
| 2 | Vector index ownership | Muse parallel index vs query Knowtation `data/` index directly | **DECIDED — Split by capability. Muse owns structural/lexical intel — link graph, symbols, hotspots from live-vault parsing (`build_link_index`/`code_intel`), plus commit-graph history/hot-notes (`prime_context`); Knowtation's live `data/` vector index stays canonical for semantic search (queried at HEAD, not rebuilt or versioned by Muse).** Muse surfaces `index_freshness` (mtime of `data/`) so agents know vector recency. **KD-5a must resolve:** whether `data/` needs `.museignore` (today only `.knowtation` is always-ignored) and the `knowtation/search` fan-out/ranking. | `link_index.py` `build_link_index(root)` + `code_intel.py` walk live files; `prime_context.py` walks commit graph; `stats.py` reads `data/` mtime only ("no vector store"); `plugin.py` `_ALWAYS_IGNORE_DIRS` excludes `.knowtation` (not `data/`) |
| 3 | Consolidation daemon coupling | `muse merge --consolidate` pre-hook vs async watcher | **DECIDED — Pre-merge hook that dispatches asynchronously. `--consolidate` is the explicit opt-in trigger (default off); execution is fire-and-forget background POST to the local hub daemon so merge never blocks on LLM/network latency.** Hook errors are caught by the merge CLI and the registry, so they never fail the merge. | `hooks.py` `KnowtationMergeHook.pre_merge_hook` (default `consolidate=False`) → `_post_consolidate_in_background`, `out_of_band=True`; auto-registered at import via `__init__.py` |
| 4 | ICP canister reuse | Knowtation Motoko canister vs generic Muse attestation interface | **DECIDED — Both layers: generic `MuseAttestationProvider` interface in core, implemented by the knowtation plugin, which REUSES the existing Knowtation Motoko canister (`dejku-syaaa-aaaaa-qgy3q-cai`) + AIR HMAC daemon. No new ICP infra.** Note (verified): the interface + implementation + registration helpers exist, but only the *merge* hook is auto-registered at import today — **wiring the attestation provider / ICP push hook into the runtime commit/push path is KD-5a/5b work.** | core `MuseAttestationProvider` protocol + registry; `attestation.py` `KnowtationHmacAttestationProvider`, `icp_push_hook.py` `KnowtationICPPushHook`; helpers `register_knowtation_attestation_provider` / `_icp_push_hook` (not yet called in `__init__.py`); canister-ID SSRF guard |
| 5 | SKILL.md agent discovery | Merge into Muse `agent.md` vs keep separate | **DECIDED — Keep separate. `muse agent-config` stays a canonical (`.muse/agent.md`) → derived-adapter generator; it does NOT auto-discover/inline product SKILL.md files.** Optional (prospective, not built): a reference pointer to the skill when a knowtation domain is detected — no content merge. | `cli/commands/agent_config.py` source→adapter model (`_ADAPTERS`, `run_sync`); no SKILL.md scan exists; SKILL.md owned by product `.cursor/skills/` (11 files) |

**Downstream effect on KD-5a:** these answers freeze the MCP contract's search *ownership split* (OQ2),
consolidate *coupling* (OQ3 async dispatch), attest *architecture* (OQ4 generic interface + canister reuse),
and confirm no `agent.md` merge work (OQ5). Contract-level detail the decisions deliberately left to the
contract — (a) `knowtation/search` fan-out algorithm/weights/dedupe/timeout; (b) `knowtation/consolidate`
return schema; (c) `knowtation/attest` runtime registration + required-mode; (d) whether Muse must
`.museignore` `data/`; (e) MCP-scope activation semantics — is now **RESOLVED and frozen in §KD-5a Contract**
(KD-5a.A), 2026-07-10.

---

## Cross-repo coordination (read-only pointers)

| Document | Repo | Purpose |
| --- | --- | --- |
| `docs/CROSS-REPO-COORDINATION.md` | scooling | SD-8 namespace decision; canonical-first ordering |
| `docs/KNOWTATION-MUSEHUB-WIRING.md` | scooling | How Scooling will consume domain features long-term |
| `docs/VERIFICATION-MATRIX.md` | scooling | Source-backed facts on plugin manifest |
| `musehub/docs/issues/custom-domain-registration.md` | musehub | Marketplace URL + author-identity hardening notes |

Scooling **Phase 1 rule:** must not require live MuseHub or production Knowtation Domain. Domain activation does not block Scooling Phase 9A.

---

## Governance hygiene (manual until orchestrator is live)

At **session end** for any KD phase:

1. Update **this file** — build status table, "Next step at a glance", phase Status lines.
2. Update **`docs/MUSEHUB-OVERSEER-HANDOVER.md`** — rotate NEXT SESSION, verified snapshot, VCS table, change log, paste-ready prompt.
3. Muse commit on feature branch (Tier 1); staging push / merge to `main` only with Tier 3 authorization.
4. Run test suite for touched areas before commit.

A session that ends without both governance docs updated is **incomplete**.

**Orchestrator:** The cross-workspace overseer orchestrator (Scooling session) is **not required** for this track yet. Use these two docs manually until that tooling ships.

---

## Verified snapshot (2026-07-10)

| Fact | Source |
| --- | --- |
| Plugin path | `~/MUSE_HUB/gabriel-muse/muse/plugins/knowtation/` — 26 `.py` files |
| Test files | `~/MUSE_HUB/gabriel-muse/tests/test_knowtation_*.py` — 27 files |
| Last full-suite count | 1570 passed, 0 failed (2026-06-20 recovery) |
| Staging plugin repo | `https://staging.musehub.ai/aaronrene/gabriel-muse` — HTTP 200 |
| Marketplace listing | `@aaronrene/knowtation` — version 1.0.0, 6 dimensions, `install_count: 0` |
| Test vault | `~/MUSE_HUB/knowtation-vault-smoke` — 3 notes, `domain=knowtation`, Harmony policies |
| Issue tracker | [gabriel/muse #2](https://staging.musehub.ai/gabriel/muse/issues/2) — assigned aaronrene |
| OQ resolution basis | Shipped plugin source — `detector.py`, `link_index.py`, `stats.py`, `hooks.py`, `attestation.py`, `icp_push_hook.py`, `cli/commands/agent_config.py` |

---

## Change log

- **2026-07-10** — **KD-6a DONE** (Thinking). Froze the MuseHub vault UI contract for the `musehub`
  repo (§KD-6a Contract): 4 page groups (vault repo landing, note detail, knowledge proposals, vault
  search) with page/route/MCP-mapping/error-enum tables and a seven-tier test matrix + required
  Playwright browser E2E. Resolved five open UI contract items: (a) server-side sanitised
  markdown+wikilink+frontmatter render (bodies-as-data); (b) vault search = `knowtation/search`
  hybrid (not hub-DB `global_search`), lexical-degrade banner; (c) proposals ownership split —
  MuseHub renders/reviews (KD-2 section-aware harmony diff), Knowtation owns create + server-side
  scope via `knowtation/propose`; (d) domain-intel freshness + MCP/store read-path failure isolation
  (intel outage never 5xx); (e) activation gate on active domain==knowtation (not `viewer_type`),
  `vault` viewer_type deferred/optional. Frozen conventions: reuse `/{owner}/{repo_slug}` route tree +
  content negotiation; **no template calls MCP inline** — hub-side `services/knowtation_view` adapter
  boundary; KD-5b MCP surface (9 tools / 8 resources / 4 prompts) consumed **as-is** (no redesign).
  Flagged KD-6b new work (adapter, `ui_vault.py`, `note_detail.html`/`vault_search.html`, markdown
  post-processor, KD-2 diff renderer, vault intel-strip loader, Playwright suite). Muse commit on
  `feat/kd-6a`. NEXT → **KD-6b** (Auto).
- **2026-07-10** — **KD-5b DONE** (Auto). Implemented the frozen §KD-5a MCP domain surface:
  `muse/mcp/server.py` + `muse/mcp/namespaces/knowtation.py` with activation gate
  (`repo.json domain==knowtation`), `bootstrap_knowtation_mcp` (attestation + ICP hook registration),
  `search.lexical_search` + vector client + hybrid fan-out, hub `propose`, resource serializers,
  prime enrichment, 4 vault prompts, stdio entry (`python -m muse.mcp.stdio_server`). Seven-tier test
  matrix: 36 tests in `tests/test_knowtation_mcp_*.py` + Claude Desktop stdio integration against
  `knowtation-vault-smoke` (9 tools / 8 resources / 4 prompts list + search/prime round-trip).
  Full knowtation suite: **1606 passed**. Muse commit on `feat/kd-5b`. NEXT → **KD-6a** (Thinking).
- **2026-07-10** — **KD-5a DONE** (Thinking). Froze the Muse MCP domain-surface contract for the
  `knowtation` namespace (§KD-5a Contract): 9 tools, 8 resources, 4 prompts — each with JSON-RPC
  input/output schema, backing plugin API mapping, and error-reason enum. Resolved the five open
  contract items: (a) search fan-out `w_lex=0.4`/`w_vec=0.6`, path dedupe, 2 s vector timeout →
  lexical-only `degraded`; (b) `consolidate` dispatch-receipt schema, async completion observed via
  `memory/recent`; (c) attest runtime registration via `bootstrap_knowtation_mcp` (not `__init__.py`),
  `air.required` mode, `PROVIDER_UNREGISTERED` structured error; (d) `.museignore [domain.knowtation]`
  ignores `data/` for snapshots while `stats` still reads its mtime; (e) namespace mounts only on
  `.muse/repo.json domain==knowtation`, detector advisory. Specified the `muse/mcp/` mount point
  (server + `knowtation` namespace, both KD-5b new work) and musehub stdio/SSE hosting. Defined the
  seven-tier test matrix + Claude Desktop integration test against `knowtation-vault-smoke`. Flagged
  KD-5b new work (search lexical+vector, propose→hub, attest registration, resource serializers, MCP
  server scaffold). Muse commit on `feat/kd-5a`. NEXT → **KD-5b** (Auto).
- **2026-07-10** — **KD-OQ review pass** (independent model, read-only). Verified all 5 decisions against source; decisions stand. Corrected: prompt count 3→**4** (issue #2 Phase 5.3) and KD-5 tool list now includes `consolidate` (9 tools); tightened OQ1 (detector classifies; activation via `repo.json`), OQ2 (link_index/code_intel are live-file, not commit-snapshot; `data/` not auto-ignored), OQ4 (registration helpers exist but only the merge hook auto-registers — runtime wiring is KD-5a/5b). Added explicit KD-5a open contract items (search fan-out, consolidate return schema, attest wiring, `data/` ignore, activation semantics).
- **2026-07-10** — **KD-OQ DONE.** All 5 issue #2 open questions resolved with source-backed rationale (see table). Decisions: OQ1 frontmatter-primary + optional `.knowtation` marker; OQ2 Muse structural index + Knowtation live vector index (split); OQ3 async-dispatch pre-merge hook; OQ4 generic `MuseAttestationProvider` reusing the ICP canister; OQ5 keep SKILL.md separate. NEXT → **KD-5a** (MCP contract, Thinking).
- **2026-07-10** — **KD-ACTIVATE DONE.** Vault `knowtation-vault-smoke` activated; smoke 5 PASS / 3 PARTIAL. NEXT → KD-OQ. CLI gaps documented (merge dispatch, symbols routing, diff granularity).
- **2026-07-10** — Initial MuseHub Roadmap created. Phases 1–4 + 7 marked DONE (local); KD-ACTIVATE set as NEXT.