dreamteamer 0.15.0 → 0.16.0

package/README.md

@@ -146,10 +146,12 @@ workspace pins**, so the editor, the CLI and any agent session are provably runn
 This is an agent-native tool, so its documentation is shipped as skills the agent loads on demand —
 and you can read them like any other file:
 
-- [`skills/using-dreamteamer`](skills/using-dreamteamer) — the map: collections, conventions, the CLI,
-  how records work
-- [`skills/building-dreamteamer`](skills/building-dreamteamer) — authoring: collections, skills,
-  agents, commands, UI views, and which of those a given request should become
+- [`skills/using-dreamteamer`](skills/using-dreamteamer) — the one skill: working with records
+  (the CLI, conventions, commits) and modeling the workspace (collections, skills, agents,
+  commands, UI views — and which of those a given request should become), each topic a reference
+  loaded on demand
+- [`docs/one-skill-blast-radius.md`](docs/one-skill-blast-radius.md) — the 0.16.0 skill
+  consolidation: what breaks for a consumer, what to grep for, which claims were verified live
 - [`docs/repos-and-modules.md`](docs/repos-and-modules.md) — attached repos vs modules, and why they
   have different homes
 - [`docs/namespaces-blast-radius.md`](docs/namespaces-blast-radius.md) — scoping collections under a

package/collections/collections.collection.yaml

@@ -37,7 +37,17 @@ schema:
       properties:
         path:
           type: string
-          description: Folder holding the records, workspace-relative. `data/` for content, `state/` for operational records, `system/` for sources.
+          description: >-
+            Folder holding the records, workspace-relative. `data/<collection>` — that is the answer
+            unless you can state a reason. `state/<collection>` is DEPRECATED as a convention since
+            2026-08-31: decision 4 created it for runs, triggers, registries and cursors, all seven
+            of those collections have been deleted, and the one real operational-data need that
+            arrived since went to a gitignored `.cache/*.jsonl` because append-only readings are the
+            wrong shape for records. The mechanism still works and is kept, exactly like `group`
+            below, so a workspace wanting a second root has one. ⚠ NEVER author `system/` — sources
+            have lived in `modules/<module>/<kind>/` since the 2026-08-05 flatten, and a `system/`
+            prefix is only how `runtime.js` recognises a RUNTIME collection in a descriptor compiled
+            by a pre-flatten engine.
         codec:
           type: string
           enum: [md, yaml, json, file]
@@ -89,7 +99,7 @@ schema:
       type: string
       description: >-
         Which field carries MANUAL order — the one a drag writes. The field must be declared by this
-        collection's own schema, and holds a fractional index (`dt <collection> move`), never an
+        collection's own schema, and holds a fractional index (`dt move <collection>/<id>`), never an
         integer: renumbering is a multi-file commit against git. A surface offers dragging only while
         it is sorted by this field, because a handle that reorders nothing is a lie.
     icon:

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.15.0",
+	"version": "0.16.0",
 	"description": "A workspace compiler for coding agents — schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",

package/skills/using-dreamteamer/SKILL.md

@@ -1,131 +1,138 @@
 ---
 name: using-dreamteamer
-description: always load first — describes this dreamteamer workspace, its collections, conventions and your pending tasks
+description: always load first in a dreamteamer workspace — reading, writing and committing records, and changing what the workspace keeps or does (collections and fields, skills, commands, agents, ui-views, component code). Also when deciding which of those a request should become, when a compile or check error names a source file, or when a request names a new kind of thing to keep.
 ---
 
 # using dreamteamer
 
-this is a **dreamteamer** workspace: collections, skills, agents and commands are records compiled
-from sources into a runtime the harness reads.
+this is a **dreamteamer** workspace: collections of typed records, plus the skills, commands,
+agents and views that operate on them — all compiled from sources into a runtime the harness
+reads.
 
-**core principle:** read the compiled runtime, write the sources, compile — then `dt commit` to publish.
+**core principle:** read the compiled runtime, write records with the CLI and sources under
+`modules/`, compile after any source change — then `dt commit` publishes what you wrote.
 
-## when to use
+## when to load
 
-load this **first, every session** in this repo. reload mid-session on any of these symptoms: you're
+first thing, every session in this repo. reload mid-session on any of these symptoms: you're
 about to guess a collection's fields; you can't tell whether the file to edit lives under
 `modules/*/<kind>/` or `.dreamteamer/`; you wrote something and the harness didn't notice; you're
 unsure which skill owns the job in front of you.
 
