dreamteamer 0.6.3 → 0.7.0

package/README.md

@@ -1,82 +1,154 @@
 # dreamteamer
 
-A workspace compiler for coding agents. Module sources compile **explicitly** into `.dreamteamer/`,
-the single runtime read surface, and from there into per-harness adapters — Claude Code, Codex, Pi,
-Gemini CLI, Cursor. Data is plain files: records are `<id>.<suffix>.<ext>`, ids are paths,
-references are `<collection>/<id>`. A write lands on disk; `dreamteamer commit` publishes it, one
-commit per repo. Hard validation before disk; nothing hidden.
+**Structured, modular memory for coding agents.**
+
+Your agent already has a memory. You just can't see it — it's prose, in a black box somewhere,
+untracked and unshared. And memory *is* context, which is the single biggest lever on what your agent
+decides and how well it does it. So the most consequential thing in your setup is the one you have the
+least access to.
+
+dreamteamer makes it **files with a schema**: plain markdown in your git repo that your agent reads
+natively, and that you can browse as tables, boards and forms.
 
 ```bash
-npm i dreamteamer         # engine + the `dreamteamer` bin
+npm i dreamteamer
 npx dreamteamer init      # scaffold a workspace
 npx dreamteamer compile   # sources → .dreamteamer (+ harness adapters)
-npx dreamteamer check     # validate every record
+npx dreamteamer check     # prove every record and every link is intact
 npx dreamteamer help      # the full command surface
 ```
 
