dreamteamer 0.20.0 → 0.22.0

package/bin/dt-hook.sh

@@ -0,0 +1,54 @@
+#!/bin/sh
+# dt-hook.sh — run the engine from a harness hook, where there is no PATH to speak of.
+#
+# ⚠ THIS FILE EXISTS BECAUSE OF A MEASUREMENT, not a worry. A harness hook is `sh -c`, and `sh`
+# reads NO startup file — not .zshenv, not .bash_profile, not .bashrc. On the machine where the
+# first live worktree spawn was watched:
+#
+#     env -i zsh -c 'command -v node'   ->  ~/.nvm/versions/node/<v>/bin/node
+#     env -i sh  -c 'command -v node'   ->  NOT FOUND
+#
+# So a hook line beginning with a bare `npm`, `npx` or `node` fails, and fails SILENTLY: a fresh
+# worktree has no node_modules either, so there is nothing to fall back to, and a hook's stderr goes
+# to a log the session never reads. A shell-profile fix cannot reach this (`bash -c` and `sh -c`
+# were both measured failing after one was applied) and would not travel with the workspace anyway.
+# Hence an absolute resolution, here, in the one language a hook is guaranteed to have.
+#
+#   sh /path/to/dt-hook.sh <verb> [args...]
+#
+# Resolution order: $DREAMTEAMER_NODE · node on PATH · the highest ~/.nvm install · /opt/homebrew ·
+# /usr/local. The last two are where the two common non-nvm installers put it.
+set -eu
+
+node=""
+if [ -n "${DREAMTEAMER_NODE:-}" ] && [ -x "${DREAMTEAMER_NODE}" ]; then
+	node="${DREAMTEAMER_NODE}"
+elif command -v node >/dev/null 2>&1; then
+	node="$(command -v node)"
+else
+	# `sort -V`, never a plain sort: v9.9.9 sorts AFTER v10.10.0 lexicographically, which would hand
+	# every hook the oldest install on the disk. A glob that matches nothing expands to itself, so
+	# the whole pipeline is allowed to come back empty rather than being trusted — and EVERY stage
+	# of it is silenced, because `-V` is not in POSIX and a sort that lacks it would otherwise write
+	# a usage error into the one stream a hook must leave clean.
+	nvm=""
+	if [ -n "${HOME:-}" ]; then
+		nvm="$(ls -d "${HOME}"/.nvm/versions/node/*/bin/node 2>/dev/null | sort -V 2>/dev/null | tail -1 2>/dev/null)" || nvm=""
+	fi
+	for candidate in "${nvm}" /opt/homebrew/bin/node /usr/local/bin/node; do
+		if [ -n "${candidate}" ] && [ -x "${candidate}" ]; then
+			node="${candidate}"
+			break
+		fi
+	done
+fi
+
+# ⚠ STDOUT, NOT STDERR, and that is the whole point of failing loudly here: a hook's stdout is added
+# to the session's context, so this line is read by the agent that is about to work in a checkout
+# nothing has made ready. Its stderr is not.
+if [ -z "${node}" ]; then
+	echo "✖ dreamteamer hook: node not found — set DREAMTEAMER_NODE=/path/to/node in the harness environment, or install node under ~/.nvm, /opt/homebrew or /usr/local"
+	exit 1
+fi
+
+exec "${node}" "$(dirname "$0")/dreamteamer.js" "$@"

package/collections/collections.collection.yaml

@@ -120,6 +120,15 @@ schema:
         opened on its own. It is stated here as DATA precisely so the record layer never has to
         learn what a module is; a bare string list rather than `x-reference: collections`, because
         the whole point is that the target is absent.
