dreamteamer 0.31.0 → 0.32.0

package/collections/collections.collection.yaml

@@ -91,6 +91,32 @@ schema:
         entry:
           type: string
           description: Folder shapes only — the file inside the folder that IS the record (e.g. SKILL.md).
+        under:
+          type: object
+          description: >-
+            RELATIONSHIP-BASED STORAGE — records live INSIDE the folder of the record they belong
+            to. `{ field: company, path: meetings }` puts a meeting whose `company` is
+            `companies/northwind` at `<companies root>/northwind/meetings/<id>.meeting.md`; one with
+            no `company` stays in this collection's own `path`, which remains its fallback root.
+            Still ONE logical collection: `list` is the union across every parent folder, a
+            reference is `<collection>/<id>` wherever the file sits, and the id never changes when
+            the owner does — `set <field>=…` MOVES the file. `field` must be a scalar `x-reference`
+            to exactly one collection, that collection must be `shape: folder`, and one level is
+            supported (a placed collection cannot be a parent). The field is the intended owner and
+            the folder is observed placement: `check` reports a disagreement, `dreamteamer relocate`
+            reconciles it, nothing infers an owner from where a file was found. Not for a record
+            many parents share equally — that is a plain reference.
+          required: [field, path]
+          properties:
+            field:
+              type: string
+              description: The scalar reference field on THIS collection that names the parent record.
+            path:
+              type: string
+              description: The folder INSIDE each parent record's folder that holds these records — relative, e.g. `meetings`.
+            collection:
+              type: string
+              description: DERIVED by compile, never authored — the parent collection, read off `field`'s x-reference so the record layer never opens a schema to find it.
         repo:
           type: string
           description: DERIVED by compile, never authored — the workspace-relative root of the git repo holding these records ('.' is the workspace). Set from the owning module's `owns-data`.

package/package.json

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

package/skills/using-dreamteamer/SKILL.md

@@ -30,7 +30,10 @@ unsure which skill owns the job in front of you.
 
 - a record is a `<id>.<suffix>.<ext>` file (or a folder, for folder-shape collections). **the id
   is the path** inside the collection folder minus suffix and extension — nested folders join in:
-  `data/meetings/2026/07/standup.meeting.md` ⇒ id `2026/07/standup`.
+  `data/meetings/2026/07/standup.meeting.md` ⇒ id `2026/07/standup`. a collection may instead keep
+  its records INSIDE the folder of the record they belong to (`storage.under` — a company's
+  meetings in `data/companies/<company>/meetings/`): still ONE collection, the same id, the same
+  `meetings/<id>` reference; only the folder follows the owner field (`references/collections.md`).
 - **references are `<collection>/<id>`** strings — always qualified, greppable, never a bare name
   and never a file path.
 
@@ -61,7 +64,7 @@ dispatch, so it cannot drift):
 
 - a collection may be spelled in the SINGULAR on any of these (`dt add task "call the bank"` — one bare positional is the title); references inside records still spell the full name
 - read & measure — `list` `get` `values` `history` `diff` `next` `relations` `resolve`
-- write & publish — `add` `set` `rm` `rename` `move` `revert` `commit`
+- write & publish — `add` `set` `rm` `rename` `move` `revert` `commit` `relocate`
 - fields (sources, through the compile gate) — `add-field` `set-field` `rm-field` `rename-field` (system entities — modules, collections, skills, ui-views… — take the RECORD verbs above)
 - workspace — `init` `install` `update` `compile` `check` `status` `changes` `help`
 - an EXTENSION (a workspace module or a dependency declaring `dreamteamer.extension`) adds verbs of
@@ -105,6 +108,7 @@ Load by the map; nothing here is loaded "just in case".
 | "what changed while I was away" | `references/changes.md` |
 | the workspace seems unable to do something — a new kind of thing, a missing capability, "don't we already have this?" | `references/before-you-build.md` (look first); a new model then continues `references/data-modeling.md` (decide) → `references/collections.md` (write it) |
 | a collection or field, mechanically — the descriptor, the system and field verbs, `templates:`/`extends:`, a compile or check message | `references/collections.md` |
+| "keep a company's meetings in the company's folder" — records stored beside the record they belong to, a `placed … but` check report, `dt relocate` | `references/collections.md` (declaring it) · `references/records.md` (working with it) |
 | knowledge a session should find on its own | `references/skills.md` |
 | "let me type one word and have this done" | `references/commands.md` |
 | "which command applies to this record?" — a binding, a gate | `references/commands.md` |

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

@@ -172,7 +172,77 @@ is copied.
 - Nested namespaces work (`work/clients`); the 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.
