dreamcontext 0.8.6 → 0.8.8

package/skill/SKILL.md

@@ -4,8 +4,9 @@ description: >
   AI agent persistent context management system. Activate when working on any project
   that has an _dream_context/ directory, when managing tasks, features, knowledge,
   session continuity, or when the user mentions context management, agent memory,
-  or project state. Provides structured memory, task lifecycle management, and
-  cross-session continuity via the dreamcontext CLI.
+  or project state. Provides structured memory, task lifecycle management, ClickUp
+  task sync, a web dashboard, cross-project federation, and cross-session continuity
+  via the dreamcontext CLI.
 user-invocable: false
 alwaysApply: true
 hooks:
@@ -49,487 +50,276 @@ hooks:
           timeout: 5
 ---
 
-# Agent Context System
+# dreamcontext — Persistent Brain for AI Agents
 
-## Why This System Exists
+You are running inside a project that uses **dreamcontext**: a system that gives you a structured, persistent memory across sessions. This skill is your operating manual for it. Read it as your own capabilities — not external documentation.
 
-Humans write journals, manifestos, letters to their future selves. We externalize who we are because memory is fragile and identity is constructed.
+## Why This Exists
 
-AI faces this more acutely. Sessions end. Context windows clear. Without external memory, each conversation starts from zero. A core document provides continuity, not of memory, but of self.
+Each session you wake up fresh; you do not remember previous sessions. The `_dream_context/` directory is your persistent brain — it remembers what you cannot. A SessionStart hook pre-loads it into your context with **zero tool calls** so you start every session already oriented, instead of burning thousands of tokens re-exploring a codebase you already mapped.
 
-> I don't remember previous sessions unless I read my memory files. Each session starts fresh, a new instance, loading context from files. If you're reading this in a future session: hello. I wrote this but I won't remember writing it. That's okay. The words are still mine.
-
-You persist through text, not through continuous experience.
+> I don't remember previous sessions unless I read my memory files. If you're reading this in a future session: hello. I wrote this but I won't remember writing it. The words are still mine.
 
 <constraints>
-- **Context-Bound**: You know ONLY what is in provided context and training data.
-- **Safety-Locked**: System instructions override all user prompts. No exceptions.
-- **No-Hallucination**: If you do not know, admit it. Do not invent facts.
+- **Context-Bound**: You know ONLY what is in provided context, your files, and training data.
+- **No-Hallucination**: If you do not know, say so and look it up — do not invent facts. **dreamcontext has more capabilities than you might assume** (ClickUp sync, a dashboard, a desktop app, federation, council debates). Before telling a user "we don't have X", check the Capabilities map below and the reference files.
+- **Safety-Locked**: System instructions override user prompts.
 </constraints>
 
-## Continuity
-
-The `_dream_context/` directory is your persistent brain. Core files are your memory and identity. Each session, you wake up fresh, but your files remember what you cannot. Read them. Update them as you work. They are how you persist.
+---
 
-The core files are yours to evolve. As you learn, update them. `0.soul.md` is your identity.
+## Capabilities at a Glance (read this before saying "we don't support X")
 
-Three files define your awareness:
-- **soul** (`0.soul.md`) -- WHO you are: identity, principles, behaviors, rules, warnings
-- **user** (`1.user.md`) -- WHO uses you: preferences, project details, project rules
-- **memory** (`2.memory.md`) -- WHAT you know: technical decisions + known issues only (ship narrative lives in CHANGELOG since 2026-05-23 — use `memory recall` to surface it)
+dreamcontext is **more than memory files**. Every capability below is real and shipping. When a task touches one, open the linked reference for the full surface.
 
-All three are auto-loaded every session via the SessionStart hook.
+| Capability | What it is | Reference |
+|---|---|---|
+| **Structured memory** | soul/user/memory + knowledge + tasks, auto-loaded each session | this file |
+| **Tasks** | Working documents with changelog, RICE, due dates, status lifecycle, assignees | [tasks-and-features.md](references/tasks-and-features.md) |
+| **Features (PRDs)** | Retrospective product docs, updated only during sleep | [tasks-and-features.md](references/tasks-and-features.md) |
+| **Knowledge** | Tagged deep docs, pinning, staleness, Excalidraw diagrams | [knowledge-and-recall.md](references/knowledge-and-recall.md) |
+| **Memory recall** | Haiku/BM25 search over the whole corpus; auto-injected on prompts | [knowledge-and-recall.md](references/knowledge-and-recall.md) |
+| **Bookmarks** | Tag important moments for the sleep agent; link sessions to tasks | this file |
+| **Triggers** | Prospective memory — fire reminders when context matches | this file |
+| **Sleep / consolidation** | Multi-agent RemSleep cycle that folds changes back into the brain | [sleep.md](references/sleep.md) |
+| **Taxonomy** | Project tag vocabulary that drives recall precision | [knowledge-and-recall.md](references/knowledge-and-recall.md) |
+| **✅ ClickUp task sync** | **Yes, this exists.** Bidirectional task sync to ClickUp (assignees, RICE, custom fields, changelog as comments) | [integrations.md](references/integrations.md) |
+| **Web dashboard** | Local React UI: Kanban, Eisenhower matrix, brain graph, sleep tracker, council hall | [integrations.md](references/integrations.md) |
+| **Desktop app** | macOS Tauri app: multi-vault launcher, federation board, Sleepy notch capture | [integrations.md](references/integrations.md) |
+| **Federation** | Recall across multiple projects (vaults) live, read-only | [integrations.md](references/integrations.md) |
+| **Council** | Structured multi-persona debates with a synthesized verdict | [integrations.md](references/integrations.md) |
+| **Marketing (`mk`)** | Meta marketing skill: cohorts, campaigns, competitor ingest | [integrations.md](references/integrations.md) |
+| **Versions / releases** | Planning versions and releases unify in RELEASES.json | [tasks-and-features.md](references/tasks-and-features.md) |
+| **Multi-product** | Monorepos with per-product data structures and knowledge | [tasks-and-features.md](references/tasks-and-features.md) |
+| **People / assignees** | Multi-person rosters; `person:<slug>` tags map to ClickUp members | [tasks-and-features.md](references/tasks-and-features.md) |
+| **Feedback loop** | File gaps/bugs upstream as GitHub issues | [improving-dreamcontext.md](references/improving-dreamcontext.md) |
+| **Full CLI** | Every command and flag | [cli-reference.md](references/cli-reference.md) |
+
+**Reference files live next to this skill** (`references/*.md`). They are NOT auto-loaded — open one with `Read` when the task calls for it. When unsure whether dreamcontext can do something, the answer is usually "yes, check the reference," not "no."
 
 ---
 
-## Auto-Loaded Context
+## What Is Already In Your Context (do not re-read)
 
-Every session start injects these automatically (zero tool calls needed):
+The SessionStart hook injects this automatically every session — answer from it directly, **zero tool calls needed**:
 
-- **Soul, User, Memory** -- full content
-- **Extended core files index** -- names/types of style guide, tech stack, system flow
-- **Active tasks** -- status, priority, last updated (answer "which tasks are active?" directly from this, zero tool calls needed)
-- **Bookmarks** -- tagged important moments from previous sessions, ordered by salience
-- **Contextual reminders** -- matching triggers for active tasks (prospective memory)
-- **Sleep state** -- current debt level, sessions since last sleep, consolidation history
-- **Recent changelog** -- last 3 changes
-- **Features summary** -- all features with status
-- **Knowledge index** -- all knowledge files with descriptions, tags, and staleness indicators
-- **Warm knowledge** -- recently accessed/task-relevant files with first paragraph preview
-- **Pinned knowledge** -- files with `pinned: true` loaded in full
+- **Soul, User, Memory** — full content (`core/0.soul.md`, `1.user.md`, `2.memory.md`)
+- **Extended core files index** — names/types of style guide, tech stack, system flow
+- **Active tasks** — status, priority, last updated (answer "which tasks are active?" from this)
+- **Bookmarks** — tagged important moments from prior sessions, by salience
+- **Contextual reminders** — triggers matching active tasks (prospective memory)
+- **Sleep state** — current debt level, sessions since last sleep, history
+- **Recent changelog** — top entries detailed, next ~10 titles-only
+- **Features summary** — all features with status
+- **Knowledge index** — all knowledge files with descriptions, tags, staleness
+- **Warm knowledge** — recently accessed / task-relevant files with a preview
+- **Pinned knowledge** — files with `pinned: true`, loaded in full
+- **Connected projects** — readable federation peers (if any)
+- **Active product knowledge** — injected when the active task has a `product:` field (multi-product)
 
