dreamteamer 0.6.3 → 0.6.4

package/collections/collections.collection.yaml

@@ -69,9 +69,21 @@ schema:
     icon:
       type: string
       description: material-symbols-outlined icon name, drawn in the nav and page header. The VS Code tree maps it to the nearest codicon — an unmapped name falls back to a generic cylinder, so pick one that is already mapped or add the row.
+    owner:
+      type: string
+      x-reference: modules
+      description: >-
+        The module that OWNS this concept — DERIVED by compile from the base source, never authored.
+        An overlay adds fields to somebody else's collection and does not take it over, so `meetings`
+        stays owned by crm even though hq3 overlays it. This is the workspace's real partition, and
+        what the nav groups by.
     group:
       type: string
-      description: Which nav folder this collection sits in. Ungrouped collections list at the top level; `system` is the plumbing group behind the gear.
+      description: >-
+        DEPRECATED as a nav axis since 2026-08-11 — the nav groups by `owner` (a module, which has a
+        title of its own) instead of by this string with a display-name map maintained in a surface.
+        Still read by nothing; kept so the change is a code revert rather than a data migration, and
+        because a workspace may yet want a partition that deliberately DIFFERS from its modules.
 order: 10
 list_fields: [name, last-modified]
 icon: schema

package/collections/modules.collection.yaml

@@ -0,0 +1,81 @@
+name: modules
+# The modules this workspace compiled, PROJECTED by compile from what it discovered — the first
+# derived collection in core, and the shape is deliberate enough to name.
+#
+# Every other runtime-stored collection (skills, commands, ui-views…) is STAGED from a module's
+# source folder and read back by the engine. This one is neither: `package.json` stays the source of
+# truth and compile keeps reading it, so a record here is a projection, never an input. Editing one
+# would be editing a photograph.
+#
+# Why it earns a place anyway, against the three questions:
+#   1. Does the ENGINE read it? It reads the DATA, which is the test that matters. `dependencies`
+#      names modules and is checked for cycles; `peerDependencies` names collections and is what
+#      lets a cross-module reference compile at all (compile.js — "cyclic module dependencies",
+#      "an overlay cannot compile without its base"). This is enforced structure, not annotation.
+#   2. Recipe creeping into core? No. A module is the engine's own concept.
+#   3. Could a module do it instead? No — nothing inside a module can enumerate the module set.
+#
+# What it buys is the thing a `group:` label cannot express: EDGES. A group is a partition; a
+# dependency is a relation, and it has two kinds that mean different things. Once it is a
+# collection, the browse, the diagram, `dt modules list` and the nav all work with no code written
+# for any of them.
+storage: { path: modules, codec: yaml, shape: file, suffix: module }
+id:
+  generate: "{{ name | slug }}"
+  pattern: "^[a-z0-9-]+$"
+title_template: "{{ name }}"
+schema:
+  type: object
+  required: [name, channel]
+  properties:
+    name:
+      type: string
+      description: The module's package name, verbatim — `@dreamteamer/crm`, `hq3-workspace`.
+    title:
+      type: string
+      description: >-
+        What to CALL this module — authored as `dreamteamer.title` in its package.json, else derived
+        from the id. Authored because deriving cannot know an acronym: titleCase("crm") is "Crm".
+        A module names itself, which is what replaces a display-name map maintained in a surface.
+    channel:
+      type: string
+      enum: [path, git, npm, inline]
+      description: How this module reached the workspace. `inline` is the workspace's own sources.
+    path:
+      type: string
+      description: Workspace-relative root of the module's sources.
+    owns_data:
+      type: boolean
+      description: >-
+        The module keeps its records in its OWN clone rather than this workspace's data/ — so a
+        write there commits in that repo, and a rename spanning both is unavoidably two commits.
+    dependencies:
+      type: array
+      description: >-
+        Modules this one cannot compile without — an overlay needs its base. HARD and acyclic;
+        compile fails on a ring and names the peer escape hatch.
+      items:
+        type: string
+        x-reference: modules
+    peer_dependencies:
+      type: array
+      description: >-
+        Collections this module REFERENCES but does not own. Soft on purpose: naming a concept
+        rather than a module is what keeps two modules from forming a ring, and what lets a module
+        ship an unused reference without dragging in a whole CRM.
+      items:
+        type: string
+        x-reference: collections
+    collections:
+      type: array
+      description: >-
+        Collections this module contributed a source for. A collection merged from several modules
+        appears under EVERY one of them — which is the honest answer the flat "which module owns
+        this" provenance could not give (it took the first source and dropped the overlay).
+      items:
+        type: string
+        x-reference: collections
+order: 140
+list_fields: [title, name, channel, collections]
+icon: deployed_code
+group: system

