dreamteamer 0.6.0

package/src/events.js

@@ -0,0 +1,124 @@
+// item events — DERIVED from git history, never observed live (the slice-5 contract in
+// using-dreamteamer → references/git-events.md): a closed laptop loses nothing, every evaluation is
+// auditable and replayable forever. history IS the queue; there is no events file.
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { EXT } from './records.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
+ *  repo then resolves that date to its own sha. Still cursor-less and stores nothing, so it can
+ *  be run twice with no consequence. */
+export function deriveEvents(root, descriptors, from, to = 'HEAD') {
+	const byRepo = new Map();
+	for (const d of descriptors.values()) {
+		const p = d.storage?.path;
+		if (!p || d.storage.base === 'runtime') continue; // runtime entities aren't item events
+		const repo = d.storage.repo ?? '.';
+		if (!byRepo.has(repo)) byRepo.set(repo, []);
+		byRepo.get(repo).push(p);
+	}
+	const when = asDate(root, from);
+	const events = [];
+	for (const [repo, dirs] of byRepo) {
+		const cwd = path.resolve(root, repo);
+		const prefix = repo === '.' ? '' : `${repo}/`;
+		// descriptors carry WORKSPACE-relative paths; git in the module repo wants its own
+		const relDirs = dirs.map((d) => (prefix && d.startsWith(prefix) ? d.slice(prefix.length) : d));
+		// a repo whose history STARTS after the baseline (the agentlog clone is younger than the
+		// workspace) has no commit to diff against — but every record in it IS new since then,
+		// so fall back to the empty tree rather than silently contributing zero events
+		const fromSha = shaAt(cwd, when) ?? EMPTY_TREE;
+		let out = '';
+		try {
+			out = execFileSync(
+				'git', ['diff', '--name-status', '-z', `${fromSha}..${to}`, '--', ...relDirs],
+				{ cwd },
+			).toString();
+		} catch { continue; }
+		events.push(...parseNameStatus(out, prefix, descriptors, repo));
+	}
+	return events;
+}
+
+// git's own "no parent" object — the diff baseline for a repo younger than the requested date
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+/** A sha or a date in → an ISO instant. A sha is resolved in the WORKSPACE repo, since that is
+ *  the only repo a caller could have got one from. */
+function asDate(root, from) {
+	// a BARE date is pinned to midnight: git's approxidate fills unspecified fields from NOW, so
+	// `--before=2026-08-01` means 2026-08-01 at the current clock time and the same command
+	// answers differently in the morning and the evening (measured, 2026-08-03)
+	if (/^\d{4}-\d{2}-\d{2}$/.test(from)) return `${from}T00:00:00`;
+	if (/^\d{4}-\d{2}-\d{2}/.test(from)) return from;
+	try {
+		return execFileSync('git', ['show', '-s', '--format=%cI', from], { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] })
+			.toString().trim();
+	} catch {
+		throw new Error(`--since "${from}" is neither a date (YYYY-MM-DD) nor a commit in this workspace`);
+	}
+}
+
+function shaAt(cwd, when) {
+	try {
+		return execFileSync('git', ['rev-list', '-1', `--before=${when}`, 'HEAD'], { cwd, stdio: ['ignore', 'pipe', 'ignore'] })
+			.toString().trim() || null;
+	} catch { return null; }
+}
+
+/** `git diff --name-status -z` output → record events. `prefix` turns each REPO-relative path
+ *  into the WORKSPACE-relative one pathToRecord expects; without it every module-owned path
+ *  matches nothing and the repo silently contributes zero events. Note the -z layout: unlike
+ *  `status --porcelain -z`, the status letter and the path are SEPARATE NUL-terminated chunks. */
+function parseNameStatus(out, prefix, descriptors, repo) {
+	const parts = out.split('\0').filter((s) => s.length > 0);
+	const events = [];
+	const push = (type, relPath) => {
+		const rec = pathToRecord(descriptors, relPath);
+		if (rec) events.push({ type, ...rec, path: relPath, repo });
+	};
+	for (let i = 0; i < parts.length; ) {
+		const status = parts[i++];
+		const p1 = prefix + parts[i++];
+		if (status.startsWith('R') || status.startsWith('C')) {
+			const p2 = prefix + parts[i++];
+			if (status.startsWith('R')) push('item-removed', p1);
+			push('item-added', p2);
+		} else {
+			push(status[0] === 'A' ? 'item-added' : status[0] === 'D' ? 'item-removed' : 'item-updated', p1);
+		}
+	}
+	return events;
+}
+
+/** map a workspace-relative path to {collection, id} via storage.path longest-prefix
+ *  match + suffix/codec (file shape) or entry (folder shape). non-records → null. */
+export function pathToRecord(descriptors, relPath) {
+	let best = null;
+	for (const d of descriptors.values()) {
+		const base = d.storage?.path;
+		if (!base || d.storage.base === 'runtime') continue; // runtime entities aren't item events
+		if (!relPath.startsWith(base + '/')) continue;
+		if (best && base.length <= best.storage.path.length) continue;
+		best = d;
+	}
+	if (!best) return null;
+	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)) };
+	}
+	const tail = `.${best.storage.suffix}${EXT[best.storage.codec ?? 'md']}`;
+	if (!rest.endsWith(tail)) return null;
+	return { collection: best.name, id: rest.slice(0, -tail.length) };
+}
+
+/** the commit that last touched `path` inside the range — the event's provenance sha,
+ *  and one leg of the deterministic run-dedupe key (trigger + item + commit). */
+export function eventCommit(root, fromSha, toSha, relPath) {
+	const out = execFileSync('git', ['log', '--format=%H', '-1', `${fromSha}..${toSha}`, '--', relPath], { cwd: root })
+		.toString().trim();
+	return out || toSha;
+}

