dreamteamer 0.6.0

package/collections/repos.collection.yaml

@@ -0,0 +1,42 @@
+name: repos
+# 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.
+storage: { path: data/repos, codec: yaml, shape: file, suffix: repo }
+id:
+  generate: "{{ name | slug }}"
+  pattern: "^[a-z0-9-]+$"
+schema:
+  type: object
+  required: [name, url]
+  properties:
+    name:
+      type: string
+      description: The CLONE FOLDER name, not a display title — this is what appears on disk.
+    description:
+      type: string
+      description: What this repo is, in one line.
+    url:
+      type: string
+      description: The git remote to clone from.
+    ref:
+      type: string
+      default: main
+      description: Branch or tag to check out.
+    identity:
+      type: string
+      description: 'Opaque path segment grouping clones by the account that owns them: <repos-path>/<identity>/<name>.'
+    path:
+      type: string
+      description: Workspace-relative path override. Wins over the derived <repos-path>/<identity>/<name>.
+    visibility:
+      type: string
+      enum: [private, public]
+      default: private
+      description: Whether the repo is public. Defaults to private, because assuming otherwise is the expensive mistake.
+order: 145
+list_fields: [name, identity, ref, url]
+icon: source
+group: system

package/collections/skills.collection.yaml

@@ -0,0 +1,22 @@
+name: skills
+storage: { path: skills, codec: md, shape: folder, entry: SKILL.md }
+id: { generate: "{{ name | slug }}" }
+schema:
+  type: object
+  required: [name, description]
+  properties:
+    name:
+      type: string
+      description: The skill id — must equal the folder name.
+    description:
+      type: string
+      description: WHEN to load this skill, not what it contains. A session matches its situation against this line, so a description that describes the contents is a skill that never triggers.
+    instructions:
+      type: string
+      format: markdown
+      x-body: true
+      description: The skill itself. Keep it a digest with references/ beside it — a skill nobody can afford to load is not a capability.
+order: 20
+list_fields: [name, last-modified, description]
+icon: psychology
+group: system

package/collections/ui-views.collection.yaml

@@ -0,0 +1,48 @@
+name: ui-views
+title: UI Views
+storage: { path: ui-views, codec: yaml, shape: file, suffix: ui-view }
+id: { generate: "{{ path | slug }}" }
+schema:
+  type: object
+  required: [path, target, layout]
+  properties:
+    path:
+      type: string
+      description: The route this view renders at. The record id is derived from it, so a view saved from the CLI and one saved from the UI land on the same record.
+    nav:
+      type: object
+      description: How the view appears in navigation. Omit it entirely for a route with no nav entry.
+      properties:
+        label:
+          type: string
+          description: What the nav entry reads.
+        icon:
+          type: string
+          description: material-symbols-outlined icon name for the nav entry.
+        order:
+          type: number
+          description: Sort position among its siblings.
+    target:
+      type: string
+      enum: [list, item, page]
+      description: What the view renders — a collection listing, one record, or a standalone page.
+    collection:
+      type: string
+      x-reference: collections
+      description: Which collection this view is of.
+    default:
+      type: boolean
+      description: 'Marks the view a bare /content/<collection> renders. Directus-parity: a collection''s default presentation is an ordinary view record, not a second mechanism. At most one per collection, and never its own route — it IS the collection page.'
+    layout:
+      type: string
+      description: A REGISTERED layout/component id (table, cards, kanban, calendar, map…). An unregistered id degrades visibly rather than erroring.
+    options:
+      type: object
+      description: Layout-specific settings — columns, sort, grouping. Deliberately open, since each layout wants different things.
+    filter:
+      type: object
+      description: The saved filter this view applies, in the studio's operator set.
+order: 50
+list_fields: [path, last-modified, target, collection, layout]
+icon: dashboard_customize
+group: system

package/collections/users.collection.yaml