+  inner one's records as its own. The one DECLARED exception is the next section: a collection
+  stored under the records of a folder-shape parent, where compile knows exactly which files
+  belong to whom.
+
+## relationship-based storage — records beside the record they belong to
+
+A collection can keep each record INSIDE the folder of the record it belongs to, so a company's
+folder holds the company's meetings and a browse of `data/companies/northwind/` shows the whole
+account. It is declared on the CHILD's `storage`, in one line, and changes nothing about what the
+collection IS:
+
+```yaml
+# modules/default/collections/meetings.collection.yaml
+storage: { path: data/meetings, suffix: meeting, under: { field: company, path: meetings } }
+```
+
+```text
+data/companies/northwind/company.md                            ← the parent: shape: folder, entry: company.md
+data/companies/northwind/meetings/2026/10/kickoff.meeting.md   ← meetings/2026/10/kickoff, company: companies/northwind
+data/meetings/2026/10/offsite.meeting.md                       ← meetings/2026/10/offsite, no company: the FALLBACK root
+```
+
+- **Still one logical collection.** `dt list meetings` is the union across every company folder
+  and the fallback root, ordered by id; `dt get meetings/2026/10/kickoff` finds the file wherever it
+  sits; a reference is `meetings/<id>` everywhere. Nothing is spelled per company — no descriptor,
+  no skill, no view.
+- **The id is independent of placement.** `dt set meetings/<id> company=companies/harbor` MOVES
+  the file into Harbor's folder and changes nothing else: not the id, not one inbound reference.
+  Clearing the field moves it back to the fallback root. An id is unique across every root, and a
+  second file claiming one is a `check` violation and a write refusal, never last-one-wins.
+- **`field`** is a scalar `x-reference` to exactly ONE collection (a list has no single folder; a
+  union has no single parent). **`path`** is a relative folder inside each parent record's folder.
+  compile derives `under.collection` from the field; nothing else is authored.
+- **The parent must be `shape: folder`** (`storage: { shape: folder, entry: company.md }`) — only
+  a folder can hold anything beside the record. A file-shape collection that should become a
+  parent changes its descriptor to folder shape, and `dt relocate <collection>` then moves each
+  `<id>.<suffix>.md` into `<id>/<entry>` with its id unchanged (`check` names them until it runs).
+- **One level.** A placed collection cannot itself be a parent; the child is a text record
+  (`md` · `yaml` · `json`, file shape) — an opaque or folder-shape child is refused for now. Two
+  children of one parent need two different paths, and a path never equals the parent's entry.
+- **The field is the owner; the folder is observed placement.** A file found under the wrong
+  company — moved by hand, or sitting in the fallback root from before the declaration existed — is
+  `placed under … but <field> is …` in `check`, which changes nothing. `dt relocate <collection>`
+  (or `<collection>/<id>`, `--dry-run` first) moves files to where the compiled descriptor puts
+  them and refuses a source with unpublished changes or an occupied destination. Editing some OTHER
+  field never relocates as a side effect; nothing ever infers an owner from where a file was found.
+- **A parent with records inside its folder cannot be removed** — not with `--force` either;
+  reassign or clear their owner first. Renaming the parent carries the folder with everything in
+  it and rewrites the children's owner field; their ids do not change.
+- **Adopting it on existing data is three explicit steps**, each reviewable: make the parent folder
+  shape and `relocate` it; add `under` to the child and compile (no file moves at compile — `check`
+  reports every mismatch); `relocate` the child, `--dry-run` first. `dt commit` stages a moved
+  record's old and new path together; `dt revert` of an owner change moves the file back.
+- **Removing or changing `under` is the same walk backwards, and compile holds the door.** While
+  records still sit inside parent folders, a compile that drops the declaration, changes its
+  `path`, or moves the PARENT collection's `storage.path` is REFUSED — the new descriptor would stop
+  every reader seeing them. The order is
+  `dt relocate <collection> --to-root` (every placed record back into the collection's own folder,
+  ids unchanged, under the still-current declaration) → edit the descriptor → compile → `dt relocate
+  <collection>` to place them under the new path. The same order renames a placed collection.
+- **`relocate` refuses before it moves anything**: a dangling or malformed owner field (fix the
+  field first — it never makes a folder for a parent that does not exist), an occupied destination,
+  a source with unpublished changes, or a destination behind a symlink. One problem refuses the
+  whole plan; `--dry-run` reports it.
+- **Inside a parent's folder, only real entries count.** A symlink at a child root, on the way to
+  one, or anywhere beneath one — a folder or a file — is never written through and never read as a
+  record; `check` names it. The collection's own roots (`data/`, `storage.path`) are not subject to
+  this; the rule is about what a record folder may contain.
+- **When NOT to use it.** A record several parents share equally, a record whose owner is usually
+  unknown, or a collection nobody browses as a folder — keep conventional storage and a plain
+  reference. Folder grouping is a browsing convenience, never a permission boundary.
 
 ## `templates:` — a live shared field set
 