+    sensitive:
+      type: boolean
+      description: >-
+        This collection's records must not leave the workspace through an export — `dt export
+        <target>` writes none of them and names the omission in what it does write (the schema
+        source, the persona), so a reader knows the gap is deliberate. Set with `dt set
+        collections/<c> sensitive=true`. For ONE field rather than the collection, mark the field:
+        `x-sensitive: true` on its property (`dt add-field … --sensitive`). Nothing is inferred
+        from a name — the mark is the decision.
     module:
       type: string
       description: >-

package/collections/command-bindings.collection.yaml

@@ -19,7 +19,7 @@ schema:
     collection:
       type: string
       x-reference: collections
-      description: The collection the command applies TO — which is what makes `dt commands for <ref>` able to answer "what can I do with this record".
+      description: The collection the command applies TO — which is what makes `dt next <ref>` able to answer "what can I do with this record".
     target:
       type: string
       enum:

package/collections/proofs.collection.yaml

@@ -0,0 +1,96 @@
+name: proofs
+storage:
+  path: proofs
+  codec: yaml
+  shape: file
+  suffix: proof
+id:
+  generate: '{{ name | slug }}'
+schema:
+  type: object
+  required:
+    - name
+    - about
+    - kind
+  properties:
+    name:
+      type: string
+      description: The proof id — must equal the filename.
+    about:
+      type: array
+      items:
+        type: string
+      description: What this proof is ABOUT — one or more artifact refs it proves something about. An artifact ref is `skills/<id>` · `commands/<id>` · `command-bindings/<id>` · `<module-id>/bin/<file>`.
+    kind:
+      type: string
+      enum:
+        - gate
+        - live
+      description: '`gate` — a static check with no fixture record; `live` — runs against a real record and is judged by `expect`.'
+    mode:
+      type: string
+      enum:
+        - readonly
+        - writes
+      description: Whether a `live` proof only reads the workspace or actually writes to it. Required when kind is live, forbidden on a gate.
+    description:
+      type: string
+      description: What this proof asserts, in one line.
+    external:
+      type: boolean
+      description: Excludes this proof from a bare `--all` run — it needs a network call, a credential or a mount that is not always present. `--external` still runs it.
+    requires:
+      type: object
+      description: What must already be present for this proof to be runnable at all — missing ones make it UNAVAILABLE rather than FAIL.
+      properties:
+        env:
+          type: array
+          items:
+            type: string
+          description: '.env keys (names only, never values) that must be set.'
+        bin:
+          type: array
+          items:
+            type: string
+          description: Binaries that must be on PATH.
+    given:
+      type: object
+      description: The record a `live` proof runs against — either a live filter over a collection or a checked-in fixture. Exactly one of `where`/`fixture`.
+      properties:
+        collection:
+          type: string
+          description: A collection NAME (not a reference) the record is picked from — e.g. `notes`, never `collections/notes`.
+        where:
+          type: object
+          description: 'A filter narrowing which record is picked — the ordinary filter grammar, one reference hop deep. ⚠ It may NOT use `{record}`: the given is what PICKS the record, so nothing substitutes here and compile refuses the literal.'
+        pick:
+          type: string
+          description: '`latest` (the collection''s own `sort_field`, descending — refused when the collection declares none) or an explicit record id. `any` is refused. A `fixture` given REQUIRES a `pick: <id>` naming one of its records.'
+        fixture:
+          type: boolean
+          description: Read the record from this proof's own fixtures folder instead of the live workspace.
+    steps:
+      type: array
+      items:
+        type: object
+      description: What actually runs, in order — a shell command (`run`) or a bound command (`perform`). Required; a gate takes one or more `run` steps, a live proof one or more of either.
+    expect:
+      type: array
+      items:
+        type: object
+      description: 'What must hold for a `live` proof to PASS. Live only, and every row is exactly ONE of four forms — `collection`+`where`+`count` · `record`+`where` · `step` (`exit`/`stdout`/`stdout_json`) · `path`+`exists`. A row whose keys span two forms is a compile error, because compile and the judge would otherwise read it as different shapes. `count` takes its own closed operator set (`_eq _neq _gt _gte _lt _lte _delta`) and every operand must be an INTEGER; a `record:` row REQUIRES a non-empty `where` and takes only the literal `{record}` as its target; a `step:` index past the last step is refused; `stdout` and `stdout_json` are FILTER MAPS (`{ _contains: ''…'' }` · `{ ''a.b'': { _gte: 1 } }`) and a scalar, a list or a bare key is refused, because the judge reads only a map and a row it skips asserts nothing. A `where`''s string literals substitute `{record}` and `{record.<field>}` against the picked record before the filter runs — in an expectation only, never in `given.where`.'
+    timeout:
+      type: integer
+      description: Seconds allowed per `run` step before it is killed.
+order: 46
+# ⚠ NO `last-modified` HERE (M12). Every other list_fields carries it, and on a proof it renders as
+# a bare `-` in the MIDDLE of the row: `dt list proofs` appends two computed columns (availability
+# and the ledger tail) after the declared ones, so the empty cell sits between the about list and
+# the answer the reader came for. A proof's meaningful date is its LAST RUN, which is the `last`
+# column, not the mtime of a file git already tracks.
+list_fields:
+  - name
+  - kind
+  - about
+icon: verified
+group: system

package/collections/repos.collection.yaml

@@ -6,12 +6,13 @@ use_when: >-
   a repository this workspace depends on is named — its own engine or extension clone, a client's
   repo — read the record here for WHERE it lives (`path`, a `${env:…}` template `dt resolve` renders
   per machine) before assuming a path or concluding a clone is unreachable; `dt status` reports
-  each one and `dt ensure` materializes it
+  each one and `dt install repos/<id>` materializes it
 # An external git repo attached to this workspace. Owns CLONE LIFECYCLE ONLY — a repo record
 # never contributes schema, skills or UI (that is what a module is, declared in package.json
 # `dreamteamer.git-modules`, because modules must be restorable BEFORE compile can run).
-# Working trees are materialized ON DEMAND via `dreamteamer repos ensure <id>`, never at install:
-# the record count only grows and any given session needs almost none of them.
+# Working trees are materialized ON DEMAND via `dreamteamer install repos/<id>`, and never as part
+# of making a checkout ready: the record count only grows and any given session needs almost none
+# of them.
 storage: { path: data/repos, codec: yaml, shape: file, suffix: repo }
 id:
   generate: "{{ name | slug }}"

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "dreamteamer",
-	"version": "0.20.0",
-	"description": "A workspace compiler for coding agents — schema-validated records as plain files over git, compiled into every harness",
+	"version": "0.22.0",
+	"description": "A workspace compiler for coding agents \u2014 schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",
 	"homepage": "https://github.com/dreamteamer/dreamteamer#readme",

package/skills/using-dreamteamer/SKILL.md

@@ -59,10 +59,12 @@ their flags, on one page (there is no per-verb `--help`).
 the verb names, as a map (semantics and flags live in `help`; a test holds this list to the
 dispatch, so it cannot drift):
 
-- read & measure — `list` `get` `values` `history` `diff` `commands` `relations` `resolve`
-- write & publish — `add` `set` `rm` `rename` `move` `revert` `commit` `ensure`
-- fields (sources, through the compile gate) — `add-field` `update-field` `remove-field` `rename-field` (system entities — modules, collections, skills, ui-views… — take the RECORD verbs above)
-- workspace — `init` `install` `update` `compile` `check` `status` `start` `changes` `help` don't learn syntax from prose, this skill included: prose drifts, and `help` ships in
+- 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`
+
+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
@@ -80,14 +82,17 @@ 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` |
 
 three act-two tie-breakers, because they are the ones that go wrong:
 
@@ -107,8 +112,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 and collection-templates
-are collections in the runtime, and since 0.19.0 the ordinary verbs write them:
+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:
 
 ```
 dt add modules --name core --description "The shared nouns."
