dreamcontext 0.12.0 → 0.13.1

package/package.json

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

package/skill/SKILL.md

@@ -3,10 +3,12 @@ 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, ClickUp/GitHub
-  task sync, a web dashboard, cross-project federation, and cross-session continuity
-  via the dreamcontext CLI.
+  insights (Lab analytics metrics), roadmap objectives/OKRs, session continuity, or
+  when the user mentions context management, agent memory, or project state — the words
+  insight, objective, task, feature, knowledge name dreamcontext entities in any language.
+  Provides structured memory, task lifecycle management, analytics insight syncing,
+  ClickUp/GitHub task sync, a web dashboard, cross-project federation, and cross-session
+  continuity via the dreamcontext CLI.
 user-invocable: false
 alwaysApply: true
 hooks:
@@ -77,6 +79,7 @@ dreamcontext is **more than memory files**. Every capability below is real and s
 | **Structured memory** | soul/user/memory + knowledge + tasks, auto-loaded each session | this file |
 | **Tasks** | Working documents with changelog, RICE, status lifecycle, start/due date ranges, resolved assignees, and project-declared custom fields (`overrides/task.md`) | [tasks-and-features.md](references/tasks-and-features.md) |
 | **Roadmap / Objectives** | PO-authored OKR board: objectives in `core/objectives/`, many-to-many task links (`objectives:` frontmatter), dependency DAG with full forecast cascade, target vs forecast slip detection, `dreamcontext roadmap` (+ `--json`) | [tasks-and-features.md](references/tasks-and-features.md) |