package/src/field-values.js

@@ -0,0 +1,69 @@
+// distinct values actually present in a collection's field.
+//
+// Why this exists: a filter (or a command-binding validator) can only offer a dropdown when
+// something tells it the value set. `enum` in the descriptor does that — but most string fields
+// aren't enums and never will be. `meetings.status` and `meetings.visibility` are plain
+// `type: string`, so the filter builder correctly fell back to a free-text box and the operator
+// had to know the vocabulary by heart (operator 2026-07-28: "still no dropdown for many things,
+// visibility, status — why?").
+//
+// The data already knows. This derives the vocabulary from the records themselves, so every
+// low-cardinality field becomes selectable with no schema change and no risk of `check` failing
+// on a value that predates an enum someone added later.
+import { bodyField } from './store.js';
+
+/** Above this many distinct values a dropdown stops being a dropdown — report and stop counting. */
+export const DEFAULT_LIMIT = 50;
+
+/**
+ * `{ collection, field, values: [{value, count}], total, truncated }` — most-used first, then
+ * alphabetical, so the dropdown leads with what the operator actually uses.
+ *
+ * Array-valued fields (tags, attendees) contribute each ENTRY, not the array: filtering
+ * `attendees` by `contacts/ada` is the useful question, and `matchesFilter` already gives array
+ * fields containment semantics for `_eq`/`_in`, so the two halves agree.
+ *
+ * Bodies are skipped outright — a markdown body has one distinct value per record and counting
+ * them is pure waste. Objects are skipped too: there is no sane dropdown entry for a subtree.
+ */
+export function distinctValues(store, collection, field, { limit = DEFAULT_LIMIT } = {}) {
+	const d = store.descriptor(collection);
+	const prop = d.schema?.properties?.[field];
+	if (!prop && field !== 'id') {
+		throw new Error(`unknown field "${field}" on ${collection} (known: ${Object.keys(d.schema?.properties ?? {}).join(', ')})`);
+	}
+	if (prop?.['x-body']) return { collection, field, values: [], total: 0, truncated: false, skipped: 'body' };
+	const isObject = prop?.type === 'object' || prop?.items?.type === 'object';
+	if (isObject) return { collection, field, values: [], total: 0, truncated: false, skipped: 'object' };
+
+	// An enum already IS the vocabulary — hand it back verbatim (counts omitted: the schema's
+	// answer must not shrink just because no record happens to use a legal value yet).
+	const declared = prop?.enum ?? prop?.items?.enum;
+	if (Array.isArray(declared) && declared.length) {
+		return { collection, field, values: declared.map((value) => ({ value, count: null })), total: declared.length, truncated: false, source: 'enum' };
+	}
+
+	const bf = bodyField(d);
+	const counts = new Map();
+	for (const { id, fields } of store.readAll(collection)) {
+		const raw = field === 'id' ? id : fields[field];
+		if (raw == null || raw === '' || (bf && field === bf)) continue;
+		for (const v of Array.isArray(raw) ? raw : [raw]) {
+			if (v == null || v === '' || typeof v === 'object') continue;
+			counts.set(v, (counts.get(v) ?? 0) + 1);
+		}
+	}
+
+	const sorted = [...counts.entries()]
+		.sort((a, b) => b[1] - a[1] || String(a[0]).localeCompare(String(b[0])))
+		.map(([value, count]) => ({ value, count }));
+
+	return {
+		collection,
+		field,
+		values: sorted.slice(0, limit),
+		total: sorted.length,
+		truncated: sorted.length > limit,
+		source: 'data',
+	};
+}