@@ -120,6 +125,10 @@ 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.
+
 `dt schema <op>` is **gone** since 0.19.0 and fails with the translation printed. `UPDATING.md` has
 the complete mapping table.
 
@@ -130,7 +139,7 @@ holds the source**, so a write into a `git_modules/` module commits there and sa
 `ahead 1 — push when ready`. A record write lands on disk and `dt commit` publishes it.
 
 ⚠ **Every verb that moves records or clears values takes `--dry-run` and prints its plan first:**
-`rename collections/…`, `rename-field`, `remove-field`, `set collections/… module=`,
+`rename collections/…`, `rename-field`, `rm-field`, `set collections/… module=`,
 `rm modules/… --force`. The plan line is one shape — `records N · refs M · descriptors K · values
 cleared V` — so two dry runs are comparable, and a term that reads 0 means zero rather than
 unmeasured (where a number genuinely cannot be known before the run, the plan says so in words).

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

@@ -40,13 +40,27 @@ install. The looking still matters; the taking changed shape.
 
 | # | look at | how, concretely | what you get |
 |---|---|---|---|
-| 1 | **this workspace's own modules** | the orientation block's MODULES AND THEIR COLLECTIONS list is already in your context — find the module whose sentence owns the concept, then reread its collections with the concept's *synonyms* in mind, `use when` clauses included; then read the candidate's DESCRIPTOR, not its records; `dt help` shows the verbs and `dt commands <collection>` the bound ones; the module's skills line names 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 |
+| 1 | **this workspace's own modules** | the orientation block's MODULES AND THEIR COLLECTIONS list is already in your context — find the module whose sentence owns the concept, then reread its collections with the concept's *synonyms* in mind, `use when` clauses included; then read the candidate's DESCRIPTOR, not its records; `dt help` shows the verbs and `dt next <collection>` the bound ones; the module's skills line names 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, system and field verbs included; read it rather than recalling it | the capability may already be a verb (`relations rebuild`, `resolve`, `ensure`) rather than a missing module |
+| 4 | **the engine's own surface** | `dt help` — the complete verb surface, system and field verbs included; read it rather than recalling it | the capability may already be a verb (`relations rebuild`, `resolve`, `install repos/<id>`) rather than a missing module |
 
 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.