-There is a VS Code extension — [dreamteamer-vscode](https://github.com/dreamteamer/dreamteamer-vscode) —
-which loads the engine **your workspace pins**, so the editor, the CLI and any agent session are
-provably running the same code.
+Apache-2.0. No server, no account, no telemetry.
 
-## Sources, and where they come from
+## Structured
 
-A module contributes collections, skills, agents, commands, command-bindings, UI views and
-collection templates. Modules are discovered over three channels, in precedence order: inline
-`modules/*`, then `git_modules/*`, then npm dependencies. Sources live **flat at a module root** —
-`modules/crm/skills/`, beside `package.json` — and an unknown folder at a module root is a compile
-error rather than a silent skip.
+A record is a file. That's the whole trick.
 
-## Attached repos (`repos`) vs modules (`git-modules`)
+```
+data/meetings/2026/07/kickoff.meeting.md
+```
 
-Two different lifecycles, deliberately two different homes.
+```yaml
+---
+title: Kickoff
+date: 2026-07-14
+attendees: [contacts/ada, contacts/lin]
+project: projects/apollo
+---
+Ada walked through the constraints. Lin owns the spec by Friday.
+```
 
-**Modules** are declared in the workspace's `package.json` under `dreamteamer.git-modules` and
-restored by `dreamteamer install`. They MUST live in config rather than in records because of a
-genuine bootstrap ordering: a fresh clone has no `.dreamteamer`, therefore no compiled schemas,
-therefore no readable records — so module clones have to be restorable before anything can be read.
+Your agent opens that file the way it opens any file. Nothing is intercepted, nothing is proxied,
+there is no API to learn.
 
-**Attached repos** are `repos` records under `data/repos/`. They contribute NOTHING to the
-workspace — no schema, no skills, no UI. A repo record says only where a related git repo lives and
-how to get it, and exists so that domain collections can reference `repos/<id>` instead of each
-inventing its own url/ref/identity fields. Because they are not needed at compile time, they get to
-be data — which buys hard validation, the record CLI verbs, and history for free.
+But `attendees` isn't a string — it's a link. `dreamteamer check` proves every one of them resolves,
+and renaming `contacts/ada` updates everything pointing at it. A write with an unknown field, a wrong
+type, or a reference to a record that doesn't exist is **rejected before it touches disk**.
 
-Working trees are materialized **on demand**:
+**A schema is an agreement about what things are called.** Shared terminology with guardrails — not a
+cage, because it stays negotiable. You change it by saying so:
 
-```bash
-dreamteamer repos ensure <id>     # clone if missing, print the path; idempotent
-dreamteamer repos ensure --all    # explicit opt-in, e.g. before going offline
+> *"From here on a client has a renewal date, and it's a date."*
+
+That's a schema update and a data migration, and it's an **explicit, reviewable event** rather than
+silent drift. Once it exists you get the column in a table, the field in a form, validation, sorting
+and aggregation — all of it falling out of having said what the thing is.
+
+The shape of a record is deliberately dull, because dull is what survives:
+
+- records are `<id>.<suffix>.<ext>` files; **the id is the path** inside the collection folder
+- references are `<collection>/<id>` — always qualified, greppable, never a bare name
+- a collection may be scoped under a **declared namespace** — `health/doctors/dana-levi`, stored in
+  `data/health/doctors/`. The default namespace is the empty prefix, so `tasks/kickoff` is unchanged
+- a write lands on disk; `dreamteamer commit` publishes it, one commit per repo
+- schemas are JSON Schema in a YAML file, one per collection
+
+## Modular
+
+**Data and skills are the new app structure.** A coding agent with the right skills over the right
+data is arbitrary functionality — but composing that with no module system is where most setups stall.
+
+So dreamteamer doesn't invent one. **It uses npm.**
+
+`node_modules` is battle-tested, universally adopted, and already sitting in nearly every
+coding-agent setup. A module contributes collections, skills, agents, commands, command-bindings and
+UI views — and skills and agents are treated as exactly what they are: **memory that loads into
+context**, living in the same module structure as everything else, in a standard your tooling already
+understands.
+
+Three channels, one shape:
+
+```
+modules/<name>/        # lives in this repo
+git_modules/<name>/    # lives in its own repo
+node_modules/<name>/   # published package
 ```
 
-`install` deliberately does not do this. The record count only grows while the fraction any given
-session needs only shrinks, so eager restore would make every fresh clone slow, would require every
-identity's credentials to be present at install time, and would let one unreachable remote fail the
-whole install. Lazy materialization fails only the action you asked for, at the moment you asked.
+Precedence runs top to bottom, so a local copy shadows a published one — which is how you develop a
+module and use it in the same workspace at the same time.
+
+Sources live **flat at a module root** — `modules/crm/skills/`, beside `package.json` — and a folder
+at a module root that isn't a known kind is a compile error rather than a silent skip.
+
+### Modules are not rigid
+
+This is the part that differs from npm on purpose.
+
+Installing a module into a workspace that already has opinions — its own idea of what a `contact` is —
+is a **negotiation, not an overwrite**. Four workspaces wanted a CRM and all four wanted a different
+`contacts`. A hard import would force one answer and make every divergence a fork.
+
+Two same-name collections is a compile error that names both descriptors and tells you the move:
+declare `extends: <module>/<collection>` and overlay only what differs. Because every schema is one
+small YAML file, adapting is cheap — read it, change what doesn't fit, and the diff shows exactly what
+you agreed to.
 
-Path resolution is `<repos-path>/<identity>/<name>`, where `repos-path` is a `package.json`
-`dreamteamer` key defaulting to `projects`, and `identity` is optional (omit it for
-`<repos-path>/<name>`). A record's `path` field overrides the derivation entirely.
+So domain modules are **recipes you copy and adapt, not packages you install**, and divergence is the
+normal case rather than a failure.
 
-**`identity` is an opaque path segment to the engine.** A workspace may use it to select a git
-identity — via `~/.gitconfig` `includeIf` rules keyed on the path, for example — but that resolution
-happens outside the engine, which only joins it into a path.
+## Every harness, one source
 
-**A missing working tree is not a violation.** `dreamteamer check` does not and must not flag it: a
-reference to `repos/<id>` resolves because the RECORD exists, and whether the clone is on disk is
-irrelevant to referential integrity. Presence is reported by `dreamteamer status`.
+`compile` writes `.dreamteamer/` — the single runtime read surface — and from there into per-harness
+adapters: Claude Code, Codex, Pi, Gemini CLI, Cursor. Author a skill once; every agent you run sees it.
 
-## Domain modules are recipes, not packages
+## The editor
 
-Anything domain-shaped — people, meetings, products, content — belongs in a module, and a generic
-version belongs in a recipe a workspace **copies and adapts**. They are deliberately not installable
-packages: four workspaces wanted a CRM and all four wanted a different `contacts`, so an import
-would force one answer and make every divergence a fork.
+[dreamteamer-vscode](https://github.com/dreamteamer/dreamteamer-vscode) gives you tables, boards,
+calendars, maps, forms and a data-model designer over the same files — and it loads **the engine your
+workspace pins**, so the editor, the CLI and any agent session are provably running the same code.
+
+## Docs
+
+This is an agent-native tool, so its documentation is shipped as skills the agent loads on demand —
+and you can read them like any other file:
+
+- [`skills/using-dreamteamer`](skills/using-dreamteamer) — the map: collections, conventions, the CLI,
+  how records work
+- [`skills/building-dreamteamer`](skills/building-dreamteamer) — authoring: collections, skills,
+  agents, commands, UI views, and which of those a given request should become
+- [`docs/repos-and-modules.md`](docs/repos-and-modules.md) — attached repos vs modules, and why they
+  have different homes
+- [`docs/namespaces-blast-radius.md`](docs/namespaces-blast-radius.md) — scoping collections under a
+  namespace (`health/doctors`), what it costs consumers, and why the default namespace is transparent
+- [`UPDATING.md`](UPDATING.md) — what to do when upgrading, one section per release
+
+## What it isn't
+
+Not a database — records are files and git is the history. Not a cloud service — there is no server
+and no account. Not a note-taking app — it's the layer underneath one.
+
+And it is **not** for data that needs row-level access control, field-level encryption, or provable
+erasure. Git cannot do those, and pretending otherwise is how people get hurt. This is for
+human-scale structured knowledge: thousands of records, not millions.
 
 ## Contributing
 
 Issues are welcome. For anything larger than a typo, please open a discussion before a pull request —
-this is a small, deliberately lean codebase (`npm run metrics` enforces size budgets), and it's
-better to agree on the shape first.
+this is a small, deliberately lean codebase (`npm run metrics` enforces size budgets), and it's better
+to agree on the shape first.
+
+`npm run verify` is the gate: import-layer direction, size budgets, and the test suite (tiers 1+2,
+zero dependencies, a few seconds). See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## License
 

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,7 +1,7 @@
 {
 	"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",
+	"version": "0.7.0",
+	"description": "A workspace compiler for coding agents \u2014 schema-validated records as plain files over git, compiled into every harness",
 	"license": "Apache-2.0",
 	"author": "Gilad Khen <giladkhen@gmail.com>",
 	"homepage": "https://github.com/dreamteamer/dreamteamer#readme",
@@ -49,10 +49,16 @@
 		"express": "^5.2.1",
 		"js-yaml": "^4.1.0"
 	},
-	"dreamteamer": {},
+	"dreamteamer": {
+		"title": "System"
+	},
 	"scripts": {
+		"test": "node scripts/test.mjs",
+		"test:unit": "node scripts/test.mjs --unit",
+		"test:watch": "node --watch scripts/test.mjs --unit",
 		"metrics": "node scripts/metrics.mjs",
 		"metrics:check": "node scripts/metrics.mjs --check",
-		"layers": "node scripts/layers.mjs"
+		"layers": "node scripts/layers.mjs",
+		"verify": "node scripts/layers.mjs && node scripts/metrics.mjs --check && node scripts/test.mjs"
 	}
 }

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

@@ -8,6 +8,7 @@ One descriptor file: `modules/<module>/collections/<name>.collection.yaml`. The
 | goal | how |
 |---|---|
 | new collection from a template | `dt collections add --name research-docs --template docs` |
+| move one into a namespace | `dt collections rename doctors health/doctors` (or `doctors --namespace health`) |
 | templateless | `dt collections add --name <n>` — emits a minimal compilable schema |
 | add a field | `dt <collection> add-field --name urgent --type boolean --default-value false` |
 | change / drop a field | `dt <collection> update-field …` · `remove-field --name <f>` |
@@ -20,8 +21,37 @@ or a bare collection name for a reference into it. `--required true` widens `req
 
 ⚠ **The meta verbs write the WORKSPACE module only.** To change a field on a collection another
 module owns, either edit that module's descriptor by hand or add an `extends:` overlay.
-⚠ **There is no `collections rename`** — it refuses system sources. A rename is `git mv` of the
-descriptor + edit `name`/`storage.path`/`suffix` + re-suffix every record, all in one commit.
+**`dt collections rename <old> <new>`** moves the descriptor, the records, the record filenames and
+every inbound reference in ONE commit — including `x-reference` targets in other descriptors and any
+ui-view pointing at it. `<old> --namespace <ns>` is sugar for moving it into a namespace under the same
+bare name. It refuses a compiled source, a module-owned collection, a taken name, and an undeclared
+target namespace; a refusal leaves nothing half-moved. Two things it deliberately does NOT overrule,
+because both are authored choices: a `storage.path` you set by hand (the records stay put, and it says
+so) and a `storage.suffix` that is not the singular of the old name.
+
+## namespaces — scoping a collection under a folder
+
+A collection name may carry a slash-delimited namespace, and it becomes real directory nesting:
+
+| declare in the workspace `package.json` | create it | lands in | referenced as |
+|---|---|---|---|
+| `"namespaces": ["health"]` | `dt collections add --namespace health --name doctors` | `data/health/doctors/` | `health/doctors/dana-levi` |
+
+- **The default namespace is the empty prefix.** `tasks` stays `data/tasks/` and `tasks/kickoff`, so
+  common entities need no prefix and adopting namespaces migrates nothing. `default` is RESERVED —
+  there is never a second spelling for one collection.
+- ⚠ **The namespace MUST be declared before the collection compiles.** An id is also a slash path
+  (`meetings/2026/07/kickoff`), so `a/b/c` is ambiguous without the declared set; an undeclared prefix
+  is a compile error rather than a reference that silently names a different collection.
+- `--namespace health --name doctors` and `--name health/doctors` are the same thing. The descriptor
+  lands at `collections/health/doctors.collection.yaml`, mirroring the runtime; the `suffix` comes off
+  the bare name (`<id>.doctor.md`).
+- `x-reference: health/doctors`, `disable: "<module>/health/doctors"` and every record verb all take the
+  QUALIFIED name — it is the collection's identity everywhere.
+- Nested namespaces work (`work/clients`), longest declared prefix wins.
+- ⚠ **No collection may store records inside another's folder** — a namespace folder cannot itself be a
+  collection root. compile refuses it, because the outer collection would index the inner one's records
+  as its own.
 
 ## `templates:` — a live shared field set
 

package/skills/using-dreamteamer/references/records.md

@@ -74,6 +74,23 @@ due: '2026-07-28'
 Users report the login button does nothing on mobile.
 ```
 
+## namespaced collections
+
+A collection may be scoped under a namespace declared in the workspace `package.json`
+(`dreamteamer.namespaces`). Everything about working with its records is unchanged except that the
+QUALIFIED name is the collection's name everywhere:
+
+```bash
+dt health/doctors add --name "Dana Levi"     # → data/health/doctors/dana-levi.doctor.md
+dt health/visits add --name Checkup --date 2026-03-04 --doctor health/doctors/dana-levi
+```
+
+- a reference is still `<collection>/<id>` — `health/doctors/dana-levi` is the collection
+  `health/doctors` and the id `dana-levi`.
+- the **default namespace has no prefix**: `tasks/kickoff` in `data/tasks/`, exactly as always.
+- ⚠ a namespace only exists if it is DECLARED. Without the declaration the same string reads as the
+  collection `health` with a nested id, so it dangles — `dt check` says so.
+
 ## the hard rules
 
 **never hand-rename or `mv` a record file** — the id IS the path, so a rename silently dangles

package/src/check.js

@@ -6,7 +6,8 @@ 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 { NO_RUNTIME, loadDescriptors, runtimeDir } from './runtime.js';
+import { NO_RUNTIME, loadDescriptors, runtimeDir, namespaces as compiledNamespaces } from './runtime.js';
+import { parseRef } from './namespace.js';
 
 export function check({ root }) {
 	const RUNTIME = runtimeDir(root);
@@ -25,6 +26,9 @@ export function check({ root }) {
 		console.error(`✖ ${NO_RUNTIME}`);
 		return 2;
 	}
+	// Off the manifest, like the descriptors themselves — `check` is in the record layer and must not
+	// learn what a workspace package.json is (see the split in CLAUDE.md).
+	const namespaces = compiledNamespaces(root);
 
 	// ---- index all records: collection -> Map<id, filePath> ------------------------
 	const index = new Map();
@@ -74,10 +78,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 +109,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);
@@ -120,7 +126,8 @@ export function check({ root }) {
 			const self = `${name}/${id}`;
 			for (const value of valuesAt(fields, fieldPath)) {
 				if (typeof value !== 'string' || value.startsWith('@')) continue;
-				const targetId = value.slice(value.indexOf('/') + 1);
+				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 back = [...valuesAt(targetFields, [inverse])];
@@ -132,17 +139,28 @@ 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('/');
-		if (slash < 1) return flag(file, `${fieldPath.join('.')}: reference "${value}" is not <collection>/<id>`);
-		const coll = value.slice(0, slash);
-		const id = value.slice(slash + 1);
+		// The SAME parser the store writes through (src/namespace.js) — `check` disagreeing with the
+		// write path about where a namespace ends would flag valid records and pass invalid ones.
+		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 (!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 +168,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/cli.js

@@ -55,8 +55,14 @@ repo attachment (working trees are materialized ON DEMAND, never at install):
   repos ensure --all [--json]                 (explicit opt-in: everything, e.g. before going offline)
 
 meta verbs (schema operations — write SOURCES through a compile gate, never the runtime):
-  collections add --name <name> [--template docs|entity]
+  collections add --name <name> [--namespace <ns>] [--template docs|entity]
+                            (--namespace health --name doctors === --name health/doctors; the
+                             namespace must already be declared in dreamteamer.namespaces, and
+                             records land in data/<ns>/<name>/)
   collections rm <name> [--force]             (--force required if it still has records)
+  collections rename <old> <new>              (or <old> --namespace <ns> to move it into one)
+                            moves the descriptor AND the records, re-suffixes files when the
+                            suffix was derived, rewrites every inbound reference, ONE commit
   <collection> add-field    --name <field> --type <type> [--options a,b] [--default-value v] [--required true]
                             [--description "what this field means"]
                             types: string text markdown boolean number integer date datetime

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) {