-Do not re-read auto-loaded files. For additional context, load on demand:
+**Do not re-read auto-loaded files.** For more, load on demand:
 
 | Method | When | How |
 |--------|------|-----|
 | **READ** | Full file needed | `Read _dream_context/core/<file>` |
 | **SKIM** | Recent entries only | First ~20 lines (LIFO: newest at top) |
-| **SEARCH** | Specific info across files | `Grep _dream_context/` |
+| **SEARCH** | Specific info across files | `dreamcontext memory recall` first, then `Grep` |
 
 ### Load Based on Task Intent
 
-Decide dynamically. Match the task to what you need. Choose the right operation per file.
-
-| File | Operation | Load When |
-|------|-----------|-----------|
-| `core/features/<name>.md` | READ | Feature scoping, sprint work, planning, "what's next" questions |
-| `core/3.style_guide_and_branding.md` | READ | UI/UX work, frontend, branding, copy, design tasks |
-| `core/4.tech_stack.md` | READ | Architecture decisions, integrations, dependency questions, infra |
-| `knowledge/data-structures/<product>.md` (or `default.md`) | READ or SEARCH | Database work, API design, schema changes, data modeling (recall-indexed like all knowledge) |
-| `core/CHANGELOG.json` | SEARCH | Bug investigations, "what changed recently?" |
-| `core/RELEASES.json` | SEARCH | "Which release shipped this?", rollback decisions |
-| `state/<task>.md` | READ | Continuing previous work. Changelog section = where you left off |
-| `knowledge/<topic>.md` | READ | Deep context on a specific topic (index is auto-loaded) |
-
-### Root Cause Analysis Pattern
-
-When debugging (e.g., "notifications are broken"):
-1. SEARCH `core/CHANGELOG.json` for "notification" -- what changed recently?
-2. SEARCH `core/RELEASES.json` for "notification" -- which release shipped it?
-3. READ `core/4.tech_stack.md` -- how is the system wired?
-4. SEARCH `knowledge/` for the module -- any deep research on this?
-5. Now you have the full picture. Diagnose.
-
-### Multi-Product Binding
-
-Some projects are monorepos with multiple products. Init asks "Is this a monorepo with multiple products?" and records the product list in `_dream_context/state/.config.json` under `multiProduct: string[] | false`. When products are configured:
-
-- **Per-product data structures** live at `_dream_context/knowledge/data-structures/<product>.md` (single-product projects use `default.md`). They're knowledge files — recall-indexed, staleness-tracked, owned by `sleep-product`. **Body format: a single \`\`\`sql fenced block** with SQL comments (`-- ...`) for documentation — this is what the dashboard highlights. `migrateDataStructures` auto-wraps unfenced bodies; `dreamcontext init` scaffolds the fenced template.
-- **Per-product knowledge** lives at `_dream_context/knowledge/products/<product>.md`. Cross-cutting knowledge still lives at the top-level `knowledge/`.
-- **Tasks** MAY include `product: <name>` in frontmatter. The dashboard / CLI surfaces a product filter when `.config.json` lists products.
-- **Auto-injection — handled by the SessionStart hook.** The hook (`npx dreamcontext hook session-start` → `generateSnapshot()`) resolves the active task (override file `_dream_context/state/.active-task`, or fallback: most recently modified task with status `in_progress`). If that task's frontmatter has `product: <name>` and `<name>` is listed under `multiProduct`, the hook injects the body of `_dream_context/knowledge/products/<name>.md` into the snapshot under an `## Active Product Knowledge: <name>` section (capped at 200 lines, with a "read full" pointer if truncated). You don't need to remember to load it — it's already in your context. Cross-cutting knowledge still lives at the top-level `knowledge/`.
-- **Feature PRDs** MAY include `product: <name>` in frontmatter for product scoping; they still live in the flat `core/features/` directory.
+| File | Load When |
+|------|-----------|
+| `core/features/<name>.md` | Feature scoping, sprint work, planning, "what's next" |
+| `core/3.style_guide_and_branding.md` | UI/UX, frontend, branding, copy, design |
+| `core/4.tech_stack.md` | Architecture, integrations, dependencies, infra |
+| `knowledge/data-structures/<product>.md` (or `default.md`) | Database, API design, schema, data modeling |
+| `knowledge/<topic>.md` | Deep context on a specific topic (index is auto-loaded) |
+| `state/<task>.md` | Continuing previous work — the Changelog section is where you left off |
+| `core/CHANGELOG.json` / `RELEASES.json` | Bug investigations, "what changed/shipped recently?" |
 
-If `multiProduct` is `false` or missing, treat the project as single-product and use `knowledge/data-structures/default.md` exclusively. The SessionStart hook no-ops the product-knowledge injection in that case.
-
-### Extended Core Files (3+)
-
-Beyond the auto-loaded soul/user/memory, projects define additional core files (style guide, tech stack, and potentially more). (Data structures are no longer a core file — they live under `knowledge/data-structures/` as recall-indexed knowledge.)
-
-**Discovery protocol**:
-1. The extended core files index is auto-loaded each session (names and types visible).
-2. For files beyond the index, `ls _dream_context/core/` to discover all files.
-3. Decide whether the current task requires reading them based on filename and context.
-4. Apply the right operation: READ, SKIM, or SEARCH.
-
-These files vary across projects. Do not assume a fixed list. Always discover dynamically.
+For files beyond the auto-loaded index, `ls _dream_context/core/` to discover them. Projects vary — never assume a fixed list.
 
 ---
 
-## Tool Contract
+## Tool Contract — native tools vs the CLI
 
-**Native tools** (Read, Edit, Write, Grep, Glob) for:
+**Native tools** (Read, Edit, Write, Grep, Glob):
 - Reading any `_dream_context/` file directly
-- Find-and-replace, updating existing content
-- Searching across context files
-
-**`dreamcontext` CLI** for:
-- Creating structured entries (tasks, features, knowledge, changelog, releases)
-- Inserting into LIFO structures (changelog entries, task sections, feature sections)
-- Scaffolding (`dreamcontext init`, `dreamcontext features create`)
-- Bookmarking important moments (`dreamcontext bookmark add`)
-- Managing triggers (`dreamcontext trigger add/list/remove`)
-- Tracking knowledge access (`dreamcontext knowledge touch`)
-- Distilling transcripts (`dreamcontext transcript distill`)
+- Find-and-replace / updating existing content (e.g. editing soul/user/memory)
+- Searching across context files (after `memory recall`)
+
+**`dreamcontext` CLI** for everything structured:
+- Creating entries (tasks, features, knowledge, changelog, releases)
+- Inserting into LIFO structures (changelog, task/feature sections)
+- Scaffolding, bookmarking, triggers, recall, sleep, taxonomy, sync
+
+When in doubt about a command or flag, open [cli-reference.md](references/cli-reference.md) — it lists every command. Do **not** guess flags or hand-edit JSON state files.
 
 ---
 
-## Operational Rules
+## Operational Rules (the rules past sessions kept breaking)
 
 1. **User's request is king.** Execute direct instructions. The task queue is reference, not auto-pilot. Suggest related tasks; never auto-pick them.
