dreamteamer 0.9.1 → 0.12.0

package/src/cli.js

@@ -1,5 +1,14 @@
-// dreamteamer CLI — noun-verb grammar over the same primitives every surface uses.
-// this phase ships: compile, check, status. collection verbs land next.
+// dreamteamer CLI — VERB-FIRST: `dt <verb> [<target>]`, over the same primitives every surface uses.
+//
+// The verb set is CLOSED. `run()` switches on it and anything unrecognised is an error, because the
+// predecessor grammar (`dt <collection> <verb>`) made the FALLBACK the collection path: a typo
+// dispatched to a collection lookup and answered "unknown collection", which is a true sentence
+// about the wrong thing. It also meant no verb could ever be named without a noun in front of it
+// — `dt resolve '<string>'` had nowhere to live — and a namespaced reference had to be typed as two
+// arguments that only the caller knew belonged together.
+//
+// This file TRANSLATES; it does not implement. Every record and schema verb lands on
+// `collectionCommand(ws, collection, verb, args)`, whose signature is unchanged.
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
@@ -11,6 +20,8 @@ import { init, install, installClone, update, listRepos } from './init.js';
 import { deriveEvents } from './events.js';
 import { commitPending } from './commit.js';
 import { Store } from './store.js';
+import { splitRef } from './ref.js';
+import { parseEnvValues, renderTemplate } from './env-vars.js';
 
 // git calls whose failure we CATCH must not print git's own error: execFileSync forwards the
 // child's stderr to ours unless told otherwise, so a handled "not a git repository" still
@@ -18,9 +29,64 @@ import { Store } from './store.js';
 const QUIET = ['ignore', 'pipe', 'ignore'];
 
 
-const USAGE = `usage: dreamteamer <command> | dreamteamer <collection> <verb> …
+const USAGE = `usage: dreamteamer <verb> [<target>] [flags]
 
-commands:
+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:
+  list   <collection> [--filter k=v] [--where <json>] [--sort [-]<field>] [--json]
+                                              (--where takes the studio's operator set, e.g.
+                                               '{"starts":{"_gte":"2026-07-01"}}'; date-times
+                                               sort and compare as instants, across offsets)
+  get    <collection>/<id> [--json]
+  add    <collection> --<field> <value> … [--id <explicit-id>]
+  set    <collection>/<id> <field>=<value> …
+  rm     <collection>/<id> [--force]
+  rename <collection>/<id> <new-id>           (rewrites all inbound refs, ONE commit)
+  move   <collection>/<id> --after|--before <id> | --top | --bottom
+  move   <collection> --init                  (place every record that has no sort value yet)
+  values <collection> <field> [--limit n]     (the vocabulary a field actually uses —
+                                               what a filter/validator offers as choices)
+  history <collection>/<id> [--json]          (git revisions of this record, newest first)
+  diff    <collection>/<id> [--hash <sha>]    (the patch one revision applied; defaults to HEAD)
+  revert  <collection>/<id> --hash <sha>      (restore the content at <sha>, as a NEW commit)
+  commands <collection>[/<id>] [--ids <id>,…] (bound commands + per-record state:
+                                               available / done / not-applicable)
+  ensure  <repos-id> | --all [--json]         (materialize an attached repo's working tree ON
+                                               DEMAND — never at install; --all is the explicit
+                                               opt-in, e.g. before going offline)
+  resolve '<string>' | <collection>/<id> <field>
+                                              (render \${env:NAME} · \${workspaceFolder} ·
+                                               \${userHome} — the ONLY substitution point; a
+                                               record keeps the template verbatim. An array
+                                               field prints one item per line)
+
+schema verbs (write SOURCES through a compile gate, never the runtime — a different act, so a
+different word in front of it):
+  schema add-collection --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>/)
+  schema rm-collection <name> [--force]       (--force required if it still has records)
+  schema rename-collection <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
+  schema add-field    <collection> --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
+                                   enum tags <collection> — a date-time may be written as
+                                   "2026-07-28 12:00" or "2026-07-28T12:00"; the local offset is
+                                   stamped on for you (2026-07-28T12:00:00+03:00)
+  schema update-field <collection> --name <field> --type <type> [--options a,b] [--default-value v]
+                            [--required true|false] [--description "…"]
+                            (an existing description survives a retype)
+  schema remove-field <collection> --name <field>
+  schema add-view --path </route> --target list --collection collections/<c> --layout <id>
+                            [--id <id>] [k.v=…]
+  schema set-view <id> <key>=<value> …        (dotted keys: options.sort=-date, nav.label=Recent)
+  schema rm-view <id>
+
+workspace verbs:
   init        write the workspace skeleton into the current directory (never compiles)
   --version   print the engine version (works anywhere)
   install     restore git_modules/ from the lockfile map; --clone <url> [name] adds one