package/skills/using-dreamteamer/references/data-modeling.md

@@ -300,7 +300,15 @@ roadmap, not a model; wait for the second consumer.
   `max_bytes` (default 200 KB). A big binary is not a record: it lives outside the vault under a
   declared var, with an ordinary record carrying the `${env:...}` template that points at it.
 - **`shape: folder` when a record is intrinsically several files** (a skill with references beside
-  it). Rare; prefer one file until the record itself demands companions.
+  it), or when OTHER collections' records should live inside it — see the next bullet. Otherwise
+  prefer one file until the record itself demands companions.
+- **`storage.under` when people browse a parent as a unit** — a company folder holding that
+  company's meetings, a case folder holding its documents. It is one line on the CHILD
+  (`under: { field: company, path: meetings }`), the collection stays ONE collection with the same
+  ids and references, and the owner field is what moves a file (`collections.md`). Choose ONE
+  physical owner and leave every other relationship a plain reference; keep conventional storage
+  when no single owner is sensible, when the owner is usually unknown, or when nobody would open
+  the folder. It organises files; it grants nothing.
 - **Machine-specific paths are templates, never absolute paths.** `${env:FILES_FOLDER}/…` is inert
   data rendered per machine by `dt resolve`; an absolute path in a record is wrong on every other
   machine, silently. **A files folder is named after the collection or field that indexes it, and

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

