dreamteamer 0.25.1 → 0.27.0

package/bin/dreamteamer.js

@@ -12,6 +12,34 @@ import { pathToFileURL, fileURLToPath } from 'node:url';
 const MODULE_SEGMENTS = new Set(['node_modules', 'git_modules', 'modules']);
 
 const self = fileURLToPath(import.meta.url);
+
+// `--vault <path>` — operate on ANOTHER workspace without leaving this one. Consumed HERE, before
+// anything else resolves, because every verb downstream answers "which workspace am I in" from
+// process.cwd(): changing the directory once IS the whole implementation, and it also points the
+// dev-clone walk below at the TARGET's git_modules rather than the caller's.
+//
+// ⚠ It is spliced out of process.argv, not just out of the slice handed to run(): the dev-clone
+// branch re-enters this same file, and a flag left in place would be applied a SECOND time — the
+// path resolving against the already-changed directory, i.e. at the wrong workspace, silently.
+//
+// The path resolves against the INVOKING directory, which is where the caller typed it. Every other
+// relative path in the command then resolves against the target — the same rule a `cd` would give.
+const vaultAt = process.argv.indexOf('--vault', 2);
+if (vaultAt !== -1) {
+	const target = process.argv[vaultAt + 1];
+	if (!target || target.startsWith('-')) {
+		console.error('\u2716 --vault needs a path to a workspace, e.g. `--vault ../another-workspace`');
+		process.exit(1);
+	}
+	const resolved = path.resolve(process.cwd(), target);
+	if (!fs.existsSync(resolved)) {
+		console.error(`\u2716 --vault ${target} \u2014 no such directory (resolved to ${resolved})`);
+		process.exit(1);
+	}
+	process.chdir(resolved);
+	process.argv.splice(vaultAt, 2);
+}
+
 const devBin = findDevClone(process.cwd());
 // `realpath`, NOT `path.resolve`: resolve is pure string math and does not follow symlinks, so a
 // workspace whose git_modules/dreamteamer is a SYMLINK to the engine it is already running (the

package/collections/collections.collection.yaml

@@ -172,10 +172,19 @@ schema:
     group:
       type: string
       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.
+        The collection's PARTITION — which family of nouns it belongs to, authored freely (`crm`,
+        `finance`, `family`, `content`…) and set with `dt set collections/<c> group=<g>`. One value
+        is reserved and load-bearing: `group: system` says the collection is the workspace's own
+        MACHINERY rather than one of its domain nouns, so it is left out of the generated block's
+        domain listing, named on the system-collections line instead, and drawn on a surface's
+        schema surface rather than in the record tree. ⚠ It does NOT change where records live or
+        whether they can be written — that is `storage.base`, asked separately, and `repos` is the
+        collection where the two answers split: `group: system` and workspace-stored records the
+        operator edits by hand. Nearly removed on 2026-08-11, when the nav stopped grouping by it in
+        favour of `owner` (a module, which has a title of its own) and nothing else read it; kept
+        then so the change would be a code revert rather than a data migration, and because a
+        workspace may want a partition that deliberately DIFFERS from its modules. That is what it
+        became.
 order: 10
 list_fields: [name, last-modified]
 icon: schema

package/collections/repos.collection.yaml

@@ -52,4 +52,10 @@ schema:
 order: 145
 list_fields: [name, identity, ref, url]
 icon: source
+# MACHINERY, NOT A DOMAIN NOUN, and `group: system` is the whole statement of it. `repos` is the
+# engine's only collection whose records live in `data/`, which used to make every workspace render
+# a **System** module group with one collection under it — the group the block's own renderer says
+# should not exist (harnesses.js). Being in the `system` partition folds it out of the block's
+# domain listing and onto the schema surface instead. The records stay real, writable and committed;
+# only the presentation changes.
 group: system

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dreamteamer",
-	"version": "0.25.1",
+	"version": "0.27.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

@@ -71,6 +71,22 @@ on: **validation is hard** (unknown fields included; an invalid write is rejecte
 with no partial state), and **a write does not commit** — `dt commit` publishes, scoped
 (`references/records.md`).
 
