dreamteamer 0.9.0 → 0.10.0

package/collections/collections.collection.yaml

@@ -11,6 +11,17 @@ schema:
     description:
       type: string
       description: What kind of thing this collection holds, in one line.
+    use_when:
+      type: string
+      description: >-
+        WHEN to reach for this collection, in one clause — rendered into the orientation block every
+        agent session loads. OPTIONAL and usually absent: for most collections the trigger IS the
+        description (`contacts` = a person; you use it when you have a person), and a restatement
+        there costs every session tokens while diluting the few that carry real information. The
+        test: author this only when an agent that FULLY UNDERSTANDS the description would still not
+        know to reach for the collection. It spans both acts — read ("you are about to diagnose a
+        defect — search here first") and write ("a day needs planning"). NOT a place for procedure:
+        a `how` belongs in the module's skill, this field holds a `when`.
     title:
       type: string
       description: What to call this collection in the nav and page headers. DERIVED from `name` by title-casing when absent — author it only when that is wrong (`ui-views` → `UI Views`).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "A workspace compiler for coding agents \u2014 schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",

package/src/compile.js

@@ -696,6 +696,17 @@ export function compile({ root, pkg }) {
 		}
 		const rt = path.join('collections', `${name}.collection.yaml`);
 		entries.set(rt, { sources: [...group.map((g) => g.src), ...templateSources], bytes: Buffer.from(dump(merged)) });
+		// A descriptor with no `description:` renders in the orientation block as a bare NAME — an
+		// agent learns the noun exists and nothing about when it is the right one. Derived pressure
+		// rather than a heroic backfill pass, and the same shape as the per-missing-env-key warning:
+		// non-blocking, named per offender, so the gap converges instead of being rediscovered.
+		//
+		// ⚠ Deliberately NO equivalent warning for `use_when`. That field is optional and correct to
+		// omit on most collections — warning on it would invert its authoring test and manufacture a
+		// restatement of the description on every collection that does not need one.
+		if (merged.storage.base !== 'runtime' && !String(merged.description ?? '').trim()) {
+			console.warn(`⚠ collection ${name} has no description — it renders as a bare name in the orientation block every session loads`);
+		}
 		counts.collections++;
 		if (extenders.length) mergedCount++;
 	}
@@ -840,7 +851,13 @@ export function compile({ root, pkg }) {
 	// clear each kind's folder, plus `system/` — a runtime compiled by a pre-flatten engine has the
 	// whole tree under there, and leaving it would keep stale descriptors on disk beside the fresh
 	// ones. Never `rm -rf` the runtime root itself: it also holds the write lock.
-	for (const kind of KINDS) fs.rmSync(path.join(RUNTIME, kind), { recursive: true, force: true });
+	// ⚠ DERIVED_KINDS too, not just KINDS. `modules/` is projected rather than staged, so it was not
+	// in this loop and never got cleared — a module that was RENAMED or REMOVED left its old record
+	// behind forever, listing collections that no longer exist. `check` reads those records like any
+	// other, so it surfaced as a dangling reference in a file nobody had touched, twice in one day
+	// (`hq3-workspace` after the workspace-module rename, and again after `crm` was folded in). The
+	// runtime is build output; stale build output is the compiler's problem, not the reader's.
+	for (const kind of [...KINDS, ...DERIVED_KINDS]) fs.rmSync(path.join(RUNTIME, kind), { recursive: true, force: true });
 	fs.rmSync(path.join(RUNTIME, 'system'), { recursive: true, force: true });
 	fs.rmSync(path.join(RUNTIME, 'ui'), { recursive: true, force: true });
 	for (const [rt, e] of entries) {

package/src/harnesses.js

@@ -56,7 +56,7 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		}
 		summary.push(`claude-code → .claude (${n} files)`);
 	}
-	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version) : null);
+	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version, entries) : null);
 
 	// ---- shared cross-agent skills mirror (.agents/skills) — codex/pi discover it,
 	// cursor/gemini blocks point at it. written once no matter how many harnesses use it.
@@ -73,17 +73,17 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	}
 
 	// ---- codex + pi: both read root AGENTS.md; one block serves both ----------------
