dreamteamer 0.13.3 → 0.14.0

package/collections/collections.collection.yaml

@@ -40,9 +40,17 @@ schema:
           description: Folder holding the records, workspace-relative. `data/` for content, `state/` for operational records, `system/` for sources.
         codec:
           type: string
-          enum: [md, yaml, json]
+          enum: [md, yaml, json, file]
           default: md
-          description: File format. Use `md` whenever the record has a body a human will read.
+          description: 'File format. Use `md` whenever the record has a body a human will read. `file` makes the record an OPAQUE file — any extension, no frontmatter, fields DERIVED (`ext`, `bytes`), written with `add --from <path>` and never with `set`. For icons, logos and images.'
+        max_bytes:
+          type: integer
+          default: 204800
+          description: '`codec: file` only — the largest a record may be, in bytes. `check` reports anything over it. A record is a small file; a big one belongs outside the vault.'
+        extensions:
+          type: array
+          items: { type: string }
+          description: '`codec: file` only — the extensions this collection accepts, lowercase and without the dot. Omitted means any.'
         shape:
           type: string
           enum: [file, folder]

package/package.json

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

package/skills/building-dreamteamer/references/collections.md

@@ -86,12 +86,16 @@ templates: [collection-templates/provenance]   # merged at compile, every time
   WRITTEN, so a back-dated import files under the import month; derive from the domain's own date
   field instead). `id.pattern` must accept everything the template can produce — non-latin titles
   slug to a deterministic short hash, so `[a-z0-9-]` still holds.
-- **The `x-` keywords carry the domain semantics.** `x-reference` (a target collection, or `"*"` for
-  any) is what lets `check` and `rename` follow a field. `x-body` marks the single field that becomes
-  the md body. `x-inverse` declares a two-way link and makes `check` enforce both directions.
-  `x-title-template` overrides how a VALUE of that field is labelled — rarely needed, because a
-  reference already inherits its TARGET collection's `title_template`; author it there instead, once,
-  rather than on every field pointing at it.
+- **The `x-` keywords carry the domain semantics.** `x-reference` (a target collection, a LIST of
+  them for a union, or `"*"` for any) is what lets `check` and `rename` follow a field. On input, a
+  single-target field also accepts a bare id (`standup`, not `meetings/standup`) — it is qualified
+  before disk, so the file always carries the fully-qualified form; a union or `"*"` field has no
+  single target to infer from, so it still requires the qualified spelling. `x-body` marks the
+  single field that becomes the md body. `x-inverse` declares a two-way link and makes `check`
+  enforce both directions. `x-title-template` overrides how a VALUE of that field is labelled —
+  rarely needed, because a reference already inherits its TARGET collection's `title_template`;
+  author it there instead, once, rather than on every field pointing at it (a union field inherits a
+  template only when every member's target collection agrees on one).
 - **Do not enum a field after the fact.** Enumerating a vocabulary the records already violate makes
   `check` fail on every pre-existing value. `dt values <collection> <field>` derives the real
   vocabulary from the data — a filter dropdown gets it for free without locking the set.

package/src/check.js

@@ -5,9 +5,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
-import { parseRecord, patternRe, fmtAjvError, unknownFields, walk, EXT } from './records.js';
+import { parseRecord, patternRe, fmtAjvError, unknownFields, walk, idFromRecordPath, MAX_RECORD_BYTES } from './records.js';
 import { NO_RUNTIME, loadDescriptors, runtimeDir, namespaces as compiledNamespaces } from './runtime.js';
 import { parseRef } from './namespace.js';
+import { refTargetsOf } from './ref.js';
 
 export function check({ root }) {
 	const RUNTIME = runtimeDir(root);
@@ -63,11 +64,28 @@ export function check({ root }) {
 				else strays.push({ collection: name, file: rel(p), note: `missing entry file ${d.storage.entry}` });
 			}
 		} else {
-			const tail = `.${d.storage.suffix}${EXT[d.storage.codec ?? 'md']}`;
+			const opaque = (d.storage.codec ?? 'md') === 'file';
+			const allowed = d.storage.extensions;                  // undefined = any
+			const max = d.storage.max_bytes ?? MAX_RECORD_BYTES;
 			for (const f of walk(dir)) {
-				const r = path.relative(dir, f);
-				if (r.endsWith(tail)) ids.set(r.slice(0, -tail.length), f);
-				else strays.push({ collection: name, file: rel(f) });
+				const id = idFromRecordPath(d, path.relative(dir, f));
+				if (id === null) { strays.push({ collection: name, file: rel(f) }); continue; }
+				// One id is one file. Under a fixed-extension codec this cannot happen; under `file` it
+				// can, and picking one silently is how a replaced logo keeps rendering as its predecessor.
+				if (ids.has(id)) {
+					violations.push({ file: rel(f), msg: `collection "${name}" holds the id "${id}" twice — ${rel(ids.get(id))} and ${rel(f)}. Remove one.` });
+					continue;
+				}
+				ids.set(id, f);
+				if (!opaque) continue;
+				const ext = path.extname(f).slice(1).toLowerCase();
+				if (allowed && !allowed.includes(ext)) {
+					violations.push({ file: rel(f), msg: `collection "${name}" does not accept .${ext} — its declared extensions are ${allowed.join(', ')}` });
+				}
+				const size = fs.statSync(f).size;
+				if (size > max) {
+					violations.push({ file: rel(f), msg: `is ${size} bytes, over collection "${name}"'s max_bytes of ${max} — a record is a small file; a big one belongs outside the vault` });
+				}
 			}
 		}
 	}
