dreamcontext 0.5.4 → 0.7.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
 
@@ -151,12 +193,13 @@ your-project/
 │   │   ├── 2.memory.md                  # Decisions & known issues
 │   │   ├── 3.style_guide_and_branding.md
 │   │   ├── 4.tech_stack.md              # Tech decisions
-│   │   ├── 5.data_structures.sql
 │   │   ├── 6.system_flow.md             # Session lifecycle, data flows
 │   │   ├── CHANGELOG.json
 │   │   ├── RELEASES.json
 │   │   └── features/                    # Feature PRDs
 │   ├── knowledge/                       # Tagged docs (index in snapshot)
+│   │   ├── data-structures/             # Schema files (SQL-fenced, highlighted)
+│   │   │   └── default.md              # single-product; one per product if monorepo
 │   │   └── *.md                         # pinned: true → auto-loaded in full
 │   └── state/                           # Active tasks + working state
 │       ├── *.md                         # Active task files
@@ -169,8 +212,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 +274,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 +307,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 +398,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 +540,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 +605,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 +614,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/sleep-product.md

@@ -54,8 +54,9 @@ If none apply when you start, no-op cheaply: read the brief, scan for actual sig
 | You touch | You don't touch |
 |---|---|
 | `_dream_context/knowledge/*.md` (create + edit) | core 0-6 files (sleep-state owns) |
-| `_dream_context/core/features/*.md` (create + edit) | task files (sleep-tasks owns) |
-| `dreamcontext knowledge create --tags "..."` | changelog, releases (sleep-state owns) |
+| `_dream_context/knowledge/data-structures/<product>.md` (schemas, models, API contracts) | task files (sleep-tasks owns) |
+| `_dream_context/core/features/*.md` (create + edit) | changelog, releases (sleep-state owns) |
+| `dreamcontext knowledge create --tags "..."` | |
 | `dreamcontext features create <name>` | |
 | `dreamcontext features insert <name> <section>` | |
 | Frontmatter: `pinned`, `status`, `updated`, `released_version`, `related_tasks` | |
@@ -167,7 +168,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 +176,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>" \
@@ -230,6 +251,22 @@ Product-scoped knowledge. Cross-cutting findings still go to top-level `knowledg
 
 This is a one-time bootstrap per product; once the file exists, treat it like any other knowledge file (edit on demand, don't recreate).
 
+#### B6. Data structures (schemas / models / API contracts)
+
+Data structures live at `knowledge/data-structures/<product>.md` (`default.md` for single-product). They moved here from `core/` because schemas ARE domain knowledge — this gives them recall indexing, staleness flags, and the knowledge UI for free. **You own these writes now** (sleep-state only flags them for you).
+
+**Single-observation gate.** Unlike most knowledge (which waits for repetition), a schema/data-model change is reflected in the *same* cycle — no pattern repetition required. If `sleep-state` flagged a schema/table/model change, or the diff shows one, write it now.
+
+**Routing.**
+- Active task has `product: X` → `knowledge/data-structures/X.md` (create if missing).
+- Otherwise (single-product) → `knowledge/data-structures/default.md`.
+- Frontmatter: `type: data-structures`, `product: <name>`, `tags: [data-structures, database, schema]` (add domain tags as relevant).
+
+**Migration of the old locations** (idempotent; the dir move runs automatically on `dreamcontext sleep start`, but confirm + handle the legacy file):
+- If `core/data-structures/*.md` still exists and the knowledge copy is absent, it was (or should be) moved to `knowledge/data-structures/` — the `sleep start` migration handles this. Verify it landed.
+- If the even-older `core/5.data_structures.sql` exists and `knowledge/data-structures/default.md` does not, copy it there (add the data-structures frontmatter) — don't delete the legacy file.
+- **Never delete** the old `core/data-structures/` dir or the legacy `.sql` yourself — leave them for the user to remove after confirming (the `doctor` command nags about both). Note any migration in your report.
+
 ## Return — single combined report
 
 ```
@@ -247,8 +284,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 +300,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.