@@ -0,0 +1,21 @@
+name: users
+storage: { path: data/users, codec: yaml, shape: file, suffix: user }
+id: { generate: "{{ name | slug }}" }
+schema:
+  type: object
+  required: [name]
+  properties:
+    name:
+      type: string
+      description: The person's name. Its slug is the id, and `@me` resolves against it — so it must agree with `git config user.name`, or an assignee query comes back empty with no error.
+    description:
+      type: string
+      description: Who this person is, in one line.
+    email:
+      type: string
+      format: email
+      description: Their email address.
+order: 140
+list_fields: [name, last-modified, email]
+icon: badge
+group: system

package/package.json

@@ -0,0 +1,58 @@
+{
+	"name": "dreamteamer",
+	"version": "0.6.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>",
+	"homepage": "https://github.com/dreamteamer/dreamteamer#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/dreamteamer/dreamteamer.git"
+	},
+	"bugs": {
+		"url": "https://github.com/dreamteamer/dreamteamer/issues"
+	},
+	"keywords": [
+		"agent",
+		"coding-agent",
+		"claude-code",
+		"workspace",
+		"compiler",
+		"cli",
+		"yaml",
+		"markdown",
+		"json-schema",
+		"git"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=20"
+	},
+	"bin": {
+		"dreamteamer": "./bin/dreamteamer.js"
+	},
+	"files": [
+		"NOTICE",
+		"bin",
+		"src",
+		"collections",
+		"skills",
+		"agents",
+		"commands",
+		"command-bindings",
+		"ui-views",
+		"collection-templates"
+	],
+	"dependencies": {
+		"ajv": "^8.17.1",
+		"ajv-formats": "^3.0.1",
+		"express": "^5.2.1",
+		"js-yaml": "^4.1.0"
+	},
+	"dreamteamer": {},
+	"scripts": {
+		"metrics": "node scripts/metrics.mjs",
+		"metrics:check": "node scripts/metrics.mjs --check",
+		"layers": "node scripts/layers.mjs"
+	}
+}

