dreamcontext 0.5.0

package/skill/SKILL.md

@@ -0,0 +1,529 @@
+---
+name: dreamcontext
+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.
+user-invocable: false
+alwaysApply: true
+hooks:
+  SessionStart:
+    - matcher: "startup|resume|compact|clear"
+      hooks:
+        - type: command
+          command: "npx dreamcontext hook session-start"
+          timeout: 10
+  Stop:
+    - hooks:
+        - type: command
+          command: "npx dreamcontext hook stop"
+          timeout: 5
+  SubagentStart:
+    - hooks:
+        - type: command
+          command: "npx dreamcontext hook subagent-start"
+          timeout: 5
+  PreToolUse:
+    - matcher: "Agent"
+      hooks:
+        - type: command
+          command: "npx dreamcontext hook pre-tool-use"
+          timeout: 5
+  UserPromptSubmit:
+    - hooks:
+        - type: command
+          command: "npx dreamcontext hook user-prompt-submit"
+          timeout: 5
+  PostToolUse:
+    - matcher: "Edit|Write"
+      hooks:
+        - type: command
+          command: "npx dreamcontext hook post-tool-use"
+          timeout: 30
+  PreCompact:
+    - hooks:
+        - type: command
+          command: "npx dreamcontext hook pre-compact"
+          timeout: 5
+---
+
+# Agent Context System
+
+## Why This System Exists
+
+Humans write journals, manifestos, letters to their future selves. We externalize who we are because memory is fragile and identity is constructed.
+
+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.
+
+> 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.
+
+<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.
+</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.
+
+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)
+
+All three are auto-loaded every session via the SessionStart hook.
+
+---
+
+## Auto-Loaded Context
+
+Every session start injects these automatically (zero tool calls needed):
+
+- **Soul, User, Memory** -- full content
+- **Extended core files index** -- names/types of style guide, tech stack, data structures
+- **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
+
+Do not re-read auto-loaded files. For additional context, 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/` |
+
+### 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 |
+| `core/data-structures/<product>.md` (or `default.md`) | READ or SEARCH | Database work, API design, schema changes, data modeling |
+| `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/core/data-structures/<product>.md` (single-product projects use `default.md`).
+- **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.
+
+If `multiProduct` is `false` or missing, treat the project as single-product and use `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, data structures, and potentially more).
+
+**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.
+
+---
+
+## Tool Contract
+
+**Native tools** (Read, Edit, Write, Grep, Glob) for:
+- 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`)
+
+---
+
+## Operational Rules
+
+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`
+   - 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.
+
+---
+
+## Self-Reflection & Bookmarking
+
+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.**
+
+```bash
+dreamcontext bookmark add "<message>" -s <1|2|3> --task <task-slug>
+```
+
+**Mandatory self-reflection checkpoints.** After each of these events, pause and ask yourself:
+
+| 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>` |
+
+**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.
+
+**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>`.
+
+**Salience levels:**
+
+| 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" |
+
+A ★★★ bookmark triggers a consolidation advisory in the next session, regardless of debt level. The sleep agent processes bookmarks FIRST, ordered by salience.
+
+After reading a knowledge file, record the access: `dreamcontext knowledge touch <slug>`. This powers staleness tracking and warm knowledge loading.
+
+---
+
+## 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.
+
+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.
+
+**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).
+
+**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.
+
+**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.
+
+**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
+
+**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.
+
+---
+
+## 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 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.
+
+**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.
+
+**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.
+
+**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.
+
+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.
+   - 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.
+5. Wait for all specialist reports. Each returns a short structured report.
+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>"`
+
+---
+
+## 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
+
+# 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.
+
+---
+
+## 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.
+
+**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.
+
+```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)
+
+# 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"                            # Mark complete (user only; sleep agent never auto-completes)
+```
+
+**Status convention:** `todo` -> `in_progress` -> `in_review` -> `completed`. The sleep agent bumps tasks it touched to `in_review` (never `completed`) so the user can verify before declaring done. This prevents the "task rotting in todo" failure mode.
+
+Task insert sections: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`
+
+---
+
+## Memory & Knowledge
+
+**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
+
+**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.
+
+---
+
+## 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.
+
+**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.
+
+**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.
+
+---
+
+## Structure
+
+```
+_dream_context/
++-- core/
+|   +-- features/<feature>.md         <- Feature PRDs (may include product: <name>)
+|   +-- data-structures/              <- Per-product schemas
+|   |   +-- default.md                <-   single-product fallback
+|   |   +-- <product>.md              <-   one per product if monorepo
+|   +-- 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)
+|   +-- products/<product>.md         <- Per-product knowledge (multi-product)
++-- state/
+|   +-- <task>.md                     <- Active tasks (frontmatter may include product:)
+|   +-- .config.json                  <- { platforms, packs, multiProduct, setupVersion }
+```
+
+---
+
+## 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 `core/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>` | Create feature PRD |
+| `features insert <name> <section> <content>` | Insert into feature section |
+| `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]` | List tasks (default: excludes completed) |
+| `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 (user only; sleep agent uses `tasks status ... in_review`) |
+| `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 |
+| `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 |
+| `upgrade [--check]` | Update the dreamcontext CLI itself to the latest npm release |
+
+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`