-**this file is the MAP, not the procedure.** Detail lives in two references beside it, loaded on
-demand:
-
-| load | when |
-|---|---|
-| `references/records.md` | reading, creating, updating, renaming or deleting any record — the CLI verbs, hand-writing rules, the hard rules about ids and renames |
-| `references/git-events.md` | "what changed while I was away" — `dt changes`, and how record events are derived from git history |
-
 ## the contract
 
 | concern | where | rule |
 |---|---|---|
 | schemas (read) | `.dreamteamer/collections/*.collection.yaml` | the single source of truth for what exists and its shape. **never edit under `.dreamteamer/`** — generated and gitignored |
 | provenance | `.dreamteamer/manifest.yaml` | which module shipped which entry |
-| sources (write) | `modules/<module>/` — **including the workspace's own**, the `dreamteamer.workspace-module` named in `package.json` | a source folder at the workspace ROOT is a compile ERROR. same-name collisions across modules are compile errors too. after ANY source change: `npm run compile` |
-| content records | `data/<collection>/` | per each descriptor's `storage.path` |
-| operational records | `state/<collection>/` | whatever a module declares there; core ships none |
+| sources (write) | `modules/<module>/<kind>/` — **including the workspace's own**, the `dreamteamer.workspace-module` named in `package.json` | a source folder at the workspace ROOT is a compile error (whenever `workspace-module` is set — every `dt init` workspace); same-name collisions across modules too. after ANY source change: `dt compile` |
+| records (write) | `data/…`, per each descriptor's `storage.path` | the CLI writes them validated; hand-edits are legal and owe `dt check` |
 
-- a record is a `<id>.<suffix>.<ext>` file (or a folder, for folder-shape collections). **the id is
-  the path** inside the collection folder minus suffix and extension — nested folders join in:
+- a record is a `<id>.<suffix>.<ext>` file (or a folder, for folder-shape collections). **the id
+  is the path** inside the collection folder minus suffix and extension — nested folders join in:
   `data/meetings/2026/07/standup.meeting.md` ⇒ id `2026/07/standup`.
-- **references are `<collection>/<id>`** strings — always qualified, greppable, never a bare name and
-  never a file path.
+- **references are `<collection>/<id>`** strings — always qualified, greppable, never a bare name
+  and never a file path.
+
+**lifecycle:** `dt init` writes a new workspace's skeleton (it never compiles). a FRESH CLONE owes
+`dt install` (restores `git_modules/`) then `dt compile` before anything reads — `.dreamteamer/`
+and the harness folders are gitignored build output, so a clone has no runtime until compile
+writes one — and `.env` is per-machine (declared keys: `references/records.md`). `dt status` says
+whether the runtime is fresh. the workspace's own switches live in `package.json`'s `dreamteamer`
+block (`references/collections.md`, the workspace manifest).
 
 ## the CLI is the front door
 
-`npm run --silent dt -- help` is the command surface — don't learn the generic verbs and flags from
-prose; prose drifts. it does **not** list the purpose-built verbs some collections have
-(`schema add-collection`, `schema add-field <collection>`, `ensure`) — those live in the skill that owns
-them, and a verb absent from `help` still works.
+`dt` in this skill means the dreamteamer CLI: **`npx dreamteamer`** works in any workspace, and a
+workspace may alias it as an npm script — check `scripts` in `package.json` (the common spelling
+is `npm run --silent dt -- <verb> …`).
 
-what you need to know *about* the CLI: collection verbs validate hard — invalid writes, **including
-unknown fields**, are rejected before disk — and a write does NOT commit (see conventions below).
+**`dt help` is the complete command surface** — record verbs, schema verbs, workspace verbs, and
+their flags, on one page (there is no per-verb `--help`). don't learn syntax from prose, this skill included: prose drifts, and `help` ships in
+the same file as the dispatch it documents. run it once before your first write of a session.
+what prose adds is judgment — *when* a verb is the right move, and the guarantees you can lean
+on: **validation is hard** (unknown fields included; an invalid write is rejected before disk
+with no partial state), and **a write does not commit** — `dt commit` publishes, scoped
+(`references/records.md`).
 
-## routing
+## two acts, one map
 