package/skills/building-dreamteamer/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: building-dreamteamer
+description: use when authoring or changing anything in a module's source folders (collections/, skills/, agents/, commands/, command-bindings/, ui-views/, collection-templates/) — a collection or a field, a skill, a command, an agent, a ui-view, or studio component code. Also when deciding WHICH of those a request should become, or when a compile/check error names a source file.
+---
+
+# building dreamteamer
+
+**core principle:** you write a **source** under `modules/<module>/<kind>/`, `compile` makes
+it real, `check` reports what disagrees. Nothing you author is live until compile runs, and nothing
+under `.dreamteamer/` or `.claude/` is ever the thing to edit.
+
+This skill is the **digest**. The shape of each entity, and the mistakes specific to it, live in
+`references/` — load exactly the one you need.
+
+## first: which entity is this?
+
+Most authoring mistakes are a wrong choice here, not a wrong file. Pick by what the operator
+actually wants to happen:
+
+| the ask | write | reference |
+|---|---|---|
+| "the workspace has no home for this kind of thing" / a field is missing | a **collection** | `references/collections.md` |
+| "when you're already doing X, know this" — knowledge a session should find itself | a **skill** | `references/skills.md` |
+| "let me type one word and have you do this" | a **command** | `references/commands.md` |
+| "do this with a fresh context and its own tools" | an **agent** | `references/agents.md` |
+| "put it at this route / in the nav / show it as a board" | a **ui-view** | `references/ui-views.md` |
+| a rendering or editing behaviour no registered component has | **component code** | `references/ui-components.md` |
+| "which command applies to this record?" | a **command-binding** | `references/commands.md` |
+
+Three tie-breakers worth internalising, because they are the ones that go wrong:
+
+- **skill vs command:** a skill triggers itself when the situation arises; a command needs the
+  operator to remember it exists. If the answer is "and they'd have to think of running it", write
+  the skill.
+- **agent vs skill:** an agent costs a whole context. If "just tell the current session how" works,
+  it is a skill.
+- **a multi-step process is a CHAIN OF COMMANDS, not an entity.** There is no workflow kind: a
+  `workflows` collection with run records, triggers and an executor existed until 2026-07-31 and was
+  removed after three days of measurement showed the work being done by a command chain instead. Write
+  one command per step, bind each to its collection so `dt commands for <ref>` shows what applies, and
+  a command whose body invokes the others in order if the sequence needs a name. The record's own state
+  is the progress marker — which is what made the run records redundant.
+
+## the rules that apply to every kind
+
+These were duplicated across seven skills; they are true for all of them.
+
+1. **Sources live in a module.** `modules/<module>/<kind>/`. The workspace's own go in its
+   **workspace module** — the `dreamteamer.workspace-module` name in `package.json`. A root
+   source folder at the WORKSPACE root is a **compile error**, not a fallback.
+2. **The filename is the id.** `<name>.<kind>.<ext>`, or a folder named `<id>` for folder-shape
+   kinds (skills). Where a record also carries a `name` in frontmatter (agents, commands),
+   the two **must agree** — the harness names the file from the filename, so a mismatch
+   makes the id lie.
+3. **The meta-descriptor IS the spec.** Every kind is itself a collection:
+   `.dreamteamer/collections/<kind>.collection.yaml` lists every key it may carry with its
+   allowed values. Read that, plus a real one (`dt <kind> get <id>`), instead of learning the shape
+   from prose. Prose drifts; the descriptor cannot.
+4. **`npm run compile`, then `npm run check`.** Compile materializes the runtime and the harness
+   adapters; check validates refs and shapes and never modifies files. Neither is optional.
+5. **A running session does not see new sources.** Compile writes files; it cannot reach into a
+   conversation already in progress. A new command, agent or skill is available in the **next**
+   session. Say so rather than letting the operator wonder.
+6. **References are qualified** — `skills/<id>`, `agents/<id>`, `commands/<id>`, `collections/<id>`,
+   `users/<id>`. A bare name fails `check`.
+7. **Never edit generated output.** `.dreamteamer/`, `.claude/`, `.agents/`, `.cursor/` are all
+   overwritten and pruned on the next compile. If you found the thing you want to change in one of
+   those, you are in the wrong file.
+8. **The CLI refuses system-stored records on purpose.** `dt skills set …` will not work; edit the
+   module source and compile. The exceptions are the meta verbs that write sources *through* a
+   compile gate — `collections add`, `<collection> add-field`, `ui-views add|set` — which exist so
+   an uncompilable source can never land in history.
+9. **Never duplicate a procedure across records.** A command body that restates a skill, an agent
+   body that inlines its skill's steps, a command that re-types another command's prompt — each is two
+   copies that drift. Reference the one that owns it.
+10. **Module-shipped entities must not name a workspace's own users, accounts or paths.** Use
+    `@initiator` / `@me`, and read per-install values from `.env` naming the variable. A hard-coded
+    `users/<someone>` does not resolve in anyone else's workspace.
+
+## the loop
+
+```bash
+# 1. author the source under modules/<module>/<kind>/
+npm run compile     # required — nothing is live before this
+npm run check       # refs, shapes, id patterns
+npm run --silent dt -- status    # when unsure whether the runtime is fresh
+```
+
+`compile` fails **closed**: a source that cannot compile is rejected and the previous runtime
+stands. Read the error — it names the file and, for a collision or an unresolved ref, both sides.
+
+## is this core, or is it a recipe?
+
+If you are adding to the **engine's own** sources, the bar is higher than "useful". Core carries
+only what the engine itself reads or the compile/check/run loop needs. Anything domain-shaped —
+a collection about people, meetings, tasks, products, content — belongs in a module, and a *generic*
+version of it belongs in the `recipes` repo rather than here.
+
+**The test is: does the ENGINE read it?** Core's collections are the entity kinds the compiler itself
+materializes, plus `users` (because `@me` resolves against it) and `repos` (because `repos ensure`
+clones them). Everything else has been ejected on exactly that test — `teams` (nothing resolved a
+team), `mounts` (a one-implementation adapter enum over an `.env` key), `module-registries` (zero
+readers), `workflows`/`workflow-runs`/`workflow-triggers`/`cursors` and `migrations`/`migration-runs`
+(measured unused), and finally `tasks`, whose only claim to core had been the workflow gate that no
+longer exists. `npm run metrics` in the engine holds the budgets that keep this honest.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| authoring under `.dreamteamer/` or `.claude/` | generated; the change vanishes on the next compile |
+| a source folder at the workspace root | compile error by design — it goes in the workspace module |
+| forgetting compile | the CLI, `check` and every harness still see the old shape |
+| filename ≠ frontmatter `name` | the id lies; dispatch and invocation miss |
+| telling the operator it works now | it works in their **next** session |
+| writing a bespoke entity when a registered one would do | prefer a record over code, and an existing layout/skill over a new one |
+| picking the entity by what is easiest to write | pick by how it should be triggered — that is what the choice encodes |

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

