dreamteamer 0.27.0 → 0.29.0

package/README.md

@@ -150,6 +150,9 @@ adapters: Claude Code, Codex, Pi, Gemini CLI, Cursor. Author a skill once; every
 
 ## The editor
 
+Extension id `dreamteamer.dreamteamer-vscode` (Marketplace · Open VSX). `init` and `compile` write the
+`.vscode/extensions.json` recommendation, and `dt status` reports whether it is active.
+
 [dreamteamer-vscode](https://github.com/dreamteamer/dreamteamer-vscode) gives you tables, boards,
 calendars, maps, forms and a data-model designer over the same files — and it loads **the engine your
 workspace pins**, so the editor, the CLI and any agent session are provably running the same code.

package/collections/collections.collection.yaml

@@ -4,10 +4,24 @@ 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: >-
@@ -53,6 +67,15 @@ schema:
             have lived in `modules/<module>/<kind>/` since the 2026-08-05 flatten, and a `system/`
             prefix is only how `runtime.js` recognises a RUNTIME collection in a descriptor compiled
             by a pre-flatten engine.
+        driver:
+          type: string
+          description: >-
+            The name of an engine DRIVER that answers this collection's verbs instead of a folder of
+            files — `docker` is the one shipped (src/containers.js: `containers`, `images`). A driver
+            collection has no records on disk: its derived `path` names a folder that never exists,
+            so check, commit and the store read zero records and never write one; the CLI and the REST
+            route dispatch to the driver first. A string checked against the drivers the engine has,
+            not an enum — one implementation, and a second is a code change, not a vocabulary change.
         codec:
           type: string
           enum: [md, yaml, json, file]

package/collections/containers.collection.yaml

@@ -0,0 +1,81 @@
+name: containers
+description: >-
+  A workspace running as a container — one person's editor, harness and compiled workspace over a
+  named volume set, answered over the Docker Engine API rather than from a folder of files.
+use_when: >-
+  a workspace has to RUN somewhere for someone — `dt start container <name> --template <t>` makes
+  one and prints its editor URL; `dt list containers` says what is running and where; `stop`, `open`,
+  `rm` are the lifecycle. Not a record: nothing lands under data/, nothing is committed, and Docker
+  keeps the history
+# MACHINERY WITH A DRIVER, NOT A RECORD COLLECTION. `storage.driver: docker` says every verb on this
+# collection is answered by src/containers.js over the Engine API: `list` is GET /containers/json,
+# `get` is an inspect, `add`/`start` create-and-start, `rm` removes. The derived storage.path names a
+# folder that never exists, so every walker (check, commit, the store's index) reads zero records here
+# and never writes one; the REST route and the CLI dispatch to the driver before the store is asked.
+# `group: system` folds it out of the orientation block's domain listing, beside `repos` and the
+# compiled kinds, which is where a stranger's mental model puts "the thing my workspace runs in".
+storage:
+  driver: docker
+schema:
+  type: object
+  required: [name, template]
+  properties:
+    # ---- identity ----
+    name:
+      type: string
+      description: The workspace name — also the container name and the stem of its three volumes (`dreamteamer-<name>-workspace` · `-home` · `-files`).
+    template:
+      type: string
+      description: The template it was made from — an image carrying `dreamteamer.template`, `dreamteamer.ports` and `dreamteamer.modules` labels; `--template hq` resolves to `<DT_REGISTRY>/hq:<DT_TEMPLATE_TAG>` or to `DT_IMAGE_hq`.
+    image:
+      type: string
+      description: The image reference the container runs.
+    id:
+      type: string
+      description: Docker's short id.
+    # ---- runtime ----
+    state:
+      type: string
+      enum: [created, running, paused, restarting, exited, dead]
+      description: Docker's container state.
+    status:
+      type: string
+      description: Docker's own phrase — `Up 2 hours`, `Exited (0) 3 minutes ago`.
+    started:
+      type: string
+      format: date-time
+      description: When it last started.
+    # ---- network ----
+    editor_url:
+      type: string
+      description: Where the person opens the editor — `http://localhost:<port>/?folder=<workspace dir>`; the host port comes from DT_PORT_BASE upward, bound to DT_BIND (127.0.0.1).
+    port:
+      type: integer
+      description: The host port the editor is published on.
+    bind:
+      type: string
+      description: The host address it is bound to — loopback unless the host .env says otherwise.
+    # ---- storage ----
+    workspace_dir:
+      type: string
+      description: Where the workspace is mounted inside — `/workspaces/<name>`, the dev-container convention.
+    volumes:
+      type: object
+      description: The three named volumes — `workspace` (the repo), `home` (the person's logins and editor settings), `files` (FILES_FOLDER). Plain `rm` keeps them; `rm --force` removes them.
+    mounts:
+      type: array
+      items: { type: string }
+      description: Extra bind or volume mounts passed as `--mount <host-path|volume>:<container-path>[:ro]`.
+    # ---- person ----
+    person:
+      type: string
+      description: Whose container this is — the git identity injected as env; the harness login happens INSIDE, once, and is never injected.
+    # ---- provenance ----
+    created:
+      type: string
+      format: date-time
+      description: When Docker created it.
+order: 146
+list_fields: [name, template, state, editor_url, person]
+icon: deployed_code
+group: system

package/collections/images.collection.yaml

@@ -0,0 +1,46 @@
+name: images
+description: >-
+  A template a workspace container is made from — a Docker image carrying the `dreamteamer.template`,
+  `dreamteamer.ports` and `dreamteamer.modules` labels — as the local Docker holds it.
+use_when: >-
+  choosing what a container runs — `dt list images` shows the templates present, `dt add image
+  --template <t>` pulls one, `dt rm image <ref>` removes one; a template is an IMAGE WITH LABELS, not
+  a record here, so there is nothing to author — publish an image with the labels and it appears
+# The second driver-backed collection (see containers.collection.yaml for what that means). `list` is
+# GET /images/json filtered to the template label, `get` an inspect, `add --template` a pull, `rm` a
+# delete. No records, no folder, no commit.
+storage:
+  driver: docker
+schema:
+  type: object
+  required: [image]
+  properties:
+    # ---- identity ----
+    image:
+      type: string
+      description: The image reference — `<registry>/<template>:<tag>`.
+    template:
+      type: string
+      description: The `dreamteamer.template` label — the word `--template` takes.
+    id:
+      type: string
+      description: Docker's image id.
+    # ---- what it runs ----
+    ports:
+      type: string
+      description: The `dreamteamer.ports` label — the in-container port the editor listens on (8080 by convention).
+    modules:
+      type: string
+      description: The `dreamteamer.modules` label — the modules the template installs, comma-separated.
+    # ---- size and time ----
+    size_mb:
+      type: integer
+      description: Image size in megabytes.
+    created:
+      type: string
+      format: date
+      description: When the image was built.
+order: 147
+list_fields: [template, image, size_mb, created]
+icon: layers
+group: system

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.27.0",
+	"version": "0.29.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>",
@@ -29,7 +29,8 @@
 		"node": ">=20"
 	},
 	"bin": {
-		"dreamteamer": "bin/dreamteamer.js"
+		"dreamteamer": "bin/dreamteamer.js",
+		"dt": "bin/dreamteamer.js"
 	},
 	"files": [
 		"NOTICE",
@@ -49,7 +50,7 @@
 		"express": "^5.2.1",
 		"fractional-indexing": "^4.0.0",
 		"js-yaml": "^4.1.0",
-		"yaml": "2.8.1"
+		"yaml": "2.8.4"
 	},
 	"dreamteamer": {
 		"title": "System"

package/skills/using-dreamteamer/SKILL.md

@@ -59,6 +59,7 @@ 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):
 
+- a collection may be spelled in the SINGULAR on any of these (`dt add task "call the bank"` — one bare positional is the title); references inside records still spell the full name
 - read & measure — `list` `get` `values` `history` `diff` `next` `relations` `resolve`
 - write & publish — `add` `set` `rm` `rename` `move` `revert` `commit`
 - 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)

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

