dreamteamer 0.30.0 → 0.32.0

package/README.md

@@ -1,14 +1,24 @@
 # dreamteamer
 
-**Structured, modular memory for coding agents.**
+**dreamteamer is a modular AI workspace builder.**
 
-Your agent already has a memory. You just can't see it — it's prose, in a black box somewhere,
-untracked and unshared. And memory *is* context, which is the single biggest lever on what your agent
-decides and how well it does it. So the most consequential thing in your setup is the one you have the
-least access to.
+It gives your coding agents a structured, modular memory. Instead of hiding context in unmanaged prose, dreamteamer stores memory as **plain markdown files with a schema** directly in your git repo. Agents read it natively, and you can browse it as tables, boards, and forms.
 
-dreamteamer makes it **files with a schema**: plain markdown in your git repo that your agent reads
-natively, and that you can browse as tables, boards and forms.
+No server, no account, no telemetry. Just a lightweight npm package.
+
+---
+
+## Features
+
+- **Structured Memory as Files**: A record is just a markdown file with YAML frontmatter. Your agent opens it like any other file.
+- **Strict Validation**: Schemas ensure your agents use agreed-upon terminology. Invalid links, wrong types, or unknown fields are rejected before they touch the disk.
+- **Agent Agnostic**: Author a skill or schema once, use it everywhere. Core compiles to Claude Code, Cursor, Gemini CLI, and more.
+- **NPM Modularity**: Distribute domain knowledge, skills, and agents using the npm ecosystem you already know. 
+- **Visual Editor**: The [VS Code extension](https://github.com/dreamteamer/dreamteamer-vscode) gives you a powerful UI (tables, boards, forms) over your plain text files.
+
+## Getting Started
+
+Scaffold your AI workspace in seconds:
 
 ```bash
 npm i dreamteamer
@@ -18,15 +28,10 @@ npx dreamteamer check     # prove every record and every link is intact
 npx dreamteamer help      # the full command surface
 ```
 
-Apache-2.0. No server, no account, no telemetry.
+## How It Works
 
-## Structured
-
-A record is a file. That's the whole trick.
-
-```
-data/meetings/2026/07/kickoff.meeting.md
-```
+### 1. Define Records
+A record is a file inside your collection directory (e.g., `data/meetings/2026/07/kickoff.meeting.md`):
 
 ```yaml
 ---
@@ -38,160 +43,49 @@ project: projects/apollo
 Ada walked through the constraints. Lin owns the spec by Friday.
 ```
 
-Your agent opens that file the way it opens any file. Nothing is intercepted, nothing is proxied,
-there is no API to learn.
-
-But `attendees` isn't a string — it's a link. `dreamteamer check` proves every one of them resolves,
-and renaming `contacts/ada` updates everything pointing at it. A write with an unknown field, a wrong
-type, or a reference to a record that doesn't exist is **rejected before it touches disk**.
-
-**A schema is an agreement about what things are called.** Shared terminology with guardrails — not a
-cage, because it stays negotiable. You change it by saying so:
-
-> *"From here on a client has a renewal date, and it's a date."*
-
-That's a schema update and a data migration, and it's an **explicit, reviewable event** rather than
-silent drift. Once it exists you get the column in a table, the field in a form, validation, sorting
-and aggregation — all of it falling out of having said what the thing is.
-
-The shape of a record is deliberately dull, because dull is what survives:
-
-- records are `<id>.<suffix>.<ext>` files; **the id is the path** inside the collection folder
-- references are `<collection>/<id>` — always qualified, greppable, never a bare name
-- a collection may be scoped under a **declared namespace** — `health/doctors/dana-levi`, stored in
-  `data/health/doctors/`. The default namespace is the empty prefix, so `tasks/kickoff` is unchanged
-- a write lands on disk; `dreamteamer commit` publishes it, one commit per repo
-- schemas are JSON Schema in a YAML file, one per collection
-
-### Machine-specific references
-
-Some things a record points at only exist on one machine — a synced Drive folder, an external disk,
-a checkout somewhere else. Those are written as **templates**, never as absolute paths:
-
-```yaml
-source_file: ${env:FILES_FOLDER}/2026/q3.pdf
-```
-
-Three variables, borrowing VS Code's grammar: `${env:NAME}` — declared in `dreamteamer.vars` in
-`package.json`, valued in the gitignored `.env` (an empty or whitespace-only value counts as no
-value at all) — plus `${workspaceFolder}` and `${userHome}`. One verb renders them:
+### 2. Enforce Schemas
+Your agents read the file directly, but `dreamteamer check` ensures that every reference (like `contacts/ada`) actually resolves. **A schema is an agreement about what things are called.**
 
-```bash
-npx dreamteamer resolve '${env:FILES_FOLDER}/x'            # → /Volumes/annex/x
-npx dreamteamer resolve <collection>/<id> <field>          # render what a record already holds
-```
-
-**Templates are ordinary data — write them literally; nothing substitutes until `resolve` is
-called.** `get`, `list`, `check` and every harness see the template verbatim, which is exactly what
-makes the record mean the same thing on every machine instead of quietly meaning two things. An
-undeclared key and a declared-but-absent one are different errors, and `compile` warns — by name,
-never by value — when a declared var has nothing behind it here.
+### 3. Share & Compose
+Because dreamteamer uses npm, you can install domain modules containing collections, skills, and agents. If a module doesn't perfectly fit your needs, you don't fork it—you adapt it locally by overriding just the schema fields you need to change.
 
-## Modular
+## Programmatic Usage
 
-**Data and skills are the new app structure.** A coding agent with the right skills over the right
-data is arbitrary functionality — but composing that with no module system is where most setups stall.
+Use dreamteamer in your own scripts or apps:
 
-So dreamteamer doesn't invent one. **It uses npm.**
+```javascript
+import { openWorkspace, Store } from 'dreamteamer';
 
-`node_modules` is battle-tested, universally adopted, and already sitting in nearly every
-coding-agent setup. A module contributes collections, skills, agents, commands, command-bindings and
-UI views — and skills and agents are treated as exactly what they are: **memory that loads into
-context**, living in the same module structure as everything else, in a standard your tooling already
-understands.
+const ws = await openWorkspace('.');        // no compile, no writes
+const store = new Store(ws);
 
-Three channels, one shape:
-
-```
-modules/<name>/        # lives in this repo
-git_modules/<name>/    # lives in its own repo
-node_modules/<name>/   # published package
+for (const { id, fields } of store.readAll('notes')) {
+  console.log(id, fields.title);
+}
 ```
 
-Precedence runs top to bottom, so a local copy shadows a published one — which is how you develop a
-module and use it in the same workspace at the same time.
-
-A published package or a git clone may carry **several** modules: when its root has a `modules/`
-folder, each `modules/<name>/` with a `dreamteamer` key in its `package.json` is a module on that
-channel, and the root itself is never compiled. One `npm install` then delivers a whole family, and the
-workspace keeps what it wants — a bare module name in `dreamteamer.disable` drops a module before
-compile looks at it (an entry with a slash, `<module>/<entity>`, still disables one entity):
-
-```json
-"dreamteamer": { "disable": ["recordings", "introspection"] }
-```
-
-Disabling a module another one declares in `dependencies` is refused, naming what is present. The
-workspace's own `modules/*` never nest.
-
-Sources live **flat at a module root** — `modules/crm/skills/`, beside `package.json` — and a folder
-at a module root that isn't a known kind is a compile error rather than a silent skip.
-
-### Modules are not rigid
-
-This is the part that differs from npm on purpose.
-
-Installing a module into a workspace that already has opinions — its own idea of what a `contact` is —
-is a **negotiation, not an overwrite**. Four workspaces wanted a CRM and all four wanted a different
-`contacts`. A hard import would force one answer and make every divergence a fork.
-
-Two same-name collections is a compile error that names both descriptors and tells you the move:
-declare `extends: <module>/<collection>` and overlay only what differs. Because every schema is one
-small YAML file, adapting is cheap — read it, change what doesn't fit, and the diff shows exactly what
-you agreed to.
-
-So domain modules are **recipes you copy and adapt, not packages you install**, and divergence is the
-normal case rather than a failure.
-
-## Every harness, one source
-
-`compile` writes `.dreamteamer/` — the single runtime read surface — and from there into per-harness
-adapters: Claude Code, Codex, Pi, Gemini CLI, Cursor. Author a skill once; every agent you run sees it.
-
-## The editor
-
-Extension id `dreamteamer.dreamteamer-vscode` (Marketplace · Open VSX). `init` and `compile` write the
-`.vscode/extensions.json` recommendation, and `dt status` reports whether it is active.
-
-[dreamteamer-vscode](https://github.com/dreamteamer/dreamteamer-vscode) gives you tables, boards,
-calendars, maps, forms and a data-model designer over the same files — and it loads **the engine your
-workspace pins**, so the editor, the CLI and any agent session are provably running the same code.
-
-## Docs
-
-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:
+## Extensions
 
-- [`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
-  namespace (`health/doctors`), what it costs consumers, and why the default namespace is transparent
-- [`UPDATING.md`](UPDATING.md) — what to do when upgrading, one section per release
+An extension adds verbs, source kinds or harnesses through one contract
+([`references/extensions.md`](skills/using-dreamteamer/references/extensions.md)). It can be a
+workspace module (`modules/<id>/package.json` declaring `dreamteamer.extension`) or an installed
+dependency.
 
-## What it isn't
+Behaviour proofs, worktrees, the REST API, the NotebookLM exporter and the local Docker host left core
+in 0.31.0 and return as extensions. None is published yet.
 
-Not a database — records are files and git is the history. Not a cloud service — there is no server
-and no account. Not a note-taking app — it's the layer underneath one.
+## Agent-Native Documentation
 
-And it is **not** for data that needs row-level access control, field-level encryption, or provable
-erasure. Git cannot do those, and pretending otherwise is how people get hurt. This is for
-human-scale structured knowledge: thousands of records, not millions.
+Because this is an agent-native tool, documentation is shipped as skills your agent loads on demand:
+- [`skills/using-dreamteamer`](skills/using-dreamteamer) — Core skill for working with records and modeling the workspace.
+- [`docs/`](docs/) — Deeper architectural context, upgrade guides, and rationale.
 
 ## Contributing
 
-Issues are welcome. For anything larger than a typo, please open a discussion before a pull request —
-this is a small, deliberately lean codebase (`npm run metrics` enforces size budgets), and it's better
-to agree on the shape first.
+We welcome issues and discussions! For anything larger than a typo, please open a discussion before submitting a PR. This is a deliberately lean codebase and we prefer to agree on shape first. `npm run verify` enforces our size and test budgets. 
 
-`npm run verify` is the gate: import-layer direction, size budgets, and the test suite (tiers 1+2,
-zero dependencies, a few seconds). See [CONTRIBUTING.md](CONTRIBUTING.md).
+See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
 ## License
 
-Apache-2.0 © 2026 Gilad Khen. See [LICENSE](LICENSE).
+[Apache-2.0](LICENSE) © 2026 Gilad Khen.

package/collections/collections.collection.yaml

@@ -67,15 +67,6 @@ schema:
             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.
-        driver:
-          type: string
-          description: >-
-            The name of an engine DRIVER that answers this collection's verbs instead of a folder of
-            files — `docker` is the one shipped (src/containers.js: `containers`, `images`). A driver
-            collection has no records on disk: its derived `path` names a folder that never exists,
-            so check, commit and the store read zero records and never write one; the CLI and the REST
-            route dispatch to the driver first. A string checked against the drivers the engine has,
-            not an enum — one implementation, and a second is a code change, not a vocabulary change.
         codec:
           type: string
           enum: [md, yaml, json, file]
@@ -100,6 +91,32 @@ schema:
         entry:
           type: string
           description: Folder shapes only — the file inside the folder that IS the record (e.g. SKILL.md).
+        under:
+          type: object
+          description: >-
+            RELATIONSHIP-BASED STORAGE — records live INSIDE the folder of the record they belong
+            to. `{ field: company, path: meetings }` puts a meeting whose `company` is
+            `companies/northwind` at `<companies root>/northwind/meetings/<id>.meeting.md`; one with
+            no `company` stays in this collection's own `path`, which remains its fallback root.
+            Still ONE logical collection: `list` is the union across every parent folder, a
+            reference is `<collection>/<id>` wherever the file sits, and the id never changes when
+            the owner does — `set <field>=…` MOVES the file. `field` must be a scalar `x-reference`
+            to exactly one collection, that collection must be `shape: folder`, and one level is
+            supported (a placed collection cannot be a parent). The field is the intended owner and
+            the folder is observed placement: `check` reports a disagreement, `dreamteamer relocate`
+            reconciles it, nothing infers an owner from where a file was found. Not for a record
+            many parents share equally — that is a plain reference.
+          required: [field, path]
+          properties:
+            field:
+              type: string
+              description: The scalar reference field on THIS collection that names the parent record.
+            path:
+              type: string
+              description: The folder INSIDE each parent record's folder that holds these records — relative, e.g. `meetings`.
+            collection:
+              type: string
+              description: DERIVED by compile, never authored — the parent collection, read off `field`'s x-reference so the record layer never opens a schema to find it.
         repo:
           type: string
           description: DERIVED by compile, never authored — the workspace-relative root of the git repo holding these records ('.' is the workspace). Set from the owning module's `owns-data`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.30.0",
+	"version": "0.32.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>",
@@ -28,6 +28,19 @@
 	"engines": {
 		"node": ">=20"
 	},
+	"main": "./src/api.js",
+	"types": "./src/api.d.ts",
+	"exports": {
+		".": {
+			"types": "./src/api.d.ts",
+			"default": "./src/api.js"
+		},
+		"./records": {
+			"types": "./src/records-api.d.ts",
+			"default": "./src/records-api.js"
+		},
+		"./package.json": "./package.json"
+	},
 	"bin": {
 		"dreamteamer": "bin/dreamteamer.js",
 		"dt": "bin/dreamteamer.js"
@@ -47,7 +60,6 @@
 	"dependencies": {
 		"ajv": "^8.17.1",
 		"ajv-formats": "^3.0.1",
-		"express": "^5.2.1",
 		"fractional-indexing": "^4.0.0",
 		"js-yaml": "^4.1.0",
 		"yaml": "2.8.4"

package/skills/using-dreamteamer/SKILL.md

@@ -30,7 +30,10 @@ unsure which skill owns the job in front of you.
 
 - 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`.
+  `data/meetings/2026/07/standup.meeting.md` ⇒ id `2026/07/standup`. a collection may instead keep
+  its records INSIDE the folder of the record they belong to (`storage.under` — a company's
+  meetings in `data/companies/<company>/meetings/`): still ONE collection, the same id, the same
+  `meetings/<id>` reference; only the folder follows the owner field (`references/collections.md`).
 - **references are `<collection>/<id>`** strings — always qualified, greppable, never a bare name
   and never a file path.
 
@@ -61,9 +64,13 @@ dispatch, so it cannot drift):
 
 - a collection may be spelled in the SINGULAR on any of these (`dt add task "call the bank"` — one bare positional is the title); references inside records still spell the full name
 - read & measure — `list` `get` `values` `history` `diff` `next` `relations` `resolve`
-- write & publish — `add` `set` `rm` `rename` `move` `revert` `commit`
+- write & publish — `add` `set` `rm` `rename` `move` `revert` `commit` `relocate`
 - fields (sources, through the compile gate) — `add-field` `set-field` `rm-field` `rename-field` (system entities — modules, collections, skills, ui-views… — take the RECORD verbs above)
-- workspace — `init` `install` `land` `update` `compile` `check` `prove` `status` `start` `changes` `export` `help`
+- workspace — `init` `install` `update` `compile` `check` `status` `changes` `help`
+- an EXTENSION (a workspace module or a dependency declaring `dreamteamer.extension`) adds verbs of
+  its own, and `dt help` lists them under its name; each ships the skill that teaches it. A verb that
+  answers "left core in 0.31.0" (`dt prove` · `dt land` · `dt worktree` · `dt serve` · `dt notebooklm` · the Docker
+  host) has no published extension yet — see `references/extensions.md`.
 
 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.
@@ -99,17 +106,16 @@ Load by the map; nothing here is loaded "just in case".
 | a brand-new or empty workspace, dreamteamer over an existing pile of files, "help me set this up" | `references/getting-started.md` |
 | read, create, update, rename, delete, commit — or UNDO — a record | `references/records.md` |
 | "what changed while I was away" | `references/changes.md` |
-| the workspace has to reach a reader that is not a coding agent — a NotebookLM notebook; "which fields are sensitive" | `references/exporting.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 system and field verbs, `templates:`/`extends:`, a compile or check message | `references/collections.md` |
+| "keep a company's meetings in the company's folder" — records stored beside the record they belong to, a `placed … but` check report, `dt relocate` | `references/collections.md` (declaring it) · `references/records.md` (working with it) |
 | 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` |
-| "how would anyone know this still works?" — a proof of a skill, a command or a script, and the exit code `dt prove` answers with | `references/proofs.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` |
-| a second checkout — making one ready, landing its records, a harness that cuts them for you | `references/worktrees.md` |
+| an optional tool — behaviour proofs, worktrees, a REST server, an exporter, a new harness — and whether to write one | `references/extensions.md` |
 | other agent sessions are running on this machine — finding them, messaging one, coordinating several, and what may not cross between them | `references/sessions.md` |
 
 three act-two tie-breakers, because they are the ones that go wrong:
@@ -131,7 +137,8 @@ workspace's decision log (where one exists) wins over older documents.
 ## system entities take the RECORD verbs
 
 Modules, collections, skills, agents, commands, command-bindings, ui-views, collection-templates
-and proofs are collections in the runtime, and since 0.19.0 the ordinary verbs write them:
+— and any kind an installed extension contributes — are collections in the runtime, and since
+0.19.0 the ordinary verbs write them:
 
 ```
 dt add modules --name core --description "The shared nouns."
@@ -143,9 +150,8 @@ dt set modules/hr namespaces=hr dependencies=modules/core
 dt rm modules/hr --force                     # --dry-run first; it prints its plan
 ```
 
-⚠ **`proofs` is the one exception, and only to `add`:** a proof is hand-authored like a skill or a
-command, so `dt add proofs` is refused, naming the file to write
-(`modules/<module>/proofs/<id>.proof.yaml`, `references/proofs.md`). Every other verb works on it.
+⚠ **`add` scaffolds skills only.** Agents, commands, bindings, templates and contributed kinds are
+hand-authored — `dt add agents` is refused, naming the file to write. Every other verb works on them.
 
 `dt schema <op>` is **gone** since 0.19.0 and fails with the translation printed. `UPDATING.md` has
 the complete mapping table.

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

@@ -49,9 +49,10 @@ Only after all four: build it, in the module that owns the concept.
 
 ## name the proof before you build it
 
-**Before writing the thing, say how anyone would know it works** — one sentence, in the shape a
-`proofs` record takes: *this record, in this state, after this step, must look like this*
-(`proofs.md`). It costs a minute and it is the cheapest design review there is.
+**Before writing the thing, say how anyone would know it works** — one sentence: *this record, in
+this state, after this step, must look like this*. It costs a minute and it is the cheapest design
+review there is. (With a proofs extension installed, that sentence is exactly the shape of a
+`proofs` record, and `dt prove` runs it — its own skill says how.)
 
 ⚠ **When you cannot name one, the artifact has no observable post-state, and THAT is the first
 thing to change** — not something to note and carry on past. A skill nothing can check is a skill

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

@@ -172,7 +172,77 @@ is copied.
 - Nested namespaces work (`work/clients`); the longest declared prefix wins.
 - ⚠ **No collection may store records inside another's folder** — a namespace folder cannot
   itself be a collection root. Compile refuses it, because the outer collection would index the
-  inner one's records as its own.
+  inner one's records as its own. The one DECLARED exception is the next section: a collection
+  stored under the records of a folder-shape parent, where compile knows exactly which files
+  belong to whom.
+
+## relationship-based storage — records beside the record they belong to
+
+A collection can keep each record INSIDE the folder of the record it belongs to, so a company's
+folder holds the company's meetings and a browse of `data/companies/northwind/` shows the whole
+account. It is declared on the CHILD's `storage`, in one line, and changes nothing about what the
+collection IS:
+
+```yaml
+# modules/default/collections/meetings.collection.yaml
+storage: { path: data/meetings, suffix: meeting, under: { field: company, path: meetings } }
+```
+
+```text
+data/companies/northwind/company.md                            ← the parent: shape: folder, entry: company.md
+data/companies/northwind/meetings/2026/10/kickoff.meeting.md   ← meetings/2026/10/kickoff, company: companies/northwind
+data/meetings/2026/10/offsite.meeting.md                       ← meetings/2026/10/offsite, no company: the FALLBACK root
+```
+
+- **Still one logical collection.** `dt list meetings` is the union across every company folder
+  and the fallback root, ordered by id; `dt get meetings/2026/10/kickoff` finds the file wherever it
+  sits; a reference is `meetings/<id>` everywhere. Nothing is spelled per company — no descriptor,
+  no skill, no view.
+- **The id is independent of placement.** `dt set meetings/<id> company=companies/harbor` MOVES
+  the file into Harbor's folder and changes nothing else: not the id, not one inbound reference.
+  Clearing the field moves it back to the fallback root. An id is unique across every root, and a
+  second file claiming one is a `check` violation and a write refusal, never last-one-wins.
+- **`field`** is a scalar `x-reference` to exactly ONE collection (a list has no single folder; a
+  union has no single parent). **`path`** is a relative folder inside each parent record's folder.
+  compile derives `under.collection` from the field; nothing else is authored.
+- **The parent must be `shape: folder`** (`storage: { shape: folder, entry: company.md }`) — only
+  a folder can hold anything beside the record. A file-shape collection that should become a
+  parent changes its descriptor to folder shape, and `dt relocate <collection>` then moves each
+  `<id>.<suffix>.md` into `<id>/<entry>` with its id unchanged (`check` names them until it runs).
+- **One level.** A placed collection cannot itself be a parent; the child is a text record
+  (`md` · `yaml` · `json`, file shape) — an opaque or folder-shape child is refused for now. Two
+  children of one parent need two different paths, and a path never equals the parent's entry.
+- **The field is the owner; the folder is observed placement.** A file found under the wrong
+  company — moved by hand, or sitting in the fallback root from before the declaration existed — is
+  `placed under … but <field> is …` in `check`, which changes nothing. `dt relocate <collection>`
+  (or `<collection>/<id>`, `--dry-run` first) moves files to where the compiled descriptor puts
+  them and refuses a source with unpublished changes or an occupied destination. Editing some OTHER
+  field never relocates as a side effect; nothing ever infers an owner from where a file was found.
+- **A parent with records inside its folder cannot be removed** — not with `--force` either;
+  reassign or clear their owner first. Renaming the parent carries the folder with everything in
+  it and rewrites the children's owner field; their ids do not change.
+- **Adopting it on existing data is three explicit steps**, each reviewable: make the parent folder
+  shape and `relocate` it; add `under` to the child and compile (no file moves at compile — `check`
+  reports every mismatch); `relocate` the child, `--dry-run` first. `dt commit` stages a moved
+  record's old and new path together; `dt revert` of an owner change moves the file back.
+- **Removing or changing `under` is the same walk backwards, and compile holds the door.** While
+  records still sit inside parent folders, a compile that drops the declaration, changes its
+  `path`, or moves the PARENT collection's `storage.path` is REFUSED — the new descriptor would stop
+  every reader seeing them. The order is
+  `dt relocate <collection> --to-root` (every placed record back into the collection's own folder,
+  ids unchanged, under the still-current declaration) → edit the descriptor → compile → `dt relocate
+  <collection>` to place them under the new path. The same order renames a placed collection.
+- **`relocate` refuses before it moves anything**: a dangling or malformed owner field (fix the
+  field first — it never makes a folder for a parent that does not exist), an occupied destination,
+  a source with unpublished changes, or a destination behind a symlink. One problem refuses the
+  whole plan; `--dry-run` reports it.
+- **Inside a parent's folder, only real entries count.** A symlink at a child root, on the way to
+  one, or anywhere beneath one — a folder or a file — is never written through and never read as a
+  record; `check` names it. The collection's own roots (`data/`, `storage.path`) are not subject to
+  this; the rule is about what a record folder may contain.
+- **When NOT to use it.** A record several parents share equally, a record whose owner is usually
+  unknown, or a collection nobody browses as a folder — keep conventional storage and a plain
+  reference. Folder grouping is a browsing convenience, never a permission boundary.
 
 ## `templates:` — a live shared field set
 

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

@@ -151,11 +151,11 @@ they read stay honest:
   `{ summary: { _nempty: true } }` works the moment `summary` is a mirror — or ship the binding
   without a `can-exit` and accept that it never shows done. What is not honest is a proxy field a
   human must remember to set.
-- **A `can-exit` and a proof's `count` answer different questions — put each expectation on its own
-  side.** A gate is a filter over ONE record, evaluated on every render of `dt next` and every board
+- **A `can-exit` and a proof's `count` (a proofs extension) answer different questions — put
+  each expectation on its own side.** A gate is a filter over ONE record, evaluated on every render of `dt next` and every board
   the studio draws, so it can only ever read that record's own fields (plus one outbound hop) — which
   is exactly the gap the bullet above names: "a summary referencing this record exists" is
-  inexpressible there. A **proof** (`proofs.md`) is evaluated on demand and is collection-scoped, so
+  inexpressible there. A **proof** is evaluated on demand and is collection-scoped, so
   it says the thing a gate cannot: `{ collection: summaries, where: { about: { _eq: '{record}' } },
   count: { _delta: 1 } }` — *running this command left one more summary behind*. (`{record}` inside a
   proof's `where` is SUBSTITUTED with the picked record's reference before the filter runs, which is

package/skills/using-dreamteamer/references/data-modeling.md

@@ -300,7 +300,15 @@ roadmap, not a model; wait for the second consumer.
   `max_bytes` (default 200 KB). A big binary is not a record: it lives outside the vault under a
   declared var, with an ordinary record carrying the `${env:...}` template that points at it.
 - **`shape: folder` when a record is intrinsically several files** (a skill with references beside
-  it). Rare; prefer one file until the record itself demands companions.
+  it), or when OTHER collections' records should live inside it — see the next bullet. Otherwise
+  prefer one file until the record itself demands companions.
+- **`storage.under` when people browse a parent as a unit** — a company folder holding that
+  company's meetings, a case folder holding its documents. It is one line on the CHILD
+  (`under: { field: company, path: meetings }`), the collection stays ONE collection with the same
+  ids and references, and the owner field is what moves a file (`collections.md`). Choose ONE
+  physical owner and leave every other relationship a plain reference; keep conventional storage
+  when no single owner is sensible, when the owner is usually unknown, or when nobody would open
+  the folder. It organises files; it grants nothing.
 - **Machine-specific paths are templates, never absolute paths.** `${env:FILES_FOLDER}/…` is inert
   data rendered per machine by `dt resolve`; an absolute path in a record is wrong on every other
   machine, silently. **A files folder is named after the collection or field that indexes it, and

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

@@ -0,0 +1,60 @@
+# extensions — optional tools, and the one seam they plug into
+
+Core is records plus the workspace compiler. Anything with a lifecycle of its own — a server, a
+Docker host, a behaviour-test runner, an exporter to one vendor — is an **extension**: code the engine
+calls, which a workspace has when it wants that capability and does without otherwise.
+
+The verbs that left core in 0.31.0 — `prove` · `land` · `worktree`, `serve`, `notebooklm`, and the
+Docker host — return as extensions, and **none is published yet**. Typed against core, each fails with
+exit 2 and says so. A workspace that needs one now carries it as its own module (below), or stays on
+0.30.x.
+
+`dt status` lists the extensions this workspace loaded, and `dt help` appends each one's usage.
+
+## how a workspace turns one on
+
+Two places, one declaration — a `package.json` carrying `"dreamteamer": { "extension": "./entry.js" }`:
+
+- **a workspace module**, `modules/<id>/package.json`. Its code is the workspace's own, like `bin/`,
+  so it needs no package and no npm. This is how a workspace carries an extension nobody has
+  published, and it shadows a dependency of the same name.
+- **a direct dependency.** npm put the code there on purpose; a transitive package is never loaded
+  however it advertises.
+
+A bare entry in `dreamteamer.disable` switches one off while leaving it in place. Two extensions
+claiming the same verb, source kind or harness is a refusal at load, naming both — never "last one
+wins".
+
+An extension is ALSO a content module (its `dreamteamer` key makes it one): its collections and skills
+travel with its code, and compile discovers them like any other module's.
+
+⚠ **Remove an extension and its kind goes with it.** A workspace holding `proofs/` folders with no
+extension contributing `proofs` fails compile on the unknown folder — deliberately: a proof that
+compiles with no validator would be a claim nothing checks. The next compile after a removal also
+prunes the extension's compiled folder and its managed blocks.
+
+## writing one — the contract
+
+The entry's default export is `activate(dt)`. `dt` is the RUNNING engine's public API
+(`import('dreamteamer')`'s namespace), so the extension never imports an engine of its own and can
+never disagree with the one the operator ran. It returns a contribution; every key is optional:
+
+| key | shape | what core does with it |
+|---|---|---|
+| `commands` | `{ <verb>: { usage, run(ws, argv) } }` | `dt <verb> …` runs it in-process with the opened workspace; the return is the exit code |
+| `sourceKinds` | `[{ kind, exclude?: [subtree] }]` | compile stages `<module>/<kind>/` like a built-in kind; `exclude` keeps fixtures out |
+| `analyze` | `(draft) → { errors?, warnings?, notes? }` | runs after assembly, before any output is replaced; an error fails the compile (and every schema write, which compiles) |
+| `harnesses` | `{ <id>: (ctx) → { blocks: { <file>: text }, summary } }` | a harness adapter writing managed blocks into user-owned files |
+| `orientation` | a string | one paragraph appended to every orientation block |
+| `hooks` | `{ <ClaudeHookEvent>: '<dt verb args>' }` | merged into `dt install --print-adapters` |
+
+The `draft` is data only: the staged entries, the final merged descriptors, the modules, declared var
+and env key NAMES, and the previous manifest. No writer, no Store, no environment values — an analysis
+that needs one is a command, not an analysis.
+
+## a module, or an extension?
+
+A **module** ships collections, skills, commands, agents, views and UI code — content. An
+**extension** ships code the engine calls. Reach for an extension only when the capability needs one
+of the contribution keys above; everything else is a module, and a module is copied and adapted per
+workspace rather than installed (`references/before-you-build.md`).

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

@@ -111,6 +111,23 @@ first slash. the default namespace has no prefix (`tasks/kickoff`, exactly as al
 undeclared prefix reads as a nested id and dangles — `dt check` says so. declaring one is
 `collections.md`.
 
+## records stored under another record — the folder follows the owner
+
+a collection may declare `storage.under` (`collections.md`): a meeting with a `company` lives in
+that company's folder, one without stays in `data/meetings/`. working with it is unchanged in
+every way that names a record — `list` is the whole collection, `get`/`set`/`rm`/`rename` take
+`meetings/<id>` wherever the file sits, references never carry a folder — and different in one:
+**the owner field moves the file.** `dt set meetings/<id> company=companies/harbor` relocates the
+record into Harbor's folder with the same id and every inbound reference intact; `company=`
+moves it back to the fallback root. so never `mv` one by hand, exactly as for a rename — a file
+under the wrong company is what `check` reports as `placed under … but`, and `dt relocate
+<collection>[/<id>]` (`--dry-run` first) is what moves it to where its field says — refusing whole
+when an owner field dangles, a destination is taken or a source is unpublished. a parent
+holding records in its folder refuses `rm` until they are reassigned; `dt commit <collection>/<id>`
+after a move publishes both paths; `dt revert` of an owner change moves the file back too. before
+the declaration is removed or its path changed: `dt relocate <collection> --to-root`
+(`collections.md` has the order — compile refuses the edit while records would be stranded).
+
 ## two-way relations — the mirror is generated, and read-only
 
 a reference field may declare `x-inverse`: compile GENERATES the field it names on the TARGET