@@ -0,0 +1,44 @@
+# agents
+
+`modules/<module>/agents/<name>.agent.md`. The filename MUST equal the frontmatter `name`.
+Compile copies the file to `.claude/agents/<name>.md` with one real transform — the `skills:`
+frontmatter key becomes an in-body load instruction — so the record *is* the subagent definition.
+
+**Before writing one, check it should not be a skill.** An agent costs a whole context. It earns
+that only when the job needs a dispatchable persona with its own tool allowlist and skill set — a
+router, a reviewer, a critic that must not share the caller's context.
+
+```yaml
+---
+name: dreamteamer
+description: master agent — routes a request to the right collection, skill or agent; the default operator for data-facing work
+tools: [Read, Write, Edit, Grep, Glob, Bash]
+skills: [skills/using-dreamteamer]
+---
+```
+
+| field | required | notes |
+|---|---|---|
+| `name` | yes | must equal the filename; this is the id and the subagent's identity |
+| `description` | yes | **when a dispatcher should pick this agent** — concrete triggers, not a role title |
+| `tools` | no | tool allowlist; give only what the job needs. Omit for the harness default |
+| `model` | no | override (`sonnet`, `opus`, …); omit to inherit |
+| `skills` | no | `skills/<id>` refs, verified by `check` — loaded before the agent works |
+
+The body is the `instructions` field (`x-body: true`) and becomes the subagent's system prompt.
+Direct instructions: what to read, what to decide, in what order, what it hands back. Keep it tight
+— a few sentences to a short paragraph. **The procedure lives in the referenced skills**, never
+duplicated here.
+
+Reference: the core module's `agents/dreamteamer.agent.md` — the only agent core ships, and the
+shape to copy: short trigger description, tight tool list, 1–2 skill refs, a one-paragraph body.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| a `description` that is a role title ("the research agent") | dispatchers match on triggers; say when to pick it |
+| `skills: [using-dreamteamer]` | refs are qualified: `skills/using-dreamteamer` |
+| pasting the skill's procedure into the body | two copies, one drifts |
+| a broad `tools` list | a Write tool on a read-only reviewer is a footgun |
+| creating an agent for a one-off instruction | a skill is usually the right answer |

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