+## one session, several workspaces
+
+a harness can be pointed at more than one workspace at a time. when it is, it loads skills, commands
+and agents from ALL of them and the workspace INSTRUCTIONS from the PRIMARY one only — measured:
+zero instruction blocks from the others across every session on record. so the schema in context is
+the primary workspace's, whoever shipped the skill you are reading.
+
+- **start a session in the workspace it is about.** it is the only thing that loads that workspace's
+  instructions, and it settles name collisions in its favour.
+- **to touch another workspace from here, `--vault <path>` — not `cd`.** the flag resolves the
+  target's schema, validates and commits there, and leaves the working directory alone; a `cd`
+  outlives the command.
+- **every record write prints the workspace it landed in** — `✔ <workspace> · <path>`. a write to
+  the wrong workspace passes validation, because the collection usually exists in both, so that line
+  is what distinguishes them.
+
 ## two acts, one map
 
 Act one is **working with data** — the records themselves. Act two is **modeling the workspace**

package/src/cli.js

@@ -35,6 +35,10 @@ const QUIET = ['ignore', 'pipe', 'ignore'];
 
 export const USAGE = `usage: dreamteamer <verb> [<target>] [flags]
 
+  --vault <path>   run against another workspace. The path resolves from the directory you typed it
+                   in; every other path in the command resolves inside the target. The working
+                   directory is unchanged.
+
 record verbs (hard validation — invalid writes are rejected before disk).
 A <target> is either a collection name or a <collection>/<id> reference; the reference splits at
 the longest DECLARED collection prefix, so finance/transactions/2026/03/coffee is ONE argument:
@@ -269,6 +273,16 @@ const FIELD_VERBS = ['add-field', 'set-field', 'rm-field', 'rename-field'];
 // misspelling — `dt commit --dryrun` COMMITTED, because `rest.includes('--dry-run')` is false for a
 // flag nobody typed correctly. The record/system/field verbs are checked in `collections-cli.js`,
 // beside the parser they share; these nine have no shared parser, so the table is here.
+// Flags consumed BEFORE dispatch, in bin/dreamteamer.js, so no verb ever sees them. They are real
+// and honoured; they are simply honoured earlier than VERB_FLAGS/WORKSPACE_FLAGS can express.
+//
+// ⚠ Listing one here EXEMPTS it from the "documented flags are accepted by some verb" guard, which
+// exists because 0.19.0 shipped a flag that was documented and silently swallowed. The exemption is
+// only safe while the behaviour is pinned somewhere else: `--vault` is covered end-to-end in
+// test/integration/cross-workspace-targeting.test.js. A global flag with no such file is the exact
+// defect that guard was written to catch \u2014 add the coverage, not the entry.
+export const GLOBAL_FLAGS = ['vault'];
+
 export const WORKSPACE_FLAGS = {
 	init: ['name', 'data-path', 'harnesses', 'workspace-module'], update: [],
 	install: ['clone', 'dry-run', 'json', 'link-env', 'all', 'hook', 'print-adapters'],

package/src/collections-cli.js

@@ -118,6 +118,14 @@ export function collectionCommand(ws, collection, verb, args) {
 
 	const d = store.descriptor(collection);
 
+	// Every record write says WHICH workspace it landed in. `--vault` is OPTIONAL and a bare command
+	// resolves from the working directory, so the one thing the flag cannot do is tell you when you
+	// forgot it \u2014 this can, for the price of one word, with no state and nothing refused. A write
+	// aimed at one workspace and landed in another becomes visible on the very next line of output
+	// instead of never: on a machine holding several workspaces most collection NAMES are shared while
+	// their fields are not, so the misplaced write succeeds and reports success.
+	const at = ws.pkg?.name ? `${ws.pkg.name} \u00b7 ` : '';
+
 	switch (verb) {
 		case 'list': {
 			const { rows, narrowed } = narrowRows(store, d, collection, flags);
@@ -167,7 +175,7 @@ export function collectionCommand(ws, collection, verb, args) {
 				const id = need(pos, 0, 'id');
 				if (!flags.from) throw new Error(`"${collection}" is a \`codec: file\` collection — pass --from <path> with the file to import`);
 				const { id: written, file } = store.addFile(collection, id, flags.from, { force: !!flags.force });