+
+⚠ **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
+whose only evidence is that a session read it; a command whose completion leaves no trace in any
+record is a command nobody can tell ran. Give it a post-state — a field it sets, a record it
+writes, a file it leaves, an exit code it returns — and the proof follows for free. Do it after the
+proposal is accepted and before the build, so the assertion is what you build toward rather than
+what you retrofit.
+
 ## what "found" actually means
 
 Rarely the exact thing. Four outcomes, each with its own move:

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

@@ -63,26 +63,26 @@ unpublished schema is not a state the workspace should sit in. The verbs and eve
 `dt help` under "system verbs" and "field verbs" — read that, not prose. What help cannot tell you:
 
 - **The field verbs write the WORKSPACE module.** On a collection another module owns, `add-field`
-  and `update-field` author an `extends:` overlay in the workspace module — which compiles only
+  and `set-field` author an `extends:` overlay in the workspace module — which compiles only
   if the workspace module declares the owning module in `dreamteamer.dependencies` (the extends
-  gate exempts nobody). `remove-field` has no overlay form at all — an overlay cannot remove an
+  gate exempts nobody). `rm-field` has no overlay form at all — an overlay cannot remove an
   inherited field, so it refuses a module-shipped field by name. So on a module-owned collection:
-  declare the dependency and let add/update write the overlay (the change stays workspace-local),
-  or **edit the owning module's descriptor by hand** and compile (the change ships with the
-  module) — the only exit for a removal. Pick by who should own the field — `data-modeling.md`
-  Part III.
+  declare the dependency and let `add-field`/`set-field` write the overlay (the change stays
+  workspace-local), or **edit the owning module's descriptor by hand** and compile (the change
+  ships with the module) — the only exit for a removal. Pick by who should own the field —
+  `data-modeling.md` Part III.
 - **`--type <collection>` beats the type sugar, always.** A type that names a collection in the
   runtime is a reference to it, whatever `string`/`enum`/`date`/`tags`/… would otherwise mean — so
   in a workspace that ships a `tags` collection, `--type tags` points at it and the relation flags
   work on it. Only a stated `--type` resolves this way; omitting it still means a plain string.
-- `remove-field` on a populated field **clears the values in the same write and reports the
+- `rm-field` on a populated field **clears the values in the same write and reports the
   count** — a leftover key would make every later write to those records fail as unknown. It also
   prunes the field out of **the same descriptor's `list_fields` and `sort_field`** (that is the
   field's own presentation, and a dangling `sort_field` is a compile error), and **warns, by id,**
   about any ui-view whose `options.columns` still names it — a different source, so it is named
   rather than edited.
 - **`add-field` inserts before the `x-body` field**, on the same rule as a `templates:` merge
