dreamteamer 0.29.0 → 0.31.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]

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.29.0",
+	"version": "0.31.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

@@ -63,7 +63,11 @@ dispatch, so it cannot drift):
 - read & measure — `list` `get` `values` `history` `diff` `next` `relations` `resolve`
 - write & publish — `add` `set` `rm` `rename` `move` `revert` `commit`
 - 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 +103,15 @@ 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` |
 | 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 +133,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 +146,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/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/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/sessions.md

@@ -6,7 +6,7 @@ refusals that keep that from looping, lying, or carrying private data somewhere
 
 The whole design turns on one asymmetry. Two sessions in the same tree are conflict-BLIND, and so are
 two sessions in one conversation: **the second write wins and nobody is told.** Sessions are
-`worktrees`' twin — observed, never stored, and the registry is the authority rather than anyone's
+git worktrees' twin — observed, never stored, and the registry is the authority rather than anyone's
 memory of it.
 
 | the question | read |
@@ -175,10 +175,9 @@ A coordinator spans repos by construction, and one of them may publish.
    records it may not message a publishing session at all, whatever it means to say. This is what
    keeps rule 1 safe after compaction, when it can no longer recall precisely what it read.
 6. ⚠ **`cwd` is not the repo, and one repo is not one tree.** Harnesses put worktrees *inside* the
-   repo or *under the home directory* depending on the harness (`references/worktrees.md`). A `cwd`
-   under a harness's own worktree root is still that repo and carries its full boundary — so a
-   path-prefix test against the primary root gets it wrong in the dangerous direction. `dt list
-   worktrees` is the instrument.
+   repo or *under the home directory* depending on the harness. A `cwd` under a harness's own
+   worktree root is still that repo and carries its full boundary — so a path-prefix test against
+   the primary root gets it wrong in the dangerous direction. `git worktree list` is the instrument.
 
 ## not stepping on your own toes
 

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

@@ -160,12 +160,10 @@ Skills ship with modules and are read by any operator on any machine:
   renamed verb or a changed limit in a skill sends every future session down the old path
   confidently. When you catch a skill lying, fixing it is part of the task you are on, not a
   follow-up.
-- **Give it a proof, and know what a proof cannot cover.** A `proofs` record (`proofs.md`) pins the
+- **Give it a mechanical check, and know what one cannot cover.** Something must pin the
   mechanical half: the script the skill names runs, the record it promises appears, the path it
-  files to exists. Write it in the same commit — `dt add skills` nudges you with the path the moment
-  it writes the skill (compile's own nudge covers new commands and scripts, never skills), and
-  `dt list proofs --missing` names every artifact nobody claimed anything about. ⚠ **A
-  green proof is not evidence the skill TEACHES.** Whether a fresh session finds it, loads it and
+  files to exists — in a workspace with a proofs extension, that is a `proofs` record, written
+  in the same commit. ⚠ **A green check is not evidence the skill TEACHES.** Whether a fresh session finds it, loads it and
   does the job right is the eval layer: real tasks, blind sessions, a scoring sheet — a procedure,
   never something the engine runs.
 - **Retire what nothing loads.** A skill nobody uses still costs its line in every session's index.

package/src/api.d.ts

@@ -0,0 +1,109 @@
+// The typed contract of `import … from 'dreamteamer'` (src/api.js). It re-exports the record half
+// (`dreamteamer/records`, src/records-api.d.ts) and adds the workspace half. A test pins each runtime
+// export list to its declaration, so a name added to one and not the other fails the suite.
+
+export * from './records-api.js';
+import type { Fields, Descriptor, Descriptors, Manifest, Store } from './records-api.js';
+
+// ---- the workspace and extensions ------------------------------------------------------------------
+
+export interface Workspace {
+	/** absolute path of the workspace root */
+	root: string;
+	/** the workspace package.json */
+	pkg: { name?: string; dependencies?: Record<string, string>; devDependencies?: Record<string, string>; dreamteamer?: Record<string, any>; [k: string]: unknown };
+	/** the ACTIVATED extensions, present on a handle from `openWorkspace` */
+	extensions?: LoadedExtension[];
+}
+
+/** What an extension's `activate(dt)` returns. Every key is optional. */
+export interface Contribution {
+	commands?: Record<string, { usage?: string; run(ws: Workspace, argv: string[]): number | void | Promise<number | void> }>;
+	sourceKinds?: (string | { kind: string; exclude?: string[] })[];
+	analyze?(draft: CompileDraft): { errors?: string[]; warnings?: string[]; notes?: string[] } | void;
+	harnesses?: Record<string, (ctx: HarnessContext) => { blocks?: Record<string, string | null>; summary?: string } | void>;
+	orientation?: string | ((ctx: { entries: Map<string, Entry> }) => string);
+	hooks?: Record<string, string>;
+}
+export type Activate = (dt: typeof import('./api.js')) => Contribution | Promise<Contribution>;
+export interface LoadedExtension {
+	name: string;
+	version: string;
+	commands: NonNullable<Contribution['commands']>;
+	sourceKinds: { kind: string; exclude: string[]; extension: string }[];
+	analyze: Contribution['analyze'] | null;
+	harnesses: NonNullable<Contribution['harnesses']>;
+	orientation: Contribution['orientation'] | null;
+	hooks: Record<string, string>;
+}
+export type Entry = { sources: { path: string; hash: string }[]; bytes: Buffer };
+export interface CompileDraft {
+	/** runtime-relative path → staged entry; read-only */
+	readonly entries: Map<string, Entry>;
+	/** the FINAL merged descriptors */
+	readonly descriptors: Descriptors;
+	readonly modules: { id: string; name: string; root: string; channel: 'inline' | 'git' | 'npm' }[];
+	/** names only — never values */
+	readonly declaredVars: string[];
+	readonly declaredEnv: string[];
+	readonly previousManifest: Manifest | null;
+	/** parse one staged YAML entry, with its source path in any error */
+	parse(runtimePath: string): any;
+}
+export interface HarnessContext {
+	entries: Map<string, Entry>;
+	version: string;
+	collections: { name: string; generated: boolean; systemGroup: boolean; description: string; module: string; sensitive: boolean; sensitiveFields: string[] }[];
+	modules: { id: string; title: string; description: string; path: string }[];
+}
+
+export const EXTENSION_API: 1;
+export function openWorkspace(start?: string): Promise<Workspace & { extensions: LoadedExtension[] }>;
+export function findWorkspace(start?: string): Workspace;
+export function declaredExtensions(ws: Workspace): { name: string; version: string; dir: string; entry: string }[];
+export const engineBin: string;
+export const engineRoot: string;
+
+export function envContext(ws: Workspace): unknown;
+export function renderTemplate(template: string, ctx: unknown): string;
+export function parseEnvValues(text: string): Map<string, string>;
+export function satisfies(version: string, range: string): boolean | null;
+
+// ---- the compiler, schema and module operations --------------------------------------------------
+
+/** throws CompileError on a bad source; prints its summary; returns 0 */
+export function compile(ws: Workspace): 0;
+export function staleness(root: string): { compiled: boolean; stale: string[]; manifest?: Manifest; message?: string };
+export function warnIfStale(root: string): ReturnType<typeof staleness>;
+export function discoverModules(root: string, pkg: Workspace['pkg']): { modules: { name: string; root: string; channel: string }[]; shadows: unknown[]; disabledModules: string[] };
+export class CompileError extends Error {}
+export const KINDS: readonly string[];
+export const MANAGED_BLOCKS: readonly { id: 'orientation' | 'instructions'; begin: string; end: string }[];
+type SchemaOp = (ws: Workspace, store: Store, ...args: any[]) => any;
+export const createCollection: SchemaOp, removeCollection: SchemaOp, renameCollection: SchemaOp, moveCollection: SchemaOp, setCollectionScalars: SchemaOp;
+export const addField: SchemaOp, updateField: SchemaOp, removeField: SchemaOp, removeFieldPlan: SchemaOp, renameField: SchemaOp, renameFieldPlan: SchemaOp;
+export function fieldDef(store: Store, flags: Record<string, unknown>, collection: string): any;
+export function statedKeywords(flags: Record<string, unknown>): any;
+export const saveUiView: SchemaOp, removeUiView: SchemaOp;
+export const createModule: SchemaOp, setModule: SchemaOp, renameModule: SchemaOp, removeModule: SchemaOp;
+export const createSkill: SchemaOp, refuseHandAuthored: SchemaOp, removeEntity: SchemaOp, renameEntity: SchemaOp, setEntityFrontmatter: SchemaOp;
+export function init(opts?: { flags?: Record<string, string> }): 0;
+export function ensureRepo(ws: Workspace, id: string): { path: string; cloned: boolean };
+export function ensureAllRepos(ws: Workspace): { path: string; cloned: boolean }[];
+export function listRepos(ws: Workspace): { id: string; path: string; present: boolean; unresolved?: string }[];
+export function installClone(ws: Workspace, url: string, name?: string): number;
+
+// ---- the checkout -------------------------------------------------------------------------------------
+
+export function describeCheckout(root: string, git?: (args: string[], cwd: string) => string): { root: string; kind: 'primary' | 'linked'; gitDir: string; commonDir: string; primary: string; insideRoot: boolean };
+export function installCommand(ws: Workspace, argv: string[], opts?: { open?: (at: string) => Promise<Workspace> }): Promise<number>;
+export function resolveNpm(execPath?: string, env?: NodeJS.ProcessEnv): string | null;
+export function childEnv(): NodeJS.ProcessEnv;
+export function readHookInput(stdinText: string): { cwd: string | null; name: string | null; raw: Record<string, unknown> };
+export function readStdin(isTTY?: boolean): string;
+
+// ---- CLI helpers ------------------------------------------------------------------------------------------
+
+/** write `text` plus a trailing newline, synchronously, looping on short writes — safe before process.exit */
+export function emit(text: string, fd?: number): void;
+export function parseArgs(argv: string[]): { flags: Record<string, string | boolean | string[]>; pos: string[] };