-	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version) : null);
+	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version, entries) : null);
 	if (on('codex')) summary.push('codex → AGENTS.md block');
 	if (on('pi')) summary.push('pi → AGENTS.md block + .agents/skills');
 
 	// ---- gemini-cli: GEMINI.md is its context file -----------------------------------
-	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version) : null);
+	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version, entries) : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
 	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
 	if (on('cursor')) {
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version)}\n\n${STAMP}\n`;
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -123,6 +123,161 @@ function buildSkillsIndex(entries) {
 	return index.sort((a, b) => a.id.localeCompare(b.id));
 }
 
+/** One flattened line of prose from a possibly-folded YAML scalar. */
+const flat = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+
+/** collection name -> description / use_when / whether it is a schema-ops collection, read from the
+ *  compiled descriptor BYTES compile already holds. Same pattern as buildSkillsIndex: no filesystem
+ *  read, and deliberately nothing that touches `data/` — see collectionsSection for why. */
+function buildCollectionsIndex(entries) {
+	const index = [];
+	for (const [rt, e] of entries) {
+		const m = /^collections\/(.+)\.collection\.yaml$/.exec(rt);
+		if (!m) continue;
+		let d = {};
+		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { /* unparseable descriptor */ }
+		index.push({
+			name: d.name ?? m[1],
+			// DERIVED, never a hardcoded name list: `runtime` is exactly the schema-ops set
+			// (collections, commands, skills, agents, ui-views, command-bindings,
+			// collection-templates, modules) and stays right in a workspace shipping others.
+			system: d.storage?.base === 'runtime',
+			description: flat(d.description),
+			useWhen: flat(d.use_when),
+		});
+	}
+	return index.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/** Commands, for the harnesses that do NOT discover them natively. claude-code writes every command
+ *  into `.claude/commands` and its harness injects name+description at session start, so an index in
+ *  CLAUDE.md would be a second copy of what is already there. codex/pi/gemini-cli/cursor got one
+ *  pointer line and nothing else — which is why this is conditional, like the skills index. */
+function buildCommandsIndex(entries) {
+	const index = [];
+	for (const [rt, e] of entries) {
+		const m = /^commands\/(.+)\.command\.md$/.exec(rt);
+		if (!m) continue;
+		const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(e.bytes.toString('utf8'));
+		let desc = '';
+		try { desc = (fm ? load(fm[1]) : {})?.description ?? ''; } catch { /* unparseable frontmatter */ }
+		index.push({ id: m[1], desc: flat(desc) });
+	}
+	return index.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** THE LEXICON — the half of the DSL that was never at t=0. The grammar (record shape, reference
+ *  shape, namespaces) has been in this block since 0.6; an agent could form a well-shaped reference
+ *  and not name one thing it could be about. The dogfood vault's hand-written list in CLAUDE.md is
+ *  the argument for deriving it: that list named three collections for 48 hours after they were
+ *  deleted, because a human had to remember to edit it.
+ *
+ *  ⚠ NO RECORD COUNTS, and that is not an omission. This block lands in CLAUDE.md / AGENTS.md /
+ *  GEMINI.md, which are COMMITTED files. A count changes on every write, so every compile after
+ *  ordinary data work would re-dirty three tracked files — in trees where more than one agent has
+ *  uncommitted work — and the number would be stale the moment it was printed. Ordering is
+ *  namespace-grouped then alphabetical precisely so the block diffs ONLY when the schema changed. */
+function collectionsSection(index, namespaces) {
+	if (!index.length) return [];
+	const nsOf = (name) => {
+		const i = name.indexOf('/');
+		const p = i < 0 ? '' : name.slice(0, i);
+		return namespaces.includes(p) ? p : '';
+	};
+	const lines = [
+		'',
+		'COLLECTIONS — the nouns of this workspace. The descriptor at',
+		'`.dreamteamer/collections/<name>.collection.yaml` is the authority on fields, id shape and',
+		'defaults — read it before writing a kind you have not written this session. Create records',
+		'with `dt <collection> add`: it generates the id and rejects invalid writes before disk.',
+	];
+	const data = index.filter((c) => !c.system);
+	for (const group of ['', ...namespaces]) {
+		for (const c of data.filter((c) => nsOf(c.name) === group)) {
+			lines.push(`- ${c.name}${c.description ? ` — ${c.description}` : ''}`);
+			if (c.useWhen) lines.push(`    use when: ${c.useWhen}`);
+		}
+	}
+	const system = index.filter((c) => c.system).map((c) => c.name);
+	if (system.length) lines.push(`- schema-ops only (write with the meta verbs, never by hand): ${system.join(' · ')}`);
+	return lines;
+}
+
+/** Collection-templates are field sets modules stamp onto their collections — the provenance quad
+ *  reaches ~40 collections in the dogfood vault and was stated nowhere an agent reads.
+ *
+ *  ⚠ RENDERED, NEVER HARDCODED. An earlier draft wrote the four provenance field names straight
+ *  into this file. That is recipe knowledge in core: `provenance` is shipped by a MODULE, and
+ *  deliberately triplicated (`provenance`, `crm-provenance`, `rnd-provenance`) so each module stays
+ *  copyable on its own. A workspace without them would have been handed a block that lies. Core
+ *  renders the line; the module owns the sentence. */
+function templatesSection(entries) {
+	const rows = [];
+	for (const [rt, e] of entries) {
+		const m = /^collection-templates\/(.+)\.collection-template\.yaml$/.exec(rt);
+		if (!m) continue;
+		let d = {};
+		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { /* unparseable template */ }
+		rows.push({ name: d.name ?? m[1], description: flat(d.description) });
+	}
+	if (!rows.length) return [];
+	rows.sort((a, b) => a.name.localeCompare(b.name));
+	return ['', 'CROSS-CUTTING TEMPLATES — field sets modules stamp onto their collections:',
+		...rows.map((r) => `- ${r.name}${r.description ? ` — ${r.description}` : ''}`)];
+}
+
+/** `can-enter` / `can-exit` rendered LITERALLY. Translating a filter into English would be a
+ *  generator that has to grow with every operator the filter grammar gains, for prose the binding's
+ *  own `description:` already carries. Real shapes are a nested map terminating in one `_op`:
+ *    {status: {_eq: draft}}          -> status=draft
+ *    {status: {_in: [enriched, x]}}  -> status in enriched|x
+ *    {file: {_nempty: true}}         -> file set
+ *    {meeting: {_empty: true}}       -> meeting empty */
+const GATE_OPS = {
+	_eq: (p, v) => `${p}=${v}`,
+	_in: (p, v) => `${p} in ${[].concat(v).join('|')}`,
+	_nempty: (p) => `${p} set`,
+	_empty: (p) => `${p} empty`,
+};
+
+function renderGate(label, filter) {
+	const parts = [];
+	const walkFilter = (obj, at) => {
+		for (const [k, v] of Object.entries(obj ?? {})) {
+			if (k.startsWith('_')) parts.push((GATE_OPS[k] ?? ((p, x) => `${p} ${k.slice(1)} ${x}`))(at, v));
+			else if (v && typeof v === 'object') walkFilter(v, at ? `${at}.${k}` : k);
+			else parts.push(`${at ? `${at}.` : ''}${k}=${v}`);
+		}
+	};
+	if (filter && typeof filter === 'object') walkFilter(filter, '');
+	return parts.length ? `${label}: ${parts.join(', ')}` : '';
+}
+
+/** The METHODS on a type. A binding says which collection a command applies to and the record state
+ *  that makes it available — invisible on EVERY harness, claude-code included, whose native command
+ *  discovery gives the command's description and nothing about what it acts on. The cost of the
+ *  absence is on disk: a contact record in the dogfood vault carries the hand-written sentence
+ *  "`status: draft` keeps this in the /scrape-contact queue" — an agent re-deriving a can-enter
+ *  filter into prose because nothing surfaced it. */
+function bindingsSection(entries) {
+	const byCollection = new Map();
+	for (const [rt, e] of entries) {
+		if (!/^command-bindings\/.+\.command-binding\.yaml$/.test(rt)) continue;
+		let d = {};
+		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { continue; }
+		const coll = String(d.collection ?? '').replace(/^collections\//, '');
+		const cmd = String(d.command ?? '').replace(/^commands\//, '');
+		if (!coll || !cmd) continue;
+		const gate = [renderGate('enter', d['can-enter']), renderGate('exit', d['can-exit'])].filter(Boolean).join(' · ');
+		if (!byCollection.has(coll)) byCollection.set(coll, []);
+		byCollection.get(coll).push(`/${cmd}${gate ? ` (${gate})` : ''}`);
+	}
+	if (!byCollection.size) return [];
+	const lines = ['', 'VERBS BOUND TO COLLECTIONS (`dt commands for <collection>[/<id>]` answers per record):'];
+	for (const coll of [...byCollection.keys()].sort()) lines.push(`- ${coll} — ${byCollection.get(coll).sort().join(' · ')}`);
+	return lines;
+}
+
 /** `sourceLayout` describes what THIS workspace actually looks like — 'flat' (`<module>/skills/`),
  *  'nested' (the pre-2026-08-05 `<module>/system/skills/`), or 'mixed'. It is passed in rather than
  *  assumed because generated prose that contradicts the workspace is worse than no prose: this block
@@ -134,7 +289,7 @@ function buildSkillsIndex(entries) {
  *  agent that splits `health/doctors/dana-levi` at the first slash reads a collection that does not
  *  exist. Naming the declared list is what makes the grammar decidable from this block alone, without
  *  the agent having to go read the manifest. A workspace with no namespaces gets no extra sentence. */
-function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown') {
+function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown', entries = new Map()) {
 	const sourcesLine = {
 		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
@@ -145,7 +300,8 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 		// exactly one minor release and then quietly wrong in every workspace it had been written into.
 		// Passed rather than imported because compile.js already computes it and imports THIS module —
 		// reaching back for `engineVersion` would close a cycle for the sake of one string.
-		`this workspace is operated by dreamteamer v${version}. **read the \`using-dreamteamer\` skill before`,
+		`this workspace is a typed record DSL operated by dreamteamer v${version} — collections are the`,
+		'nouns. **read the `using-dreamteamer` skill before',
 		'working with data.** schemas (read): `.dreamteamer/collections/` (provenance:',
 		'`.dreamteamer/manifest.yaml`). sources (write): ' + sourcesLine,
 		'`command-bindings/`, `ui-views/`, `collection-templates/`',