package/package.json

@@ -1,58 +1,60 @@
 {
-	"name": "dreamteamer",
-	"version": "0.6.3",
-	"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>",
-	"homepage": "https://github.com/dreamteamer/dreamteamer#readme",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/dreamteamer/dreamteamer.git"
-	},
-	"bugs": {
-		"url": "https://github.com/dreamteamer/dreamteamer/issues"
-	},
-	"keywords": [
-		"agent",
-		"coding-agent",
-		"claude-code",
-		"workspace",
-		"compiler",
-		"cli",
-		"yaml",
-		"markdown",
-		"json-schema",
-		"git"
-	],
-	"type": "module",
-	"engines": {
-		"node": ">=20"
-	},
-	"bin": {
-		"dreamteamer": "./bin/dreamteamer.js"
-	},
-	"files": [
-		"NOTICE",
-		"bin",
-		"src",
-		"collections",
-		"skills",
-		"agents",
-		"commands",
-		"command-bindings",
-		"ui-views",
-		"collection-templates"
-	],
-	"dependencies": {
-		"ajv": "^8.17.1",
-		"ajv-formats": "^3.0.1",
-		"express": "^5.2.1",
-		"js-yaml": "^4.1.0"
-	},
-	"dreamteamer": {},
-	"scripts": {
-		"metrics": "node scripts/metrics.mjs",
-		"metrics:check": "node scripts/metrics.mjs --check",
-		"layers": "node scripts/layers.mjs"
-	}
+  "name": "dreamteamer",
+  "version": "0.6.4",
+  "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>",
+  "homepage": "https://github.com/dreamteamer/dreamteamer#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dreamteamer/dreamteamer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dreamteamer/dreamteamer/issues"
+  },
+  "keywords": [
+    "agent",
+    "coding-agent",
+    "claude-code",
+    "workspace",
+    "compiler",
+    "cli",
+    "yaml",
+    "markdown",
+    "json-schema",
+    "git"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "dreamteamer": "./bin/dreamteamer.js"
+  },
+  "files": [
+    "NOTICE",
+    "bin",
+    "src",
+    "collections",
+    "skills",
+    "agents",
+    "commands",
+    "command-bindings",
+    "ui-views",
+    "collection-templates"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1",
+    "ajv-formats": "^3.0.1",
+    "express": "^5.2.1",
+    "js-yaml": "^4.1.0"
+  },
+  "dreamteamer": {
+    "title": "System"
+  },
+  "scripts": {
+    "metrics": "node scripts/metrics.mjs",
+    "metrics:check": "node scripts/metrics.mjs --check",
+    "layers": "node scripts/layers.mjs"
+  }
 }

package/src/check.js

@@ -74,10 +74,12 @@ 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 softRefs = new Map(); // absent-but-declared peer collection -> how many refs point at it
 
 	for (const [name, d] of descriptors) {
 		const validate = ajv.compile(d.schema);
 		const refFields = collectRefFields(d.schema);
+		const softTargets = d.unresolved_peers ? new Set(d.unresolved_peers) : null;
 		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) {
@@ -103,7 +105,7 @@ export function check({ root }) {
 			}
 			for (const [fieldPath, target] of refFields) {
 				for (const value of valuesAt(fields, fieldPath)) {
-					checkRef(file, fieldPath, value, target);
+					checkRef(file, fieldPath, value, target, softTargets);
 				}
 			}
 			parsed.get(name).set(id, fields);
@@ -132,7 +134,7 @@ export function check({ root }) {
 		}
 	}
 
