dreamteamer 0.31.0 → 0.33.0

package/README.md

@@ -71,8 +71,10 @@ An extension adds verbs, source kinds or harnesses through one contract
 workspace module (`modules/<id>/package.json` declaring `dreamteamer.extension`) or an installed
 dependency.
 
-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.
+Behaviour proofs (`@dreamteamer/proofs`), worktrees (`@dreamteamer/worktrees`), the REST API
+(`@dreamteamer/http`) and the NotebookLM exporter (`@dreamteamer/notebooklm`) are extension packages;
+the local Docker host is the global `dt-docker` bin (`@dreamteamer/docker-workspaces`). A verb typed
+without its package prints the install line.
 
 ## Agent-Native Documentation
 

package/collections/agents.collection.yaml

@@ -1,33 +1,42 @@
 name: agents
-storage: { path: agents, codec: md, shape: file, suffix: agent }
-id: { generate: "{{ name | slug }}" }
-schema:
-  type: object
-  required: [name, description]
-  properties:
-    name:
-      type: string
-      description: The agent id — must equal the filename, or dispatch misses.
-    description:
-      type: string
-      description: WHEN to dispatch this agent, in one line. The harness matches a request against this, so it is the agent's entire discoverability.
-    tools:
-      type: array
-      items: { type: string }
-      description: The tools this agent may use. Empty means the harness default set.
-    model:
-      type: string
-      description: Which model to run it on. Omit to inherit the session's.
-    skills:
-      type: array
-      items: { type: string, x-reference: skills }
-      description: Skills this agent should load. Reference them rather than restating their steps in the body.
-    instructions:
-      type: string
-      format: markdown
-      x-body: true
-      description: The agent's system prompt — what it is for and how it should work.
-order: 30
-list_fields: [name, last-modified, description]
-icon: smart_toy
-group: system
+record_title: '{{ name }}'
+description: A job that runs in a fresh context with its own tools — dispatched by its `description`.
+use_when: >-
+  a job needs a context of its own (a long search, a review, an isolated build) — write it here; when
+  telling the current session how is enough, it is a skill instead
+internal: true
+storage:
+  path: agents
+  format: md
+ids:
+  from: '{{ name | slug }}'
+fields:
+  name:
+    type: string
+    required: true
+    description: The agent id — must equal the filename, or dispatch misses.
+  description:
+    type: string
+    required: true
+    description: WHEN to dispatch this agent, in one line. The harness matches a request against this, so it is the agent's entire discoverability.
+  tools:
+    type: string
+    many: true
+    description: The tools this agent may use. Empty means the harness default set.
+  model:
+    type: string
+    description: Which model to run it on. Omit to inherit the session's.
+  skills:
+    type: skills
+    many: true
+    description: Skills this agent should load. Reference them rather than restating their steps in the body.
+  instructions:
+    type: markdown
+    body: true
+    description: The agent's system prompt — what it is for and how it should work.
+display:
+  nav:
+    icon: smart_toy
+    order: 30
+  list:
+    columns: [name, last_modified, description]

package/collections/collections.collection.yaml

@@ -1,205 +1,69 @@
+# A collection descriptor, as compile writes it: the authored keys (mixins and overlays merged in) and
+# the `compiled` block holding everything compile decided. The authority on what each authored key
+# means is skills/using-dreamteamer/references/collections.md; every reader asks a compiled
+# descriptor through src/descriptor.js rather than reading these keys directly.
 name: collections
