@reddb-io/red-skills-memory 2.75.2

package/skills/core/improve-skills/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: improve-skills
+description: Generate approval-gated Skill improvement proposals from Memory Skill telemetry. Use when repeated failures suggest a skill should be patched, but direct self-modification would be unsafe.
+disable-model-invocation: true
+---
+
+# memory improve-skills
+
+Generate concrete Skill improvement proposals from Skill telemetry evidence.
+
+<what-to-do>
+
+**Generate approval-gated Skill improvement proposals from telemetry evidence, review each one before applying, and never patch a skill without explicit human approval.**
+
+## 1. Run the proposal surface
+
+Prefer JSON when another agent or command will inspect the result:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" improve skills --json
+```
+
+To write proposal files:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" improve skills --write-proposal --json
+```
+
+To list and inspect pending proposal files before applying or archiving:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" improve proposals list --json
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" improve proposals show .red/memory/proposals/<proposal>.md --json
+```
+
+To apply a reviewed proposal that contains a structured patch block:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" improve apply .red/memory/proposals/<proposal>.md --yes --json
+```
+
+To remove a reviewed proposal from the pending queue without deleting history:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" improve proposals archive .red/memory/proposals/<proposal>.md --reason rejected --yes --json
+```
+
+The command writes proposals under:
+
+```text
+.red/memory/proposals/
+```
+
+## 2. Interpret states
+
+See [init-chain state taxonomy](../../references/PRECONDITIONS.md#init-chain-state-taxonomy) — for `uninitialized`, run `/memory:init`; for `no-op`, re-run with `--mode graph`; for `unavailable`, add `--skill-telemetry`.
+- `no-candidates` — telemetry does not currently support a proposal.
+- `proposal-ready` — dry-run found proposal candidates but wrote no files. JSON summaries include `recentFailures`, `dominantErrorStage`, `dominantErrorClass`, `patchDrafted`, `score`, `priority`, and `scoreReasons` for machine-readable routing.
+- `proposal-written` — proposal files were written or refreshed for review, including recent failure evidence, a deterministic `Fingerprint`, and a draft structured patch block when the skill file has a safe unique insertion anchor.
+- `applied` — an explicitly approved structured patch was applied.
+- `pending` — proposal lifecycle listing found pending proposal files.
+- `shown` — a specific proposal file was returned for review.
+- `archived` — a proposal was moved under `.red/memory/proposals/archive/<reason>/`.
+
+## 3. Review before applying
+
+For each proposal, inspect:
+
+- evidence category and reason;
+- target skill path;
+- hypothesis;
+- proposed patch targets;
+- validation plan.
+
+Only patch the skill after explicit human approval or an equivalent review gate.
+
+`memory improve apply` refuses to run unless all of these are true:
+
+- the command includes `--yes`;
+- the proposal contains a fenced ````json memory-skill-patch` block;
+- the proposal file and patch target remain inside `--root`;
+- `oldString` appears exactly once in the target file.
+
+Patch block format:
+
+````markdown
+```json memory-skill-patch
+{
+  "path": "plugins/dev/skills/example/SKILL.md",
+  "oldString": "text to replace",
+  "newString": "replacement text"
+}
+```
+````
+
+## 4. Preserve the safety boundary
+
+- ✅ Write proposals when telemetry shows repeated failure evidence.
+- ✅ Treat proposal files as review artifacts, not source of truth.
+- ✅ Use `memory improve proposals list/show/archive` to keep the pending queue clean and auditable.
+- ✅ Expect repeated runs to reuse a pending proposal with the same fingerprint instead of creating duplicates.
+- ✅ Review the generated `oldString`: it should target `Setup`/`Prerequisites` for setup failures, `Execution`/`Commands` for execute failures, `Verification`/`Validation` for verify failures, and `Troubleshooting`/`Common Pitfalls` for timeout/lock/rate-limit style failures when those sections exist.
+- ✅ Apply the smallest skill patch that addresses the observed failure mode.
+- ✅ Run repo metadata/skill validation after applying a proposal.
+- ✅ Include recent failed result evidence in proposals so reviewers see the stage/class/code that triggered the recommendation.
+- ✅ Rank proposal candidates by deterministic priority score so agents fix the highest-impact failure loops first.
+- ✅ Generate a draft `json memory-skill-patch` block only when the target skill is readable and has a safe unique anchor.
+- ✅ Require `--yes` and an exact `oldString` match before applying a proposal.
+- ❌ Do not let Memory patch anything unless the proposal has a structured apply block.
+- ❌ Do not let Memory archive proposals without `--yes` and an explicit `--reason applied|rejected|stale`.
+- ❌ Do not let Memory archive, delete, or rewrite Skill files outside the reviewed patch target.
+- ❌ Do not generate proposals from one-off failures without enough evidence.
+- ❌ Do not store secrets or raw transcript dumps in proposals.
+
+</what-to-do>
+
+<supporting-info>
+
+`memory improve skills` currently proposes fixes for curatable skills flagged as `frequently-failing` by partitioned Skill telemetry rollups. Each Evidence card gets a deterministic fingerprint from its telemetry source, refinement route, dominant error pattern, and telemetry window; unresolved cards in `captured`, `routed`, or `proposed` status with the same fingerprint are refreshed in place, while reviewed or terminal cards (`approved`, `rejected`, `promoted`, `archived`) are preserved and a later run creates a new card. Draft patch blocks choose a semantic section anchor from the dominant failure stage/class before falling back to a tail anchor. It is deliberately proposal-gated: the Memory plugin may write `.red/memory/proposals/*.md`, but applying a patch remains an explicit review step handled outside this command.
+
+This is the first mutating stage in the self-improvement loop. Proposal generation mutates only `.red/memory/proposals/`; proposal application can patch a target skill only when a reviewed structured block plus `--yes` are both present.
+
+</supporting-info>

