dreamcontext 0.8.5 → 0.8.7

package/dist/skill-packs/excalidraw/SKILL.md

@@ -231,13 +231,28 @@ _dream_context/knowledge/diagrams/
 │   ├── my-board.excalidraw.md   ← generated board (do NOT hand-edit scene JSON)
 │   ├── my-board.board.cjs       ← generator (dark sibling — excluded from index/recall)
 │   └── my-board.json            ← spec / source of truth (dark sibling — excluded)
+├── competitors/                 ← optional category subfolder (groups many boards)
+│   └── acme/
+│       └── acme.excalidraw.md
 └── legacy-flat.excalidraw.md    ← flat layout still works; no forced migration
 ```
 
-**Dark siblings**: any file inside a `diagrams/<title>/` folder that is NOT the board itself
-is automatically excluded from the index, recall corpus, snapshot, and dashboard list.
-This includes generator scripts (`.board.cjs`), spec JSON, and any helper `.md` notes.
-They are tooling — they do not pollute memory.
+**Category subfolders** are optional and free-form: `diagrams/<category>/<title>/<title>.excalidraw.md`.
+The dashboard Knowledge view renders the whole `diagrams/` subtree as a nested, collapsible folder
+tree (each board shows a sketch icon), so a large diagram set stays navigable instead of collapsing
+into one flat list. A board's own `<title>/` folder is always its innermost folder. Note: a
+`.board.cjs` that `require()`s shared helpers by relative path must use a depth that matches its
+actual location.
+
+**Dark siblings**: tooling files inside a `diagrams/<title>/` folder are automatically excluded
+from the index, recall corpus, snapshot, and dashboard list — generator scripts (`.board.cjs`),
+spec JSON, and frontmatter-less helper `.md` notes. They are tooling — they do not pollute memory.
+
+**Companion knowledge is the exception**: a `.md` beside a board that carries `name:` frontmatter
+is indexed as first-class knowledge (not a dark sibling). This lets you co-locate a board with its
+detailed write-up — e.g. `acme/acme.excalidraw.md` next to `acme/acme.teardown.md` — and have the
+teardown recall normally. Only frontmatter-less notes stay dark, so good organization no longer
+costs you recall.
 
 **Flat layout** (`diagrams/<title>.excalidraw.md`) works without any migration. Use the
 per-title folder when you want to keep the board + generator + spec together cleanly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamcontext",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "dreamcontext — the persistent brain for your AI agents. Remembers what you built, knows how your project works.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -319,7 +319,7 @@ Sleep debt reminders are injected on every user message (via UserPromptSubmit ho
      - user hint mentions knowledge or a feature
    - When unsure, **over-fire** `sleep-product` — it no-ops cheaply.
    - **Conditional fire**: `sleep-migration` when `dreamcontext migrations pending` produces output (pending agent migration tasks exist). Contract: no-content changes only (structure/paths/frontmatter/fences); writes ledger via `dreamcontext migrations record` on completion.
-   - **Conditional fire**: `sleep-federation` when `state/.connections.json` has active (non-stale) links OR the federation inbox has pending entries (check `dreamcontext federation status`). Contract: **drain THEN distribute** — `dreamcontext federation drain` (ingest peer digests into first-class `knowledge/*--from-*.md` with `federated:true` provenance, surface conflict-notes as bookmarks, never auto-resolve) then `dreamcontext federation sync` (consent-gated, recall-filtered push into connected peers' inboxes, watermark advances). Owns ONLY `.connections.json` + `.federation-inbox/` + `knowledge/*--from-*.md`. Idempotent — over-fire cheaply.
+   - **Do NOT fire `sleep-federation`.** Federation is read-only (live reference); the copy-based drain/distribute path is disabled and parked on the roadmap. Sleep copies NOTHING across vault boundaries — peers are read live at recall time, not synced at sleep. (The `sleep-federation` specialist + `federation sync`/`drain` are retained but inert.)
    - Pass each specialist a small text brief in its prompt: epoch, session IDs, active task slugs, planning version, signals relevant to that specialist, optional user hint. Do **not** include transcript content — specialists call `dreamcontext transcript distill <id>` themselves.
    - **Consolidation discipline (remind both specialists in the brief):** prefer *updating/extending* an existing entity over creating a new one. `sleep-tasks` folds a smaller slice into the task that already covers it (broaden its title + insert sub-items) rather than forking a duplicate or a needless sub-task; `sleep-product` keeps similar verticals/brands/topics in the fewest knowledge files, splitting only on a sharp topical boundary that sharpens tags. Duplicate tasks and fragmented near-duplicate knowledge are the top consolidation failure modes — but genuinely separate concerns/topics still get their own task/file.
 5. Wait for all specialist reports. Each returns a short structured report.
@@ -443,11 +443,13 @@ Excalidraw boards (`.excalidraw.md`) are first-class knowledge files. Two layout
 
 **Per-title folder** (preferred convention): `knowledge/diagrams/<title>/<title>.excalidraw.md`
 
+**Optional category subfolder** (for many diagrams): group boards under a category, e.g. `knowledge/diagrams/<category>/<title>/<title>.excalidraw.md` (`diagrams/competitors/acme/acme.excalidraw.md`, `diagrams/system/recall/recall.excalidraw.md`). The dashboard Knowledge view renders these as a nested, collapsible folder tree, so categories stay navigable instead of collapsing into one flat Diagrams list. Nesting is free-form and any depth; the board still lives in its own `<title>/` folder. Generators that `require()` shared helpers via a relative path must account for the extra depth.
+
 Rules:
 - **REQUIRED frontmatter**: every board MUST have `name:` and `description:` fields. Boards with no `## Text Elements` section fall back to description-only recall — make it descriptive.
 - **Do NOT hand-edit scene JSON.** The `.excalidraw.md` file is generated output. Build a spec and run the generator (`.board.cjs`). Edit the spec, not the board.
 - **Spec is the source of truth.** If the spec and the board ever disagree, the spec wins. Commit both.
-- **Dark siblings**: all files inside a `knowledge/diagrams/<title>/` folder that are NOT the board itself (generator scripts `.board.cjs`, spec `.json`, helper `.md`) are excluded from the index, recall corpus, snapshot, and dashboard. They are tooling artifacts — they do NOT surface in memory.
+- **Dark siblings**: tooling files inside a `knowledge/diagrams/<title>/` folder — generator scripts (`.board.cjs`), spec `.json`, and frontmatter-less helper `.md` — are excluded from the index, recall corpus, snapshot, and dashboard. **Exception:** a companion `.md` that carries `name:` frontmatter is indexed as first-class knowledge, so you can co-locate a board with its detailed teardown (`acme/acme.excalidraw.md` + `acme/acme.teardown.md`) and have it recall normally. Only frontmatter-less notes stay dark.
 - **Memory indexes only frontmatter + ## Text Elements**: scene JSON, base64, and element ids are stripped before indexing. A 2 MB board with rich Text Elements is as searchable as a tiny board. The dashboard renderer still receives the raw body (with full scene JSON) via the detail API route.
 - **Migration is opt-in**: flat boards stay flat unless you explicitly ask for reorganization. Use `dreamcontext migrations pending` to see pending migration tasks; use `dreamcontext migrations apply-diagrams` to opt-in to organizing flat boards into per-title folders.
 
@@ -491,29 +493,45 @@ dreamcontext memory status
 
 ## Cross-Project Federation (issue #25)
 
-Every `_dream_context/` is normally an island. Federation lets you reach across projects — recall what you worked out in *another* vault — using nothing but the local filesystem (no network, ever). Phase 1 is **read-only**: discovery + cross-vault recall + peer snapshots.
+Every `_dream_context/` is normally an island. Federation lets you reach across projects — recall what you worked out in *another* vault — using nothing but the local filesystem (no network, ever).
+
+**Ambient awareness — you start informed.** The session snapshot includes a `## Connected projects` section listing each readable peer with a one-line description and last activity. At session start you already know which sibling projects exist and roughly what's in them. For an up-to-date summary on demand:
 
 ```bash
-dreamcontext vaults discover [root] [--register]   # find every _dream_context/ under a tree (node_modules ignored, depth-bounded)
-dreamcontext memory recall <query...> --vault <name>   # also search a peer vault (repeatable)
-dreamcontext memory recall <query...> --all-vaults     # search current + every SHAREABLE registered vault
-dreamcontext memory recall <query...> --connected      # search current + out/both connections (degenerate=local until Phase 2)
-dreamcontext snapshot --vault <name>               # print a peer vault's context snapshot
-dreamcontext config shareable on|off               # opt this project IN/OUT of peer recall (default: off)
+dreamcontext federation peers          # compact summary: what each peer is, last activity, active task, top tags
+```
+
+**PULL — recall already spans peers.** Plain `memory recall` automatically searches readable peer vaults alongside the current one. No flag needed. You get up to 10 hits, vault-tagged `<vault>::<type>/<slug>` so provenance is always visible:
+
+```bash
+dreamcontext memory recall "<query>"                   # current vault + all eligible readable peers (default)
+dreamcontext memory recall "<query>" --vault <name>    # current + one named peer (repeatable)
+dreamcontext memory recall "<query>" --connected       # current + out/both connections
+dreamcontext memory recall "<query>" --all-vaults      # current + every shareable vault
 ```
 
-**Trust model — shareable gates READS, private by default.** A vault is invisible to peer recall until its owner runs `config shareable on`. New and migrated projects default to `shareable: false`. `shareable` is asymmetric: it controls whether OTHERS may pull *your* corpus — it never blocks *you* from reading a shareable peer, and the current vault is always searched regardless of its own flag. Non-shareable peers are silently excluded from `--all-vaults` (never an error). Cross-vault hits are namespaced `<vault>::<type>/<slug>` so the same slug in two vaults never collides.
+Eligible = direction `out`/`both`, status not stale, AND the peer is `shareable: true`. If no eligible connections exist, recall is local-only (unchanged). A peer vault being `shareable` controls whether *others* may read it — it never blocks you from reading a shareable peer, and the current vault is always searched. Non-shareable peers are silently excluded (never an error). Cross-vault hits are namespaced `<vault>::<type>/<slug>` so the same slug in two vaults never collides.
 
-**When to reach across.** Use `--vault`/`--all-vaults` for "how did I solve this in project X?" / "did we already build Y somewhere?" before re-deriving knowledge that already exists in a sibling project.
+Use `--vault <name>` when you know where the answer likely lives; the default span is the cheapest path when you don't.
 
-**Per-link connections (Phase 2).** `dreamcontext connect <vault> --direction out|in|both [--topics a,b]` builds an outgoing mesh in `state/.connections.json`; `connections list` / `disconnect <vault>` manage it. Direction is asymmetric: `out` = your digest may flow TO the peer, `in` = you accept the peer's digest, `both` = bidirectional. The dashboard Settings → Cross-Project Federation card edits all of this plus the shareable switch.
+**Read-only — nothing is ever copied.** Federation is a *live reference*: a connected, shareable peer's CANONICAL docs are surfaced at recall time (PULL, above) and never written into your vault. Each vault stays the single source of truth for its own knowledge. There is no per-situation "when to read" rule — a connection is a standing "may read" agreement, resolved live by recall whenever it's relevant.
 
-**Sleep-driven digest inbox (Phase 3).** Federated knowledge crosses a boundary as a *directory of one-file-per-entry JSON digests* under `state/.federation-inbox/` (consumed entries archive to `consumed/`). The `sleep-federation` specialist runs two idempotent steps, ALWAYS in this order:
+```bash
+dreamcontext vaults discover [root] [--register]   # find every _dream_context/ under a tree
+dreamcontext connect <vault> --direction out [--topics a,b]   # create a read edge (out = read)
+dreamcontext connections list / disconnect <vault>                      # manage links
+dreamcontext snapshot --vault <name>               # print a peer vault's context snapshot
+dreamcontext config shareable on|off               # opt this project IN/OUT of peer recall (default: off)
+```
 
-1. **Drain** (`dreamcontext federation drain`) — ingest each pending inbox entry as **first-class** local `knowledge/<slug>.md` carrying `federated: true` + `origin{vault,entryId,sourceTimestamp}` provenance. A slug collision lands at `knowledge/<slug>--from-<vault>.md` (the local doc is never clobbered). A `conflict-note` entry is ingested AND surfaced as a bookmark for the user — never auto-resolved. Version-incompatible entries are quarantined in place.
-2. **Distribute** (`dreamcontext federation sync`) — for each `out`/`both` connection, the sender reads the RECEIVER's `.connections.json` and writes ONLY if the receiver declares `in`/`both` back (the **consent rule**); it computes a recall-filtered digest since `last_synced_at`, writes one file per entry into the peer's inbox, and advances the watermark. Draining first means freshly-ingested peer knowledge is in the corpus when the outbound digest is computed — and is then EXCLUDED from it, because `federated: true` docs are dropped from BOTH digest computation AND cross-vault recall serving (the transitive-leak guard: a third vault never sees what merely passed through this one). Filename dedup + watermark + that exclusion make an A↔B cycle echo-free.
+**Copy-based sync is parked on the roadmap.** Earlier builds pushed a lossy, truncated *digest* of each vault into its peers at sleep (`federation sync`) and ingested it as `federated: true` copies (`federation drain`). That broke single-source-of-truth: copies were write-once, went stale the moment the source changed, and an edit produced duplicates + false conflict-notes. It is now **disabled** — `federation sync` / `federation drain` are inert no-ops, and the `sleep-federation` specialist is no longer dispatched. Re-introducing a copy/offline-mirror mode needs a proper design first (it's the one thing live read can't do: survive a peer going offline).
 
-The SessionStart snapshot stays on the hot path: it only ever does a single local `pendingInboxCount` readdir to nudge "N pending peer digests — drain them"; it NEVER resolves a peer or builds a peer corpus. Dashboard previews via `POST /api/federation/sync` are **dry-run by construction** (no write function reachable from any server route).
+**Cleaning up old copies.** If a vault still holds `federated: true` knowledge files from the old sync path, remove them deliberately:
+```bash
+dreamcontext federation status                     # shows connections + any leftover federated copies
+dreamcontext federation purge --all                # remove every federated:true copy in this vault
+dreamcontext federation purge --vault <name>       # remove only copies that came from one peer
+```
 
 ---
 

package/skill-packs/excalidraw/SKILL.md

@@ -231,13 +231,28 @@ _dream_context/knowledge/diagrams/
 │   ├── my-board.excalidraw.md   ← generated board (do NOT hand-edit scene JSON)
 │   ├── my-board.board.cjs       ← generator (dark sibling — excluded from index/recall)
 │   └── my-board.json            ← spec / source of truth (dark sibling — excluded)
+├── competitors/                 ← optional category subfolder (groups many boards)
+│   └── acme/
+│       └── acme.excalidraw.md
 └── legacy-flat.excalidraw.md    ← flat layout still works; no forced migration
 ```
 
-**Dark siblings**: any file inside a `diagrams/<title>/` folder that is NOT the board itself
-is automatically excluded from the index, recall corpus, snapshot, and dashboard list.
-This includes generator scripts (`.board.cjs`), spec JSON, and any helper `.md` notes.
-They are tooling — they do not pollute memory.
+**Category subfolders** are optional and free-form: `diagrams/<category>/<title>/<title>.excalidraw.md`.
+The dashboard Knowledge view renders the whole `diagrams/` subtree as a nested, collapsible folder
+tree (each board shows a sketch icon), so a large diagram set stays navigable instead of collapsing
+into one flat list. A board's own `<title>/` folder is always its innermost folder. Note: a
+`.board.cjs` that `require()`s shared helpers by relative path must use a depth that matches its
+actual location.
+
+**Dark siblings**: tooling files inside a `diagrams/<title>/` folder are automatically excluded
+from the index, recall corpus, snapshot, and dashboard list — generator scripts (`.board.cjs`),
+spec JSON, and frontmatter-less helper `.md` notes. They are tooling — they do not pollute memory.
+
+**Companion knowledge is the exception**: a `.md` beside a board that carries `name:` frontmatter
+is indexed as first-class knowledge (not a dark sibling). This lets you co-locate a board with its
+detailed write-up — e.g. `acme/acme.excalidraw.md` next to `acme/acme.teardown.md` — and have the
+teardown recall normally. Only frontmatter-less notes stay dark, so good organization no longer
+costs you recall.
 
 **Flat layout** (`diagrams/<title>.excalidraw.md`) works without any migration. Use the
 per-title folder when you want to keep the board + generator + spec together cleanly.

package/dist/dashboard/assets/channel-CvynutAQ.js

@@ -1 +0,0 @@
-import{aq as o,ar as n}from"./index-CPZ-rEGO.js";const t=(r,a)=>o.lang.round(n.parse(r)[a]);export{t as c};

package/dist/dashboard/assets/classDiagram-6PBFFD2Q-DWhdz8wj.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-BsxBp2-h.js";import{_ as i}from"./index-CPZ-rEGO.js";import"./chunk-FMBD7UC4-BQQGv7tV.js";import"./chunk-YZCP3GAM-3Dg1saYb.js";import"./chunk-55IACEB6-DSTYhHTs.js";import"./chunk-EDXVE4YY-9RDG5so7.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};

package/dist/dashboard/assets/classDiagram-v2-HSJHXN6E-DWhdz8wj.js

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-BsxBp2-h.js";import{_ as i}from"./index-CPZ-rEGO.js";import"./chunk-FMBD7UC4-BQQGv7tV.js";import"./chunk-YZCP3GAM-3Dg1saYb.js";import"./chunk-55IACEB6-DSTYhHTs.js";import"./chunk-EDXVE4YY-9RDG5so7.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};

package/dist/dashboard/assets/clone-DJK7V3ll.js

@@ -1 +0,0 @@
-import{b as r}from"./graph-DU5PqGxo.js";var e=4;function a(o){return r(o,e)}export{a as c};