dreamteamer 0.26.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: >-
@@ -172,10 +186,19 @@ schema:
     group:
       type: string
       description: >-
-        DEPRECATED as a nav axis since 2026-08-11 — the nav groups by `owner` (a module, which has a
-        title of its own) instead of by this string with a display-name map maintained in a surface.
-        Still read by nothing; kept so the change is a code revert rather than a data migration, and
-        because a workspace may yet want a partition that deliberately DIFFERS from its modules.
+        The collection's PARTITION — which family of nouns it belongs to, authored freely (`crm`,
+        `finance`, `family`, `content`…) and set with `dt set collections/<c> group=<g>`. One value
+        is reserved and load-bearing: `group: system` says the collection is the workspace's own
+        MACHINERY rather than one of its domain nouns, so it is left out of the generated block's
+        domain listing, named on the system-collections line instead, and drawn on a surface's
+        schema surface rather than in the record tree. ⚠ It does NOT change where records live or
+        whether they can be written — that is `storage.base`, asked separately, and `repos` is the
+        collection where the two answers split: `group: system` and workspace-stored records the
+        operator edits by hand. Nearly removed on 2026-08-11, when the nav stopped grouping by it in
+        favour of `owner` (a module, which has a title of its own) and nothing else read it; kept
+        then so the change would be a code revert rather than a data migration, and because a
+        workspace may want a partition that deliberately DIFFERS from its modules. That is what it
+        became.
 order: 10
 list_fields: [name, last-modified]
 icon: schema

package/collections/repos.collection.yaml

@@ -52,4 +52,10 @@ schema:
 order: 145
 list_fields: [name, identity, ref, url]
 icon: source
+# MACHINERY, NOT A DOMAIN NOUN, and `group: system` is the whole statement of it. `repos` is the
+# engine's only collection whose records live in `data/`, which used to make every workspace render
+# a **System** module group with one collection under it — the group the block's own renderer says
+# should not exist (harnesses.js). Being in the `system` partition folds it out of the block's
+# domain listing and onto the schema surface instead. The records stay real, writable and committed;
+# only the presentation changes.
 group: system

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.26.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}`);
 }