-storage: { path: collections, codec: yaml, shape: file, suffix: collection }
-id: { generate: "{{ name | slug }}" }
-schema:
-  type: object
-  required: [name, schema]
-  # The fields fall into five groups, in this order: IDENTITY (name · singular · title ·
-  # title_template — what the collection and a record of it are called), RETRIEVAL (description ·
-  # use_when — what brings a session here), SHAPE (extends · schema · id · sensitive), PLACEMENT
-  # (storage · module · group — where records live and who owns them), PRESENTATION (order ·
-  # list_fields · sort_field · icon · ui — how the surfaces show it). A new field joins one of
-  # these; a field that fits none is a sign it belongs on a record, not on the collection.
-  properties:
-    name:
-      type: string
-      description: The collection id — must equal the filename, and must be unique across every installed module.
-    singular:
-      type: string
-      description: >-
-        The word the CLI accepts beside `name` — `dt add task …` for `tasks`. DERIVED by inflection
-        when absent (`tasks` → `task`, `companies` → `company`, `rnd/projects` → `rnd/project`) and
-        authored only where inflection is wrong (`people` → `person`, `meeting-analyses` →
-        `meeting-analysis`). Typed input only: a REFERENCE inside a record still spells the full
-        name. compile refuses two collections whose name or singular coincide.
-    description:
-      type: string
-      description: >-
-        What one record IS, in one line — and the neighbour it is NOT, when a confusable one exists
-        ("the person, never the org — that is `companies`"). Rendered into the orientation block
-        every agent session loads, so it is retrieval surface, not documentation.
-    use_when:
-      type: string
-      description: >-
-        The SITUATIONS that should bring a session here, in one clause — rendered under the
-        description in the orientation block. A description says what a record is; this says when
-        to reach for the collection, in both directions: to READ ("about to diagnose a defect — search
-        here first, filtered by repo") and to WRITE ("a thought arrives that has no home yet"). Author
-        it for every collection whose trigger is not literally "you have one of these": a schema is
-        designed to be used, and the measured failure is a session inventing a new state or field while
-        the collection that already modelled it sat in its context. Two rules: it names a situation,
-        never a procedure (a `how` belongs in the module's skill); and it must not restate the
-        description — a paraphrase costs every session tokens and dilutes the clauses that carry
-        signal. Omit only where the noun is the whole trigger.
-    title:
-      type: string
-      description: What to call this collection in the nav and page headers. DERIVED from `name` by title-casing when absent — author it only when that is wrong (`ui-views` → `UI Views`).
-    title_template:
-      type: string
-      description: 'How to label a RECORD of this collection, e.g. `{{ name }}`. DERIVED from the first of title/name/subject the schema declares (else `{{ id }}`). Every reference field pointing at this collection renders its value through this, so it is authored HERE once, not on each referencing field.'
-    extends:
-      type: string
-      description: 'The module collection this one overlays, as `<module>/<collection>`. An overlay adds or narrows fields; it never redefines storage.'
-    storage:
-      type: object
-      description: Where the records live on disk and how they are encoded.
-      properties:
-        path:
-          type: string
-          description: >-
-            Folder holding the records, workspace-relative. `data/<collection>` — that is the answer
-            unless you can state a reason. `state/<collection>` is DEPRECATED as a convention since
-            2026-08-31: decision 4 created it for runs, triggers, registries and cursors, all seven
-            of those collections have been deleted, and the one real operational-data need that
-            arrived since went to a gitignored `.cache/*.jsonl` because append-only readings are the
-            wrong shape for records. The mechanism still works and is kept, exactly like `group`
-            below, so a workspace wanting a second root has one. ⚠ NEVER author `system/` — sources
-            have lived in `modules/<module>/<kind>/` since the 2026-08-05 flatten, and a `system/`
-            prefix is only how `runtime.js` recognises a RUNTIME collection in a descriptor compiled
-            by a pre-flatten engine.
-        codec:
-          type: string
-          enum: [md, yaml, json, file]
-          default: md
-          description: 'File format. Use `md` whenever the record has a body a human will read. `file` makes the record an OPAQUE file — any extension, no frontmatter, fields DERIVED (`ext`, `bytes`), written with `add --from <path>` and never with `set`. For icons, logos and images.'
-        max_bytes:
-          type: integer
-          default: 204800
-          description: '`codec: file` only — the largest a record may be, in bytes. `check` reports anything over it. A record is a small file; a big one belongs outside the vault.'
-        extensions:
-          type: array
-          items: { type: string }
-          description: '`codec: file` only — the extensions this collection accepts, lowercase and without the dot. Omitted means any.'
-        shape:
-          type: string
-          enum: [file, folder]
-          default: file
-          description: One file per record, or one folder per record.
-        suffix:
-          type: string
-          description: 'The middle segment of a record filename: `<id>.<suffix>.<ext>`.'
-        entry:
-          type: string
-          description: Folder shapes only — the file inside the folder that IS the record (e.g. SKILL.md).
-        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`.
-    id:
-      type: object
-      description: How a record's id is derived and what shape it is allowed to take.
-      properties:
-        generate:
-          # ⚠ STRING OR AN ORDERED LIST OF STRINGS, and this schema has to say so or `check` refuses
-          # the very form 0.25.0 added. `generateId` learned the list in 0.25.0 and THIS declaration
-          # did not, so a descriptor carrying one compiled fine and then failed `check` with
-          # "must be string" — the feature was unusable in exactly the workspaces it was written for.
-          # Missed because the release was smoked with `dt add` against string templates; nothing
-          # ran `check` over a descriptor that used a list.
-          # anyOf, NOT oneOf: the validator coerces a single-element array to a string, so
-          # `['{{ name | slug }}']` matches BOTH branches and `oneOf` (exactly one) rejects it.
-          anyOf:
-            - type: string
-            - type: array
-              minItems: 1
-              items: { type: string }
-          description: >-
-            Template the id is built from, e.g. `{{ created | date }}--{{ name | slug }}`. Derive it from a field the
-            record OWNS, never from write time. An ORDERED LIST takes the first template whose fields are all present —
-            `['{{ code }}', '{{ name | slug }}']` is "the code when there is one, the name otherwise", which is how a
-            collection keeps a readable latin handle without forcing a field onto every record. A template naming a
-            missing field is skipped rather than fatal; when every one fails, the last error is the one raised.
-        pattern:
-          type: string
-          description: Regex every id must match. `check` enforces it.
-    schema:
-      type: object
-      description: A JSON Schema for the record's fields — validated against the meta-schema, not typed here. A field's own `description:` is what every surface shows as its explanation.
-    order:
-      type: number
-      description: Sort position in the nav. Lower comes first.
-    list_fields:
-      type: array
-      items: { type: string }
-      description: The columns a list view shows by default.
-    sort_field:
-      type: string
-      description: >-
-        Which field carries MANUAL order — the one a drag writes. The field must be declared by this
-        collection's own schema, and holds a fractional index (`dt move <collection>/<id>`), never an
-        integer: renumbering is a multi-file commit against git. A surface offers dragging only while
-        it is sorted by this field, because a handle that reorders nothing is a lie.
-    icon:
-      type: string
-      description: material-symbols-outlined icon name, drawn in the nav and page header. The VS Code tree maps it to the nearest codicon — an unmapped name falls back to a generic cylinder, so pick one that is already mapped or add the row.
-    unresolved_peers:
-      type: array
-      items: { type: string }
-      description: >-
-        DERIVED by compile, never authored — the collections THIS one references that its module
-        declared as a `peerDependencies` peer and nothing installed provides. `check` reads it to
-        excuse those references as unresolvable rather than wrong, which is what lets a module be
-        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: >-
-        The module that OWNS this concept, as its bare id — DERIVED by compile from the base source,
-        and the one field a `dt set` may write: `dt set collections/<c> module=<m>` MOVES the
-        descriptor into that module. An overlay adds fields to somebody else's collection and does
-        not take it over, so the owner is the source declaring no `extends`. This is the workspace's
-        real partition, and what the nav groups by.
-    overlays:
-      type: array
-      items: { type: string }
-      description: >-
-        DERIVED by compile, never authored — the modules contributing an `extends:` overlay to this
-        collection, by id. ABSENT when there are none: an empty list is a statement nobody made.
-        `dt get collections/<c> --module <m>` prints one contribution alone.
-    owner:
-      type: string
-      x-reference: modules
-      description: >-
-        ⚠ COMPAT, ONE RELEASE ONLY — superseded by `module`, which carries the same fact as the bare
-        id the operator actually types. Kept because a surface groups its nav by this key and reads
-        it as a reference; both are written by compile until that surface has moved. Removed in the
-        release after 0.19.0.
-    group:
-      type: string
-      description: >-
-        The collection's PARTITION — which family of nouns it belongs to, authored freely (`crm`,
-        `finance`, `family`, `content`…) and set with `dt set collections/<c> group=<g>`. One value
-        is reserved and load-bearing: `group: system` says the collection is the workspace's own
-        MACHINERY rather than one of its domain nouns, so it is left out of the generated block's
-        domain listing, named on the system-collections line instead, and drawn on a surface's
-        schema surface rather than in the record tree. ⚠ It does NOT change where records live or
-        whether they can be written — that is `storage.base`, asked separately, and `repos` is the
-        collection where the two answers split: `group: system` and workspace-stored records the
-        operator edits by hand. Nearly removed on 2026-08-11, when the nav stopped grouping by it in
-        favour of `owner` (a module, which has a title of its own) and nothing else read it; kept
-        then so the change would be a code revert rather than a data migration, and because a
-        workspace may want a partition that deliberately DIFFERS from its modules. That is what it
-        became.
-order: 10
-list_fields: [name, last-modified]
-icon: schema
-group: system
+record_title: '{{ name }}'
+description: A typed set of records — what one record is, where records live, how ids are made, the fields, and how surfaces draw it.
+use_when: >-
+  a new kind of thing has to be kept, or a collection's shape, storage or display changes — write the
+  descriptor in a module's collections/ folder and run dt compile; read a compiled one here to learn
+  what a collection is
+internal: true
+storage:
+  path: collections
+  format: yaml
+ids:
+  from: '{{ name | slug }}'
+fields:
+  name:
+    type: string
+    required: true
+    description: The collection's name — equal to the filename, unique across every installed module, carrying its namespace (`health/visits`).
+  title:
+    type: string
+    description: The human label. Default the title-cased bare name.
+  singular:
+    type: string
+    description: The word the CLI accepts beside the name (`dt add task …`). Default the inflected bare name, namespace kept.
+  record_title:
+    type: string
+    description: How one record is labelled wherever it is referenced, a template. Its first token is the field `dt add <collection> "<title>"` fills.
+  description:
+    type: string
+    description: What one record IS, in one line — naming the confusable neighbour it is not.
+  use_when:
+    type: string
+    description: The situations that should bring a session to this collection, to read it and to write it.
+  internal:
+    type: boolean
+    description: Workspace plumbing rather than a domain noun — left out of the domain listing.
+  sensitive:
+    type: boolean
+    description: Records never leave the workspace through an export.
+  storage:
+    type: map
+    description: Where records live — path, format (md · yaml · json · binary), shape (file · folder), entry, suffix, under { parent, subfolder }, max_bytes, accept.
+  ids:
+    type: map
+    description: How a record's id is made — `from` (a template, or an ordered list of them) and `pattern`.
+  fields:
+    type: map
+    values: map
+    description: The fields, in the descriptor's own vocabulary, in form order.
+  constraints:
+    type: map
+    many: true
+    description: JSON Schema combinators for a rule across fields.
+  display:
+    type: map
+    description: How surfaces draw it — nav, list, record, form.
+  compiled:
+    type: map
+    description: Written by compile, never authored — defaults, module, repo, runtime, under_collection, mirrors, overlaid_by, unresolved_peers, fields, json_schema.
+display:
+  nav:
+    icon: schema
+    order: 10
+  list:
+    columns: [name, last_modified]

package/collections/command-bindings.collection.yaml

@@ -1,46 +1,40 @@
 name: command-bindings
+description: A command applied to a collection, and the record state that makes it available and that means it is done.
+use_when: >-
+  a command acts on the records of one collection — bind it here, gated on the record's own fields,
+  so `dt next <collection>/<id>` and the orientation block can say what to run on a record and when
+internal: true
 storage:
   path: command-bindings
-  codec: yaml
-  shape: file
-  suffix: command-binding
-id:
-  generate: '{{ command | basename }}--{{ collection | basename }}'
-schema:
-  type: object
-  required:
-    - command
-    - collection
-  properties:
-    command:
-      type: string
-      x-reference: commands
-      description: The command this binding applies.
-    collection:
-      type: string
-      x-reference: collections
-      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:
-        - record
-        - collection
-      default: record
-      description: Whether the command runs against one record or the whole collection.
-    can-enter:
-      type: object
-      description: The record state that makes this command AVAILABLE — a filter over the record's own fields. This is what turns a collection into a queue without any run records.
-    can-exit:
-      type: object
-      description: The record state that means the command has already been DONE. Together with can-enter, the record's own fields are the progress marker.
-    description:
-      type: string
-      description: What applying this command to this collection does, in one line.
-order: 45
-list_fields:
-  - command
-  - collection
-  - target
-  - last-modified
-icon: bolt
-group: system
+  format: yaml
+ids:
+  from: '{{ command | basename }}--{{ collection | basename }}'
+fields:
+  command:
+    type: commands
+    required: true
+    description: The command this binding applies.
+  collection:
+    type: collections
+    required: true
+    description: The collection the command applies to — what lets `dt next <ref>` answer "what can I do with this record".
+  scope:
+    type: string
+    default: record
+    enum: [record, collection]
+    description: Whether the command runs against one record or the whole collection.
+  available_when:
+    type: map
+    description: The record state that makes this command available — a filter over the record's own fields. It turns a collection into a queue with no run records.
+  done_when:
+    type: map
+    description: The record state that means the command has been done. With `available_when`, the record's own fields are the progress marker.
+  description:
+    type: string
+    description: What applying this command to this collection does, in one line.
+display:
+  nav:
+    icon: bolt
+    order: 45
+  list:
+    columns: [command, collection, scope, last_modified]

package/collections/commands.collection.yaml

@@ -1,36 +1,51 @@
 name: commands
-storage: { path: commands, codec: md, shape: file, suffix: command }
-id: { generate: "{{ name | slug }}" }
-schema:
-  type: object
-  required: [name]
-  properties:
-    name:
-      type: string
-      description: The command id — must equal the filename, and is what the operator types after the slash.
-    description:
-      type: string
-      description: What this command does, in one line. It is the whole entry in the / picker, so write it for someone scanning.
-    # native claude-code slash-command frontmatter — compile copies commands verbatim,
-    # so these flow straight into .claude/commands/<name>.md and the / picker
-    argument-hint:
-      type: string
-      description: What arguments the command takes, shown inline in the / picker.
-    allowed-tools:
-      type: string
-      description: Tools this command may use, when it should be narrower than the session's.
-    model:
-      type: string
-      description: Which model to run it on. Omit to inherit the session's.
-    disable-model-invocation:
-      type: boolean
-      description: Set when only a person may run this — it stops the model invoking it on its own.
-    prompt:
-      type: string
-      format: markdown
-      x-body: true
-      description: The command body. Reference the skill that owns the procedure rather than restating its steps — two copies drift.
-order: 40
-list_fields: [name, last-modified, description]
-icon: terminal
-group: system
+record_title: '{{ name }}'
+description: A procedure the operator starts by typing its name after a slash — the entry point, never the procedure itself.
+use_when: >-
+  a job should start on one typed word, or a chain of jobs should be gated on a record's fields —
+  write the entry here and point it at the skill that owns the steps; if a session should find the
+  job on its own, it is a skill instead
+internal: true
+storage:
+  path: commands
+  format: md
+ids:
+  from: '{{ name | slug }}'
+fields:
+  name:
+    type: string
+    required: true
+    description: The command id — must equal the filename, and is what the operator types after the slash.
+  description:
+    type: string
+    description: What this command does, in one line. It is the whole entry in the / picker, so write it for someone scanning.
+  use_when:
+    type: string
+    description: The situations that should bring a session to this command, one clause. Rendered into the harness's trigger line after the description.
+  # Claude Code's own slash-command frontmatter — compile copies a command verbatim into the
+  # harness, so these keep the harness's spelling and are marked passthrough.
+  argument-hint:
+    type: string
+    passthrough: true
+    description: What arguments the command takes, shown inline in the / picker.
+  allowed-tools:
+    type: string
+    passthrough: true
+    description: Tools this command may use, when it should be narrower than the session's.
+  model:
+    type: string
+    description: Which model to run it on. Omit to inherit the session's.
+  disable-model-invocation:
+    type: boolean
+    passthrough: true
+    description: Set when only a person may run this — it stops the model invoking it on its own.
+  prompt:
+    type: markdown
+    body: true
+    description: The command body. Reference the skill that owns the procedure rather than restating its steps — two copies drift.
+display:
+  nav:
+    icon: terminal
+    order: 40
+  list:
+    columns: [name, last_modified, description]

package/collections/mixins.collection.yaml

@@ -0,0 +1,49 @@
+# The first meta-descriptor written in descriptor format v2: a mixin is itself a partial v2
+# descriptor, so its own shape is stated in the vocabulary it contributes.
+name: mixins
+record_title: '{{ name }}'
+description: A partial descriptor merged into every collection that lists it in `mixins` — shared fields, and where it says so storage, id and display.
+use_when: >-
+  several collections in one module need the same fields (provenance, a dated document's id shape) —
+  write them once here and list the mixin, rather than restating the fields in every descriptor
+internal: true
+storage:
+  path: mixins
+  format: yaml
+ids:
+  from: '{{ name | slug }}'
+  pattern: '^[a-z0-9-]+$'
+fields:
+  name:
+    type: string
+    required: true
+    description: The mixin id. Scope it to its module (`clinic-provenance`, not `provenance`) — two modules shipping one id is a compile error, not a merge.
+  description:
+    type: string
+    description: What the mixin contributes, in one line.
+  use_when:
+    type: string
+    description: Which collections should list it.
+  fields:
+    type: map
+    values: map
+    description: The fields it contributes, in the descriptor's own field vocabulary. They are inserted before the collection's body field; a name the collection or another mixin also declares is a compile error.
+  storage:
+    type: map
+    description: Storage keys applied where the collection is silent.
+  ids:
+    type: map
+    description: How record ids are made (`from`, `pattern`), applied where the collection is silent.
+  display:
+    type: map
+    description: Display keys applied key by key where the collection is silent.
+  constraints:
+    type: map
+    many: true
+    description: JSON Schema combinators appended to the collection's own.
+display:
+  nav:
+    icon: content_copy
+    order: 120
+  list:
+    columns: [name, description]