-	function checkRef(file, fieldPath, value, target) {
+	function checkRef(file, fieldPath, value, target, softTargets) {
 		if (typeof value !== 'string') return;
 		if (value.startsWith('@')) return; // runtime tokens (@me, @initiator) are legal
 		const slash = value.indexOf('/');
@@ -142,7 +144,17 @@ export function check({ root }) {
 		if (target !== '*' && coll !== target) {
 			return flag(file, `${fieldPath.join('.')}: reference "${value}" should target collection "${target}"`);
 		}
-		if (!descriptors.has(coll)) return flag(file, `${fieldPath.join('.')}: reference "${value}" targets unknown collection "${coll}"`);
+		if (!descriptors.has(coll)) {
+			// A collection the owning module DECLARED as a peer and nothing installed provides is the
+			// normal state of a module opened on its own — the reference is unresolvable, not wrong.
+			// `unresolved_peers` is stamped by compile so this layer never has to know what a module
+			// is (see the record/workspace split in CLAUDE.md).
+			if (softTargets?.has(coll)) {
+				softRefs.set(coll, (softRefs.get(coll) ?? 0) + 1);
+				return;
+			}
+			return flag(file, `${fieldPath.join('.')}: reference "${value}" targets unknown collection "${coll}"`);
+		}
 		if (!index.get(coll).has(id)) return flag(file, `${fieldPath.join('.')}: dangling reference "${value}" — no such record`);
 	}
 
@@ -150,6 +162,11 @@ export function check({ root }) {
 	for (const s of strays) {
 		console.log(`⚠ ${s.file} — unrecognized file in ${s.collection} folder${s.note ? ` (${s.note})` : ''}`);
 	}
+	// Warned, never silent: the references are real and currently resolve to nothing. This is the
+	// expected reading when a module is opened without the workspace that provides the concept.
+	for (const [coll, n] of [...softRefs].sort()) {
+		console.log(`⚠ peer collection "${coll}" is declared but not installed — ${n} reference${n === 1 ? '' : 's'} unresolvable`);
+	}
 	if (violations.length === 0) {
 		console.log(`✔ 0 violations (${[...index.values()].reduce((n, m) => n + m.size, 0)} records across ${descriptors.size} collections)`);
 		return 0;

package/src/compile.js

@@ -7,13 +7,14 @@ import path from 'node:path';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import { load, dump } from './yaml.js';
+import { slug } from './template.js';
 import { walk } from './records.js';
 import { unknownOperators } from './filter.js';
 // circular on paper in earlier versions — safe: both sides only
 // call at run time, same pattern as store.js ↔ compile.js.
 import { runHarnessAdapters } from './harnesses.js';
 import { satisfies } from './semver.js';
-import { readManifest, runtimeDir } from './runtime.js';
+import { DERIVED_KINDS, readManifest, runtimeDir } from './runtime.js';
 
 // re-exported, not moved: `readManifest` is in the VS Code extension's hand-maintained engine
 // contract as `compileMod.readManifest` (engine.ts), and a removed export is the same cross-repo
@@ -64,8 +65,30 @@ function staleDisplayKeywords(schema, prefix = '') {
 	return out;
 }
 
+/**
+ * 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.
+ */
+function refTargets(schema, prefix = '') {
+	const out = [];
+	for (const [key, prop] of Object.entries(schema?.properties ?? {})) {
+		if (!prop || typeof prop !== 'object') continue;
+		const at = `${prefix}${key}`;
+		if (prop['x-reference']) out.push([at, prop['x-reference']]);
+		if (prop.items && typeof prop.items === 'object' && prop.items['x-reference']) out.push([`${at}[]`, prop.items['x-reference']]);
+		if (prop.properties) out.push(...refTargets(prop, `${at}.`));
+		if (prop.items?.properties) out.push(...refTargets(prop.items, `${at}[].`));
+	}
+	return out;
+}
+
 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
+// KINDS on purpose: a module folder named `modules/` would be nonsense, and `isSystem` below keys
+// off KINDS to decide `storage.base`, so a `modules` collection landing on `base: workspace` would
+// point the store at the SOURCE directory and read every module folder as a record.
 
 /**
  * A module's source folder for one kind. The layout is FLAT — `<module>/skills`, beside `data/` —
@@ -238,6 +261,8 @@ export function compile({ root, pkg }) {
 	const engineVer = engineVersion();
 	const declaredEnv = new Map(); // env key -> [module names]
 	const moduleIgnores = new Map(); // module name -> non-source folders it declares (strayKindDirs)
+	const moduleDeps = new Map();  // module name -> [module names]      — HARD, must be acyclic
+	const modulePeers = new Map(); // module name -> [collection names]  — SOFT, cannot cycle
 	for (const source of sources) {
 		let mpkg;
 		try { mpkg = JSON.parse(fs.readFileSync(path.join(source.root, 'package.json'), 'utf8')); } catch { continue; }
@@ -246,6 +271,16 @@ export function compile({ root, pkg }) {
 			if (!Array.isArray(ignore)) fail(`module "${source.name}": "ignore" must be a list of folder names (got ${JSON.stringify(ignore)})`);
 			moduleIgnores.set(source.name, ignore.map(String));
 		}
+		// npm's TERMINOLOGY, deliberately not npm's namespace: these live under `dreamteamer` so
+		// npm's own resolver never tries to fetch an inline or git-channel module.
+		for (const [key, sink] of [['dependencies', moduleDeps], ['peerDependencies', modulePeers]]) {
+			const decl = mpkg.dreamteamer?.[key];
+			if (decl === undefined) continue;
+			if (!Array.isArray(decl) || decl.some((v) => typeof v !== 'string')) {
+				fail(`module "${source.name}": dreamteamer.${key} must be a list of ${key === 'dependencies' ? 'module names' : 'collection names'} (got ${JSON.stringify(decl)})`);
+			}
+			sink.set(source.name, decl);
+		}
 		const range = mpkg.dreamteamer?.engine;
 		if (range) {
 			const ok = satisfies(engineVer, range);
@@ -275,6 +310,36 @@ export function compile({ root, pkg }) {
 		}
 	}
 
+	// ---- the module dependency graph -------------------------------------------------
+	// `dependencies` names MODULES and must be acyclic. `peerDependencies` names COLLECTIONS and
+	// therefore cannot cycle at all — which is the whole reason it exists: two modules that each
+	// reference a concept the other owns (crm needs `products`, rnd needs `contacts`) would be an
+	// unbreakable ring under module-named deps, and are two independent peer declarations here.
+	const moduleNames = new Set(sources.map((s) => s.name));
+	for (const [mod, deps] of moduleDeps) {
+		for (const dep of deps) {
+			if (dep === mod) fail(`module "${mod}" declares itself as a dependency`);
+			if (!moduleNames.has(dep)) {
+				fail(`module "${mod}" depends on "${dep}", which is not installed — modules present: ${[...moduleNames].sort().join(', ')}`);
+			}
+		}
+	}
+	// DFS with an explicit path so the error can print the ring rather than just naming one module
+	{
+		const state = new Map(); // name -> 'open' | 'done'
+		const visit = (mod, trail) => {
+			if (state.get(mod) === 'done') return;
+			if (state.get(mod) === 'open') {
+				const ring = [...trail.slice(trail.indexOf(mod)), mod];
+				fail(`cyclic module dependencies: ${ring.join(' → ')}\n  a reference to a CONCEPT another module owns belongs in dreamteamer.peerDependencies (a collection name), which cannot cycle.`);
+			}
+			state.set(mod, 'open');
+			for (const dep of moduleDeps.get(mod) ?? []) visit(dep, [...trail, mod]);
+			state.set(mod, 'done');
+		};
+		for (const mod of moduleDeps.keys()) visit(mod, []);
+	}
+
 	const dataOwners = dataOwningModules(sources, fail, rel);
 
 	const disabled = new Set(config.disable ?? []);
@@ -413,6 +478,28 @@ export function compile({ root, pkg }) {
 		templateDocs.set(m[1], { template: doc.template ?? {}, src: entry.sources[0] });
 	}
 
+	// ---- who owns which collection, and which module IS the workspace ----------------
+	// Needed before the resolution loop so each descriptor can be validated against the graph as it
+	// is merged. The owner is the group member that does NOT declare `extends`; a group with two of
+	// those is a name collision, and the loop below raises it properly — this pass only maps.
+	// A module's record id: the npm scope stripped, so `@dreamteamer/crm` reads as `crm` — which is
+	// what every message in this engine already calls it.
+	const moduleId = (n) => slug(String(n).replace(/^@[^/]+\//, ''));
+	const collOwner = new Map(); // collection name -> owning module name
+	const moduleColls = new Map(); // module name -> Set(collection names it contributed to)
+	for (const [name, group] of descriptorGroups) {
+		const base = group.find((g) => !g.doc.extends);
+		if (base) collOwner.set(name, base.moduleName);
+	}
+	// The engine's own nine collections are an implicit dependency of every module: seven entity
+	// kinds plus the two the compiler materializes. Requiring every module to declare a dependency
+	// on the host it cannot run without would be ceremony, not verification.
+	const CORE_COLLECTIONS = new Set([...KINDS, ...DERIVED_KINDS, 'users', 'repos']);
+	const wsDir = config['workspace-module'];
+	const wsModuleName = wsDir
+		? sources.find((s) => rel(s.root) === path.join('modules', wsDir))?.name
+		: pkg.name;
+
 	// ---- resolve descriptor groups (templates + extends merge) ---------------------
 	counts.collections = 0;
 	let mergedCount = 0;
@@ -448,6 +535,11 @@ export function compile({ root, pkg }) {
 			if (ext.doc.extends !== expected) {
 				fail(`${ext.src.path}: extends "${ext.doc.extends}" does not name the base "${expected}"`);
 			}
+			// `extends` is the hardest dependency there is — the extender does not compile at all
+			// without the base (see the "no base found" failure above), so it must say so.
+			if (ext.moduleName !== base.moduleName && !(moduleDeps.get(ext.moduleName) ?? []).includes(base.moduleName)) {
+				fail(`${ext.src.path}: extends "${expected}" but module "${ext.moduleName}" does not declare "${base.moduleName}" in dreamteamer.dependencies — an overlay cannot compile without its base.`);
+			}
 			merged = mergeDescriptor(merged, ext.doc);
 		}
 		delete merged.extends;
@@ -464,7 +556,8 @@ export function compile({ root, pkg }) {
 		merged.storage ??= {};
 		const owned = dataOwners.get(storageOwnerOf(group, base));
 		const storagePath = String(merged.storage.path ?? '');
-		const isSystem = KINDS.includes(storagePath) || KINDS.includes(storagePath.replace(/^system\//, ''));
+		const systemKinds = [...KINDS, ...DERIVED_KINDS];
+		const isSystem = systemKinds.includes(storagePath) || systemKinds.includes(storagePath.replace(/^system\//, ''));
 		merged.storage.base = isSystem ? 'runtime' : 'workspace';
 		if (owned && !isSystem) {
 			const modRel = rel(owned.root);
@@ -487,6 +580,56 @@ export function compile({ root, pkg }) {
 		} catch (e) {
 			fail(`collection "${name}": schema is not a valid JSON Schema — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
 		}
+		// ---- the reference contract: every target is owned, depended on, or declared a peer ----
+		// Attribution is unioned across the whole group rather than taken from the base, because the
+		// merge keeps no per-field provenance — an overlay that adds a ref field would otherwise be
+		// judged against the BASE module's declarations, which it never wrote.
+		const groupModules = [...new Set(group.map((g) => g.moduleName))];
+		// WHO OWNS the concept — the module whose source is the base, not the ones overlaying it.
+		// An overlay adds fields to somebody else's collection (hq3 adds `tags` to crm's contacts);
+		// it does not take the concept over. Measured 2026-08-11: letting the overlay win moves
+		// `contacts` and `meetings` out of CRM, and a CRM without contacts reads as broken.
+		//
+		// ⚠ This is NOT the `module` provenance field an outside review rejected this morning. That
+		// one duplicated `group:` while claiming to name every contributor, and got the merged case
+		// wrong by taking the first source. This names ONE thing — the owner — for which the base
+		// IS the answer, and it exists to REPLACE `group:` as the workspace's partition rather than
+		// to sit beside it.
+		merged.owner = `modules/${moduleId(base?.moduleName ?? groupModules[0])}`;
+		// EVERY contributing module, not just the base — a collection merged from crm + hq3 belongs
+		// to both, and saying otherwise is what made a flat "which module owns this" field wrong.
+		for (const m of groupModules) {
+			if (!moduleColls.has(m)) moduleColls.set(m, new Set());
+			moduleColls.get(m).add(name);
+		}
+		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 === '*') {
+				// The workspace module is the orchestrating parent and may reference anything —
+				// including modules that do not exist yet, which is what `tasks.item` means.
+				// Anywhere else a wildcard is a cross-module surface no declaration can cover.
+				if (!groupModules.includes(wsModuleName)) {
+					console.warn(`⚠ collection ${name}: field "${at}" uses x-reference: '*' outside the workspace module — an unverifiable cross-module surface; name the collections it may target`);
+				}
+				continue;
+			}
+			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 —
+		// check.js is in the record layer and must not know modules exist).
+		const unresolved = [...declaredPeers].filter((p) => !collOwner.has(p)).sort();
+		if (unresolved.length) merged.unresolved_peers = unresolved;
+
 		// ---- resolved labels: what to CALL this collection, its records and its fields --------
 		// Written into the artifact next to `storage.base` and for the same reason: the nav, the
 		// browse page, the CLI and the extension then read ONE field instead of each carrying its
@@ -507,6 +650,64 @@ export function compile({ root, pkg }) {
 		if (extenders.length) mergedCount++;
 	}
 
+	// ---- modules, projected ---------------------------------------------------------
+	// One record per discovered module, written from what discovery and the package pass already
+	// established. `package.json` remains the source of truth and compile keeps reading it — this
+	// is a photograph, never an input (see collections/modules.collection.yaml for why it earns a
+	// place in core at all).
+	//
+	// The id strips an npm scope so `@dreamteamer/crm` reads as `crm`, which is what every message
+	// in this engine already calls it. A collision is a hard failure rather than a silent overwrite:
+	// two modules answering to one id would make `dependencies` ambiguous, and an ambiguous edge is
+	// worse than no diagram.
+	const idByModule = new Map();
+	for (const source of sources) {
+		const id = moduleId(source.name);
+		const clash = idByModule.get(id);
+		if (clash && clash !== source.name) fail(`modules "${clash}" and "${source.name}" both resolve to the id "${id}" — rename one.`);
+		idByModule.set(id, source.name);
+	}
+	for (const source of sources) {
+		const id = moduleId(source.name);
+		let mpkg = {};
+		try { mpkg = JSON.parse(fs.readFileSync(path.join(source.root, 'package.json'), 'utf8')).dreamteamer ?? {}; } catch { /* inline workspace source */ }
+		const record = {
+			name: source.name,
+			// Authored wins; the derived fallback title-cases the id the same way a collection's
+			// `title` is derived. `@dreamteamer/crm` -> "Crm" until crm declares "CRM" — which is
+			// the point: the module is the only place that knows.
+			title: typeof mpkg.title === 'string' && mpkg.title ? mpkg.title : titleCase(id),
+			channel: source.channel,
+			path: rel(source.root) || '.',
+			...(mpkg['owns-data'] === true ? { owns_data: true } : {}),
+			// Declared module names become record IDS here, because that is what an x-reference
+			// resolves against. An undeclared/unknown name would dangle, and `check` would say so —
+			// but compile has already failed on that case (the acyclicity pass resolves every one).
+			// ⚠ A reference VALUE is `<collection>/<id>`, never a bare id — `check` rejects the bare
+			// form, which is exactly what it did to the first pass of this projection (63 violations).
+			...(moduleDeps.get(source.name)?.length
+				? { dependencies: moduleDeps.get(source.name).map((n) => `modules/${moduleId(n)}`) }
+				: {}),
+			...(modulePeers.get(source.name)?.length
+				? { peer_dependencies: modulePeers.get(source.name).map((c) => `collections/${c}`) }
+				: {}),
+			...(moduleColls.get(source.name)?.size
+				? { collections: [...moduleColls.get(source.name)].sort().map((c) => `collections/${c}`) }
+				: {}),
+		};
+		const bytes = Buffer.from(dump(record));
+		// ⚠ The source hash is the hash of the SOURCE FILE, not of the projected record. Hashing the
+		// output made every source "differ" on the next run, so `staleness` reported the workspace
+		// stale immediately after a clean compile — the one signal that has to stay trustworthy.
+		const pkgPath = path.join(source.root, 'package.json');
+		const pkgBytes = fs.existsSync(pkgPath) ? fs.readFileSync(pkgPath) : bytes;
+		entries.set(path.join('modules', `${id}.module.yaml`), {
+			sources: [{ path: rel(pkgPath), hash: sha256(pkgBytes) }],
+			bytes,
+		});
+		counts.modules = (counts.modules ?? 0) + 1;
+	}
+
 	// ---- unresolved references are compile errors (an agent's declared skills)
 	const skillIds = new Set([...entries.keys()].filter((k) => k.startsWith('skills/')).map((k) => k.split('/')[1]));
 	for (const [rt, e] of entries) {

package/src/presentation.js

@@ -5,6 +5,8 @@
 // the client adapter shrinks to a thin path translator. shapes deliberately match what
 // the studio components already speak (field {field,type,meta,schema}).
 
+import { sourceHint } from './runtime.js';
+
 /** the projection for every collection: rows keyed by collection name + collection meta. */
 export function presentation(descriptors) {
 	const collections = [];
@@ -60,7 +62,16 @@ function collectionRow(d) {
 	if (typeof d.icon === 'string') meta.icon = d.icon;
 	if (typeof d.group === 'string') meta.group = d.group;
 	if (typeof d.description === 'string' && d.description.length > 0) meta.description = d.description;
-	return { collection: d.name, meta, system: d.storage?.base === 'runtime' };
+	// A compiled collection is READ-ONLY through the record layer, and the UI needs to say so
+	// BEFORE offering a button — an error after the click is a worse answer than a disabled
+	// control with a reason. The sentence comes from runtime.js so the store's refusal and this
+	// hint can never disagree.
+	const system = d.storage?.base === 'runtime';
+	if (system) {
+		meta.readonly = true;
+		meta.readonly_hint = sourceHint(d);
+	}
+	return { collection: d.name, meta, system };
 }
 
 function referenceTargetOf(prop) {

package/src/runtime.js

@@ -16,6 +16,27 @@ import { load } from './yaml.js';
 
 export const RUNTIME_DIR = '.dreamteamer';
 
+/**
+ * Runtime kinds compile PROJECTS rather than stages — they have no source folder under a module
+ * root, so nothing can be "edited and recompiled" in the usual place. Lives here, in the boundary,
+ * because it is a fact about the runtime's SHAPE: the compiler writes them and the record layer has
+ * to describe them, and neither half should learn it from the other (the `storage.base` precedent).
+ */
+export const DERIVED_KINDS = ['modules'];
+
+/**
+ * Where a human edits a compiled collection, as one sentence. ONE definition, because there are two
+ * consumers who must never drift: the store's refusal (`dt modules set …`) and the presentation
+ * projection the UI reads to explain a disabled button. This repo's own history is the argument —
+ * `git log`/`git diff` and the `?sort=` comparator were each hand-copied into the extension and
+ * went wrong in both places.
+ */
+export function sourceHint(d) {
+	return DERIVED_KINDS.includes(d?.storage?.path)
+		? "the source it was projected from (for `modules`, the module's package.json)"
+		: `the file under the owning module (modules/<module>/${d?.storage?.path}/)`;
+}
+
 /** One message, two callers with different manners: the store throws it, `check` prints it. */
 export const NO_RUNTIME = 'no compiled runtime — run `dreamteamer compile` first';
 

package/src/store.js

@@ -11,7 +11,7 @@ import { dump } from './yaml.js';
 import { generateId } from './template.js';
 import { parseRecord, parseRecordText, patternRe, fmtAjvError, unknownFields, walk, EXT, assertSafeId } from './records.js';
 import { normalizeRecord } from './temporal.js';
-import { NO_RUNTIME, loadDescriptors, runtimeDir, sourceRoots as compiledSourceRoots } from './runtime.js';
+import { NO_RUNTIME, sourceHint, loadDescriptors, runtimeDir, sourceRoots as compiledSourceRoots } from './runtime.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
@@ -46,7 +46,13 @@ export class Store {
 	writableDescriptor(collection) {
 		const d = this.descriptor(collection);
 		if (d.storage.base === 'runtime') {
-			throw new Error(`"${collection}" records are compiled sources — edit the file under the owning module (modules/<module>/${d.storage.path}/) and run \`dreamteamer compile\``);
+			// Two different runtime shapes, and pointing at the wrong one is worse than saying
+			// nothing: a STAGED kind (skills, commands, ui-views…) really does have a source file
+			// under `modules/<module>/<kind>/`, while a PROJECTED one (modules) has no such folder
+			// and never should — its source is the module's package.json. `x-source` says which,
+			// stated as data on the descriptor so the store never has to know what a module is.
+			const from = sourceHint(d);
+			throw new Error(`"${collection}" records are compiled sources — edit ${from} and run \`dreamteamer compile\``);
 		}
 		return d;
 	}