@@ -166,6 +322,9 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 			'DECLARED prefix, not at the first slash. collections with no prefix are unaffected.',
 		);
 	}
+	lines.push(...collectionsSection(buildCollectionsIndex(entries), namespaces));
+	lines.push(...templatesSection(entries));
+	lines.push(...bindingsSection(entries));
 	// claude-code discovers skills natively (Skill tool) — an index in CLAUDE.md is pure
 	// context bloat there. every other harness gets the trigger index + discovery pointers.
 	if (flavor !== 'claude-code') {
@@ -177,7 +336,8 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 			...skillsIndex.map((s) => `- \`${s.id}\` — ${s.desc}`),
 			'',
 			'agent personas live at `.dreamteamer/agents/*.agent.md`; commands at',
-			'`.dreamteamer/commands/` (invoked as `/<name>` by the harness).',
+			'`.dreamteamer/commands/`, invoked as `/<name>` by the harness:',
+			...buildCommandsIndex(entries).map((c) => `- \`/${c.id}\` — ${c.desc}`),
 		);
 	}
 	return lines.join('\n');

package/src/schema-ops.js

@@ -95,6 +95,50 @@ function descriptorSourceDir(ws, name) {
 	return { dir: kindDir(moduleRoot, 'collections'), sources };
 }
 