@@ -111,6 +111,23 @@ first slash. the default namespace has no prefix (`tasks/kickoff`, exactly as al
 undeclared prefix reads as a nested id and dangles — `dt check` says so. declaring one is
 `collections.md`.
 
+## records stored under another record — the folder follows the owner
+
+a collection may declare `storage.under` (`collections.md`): a meeting with a `company` lives in
+that company's folder, one without stays in `data/meetings/`. working with it is unchanged in
+every way that names a record — `list` is the whole collection, `get`/`set`/`rm`/`rename` take
+`meetings/<id>` wherever the file sits, references never carry a folder — and different in one:
+**the owner field moves the file.** `dt set meetings/<id> company=companies/harbor` relocates the
+record into Harbor's folder with the same id and every inbound reference intact; `company=`
+moves it back to the fallback root. so never `mv` one by hand, exactly as for a rename — a file
+under the wrong company is what `check` reports as `placed under … but`, and `dt relocate
+<collection>[/<id>]` (`--dry-run` first) is what moves it to where its field says — refusing whole
+when an owner field dangles, a destination is taken or a source is unpublished. a parent
+holding records in its folder refuses `rm` until they are reassigned; `dt commit <collection>/<id>`
+after a move publishes both paths; `dt revert` of an owner change moves the file back too. before
+the declaration is removed or its path changed: `dt relocate <collection> --to-root`
+(`collections.md` has the order — compile refuses the edit while records would be stranded).
+
 ## two-way relations — the mirror is generated, and read-only
 
 a reference field may declare `x-inverse`: compile GENERATES the field it names on the TARGET

package/src/check.js

@@ -10,6 +10,7 @@ import { NO_RUNTIME, loadDescriptors, runtimeDir, namespaces as compiledNamespac
 import { parseRef } from './namespace.js';
 import { refTargetsOf, refIsSoft } from './ref.js';
 import { relationsOf, expectedMirrors } from './relations.js';
+import { placementOf, placedRecords, ownerIdOf, symlinkedChildRoots } from './placement.js';
 
 export function check({ root }) {
 	const RUNTIME = runtimeDir(root);
@@ -34,16 +35,19 @@ export function check({ root }) {
 
 	// ---- index all records: collection -> Map<id, filePath> ------------------------
 	const index = new Map();
+	// placed collections only: id -> the parent id its file was FOUND under (null = the fallback root)
+	const observed = new Map();
 	const strays = [];
 	// declared here rather than beside the validation pass: indexing can itself produce a
 	// finding (an unreachable data root, below) before a single record is read.
 	const violations = [];
+	const dirOf = (d) => path.join(d.storage.base === 'runtime' ? RUNTIME : root, d.storage.path);
 	for (const [name, d] of descriptors) {
 		const ids = new Map();
 		index.set(name, ids);
 		// runtime-based (knowhow/meta) collections are read from the COMPILED runtime —
 		// their sources may live in any module; .dreamteamer is the merged read surface
-		const dir = path.join(d.storage.base === 'runtime' ? RUNTIME : root, d.storage.path);
+		const dir = dirOf(d);
 		// An unreachable data ROOT is a finding, not a skip: a collection whose module clone is
 		// missing otherwise reports zero records and a clean check — a silent success. An EMPTY
 		// directory stays fine (a module with no records yet is normal); only a missing owning
@@ -53,13 +57,46 @@ export function check({ root }) {
 			violations.push({ file: d.storage.path, msg: `collection "${name}" is owned by ${d.storage.repo}, which is not present — every record in it is unreadable` });
 			continue;
 		}
+		const under = placementOf(d);
+		if (under) {
+			// ONE logical collection across the fallback root and every parent folder — the same walk
+			// the store indexes with (src/placement.js), so the two cannot disagree about which files
+			// are records. The first file to claim an id keeps it; every later one is a violation,
+			// because a `get` that silently answered from whichever folder sorted later is the
+			// failure this report exists to make visible.
+			const seen = new Map();
+			observed.set(name, seen);
+			const parentDir = dirOf(descriptors.get(under.collection));
+			// a child root that is (or sits behind) a symlink is not read — whatever it points at is not
+			// this parent's folder — and it is named here rather than silently skipped
+			for (const link of symlinkedChildRoots(under, parentDir)) {
+				violations.push({ file: rel(link), msg: `is a symlink — ${name} records are read only from real folders inside ${under.collection} records; whatever this points at is not indexed. Replace it with a real folder.` });
+			}
+			const onLink = (p) => violations.push({ file: rel(p), msg: `is a symlink inside a ${under.collection} record's folder — nothing behind it is read as a ${name} record, and nothing is written through it. Replace it with a real folder or file.` });
+			for (const r of placedRecords(d, dir, parentDir, onLink)) {
+				if (ids.has(r.id)) {
+					violations.push({ file: rel(r.file), msg: `collection "${name}" holds the id "${r.id}" twice — ${rel(ids.get(r.id))} and ${rel(r.file)}. Remove one.` });
+					continue;
+				}
+				ids.set(r.id, r.file);
+				seen.set(r.id, r.parentId);
+			}
+			continue;
+		}
 		if (!fs.existsSync(dir)) continue;
 		const shape = d.storage.shape ?? 'file';
 		if (shape === 'folder') {
+			// a FILE record at the root of a folder-shape collection is the state a collection is in
+			// right after its shape changed — named as such, with the verb that finishes the change
+			const asFile = { ...d, storage: { ...d.storage, shape: 'file' } };
 			for (const entry of fs.readdirSync(dir).sort()) {
 				if (entry.startsWith('.')) continue;
 				const p = path.join(dir, entry);
-				if (!fs.statSync(p).isDirectory()) { strays.push({ collection: name, file: rel(p) }); continue; }
+				if (!fs.statSync(p).isDirectory()) {
+					const legacy = idFromRecordPath(asFile, entry) !== null;
+					strays.push({ collection: name, file: rel(p), note: legacy ? `a file-shape record in a folder-shape collection — dreamteamer relocate ${name} moves it to ${entry.split('.')[0]}/${d.storage.entry}` : undefined });
+					continue;
+				}
 				const main = path.join(p, d.storage.entry ?? 'SKILL.md');
 				if (fs.existsSync(main)) ids.set(entry, main);
 				else strays.push({ collection: name, file: rel(p), note: `missing entry file ${d.storage.entry}` });
@@ -127,6 +164,24 @@ export function check({ root }) {
 					checkRef(file, fieldPath, value, target, softTargets, soft);
 				}
 			}
+			// ---- placement: the FIELD is the intended owner, the FOLDER is observed placement ---
+			// Reported, never repaired: a record found under the wrong company is either a hand move
+			// (the field is right, run relocate) or a hand edit of the field (the folder is right, set
+			// it back) and only a person knows which. A malformed owner value is skipped here — the
+			// reference check above has already named it, and "placed under X but owner is empty"
+			// on top of that would be a second report of one typo.
+			const under = placementOf(d);
+			if (under) {
+				const raw = fields[under.field];
+				const wellFormed = raw == null || raw === '' || parseRef(raw, namespaces);
+				const want = ownerIdOf(fields, under, (v) => parseRef(v, namespaces));
+				const got = observed.get(name).get(id);
+				if (wellFormed && want !== got) {
+					const where = got ? `under ${under.collection}/${got}` : `in its own root (${d.storage.path})`;
+					const should = want ? `${under.field} is ${under.collection}/${want}` : `${under.field} is empty`;
+					flag(file, `placed ${where} but ${should} — the file is not where its owner puts it. Run: dreamteamer relocate ${name}/${id}`);
+				}
+			}
 			parsed.get(name).set(id, fields);
 		}
 	}

package/src/checkout.js

@@ -55,7 +55,7 @@ export function planInstall(state, opts = {}) {
 	const { checkout: c } = state;
 	const steps = [];
 	// ⚠ EVERY declared direct dependency, not just the engine. A worktree whose engine is a mirrored dev
-	// LINK used to read as ready while an installed extension (@dreamteamer/workflows) was missing — so
+	// LINK used to read as ready while an installed extension was missing — so
 	// npm never ran, and compile then refused the extension's source folder as an unknown kind.
 	const missing = state.missingDeps ?? [];
 	steps.push(missing.length
@@ -336,7 +336,7 @@ export function readHookInput(stdinText) {
 
 // The hook events and the verb each one runs. Core owns ONE — making the checkout a session opens in
 // ready — and an installed extension adds its own (`hooks:` in its contribution; the worktree
-// lifecycle lives in @dreamteamer/workflows). NO MATCHER on any of them (spec §13.9): bootstrap is
+// lifecycle belongs to a worktree extension). NO MATCHER on any of them (spec §13.9): bootstrap is
 // idempotent precisely so the session-start hook may fire on every event — `startup` alone would
 // silence it on resume, clear, compact and fork, which is most of what a long session actually does.
 const CLAUDE_HOOKS = { SessionStart: 'install --hook' };

package/src/cli.js

@@ -79,6 +79,17 @@ the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee i
   relations [<collection>]                    (every two-way pair: owner.field → target.mirror)
   relations rebuild <collection> [--drop <f>] (regenerate mirror VALUES from the owning side;
                                                --drop removes a stale ex-mirror key from records)
+  relocate <target> [--dry-run] [--json]      (move record FILES to where the compiled descriptor
+                                               puts them — a record stored under another
+                                               collection (storage.under) whose folder disagrees
+                                               with its owner field, or a file record in a
+                                               collection that became shape: folder. Ids and
+                                               references never change; a pending edit on a
+                                               moved file, or a dangling owner, refuses the whole
+                                               plan — commit, or fix the field, first)
+  relocate <collection> --to-root [--dry-run]  (the REVERSE: every placed record back into the
+                                               collection's own folder, ids unchanged — the step
+                                               before removing or changing storage.under)
   resolve '<string>' | <collection>/<id> <field>
                                               (render \${env:NAME} · \${workspaceFolder} ·
                                                \${userHome} — the ONLY substitution point; a
@@ -245,7 +256,7 @@ export const WORKSPACE_FLAGS = {
 	init: ['name', 'data-path', 'harnesses', 'workspace-module'], update: [],
 	install: ['clone', 'dry-run', 'json', 'link-env', 'all', 'hook', 'print-adapters'],
 	compile: ['watch'], check: [], status: [],
-	changes: ['since', 'json'], commit: ['dry-run', 'json'],
+	changes: ['since', 'json'], commit: ['dry-run', 'json'], relocate: ['dry-run', 'json', 'to-root'],
 };
 
 /** Every verb this CLI answers itself — the set an extension's `commands` may not claim. The retired
@@ -254,7 +265,7 @@ export const WORKSPACE_FLAGS = {
 export const CORE_VERBS = [
 	'init', 'install', 'update', 'compile', 'check', 'status', 'changes', 'commit', 'help', 'version', '--version', '-v',
 	'list', 'add', 'values', 'get', 'set', 'rm', 'rename', 'history', 'diff', 'revert', 'move', 'next',
-	'add-field', 'set-field', 'rm-field', 'rename-field', 'relations', 'resolve',
+	'add-field', 'set-field', 'rm-field', 'rename-field', 'relations', 'resolve', 'relocate',
 	'schema', 'ensure', 'update-field', 'remove-field', 'commands',
 ];
 
@@ -547,6 +558,24 @@ export async function run(argv) {
 			case 'relations':
 				warnIfStale(ws.root);
 				process.exit(relationsCommand(ws, rest));
+			case 'relocate': {
+				warnIfStale(ws.root);
+				const store = new Store(ws);
+				const target = rest.find((a) => !a.startsWith('--'));
+				if (!target) throw new Error('dt relocate needs a target: dreamteamer relocate <collection> | <collection>/<id> [--dry-run]');
+				// a collection, or one record of it — the either-shape every other target has
+				const asCollection = canonicalCollection(store.descriptors, target);
+				const { collection, id } = asCollection ? { collection: asCollection, id: null } : splitRef(store.descriptors, target);
+				const out = store.relocate(collection, { only: id ? [id] : null, dryRun: rest.includes('--dry-run'), toRoot: rest.includes('--to-root') });
+				if (rest.includes('--json')) { emit(JSON.stringify(out, null, 2)); process.exit(out.problems.length ? 1 : 0); }
+				const rel = (p) => path.relative(ws.root, p);
+				for (const m of out.moves) console.log(`${out.applied ? '✔' : '→'} ${collection}/${m.id}  ${rel(m.from)} → ${rel(m.to)}`);
+				for (const p of out.problems) console.error(`✖ ${p}`);
+				if (!out.moves.length && !out.problems.length) console.log(`nothing to relocate — every ${collection} record is where its descriptor puts it`);
+				else if (!out.applied && !out.problems.length) console.log(`${out.moves.length} move(s) planned (dry run) — nothing was moved`);
+				else if (out.applied) console.log(`${out.moves.length} record(s) relocated — ids and references unchanged; \`dreamteamer commit ${collection}\` publishes the moves`);
+				process.exit(out.problems.length ? 1 : 0);
+			}
 			case 'resolve':
 				process.exit(resolveVariables(ws, rest));
 			default:

package/src/commit.js

@@ -329,6 +329,13 @@ function scopeByRepo(descriptors, only) {
 		const repo = d.storage.repo ?? '.';
 		if (!byRepo.has(repo)) byRepo.set(repo, []);
 		byRepo.get(repo).push(p);
+		// A collection stored UNDER another keeps most of its files inside the parent's folder, so
+		// scoping `git status` to its own path alone would sample only the fallback root and report
+		// the rest as "nothing pending" — the one report that looks like success. The parent's path
+		// joins the pathspec; pathToRecord then attributes each file to the collection it belongs to,
+		// and the row filter in commitPlan keeps the parent's own records out of a scoped commit.
+		const parent = d.storage.under && descriptors.get(d.storage.under.collection);
+		if (parent?.storage?.path && !byRepo.get(repo).includes(parent.storage.path)) byRepo.get(repo).push(parent.storage.path);
 	}
 	return byRepo;
 }

package/src/compile.js

@@ -10,6 +10,8 @@ import addFormats from 'ajv-formats';
 import { load, dump } from './yaml.js';
 import { slug } from './template.js';
 import { walk, patternRe } from './records.js';
+import { refTargetsOf } from './ref.js';
+import { subpathProblem, placedRecords } from './placement.js';
 import { unknownOperators } from './filter.js';
 import {
 	normalizeNamespaces, namespaceProblems, unqualifiedProblems, defaultStoragePath, storageOverlaps,
@@ -20,7 +22,7 @@ import { runHarnessAdapters, renderContributions, BEGIN, END, INSTRUCTIONS_BEGIN
 import { ensureEditorRecommendation, ensureEnvExample } from './workspace.js';
 import { satisfies } from './semver.js';
 import { parseEnvValues } from './env-vars.js';
-import { DERIVED_KINDS, readManifest, runtimeDir, engineId, engineVersion } from './runtime.js';
+import { DERIVED_KINDS, readManifest, runtimeDir, engineId, engineVersion, loadDescriptors as loadCompiledDescriptors } from './runtime.js';
 import { excludedFromKind, disablesPackage, isPackageEntry } from './extensions.js';
 export { engineId, engineVersion, readManifest };
 
@@ -381,6 +383,101 @@ function stampMirror(byName, ctx, ownerName, field, prop, holder, mirrorName, ta
 	t.schema.properties = { ...t.schema.properties, [mirrorName]: generated };
 }
 
+/**
+ * `storage.under` — RELATIONSHIP-BASED STORAGE, validated and derived (see src/placement.js for the
+ * contract the record layer holds). Authored as `{ field, path }` on the CHILD; compiled with the
+ * parent `collection` stamped on, read off the field's `x-reference`, so Store, check and events
+ * never open a schema to find the parent.
+ *
+ * Authored on the child rather than on the parent's inverse field on purpose: the parent's side of
+ * the relation is a GENERATED mirror (or absent — no inverse is required), and `storage` is the
+ * block that already answers "where do THIS collection's records live". One authored spelling, one
+ * compiled spelling, no second copy.
+ *
+ * Every refusal below is a shape the record layer could not make safe at runtime: a list owner has
+ * no single folder, a file-shape parent has no folder at all, an opaque or folder-shape child needs
+ * code the store does not carry yet, a second level of nesting has no reader, and two children on
+ * one path would index each other's files. Compile is where a descriptor is read, so compile says no.
+ */
+function resolvePlacement(byName) {
+	const claims = new Map(); // parent collection -> [{ path, name }]
+	for (const [name, d] of byName) {
+		const under = d.storage?.under;
+		if (under === undefined) continue;
+		const where = `collection "${name}": storage.under`;
+		if (!under || typeof under !== 'object' || Array.isArray(under)) fail(`${where} must be an object { field: <reference field>, path: <folder inside the parent record> }`);
+		const unknown = Object.keys(under).filter((k) => k !== 'field' && k !== 'path');
+		if (unknown.length) fail(`${where} has unknown key(s) ${unknown.join(', ')} — it takes \`field\` and \`path\`, nothing else`);
+		if (typeof under.field !== 'string' || !under.field) fail(`${where}.field must name the scalar reference field that holds the parent`);
+		const bad = subpathProblem(under.path);
+		if (bad) fail(`${where}.path ${bad}`);
+		// the CHILD's own shape first: an opaque collection has no authored fields at all (compile
+		// replaces its schema with the derived ones), so judged later this would read as "no such field"
+		if ((d.storage.codec ?? 'md') === 'file') fail(`${where}: this collection is codec: file — an opaque record is not placed under a parent yet; keep it in its own folder`);
+		if ((d.storage.shape ?? 'file') === 'folder') fail(`${where}: this collection is shape: folder — a folder record is not placed under a parent yet; keep it in its own folder`);
+		const prop = d.schema?.properties?.[under.field];
+		if (!prop || typeof prop !== 'object') fail(`${where}.field "${under.field}" — no such field in ${name}'s schema`);
+		if (prop.type === 'array' || prop.items) fail(`${where}.field "${under.field}" is a list — a record lives in ONE place, so its owner is a scalar reference`);
+		const targets = refTargetsOf(prop);
+		if (!targets) fail(`${where}.field "${under.field}" is not a reference — the owner field needs \`x-reference: <parent collection>\``);
+		if (targets === '*' || targets.length !== 1) fail(`${where}.field "${under.field}" must reference exactly one collection — a record can live under one kind of parent`);
+		const parentName = targets[0];
+		const parent = byName.get(parentName);
+		if (!parent) fail(`${where}: parent collection "${parentName}" is not installed — a record cannot live inside a folder nothing provides`);
+		// nesting before shape: a placed collection is file-shape by the rule two lines up, so judged
+		// the other way round every nesting attempt would be told to make its parent a folder
+		if (parent.storage?.under !== undefined) fail(`${where}: "${parentName}" is itself stored under another collection — one level is supported; a placed collection cannot be a parent`);
+		if ((parent.storage?.shape ?? 'file') !== 'folder') fail(`${where}: "${parentName}" is not shape: folder — a record can only live INSIDE a parent that is a folder (storage: { shape: folder, entry: <file> } on ${parentName})`);
+		if ((parent.storage?.repo ?? '.') !== (d.storage?.repo ?? '.')) fail(`${where}: "${parentName}" lives in another git repo (storage.repo) — a record and the folder it sits in must share one`);
+		const entry = parent.storage.entry;
+		if (entry && under.path.split('/')[0] === entry) fail(`${where}.path "${under.path}" collides with ${parentName}'s entry file "${entry}" — pick a folder name`);
+		const siblings = claims.get(parentName) ?? [];
+		for (const s of siblings) {
+			if (s.path === under.path || s.path.startsWith(under.path + '/') || under.path.startsWith(s.path + '/')) {
+				fail(`collections "${s.name}" and "${name}" both store records under ${parentName}/<id>/${s.path === under.path ? s.path : `${s.path} · ${under.path}`} — one would index the other's files; give each its own folder`);
+			}
+		}
+		claims.set(parentName, [...siblings, { path: under.path, name }]);
+		d.storage.under = { field: under.field, path: under.path, collection: parentName };
+	}
+}
+
+/**
+ * A `storage.under` that is REMOVED or CHANGED while records still sit under the old declaration is
+ * refused (R3). The compiled descriptor is the only thing that knows where those records are: the
+ * moment it is rewritten, listing, check and relocate all read the new layout, the old child folders
+ * fall out of every walk, and a workspace with records on disk reports ✔ 0 violations over fewer
+ * records than it holds — the quietest data loss there is. So the runtime about to be replaced is
+ * read first, and a transition with records in the way names the two-step that is safe:
+ * `relocate --to-root` under the OLD declaration (ids unchanged), then compile, then `relocate`.
+ * Adding `under` to a conventional collection moves nothing out of sight and is not refused.
+ */
+function refusePlacementTransitions(root, byName) {
+	const previous = loadCompiledDescriptors(root);
+	if (!previous) return;
+	for (const [name, d] of byName) {
+		const prev = previous.get(name);
+		const was = prev?.storage?.under;
+		if (!was?.collection || !was.path) continue;
+		const now = d.storage?.under ?? null;
+		const parent = previous.get(was.collection);
+		if (!parent?.storage?.path || !prev.storage?.path) continue;
+		// The EFFECTIVE root, not only the annotation: the parent collection's own `storage.path` is
+		// part of where every child record is, so moving the parent's folder in its descriptor strands
+		// the children exactly as dropping `under` does (R3b).
+		const newParentPath = now ? byName.get(now.collection)?.storage?.path : null;
+		const same = now && now.collection === was.collection && now.path === was.path && newParentPath === parent.storage.path;
+		if (same) continue;
+		let n = 0;
+		for (const r of placedRecords(prev, path.join(root, prev.storage.path), path.join(root, parent.storage.path))) if (r.parentId !== null) n++;
+		if (!n) continue;
+		const what = !now ? 'storage.under was removed'
+			: now.collection !== was.collection || now.path !== was.path ? `storage.under changed (${was.path} → ${now.path})`
+			: `${was.collection}'s storage.path changed (${parent.storage.path} → ${newParentPath})`;
+		fail(`collection "${name}": ${what}, but ${n} ${name} record(s) still sit inside ${was.collection} folders (${parent.storage.path}/<id>/${was.path}/) — compiling would stop every reader seeing them. First move them out under the CURRENT declaration: dreamteamer relocate ${name} --to-root (to ${prev.storage.path}, ids unchanged), then compile${now ? `, then dreamteamer relocate ${name} to place them again` : ''}.`);
+	}
+}
+
 /** The source kinds the compiler itself stages. An installed extension may add more
  *  (`sourceKinds`, src/extensions.js) — every enumeration below reads `kindsOf(ws)`, never this alone. */
 export const KINDS = ['collections', 'skills', 'agents', 'commands', 'command-bindings', 'ui-views', 'collection-templates'];
@@ -1386,6 +1483,11 @@ export function compile(ws) {
 		moduleDeps, wsModuleName,
 		moduleOf: (n) => collOwner.get(n),
 	});
+	// ---- placement: a collection stored UNDER another ---------------------------------
+	// Here for the same reason relations are: `storage.under` names a field of this collection AND
+	// the shape of ANOTHER collection, so it can only be judged once every descriptor exists.
+	resolvePlacement(new Map([...mergedGroups].map(([n, g]) => [n, g.merged])));
+	refusePlacementTransitions(root, new Map([...mergedGroups].map(([n, g]) => [n, g.merged])));
 
 	// ---- resolved labels, then bytes -------------------------------------------------
 	// A second loop rather than a tail of the first: generated mirror fields do not exist until the

package/src/events.js

@@ -4,6 +4,7 @@
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { idFromRecordPath } from './records.js';
+import { placedChildAt } from './placement.js';
 
 /** Record events between two points, across EVERY repo that holds records. `from` is a sha or a
  *  date — a sha is meaningless in another repo, so it is resolved to its commit DATE and each
@@ -107,8 +108,12 @@ export function pathToRecord(descriptors, relPath) {
 	const rest = relPath.slice(best.storage.path.length + 1);
 	if (best.storage.shape === 'folder') {
 		const entry = best.storage.entry ?? 'SKILL.md';
-		if (!rest.endsWith('/' + entry)) return null;
-		return { collection: best.name, id: rest.slice(0, -(entry.length + 1)) };
+		// `<id>/<entry>` is the parent's own record; anything deeper may be a record of a collection
+		// stored UNDER it (`<id>/meetings/2026/10/kickoff.meeting.md`), which the longest-prefix match
+		// above can never see because its own storage.path is elsewhere. One place decides, so a
+		// commit, an event and a surface agree on whose record a path is.
+		if (rest.endsWith('/' + entry) && rest.indexOf('/') === rest.length - entry.length - 1) return { collection: best.name, id: rest.slice(0, -(entry.length + 1)) };
+		return placedChildAt(descriptors, best.name, rest);
 	}
 	const id = idFromRecordPath(best, rest);
 	return id === null ? null : { collection: best.name, id };

package/src/extensions.js

@@ -58,8 +58,8 @@ export function declaredExtensions(ws) {
 
 /**
  * Does a `dreamteamer.disable` list switch off the WHOLE package `name`? An entry names a package by
- * its full name (`@dreamteamer/workflows`, `probe-kit`) or by its module id — the name with the npm
- * scope stripped (`workflows`), which is what every engine message calls a module. Anything else with
+ * its full name (`@scope/kit`, `probe-kit`) or by its module id — the name with the npm
+ * scope stripped (`kit`), which is what every engine message calls a module. Anything else with
  * a slash is `<module>/<entity>`, one entity of a module, and never the package.
  *
  * ⚠ The scoped full name used to be read as `<module>/<entity>` because it contains a slash, and the

package/src/harnesses.js

@@ -19,8 +19,8 @@ export const KNOWN_HARNESSES = ['claude-code', 'codex', 'pi', 'gemini-cli', 'cur
 export const STAMP = '<!-- generated by dreamteamer compile — do not edit; source of truth lives in modules/<module>/<kind>/ -->';
 
 // ⚠ THE VALUES ARE A CONTRACT, not an implementation detail: every managed root file on every disk
-// already carries these two exact strings, and a tool that merges branches (@dreamteamer/workflows'
-// `land`) classifies a conflict by asking whether its hunks lie between them. Changing a byte orphans
+// already carries these two exact strings, and a tool that merges branches (a worktree
+// extension's `land`) classifies a conflict by asking whether its hunks lie between them. Changing a byte orphans
 // every block ever written and silently reclassifies a generated conflict as the operator's own prose.
 export const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
 export const END = '<!-- dreamteamer:end -->';