@@ -0,0 +1,42 @@
+# before you build — look for it first
+
+**Core principle:** when the workspace can't do something, **look before you build** — and when you do
+find something, **propose concretely, never install or copy silently.** The operator decides what
+enters their workspace.
+
+This replaced a standalone `discovering-new-capabilities` skill on 2026-07-31, whose premise — "find
+and propose an **installable** module" — had been reversed: domain modules are no longer packages you
+install. The looking still matters; the taking changed shape.
+
+## where to look, in order
+
+| # | look at | what you get |
+|---|---|---|
+| 1 | **this workspace's own modules** — `.dreamteamer/manifest.yaml` names them | the thing may already exist under a name you didn't guess. Check the collections list and `dt <c> --help` before anything else |
+| 2 | **the `recipes` repo** — reference modules maintained to be **copied and adapted** | a working module with its reasoning attached. Read its `using-recipes` skill for the adoption procedure |
+| 3 | **a sibling workspace under `projects/`** | another vault may already have solved it concretely. That is a *reference*, not a source — and it holds real personal data, so read, never lift |
+| 4 | **the engine's own surface** — `dt help`, plus the purpose-built verbs `help` omits | a verb missing from `help` is not a verb that doesn't exist |
+
+Only after all four: build it, in the module that owns the concept.
+
+## how to propose
+
+Say three things: **what you found**, **what adopting it would cost**, and **what you would delete
+from it**. That last one is not politeness — adoption is mostly deletion, and a proposal that skips it
+is asking the operator to accept a maximal module sight unseen. Name the `.env` keys, external
+accounts and binaries it needs, because a skill whose setup nobody did is a skill that fails at the
+worst possible moment.
+
+Then stop and let them choose. Copying a recipe in is a one-way door in practice: from that moment the
+copy is theirs to maintain, and nothing will later tell them it drifted from the original.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| building because you didn't find it in 30 seconds | there are four places to look, and the first is this workspace |
+| `npm i` / `git_modules` a recipe module | recipes are copied, not installed — importing re-creates the fork the split exists to avoid |
+| copying a recipe in and keeping all of it | deleting what you won't use IS the adoption step |
+| lifting from another workspace under `projects/` | those hold real personal data; read for reference only |
+| proposing without naming the setup cost | the `.env` keys and the accounts are the actual price |
+| installing or copying, then telling the operator | they decide what enters their workspace, before it enters |

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

