dreamteamer 0.19.0 → 0.19.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.19.0",
+	"version": "0.19.1",
 	"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>",

package/src/cli.js

@@ -29,7 +29,7 @@ import { envContext, renderTemplate } from './env-vars.js';
 const QUIET = ['ignore', 'pipe', 'ignore'];
 
 
-const USAGE = `usage: dreamteamer <verb> [<target>] [flags]
+export const USAGE = `usage: dreamteamer <verb> [<target>] [flags]
 
 record verbs (hard validation — invalid writes are rejected before disk).
 A <target> is either a collection name or a <collection>/<id> reference; the reference splits at
@@ -89,8 +89,10 @@ The commit lands in the repo that holds the source, so a write into a git module
                                                health/doctors; a module declaring exactly ONE
                                                namespace infers it, and the resolved name is echoed.
                                                --namespace '' means no namespace)
-  add    modules --name <id> [--description "…"]
+  add    modules --name <id> [--description "…"] [--namespace <ns>]
                                               (modules/<id>/ + every kind folder + package.json.
+                                               --namespace DECLARES it in the module (§8), so every
+                                               later \`add collections --module <id>\` infers it.
                                                folder = package name = id, so a module never forks.
                                                the git shape is \`install --clone <url> [name]\`)
   add    skills --name <id> --description "…"  (skills/<id>/SKILL.md — --description is required,
@@ -192,9 +194,23 @@ const EITHER_VERBS = new Set(['move', 'commands']);
 // verbs, and `collectionCommand`'s interceptors are the whole dispatch (§4).
 const FIELD_VERBS = ['add-field', 'update-field', 'remove-field', 'rename-field'];
 
+// WORKSPACE VERBS take a closed set of options, and nothing downstream of here would notice a
+// misspelling — `dt commit --dryrun` COMMITTED, because `rest.includes('--dry-run')` is false for a
+// flag nobody typed correctly. The record/system/field verbs are checked in `collections-cli.js`,
+// beside the parser they share; these nine have no shared parser, so the table is here.
+export const WORKSPACE_FLAGS = {
+	init: ['name', 'data-path', 'harnesses', 'workspace-module'], install: ['clone'], update: [],
+	start: ['port'], compile: ['watch'], check: [], status: [],
+	changes: ['since', 'json'], commit: ['dry-run', 'json'],
+};
+
 export function run(argv) {
 	const [cmd, ...rest] = argv;
 	try {
+		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)'}`);
+		}
 		if (cmd === '--version' || cmd === '-v' || cmd === 'version') {
 			// works OUTSIDE a workspace — the post-install "did it land?" affordance
 			const p = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'));

package/src/collections-cli.js

@@ -78,6 +78,7 @@ const LIST_META_FLAGS = new Set(['json', 'filter', 'where', 'sort']);
 export function collectionCommand(ws, collection, verb, args) {
 	const store = new Store(ws);
 	const { flags, pos } = parseArgs(args);
+	refuseUnknownFlags(store, collection, verb, flags);
 
 	// ---- system verbs: source writes, never the runtime ----------
 	// These MUST come before the generic switch: their collections are system-stored, so the
@@ -137,6 +138,17 @@ export function collectionCommand(ws, collection, verb, args) {
 			// panel that produced that JSON cannot disagree about which records match.
 			const whereJson = oneValue(flags, 'where');
 			const where = whereJson ? load(whereJson) : null;
+			// ⚠ A FLAG NAME IS NOT THE ONLY THING THAT CAN BE MISSPELLED. `--filter nmae=Ada` and
+			// `--sort nmae` are correctly spelled FLAGS whose VALUE names a field that does not exist,
+			// and both answer at exit 0 — an empty listing and an unsorted one. Same silent-empty class,
+			// worse than a bad write because there is nothing to notice. `--where` gets the type check
+			// for the same reason: `--where 'name _eq Ada'` yaml-parses to a STRING, and matchesFilter
+			// then matched every row.
+			if (whereJson && (typeof where !== 'object' || where === null)) throw new Error(`--where takes ONE filter OBJECT and got a ${where === null ? 'null' : typeof where}: ${whereJson}\n  a condition is {"<field>":{"_eq":"<value>"}} — the shorthand for one equality is --filter <field>=<value>`);
+			const sort = oneValue(flags, 'sort');
+			const vocab = ['id', ...Object.keys(d.schema?.properties ?? {})];
+			const stray = [...filters.map(([k]) => k), ...(sort ? [String(sort).replace(/^-/, '')] : [])].find((f) => !vocab.includes(f));
+			if (stray) throw new Error(`${collection} has no field "${stray}"${nearest(stray, vocab) ? ` — did you mean "${nearest(stray, vocab)}"?` : ''} (dt get collections/${collection} lists them)`);
 			const resolve = where ? recordResolver(store) : null;
 			const bf = bodyField(d);
 			const rows = [];
@@ -149,7 +161,6 @@ 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.
-			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')];
@@ -224,6 +235,7 @@ export function collectionCommand(ws, collection, verb, args) {
 		}
 		case 'rm': {
 			const id = need(pos, 0, 'id');
+			if (flags['dry-run']) return dryRunPlan(`rm ${collection}/${id}`, { records: store.ids(collection).has(id) ? 1 : 0, refs: store.findInboundRefs(`${collection}/${id}`).length });
 			const { inboundIgnored } = store.rm(collection, id, { force: !!flags.force });
 			flags.json ? emit(JSON.stringify({ id, removed: true, inboundIgnored })) : console.log(`✔ removed${inboundIgnored ? ` (${inboundIgnored} inbound reference(s) left dangling — run \`dreamteamer check\`)` : ''}`);
 			return 0;
@@ -240,9 +252,11 @@ export function collectionCommand(ws, collection, verb, args) {
 		// no enum describes (operator: "still no dropdown for many things, visibility, status").
 		case 'values': {
 			const field = need(pos, 0, 'field');
-			const out = distinctValues(store, collection, field, {
-				limit: flags.limit === undefined ? undefined : Number(flags.limit),
-			});
+			// ⚠ A BARE `--limit` parses as the boolean `true`, and `Number(true)` is 1 — so it
+			// truncated the vocabulary to one value while the footer claimed "showing 1", which reads
+			// as a fact about the collection. Refused, in `--drop`'s words.
+			if ('limit' in flags && !Number.isFinite(Number(oneValue(flags, 'limit')))) throw new Error(`--limit needs a number: dreamteamer values ${collection} ${field} --limit 20`);
+			const out = distinctValues(store, collection, field, { limit: flags.limit === undefined ? undefined : Number(flags.limit) });
 			if (flags.json) { emit(JSON.stringify(out, null, 2)); return 0; }
 			if (out.skipped) { console.log(`(${collection}.${field} is a ${out.skipped} field — no value vocabulary)`); return 0; }
 			if (!out.values.length) { console.log(`(no values set on ${collection}.${field})`); return 0; }
@@ -326,10 +340,20 @@ function metaReposEnsure(ws, flags, pos) {
 
 // `dreamteamer add modules --name core [--description "…"]`
 function metaModulesAdd(ws, store, flags) {
-	refuseRepeats(flags);
-	const out = createModule(ws, store, { name: oneValue(flags, 'name'), description: oneValue(flags, 'description') });
+	// ⚠ BEFORE the write, as `add collections` does it and for the same reason: naming the mistake
+	// after the call lands a committed module and then exits 1.
+	if (flags.namespace === true) throw new Error("--namespace takes a value: dreamteamer add modules --name <id> --namespace <ns>");
+	const out = createModule(ws, store, {
+		name: oneValue(flags, 'name'),
+		description: oneValue(flags, 'description'),
+		namespace: oneValue(flags, 'namespace'),
+	});
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
 	console.log(`✔ ${out.root}/ — package.json + ${KIND_COUNT} kind folder(s)`);
+	// §6.2 promises the namespace is DECLARED IN THE MODULE, and §8 makes every later
+	// `add collections --module <id>` infer it — so the declaration is echoed, because an inferred
+	// identity the operator did not type is one they must be able to read back.
+	if (out.namespace) console.log(`✔ declared namespace "${out.namespace}" in modules/${out.id}`);
 	console.log('✔ compiled — the module is live (add a collection with `dreamteamer add collections --name <c> --module ' + out.id + '`)');
 	reportCommits(out.commits);
 	return 0;
@@ -337,18 +361,14 @@ function metaModulesAdd(ws, store, flags) {
 
 // `dreamteamer rm modules/core [--force] [--dry-run]`
 function metaModulesRm(ws, store, flags, pos) {
-	refuseRepeats(flags);
 	const id = need(pos, 0, 'module id');
 	const out = removeModule(ws, store, id, { force: !!flags.force, dryRun: !!flags['dry-run'] });
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
-	if (out.dryRun) {
-		console.log(`dry run — dreamteamer rm modules/${id} --force would:`);
-		console.log(planLine(out));
-		if (out.collections.length) console.log(`  sources removed for: ${out.collections.join(', ')}`);
-		if (out.withRecords.length) console.log(`  records left in place and UNINDEXED: ${out.withRecords.join(', ')}`);
-		if (out.dependents.length) console.log(`  dependencies entry dropped from: ${out.dependents.join(', ')}`);
-		return 0;
-	}
+	if (out.dryRun) return dryRunPlan(`rm modules/${id} --force`, out, [
+		out.collections.length ? `sources removed for: ${out.collections.join(', ')}` : null,
+		out.withRecords.length ? `records left in place and UNINDEXED: ${out.withRecords.join(', ')}` : null,
+		out.dependents.length ? `dependencies entry dropped from: ${out.dependents.join(', ')}` : null,
+	]);
 	console.log(`✔ removed module ${out.removed}`);
 	if (out.withRecords.length) console.log(`  ⚠ records remain and are now unindexed: ${out.withRecords.join(', ')}`);
 	if (out.dependents.length) console.log(`  dropped it from ${out.dependents.join(', ')}'s dependencies`);
@@ -359,7 +379,6 @@ function metaModulesRm(ws, store, flags, pos) {
 
 // `dreamteamer rename modules/core shared`
 function metaModulesRename(ws, store, flags, pos) {
-	refuseRepeats(flags);
 	const oldId = need(pos, 0, 'module id');
 	const out = renameModule(ws, store, oldId, need(pos, 1, 'new module id'));
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
@@ -373,12 +392,12 @@ function metaModulesRename(ws, store, flags, pos) {
 
 // `dreamteamer set modules/hr description="…" dependencies=modules/core`
 function metaModulesSet(ws, store, flags, pos) {
-	refuseRepeats(flags);
 	const id = need(pos, 0, 'module id');
 	const changes = { ...pairs(pos.slice(1)), ...stripMeta(flags) };
 	if (!Object.keys(changes).length) throw new Error('nothing to set — pass key=value pairs (description, dependencies, peerDependencies)');
 	const out = setModule(ws, store, id, changes);
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
+	if (out.unchanged) return alreadyThat(`modules/${id} ${out.changed.join(', ')}`);
 	console.log(`✔ ${rel(ws.root, out.file)} — ${out.changed.join(', ')}`);
 	console.log('✔ compiled — the module record is up to date');
 	reportCommits(out.commits);
@@ -389,11 +408,26 @@ function metaModulesSet(ws, store, flags, pos) {
  *  KINDS so the sentence cannot go stale against the list it describes. */
 const KIND_COUNT = KINDS.length;
 
-/** The plan line every destructive verb prints, one shape: `records N · refs M · descriptors K ·
- *  values cleared V`. ONE format, because a reader comparing two dry runs must not have to work out
- *  whether a missing term means zero or means "this verb does not count that". */
-function planLine(plan) {
-	return `  records ${plan.records ?? 0} · refs ${plan.refs ?? 0} · descriptors ${plan.descriptors ?? 0} · values cleared ${plan.cleared ?? 0}`;
+/**
+ * THE ONE PLAN PRINTER, for every verb that moves records or clears values — one shape, `records N ·
+ * refs M · descriptors K · values cleared V`, because a reader comparing two dry runs must not have
+ * to work out whether a missing term means zero or means "this verb does not count that".
+ *
+ * ⚠ FOUR OF THE SIX SPELLINGS DOCUMENTED `--dry-run` AND EXECUTED ANYWAY, and the self-commit made
+ * it durable: `dt rm collections/widgets --dry-run --force` printed "✔ removed collection widgets",
+ * deleted the source and committed it, at exit 0, against a `dt help` that spells `rm <system>/<id>
+ * [--force] [--dry-run]` verbatim. `rm modules/<id>` was the ONE that honoured it. A flag a verb
+ * advertises and ignores is worse than one it does not have — the operator's whole reason for typing
+ * it is that they are not sure yet.
+ *
+ * It counts only what it can count WITHOUT doing the op; an unmeasured term is stated as such in
+ * `extra` rather than guessed at, per `rename collections`' dry run.
+ */
+function dryRunPlan(what, plan, extra) {
+	console.log(`dry run — dreamteamer ${what} would:`);
+	console.log(`  records ${plan.records ?? 0} · refs ${plan.refs ?? 0} · descriptors ${plan.descriptors ?? 0} · values cleared ${plan.cleared ?? 0}`);
+	for (const line of extra ?? []) if (line) console.log(`  ${line}`);
+	return 0;
 }
 
 /**
@@ -417,7 +451,6 @@ function reportCommits(commits) {
 
 // `dreamteamer collections add --name research-docs --template docs`
 function metaCollectionsAdd(ws, store, flags) {
-	refuseRepeats(flags);
 	// ⚠ BEFORE the write, not after. `--namespace=` is the empty STRING (clear it); a bare
 	// `--namespace` parses as `true`, which is a mistake worth naming — and naming it AFTER the call
 	// lands a committed collection and then exits 1, which is the one report shape that lies twice.
@@ -452,7 +485,6 @@ function metaCollectionsAdd(ws, store, flags) {
  * half-applies or has to be explained, and the operator gets no signal about which happened.
  */
 function metaCollectionsSet(ws, store, flags, pos) {
-	refuseRepeats(flags);
 	const name = need(pos, 0, 'collection name');
 	const positional = pairs(pos.slice(1));
 	const changes = { ...positional, ...stripMeta(flags) };
@@ -465,12 +497,7 @@ function metaCollectionsSet(ws, store, flags, pos) {
 	if (moveTo !== undefined) {
 		const out = moveCollection(ws, store, name, String(moveTo), { dryRun: !!flags['dry-run'] });
 		if (flags.json) { emit(JSON.stringify(out)); return 0; }
-		if (out.dryRun) {
-			console.log(`dry run — dreamteamer set collections/${name} module=${moveTo} would:`);
-			console.log(planLine(out));
-			console.log(`  descriptor  ${out.from} → ${out.to} (records stay where they are)`);
-			return 0;
-		}
+		if (out.dryRun) return dryRunPlan(`set collections/${name} module=${moveTo}`, out, [`descriptor  ${out.from} → ${out.to} (records stay where they are)`]);
 		if (!out.moved) { console.log(`✔ ${name} — already owned by ${out.from}, nothing to do`); return 0; }
 		console.log(`✔ ${name}: ${out.from} → ${out.to}`);
 		console.log(`  records     ${out.records} left in place — a move never changes an id`);
@@ -482,6 +509,7 @@ function metaCollectionsSet(ws, store, flags, pos) {
 	if (!Object.keys(changes).length) throw new Error('nothing to set — pass key=value pairs, or module=<id> to move it');
 	const out = setCollectionScalars(ws, store, name, changes, { moduleId: undefined });
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
+	if (out.unchanged) return alreadyThat(`collections/${name} ${out.changed.join(', ')}`);
 	console.log(`✔ ${rel(ws.root, out.file)} — ${out.changed.join(', ')}`);
 	console.log('✔ compiled — the descriptor is up to date');
 	reportCommits(out.commits);
@@ -500,7 +528,6 @@ function metaCollectionsSet(ws, store, flags, pos) {
  * it writes ONE descriptor and keeps the numbers legible.
  */
 function metaCollectionsMove(ws, store, flags, pos) {
-	refuseRepeats(flags);
 	const name = need(pos, 0, 'collection name');
 	store.descriptor(name);
 	const rows = [...store.readAll('collections')]
@@ -541,7 +568,6 @@ function metaCollectionsMove(ws, store, flags, pos) {
  *  this is the only way to see what a given module actually wrote, which is the question an overlay
  *  makes unanswerable from the runtime alone. */
 function metaCollectionsGet(ws, store, flags, pos) {
-	refuseRepeats(flags);
 	const name = need(pos, 0, 'collection name');
 	const moduleId = oneValue(flags, 'module');
 	const { file } = collectionSourceFileFor(ws, store, name, moduleId);
@@ -554,7 +580,6 @@ function metaCollectionsGet(ws, store, flags, pos) {
 // 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 rename collections/<old> <new> | collections/<old> --namespace <ns>');
 	// `--namespace health` on its own moves the collection INTO that namespace keeping its bare name,
@@ -566,15 +591,14 @@ function metaCollectionsRename(ws, store, flags, pos) {
 	if (flags['dry-run']) {
 		const d = store.descriptor(oldName);
 		const records = store.ids(oldName).size;
-		console.log(`dry run — dreamteamer rename collections/${oldName} ${newName} would:`);
-		console.log(planLine({ records, refs: 0, descriptors: 1, cleared: 0 }));
-		console.log(`  records  ${d.storage.path} → ${defaultStoragePath(newName, store.namespaces, ws.pkg.dreamteamer?.['data-path'] ?? 'data')}`);
 		// ⚠ `refs` is honestly 0 here and the line says so. Counting them would mean running the batch
 		// rewrite to find out, which IS the op — and a number the plan cannot know is worse than a
 		// stated gap: the plan line has a fixed shape precisely so a reader never has to guess whether
 		// a term is zero or unmeasured.
-		console.log('  refs are counted only by the real run — the rewrite is what discovers them');
-		return 0;
+		return dryRunPlan(`rename collections/${oldName} ${newName}`, { records, descriptors: 1 }, [
+			`records  ${d.storage.path} → ${defaultStoragePath(newName, store.namespaces, ws.pkg.dreamteamer?.['data-path'] ?? 'data')}`,
+			'refs are counted only by the real run — the rewrite is what discovers them',
+		]);
 	}
 	const out = renameCollection(ws, store, oldName, newName);
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
@@ -592,8 +616,8 @@ 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');
+	if (flags['dry-run']) return dryRunPlan(`rm collections/${name}`, { records: store.ids(name).size, descriptors: 1 }, [`descriptor removed; records under ${store.descriptor(name).storage.path} stay in place and become unindexed`]);
 	const out = removeCollection(ws, store, name, { force: !!flags.force });
 	flags.json ? emit(JSON.stringify(out)) : console.log(`✔ removed collection ${out.removed}`);
 	console.log('✔ compiled — the collection is gone');
@@ -603,7 +627,6 @@ 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
@@ -611,7 +634,7 @@ function metaAddField(ws, store, collection, flags) {
 	const stray = (prop.items ?? prop)['x-reference'] === undefined && relationFlagsStated(flags);
 	if (stray) throw new Error(`--${stray} needs a --type <collection> reference.`);
 	const out = addField(ws, store, collection, { name: flags.name, prop, required: flags.required === 'true', moduleId: oneValue(flags, 'module') });
-	if (out.unchanged) return alreadyThat(collection, flags.name);
+	if (out.unchanged) return alreadyThat(`${collection}.${flags.name}`);
 	console.log(`✔ ${rel(ws.root, out.file)}${out.extends ? ` (extends ${out.extends})` : ''}`);
 	console.log('✔ compiled — the field is live');
 	reportCommits(out.commits);
@@ -622,8 +645,8 @@ function metaAddField(ws, store, collection, flags) {
 
 /** The idempotent answer, in `rename-collection`'s words — a command that asks for what is already
  *  there succeeded, and the operator needs to know which field it was talking about. */
-function alreadyThat(collection, field) {
-	console.log(`✔ ${collection}.${field} — already exactly that, nothing to do`);
+function alreadyThat(subject) {
+	console.log(`✔ ${subject} — already exactly that, nothing to do`);
 	return 0;
 }
 
@@ -655,7 +678,6 @@ 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
@@ -663,7 +685,7 @@ function metaUpdateField(ws, store, collection, flags) {
 	// `flags` for the VALUES and `stated` for what the caller meant to restate: updateField carries
 	// every unstated relation keyword forward from the previous prop.
 	const out = updateField(ws, store, collection, flags.name, { prop, required, flags, stated: statedKeywords(flags), moduleId: oneValue(flags, 'module') });
-	if (out.unchanged) return alreadyThat(collection, flags.name);
+	if (out.unchanged) return alreadyThat(`${collection}.${flags.name}`);
 	console.log(`✔ ${rel(ws.root, out.file)}${out.extends ? ` (extends ${out.extends})` : ''}`);
 	console.log('✔ compiled — the field is updated');
 	reportCommits(out.commits);
@@ -677,16 +699,12 @@ 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 moduleId = oneValue(flags, 'module');
 	if (flags['dry-run']) {
 		const plan = removeFieldPlan(store, collection, name);
-		console.log(`dry run — dreamteamer remove-field ${collection} --name ${name} would:`);
-		console.log(planLine(plan));
-		if (plan.staleViews.length) console.log(`  ui-views still listing it as a column: ${plan.staleViews.join(', ')}`);
-		return 0;
+		return dryRunPlan(`remove-field ${collection} --name ${name}`, plan, [plan.staleViews.length ? `ui-views still listing it as a column: ${plan.staleViews.join(', ')}` : null]);
 	}
 	const out = removeField(ws, store, collection, name, { moduleId });
 	flags.json ? emit(JSON.stringify(out)) : console.log(`✔ removed field ${collection}.${out.removed}`);
@@ -709,7 +727,6 @@ const ENTITY_KINDS = new Set(['skills', 'agents', 'commands', 'command-bindings'
 const SCAFFOLDABLE = new Set(['skills']);
 
 function metaEntityVerb(ws, store, kind, verb, flags, pos) {
-	refuseRepeats(flags);
 	const one = kind.replace(/s$/, '');
 	if (verb === 'add') {
 		const name = oneValue(flags, 'name');
@@ -726,7 +743,9 @@ function metaEntityVerb(ws, store, kind, verb, flags, pos) {
 		return 0;
 	}
 	if (verb === 'rm') {
-		const out = removeEntity(ws, store, kind, need(pos, 0, `${one} id`));
+		const id0 = need(pos, 0, `${one} id`);
+		if (flags['dry-run']) return dryRunPlan(`rm ${kind}/${id0}`, { descriptors: 1 }, [`the ${one} source is removed; nothing else moves`]);
+		const out = removeEntity(ws, store, kind, id0);
 		if (flags.json) { emit(JSON.stringify(out)); return 0; }
 		console.log(`✔ removed ${one} ${out.removed}`);
 		console.log('✔ compiled — it is gone');
@@ -748,6 +767,7 @@ function metaEntityVerb(ws, store, kind, verb, flags, pos) {
 	if (!Object.keys(changes).length) throw new Error(`nothing to set — pass key=value pairs (a ${one}'s frontmatter keys)`);
 	const out = setEntityFrontmatter(ws, store, kind, id, changes);
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
+	if (out.unchanged) return alreadyThat(`${kind}/${id} ${out.changed.join(', ')}`);
 	console.log(`✔ ${rel(ws.root, out.file)} — ${out.changed.join(', ')}`);
 	console.log('✔ compiled — the change is live');
 	reportCommits(out.commits);
@@ -756,25 +776,27 @@ function metaEntityVerb(ws, store, kind, verb, flags, pos) {
 
 /** The path `revert`'s refusal names — where a human edits this compiled entity. */
 function sourceHintFor(store, collection) {
-	const d = store.descriptors.get(collection);
-	return d?.storage?.path ? `modules/*/${d.storage.path}/` : `modules/*/${collection}/`;
+	// ⚠ `modules` is the one system collection that is PROJECTED rather than stored as a kind folder:
+	// its source is each module's package.json. Deriving the hint from `storage.path` gave
+	// `modules/*/modules/`, which `git ls-files` matches nothing at all — a correct refusal handing
+	// over an unusable remedy.
+	if (collection === 'modules') return 'modules/*/package.json';
+	return `modules/*/${store.descriptors.get(collection)?.storage?.path ?? collection}/`;
 }
 
 // `dreamteamer rename-field people --name employer --to company`
 function metaRenameField(ws, store, collection, flags) {
-	refuseRepeats(flags);
 	const from = oneValue(flags, 'name') ?? oneValue(flags, 'field');
 	if (!from) throw new Error(`missing --name <field>: dreamteamer rename-field ${collection} --name <field> --to <new-name>`);
 	const to = oneValue(flags, 'to');
 	if (flags['dry-run']) {
 		const plan = renameFieldPlan(store, collection, from);
-		console.log(`dry run — dreamteamer rename-field ${collection} --name ${from} --to ${to ?? '<new-name>'} would:`);
-		console.log(planLine(plan));
 		// ⚠ The same honesty the `rename collections` dry run needs, for the same reason: a number the
 		// plan cannot know is worse than a stated gap.
-		console.log('  descriptors, ui-views and command-bindings naming it are counted by the real run —');
-		console.log('  the rewrite is what discovers which of them carry the name');
-		return 0;
+		return dryRunPlan(`rename-field ${collection} --name ${from} --to ${to ?? '<new-name>'}`, plan, [
+			'descriptors, ui-views and command-bindings naming it are counted by the real run —',
+			'the rewrite is what discovers which of them carry the name',
+		]);
 	}
 	const out = renameField(ws, store, collection, from, to, { moduleId: oneValue(flags, 'module') });
 	if (flags.json) { emit(JSON.stringify(out)); return 0; }
@@ -877,11 +899,16 @@ 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']);
+// ⚠ `module` is a VERB OPTION, exactly as it is on every other verb that takes one (see META_FLAGS)
+// — it says WHERE the source lands and is never a key of the view. Omitting it here is what wrote
+// `module: core` into the yaml as a field.
+const VIEW_META_FLAGS = new Set(['id', 'json', 'force', 'module']);
 
 function metaUiView(ws, store, verb, flags, pos) {
 	if (verb === 'rm') {
-		const out = removeUiView(ws, store, need(pos, 0, 'ui-view id'));
+		const viewId = need(pos, 0, 'ui-view id');
+		if (flags['dry-run']) return dryRunPlan(`rm ui-views/${viewId}`, { descriptors: 1 }, ['the view source is removed; its route stops resolving']);
+		const out = removeUiView(ws, store, viewId);
 		flags.json ? emit(JSON.stringify(out)) : console.log(`✔ removed ui-view ${out.removed}`);
 		console.log('✔ compiled — the route is gone');
 		reportCommits(out.commits);
@@ -919,8 +946,10 @@ function metaUiView(ws, store, verb, flags, pos) {
 	// saved from the CLI and one saved from the panel land on the SAME record.
 	id ??= slug(view.path);
 
-	const out = saveUiView(ws, store, { id, view });
-	flags.json ? emit(JSON.stringify(out)) : console.log(`✔ ${rel(ws.root, out.file)}`);
+	const out = saveUiView(ws, store, { id, view, moduleId: oneValue(flags, 'module') });
+	if (flags.json) { emit(JSON.stringify(out)); return 0; }
+	if (out.unchanged) return alreadyThat(`ui-views/${id}`);
+	console.log(`✔ ${rel(ws.root, out.file)}`);
 	console.log(`✔ compiled — ${view.path} is live`);
 	reportCommits(out.commits);
 	return 0;
@@ -938,7 +967,9 @@ function metaUiView(ws, store, verb, flags, pos) {
 export function relationsCommand(ws, args) {
 	const store = new Store(ws);
 	const { flags, pos } = parseArgs(args);
-	if (pos[0] === 'rebuild') return relationsRebuild(store, flags, pos);
+	const rebuilding = pos[0] === 'rebuild';
+	refuseUnknownFlags(store, (rebuilding ? pos[1] : pos[0]) ?? '', rebuilding ? 'rebuild' : 'relations', flags);
+	if (rebuilding) return relationsRebuild(store, flags, pos);
 
 	// `store.relations()` is `relationsOf(this.descriptors)` memoized per Store — going through it
 	// rather than calling relationsOf here keeps one decoder for the whole process.
@@ -1093,22 +1124,6 @@ function oneValue(flags, key) {
 	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) {
@@ -1158,3 +1173,98 @@ const fmtCell = (v) => (v === undefined ? '-' : Array.isArray(v) ? v.join(',') :
 function rel(root, p) {
 	return p.startsWith(root) ? p.slice(root.length + 1) : p;
 }
+
+/**
+ * THE ONE PLACE A FLAG NAME IS VALIDATED — every record, system and field verb goes through
+ * `collectionCommand`, so the check lives beside the parser they share rather than being
+ * re-invented per verb.
+ *
+ * ⚠ IT EXISTS BECAUSE THE PARSER USED TO SWALLOW EVERYTHING. `dt add modules --name hr --bogusflag x`
+ * succeeded silently, so a misspelled flag and a supported one were indistinguishable — and that is
+ * what let `add modules --namespace hr` be accepted-and-ignored for a whole release with nobody
+ * noticing. The worst instance was `--dryrun`, where the swallowed flag is the one standing between
+ * a plan and a self-committed delete.
+ *
+ * TWO VOCABULARIES, and the split is what keeps the refusal honest. A verb's OPTIONS are closed and
+ * enumerated here; an entity's own KEYS are open and cannot be — `dt list people --status todo` is a
+ * shorthand filter on a declared field, `dt add people --name Ada` writes one, and a ui-view's
+ * `options.*` is an open bag by design. So the allowlist is the table PLUS the target's declared
+ * properties, and nothing is refused that either half can name.
+ *
+ * ⚠ A REFUSAL THAT REJECTS A VALID FLAG IS WORSE THAN THE SILENCE IT REPLACES, which is why a verb
+ * with no table entry is left exactly as it was rather than being guessed at — and why the field
+ * verbs' row is the whole `fieldDef` vocabulary, read off nothing, so a flag added there has to be
+ * added here too or its own test fails.
+ *
+ * A key is `<collection>:<verb>` where the system entity has its own interceptor, `<verb>` otherwise.
+ */
+export const FIELD_FLAGS = ['json', 'module', 'name', 'field', 'type', 'options', 'default-value', 'default', 'required', 'description', 'many', 'inverse', 'inverse-description', 'unique', 'body', 'on-delete', 'mirror-of', 'target'];
+const JSON_ONLY = ['json'];
+const FORCE_RM = ['json', 'force', 'dry-run'];
+const NAV_MOVE = ['json', 'after', 'before', 'top', 'bottom'];
+
+export const VERB_FLAGS = {
+	list: ['json', 'filter', 'where', 'sort'], get: JSON_ONLY, add: ['json', 'id', 'from', 'force'], set: JSON_ONLY,
+	rm: FORCE_RM, rename: JSON_ONLY, move: [...NAV_MOVE, 'init'], values: ['json', 'limit'],
+	history: JSON_ONLY, diff: ['json', 'hash'], revert: ['json', 'hash'],
+	ensure: ['json', 'all'], for: ['json', 'ids'], relations: JSON_ONLY, rebuild: ['json', 'drop'],
+	'add-field': FIELD_FLAGS, 'update-field': FIELD_FLAGS,
+	'remove-field': ['json', 'module', 'name', 'field', 'dry-run'],
+	'rename-field': ['json', 'module', 'name', 'field', 'to', 'dry-run'],
+	'collections:add': ['json', 'module', 'name', 'namespace', 'template', 'description', 'suffix', 'id-shape'],
+	'collections:get': ['json', 'module'], 'collections:set': ['json', 'module', 'dry-run'],
+	'collections:rm': FORCE_RM, 'collections:rename': ['json', 'namespace', 'dry-run'], 'collections:move': NAV_MOVE,
+	'modules:add': ['json', 'name', 'description', 'namespace'], 'modules:rename': JSON_ONLY, 'modules:rm': FORCE_RM,
+	'modules:set': ['json', 'description', 'namespaces', 'dependencies', 'peerDependencies'],
+	// the identity kinds: `add` scaffolds, `rm`/`rename` fall through to the generic rows, and `set`
+	// is deliberately UNCHECKED — a skill's frontmatter is an open document (`allowed-tools`, `model`,
+	// whatever a harness reads), so there is no closed set to check it against.
+	'skills:add': ['json', 'module', 'name', 'description'],
+	'ui-views:add': ['json', 'module', 'id', 'force'], 'ui-views:set': ['json', 'module', 'id', 'force'], 'ui-views:rm': FORCE_RM,
+};
+
+/** Edit distance, capped — enough to turn `--fliter` into "did you mean --filter?", and to refuse to
+ *  guess at anything further away than a typo. */
+function nearest(word, candidates) {
+	const distance = (c) => {
+		let prev = [...Array(word.length + 1).keys()];
+		for (let i = 1; i <= c.length; i++) {
+			const row = [i];
+			for (let j = 1; j <= word.length; j++) row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (c[i - 1] === word[j - 1] ? 0 : 1));
+			prev = row;
+		}
+		return prev[word.length];
+	};
+	const cap = Math.min(3, Math.ceil(word.length / 2));
+	return candidates.map((c) => [c, distance(c)]).filter(([, n]) => n <= cap).sort((a, b) => a[1] - b[1])[0]?.[0] ?? null;
+}
+
+function refuseUnknownFlags(store, collection, verb, flags) {
+	const d = store.descriptors.get(collection);
+	const known = VERB_FLAGS[`${collection}:${verb}`]
+		?? (ENTITY_KINDS.has(collection) && verb === 'add' ? VERB_FLAGS['skills:add'] : VERB_FLAGS[verb]);
+	if (!known) return; // no declared vocabulary — left exactly as it was rather than guessed at
+	// The OPEN half: a data collection's own fields (shorthand filters and field writes), and the
+	// declared keys of an entity `set` writes (`--layout` on a view, and dotted `options.sort`).
+	const system = d?.storage?.base === 'runtime';
+	const openOf = !system ? (['list', 'add', 'set'].includes(verb) ? `field of ${collection}` : null)
+		: (collection === 'ui-views' && verb !== 'rm') || (ENTITY_KINDS.has(collection) && verb === 'set') ? `declared key of ${collection}` : null;
+	const open = openOf ? Object.keys(d?.schema?.properties ?? {}) : [];
+	const allowed = new Set([...known, ...open]);
+	for (const f of Object.keys(flags)) {
+		if (allowed.has(f) || (openOf && allowed.has(f.split('.')[0]))) continue;
+		const near = nearest(f, [...allowed]);
+		throw new Error(`unknown flag "--${f}" on \`dt ${verb} ${collection}\`${near ? ` — did you mean --${near}?` : ''}\n  known: ${[...known].sort().map((k) => `--${k}`).join(', ')}${openOf ? `, plus any ${openOf}` : ''}`);
+	}
+	// ⚠ AND THE REPEAT REFUSAL, which used to be 15 hand-written `refuseRepeats(flags)` lines — one
+	// per meta verb, and a new verb had to remember it. A SCHEMA verb takes one value per flag (none
+	// of them means a list by repetition), so the same table that says which flags exist says which
+	// verbs the rule applies to: everything with a closed vocabulary EXCEPT the open halves, where a
+	// repeat legitimately composes (`--filter a=1 --filter b=2`, `--tags a --tags b`). `ui-views`
+	// keeps its own message, which names both spellings of the fix. ⚠ THE FIELD VERBS COUNT AS SCHEMA
+	// VERBS EVEN THOUGH THEIR TARGET IS A DATA COLLECTION — `add-field notes --name x --name y` is the
+	// case the old helper was written for, and keying the rule on the target alone excused it.
+	if (collection === 'ui-views' || (!system && !verb.endsWith('-field'))) return;
+	const dup = Object.entries(flags).find(([, v]) => Array.isArray(v));
+	if (dup) throw new Error(`--${dup[0]} was given ${dup[1].length} times, and a schema verb takes ONE value per flag: ${dup[1].map((x) => `--${dup[0]} ${x}`).join(' ')}`);
+}

package/src/schema-ops.js

@@ -98,6 +98,22 @@ function writeGated(ws, store, files, subject, mutate, after, { commentsMayDecre
 				throw e;
 			}
 		}
+		// ⚠ A WRITE THAT CHANGED NO BYTES MUST NOT REACH `git commit`. `git commit` on an empty index
+		// exits NON-ZERO, so the catch below read a successful no-op as a failed op and reported
+		// `✖ git commit failed — the schema change was rolled back` with the raw git command appended,
+		// at exit 1 — for `dt set collections/people description=<the value it already has>`, which
+		// asked for nothing and got nothing. Every sibling verb already has the graceful spelling
+		// ("already named that, nothing to do"), and the documented namespace cleanup path
+		// (`dt set modules/<m> namespaces=<ns>` where it is already declared) ran straight into it.
+		//
+		// Compared as BYTES, after the gate compile: an op whose mutation is a re-serialization can
+		// produce an identical file, and "identical" is the only definition of no-op the caller can
+		// act on.
+		const moved = snapshots.some(({ f, prev }) => {
+			const now = fs.existsSync(f) ? fs.readFileSync(f) : null;
+			return now === null ? prev !== null : prev === null || !now.equals(prev);
+		});
+		if (!moved && !extra.files.length) return { ...extra, commits: [], unchanged: true };
 		const rels = [...files, ...extra.files].map((f) => path.relative(ws.root, f));
 		// Schema ops commit UNCONDITIONALLY — `auto-commit` governs RECORD writes only. A source
 		// change is inseparable from the compile that validated it, and `dt commit` scopes itself
@@ -240,7 +256,7 @@ function editWorkspacePkg(ws, mutate) {
 	return file;
 }
 
-export function createModule(ws, store, { name, description }) {
+export function createModule(ws, store, { name, description, namespace }) {
 	if (!name || name === true) throw new Error('missing module name — dreamteamer add modules --name <id>');
 	if (!MODULE_ID.test(name)) {
 		throw new Error(`invalid module id "${name}" — lowercase alphanumeric with single hyphens. It becomes a folder name, a package name and a record id at once, so there is only one spelling.`);
@@ -253,6 +269,23 @@ export function createModule(ws, store, { name, description }) {
 
 	const dt = {};
 	if (typeof description === 'string' && description) dt.description = description;
+	// §6.2: `--namespace hr` DECLARES THE NAMESPACE IN THE MODULE, which is the whole point of §8 —
+	// the workspace's effective set is the union of what its modules declare, so a module that owns a
+	// namespace can be copied alone into a bare workspace and still compile.
+	//
+	// ⚠ It used to be dropped on the floor. `dt add modules --name hr --namespace hr` reported ✔,
+	// shipped `"dreamteamer": {}`, left the manifest's `namespaces: []`, and the next
+	// `add collections --module hr` then created an UNPREFIXED collection — four steps of silence
+	// behind one accepted-and-ignored flag. Normalized here rather than trusted: a leading or
+	// trailing slash in a declaration re-splits every reference under it.
+	const ns = typeof namespace === 'string' ? namespace.replace(/^\/+|\/+$/g, '') : '';
+	if (ns) {
+		const owner = moduleRows(store).find((r) => normalizeNamespaces(r.fields.namespaces).includes(ns));
+		// compile refuses two declarations of one namespace, and refusing it HERE names the verb that
+		// fixes it instead of rolling a created module back over a compile error.
+		if (owner) throw new Error(`namespace "${ns}" is already declared by ${owner.id} — one owner. Remove it there first (dt set modules/${owner.id} namespaces=…), or pick another namespace.`);
+		dt.namespaces = [ns];
+	}
 	// `files` is the npm publish surface: every kind a module CAN ship, so a kind added to the engine
 	// does not silently stop being packaged.
 	const mpkg = { name, private: true, version: '0.0.1', files: [...KINDS], dreamteamer: dt };
@@ -272,7 +305,7 @@ export function createModule(ws, store, { name, description }) {
 		},
 		undo: () => fs.rmSync(root, { recursive: true, force: true }),
 	});
-	return { id: name, root: path.relative(ws.root, root), file: pkgFile, commits: out.commits };
+	return { id: name, root: path.relative(ws.root, root), file: pkgFile, namespace: ns || null, commits: out.commits };
 }
 
 /** The settable fields of a `modules` record, and how each translates from the record-shaped value
@@ -338,7 +371,7 @@ export function setModule(ws, store, id, changes) {
 			});
 		}
 	}, undefined, { commentsMayDecrease: true });
-	return { id, file, changed, commits: gate.commits };
+	return { id, file, changed, commits: gate.commits, unchanged: gate.unchanged };
 }
 
 export function removeModule(ws, store, id, { force = false, dryRun = false } = {}) {
@@ -755,6 +788,15 @@ export function setCollectionScalars(ws, store, name, changes, { moduleId } = {}
 			throw new Error(`${key}: ${collectionMissingFields(name, missing)} — declare it first (dreamteamer add-field ${name} --name ${missing[0]} --type <t>).`);
 		}
 	}
+	// ⚠ NAMED, not resolved to an overlay. `collectionSourceFile` falls back to a workspace-module
+	// path for a base it cannot write, which is right for `add-field` (an overlay IS the remedy) and
+	// wrong here: a collection-level scalar has no overlay spelling, so the fallback produced
+	// `modules/default/collections/repos.collection.yaml is not on disk — run compile and re-run`,
+	// and compiling will never help. `rm` and `rename` already say the true sentence.
+	const owned = baseDescriptorSource(ws, name).base;
+	if (owned && IN_NODE_MODULES(owned)) {
+		throw new Error(`"${name}" ships from node_modules (${owned}) — a write there is erased by the next \`npm install\`, and a collection-level scalar has no overlay spelling. Add "<module>/${name}" to dreamteamer.disable and declare your own instead.`);
+	}
 	const { file } = collectionSourceFile(ws, store, name, moduleId, { subject: name });
 	if (!fs.existsSync(file)) throw new Error(`${path.relative(ws.root, file)} is not on disk — run \`dreamteamer compile\` and re-run.`);
 	const previousText = fs.readFileSync(file, 'utf8');
@@ -770,7 +812,7 @@ export function setCollectionScalars(ws, store, name, changes, { moduleId } = {}
 		}
 		fs.writeFileSync(file, writeSource(previousText, doc));
 	});
-	return { name, file, changed, commits: gate.commits };
+	return { name, file, changed, commits: gate.commits, unchanged: gate.unchanged };
 }
 
 // ---- rename-field ------------------------------------------------------------------------------
@@ -965,10 +1007,19 @@ export function renameField(ws, store, collection, from, to, { moduleId, dryRun
 						if (String(doc.collection ?? '') !== `collections/${collection}`) continue;
 						const keys = kind === 'ui-views' ? ['filter'] : ['can-enter', 'can-exit'];
 						let changed = false;
-						if (Array.isArray(doc.options?.columns) && doc.options.columns.includes(from)) {
-							doc.options.columns = doc.options.columns.map((c) => (c === from ? to : c));
+						// The field-name LISTS: `columns` is honoured by every layout, `ref_fields` and
+						// `value_fields` are the diagram's link-by pickers. Same vocabulary `list_fields` uses.
+						for (const key of ['columns', 'ref_fields', 'value_fields']) {
+							if (!Array.isArray(doc.options?.[key]) || !doc.options[key].includes(from)) continue;
+							doc.options[key] = doc.options[key].map((c) => (c === from ? to : c));
 							changed = true;
 						}
+						// ⚠ AND `options.sort`, which is a field name with an optional `-` in front of it. It
+						// was the one §3.2 surface the rename missed, and the miss is invisible: `dt check`
+						// reports 0 violations for a view sorting on a field that no longer exists, so the
+						// listing silently falls back to an arbitrary order.
+						const sorted = /^(-?)(.+)$/.exec(typeof doc.options?.sort === 'string' ? doc.options.sort : '');
+						if (sorted && sorted[2] === from) { doc.options.sort = sorted[1] + to; changed = true; }
 						for (const key of keys) if (rewriteFilterField(doc[key], from, to)) changed = true;
 						if (!changed) continue;
 						const after = writeSource(before, doc);
@@ -2309,9 +2360,17 @@ function uiViewSourceFile(ws, id) {
 // saved views (M3): a studio-saved view IS a ui-view record — but ui-views are
 // system-stored (sources + compile), so the write goes through the same gate as any
 // other schema op. the studio "save view" button lands here.
-export function saveUiView(ws, store, { id, view }) {
+export function saveUiView(ws, store, { id, view, moduleId }) {
 	if (!id || !/^[a-z0-9][a-z0-9-/]*$/.test(id)) throw new Error(`invalid ui-view id "${id}" — lowercase slug required`);
-	const { file: dest, shipped } = uiViewSourceFile(ws, id);
+	// §5: `add` on a system collection takes `--module`. It used to be dropped by the parser and then
+	// assigned into the VIEW as a field called `module` — `dt add ui-views … --module core` wrote
+	// `module: core` into the yaml, compiled clean, and self-committed a workspace only `dt check`
+	// would later object to. An explicit target module resolves the destination; without one the
+	// manifest answers (an existing view is edited where it lives), and the workspace module is the
+	// fallback for a new one.
+	const { file: dest, shipped } = moduleId
+		? { file: path.join(kindDir(path.join(ws.root, moduleRecord(store, moduleId).fields.path), 'ui-views'), `${id}.ui-view.yaml`), shipped: null }
+		: uiViewSourceFile(ws, id);
 	if (shipped && /(^|\/)node_modules\//.test(shipped))
 		throw new Error(`ui-view "${id}" is shipped by an installed package (${shipped}) — a write there is erased by the next npm install.\n  save it under a different name, or disable it (dreamteamer.disable) and re-create it.`);
 	const existed = fs.existsSync(dest);
@@ -2325,7 +2384,7 @@ export function saveUiView(ws, store, { id, view }) {
 		fs.mkdirSync(path.dirname(dest), { recursive: true });
 		fs.writeFileSync(dest, writeSource(previous, view));
 	}, undefined, { commentsMayDecrease: true });
-	return { id, file: dest, updated: existed, commits: gate.commits };
+	return { id, file: dest, updated: existed, commits: gate.commits, unchanged: gate.unchanged };
 }
 
 export function removeUiView(ws, store, id) {
@@ -2716,6 +2775,16 @@ export function setEntityFrontmatter(ws, store, kind, id, changes) {
 	const { dir, file, shipped } = entitySource(ws, kind, id);
 	if (!shipped) throw new Error(`${kind.replace(/s$/, '')} "${id}" does not exist — dt list ${kind}`);
 	refuseNpmEntity(kind, id, shipped);
+	// ⚠ THE DESCRIPTOR IS THE AUTHORITY, and the engine was disagreeing with itself: `dt set
+	// skills/<id> descripton="oops"` wrote the typo, compiled, SELF-COMMITTED — and then `dt check`
+	// failed on the very workspace the self-commit exists to keep valid, because the `skills`
+	// descriptor declares a closed set of properties and check validates against it. "Frontmatter is
+	// an open document" was the wrong half to believe: if a key is not in the descriptor, `check`
+	// will reject it, so `set` refuses it first. Its two siblings already read this way
+	// (`setCollectionScalars`, `setModule`), and a body field is not settable from the CLI at all.
+	const props = store.descriptors.get(kind)?.schema?.properties ?? {};
+	const unknown = Object.keys(changes).find((k) => !(k in props) || props[k]?.['x-body'] === true);
+	if (unknown) throw new Error(`"${unknown}" is not a settable key of ${kind} — declared: ${Object.keys(props).filter((k) => props[k]?.['x-body'] !== true).join(', ')}. \`dreamteamer check\` rejects anything else, so this is refused before it is committed.`);
 	const target = shape.folder ? path.join(dir, 'SKILL.md') : file;
 	// A YAML source (a binding, a template) is a whole document; a markdown one has frontmatter and
 	// prose. `writeSource` round-trips both — the difference is only which text it is handed.
@@ -2740,7 +2809,7 @@ export function setEntityFrontmatter(ws, store, kind, id, changes) {
 			fs.writeFileSync(target, text);
 		}
 	}, undefined, { commentsMayDecrease: true });
-	return { id, file: target, changed, commits: gate.commits };
+	return { id, file: target, changed, commits: gate.commits, unchanged: gate.unchanged };
 }
 
 /**