-  below: property order is form order, and a record's body belongs last. `update-field` never
+  below: property order is form order, and a record's body belongs last. `set-field` never
   reorders — an existing field keeps the place its author gave it.
 - **`dt rename collections/<old> <new>`** moves the descriptor **in the module that ships it**
   (its guard is against writes an `npm install` would erase, not against modules), plus the
@@ -227,6 +227,45 @@ Two gates around it:
 - ⚠ **An overlay can add fields but cannot remove an inherited one.** If the shape is wrong for
   the module rather than just for this workspace, fix the base.
 
+## `x-choices` — what an enum VALUE looks like
+
+An enum value carries a label and nothing else by default: a surface gets `{ text, value }` and
+draws the value. `x-choices` is an OPTIONAL sparse map, keyed by the value, that gives a surface
+more to draw with — a board grouping by the field, a dropdown in a form, anything reading
+`edit_options.choices`.
+
+```yaml
+lane:
+  type: string
+  enum: [alpha, bravo, charlie]
+  x-choices:
+    alpha:
+      label: Alpha team          # what a surface shows; the stored VALUE is still `alpha`
+      description: the one that ships
+      icon: rocket               # a codicon name …
+      color: charts.blue         # a theme colour id — the accent
+      background: charts.blue    #   … and the fill
+    bravo:
+      icon: assets/icons/lucide/anchor   # … OR a reference to a `codec: file` record
+```
+
+- **Sparse and additive.** Decorate one value, or none. A value with no entry projects exactly as it
+  did before this keyword existed, so adding it changes nothing that already works.
+- **`enum` still owns the value set AND its order.** A map key cannot add, remove or reorder a
+  value — which matters, because a grouped view takes its band order from the enum.
+- **Five keys, and only five** — `label` · `description` · `icon` · `color` · `background`, each an
+  optional string. Anything else in an entry is dropped: the projection copies by name, so a
+  descriptor cannot inject keys into a contract every surface reads.
+- **`label` becomes `text`.** So a workspace can relabel a value without touching the value, and no
+  stored record moves.
+- **`icon` is a codicon name or a reference to a record of a `codec: file` collection.** A codicon
+  name never contains a slash and a record reference always does, so the surface decides which
+  without a second keyword.
+- **Colours are theme colour ids, not hex.** A hex is authored against one theme and wrong in the
+  other.
+- **Both mistakes warn rather than fail** — a key that is not one of the enum's values, and the
+  keyword on a field with no enum. See the message catalog below.
+
 ## the reference contract — `x-reference` across the module graph
 
 Every `x-reference` target must be one of: a **core** collection (the entity kinds plus `repos`)
@@ -291,6 +330,8 @@ collection author actually meets. (⚠ = warning: it compiled, and you should st
 | `cyclic module dependencies: a → b → a` | concept-level links declared as module deps | the collection belongs in `peerDependencies` |
 | relation refusals (`stamps a mirror onto…`, `declared on both sides…`) | the relation rules | `data-modeling.md` Part VI |
 | ⚠ `x-unique on "f" is inert` | a relation keyword with no relation — nothing enforces it | declare the inverse, or drop it |
+| ⚠ `x-choices on "f" has an entry for "k"` | it decorates enum VALUES and `k` is not one — a typo, or a value since removed | fix the spelling, or drop the entry |
+| ⚠ `x-choices on "f" is inert` | the keyword on a field that declares no enum — nothing reads it | give the field an enum, or drop the keyword |
 | ⚠ `collection … has no description` | it renders as a bare name in the orientation block every session loads | write the sentence (`data-modeling.md` §18) |
 | ⚠ `module "…" contributed no recognised sources` | its folders match no kind and it ships no UI bundle | usually a layout or naming mistake |
 | ⚠ `module X: <channel> copy shadows <channel> copy` | the same module delivered twice — the more local wins (npm-link semantics) | intended for dev; otherwise remove one |
@@ -316,7 +357,7 @@ silently not discovered — see declaring a module.)*
 | a second same-name descriptor without `extends` | compile error by design |
 | a plain string where a ref belongs | use `x-reference` so `check` and `rename` can follow it |
 | a `templates:` ref pointing at another module | that module can no longer be copied or installed alone |