@@ -0,0 +1,120 @@
+# collections
+
+One descriptor file: `modules/<module>/collections/<name>.collection.yaml`. The descriptor
+**describes reality** — you do not edit records to fit an inferred schema.
+
+## the meta verbs (real, absent from `dt help`)
+
+| goal | how |
+|---|---|
+| new collection from a template | `dt collections add --name research-docs --template docs` |
+| templateless | `dt collections add --name <n>` — emits a minimal compilable schema |
+| add a field | `dt <collection> add-field --name urgent --type boolean --default-value false` |
+| change / drop a field | `dt <collection> update-field …` · `remove-field --name <f>` |
+| delete a collection | `dt collections rm <name>` |
+| what templates exist | `.dreamteamer/collection-templates/` |
+
+`--type` is sugar over JSON Schema: `string`/`text`, `markdown`, `boolean`, `number`, `integer`,
+`date`, `datetime`, `enum` (+`--options "a,b,c"`), `tags`, `reference` (+`--target <collection>`),
+or a bare collection name for a reference into it. `--required true` widens `required`.
+
+⚠ **The meta verbs write the WORKSPACE module only.** To change a field on a collection another
+module owns, either edit that module's descriptor by hand or add an `extends:` overlay.
+⚠ **There is no `collections rename`** — it refuses system sources. A rename is `git mv` of the
+descriptor + edit `name`/`storage.path`/`suffix` + re-suffix every record, all in one commit.
+
+## `templates:` — a live shared field set
+
+```yaml
+name: meetings
+templates: [collection-templates/provenance]   # merged at compile, every time
+```
+
+- **`templates:` is not `extends:`.** `extends: <module>/<collection>` means "this descriptor
+  *overlays* another module's collection of the same name". `templates:` pulls in a field set and
+  says nothing about module layering. A descriptor may use both.
+- **Precedence is template < base < overlay** — a descriptor always wins on a key it declares, so a
+  collection can tighten a templated field (add an enum, change a default) without touching the
+  template.
+- **The template is a declared SOURCE of every consumer**, so editing it marks them stale and
+  `dt status` names them. Without that, the edit would apply to nothing and warn about nothing.
+- **Template properties insert before the `x-body` field** — property order is form order, and a
+  record's body belongs last.
+- ⚠ **A `templates:` ref must resolve inside the module that ships the descriptor**, or that module
+  cannot be installed or copied on its own. This is the single most expensive mistake in the
+  project's history: an extracted module whose every descriptor referenced a template living in the
+  *consuming* workspace could not compile into a bare workspace at all, and nobody noticed for
+  months. A collection-template id is an *identity* entity, so two modules cannot both ship
+  `provenance` — scope the id per module (`crm-provenance`).
+- `--template X` at creation copies the fields in once. `templates:` is the live version; prefer it
+  for anything you will want to change in one place later.
+
+## judgment the descriptor can't tell you
+
+- **`id.generate` takes creation-time values only** — `{{ created | date }}--{{ name | slug }}`,
+  never a mutable field (`due`, `status`, and note `created` itself is the moment the record is
+  WRITTEN, so a back-dated import files under the import month; derive from the domain's own date
+  field instead). `id.pattern` must accept everything the template can produce — non-latin titles
+  slug to a deterministic short hash, so `[a-z0-9-]` still holds.
+- **The `x-` keywords carry the domain semantics.** `x-reference` (a target collection, or `"*"` for
+  any) is what lets `check` and `rename` follow a field. `x-body` marks the single field that becomes
+  the md body. `x-inverse` declares a two-way link and makes `check` enforce both directions.
+  `x-title-template` overrides how a VALUE of that field is labelled — rarely needed, because a
+  reference already inherits its TARGET collection's `title_template`; author it there instead, once,
+  rather than on every field pointing at it.
+- **Do not enum a field after the fact.** Enumerating a vocabulary the records already violate makes
+  `check` fail on every pre-existing value. `dt <collection> values <field>` derives the real
+  vocabulary from the data — a filter dropdown gets it for free without locking the set.
+- **`icon` / `group`** are the studio nav's material-symbol icon and folder; ungrouped collections
+  list at the top. `list_fields` is the SEED a module ships, not a competing source of truth — a
+  ui-view's `columns` REPLACES it.
+
+## extending another module's collection
+
+```yaml
+name: tasks
+extends: '@dreamteamer/dreamteamer/tasks'
+schema:
+  properties:
+    urgent: { type: boolean, default: false }
+```
+
+Compile merges `schema.properties` per-property, unions `required`, and takes `storage`/`id` from
+the base. Two modules extending the same base are applied in module-discovery order and the last
+wins on any shared key — so keep extenders **disjoint** and never rely on the collision. Two
+same-name descriptors where neither declares `extends` is a compile error; so is an `extends` value
+that does not name the actual base.
+
+⚠ **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.
+
+## registering an existing data folder
+
+1. Sample the files: derive `suffix`/`codec` from the filenames (`<id>.<suffix>.<ext>`) and the id
+   `pattern` from the id shapes actually present.
+2. Collect frontmatter keys across files → `properties`; infer types from values. A string field
+   with ≤10 distinct values, repeats and ≥80% fill is probably an `enum` — but see the warning
+   above. Values shaped `<collection>/<id>` are `x-reference` fields. No frontmatter at all →
+   `required: []` with a comment saying why.
+3. **Never edit the records to fit an inferred schema.** Describe reality, compile, run `check`,
+   then decide which violations are worth fixing in the data.
+
+**Evolving a schema:** widening (a new optional field, a new enum value) is always safe; narrowing
+(a new required field, a removed enum value) needs the data cleaned first. A shape change across many existing
+records is a **one-shot script you write, run once and commit with the records it rewrote** — there is
+no `dt migrate`. A record-based migration mechanism shipped in July 2026 and was removed on 2026-07-31
+having never once been used: every real schema change in this project's history went around it as a
+script. If you write one, say in the commit message what it did, because that message is the only
+ledger.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| a mutable field in `id.generate` (`due`, `status`) | ids must never change |
+| `id.generate` from `created` for imported records | `created` is when the record was written, not when the thing happened |
+| tightening `required` before cleaning the data | check floods; widen, rewrite the data, then narrow |
+| 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 |
+| inventing a collection for a one-off extraction | a collection is for things that recur; prefer the nearest real one |

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