package/skills/core/ingest/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ingest
+description: Walk a repo (or a subtree) and populate the memory graph from its code and markdown — symbols, files, headings, concepts, and the edges between them. Use when the user says "index this repo", "ingest the codebase into memory", "/memory:ingest …", or when you want recall to know about the project's structure before working in it. Requires `memory init --mode graph` to have run.
+---
+
+# memory ingest
+
+Indexes a project tree into the **graph** store with the deterministic
+extractors — no LLM calls. Code files (`.ts/.tsx/.js/.jsx/.py/.go/.rs`) become
+`file` + `symbol` nodes with `DEFINED_IN` edges; TypeScript/JavaScript files
+also become `import` nodes with `IMPORTS` edges for static import and re-export
+specifiers. Markdown files become `concept` nodes (one per file, one per h1–h3
+heading) with `REFERENCES` edges for every `[[wiki-link]]`, plus a stored doc
+chunk for later search. Everything dedupes by content hash, so re-ingesting an
+unchanged tree is a no-op.
+
+For changed-file freshness, use `memory refresh`: it stores a per-file content
+hash manifest, skips unchanged files, reports added / updated / skipped / stale
+graph elements, and supports hook-friendly `--staged` and `--stdin` modes. The
+first freshness implementation is hook-only; there is no filesystem watcher.
+
+This is the `EXTRACTED` (deterministic) ingest path only. Conversation/git
+(`INFERRED`) ingestion is not part of this surface.
+
+<what-to-do>
+
+**Index the repository tree into the graph store with the deterministic extractors, then relay the file, node, edge, and doc counts so the user knows what was graphed.**
+
+## 1. Require graph mode
+
+See [Memory preconditions](../../references/PRECONDITIONS.md). If memory is not initialized, run `/memory:init`. If `mode` is not `graph`, ingest has nothing to write to; tell the user to re-run `memory init --mode graph`.
+
+## 2. Ingest
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" ingest <path>
+```
+
+`<path>` is the directory to walk (defaults to `.`). Add `--max-files N` to cap
+the pass on a large monorepo. `node_modules/`, `dist/`, `.git/`, `.red/`, and
+build/coverage output are ignored by default.
+
+## 3. Scope a Large Repo
+
+Before graphing a big tree, scope the pass. The CLI always prints the
+**candidate-file count** before processing so you know what you're about to
+index. Narrow it with `--scope`:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" ingest <path> --scope core
+```
+
+| `--scope`         | What it graphs                                                        |
+| ----------------- | -------------------------------------------------------------------- |
+| `proceed`         | every candidate (the default)                                        |
+| `core`            | core/app source only — skips tests, examples, vendored & lib trees   |
+| `libs`            | shared library/package code only — skips app trees, tests & examples |
+| `generate-ignore` | writes a committed `.memoryignore` and stops (no ingest this run)     |
+
+`--scope generate-ignore` writes a **`.memoryignore`** at the repo root — a
+committed, human-editable, gitignore-style list of fast-glob patterns (one per
+line, `#` comments allowed). Commit it so the whole team shares the same graph
+scope. Every later `memory ingest` / `memory refresh` honours it automatically,
+with no re-prompt. Hand-edit it any time to add or remove patterns.
+
+## 4. Refresh Changed Files
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" refresh <file...> --root .
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" refresh --staged --root .
+git diff --cached --name-only -z | node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" refresh --stdin --root .
+```
+
+Use `refresh` after small edits or from git hooks. It is graph-mode only and
+does not require a daemon.
+
+## 5. Report
+
+The CLI prints the file / node / edge / doc counts. Relay them so the user knows
+what was indexed. For refresh, also relay added / updated / skipped / stale
+graph element counts. Then use `/memory:recall` to read the graph back.
+
+## DOs / DON'Ts
+
+- ✅ Ingest after `memory init --mode graph` so recall has structure to search.
+- ✅ Re-run ingest after large refactors — dedupe makes it cheap and keeps the graph current.
+- ✅ Use `memory refresh --staged` or `--stdin` from git hooks for daemon-free freshness.
+- ❌ Don't run ingest in markdown-only mode — there is no graph to populate.
+- ❌ Don't expect call/type graphs yet — this slice extracts symbols, TS/JS imports, and markdown structure only.
+
+</what-to-do>

package/skills/core/init/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: init
+description: One-time setup wizard for the memory plugin. Asks what storage to use and writes the per-project memory config. Two modes ship today — markdown-only (plain notes, no engine) and graph (governed operational memory over a per-project RedDB store). Hooks are optional in graph mode; MCP/read surfaces come with graph mode. Use when the user installs the memory plugin and wants to turn memory on, or says "memory init", "set up memory", "initialize memory".
+disable-model-invocation: true
+---
+
+# memory init
+
+<what-to-do>
+
+**Bootstrap memory for this repo: pick the storage mode with the user, run the wizard, and confirm which mode and hooks are active before pointing them at the next step.**
+
+## 1. Runtime is fetched automatically (no build step)
+
+`${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs` ships with the plugin and resolves
+the runtime on first use — it downloads the bundled CLI (`memory-cli.mjs`) plus
+the native `red` engine into `~/.cache/reddb-memory/<version>/` and verifies
+their checksums (ADR 0029). There is nothing to build or `pnpm install`; the
+first command below just pays a one-time download (needs network). Every command
+in these skills runs through the bootstrap, which delegates to the fetched CLI.
+
+## 2. Run the wizard
+
+Run from the repo you want memory in (`--root` defaults to the current dir).
+Pass the mode the user picked:
+
+```bash
+# markdown-only — no engine, nothing auto-fires
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" init --mode markdown-only
+
+# graph — typed knowledge graph over a per-project RedDB store
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" init --mode graph
+
+# graph with the four auto-firing hooks on (recall/index/extract/flush)
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" init --mode graph --hooks
+```
+
+markdown-only writes a `plugins.memory` block to `.red/config.yaml` (all hooks off, MCP off, RedDB
+not required) and creates `.red/memory/notes/`. graph writes the same config
+shape with `mode: "graph"`, `reddb: true`, a `storePath`, and provisions the
+RedDB store at `.red/memory/graph.rdb`.
+
+If graph mode was chosen, read [graph-reference.md](graph-reference.md) for the
+written config shape and how graph writes are stored.
+
+Ask the user whether to turn the auto-firing hooks on. Pass `--hooks` only in
+graph mode and only if they say yes; the hooks are wired in the plugin manifest
+but stay **dormant** (the CLI reads the config and exits silently) until the
+config flag is on. On **Codex**, also tell the user to set
+`[features].plugin_hooks = true` in their config — Codex hooks are off by
+default, and note that Codex has no `PreCompact` event (the flush leans on Stop
++ SessionStart there).
+
+## 3. Confirm
+
+Tell the user memory is on, which mode, whether the auto-firing hooks are on or
+off, and that they can now use `/memory:store <fact>` and
+`/memory:recall <query>` — which route to the configured mode automatically.
+For graph mode, mention the golden path: store one scoped decision/gotcha,
+recall it, verify with claim-check/readiness/governance, then hand off with a
+context pack when needed.
+
+## DOs / DON'Ts
+
+- ✅ Ask before passing `--hooks`; the config flag, not the manifest, is what makes a hook active vs dormant.
+- ❌ Don't require, install, or connect to RedDB in markdown-only mode.
+- ❌ Don't commit `.red/memory/graph.rdb*` — the store is per-project local state, like `node_modules/`.
+- ❌ Don't hand-write the `plugins.memory` block in `.red/config.yaml` — go through the CLI so the schema stays valid.
+
+</what-to-do>
+
+<supporting-info>
+
+## Storage modes
+
+- **markdown-only** — searchable project notes with **zero engine dependency**:
+  notes are plain markdown under `.red/memory/notes/`, no hooks fire, no MCP
+  server runs, RedDB is not required.
+- **graph** — governed operational memory (nodes + edges) over a per-project
+  RedDB store at `.red/memory/graph.rdb`. `/memory:store` writes deduped facts;
+  `/memory:recall` returns zero-token governed context with graph expansion,
+  provenance/trust, and supersession handling. RedDB is required, but it runs
+  out-of-process from the bundled binary — no service to manage. Graph mode can
+  also opt into **auto-firing hooks** (SessionStart recall, PostToolUse re-index,
+  Stop extract, PreCompact flush where the host supports it); they default off.
+
+Hybrid mode is not a separate storage mode: use markdown-only for plain notes or
+graph for governed operational memory. markdown-only never gets hooks. MCP/read
+surfaces are available from the fetched CLI; hook activation still comes from the
+per-project config.
+
+## Plugin dependency
+
+The `memory` plugin requires the `dev` plugin (it builds on dev's processes —
+`/afk`, `/triage`, `/diagnose`). Install `dev` first.
+
+</supporting-info>

package/skills/core/init/graph-reference.md

@@ -0,0 +1,40 @@
+# Graph-mode reference
+
+Read this only when graph mode was chosen — the config shape written for the
+`plugins.memory` block and how graph writes are stored.
+
+## Config shape
+
+markdown-only:
+
+```json
+{
+  "version": 1,
+  "mode": "markdown-only",
+  "notesDir": ".red/memory/notes",
+  "hooks": { "sessionStart": false, "postToolUse": false, "stop": false, "preCompact": false },
+  "mcp": false,
+  "reddb": false
+}
+```
+
+graph:
+
+```json
+{
+  "version": 1,
+  "mode": "graph",
+  "notesDir": ".red/memory/notes",
+  "storePath": ".red/memory/graph.rdb",
+  "hooks": { "sessionStart": false, "postToolUse": false, "stop": false, "preCompact": false },
+  "mcp": false,
+  "reddb": true
+}
+```
+
+## Graph storage internals
+
+Graph writes go through RedDB's multi-model DML (`INSERT … NODE/EDGE`), not
+table inserts, and dedupe lives in a KV index — see ADR 0007 for the engine
+constraints. The store is the embedded `file://` RedDB; the SDK spawns the
+bundled `red` binary out-of-process, so there is no service to run.

package/skills/core/recall/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: recall
+description: Search the project's configured memory surface and return governed context ranked by relevance. Use when the user asks "what do we know about …", "did we decide …", "have we seen this before", "/memory:recall …", or when you want past decisions/gotchas before acting. Requires `memory init` to have run.
+---
+
+# memory recall
+
+Searches the project's memory for facts stored by `/memory:store`, ranked by how
+strongly they match the query — the zero-token read path, no LLM extraction. In
+**markdown-only** mode it full-text-searches the notes; in **graph** mode it runs
+the governed recall engine — deterministic text seeds expanded through the graph
+neighborhood, ranked with tier/trust/recency/centrality, hiding superseded nodes
+behind the current head of a `SUPERSEDED_BY` chain. Vector hits can contribute
+when a vector provider/projection is explicitly ready, but recall is not
+vector-first. Routing follows `memory init`. Graph mode also exposes
+`search`/`neighbors`/`traverse`/`path`/`stats` read verbs, MCP (`memory-mcp`),
+HTTP, context-pack, readiness, claim-check, and Workbench diagnostics; see the
+plugin README.
+
+<what-to-do>
+
+**Search the memory graph for facts matching the query and fold the ranked hits into your answer — do not re-derive what the project may already know.**
+
+## 1. Require init
+
+If memory is not configured — see [Memory preconditions](../../references/PRECONDITIONS.md) — there is nothing to recall; suggest `/memory:init`.
+
+## 2. Recall
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" recall <query terms>
+```
+
+Everything after `recall` is the query. Add `--limit N` to cap results
+(default 10).
+
+## 3. Use the hits
+
+Read the returned evidence and fold what's relevant into your answer or your
+next step — cite the fact, don't just dump the list. Treat recall as a governed
+context candidate set: verify stale/high-impact claims before relying on them.
+If there are no matches, say so plainly rather than guessing.
+
+## DOs / DON'Ts
+
+- ✅ Recall before re-deriving something the project may already know.
+- ✅ Treat a recalled note as a claim made at store time — verify it still holds before relying on it.
+- ❌ Don't assume an empty result means the fact is false — it may just be unstored.
+
+</what-to-do>

package/skills/core/skills-status/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: skills-status
+description: Diagnose Skill telemetry status and recent Skill usage events. Use when checking whether self-improvement telemetry is enabled, whether skills are being observed, or before running the report-only Skill curator. Graph mode with `--skill-telemetry` provides full output; all other states explain what is missing.
+---
+
+# memory skills-status
+
+Read-only diagnostic for the self-improvement loop. It shows whether Skill telemetry is uninitialized, unavailable, or enabled; when enabled, it lists observed skills, recent events, and outcome counts.
+
+<what-to-do>
+
+**Run the skills-status diagnostic, interpret the telemetry state, and recommend the next concrete action — never mutate skills from this command.**
+
+## 1. Run the diagnostic
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" status skills
+```
+
+Use `--all` to include bundled plugin/hub skills, and `--json` when another script needs structured output.
+
+## 2. Interpret the state
+
+See the [init-chain state taxonomy](../../references/PRECONDITIONS.md#init-chain-state-taxonomy). For the `uninitialized` case, recommend `memory init --mode graph --skill-telemetry`; for `no-op`, graph mode is required; for `unavailable`, the explicit `skillTelemetry` opt-in is off.
+- `enabled` — read partitioned rollups and recent events; rollups are stored per skill/event marker so telemetry scales beyond the engine KV value cap.
+
+Do not treat non-enabled states as errors; this command is a diagnostic and exits cleanly.
+
+## 3. Decide the next action
+
+- If telemetry is enabled and the user wants maintenance recommendations, run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" curate skills
+```
+
+- If there are archive candidates and the user wants to act, use the `dev` plugin's `/curate` workflow. The Memory plugin's curator is report-only.
+- If events are empty, tell the user telemetry is enabled but no skill use has been observed yet.
+
+## DOs / DON'Ts
+
+- ✅ Run before `/curate` so you know whether telemetry is collecting evidence.
+- ✅ Keep default output focused on Curatable skills; use `--all` for bundled read-only skills.
+- ❌ Do not mutate skills from this command.
+- ❌ Do not infer skill quality from one failure; use curator thresholds and human review.
+
+</what-to-do>

package/skills/core/store/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: store
+description: Save one durable work fact to the project's configured memory surface. Use when the user says "remember this", "store that …", "/memory:store …", or when you want a scoped decision, gotcha, validation, or why-note to survive across sessions. Requires `memory init` to have run.
+---
+
+# memory store
+
+Saves one fact to the project's memory and routes to whatever `memory init`
+configured. In **markdown-only** mode it writes a markdown note under
+`.red/memory/notes/` — the note **is** the canonical store, human-readable and
+committable. In **graph** mode it writes a deduped node to the RedDB store
+(storing the same fact twice returns the same node) with the
+metadata needed for governed recall, freshness, and later supersession. Either
+way the fact is recallable later with `/memory:recall`.
+
+<what-to-do>
+
+**Save one fact to the project memory — a decision, a gotcha, or a why-note — and confirm the stored identity so the user knows what was captured.**
+
+## 1. Require init
+
+If memory is not configured — see [Memory preconditions](../../references/PRECONDITIONS.md) — run `/memory:init` before storing.
+
+## 2. Store the fact
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/bootstrap.mjs" store <the fact text>
+```
+
+Pass the fact as the argument (everything after `store` is joined into one
+note). The CLI routes by config. Markdown-only writes `<timestamp>-<slug>.md` with YAML
+frontmatter and the fact as the body. Graph mode prints the stored/deduped node
+identity and keeps the durable evidence in `.red/memory/graph.rdb`.
+
+## 3. Confirm
+
+Report the note path or graph node id so the user knows what was captured.
+
+## DOs / DON'Ts
+
+- ✅ Store a single, self-contained fact per call (a decision, a gotcha, a why-note).
+- ✅ Capture the *why*, not just the *what*, when the user is explaining a decision.
+- ❌ Don't store Personal facts (biographical details, identity context, long-lived human preferences) in Memory — see [Brain-vs-Memory boundary](../../../../brain/skills/references/BRAIN_VS_MEMORY.md) and route to `brain capture` instead.
+- ❌ Don't store secrets — notes are plain text on disk and may be committed.
+- ❌ Don't hand-write files into `notesDir` — go through the CLI so ids and frontmatter stay consistent.
+
+</what-to-do>

package/skills/core/view/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: view
+description: Open the project Memory graph in red-ui (the visual cluster/query/collections workspace) by pointing the red-ui MCP App at the local RedDB store, falling back to the browser Workbench in terminal hosts. Use when the user wants to SEE the memory graph, clusters, or collections visually rather than recall text.
+disable-model-invocation: true
+---
+
+# memory view
+
+Opens the project's Memory graph store (`.red/memory/graph.rdb`) as a visual workspace. The graph data is served by RedDB; this skill only points a renderer at it — it never mutates the store.
+
+<what-to-do>
+
+**Resolve the store, pick a view, then open it host-aware: the red-ui MCP App in a GUI host, the browser Workbench in a terminal. Read-only — never write to the store, never seed a token in any URL.**
+
+### 1. Resolve the store
+
+- Default store path: `.red/memory/graph.rdb` (repo-relative). If `.red/config.yaml` sets `plugins.memory.storePath`, use that instead. Resolve to an absolute path.
+- If the file does not exist, or Memory is in `markdown-only` mode (no graph): tell the user there is no graph to view, point them at `/memory:init` (graph mode) + `/memory:ingest`, and stop. Do not invent a connection.
+
+### 2. Pick the view
+
+Map the user's intent to red-ui's view enum (default `cluster` — the graph):
+
+- graph / clusters / communities → `cluster`
+- query / search / cypher → `query`
+- collections / tables → `collections`
+- home / overview → `home`
+
+### 3. Open it — host-aware
+
+- **GUI / MCP-Apps host** (Claude Desktop, claude.ai, VS Code, Cursor, …): call the red-ui MCP tool **`open_red_ui`** with `{ "connectionUrl": "<abs path to the .rdb store>", "view": "<view>" }`. red-ui spawns a local single-writer `red server` for the file (read-only if the Memory engine already holds it) and renders the workspace embedded in the chat.
+- **Terminal host** (Claude Code), or red-ui unavailable / the app does not render: MCP Apps need an iframe surface a terminal does not have. Fall back to the **Workbench** — run `memory serve` to expose the store over `http://localhost:<port>` and give the user the URL to open in a browser (or `memory workbench` for the static artifact). State clearly that you used the fallback and why.
+
+### Hard rules
+
+- ❌ Never write to or mutate the store — this is a read-only viewer.
+- ❌ Never put a secret/token in `connectionUrl` or any iframe URL (red-ui seeds only the non-secret endpoint + route; tokens go over the later postMessage channel).
+- ❌ Do not invent a connection — if the store is absent, stop and route to `/memory:init` / `/memory:ingest`.
+- ✅ Default to `cluster` (the graph) when the user just says "show me the memory graph".
+- ✅ Always name which surface opened (embedded MCP App vs browser Workbench fallback).
+
+</what-to-do>
+
+<supporting-info>
+
+### Why host-aware
+
+MCP Apps (SEP-1865) render a server-provided `ui://` HTML resource inside a sandboxed iframe — only GUI hosts have that surface. The red-ui MCP server (wired into this plugin's `.mcp.json` as `red-ui`) advertises `ui://red-ui/app.html`; the graph data itself is read by the red-ui app **directly from RedDB over HTTP**, not through the MCP bridge — the bridge only passes the connection URL and the view. A terminal host (Claude Code) cannot render the iframe, so the Workbench (`memory serve`) is the equivalent surface there.
+
+### connectionUrl forms
+
+- **File path** (e.g. the resolved `.red/memory/graph.rdb`) — red-ui spawns its own `red server` for the file (ADR-0006 single-writer flock; read-only if the Memory engine holds it).
+- **HTTP URL** (e.g. `http://localhost:5055`) — if a `red`/`memory serve` process is already serving the store, pass its URL directly.
+
+### red-ui views
+
+`home · query · collections · cluster · security` — `cluster` is the graph/communities visualization.
+
+</supporting-info>

package/skills/core/wiki/C4-reference.md

@@ -0,0 +1,101 @@
+# C4 Diagram — reference
+
+How to build and maintain the wiki's C4 model. The `wiki` skill decides *when* C4 work triggers (the Ingest C4-awareness step and the Lint C4-staleness check own those conditions); this file describes *how* to write it.
+
+Optional, complexity-gated. When the system has enough moving parts that one person can't keep the architecture in their head — typically **≥3 services / containers** or any non-trivial cross-system integration — maintain a [C4 model](https://c4model.com) at `.red/wiki/C4.md`. It is the single architectural map for the project; every other wiki page that touches structure references it. The wiki never auto-creates `C4.md` — when a trigger fires and the file is absent, propose creation; once it exists, keep it current.
+
+## Structure
+
+The Mermaid block stays minimal (it is just a rendering aid). The **prose around it carries the full C4 content** — actor/system/container/component names, responsibilities, technology choices, relationship semantics.
+
+````markdown
+# C4 — <system name>
+
+<one-line description, using the canonical system name from .red/CONTEXT.md>
+
+updated: <YYYY-MM-DD>
+context: ../CONTEXT.md   _(this file is bound to the glossary — every label below must match)_
+
+## Level 1 — Context
+
+```mermaid
+flowchart LR
+  user([User])
+  sys[System]
+  ext[(External service)]
+  user --> sys
+  sys -->|HTTPS| ext
+```
+
+**Actors**
+
+- **User** _(from CONTEXT.md)_ — <responsibility, what they want from the system>.
+
+**Systems**
+
+- **System** _(from CONTEXT.md)_ — <purpose, in one sentence>.
+- **External service** _(from CONTEXT.md)_ — <what it provides, why we depend on it>.
+
+**Relationships**
+
+- User → System: <how they interact, protocol, frequency>.
+- System → External service: <calls made, data exchanged, failure mode>.
+
+## Level 2 — Container
+
+```mermaid
+flowchart LR
+  user([User])
+  subgraph sys[System]
+    api[API]
+    db[(Postgres)]
+  end
+  user -->|HTTPS| api
+  api -->|SQL| db
+```
+
+**Containers (inside System)**
+
+- **API** _(from CONTEXT.md)_ — <responsibility>. Tech: <language, framework>. Owner: <team / module>.
+- **Postgres** _(from CONTEXT.md)_ — <what it stores>. Tech: <version, hosting>.
+
+**Relationships**
+
+- User → API: <protocol, auth, payload shape>.
+- API → Postgres: <connection style, transaction discipline>.
+
+## Level 3 — Component _(per container; only where complexity warrants)_
+
+### API _(from CONTEXT.md)_
+
+```mermaid
+flowchart LR
+  in([request]) --> handler --> service --> repo[(db)]
+```
+
+**Components**
+
+- **Handler** _(from CONTEXT.md)_ — <HTTP-facing layer, validation, auth>.
+- **Service** _(from CONTEXT.md)_ — <domain logic, orchestration>.
+- **Repo** _(from CONTEXT.md)_ — <persistence layer, queries owned>.
+
+**Relationships**
+
+- Handler → Service: <DTO shape, sync/async>.
+- Service → Repo: <which methods, transactional boundary>.
+
+## Notes
+
+- <decisions, assumptions, gaps, "to-be-decided" items — same vocabulary as above>
+- New terms surfaced during diagramming that need a CONTEXT.md entry: <list, or "none">.
+````
+
+The Mermaid syntax is intentionally simple — `flowchart` (universally rendered by every Mermaid viewer including GitHub), not `C4Context` / `C4Container` / `C4Component` (experimental, breaks in many renderers). Shape conventions: `[box]` for system/container/component, `([rounded])` for actor, `[(cylinder)]` for datastore, `subgraph` for "lives inside". The diagram is the index; the prose is the substance.
+
+Level 4 (Code) is intentionally omitted — derive it from the source on demand.
+
+## Vocabulary discipline
+
+Every name used in the diagram and the prose must match a term already defined in `.red/CONTEXT.md`. If you find yourself writing a name in `C4.md` that is not in the glossary, stop and update the glossary first, then reference it here. The C4 inherits its words from CONTEXT — never the other way around. A term invented inside `C4.md` without a glossary entry is a contradiction the next lint pass will flag.
+
+Bump the `updated:` frontmatter on every meaningful edit. The Lint staleness check uses that field to decide whether sources have outpaced the diagram.