package/src/filter.js

@@ -0,0 +1,107 @@
+// record filtering — the operator set harvested from an earlier engine's
+// query/compare.ts (Directus-style), trimmed to what the studio FilterBuilder
+// and saved views actually emit. evaluated server-side over parsed records.
+// negative operators deliberately reject null (SQL semantics).
+import { compareValues } from './temporal.js';
+
+export function matchesFilter(record, filter, resolve) {
+	if (filter == null || typeof filter !== 'object') return true;
+	for (const [key, cond] of Object.entries(filter)) {
+		if (key === '_and') { if (!cond.every((c) => matchesFilter(record, c, resolve))) return false; continue; }
+		if (key === '_or') { if (!cond.some((c) => matchesFilter(record, c, resolve))) return false; continue; }
+		if (!matchesField(record[key], cond, resolve)) return false;
+	}
+	return true;
+}
+
+function matchesField(value, cond, resolve) {
+	if (cond === null || typeof cond !== 'object' || Array.isArray(cond)) return compare('_eq', value, cond);
+	for (const [op, operand] of Object.entries(cond)) {
+		if (!op.startsWith('_')) {
+			// one-hop relational condition (tier 1): a non-operator key means the field holds a
+			// `<collection>/<id>` ref (or an array of them) — resolve and evaluate the sub-condition
+			// against the target record. array refs use _some semantics (any target matches).
+			// no resolver wired, a dangling ref, or a non-ref value NARROWS, never widens — same
+			// fail-closed posture as unknown operators. inbound refs are tier 2 (not supported).
+			if (!resolve) return false;
+			const refs = (Array.isArray(value) ? value : [value]).filter((r) => typeof r === 'string');
+			if (!refs.some((r) => { const target = resolve(r); return target && matchesField(target[op], operand, resolve); })) return false;
+			continue;
+		}
+		if (!compare(op, value, operand)) return false;
+	}
+	return true;
+}
+
+function compare(op, v, o) {
+	const s = (x) => String(x ?? '');
+	const empty = v == null || v === '' || (Array.isArray(v) && v.length === 0);
+	// array field values (tags, attendees): containment semantics for eq/contains
+	const arr = Array.isArray(v);
+	switch (op) {
+		case '_eq': return arr ? v.includes(o) : looseEq(v, o);
+		case '_neq': return v != null && !(arr ? v.includes(o) : looseEq(v, o));
+		case '_ieq': return s(v).toLowerCase() === s(o).toLowerCase();
+		case '_nieq': return v != null && s(v).toLowerCase() !== s(o).toLowerCase();
+		case '_lt': return v != null && cmp(v, o) < 0;
+		case '_lte': return v != null && cmp(v, o) <= 0;
+		case '_gt': return v != null && cmp(v, o) > 0;
+		case '_gte': return v != null && cmp(v, o) >= 0;
+		case '_in': return toArray(o).some((x) => (arr ? v.includes(x) : looseEq(v, x)));
+		case '_nin': return v != null && !toArray(o).some((x) => (arr ? v.includes(x) : looseEq(v, x)));
+		case '_null': return o ? v == null : v != null;
+		case '_nnull': return o ? v != null : v == null;
+		case '_empty': return o ? empty : !empty;
+		case '_nempty': return o ? !empty : empty;
+		case '_contains': return arr ? v.some((x) => s(x).includes(s(o))) : s(v).includes(s(o));
+		case '_ncontains': return v != null && !s(v).includes(s(o));
+		case '_icontains': return arr ? v.some((x) => s(x).toLowerCase().includes(s(o).toLowerCase())) : s(v).toLowerCase().includes(s(o).toLowerCase());
+		case '_starts_with': return s(v).startsWith(s(o));
+		case '_istarts_with': return s(v).toLowerCase().startsWith(s(o).toLowerCase());
+		case '_ends_with': return s(v).endsWith(s(o));
+		case '_iends_with': return s(v).toLowerCase().endsWith(s(o).toLowerCase());
+		case '_between': { const [a, b] = toArray(o); return v != null && cmp(v, a) >= 0 && cmp(v, b) <= 0; }
+		case '_nbetween': { const [a, b] = toArray(o); return v != null && (cmp(v, a) < 0 || cmp(v, b) > 0); }
+		case '_regex': try { return new RegExp(String(o)).test(s(v)); } catch { return false; }
+		default:
+			// unknown operator NARROWS, never widens (review finding 5): filters are load-bearing
+			// in compiled ui-views — a typo'd _nq matching everything showed every user's tasks
+			// with no signal. warn once per operator per process.
+			warnUnknownOp(op);
+			return false;
+	}
+}
+
+export const KNOWN_OPERATORS = new Set(['_eq', '_neq', '_ieq', '_nieq', '_lt', '_lte', '_gt', '_gte', '_in', '_nin', '_null', '_nnull', '_empty', '_nempty', '_contains', '_ncontains', '_icontains', '_starts_with', '_istarts_with', '_ends_with', '_iends_with', '_between', '_nbetween', '_regex', '_and', '_or']);
+
+const warned = new Set();
+function warnUnknownOp(op) {
+	if (warned.has(op)) return;
+	warned.add(op);
+	console.warn(`⚠ unknown filter operator "${op}" — treated as matching NOTHING (known: ${[...KNOWN_OPERATORS].join(', ')})`);
+}
+
+// walk a filter tree and return every operator key not in the known set — compile
+// validates ui-view filters with this so a typo'd operator fails loudly at compile time.
+export function unknownOperators(filter, found = new Set()) {
+	if (filter == null || typeof filter !== 'object') return found;
+	for (const [key, cond] of Object.entries(filter)) {
+		if (key === '_and' || key === '_or') {
+			for (const c of Array.isArray(cond) ? cond : []) unknownOperators(c, found);
+		} else if (key.startsWith('_')) {
+			if (!KNOWN_OPERATORS.has(key)) found.add(key);
+		} else if (cond !== null && typeof cond === 'object' && !Array.isArray(cond)) {
+			// field conditions recurse like filters: operator maps at any depth are checked,
+			// and non-operator keys (one-hop relational conditions) descend into their sub-filter
+			unknownOperators(cond, found);
+		}
+	}
+	return found;
+}
+
+const looseEq = (v, o) => v === o || String(v) === String(o) || (typeof v === 'number' && Number(o) === v);
+const toArray = (o) => (Array.isArray(o) ? o : String(o).split(',').map((x) => x.trim()));
+// ordering lives in temporal.js: a date-time carries its own local offset, so `_gt`/`_lt` have to
+// compare INSTANTS. String order would put `…T12:00+03:00` after `…T11:00+01:00`, which is the
+// earlier moment. Numbers and plain strings behave exactly as before.
+const cmp = compareValues;

