dreamteamer 0.16.0 → 0.17.0

package/src/collections-cli.js

@@ -86,15 +86,26 @@ export function collectionCommand(ws, collection, verb, args) {
 
 	switch (verb) {
 		case 'list': {
-			const filters = Object.entries(flags).filter(([k]) => !LIST_META_FLAGS.has(k));
-			if (typeof flags.filter === 'string') {
-				const eq = flags.filter.indexOf('=');
-				filters.push([flags.filter.slice(0, eq), flags.filter.slice(eq + 1)]);
+			// EVERY condition, ANDed — a repeated flag composes rather than replacing. `--filter a=1
+			// --filter b=2` used to keep only `b=2` and return rows the caller had excluded, which is
+			// the one failure a narrowing verb must not have: a listing that answers a question nobody
+			// asked, at exit 0. Bare-field flags (`--status todo`) already composed this way; the
+			// meta flag now reads the same, and `[].concat` treats one and many alike.
+			const filters = Object.entries(flags)
+				.filter(([k]) => !LIST_META_FLAGS.has(k))
+				.flatMap(([k, v]) => [].concat(v).map((one) => [k, one]));
+			for (const cond of [].concat(flags.filter ?? [])) {
+				const eq = String(cond).indexOf('=');
+				// `--filter status` is not a condition. It used to slice into `statu = status`, which
+				// matches nothing and reads as a fact about the collection.
+				if (eq < 1) throw new Error(`--filter takes <field>=<value> — got "${cond}"`);
+				filters.push([String(cond).slice(0, eq), String(cond).slice(eq + 1)]);
 			}
 			// `--where` is the SAME operator set the studio's filter panel emits and saved views
 			// store — one `matchesFilter`, so `--where '{"starts":{"_gte":"2026-07-01"}}'` and the
 			// panel that produced that JSON cannot disagree about which records match.
-			const where = typeof flags.where === 'string' ? load(flags.where) : null;
+			const whereJson = oneValue(flags, 'where');
+			const where = whereJson ? load(whereJson) : null;
 			const resolve = where ? recordResolver(store) : null;
 			const bf = bodyField(d);
 			const rows = [];
@@ -107,7 +118,8 @@ export function collectionCommand(ws, collection, verb, args) {
 			// sorting was studio-only until now: the browse table ordered records and no CLI
 			// invocation could. Same `sortRows` the server and api.ts call, so `--sort -starts`
 			// orders date-times by INSTANT across mixed offsets rather than by string.
-			if (typeof flags.sort === 'string') sortRows(rows, flags.sort);
+			const sort = oneValue(flags, 'sort');
+			if (sort) sortRows(rows, sort);
 			if (flags.json) { emit(JSON.stringify(rows, null, 2)); return 0; }
 			const cols = ['id', ...(d.list_fields ?? []).filter((c) => c !== 'id')];
 			for (const r of rows) console.log(cols.map((c) => fmtCell(r[c])).join('  '));
@@ -138,9 +150,7 @@ export function collectionCommand(ws, collection, verb, args) {
 		}
 		case 'set': {
 			const id = need(pos, 0, 'id');
-			const changes = coerceArrays(d, Object.fromEntries(
-				pos.slice(1).filter((p) => p.includes('=')).map((p) => [p.slice(0, p.indexOf('=')), p.slice(p.indexOf('=') + 1)])
-			));
+			const changes = coerceArrays(d, pairs(pos.slice(1)));
 			Object.assign(changes, coerceArrays(d, stripMeta(flags)));
 			if (!Object.keys(changes).length) throw new Error('nothing to set — pass key=value pairs or --key value flags');
 			store.set(collection, id, changes);
@@ -219,7 +229,7 @@ export function collectionCommand(ws, collection, verb, args) {
 		}
 		case 'diff': {
 			const id = need(pos, 0, 'id');
-			const out = historyDiff(store, collection, id, typeof flags.hash === 'string' ? flags.hash : 'HEAD');
+			const out = historyDiff(store, collection, id, oneValue(flags, 'hash') ?? 'HEAD');
 			if (flags.json) { emit(JSON.stringify(out, null, 2)); return 0; }
 			console.log(out.diff.trimEnd() || `(no change to ${out.path} in ${out.hash})`);
 			return 0;
@@ -228,7 +238,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			const id = need(pos, 0, 'id');
 			// the hash is REQUIRED and has no default: "revert" with an implied target is how you
 			// destroy the wrong record. `<c> history <id>` is where you get one.
-			const hash = typeof flags.hash === 'string' ? flags.hash : pos[1];
+			const hash = oneValue(flags, 'hash') ?? pos[1];
 			if (!hash) throw new Error(`missing --hash <commit> — run \`dreamteamer history ${collection}/${id}\` to pick one`);
 			const out = store.revert(collection, id, hash);
 			flags.json ? emit(JSON.stringify(out)) : console.log(out.reverted ? `✔ reverted ${collection}/${id} to ${String(hash).slice(0, 7)}` : `= already identical to ${String(hash).slice(0, 7)} — nothing changed`);
@@ -252,7 +262,7 @@ export function collectionCommand(ws, collection, verb, args) {
 // the only caller, so a second, weaker splitter here could only ever disagree with it.
 function metaCommandsFor(ws, store, flags, pos) {
 	const collection = need(pos, 0, 'collection');
-	const ids = typeof flags.ids === 'string' ? flags.ids.split(',').map((s) => s.trim()).filter(Boolean) : [];
+	const ids = (oneValue(flags, 'ids') ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 	const out = commandsFor(store, collection, ids);
 	if (flags.json) { emit(JSON.stringify(out, null, 2)); return 0; }
 	if (!out.commands.length) { console.log(`(no commands bound to ${collection})`); return 0; }
@@ -280,6 +290,7 @@ function metaReposEnsure(ws, flags, pos) {
 
 // `dreamteamer collections add --name research-docs --template docs`
 function metaCollectionsAdd(ws, store, flags) {
+	refuseRepeats(flags);
 	const { file } = createCollection(ws, store, { name: flags.name, template: flags.template, namespace: flags.namespace });
 	console.log(`✔ ${rel(ws.root, file)}`);
 	console.log('✔ compiled — the collection is live (schema ops prove sources with a real compile)');
@@ -290,6 +301,7 @@ function metaCollectionsAdd(ws, store, flags) {
 // The whole point is that namespacing EXISTING data is one command instead of a six-step hand
 // migration whose last step (rewriting references) dangles everything when forgotten.
 function metaCollectionsRename(ws, store, flags, pos) {
+	refuseRepeats(flags);
 	const [oldName, explicitNew] = pos;
 	if (!oldName) throw new Error('usage: dreamteamer schema rename-collection <old> <new> | <old> --namespace <ns>');
 	// `--namespace health` on its own moves the collection INTO that namespace keeping its bare name,
@@ -313,6 +325,7 @@ function metaCollectionsRename(ws, store, flags, pos) {
 // `dreamteamer collections rm widgets [--force]` — --force is required to drop a collection
 // that still has records (removeCollection refuses otherwise, and says so).
 function metaCollectionsRm(ws, store, flags, pos) {
+	refuseRepeats(flags);
 	const name = need(pos, 0, 'collection name');
 	const out = removeCollection(ws, store, name, { force: !!flags.force });
 	flags.json ? emit(JSON.stringify(out)) : console.log(`✔ removed collection ${out.removed}`);
@@ -322,6 +335,7 @@ function metaCollectionsRm(ws, store, flags, pos) {
 
 // `dreamteamer tasks add-field --name urgent --type boolean --default-value false`
 function metaAddField(ws, store, collection, flags) {
+	refuseRepeats(flags);
 	const prop = fieldDef(store, flags, collection);
 	// fieldDef DEFERS every relation flag it has no reference to attach to, because on update-field
 	// the target is carried in afterwards. add-field has nothing to carry, so a relation flag that
@@ -372,6 +386,7 @@ function reportMirror(store, collection, fieldName, prop) {
 // Same flag vocabulary as add-field (one `fieldDef`), so the two read as one operation with two
 // preconditions rather than two dialects.
 function metaUpdateField(ws, store, collection, flags) {
+	refuseRepeats(flags);
 	if (!flags.name) throw new Error('missing --name <field>');
 	const prop = fieldDef(store, flags, collection);
 	// tri-state: omitting --required leaves requiredness ALONE, rather than silently clearing it
@@ -392,6 +407,7 @@ function metaUpdateField(ws, store, collection, flags) {
 
 // `dreamteamer tasks remove-field --name urgent`
 function metaRemoveField(ws, store, collection, flags) {
+	refuseRepeats(flags);
 	const name = flags.name ?? flags.field;
 	if (!name) throw new Error('missing --name <field>');
 	const out = removeField(ws, store, collection, name);
@@ -402,6 +418,10 @@ function metaRemoveField(ws, store, collection, flags) {
 		// half of a destructive verb, and a silent deletion is a different act from a reported one.
 		if (out.cleared) console.log(`  cleared its values from ${out.cleared} ${collection} record${out.cleared === 1 ? '' : 's'} (git holds them: git show HEAD~1)`);
 		reportDropped(out.dropped);
+		// This descriptor's own `list_fields`/`sort_field` were pruned with the field; a ui-view is a
+		// source this verb does not own, so it is NAMED rather than edited — and naming it is the whole
+		// point, since a column of a field that no longer exists renders as an empty one.
+		if (out.staleViews?.length) console.warn(`⚠ still listing ${collection}.${name} as a column: ${out.staleViews.join(', ')} — edit with \`dreamteamer schema set-view <id> options.columns=…\``);
 	}
 	return 0;
 }
@@ -411,8 +431,26 @@ function metaRemoveField(ws, store, collection, flags) {
 // through saveUiView's compile gate rather than the record store. Without these verbs everything
 // the Layout options panel does — columns, order, sort, layout, filter, nav — was click-only.
 
-/** `--options '{"sort":"-date"}'` style flags, plus dotted `options.sort=-date` positionals. */
-function parseViewValue(raw) {
+/**
+ * Layout options whose value is a LIST, so `options.columns=title,status` means what it says.
+ *
+ * ⚠ NAMED, not inferred, and that is the whole design: `options` is an open bag with no schema —
+ * each layout declares its own keys and unknown ones ride through untouched — so nothing in the
+ * runtime can tell a list key from a scalar one. Without this set the comma spelling every other
+ * verb accepts for an array (`--tags a,b`) stored the literal string `"title,status"`, which the
+ * surface reads with `Array.isArray` and therefore ignores: a view that looked configured, drew
+ * the descriptor's `list_fields` instead, and reported nothing anywhere.
+ *
+ * `columns` is honoured by every layout; `ref_fields` and `value_fields` are the diagram's
+ * link-by pickers. `arrangement` is deliberately ABSENT — its elements are objects, so the JSON
+ * form is its only honest spelling, and a comma split would quietly produce garbage.
+ */
+const VIEW_LIST_OPTIONS = new Set(['options.columns', 'options.ref_fields', 'options.value_fields']);
+
+/** `--options '{"sort":"-date"}'` style flags, plus dotted `options.sort=-date` positionals. The
+ *  KEY is passed because the value's shape depends on it: only the key says whether a comma is a
+ *  separator or a character. */
+function parseViewValue(raw, key) {
 	if (typeof raw !== 'string') return raw;
 	const t = raw.trim();
 	if (t === 'true') return true;
@@ -421,6 +459,22 @@ function parseViewValue(raw) {
 	if (t.startsWith('{') || t.startsWith('[')) {
 		try { return JSON.parse(t); } catch { throw new Error(`not valid JSON: ${t}`); }
 	}
+	// ⚠ A QUOTED value is a LITERAL string, and `options.sort='""'` is the whole reason the branch
+	// exists: `sort: ''` is what the surface requires to round-trip "unsorted" (omit it and the
+	// ordering silently reverts to a fallback on the next load), and the dotted grammar could not
+	// express it — an empty value UNSETS, by the same convention `dt set` has for a record field.
+	// So the quoting is the operator saying "the empty string IS the value"; `assignViewValue`
+	// carries that through to `assignPath`.
+	if (t.startsWith('"')) {
+		try {
+			const s = JSON.parse(t);
+			if (typeof s === 'string') return s;
+		} catch { /* one message for every malformed quoting, below */ }
+		throw new Error(`not a quoted string: ${t} — a literal is written like '"-date"' (and '""' for the empty one)`);
+	}
+	// An empty value falls through to assignPath, which UNSETS the key — a `columns=` that wrote
+	// `columns: []` would be a configured-to-show-nothing view, not a removed setting.
+	if (t !== '' && VIEW_LIST_OPTIONS.has(key)) return t.split(',').map((s) => s.trim()).filter(Boolean);
 	return raw;
 }
 
@@ -435,11 +489,15 @@ function parseViewValue(raw) {
  *
  * Intermediate objects are not created on the way to a delete: unsetting `a.b` on a record with no
  * `a` should leave the record alone, not grow an empty `a: {}`.
+ *
+ * `explicit` is the escape hatch, and it has exactly one caller: a value the operator QUOTED
+ * (`options.sort='""'`) is a value, empty or not. Without it the convention above has no exception
+ * and `sort: ''` — which the surface needs to mean "unsorted" — is unwritable from the CLI.
  */
-function assignPath(target, dotted, value) {
+function assignPath(target, dotted, value, explicit = false) {
 	const keys = dotted.split('.');
 	const leaf = keys[keys.length - 1];
-	const unset = value === null || value === '';
+	const unset = !explicit && (value === null || value === '');
 	let node = target;
 	for (const k of keys.slice(0, -1)) {
 		if (node[k] == null || typeof node[k] !== 'object' || Array.isArray(node[k])) {
@@ -452,6 +510,12 @@ function assignPath(target, dotted, value) {
 	else node[leaf] = value;
 }
 
+/** One dotted `key=value` write into a view: the value grammar, plus the one signal `assignPath`
+ *  cannot recover from the parsed value — whether the operator quoted it. */
+function assignViewValue(view, key, raw) {
+	assignPath(view, key, parseViewValue(raw, key), typeof raw === 'string' && raw.trim().startsWith('"'));
+}
+
 const VIEW_META_FLAGS = new Set(['id', 'json', 'force']);
 
 function metaUiView(ws, store, verb, flags, pos) {
@@ -466,7 +530,7 @@ function metaUiView(ws, store, verb, flags, pos) {
 	// store means `set` works on a MODULE-shipped view too — the edit lands as a workspace source
 	// that shadows it, which is the same thing saving one in the UI does.
 	let view = {};
-	let id = typeof flags.id === 'string' ? flags.id : undefined;
+	let id = oneValue(flags, 'id');
 	if (verb === 'set') {
 		id ??= need(pos, 0, 'ui-view id');
 		const { fields } = store.read('ui-views', id);
@@ -476,11 +540,16 @@ function metaUiView(ws, store, verb, flags, pos) {
 
 	for (const p of pos.slice(verb === 'set' ? 1 : 0)) {
 		if (!p.includes('=')) continue;
-		assignPath(view, p.slice(0, p.indexOf('=')), parseViewValue(p.slice(p.indexOf('=') + 1)));
+		assignViewValue(view, p.slice(0, p.indexOf('=')), p.slice(p.indexOf('=') + 1));
 	}
 	for (const [k, v] of Object.entries(flags)) {
 		if (VIEW_META_FLAGS.has(k)) continue;
-		assignPath(view, k, parseViewValue(v));
+		// A view key holds ONE value, and a list IS one value — so a repeated flag is a mistake with
+		// two spellings to correct it, rather than an array nobody asked for.
+		if (Array.isArray(v)) {
+			throw new Error(`--${k} was given ${v.length} times — a view key takes one value, and a list is written as one: --${k} ${v.join(',')} (or the JSON form '${JSON.stringify(v)}')`);
+		}
+		assignViewValue(view, k, v);
 	}
 
 	if (!view.path) throw new Error('missing --path </route> — a view is addressed by its route');
@@ -621,21 +690,75 @@ function* parseEach(store, collection, onError) {
 	}
 }
 
-function parseArgs(args) {
+/**
+ * `--flag value`, `--flag=value`, a bare `--flag` (true), and positionals.
+ *
+ * ⚠ A REPEATED flag PROMOTES TO AN ARRAY; it does not overwrite. `dt add c --tags a --tags b`
+ * assigned twice and kept `b`, so the first value never reached disk and nothing said so — the
+ * shape of every silent-wrong-answer bug this CLI has had. The promotion is the only honest parse,
+ * because "the operator typed it twice" is a fact the parser cannot interpret on its own.
+ *
+ * Every consumer of a flag therefore owes an answer to "what does a repeat MEAN here", and there
+ * are exactly three: it is one ELEMENT of an array field (`coerceArrays`), it is one more
+ * conjunctive CONDITION (`--filter`, in list), or the flag holds one value and a repeat is a
+ * MISTAKE (`oneValue`, and the view writer). Silence is not one of them.
+ */
+export function parseArgs(args) {
 	const flags = {};
 	const pos = [];
+	const put = (k, v) => { flags[k] = k in flags ? [].concat(flags[k], v) : v; };
 	for (let i = 0; i < args.length; i++) {
 		const a = args[i];
 		if (a.startsWith('--')) {
 			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;
+			if (eq > -1) put(a.slice(2, eq), a.slice(eq + 1));
+			else if (i + 1 < args.length && !args[i + 1].startsWith('--')) put(a.slice(2), args[++i]);
+			else put(a.slice(2), true);
 		} else pos.push(a);
 	}
 	return { flags, pos };
 }
 
+/** Read a flag that takes exactly ONE value. A repeat arrives as an array, and dropping it on the
+ *  floor (`typeof v === 'string'` reads an array as absent) would answer the wrong question at exit
+ *  0 — so it is named instead, with the line that was typed. */
+function oneValue(flags, key) {
+	const v = flags[key];
+	if (Array.isArray(v)) {
+		throw new Error(`--${key} was given ${v.length} times and takes ONE value: ${v.map((x) => `--${key} ${x}`).join(' ')}`);
+	}
+	return typeof v === 'string' ? v : undefined;
+}
+
+/**
+ * A schema verb takes ONE value per flag, and a repeat is refused before anything is written.
+ *
+ * None of them means a list by repetition — `--options a,b` is one value, and `--name` names the
+ * single thing being written — so every repeat is a mistake. It has to be caught here because the
+ * ones that matter are IDENTITY: `--name x --name y` wrote a field called `y` before the promotion
+ * and one called `x,y` after it, and both of those are a source file the operator then has to find
+ * and edit by hand.
+ */
+function refuseRepeats(flags) {
+	const dup = Object.entries(flags).find(([, v]) => Array.isArray(v));
+	if (!dup) return;
+	const [k, v] = dup;
+	throw new Error(`--${k} was given ${v.length} times, and a schema verb takes ONE value per flag: ${v.map((x) => `--${k} ${x}`).join(' ')}`);
+}
+
+/** `field=value` positionals, with the same promote-on-repeat rule the flags have. It was
+ *  `Object.fromEntries`, which keeps the LAST pair — `dt set c/id tags=a tags=b` wrote `[b]`. */
+function pairs(list) {
+	const out = {};
+	for (const p of list) {
+		if (!p.includes('=')) continue;
+		const k = p.slice(0, p.indexOf('='));
+		const v = p.slice(p.indexOf('=') + 1);
+		out[k] = k in out ? [].concat(out[k], v) : v;
+	}
+	return out;
+}
+
 const META_FLAGS = new Set(['id', 'json', 'force', 'filter']);
 const stripMeta = (flags) => Object.fromEntries(Object.entries(flags).filter(([k]) => !META_FLAGS.has(k)));
 
@@ -643,9 +766,18 @@ const stripMeta = (flags) => Object.fromEntries(Object.entries(flags).filter(([k
 function coerceArrays(d, fields) {
 	const out = {};
 	for (const [k, v] of Object.entries(fields)) {
-		out[k] = d.schema.properties?.[k]?.type === 'array' && typeof v === 'string'
-			? v.split(',').map((s) => s.trim()).filter(Boolean)
-			: v;
+		const isList = d.schema.properties?.[k]?.type === 'array';
+		// An array here means the operator SPELLED the key twice (`--tags a --tags b`, or
+		// `tags=a tags=b`). On a list field each sighting is one element — deliberately NOT
+		// comma-split again, so a value that contains a comma can be written by repeating the flag.
+		if (Array.isArray(v)) {
+			if (!isList) {
+				throw new Error(`${k} was given ${v.length} times (--${k} <value> / ${k}=<value>) and ${k} is not an array field — pass it once`);
+			}
+			out[k] = v;
+			continue;
+		}
+		out[k] = isList && typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : v;
 	}
 	return out;
 }

package/src/commit.js

@@ -377,7 +377,14 @@ function sample(root, repo, dirs, descriptors) {
 		const fromRel = (status === 'R' || status === 'C') ? chunks[++i] : null;
 		const rec = pathToRecord(descriptors, prefix + repoRel);
 		if (!rec) continue;
-		rows.push({ repoRel, fromRel, ...rec, verb: VERB[status] ?? 'set' });
+		// ⚠ `M` MEANS `set` FOR EVERY CODEC BUT ONE. `set` is the single verb the store refuses on a
+		// `codec: file` record — its bytes ARE the record, and the refusal's own message says to use
+		// `add --from … --force` instead — so a forced replacement was published under the name of
+		// the one thing that cannot be done to it. The status letter still decides; the descriptor
+		// only says what the letter is called here.
+		let verb = VERB[status] ?? 'set';
+		if (verb === 'set' && (descriptors.get(rec.collection)?.storage?.codec ?? 'md') === 'file') verb = 'replace';
+		rows.push({ repoRel, fromRel, ...rec, verb });
 	}
 	return { cwd, rows };
 }
@@ -485,6 +492,7 @@ export function commitPending(store, { only = [], message, dryRun = false } = {}
 			// store.js has always used.
 			execFileSync('git', ['add', '--all', '--', ...paths], { cwd });
 			execFileSync('git', ['commit', '--quiet', '-m', subject, '--', ...paths, ...alreadyStaged], { cwd });
+			store.headMoved(); // the verb that exists to move HEAD — see store.gitHead
 		}
 		const sha = dryRun ? null : execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd }).toString().trim();
 		results.push({ repo, rows, subject, sha, warning, leftPending });

package/src/compile.js

@@ -12,7 +12,7 @@ import { walk, patternRe } from './records.js';
 import { unknownOperators } from './filter.js';
 import {
 	normalizeNamespaces, namespaceProblems, unqualifiedProblems, defaultStoragePath, storageOverlaps,
-	baseNameOf,
+	baseNameOf, singular,
 } from './namespace.js';
 // circular on paper in earlier versions — safe: both sides only
 // call at run time, same pattern as store.js ↔ compile.js.
@@ -104,7 +104,7 @@ function normalizeRelationKeywords(schema, name, prefix = '') {
 			// every per-relation keyword, not just `x-inverse` — `x-unique` decides the mirror's
 			// cardinality, `x-on-delete` its removal rule and `x-inverse-of` names the owner from the
 			// other spelling, so all four have to reach the same node the relation is read from.
-			for (const kw of ['x-inverse', 'x-title-template', 'x-unique', 'x-on-delete', 'x-inverse-of']) {
+			for (const kw of ['x-inverse', 'x-title-template', 'x-unique', 'x-on-delete', 'x-inverse-of', 'x-reference-soft']) {
 				if (!(kw in prop)) continue;
 				if (kw in prop.items && prop.items[kw] !== prop[kw]) {
 					fail(`collection "${name}": field "${at}" declares conflicting ${kw} on the property and its items — keep one.`);
@@ -423,14 +423,29 @@ const NON_SOURCE_DIRS = new Set([
 ]);
 
 /** Unrecognised source-root folders in a module, or [] for the workspace root (a vault legitimately
- *  holds arbitrary directories — this gate is about PACKAGES, whose folders all mean something). */
+ *  holds arbitrary directories — this gate is about PACKAGES, whose folders all mean something).
+ *
+ *  ⚠ `system/` is enumerated TOO, under the same rule. It is in NON_SOURCE_DIRS so the root pass
+ *  waves it through, and that waved through everything BELOW it — so `system/gizmos/probe.gizmo.yaml`
+ *  compiled ✔ in silence while the identical folder at the module root hard-errored. That is exactly
+ *  the decision-156 shape the root gate exists to prevent, surviving one level down: `kindDir` still
+ *  reads `system/<kind>` as the pre-flatten fallback, so a kind the engine stopped knowing is just as
+ *  invisible there as it ever was at the root, and the half-migrated module is the likeliest place
+ *  for one to be. Known kinds under `system/` keep compiling — the fallback is deliberate and stays
+ *  (CLAUDE.md); only UNKNOWN folders become errors, and `dreamteamer.ignore` excuses them in both
+ *  places with one entry. */
 function strayKindDirs(source, wsRoot, declaredIgnore) {
 	if (path.resolve(source.root) === path.resolve(wsRoot)) return [];
 	const allow = new Set([...KINDS, ...NON_SOURCE_DIRS, ...declaredIgnore]);
-	return fs.readdirSync(source.root, { withFileTypes: true })
+	const dirsIn = (dir, prefix = '') => (fs.existsSync(dir) ? fs.readdirSync(dir, { withFileTypes: true }) : [])
 		.filter((e) => e.isDirectory() && !e.name.startsWith('.') && !allow.has(e.name))
-		.map((e) => e.name)
-		.sort();
+		.map((e) => `${prefix}${e.name}`);
+	return [
+		...dirsIn(source.root),
+		// The SAME allow set one level down — a generic package folder reads the same wherever the
+		// module put it, and one `ignore` entry covers both spellings rather than two.
+		...dirsIn(path.join(source.root, 'system'), 'system/'),
+	].sort();
 }
 
 const sha256 = (buf) => 'sha256:' + createHash('sha256').update(buf).digest('hex');
@@ -527,6 +542,30 @@ export function compile({ root, pkg }) {
 	const harnesses = config.harnesses ?? ['claude-code'];
 	const rel = (p) => path.relative(root, p);
 
+	/** ⚠ YAML, WITH THE FILE IN THE MESSAGE. js-yaml reports `line:column` and a snippet and never a
+	 *  path, so one stray tab in a workspace of a hundred sources was an mtime bisect. Every parse of
+	 *  a MODULE SOURCE goes through here; the projected records compile dumps itself do not need it. */
+	const loadSource = (text, srcPath) => {
+		try {
+			return load(text);
+		} catch (e) {
+			return fail(`${srcPath}: ${e.message}`);
+		}
+	};
+
+	/** An EMPTY source is never intentional, and every reader indexes straight into what it parses.
+	 *  The collection case died with a bare "Cannot read properties of undefined" naming no file; a
+	 *  0-byte ui-view was worse — compile said ✔ and `check` caught it one gate later, naming the
+	 *  COMPILED artifact under `.dreamteamer/`, which nobody can edit and the next compile overwrites.
+	 *  Refuse here, the last layer that still knows which module file the bytes came from.
+	 *  ⚠ ENTITY FILES ONLY. A skill is a FOLDER: its `SKILL.md` is the entity and is covered, while a
+	 *  placeholder under `references/` is the author's business, not the compiler's. */
+	const refuseEmptySource = (srcPath) => {
+		if (fs.readFileSync(srcPath, 'utf8').trim() === '') {
+			fail(`${rel(srcPath)}: source is empty — there is nothing to compile. Delete the file, or write one.`);
+		}
+	};
+
 	// ---- discover sources: channel modules then the workspace's own -----------------
 	const { modules: discovered, shadows } = discoverModules(root, pkg);
 	for (const s of shadows) console.warn(shadowWarning(s));
@@ -688,9 +727,13 @@ export function compile({ root, pkg }) {
 		// both of which used to compile ✔ and contribute nothing (see NON_SOURCE_DIRS)
 		const strays = strayKindDirs(source, root, moduleIgnores.get(source.name) ?? []);
 		if (strays.length) {
+			// `ignore` matches a FOLDER NAME, at the root and under `system/` alike, so the remedy has
+			// to quote the bare name — suggesting "system/gizmos" would print an entry that matches
+			// nothing and send the reader back for a second compile to find that out.
+			const ignorable = [...new Set(strays.map((s) => s.replace(/^system\//, '')))];
 			fail(`module "${source.name}" (${rel(source.root)}) has folder(s) that are not a known kind: ${strays.join(', ')}
   known kinds: ${KINDS.join(', ')}
-  if these are not sources, declare them: "dreamteamer": { "ignore": [${strays.map((s) => `"${s}"`).join(', ')}] } in ${rel(path.join(source.root, 'package.json'))}`);
+  if these are not sources, declare them: "dreamteamer": { "ignore": [${ignorable.map((s) => `"${s}"`).join(', ')}] } in ${rel(path.join(source.root, 'package.json'))}`);
 		}
 		for (const kind of KINDS) {
 			// a half-moved module compiles its flat half and drops the rest — say so rather than
@@ -721,7 +764,16 @@ export function compile({ root, pkg }) {
 				if (kind === 'collections' && !isDir) {
 					// descriptors merge via 'extends' — collect per collection name
 					const bytes = fs.readFileSync(srcPath);
-					const doc = load(bytes.toString('utf8'));
+					// A `touch`ed file on the way to writing one is the ordinary way to arrive here. The
+					// descriptor keeps its own wording — it is the one kind that can say what is missing.
+					if (bytes.toString('utf8').trim() === '') {
+						fail(`${rel(srcPath)}: collection source is empty — a descriptor needs at least 'name' and 'schema' (or 'extends'). Delete the file, or write one.`);
+					}
+					const doc = loadSource(bytes.toString('utf8'), rel(srcPath));
+					// a scalar or a list parses fine and then reads as undefined on every key below
+					if (doc == null || typeof doc !== 'object' || Array.isArray(doc)) {
+						fail(`${rel(srcPath)}: collection source is not a mapping — a descriptor needs at least 'name' and 'schema' (or 'extends').`);
+					}
 					// `codec: file` records are opaque bytes: there are no fields, so there is no schema to
 					// require and none to honour. Every other codec parses text into fields and must declare
 					// what they are.
@@ -733,18 +785,23 @@ export function compile({ root, pkg }) {
 					descriptorGroups.get(doc.name).push({ src: { path: rel(srcPath), hash: sha256(bytes) }, doc, moduleName: source.name });
 					contributed.add(source.name);
 				} else if (FOLDER_KINDS.has(kind) && isDir) {
+					// the folder's ENTITY file, not its payload — see refuseEmptySource
+					const entityFile = path.join(srcPath, 'SKILL.md');
+					if (fs.existsSync(entityFile)) refuseEmptySource(entityFile);
 					for (const file of walk(srcPath)) {
 						addEntry(path.join(kind, name, path.relative(srcPath, file)), file);
 						contributed.add(source.name);
 					}
 					counts[kind]++;
 				} else if (!isDir) {
+					refuseEmptySource(srcPath);
 					addEntry(path.join(kind, name), srcPath);
 					contributed.add(source.name);
 					counts[kind]++;
 				} else {
 					// nested dirs for file-shape kinds (e.g. date-partitioned) — recurse
 					for (const file of walk(srcPath)) {
+						refuseEmptySource(file);
 						addEntry(path.join(kind, path.relative(srcDir, file)), file);
 						contributed.add(source.name);
 						counts[kind]++;
@@ -805,8 +862,8 @@ export function compile({ root, pkg }) {
 	for (const [rt, entry] of entries) {
 		const m = /^collection-templates\/(.+)\.collection-template\.yaml$/.exec(rt);
 		if (!m) continue;
-		const doc = load(entry.bytes.toString('utf8'));
-		templateDocs.set(m[1], { template: doc.template ?? {}, src: entry.sources[0] });
+		const doc = loadSource(entry.bytes.toString('utf8'), entry.sources[0].path);
+		templateDocs.set(m[1], { template: doc?.template ?? {}, src: entry.sources[0] });
 	}
 
 	// ---- namespaces: the declared list, validated against what actually compiled ----------
@@ -916,6 +973,21 @@ export function compile({ root, pkg }) {
 		// An authored `storage.path` still wins — registering an existing folder is a first-class case
 		// (skills/using-dreamteamer/references/collections.md).
 		merged.storage.path ??= defaultStoragePath(name, namespaces, config['data-path'] ?? 'data');
+		// The middle segment of every record filename, `<id>.<suffix>.<ext>`. DERIVED here, exactly as
+		// `path` is above, so the runtime always carries an explicit one.
+		//
+		// ⚠ Absent, it was interpolated raw and every record landed as `<id>.undefined.md` — silent at
+		// compile, at `add` and at `check`, because `idFromRecordPath` reads the same undefined back
+		// and the round trip agrees with itself. On a `codec: file` collection it is not even silent
+		// for long: the next verb dies inside that function on `undefined.replace`.
+		//
+		// The rule is the singular of the BARE name (`health/doctors` records are `<id>.doctor.md`,
+		// not `<id>.health/doctor.md`) — the same rule `collections add` writes into a new descriptor,
+		// and the one `rename-collection` already ASSUMES when it tests `oldSuffix === singular(oldBase)`
+		// to decide whether a suffix may be re-derived. Deriving here makes that assumption true rather
+		// than coincidental. Kinder than refusing, and no existing workspace changes: a descriptor that
+		// authors a suffix keeps it, and one that does not was writing `.undefined.` files.
+		merged.storage.suffix ??= singular(baseNameOf(name, namespaces));
 		const storagePath = String(merged.storage.path ?? '');
 		const systemKinds = [...KINDS, ...DERIVED_KINDS];
 		const isSystem = systemKinds.includes(storagePath) || systemKinds.includes(storagePath.replace(/^system\//, ''));
@@ -1001,6 +1073,8 @@ export function compile({ root, pkg }) {
 		const declaredDeps = new Set(groupModules.flatMap((m) => moduleDeps.get(m) ?? []));
 		const declaredPeers = new Set(groupModules.flatMap((m) => modulePeers.get(m) ?? []));
 		const owns = (t) => groupModules.includes(collOwner.get(t));
+		// what THIS collection actually points at — see `unresolved_peers` below
+		const referenced = new Set();
 		normalizeRelationKeywords(merged.schema, name);
 		for (const [at, raw] of refTargets(merged.schema)) {
 			if (raw === '*') {
@@ -1021,6 +1095,7 @@ export function compile({ root, pkg }) {
 				fail(`collection "${name}": field "${at}" has an invalid x-reference ${JSON.stringify(raw)} — expected a collection name, a non-empty list of collection names, or '*'.`);
 			}
 			for (const target of targets) {
+				referenced.add(target);
 				if (CORE_COLLECTIONS.has(target) || owns(target)) continue;
 				const owner = collOwner.get(target);
 				if (owner && declaredDeps.has(owner)) continue;
@@ -1034,7 +1109,13 @@ export function compile({ root, pkg }) {
 		// Declared peers that nothing provides, stated as DATA on the descriptor so `check` can
 		// excuse their references without learning what a module is (the `storage.base` precedent —
 		// check.js is in the record layer and must not know modules exist).
-		const unresolved = [...declaredPeers].filter((p) => !collOwner.has(p)).sort();
+		//
+		// ⚠ Only the peers THIS collection references. It used to be every peer the module declared,
+		// stamped onto every collection in it — which made the field a module-level fact wearing a
+		// collection-level key, and handed a collection that references nothing an excuse it can
+		// never legitimately use. A peer declared for one collection would then have silently excused
+		// a typo'd reference in a sibling.
+		const unresolved = [...declaredPeers].filter((p) => referenced.has(p) && !collOwner.has(p)).sort();
 		if (unresolved.length) merged.unresolved_peers = unresolved;
 
 		// ONE BODY PER COLLECTION. A record's prose is the text after the frontmatter — there is only
@@ -1187,7 +1268,7 @@ export function compile({ root, pkg }) {
 	for (const [rt, e] of entries) {
 		if (rt.startsWith('agents/')) {
 			const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(e.bytes.toString('utf8'));
-			const doc = fm ? load(fm[1]) : {};
+			const doc = fm ? loadSource(fm[1], e.sources[0].path) : {};
 			for (const sk of doc.skills ?? []) {
 				if (!skillIds.has(String(sk).replace(/^skills\//, ''))) fail(`${rt}: references unknown skill "${sk}"`);
 			}
@@ -1221,7 +1302,7 @@ export function compile({ root, pkg }) {
 	const ownFields = load(entries.get(path.join('collections', 'ui-views.collection.yaml'))?.bytes?.toString('utf8') ?? '')?.schema?.properties ?? {};
 	for (const [rt, e] of entries) {
 		if (!rt.startsWith('ui-views/')) continue;
-		const view = load(e.bytes.toString('utf8'));
+		const view = loadSource(e.bytes.toString('utf8'), e.sources[0].path);
 		// filters are load-bearing (they narrow what the operator SEES) — typo'd operators
 		// fail at compile, not silently at render (review finding 5)
 		const badOps = view?.filter ? [...unknownOperators(view.filter)] : [];
@@ -1258,7 +1339,7 @@ export function compile({ root, pkg }) {
 	const commandIds = new Set([...entries.keys()].filter((k) => k.startsWith('commands/')).map((k) => path.basename(k).replace(/\.command\.md$/, '')));
 	for (const [rt, e] of entries) {
 		if (!rt.startsWith('command-bindings/')) continue;
-		const b = load(e.bytes.toString('utf8'));
+		const b = loadSource(e.bytes.toString('utf8'), e.sources[0].path);
 		const cmd = String(b?.command ?? '').replace(/^commands\//, '');
 		if (!cmd || !commandIds.has(cmd)) fail(`${rt}: references unknown command "${b?.command ?? ''}"`);
 		const coll = String(b?.collection ?? '').replace(/^collections\//, '');

package/src/env-vars.js

@@ -7,7 +7,9 @@
 // Two accepted non-goals, unchanged on purpose: `KEY =value` (space before `=`) doesn't match the
 // key pattern and is silently dropped, no diagnostic; an unquoted value keeps a trailing inline
 // `# comment` as part of its text (quote it to strip one).
+import fs from 'node:fs';
 import os from 'node:os';
+import path from 'node:path';
 
 export function parseEnvValues(text) {
 	const out = new Map();
@@ -22,6 +24,19 @@ export function parseEnvValues(text) {
 	return out;
 }
 
+/** What `renderTemplate` renders AGAINST, for one workspace: the names `dreamteamer.vars` declares,
+ *  the values this machine's `.env` carries, and the root. One builder rather than three lines at
+ *  each call site — `dt resolve` and `repos ensure` disagreeing about which vars are declared would
+ *  be a path that renders in one verb and refuses in the other. */
+export function envContext(ws) {
+	const envFile = path.join(ws.root, '.env');
+	return {
+		env: parseEnvValues(fs.existsSync(envFile) ? fs.readFileSync(envFile, 'utf8') : ''),
+		workspaceFolder: ws.root,
+		declared: ws.pkg.dreamteamer?.vars ?? [],
+	};
+}
+
 const SUPPORTED = 'supported: ${env:NAME}, ${workspaceFolder}, ${userHome}';
 
 export function renderTemplate(str, { env, workspaceFolder, declared }) {