-				flags.json ? emit(JSON.stringify({ id: written, path: rel(ws.root, file) })) : console.log(`✔ ${rel(ws.root, file)}`);
+				flags.json ? emit(JSON.stringify({ id: written, path: rel(ws.root, file) })) : console.log(`✔ ${at}${rel(ws.root, file)}`);
 				return 0;
 			}
 			if (flags.from) throw new Error(`--from imports a file as a record, and "${collection}" is not a \`codec: file\` collection`);
@@ -175,7 +183,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			const { id, file, idFallback } = store.add(collection, fields, { id: flags.id });
 			flags.json
 				? emit(JSON.stringify({ id, path: rel(ws.root, file), ...(idFallback ? { idFallback } : {}) }))
-				: console.log(`✔ ${rel(ws.root, file)}`);
+				: console.log(`✔ ${at}${rel(ws.root, file)}`);
 			// ⚠ SAY IT, EVERY TIME. The id was derived from a hash because the value it is generated
 			// from carries no a-z0-9 — the write succeeded and the record is fine, but the id is
 			// unreadable and unguessable, and nobody finds that out until they try to type it. By
@@ -194,7 +202,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			Object.assign(changes, coerceArrays(d, stripMeta(flags)));
 			if (!Object.keys(changes).length) throw new Error('nothing to set — pass key=value pairs or --key value flags');
 			store.set(collection, id, changes);
-			flags.json ? emit(JSON.stringify({ id })) : console.log('✔ updated');
+			flags.json ? emit(JSON.stringify({ id })) : console.log(`✔ ${at}updated`);
 			return 0;
 		}
 		// Manual ordering. ONE record is written per move — that is the entire feature; a dense
