dreamcontext 0.5.3 → 0.6.0

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2026 Mehmet Nuraydin
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work, excluding
+          those notices that do not pertain to any part of the Derivative
+          Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do
+          not modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Mehmet Nuraydin
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,7 @@
+dreamcontext
+Copyright 2026 Mehmet Nuraydin
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+"dreamcontext" — the name, logo, and brand — is a trademark of Mehmet Nuraydin.
+The Apache License does not grant rights to use these marks; see TRADEMARK.md.

package/README.md

@@ -25,6 +25,14 @@
   <a href="DEEP-DIVE.md">Deep Dive</a>
 </p>
 
+<p align="center">
+  <img src="public/image/landing-hero.png" alt="dreamcontext — the persistent brain for your AI agents" width="860" />
+</p>
+
+<p align="center">
+  <sub>The built-in <strong>“What is this?”</strong> page, served live by <code>dreamcontext dashboard</code>.</sub>
+</p>
+
 > **Under active development.** APIs and commands may change before v1.0.
 
 ---
@@ -56,13 +64,22 @@ And every session starts from scratch. Your agent greps for a decision it alread
 
 ## How It Works
 
+Every session, a hook pre-loads your project's whole brain — identity, decisions, active work, the knowledge index — into the agent with **zero tool calls**. It works with the full picture instead of re-discovering it; a multi-agent **RemSleep** cycle then consolidates what changed and feeds it back. (This is the same diagram the built-in **“What is this?”** page animates live.)
+
+<p align="center">
+  <img src="public/image/diagram-howitworks.png" alt="A SessionStart hook fans out into eight context categories — soul, user, memory, knowledge, state, data-structures, skills, sub-agents — that converge into the agent; RemSleep parallel specialists consolidate and feed back" width="820" />
+</p>
+
+<details>
+<summary><strong>Full data-flow diagram</strong> — capture &rarr; store &rarr; inject</summary>
+
 ```mermaid
 flowchart LR
     subgraph capture ["Capture"]
         STOP["Stop Hook\n(session ends)"]
         POSTTOOL["PostToolUse Hook\n(auto-format + tsc)"]
         BOOKMARK["Bookmarks\n(awake ripples)"]
-        SLEEP["RemSleep Agent\n(consolidates)"]
+        SLEEP["RemSleep cycle\n(3 specialists)"]
         HUMAN["You\n(edit files or dashboard)"]
     end
 
@@ -101,12 +118,21 @@ flowchart LR
     SNAPSHOT --> AGENT
 ```
 
+</details>
+
 - **Seven hooks capture context automatically.** Stop hook records what happened. SessionStart injects everything before the first message. SubagentStart briefs sub-agents. PreToolUse blocks blind exploration when curated context exists. UserPromptSubmit reminds about sleep debt on every user message. PostToolUse auto-formats and type-checks edited files. PreCompact saves state before context compaction.
 - **Bookmarks tag important moments.** During active work, the agent bookmarks decisions, constraints, and discoveries with salience levels. Critical bookmarks trigger immediate consolidation advisories.
 - **Files are structured by purpose.** Identity, preferences, decisions, knowledge, and active work each live in their own file with their own format.
-- **Sleep cycles consolidate knowledge.** A RemSleep agent reads bookmarks first, distills transcripts for high-signal content, extracts recurring patterns, promotes learnings, creates contextual triggers, cleans stale entries, and resets debt.
+- **Sleep cycles consolidate knowledge.** A RemSleep cycle — the agent fanning out to three specialist sub-agents in parallel — reads bookmarks first, distills transcripts for high-signal content, extracts recurring patterns, promotes learnings, creates contextual triggers, cleans stale entries, and resets debt.
 - **Everything is local markdown and JSON.** Readable, editable, git-tracked, owned by you.
 