@@ -112,3 +112,24 @@ prefers. Nothing about the code moves; `check` and `compile` read only what desc
 | hand-writing the first descriptor | `dt add collections` is compile-gated and publishes itself; hand-written sources owe `dt compile` |
 | rewriting existing files to fit a guessed schema | describe reality, compile, `check` — then decide which violations are worth fixing in the data |
 | waiting for a UI before starting | the CLI and the records are the complete system; any surface renders them later, unchanged |
+
+## The editor
+
+The VS Code-family extension is **`dreamteamer.dreamteamer-vscode`** (Marketplace and Open VSX). It
+loads the engine the workspace pins, so the editor, the CLI and an agent session run the same code.
+`init` writes `.vscode/extensions.json` recommending it and `compile` keeps that file current, so a
+VS Code, Cursor or code-server window opened on the workspace offers to install it — that prompt is
+the intended path. From a terminal:
+
+```bash
+code --install-extension dreamteamer.dreamteamer-vscode            # VS Code (on some machines `code` is Cursor)
+code-server --install-extension dreamteamer.dreamteamer-vscode \
+  --extensions-dir <the dir the running server was started with>   # match its --extensions-dir, or the window never sees it
+```
+
+⚠ Inside code-server's own terminal (or an agent it started) that command fails with `error not spawned
+with IPC`: the shell inherits code-server's `VSCODE_*` / `CODE_SERVER_PARENT_PID` variables and the
+CLI thinks it is a forked child. Prefix it with `env -u VSCODE_ESM_ENTRYPOINT -u VSCODE_HANDLES_SIGPIPE
+-u VSCODE_HANDLES_UNCAUGHT_ERRORS -u VSCODE_NLS_CONFIG -u VSCODE_CWD -u VSCODE_RECONNECTION_GRACE_TIME
+-u CODE_SERVER_PARENT_PID`, or let the recommendation prompt do the install. Whether the extension is
+ACTIVE is `dt status`'s `editor:` line — it reads the marker the extension writes on activation.

package/src/cli.js

@@ -16,6 +16,7 @@ import { findWorkspace } from './workspace.js';
 import { compile, staleness, warnIfStale, discoverModules, CHANNEL_LABEL, locationOf, KINDS } from './compile.js';
 import { check } from './check.js';
 import { collectionCommand, emit, relationsCommand, parseArgs, refuseUnknownFlags } from './collections-cli.js';
+import { driverTarget, driverCommand, setup as hostSetup, parseFlags as hostFlags, DRIVER_VERBS, LIFECYCLE_VERBS, CONTAINER_FLAGS } from './containers.js';
 import { init, installClone, update, listRepos } from './init.js';
 import { installCommand, describeCheckout, listWorktrees, worktreeCommand } from './checkout.js';
 import { proveCommand, readLedger, flagEnabled } from './prove.js';
@@ -23,7 +24,7 @@ import { landCommand } from './land.js';
 import { deriveEvents } from './events.js';
 import { commitPending } from './commit.js';
 import { Store } from './store.js';
-import { splitRef } from './ref.js';
+import { splitRef, canonicalCollection } from './ref.js';
 import { envContext, renderTemplate } from './env-vars.js';
 import { exportCommand, EXPORT_FLAGS } from './export-notebooklm.js';
 
@@ -57,8 +58,12 @@ the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee i
                                                case-insensitive variants; date-times sort and
                                                compare as instants, across offsets)
   get    <collection>/<id> [--json]
-  add    <collection> --<field> <value> … [--id <explicit-id>]
-                                              (a codec-file collection takes --from <path>
+  add    <collection> ["<title>"] --<field> <value> … [--id <explicit-id>]
+                                              (ONE bare positional fills the collection's title
+                                               field — the one its title_template names — so
+                                               dt add task "call the bank" is
+                                               dt add tasks --name "call the bank".
+                                               a codec-file collection takes --from <path>
                                                instead — the file IS the record, fields derive;
                                                --force replaces an existing file record.
                                                A repeated --<field> is one ELEMENT of an array
@@ -164,6 +169,12 @@ collection: the ENGINE does not read one, and \`rename-field\` was the only capa
                              title_template, id.generate, a ui-view's options.columns and filter,
                              and a command-binding's can-enter/can-exit. ONE commit)
 
+Every <collection> above may be spelled in the SINGULAR: dt add task …, dt get task/<id>,
+dt list meeting-analysis, dt add-field task …. The singular is derived from the descriptor
+(tasks → task, companies → company) and authored on it as singular: where inflection is
+wrong (people → person); compile refuses two collections whose words collide. A REFERENCE
+inside a record still names the collection in full — tasks/kickoff, never task/kickoff.
+
 Every verb that MOVES records or CLEARS values takes --dry-run and prints its plan first:
     records N · refs M · descriptors K · values cleared V
 
@@ -232,6 +243,31 @@ workspace verbs:
               and one \`proofs:\` line counting each proof's LAST verdict on this machine
               [--strict] exit 1 when any proof's ledger tail is a FAIL
   start       serve the clean REST api at /api [--port <n>]
+
+containers — a workspace as a running container (Docker Engine API over its socket, no dependency;
+these verbs work with NO workspace, so npm i -g dreamteamer and Docker Desktop are enough):
+  setup       make THIS MACHINE ready: checks Docker, writes ~/.dreamteamer/.env with its defaults
+              (DT_PORT_BASE 8100 · DT_BIND 127.0.0.1 · DT_REGISTRY · DT_TEMPLATE_TAG ·
+              DT_DOCKER_TIMEOUT 30 — seconds a request to Docker may sit idle before the verb
+              fails), lists the templates present, pulls one on request [--template <t>] [--json]
+  start       container <name> --template <t>   create-if-absent and start: a code-server editor at
+              http://localhost:<port>/?folder=/workspace over a compiled workspace, three named volumes
+              (workspace · home · files), image <DT_REGISTRY>/<template>:<tag> or DT_IMAGE_<template>.
+              The workspace is mounted at /workspaces/<name>. Idempotent. NO token is ever injected —
+              log in INSIDE, once; the home volume keeps it.
+              [--repo <git url>]  clone an EXISTING workspace into the volume on first start, instead
+                                  of laying the template down — how a person joins one on GitHub
+              [--mount <host-path|volume>:<container-path>[:ro]]  extra mounts, repeatable
+              [--name <git name>] [--email <git email>] [--no-open] [--json]
+  stop        container <name>                  stop it; every volume kept [--json]
+  open        container <name>                  print (and open) its editor URL [--no-open]
+              [--vscode]  print (and open) the Dev Containers attach URI instead — the host's own
+                          VS Code inside the container, extensions from the image's metadata label
+  list        containers | images               the record verbs, answered over Docker instead of a
+  get         container <name> | image <ref>    folder — singular or plural, either spelling.
+  rm          container <name> [--force]        plain rm keeps the volumes; --force removes them too
+  add         image --template <t>              pull a template's image; rm image <ref> removes one
+
   changes     what changed in every repo that holds records, as record events
               [--since <sha|YYYY-MM-DD>] (default: HEAD~1 — the last commit's own changes) [--json]
   commit      publish records already written to disk: samples git status over every
@@ -286,7 +322,10 @@ export const GLOBAL_FLAGS = ['vault'];
 export const WORKSPACE_FLAGS = {
 	init: ['name', 'data-path', 'harnesses', 'workspace-module'], update: [],
 	install: ['clone', 'dry-run', 'json', 'link-env', 'all', 'hook', 'print-adapters'],
-	start: ['port'], compile: ['watch'], check: [], status: ['strict'],
+	// `start` is TWO forms: bare, the REST api (--port); with a `container <name>` target, the
+	// lifecycle verb — whose flags are the driver's. One table, because `flags-honoured` reads it.
+	start: ['port', ...CONTAINER_FLAGS], compile: ['watch'], check: [], status: ['strict'],
+	setup: ['template', 'json'], stop: ['json'], open: ['json', 'no-open', 'vscode'],
 	changes: ['since', 'json'], commit: ['dry-run', 'json'],
 	export: EXPORT_FLAGS,
 	// the UNION of every form's flags — the outer typo gate. Which flags each FORM takes is refused
@@ -299,6 +338,15 @@ export const WORKSPACE_FLAGS = {
 export function run(argv) {
 	const [cmd, ...rest] = argv;
 	try {
+		// HOST VERBS resolve BEFORE workspace discovery: `setup`, and any verb whose target is a
+		// driver collection (`containers`, `images`, singular or plural). They answer identically on a
+		// bare machine — `npm i -g dreamteamer` and Docker Desktop, nothing else — and inside a
+		// workspace, because the thing they make IS the workspace (src/containers.js).
+		const host = hostDispatch(cmd, rest);
+		if (host) {
+			host.then((code) => process.exit(code)).catch((e) => { console.error(`✖ ${e.message}`); process.exit(1); });
+			return;
+		}
 		if (cmd in WORKSPACE_FLAGS) {
 			const bad = rest.filter((a) => a.startsWith('--')).map((a) => a.slice(2).split('=')[0]).find((f) => !WORKSPACE_FLAGS[cmd].includes(f));
 			if (bad) throw new Error(`unknown flag "--${bad}" on \`dt ${cmd}\`\n  known: ${WORKSPACE_FLAGS[cmd].map((f) => `--${f}`).join(', ') || '(none — this verb takes no flags)'}`);
