dreamteamer 0.6.4 → 0.8.0

package/src/collections-cli.js

@@ -8,7 +8,7 @@ import { Store, bodyField } from './store.js';
 import { load, dump } from './yaml.js';
 import { slug } from './template.js';
 import {
-	createCollection, removeCollection, addField, updateField, removeField, fieldDef, saveUiView, removeUiView,
+	createCollection, removeCollection, renameCollection, addField, updateField, removeField, fieldDef, saveUiView, removeUiView,
 	// was copy-pasted here, and the copy went stale the moment the source layout gained a second
 	// spelling — one implementation, two callers
 	workspaceSystemDir,
@@ -17,6 +17,7 @@ import { history, historyDiff } from './history.js';
 import { commandsFor, recordResolver } from './record-commands.js';
 import { distinctValues } from './field-values.js';
 import { matchesFilter } from './filter.js';
+import { baseNameOf, normalizeNamespaces } from './namespace.js';
 import { sortRows } from './temporal.js';
 import { ensureRepo, ensureAllRepos } from './init.js';
 
@@ -69,6 +70,7 @@ export function collectionCommand(ws, collection, verb, args) {
 	// ordinary record path refuses them ("… are system sources") and always would.
 	if (collection === 'collections' && verb === 'add') return metaCollectionsAdd(ws, store, flags);
 	if (collection === 'collections' && verb === 'rm') return metaCollectionsRm(ws, store, flags, pos);
+	if (collection === 'collections' && verb === 'rename') return metaCollectionsRename(ws, store, flags, pos);
 	if (collection === 'commands' && verb === 'for') return metaCommandsFor(ws, store, flags, pos);
 	if (collection === 'ui-views' && ['add', 'set', 'rm'].includes(verb)) return metaUiView(ws, store, verb, flags, pos);
 	if (collection === 'repos' && verb === 'ensure') return metaReposEnsure(ws, flags, pos);
@@ -228,12 +230,36 @@ function metaReposEnsure(ws, flags, pos) {
 
 // `dreamteamer collections add --name research-docs --template docs`
 function metaCollectionsAdd(ws, store, flags) {
-	const { file } = createCollection(ws, store, { name: flags.name, template: flags.template });
+	const { file } = createCollection(ws, store, { name: flags.name, template: flags.template, namespace: flags.namespace });
 	console.log(`✔ ${rel(ws.root, file)}`);
 	console.log('✔ compiled — the collection is live (schema ops prove sources with a real compile)');
 	return 0;
 }
 
+// `dreamteamer collections rename doctors health/doctors`, or `… doctors --namespace health`.
+// The whole point is that namespacing EXISTING data is one command instead of a six-step hand
+// migration whose last step (rewriting references) dangles everything when forgotten.
+function metaCollectionsRename(ws, store, flags, pos) {
+	const [oldName, explicitNew] = pos;
+	if (!oldName) throw new Error('usage: collections rename <old-name> <new-name> | <old-name> --namespace <ns>');
+	// `--namespace health` on its own moves the collection INTO that namespace keeping its bare name,
+	// which is the common case and saves retyping it.
+	const newName = explicitNew
+		?? (flags.namespace ? `${String(flags.namespace).replace(/^\/+|\/+$/g, '')}/${baseNameOf(oldName, normalizeNamespaces(ws.pkg.dreamteamer?.namespaces))}` : null);
+	if (!newName) throw new Error('missing new name — give it positionally or with --namespace <ns>');
+
+	const out = renameCollection(ws, store, oldName, newName);
+	if (flags.json) { emit(JSON.stringify(out)); return 0; }
+	if (!out.renamed) { console.log(`✔ ${oldName} — already named that, nothing to do`); return 0; }
+	console.log(`✔ ${oldName} → ${out.name}`);
+	if (out.from !== out.to) console.log(`  records  ${out.from} → ${out.to} (${out.records})`);
+	if (out.suffix) console.log(`  suffix   .${out.suffix.from}.md → .${out.suffix.to}.md`);
+	if (out.pathKept) console.log(`  ⚠ storage.path kept as "${out.pathKept}" — it was authored, so the rename did not overrule it`);
+	console.log(`  refs     ${out.rewrites} rewritten`);
+	console.log('✔ compiled — the rename is live, in ONE commit');
+	return 0;
+}
+
 // `dreamteamer collections rm widgets [--force]` — --force is required to drop a collection
 // that still has records (removeCollection refuses otherwise, and says so).
 function metaCollectionsRm(ws, store, flags, pos) {

package/src/compile.js

@@ -8,8 +8,11 @@ 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 { walk, patternRe } from './records.js';
 import { unknownOperators } from './filter.js';
+import {
+	normalizeNamespaces, namespaceProblems, unqualifiedProblems, defaultStoragePath, storageOverlaps,
+} from './namespace.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';
@@ -387,7 +390,18 @@ export function compile({ root, pkg }) {
 			const srcDir = kindDir(source.root, kind);
 			if (!fs.existsSync(srcDir)) continue;
 			counts[kind] ??= 0;
-			for (const name of fs.readdirSync(srcDir).sort()) {
+			// `collections/` is enumerated RECURSIVELY, so a namespaced descriptor can be authored at
+			// `collections/health/doctors.collection.yaml` — mirroring where it lands in the runtime and
+			// letting a workspace group its descriptors the same way its data is grouped.
+			//
+			// ⚠ This is load-bearing, not cosmetic. `schema-ops` derives a descriptor's source path from
+			// its name, so `add-field` on `health/doctors` writes the nested path; with a flat readdir
+			// that file was written, silently skipped, and the verb reported ✔ while changing nothing —
+			// the decision-156 shape again. Every other kind stays flat: their ids are single segments.
+			const names = kind === 'collections'
+				? [...walk(srcDir)].map((f) => path.relative(srcDir, f).split(path.sep).join('/'))
+				: fs.readdirSync(srcDir).sort();
+			for (const name of names) {
 				if (name.startsWith('.')) continue;
 				const entityId = name.replace(/\.[^.]+\.(yaml|md|json)$/, '');
 				if (disabled.has(`${source.name}/${entityId}`)) { disabledHits.add(`${source.name}/${entityId}`); continue; }
@@ -478,6 +492,21 @@ export function compile({ root, pkg }) {
 		templateDocs.set(m[1], { template: doc.template ?? {}, src: entry.sources[0] });
 	}
 
+	// ---- namespaces: the declared list, validated against what actually compiled ----------
+	// Declared in the WORKSPACE package.json only, never per-module. A module that could declare a
+	// namespace could rename where another module's records live, and the whole point of a namespace
+	// is that the workspace decides how its own data is partitioned. `namespaces` is also config
+	// rather than records for the same bootstrap reason `git-modules` is (docs/repos-and-modules.md):
+	// a reference has to be parseable before anything has been compiled.
+	const namespaces = normalizeNamespaces(config.namespaces);
+	const collectionNames = [...descriptorGroups.keys()];
+	for (const p of namespaceProblems(namespaces, collectionNames)) fail(p);
+	// The silent failure this whole feature had to fix: a slash in a collection name used to compile
+	// clean, land at `.dreamteamer/collections/<ns>/<name>.collection.yaml`, and then vanish — the
+	// descriptor loader read one directory level, so the collection was simply absent from the
+	// runtime while compile reported ✔ (the same shape as decision 156).
+	for (const p of unqualifiedProblems(collectionNames, namespaces)) fail(p);
+
 	// ---- 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
@@ -491,10 +520,13 @@ export function compile({ root, pkg }) {
 		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']);
+	// The engine's own nine collections are an implicit dependency of every module: the entity kinds
+	// the compiler materializes, plus `repos` (because `repos ensure` clones them). Requiring every
+	// module to declare a dependency on the host it cannot run without would be ceremony, not
+	// verification. ⚠ `users` was in this set until 0.8.0 — a module still declaring
+	// `x-reference: users` now FAILS here, which is the intended loud outcome rather than a ref
+	// pointing at a collection nothing provides.
+	const CORE_COLLECTIONS = new Set([...KINDS, ...DERIVED_KINDS, 'repos']);
 	const wsDir = config['workspace-module'];
 	const wsModuleName = wsDir
 		? sources.find((s) => rel(s.root) === path.join('modules', wsDir))?.name
@@ -504,6 +536,7 @@ export function compile({ root, pkg }) {
 	counts.collections = 0;
 	let mergedCount = 0;
 	let templatedCount = 0;
+	const storageEntries = []; // {name, path, base} per collection — checked for overlap after the loop
 	for (const [name, group] of descriptorGroups) {
 		// a template's bytes feed the compiled descriptor, so it MUST be one of that descriptor's
 		// declared sources — otherwise editing the template leaves every consumer silently stale
@@ -555,6 +588,12 @@ export function compile({ root, pkg }) {
 		// the workspace root, read as zero records, and become writable through the store.
 		merged.storage ??= {};
 		const owned = dataOwners.get(storageOwnerOf(group, base));
+		// A namespaced collection's folder IS its namespace, nested: `health/doctors` →
+		// `data/health/doctors`. Derived rather than required so a descriptor never has to repeat its
+		// own name in a path, and so moving a collection between namespaces is a one-line edit.
+		// An authored `storage.path` still wins — registering an existing folder is a first-class case
+		// (skills/building-dreamteamer/references/collections.md).
+		merged.storage.path ??= defaultStoragePath(name, namespaces, config['data-path'] ?? 'data');
 		const storagePath = String(merged.storage.path ?? '');
 		const systemKinds = [...KINDS, ...DERIVED_KINDS];
 		const isSystem = systemKinds.includes(storagePath) || systemKinds.includes(storagePath.replace(/^system\//, ''));
@@ -566,6 +605,7 @@ export function compile({ root, pkg }) {
 		} else {
 			merged.storage.repo = '.';
 		}
+		storageEntries.push({ name, path: merged.storage.path, base: merged.storage.base });
 		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`
@@ -580,6 +620,16 @@ 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(', ')})`);
 		}
+		// Same reasoning one line up, for the OTHER regex a descriptor carries. `patternRe` throws on a
+		// malformed pattern, and it is called from `store.add` and from `check` — so without this gate a
+		// typo'd `id.pattern` surfaces as a raw "Invalid regular expression" from inside a write instead
+		// of as a compile error naming the descriptor.
+		if (merged.id?.pattern !== undefined) {
+			if (typeof merged.id.pattern !== 'string') fail(`collection "${name}": id.pattern must be a string (got ${JSON.stringify(merged.id.pattern)})`);
+			try { patternRe(merged.id.pattern); } catch (e) {
+				fail(`collection "${name}": id.pattern is not a valid regular expression — ${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
@@ -650,6 +700,12 @@ export function compile({ root, pkg }) {
 		if (extenders.length) mergedCount++;
 	}
 
+	// ---- no collection may sit inside another's folder -------------------------------
+	// Checked HERE because it is the first moment every path is resolved (namespace nesting, the
+	// `owns-data` module prefix and any authored override all already applied). See
+	// namespace.storageOverlaps for what this silently did before it was checked.
+	for (const p of storageOverlaps(storageEntries)) fail(p);
+
 	// ---- 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
@@ -749,6 +805,12 @@ export function compile({ root, pkg }) {
 		// fail at compile, not silently at render (review finding 5)
 		const badOps = view?.filter ? [...unknownOperators(view.filter)] : [];
 		if (badOps.length) fail(`${rt}: unknown filter operator(s) ${badOps.join(', ')}`);
+		// `@me` died with the `users` collection in 0.8.0. It expanded to `users/<slug>`, so on this
+		// engine it can only ever match nothing — and a filter that narrows to zero rows is the exact
+		// silent failure this block exists to prevent. Refuse it by name, with the fix.
+		if (view?.filter && JSON.stringify(view.filter).includes('"@me"')) {
+			fail(`${rt}: filter uses "@me", which was removed with the \`users\` collection in 0.8.0 — it would now match nothing.\n  filter on a field this workspace owns instead (e.g. { status: { _eq: "todo" } }).`);
+		}
 	}
 
 	// ---- command-binding validation --------------------------------------------------
@@ -795,12 +857,17 @@ export function compile({ root, pkg }) {
 	const anyFlat = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, k))));
 	const anyNested = sources.some((s) => KINDS.some((k) => fs.existsSync(path.join(s.root, 'system', k))));
 	const sourceLayout = anyFlat && anyNested ? 'mixed' : anyNested ? 'nested' : 'flat';
-	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout });
+	const { outputs: adapterOutputs, summary: harnessSummary } = runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout, namespaces, version: engineVer });
 
 	// ---- provenance manifest ------------------------------------------------------
 	const manifest = {
 		compiled: new Date().toISOString(),
 		host: engineId(),
+		// The declared namespace list, carried across the boundary so the RECORD layer can split a
+		// reference without importing the compiler or re-reading package.json — the same reason
+		// `storage.base` is a field instead of a path test. An older runtime has no key here, which
+		// reads as "no namespaces", which is exactly right for a workspace that never declared any.
+		namespaces,
 		modules: sources.map((s) => ({ name: s.name, channel: s.channel, root: rel(s.root) || '.' })),
 		ui: uiModules.sort(),
 		'adapter-outputs': adapterOutputs.sort(),

package/src/harnesses.js

@@ -21,7 +21,7 @@ export const STAMP = '<!-- generated by dreamteamer compile — do not edit; sou
 const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 const END = '<!-- dreamteamer:end -->';
 
-export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat' }) {
+export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown' }) {
 	const outputs = [];
 	const summary = [];
 	const rel = (p) => path.relative(root, p);
@@ -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) : null);
+	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version) : 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) : null);
+	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version) : 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) : null);
+	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version) : 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)}\n\n${STAMP}\n`;
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version)}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
@@ -127,15 +127,25 @@ function buildSkillsIndex(entries) {
  *  '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
  *  is the first thing an agent session reads, and a workspace still on the old layout was being told
- *  to write somewhere it does not keep its sources. */
-function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
+ *  to write somewhere it does not keep its sources.
+ *
+ *  `namespaces` is here for exactly the same reason, and it matters more. A reference is
+ *  `<collection>/<id>`, and an id is ALSO a slash path — so in a workspace with declared namespaces an
+ *  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') {
 	const sourcesLine = {
 		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		mixed: '`modules/<module>/<kind>/`, or `<module>/system/<kind>/` where a module still nests it —\n`collections/`, `skills/`, `agents/`, `commands/`,',
 	}[sourceLayout] ?? '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,';
 	const lines = [
-		'this workspace is operated by dreamteamer v0.6. **read the `using-dreamteamer` skill before',
+		// PASSED IN, never hardcoded: this string used to say "v0.6" literally, which was correct for
+		// 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`,
 		'working with data.** schemas (read): `.dreamteamer/collections/` (provenance:',
 		'`.dreamteamer/manifest.yaml`). sources (write): ' + sourcesLine,
 		'`command-bindings/`, `ui-views/`, `collection-templates/`',
