dreamteamer 0.27.0 → 0.28.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: >-

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.27.0",
+	"version": "0.28.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,24 @@ 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), 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>.
+              Idempotent. NO token is ever injected — log in INSIDE, once; the home volume keeps it.
+              [--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]
+  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 +315,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'],
 	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 +331,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 +356,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 +550,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 +714,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 +782,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 +808,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);

package/src/compile.js

@@ -16,7 +16,8 @@ import {
 	baseNameOf, singular, namespaceOf } from './namespace.js';
 // circular on paper in earlier versions — safe: both sides only
 // call at run time, same pattern as store.js ↔ compile.js.
-import { runHarnessAdapters } from './harnesses.js';
+import { runHarnessAdapters, BEGIN, END, INSTRUCTIONS_BEGIN, INSTRUCTIONS_END } from './harnesses.js';
+import { ensureEditorRecommendation, ensureEnvExample } from './workspace.js';
 import { satisfies } from './semver.js';
 import { parseEnvValues } from './env-vars.js';
 import { DERIVED_KINDS, readManifest, runtimeDir, engineId, engineVersion } from './runtime.js';
@@ -676,7 +677,9 @@ export function compile({ root, pkg }) {
 	// what every message in this engine already calls it. Defined HERE, above the namespace pass,
 	// because a namespace error has to name the module by the id the fix is typed with.
 	const moduleId = (n) => slug(String(n).replace(/^@[^/]+\//, ''));
+	const channelOf = new Map(sources.map((s) => [s.name, s.channel]));
 	const declaredEnv = new Map(); // env key -> [module names]
+	const envMeta = new Map();     // env key -> { description, example } — the first module to say wins
 	const moduleIgnores = new Map(); // module name -> non-source folders it declares (strayKindDirs)
 	const moduleDeps = new Map();  // module name -> [module names]      — HARD, must be acyclic
 	const modulePeers = new Map(); // module name -> [collection names]  — SOFT, cannot cycle
@@ -717,9 +720,17 @@ export function compile({ root, pkg }) {
 			if (ok === false) console.warn(`⚠ module ${source.name} declares engine "${range}" — running engine is ${engineVer} (out of range; compile continues)`);
 			else if (ok === null) console.warn(`⚠ module ${source.name}: engine range "${range}" not understood by the built-in checker (see src/semver.js) — not verified`);
 		}
-		for (const k of mpkg.dreamteamer?.env ?? []) {
+		// `dreamteamer.env`: a bare key name, or `{ name, description, example }` so the warning and
+		// `.env.example` can say what the key IS and what a value looks like — a bare `WORK_CALENDARS`
+		// told a first-run operator nothing about ids, addresses or display names (2026-09-24).
+		const envDecl = mpkg.dreamteamer?.env ?? [];
+		if (!Array.isArray(envDecl)) fail(`module "${source.name}": dreamteamer.env must be a list of key names or { name, description, example } objects (got ${JSON.stringify(envDecl)})`);
+		for (const entry of envDecl) {
+			const k = typeof entry === 'string' ? entry : entry?.name;
+			if (typeof k !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(k)) fail(`module "${source.name}": dreamteamer.env entry ${JSON.stringify(entry)} — a key is an identifier (A-Z, 0-9, _) as a string or as { name, description, example }`);
 			if (!declaredEnv.has(k)) declaredEnv.set(k, []);
 			declaredEnv.get(k).push(source.name);
+			if (typeof entry === 'object' && !envMeta.has(k)) envMeta.set(k, { description: entry.description ? String(entry.description) : undefined, example: entry.example !== undefined ? String(entry.example) : undefined });
 		}
 		// Gathered here because mpkg is already parsed; refused below, next to the workspace's own
 		// declaration. The classic layout pushes the ROOT itself as an inline source, whose
@@ -758,7 +769,8 @@ export function compile({ root, pkg }) {
 			const present = new Set([...parsedEnv].filter(([, v]) => v.trim() !== '').map(([k]) => k));
 			for (const [k, mods] of declaredEnv) {
 				if (present.has(k)) continue;
-				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k} — missing from .env (see .env.example)`);
+				const about = envMeta.get(k)?.description ? ` (${envMeta.get(k).description})` : '';
+				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k}${about} — missing from .env (see .env.example)`);
 			}
 			for (const k of declaredVars) {
 				if (present.has(k)) continue;
@@ -767,6 +779,17 @@ export function compile({ root, pkg }) {
 		}
 	}
 
+	// Two root files kept current on every compile, both cheap and both about the FIRST run of a
+	// stranger: `.env.example` lists every declared key with its description, so the warning above
+	// points at a file that actually names them; `.vscode/extensions.json` recommends the editor
+	// extension, so the first window offers it. Both are append/merge-only — nothing authored moves.
+	{
+		const added = ensureEnvExample(root, [...declaredEnv].map(([key, mods]) => ({ key, modules: mods, ...(envMeta.get(key) ?? {}) })),
+			'# secrets for skills and modules go here (copy to .env; .env is never committed).\n# modules declare the env keys they require in their package.json dreamteamer.env list.\n');
+		if (added.length) console.log(`✔ .env.example now names ${added.join(', ')}`);
+		ensureEditorRecommendation(root);
+	}
+
 	// ---- local-assets and postinstall: what `dt install` will do to a checkout -------
 	// `local-assets` are the gitignored heavy folders a checkout SHARES by symlink instead of
 	// duplicating — a browser profile dir, a model cache. Declared, never discovered. Every
@@ -1093,6 +1116,7 @@ export function compile({ root, pkg }) {
 	let mergedCount = 0;
 	let templatedCount = 0;
 	const storageEntries = []; // {name, path, base} per collection — checked for overlap after the loop
+	const wordEntries = [];    // {name, word: singular} per collection — checked for collisions after the loop
 	// Merged descriptors are held, NOT dumped, until every one of them exists: a relation spans two
 	// collections, and the second is not merged yet when the first is reached. So this loop resolves
 	// and validates each descriptor on its own, `materializeRelations` runs over the whole set, and
@@ -1285,8 +1309,14 @@ export function compile({ root, pkg }) {
 			if (raw === '*') {
 				// The workspace module is the orchestrating parent and may reference anything —
 				// including modules that do not exist yet, which is what `tasks.item` means.
-				// Anywhere else a wildcard is a cross-module surface no declaration can cover.
-				if (!groupModules.includes(wsModuleName)) {
+				// Anywhere else a wildcard is a cross-module surface no declaration can cover — and
+				// it is the MODULE AUTHOR's to cover, so the warning is raised only where the author
+				// is: a module in this tree (inline). A module installed from npm or a clone is
+				// somebody else's source; warning its consumers about it on every compile told a
+				// first-run operator four things they could not fix (2026-09-24). The module's own
+				// CI, compiling it alone, still sees them.
+				const authoredHere = groupModules.some((m) => (channelOf.get(m) ?? 'inline') === 'inline');
+				if (!groupModules.includes(wsModuleName) && authoredHere) {
 					console.warn(`⚠ collection ${name}: field "${at}" uses x-reference: '*' outside the workspace module — an unverifiable cross-module surface; name the collections it may target`);
 				}
 				continue;
@@ -1380,6 +1410,16 @@ export function compile({ root, pkg }) {
 		// for `meta.title_field`, promoted to an authorable field. Reference fields pointing here
 		// inherit it (presentation.js), which is what replaces 51 hand-written `x-display` lines.
 		merged.title_template ??= `{{ ${['title', 'name', 'subject'].find((f) => f in labelProps) ?? 'id'} }}`;
+		// The word the CLI accepts beside the name (`dt add task …`). DERIVED by the same inflection
+		// the storage suffix already uses, with the namespace kept (`rnd/projects` → `rnd/project`),
+		// so the two never disagree; AUTHORED where inflection is wrong (`people` → `person`).
+		// Collisions are refused after the loop, once every descriptor has one.
+		if (merged.singular !== undefined && (typeof merged.singular !== 'string' || !merged.singular.trim())) fail(`collection "${name}": \`singular\` must be a non-empty string`);
+		if (merged.singular === undefined) {
+			const ns = namespaceOf(name, namespaces);
+			merged.singular = ns ? `${ns}/${singular(baseNameOf(name, namespaces))}` : singular(name);
+		}
+		wordEntries.push({ name, word: merged.singular });
 		for (const [fieldName, prop] of Object.entries(labelProps)) {
 			if (!prop || typeof prop !== 'object' || Array.isArray(prop)) continue;
 			prop.title ??= titleCase(fieldName);
@@ -1445,6 +1485,19 @@ export function compile({ root, pkg }) {
 	// `owns-data` module prefix and any authored override all already applied). See
 	// namespace.storageOverlaps for what this silently did before it was checked.
 	for (const p of storageOverlaps(storageEntries)) fail(p);
+	// Two collections that answer to one word would make `dt add <word>` a coin toss, so the set of
+	// words — every name and every singular — must be injective. Refused with both names, because
+	// the fix is an authored `singular:` on one of them and the author needs to know which two.
+	{
+		const owners = new Map(); // word -> name
+		for (const { name } of wordEntries) owners.set(name, name);
+		for (const { name, word } of wordEntries) {
+			if (word === name) continue;
+			const other = owners.get(word);
+			if (other && other !== name) fail(`collections "${name}" and "${other}" both answer to the word "${word}" (a name or a singular) — author \`singular:\` on one of them so \`dt add ${word}\` names exactly one collection`);
+			owners.set(word, name);
+		}
+	}
 
 	// ---- modules, projected ---------------------------------------------------------
 	// One record per discovered module, written from what discovery and the package pass already
@@ -1526,6 +1579,19 @@ export function compile({ root, pkg }) {
 		counts.modules = (counts.modules ?? 0) + 1;
 	}
 
+	// ---- the workspace's own hand-written instructions -------------------------------
+	// ONE source, rendered verbatim into every harness's instruction file. It is registered as a
+	// manifest entry for exactly one reason: `staleness` walks manifest sources, so a file that is
+	// not one can be edited forever without `dt status` ever saying the harness files lag it — and a
+	// silent lag on the file carrying the operator's rules is the worst possible thing to be silent
+	// about. The runtime copy is never read by anything; the manifest ENTRY is the whole point.
+	const instructionsPath = path.join(root, INSTRUCTIONS_SOURCE);
+	if (fs.existsSync(instructionsPath)) {
+		const bytes = fs.readFileSync(instructionsPath);
+		refuseManagedMarkers(bytes.toString('utf8'), rel(instructionsPath));
+		entries.set('instructions.md', { sources: [{ path: rel(instructionsPath), hash: sha256(bytes) }], bytes });
+	}
+
 	// ---- unresolved references are compile errors (an agent's declared skills)
 	const skillIds = new Set([...entries.keys()].filter((k) => k.startsWith('skills/')).map((k) => k.split('/')[1]));
 	for (const [rt, e] of entries) {
@@ -1877,6 +1943,14 @@ export function staleness(root) {
 			}
 		}
 	}
+	// ⚠ `dreamteamer.md` is a compile source that is NOT under a KIND directory, so the walk above
+	// cannot reach it — and its CREATION is the one moment that matters most: day one in an adopting
+	// workspace, when no harness file carries an instructions block yet. Every later EDIT was already
+	// caught by the manifest-source walk at the top of this function; only the first write was silent,
+	// and it reported `.dreamteamer is fresh` while the rules reached no agent at all.
+	if (fs.existsSync(path.join(root, INSTRUCTIONS_SOURCE)) && !known.has(INSTRUCTIONS_SOURCE)) {
+		stale.push(`${INSTRUCTIONS_SOURCE} (new, uncompiled)`);
+	}
 	return { compiled: true, stale, manifest };
 }
 
@@ -1965,6 +2039,42 @@ function descriptorAjv() {
 	return _descriptorAjv;
 }
 
+// ⚠ A MANAGED MARKER INSIDE `dreamteamer.md` IS A REFUSAL, not something to escape around.
+// The file is rendered VERBATIM into a managed block, and `writeBlock` finds that block by the FIRST
+// occurrence of its begin marker anywhere in the file — so a marker quoted inside the rendered text
+// is found before the real delimiter. Both directions were measured on a fixture:
+//
+//   - quoting the ORIENTATION pair: the orientation pass rewrites the quoted region, the instructions
+//     pass that runs immediately after restores it from source, and the real orientation block is
+//     never touched again. It silently keeps describing the schema of the day it was written, while
+//     `compile` exits 0 and `status` reports the runtime fresh.
+//   - quoting the INSTRUCTIONS end marker: the block is closed at the quote and a second end line is
+//     appended, so all three committed root files grow by ~40 bytes and one duplicated line per
+//     compile, without ever reaching a fixed point.
+//
+// Escaping the markers on the way out is the alternative, and it is not one: the whole promise of
+// this file is that what was written is what every agent reads, and an escaped marker is not that.
+// A rule ABOUT the block describes it instead of quoting it.
+/** The one hand-written root source. Named once: `compile` reads it and `staleness` looks for it. */
+export const INSTRUCTIONS_SOURCE = 'dreamteamer.md';
+
+const MANAGED_MARKERS = [
+	['the orientation block', BEGIN],
+	['the orientation block', END],
+	['the instructions block', INSTRUCTIONS_BEGIN],
+	['the instructions block', INSTRUCTIONS_END],
+];
+
+function refuseManagedMarkers(text, srcPath) {
+	const lines = text.split('\n');
+	for (const [i, line] of lines.entries()) {
+		for (const [which, marker] of MANAGED_MARKERS) {
+			if (!line.includes(marker)) continue;
+			fail(`${srcPath}:${i + 1}: contains the managed marker ${marker}, which delimits ${which} in the harness files. This source is rendered verbatim into that block, so the quoted copy is found before the real delimiter and the block is rewritten around the wrong place. Describe the block instead of quoting its marker.`);
+		}
+	}
+}
+
 function fail(msg) {
 	throw new CompileError(`compile error: ${msg}`);
 }

package/src/containers.js

@@ -0,0 +1,422 @@
+// containers.js — `containers` and `images` as verbs over the Docker Engine API. The one storage
+// DRIVER in core: a workspace becomes a running container (`dt start container <name> --template
+// <t>`), the person opens code-server at a loopback URL, and the same record verbs — list · get ·
+// add · rm — answer over Docker instead of over a folder of files.
+//
+// WHY THIS IS CORE AND NOT A MODULE. A module ships collections, skills, commands and views INTO a
+// workspace; every one of them needs a compiled runtime to exist. This runs BEFORE any workspace
+// exists — `npm i -g dreamteamer && dt setup && dt start container …` on a machine with nothing
+// but Docker Desktop — and a module has no place to stand there. That is the "could a module do it"
+// question, answered: no, because the thing being made IS the workspace.
+//
+// WHY THERE IS NO DEPENDENCY. The Engine API is HTTP over a Unix socket (a named pipe on Windows),
+// and `node:http` takes `socketPath`. Measured 2026-09-24 against Docker Desktop 29.3.1 / API 1.54:
+// /version, /containers/json and /images/json all answered from a bare `node -e`. The ONE call the
+// API makes awkward is `POST /build`, which wants a tar stream Node core cannot produce — so
+// templates ship PREBUILT (a registry pull is `POST /images/create`, streamed JSON lines) and a
+// local build is the `docker` CLI Docker Desktop installs anyway, never this file.
+//
+// WHAT A DRIVER COLLECTION IS NOT. Not records: nothing under `data/`, nothing `dt commit` sees,
+// nothing `dt check` reads, no history (Docker keeps its own). It is not compiled into
+// `.dreamteamer/collections` either — these two nouns resolve HERE, ahead of workspace discovery,
+// so `dt list containers` answers identically inside a workspace and on a bare host.
+//
+// TEST KNOBS, stated once: `DT_DOCKER_SOCKET` points the client at any socket (a fake in tests);
+// `DT_HOME` relocates `~/.dreamteamer`; `DT_HEALTH_TIMEOUT=0` skips the wait for code-server's
+// /healthz. None is documented in help — they are how the suite drives this file without Docker.
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync, spawn } from 'node:child_process';
+import { parseEnvValues } from './env-vars.js';
+import { emit } from './collections-cli.js';
+
+// ---- the two nouns, singular and plural --------------------------------------------------------
+// The operator's spelling is `dt start container hq-dana` and `dt list containers`; both resolve.
+// This is the singular map for the driver collections ONLY — the general rule ("every record verb
+// accepts the singular, derived from the descriptor") is a filed feature, not this file's job.
+export const NOUNS = { containers: 'containers', container: 'containers', images: 'images', image: 'images' };
+export const DRIVER_VERBS = new Set(['list', 'get', 'add', 'rm', 'start', 'stop', 'open']);
+export const LIFECYCLE_VERBS = new Set(['start', 'stop', 'open']);
+
+/** `containers`, `container`, `containers/<id>` → { collection, id }; null when the word is not ours. */
+export function driverTarget(word) {
+	if (!word || word.startsWith('--')) return null;
+	const slash = word.indexOf('/');
+	const noun = slash === -1 ? word : word.slice(0, slash);
+	const collection = NOUNS[noun];
+	if (!collection) return null;
+	return { collection, id: slash === -1 ? undefined : word.slice(slash + 1) };
+}
+
+// ---- host configuration: ~/.dreamteamer/.env ---------------------------------------------------
+export const HOST_DEFAULTS = {
+	DT_PORT_BASE: '8100',       // NOT 8080: that is code-server's in-container port, `dt start`'s REST default, and the old dev image's exposed port — three things on one number
+	DT_BIND: '127.0.0.1',       // loopback only; a remote tier puts auth in front before this changes
+	DT_REGISTRY: 'dreamteamer', // `<registry>/<template>:<tag>` is the image a template name resolves to
+	DT_TEMPLATE_TAG: 'latest',
+};
+
+export function hostDir() { return process.env.DT_HOME ?? path.join(os.homedir(), '.dreamteamer'); }
+
+/** Defaults, then the file, then the process env — the same precedence a shell would give. */
+export function hostEnv() {
+	const file = path.join(hostDir(), '.env');
+	// parseEnvValues answers a Map — spread it as entries, or the file silently contributes nothing.
+	const fromFile = fs.existsSync(file) ? Object.fromEntries(parseEnvValues(fs.readFileSync(file, 'utf8'))) : {};
+	const out = { ...HOST_DEFAULTS, ...fromFile };
+	for (const k of Object.keys(process.env)) if (k.startsWith('DT_') && process.env[k] !== undefined) out[k] = process.env[k];
+	return out;
+}
+
+// ---- the Engine API client ---------------------------------------------------------------------
+export function socketPath() {
+	if (process.env.DT_DOCKER_SOCKET) return process.env.DT_DOCKER_SOCKET;
+	if (process.platform === 'win32') return '//./pipe/docker_engine';
+	for (const p of ['/var/run/docker.sock', path.join(os.homedir(), '.docker', 'run', 'docker.sock')]) {
+		try { if (fs.statSync(p).isSocket()) return p; } catch { /* next */ }
+	}
+	return '/var/run/docker.sock';
+}
+
+function unreachable(sock) {
+	const hint = process.platform === 'darwin' ? ' — is Docker Desktop running? `open -a Docker` starts it' : ' — is the Docker daemon running?';
+	return new Error(`Docker is not reachable at ${sock}${hint}. \`dt setup\` checks this and says what is missing.`);
+}
+
+/** One request. Resolves { status, body } where body is parsed JSON when the response is JSON,
+ *  else the raw text. `onLine` receives each JSON line of a streaming response (a pull). */
+export function api(method, urlPath, body, { onLine } = {}) {
+	const sock = socketPath();
+	return new Promise((resolve, reject) => {
+		const payload = body === undefined ? undefined : JSON.stringify(body);
+		const req = http.request({
+			socketPath: sock, method, path: urlPath,
+			headers: payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {},
+		}, (res) => {
+			let text = '';
+			let pending = '';
+			res.setEncoding('utf8');
+			res.on('data', (chunk) => {
+				text += chunk;
+				if (!onLine) return;
+				pending += chunk;
+				const lines = pending.split('\n');
+				pending = lines.pop();
+				for (const l of lines) if (l.trim()) { try { onLine(JSON.parse(l)); } catch { /* not JSON */ } }
+			});
+			res.on('end', () => {
+				const isJson = /json/.test(res.headers['content-type'] ?? '');
+				let parsed = text;
+				if (isJson && !onLine) { try { parsed = text ? JSON.parse(text) : null; } catch { parsed = text; } }
+				resolve({ status: res.statusCode, body: parsed });
+			});
+		});
+		req.on('error', (e) => reject(e.code === 'ENOENT' || e.code === 'ECONNREFUSED' ? unreachable(sock) : e));
+		if (payload) req.write(payload);
+		req.end();
+	});
+}
+
+/** Throw the daemon's own sentence on a non-2xx, so a refusal reads as Docker's rather than ours. */
+function ok(res, what) {
+	if (res.status >= 200 && res.status < 400) return res.body;
+	const msg = res.body && typeof res.body === 'object' && res.body.message ? res.body.message : String(res.body ?? '').trim();
+	throw new Error(`${what}: Docker answered ${res.status}${msg ? ` — ${msg}` : ''}`);
+}
+
+const LABEL = { workspace: 'dreamteamer.workspace', template: 'dreamteamer.template', person: 'dreamteamer.person', ports: 'dreamteamer.ports', modules: 'dreamteamer.modules' };
+const filters = (label) => encodeURIComponent(JSON.stringify({ label: [label] }));
+
+// ---- images ------------------------------------------------------------------------------------
+export function imageRef(template, env = hostEnv()) {
+	// `DT_IMAGE_<template>=<ref>` pins one template to any image, which is how a local build or a
+	// private registry is reached without the registry default changing for every other template.
+	return env[`DT_IMAGE_${template}`] ?? `${env.DT_REGISTRY}/${template}:${env.DT_TEMPLATE_TAG}`;
+}
+
+const imageRow = (i) => ({
+	image: (i.RepoTags ?? []).find((t) => t !== '<none>:<none>') ?? i.Id.slice(7, 19),
+	template: i.Labels?.[LABEL.template] ?? '',
+	ports: i.Labels?.[LABEL.ports] ?? '',
+	modules: i.Labels?.[LABEL.modules] ?? '',
+	size_mb: Math.round((i.Size ?? 0) / 1e6),
+	created: i.Created ? new Date(i.Created * 1000).toISOString().slice(0, 10) : '',
+	id: i.Id,
+});
+
+export async function listImages() {
+	const body = ok(await api('GET', `/images/json?filters=${filters(LABEL.template)}`), 'list images');
+	return body.map(imageRow).sort((a, b) => a.image.localeCompare(b.image));
+}
+
+export async function inspectImage(ref) {
+	const res = await api('GET', `/images/${encodeURIComponent(ref)}/json`);
+	return res.status === 404 ? null : ok(res, `get image ${ref}`);
+}
+
+export async function pullImage(ref, log = console.error) {
+	const [name, tag] = splitTag(ref);
+	let last = '';
+	const res = await api('POST', `/images/create?fromImage=${encodeURIComponent(name)}&tag=${encodeURIComponent(tag)}`, undefined, {
+		onLine: (l) => { if (l.status && l.status !== last) { last = l.status; log(`  … ${l.status}${l.id ? ` ${l.id}` : ''}`); } if (l.error) throw new Error(l.error); },
+	});
+	if (res.status !== 200) throw new Error(`pull ${ref}: Docker answered ${res.status} — ${String(res.body).trim()}. A local build is \`docker build -t ${ref} …\`, or pin DT_IMAGE_<template> in ${path.join(hostDir(), '.env')}`);
+}
+
+function splitTag(ref) {
+	const at = ref.lastIndexOf(':');
+	const slash = ref.lastIndexOf('/');
+	return at > slash ? [ref.slice(0, at), ref.slice(at + 1)] : [ref, 'latest'];
+}
+
+// ---- containers --------------------------------------------------------------------------------
+const containerRow = (c) => {
+	const name = (c.Names?.[0] ?? '').replace(/^\//, '');
+	const port = (c.Ports ?? []).find((p) => p.PublicPort)?.PublicPort;
+	return {
+		name, template: c.Labels?.[LABEL.template] ?? '', state: c.State, status: c.Status,
+		editor_url: port ? editorUrl(port) : '', image: c.Image, person: c.Labels?.[LABEL.person] ?? '',
+		created: c.Created ? new Date(c.Created * 1000).toISOString().slice(0, 16).replace('T', ' ') : '', id: c.Id,
+	};
+};
+const editorUrl = (port) => `http://localhost:${port}/?folder=/workspace`;
+const volumeNames = (name) => ({ workspace: `dreamteamer-${name}-workspace`, home: `dreamteamer-${name}-home`, files: `dreamteamer-${name}-files` });
+
+export async function listContainers() {
+	const body = ok(await api('GET', `/containers/json?all=1&filters=${filters(LABEL.workspace)}`), 'list containers');
+	return body.map(containerRow).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function inspectContainer(name) {
+	const res = await api('GET', `/containers/${encodeURIComponent(name)}/json`);
+	if (res.status === 404) return null;
+	const c = ok(res, `get container ${name}`);
+	if (!c.Config?.Labels?.[LABEL.workspace]) throw new Error(`"${name}" is a Docker container but not a dreamteamer workspace (no ${LABEL.workspace} label) — this verb only touches containers it made`);
+	return c;
+}
+
+/** The shape `dt get container <name>` prints: the categorised view over `docker inspect`. */
+export function containerDetail(c) {
+	const binding = Object.values(c.HostConfig?.PortBindings ?? {}).flat()[0];
+	const mounts = Object.fromEntries((c.Mounts ?? []).filter((m) => m.Type === 'volume').map((m) => [m.Destination, m.Name]));
+	return {
+		name: c.Name.replace(/^\//, ''), id: c.Id.slice(0, 12),
+		template: c.Config.Labels[LABEL.template] ?? '', image: c.Config.Image,
+		state: c.State?.Status, started: c.State?.StartedAt, restarts: c.RestartCount ?? 0,
+		bind: binding?.HostIp ?? '', port: binding ? Number(binding.HostPort) : undefined,
+		editor_url: binding ? editorUrl(binding.HostPort) : '',
+		volumes: { workspace: mounts['/workspace'] ?? '', home: mounts['/home/node'] ?? '', files: mounts['/files'] ?? '' },
+		person: c.Config.Labels[LABEL.person] ?? '', created: c.Created, labels: c.Config.Labels,
+	};
+}
+
+/** The lowest host port from DT_PORT_BASE upward that no dreamteamer container already holds. */
+export async function allocatePort(env = hostEnv()) {
+	const base = Number(env.DT_PORT_BASE);
+	if (!Number.isInteger(base) || base < 1024) throw new Error(`DT_PORT_BASE must be an integer port above 1023 (got "${env.DT_PORT_BASE}")`);
+	const all = ok(await api('GET', `/containers/json?all=1&filters=${filters(LABEL.workspace)}`), 'list containers');
+	const taken = new Set(all.flatMap((c) => (c.Ports ?? []).map((p) => p.PublicPort)).filter(Boolean));
+	// A stopped container publishes nothing in /containers/json, so read its binding from inspect —
+	// otherwise the second workspace lands on the first one's port the moment the first is stopped.
+	for (const c of all) if (c.State !== 'running') {
+		const d = await api('GET', `/containers/${c.Id}/json`);
+		for (const b of Object.values(d.body?.HostConfig?.PortBindings ?? {}).flat()) taken.add(Number(b.HostPort));
+	}
+	let port = base;
+	while (taken.has(port)) port++;
+	return port;
+}
+
+function person(flags, env) {
+	const git = (k) => { try { return execFileSync('git', ['config', '--global', k], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); } catch { return ''; } };
+	const name = flags.name ?? env.DT_PERSON_NAME ?? git('user.name');
+	const email = flags.email ?? env.DT_PERSON_EMAIL ?? git('user.email');
+	return { name, email };
+}
+
+/** Create-if-absent and start. Idempotent: a second call on an existing name starts it and prints
+ *  the same URL. Never injects a token — the person logs in INSIDE, once, and the home volume keeps it. */
+export async function startContainer(name, flags, log = console.log) {
+	if (!/^[a-z0-9][a-z0-9_.-]*$/.test(name)) throw new Error(`"${name}" is not a container name — lowercase letters, digits, "-", "_" and "."; e.g. hq-dana`);
+	const env = hostEnv();
+	let c = await inspectContainer(name);
+	if (!c) {
+		const template = typeof flags.template === 'string' ? flags.template : undefined;
+		if (!template) throw new Error(`container "${name}" does not exist yet — name the template that makes it: dt start container ${name} --template <t> (dt list images shows the templates present)`);
+		const ref = imageRef(template, env);
+		let img = await inspectImage(ref);
+		if (!img) { log(`… pulling ${ref}`); await pullImage(ref, log); img = await inspectImage(ref); }
+		if (!img) throw new Error(`image ${ref} is still absent after the pull`);
+		const labels = img.Config?.Labels ?? {};
+		const inner = Number(labels[LABEL.ports] ?? 8080);
+		const port = await allocatePort(env);
+		const who = person(flags, env);
+		const vols = volumeNames(name);
+		const body = {
+			Image: ref,
+			Labels: { [LABEL.workspace]: name, [LABEL.template]: template, [LABEL.person]: who.name },
+			Env: [
+				`DT_WORKSPACE=${name}`, `DT_TEMPLATE=${template}`, 'FILES_FOLDER=/files',
+				...(who.name ? [`GIT_AUTHOR_NAME=${who.name}`, `GIT_COMMITTER_NAME=${who.name}`] : []),
+				...(who.email ? [`GIT_AUTHOR_EMAIL=${who.email}`, `GIT_COMMITTER_EMAIL=${who.email}`] : []),
+			],
+			ExposedPorts: { [`${inner}/tcp`]: {} },
+			HostConfig: {
+				PortBindings: { [`${inner}/tcp`]: [{ HostIp: env.DT_BIND, HostPort: String(port) }] },
+				Mounts: [
+					{ Type: 'volume', Source: vols.workspace, Target: '/workspace' },
+					{ Type: 'volume', Source: vols.home, Target: '/home/node' },
+					{ Type: 'volume', Source: vols.files, Target: '/files' },
+				],
+				RestartPolicy: { Name: 'unless-stopped' },
+			},
+		};
+		ok(await api('POST', `/containers/create?name=${encodeURIComponent(name)}`, body), `create container ${name}`);
+		c = await inspectContainer(name);
+		log(`✔ created ${name} from ${ref} · ${env.DT_BIND}:${port} → ${inner} · volumes ${Object.values(vols).join(', ')}`);
+	}
+	if (c.State?.Status !== 'running') {
+		const res = await api('POST', `/containers/${c.Id}/start`);
+		if (res.status !== 204 && res.status !== 304) ok(res, `start container ${name}`);
+		c = await inspectContainer(name);
+	}
+	const detail = containerDetail(c);
+	await waitHealthy(detail, log);
+	log(`✔ container ${name} · ${detail.state} · ${detail.editor_url}`);
+	if (!flags['no-open'] && detail.editor_url) openUrl(detail.editor_url);
+	return detail;
+}
+
+/** Poll code-server's /healthz so the URL printed is one that already answers. */
+async function waitHealthy(detail, log) {
+	const seconds = process.env.DT_HEALTH_TIMEOUT !== undefined ? Number(process.env.DT_HEALTH_TIMEOUT) : 90;
+	if (!seconds || !detail.port) return;
+	const until = Date.now() + seconds * 1000;
+	let told = false;
+	while (Date.now() < until) {
+		const up = await new Promise((r) => {
+			const req = http.get({ host: detail.bind || '127.0.0.1', port: detail.port, path: '/healthz', timeout: 2000 }, (res) => { res.resume(); r(res.statusCode < 500); });
+			req.on('error', () => r(false)); req.on('timeout', () => { req.destroy(); r(false); });
+		});
+		if (up) return;
+		if (!told) { log('… waiting for the editor to answer (first start compiles the workspace)'); told = true; }
+		await new Promise((r) => setTimeout(r, 1500));
+	}
+	log(`⚠ the editor did not answer within ${seconds}s — \`docker logs ${detail.name}\` says why`);
+}
+
+function openUrl(url) {
+	const cmd = process.platform === 'darwin' ? ['open', url] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', url] : ['xdg-open', url];
+	try { spawn(cmd[0], cmd.slice(1), { stdio: 'ignore', detached: true }).unref(); } catch { /* printing the URL is the contract; opening it is a courtesy */ }
+}
+
+export async function stopContainer(name) {
+	const c = await inspectContainer(name);
+	if (!c) throw new Error(`no container "${name}" — dt list containers`);
+	const res = await api('POST', `/containers/${c.Id}/stop?t=10`);
+	if (res.status !== 204 && res.status !== 304) ok(res, `stop container ${name}`);
+	return containerDetail(await inspectContainer(name));
+}
+
+/** Plain `rm` keeps the three volumes — the workspace, the login, the files. `--force` removes them too. */
+export async function removeContainer(name, { force = false } = {}, log = console.log) {
+	const c = await inspectContainer(name);
+	if (!c) throw new Error(`no container "${name}" — dt list containers`);
+	const vols = containerDetail(c).volumes;
+	if (c.State?.Status === 'running') await api('POST', `/containers/${c.Id}/stop?t=10`);
+	ok(await api('DELETE', `/containers/${c.Id}?v=false`), `rm container ${name}`);
+	const named = Object.values(vols).filter(Boolean);
+	if (force) {
+		for (const v of named) { const r = await api('DELETE', `/volumes/${encodeURIComponent(v)}`); if (r.status !== 204 && r.status !== 404) ok(r, `rm volume ${v}`); }
+		log(`✔ removed ${name} and its volumes ${named.join(', ')}`);
+	} else {
+		log(`✔ removed ${name} · kept volumes ${named.join(', ')} (dt rm container ${name} --force removes them too; dt start container ${name} --template <t> reattaches them)`);
+	}
+}
+
+// ---- setup: the host's board -------------------------------------------------------------------
+export async function setup(flags, log = console.log) {
+	const dir = hostDir();
+	const file = path.join(dir, '.env');
+	fs.mkdirSync(dir, { recursive: true });
+	const existing = fs.existsSync(file) ? Object.fromEntries(parseEnvValues(fs.readFileSync(file, 'utf8'))) : {};
+	const missing = Object.entries(HOST_DEFAULTS).filter(([k]) => !(k in existing));
+	if (missing.length) {
+		const header = fs.existsSync(file) ? '' : '# dreamteamer host configuration — read by `dt setup`, `dt start container` and friends.\n# DT_IMAGE_<template>=<ref> pins a template to an image; DT_PERSON_NAME / DT_PERSON_EMAIL are the git identity containers get.\n';
+		fs.appendFileSync(file, header + missing.map(([k, v]) => `${k}=${v}`).join('\n') + '\n');
+	}
+	const board = [];
+	board.push(`host env    ${file} · ${missing.length ? `${missing.length} default(s) written` : 'present'}`);
+	let docker;
+	try {
+		const v = ok(await api('GET', '/version'), 'docker version');
+		docker = `docker      ${v.Version} · api ${v.ApiVersion} · ${v.Os}/${v.Arch} · ${socketPath()}`;
+	} catch (e) {
+		board.push(`docker      ✖ ${e.message}`);
+		for (const l of board) log(l);
+		return 1;
+	}
+	board.push(docker);
+	const images = await listImages();
+	board.push(`templates   ${images.length ? images.map((i) => `${i.template} (${i.image})`).join(', ') : 'none present — dt add image --template <t> pulls one'}`);
+	const template = typeof flags.template === 'string' ? flags.template : undefined;
+	if (template) {
+		const ref = imageRef(template);
+		if (!(await inspectImage(ref))) { log(`… pulling ${ref}`); await pullImage(ref, log); board.push(`pulled      ${ref}`); } else board.push(`present     ${ref}`);
+	}
+	const running = (await listContainers()).filter((c) => c.state === 'running');
+	board.push(`containers  ${running.length} running${running.length ? ' — ' + running.map((c) => `${c.name} ${c.editor_url}`).join(', ') : ''}`);
+	for (const l of board) log(l);
+	return 0;
+}
+
+// ---- the verb surface `cli.js` hands over ------------------------------------------------------
+const table = (rows, cols) => {
+	if (!rows.length) return '(none)';
+	const w = cols.map((c) => Math.max(c.length, ...rows.map((r) => String(r[c] ?? '').length)));
+	return rows.map((r) => cols.map((c, i) => String(r[c] ?? '').padEnd(w[i])).join('  ').trimEnd()).join('\n');
+};
+
+/** `dt <verb> <container|containers|image|images>[/<id>] [<id>] [flags]` → exit code. */
+export async function driverCommand(verb, target, args) {
+	const { flags, pos } = parseFlags(args);
+	const id = target.id ?? pos[0];
+	const json = flags.json === true;
+	const col = target.collection;
+	if (!DRIVER_VERBS.has(verb)) throw new Error(`\`${verb}\` is not a verb on ${col} — list · get · add · rm${col === 'containers' ? ' · start · stop · open' : ''}`);
+	if (col === 'images') {
+		if (LIFECYCLE_VERBS.has(verb)) throw new Error(`\`${verb}\` is a container verb — an image is started by starting a container from it: dt start container <name> --template <t>`);
+		if (verb === 'list') { const rows = await listImages(); json ? emit(JSON.stringify(rows, null, 2)) : console.log(table(rows, ['template', 'image', 'size_mb', 'ports', 'created'])); return 0; }
+		if (verb === 'get') { if (!id) throw new Error('dt get image <ref>'); const i = await inspectImage(id); if (!i) throw new Error(`no image "${id}"`); emit(JSON.stringify(json ? i : imageRow({ ...i, Labels: i.Config?.Labels, Created: Date.parse(i.Created) / 1000 }), null, 2)); return 0; }
+		if (verb === 'add') { const t = typeof flags.template === 'string' ? flags.template : undefined; if (!t) throw new Error('dt add image --template <t> pulls the template\'s image'); const ref = imageRef(t); console.log(`… pulling ${ref}`); await pullImage(ref); console.log(`✔ ${ref}`); return 0; }
+		if (verb === 'rm') { if (!id) throw new Error('dt rm image <ref>'); ok(await api('DELETE', `/images/${encodeURIComponent(id)}${flags.force ? '?force=true' : ''}`), `rm image ${id}`); console.log(`✔ removed image ${id}`); return 0; }
+	}
+	// containers
+	if (verb === 'list') { const rows = await listContainers(); json ? emit(JSON.stringify(rows, null, 2)) : console.log(table(rows, ['name', 'template', 'state', 'editor_url', 'person', 'created'])); return 0; }
+	if (!id) throw new Error(`dt ${verb} container <name>${verb === 'start' || verb === 'add' ? ' --template <t>' : ''}`);
+	if (verb === 'get') { const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}" — dt list containers`); emit(JSON.stringify(json ? c : containerDetail(c), null, 2)); return 0; }
+	if (verb === 'start' || verb === 'add') { const d = await startContainer(id, flags); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
+	if (verb === 'stop') { const d = await stopContainer(id); console.log(`✔ stopped ${id} · volumes kept`); if (json) emit(JSON.stringify(d, null, 2)); return 0; }
+	if (verb === 'open') { const c = await inspectContainer(id); if (!c) throw new Error(`no container "${id}"`); const d = containerDetail(c); if (!d.editor_url) throw new Error(`${id} publishes no port`); console.log(d.editor_url); if (!flags['no-open']) openUrl(d.editor_url); return 0; }
+	if (verb === 'rm') { await removeContainer(id, { force: flags.force === true }); return 0; }
+	return 1;
+}
+
+/** A local flag parser: `--k v`, `--k=v`, bare `--k` → true. Kept here rather than importing the
+ *  record parser's promotion rules — a repeated flag on these verbs is a mistake, not an array. */
+export function parseFlags(args) {
+	const flags = {}; const pos = [];
+	for (let i = 0; i < args.length; i++) {
+		const a = args[i];
+		if (!a.startsWith('--')) { pos.push(a); continue; }
+		const eq = a.indexOf('=');
+		if (eq > -1) flags[a.slice(2, eq)] = a.slice(eq + 1);
+		else if (i + 1 < args.length && !args[i + 1].startsWith('--')) flags[a.slice(2)] = args[++i];
+		else flags[a.slice(2)] = true;
+	}
+	return { flags, pos };
+}
+
+export const CONTAINER_FLAGS = ['template', 'name', 'email', 'no-open', 'json', 'force'];

package/src/harnesses.js

@@ -25,6 +25,12 @@ export const STAMP = '<!-- generated by dreamteamer compile — do not edit; sou
 export const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 export const END = '<!-- dreamteamer:end -->';
 
+// A SECOND managed block, deliberately not folded into the orientation one. Separate delimiters
+// keep the orientation block's asserted size budget meaningful, and let `dreamteamer.md` be removed
+// on its own without the removal touching anything generated from the schema.
+export const INSTRUCTIONS_BEGIN = '<!-- dreamteamer:instructions:begin -->';
+export const INSTRUCTIONS_END = '<!-- dreamteamer:instructions:end -->';
+
 export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown', workspaceModule = '' }) {
 	const outputs = [];
 	// ⚠ SEPARATE from `outputs`: these are USER-OWNED root files carrying a managed block, and the
@@ -92,9 +98,34 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	block('GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
+	// ---- the operator's own rules, one source, every harness -------------------------
+	// Rendered VERBATIM. Nothing here reformats, wraps or summarises it: it is the operator's prose,
+	// and the whole value is that what he wrote is what every agent reads.
+	//
+	// ⚠ `enabled ? instructions : null` mirrors the orientation calls above, and the null branch is
+	// load-bearing twice: a harness switched off has its block removed, and so does a workspace that
+	// deletes its dreamteamer.md — `instructions` is null in that case and the same branch runs.
+	//
+	// ⚠ NOT through the local `block()` helper: that pushes the filename onto `blocks`, and these
+	// three files are already on it from their orientation calls above — pushing twice would hand
+	// git the same pathspec twice (schema-ops.regeneratedOutputs is the reader).
+	// ⚠ `|| null`, NOT `?? null`. `.trimEnd()` on a whitespace-only source yields `''`, which is not
+	// nullish — so the three Markdown files got an empty BEGIN/END pair while the cursor rule, which
+	// tests the string for truthiness below, omitted the part entirely. An empty source means no
+	// block, everywhere.
+	const instructions = entries.get('instructions.md')?.bytes?.toString('utf8').trimEnd() || null;
+	const instructionsBlock = (file, enabled) =>
+		writeBlock(root, file, enabled ? instructions : null, { begin: INSTRUCTIONS_BEGIN, end: INSTRUCTIONS_END, above: BEGIN });
+	instructionsBlock('CLAUDE.md', on('claude-code'));
+	instructionsBlock('AGENTS.md', on('codex') || on('pi'));
+	instructionsBlock('GEMINI.md', on('gemini-cli'));
+
 	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
 	if (on('cursor')) {
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule)}\n\n${STAMP}\n`;
+		// ⚠ `.mdc` is written WHOLE by `write()`, not through `writeBlock`, so removal is automatic: a
+		// compile with no dreamteamer.md simply rewrites the file without the part.
+		const instructionsPart = instructions ? `${INSTRUCTIONS_BEGIN}\n${instructions}\n${INSTRUCTIONS_END}\n\n` : '';
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${instructionsPart}${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -548,22 +579,35 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 
 // managed block in a USER-OWNED root file. content=null removes the block; a file left
 // empty (or whitespace) after removal is deleted — we created it, we clean it up.
-function writeBlock(root, filename, content) {
+function writeBlock(root, filename, content, { begin = BEGIN, end = END, above } = {}) {
 	const file = path.join(root, filename);
 	const exists = fs.existsSync(file);
 	if (content == null) {
 		if (!exists) return;
 		let text = fs.readFileSync(file, 'utf8');
-		if (!text.includes(BEGIN)) return;
-		text = text.replace(new RegExp(`\\n?\\n?${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}\\n?`), '\n');
+		if (!text.includes(begin)) return;
+		text = text.replace(new RegExp(`\\n?\\n?${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}\\n?`), '\n');
 		if (text.trim() === '') fs.rmSync(file);
 		else fs.writeFileSync(file, text);
 		return;
 	}
-	const block = `${BEGIN}\n${content}\n${END}`;
+	const block = `${begin}\n${content}\n${end}`;
+	// ⚠ A FUNCTION REPLACEMENT, never the string. `String.prototype.replace` reads `$&`, `` $` ``,
+	// `$'` and `$1` out of a STRING replacement and substitutes around the match — so a block whose
+	// content carries any of them is silently rewritten on the way in, and `$'…'` is ordinary bash in
+	// a file about shell commands. Measured: `use $'\n'` rendered as `use ` + the entire preamble.
+	// A function replacement is taken literally, which is what "verbatim" has to mean.
+	const insert = (replacement) => () => replacement;
 	let text = exists ? fs.readFileSync(file, 'utf8') : '';
-	if (text.includes(BEGIN)) text = text.replace(new RegExp(`${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}`), block);
-	else text = (text.trimEnd() + '\n\n' + block + '\n').replace(/^\n+/, '');
+	if (text.includes(begin)) {
+		text = text.replace(new RegExp(`${escapeRe(begin)}[\\s\\S]*?${escapeRe(end)}`), insert(block));
+	} else if (above && text.includes(above)) {
+		// ⚠ ORDER IS THE CONTRACT, not a preference. The rules must be read BEFORE the schema
+		// orientation, and a harness that truncates a long context file truncates the tail.
+		text = text.replace(above, insert(`${block}\n\n${above}`));
+	} else {
+		text = (text.trimEnd() + '\n\n' + block + '\n').replace(/^\n+/, '');
+	}
 	fs.writeFileSync(file, text);
 }
 

package/src/init.js

@@ -8,6 +8,7 @@ import { discoverModules, KINDS } from './compile.js';
 import { KNOWN_HARNESSES } from './harnesses.js';
 import { Store } from './store.js';
 import { envContext, renderTemplate } from './env-vars.js';
+import { ensureEditorRecommendation } from './workspace.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
@@ -147,8 +148,10 @@ export function init({ flags = {} } = {}) {
 	// A workspace that needs people as records ships its own collection (a module's `contacts` already
 	// does), and reads the operator from git where it needs one. `teams` went the same way 2026-07-31.
 
-	// .gitignore + .env.example (append-if-missing, never clobber)
+	// .gitignore + .env.example (append-if-missing, never clobber) + the editor recommendation, so
+	// the first window opened on this workspace offers the extension instead of leaving it to be found
 	appendMissing(path.join(root, '.gitignore'), GITIGNORE);
+	ensureEditorRecommendation(root);
 	if (!fs.existsSync(path.join(root, '.env.example'))) fs.writeFileSync(path.join(root, '.env.example'), ENV_EXAMPLE);
 
 	// one init commit (if we're in a git repo)

package/src/ref.js

@@ -1,15 +1,37 @@
-// split "<collection>/<id>" against the DECLARED collections — longest prefix at a "/" boundary,
-// because both collection names and ids may contain slashes (namespaces; path-shaped ids).
+// The words a collection answers to on the command line: its declared name and its `singular`
+// (compile stamps one on every descriptor — derived by inflection, authorable where inflection is
+// wrong — and refuses two collections whose words collide). `dt add task …` and `dt add tasks …`
+// are the same call. ⚠ TYPED INPUT ONLY: a reference VALUE inside a record (`tasks/kickoff`) is
+// parsed by namespace.js's parseRef against declared names and never learns the singular, so
+// `task/kickoff` in a field stays the dangling reference `check` reports it as.
+function* words(descriptors) {
+	for (const [name, d] of descriptors) {
+		yield [name, name];
+		if (d?.singular && d.singular !== name) yield [d.singular, name];
+	}
+}
+
+/** The declared collection a typed word names — the name itself or its singular — else null. */
+export function canonicalCollection(descriptors, word) {
+	if (descriptors.has(word)) return word;
+	for (const [w, name] of words(descriptors)) if (w === word) return name;
+	return null;
+}
+
+// split "<collection>/<id>" against the DECLARED collections and their singulars — longest prefix
+// at a "/" boundary, because both collection names and ids may contain slashes (namespaces;
+// path-shaped ids). The collection returned is always the declared NAME, whichever word was typed.
 export function splitRef(descriptors, ref) {
 	let best = null;
-	for (const name of descriptors.keys()) {
-		if (ref === name || ref.startsWith(name + '/')) {
-			if (!best || name.length > best.length) best = name;
+	let bestName = null;
+	for (const [w, name] of words(descriptors)) {
+		if (ref === w || ref.startsWith(w + '/')) {
+			if (!best || w.length > best.length) { best = w; bestName = name; }
 		}
 	}
 	if (!best) throw new Error(`unknown collection in reference "${ref}" (known: ${[...descriptors.keys()].sort().join(', ')})`);
 	if (ref === best) throw new Error(`reference "${ref}" names a collection but no record id`);
-	return { collection: best, id: ref.slice(best.length + 1) };
+	return { collection: bestName, id: ref.slice(best.length + 1) };
 }
 
 /**

package/src/workspace.js

@@ -49,3 +49,53 @@ export function nestedAsModule(outer, inner) {
 		.split(path.sep)
 		.some((seg) => MODULE_SEGMENTS.has(seg));
 }
+
+/** The VS Code-family extension for this workspace, as the editor learns of it: a recommendation
+ *  in `.vscode/extensions.json`, which VS Code, Cursor and code-server all read on open and offer to
+ *  install. Written by `init` and kept current by `compile`, because a compiled workspace that never
+ *  names its editor left a first-run agent searching a registry for the id (measured 2026-09-24:
+ *  three install attempts, two of them into a directory the running editor did not read). An
+ *  existing file is MERGED, never replaced: a file the operator authored (comments included) is left
+ *  alone whenever it already names the extension; one that does not is re-read as JSON and gains the
+ *  id, and one that is neither is left with a warning rather than clobbered. */
+export const EDITOR_EXTENSION_ID = 'dreamteamer.dreamteamer-vscode';
+export function ensureEditorRecommendation(root, warn = console.warn) {
+	const file = path.join(root, '.vscode', 'extensions.json');
+	if (!fs.existsSync(file)) {
+		fs.mkdirSync(path.dirname(file), { recursive: true });
+		fs.writeFileSync(file, JSON.stringify({ recommendations: [EDITOR_EXTENSION_ID] }, null, '\t') + '\n');
+		return 'written';
+	}
+	const text = fs.readFileSync(file, 'utf8');
+	if (text.includes(EDITOR_EXTENSION_ID)) return 'present';
+	let parsed;
+	try { parsed = JSON.parse(text); } catch {
+		warn(`⚠ .vscode/extensions.json does not recommend ${EDITOR_EXTENSION_ID} and is not plain JSON, so it was left alone — add the id to its "recommendations" by hand`);
+		return 'left';
+	}
+	if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) { warn(`⚠ .vscode/extensions.json is not an object — left alone; add ${EDITOR_EXTENSION_ID} to "recommendations" by hand`); return 'left'; }
+	parsed.recommendations = [...(Array.isArray(parsed.recommendations) ? parsed.recommendations : []), EDITOR_EXTENSION_ID];
+	fs.writeFileSync(file, JSON.stringify(parsed, null, '\t') + '\n');
+	return 'merged';
+}
+
+/** `.env.example` lists every env key the installed modules declare — the file the missing-key
+ *  warning points at, which used to carry two comment lines and none of the keys it was cited for.
+ *  Append-only and idempotent: a key already named in the file (as `KEY=` or `# KEY`) is not added
+ *  again, and nothing an operator wrote is touched. Values never appear here — an example does. */
+export function ensureEnvExample(root, entries, header = '') {
+	if (!entries.length) return [];
+	const file = path.join(root, '.env.example');
+	const existing = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : header;
+	const named = new Set([...existing.matchAll(/^\s*#?\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/gm)].map((m) => m[1]));
+	const added = [];
+	let out = existing;
+	for (const e of entries) {
+		if (named.has(e.key)) continue;
+		const who = e.modules?.length ? ` (module ${e.modules.join(', ')})` : '';
+		out = out.trimEnd() + `\n\n# ${e.description ?? `declared by ${e.modules.join(', ')}`}${e.description ? who : ''}\n${e.key}=${e.example ?? ''}\n`;
+		added.push(e.key);
+	}
+	if (added.length) fs.writeFileSync(file, out.replace(/^\n+/, ''));
+	return added;
+}