-| the request is about | load |
-|---|---|
-| a record — read, create, update, rename, delete | `references/records.md` |
-| authoring anything under a module's source folders — a collection, field, skill, command, agent, ui-view, or component code | `building-dreamteamer` |
-| "what changed while I was away" | `references/git-events.md` |
-| the workspace lacks the capability entirely | `building-dreamteamer` → `references/before-you-build.md`, then `references/data-modeling.md` |
-
-Domain work — meetings, contacts, tasks, content, design — is owned by the **module** that ships those
-collections, not by core. Read that module's own skills. Core knows about entity kinds and `repos`,
-and deliberately nothing else — including nothing about people. There is no `users` collection.
-
-## conventions
-
-- **a write puts a record on disk; `dreamteamer commit` publishes it.** committing is POLICY —
-  `"auto-commit"` in the workspace's `package.json`, default off — not a property of the write. so
-  commit when a logical change is complete, and run `dt status` if you are unsure what is pending.
-  subjects still read `dreamteamer: <verb> <detail>` for a single record (`dt commit` composes them
-  from git's own status letters), and a multi-record commit says what it swept.
-- **one commit per REPO.** a module can own its records (`owns-data` in its package.json), and git
-  has no cross-repo commit — so a rename whose inbound refs live in another repo is TWO commits.
-  `dt commit` prints both. `--dry-run` shows the set first.
-- **scope the commit to what YOU wrote: `dt commit <collection>/<id>`.** any number of targets, each
-  either a whole `<collection>` or one record — bare `dt commit` publishes everything pending, and
-  `dt commit <collection>` publishes every dirty record under it *whoever wrote it*, which is the
-  same sweep as the blanket add below when a second session shares the tree.
-- **never `git add -A`, `git add .`, or `git commit -a`.** stage explicit paths. more than one agent
-  can be working in a tree, and a blanket add silently commits whatever another session has
-  uncommitted right now — under your subject, leaving `git status` clean and the damage invisible.
-  the CLI's own writes are pathspec-scoped for exactly this reason, which is why it is the preferred
-  path for record writes.
-- **validate after bulk edits**: `npm run check` reports violations and never modifies files.
-- workspace-level rules live in `CLAUDE.md`, and a workspace's decision log (where one exists) wins
-  over older documents.
-- **session greeting** — surface the operator's inbox from whatever collection this workspace uses for
-  work, e.g. `npm run --silent dt -- list tasks --status todo`. ⚠ **there is no `users` collection and
-  no `@me`** (both removed in 0.8.0); read the operator from `git config user.name` at the point you
-  need one, and never filter on a person unless this workspace owns a collection of them.
-
-## machine-specific references
-
-a path that exists on only one machine — a synced folder, an external disk — is written as a
-**template**, never as an absolute path:
-
-```yaml
-source_file: ${env:FILES_FOLDER}/2026/q3.pdf
-```
-
-| variable | renders to |
+Act one is **working with data** — the records themselves. Act two is **modeling the workspace**
+— changing what it keeps (collections, fields) or what it does (skills, commands, agents, views).
+Load by the map; nothing here is loaded "just in case".
+
+| the job | load |
 |---|---|
-| `${env:NAME}` | `NAME`'s value in the workspace's `.env` — and only if `NAME` is listed in `dreamteamer.vars` in `package.json` AND has a non-empty value there (an empty or whitespace-only value fails exactly like an unset key) |
-| `${workspaceFolder}` | the workspace root, absolute |
-| `${userHome}` | the current user's home directory |
-
-- **declare the key before using it**: `"dreamteamer": { "vars": ["FILES_FOLDER"] }`. an undeclared
-  key and a declared-but-absent one are deliberately different errors — the first is a typo, the
-  second is a machine nobody has set up. `npm run compile` warns per declared var with no value in
-  `.env`, naming keys only.
-- **render with `dt resolve`, the only substitution point**: `dt resolve '${env:FILES_FOLDER}/x'`, or
-  `dt resolve <collection>/<id> <field>` to render what a record already holds (an array field prints
-  one item per line). an argument containing `${` is always a template, so a ref-shaped one is never
-  split as a reference.
-- ⚠ **templates are ordinary data — write them literally; nothing substitutes until resolve is
-  called.** `dt get`, `list`, `check` and every harness read the template verbatim. an un-namespaced
-  `${VAR}` is inert, so prose may mention `${…}` freely.
+| read, create, update, rename, delete, commit — or UNDO — a record | `references/records.md` |
+| "what changed while I was away" | `references/changes.md` |
+| the workspace seems unable to do something — a new kind of thing, a missing capability, "don't we already have this?" | `references/before-you-build.md` (look first); a new model then continues `references/data-modeling.md` (decide) → `references/collections.md` (write it) |
+| a collection or field, mechanically — the descriptor, the `schema` verbs, `templates:`/`extends:`, a compile or check message | `references/collections.md` |
+| knowledge a session should find on its own | `references/skills.md` |
+| "let me type one word and have this done" | `references/commands.md` |
+| "which command applies to this record?" — a binding, a gate | `references/commands.md` |
+| a job needing a fresh context and its own tools | `references/agents.md` |
+| a route, a nav entry, a board / calendar / map over records | `references/ui-views.md` |
+| a rendering or editing behaviour nothing registered has | `references/ui-components.md` |
+
+three act-two tie-breakers, because they are the ones that go wrong:
+
+- **skill vs command:** a skill triggers itself when the situation arises; a command needs the
+  operator to remember it exists. if the answer is "and they'd have to think of running it",
+  write the skill.
+- **agent vs skill:** an agent costs a whole context. if "just tell the current session how"
+  works, it is a skill.
+- **a multi-step process is a CHAIN OF COMMANDS** gated on record fields (`references/commands.md`),
+  never a workflow entity — there is no workflow kind, deliberately: the record's own state is
+  the progress marker.
+
+domain work — meetings, patients, invoices, whatever this workspace is about — is owned by the
+**module** that ships those collections; read that module's own skills. core knows entity kinds
+and `repos`, and deliberately nothing else. workspace-level rules live in `CLAUDE.md`, and a
+workspace's decision log (where one exists) wins over older documents.
+
+## the rules that hold in both acts
+
+1. **sources live in a module** — `modules/<module>/<kind>/`; the workspace's own go in its
+   workspace module. **a module is discovered by its `package.json` carrying a `dreamteamer`
+   key** (`"dreamteamer": {}` is enough) — without it, the folder is silently ignored.
+2. **the filename is the id.** where a record also carries a frontmatter `name` (agents,
+   commands), the two must agree, or the id lies and dispatch misses.
+3. **the meta-descriptor is the spec.** every source kind is itself a collection — read
+   `.dreamteamer/collections/<kind>.collection.yaml` plus one real record (`dt get <kind>/<id>`)
+   instead of learning a shape from prose.
+4. **`dt compile`, then `dt check`**, after any source change. compile fails closed — a bad
+   source is rejected and the previous runtime stands; check reports and never modifies.
+5. **a running session does not see new sources.** a new skill, command or agent is live in the
+   operator's NEXT session — say so rather than letting them wonder.
+6. **never edit generated output.** `.dreamteamer/`, `.claude/`, `.agents/`, `.cursor/` are
+   overwritten and pruned on the next compile — if you found the thing to change there, you are
+   in the wrong file.
+7. **the CLI refuses system-stored records on purpose** (`dt set skills/<id>` — no): edit the
+   module source and compile. the `schema` verbs are the sanctioned exception — they write
+   sources *through* a compile gate, so an uncompilable source can never land.
+8. **never duplicate a procedure across records.** a command body restating a skill, an agent
+   inlining its skill's steps — two copies, and one drifts. reference the owner.
+9. **nothing module-shipped names a person, an account or a machine path.** per-install values
+   are `${env:VAR}` templates plus a declared var, rendered only by `dt resolve`
+   (`references/records.md`).
+10. **commit discipline: scope to what YOU wrote** — `dt commit <collection>/<id> …` — and never
+    `git add -A`, `git add .` or `git commit -a`: a blanket add silently sweeps another session's
+    pending work under your subject. commit when a logical change is complete — records via
+    `dt commit`, sources via `git add <specific paths>`; `dt status` says what is pending, and
+    `dt check` runs after bulk edits.
 
 ## common mistakes
 
-| mistake | why it bites |
+| mistake | reality |
 |---|---|
-| editing something under `.dreamteamer/` | generated + gitignored; the change vanishes on the next compile |
-| changing a source and not compiling | the harness and `check` still read the stale runtime |
+| editing under `.dreamteamer/` or `.claude/` | generated — the change vanishes next compile; find the module source |
+| changing a source and not compiling | the CLI, `check` and every harness still read the stale runtime |
 | hand-writing a record the CLI could add | skips validation, id generation and defaults |
 | bare refs (`ada`, `data/contacts/x.contact.md`) | refs are `<collection>/<id>`; anything else fails check |
-| assuming a write was committed | it was not, unless `auto-commit` is on — `dt status` says what is pending |
+| assuming a write was committed | it was not (unless `auto-commit` is on) — `dt status` shows pending |
+| learning flags from prose or memory | `dt help` is the surface; prose carries judgment only |
+| a new module folder compile ignores | its `package.json` needs a `dreamteamer` key |
 | `git add -A` in a shared tree | steals another session's uncommitted work, invisibly |
-| an absolute machine path in a record | it is wrong on every other machine — write `${env:NAME}` and declare the key |
+| an absolute machine path in a record | wrong on every other machine — `${env:NAME}` + a declared var |
+| picking an entity by what is easiest to write | pick by how it should be TRIGGERED — that is what the choice encodes |
+| telling the operator a new source works now | it works in their **next** session |

package/skills/using-dreamteamer/references/agents.md

@@ -0,0 +1,162 @@
+# agents — a persona you pay a whole context for
+
+`modules/<module>/agents/<name>.agent.md` — one markdown file whose filename MUST equal the
+frontmatter `name`. Compile turns it into a dispatchable subagent definition with one real
+transform (below), so the record *is* the subagent.
+
+You are usually here for one of two reasons: deciding whether an agent is the right entity at all,
+or authoring one. Either way, what you write is judged by three readers who are not you:
+
+- the **dispatcher** — a harness or a master agent matching a request against `description`. That
+  one line is the agent's entire discoverability;
+- the **agent itself** — waking with your body as its system prompt, its declared skills, its
+  declared tools, and **none of the caller's context**;
+- the **caller** — who gets back only what the agent chooses to hand back, and must act on it.
+
+| the question | read |
+|---|---|
+| should this be an agent at all | the economics |
+| what compile does with the file | mechanics |
+| the one line the dispatcher sees | the description |
+| the body | the system prompt |
+| tools, model, skills | the allowances |
+| does it actually work | verification |
+
+## the economics — when an agent earns a context
+
+An agent costs a whole context per dispatch: the harness spins up a fresh session, loads the
+declared skills, and the persona re-orients from zero before its first useful act. That cost buys
+exactly four things, and a job that needs none of them should be something cheaper:
+
+| the job needs | why an agent and nothing else delivers it |
+|---|---|
+| **isolation** — fresh eyes that must not share the caller's context | a reviewer or critic run inside the author's context inherits the author's blind spots; the empty context IS the value |
+| **a narrower tool set, as a guarantee** | "read-only" enforced by allowlist, not by promise — a skill inherits whatever tools the session already has |
+| **parallelism** — several independent subtasks at once | each needs its own context by construction |
+| **routing** — a persona whose whole job is picking the right collection, skill or agent | the master-agent pattern; core's own `dreamteamer` agent is exactly this |
+
+What does *not* justify one:
+
+- **Size.** "It's a big task" — the current session can do big tasks; a skill tells it how.
+- **Recurrence.** A situation that keeps arising wants a skill, which triggers itself.
+- **A shortcut.** Something the operator deliberately types is a command.
+- **A procedure.** Procedures live in skills; an agent *references* its skills, never restates
+  them (the digest's never-duplicate rule — two copies drift).
+
+The tie-breakers, as tests: if "just tell the current session how" works, write the skill. If the
+operator must remember to run it, write the command. Write the agent only when the fresh context is
+a *feature* — independence, enforcement, parallelism — rather than an overhead.
+
+## mechanics — what compile does with the file
+
+- **Copies it to `.claude/agents/<name>.md`** (stamped as generated) with **one transform**: the
+  `skills:` frontmatter list is not a key any harness understands, so compile deletes it and
+  prepends a body line — *"ALWAYS load these skills (Skill tool) before acting: …"*. Everything
+  else passes through verbatim.
+- **Validates the skill refs.** A `skills:` entry naming a skill that is not in this compile is a
+  **compile error**, not a dangling pointer — an agent cannot ship pointing at a skill its module
+  forgot to bring. Self-containment with teeth: the module that ships the agent ships (or depends
+  on) its skills.
+- **Only claude-code gets native agent files.** The other harnesses' orientation blocks point at
+  `.dreamteamer/agents/` and leave dispatch to whoever reads them. Write for the record, not for
+  one harness's dispatch mechanics.
+- Like every source: a new or changed agent exists in the **next** session, not this one.
+
+| field | required | notes |
+|---|---|---|
+| `name` | yes | must equal the filename — this is the id, and dispatch misses when they disagree |
+| `description` | yes | **when a dispatcher should pick this agent** — concrete triggers, never a role title |
+| `tools` | no | the allowlist; give only what the job needs. Omit = the harness default set, which is broad |
+| `model` | no | override (`sonnet`, `opus`, …); omit to inherit the session's |
+| `skills` | no | qualified `skills/<id>` refs, verified at compile — loaded before the agent acts |
+
+The body is the `instructions` field (`x-body: true`) and becomes the subagent's system prompt.
+
+## the description — written for the dispatcher
+
+The dispatcher sees the description and nothing else. A role title ("the research agent") gives it
+nothing to match against; triggers do — the request shapes, symptoms, and words a caller would
+actually use:
+
+```yaml
+# ✖ a role title — matches nothing in particular, so it matches wrongly
+description: the review agent
+
+# ✔ dispatch conditions — request shapes, concrete situations
+description: dispatch when freshly-written records need checking against their collection's
+  conventions before commit — a batch import, a bulk edit, records written by a new skill
+```
+
+Same discipline as a skill description (`skills.md`): conditions, not contents. A description that
+summarizes what the agent will do invites the dispatcher to do it itself instead of dispatching.
+
+## the body — a system prompt for someone with no memory of this conversation
+
+The agent wakes knowing only what the body, its skills, and the dispatch prompt tell it. Three
+parts, in order, and rarely more than a paragraph:
+
+1. **What to read first** — the records, descriptors or files that orient it.
+2. **What to do** — by reference to its skills, never by restating them. The body says *which*
+   judgment to apply; the skill owns *how*.
+3. **What to hand back — the return contract.** The most-omitted part, and the one the caller
+   actually depends on. An agent whose body never states its output shape returns an essay, and
+   the caller re-derives what it needed from prose. Name the shape: the verdict, the evidence,
+   what was not checked.
+
+A body growing past ~15 lines has swallowed a skill — extract the procedure into one and reference
+it.
+
+Two references worth copying. Core's `agents/dreamteamer.agent.md` — the only agent core ships —
+shows the router shape: trigger description, tight tool list, one skill ref, one-paragraph body.
+And the reviewer shape, annotated:
+
+```yaml
+---
+name: record-reviewer
+description: dispatch when freshly-written records need checking against their collection's
+  conventions before commit — a batch import, a bulk edit, records written by a new skill
+tools: [Read, Grep, Glob, Bash]          # no Write, no Edit — read-only is the guarantee
+skills: [skills/using-dreamteamer]        # qualified; verified at compile
+---
+Load the skills above, then read the compiled descriptor of every collection the dispatch prompt
+names. Sample the named records against them: field conventions, reference shape, id shape,
+suspiciously empty required fields. Do not fix anything. Hand back one line per problem —
+`<ref> — <what is wrong> — <the fix>` — then the list of records checked and found clean.
+```
+
+Why each line earns its place: the tool list omits Write/Edit because the *allowlist* is the
+enforcement (the body's "do not fix anything" is only the explanation); the description names three
+dispatch situations, not a title; the body is read → judge → hand back, with the return contract
+concrete enough that the caller can act on it mechanically.
+
+## the allowances — tools, model, skills
+
+- **Tools**: subtract, don't add. Start from what the job cannot work without; a Write tool on a
+  read-only reviewer is a footgun, and "it might need it" is how footguns ship. Omitting the key
+  means the harness default — which is broad, and therefore also a choice.
+- **Model**: omit to inherit. Override downward for cheap high-volume jobs (a formatter, a
+  triager); override upward only when the job measurably fails on the default.
+- **Skills**: one or two. Each ref is loaded on *every* dispatch — a per-invocation cost, which is
+  why the procedure lives in the skill once instead of being pasted into both. Design the pair to
+  be self-sufficient: a subagent cannot reliably ask the caller questions mid-flight, so what it
+  needs must arrive in the body, the skills, or the dispatch prompt.
+
+## verification
+
+Compile + check prove the record is well-formed, not that the persona works. In the next session
+(or from a fresh dispatch): give it a realistic task and judge the **result shape** — did it load
+its skills, did the tool limits hold, and above all did it hand back the return contract, or an
+essay? Reading your own agent definition proves nothing; the same rule as skills.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| a `description` that is a role title ("the research agent") | dispatchers match on triggers; say when to pick it |
+| `skills: [using-dreamteamer]` | refs are qualified: `skills/using-dreamteamer` |
+| pasting the skill's procedure into the body | two copies, one drifts; the body references, the skill owns |
+| no return contract in the body | the agent returns an essay and the caller re-derives the answer |
+| a broad `tools` list "just in case" | the allowlist is the enforcement — a Write tool on a reviewer is a footgun |
+| creating an agent for a one-off instruction | a skill (recurring) or just doing it (one-off) is the right answer |
+| creating an agent because the task is big | size is not isolation; a skill in the current session handles big |
+| testing by reading the definition | dispatch it with a real task and judge what it hands back |

package/skills/using-dreamteamer/references/before-you-build.md

@@ -0,0 +1,99 @@
+# before you build — look for it first
+
+The situation: the operator asked for something the workspace does not seem to do, and you are one
+`schema add-collection` or one new skill away from making it exist. This reference is the pause
+before that. **When the workspace can't do something, look before you build — and when you do find
+something, propose concretely, never install or copy silently.** The operator decides what enters
+their workspace.
+
+Two people meet in this decision, and only one of them is in the room. The session about to build
+(you) experiences exactly one step of the capability's life: creating it, which is also its
+cheapest step. The operator owns every other step — compiling it, maintaining it, paying for its
+line in the orientation block every session loads, and eventually noticing it drifted or died.
+Every rule below is that asymmetry applied.
+
+| the question | read |
+|---|---|
+| where do I look, and how, concretely | the four places |
+| I found something — is that "found"? | what found means |
+| how do I put it to the operator | the proposal |
+| nothing exists anywhere | build it — in the module that owns the concept (`data-modeling.md` Part III), after proposing (Part II §7) |
+
+This replaced a standalone `discovering-new-capabilities` skill on 2026-07-31, whose premise — "find
+and propose an **installable** module" — had been reversed: domain modules are no longer packages you
+install. The looking still matters; the taking changed shape.
+
+## why looking wins
+
+- **A duplicate is worse than a gap.** Two collections holding one concept under two names split
+  every future search, and neither ever learns what the other knows. A gap at least stays visible.
+- **The thing you didn't find still costs you.** Building beside an existing capability means the
+  operator now maintains both, and the day they diverge nobody can say which is right.
+- **Adoption is mostly deletion.** A found module arrives maximal — collections you don't need,
+  skills for accounts you don't have. The work of adopting it is cutting it down, which is far
+  cheaper than building up, and keeps the found thing's hard-won trap notes intact.
+- **Hard-to-find is its own diagnosis.** When the capability existed and you missed it, the fix is
+  a better `description` or `use_when` on the existing entity — not a second entity. The miss you
+  just experienced is exactly the retrieval test that description failed.
+
+## the four places, in order
+
+| # | look at | how, concretely | what you get |
+|---|---|---|---|
+| 1 | **this workspace's own modules** | the orientation block's COLLECTIONS list is already in your context — reread it with the concept's *synonyms* in mind; `.dreamteamer/manifest.yaml` names every module and entry; `dt help` shows the verbs and `dt commands <collection>` the bound ones; the skills index shows the techniques | the thing may already exist under a name you didn't guess. This is where misses actually happen, because it is the place you assume you already know |
+| 2 | **a recipes repo — where this workspace's own CLAUDE.md names one** (reference modules maintained to be **copied and adapted**) | read that repo's own instructions first; they ARE the adoption procedure. no recipes repo declared → skip this row | a working module with its reasoning attached — descriptors, skills, and the trap notes that each cost someone a day |
+| 3 | **a sibling workspace — where the operator has named one** | read-only; grep its `modules/` for the concept. none named → skip | another vault may have solved it concretely. That is a *reference*, not a source — it holds real personal data, so read the shape, never lift the content |
+| 4 | **the engine's own surface** | `dt help` — the complete verb surface, schema verbs included; read it rather than recalling it | the capability may already be a verb (`relations rebuild`, `resolve`, `ensure`) rather than a missing module |
+
+Only after all four: build it, in the module that owns the concept.
+
+## what "found" actually means
+
+Rarely the exact thing. Four outcomes, each with its own move:
+
+| what you found | the move |
+|---|---|
+| the exact capability, live in this workspace | use it — and if finding it took effort, fix the `description`/`use_when` that made it hard, in the same breath |
+| a recipe covering most of it | propose copy-and-adapt (below). Adoption is deletion |
+| a partial match — a collection that could grow a field, a skill that covers half the job | propose extending the existing thing, in the module that owns the concept. Growing a field on the right collection beats a new collection every time (`data-modeling.md` Part IX: additive first) |
+| a concrete solution in a sibling workspace | read it for shape and traps, rebuild clean with a synthetic cast — never lift records, names, or account details |
+
+## how to propose
+
+Say three things: **what you found**, **what adopting it would cost**, and **what you would delete
+from it**. That last one is not politeness — adoption is mostly deletion, and a proposal that skips
+it is asking the operator to accept a maximal module sight unseen. Name the `.env` keys, external
+accounts and binaries it needs, because a skill whose setup nobody did is a skill that fails at the
+worst possible moment.
+
+The shape, at the size it should be:
+
+> Found: `recipes/clinic` ships `health/lab-values` plus an ingest skill for lab-report PDFs.
+> Cost: one `.env` key (`FILES_FOLDER`), no binaries, ~300 lines of skill prose in every future
+> compile. I would delete: the portal-scraping half (you file PDFs by hand), the `insurers`
+> collection (out of scope here), and its example cast. I would keep: the collection, the
+> one-value-per-record grain, and the dedupe rule — that last one is the part worth having.
+
+Then stop and let them choose. Copying a recipe in is a one-way door in practice: from that moment
+the copy is theirs to maintain, and nothing will later tell them it drifted from the original.
+
+## the one-way doors, named
+
+- **Copying a recipe in** — yours from that moment; drift from the original is silent by design.
+- **Creating a collection** — cheap to make, expensive to retire: records accumulate, references
+  point at it, and deleting it later is a migration, not an undo.
+- **Installing anything** (`npm i`, `git_modules/`) for a domain module — recipes are copied, not
+  installed; importing one re-creates the fork the copy-and-adapt split exists to avoid.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| building because you didn't find it in 30 seconds | there are four places to look, and the first is this workspace |
+| searching only the literal word the operator used | the existing thing is usually filed under a synonym — search the concept, not the string |
+| `npm i` / `git_modules` a recipe module | recipes are copied, not installed — importing re-creates the fork the split exists to avoid |
+| copying a recipe in and keeping all of it | deleting what you won't use IS the adoption step |
+| lifting from another workspace under `projects/` | those hold real personal data; read for reference only |
+| proposing without naming the setup cost | the `.env` keys and the accounts are the actual price |
+| installing or copying, then telling the operator | they decide what enters their workspace, before it enters |
+| finding it, using it, and leaving the bad description in place | the next session will miss it exactly as you just did |

package/skills/using-dreamteamer/references/changes.md

@@ -0,0 +1,55 @@
+# what changed — record events derived from git
+
+**core principle:** record events are never observed live — they are **derived from git
+history**. a closed laptop loses nothing, every derivation is auditable and replayable forever,
+and history IS the queue: there is no events file, and there never should be.
+
+```bash
+dt changes                        # what the last commit changed (--since HEAD~1)
+dt changes --since <sha|YYYY-MM-DD>
+dt changes --json
+```
+
+per record it reports the collection, the id and one of `item-added` / `item-updated` /
+`item-removed`, grouped by collection with counts. **read-only by construction** — no cursor,
+nothing stored, so running it twice is free and running it wrong costs nothing.
+
+## when to use
+
+the operator asks what changed or what they missed; you are reconciling after a batch of edits or
+a bulk rewrite; you want to know what a range of commits did to the *data*. **not for** ordinary
+"show me the diff" questions — plain `git log` / `git diff` is better — not for reading or
+writing individual records (`records.md`), and not for UNCOMMITTED writes: it diffs commits, so
+pending records are invisible to it (`dt commit --dry-run` shows those).
+
+## the mechanism — enough to trust its edges
+
+1. it covers **every repo that holds records**: each compiled descriptor's `storage.path`,
+   grouped per repo (a module can own its records). a changed path that matches no descriptor is
+   **skipped** — source and runtime churn are not data events — and runtime entities never
+   appear.
+2. `--since` takes a sha or a date. a sha is resolved to its commit DATE in the workspace repo
+   (a sha means nothing in another repo), and each repo then resolves that date against its own
+   history; a repo younger than the date reports everything in it as added. ⚠ a bare date is
+   pinned to **midnight** deliberately — git's own approxidate fills missing fields from the
+   current clock, so the same command would answer differently morning and evening (measured).
+3. the git status letter becomes the event: `A` → added, `M` → updated, `D` → removed. **a
+   rename emits removed + added** — there is deliberately no `item-renamed`, because the id IS
+   the path and a moved record is a different record to any consumer.
+
+## if you are ever asked to automate on top of this
+
+this derivation is the surviving half of a removed automation layer (its run-records went unused:
+one workflow, nine runs, seven abandoned, in three days). the lessons it left: **never store an
+event queue** — a queue drifts from reality, history cannot; make every evaluator **idempotent
+over a range** (the old design keyed on `trigger + item + commit` — reuse that shape); and **a
+migration is not a data event** — a bulk rewrite looks like N added records, so scope past it
+rather than run over it.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| hand-rolling the diff + path mapping | `dt changes` is the mechanism; a hand-roll misses folder-shape records, per-repo grouping and the rename split |
+| writing an events file to "remember" what changed | history is the record; anything you write can drift from it |
+| reading the output as a to-do list | it says what changed, not what it means — the judgment is yours |