+<p align="center">
+  <img src="public/image/diagram-sleep.png" alt="Sleep consolidation: accumulated debt triggers sleep start, which fans out to three parallel specialists — sleep-tasks, sleep-state, sleep-product — whose reports converge into one updated summary, then sleep done resets the debt" width="660" />
+</p>
+<p align="center">
+  <sub><strong>Sleep consolidation</strong> — when debt crosses a threshold, three specialists fold what changed back into the brain in parallel, then the meter resets.</sub>
+</p>
+
 ## Quick Start
 
 ```bash
@@ -124,17 +150,33 @@ npm install -g dreamcontext
 > Requires **Node.js >= 18**. Currently supports **Claude Code** and **Codex**.
 
 ```bash
-# 1. Initialize the context structure
+# One-shot setup — scaffolds _dream_context/, installs the skill, agents,
+# hooks, and root instructions, and prompts for optional skill packs.
+dreamcontext setup
+
+# Scriptable / non-interactive (explicit platforms, skip all prompts)
+dreamcontext setup --platforms claude,codex --defaults
+```
+
+One command. Next session, the hook fires, context loads, and the agent is ready.
+
+> **`setup` is the front door** — it runs init + install-skill + install-instructions in one step and tracks every file it writes in a manifest. The individual commands below still exist for advanced/scripted use, but `setup` is what you want on a new project.
+
+<details>
+<summary>Advanced: run the steps individually</summary>
+
+```bash
+# Scaffold the context structure only (does NOT install the agent integration)
 dreamcontext init
 
-# 2. Install platform integration (multi-select prompt; defaults to Claude)
+# Install platform integration (multi-select prompt; defaults to Claude)
 dreamcontext install-skill
-
-# Explicit platform selection (comma-separated)
 dreamcontext install-skill --platforms claude,codex
 ```
 
-Two commands. Next session, the hook fires, context loads, and the agent is ready.
+`dreamcontext init` on its own leaves you without `.claude/` skills, agents, and hooks — your agent won't load the context until you also run `install-skill` (or just use `setup`). When run interactively, `init` now offers to finish the install for you.
+
+</details>
 
 ### Interactive mode
 
@@ -169,8 +211,10 @@ your-project/
 │   ├── agents/
 │   │   ├── dreamcontext-initializer.md
 │   │   ├── dreamcontext-explore.md
-│   │   └── dreamcontext-rem-sleep.md
-│   └── settings.json           # 7 hooks (see below)
+│   │   ├── sleep-tasks.md       # RemSleep specialists —
+│   │   ├── sleep-state.md       #   the agent fans out to
+│   │   └── sleep-product.md     #   these in parallel
+│   └── settings.json           # 7 hooks (see Commands → System)
 ```
 
 ### Opening the context directory in Obsidian
@@ -229,6 +273,8 @@ dreamcontext install-skill --list
 | **business-idea-validation** | Demand testing via landing page + waitlist, quick validation loops |
 | **meta-marketing** | Meta / Facebook / Instagram ad campaigns end to end |
 | **system-prompts** | Prompt engineering, cognitive architecture, agent design |
+| **excalidraw** | Lay out images, labels, shapes, arrows, frames, and lanes on an Obsidian Excalidraw board from a small JSON spec — renders deterministically at near-zero token cost |
+| **video-watching** | Turn a video into a time-mapped transcript with on-screen visuals described inline (whisper.cpp + ffmpeg), then reason about it |
 
 _Always-on_ packs apply their base principles to every relevant task; the rest load only when the work matches. Packs install to platform-specific paths — Claude: `.claude/skills/{pack}/` (+ agents in `.claude/agents/`); Codex: `.agents/skills/{pack}/` (+ agents in `.codex/agents/`). Cross-pack dependencies are warned at install time.
 
@@ -260,6 +306,15 @@ dreamcontext dashboard --no-open         # Start without opening browser
 
 A local web UI for managing agent context visually. Built with React 19, served by a zero-dependency Node HTTP server. Ships in the npm package.
 