@@ -0,0 +1,69 @@
+# commands and command-bindings
+
+## commands
+
+`modules/<module>/commands/<name>.command.md`. A command is a **canned prompt a human
+deliberately types**. Compile copies the file verbatim to `.claude/commands/<name>.md` — that file
+is what makes `/<name>` work.
+
+```markdown
+---
+name: process-inbox
+description: triage every open task assigned to me, one at a time
+argument-hint: "[assignee]"
+---
+load this workspace's tasks skill. list my open tasks
+(`npm run --silent dt -- tasks list --assignee users/<me> --status todo`), then walk them one at a
+time: restate it, ask me to keep / reassign / drop, apply the decision with `tasks set`.
+done when the list is empty or I say stop.
+```
+
+- **`description`** is the only thing the operator sees in the `/` picker — say what running it does.
+- **The body is the `prompt` field** (`x-body: true`) and is sent **verbatim as the turn**. Write
+  imperatives to yourself — which skill to load, which records to touch, what "done" means — not
+  documentation about the command.
+- **`$ARGUMENTS` / `$1`** are substituted by the harness with whatever was typed after the command
+  name. Pass-through frontmatter: `argument-hint`, `allowed-tools`, `model`,
+  `disable-model-invocation`.
+- **Convention:** a record command takes record ref(s) (`/transcribe-recording meetings/<id> …`); a
+  collection command takes the collection name. A multi-select invocation carries the **eligible**
+  refs only, space-separated, so nothing is silently dropped.
+
+## command-bindings — which commands apply to which records
+
+`modules/<module>/command-bindings/<command>--<collection>.command-binding.yaml`. An m2m
+record joining a command to a collection, so **every (command, record) pair has a state**.
+
+```yaml
+command: commands/transcribe-recording
+collection: collections/meeting-recordings
+target: record                      # or `collection` for commands that need no record
+can-enter: { file: { _nempty: true } }
+can-exit:  { transcription: { _nempty: true } }
+description: audio present, no transcript yet
+```
+
+- **`can-exit` doubles as the done-detector**, giving three states: `available` (enter ✓, exit ✗),
+  `done` (exit ✓ — shown completed, not disabled), `not-applicable` (enter ✗). That is what makes
+  the work queue **derivable from the data** rather than remembered.
+- **Filters support one-hop OUTBOUND ref traversal**: `{ recording: { file: { _nempty: true } } }`
+  resolves the ref and evaluates the sub-condition on the target. Array refs use `_some` semantics.
+  A missing resolver, a dangling ref or a non-ref value **narrows**, never widens.
+- ⚠ **INBOUND refs are unsupported.** "a summary referencing this meeting exists" is inexpressible,
+  so a command whose completion is only visible from the other side ships without a `can-exit` and
+  never shows done. Say so rather than faking it with a proxy field.
+- **Pick the signal carefully.** "Is it transcribed?" is `transcription._nempty` (the provenance
+  object), NOT `transcript._nempty` — a body can be filled by hand with no provenance, which is
+  exactly the case worth flagging as not-yet-done.
+- Read the queue with `dt commands for <collection>[/<id>] [--ids a,b] [--json]`.
+
+## common mistakes
+
+| mistake | reality |
+|---|---|
+| filename ≠ `name` | the invocable name comes from the filename; the id then lies |
+| a body that restates a whole skill | say "load `<skill>`" — one copy of the procedure |
+| a body that describes the command | it is sent verbatim as a turn; write imperatives |
+| a command for something a skill should auto-trigger | commands need the operator to remember them |
+| a `can-exit` on a `target: collection` binding | there is no record to evaluate it against; compile warns |
+| a `can-exit` over an inbound ref | unsupported — the command will never report done |