@@ -145,6 +155,17 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
 		'check`) after bulk edits; run `dreamteamer compile` (`npm run compile`) after changing any',
 		'source or installing modules.',
 	];
+	// ⚠ Only when the workspace HAS namespaces. Telling an agent about a feature this workspace does
+	// not use is the same failure as telling it the wrong source layout — prose that contradicts the
+	// workspace is worse than no prose.
+	if (namespaces.length) {
+		lines.push(
+			`this workspace declares NAMESPACES: ${namespaces.map((n) => `\`${n}\``).join(', ')}. a collection`,
+			'in one is named with its prefix (`health/doctors`), stores records under `data/<namespace>/`,',
+			'and is referenced as `<namespace>/<collection>/<id>` — so split a reference at the end of the',
+			'DECLARED prefix, not at the first slash. collections with no prefix are unaffected.',
+		);
+	}
 	// 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') {

package/src/init.js

@@ -4,8 +4,6 @@
 import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { dump } from './yaml.js';
-import { slugOrHash } from './template.js';
 import { discoverModules, KINDS } from './compile.js';
 import { Store } from './store.js';
 
@@ -76,7 +74,17 @@ export function init({ flags = {} } = {}) {
 		'data-path': dataPath,
 		harnesses,
 		'gitignore-runtime-folder': true,
-		'workspace-module': name, // workspace-owned system sources live in modules/<name>/ — data and logic stay separated
+		// The workspace's own sources live in `modules/default/`, and the folder is named for its ROLE,
+		// not for the vault. It used to be named after the workspace, and that name went stale twice in
+		// one repo (`hq3` → `gk`, decision 213 reversed by 224) — each rename rewriting every path that
+		// RESOLVES while the historical documents deliberately kept the old spelling, so a stale-looking
+		// `modules/hq3` was correct in prose and a bug in a path. A role name cannot go stale.
+		//
+		// `default` is deliberately the same word `RESERVED_NAMESPACES` holds (namespace.js): this module
+		// owns the DEFAULT-namespace collections, and the default namespace is the empty prefix. The one
+		// misreading it invites — `default/tasks` — is a compile error whose message states the rule.
+		// Override with `--workspace-module <name>` if a workspace wants its own spelling.
+		'workspace-module': flags['workspace-module'] ?? 'default',
 		'git-modules': {},
 		disable: [],
 		...pkg.dreamteamer,
@@ -102,23 +110,16 @@ export function init({ flags = {} } = {}) {
 	fs.mkdirSync(path.join(root, dataPath), { recursive: true });
 	fs.mkdirSync(path.join(root, 'state'), { recursive: true });
 
-	// seed the operator's user record from the git identity.
+	// NO user record is seeded, and there is no `users` collection — both removed from core in 0.8.0.
+	// It failed the "does the ENGINE read it?" test on a circular justification: `users` was core
+	// because `@me` resolved against it, and `@me` existed because `users` was core. Nothing else in
+	// the compiler, the store or `check` ever read a user record. One record per workspace, whose only
+	// job was to restate `git config user.name` in a file that then had to AGREE with it — and when it
+	// disagreed the symptom was an empty inbox with no error (decision 99b), a trap that now cannot
+	// happen because there is nothing to disagree with.
 	//
-	// The id MUST be slugOrHash(git user.name) — that is exactly how `@me` resolves in filters and
-	// ui-views (server.js / fsdata.ts), so seeding it from the same source is what makes the core
-	// /inbox view work by construction. A workspace where a user record is authored by hand under a
-	// different id gets an EMPTY inbox with no error (decision 99b) — hence the setup-script step in
-	// any workspace with a second person.
-	//
-	// No `everyone` team is seeded: `teams` was removed from core 2026-07-31. It was a one-record
-	// abstraction with no reader — nothing in the engine, in `check`, or in any view resolved a team.
-	const gitName = tryGit(root, ['config', 'user.name']) ?? 'operator';
-	const gitEmail = tryGit(root, ['config', 'user.email']);
-	const userId = slugOrHash(gitName);
-	const usersDir = path.join(root, dataPath, 'users');
-	fs.mkdirSync(usersDir, { recursive: true });
-	const userFile = path.join(usersDir, `${userId}.user.yaml`);
-	if (!fs.existsSync(userFile)) fs.writeFileSync(userFile, dump({ name: gitName, ...(gitEmail ? { email: gitEmail } : {}) }));
+	// A workspace that needs people as records ships its own collection (a module's `contacts` already
+	// does), and reads the operator from git where it needs one. `teams` went the same way 2026-07-31.
 
 	// .gitignore + .env.example (append-if-missing, never clobber)
 	appendMissing(path.join(root, '.gitignore'), GITIGNORE);

package/src/namespace.js

@@ -0,0 +1,181 @@
+// NAMESPACES — how a collection name is scoped, and how a reference splits back apart.
+//
+// A namespace is a slash-delimited prefix on a collection name: `health/doctors` is the collection
+// `doctors` in the namespace `health`, and its records live under `data/health/doctors/`. A
+// reference to one of those records is `health/doctors/dana-levi`.
+//
+// ⚠ THE WHOLE PROBLEM IN ONE LINE: an id is ALSO a slash-delimited path (`meetings/2026/07/kickoff`
+// is one collection and a three-segment id), so `a/b/c` is either collection `a` + id `b/c` or
+// collection `a/b` + id `c`, and nothing about the STRING says which.
+//
+// So namespaces are DECLARED, in the workspace package.json:
+//
+//     "dreamteamer": { "namespaces": ["health", "finance", "work/clients"] }
+//
+// and every split consults that closed set, longest match first. The alternative — inferring the
+// boundary from whichever collections happen to exist — was rejected: it makes the meaning of a
+// reference depend on the current descriptor set, so installing a module could silently re-point
+// references in records nobody edited. A declared list also turns the dangerous case (a namespace
+// whose name collides with a collection's) into a compile error instead of a longest-prefix win.
+//
+// The DEFAULT namespace is the empty prefix. `tasks/kickoff` is a reference into it, `data/tasks/`
+// is where it lives, and that is exactly what every workspace already has — which is why adopting
+// namespaces migrates nothing. `default` is reserved precisely so there is never a second spelling
+// for the same collection.
+//
+// This module is deliberately PURE — the declared list arrives as an argument. compile validates it
+// and writes it into the manifest; runtime.js hands it to the record layer. Nothing here reads a
+// file, so all of it is unit-testable without a workspace.
+
+/** Never a namespace: it would give the default namespace a second, prefixed spelling. */
+export const RESERVED_NAMESPACES = new Set(['default']);
+
+/** One segment of a namespace or collection name: the id-safe alphabet the rest of the engine uses. */
+const SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * The declared list, cleaned and ordered for prefix matching: de-duplicated, slash-trimmed, and
+ * sorted LONGEST FIRST so a nested namespace (`work/clients`) is tested before its parent (`work`).
+ * Order is the correctness property here, not a nicety — parent-first would claim `work/clients/acme`
+ * for the namespace `work`, making the collection `clients` and the id `acme` on a workspace where
+ * `work/clients` is the namespace and the collection is something else entirely.
+ */
+export function normalizeNamespaces(list) {
+	if (!Array.isArray(list)) return [];
+	const seen = new Set();
+	for (const raw of list) {
+		if (typeof raw !== 'string') continue;
+		const ns = raw.trim().replace(/^\/+|\/+$/g, '');
+		if (ns) seen.add(ns);
+	}
+	return [...seen].sort((a, b) => b.length - a.length || a.localeCompare(b));
+}
+
+/**
+ * Everything wrong with a declared list, as sentences — or `[]`. `collectionNames` is every compiled
+ * collection's qualified name, which is what makes the collision check possible at all.
+ *
+ * compile calls this and fails on a non-empty result. It is a separate function from the compiler so
+ * the rules can be tested directly, and so the error text lives beside the semantics it protects.
+ */
+export function namespaceProblems(namespaces, collectionNames = []) {
+	const problems = [];
+	const names = new Set(collectionNames);
+	for (const ns of namespaces) {
+		const segments = ns.split('/');
+		for (const seg of segments) {
+			if (RESERVED_NAMESPACES.has(seg)) {
+				problems.push(`namespace "${ns}": "${seg}" is reserved — the default namespace is the EMPTY prefix, so a collection in it is spelled \`tasks\`, never \`default/tasks\`.`);
+			} else if (!SEGMENT.test(seg)) {
+				problems.push(`namespace "${ns}": segment "${seg}" must be lowercase alphanumeric with single hyphens (it becomes a folder name and part of every reference).`);
+			}
+		}
+		// The collision that makes a slash-delimited namespace dangerous: with BOTH a namespace
+		// `health` and a collection `health`, the reference `health/doctors/dana-levi` is a record of
+		// collection `health/doctors` AND a record of collection `health` with the nested id
+		// `doctors/dana-levi`. Longest-match would silently pick the first and make the second
+		// unreferenceable. Refused up front instead.
+		if (names.has(ns)) {
+			problems.push(`namespace "${ns}" collides with the collection of the same name — a reference like "${ns}/x/y" would be ambiguous. Rename one.`);
+		}
+	}
+	return problems;
+}
+
+/** `health` + `doctors` → `health/doctors`; the default namespace (empty) → `doctors`. */
+export function qualify(namespace, name) {
+	const ns = String(namespace ?? '').replace(/^\/+|\/+$/g, '');
+	return ns ? `${ns}/${name}` : String(name);
+}
+
+/**
+ * The declared namespace a qualified collection name sits in, or `''` for the default namespace.
+ * Matched against the declared list rather than by cutting at the last slash, because a collection
+ * name is only namespaced if its prefix was actually declared — see `unqualifiedProblems`.
+ */
+export function namespaceOf(qualified, namespaces) {
+	for (const ns of namespaces) if (qualified.startsWith(ns + '/')) return ns;
+	return '';
+}
+
+/** The bare collection name inside its namespace: `health/doctors` → `doctors`. */
+export function baseNameOf(qualified, namespaces) {
+	const ns = namespaceOf(qualified, namespaces);
+	return ns ? qualified.slice(ns.length + 1) : qualified;
+}
+
+/**
+ * A collection name carrying a slash whose prefix is NOT declared, which is the silent-failure this
+ * whole module exists to prevent: every reference to it would split at the first slash, name a
+ * collection that does not exist, and dangle. Returns problems as sentences, or `[]`.
+ */
+export function unqualifiedProblems(collectionNames, namespaces) {
+	const problems = [];
+	for (const name of collectionNames) {
+		if (!name.includes('/')) continue;
+		if (namespaceOf(name, namespaces)) continue;
+		const guess = name.slice(0, name.lastIndexOf('/'));
+		problems.push(`collection "${name}" is namespaced, but "${guess}" is not declared — add it to \`dreamteamer.namespaces\` in package.json, or every reference to this collection will split at the first slash and dangle.`);
+	}
+	return problems;
+}
+
+/**
+ * Split a reference into `{ collection, id }`, or `null` when it is not a reference shape.
+ *
+ * THE one place the boundary is decided. Everything that parses a reference — the store's write-time
+ * check, `check`'s report, the extension's go-to-definition — goes through here, so a namespace can
+ * never mean one thing on write and another on read.
+ */
+export function parseRef(ref, namespaces = []) {
+	if (typeof ref !== 'string' || !ref) return null;
+	for (const ns of namespaces) {
+		if (!ref.startsWith(ns + '/')) continue;
+		const rest = ref.slice(ns.length + 1);
+		const slash = rest.indexOf('/');
+		// `health/doctors` alone names a COLLECTION, not a record — there is no id, so it is not a
+		// reference. Falling through to the unnamespaced split would call it collection `health`,
+		// which is the ambiguity this module refuses everywhere else.
+		if (slash < 1 || slash === rest.length - 1) return null;
+		return { collection: `${ns}/${rest.slice(0, slash)}`, id: rest.slice(slash + 1) };
+	}
+	const slash = ref.indexOf('/');
+	if (slash < 1 || slash === ref.length - 1) return null;
+	return { collection: ref.slice(0, slash), id: ref.slice(slash + 1) };
+}
+
+/**
+ * The folder a collection's records belong in, workspace-relative and WITHOUT any module prefix
+ * (compile adds that for an `owns-data` module). The namespace becomes real directory nesting, which
+ * is the point: `health/doctors` lands in `data/health/doctors/` rather than beside `data/tasks/`.
+ */
+export function defaultStoragePath(qualified, namespaces, dataPath = 'data') {
+	const ns = namespaceOf(qualified, namespaces);
+	const base = ns ? qualified.slice(ns.length + 1) : qualified;
+	return ns ? `${dataPath}/${ns}/${base}` : `${dataPath}/${base}`;
+}
+
+/**
+ * Storage paths that swallow each other, as sentences — or `[]`. `entries` is `[{name, path}]`.
+ *
+ * ⚠ MEASURED DATA LOSS, not a hypothetical. Give collection A the path `data/health` and collection
+ * B `data/health/doctors`, and A's recursive walk indexes B's records as its own: `dt A list` prints
+ * B's records under A's name, `check` reports B's fields as unknown fields of A, and a write through
+ * A can overwrite a record of B. compile reported ✔ through all of it, because nothing ever compared
+ * two collections' paths. Namespaces make near-misses like this ordinary, so the check is no longer
+ * optional.
+ *
+ * Segment-wise on purpose: `data/health` must not flag `data/health-notes`.
+ */
+export function storageOverlaps(entries) {
+	const problems = [];
+	const sorted = [...entries].filter((e) => e.path).sort((a, b) => a.path.localeCompare(b.path));
+	for (const outer of sorted) {
+		for (const inner of sorted) {
+			if (outer === inner || outer.base !== inner.base) continue;
+			if (!inner.path.startsWith(outer.path + '/')) continue;
+			problems.push(`collection "${inner.name}" stores records under "${inner.path}", which is INSIDE "${outer.name}"'s folder "${outer.path}" — the outer collection would index the inner one's records as its own. Give one of them a folder of its own.`);
+		}
+	}
+	return problems;
+}