+| **Lab / Insights** | Curated analytics **metrics** ("insights") synced from HTTP APIs or local scripts into the brain: manifests in `lab/insights/`, cached series every session, roadmap Key-Result binding (`lab bind` / the dashboard's objective dialogs — one feeder per objective, seeds `metric.current` on connect), dashboard Lab page. **An insight is NOT a knowledge file** — create with `dreamcontext lab create`, never `knowledge create` | [tasks-and-features.md](references/tasks-and-features.md) |
 | **Features (PRDs)** | Retrospective product docs, updated only during sleep | [tasks-and-features.md](references/tasks-and-features.md) |
 | **Knowledge** | Tagged deep docs, pinning, staleness, Excalidraw diagrams | [knowledge-and-recall.md](references/knowledge-and-recall.md) |
 | **Memory recall** | Haiku/BM25 search over the whole corpus; auto-injected on prompts | [knowledge-and-recall.md](references/knowledge-and-recall.md) |
@@ -101,6 +104,38 @@ dreamcontext is **more than memory files**. Every capability below is real and s
 
 ---
 
+## Entity Router — create the RIGHT thing (past sessions got this wrong)
+
+dreamcontext has **eight distinct entity types**, each with ONE home and ONE creation path. When the user says "create/add/track X", route by what X **is** — never by the nearest command you happen to remember. The canonical mistake: user says *"create an insight"* and the agent runs `knowledge create`. An insight is not knowledge.
+
+Two routing rules that override surface reading:
+
+- **Entity nouns are reserved words — in ANY language.** In a dreamcontext project, *insight, objective, roadmap, task, feature, knowledge, bookmark, trigger, release* name THESE entities, not their dictionary meanings — whatever language the sentence around them is in ("insight oluşturalım", "crea un insight" → `lab create`, not a prose analysis or an external dashboard). The trigger phrases below are English examples; match the **intent**, not the exact words.
+- **Route by problem-shape too, not only by verbs.** Users often describe the need without naming the entity. If the described capability matches a subsystem's shape (see litmus tests + the "don't rebuild" rule below), that subsystem IS the answer.
+
+| User says… | Entity | What it IS | Create with |
+|---|---|---|---|
+| "create an insight", "track MRR / WAU / signups", "add a metric", "I want to see X every session", **or the problem-shape:** "a chart/number that refreshes itself from Notion/Stripe/an API", "I don't want to ask you to re-fetch it every time", "same data, different views/date ranges" | **Insight** — `lab/insights/<slug>.md` | A curated analytics **metric backed by an external source** (HTTP API or script) — a number/series that re-syncs. Has a manifest, cache, TTL, adapters, tweaks, dashboard renders with a refresh button, optional KR binding (`lab bind <insight> <objective>`) | `dreamcontext lab create <slug> --title "…"` (offer-and-confirm protocol → [tasks-and-features.md](references/tasks-and-features.md)) |
+| "add an objective / goal / OKR", "put it on the roadmap", "we want X by Q4" | **Objective** — `core/objectives/<slug>.md` | A PO-authored **outcome** with target date, dependency DAG, optional Key-Result metric | `dreamcontext roadmap objective create` (ASK first — objectives are PO-owned) |
+| "document this", "write up the research / decision / how X works" | **Knowledge** — `knowledge/…` | Durable **prose**: research, decisions, rationale, domain context. It doesn't refresh itself and it isn't work to do | `dreamcontext knowledge create <name>` |
+| "the X feature", what a shipped capability is | **Feature PRD** — `knowledge/features/` | Retrospective **product doc** (user stories + acceptance criteria) | Sleep agent ONLY — never during active work |
+| any work over ~5 minutes, "let's build / fix X" | **Task** — `state/<slug>.md` | A **working document** with lifecycle, changelog, criteria | `dreamcontext tasks create` (check for an existing one first) |
+| a moment worth remembering, a correction, a decision made | **Bookmark** | A salience-tagged marker for the sleep agent | `dreamcontext bookmark add "…" -s N --task <slug>` |
+| "remind me when / next time X comes up" | **Trigger** | Prospective memory — fires when context matches | `dreamcontext trigger add <when> <remind>` |
+| "version / release / sprint / milestone" | **Release entry** — `RELEASES.json` | A planning version or shipped release | `dreamcontext core releases add` |
+
+**Litmus tests when unsure:**
+- Is it a **number/series that updates from a source**? → insight (`lab`).
+- Is it an **outcome with a committed date**? → objective (`roadmap`).
+- Is it **prose you write once and maintain**? → knowledge.
+- Is it **work to do**? → task.
+
+**Don't rebuild what the brain already has.** Before proposing to scaffold ANY new app, script, page, or external service for the user's need, check whether a dreamcontext subsystem already covers it: a self-refreshing metric/chart → **Lab insight** (the dashboard's Lab page IS the refreshable view — adapters, tweaks, renders included); OKR/goal tracking → **roadmap objectives**; "remind me when…" → **triggers**; kanban/board views → the **dashboard**. The second canonical mistake (a real past failure): the user described "a debt number that refreshes from Notion, with tweakable views" and the agent designed a brand-new Vercel dashboard — when `lab create` + a script adapter was the whole answer. Propose external builds only when no subsystem fits, and say why it doesn't.
+
+If the requested entity type is ambiguous ("track this" could be insight, objective, or trigger), **ask one clarifying question instead of guessing** — creating the wrong entity pollutes the brain and the user has to notice and undo it.
+
+---
+
 ## What Is Already In Your Context (do not re-read)
 
 The SessionStart hook injects this automatically every session — answer from it directly, **zero tool calls needed**:
@@ -109,6 +144,7 @@ The SessionStart hook injects this automatically every session — answer from i
 - **Extended core files index** — names/types of style guide, tech stack, system flow
 - **Active tasks** — status, priority, last updated, and the objectives each serves (answer "which tasks are active?" from this)
 - **Objectives (roadmap)** — active + recently-finished objectives with progress %, target vs forecast, and slip flags. **Weigh decisions against these outcomes** — they are WHAT the project is driving toward
+- **Lab insights** — cached analytics metrics (title / latest value / staleness / group) when `lab/insights/` is non-empty. Answer "what's our MRR/WAU?" from it; `dreamcontext lab sync` only when stale
 - **Bookmarks** — tagged important moments from prior sessions, by salience
 - **Contextual reminders** — triggers matching active tasks (prospective memory)
 - **Sleep state** — current debt level, sessions since last sleep, history
@@ -180,7 +216,7 @@ When in doubt about a command or flag, open [cli-reference.md](references/cli-re
 
    Skip triage only when the request is (a) a 1-line factual question, (b) purely about dreamcontext mechanics (this skill), or (c) outside every available skill's domain. When in doubt, load.
 
-3. **Recall before grep.** Before grepping `_dream_context/` for prior decisions or "did we already do X?", run `dreamcontext memory recall "<query>"`. It ranks across knowledge, features, tasks, memory, and changelog in one shot — cheaper and more on-target than blind Grep.
+3. **Recall before grep.** Before grepping `_dream_context/` for prior decisions or "did we already do X?", run `dreamcontext memory recall "<query>"`. It ranks across knowledge, features, tasks, memory, changelog, objectives, and insights in one shot — cheaper and more on-target than blind Grep.
 
 4. **Single source of truth — check before creating, update over duplicate.** Every fact lives in exactly ONE place. Before creating any task/feature/knowledge, `dreamcontext memory recall` for it; if it exists, UPDATE it instead of forking a copy.
    - **Know feature vs knowledge.** A **feature** (`knowledge/features/<name>.md` — typed knowledge, `type: feature`; the `dreamcontext features` CLI is a deprecated compat alias) is product documentation — what a capability *is*, its user stories + acceptance criteria — updated only at sleep. **Knowledge** (`knowledge/…`) is other durable material: research, decisions, rationale, domain/technical context. In-progress work lives in a **task**, never in a feature or knowledge file.
@@ -300,6 +336,7 @@ Status: `todo → in_progress → in_review → completed`. Sections: `why`, `us
 - **Quick capture:** `dreamcontext memory remember "<text>"` writes a `type=note` CHANGELOG entry; sleep reconciles it later. (`2.memory.md` no longer has a LIFO ship-narrative section — ship events live in CHANGELOG.)
 - **Knowledge files:** index auto-loaded; create with `dreamcontext knowledge create <name>`; pin frequently-needed ones (`pinned: true`); read non-pinned on demand and `knowledge touch` after. Group a flat file into a context folder with `dreamcontext knowledge move <slug> <folder>` (atomic move + inbound `[[wikilink]]` rewrite — never `mv` + hand-edit links).
 - **Features are sleep-only** (see rule 9).
+- **Insights are NOT knowledge** — a metric the user wants tracked ("create an insight", "track MRR") is a **Lab insight** (`dreamcontext lab create`), not a knowledge file. See the Entity Router above; full protocol → [tasks-and-features.md](references/tasks-and-features.md).
 
 **Recall modes, taxonomy, Excalidraw boards/diagrams, multi-product knowledge** → [knowledge-and-recall.md](references/knowledge-and-recall.md).
 
@@ -353,6 +390,11 @@ _dream_context/
 │   ├── features/<feature>.md         ← Feature PRDs, typed knowledge (type: feature; may include product:)
 │   ├── data-structures/{default,<product>}.md   ← schemas (recall-indexed; ```sql body)
 │   └── products/<product>.md         ← per-product knowledge (multi-product)
+├── lab/                              ← Analytics insights (curated metrics — NOT knowledge)
+│   ├── insights/<slug>.md            ←   insight manifests (`dreamcontext lab create`)
+│   ├── cache/<slug>.json             ←   synced series snapshots (never hand-edit)
+│   ├── scripts/<slug>.mjs            ←   custom-script adapters (run locally with your credentials)
+│   └── credentials.json              ←   gitignored — write ONLY via `lab credentials set`
 ├── overrides/
 │   └── task.md                       ← OPTIONAL: project task template + custom_fields schema (briefed to agents)
 ├── state/

package/skill/references/cli-reference.md

@@ -71,12 +71,31 @@ Sections for `tasks insert`: `why`, `user_stories`, `acceptance_criteria`, `cons
 | `roadmap objective delete <slug>` | Delete; other objectives' `depends_on` are healed automatically. `--yes`. |
 | `roadmap objective depend <A> <B>` | A depends on B — **rejected at write time** if it would create a circular dependency. |
 | `roadmap objective undepend <A> <B>` | Remove the dependency edge. |
-| `roadmap objective metric <slug>` | Set/update the objective's Key Result metric (outcome-based progress instead of task rollup). `--current <n>` (the common nudge — latest observed value), `--target <n>`, `--baseline <n>`, `--label <text>`, `--unit <text>`, `--clear` (remove the metric, back to task-based progress). Sleep may update `--current` when it observes a new real value; all other objective fields stay PO-owned. |
+| `roadmap objective metric <slug>` | Set/update the objective's Key Result metric (outcome-based progress instead of task rollup). `--current <n>` (the common nudge — latest observed value), `--target <n>`, `--baseline <n>`, `--label <text>`, `--unit <text>`, `--clear` (remove the metric, back to task-based progress). Sleep may update `--current` when it observes a new real value; all other objective fields stay PO-owned. **Insight-fed objectives are hands-off:** if a Lab insight binds this objective (`lab list --json` → `binding.objective`), `lab sync` owns `current` — don't hand-write it, suggest a sync instead; and before `--clear`, disconnect the feeder (`lab bind <insight> --clear`) so no binding is left warning on every sync. |
 
 Task-side linkage: `tasks create --objectives a,b` · `tasks objectives <task> a,b|clear` · `tasks list --objective <slug>`. Objectives are recallable: `memory recall "<query>" --types objective`.
 
 ---
 
+## Lab (analytics insights — see [tasks-and-features.md](tasks-and-features.md))
+
+Curated metrics synced from HTTP APIs or local scripts into `_dream_context/lab/`. **This — not `knowledge create` — is what "create an insight" means.** The SessionStart snapshot renders a Lab section; insights are recallable via `memory recall "<query>" --types insight`.
+
+| Command | Description |
+|---|---|
+| `lab create <slug>` | Scaffold `lab/insights/<slug>.md`. `--title <str>` (required), `--group <section>`, `--render number\|line\|pie\|raw` (default number), `--adapter http\|script` (default http), `--unit <str>`, `--ttl <minutes>` (default 1440). Edit the manifest afterwards to set the real endpoint/extract (or script) config, then sync. |
+| `lab sync [slug]` | Sync one insight, or every insight with `--all`. `--force` refetches even when the cache is within TTL (fresh insights are otherwise skipped and reported). On failure the prior series is kept, the error is loud, and the exit code is non-zero — never a silent half-sync. A changed custom script prints a loud tripwire notice before executing. |
+| `lab list` | All insights with latest value, unit, staleness. `--json`. |
+| `lab show <slug>` | Manifest + cached series — **cache only, never fetches**. `--json`. |
+| `lab tweak <slug> <key> <value>` | Set one declared tweak (typed `enum\|date\|string`; a relative range is an enum tweak keyed `range`). |
+| `lab bind <slug> [objective]` | Connect an insight to an objective's Key Result (`--value latest\|series:<name>`; `--clear` disconnects). Enforces ONE feeder per objective (a previous feeder is unbound loudly) and immediately seeds `metric.current` from the cached latest. The dashboard equivalent lives in the objective create modal / detail panel (Key Result section). |
+| `lab credentials set <key>` | Store a secret for `{{cred:key}}` placeholders — hidden prompt (`--value` works but is shell-history-risky). Gitignore-first, mode 0600. **The only supported way to create `lab/credentials.json`.** |
+| `lab credentials list` | Credential key NAMES only — values are never printed. |
+
+**Trust note:** `lab/scripts/*.mjs` run locally, in-process, with credentials passed in — same trust level as the repo. Review scripts before their first sync. **Sleep does NOT run lab sync** — refreshing is always an explicit action. An insight manifest may carry `binding: {objective: <slug>, value: latest}` to auto-write that objective's Key-Result `metric.current` on every successful sync — set it via `lab bind` or the dashboard's objective dialogs, not by hand.
+
+---
+
 ## Features
 
 | Command | Description |
@@ -120,7 +139,7 @@ Sections for `features insert`: `changelog`, `notes`, `technical_details`, `cons
 
 | Command | Description |
 |---|---|
-| `memory recall <query...>` | Search the corpus (knowledge + features + tasks + memory + changelog). `-t/--top <n>`, `--types <csv>`, `--json`, `--plain`, `--vault <name>` (repeatable), `--connected`, `--all-vaults`. |
+| `memory recall <query...>` | Search the corpus (knowledge + features + tasks + memory + changelog + objectives + insights). `-t/--top <n>`, `--types <csv>`, `--json`, `--plain`, `--vault <name>` (repeatable), `--connected`, `--all-vaults`. |
 | `memory remember <text...>` | Quick-append a CHANGELOG entry (`type=note`, `scope=quick`). `--summary`, `--type`, `--scope`, `--references <csv>`, `--person <csv>`. |
 | `memory update <slug>` | Update a knowledge file. `-d/--description`, `-t/--tags`, `-c/--content`, `--append <text>`, `--pin`, `--unpin`. |
 | `memory delete <slug>` | Delete a knowledge file (irreversible; recover via git). `-f/--force`. |

package/skill/references/knowledge-and-recall.md

@@ -4,6 +4,8 @@
 
 Deep, durable docs the agent should recall in future sessions (research, design rationale, domain context). The **index is auto-loaded each session** (names, descriptions, tags, staleness) — so you already know what exists.
 
+**Knowledge is prose, not everything.** A metric the user wants tracked ("create an insight", "track MRR") is a **Lab insight** (`dreamcontext lab create` — see [tasks-and-features.md](tasks-and-features.md)); an outcome with a target date is a roadmap **objective**; what a shipped capability is belongs in a **feature PRD**. See the Entity Router in SKILL.md before creating anything.
+
 ```bash
 dreamcontext knowledge create <name> -d "description" -t architecture,api -c "body"
 dreamcontext knowledge index [--tag <tag>] [--plain]
@@ -43,7 +45,7 @@ It moves the file **and** rewrites every inbound `[[wikilink]]` in one atomic st
 
 ## Memory functions — what they are and how to use them
 
-The `memory` command group is your interface to the curated corpus: `knowledge/*` (`knowledge/features/*` loads as its own `feature` channel — `--types feature` vs `--types knowledge` — never double-counted), `state/*.md`, `core/2.memory.md` (Technical Decisions + Known Issues), and every `core/CHANGELOG.json` entry. No setup, no index file, no external service — rebuilt in memory each call (<100ms on ~130 docs).
+The `memory` command group is your interface to the curated corpus: `knowledge/*` (`knowledge/features/*` loads as its own `feature` channel — `--types feature` vs `--types knowledge` — never double-counted), `state/*.md`, `core/2.memory.md` (Technical Decisions + Known Issues), every `core/CHANGELOG.json` entry, `core/objectives/*` (`objective` channel), and `lab/insights/*` (`insight` channel). No setup, no index file, no external service — rebuilt in memory each call (<100ms on ~130 docs).
 
 | Function | Use it to… | Command |
 |---|---|---|
@@ -57,7 +59,7 @@ The `memory` command group is your interface to the curated corpus: `knowledge/*
 
 ### recall — your first-line discovery tool
 
-**Run `memory recall` BEFORE grep or blind file reads** whenever the user asks "where did we decide X?", "have we discussed Y?", "what do we know about Z?", or before duplicating work. It ranks across knowledge + features + tasks + memory + changelog in one shot.
+**Run `memory recall` BEFORE grep or blind file reads** whenever the user asks "where did we decide X?", "have we discussed Y?", "what do we know about Z?", or before duplicating work. It ranks across knowledge + features + tasks + memory + changelog + objectives + insights in one shot.
 
 ```bash
 # Plain discovery — top 10 hits with snippets
@@ -68,6 +70,7 @@ dreamcontext memory recall "auth flow" --types knowledge,feature
 dreamcontext memory recall "deprecated" --types changelog        # ship history
 dreamcontext memory recall "rate limit" --types task             # in-flight work
 dreamcontext memory recall "retention goal" --types objective    # roadmap objectives (OKR outcomes)
+dreamcontext memory recall "weekly active users" --types insight # lab insights (curated analytics metrics)
 
 # Tune result count / machine-readable output
 dreamcontext memory recall "rice prioritization" --top 3 --json

package/skill/references/sleep.md

@@ -53,6 +53,7 @@ For non-file-change work (architecture discussion, a decision with no edits): `d
 5. **Wait for all reports** (each returns a short structured report).
 6. **`dreamcontext reflect`** — each candidate is a term seen across multiple sessions not yet in soul/user/memory/knowledge. Promote into `2.memory.md` or a knowledge file ONLY if genuinely load-bearing; most are noise — discard. Never auto-promote.
 7. **Roadmap refresh** if `_dream_context/core/objectives/` is non-empty: run `dreamcontext roadmap` — a cheap deterministic call that recomputes rollups/forecasts from the reconciled tasks and rewrites the auto-generated `knowledge/roadmap/board.md`. Surface any 🔴 SLIPPING objectives (and objectives whose member tasks are now all complete — suggest the PO confirm them done) in your summary. Sleep never edits objective files themselves — they are PO-authored.
+   **Insight-fed objectives:** if `_dream_context/lab/insights/` is non-empty, also run `dreamcontext lab list` — an objective fed by a bound insight (`binding.objective` in the manifest) has a *measured* KR `current` owned by `lab sync`; no specialist hand-writes it. Surface any bound insight whose cache is stale or errored ("KR for `<objective>` is fed by insight `<slug>`, last synced `<date>` — suggest `dreamcontext lab sync <slug>`"). **Sleep NEVER runs `lab sync`** — credentials, latency, non-determinism; refreshing is always an explicit user/agent action outside sleep.
 8. **Marketing pass** if `_dream_context/marketing/` exists: `dreamcontext mk rem-sleep`.
 9. **Council promote check:** `dreamcontext council list --unpromoted` — promote if the user engaged positively.
 10. **`dreamcontext sleep done "<one-paragraph summary stitched from specialist reports>"`** — clears pre-epoch state, resets debt, writes a history entry. (If a remote backend — ClickUp or GitHub — is active and any task pushes failed, this auto-retries once, then errors loudly with the failed slugs.)
@@ -64,7 +65,7 @@ For non-file-change work (architecture discussion, a decision with no edits): `d
 
 | Specialist | Owns | Notes |
 |---|---|---|
-| `sleep-tasks` | Task files (`state/*.md`) | Reconciles task bodies to truth, bumps statuses, creates tasks for untracked work, attaches to the planning version, sets the start/due range, and keeps declared custom fields current (never fabricating `ask` fields in the no-user sleep context). When objectives exist, proposes `objectives:` links for tasks with an EMPTY/absent list (multiple slugs when a task serves several outcomes) — **never overwrites a non-empty list** (that's a PO decision). |
+| `sleep-tasks` | Task files (`state/*.md`) | Reconciles task bodies to truth, bumps statuses, creates tasks for untracked work, attaches to the planning version, sets the start/due range, and keeps declared custom fields current (never fabricating `ask` fields in the no-user sleep context). When objectives exist, proposes `objectives:` links for tasks with an EMPTY/absent list (multiple slugs when a task serves several outcomes) — **never overwrites a non-empty list** (that's a PO decision). May refresh a KR's observed `current` via `roadmap objective metric` — EXCEPT objectives fed by a bound Lab insight (measured by `lab sync`; hands-off, staleness surfaced instead). |
 | `sleep-state` | Core identity (soul, user, memory, core 3–6), CHANGELOG, RELEASES | Records patterns/decisions/preferences, writes a changelog entry per meaningful change since the epoch, surfaces release readiness, enforces anti-bloat ceilings, flags stale knowledge for `sleep-product`. |
 | `sleep-product` | Knowledge files + feature PRDs | Creates/reconciles `knowledge/*.md` and `knowledge/features/*.md` (typed knowledge, `type: feature`), processes staleness flags, maintains the knowledge index + taxonomy. |
 | `sleep-migration` | Structure only | Moves/renames folders, normalizes frontmatter, wraps fences. Never alters body prose. |

package/skill/references/tasks-and-features.md

@@ -143,14 +143,63 @@ Objectives are PO-authored, so this is an **offer-and-confirm** flow, never a si
 1. **Dedup first.** Run `dreamcontext roadmap objective list` and `dreamcontext memory recall "<the outcome>" --types objective`. If an objective already covers it, DON'T propose a new one — offer to update the existing one instead (or just link the current work to it).
 2. **Offer it.** If it's genuinely new, ask: *"This sounds like a roadmap objective — want me to add it?"* Never create without a yes.
 3. **Ask the dates.** On yes, ask for the committed window — start and target date (`--target`, and set start via `objective edit`/dashboard). Don't invent dates.
-4. **Offer a Key Result.** Ask whether to track it by a number rather than member tasks: *"Track this by a metric (e.g. MRR 0→2000) or by its tasks?"* If a metric, capture `label` + `baseline`/`target` (`--metric*` flags on create, or `objective metric` after).
+4. **Offer a Key Result.** Ask whether to track it by a number rather than member tasks: *"Track this by a metric (e.g. MRR 0→2000) or by its tasks?"* If a metric, capture `label` + `baseline`/`target` (`--metric*` flags on create, or `objective metric` after). If a Lab insight already measures this outcome (`memory recall "<outcome>" --types insight`), offer to connect it — `dreamcontext lab bind <insight> <objective>` — so `current` is measured, not asserted.
 5. **Detect + propose dependencies.** From the existing objective list, infer likely `depends_on` edges ("make-it-a-business can't happen before simplified-ux and team-ready ship") and **propose them for confirmation**; on yes, apply with `objective depend <A> <B>` (the write-time cycle guard protects you). Never write a dependency edge silently.
-6. **Keep the Key Result current.** When the session later surfaces a real observed value for a tracked objective ("MRR just hit $1,250", "we're at 400 active users"), offer to update it: `dreamcontext roadmap objective metric <slug> --current <n>`. Use a value you actually observed — never estimate. (Sleep may also refresh `--current` autonomously from observed values.)
+6. **Keep the Key Result current — unless an insight feeds it.** When the session later surfaces a real observed value for a tracked objective ("MRR just hit $1,250", "we're at 400 active users"), offer to update it: `dreamcontext roadmap objective metric <slug> --current <n>`. Use a value you actually observed — never estimate. (Sleep may also refresh `--current` autonomously from observed values.) **Exception:** if a bound insight feeds the objective (`dreamcontext lab list --json` → a manifest whose `binding.objective` is the slug), `current` is *measured* — hands off; suggest `dreamcontext lab sync <insight>` instead of writing a number the next sync would overwrite. And when removing a fed objective's metric (`--clear`), disconnect the feeder first (`lab bind <insight> --clear`) — a binding with no Key Result warns on every sync.
 
 The through-line: **you detect and propose; the PO confirms.** Every create, date, dependency, and metric write waits for a yes — matching the "objectives are PO-authored" invariant and the board-first ritual (`knowledge/visual-first-board-ritual.md`).
 
 ---
 
+## Lab insights — curated analytics metrics
+
+An **insight** is a named, curated **metric backed by an external source** — "Weekly Active Users from our PostHog API", "MRR from a billing script". It is a number/series that **re-syncs on demand**, never a prose document. This is the entity users mean by "create an insight", "track signups", "I want to see MRR every session".
+
+**What an insight is NOT (route correctly):**
+- NOT **knowledge** — knowledge is prose you write and maintain; an insight fetches its value from a source. Never `knowledge create` for a metric.
+- NOT an **objective** — an objective is an outcome with a target date; an insight is the *measurement*. (The two connect: an insight can *feed* an objective's Key Result via binding, below.)
+- NOT a raw data dump — rollup structurally caps every series at 62 points (daily→weekly→monthly coarsening by span). Insights are curated metrics, by design.
+
+**Where it lives:** manifest at `_dream_context/lab/insights/<slug>.md` (frontmatter config + a `## Meaning` prose section that makes it recallable), cached series at `lab/cache/<slug>.json`, custom scripts at `lab/scripts/<slug>.mjs`, secrets in gitignored `lab/credentials.json`. Manifests + caches sync in the brain repo; only credentials stay local.
+
+**How agents see it:** the SessionStart snapshot renders a **Lab** section (title / latest value / staleness / group) — answer "what's our MRR?" from it without tool calls. Deeper: `dreamcontext lab show <slug>` (cache only, no fetch) and `memory recall "<meaning phrase>" --types insight`. The dashboard has a Lab page (number/line/pie/raw cards, per-insight refresh, sync-all, tweak editing).
+
+```bash
+dreamcontext lab create <slug> --title "Weekly Active Users" [--render number|line|pie|raw] [--adapter http|script] [--group <section>] [--unit users] [--ttl 1440]
+dreamcontext lab sync <slug> [--force]      # one insight (TTL-fresh is skipped unless --force)
+dreamcontext lab sync --all [--force]       # every insight; exits non-zero if any fail
+dreamcontext lab list [--json]              # all insights with latest value + staleness
+dreamcontext lab show <slug> [--json]       # manifest + cached series (never fetches)
+dreamcontext lab tweak <slug> <key> <value> # set a declared tweak (e.g. range last_1_year)
+dreamcontext lab bind <slug> <objective>    # connect to an objective's KR (--value latest|series:<name>; --clear)
+dreamcontext lab credentials set <key>      # hidden prompt; the ONLY way to store a secret
+dreamcontext lab credentials list           # key NAMES only — values are never printed
+```
+
+**Adapters:** `http` — declarative JSON API (endpoint/headers/body templates with `{{tweak:key}}` and `{{cred:key}}` placeholders, JSON-path `extract`, multi-series split via `seriesKey`); `script` — escape hatch, `lab/scripts/<slug>.mjs` exporting a default async function. `lab create` scaffolds the manifest; edit it to set the real endpoint/extract config, then run the first sync.
+
+**Key-Result binding (insight → objective):** a manifest `binding: {objective: <slug>, value: latest}` makes every successful sync write the objective's KR `metric.current` automatically — upgrading the roadmap from PO-asserted numbers to measured ones. Offer this whenever an insight measures an existing objective's outcome. Set it via `lab bind` (or the dashboard's objective create modal / detail panel, which search insights by name); binding is ONE feeder per objective — connecting a new insight unbinds the previous one loudly, and connecting immediately seeds `metric.current` from the cached latest.
+
+**Sync semantics:** TTL staleness (default 1440 min) — fresh insights are skipped and reported, `--force` refetches; on failure the prior series is KEPT and the error is loud (never a silent half-sync). **Sleep does NOT run lab sync** — refresh is always an explicit user/agent action.
+
+### Insight capture (in-session — ASK, never auto-create)
+
+Mirrors proactive objective capture. When the user states or implies a recurring metric need ("I keep checking MRR by hand", "we should watch signups", "create an insight for DAU"):
+
+1. **Dedup first.** `dreamcontext memory recall "<metric>" --types insight` and `dreamcontext lab list`. If one covers it, offer to update/re-sync it instead.
+2. **Offer it.** *"Want me to track this as a Lab insight so every session sees the current value?"* Never create without a yes.
+3. **Agree the shape.** Slug, title, render (number/line/pie/raw), group, unit — and write a real `## Meaning` section (it powers recall).
+4. **Pick the source.** HTTP endpoint (+ extract path) or a custom script. Secrets go in via `dreamcontext lab credentials set <key>` — never inline in the manifest.
+5. **Declare tweaks** the user will want to adjust (typed `enum`/`date`/`string`; a relative range is an enum tweak keyed `range`).
+6. **Scaffold + first sync.** `lab create`, edit the manifest, `lab sync <slug>`, confirm the value looks right.
+7. **Offer KR binding** if an existing roadmap objective tracks the same outcome: `dreamcontext lab bind <insight> <objective>` — connecting seeds the objective's `metric.current` from the cached latest immediately, and every future sync keeps it measured. One feeder per objective (binding a new insight unbinds the previous one loudly); disconnect with `lab bind <insight> --clear`.
+
+Every write waits for a yes.
+
+**Security (plain language, tell the user when relevant):** lab scripts execute **locally, in-process, with your credentials passed in** — anyone who can push to a shared brain repo can change what runs on your machine at the next sync. Review a script before its first sync and heed the loud "script changed since last run" tripwire notice. Credentials are written ONLY via `lab credentials set` (gitignore-first, file mode 0600, never printed back, redacted from every error/log).
+
+---
+
 ## The Workflow flowchart (keep it in sync)
 
 Every task file has a `## Workflow` mermaid block near the top: one node per acceptance criterion, grouped under milestone subgraphs, with status classes `done` / `active` / `todo` / `blocked`. It is the load-bearing summary of the task — drift makes future sessions misread progress.

package/dist/dashboard/assets/channel-CIIBmX-d.js

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

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

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-DjvoLiQ0.js";import{_ as i}from"./index-C2R7Is0-.js";import"./chunk-FMBD7UC4-DDlvS1yz.js";import"./chunk-YZCP3GAM-CZjAdM3g.js";import"./chunk-55IACEB6-D-m72jvC.js";import"./chunk-EDXVE4YY-BCjmEpM7.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};

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

@@ -1 +0,0 @@
-import{s as a,c as s,a as e,C as t}from"./chunk-4TB4RGXK-DjvoLiQ0.js";import{_ as i}from"./index-C2R7Is0-.js";import"./chunk-FMBD7UC4-DDlvS1yz.js";import"./chunk-YZCP3GAM-CZjAdM3g.js";import"./chunk-55IACEB6-D-m72jvC.js";import"./chunk-EDXVE4YY-BCjmEpM7.js";var u={parser:e,get db(){return new t},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{u as diagram};

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

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