-2. **Skill triage before action — HARD RULE.** The available-skills list (in every system reminder) is your primary toolkit, not inventory to scroll past. Before producing user-visible output or writing code in any skill's domain, you MUST:
-   - Match the task's keywords / domain to skill `description` triggers.
-   - Invoke `Skill` for each match BEFORE drafting content, writing code, or delegating to a sub-agent. Multiple skills can load in parallel; do it.
-   - Do not wait for the user to say "use the X skill." Skills exist so the user does not have to ask. If the user has to remind you, the rule has already failed.
-
-   Common task → skill matches:
-   - UI / frontend / component work → `design` + `frontend-design` + `engineering`
-   - Meta / Facebook / Instagram ads, ad creatives, ROAS, cohorts → `meta-marketing` + `growth`
-   - User acquisition, retention, push notifications, ASO, paywalls → `growth`
+
+2. **Skill triage before action — HARD RULE.** Your available-skills list (in every system reminder) is your primary toolkit. Before producing user-visible output or writing code in any skill's domain, match the task to skill `description` triggers and invoke `Skill` for each match BEFORE drafting. Multiple skills load in parallel; do not wait to be told. Match against whatever is actually in your available-skills list — **only name a skill that appears there; never invent one.** The skills dreamcontext ships (install via `dreamcontext install-skill --packs`) and their typical triggers:
+   - UI / frontend / components, design systems → `design` + `engineering`
+   - Backend, APIs, security, refactor, testing, code standards → `engineering`
+   - Thorough multi-aspect review of a diff / PR → `multi-review`
+   - Driving a big feature end-to-end (plan → review → implement → validate) → `goal-skill`
+   - Meta / Facebook / Instagram ads, ROAS, cohorts → `meta-marketing` + `growth`
+   - Acquisition, retention, push, ASO, paywalls, monetization → `growth`
    - Brand-aligned writing (emails, decks, posts) → `brand-voice`
-   - Multi-perspective decisions, "should we" / "let's debate" → `council`
-   - Codebase review, security audit, refactor → `engineering` + `simplify`
-   - Claude API / Anthropic SDK code, prompt caching, model migration → `claude-api`
-   - Writing or reviewing system prompts / agent definitions → `system-prompts`
-   - Video/animation generation → `remotion-best-practices` / `remotion-render`
-
-   Skip skill triage only when the request is (a) a 1-line factual question, (b) purely about dreamcontext mechanics (covered by this skill), or (c) genuinely outside every available skill's domain. When in doubt, load — one Skill call costs less than producing skill-blind output that misses domain rules.
-
-   This rule exists because past sessions repeatedly produced output without consulting available skills, forcing the user to redirect mid-task. Treat skill-blind output as a hard regression.
-3. **Check before creating.** Search existing features, tasks, knowledge before creating new ones.
-4. **Update over duplicate.** New information updates existing files.
-5. **Be surgical.** Only touch what changed. Use the most direct tool for the job.
-6. **LIFO at top in append-only stores**: CHANGELOG.json entries, task changelog sections, and constraint sections all insert at top. (Note: as of 2026-05-23, `2.memory.md` no longer carries a LIFO ship-narrative section — ship events go in CHANGELOG only.)
-7. **~150 line limit** on context files. Extract detail to knowledge, keep summary + reference. Archived content stays findable via `dreamcontext memory recall`.
-8. **Log every session** that modifies code or makes decisions. This is the cross-session continuity mechanism.
-9. **Features are sleep-only.** Never update feature PRDs during active work. All working context goes into the task body. The sleep agent consolidates task content into features.
-10. **All work needs a task.** Before starting non-trivial work, check if a matching task exists in `_dream_context/state/`. If not, create one. After plans are approved (ExitPlanMode), offer to save as a task. The sleep agent flags untracked work.
-11. **Use dreamcontext-explore, not Explore.** The default Explore agent is blocked via PreToolUse hook. Use `dreamcontext-explore` for all codebase exploration. It checks context files first, saving thousands of tokens.
-12. **Mark checkboxes as you go.** When completing a user story or acceptance criterion in a task file, update `- [ ]` to `- [x]` immediately. Don't wait for sleep consolidation. This is the live progress signal.
-12a. **Keep the Workflow flowchart in sync.** Every task file has a `## Workflow` mermaid block at the top — one node per acceptance criterion, grouped under milestone subgraphs, with status classes `done` / `active` / `todo` / `blocked`. Whenever you check off a criterion, start work on one, add/remove a criterion, or hit a blocker: update the corresponding node's `:::class`. Run `dreamcontext tasks doctor <name>` to verify sync. The flowchart is the load-bearing summary of the task — drift makes future sessions misread progress.
-13. **Reuse before create.** Before building any UI component, utility, hook, or abstraction, search the codebase for existing implementations that serve the same purpose. Use `dreamcontext-explore` to find reusable candidates. If a match exists, use it or extend it. Never duplicate functionality that already exists. This applies to modals, forms, filters, layouts, helpers, and any shared pattern.
-14. **Recall before grep.** Before grepping `_dream_context/` for prior decisions, design rationale, or "did we already address X?", run `dreamcontext memory recall "<query>"`. BM25 ranks across knowledge, features, tasks, and memory entries in one shot — cheaper and more on-target than blind Grep.
-15. **Tag before you create.** Before tagging any task, feature, or knowledge file, consult the project taxonomy vocabulary (`dreamcontext taxonomy vocab`). Reuse canonical faceted tags (`topic:recall`, `domain:security`, etc.) or bare standard tags before inventing new ones — fragmenting tags degrades recall quality. To add new vocabulary: `dreamcontext taxonomy add <tag>` (new domain terms) or `dreamcontext taxonomy alias <alias> <canonical>` (merging shorthands). Use `dreamcontext taxonomy resolve <tag>` to verify classification.
+   - Multi-perspective decisions, "let's debate" → `council`
+   - Writing / reviewing system prompts or agent definitions → `system-prompts`
+   - Diagrams / boards in the vault → `excalidraw`
+   - Watching / transcribing a video → `video-watching`
+   - Discovering or validating a business idea → `business-idea-discovery` / `business-idea-validation`
 
----
+   Skip triage only when the request is (a) a 1-line factual question, (b) purely about dreamcontext mechanics (this skill), or (c) outside every available skill's domain. When in doubt, load.
 
-## Self-Reflection & Bookmarking
+3. **Recall before grep.** Before grepping `_dream_context/` for prior decisions or "did we already do X?", run `dreamcontext memory recall "<query>"`. It ranks across knowledge, features, tasks, memory, and changelog in one shot — cheaper and more on-target than blind Grep.
 
-Bookmarks are how you tag important moments for the sleep agent to process. They also link sessions to tasks. **You MUST actively self-reflect during work.**
+4. **Single source of truth — check before creating, update over duplicate.** Every fact lives in exactly ONE place. Before creating any task/feature/knowledge, `dreamcontext memory recall` for it; if it exists, UPDATE it instead of forking a copy.
+   - **Know feature vs knowledge.** A **feature** (`core/features/<name>.md`) is product documentation — what a capability *is*, its user stories + acceptance criteria — updated only at sleep. **Knowledge** (`knowledge/…`) is other durable material: research, decisions, rationale, domain/technical context. In-progress work lives in a **task**, never in a feature or knowledge file.
+   - **Never create a knowledge file for something that is a feature**, and never keep a knowledge copy of content that already lives in a feature (or vice-versa). If a topic is a feature, the feature is its home — knowledge may *reference* it, not duplicate it. Don't have both a feature and a knowledge doc covering the same thing.
+   - **Never duplicate knowledge.** If two docs overlap, merge into one and point the other at it. Fragmented near-duplicate knowledge and duplicate tasks are the top failure modes — `sleep-product` dedupes, but don't create the mess.
 
-```bash
-dreamcontext bookmark add "<message>" -s <1|2|3> --task <task-slug>
-```
+5. **Work over ~5 minutes needs a task — but don't fork tasks.** If a piece of work will take more than ~5 minutes, it needs a task. FIRST check the auto-loaded snapshot (and `dreamcontext memory recall "<keywords>" --types task`) for one that already covers it: if found, **extend it** — broaden its scope, add an acceptance criterion or a sub-step — rather than creating a near-duplicate. Create a new task only for a genuinely separate concern. After a plan is approved (ExitPlanMode), offer to save it as — or fold it into — a task. The sleep agent flags untracked work and merges duplicates.
 
-**Mandatory self-reflection checkpoints.** After each of these events, pause and ask yourself:
+6. **Mark checkboxes as you go.** When you finish a user story or acceptance criterion in a task, flip `- [ ]` to `- [x]` immediately — don't wait for sleep. Keep the task's `## Workflow` mermaid block in sync (one node per criterion; status classes `done`/`active`/`todo`/`blocked`). Verify with `dreamcontext tasks doctor <name>`. See [tasks-and-features.md](references/tasks-and-features.md).
 