-| a field verb aimed at a module-owned collection, retried verbatim | add/update write a workspace overlay behind a dependency gate — declare the dependency or edit the owning module; remove-field refuses outright (edit the module) |
+| a field verb aimed at a module-owned collection, retried verbatim | add-field/set-field write a workspace overlay behind a dependency gate — declare the dependency or edit the owning module; rm-field refuses outright (edit the module) |
 | authoring `storage.path` under an entity-kind name | it compiles as a runtime collection and becomes unwritable |
 | hand-editing schema when a schema verb could express it | the verbs are compile-gated and commit their write; a hand edit can land uncompilable and sit unpublished |
 | ignoring a ⚠ because compile said ✔ | every warning above is a defect with a deferred bill |

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

@@ -8,7 +8,7 @@ queue without any run records.
 What you write is consumed by three readers with different needs: the **operator** scanning the
 `/` picker, who sees the `description` and `argument-hint` and nothing else; the **session** that
 receives the body verbatim as its turn, and needs instructions, not documentation; and the
-**surfaces** that render bindings — `dt commands <ref>`, the studio's Commands tab, and the
+**surfaces** that render bindings — `dt next <ref>`, the studio's Commands tab, and the
 orientation block, which prints every binding's gates so each new session knows the queue exists
 before any skill is loaded.
 