@@ -228,20 +236,20 @@ export function collectionCommand(ws, collection, verb, args) {
 
 			const id = need(pos, 0, 'id');
 			store.set(collection, id, { [field]: placementKey(rows, id, flags, collection) });
-			flags.json ? emit(JSON.stringify({ id })) : console.log('✔ moved');
+			flags.json ? emit(JSON.stringify({ id })) : console.log(`✔ ${at}moved`);
 			return 0;
 		}
 		case 'rm': {
 			const id = need(pos, 0, 'id');
 			if (flags['dry-run']) return dryRunPlan(`rm ${collection}/${id}`, { records: store.ids(collection).has(id) ? 1 : 0, refs: store.findInboundRefs(`${collection}/${id}`).length });
 			const { inboundIgnored } = store.rm(collection, id, { force: !!flags.force });
-			flags.json ? emit(JSON.stringify({ id, removed: true, inboundIgnored })) : console.log(`✔ removed${inboundIgnored ? ` (${inboundIgnored} inbound reference(s) left dangling — run \`dreamteamer check\`)` : ''}`);
+			flags.json ? emit(JSON.stringify({ id, removed: true, inboundIgnored })) : console.log(`✔ ${at}removed${inboundIgnored ? ` (${inboundIgnored} inbound reference(s) left dangling — run \`dreamteamer check\`)` : ''}`);
 			return 0;
 		}
 		case 'rename': {
 			const out = store.rename(collection, need(pos, 0, 'old id'), need(pos, 1, 'new id'));
 			if (flags.json) { emit(JSON.stringify(out)); return 0; }
-			console.log(`✔ renamed ${collection}/${need(pos, 0, 'old id')} → ${collection}/${out.id}`);
+			console.log(`✔ ${at}renamed ${collection}/${need(pos, 0, 'old id')} → ${collection}/${out.id}`);
 			if (out.touched) console.log(`✔ rewrote ${out.rewrites} inbound reference(s) across ${out.touched} file(s)`);
 			return 0;
 		}

package/src/harnesses.js

@@ -142,7 +142,16 @@ const NOTEBOOK_PLANS = [
 function notebooklmBlock(entries, version) {
 	const index = buildCollectionsIndex(entries);
 	const modules = buildModulesIndex(entries);
-	const data = index.filter((c) => !c.system);
+	// ⚠ `generated`, NOT `systemGroup` — the same split the orientation block's system line makes,
+	// asked for the opposite reason. There the question is presentational ("group it out of the
+	// domain listing"); HERE it is a STORAGE question, because every number and name below has to
+	// describe what `dt export notebooklm` will actually ship, and the export ships by storage
+	// (`storage.base !== 'runtime'` — export-notebooklm.js). Reading the partition here made this file
+	// say "exports 1 collections" and list only `notes` for a workspace whose export shipped
+	// `repos.md` as a second source and headed a `## module: System` group for it in the schema map
+	// — so the persona generated from this line would not know about a source it had been given.
+	// The count and the export are pinned to each other by a test (notebooklm-harness.test.js).
+	const data = index.filter((c) => !c.generated);
 	const withheldCollections = data.filter((c) => c.sensitive).map((c) => c.name);
 	const withheldFields = data.flatMap((c) => c.sensitiveFields.map((f) => `${c.name}.${f}`));
 	const exported = data.filter((c) => !c.sensitive);
@@ -245,10 +254,16 @@ function buildCollectionsIndex(entries) {
 		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { /* unparseable descriptor */ }
 		index.push({
 			name: d.name ?? m[1],
-			// DERIVED, never a hardcoded name list: `runtime` is exactly the schema-ops set
-			// (collections, commands, skills, agents, ui-views, command-bindings,
-			// collection-templates, modules) and stays right in a workspace shipping others.
-			system: d.storage?.base === 'runtime',
+			// ⚠ TWO QUESTIONS, KEPT SEPARATE. `systemGroup` answers "is this machinery, group it out
+			// of the domain listing"; `generated` answers "is this build output the hand-edit warning
+			// is about" — they agreed until `repos`, machinery whose records are still real files
+			// under `data/`. The partition is AUTHORED (`group: system` on the descriptor, ten core
+			// collections carry it), never derived from storage: a workspace collection may be its
+			// own apparatus, and a runtime-stored one may not be. An unparseable descriptor (`d = {}`
+			// from the catch above) carries neither key and answers false to both, which leaves it in
+			// the domain listing — the visible failure rather than the silent one.
+			systemGroup: d.group === 'system',
+			generated: d.storage?.base === 'runtime',
 			description: flat(d.description),
 			useWhen: flat(d.use_when),
 			module: d.module ?? '',
@@ -354,10 +369,10 @@ function collectionsSection(index, modules, workspaceModule) {
 		'collection\'s `write:` line names only what the store REFUSES — required fields that have no',
 		'default (a defaulted one is filled in for you), closed enums with their size, one example.',
 	];
-	const data = index.filter((c) => !c.system);
+	const data = index.filter((c) => !c.systemGroup);
 	const isWs = (m) => m.path === `modules/${workspaceModule}/`;
 	const groups = modules
-		.filter((m) => { const own = index.filter((c) => c.module === m.id); return own.some((c) => !c.system) || (!own.length && (m.skills.length || m.commands.length || m.bin.length || m.proofs.length)); })
+		.filter((m) => { const own = index.filter((c) => c.module === m.id); return own.some((c) => !c.systemGroup) || (!own.length && (m.skills.length || m.commands.length || m.bin.length || m.proofs.length)); })
 		.sort((a, b) => (isWs(b) - isWs(a)) || a.title.localeCompare(b.title));
 	for (const m of groups) {
 		const where = [`\`${m.id}\``, m.path ? m.path.replace(/\/$/, '') : 'the workspace root', ...(m.namespaces.length ? [`namespaces: ${m.namespaces.join(' · ')}`] : [])];
@@ -370,13 +385,19 @@ function collectionsSection(index, modules, workspaceModule) {
 			if (c.write) lines.push(`    write: ${c.write}`);
 		}
 	}
-	const system = index.filter((c) => c.system).map((c) => c.name);
+	const sys = index.filter((c) => c.systemGroup);
+	const system = sys.filter((c) => c.generated).map((c) => c.name);
+	const kept = sys.filter((c) => !c.generated).map((c) => c.name);
 	// ⚠ THIS LINE IS THE FIRST THING A SESSION READS about the system collections, and until 0.19.0
 	// it said "schema-ops only", which named an internal module and a grammar that no longer exists.
 	// It now names the VERBS and the one policy difference, because an agent that knows the verbs
-	// exist still has to be told that these commit and records do not.
-	if (system.length) {
-		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`set-field\`/\`rm-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes). Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}`);
+	// exist still has to be told that these commit and records do not. And it is PARTITIONED on
+	// `generated`, not `systemGroup`: the partition only answers the grouping question, so a system
+	// collection whose records are real files (`repos`) gets its own trailing clause instead of being
+	// told "it is build output" — a sentence that was false of it and is false of the next data-backed
+	// system collection too, since the split is derived rather than naming one.
+	if (sys.length) {
+		lines.push('', `- system collections — the SAME verbs (add · set · rm · rename · list · get), plus \`dt add-field\`/\`set-field\`/\`rm-field\`/\`rename-field <collection>\`. A system write COMMITS ITSELF, in the repo holding the source; a record write does not (\`dt commit\` publishes).${system.length ? ` Never hand-edit \`.dreamteamer/\` — it is build output: ${system.join(' · ')}.` : ''}${kept.length ? ` Machinery whose records are real files you edit like any other: ${kept.join(' · ')}` : ''}`);
 	}
 	return lines;
 }

package/src/presentation.js

@@ -82,6 +82,10 @@ function collectionRow(d) {
 	// it — the extension reads the presentation contract, not raw descriptors.
 	if (typeof d.sort_field === 'string') meta.sort_field = d.sort_field;
 
+	// The collection's PARTITION, and the reserved value `system` is how a surface knows to draw this
+	// collection as the workspace's machinery rather than in the record tree. It is carried in `meta`
+	// beside the other presentation keys because that is the question it answers; the top-level
+	// `system` below answers a different one and they must never be folded together.
 	if (typeof d.group === 'string') meta.group = d.group;
 	if (typeof d.description === 'string' && d.description.length > 0) meta.description = d.description;
 	// ⚠ `system` IS NOT `readonly`, AND SAYING SO COST A RELEASE. Until 0.19.0 the two were the
@@ -107,10 +111,25 @@ function collectionRow(d) {
 	//      already answers with its own sentence naming the fix, which is the contract the schema
 	//      surfaces are built on.
 	//
-	// `system` STAYS and is unchanged: the CLI and REST dispatch key on it, and it is what puts a
-	// kind in the schema surface rather than the data one. A consumer that disables editing must
-	// key on `meta.readonly` (per field, as `id`, `last-modified` and relation mirrors do) or on
-	// the verb it is about to offer — never on `system`.
+	// `system` STAYS and is unchanged: the CLI and REST dispatch key on it. A consumer that disables
+	// editing must key on `meta.readonly` (per field, as `id`, `last-modified` and relation mirrors
+	// do) or on the verb it is about to offer — never on `system`.
+	//
+	// ⚠ AND `system` IS NO LONGER WHAT PUTS A KIND ON THE SCHEMA SURFACE — that clause stood here
+	// until `repos` and belongs to `meta.group` now. TWO QUESTIONS, KEPT SEPARATE, exactly as
+	// `buildCollectionsIndex` in src/harnesses.js keeps them:
+	//
+	//   `system`       decides HOW A WRITE IS PERFORMED. Is this collection's storage the compiled
+	//                  runtime? The CLI and the REST layer dispatch on it, and a surface that gets
+	//                  it wrong answers 400 to a write the store would have accepted.
+	//   `meta.group`   decides WHERE THE COLLECTION IS DRAWN. Its reserved value `system` says this
+	//                  is the workspace's machinery rather than one of its domain nouns, and folds
+	//                  the collection out of the record tree and onto the schema surface.
+	//
+	// The two agreed for every collection until `repos` — machinery whose records are ordinary,
+	// hand-edited files under `data/` — and it is why they must never be collapsed into one: a
+	// surface routing a `repos` write by the partition sends it to the system write path, whose
+	// entity ops know no such kind, and the write dies as a 400. Measured.
 	const system = d.storage?.base === 'runtime';
 	return { collection: d.name, meta, system };
 }

package/src/schema-ops.js

@@ -755,6 +755,9 @@ const COLLECTION_SETTABLE = {
 	title: (v) => String(v),
 	title_template: (v) => String(v),
 	icon: (v) => String(v),
+	// The collection's partition. `group=system` is the reserved value: it moves the collection out
+	// of the block's domain listing and onto a surface's schema surface, and changes nothing about
+	// where its records live or whether they can be written.
 	group: (v) => String(v),
 	sort_field: (v) => String(v),
 	order: (v) => {