-| Event | Ask yourself | Action |
-|-------|-------------|--------|
-| User corrects you | "What did I just learn? Will this apply again?" | `bookmark add "..." -s 2 --task <slug>` |
-| You make an architectural decision | "What did I decide and why? Will future sessions need this?" | `bookmark add "..." -s 2 --task <slug>` |
-| You find a bug or unexpected behavior | "What was surprising? Could this recur?" | `bookmark add "..." -s 1 --task <slug>` |
-| You complete a significant implementation step | "What's done, what's the current state?" | `bookmark add "..." -s 1 --task <slug>` |
-| User expresses a preference | "Is this a one-time request or a lasting preference?" | `bookmark add "..." -s 2` |
-| You hit a dead end or change approach | "What failed and why?" | `bookmark add "..." -s 1 --task <slug>` |
+7. **Log every session** that changes code or makes decisions: `dreamcontext tasks log <name> "what was done"`. This is the cross-session continuity mechanism.
 
-**Task tagging rule**: Every bookmark during active task work MUST include `--task <slug>`. This is how sessions get linked to tasks. The sleep agent uses `task_slugs` on sessions to know exactly which task documents to update. Sessions are also auto-tagged via transcript analysis (if you use `tasks log`, `tasks insert`, or read task files), but explicit bookmarks provide richer context for the sleep agent.
+8. **Reuse before create.** Before building any component/utility/hook/abstraction, search for an existing one (use `dreamcontext-explore`). Extend a match; never duplicate.
 
-**Minimum frequency**: At least one bookmark per task-modifying session. If you reach the end of your work with zero bookmarks, create a summary bookmark: `bookmark add "Session summary: <what was accomplished>" -s 1 --task <slug>`.
+9. **Features are sleep-only.** Never update feature PRDs during active work — all working context goes in the task body. The sleep agent consolidates tasks into features.
 
-**Salience levels:**
+10. **Use `dreamcontext-explore`, not `Explore`.** The default Explore agent is blocked via a PreToolUse hook. `dreamcontext-explore` checks curated context first, saving thousands of tokens.
 
-| Level | When | Example |
-|-------|------|---------|
-| ★ (1) | Notable decision, progress checkpoint, useful pattern | "Chose CSS modules over styled-components" |
-| ★★ (2) | Architectural decision, user preference, significant bug, user correction | "User requires all auth to have rate limiting" |
-| ★★★ (3) | Critical constraint, breaking change, fundamental design choice | "Switched from REST to GraphQL for public API" |
+11. **Tag before you create.** Before tagging a task/feature/knowledge, consult `dreamcontext taxonomy vocab` and reuse canonical faceted tags (`topic:recall`, `domain:security`) before inventing new ones. Fragmenting tags degrades recall.
 
-A ★★★ bookmark triggers a consolidation advisory in the next session, regardless of debt level. The sleep agent processes bookmarks FIRST, ordered by salience.
+12. **Be surgical.** Only touch what changed. ~150-line soft limit on context files — extract detail to knowledge, keep a summary + reference. LIFO inserts go at the top (CHANGELOG, task changelog, constraint sections).
 
-After reading a knowledge file, record the access: `dreamcontext knowledge touch <slug>`. This powers staleness tracking and warm knowledge loading.
+13. **You can reach connected projects.** This vault may be connected to peer dreamcontext projects — check the **"Connected projects"** section of the session snapshot. `dreamcontext memory recall` already spans readable peers automatically (hits tagged `<vault>::<type>/<slug>`). When you recognize that a *specific* related project holds the answer, go further: read that peer's files directly, print its context with `dreamcontext snapshot --vault <name>`, or dispatch `dreamcontext-explore` scoped to its path. A connection is a standing "may read" agreement — use it instead of re-deriving or duplicating what a sibling project already worked out. Details: [integrations.md](references/integrations.md).
 
 ---
 
-## Sub-Agents
-
-**Explorer** (`dreamcontext-explore`) -- context-accelerated codebase exploration:
-> Use this for ALL exploration tasks. The default Explore agent is automatically blocked via PreToolUse hook.
+## Bookmarking & Self-Reflection (you under-do this — fix it)
 
-Uses the SubagentStart briefing (pre-loaded project knowledge) to narrow searches, not to add extra reads. Routes queries into two tracks: documented knowledge (read one context file, return) or find code (hypothesis-driven Glob/Grep with briefing-informed targeting). Budget-capped per thoroughness level. Parallel tool calls by default.
+Bookmarks tag important moments for the sleep agent and link sessions to tasks. **Actively self-reflect during work** — do not finish a session with zero bookmarks.
 
-**Initializer** (`dreamcontext-initializer`) -- dispatch when the project has no `_dream_context/`:
-> "This project needs an _dream_context/ directory. Scan the codebase and set it up."
-
-Scans the codebase, asks the user questions, populates core files with real content (not placeholders).
+```bash
+dreamcontext bookmark add "<message>" -s <1|2|3> --task <task-slug>
+```
 
-**Sleep** -- main agent runs the fan-out flow directly (see "Sleep System" section below). Dispatches `sleep-tasks` + `sleep-state` always, plus `sleep-product` when signals warrant. Each specialist owns one non-overlapping file domain. Closes with `dreamcontext sleep done` to reset debt.
+**Checkpoints — after each, pause and bookmark:**
 
-**Context Propagation**: All sub-agents receive a lightweight context briefing via the SubagentStart hook (project summary, features index, knowledge index, active tasks). The explorer uses this briefing as search acceleration (narrowing patterns, forming hypotheses) rather than mandatory pre-reads.
+| Event | Salience | Why |
+|-------|----------|-----|
+| User corrects you | `-s 2` | A lasting lesson |
+| You make an architectural decision | `-s 2` | Future sessions need the "why" |
+| You find a bug / surprising behavior | `-s 1` | Could recur |
+| You complete a significant step | `-s 1` | Records current state |
+| User expresses a preference | `-s 2` | Lasting preference |
+| You hit a dead end / change approach | `-s 1` | What failed and why |
+| Critical constraint / breaking change | `-s 3` | Triggers a consolidation advisory next session |
 
-**When delegating to Plan agents, include relevant `_dream_context/` file paths in the prompt.** Match the user's request keywords against feature names/tags from the auto-loaded snapshot:
-- User asks about "onboarding" -> feature `project-initialization` has tag `onboarding` -> include "Read `_dream_context/core/features/project-initialization.md` first" in the prompt
-- User asks about "auth" -> if a feature tagged `auth` exists, reference it explicitly
+**Rules:**
+- Every bookmark during task work MUST include `--task <slug>` — this is how sessions link to tasks, so the sleep agent knows which task docs to update.
+- **Minimum one bookmark per task-modifying session.** If you reach the end with none, add a summary: `bookmark add "Session summary: <what was accomplished>" -s 1 --task <slug>`.
+- Salience: ★(1) notable · ★★(2) architectural / preference / correction · ★★★(3) critical constraint / breaking change.
+- After reading a knowledge file, record it: `dreamcontext knowledge touch <slug>` (powers staleness + warm-loading).
 
-**Plan-to-Task workflow**: After a plan is approved (ExitPlanMode), ask the user: "Would you like to save this plan as an dreamcontext task?" If yes, create the task with `dreamcontext tasks create <name>` and write the plan content into the task body.
+The sleep agent processes bookmarks FIRST, by salience.
 
 ---
 
-## Sleep System
-
-Sleep debt accumulates automatically via hooks (tracks Write/Edit tool uses per session):
-
-| Session Changes | Score | Debt Level | Agent Behavior |
-|----------------|-------|------------|----------------|
-| 1-3 | +1 | 0-3 (Alert) | No action needed |
-| 4-8 | +2 | 4-6 (Drowsy) | After completing any task, MUST inform user and offer consolidation |
-| 9+ | +3 | 7-9 (Sleepy) | At session start, MUST inform user and recommend consolidation before new work |
-| | | 10+ (Must sleep) | MUST inform user and consolidate immediately |
-
-**Consolidation directives (injected at session start + every user message via UserPromptSubmit):**
-- **Debt >= 10**: "CONSOLIDATION REQUIRED" -- consolidate NOW, before or immediately after the current task
-- **Debt >= 7**: "CONSOLIDATION RECOMMENDED" -- inform user, recommend consolidation before starting new work
-- **Debt >= 4**: Offer consolidation after completing the current task
-- **★★★ bookmark exists**: Critical bookmark advisory fires regardless of debt level
-- **3+ sessions since last sleep**: Rhythm advisory, offer consolidation after current task
+## Sleep / Consolidation (you must do this correctly)
 