@@ -315,7 +363,9 @@ export function run(argv) {
 			for (let i = 0; i < rest.length; i++) if (rest[i].startsWith('--')) flags[rest[i].slice(2)] = rest[i + 1];
 			process.exit(init({ flags }));
 		}
-		if (!cmd) {
+		if (!cmd || cmd === 'help') {
+			// `help` works OUTSIDE a workspace too — the host verbs above do, and a person who just ran
+			// `npm i -g dreamteamer` on a bare machine has nothing else to read.
 			emit(USAGE);
 			process.exit(0);
 		}
@@ -507,6 +557,16 @@ export function run(argv) {
 					process.exit(1);
 				}
 				console.log(`compiled: ${s.manifest.compiled}`);
+				// THE EDITOR, from the marker the extension writes on activation (`.dreamteamer/editor.json`).
+				// Without it an agent working inside the editor could not tell whether the extension was
+				// installed, active, or refusing the engine — the operator had to report "no icon".
+				try {
+					const marker = path.join(ws.root, '.dreamteamer', 'editor.json');
+					if (fs.existsSync(marker)) {
+						const e = JSON.parse(fs.readFileSync(marker, 'utf8'));
+						console.log(`editor: ${e.extension ?? 'dreamteamer-vscode'} ${e.version ?? '?'} · ${e.state ?? 'active'} ${e.activated ?? ''} · engine ${e.engine ?? '?'}${e.host ? ` · ${e.host}` : ''}`);
+					} else console.log('editor: not detected — the extension dreamteamer.dreamteamer-vscode writes .dreamteamer/editor.json when it activates on this workspace');
+				} catch { console.log('editor: marker unreadable — .dreamteamer/editor.json is not JSON'); }
 				// provenance is LIVE discovery (not the manifest) — shows what the next compile would use
 				const { modules, shadows } = discoverModules(ws.root, ws.pkg);
 				const shadowed = new Map(shadows.map((sh) => [sh.name, sh]));
@@ -661,7 +721,8 @@ export function run(argv) {
 				if (!target || target.startsWith('--')) {
 					throw new Error(`dt ${cmd} needs a collection: dreamteamer ${cmd} <collection> --name <field> …`);
 				}
-				process.exit(collectionCommand(ws, target, cmd, flagArgs));
+				// the singular is legal here too: `dt add-field task --name due …`
+				process.exit(collectionCommand(ws, canonicalCollection(new Store(ws).descriptors, target) ?? target, cmd, flagArgs));
 			}
 			case 'relations':
 				warnIfStale(ws.root);
@@ -728,6 +789,25 @@ export function run(argv) {
 	}
 }
 