@@ -107,7 +107,7 @@ can-exit:  { transcript: { _nempty: true } }
 description: audio present, not yet transcribed
 ```
 
-What a binding buys: `dt commands <collection>[/<id>] [--ids a,b] [--json]` answers "what can I do
+What a binding buys: `dt next <collection>[/<id>] [--ids a,b] [--json]` answers "what can I do
 with this record right now"; the studio draws the same answer as buttons; and the orientation block
 renders every binding with its gates **literally** (`/transcribe-visit (enter: recording_file set ·
 exit: transcript set)`) — so the gate you write is also documentation every session reads without
@@ -151,8 +151,21 @@ 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
+  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
+  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
+  what makes that line count the summaries about THIS record rather than all of them.) The rule of thumb:
+  **the record's own post-state is the binding's** (it has to be, or the queue cannot advance);
+  **what the command left elsewhere is the proof's**. Writing the second one as a gate needs a mirror
+  field or a proxy a human must remember to set; writing the first one only as a proof leaves every
+  record reading `available` forever.
 - **The binding's `description` is the state pair in words** ("audio present, not yet
-  transcribed") — it renders beside the button and in `dt commands` output (the orientation block
+  transcribed") — it renders beside the button and in `dt next` output (the orientation block
   carries the gates themselves), so write it as the answer to "why is this available".
 
 ## the chain — multi-step processes

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

@@ -93,7 +93,7 @@ The useful half of object orientation maps cleanly onto a workspace; the inherit
 | OO idea | its shape here | its non-shape |
 |---|---|---|
 | an object owns its state | a record owns its fields; the collection is the class | fields about X scattered on Y "for convenience" |
-| methods | **command-bindings**: verbs bound to a collection, gated on field state (`can-enter`/`can-exit`) — `dt commands <ref>` lists what applies to a record right now | a workflow engine; procedures copied into descriptions |
+| methods | **command-bindings**: verbs bound to a collection, gated on field state (`can-enter`/`can-exit`) — `dt next <ref>` lists what applies to a record right now | a workflow engine; procedures copied into descriptions |
 | interfaces / mixins | **`templates:`** — a shared field set stamped onto consumers, merged at compile | copy-pasting the same four fields into six descriptors |
 | encapsulation | **module ownership** — a concept's fields live with the module that owns the concept | the module that happened to need the field first |
 | polymorphism | a **union reference** (`x-reference: [meetings, visits]`) or the open-world `'*'` for evidence/source fields | a `type` field plus fields that only apply to some rows |
@@ -845,7 +845,7 @@ useless until the flood is drained.
   command-binding's `can-enter`/`can-exit`. A field is referenced BY NAME rather than as a
   `<collection>/<id>` reference, so `store.rewriteRefs` can see none of those — which is exactly
   why this used to be "no rename verb, deliberately", with the honest sequence being add-new,
-  script the values, `remove-field` the old. That sequence still works and is what you want when
+  script the values, `rm-field` the old. That sequence still works and is what you want when
   the values themselves have to CHANGE shape; when only the name changes, the verb is one command
   and takes `--dry-run`.
 - **Values** (an id, a reference target): `dt rename <collection>/<old> <new>` rewrites inbound

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

@@ -0,0 +1,53 @@
+# exporting — the workspace for a reader that is not a coding agent
+
+`compile` renders the runtime for harnesses that read files. `dt export <target>` renders it for a
+consumer that does not: today **NotebookLM**, which holds a bounded number of *sources* per notebook
+and takes its standing instructions as a 10,000-character *persona*. `dt help` has the flags; this
+page has the judgment.
+
+## what travels, and what never does
+
+Sensitivity is SCHEMA, decided once where the field is declared — never a flag on the export and
+never inferred from a field's name (`email` travels unless somebody marked it):
+
+- **a whole collection**: `dt set collections/<c> sensitive=true`. No record of it is written; the
+  schema source and the persona NAME the omission so the reader knows the gap is deliberate.
+- **one field**: `dt add-field <c> --name <f> … --sensitive`, or `dt set-field <c> --name <f>
+  --sensitive` (`--sensitive false` clears). The field is projected out of every record.
+
+Also never exported as records: the system collections (they ARE the schema source) and `codec: file`
+collections (bytes a view draws). **Before the first export of a workspace, read the report** — it
+prints every field that WAS exported per collection; that list is the review.
+
+## what a notebook gets
+
+- **`dt · schema`** — one source: workspace → module → collection → field, one heading level per
+  step, with each collection's `use when`, id shape and every field's type, enum values and reference
+  target. The lexicon the persona cannot afford in full.
+- **`dt · <collection>`** — one source per collection, `## <collection>/<id>` per record, references
+  rendered as `companies/acme (Acme Ltd)`. Over `--max-words` it shards into `dt · <c> [n/m]`.
+- **the persona** — a Markdown template with `{{workspace}}` `{{schema_brief}}` `{{sources}}`
+  `{{omitted}}` `{{exported_at}}` `{{engine_version}}` `{{schema_title}}` `{{collections}}`; the
+  engine ships a default, `--instructions <file.md>` replaces it, an unknown placeholder is an
+  error. `--response-length` and `--mode` ride along to `notebooklm configure`.
+
+**The budget is the plan's source cap** (`--plan standard|plus|pro|ultra|<n>`, default `standard` =
+50). Too many sources is a refusal that names the count and the remedies — nothing is dropped
+quietly. A workspace with more collections than the plan has sources narrows with `--collections`.
+
+## syncing
+
+Without `--notebook`/`--create` the export is a pure render into `--out` (default
+`.cache/dreamteamer/notebooklm/`, gitignored) and touches no network. With one, it makes the notebook
+match **by title**: adds new sources, replaces those whose content hash changed, removes its own stale
+ones (the `dt · ` prefix marks ownership — a source added by hand is never touched), then applies the
+persona. `notebook.json` in the out dir keeps the notebook id and per-source hashes, so the second run
+is incremental and `--create` is needed once. Every vendor call names the notebook with `-n`;
+`notebooklm use` is never run. **Preflight is `notebooklm auth check --test`** — the bare check
+reports a stale session as valid — and an expired login is the operator's to renew (`notebooklm
+login` opens a browser).
+
+## asking
+
+Not a verb here. Ask with `notebooklm ask -n <id> --json`, and treat an answer as real only when it
+has non-blank text AND at least one reference — exit 0 with an empty answer is a known shape.