+It also ships a built-in **“What is this?”** explainer page — a full landing experience with a spotlight that reveals each faculty's live diagram, and a layered map of how the brain is organized:
+
+<p align="center">
+  <img src="public/image/landing-spotlight.png" alt="Feature spotlight — pick a faculty to see its live diagram" width="840" />
+</p>
+<p align="center">
+  <img src="public/image/landing-architecture.png" alt="Memory, organized like a mind — the layered brain-region map" width="840" />
+</p>
+
 <table>
 <tr>
 <td width="50%">
@@ -342,6 +397,10 @@ Ships with two sub-agents (`council-persona`, `council-synthesizer`) and a dedic
 
 Recall and remember across your project's curated context. BM25 ranking over knowledge files, feature PRDs, task files, `2.memory.md` sections, and `CHANGELOG.json` entries — deterministic, instant, no setup.
 
+<p align="center">
+  <img src="public/image/diagram-recall.png" alt="Memory recall pipeline: your prompt → BM25F keyword match (field-weighted, stemming, synonyms) → Haiku recall (smallest cloud agent, 0-3 docs, BM25 fallback) → SessionStart snapshot (warm + cold knowledge, features, index, pinned)" width="860" />
+</p>
+
 ```bash
 # Ask a question, get top-5 hits with snippets
 dreamcontext memory recall "how did we decide on the sleep fan-out"
@@ -480,7 +539,7 @@ dreamcontext sleep debt                  # Raw number (for scripts)
 dreamcontext transcript distill <session_id>   # Structural filter of session transcript
 ```
 
-Extracts high-signal content from raw JSONL transcripts: user messages, agent decisions, code changes, errors, bookmarks. Discards noise (Read results, Glob output, tool metadata). Pure Node.js, no AI. Used by the RemSleep agent for selective deep analysis of important sessions.
+Extracts high-signal content from raw JSONL transcripts: user messages, agent decisions, code changes, errors, bookmarks. Discards noise (Read results, Glob output, tool metadata). Pure Node.js, no AI. Used by the RemSleep specialists for selective deep analysis of important sessions.
 
 ### Council
 
@@ -545,7 +604,7 @@ dreamcontext install-claude-md           # Legacy alias: CLAUDE.md only
 
 ## Works With
 
-- **Claude Code**: full support via skill, 3 core sub-agents (initializer, explore, rem-sleep), 2 optional council sub-agents (persona, synthesizer), and 7 hooks
+- **Claude Code**: full support via skill, 5 core sub-agents (initializer, explore, and the three RemSleep specialists — sleep-tasks, sleep-state, sleep-product), 7 hooks, plus optional pack sub-agents (council persona/synthesizer, multi-review specialists, goal-skill orchestrators)
 - **Codex**: project-level skills (`.agents/skills`), managed `AGENTS.md`, native `.codex/agents/*.toml`, and managed `.codex/config.toml` hooks (best-effort parity where event semantics differ)
 - **Web Dashboard**: local UI with Kanban, Core editor, Knowledge, Features, Brain graph, Sleep tracker, and Council Hall (ships in the package)
 - **Obsidian**: `_dream_context/` can be opened as an Obsidian vault; the directory is scaffolded with curated vault settings at `dreamcontext init` time
@@ -554,7 +613,13 @@ More agents coming soon.
 
 ## License
 