+/** The verbs that run with no workspace. Returns a promise of an exit code, or null when the
+ *  command is not ours and the ordinary workspace dispatch should take it. */
+function hostDispatch(cmd, rest) {
+	if (cmd === 'setup') {
+		const bad = rest.filter((a) => a.startsWith('--')).map((a) => a.slice(2).split('=')[0]).find((f) => !WORKSPACE_FLAGS.setup.includes(f));
+		if (bad) throw new Error(`unknown flag "--${bad}" on \`dt setup\`\n  known: ${WORKSPACE_FLAGS.setup.map((f) => `--${f}`).join(', ')}`);
+		return hostSetup(hostFlags(rest).flags);
+	}
+	const target = driverTarget(rest[0]);
+	if (target && DRIVER_VERBS.has(cmd)) return driverCommand(cmd, target, rest.slice(1));
+	// A lifecycle verb aimed at anything else is refused by name: `dt start tasks` is not a
+	// server and not a container, and "unknown collection" would send the reader the wrong way.
+	if (LIFECYCLE_VERBS.has(cmd) && rest[0] && !rest[0].startsWith('--')) {
+		return Promise.reject(new Error(`\`${cmd}\` is a container lifecycle verb — "${rest[0]}" is not a container. dt ${cmd} container <name>${cmd === 'start' ? ' --template <t>' : ''}${cmd === 'start' ? '; a bare `dt start` serves the REST api' : ''}`));
+	}
+	if (cmd === 'stop' || cmd === 'open') return Promise.reject(new Error(`dt ${cmd} container <name> — see \`dreamteamer help\``));
+	return null;
+}
+
 /** Translate `dt <verb> <target> …` into the noun-verb call the implementation layer takes. */
 function dispatchRecordVerb(ws, verb, args) {
 	const [target, ...rest] = args;
@@ -735,18 +815,22 @@ function dispatchRecordVerb(ws, verb, args) {
 	// A flag in the target slot is a word-order mistake, not a collection: without this,
 	// `dt list --json contacts` reported `unknown collection "--json"` and dumped every name.
 	if (target.startsWith('--')) throw new Error(`dt ${verb} takes its target BEFORE the flags: dreamteamer ${verb} <target> ${target} …`);
-	if (COLLECTION_VERBS.has(verb)) return collectionCommand(ws, target, verb, rest);
+	// A collection may be named by its declared name OR its singular (`dt add task …`); the
+	// canonical name is what every layer below sees. An unknown word passes through unchanged so
+	// the store's own "unknown collection" sentence, which lists what exists, is the one printed.
+	const { descriptors } = new Store(ws);
+	const canonical = canonicalCollection(descriptors, target) ?? target;
+	if (COLLECTION_VERBS.has(verb)) return collectionCommand(ws, canonical, verb, rest);
 	if (REF_VERBS.has(verb)) {
-		const { collection, id } = splitRef(new Store(ws).descriptors, target);
+		const { collection, id } = splitRef(descriptors, target);
 		return collectionCommand(ws, collection, verb, [id, ...rest]);
 	}
 	// EITHER_VERBS from here: a bare collection is legal for both — `move <collection> --init`,
 	// `next <collection>`.
-	const { descriptors } = new Store(ws);
-	if (descriptors.has(target)) {
+	if (descriptors.has(canonical)) {
 		return verb === 'move'
-			? collectionCommand(ws, target, 'move', rest)
-			: collectionCommand(ws, 'commands', 'for', [target, ...rest]);
+			? collectionCommand(ws, canonical, 'move', rest)
+			: collectionCommand(ws, 'commands', 'for', [canonical, ...rest]);
 	}
 	const { collection, id } = splitRef(descriptors, target);
 	if (verb === 'move') return collectionCommand(ws, collection, 'move', [id, ...rest]);

package/src/collections-cli.js

@@ -179,6 +179,16 @@ export function collectionCommand(ws, collection, verb, args) {
 				return 0;
 			}
 			if (flags.from) throw new Error(`--from imports a file as a record, and "${collection}" is not a \`codec: file\` collection`);
+			// ONE bare positional is the record's title — the field `title_template` names — so
+			// `dt add task "call the bank"` reads as a sentence. Two positionals is a mistake (a flag
+			// value that lost its flag), and so is giving the title twice; both are refused by name.
+			if (pos.length > 1) throw new Error(`dt add ${collection} takes ONE positional (the title) and flags for the rest — got ${pos.length}: ${pos.map((p) => `"${p}"`).join(' ')}`);
+			if (pos.length === 1) {
+				const titleField = /\{\{\s*([A-Za-z_][\w]*)/.exec(d.title_template ?? '')?.[1];
+				if (!titleField || titleField === 'id') throw new Error(`"${collection}" labels its records by id, so there is no title field for "${pos[0]}" to fill — pass fields as --<field> <value>`);
+				if (titleField in flags) throw new Error(`the title was given twice — "${pos[0]}" and --${titleField} ${JSON.stringify(flags[titleField])}`);
+				flags[titleField] = pos[0];
+			}
 			const fields = coerceArrays(d, stripMeta(flags));
 			const { id, file, idFallback } = store.add(collection, fields, { id: flags.id });
 			flags.json

package/src/commit.js

@@ -7,7 +7,7 @@ import path from 'node:path';
 import { pathToRecord } from './events.js';
 import { parseRecordText } from './records.js';
 import { relationsOf } from './relations.js';
-import { splitRef } from './ref.js';
+import { splitRef, canonicalCollection } from './ref.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -42,7 +42,8 @@ function parseTargets(descriptors, only) {
 	const whole = new Set();
 	const records = new Map();
 	for (const target of only) {
-		if (descriptors.has(target)) { whole.add(target); scope.add(target); continue; }
+		const asCollection = canonicalCollection(descriptors, target);
+		if (asCollection) { whole.add(asCollection); scope.add(asCollection); continue; }
 		const { collection, id } = splitRef(descriptors, target);
 		records.set(`${collection}/${id}`, { collection, id });
 		scope.add(collection);