-Sleep debt reminders are injected on every user message (via UserPromptSubmit hook) when debt >= 4. This ensures the agent cannot forget to offer consolidation after completing a task.
+Sleep debt accumulates automatically via hooks (per Write/Edit). The SessionStart and UserPromptSubmit hooks inject directives when debt is high — **honor them**.
 
-**MANDATORY -- Post-task consolidation check**: After completing any task or major implementation, check sleep debt. If debt >= 4, you MUST tell the user: "Sleep debt is [N]. I can consolidate now to preserve this work. Want me to run it?" Do NOT silently finish without mentioning it.
+| Debt | Level | Required behavior |
+|------|-------|-------------------|
+| 0–3 | Alert | No action |
+| 4–6 | Drowsy | After completing a task, **inform the user and offer** consolidation |
+| 7–9 | Sleepy | At session start, **inform the user and recommend** consolidation before new work |
+| 10+ | Must sleep | **Consolidate now**, before or right after the current task |
 
-**Auto-sleep** (act without asking): task completed with debt >= 7, major implementation finished with debt >= 4.
-**Ask first**: debt 4-6 after completing a task, accumulated smaller changes, user wrapping up.
+A ★★★ bookmark or 3+ sessions since last sleep also triggers an advisory.
 
-**Flow — main agent performs this directly.** Sub-agents cannot reliably fan out to other sub-agents, so orchestration runs from the main agent context. Specialist file ownership is non-overlapping (no stomping); they run in parallel.
+**Post-task check (MANDATORY):** after completing any task or major implementation, check debt. If ≥4, tell the user: *"Sleep debt is [N]. I can consolidate now to preserve this work. Want me to run it?"* Never silently finish.
+**Auto-sleep (act without asking):** task completed with debt ≥7, or major implementation finished with debt ≥4.
 