package/src/harnesses.js

@@ -0,0 +1,233 @@
+// harness adapters — one thin stage per harness, dispatched from compile over the same
+// compiled entries. the superpowers lesson, kept deliberately: CONTENT NEVER FORKS PER
+// HARNESS — skills copy verbatim (+stamp), every root file gets the same managed
+// orientation block; only the injection points differ per harness:
+//   claude-code → .claude/{skills,agents,commands} + CLAUDE.md block  (native everything)
+//   codex       → AGENTS.md block + .agents/skills mirror             (~/.codex reads AGENTS.md)
+//   pi          → AGENTS.md block + .agents/skills mirror             (pi auto-discovers .agents/skills)
+//   cursor      → .cursor/rules/dreamteamer.mdc + .agents/skills      (.mdc is cursor's native rule file)
+//   gemini-cli  → GEMINI.md block + .agents/skills mirror             (GEMINI.md is its context file)
+// managed blocks live in USER-OWNED files (committed); generated dirs (.claude, .agents,
+// .cursor) are gitignored and pruned by stamp. removing a harness from config removes its
+// block/file on the next compile.
+import fs from 'node:fs';
+import path from 'node:path';
+import { load, dump } from './yaml.js';
+
+export const KNOWN_HARNESSES = ['claude-code', 'codex', 'pi', 'gemini-cli', 'cursor'];
+
+export const STAMP = '<!-- generated by dreamteamer compile — do not edit; source of truth lives in modules/<module>/<kind>/ -->';
+
+const BEGIN = '<!-- dreamteamer:begin (generated — do not edit inside this block) -->';
+const END = '<!-- dreamteamer:end -->';
+
+export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat' }) {
+	const outputs = [];
+	const summary = [];
+	const rel = (p) => path.relative(root, p);
+	const write = (out, bytes) => {
+		const dest = path.join(root, out);
+		fs.mkdirSync(path.dirname(dest), { recursive: true });
+		fs.writeFileSync(dest, bytes);
+		outputs.push(out);
+	};
+
+	for (const h of harnesses) {
+		if (!KNOWN_HARNESSES.includes(h)) console.warn(`⚠ unknown harness "${h}" in dreamteamer.harnesses — skipped (known: ${KNOWN_HARNESSES.join(', ')})`);
+	}
+	const on = (h) => harnesses.includes(h);
+	const skillsIndex = buildSkillsIndex(entries);
+
+	// ---- claude-code: native skills/agents/commands dirs + CLAUDE.md block ----------
+	if (on('claude-code')) {
+		let n = 0;
+		for (const [rt, e] of entries) {
+			if (rt.startsWith('skills/')) {
+				const out = path.join('.claude/skills', rt.slice('skills/'.length));
+				write(out, out.endsWith('.md') ? stampMd(e.bytes) : e.bytes);
+				n++;
+			} else if (rt.startsWith('agents/')) {
+				write(path.join('.claude/agents', path.basename(rt).replace(/\.agent\.md$/, '.md')), stampMd(transformAgent(e.bytes)));
+				n++;
+			} else if (rt.startsWith('commands/')) {
+				write(path.join('.claude/commands', path.basename(rt).replace(/\.command\.md$/, '.md')), stampMd(e.bytes));
+				n++;
+			}
+		}
+		summary.push(`claude-code → .claude (${n} files)`);
+	}
+	writeBlock(root, 'CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout) : null);
+
+	// ---- shared cross-agent skills mirror (.agents/skills) — codex/pi discover it,
+	// cursor/gemini blocks point at it. written once no matter how many harnesses use it.
+	const wantsMirror = on('codex') || on('pi') || on('cursor') || on('gemini-cli');
+	if (wantsMirror) {
+		let n = 0;
+		for (const [rt, e] of entries) {
+			if (!rt.startsWith('skills/')) continue;
+			const out = path.join('.agents/skills', rt.slice('skills/'.length));
+			write(out, out.endsWith('.md') ? stampMd(e.bytes) : e.bytes);
+			n++;
+		}
+		summary.push(`.agents/skills mirror (${n} files)`);
+	}
+
+	// ---- codex + pi: both read root AGENTS.md; one block serves both ----------------
+	writeBlock(root, 'AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout) : null);
+	if (on('codex')) summary.push('codex → AGENTS.md block');
+	if (on('pi')) summary.push('pi → AGENTS.md block + .agents/skills');
+
+	// ---- gemini-cli: GEMINI.md is its context file -----------------------------------
+	writeBlock(root, 'GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout) : null);
+	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
+
+	// ---- cursor: native .mdc rule (alwaysApply) ---------------------------------------
+	if (on('cursor')) {
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${orientationBlock('cursor', skillsIndex, sourceLayout)}\n\n${STAMP}\n`;
+		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
+		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
+	}
+
+	// ---- prune: anything WE stamped that this compile didn't produce ------------------
+	const current = new Set(outputs);
+	for (const dir of ['.claude/skills', '.claude/agents', '.claude/commands', '.agents/skills', '.cursor/rules']) {
+		const abs = path.join(root, dir);
+		if (!fs.existsSync(abs)) continue;
+		for (const f of walk(abs)) {
+			const relOut = rel(f);
+			if (current.has(relOut)) continue;
+			if (/\.(md|mdc)$/.test(f) && fs.readFileSync(f, 'utf8').includes(STAMP)) fs.rmSync(f);
+		}
+	}
+	for (const old of prevManifest?.['adapter-outputs'] ?? []) {
+		if (!current.has(old) && fs.existsSync(path.join(root, old))) fs.rmSync(path.join(root, old));
+	}
+	// pruning leaves empty skill folders behind — sweep them (and the roots when hollow)
+	for (const dir of ['.claude', '.agents', '.cursor']) pruneEmptyDirs(path.join(root, dir));
+
+	return { outputs, summary };
+}
+
+// skill id → description one-liners from each SKILL.md's frontmatter; the orientation
+// block carries this index so harnesses without native skill discovery still get triggers.
+function buildSkillsIndex(entries) {
+	const index = [];
+	for (const [rt, e] of entries) {
+		const m = /^skills\/([^/]+)\/SKILL\.md$/.exec(rt);
+		if (!m) continue;
+		const fm = /^---\r?\n([\s\S]*?)\r?\n---/.exec(e.bytes.toString('utf8'));
+		let desc = '';
+		try { desc = (fm ? load(fm[1]) : {})?.description ?? ''; } catch { /* unparseable frontmatter */ }
+		index.push({ id: m[1], desc: String(desc).replace(/\s+/g, ' ').trim() });
+	}
+	return index.sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/** `sourceLayout` describes what THIS workspace actually looks like — 'flat' (`<module>/skills/`),
+ *  'nested' (the pre-2026-08-05 `<module>/system/skills/`), or 'mixed'. It is passed in rather than
+ *  assumed because generated prose that contradicts the workspace is worse than no prose: this block
+ *  is the first thing an agent session reads, and a workspace still on the old layout was being told
+ *  to write somewhere it does not keep its sources. */
+function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat') {
+	const sourcesLine = {
+		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
+		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
+		mixed: '`modules/<module>/<kind>/`, or `<module>/system/<kind>/` where a module still nests it —\n`collections/`, `skills/`, `agents/`, `commands/`,',
+	}[sourceLayout] ?? '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,';
+	const lines = [
+		'this workspace is operated by dreamteamer v0.6. **read the `using-dreamteamer` skill before',
+		'working with data.** schemas (read): `.dreamteamer/collections/` (provenance:',
+		'`.dreamteamer/manifest.yaml`). sources (write): ' + sourcesLine,
+		'`command-bindings/`, `ui-views/`, `collection-templates/`',
+		'(see manifest for channels). data: `data/`; operational records:',
+		'`state/`. records are `<id>.<suffix>.<ext>`',
+		'files; ids are paths; references are `<collection>/<id>`. run `dreamteamer check` (`npm run',
+		'check`) after bulk edits; run `dreamteamer compile` (`npm run compile`) after changing any',
+		'source or installing modules.',
+	];
+	// claude-code discovers skills natively (Skill tool) — an index in CLAUDE.md is pure
+	// context bloat there. every other harness gets the trigger index + discovery pointers.
+	if (flavor !== 'claude-code') {
+		lines.push(
+			'',
+			"skills — reusable techniques, one folder per skill at `.agents/skills/` (canonical:",
+			"`.dreamteamer/skills/`); each SKILL.md's description says when to load it. load",
+			'the relevant skill BEFORE the task:',
+			...skillsIndex.map((s) => `- \`${s.id}\` — ${s.desc}`),
+			'',
+			'agent personas live at `.dreamteamer/agents/*.agent.md`; commands at',
+			'`.dreamteamer/commands/` (invoked as `/<name>` by the harness).',
+		);
+	}
+	return lines.join('\n');
+}
+
+// managed block in a USER-OWNED root file. content=null removes the block; a file left
+// empty (or whitespace) after removal is deleted — we created it, we clean it up.
+function writeBlock(root, filename, content) {
+	const file = path.join(root, filename);
+	const exists = fs.existsSync(file);
+	if (content == null) {
+		if (!exists) return;
+		let text = fs.readFileSync(file, 'utf8');
+		if (!text.includes(BEGIN)) return;
+		text = text.replace(new RegExp(`\\n?\\n?${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}\\n?`), '\n');
+		if (text.trim() === '') fs.rmSync(file);
+		else fs.writeFileSync(file, text);
+		return;
+	}
+	const block = `${BEGIN}\n${content}\n${END}`;
+	let text = exists ? fs.readFileSync(file, 'utf8') : '';
+	if (text.includes(BEGIN)) text = text.replace(new RegExp(`${escapeRe(BEGIN)}[\\s\\S]*?${escapeRe(END)}`), block);
+	else text = (text.trimEnd() + '\n\n' + block + '\n').replace(/^\n+/, '');
+	fs.writeFileSync(file, text);
+}
+
+export function stampMd(bytes) {
+	const text = bytes.toString('utf8');
+	return text.includes(STAMP) ? bytes : Buffer.from(text.trimEnd() + '\n\n' + STAMP + '\n');
+}
+
+// dreamteamer agent record -> claude-code subagent: `skills` is not a harness
+// frontmatter key; translate it into a binding instruction in the body.
+export function transformAgent(bytes) {
+	const text = bytes.toString('utf8');
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
+	if (!m) return bytes;
+	const doc = load(m[1]) ?? {};
+	const body = text.slice(m[0].length);
+	const skills = doc.skills ?? [];
+	delete doc.skills;
+	const skillLine = skills.length
+		? `ALWAYS load these skills (Skill tool) before acting: ${skills.map((s) => String(s).replace(/^skills\//, '')).join(', ')}.\n\n`
+		: '';
+	return Buffer.from(`---\n${dump(doc)}---\n\n${skillLine}${body.trimStart()}`);
+}
+
+function escapeRe(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// depth-first removal of empty directories; returns true when `dir` itself was removed.
+// dotfile-only dirs count as non-empty (never delete something we can't see into).
+function pruneEmptyDirs(dir) {
+	if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return false;
+	for (const name of fs.readdirSync(dir)) {
+		const p = path.join(dir, name);
+		if (fs.statSync(p).isDirectory()) pruneEmptyDirs(p);
+	}
+	if (fs.readdirSync(dir).length === 0) {
+		fs.rmdirSync(dir);
+		return true;
+	}
+	return false;
+}
+
+function* walk(dir) {
+	for (const name of fs.readdirSync(dir).sort()) {
+		if (name.startsWith('.')) continue;
+		const p = path.join(dir, name);
+		if (fs.statSync(p).isDirectory()) yield* walk(p);
+		else yield p;
+	}
+}

package/src/history.js

@@ -0,0 +1,64 @@
+// per-record revision history, straight out of git.
+//
+// Extracted because it had drifted into being UI-only in practice: the exact same `git log
+// --follow --format=…` and `git diff <hash>~1 <hash>` lived inlined in `server.js`'s routes AND
+// copy-pasted into the VS Code extension's `src/api.ts`, with no CLI verb anywhere — so "show me
+// how this record changed" was a thing you could do by clicking and not by asking an agent. One
+// implementation here, three callers (CLI, server, extension).
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { RUNTIME_DIR, readManifest } from './runtime.js';
+
+const FORMAT = '%H%x00%an%x00%aI%x00%s';
+
+/**
+ * The TRACKED file(s) behind a record — what git actually has commits for.
+ *
+ * For an ordinary data record that is the record itself. For a SYSTEM-stored one (collections,
+ * ui-views, skills, agents…) `store.read` hands back the compiled artifact under `.dreamteamer/`,
+ * which is gitignored — asking git about it returns nothing, so history silently reported "no
+ * history" for every schema and view record. The manifest already maps each runtime entry back to
+ * the source(s) that produced it; those are the files with a past.
+ *
+ * A layered record (a workspace module overriding a module-shipped one) has SEVERAL sources and
+ * genuinely changes when any of them does, so all of them are followed.
+ */
+function trackedPaths(store, file) {
+	const rel = path.relative(store.root, file);
+	if (!rel.startsWith(RUNTIME_DIR + path.sep)) return [rel];
+	try {
+		const key = rel.split(path.sep).slice(1).join('/'); // drop the `.dreamteamer/` prefix
+		const sources = readManifest(store.root)?.entries?.[key]?.sources ?? [];
+		const paths = sources.map((s) => (typeof s === 'string' ? s : s?.path)).filter(Boolean);
+		return paths.length ? paths : [rel];
+	} catch {
+		return [rel]; // no manifest (never compiled) — nothing better to offer
+	}
+}
+
+/**
+ * `git log` for a record, newest first. `--follow` (so a rename keeps its past) only applies to a
+ * single pathspec — git rejects it outright with several — so a layered record trades it away.
+ */
+export function history(store, collection, id) {
+	const { file } = store.read(collection, id);
+	const paths = trackedPaths(store, file);
+	const follow = paths.length === 1 ? ['--follow'] : [];
+	const out = execFileSync('git', ['log', ...follow, `--format=${FORMAT}`, '--', ...paths], { cwd: store.root }).toString();
+	return out
+		.trim()
+		.split('\n')
+		.filter(Boolean)
+		.map((line) => {
+			const [hash, author, date, subject] = line.split('\0');
+			return { hash, author, date, subject };
+		});
+}
+
+/** The patch one revision applied to this record. `hash~1` means the ROOT commit has no diff. */
+export function historyDiff(store, collection, id, hash = 'HEAD') {
+	const { file } = store.read(collection, id);
+	const paths = trackedPaths(store, file);
+	const diff = execFileSync('git', ['diff', `${hash}~1`, hash, '--', ...paths], { cwd: store.root }).toString();
+	return { hash, path: paths.join(', '), diff };
+}