@@ -77,7 +95,7 @@ export function check({ root }) {
 
 	// parsed fields, kept for the symmetric-ref pass below (parse each record exactly once)
 	const parsed = new Map();
-	const inverseRules = [];   // [collection, fieldPath, targetCollection, inverseField]
+	const inverseRules = [];   // [collection, fieldPath, inverseField]
 	const softRefs = new Map(); // absent-but-declared peer collection -> how many refs point at it
 
 	for (const [name, d] of descriptors) {
@@ -87,7 +105,7 @@ export function check({ root }) {
 		const bodyField = Object.entries(d.schema.properties ?? {}).find(([, s]) => s?.['x-body'])?.[0];
 		parsed.set(name, new Map());
 		for (const [fieldPath, target, inverse] of refFields) {
-			if (inverse) inverseRules.push([name, fieldPath, target, inverse]);
+			if (inverse) inverseRules.push([name, fieldPath, inverse]);
 		}
 
 		for (const [id, file] of index.get(name)) {
@@ -121,25 +139,25 @@ export function check({ root }) {
 	// only, so some predicates are only expressible from one side and both directions have to exist
 	// — which makes an invariant mandatory, not optional. `x-inverse` on a ref field names the field
 	// on the target that must point back; a one-sided link is a violation on the side that is missing.
-	for (const [name, fieldPath, target, inverse] of inverseRules) {
+	for (const [name, fieldPath, inverse] of inverseRules) {
 		for (const [id, fields] of parsed.get(name)) {
 			const self = `${name}/${id}`;
 			for (const value of valuesAt(fields, fieldPath)) {
 				if (typeof value !== 'string' || value.startsWith('@')) continue;
-				const targetId = parseRef(value, namespaces)?.id;
-				if (targetId === undefined) continue;                  // already flagged as malformed
-				const targetFields = parsed.get(target)?.get(targetId);
-				if (!targetFields) continue;                       // already flagged as dangling
+				const ref = parseRef(value, namespaces);
+				if (!ref) continue;                                    // already flagged as malformed
+				const targetFields = parsed.get(ref.collection)?.get(ref.id);
+				if (!targetFields) continue;                           // already flagged as dangling
 				const back = [...valuesAt(targetFields, [inverse])];
 				if (!back.includes(self)) {
-					flag(index.get(target).get(targetId),
+					flag(index.get(ref.collection).get(ref.id),
 						`${inverse}: must point back to "${self}" (${self} declares ${fieldPath.join('.')}: ${value})`);
 				}
 			}
 		}
 	}
 
-	function checkRef(file, fieldPath, value, target, softTargets) {
+	function checkRef(file, fieldPath, value, targets, softTargets) {
 		if (typeof value !== 'string') return;
 		if (value.startsWith('@')) return; // runtime tokens (@me, @initiator) are legal
 		// The SAME parser the store writes through (src/namespace.js) — `check` disagreeing with the
@@ -147,8 +165,9 @@ export function check({ root }) {
 		const ref = parseRef(value, namespaces);
 		if (!ref) return flag(file, `${fieldPath.join('.')}: reference "${value}" is not <collection>/<id>`);
 		const { collection: coll, id } = ref;
-		if (target !== '*' && coll !== target) {
-			return flag(file, `${fieldPath.join('.')}: reference "${value}" should target collection "${target}"`);
+		if (targets !== '*' && !targets.includes(coll)) {
+			const want = targets.length === 1 ? `collection "${targets[0]}"` : `one of: ${targets.join(', ')}`;
+			return flag(file, `${fieldPath.join('.')}: reference "${value}" should target ${want}`);
 		}
 		if (!descriptors.has(coll)) {
 			// A collection the owning module DECLARED as a peer and nothing installed provides is the
@@ -188,15 +207,25 @@ export function check({ root }) {
 }
 
 
-// collect [fieldPath, targetCollection, inverseField] for every x-reference in the schema.
+// collect [fieldPath, targets, inverseField] for every x-reference in the schema, where `targets`
+// is '*' or the normalized array of declared collections (see refTargetsOf).
 // `x-inverse` names the field on the TARGET collection that must point back — see checkSymmetry.
 function collectRefFields(schema, prefix = []) {
 	const out = [];
 	for (const [key, s] of Object.entries(schema.properties ?? {})) {
 		if (!s || typeof s !== 'object') continue;
 		const p = [...prefix, key];
-		if (s['x-reference']) out.push([p, s['x-reference'], s['x-inverse']]);
-		if (s.items?.['x-reference']) out.push([p, s.items['x-reference'], s['x-inverse'] ?? s.items['x-inverse']]);
+		const targets = refTargetsOf(s);
+		if (targets) {
+			// s.items ?? s, not the reverse: `s['x-reference']` treats a falsy-but-present keyword
+			// ('', false) as absent, which refTargetsOf does not — that mismatch left `holder`
+			// undefined and the next line threw. Nonsense-but-authored case this still does NOT
+			// cover: `x-inverse` on `items` beside a SCALAR `x-reference` on the property is not
+			// hoisted by compile (there is no array to hoist onto), so its symmetry rule is never
+			// evaluated here either — bad authoring, not a bug in this guard.
+			const holder = s.items ?? s;
+			out.push([p, targets, holder['x-inverse']]);
+		}
 		if (s.properties) out.push(...collectRefFields(s, p));
 		if (s.items?.properties) out.push(...collectRefFields(s.items, p));
 	}

package/src/collections-cli.js

@@ -119,6 +119,16 @@ export function collectionCommand(ws, collection, verb, args) {
 			return 0;
 		}
 		case 'add': {
+			// An opaque collection is written by IMPORTING a file: the id is positional (nothing can
+			// generate it from fields that do not exist) and the bytes come from --from.
+			if ((d.storage.codec ?? 'md') === 'file') {
+				const id = need(pos, 0, 'id');
+				if (!flags.from) throw new Error(`"${collection}" is a \`codec: file\` collection — pass --from <path> with the file to import`);
+				const { id: written, file } = store.addFile(collection, id, flags.from, { force: !!flags.force });
+				flags.json ? emit(JSON.stringify({ id: written, path: rel(ws.root, file) })) : console.log(`✔ ${rel(ws.root, file)}`);
+				return 0;
+			}
+			if (flags.from) throw new Error(`--from imports a file as a record, and "${collection}" is not a \`codec: file\` collection`);
 			const fields = coerceArrays(d, stripMeta(flags));
 			const { id, file } = store.add(collection, fields, { id: flags.id });
 			flags.json ? emit(JSON.stringify({ id, path: rel(ws.root, file) })) : console.log(`✔ ${rel(ws.root, file)}`);

package/src/compile.js

@@ -73,7 +73,8 @@ function staleDisplayKeywords(schema, prefix = '') {
 /**
  * Every `x-reference` in a schema, as `[fieldPath, target]` — the same traversal check.js uses to
  * resolve refs in records, here to verify the SHAPE against the module dependency graph. Nested
- * objects and array items both carry the keyword, so both are walked.
+ * objects and array items both carry the keyword, so both are walked. `target` is the RAW keyword
+ * value — a string, or a list of strings for the union form — unvalidated; the caller checks shape.
  */
 function refTargets(schema, prefix = '') {
 	const out = [];
@@ -88,6 +89,32 @@ function refTargets(schema, prefix = '') {
 	return out;
 }
 
+/**
+ * Hoist per-relation keywords onto the node that CARRIES `x-reference` — `items` for array fields.
+ * Both places were historically tolerated and check.js read `s['x-inverse'] ?? s.items['x-inverse']`,
+ * a two-place read every future consumer would have had to copy. After this, every runtime consumer
+ * reads exactly one place. Conflicting duplicates fail loudly: silently preferring one is how a
+ * hand-authored value gets shadowed with no error anywhere.
+ */
+function normalizeRelationKeywords(schema, name, prefix = '') {
+	for (const [key, prop] of Object.entries(schema?.properties ?? {})) {
+		if (!prop || typeof prop !== 'object') continue;
+		const at = `${prefix}${key}`;
+		if (prop.items && typeof prop.items === 'object' && prop.items['x-reference']) {
+			for (const kw of ['x-inverse', 'x-title-template']) {
+				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.`);
+				}
+				prop.items[kw] = prop[kw];
+				delete prop[kw];
+			}
+		}
+		if (prop.properties) normalizeRelationKeywords(prop, name, `${at}.`);
+		if (prop.items?.properties) normalizeRelationKeywords(prop.items, name, `${at}[].`);
+	}
+}
+
 export const KINDS = ['collections', 'skills', 'agents', 'commands', 'command-bindings', 'ui-views', 'collection-templates'];
 const FOLDER_KINDS = new Set(['skills']); // folder-shape entities: copy the whole record folder
 // DERIVED_KINDS (projected, not staged) lives in runtime.js — the boundary both halves read. Not in
@@ -433,7 +460,13 @@ export function compile({ root, pkg }) {
 					// descriptors merge via 'extends' — collect per collection name
 					const bytes = fs.readFileSync(srcPath);
 					const doc = load(bytes.toString('utf8'));
-					if (!doc.name || (!doc.schema && !doc.extends)) fail(`${rel(srcPath)}: descriptor needs '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.
+					const opaque = doc.storage?.codec === 'file';
+					if (!doc.name || (!doc.schema && !doc.extends && !opaque)) fail(`${rel(srcPath)}: descriptor needs 'name' and 'schema' (or 'extends')`);
+					if (opaque && (doc.storage.shape ?? 'file') === 'folder') fail(`${rel(srcPath)}: collection "${doc.name}" is \`codec: file\` — that is one file per record, not a folder; drop \`shape: folder\``);
+					if (opaque && Object.keys(doc.schema?.properties ?? {}).length) console.warn(`⚠ collection ${doc.name}: \`schema\` is ignored under \`codec: file\` — an opaque record's fields are derived (ext, bytes)`);
 					if (!descriptorGroups.has(doc.name)) descriptorGroups.set(doc.name, []);
 					descriptorGroups.get(doc.name).push({ src: { path: rel(srcPath), hash: sha256(bytes) }, doc, moduleName: source.name });
 					contributed.add(source.name);
@@ -628,6 +661,19 @@ export function compile({ root, pkg }) {
 			merged.storage.repo = '.';
 		}
 		storageEntries.push({ name, path: merged.storage.path, base: merged.storage.base });
+		// An opaque record has no AUTHORED schema, but it does have fields — derived ones. Stating them
+		// here rather than special-casing every reader is what keeps `codec: file` a codec instead of a
+		// feature: ajv, the field list, `dt values`, the form and the diagram all carry on unchanged,
+		// and what they read is true. Any authored schema was warned about and is replaced.
+		if ((merged.storage.codec ?? 'md') === 'file') {
+			merged.schema = {
+				type: 'object',
+				properties: {
+					ext: { type: 'string', description: "The file's extension, lowercase and without the dot. Derived from the file — never written." },
+					bytes: { type: 'integer', description: "The file's size in bytes. Derived from the file — never written." },
+				},
+			};
+		}
 		for (const [at, tpl, target] of staleDisplayKeywords(merged.schema)) {
 			const fix = target
 				? `either DELETE it (a reference to "${target}" now inherits that collection's \`title_template\`) or rename it to \`x-title-template\` if this field really needs its own`
@@ -688,8 +734,9 @@ 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));
-		for (const [at, target] of refTargets(merged.schema)) {
-			if (target === '*') {
+		normalizeRelationKeywords(merged.schema, name);
+		for (const [at, raw] of refTargets(merged.schema)) {
+			if (raw === '*') {
 				// The workspace module is the orchestrating parent and may reference anything —
 				// including modules that do not exist yet, which is what `tasks.item` means.
 				// Anywhere else a wildcard is a cross-module surface no declaration can cover.
@@ -698,14 +745,24 @@ export function compile({ root, pkg }) {
 				}
 				continue;
 			}
-			if (CORE_COLLECTIONS.has(target) || owns(target)) continue;
-			const owner = collOwner.get(target);
-			if (owner && declaredDeps.has(owner)) continue;
-			if (declaredPeers.has(target)) continue;
-			const fix = owner
-				? `add "${owner}" to dreamteamer.dependencies, or "${target}" to dreamteamer.peerDependencies if the module should work without it`
-				: `add "${target}" to dreamteamer.peerDependencies — no installed module provides it`;
-			fail(`collection "${name}": field "${at}" references "${target}", which ${groupModules.join('/')} neither owns nor declares.\n  ${fix}.`);
+			// `x-reference` accepts a scalar or a LIST of targets (the union) — run the identical
+			// per-target contract check over every member.
+			const targets = Array.isArray(raw) ? raw : [raw];
+			// scalar-or-list: the list is the union form. '*' may not appear INSIDE a list — the
+			// wildcard is a scalar-only sentinel, and a union that includes "anything" is not a union.
+			if (targets.length === 0 || targets.some((t) => typeof t !== 'string' || t === '' || t === '*')) {
+				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) {
+				if (CORE_COLLECTIONS.has(target) || owns(target)) continue;
+				const owner = collOwner.get(target);
+				if (owner && declaredDeps.has(owner)) continue;
+				if (declaredPeers.has(target)) continue;
+				const fix = owner
+					? `add "${owner}" to dreamteamer.dependencies, or "${target}" to dreamteamer.peerDependencies if the module should work without it`
+					: `add "${target}" to dreamteamer.peerDependencies — no installed module provides it`;
+				fail(`collection "${name}": field "${at}" references "${target}", which ${groupModules.join('/')} neither owns nor declares.\n  ${fix}.`);
+			}
 		}
 		// 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 —

package/src/events.js

@@ -3,7 +3,7 @@
 // auditable and replayable forever. history IS the queue; there is no events file.
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { EXT } from './records.js';
+import { idFromRecordPath } from './records.js';
 
 /** Record events between two points, across EVERY repo that holds records. `from` is a sha or a
  *  date — a sha is meaningless in another repo, so it is resolved to its commit DATE and each
@@ -110,9 +110,8 @@ export function pathToRecord(descriptors, relPath) {
 		if (!rest.endsWith('/' + entry)) return null;
 		return { collection: best.name, id: rest.slice(0, -(entry.length + 1)) };
 	}
-	const tail = `.${best.storage.suffix}${EXT[best.storage.codec ?? 'md']}`;
-	if (!rest.endsWith(tail)) return null;
-	return { collection: best.name, id: rest.slice(0, -tail.length) };
+	const id = idFromRecordPath(best, rest);
+	return id === null ? null : { collection: best.name, id };
 }
 
 /** the commit that last touched `path` inside the range — the event's provenance sha,

package/src/presentation.js

@@ -6,6 +6,7 @@
 // the studio components already speak (field {field,type,meta,schema}).
 
 import { sourceHint } from './runtime.js';
+import { refTargetsOf } from './ref.js';
 
 /** the projection for every collection: rows keyed by collection name + collection meta. */
 export function presentation(descriptors) {
@@ -39,9 +40,11 @@ export function presentation(descriptors) {
 		for (const [name, prop] of Object.entries(d.schema?.properties ?? {})) {
 			if (name === 'id') continue;
 			rows.push(fieldRow(d, name, prop, new Set(d.schema?.required ?? []).has(name), descriptors));
-			const target = referenceTargetOf(prop);
-			if (target) {
-				relations.push({ collection: d.name, field: name, related_collection: target, list: prop.type === 'array' });
+			const targets = referenceTargetsOf(prop);
+			if (targets) {
+				for (const target of targets) {
+					relations.push({ collection: d.name, field: name, related_collection: target, list: prop.type === 'array' });
+				}
 			}
 		}
 		fields[d.name] = rows;
@@ -79,10 +82,10 @@ function collectionRow(d) {
 	return { collection: d.name, meta, system };
 }
 
-function referenceTargetOf(prop) {
-	const ref = prop.type === 'array' ? prop.items?.['x-reference'] : prop['x-reference'];
-	if (typeof ref !== 'string' || ref === '' || ref === '*') return null;
-	return ref;
+/** The named target collections of a reference field — null for a non-ref and for '*'. */
+function referenceTargetsOf(prop) {
+	const targets = refTargetsOf(prop);
+	return targets && targets !== '*' ? targets : null;
 }
 
 /**
@@ -92,14 +95,22 @@ function referenceTargetOf(prop) {
  * `title_template` — because "a company is labelled by its name" is a fact about companies, not
  * about each of the eleven fields that point at one. Before this, that fact was hand-copied onto
  * every referencing field as `x-display: '{{ name }}'`; 51 of the 54 sites in this workspace were
- * exactly what the target already implies.
+ * exactly what the target already implies. A UNION field inherits only when every member agrees —
+ * a template that renders half the values wrong is worse than the raw qualified ref, which is at
+ * least always correct.
  */
 function titleTemplateOf(prop, descriptors) {
-	const own = prop.type === 'array' ? prop.items?.['x-title-template'] : prop['x-title-template'];
+	// Keyed off prop.items itself, not prop.type === 'array': the compile hoist moves an authored
+	// x-title-template onto whichever node CARRIES x-reference, which for an items-bearing property
+	// is `items` regardless of whether `type: array` was also spelled out explicitly. Reading by
+	// `type` diverged from that and silently dropped the authored template for such a field.
+	const own = prop.items?.['x-title-template'] ?? prop['x-title-template'];
 	if (typeof own === 'string' && own.length > 0) return own;
-	const target = referenceTargetOf(prop);
-	const inherited = target ? descriptors.get(target)?.title_template : undefined;
-	return typeof inherited === 'string' && inherited.length > 0 ? inherited : undefined;
+	const targets = referenceTargetsOf(prop);
+	if (!targets) return undefined;
+	const inherited = targets.map((t) => descriptors.get(t)?.title_template);
+	const first = inherited[0];
+	return typeof first === 'string' && first.length > 0 && inherited.every((v) => v === first) ? first : undefined;
 }
 
 function fieldRow(d, name, prop, isRequired, descriptors) {
@@ -114,15 +125,15 @@ function fieldRow(d, name, prop, isRequired, descriptors) {
 	if (typeof prop.title === 'string' && prop.title.length > 0) meta.title = prop.title;
 
 	let type = 'string';
-	const target = referenceTargetOf(prop);
+	const targets = referenceTargetsOf(prop); // plural: x-reference may name several collections; only truthiness is used below
 
 	if (prop['x-body'] === true) {
 		type = 'text';
 		meta.special = ['dt-body'];
 		meta.edit = 'input-rich-text-md';
-	} else if (target && prop.type !== 'array') {
+	} else if (targets && prop.type !== 'array') {
 		meta.special = ['dt-relation-path'];
-	} else if (target && prop.type === 'array') {
+	} else if (targets && prop.type === 'array') {
 		type = 'json';
 		meta.special = ['dt-relation-path', 'dt-relation-list'];
 	} else if (prop.type === 'array' && prop.items?.type === 'object') {

package/src/records.js

@@ -5,6 +5,11 @@ import path from 'node:path';
 import { load } from './yaml.js';
 
 export function parseRecord(file, d, bodyField) {
+	// An opaque record IS its bytes: there is nothing to parse, and reading a PNG as utf8 would
+	// corrupt it on the way back out. What a reader gets instead is derived from the file itself.
+	if ((d.storage.codec ?? 'md') === 'file') {
+		return { ext: path.extname(file).slice(1).toLowerCase(), bytes: fs.statSync(file).size };
+	}
 	return parseRecordText(fs.readFileSync(file, 'utf8'), d, bodyField);
 }
 
@@ -47,6 +52,31 @@ export function unknownFields(schema, fields) {
 
 export const EXT = { md: '.md', yaml: '.yaml', json: '.json' };
 
+/** How big a `codec: file` record may be before `check` says something, when its collection does not
+ *  say otherwise. 200 KB fits an icon, a logo, a small illustration or a compressed photo, and does
+ *  not fit the video someone will one day try to make a record. */
+export const MAX_RECORD_BYTES = 204800;
+
+/** The id a record file carries, or null when this path is not a record of `d`.
+ *  `relPath` is relative to the collection's data directory.
+ *
+ *  THE ONLY PLACE a filename becomes an id. store, check and events each carried their own copy of
+ *  `endsWith('.' + suffix + EXT[codec])`, which is three places to update and two to forget.
+ *
+ *  `codec: file` records are opaque bytes whose extension is whatever was imported, so their tail is
+ *  `.<suffix>.<ONE extension segment>` — one, because `x.asset.tar.gz` in the folder is an archive
+ *  someone dropped there, and calling it a record would hide it from `check`'s stray report. */
+export function idFromRecordPath(d, relPath) {
+	const suffix = d.storage.suffix;
+	if ((d.storage.codec ?? 'md') === 'file') {
+		const lit = suffix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+		const m = new RegExp(`^(.+)\\.${lit}\\.[A-Za-z0-9]+$`).exec(relPath);
+		return m ? m[1] : null;
+	}
+	const tail = `.${suffix}${EXT[d.storage.codec ?? 'md']}`;
+	return relPath.endsWith(tail) ? relPath.slice(0, -tail.length) : null;
+}
+
 const JUNK_DIRS = new Set(['__pycache__', 'node_modules']);
 const JUNK_FILE = /\.(pyc|pyo)$|^\.DS_Store$/;
 

package/src/ref.js

@@ -11,3 +11,24 @@ export function splitRef(descriptors, ref) {
 	if (ref === best) throw new Error(`reference "${ref}" names a collection but no record id`);
 	return { collection: best, id: ref.slice(best.length + 1) };
 }
+
+/**
+ * The declared target set of a reference property: '*', an array of collection names, or null when
+ * the property is not a reference. `x-reference` accepts a scalar or a LIST of targets; this is the
+ * ONE place that widening is decoded — every consumer reads targets through here (or applies the
+ * identical one-liner where importing would cross a layer), so the two spellings can never mean
+ * different things in different subsystems.
+ *
+ * This function normalizes SPELLING only, not shape: `[]` decodes to `[]` and `''` decodes to
+ * `['']`, neither of which is a valid target set. Whether the array is non-empty, every member is a
+ * non-empty string, and `'*'` never hides inside a list is compile's job (see compile.js's
+ * validation of each union member) — a consumer calling this at runtime is reading an
+ * already-compiled, already-validated descriptor and can rely on the shape holding, but should not
+ * re-derive that guarantee from this decoder.
+ */
+export function refTargetsOf(prop) {
+	const raw = prop?.['x-reference'] ?? prop?.items?.['x-reference'];
+	if (raw == null) return null;
+	if (raw === '*') return '*';
+	return Array.isArray(raw) ? raw : [raw];
+}

package/src/schema-ops.js

@@ -11,11 +11,12 @@ import { load, dump } from './yaml.js';
 import { compile, kindDir, titleCase } from './compile.js';
 import { readManifest, runtimeKindDir } from './runtime.js';
 import { normalizeNamespaces, namespaceOf, baseNameOf, qualify, defaultStoragePath } from './namespace.js';
+import { refTargetsOf } from './ref.js';
 
 // Same rule as store.js: a git failure we CATCH must not also print git's own error on top of the
 // clean message we throw. stdout stays piped because some callers read it.
 const GIT_QUIET = ['ignore', 'pipe', 'ignore'];
-import { walk, EXT } from './records.js';
+import { walk, idFromRecordPath } from './records.js';
 
 // ---- the gate -------------------------------------------------------------------
 
@@ -383,10 +384,13 @@ export function renameCollection(ws, store, oldName, newName) {
 				pruneEmpty(path.dirname(oldDir), path.join(ws.root, dataPath));
 			}
 			if (newSuffix !== oldSuffix && fs.existsSync(newDir)) {
-				const ext = EXT[d.storage.codec ?? 'md'];
+				// Match on the OLD suffix, keep whatever extension the file already had — an opaque
+				// record's extension is its own, and a re-suffix must not rename it into another format.
+				const old = { storage: { ...d.storage, suffix: oldSuffix } };
 				for (const file of walk(newDir)) {
-					if (!file.endsWith(`.${oldSuffix}${ext}`)) continue;
-					const to = file.slice(0, -(oldSuffix.length + ext.length + 1)) + `.${newSuffix}${ext}`;
+					const id = idFromRecordPath(old, path.relative(newDir, file));
+					if (id === null) continue;
+					const to = path.join(newDir, `${id}.${newSuffix}${path.basename(file).slice(path.basename(id).length + oldSuffix.length + 1)}`);
 					fs.renameSync(file, to);
 					resuffixed.push([file, to]);
 				}
@@ -409,14 +413,13 @@ export function renameCollection(ws, store, oldName, newName) {
 				const before = fs.readFileSync(f, 'utf8');
 				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}`);
+				// ⚠ the boundary must cover THREE spellings: the block form (`x-reference: accounts` to
+				// end of line), the inline flow form (`{ type: string, x-reference: accounts }`, where
+				// the value ends at `,` or `}`), and a LIST — flow (`x-reference: [a, accounts, b]`) or
+				// block (`x-reference:` + `- accounts` items). 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 = retargetRefText(before, oldName, 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.`);
@@ -487,15 +490,22 @@ function descriptorSources(ws, store) {
 	return out;
 }
 
-/** Rewrite `x-reference: old` → new anywhere in a schema. Returns true if anything changed. */
+/** Rewrite `x-reference: old` → new anywhere in a schema — scalar or list entry. Returns true if anything changed. */
 function retargetRefs(schema, oldName, newName) {
 	let changed = false;
 	for (const prop of Object.values(schema?.properties ?? {})) {
 		if (!prop || typeof prop !== 'object') continue;
 		for (const holder of [prop, prop.items]) {
-			if (holder && typeof holder === 'object' && holder['x-reference'] === oldName) {
+			if (!holder || typeof holder !== 'object') continue;
+			if (holder['x-reference'] === oldName) {
 				holder['x-reference'] = newName;
 				changed = true;
+			} else if (Array.isArray(holder['x-reference'])) {
+				const i = holder['x-reference'].indexOf(oldName);
+				if (i !== -1) {
+					holder['x-reference'][i] = newName;
+					changed = true;
+				}
 			}
 		}
 		if (prop.properties && retargetRefs(prop, oldName, newName)) changed = true;
@@ -504,6 +514,73 @@ function retargetRefs(schema, oldName, newName) {
 	return changed;
 }
 
+/**
+ * The TEXTUAL x-reference retarget — a line edit, never load→dump, so comments survive (see the
+ * step-4 comment in renameCollection for the 17-descriptor lesson).
+ *
+ * Handles three spellings: scalar (`x-reference: old`), flow list (`x-reference: [a, old, b]`),
+ * and block sequence (`x-reference:` + `- old` items tracked by indent under the key):
+ *
+ *   ```
+ *   x-reference:
+ *     - doctors
+ *     - nurses
+ *   ```
+ *
+ * Two YAML styles are deliberately NOT rewritten and fall through unchanged to the caller's
+ * reparse-assert (which throws if the return does not compile), failing closed rather than
+ * half-written:
+ *
+ *   - **Same-indent block sequence**: YAML allows `- items` at the PARENT's own indent
+ *     (`x-reference:` and `- doctors` at the same indent level). The indent state machine
+ *     requires strictly deeper dashes (`item[1].length > listIndent`), so this spelling is
+ *     never entered and goes reparse-asserted instead.
+ *   - **Multi-line flow list**: a flow list split across lines — `[` on one line, `]` on
+ *     another. The flow regex requires both brackets and the body on the same line, so this
+ *     spelling is not matched and goes reparse-asserted instead.
+ *   - **A blank or comment line BETWEEN block-sequence items**: the item regex requires a
+ *     leading `-`, so a blank line or a `#`-comment line inside the list resets `listIndent`
+ *     early. Every item after the gap is then read as ordinary text rather than a list member,
+ *     and (having no `x-reference:` key on its own line) is left untouched.
+ *
+ *   All three fail closed on purpose: the engine's own `dump()` always emits deeper-indented,
+ *   gap-free sequences and single-line flow lists, so only a hand-authored descriptor can reach
+ *   these styles. Anything trickier than the three handled spellings falls through unchanged —
+ *   the caller reparses and REFUSES rather than guessing.
+ */
+function retargetRefText(text, oldName, newName) {
+	const esc = oldName.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+	const quoted = newName.includes('/') ? `'${newName}'` : newName;
+	const retag = (part) => {
+		const m = part.match(/^(\s*)(['"]?)(.*?)\2(\s*)$/);
+		return m && m[3] === oldName ? `${m[1]}${quoted}${m[4]}` : part;
+	};
+	const lines = text.split('\n');
+	let listIndent = -1; // >= 0 while inside a block-sequence x-reference list
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (listIndent >= 0) {
+			const item = line.match(/^(\s*)-\s*(['"]?)(.*?)\2\s*(#.*)?$/);
+			if (item && item[1].length > listIndent) {
+				if (item[3] === oldName) {
+					lines[i] = line.replace(new RegExp(`(-\\s*)(['"]?)${esc}\\2`), (_m, lead) => `${lead}${quoted}`);
+				}
+				continue;
+			}
+			listIndent = -1;
+		}
+		const key = line.match(/^(\s*)x-reference:\s*(.*)$/);
+		if (key && (key[2] === '' || key[2].startsWith('#'))) {
+			listIndent = key[1].length;
+			continue;
+		}
+		lines[i] = line
+			.replace(new RegExp(`(x-reference:\\s*)(['"]?)${esc}\\2(?=\\s*(?:[,}]|#|$))`, 'gm'), (_m, lead) => `${lead}${quoted}`)
+			.replace(/(x-reference:\s*\[)([^\]]*)(\])/g, (_m, open, body, close) => open + body.split(',').map(retag).join(',') + close);
+	}
+	return lines.join('\n');
+}
+
 /** Remove now-empty parents up to (not including) the data root — a moved collection leaves its
  *  namespace folder behind otherwise. */
 function pruneEmpty(dir, stopAt) {
@@ -565,9 +642,13 @@ function upsertField(ws, store, collection, fieldName, prop, required, verb) {
 	// target collection's `title_template`, so a field drawer that round-trips that projection
 	// writes the inherited value back onto the field — hand-recreating exactly the 49 duplicated
 	// `x-display` lines the inheritance replaced. Only a template that DIFFERS from the target's
-	// is a real authored override.
-	const ref = prop['x-reference'] ?? prop.items?.['x-reference'];
-	const inherited = ref && ref !== '*' ? store.descriptors.get(ref)?.title_template : undefined;
+	// is a real authored override. For a UNION (`x-reference` a list), presentation inherits only
+	// when every member's `title_template` agrees — so the cleanup here computes the same
+	// unanimous value, not just the first member's.
+	const targets = refTargetsOf(prop) ?? [];
+	const tpls = targets === '*' ? [] : targets.map((t) => store.descriptors.get(t)?.title_template);
+	const first = tpls[0];
+	const inherited = typeof first === 'string' && first.length > 0 && tpls.every((v) => v === first) ? first : undefined;
 	if (inherited) {
 		if (prop['x-title-template'] === inherited) {
 			prop = { ...prop };
@@ -597,23 +678,95 @@ function upsertField(ws, store, collection, fieldName, prop, required, verb) {
 	return { collection, field: fieldName, file: dest, extends: doc.extends };
 }
 
+/**
+ * WHERE A UI-VIEW'S SOURCE ACTUALLY LIVES — asked of the manifest, exactly as `descriptorSourceDir`
+ * asks it for a collection, and for the same reason: the guard that matters is "will `npm install`
+ * erase this write", not "which module owns it".
+ *
+ * ⚠ This used to be `workspaceSystemDir` unconditionally, which silently meant a view could only be
+ * saved if the WORKSPACE MODULE happened to ship it. Saving one shipped by any other inline module
+ * wrote a SECOND file carrying the same id, and compile refuses that by name — so the whole write
+ * rolled back and the surface reported `name collision on ui-view "…"` instead of saving. Measured
+ * on gk-brain 2026-08-28: every one of its module-shipped views (`modules/family`, `modules/rnd`,
+ * `modules/services`) was unsaveable, and the failure said nothing about why.
+ *
+ * Returns `{ file, shipped }` — where to write, and the workspace-relative source that already
+ * exists (null for a new view, which lands in the workspace module as before).
+ */
+function uiViewSourceFile(ws, id) {
+	const src = readManifest(ws.root)?.entries?.[`ui-views/${id}.ui-view.yaml`]?.sources?.[0];
+	// sources are `{path, hash}`; tolerate the pre-0.10 string form, same as compile's staleness check
+	const shipped = typeof src === 'string' ? src : src?.path;
+	if (!shipped) return { file: path.join(workspaceSystemDir(ws, 'ui-views'), `${id}.ui-view.yaml`), shipped: null };
+	return { file: path.join(ws.root, shipped), shipped };
+}
+
+/**
+ * Re-attach a rewritten YAML source's COMMENTS — the part `dump` cannot round-trip.
+ *
+ * js-yaml drops every comment on `load` → `dump`. That is fine for a generated artifact and wrong
+ * for a module SOURCE, which is where this project writes down why something exists (`setScalar`
+ * above exists for the same reason). A real round-trip needs a different YAML library and core is
+ * not taking one on for this, so this does the narrow thing that is actually safe: a comment block
+ * sitting directly above a TOP-LEVEL key is carried back above that same key, if the key survived.
+ * The file header comes along for free — it is the block above the first key.
+ *
+ * ⚠ Deliberately top-level only. A comment above a NESTED key cannot be re-placed without knowing
+ * where that key ended up, and a misplaced comment is worse than an absent one: it would attach an
+ * explanation to something it does not explain. Those are still lost. Measured against
+ * `modules/family/ui-views/health-labs-abnormal.ui-view.yaml`, whose two blocks — the file header
+ * and the ⚠ above `filter:` — are both top-level and both survive.
+ */
+function reattachComments(oldText, newText) {
+	const TOP_KEY = /^([A-Za-z_][\w-]*):/;
+	const blocks = new Map(); // surviving key -> the comment lines that sat above it
+	let pending = [];
+	for (const line of oldText.split('\n')) {
+		if (line.startsWith('#') || line.trim() === '') { pending.push(line); continue; }
+		const key = TOP_KEY.exec(line)?.[1];
+		if (key && pending.some((l) => l.startsWith('#'))) {
+			while (pending.length && pending[pending.length - 1].trim() === '') pending.pop();
+			blocks.set(key, pending);
+		}
+		pending = [];
+	}
+	if (!blocks.size) return newText;
+
+	const out = [];
+	for (const line of newText.split('\n')) {
+		const block = blocks.get(TOP_KEY.exec(line)?.[1]);
+		if (block) out.push(...block);
+		out.push(line);
+	}
+	return out.join('\n');
+}
+
 // 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 }) {
 	if (!id || !/^[a-z0-9][a-z0-9-/]*$/.test(id)) throw new Error(`invalid ui-view id "${id}" — lowercase slug required`);
-	const dest = path.join(workspaceSystemDir(ws, 'ui-views'), `${id}.ui-view.yaml`);
+	const { file: dest, shipped } = 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);
+	// A module source is where this project writes down WHY a view exists; `dump` cannot keep that.
+	const previous = existed ? fs.readFileSync(dest, 'utf8') : null;
 	writeGated(ws, store, [dest], `dreamteamer: ui-views ${existed ? 'update' : 'add'} ${id}`, () => {
 		fs.mkdirSync(path.dirname(dest), { recursive: true });
-		fs.writeFileSync(dest, dump(view));
+		fs.writeFileSync(dest, previous === null ? dump(view) : reattachComments(previous, dump(view)));
 	});
 	return { id, file: dest, updated: existed };
 }
 
 export function removeUiView(ws, store, id) {
-	const dest = path.join(workspaceSystemDir(ws, 'ui-views'), `${id}.ui-view.yaml`);
-	if (!fs.existsSync(dest)) throw new Error(`ui-view "${id}" is not workspace-owned (module-shipped views are removed via dreamteamer.disable)`);
+	// Same source resolution as the save above — an inline module's view is under this repo's git
+	// history like everything else, so deleting it is one revertable commit. Refusing it while
+	// ALLOWING a save to the same file would be an asymmetry with nothing behind it.
+	const { file: dest, shipped } = uiViewSourceFile(ws, id);
+	if (shipped && /(^|\/)node_modules\//.test(shipped))
+		throw new Error(`ui-view "${id}" is shipped by an installed package (${shipped}) — removing the file would be undone by the next npm install.\n  disable it instead: add "<module>/${id}" to dreamteamer.disable in package.json.`);
+	if (!fs.existsSync(dest)) throw new Error(`ui-view "${id}" does not exist`);
 	writeGated(ws, store, [dest], `dreamteamer: ui-views rm ${id}`, () => fs.rmSync(dest));
 	return { removed: id };
 }

package/src/store.js

@@ -9,10 +9,11 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { dump } from './yaml.js';
 import { generateId } from './template.js';
-import { parseRecord, parseRecordText, patternRe, fmtAjvError, unknownFields, walk, EXT, assertSafeId } from './records.js';
+import { parseRecord, parseRecordText, patternRe, fmtAjvError, unknownFields, walk, EXT, assertSafeId, idFromRecordPath, MAX_RECORD_BYTES } from './records.js';
 import { normalizeRecord } from './temporal.js';
 import { NO_RUNTIME, sourceHint, loadDescriptors, runtimeDir, namespaces as compiledNamespaces, sourceRoots as compiledSourceRoots } from './runtime.js';
 import { parseRef } from './namespace.js';
+import { refTargetsOf } from './ref.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -65,19 +66,33 @@ export class Store {
 		return path.join(d.storage.base === 'runtime' ? this.runtime : this.root, d.storage.path);
 	}
 
-	filePath(d, id) {
+	filePath(d, id, ext) {
 		assertSafeId(id); // never fs-join an id that can climb out of the collection
 		if (d.storage.shape === 'folder') {
 			if (!d.storage.entry) throw new Error(`collection "${d.name}" is folder-shape but declares no storage.entry`);
 			return path.join(this.dir(d), id, d.storage.entry);
 		}
+		if ((d.storage.codec ?? 'md') === 'file') {
+			// An opaque record's extension is not derivable from its id. A caller that WRITES says what
+			// it is; a caller that reads goes through the id index instead (recordRoot, below).
+			if (!ext) throw new Error(`collection "${d.name}" is \`codec: file\` — its path needs the file's extension`);
+			return path.join(this.dir(d), `${id}.${d.storage.suffix}.${ext}`);
+		}
 		return path.join(this.dir(d), `${id}.${d.storage.suffix}${EXT[d.storage.codec ?? 'md']}`);
 	}
 
 	// the on-disk unit of a record: its folder for folder shapes, its file otherwise
 	recordRoot(d, id) {
 		assertSafeId(id);
-		return d.storage.shape === 'folder' ? path.join(this.dir(d), id) : this.filePath(d, id);
+		if (d.storage.shape === 'folder') return path.join(this.dir(d), id);
+		// Only the index knows an opaque record's extension, so the on-disk unit is looked up rather
+		// than derived. An unknown id is the caller's error either way — `read` says so first.
+		if ((d.storage.codec ?? 'md') === 'file') {
+			const file = this.ids(d.name).get(id);
+			if (!file) throw new Error(`${d.name}/${id}: no such record`);
+			return file;
+		}
+		return this.filePath(d, id);
 	}
 
 	// current HEAD — one cheap rev-parse per cache check vs a multi-thousand-file walk
@@ -112,10 +127,9 @@ export class Store {
 			}
 			return ids;
 		}
-		const tail = `.${d.storage.suffix}${EXT[d.storage.codec ?? 'md']}`;
 		for (const f of walk(dir)) {
-			const r = path.relative(dir, f);
-			if (r.endsWith(tail)) ids.set(r.slice(0, -tail.length), f);
+			const id = idFromRecordPath(d, path.relative(dir, f));
+			if (id !== null) ids.set(id, f);
 		}
 		return ids;
 	}
@@ -173,6 +187,13 @@ export class Store {
 		// canonical, offset-carrying value. ajv's `date-time` accepts exactly one spelling; without
 		// this every human-shaped input is a validation error (see src/temporal.js).
 		normalizeRecord(d.schema, fields);
+		// qualifyBareRefs must ALSO run before ajv.compile(d.schema) below, for the same "one choke
+		// point" reason but a different consequence: `validate(fields)` is what triggers useDefaults,
+		// materializing any schema `default:` onto `fields` for the first time — a bare value sitting
+		// in a single-target ref field's `default:` is never seen by qualifyBareRefs and would reach
+		// checkRefs unqualified, failing as malformed rather than as the dangling reference it should
+		// read as. In practice no shipped descriptor defaults a ref field, so this is latent, not hit.
+		this.qualifyBareRefs(d, fields);
 		const validate = this.ajv.compile(d.schema); // useDefaults mutates: defaults materialize
 		if (!validate(fields)) {
 			const msgs = validate.errors.map((e) => '  ' + fmtAjvError(e, fields));
@@ -182,10 +203,37 @@ export class Store {
 		return fields;
 	}
 
+	// Bare ids are accepted on INPUT for a field whose target set has exactly one member, and
+	// qualified HERE — the same choke point that canonicalizes datetimes (normalizeRecord), for the
+	// same reason: add/set reach disk through validate(), so the file always carries the one
+	// canonical spelling. The deliberate exception is `revert`: it restores committed historical
+	// BYTES verbatim (that is the whole point of a revert), calling validate() only to prove the
+	// historical content still parses — never on the text that actually reaches atomicWrite. So a
+	// bare ref that was committed past this choke point (hand-edited, or written by an older engine)
+	// stays bare when reverted TO; `check` is what flags it, not this method. Union and '*' fields
+	// never qualify: the prefix is the only type information those values carry. A value that
+	// already parses as a ref is never rewritten — so a qualified-but-wrong id fails downstream as a
+	// precise dangling reference, not as malformed syntax. Known limit: a slash-carrying bare id
+	// (path-shaped ids) parses as a ref and is not qualified; the checkRefs error then names the
+	// misread collection.
+	qualifyBareRefs(d, fields) {
+		for (const [key, s] of Object.entries(d.schema.properties ?? {})) {
+			const targets = refTargetsOf(s);
+			if (!targets || targets === '*' || targets.length !== 1) continue;
+			const raw = fields[key];
+			if (raw == null) continue;
+			const qualify = (v) =>
+				typeof v === 'string' && v !== '' && !v.startsWith('@') && !parseRef(v, this.namespaces)
+					? `${targets[0]}/${v}`
+					: v;
+			fields[key] = Array.isArray(raw) ? raw.map(qualify) : qualify(raw);
+		}
+	}
+
 	checkRefs(d, fields, prefix = []) {
 		for (const [key, s] of Object.entries(d.schema.properties ?? {})) {
-			const target = s?.['x-reference'] ?? s?.items?.['x-reference'];
-			if (!target) continue;
+			const targets = refTargetsOf(s);
+			if (!targets) continue;
 			const raw = fields[key];
 			if (raw == null) continue;
 			for (const value of Array.isArray(raw) ? raw : [raw]) {
@@ -196,7 +244,10 @@ export class Store {
 				const parsed = parseRef(value, this.namespaces);
 				if (!parsed) throw new Error(`${key}: reference "${value}" is not <collection>/<id> — nothing was written.`);
 				const { collection: coll, id } = parsed;
-				if (target !== '*' && coll !== target) throw new Error(`${key}: reference "${value}" must target collection "${target}" — nothing was written.`);
+				if (targets !== '*' && !targets.includes(coll)) {
+					const want = targets.length === 1 ? `collection "${targets[0]}"` : `one of: ${targets.join(', ')}`;
+					throw new Error(`${key}: reference "${value}" must target ${want} — nothing was written.`);
+				}
 				if (!this.descriptors.has(coll)) throw new Error(`${key}: reference "${value}" targets unknown collection "${coll}" — nothing was written.`);
 				if (!this.ids(coll).has(id)) throw new Error(`${key}: dangling reference "${value}" — no such record. nothing was written.`);
 			}
@@ -226,8 +277,45 @@ export class Store {
 		});
 	}
 
+	/** Import a file AS a record. There are no fields to validate and nothing to serialize, which is
+	 *  why this is a sibling of add() rather than a branch inside it — the two share their last three
+	 *  lines and nothing else. */
+	addFile(collection, id, srcPath, { force = false } = {}) {
+		const d = this.writableDescriptor(collection);
+		if ((d.storage.codec ?? 'md') !== 'file') throw new Error(`"${collection}" is not a \`codec: file\` collection — add its records with --<field> values, not --from`);
+		assertSafeId(id);
+		if (d.id?.pattern && !patternRe(d.id.pattern).test(id)) {
+			throw new Error(`id "${id}" does not match pattern ${d.id.pattern} — nothing was written.`);
+		}
+		const ext = path.extname(srcPath).slice(1).toLowerCase();
+		if (!ext) throw new Error(`${srcPath} has no extension — a file record is named by one. Nothing was written.`);
+		const allowed = d.storage.extensions;
+		if (allowed && !allowed.includes(ext)) throw new Error(`"${collection}" does not accept .${ext} — its declared extensions are ${allowed.join(', ')}. Nothing was written.`);
+		const size = fs.statSync(srcPath).size;
+		const max = d.storage.max_bytes ?? MAX_RECORD_BYTES;
+		if (size > max) throw new Error(`${srcPath} is ${size} bytes, over "${collection}"'s max_bytes of ${max} — a record is a small file. Nothing was written.`);
+		const existing = this.ids(collection).get(id);
+		if (existing && !force) throw new Error(`${collection}/${id} already exists — pass --force to replace it. Nothing was written.`);
+		const file = this.filePath(d, id, ext);
+		return this.withWriteLock(() => {
+			this._idsCache.delete(collection);
+			fs.mkdirSync(path.dirname(file), { recursive: true });
+			// A replacement whose extension changed would otherwise leave its predecessor behind, and
+			// two files under one id is the ambiguity `check` reports. One id is one file.
+			const stale = existing && existing !== file ? existing : null;
+			const restore = snapshot([file, ...(stale ? [stale] : [])]);
+			if (stale) fs.rmSync(stale, { force: true });
+			fs.copyFileSync(srcPath, file);
+			this.commit([file, ...(stale ? [stale] : [])], `dreamteamer: ${collection} add ${id}`, restore, d.storage.repo ?? '.');
+			return { id, file };
+		});
+	}
+
 	set(collection, id, changes) {
 		const d = this.writableDescriptor(collection);
+		if ((d.storage.codec ?? 'md') === 'file') {
+			throw new Error(`${collection}/${id} is a file record — its fields are derived from the file, so there is nothing to set. Replace it with \`dreamteamer add ${collection} ${id} --from <path> --force\`.`);
+		}
 		const { fields, file } = this.read(collection, id);
 		const previous = fs.readFileSync(file, 'utf8');
 		const next = { ...fields, ...changes };