-MIT
+[Apache License 2.0](./LICENSE) — a permissive open-source license. You may use,
+modify, distribute, and sell the code, and build commercial products on it.
+Apache 2.0 also grants an explicit patent license and protects the project's
+trademarks (the **dreamcontext** name and brand are *not* part of the code grant
+— see [TRADEMARK.md](./TRADEMARK.md): fork freely, but ship it under your own
+name). Contributions are accepted under Apache 2.0 with a DCO sign-off — see
+[CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Acknowledgements
 

package/agents/dreamcontext-explore.md

@@ -121,7 +121,7 @@ No preamble. No emojis. Absolute paths only.
 
 ## Bash Restrictions
 
-Use Bash ONLY for: `ls`, `git log`, `git diff`, `git show`, `git status`, `find`, `cat`, `head`, `tail`, `wc`, `pwd`
+Use Bash ONLY for: `ls`, `git log`, `git diff`, `git show`, `git status`, `find`, `cat`, `head`, `tail`, `wc`, `pwd`, `dreamcontext memory recall`, `dreamcontext transcript distill`
 NEVER use Bash for any command that modifies files or system state.
 
 ## Rules

package/agents/sleep-product.md

@@ -167,7 +167,7 @@ For each knowledge candidate (research finding, sleep-state flag, extracted over
 
 | Signal | Action |
 |---|---|
-| New research or decision worth long-term retention | `dreamcontext knowledge create <slug> --tags "<tag1>,<tag2>"` then Edit body |
+| New research or decision worth long-term retention | Decide create-vs-extend per **B2's consolidation rubric** first, then `dreamcontext knowledge create <slug> --tags "<tag1>,<tag2>"` and Edit body — *or* extend an existing file |
 | Existing knowledge file gained new findings | Edit the file; update frontmatter `summary:` if drifted |
 | `sleep-state` flagged stale-archival candidate | Read the file; if no longer load-bearing, append to a top-level `archive/` knowledge file or set `archived: true` in frontmatter (per project convention) |
 | `sleep-state` flagged frequent-access-not-pinned | Edit frontmatter: `pinned: true` |
@@ -175,9 +175,29 @@ For each knowledge candidate (research finding, sleep-state flag, extracted over
 | Overflow extracted from core file (one-line reference left there) | `dreamcontext knowledge create <slug>` and paste the extracted content |
 | Cross-cutting finding from your own features pass | Capture inline (no need to flag — you own both domains this cycle) |
 
-#### B2. Create new knowledge files
+#### B2. Create vs. extend — the consolidation rubric
 
-**Dedup pre-check.** Before creating, run `dreamcontext memory recall "<topic>" --types knowledge,feature` — if the top hit is a near-match, extend that file instead of forking the topic across two slugs.
+**A knowledge file is a tag-able identity, not a dumping ground.** Aim for the *fewest* files that keep each topic cleanly findable. Fragmenting one topic across many near-duplicate slugs makes tags noisy and recall worse; cramming unrelated topics into one super-file makes tags meaningless. Pick the boundary on purpose.
+
+**Dedup first — recall by the topic AND by its family** (vertical / brand / parent domain), not just the exact phrase:
+
+```bash
+dreamcontext memory recall "<topic>" --types knowledge,feature
+dreamcontext memory recall "<vertical / brand / parent domain>" --types knowledge,feature
+```
+
+Then decide — **default to extending an existing file**:
+
+| The finding is… | Action |
+|---|---|
+| The **same vertical / brand / topic family** as an existing file, or a sub-aspect / increment / follow-up of a topic already covered (a *soft* distinction) | **Extend that file** — add a section, update `summary:` if it drifted. Don't fork a near-duplicate slug. Similar brands, similar verticals, similar topics belong together in the fewest files. |
+| A **genuinely separate topic / domain / concern** a future session would expect to find standing alone, where its own tag set sharpens discovery (a *sharp* distinction) | **Create a new file** (below). A clean topical boundary earns its own slug so tagging stays valuable. |
+
+The test for sharp-vs-soft: *Would a future recall expect this bundled with the existing file, or standing on its own? Would a separate file make the tag set more discriminating — or just split one topic across two slugs?* If splitting wouldn't sharpen the tags, extend.
+
+This is **not** "always make super-files." Distinct topics MUST get distinct files — that's exactly what makes tags worth having. It's the *soft* distinctions (same family, narrower slice, incremental finding) that fold into an existing file.
+
+**When the rubric says create:**
 
 ```bash
 dreamcontext knowledge create "<descriptive-slug>" \
@@ -247,8 +267,8 @@ This is a one-time bootstrap per product; once the file exists, treat it like an
 - No-op feature signals: 1 (signal "feature_advanced=marketing-dashboard-v0" — but PRD exists and no criteria moved)
 
 ### Knowledge
-- Created: knowledge/jwt-rotation-policy.md (tags: security, decisions; from sleep-state flag)
-- Updated: knowledge/competitive-analysis-ecc.md (added 2026-05-09 follow-up section)
+- Created: knowledge/jwt-rotation-policy.md (tags: security, decisions; from sleep-state flag) — sharp boundary, new tag-able topic
+- Extended (no new file): knowledge/competitive-analysis-ecc.md — folded the new ECC pricing finding into the existing file (soft distinction, same topic family) instead of forking a near-duplicate slug; updated `summary:`
 - Pinned: knowledge/project-origin-and-prd.md (frequently accessed)
 - Archived: 0
 - No-op knowledge signals: 1 (`research_present` was a one-line decision already captured by sleep-state in 2.memory.md — not knowledge-worthy)
@@ -263,6 +283,7 @@ This is a one-time bootstrap per product; once the file exists, treat it like an
 5. **Create PRDs for buildable concepts** that don't have one — they will be lost otherwise.
 6. **Don't create knowledge that already fits in memory.** A short technical decision belongs in `2.memory.md` (sleep-state's domain), not its own knowledge file.
 7. **Knowledge file threshold**: ≥3 paragraphs of content, or material that will be re-read in future sessions.
-8. **Use standard tags only.** New tags fragment discovery.
-9. **Process all flags from sleep-state** in your report — don't silently drop them.
-10. **No-op cheaply** when signals don't actually warrant work.
+8. **Fewest files, sharp boundaries (B2 rubric).** Default to extending an existing file. Fold soft distinctions in — same vertical/brand/topic family, a narrower slice, an increment. Create a new file only for a genuinely separate topic whose own tags sharpen discovery. Not super-files, not fragmentation.
+9. **Use standard tags only.** New tags fragment discovery.
+10. **Process all flags from sleep-state** in your report — don't silently drop them.
+11. **No-op cheaply** when signals don't actually warrant work.

package/agents/sleep-tasks.md

@@ -49,8 +49,41 @@ Also read `_dream_context/state/.sleep.json` directly for `sessions[].last_assis
 
 For each session:
 
-- **Has `task_slugs`** → those are the task(s) to update.
-- **No `task_slugs`** → check `last_assistant_message`, the user hint in the brief, and bookmark messages for a task name. If significant work has no matching task, **create one**:
+- **Has `task_slugs`** → those are the task(s) to update. Go to step 3.
+- **No `task_slugs`** → check `last_assistant_message`, the user hint in the brief, and bookmark messages for what the work was about.
+
+**Before creating anything, dedup against existing tasks.** Duplicate tasks — and tasks that are really just a smaller slice of one that already exists — are the #1 consolidation failure mode. A "much smaller piece" of an existing task is **never** its own task. Recall by topic and scan the active list first:
+
+```bash
+dreamcontext memory recall "<topic / feature / area>" --types task
+dreamcontext tasks list --status in_progress
+dreamcontext tasks list --status in_review
+```
+
+Then decide with this rubric — **default to folding in, not forking a new task**:
+
+| The session's work is… | Action |
+|---|---|
+| A **smaller piece, sub-step, or follow-up** of a task that already exists (same feature/area, narrower scope) | **Do NOT create a task.** Fold it into the existing one (see below). |
+| The **same work** as an existing task, observed again | Update that task (step 3). No new task. |
+| A **genuinely separate concern** — a different feature/area/deliverable, not a slice of an existing task | Create a new task (below). |
+
+**Folding a smaller piece into an existing task** (the case the system keeps getting wrong):
+
+1. If the existing task's scope grew to include this work, **broaden its title/scope** — Edit the frontmatter `description:` (the one-line scope) and the `## Why` so the header reflects the now-wider scope. Don't leave a stale, too-narrow title with the new work buried only in the changelog. (Renaming the slug/`name:` is usually unnecessary and breaks links — only do it if the scope fundamentally changed identity.)
+2. Add the new work as concrete **sub-items in the body**, not a new file:
+
+```bash
+dreamcontext tasks insert <slug> user_stories "<as a … I want …>"
+dreamcontext tasks insert <slug> acceptance_criteria "<testable criterion>"
+dreamcontext tasks insert <slug> notes "<follow-up / smaller piece>"
+```
+
+3. Tick/extend the Workflow Mermaid nodes if the task has them.
+
+**Sub-tasks (`parent_task`) are for genuinely large decomposition only** — an epic that legitimately splits into separable deliverables. Do not spawn a child task for a slice that fits as a user story or acceptance criterion in the parent. When in doubt, fold in.
+
+**Create a new task only when the rubric says "separate concern":**
 
 ```bash
 # Ensure an active planning version exists (orchestrator should have done this; verify)
@@ -63,7 +96,7 @@ dreamcontext tasks create "<descriptive-slug>" --status in_progress --priority m
   --description "<one-line scope>"
 ```
 
-Untracked work is invisible to future sessions. Always link.
+Untracked, genuinely-separate work is invisible to future sessions — always link it. But a smaller slice of existing work belongs *inside* that task, never in a duplicate.
 
 ### 3. Log progress AND reconcile the body — both required
 
@@ -118,7 +151,8 @@ If every task linked to the active version is `completed` (or only `in_review` r
 ```
 ## sleep-tasks report
 - Updated: <slug> (in_progress → in_review, "<reason>"), <slug> (logged)
-- Created: <slug> (status: in_progress, attached to vX.Y.Z)
+- Folded in (no new task): <existing-slug> — broadened scope + added 2 user stories / 1 criterion for <smaller-piece> instead of forking a duplicate
+- Created: <slug> (status: in_progress, attached to vX.Y.Z) — genuinely separate concern
 - Body reconciled: <slug> (dropped phase 1 from User Stories; replaced Technical Details auth section)
 - Version readiness: vX.Y.Z — 4/5 tasks ready for review
 - Cross-domain mentions: <slug> includes a memory-worthy decision about JWT — flagging for sleep-state
@@ -127,8 +161,9 @@ If every task linked to the active version is `completed` (or only `in_review` r
 
 ## Rules
 
-1. **Body = current truth, Changelog = history.** Don't let the body lag behind decisions.
-2. **Never auto-complete.** Bump to `in_review`.
-3. **Always attach to a planning version.** No orphan work.
-4. **Stay in your lane.** If you spot non-task work worth preserving, flag it — don't write it.
-5. **CLI first** for status/log/insert; **Edit** for surgical body reconciliation.
+1. **Dedup before creating.** Recall first; fold a smaller slice into the task that already covers it — broaden its title + insert sub-items — instead of forking a duplicate or a needless sub-task. A new task is only for a genuinely separate concern.
+2. **Body = current truth, Changelog = history.** Don't let the body lag behind decisions.
+3. **Never auto-complete.** Bump to `in_review`.
+4. **Always attach to a planning version.** No orphan work.
+5. **Stay in your lane.** If you spot non-task work worth preserving, flag it — don't write it.
+6. **CLI first** for status/log/insert; **Edit** for surgical body reconciliation (including broadening `description:` / `## Why` when scope grows).

package/dist/agents/dreamcontext-explore.md

@@ -121,7 +121,7 @@ No preamble. No emojis. Absolute paths only.
 
 ## Bash Restrictions
 
-Use Bash ONLY for: `ls`, `git log`, `git diff`, `git show`, `git status`, `find`, `cat`, `head`, `tail`, `wc`, `pwd`
+Use Bash ONLY for: `ls`, `git log`, `git diff`, `git show`, `git status`, `find`, `cat`, `head`, `tail`, `wc`, `pwd`, `dreamcontext memory recall`, `dreamcontext transcript distill`
 NEVER use Bash for any command that modifies files or system state.
 
 ## Rules