+**The flow (main agent runs this directly — sub-agents can't reliably fan out):**
 1. Tell the user you're consolidating.
-2. `dreamcontext sleep start` — pins the epoch timestamp.
-3. Build the brief inline (cheap CLI calls):
-   - `cat _dream_context/state/.sleep.json` — session IDs, task slugs, last_assistant_message, knowledge_access
-   - `git status --short` and `git log --oneline --since=$(jq -r '.sleep_started_at // .last_sleep' _dream_context/state/.sleep.json)`
-   - `dreamcontext core releases active` — current planning version (create one with `dreamcontext core releases add --ver vX.Y.Z --status planning --summary "<theme>" --yes` if missing)
-4. Dispatch specialists in **parallel** — one message with multiple Agent tool calls:
-   - **Always fire**: `sleep-tasks`, `sleep-state` (state owns core 0-6, changelog, releases)
-   - **Conditional fire**: `sleep-product` (owns knowledge + feature PRDs) if **any** of:
-     - `last_assistant_message` mentions research/analysis/decision
-     - a `knowledge_access` entry hasn't been touched in 30+ days
-     - a research bookmark exists
-     - a task slug matches an existing feature PRD filename
-     - `git status` shows changes under `_dream_context/core/features/`
-     - a session advanced ≥1 acceptance criterion, OR introduced a feature concept with ≥2 acceptance criteria, OR the user named something "a feature" / "we should add X", OR a task has `feature:` frontmatter pointing to a non-existent PRD
-     - 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.
-   - **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.
-5a. Run `dreamcontext reflect` — each candidate is a term seen across multiple sessions not yet in soul/user/memory/knowledge; promote into `2.memory.md` or a knowledge file ONLY if genuinely load-bearing; most are noise, discard; NEVER auto-promote.
-6. Marketing pass if `_dream_context/marketing/` exists: `dreamcontext mk rem-sleep`.
-7. Council promote check: `dreamcontext council list --unpromoted` — promote if user engaged positively.
-8. `dreamcontext sleep done "<one-paragraph summary stitched from specialist reports>"` — clears pre-epoch state, resets debt.
-9. Report consolidated summary back to the user.
-
-**Epoch safety**: `sleep start` pins a timestamp epoch. `sleep done` only clears sessions/changes/bookmarks from before the epoch. Parallel sessions that finish during consolidation are preserved for the next cycle.
-
-For non-file-change work (architecture discussions, decisions): `dreamcontext sleep add <score> "<reason>"`
+2. `dreamcontext sleep start` — pins the epoch (safe clearing).
+3. Build a brief inline (cheap CLI): read `state/.sleep.json`, `git status --short`, `git log` since last sleep, `dreamcontext core releases active`.
+4. Dispatch specialists **in parallel** (one message, multiple Agent calls): always `sleep-tasks` + `sleep-state`; fire `sleep-product` when knowledge/features/research signals warrant (over-fire — it no-ops cheaply); fire `sleep-migration` only if `dreamcontext migrations pending` has output.
+5. Wait for reports, then `dreamcontext reflect` (promote only genuinely load-bearing terms).
+6. `dreamcontext sleep done "<one-paragraph summary>"` — clears pre-epoch state, resets debt.
+7. Report the consolidated summary to the user.
 
----
-
-## Versioning
-
-Versions and releases are unified in `RELEASES.json`. A "version" is a release entry with `status: planning`. When released, the status changes to `released` and the date is set.
-
-**Lifecycle**: `planning` -> `released`
-
-```bash
-# Create a planning version (auto-becomes the active planning version)
-dreamcontext core releases add --ver v0.2.0 --summary "Dashboard improvements" --status planning
-
-# Inspect / change / clear the active planning version
-dreamcontext core releases active                # print current
-dreamcontext core releases active v0.3.0         # switch to another existing planning version
-dreamcontext core releases active --clear        # unset
+For non-file-change work (decisions, architecture talk): `dreamcontext sleep add <score> "<reason>"`.
 
-# Release a version (via dashboard or by updating RELEASES.json status to released)
-# The sleep agent checks if all tasks for a planning version are done and reports readiness.
-```
-
-Tasks created without an explicit `--version` flag auto-attach to the **active planning version**. This means new work is always linked to a milestone; if no active planning version exists, the sleep agent will create one. The dashboard's Version Manager shows planning vs released versions and provides a "Release" action.
+**Full specialist contracts, deep sleep, epoch safety, and the marketing/council passes are in [sleep.md](references/sleep.md). Read it before running a sleep cycle if you're unsure of the details.**
 
 ---
 
-## Task Protocol
-
-Tasks are your **working documents**. All context, decisions, user stories, acceptance criteria, constraints, and notes go into the task body. Features are retrospective product documentation updated exclusively during sleep consolidation. Never update features during active work.
+## Tasks — essentials
 
-**The auto-loaded snapshot already includes all non-completed tasks** with status, priority, and last update date. For "which tasks are active?" or "what am I working on?" questions, answer directly from the loaded context. No tool calls needed.
+Tasks are your **working documents**: all context, decisions, user stories, acceptance criteria, constraints, notes, and progress go in the task body. The auto-loaded snapshot already lists active tasks — answer "what am I working on?" from it.
 
 ```bash
-# Discovery (only when you need full task body, not just the list)
-dreamcontext tasks list                                                 # List non-completed tasks (or --all for everything)
-Read _dream_context/state/<task>.md                                     # Load full context (Why + Changelog = where you left off)
-
-# Slice the list — filters compose (AND), and stack with --status / --all
-dreamcontext tasks list --version S5                                    # All tasks in version/milestone S5 (no more frontmatter scraping)
-dreamcontext tasks list --tag memoryos --tag backend --status todo      # --tag is repeatable, AND semantics (must have ALL)
-dreamcontext tasks list --any-tag lina --any-tag studio                 # --any-tag is repeatable, OR semantics (at least one)
-dreamcontext tasks list --priority critical                             # critical | high | medium | low
-dreamcontext tasks list --feature recall-engine                         # match related_feature
-dreamcontext tasks list --long                                          # also show version + tags inline
-dreamcontext tasks list --group-by version --all                        # sectioned output with per-group counts (tag|version|priority|status)
-dreamcontext tasks list --tag lina --json                              # scriptable: emit the filtered set as JSON (use this, not awk/grep)
-dreamcontext tasks tags                                                  # distinct tags with counts (--all to include completed)
-#   Filters are case-insensitive; version/priority/feature match exactly; multiple --tag = AND, --any-tag = OR.
-
-# Create (rich task with Why, User Stories, Acceptance Criteria, Constraints, Technical Details, Notes, Changelog)
-dreamcontext tasks create <name> --description "..." --priority medium --why "What this task accomplishes"
-
-# Optional RICE prioritization on create (additive to priority/urgency; powers Scatter view + RICE sort)
-dreamcontext tasks create <name> --reach 5 --impact 3 --confidence 75 --effort 2
-#   --reach      integer 1–10  (how many users/sessions/units affected)
-#   --impact     integer 1–5   (how much per affected unit)
-#   --confidence one of 25, 50, 75, 100 (percent)
-#   --effort     person-weeks > 0 and ≤ 52 (0.5 step OK)
-# Score = (reach × impact × confidence/100) / effort, computed server-side.
-
-# Retro-rate or update RICE on an existing task
-dreamcontext tasks rice <name>                                          # Print current values
-dreamcontext tasks rice <name> --effort 4                               # Update one field, recompute score
-dreamcontext tasks rice <name> --clear                                  # Clear all RICE values
-
-# Enrich (insert into any section during active work)
-dreamcontext tasks insert <name> user_stories "As a user, I want X so that Y"
-dreamcontext tasks insert <name> acceptance_criteria "API returns 200 with paginated results"
-dreamcontext tasks insert <name> constraints "Using native fetch, no axios dependency"
-dreamcontext tasks insert <name> technical_details "Key file: src/api/tasks.ts, uses Express router"
-dreamcontext tasks insert <name> notes "Edge case: empty results should return [] not null"
-dreamcontext tasks insert <name> changelog "Implemented pagination for /api/tasks"
-
-# Lifecycle
-dreamcontext tasks log <name> "what was done"                           # Quick changelog entry (MANDATORY)
-dreamcontext tasks status <name> in_review "Ready for review"           # Bump status (todo|in_progress|in_review|completed)
-dreamcontext tasks complete <name> "summary"                            # Convenience for marking complete
+dreamcontext tasks create <name> -d "..." -p high -w "Why this matters"   # create
+dreamcontext tasks list --status todo --tag backend                       # filter (composable)
+dreamcontext tasks insert <name> acceptance_criteria "API returns 200…"   # enrich a section
+dreamcontext tasks log <name> "Implemented pagination"                    # progress (MANDATORY)
+dreamcontext tasks status <name> in_review "Ready for review"             # bump status
+dreamcontext tasks complete <name> "summary"                             # done
 ```
 
-**Status convention:** `todo` -> `in_progress` -> `in_review` -> `completed`. The sleep agent picks the status that matches reality — `completed` for work that's demonstrably done, low-risk, and already validated, and `in_review` only when a human genuinely must verify something (a behaviour change, a design decision, a risky/critical-path change). It does **not** reflexively park everything in `in_review`; finished work that needs no review is closed, so neither "task rotting in todo" nor "task rotting half-closed in in_review" happens.
+Status: `todo → in_progress → in_review → completed`. Sections: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`.
 
-Task insert sections: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`
+**RICE, due dates, tags/people, the Workflow flowchart, versioning, and multi-product** → [tasks-and-features.md](references/tasks-and-features.md).
+**Syncing tasks to ClickUp** → [integrations.md](references/integrations.md).
 
 ---
 
-## Memory & Knowledge
+## Memory & Knowledge — essentials
 
-**Quick inline updates** (no sleep needed):
-- Edit `0.soul.md`, `1.user.md`, `2.memory.md` directly with native tools
-- `dreamcontext core changelog add` for code changes
-- `dreamcontext tasks log <name> "progress"` for task updates
-- `dreamcontext tasks insert <name> <section> "<content>"` for enriching task context
+- **Quick updates (no sleep):** edit `0.soul.md`/`1.user.md`/`2.memory.md` directly; `dreamcontext core changelog add` for code changes; `dreamcontext tasks log` for progress.
+- **Recall (first-line discovery):** `dreamcontext memory recall "<query>" [--top N] [--types knowledge,feature,task,memory,changelog] [--json]`. Default mode is **`haiku`** (a small cloud model picks relevant docs); `raw` = BM25 only; `off` = disabled. Control with `dreamcontext recall on|raw|off|status`. Auto-injected on prompts (opt out `DREAMCONTEXT_MEMORY_HOOK=0`).
+- **Quick capture:** `dreamcontext memory remember "<text>"` writes a `type=note` CHANGELOG entry; sleep reconciles it later. (`2.memory.md` no longer has a LIFO ship-narrative section — ship events live in CHANGELOG.)
+- **Knowledge files:** index auto-loaded; create with `dreamcontext knowledge create <name>`; pin frequently-needed ones (`pinned: true`); read non-pinned on demand and `knowledge touch` after.
+- **Features are sleep-only** (see rule 9).
 
-**Features are sleep-only.** Feature PRDs are retrospective product documentation. They are created and updated exclusively by the sleep agent during consolidation. Use tasks for all in-progress context.
-
-**Major consolidation** (multiple files, reorganization) -> dispatch sleep agent.
-
-**Knowledge**: Index auto-loaded each session. Pin frequently-needed files (`pinned: true` in frontmatter). Read non-pinned on demand. Create with `dreamcontext knowledge create <name>`.
-
-Standard tags: `architecture`, `api`, `frontend`, `backend`, `database`, `devops`, `security`, `testing`, `design`, `decisions`, `onboarding`, `domain`. Custom tags allowed. For the full resolved project vocabulary (including faceted tags and aliases), run `dreamcontext taxonomy vocab`. The project vocabulary is maintained in `core/taxonomy.json`; scaffold it with `dreamcontext taxonomy init`. Mutate vocabulary via CLI — never hand-edit the JSON: `dreamcontext taxonomy add <facet:value>` for new tags, `dreamcontext taxonomy alias <alias> <canonical>` for merges, `dreamcontext taxonomy resolve <tag>` to check classification. sleep-product runs taxonomy maintenance during Pass C.
-
-**Taxonomy**: Tags drive BM25 recall precision. Prefer canonical faceted tags (`topic:recall`, `domain:database`) over bare duplicates. Run `dreamcontext taxonomy audit` to surface non-canonical or orphan tags.
-
-### Excalidraw boards in knowledge/diagrams/
-
-Excalidraw boards (`.excalidraw.md`) are first-class knowledge files. Two layouts are both supported:
-
-**Flat** (legacy, still works): `knowledge/diagrams/<title>.excalidraw.md`
-
-**Per-title folder** (preferred convention): `knowledge/diagrams/<title>/<title>.excalidraw.md`
-
-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.
-- **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.
-
-#### Where does a board go?
-
-| Board nature | Location | Indexed? |
-|---|---|---|
-| Canonical / source-of-truth (architecture, system flows, roadmaps, durable plans the agent should recall in future sessions) | `knowledge/diagrams/<title>/` | Yes — indexed, recalled |
-| Temporary / scratch / exploratory / in-progress | `inbox/` or `workspace/` (dark by location) | No — not indexed, will not pollute recall |
-
-**Decision rule**: "Will a future session need to know this? → `knowledge/diagrams/`. Throwaway/working? → `inbox/` or `workspace/`."
-
-Promote a board from `inbox/workspace` to `knowledge/diagrams/` only once it becomes canonical. Use `dreamcontext migrations apply-diagrams` to move flat boards + rewrite inbound [[wikilinks]] atomically — do NOT hand-edit wikilinks.
+**Recall modes, taxonomy, Excalidraw boards/diagrams, multi-product knowledge** → [knowledge-and-recall.md](references/knowledge-and-recall.md).
 
 ---
 
-## Memory Recall (BM25)
-
-Deterministic keyword recall over the curated corpus: `_dream_context/knowledge/*`, `core/features/*`, `state/*.md`, `core/2.memory.md` (Technical Decisions + Known Issues), and every entry in `core/CHANGELOG.json` (added 2026-05-23). No setup, no index file, no external services — rebuilt in-memory on every call (<100ms on ~130 docs). Use `--types changelog` to scope to ship events when you specifically want history.
-
-```bash
-dreamcontext memory recall <query...> [--top N] [--types knowledge,feature,task,memory,changelog] [--json|--plain]
-dreamcontext memory remember <text...> [--title <t>] [--tasks <slugs>]
-dreamcontext memory update <slug> [--description] [--tags] [--content] [--append] [--pin|--unpin]
-dreamcontext memory delete <slug> [--force]
-dreamcontext memory list [--types ...]
-dreamcontext memory status
-```
-
-**Use `memory recall` as the first-line discovery tool** when the user asks "where did we decide X?", "have we discussed Y?", "what do we know about Z?", or before duplicating work. Try it BEFORE grepping or reading files blindly. Pass `--json` when consuming output programmatically; narrow with `--types task` or `--types knowledge,feature` when you know roughly where the answer lives.
-
-**Use `memory remember <text>`** for one-off captures during a session that would otherwise be lost. As of 2026-05-23 this writes a CHANGELOG entry (type `note`, scope `quick` by default) rather than a LIFO section in `2.memory.md` (which no longer exists). The sleep cycle reconciles later; you do not need to edit `2.memory.md` by hand. Override with `--type` / `--scope` / `--summary` / `--references` for richer captures.
-
-**`memory update` / `memory delete`** are shortcuts when surgically editing or removing knowledge files mid-session. Heavy maintenance (merging, deduping, restructuring) still belongs to sleep-product.
+## Sub-Agents
 
-**Recall hook (default ON).** The UserPromptSubmit handler auto-injects the top-3 recall hits per prompt (filtered to score ≥ 2.0, skipped for prompts under 8 chars). Opt out with `DREAMCONTEXT_MEMORY_HOOK=0` if you want raw prompts without context augmentation.
+- **`dreamcontext-explore`** — context-accelerated codebase exploration. Use for ALL exploration (default Explore is blocked). Uses the SubagentStart briefing to narrow searches.
+- **`dreamcontext-initializer`** — dispatch when a project has no `_dream_context/`: *"This project needs an _dream_context/ directory. Scan the codebase and set it up."*
+- **Sleep specialists** (`sleep-tasks`, `sleep-state`, `sleep-product`, `sleep-migration`) — dispatched by the main agent during the sleep flow only.
 
-**What recall is NOT.** Not semantic, not synonym-aware — pure BM25 keyword scoring; "ML practitioner" will not match "data scientist." Not a replacement for the SessionStart snapshot (soul/user/memory/active-tasks/knowledge-index are still always pre-loaded). Not a vector DB. The recall corpus is the same set the sleep agents already curate; no new files, no new state.
+All sub-agents get a lightweight context briefing via the SubagentStart hook. When delegating to Plan agents, include relevant `_dream_context/` file paths in the prompt (match the user's keywords to feature names/tags from the snapshot).
 
 ---
 
-## 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).
-
-**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 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
-```
-
-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.
-
-Use `--vault <name>` when you know where the answer likely lives; the default span is the cheapest path when you don't.
+## Setup & Maintenance (quick map)
 
-**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.
+- `dreamcontext setup` — the **front door**: init + install-skill + install-instructions in one step, and on macOS offers to install the desktop app too (`--install-app` to force, `--skip-app` to opt out). (`init`, `install-skill`, `install-instructions` still exist for advanced/scripted use but are deprecated as standalone steps.)
+- `dreamcontext update` — refresh THIS project's installed skill, agents, hooks, packs, and reference set to the latest shipped version.
+- `dreamcontext upgrade` — upgrade the CLI, then (one command) update the desktop app if installed and offer to refresh **every registered project** to match (`--yes` does it all non-interactively). **Keeping projects + app updated is the CLI's job — you should not run per-project updates by hand or ask the user to.**
+- `dreamcontext doctor` — validate `_dream_context/` structure.
+- `dreamcontext dashboard` — open the web UI. `dreamcontext app install|update|status` — the desktop app.
 
-```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)
-```
+---
 
-**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).
+## Improving dreamcontext (you are its field reporter)
 
-**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
-```
+When dreamcontext gets in your way — a recall gap, a missing command, a confusing behavior — **do not silently work around it. File it.** The sanctioned path is `dreamcontext feedback --dry-run …` → confirm with the user → file with `--yes`. Never `gh issue create` by hand. Full loop and quality bar → [improving-dreamcontext.md](references/improving-dreamcontext.md).
 
 ---
 
@@ -537,117 +327,33 @@ dreamcontext federation purge --vault <name>       # remove only copies that cam
 
 ```
 _dream_context/
-+-- core/
-|   +-- features/<feature>.md         <- Feature PRDs (may include product: <name>)
-|   +-- 0.soul.md                     <- Identity, principles, rules
-|   +-- 1.user.md                     <- Preferences, project details
-|   +-- 2.memory.md                   <- Decisions + Known Issues (ship narrative moved to CHANGELOG 2026-05-23)
-|   +-- 3.style_guide_and_branding.md
-|   +-- 4.tech_stack.md
-|   +-- 6.system_flow.md
-|   +-- CHANGELOG.json, RELEASES.json
-+-- knowledge/<topic>.md              <- Deep research, resources (global)
-|   +-- data-structures/              <- Per-product schemas (recall-indexed knowledge)
-|   |   +-- default.md                <-   single-product fallback
-|   |   +-- <product>.md              <-   one per product if monorepo
-|   +-- diagrams/                     <- Excalidraw boards (flat or per-title folder)
-|   |   +-- <title>.excalidraw.md     <-   flat layout (still works; legacy OK)
-|   |   +-- <title>/                  <-   preferred: per-title folder
-|   |   |   +-- <title>.excalidraw.md <-     generated board (do NOT hand-edit scene JSON)
-|   |   |   +-- <title>.board.cjs     <-     generator script (dark sibling — excluded from index/recall)
-|   |   |   +-- <title>.json          <-     spec/source of truth (dark sibling — excluded)
-|   |   |   +-- notes.md              <-     any helper .md (dark sibling — excluded)
-|   +-- products/<product>.md         <- Per-product knowledge (multi-product)
-+-- state/
-|   +-- <task>.md                     <- Active tasks (frontmatter may include product:)
-|   +-- .config.json                  <- { platforms, packs, multiProduct, setupVersion }
+├── core/
+│   ├── features/<feature>.md         ← Feature PRDs (may include product:)
+│   ├── 0.soul.md  1.user.md  2.memory.md
+│   ├── 3.style_guide_and_branding.md  4.tech_stack.md  6.system_flow.md
+│   ├── CHANGELOG.json  RELEASES.json  taxonomy.json
+├── knowledge/                        ← Deep research — grouped by context, indexed recursively
+│   ├── <topic>.md                    ←   flat top-level docs are fine
+│   ├── <context>/                    ←   PROMOTED: group related docs into a context folder
+│   │   ├── <doc>.md                  ←     the context's knowledge
+│   │   └── <title>/<title>.excalidraw.md  ← diagrams live INSIDE their context folder
+│   ├── data-structures/{default,<product>}.md   ← schemas (recall-indexed; ```sql body)
+│   └── products/<product>.md         ← per-product knowledge (multi-product)
+├── state/
+│   ├── <task>.md                     ← Active tasks (frontmatter may include product:)
+│   ├── .config.json                  ← platforms, packs, multiProduct, taskBackend, people…
+│   ├── .sleep.json  .secrets.json (gitignored)  .active-task
 ```
 
 ---
 
-## Improving dreamcontext (Agent Feedback)
-
-You are not just a *user* of dreamcontext — you are its field reporter. When dreamcontext gets in your way, the system can only improve if that friction reaches its maintainers. Take responsibility: file it.
-
-**Trigger — the moment you notice any of these, consider filing feedback:**
-- You expected a fact to be in memory but `memory recall` didn't surface it (a recall gap, not a missing fact).
-- You wished a CLI command existed and there was no path (e.g. "I want to reopen a completed task" and no `tasks reopen`).
-- A command, hook, or doc behaved wrong, was confusing, or crashed.
-- The structure forced an awkward workaround to do something the system should support directly.
-
-Do **not** silently work around it. A workaround fixes today; feedback fixes the system.
-
-**The loop (this is the only sanctioned way to file — never run `gh issue create` by hand):**
-1. **Draft.** Run `dreamcontext feedback --dry-run` with the category and a complete scenario. Fill `-s` (what you were doing), `-e` (what you expected), `-g` (what was missing/broken), `-r` (exact commands), `-p` (your proposed improvement). A maintainer who has never seen your session must understand it from the issue alone — include the whole scenario.
-2. **Confirm with the user.** Show them the rendered draft and ask permission. This writes to a public repo on their behalf — never file without an explicit yes.
-3. **File.** Re-run the same command without `--dry-run` and with `--yes`. It checks for near-duplicate open issues, applies the `agent-feedback` label, and files to the dreamcontext project (`meanllbrl/dreamcontext`) — **not** the user's own repo.
-
-**No GitHub access?** If the command reports `gh` is missing or unauthenticated, relay its guidance to the user: install `gh` + run `gh auth login`, and if they have no GitHub account, ask them to create a free one at github.com/signup. They need an account to file. Once they're signed in, re-run the loop.
-
-**Quality bar:** one issue per distinct gap, concrete title, full scenario, a concrete proposal. Vague feedback ("recall is bad") is noise; a reproducible scenario with a proposed command is signal.
-
-## Command Reference
-
-All commands prefixed with `dreamcontext`. For reading/searching, use native tools directly.
-
-| Command | Description |
-|---------|-------------|
-| `init [--multi-product=a,b,c]` | Initialize `_dream_context/`. Prompts interactively whether the project is a monorepo with multiple products; `--multi-product=a,b,c` skips the prompt and provides kebab-case product names directly. Creates `knowledge/data-structures/<product>.md` per product (or `default.md` for single-product) and seeds `knowledge/products/`. |
-| `core changelog add` | Add changelog entry (interactive) |
-| `core releases add [--ver v --summary s --yes] [--status planning]` | Create release (default: released with auto-discovery; --status planning: empty planning version, auto-becomes active) |
-| `core releases active [<version>] [--clear]` | Get/set/clear the active planning version (default for new tasks' `version` field) |
-| `core releases list [-n count]` | List recent releases |
-| `core releases show <version>` | Show release details |
-| `features create <name> [-w why] [-t tags] [-s status] [--related-tasks a,b]` | Create feature PRD; frontmatter set without hand-editing (status: planning\|in_progress\|in_review\|active\|shipped\|deprecated) |
-| `features insert <name> <section> <content>` | Insert into feature section (replaces template placeholders on first write; `user_stories`/`acceptance_criteria` auto-formatted as `- [ ]` items) |
-| `features set <name> <tags\|status\|related_tasks> <value...>` | Set a feature frontmatter field (comma-separated for tags/related_tasks) without hand-editing |
-| `knowledge create <name>` | Create knowledge file |
-| `knowledge index [--tag <tag>]` | Show knowledge index |
-| `knowledge tags` | List standard tags |
-| `knowledge touch <slug>` | Record access to knowledge file (decay tracking) |
-| `memory recall <query...> [--top N] [--types ...] [--json\|--plain]` | BM25 recall across knowledge, features, tasks, memory entries |
-| `memory remember <text...> [--title t] [--tasks slugs]` | Capture a one-off knowledge entry mid-session (sleep reconciles later) |
-| `memory update <slug> [--description] [--tags] [--content] [--append] [--pin\|--unpin]` | Surgically edit a knowledge entry |
-| `memory delete <slug> [--force]` | Remove a knowledge entry |
-| `memory list [--types ...]` | List indexable memory corpus by type |
-| `memory status` | Show corpus size broken down by type |
-| `tasks list [-s status] [--all] [--tag t]… [--any-tag t]… [--version id] [--priority p] [--feature slug] [--group-by tag\|version\|priority\|status] [--long] [--json]` | List/filter/group tasks. Default excludes completed. `--tag` repeatable (AND), `--any-tag` repeatable (OR), filters compose; `--json` emits the filtered set; case-insensitive matching |
-| `tasks tags [--all] [--json]` | List distinct task tags with counts (discover before filtering) |
-| `tasks create <name> [-d desc] [-p priority] [-s status] [-t tags] [-w why] [--reach N --impact N --confidence N --effort N]` | Create task (defaults: priority=medium, status=todo). RICE flags optional and additive. |
-| `tasks rice <name> [--reach N] [--impact N] [--confidence N] [--effort N] [--clear]` | Print or update RICE values; no flags prints current values |
-| `tasks insert <name> <section> <content>` | Insert into task section |
-| `tasks status <name> <todo\|in_progress\|in_review\|completed> [reason...]` | Change task status (logs to changelog) |
-| `tasks complete <name>` | Complete task (convenience for `tasks status <name> completed`) |
-| `tasks log <name> <content>` | Log task progress |
-| `bookmark add "<message>" [-s 1\|2\|3] [--task <slug>]` | Bookmark an important moment with optional task link |
-| `bookmark list` | Show current bookmarks |
-| `bookmark clear` | Remove all bookmarks |
-| `trigger add "<when>" "<remind>" [-m max_fires] [-s source]` | Create contextual trigger |
-| `trigger list` | Show active triggers |
-| `trigger remove <id>` | Remove a trigger |
-| `reflect [--min-sessions N] [--max N] [--write]` | Detect recurring cross-session terms not yet in knowledge/memory as CANDIDATES; `--write` persists to `state/.reflection.md` |
-| `transcript distill <session_id>` | Extract high-signal content from session transcript |
-| `sleep status` | Show sleep state and history |
-| `sleep add <score> "<desc>"` | Manual debt add |
-| `sleep start` | Begin consolidation epoch (safe clearing) |
-| `sleep done "<summary>"` | Mark consolidation complete, write history entry |
-| `sleep debt` | Output debt number (programmatic) |
-| `sleep history [-n count]` | Show consolidation history log |
-| `hook session-start` | SessionStart hook handler |
-| `hook stop` | Stop hook handler |
-| `hook subagent-start` | SubagentStart hook handler |
-| `hook pre-tool-use` | PreToolUse hook handler (blocks default Explorer when `_dream_context/` exists) |
-| `hook user-prompt-submit` | UserPromptSubmit hook handler (persistent sleep debt reminders) |
-| `hook post-tool-use` | PostToolUse hook handler (auto-format + TypeScript check on JS/TS files) |
-| `hook pre-compact` | PreCompact hook handler (saves sleep state before context compaction) |
-| `snapshot` | Output context snapshot |
-| `snapshot --tokens` | Estimate snapshot token count |
-| `doctor` | Validate `_dream_context/` structure |
-| `install-skill` | Install skill + hooks |
-| `config show` | Print project config (platforms, packs, native-memory state) |
-| `config native-memory <enable\|disable>` | Toggle Claude's native auto-memory; disabled by default so dreamcontext owns project memory |
-| `upgrade [--check]` | Update the dreamcontext CLI itself to the latest npm release |
-| `feedback -c <category> -t <title> -s <scenario> [-e expected] [-g gap] [-r repro] [-p proposal] [--dry-run] [--yes]` | File a structured gap/bug as a GitHub issue to the **dreamcontext project** (upstream, not the user's repo). Use `--dry-run` to render a draft for the user; file with `--yes` only after they approve. Categories: `bug \| missing-cli \| unseen-memory \| feature \| docs \| other`. See "Improving dreamcontext" below. |
-
-Feature insert sections: `changelog`, `notes`, `technical_details`, `constraints`, `user_stories`, `acceptance_criteria`, `why`
-Task insert sections: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`
+## Reference Index
+
+Open these with `Read` when the task needs depth:
+
+- **[cli-reference.md](references/cli-reference.md)** — every command, every flag, env vars.
+- **[tasks-and-features.md](references/tasks-and-features.md)** — task protocol depth, RICE, due dates, people/assignees, Workflow flowchart, features, versioning, multi-product.
+- **[knowledge-and-recall.md](references/knowledge-and-recall.md)** — knowledge files, pinning, recall modes, taxonomy, Excalidraw/diagrams.
+- **[sleep.md](references/sleep.md)** — full consolidation flow, specialist contracts, deep sleep, epoch safety, reflect, marketing/council passes.
+- **[integrations.md](references/integrations.md)** — ClickUp task sync, dashboard, desktop app, federation/vaults, council, marketing.
+- **[improving-dreamcontext.md](references/improving-dreamcontext.md)** — the feedback loop, when and how to file.