package/src/runtime.js

@@ -13,6 +13,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { load } from './yaml.js';
+import { normalizeNamespaces } from './namespace.js';
 
 export const RUNTIME_DIR = '.dreamteamer';
 
@@ -72,9 +73,13 @@ export function loadDescriptors(root) {
 	const dir = runtimeKindDir(root, 'collections');
 	if (!fs.existsSync(dir)) return null;
 	const out = new Map();
-	for (const f of fs.readdirSync(dir).sort()) {
-		if (!f.endsWith('.collection.yaml')) continue;
-		const d = load(fs.readFileSync(path.join(dir, f), 'utf8'));
+	// RECURSIVE, because a namespaced collection compiles to `collections/<ns>/<name>.collection.yaml`
+	// and this loop used to read exactly one directory level. ⚠ That was a SILENT failure, not an
+	// error: compile wrote the nested file and reported ✔, this returned a Map without it, and the
+	// collection was simply absent — `dt <c> list` said "unknown collection" for something that had
+	// just compiled successfully. Keep the walk.
+	for (const f of walkDescriptors(dir)) {
+		const d = load(fs.readFileSync(f, 'utf8'));
 		d.storage ??= {};
 		d.storage.base ??= derivedBase(d);
 		out.set(d.name, d);
@@ -82,6 +87,27 @@ export function loadDescriptors(root) {
 	return out;
 }
 
+/** Every `*.collection.yaml` under a directory, at any depth, in a stable order. */
+function walkDescriptors(dir, out = []) {
+	for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+		if (e.name.startsWith('.')) continue;
+		const p = path.join(dir, e.name);
+		if (e.isDirectory()) walkDescriptors(p, out);
+		else if (e.name.endsWith('.collection.yaml')) out.push(p);
+	}
+	return out;
+}
+
+/**
+ * The workspace's declared namespaces, longest-first — the closed set every reference is split
+ * against. Read off the MANIFEST rather than package.json so the record layer keeps its single
+ * dependency on the compiled artifact (the `sourceRoots()` precedent), and so a runtime compiled
+ * before namespaces existed answers `[]` instead of throwing.
+ */
+export function namespaces(root) {
+	return normalizeNamespaces(readManifest(root)?.namespaces);
+}
+
 /**
  * Which root `storage.path` is relative to — the whole of what the record layer needs to know about
  * the system/data distinction, as DATA rather than as a string test it has to perform. `runtime` =