+/**
+ * Set one scalar in a YAML document TEXTUALLY, so comments and key order survive.
+ *
+ * This exists because `load` → mutate → `dump` is lossy in the one way that matters here: it drops
+ * every comment. That is fine for a generated artifact and wrong for a module SOURCE, which is where
+ * this project writes down why a collection exists. Only `renameCollection` uses it, and only for the
+ * three scalars a rename changes; anything more ambitious belongs in a real round-trip YAML library,
+ * not in a regex.
+ *
+ * Handles both spellings the descriptors actually use — a top-level key, a nested block mapping, and
+ * the inline `storage: { path: x, suffix: y }` flow form. Callers MUST re-parse and assert, because a
+ * shape not covered here fails by changing nothing rather than by throwing.
+ */
+function setScalar(text, keyPath, value) {
+	const [head, child] = keyPath;
+	if (!child) return text.replace(new RegExp(`^${head}:.*$`, 'm'), `${head}: ${value}`);
+
+	// inline flow mapping: `storage: { path: data/x, suffix: y }`
+	const flow = new RegExp(`^${head}:\\s*\\{([^}]*)\\}\\s*$`, 'm').exec(text);
+	if (flow) {
+		let body = flow[1];
+		body = new RegExp(`\\b${child}:\\s*[^,}]+`).test(body)
+			? body.replace(new RegExp(`(\\b${child}:\\s*)[^,}]+`), `$1${value}`)
+			: `${body.trimEnd()}, ${child}: ${value}`;
+		return text.slice(0, flow.index) + `${head}: {${body}}` + text.slice(flow.index + flow[0].length);
+	}
+
+	// block mapping: `storage:\n  path: data/x`
+	const block = new RegExp(`^${head}:\\n(?:[ \\t]+.*\\n)*?[ \\t]+${child}:.*$`, 'm').exec(text);
+	if (block) {
+		return text.slice(0, block.index)
+			+ block[0].replace(new RegExp(`([ \\t]+${child}:).*$`, 'm'), `$1 ${value}`)
+			+ text.slice(block.index + block[0].length);
+	}
+
+	// the key is absent under an existing block — insert it directly after the parent
+	const parent = new RegExp(`^${head}:\\s*$`, 'm').exec(text);
+	if (parent) {
+		const at = parent.index + parent[0].length + 1;
+		return text.slice(0, at) + `  ${child}: ${value}\n` + text.slice(at);
+	}
+	return text;
+}
+
 // ---- ops ------------------------------------------------------------------------
 
 export function createCollection(ws, store, { name, template, namespace }) {
@@ -263,21 +307,66 @@ export function renameCollection(ws, store, oldName, newName) {
 		};
 		for (const id of ids) captureRefs(`${oldName}/${id}`);
 		captureRefs(`collections/${oldName}`);
-		const restoreRefs = () => { for (const [f, bytes] of refFiles) fs.writeFileSync(f, bytes); };
+		const restoreRefs = () => {
+			for (const [f, bytes] of refFiles) {
+				fs.mkdirSync(path.dirname(f), { recursive: true }); // pruneEmpty may have taken the parent
+				fs.writeFileSync(f, bytes);
+			}
+		};
 
 		const touched = new Set();
 		let rewrites = 0;
 		try {
-			// 1. the descriptor source, at its new path
+			// 1. the descriptor source, at its new path — EDITED TEXTUALLY, never re-dumped.
+			//
+			// ⚠ `fs.writeFileSync(dest, dump(doc))` destroyed every comment in the descriptor, and a
+			// descriptor's comments are where this project keeps its reasoning: 194 lines across 24
+			// files in one real migration, including 22-line headers stating what belongs in a
+			// collection and which failure mode it guards against. The record survived; the thinking
+			// did not, and nothing said so.
+			//
+			// A rename changes exactly three scalars. Rewriting those three in place keeps the
+			// comments, the key order and the author's formatting — and the parse afterwards proves
+			// the edit landed rather than trusting the regex.
+			const edited = setScalar(setScalar(setScalar(srcBytes.toString('utf8'),
+				['name'], newName),
+				['storage', 'path'], newPath),
+				['storage', 'suffix'], newSuffix);
+			const parsed = load(edited);
+			if (parsed?.name !== newName || parsed?.storage?.path !== newPath || parsed?.storage?.suffix !== newSuffix) {
+				throw new Error(`could not rewrite ${path.relative(ws.root, src)} in place — name/storage.path/storage.suffix did not take. nothing was changed.`);
+			}
 			doc.name = newName;
 			doc.storage = { ...doc.storage, path: newPath, suffix: newSuffix };
 			fs.mkdirSync(path.dirname(dest), { recursive: true });
-			fs.writeFileSync(dest, dump(doc));
+			fs.writeFileSync(dest, edited);
 			if (dest !== src) fs.rmSync(src);
 			touched.add(src);
 			touched.add(dest);
 
-			// 2. the record folder, then the per-file suffix if it was derived
+			// 2. INBOUND REFERENCES FIRST, while the records are still where the store thinks they are.
+			//
+			// ⚠ This used to run AFTER the folder move and it silently missed every SELF-reference.
+			// `store.rewriteRefs` walks `recordFiles()`, which resolves each collection's directory
+			// from the descriptor loaded when the Store was built — i.e. the OLD `storage.path`. Move
+			// the records first and that walk finds an empty directory, so a record pointing at its
+			// own collection is never rewritten and dangles the moment compile catches up.
+			//
+			// It is not a corner case: it hit `finance/accounts`, where every card and loan carries
+			// `settled_by: <the account that settles it>` — 5 dangling refs out of 11 records, found
+			// only because `check` ran afterwards. Doing the rewrite first needs no descriptor reload
+			// and no second code path: the files are still at the old path, which is exactly what the
+			// old refs say.
+			for (const id of ids) {
+				const out = store.rewriteRefs(`${oldName}/${id}`, `${newName}/${id}`);
+				rewrites += out.rewrites;
+				for (const f of out.touched) touched.add(f);
+			}
+			const collOut = store.rewriteRefs(`collections/${oldName}`, `collections/${newName}`);
+			rewrites += collOut.rewrites;
+			for (const f of collOut.touched) touched.add(f);
+
+			// 3. the record folder, then the per-file suffix if it was derived
 			if (newDir !== oldDir && fs.existsSync(oldDir)) {
 				fs.mkdirSync(path.dirname(newDir), { recursive: true });
 				fs.renameSync(oldDir, newDir);
@@ -295,33 +384,48 @@ export function renameCollection(ws, store, oldName, newName) {
 			}
 			if (movedData) { touched.add(oldDir); touched.add(newDir); }
 
-			// 3. inbound references: per record id, plus the collection's own id in `collections`
-			//    (which is what ui-views and command-bindings point at).
-			for (const id of ids) {
-				const out = store.rewriteRefs(`${oldName}/${id}`, `${newName}/${id}`);
-				rewrites += out.rewrites;
-				for (const f of out.touched) touched.add(f);
-			}
-			const collOut = store.rewriteRefs(`collections/${oldName}`, `collections/${newName}`);
-			rewrites += collOut.rewrites;
-			for (const f of collOut.touched) touched.add(f);
-
 			// 4. bare `x-reference: <oldName>` in every descriptor SOURCE. Not a `<collection>/<id>`
-			//    ref, so step 3 cannot see it — and leaving it makes compile fail on an unknown target.
+			//    ref, so step 2 cannot see it — and leaving it makes compile fail on an unknown target.
+			//
+			// ⚠ TEXTUAL, for the same reason step 1 is. This used to `load` → mutate → `dump`, which
+			// meant that ANY descriptor needing a retarget lost every comment in it — including the
+			// renamed one itself when it self-references, which is how step 1's careful preservation
+			// was undone one step later. 17 of the 24 descriptors stripped in the migration that
+			// found this were stripped HERE, not there.
+			//
+			// `retargetRefs` still decides WHETHER a file is affected — it walks the parsed schema and
+			// knows about nested properties and `items` — but the write is a line edit, and the parse
+			// afterwards proves it landed.
 			for (const f of descriptorSources(ws, store)) {
 				const before = fs.readFileSync(f, 'utf8');
-				const doc2 = load(before);
-				if (!doc2 || !retargetRefs(doc2.schema, oldName, newName)) continue;
+				const probe = load(before);
+				if (!probe || !retargetRefs(probe.schema, oldName, newName)) continue;
+				// ⚠ the boundary must cover BOTH spellings. A descriptor may write the block form
+				// (`x-reference: accounts` to end of line) or the inline flow form
+				// (`{ type: string, x-reference: accounts }`), where the value ends at `,` or `}`.
+				// Anchoring on `$` alone silently matched nothing in the flow form — and the assert
+				// below turned that silence into a refusal, which is how it was found.
+				const after = before.replace(
+					new RegExp(`(x-reference:\\s*)(['"]?)${oldName.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&')}\\2(?=\\s*(?:[,}]|#|$))`, 'gm'),
+					(_m, lead) => `${lead}${newName.includes('/') ? `'${newName}'` : newName}`);
+				const reparsed = load(after);
+				if (!reparsed || retargetRefs(reparsed.schema, oldName, newName)) {
+					throw new Error(`could not retarget x-reference "${oldName}" in ${path.relative(ws.root, f)} without reformatting it — nothing was changed.`);
+				}
 				if (!refFiles.has(f)) refFiles.set(f, Buffer.from(before));
-				fs.writeFileSync(f, dump(doc2));
+				fs.writeFileSync(f, after);
 				touched.add(f);
 				rewrites++;
 			}
 
 			compile(ws); // the gate: an uncompilable rename never reaches history
 		} catch (e) {
-			restoreRefs();
+			// ⚠ undo() FIRST. A captured file can be a SELF-reference — a record of the collection being
+			// renamed — so its path only exists again once undo() has moved the folder back. Restoring
+			// before that wrote into a directory that was no longer there, and the ENOENT masked the
+			// error actually being rolled back from.
 			undo();
+			restoreRefs();
 			try { compile(ws); } catch { /* pre-rename sources were compilable */ }
 			throw e;
 		}
@@ -338,8 +442,8 @@ export function renameCollection(ws, store, oldName, newName) {
 			execFileSync('git', ['commit', '--quiet', '-m', `dreamteamer: collections rename ${oldName} → ${newName}`, '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET });
 		} catch (e) {
 			try { execFileSync('git', ['reset', '--quiet', '--', ...rels], { cwd: ws.root, stdio: GIT_QUIET }); } catch { /* nothing staged */ }
-			restoreRefs();
 			undo();
+			restoreRefs();
 			try { compile(ws); } catch { /* pre-rename sources were compilable */ }
 			throw new Error(`git commit failed — the rename was rolled back, nothing was changed. (${e.message.split('\n')[0]})`);
 		}

package/src/store.js

@@ -299,13 +299,31 @@ export class Store {
 		return new RegExp(`${ref.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}(?![\\w/-])`, 'g');
 	}
 
+	// ⚠ EACH FILE EXACTLY ONCE. The `modules` collection's storage.path is `modules` and
+	// `sourceRoots()` includes the workspace root, so walking it RE-YIELDS every module source that
+	// its own kind's walk already produced — 173 files in one real vault, every module source
+	// among them.
+	//
+	// That was harmless while every rewrite was idempotent, and stopped being harmless the day
+	// namespaces arrived: replacing `draft-docs/x` with `rnd/draft-docs/x` is NOT idempotent,
+	// because the result still contains the pattern. A second pass wrote
+	// `data/rnd/rnd/draft-docs/x` into module-source comments during a real migration. Dedupe HERE
+	// rather than making each caller idempotent — `findInboundRefs` is a caller too, and its counts
+	// were quietly doubled by the same walk.
 	*recordFiles() {
+		const seen = new Set();
 		for (const d of this.descriptors.values()) {
 			// for runtime-based collections, inbound-ref surgery targets SOURCES, not the runtime
 			const roots = d.storage.base === 'runtime' ? this.sourceRoots() : [this.root];
 			for (const srcRoot of roots) {
 				const dir = path.join(srcRoot, d.storage.path);
-				if (fs.existsSync(dir)) yield* walk(dir);
+				if (!fs.existsSync(dir)) continue;
+				for (const f of walk(dir)) {
+					const key = path.resolve(f);
+					if (seen.has(key)) continue;
+					seen.add(key);
+					yield f;
+				}
 			}
 		}
 	}