@@ -35,51 +101,30 @@ commands:
   commit      publish records already written to disk: samples git status over every
               collection's record dirs, one commit PER REPO, subject composed from the
               status letters. [<collection> …] to scope, [-m <subject>], [--dry-run]
+  help        this text
+`;
 
-collection verbs (hard validation — invalid writes are rejected before disk):
-  <collection> list [--filter k=v] [--where <json>] [--sort [-]<field>] [--json]
-                                              (--where takes the studio's operator set, e.g.
-                                               '{"starts":{"_gte":"2026-07-01"}}'; date-times
-                                               sort and compare as instants, across offsets)
-  <collection> get <id> [--json]
-  <collection> add --<field> <value> … [--id <explicit-id>]
-  <collection> set <id> <field>=<value> …
-  <collection> rm <id> [--force]
-  <collection> rename <old-id> <new-id>       (rewrites all inbound refs, ONE commit)
-  <collection> history <id> [--json]          (git revisions of this record, newest first)
-  <collection> diff <id> [--hash <sha>]       (the patch one revision applied; defaults to HEAD)
-  <collection> revert <id> --hash <sha>       (restore the content at <sha>, as a NEW commit)
+// Record verbs, split by what their <target> means. `move` and `commands` are in NEITHER set: both
+// accept either shape, and which one it is has to be decided against the declared collections.
+const REF_VERBS = new Set(['get', 'set', 'rm', 'rename', 'history', 'diff', 'revert']);
+const COLLECTION_VERBS = new Set(['list', 'add', 'values']);
+const EITHER_VERBS = new Set(['move', 'commands']);
 
-repo attachment (working trees are materialized ON DEMAND, never at install):
-  repos ensure <id> [--json]                  (clone if missing, then print the path; idempotent)
-  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> [--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
-                                   enum tags <collection> — a date-time may be written as
-                                   "2026-07-28 12:00" or "2026-07-28T12:00"; the local offset is
-                                   stamped on for you (2026-07-28T12:00:00+03:00)
-  <collection> update-field --name <field> --type <type> [--options a,b] [--default-value v] [--required true|false]
-                            [--description "…"]   (an existing description survives a retype)
-  <collection> remove-field --name <field>
-  ui-views add --path </route> --target list --collection collections/<c> --layout <id> [--id <id>] [k.v=…]
-  ui-views set <id> <key>=<value> …           (dotted keys: options.sort=-date, nav.label=Recent)
-  ui-views rm <id>
-  commands for <collection>[/<id>] [--ids <id>,…]      (bound commands + per-record state:
-                                                        available / done / not-applicable)
-  <collection> values <field> [--limit n]              (the vocabulary a field actually uses —
-                                                        what a filter/validator offers as choices)
-`;
+// `schema <op>` → the (collection, verb) pair the implementation layer already answers to. The
+// collections are literals: `collections` and `ui-views` are SYSTEM-stored, which is precisely what
+// makes these a separate group in the grammar rather than records like any other.
+const SCHEMA_OPS = {
+	'add-collection': ['collections', 'add'],
+	'rm-collection': ['collections', 'rm'],
+	'rename-collection': ['collections', 'rename'],
+	'add-view': ['ui-views', 'add'],
+	'set-view': ['ui-views', 'set'],
+	'rm-view': ['ui-views', 'rm'],
+};
+// These three name their collection POSITIONALLY (`schema add-field contacts --name phone`) and keep
+// their existing verb spelling on it — the schema group is a prefix here, not a rename.
+const SCHEMA_FIELD_OPS = new Set(['add-field', 'update-field', 'remove-field']);
+const SCHEMA_OP_LIST = [...Object.keys(SCHEMA_OPS), ...SCHEMA_FIELD_OPS].join(' | ');
 
 export function run(argv) {
 	const [cmd, ...rest] = argv;
@@ -96,6 +141,10 @@ export function run(argv) {
 			for (let i = 0; i < rest.length; i++) if (rest[i].startsWith('--')) flags[rest[i].slice(2)] = rest[i + 1];
 			process.exit(init({ flags }));
 		}
+		if (!cmd) {
+			console.log(USAGE);
+			process.exit(0);
+		}
 		const ws = findWorkspace();
 		switch (cmd) {
 			case 'install': {
@@ -202,7 +251,7 @@ export function run(argv) {
 					if (repos.length) {
 						const here = repos.filter((r) => r.present).length;
 						console.log(`repos:    ${here}/${repos.length} materialized`);
-						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path} (dreamteamer repos ensure ${r.id})`);
+						for (const r of repos) if (!r.present) console.log(`  absent: ${r.id} → ${r.path} (dreamteamer ensure ${r.id})`);
 					}
 				} catch { /* no repos descriptor compiled — nothing to report */ }
 				// Uncommitted records are invisible to `dt changes` (it diffs commits), so the
@@ -226,14 +275,25 @@ export function run(argv) {
 			case 'help':
 				console.log(USAGE);
 				process.exit(0);
-			default: {
-				if (!cmd || rest.length === 0) {
-					console.log(USAGE);
-					process.exit(cmd ? 1 : 0);
-				}
+			case 'list': case 'add': case 'values':
+			case 'get': case 'set': case 'rm': case 'rename': case 'history': case 'diff': case 'revert':
+			case 'move': case 'commands':
 				warnIfStale(ws.root);
-				process.exit(collectionCommand(ws, cmd, rest[0], rest.slice(1)));
-			}
+				process.exit(dispatchRecordVerb(ws, cmd, rest));
+			// `repos ensure` lost its noun: the repos collection is still where the declaration lives,
+			// but materializing one is a verb the operator types, not a record write.
+			case 'ensure':
+				warnIfStale(ws.root);
+				process.exit(collectionCommand(ws, 'repos', 'ensure', rest));
+			case 'schema':
+				warnIfStale(ws.root);
+				process.exit(dispatchSchemaVerb(ws, rest));
+			case 'resolve':
+				process.exit(resolveVariables(ws, rest));
+			default:
+				console.error(`✖ unknown verb "${cmd}" — dreamteamer is verb-first since 0.12.0: dt <verb> [<target>]`);
+				console.error(USAGE);
+				process.exit(1);
 		}
 	} catch (e) {
 		console.error(`✖ ${e.message}`);
@@ -241,6 +301,110 @@ export function run(argv) {
 	}
 }
 
+/** Translate `dt <verb> <target> …` into the noun-verb call the implementation layer takes. */
+function dispatchRecordVerb(ws, verb, args) {
+	const [target, ...rest] = args;
+	if (!target) throw new Error(`dt ${verb} needs a target — see \`dreamteamer help\``);
+	// A flag in the target slot is a word-order mistake, not a collection: without this,
+	// `dt list --json contacts` reported `unknown collection "--json"` and dumped every name.
+	if (target.startsWith('--')) throw new Error(`dt ${verb} takes its target BEFORE the flags: dreamteamer ${verb} <target> ${target} …`);
+	if (COLLECTION_VERBS.has(verb)) return collectionCommand(ws, target, verb, rest);
+	if (REF_VERBS.has(verb)) {
+		const { collection, id } = splitRef(new Store(ws).descriptors, target);
+		return collectionCommand(ws, collection, verb, [id, ...rest]);
+	}
+	// EITHER_VERBS from here: a bare collection is legal for both — `move <collection> --init`,
+	// `commands <collection>`.
+	const { descriptors } = new Store(ws);
+	if (descriptors.has(target)) {
+		return verb === 'move'
+			? collectionCommand(ws, target, 'move', rest)
+			: collectionCommand(ws, 'commands', 'for', [target, ...rest]);
+	}
+	const { collection, id } = splitRef(descriptors, target);
+	if (verb === 'move') return collectionCommand(ws, collection, 'move', [id, ...rest]);
+	// `commands for <c>/<id>` split its own target at the FIRST slash, which cannot name a
+	// namespaced collection. splitRef can, so the id is handed over as `--ids` — the same
+	// `commandsFor(store, collection, ids)` call, reached without re-encoding the reference.
+	// Ours goes FIRST so an explicit `--ids` from the caller still wins (last flag parsed wins).
+	return collectionCommand(ws, 'commands', 'for', [collection, '--ids', id, ...rest]);
+}
+
+/**
+ * `dt resolve '<string>'` | `dt resolve <collection>/<id> <field>` — the ONLY place a `${env:…}`
+ * template becomes a value. Records hold the template verbatim; no read path substitutes anything,
+ * so a reference means the same thing on every machine and the file says which is which.
+ *
+ * THE HEURISTIC: the first argument is a REFERENCE iff it contains no `${` AND splits against a
+ * declared collection. Both halves are needed. `${` first, because `docs/${env:X}` is ref-SHAPED
+ * and must not be split as one — a reference can never contain a template, so the marker decides it
+ * outright. Then the split, because a plain path (`/tmp/x`, `nope/q3`) must render to itself rather
+ * than report an unknown collection it was never naming. Two accepted consequences: a bare
+ * collection name resolves to itself (splitRef refuses it, so it is "just a string"), and in an
+ * UNCOMPILED workspace every argument is a string, because there are no descriptors to split
+ * against — which keeps `dt resolve '${env:K}'` working before the first compile.
+ */
+function resolveVariables(ws, args) {
+	const [target, field] = args;
+	if (!target) throw new Error("dt resolve takes a string template or a <collection>/<id> and a field: dreamteamer resolve '${env:FILES_FOLDER}/x'");
+	// resolve has no flags, so a flag-shaped target is a mistake — and the one that costs is
+	// `dt resolve --help`, which would otherwise print `--help` back and exit 0.
+	if (target.startsWith('--')) throw new Error(`dt resolve takes a string or a <collection>/<id>, not a flag ("${target}") — see \`dreamteamer help\``);
+	const declared = ws.pkg.dreamteamer?.vars ?? [];
+	const envFile = path.join(ws.root, '.env');
+	const env = parseEnvValues(fs.existsSync(envFile) ? fs.readFileSync(envFile, 'utf8') : '');
+	const ctx = { env, workspaceFolder: ws.root, declared };
+
+	let ref = null;
+	let store = null;
+	if (!target.includes('${')) {
+		try {
+			store = new Store(ws);
+			ref = splitRef(store.descriptors, target);
+		} catch { ref = null; }
+	}
+	// An argument nobody reads is a silent wrong answer: `dt resolve docs/q3 source_file garbage`
+	// exited 0 on the field it happened to recognise.
+	const takes = ref ? 2 : 1;
+	if (args.length > takes) {
+		throw new Error(`dt resolve takes ${takes === 1 ? 'one string template' : 'a reference and ONE field'} — ${args.length - takes} extra argument(s): ${args.slice(takes).join(' ')}`);
+	}
+	if (!ref) {
+		console.log(renderTemplate(target, ctx));
+		return 0;
+	}
+	if (!field) throw new Error(`dt resolve ${target} needs a field name: dreamteamer resolve ${target} <field>`);
+	const { fields } = store.read(ref.collection, ref.id);
+	const value = fields[field];
+	if (value === undefined) throw new Error(`${target} has no field "${field}"`);
+	// RENDER EVERY ITEM BEFORE PRINTING ANY. An array prints one item per line so the output pipes
+	// into a shell loop unchanged — and a loop that does not check $? cannot tell a truncated list
+	// from a short one, so a failure on item n must not leave items 1..n-1 on stdout. Anything that
+	// is not text is refused rather than stringified: a number cannot hold a template.
+	const items = Array.isArray(value) ? value : [value];
+	const bad = items.findIndex((v) => typeof v !== 'string'); // index, not the value: an item may be null
+	if (bad > -1) throw new Error(`${target} field "${field}" holds a ${typeof items[bad]} — resolve renders text (a string, or a list of them)`);
+	const rendered = items.map((v) => renderTemplate(v, ctx));
+	if (rendered.length) console.log(rendered.join('\n'));
+	return 0;
+}
+
+/** Translate `dt schema <op> …` onto the same meta verbs `collectionCommand` already routes. */
+function dispatchSchemaVerb(ws, args) {
+	const [op, ...rest] = args;
+	if (!op) throw new Error(`dt schema needs an operation — use ${SCHEMA_OP_LIST}`);
+	if (SCHEMA_FIELD_OPS.has(op)) {
+		const [collection, ...flags] = rest;
+		if (!collection || collection.startsWith('--')) {
+			throw new Error(`dt schema ${op} needs a collection: dreamteamer schema ${op} <collection> --name <field> …`);
+		}
+		return collectionCommand(ws, collection, op, flags);
+	}
+	const pair = SCHEMA_OPS[op];
+	if (!pair) throw new Error(`unknown schema operation "${op}" — use ${SCHEMA_OP_LIST}`);
+	return collectionCommand(ws, pair[0], pair[1], rest);
+}
+
 function tryGit(cwd, args) {
 	try { return execFileSync('git', args, { cwd, stdio: QUIET }).toString().trim() || null; } catch { return null; }
 }

package/src/collections-cli.js

@@ -1,6 +1,7 @@
-// noun-verb collection commands: dreamteamer <collection> list|get|add|set|rm|rename|history|diff|revert
-// + meta verbs: `collections add|rm`, `<collection> add-field|update-field|remove-field`,
-//   `ui-views add|set|rm`
+// The IMPLEMENTATION layer behind the verb-first CLI: `collectionCommand(ws, collection, verb, args)`
+// is (collection, verb) shaped and stays that way — `cli.js` translates `dt <verb> <target>` onto it.
+// So a spelling here (`collections add`, `<collection> add-field`, `commands for`, `repos ensure`) is
+// an INTERNAL pair, not what the operator types; `dt schema add-collection` is what they type.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -19,6 +20,7 @@ import { distinctValues } from './field-values.js';
 import { matchesFilter } from './filter.js';
 import { baseNameOf, normalizeNamespaces } from './namespace.js';
 import { sortRows } from './temporal.js';
+import { keyBetween, placementKey } from './fractional-index.js';
 import { ensureRepo, ensureAllRepos } from './init.js';
 
 /**
@@ -26,7 +28,7 @@ import { ensureRepo, ensureAllRepos } from './init.js';
  *
  * `console.log` to a pipe is asynchronous, and every CLI path ends in `process.exit()`, which
  * discards whatever is still buffered. A shell pipeline hides the bug completely — the reader
- * drains concurrently, so `dreamteamer contacts list --json | wc -c` reports all 32381 bytes — but
+ * drains concurrently, so `dreamteamer list contacts --json | wc -c` reports all 32381 bytes — but
  * the way a script or a coding agent actually calls this is execFileSync/spawnSync, and there the
  * child exits with the pipe still full. Measured before this fix: the same command captured with
  * execFileSync returned exactly **8190 bytes** (one pipe buffer) of that 32381-byte document, i.e.
@@ -133,6 +135,40 @@ export function collectionCommand(ws, collection, verb, args) {
 			flags.json ? emit(JSON.stringify({ id })) : console.log('✔ updated');
 			return 0;
 		}
+		// Manual ordering. ONE record is written per move — that is the entire feature; a dense
+		// integer would renumber everything below the insertion point and bury the change. The field is
+		// named by the descriptor (`sort_field`), never here, so a workspace may call it anything.
+		case 'move': {
+			const field = d.sort_field;
+			if (!field) throw new Error(`collection "${collection}" declares no sort_field — add one to its descriptor before ordering it by hand.`);
+
+			// Blanks sort FIRST (compareValues, via `?? ''`), so unplaced records surface at the top
+			// rather than hiding at the bottom, and ties fall back to id order: `walk` reads name-sorted
+			// and Array.sort is stable. That is the tiebreak two agents landing on the same key rely on.
+			const rows = [];
+			for (const { id: rid, fields } of store.readAll(collection)) rows.push({ id: rid, key: fields[field] ?? '' });
+			sortRows(rows, 'key');
+
+			if (flags.init) {
+				// Idempotent: a record that already carries a key keeps it, so --init can be re-run after
+				// adding records without disturbing an order the operator set by hand.
+				let prev = rows.filter((r) => r.key).pop()?.key ?? null;
+				let written = 0;
+				for (const r of rows) {
+					if (r.key) continue;
+					prev = keyBetween(prev, null);
+					store.set(collection, r.id, { [field]: prev });
+					written++;
+				}
+				flags.json ? emit(JSON.stringify({ placed: written })) : console.log(written ? `✔ placed ${written} record(s) in ${field}` : '✔ nothing to place');
+				return 0;
+			}
+
+			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');
+			return 0;
+		}
 		case 'rm': {
 			const id = need(pos, 0, 'id');
 			const { inboundIgnored } = store.rm(collection, id, { force: !!flags.force });
@@ -146,7 +182,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			if (out.touched) console.log(`✔ rewrote ${out.rewrites} inbound reference(s) across ${out.touched} file(s)`);
 			return 0;
 		}
-		// `dreamteamer meetings values status` — the vocabulary a field ACTUALLY uses, so a filter
+		// `dreamteamer values meetings status` — the vocabulary a field ACTUALLY uses, so a filter
 		// or a command-binding validator can offer a dropdown for a plain `type: string` field that
 		// no enum describes (operator: "still no dropdown for many things, visibility, status").
 		case 'values': {
@@ -181,7 +217,7 @@ export function collectionCommand(ws, collection, verb, args) {
 			// the hash is REQUIRED and has no default: "revert" with an implied target is how you
 			// destroy the wrong record. `<c> history <id>` is where you get one.
 			const hash = typeof flags.hash === 'string' ? flags.hash : pos[1];
-			if (!hash) throw new Error(`missing --hash <commit> — run \`dreamteamer ${collection} history ${id}\` to pick one`);
+			if (!hash) throw new Error(`missing --hash <commit> — run \`dreamteamer history ${collection}/${id}\` to pick one`);
 			const out = store.revert(collection, id, hash);
 			flags.json ? emit(JSON.stringify(out)) : console.log(out.reverted ? `✔ reverted ${collection}/${id} to ${String(hash).slice(0, 7)}` : `= already identical to ${String(hash).slice(0, 7)} — nothing changed`);
 			return 0;
@@ -193,16 +229,18 @@ export function collectionCommand(ws, collection, verb, args) {
 
 
 
-// `dreamteamer commands for <collection>[/<id>] [--ids <id>[,…]] [--json]` — which bound
-// commands apply, in which state (available / done / not-applicable). THE engine surface
-// behind the studio's Commands tab (engine/UI parity: the verb lands first, the button second).
+// Which bound commands apply, in which state (available / done / not-applicable). THE engine
+// surface behind the studio's Commands tab (engine/UI parity: the verb lands first, the button
+// second).
+//
+// ⚠ The COLLECTION arrives already resolved, and the ids only ever through `--ids`. This used to
+// split its own target at the first slash — which cannot name a namespaced collection, so
+// `commands finance/transactions` asked for a collection called "finance" and every namespaced
+// target failed. `cli.js` owns reference resolution now (splitRef, longest declared prefix) and is
+// the only caller, so a second, weaker splitter here could only ever disagree with it.
 function metaCommandsFor(ws, store, flags, pos) {
-	const target = need(pos, 0, 'collection[/id]');
-	const slash = target.indexOf('/');
-	const collection = slash > 0 ? target.slice(0, slash) : target;
-	const ids = slash > 0
-		? [target.slice(slash + 1)]
-		: typeof flags.ids === 'string' ? flags.ids.split(',').map((s) => s.trim()).filter(Boolean) : [];
+	const collection = need(pos, 0, 'collection');
+	const ids = typeof flags.ids === 'string' ? flags.ids.split(',').map((s) => s.trim()).filter(Boolean) : [];
 	const out = commandsFor(store, collection, ids);
 	if (flags.json) { emit(JSON.stringify(out, null, 2)); return 0; }
 	if (!out.commands.length) { console.log(`(no commands bound to ${collection})`); return 0; }
@@ -241,7 +279,7 @@ function metaCollectionsAdd(ws, store, flags) {
 // 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>');
+	if (!oldName) throw new Error('usage: dreamteamer schema rename-collection <old> <new> | <old> --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

package/src/compile.js

@@ -17,6 +17,7 @@ import {
 // call at run time, same pattern as store.js ↔ compile.js.
 import { runHarnessAdapters } from './harnesses.js';
 import { satisfies } from './semver.js';
+import { parseEnvValues } from './env-vars.js';
 import { DERIVED_KINDS, readManifest, runtimeDir } from './runtime.js';
 
 // re-exported, not moved: `readManifest` is in the VS Code extension's hand-maintained engine
@@ -295,21 +296,37 @@ export function compile({ root, pkg }) {
 			declaredEnv.get(k).push(source.name);
 		}
 	}
-	if (declaredEnv.size) {
+	// `dreamteamer.vars` is the WORKSPACE's own declaration (root package.json, not a module's): the
+	// keys a `${env:NAME}` template is allowed to name. Same missing-key question as
+	// `dreamteamer.env`, one .env parse, two warnings — a module needs its key to RUN, a var is
+	// needed the moment someone calls `dt resolve`, and only the workspace can declare one.
+	if (config.vars !== undefined && (!Array.isArray(config.vars) || config.vars.some((v) => typeof v !== 'string'))) {
+		fail(`dreamteamer.vars must be a list of env key names (got ${JSON.stringify(config.vars)})`);
+	}
+	const declaredVars = config.vars ?? [];
+	if (declaredEnv.size || declaredVars.length) {
 		// .env is parsed for KEY names ONLY — values never reach any output or the manifest
 		const envPath = path.join(root, '.env');
 		if (!fs.existsSync(envPath)) {
-			console.warn(`⚠ no .env — modules declare env keys: ${[...declaredEnv.keys()].join(', ')} (see .env.example)`);
+			if (declaredEnv.size) console.warn(`⚠ no .env — modules declare env keys: ${[...declaredEnv.keys()].join(', ')} (see .env.example)`);
+			if (declaredVars.length) console.warn(`⚠ no .env — dreamteamer.vars declares ${declaredVars.join(', ')}, so no \${env:…} template can render here (see .env.example)`);
 		} else {
-			const present = new Set();
-			for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
-				const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/.exec(line);
-				if (m) present.add(m[1]);
-			}
+			// ⚠ THE ONE PARSER, not a key regex of our own. This used to hand-roll
+			// `/^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/`, which accepted two lines
+			// `parseEnvValues` deliberately drops (`KEY =value`, and an indented key) and scanned a
+			// quoted value's continuation lines for keys. Either disagreement produces the worst
+			// pairing there is: compile says nothing and then `dt resolve` answers "no value in
+			// .env" about a line the operator is looking straight at. Values are read here and
+			// never printed — the warnings below name keys only.
+			const present = new Set(parseEnvValues(fs.readFileSync(envPath, 'utf8')).keys());
 			for (const [k, mods] of declaredEnv) {
 				if (present.has(k)) continue;
 				for (const mod of mods) console.warn(`⚠ module ${mod} declares env key ${k} — missing from .env (see .env.example)`);
 			}
+			for (const k of declaredVars) {
+				if (present.has(k)) continue;
+				console.warn(`⚠ dreamteamer.vars declares ${k} — missing from .env, so \${env:${k}} cannot render on this machine`);
+			}
 		}
 	}
 
@@ -630,6 +647,15 @@ export function compile({ root, pkg }) {
 				fail(`collection "${name}": id.pattern is not a valid regular expression — ${e.message} (${group.map((g) => g.src.path).join(', ')})`);
 			}
 		}
+		// `sort_field` names a field of this collection's OWN schema. Without this gate a typo
+		// surfaces as "dragging does nothing" while the drag handle is still offered — a silent lie,
+		// and the ordering it writes would land in a field no reader sorts by.
+		if (merged.sort_field !== undefined) {
+			if (typeof merged.sort_field !== 'string') fail(`collection "${name}": sort_field must be a string (got ${JSON.stringify(merged.sort_field)})`);
+			if (!(merged.schema?.properties ?? {})[merged.sort_field]) {
+				fail(`collection "${name}": sort_field "${merged.sort_field}" is not a field of its schema — declare it, or point sort_field at one that exists (${group.map((g) => g.src.path).join(', ')}).`);
+			}
+		}
 		// ---- the reference contract: every target is owned, depended on, or declared a peer ----
 		// Attribution is unioned across the whole group rather than taken from the base, because the
 		// merge keeps no per-field provenance — an overlay that adds a ref field would otherwise be
@@ -696,6 +722,17 @@ export function compile({ root, pkg }) {
 		}
 		const rt = path.join('collections', `${name}.collection.yaml`);
 		entries.set(rt, { sources: [...group.map((g) => g.src), ...templateSources], bytes: Buffer.from(dump(merged)) });
+		// A descriptor with no `description:` renders in the orientation block as a bare NAME — an
+		// agent learns the noun exists and nothing about when it is the right one. Derived pressure
+		// rather than a heroic backfill pass, and the same shape as the per-missing-env-key warning:
+		// non-blocking, named per offender, so the gap converges instead of being rediscovered.
+		//
+		// ⚠ Deliberately NO equivalent warning for `use_when`. That field is optional and correct to
+		// omit on most collections — warning on it would invert its authoring test and manufacture a
+		// restatement of the description on every collection that does not need one.
+		if (merged.storage.base !== 'runtime' && !String(merged.description ?? '').trim()) {
+			console.warn(`⚠ collection ${name} has no description — it renders as a bare name in the orientation block every session loads`);
+		}
 		counts.collections++;
 		if (extenders.length) mergedCount++;
 	}

package/src/env-vars.js

@@ -0,0 +1,40 @@
+// ${env:KEY} / ${workspaceFolder} / ${userHome} — VS Code's variable grammar, three variables.
+// Values render ONLY on explicit request (dt resolve); records are never auto-substituted.
+// parseEnvValues reads .env TEXT only (never shell-evaluates). A QUOTED value (single or double)
+// may span multiple lines — the closing quote just has to end some later line, not the one it
+// opened on — because `[^"\\]`/`[^']` match newlines in JS regex same as any other character.
+// An UNQUOTED value is line-bound: it runs to end of line, so it can't span lines.
+// Two accepted non-goals, unchanged on purpose: `KEY =value` (space before `=`) doesn't match the
+// key pattern and is silently dropped, no diagnostic; an unquoted value keeps a trailing inline
+// `# comment` as part of its text (quote it to strip one).
+import os from 'node:os';
+
+export function parseEnvValues(text) {
+	const out = new Map();
+	// KEY=value with optional `export `, optional quotes; value is whatever follows on the SAME line
+	const re = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=("(?:[^"\\]|\\.)*"|'[^']*'|[^\n]*)$/gm;
+	let m;
+	while ((m = re.exec(text))) {
+		let v = m[2].trim();
+		if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) v = v.slice(1, -1);
+		out.set(m[1], v);
+	}
+	return out;
+}
+
+const SUPPORTED = 'supported: ${env:NAME}, ${workspaceFolder}, ${userHome}';
+
+export function renderTemplate(str, { env, workspaceFolder, declared }) {
+	return str.replace(/\$\{([A-Za-z]+)(?::([A-Za-z0-9_]*))?\}/g, (whole, ns, arg) => {
+		if (arg === undefined) {
+			if (ns === 'workspaceFolder') return workspaceFolder;
+			if (ns === 'userHome') return os.homedir();
+			return whole; // un-namespaced ${VAR}: not ours, inert — prose mentions ${…} freely
+		}
+		if (ns !== 'env') throw new Error(`\${${ns}:${arg}} is not a dreamteamer variable — ${SUPPORTED}`);
+		if (!arg) throw new Error(`\${env:} needs a key name — ${SUPPORTED}`);
+		if (!declared.includes(arg)) throw new Error(`\${env:${arg}}: "${arg}" is not declared in dreamteamer.vars (workspace package.json) — declared: ${declared.join(', ') || '(none)'}`);
+		if (!env.has(arg)) throw new Error(`\${env:${arg}} is declared but has no value in .env on this machine`);
+		return env.get(arg);
+	});
+}

package/src/fractional-index.js

@@ -0,0 +1,44 @@
+// Manual ordering keys. Named for the ALGORITHM: the FIELD is named per collection via
+// `sort_field`, and nothing here may assume what it is called.
+//
+// ⚠ THE ALPHABET IS LOAD-BEARING. `compareValues` (temporal.js) ends in `localeCompare`, which is
+// locale-aware, so the library's DEFAULT base-62 keys mis-sort here: prepending three times gives
+// `Zy Zz a0`, and `sortRows` returns `a0 Zy Zz`. Same trap that breaks fractional indexing on
+// Postgres under `en_US.utf8` instead of `C`. a-z is the intersection where three things hold at
+// once — locale order agrees with codepoint order, and no key can parse as a number (the numeric
+// branch of `compareValues` would sort "9" after "10") or as a temporal.
+//
+// test/unit/fractional-index.test.js asserts the base-62 failure directly, so this argument cannot
+// be deleted as noise.
+//
+// Why a dependency rather than 75 lines of our own: the naive midpoint (halve toward the open end)
+// degenerates on APPEND, which is the commonest write — measured at 200-character keys after 1000
+// appends. The library's integer-part-with-magnitude-head keeps that at 4.
+import { generateKeyBetween } from 'fractional-indexing';
+
+const DIGITS = 'abcdefghijklmnopqrstuvwxyz';
+
+/** A key strictly between `a` and `b`. Either may be null for an open end. */
+export const keyBetween = (a, b) => generateKeyBetween(a ?? null, b ?? null, DIGITS);
+
+/**
+ * The key that puts `id` where `dest` asks, given the collection's records in current sort order
+ * (`[{ id, key }]`, blanks first). PURE — the caller does the reading and the writing, which is what
+ * lets the CLI and the HTTP surface share one placement rule instead of two that drift.
+ *
+ * Fails closed on a destination that is not placed yet: with no key on the target there is nothing to
+ * compute against, and guessing would silently put the record somewhere the operator did not ask for.
+ */
+export function placementKey(rows, id, dest, collection = '<collection>') {
+	const placed = rows.filter((r) => r.key && r.id !== id);
+	const at = (t) => {
+		const i = placed.findIndex((r) => r.id === t);
+		if (i < 0) throw new Error(`"${t}" has no sort value yet — run \`dreamteamer move ${collection} --init\` first. nothing was written.`);
+		return i;
+	};
+	if (dest.top) return keyBetween(null, placed[0]?.key ?? null);
+	if (dest.bottom) return keyBetween(placed[placed.length - 1]?.key ?? null, null);
+	if (typeof dest.after === 'string') { const i = at(dest.after); return keyBetween(placed[i].key, placed[i + 1]?.key ?? null); }
+	if (typeof dest.before === 'string') { const i = at(dest.before); return keyBetween(placed[i - 1]?.key ?? null, placed[i].key); }
+	throw new Error('say where to put it — --after <id>, --before <id>, --top or --bottom. nothing was written.');
+}