dreamteamer 0.30.0 → 0.32.0

package/src/extensions.js

@@ -0,0 +1,135 @@
+// Engine extensions — the ONE seam an optional tool plugs into.
+//
+// Core is records + the workspace compiler, and nothing that has a lifecycle of its own: an HTTP
+// server, a Docker host, a behaviour-test runner, an exporter to one vendor. Those ship as sibling
+// packages, and a workspace opts into one by DEPENDING on it — a direct dependency whose package.json
+// declares `"dreamteamer": { "extension": "./entry.js" }`. That is the whole declaration: npm already
+// put the code there on purpose, and a transitive package is never loaded however it advertises.
+//
+// The entry's default export is `activate(dt)` — `dt` is the RUNNING engine's public API (api.js), so
+// an extension never imports a second engine copy of its own and can never disagree with the one the
+// operator ran (the dev-clone shadow and `--vault` both pick the engine before this file loads).
+// A workspace's own `modules/<id>/` may declare the same key: its code is the operator's, so it
+// loads without a package — the way a workspace carries an extension nobody has published.
+// It returns a contribution, every key optional:
+//
+//   commands    { <verb>: { usage, run(ws, argv) } }       `dt <verb> …`, dispatched in-process
+//   sourceKinds [{ kind, exclude?: [subtree] }]             folders compile stages like a built-in kind
+//   analyze     (draft) → { errors?, warnings?, notes? }    judged after assembly, before any output
+//   harnesses   { <id>: (ctx) → { blocks: {file: text}, summary } }   a harness adapter
+//   orientation string                                      one paragraph appended to the orientation block
+//   hooks       { <ClaudeHookEvent>: '<dt verb args>' }     rendered by `dt install --print-adapters`
+//
+// Two contributions claiming the same verb, kind or harness is a refusal — there is no "last one
+// wins", because the loser would be an extension the operator installed that silently does nothing.
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const EXTENSION_API = 1;
+
+const CONTRIBUTION_KEYS = new Set(['commands', 'sourceKinds', 'analyze', 'harnesses', 'orientation', 'hooks']);
+
+/** The modules that declare an extension entry: the workspace's own `modules/<id>/` first, then its
+ *  direct dependencies, each sorted by name. A workspace module is the operator's own code, exactly
+ *  like its `bin/`, so it needs no package and no npm — and it SHADOWS a dependency of the same name,
+ *  the rule module content already follows. A module DISABLED by a bare `dreamteamer.disable` entry
+ *  is not an extension either — disabling is how a workspace keeps a module and switches it off. */
+export function declaredExtensions(ws) {
+	const disable = ws.pkg?.dreamteamer?.disable ?? [];
+	const out = [];
+	const seen = new Set();
+	const consider = (dir, fallback) => {
+		let pkg;
+		try { pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch { return; }
+		const entry = pkg.dreamteamer?.extension;
+		const name = pkg.name ?? fallback;
+		if (!entry || seen.has(name) || disablesPackage(disable, name)) return;
+		if (typeof entry !== 'string') throw new Error(`${name}: dreamteamer.extension must be a path to the entry module (got ${JSON.stringify(entry)})`);
+		seen.add(name);
+		out.push({ name, version: pkg.version ?? '0.0.0', dir, entry: path.join(dir, entry) });
+	};
+	let inline = [];
+	try { inline = fs.readdirSync(path.join(ws.root, 'modules')).sort(); } catch { /* no modules/ */ }
+	for (const id of inline) consider(path.join(ws.root, 'modules', id), id);
+	for (const dep of Object.keys({ ...ws.pkg?.dependencies, ...ws.pkg?.devDependencies }).sort()) consider(path.join(ws.root, 'node_modules', dep), dep);
+	return out;
+}
+
+/**
+ * Does a `dreamteamer.disable` list switch off the WHOLE package `name`? An entry names a package by
+ * 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
+ * bare id was compared against the full name — so neither spelling could disable a scoped package.
+ * Every extension this project ships is scoped.
+ */
+export function disablesPackage(disable, name) {
+	const id = String(name).replace(/^@[^/]+\//, '');
+	return (disable ?? []).some((d) => typeof d === 'string' && (d === name || d === id));
+}
+
+/** Is a `dreamteamer.disable` entry a whole-package name rather than `<module>/<entity>`? A bare
+ *  word, or a scoped npm name (`@scope/name` — one slash, leading `@`). */
+export const isPackageEntry = (d) => typeof d === 'string' && (!d.includes('/') || /^@[^/]+\/[^/]+$/.test(d));
+
+/**
+ * Import and activate every declared extension against `api`, and check the contributions cannot
+ * collide with core or with each other. `reserved` is what core already owns: its verbs, kinds and
+ * harness ids.
+ */
+export async function loadExtensions(ws, api, reserved = {}) {
+	const loaded = [];
+	const owner = { command: new Map(), kind: new Map(), harness: new Map() };
+	for (const r of reserved.verbs ?? []) owner.command.set(r, 'the engine');
+	for (const r of reserved.kinds ?? []) owner.kind.set(r, 'the engine');
+	for (const r of reserved.harnesses ?? []) owner.harness.set(r, 'the engine');
+	const claim = (what, key, by) => {
+		const prev = owner[what].get(key);
+		if (prev) throw new Error(`extension ${by} contributes the ${what} "${key}", which ${prev} already owns — uninstall one, or switch it off: add "${by}" to dreamteamer.disable in package.json`);
+		owner[what].set(key, by);
+	};
+	for (const ext of declaredExtensions(ws)) {
+		let mod;
+		try { mod = await import(pathToFileURL(ext.entry).href); } catch (e) {
+			throw new Error(`extension ${ext.name}: its entry ${path.relative(ws.root, ext.entry)} did not load — ${e.message.split('\n')[0]} (npm install?)`);
+		}
+		if (typeof mod.default !== 'function') throw new Error(`extension ${ext.name}: ${path.relative(ws.root, ext.entry)} must default-export activate(dt)`);
+		if (mod.apiVersion !== undefined && mod.apiVersion !== EXTENSION_API) {
+			throw new Error(`extension ${ext.name} targets extension API ${mod.apiVersion}; this engine (${api.engineVersion?.() ?? '?'}) speaks ${EXTENSION_API}`);
+		}
+		const c = (await mod.default(api)) ?? {};
+		for (const k of Object.keys(c)) if (!CONTRIBUTION_KEYS.has(k)) throw new Error(`extension ${ext.name} contributes an unknown key "${k}" — known: ${[...CONTRIBUTION_KEYS].join(', ')}`);
+		const commands = c.commands ?? {};
+		for (const [verb, cmd] of Object.entries(commands)) {
+			if (typeof cmd?.run !== 'function') throw new Error(`extension ${ext.name}: command "${verb}" has no run(ws, argv)`);
+			claim('command', verb, ext.name);
+		}
+		const sourceKinds = (c.sourceKinds ?? []).map((k) => normalizeKind(ext.name, k));
+		for (const k of sourceKinds) claim('kind', k.kind, ext.name);
+		for (const id of Object.keys(c.harnesses ?? {})) claim('harness', id, ext.name);
+		if (c.analyze !== undefined && typeof c.analyze !== 'function') throw new Error(`extension ${ext.name}: analyze must be a function`);
+		loaded.push({ name: ext.name, version: ext.version, commands, sourceKinds, analyze: c.analyze ?? null, harnesses: c.harnesses ?? {}, orientation: c.orientation ?? null, hooks: c.hooks ?? {} });
+	}
+	return loaded;
+}
+
+/** A contributed source kind: a plain folder name, and excluded subtrees that stay RELATIVE to it. */
+function normalizeKind(by, k) {
+	const kind = typeof k === 'string' ? k : k?.kind;
+	if (typeof kind !== 'string' || !/^[a-z][a-z0-9-]*$/.test(kind)) throw new Error(`extension ${by}: a source kind is a lowercase folder name (got ${JSON.stringify(kind)})`);
+	const exclude = (typeof k === 'object' ? k.exclude ?? [] : []).map((e) => {
+		const rel = path.posix.normalize(String(e)).replace(/\/+$/, '');
+		if (!rel || rel === '.' || rel.startsWith('..') || path.posix.isAbsolute(rel)) throw new Error(`extension ${by}: kind "${kind}" excludes "${e}", which is not a subtree of it`);
+		return rel;
+	});
+	return { kind, exclude, extension: by };
+}
+
+/** Is `relFromKind` (a '/'-separated path under the kind folder) inside one of its excluded subtrees? */
+export function excludedFromKind(kinds, kind, relFromKind) {
+	const k = kinds.find((x) => x.kind === kind);
+	return !!k && k.exclude.some((e) => relFromKind === e || relFromKind.startsWith(`${e}/`));
+}

package/src/filter.js

@@ -99,7 +99,7 @@ export function unknownOperators(filter, found = new Set()) {
 	return found;
 }
 
-// exported because `prove`'s enum validation has to compare the way THIS module compares: a proof's
+// exported (through the public API) because a proof runner's enum validation has to compare the way THIS module compares: a proof's
 // `_eq: '5'` against a numeric enum member 5 is one filter at run time, and a strict `includes`
 // there refused a proof that works — worse than the silent pass it was written to prevent.
 export const looseEq = (v, o) => v === o || String(v) === String(o) || (typeof v === 'number' && Number(o) === v);

package/src/harnesses.js

@@ -14,14 +14,14 @@ 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', 'notebooklm'];
+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>/ -->';
 
 // ⚠ THE VALUES ARE A CONTRACT, not an implementation detail: every managed root file on every disk
-// already carries these two exact strings, and `dt land` classifies a rebase conflict by asking
-// whether its hunks lie between them (src/land.js). Changing a byte orphans every block ever
-// written and silently reclassifies a generated conflict as the operator's own prose.
+// 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 -->';
 
@@ -31,7 +31,46 @@ export const END = '<!-- dreamteamer:end -->';
 export const INSTRUCTIONS_BEGIN = '<!-- dreamteamer:instructions:begin -->';
 export const INSTRUCTIONS_END = '<!-- dreamteamer:instructions:end -->';
 
-export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown', workspaceModule = '' }) {
+/** Both managed blocks as data, for a tool that has to recognise generated text in a user-owned file
+ *  (a merge tool resolving a conflict) without importing marker strings from an internal module. The
+ *  files carrying them are the manifest's `adapter-blocks`. */
+export const MANAGED_BLOCKS = Object.freeze([
+	Object.freeze({ id: 'orientation', begin: BEGIN, end: END }),
+	Object.freeze({ id: 'instructions', begin: INSTRUCTIONS_BEGIN, end: INSTRUCTIONS_END }),
+]);
+
+/**
+ * Run every piece of EXTENSION code the harness pass needs — contributed renderers and orientation
+ * paragraphs — and return plain data. Compile calls this BEFORE it replaces a single runtime byte: a
+ * renderer that throws used to do so halfway through materialization, leaving new descriptors beside
+ * the old manifest (review F7). Anything invalid is refused here with the extension's name.
+ */
+export function renderContributions({ entries, harnesses, version = 'unknown', extensions = [] }) {
+	const rendered = [];
+	const paragraphs = [];
+	for (const e of extensions) {
+		const where = (what) => `extension ${e.name}: ${what}`;
+		try {
+			const p = typeof e.orientation === 'function' ? e.orientation({ entries }) : e.orientation;
+			if (typeof p === 'string' && p.trim()) paragraphs.push(p);
+		} catch (err) { throw new Error(where(`orientation failed — ${err.message}`)); }
+		for (const [id, render] of Object.entries(e.harnesses ?? {})) {
+			if (!harnesses.includes(id)) continue;
+			let out;
+			try { out = render({ entries, version, collections: buildCollectionsIndex(entries), modules: buildModulesIndex(entries) }) ?? {}; }
+			catch (err) { throw new Error(where(`harness "${id}" failed — ${err.message}`)); }
+			for (const [file, content] of Object.entries(out.blocks ?? {})) {
+				const norm = path.posix.normalize(file);
+				if (path.isAbsolute(file) || norm.startsWith('..') || norm.includes('/../')) throw new Error(where(`harness "${id}" writes "${file}", which is not a path inside the workspace`));
+				if (content != null && typeof content !== 'string') throw new Error(where(`harness "${id}" returned a ${typeof content} block for ${file} — a block is text, or null to remove it`));
+			}
+			rendered.push([id, out]);
+		}
+	}
+	return { rendered, paragraphs };
+}
+
+export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sourceLayout = 'flat', namespaces = [], version = 'unknown', workspaceModule = '', extensions = [], kinds = [], contributions = renderContributions({ entries, harnesses, version, extensions }) }) {
 	const outputs = [];
 	// ⚠ SEPARATE from `outputs`: these are USER-OWNED root files carrying a managed block, and the
 	// prune loop below DELETES anything in a previous manifest's `adapter-outputs` that this compile
@@ -49,11 +88,18 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		outputs.push(out);
 	};
 
+	// a harness an EXTENSION adapts (`harnesses: { <id>: render }`) is known exactly while it is installed
+	const contributed = new Map(extensions.flatMap((e) => Object.entries(e.harnesses ?? {})));
+	const known = [...KNOWN_HARNESSES, ...contributed.keys()];
 	for (const h of harnesses) {
-		if (!KNOWN_HARNESSES.includes(h)) console.warn(`⚠ unknown harness "${h}" in dreamteamer.harnesses — skipped (known: ${KNOWN_HARNESSES.join(', ')})`);
+		if (!known.includes(h)) console.warn(`⚠ unknown harness "${h}" in dreamteamer.harnesses — skipped (known: ${known.join(', ')})`);
 	}
 	const on = (h) => harnesses.includes(h);
 	const skillsIndex = buildSkillsIndex(entries);
+	// what every orientation block carries beyond the schema: the source kinds extensions add, and the
+	// one paragraph each may contribute about itself
+	const extra = { kinds, paragraphs: contributions.paragraphs };
+	const orient = (flavor) => orientationBlock(flavor, skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule, extra);
 
 	// ---- claude-code: native skills/agents/commands dirs + CLAUDE.md block ----------
 	if (on('claude-code')) {
@@ -73,7 +119,7 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		}
 		summary.push(`claude-code → .claude (${n} files)`);
 	}
-	block('CLAUDE.md', on('claude-code') ? orientationBlock('claude-code', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
+	block('CLAUDE.md', on('claude-code') ? orient('claude-code') : 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.
@@ -90,12 +136,12 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	}
 
 	// ---- codex + pi: both read root AGENTS.md; one block serves both ----------------
-	block('AGENTS.md', on('codex') || on('pi') ? orientationBlock('agents-md', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
+	block('AGENTS.md', on('codex') || on('pi') ? orient('agents-md') : 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 -----------------------------------
-	block('GEMINI.md', on('gemini-cli') ? orientationBlock('gemini', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule) : null);
+	block('GEMINI.md', on('gemini-cli') ? orient('gemini') : null);
 	if (on('gemini-cli')) summary.push('gemini-cli → GEMINI.md block');
 
 	// ---- the operator's own rules, one source, every harness -------------------------
@@ -125,18 +171,25 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 		// ⚠ `.mdc` is written WHOLE by `write()`, not through `writeBlock`, so removal is automatic: a
 		// compile with no dreamteamer.md simply rewrites the file without the part.
 		const instructionsPart = instructions ? `${INSTRUCTIONS_BEGIN}\n${instructions}\n${INSTRUCTIONS_END}\n\n` : '';
-		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${instructionsPart}${orientationBlock('cursor', skillsIndex, sourceLayout, namespaces, version, entries, workspaceModule)}\n\n${STAMP}\n`;
+		const mdc = `---\ndescription: dreamteamer workspace orientation (generated)\nalwaysApply: true\n---\n\n${instructionsPart}${orient('cursor')}\n\n${STAMP}\n`;
 		write('.cursor/rules/dreamteamer.mdc', Buffer.from(mdc));
 		summary.push('cursor → .cursor/rules/dreamteamer.mdc');
 	}
 
-	// ---- notebooklm: NOTEBOOKLM.md carries the notebook's CONFIGURATION ---------------
-	// Not an orientation block: NotebookLM does not read a context file and has no skills. What it
-	// needs is a persona to paste, a response length to pick, and the limits that decide how the
-	// workspace has to be cut up — and all three go stale as collections come and go, which is why
-	// this is generated on compile rather than written once by hand.
-	block('NOTEBOOKLM.md', on('notebooklm') ? notebooklmBlock(entries, version) : null);
-	if (on('notebooklm')) summary.push('notebooklm → NOTEBOOKLM.md block');
+	// ---- harnesses an extension adapts --------------------------------------------------
+	// A contributed adapter returns managed BLOCKS for user-owned files — never whole files, which
+	// would need an ownership story of their own. Read-only indexes are handed in so an adapter never
+	// re-parses the entries this module already parsed.
+	for (const [id, out] of contributions.rendered) {
+		for (const [file, content] of Object.entries(out.blocks ?? {})) block(file, content);
+		summary.push(out.summary ?? `${id} → ${Object.keys(out.blocks ?? {}).join(', ') || 'nothing'}`);
+	}
+	// A block this compile did NOT write, in a file a previous compile did, belongs to a harness that
+	// was switched off or an extension that was uninstalled: remove it, exactly as a built-in
+	// harness's own `block(file, null)` does. The file is the operator's; only the block goes.
+	for (const file of prevManifest?.['adapter-blocks'] ?? []) {
+		if (!blocks.includes(file) && !['CLAUDE.md', 'AGENTS.md', 'GEMINI.md'].includes(file)) writeBlock(root, file, null);
+	}
 
 	// ---- prune: anything WE stamped that this compile didn't produce ------------------
 	const current = new Set(outputs);
@@ -158,103 +211,6 @@ export function runHarnessAdapters({ root, entries, harnesses, prevManifest, sou
 	return { outputs, blocks, summary };
 }
 
-/** Sources a notebook holds, per plan — Google's published table, read 2026-09. Stated here because
- *  the number decides the SHAPE of the export: a workspace with more collections than the plan has
- *  slots has to be narrowed or packed, and that is a decision the operator makes before running
- *  anything. */
-const NOTEBOOK_PLANS = [
-	['standard', 50, 50], ['plus', 100, 200], ['pro', 300, 500], ['ultra', 600, 2500],
-];
-
-/** The notebook's configuration, generated: what to paste as custom instructions, which settings to
- *  pick, and the limits that bind. Derived from the compiled DESCRIPTORS only — never from `data/`,
- *  for the same reason the orientation block carries no record counts: this lands in a committed file
- *  and a count would re-dirty it on every write. */
-function notebooklmBlock(entries, version) {
-	const index = buildCollectionsIndex(entries);
-	const modules = buildModulesIndex(entries);
-	// ⚠ `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);
-
-	// grouped by module from the COLLECTIONS index, which carries each collection's owning module —
-	// `buildModulesIndex` deliberately reports skills, commands and bin, not collections
-	const title = new Map(modules.map((m) => [m.id, m.title]));
-	const byModule = new Map();
-	for (const c of data) {
-		const k = c.module || '';
-		if (!byModule.has(k)) byModule.set(k, []);
-		byModule.get(k).push(c.name);
-	}
-	const brief = [...byModule]
-		.sort((a, b) => (title.get(a[0]) || a[0]).localeCompare(title.get(b[0]) || b[0]))
-		.map(([mod, names]) => `- ${title.get(mod) || mod || 'the workspace'}: ${names.sort().map((c) => (withheldCollections.includes(c) ? `${c} (withheld)` : c)).join(', ')}`);
-
-	const persona = [
-		'You are the reference desk for this workspace. Every source is ONE COLLECTION of it, and every row or section is one record. Answer only from the sources.',
-		'',
-		'A record is cited as `<collection>/<id>`. A field holding a reference contains exactly that form, so `leads.company = companies/acme` means the record `acme` in the `companies` source — follow those links across sources rather than guessing. A source whose name ends `--01`, `--02` is one collection split across files purely for size; treat the parts as one collection.',
-		'',
-		'What this workspace keeps, by module:',
-		...brief,
-		'',
-		withheldCollections.length || withheldFields.length
-			? `Deliberately NOT here: ${[...withheldCollections.map((c) => `the whole collection ${c}`), ...withheldFields].join('; ')}. If asked about them, say they were withheld from the export rather than inferring.`
-			: 'Nothing has been withheld from this export.',
-		'',
-		'Ground every claim in a record and name it. When the question is a table question — which rows match, what is overdue, everything about one company — read down the column and give the matching records, not a summary. When the sources do not hold the answer, say so plainly: "this workspace does not record that" is a useful answer.',
-	].join('\n');
-
-	const lines = [
-		'NOTEBOOKLM — the configuration for a notebook over this workspace. NotebookLM reads no context',
-		'file and runs no skills, so unlike the other harnesses nothing here is injected: it is applied,',
-		`once per notebook, and re-pasted when the schema changes. Regenerated by every \`dreamteamer compile\` (engine ${version}).`,
-		'',
-		'## settings',
-		'',
-		'| setting | value | why |',
-		'|---|---|---|',
-		'| response length | **longer** | records are terse; the useful answer quotes several and says which |',
-		'| chat mode | **do not set one** | `--mode` REPLACES the persona — see the warning below |',
-		'',
-		'```bash',
-		'notebooklm configure -n <notebook-id> --response-length longer \\',
-		'  --persona "$(sed -n \'/^## custom instructions/,/^## limits/p\' NOTEBOOKLM.md | sed \'1,2d;$d\')"',
-		'```',
-		'',
-		'⚠ **`configure` REPLACES the whole configuration on every call, and passing `--mode` with a persona silently discards the persona.** Measured: `--persona … --response-length longer --mode default` answers `{mode: "default", configured: true}` at exit 0, with the persona and the response length gone; the identical call without `--mode` returns both. There is also no read-only inspection — a bare `configure`, the obvious way to check the current settings, CLEARS them. So send every setting you want in ONE call, never `--mode` alongside a persona, and keep the persona in a file rather than only in the notebook.',
-		'',
-		'## custom instructions',
-		'',
-		persona,
-		'',
-		'## limits',
-		'',
-		'| plan | sources per notebook | chats per day |',
-		'|---|---|---|',
-		...NOTEBOOK_PLANS.map(([n, s, c]) => `| ${n} | ${s} | ${c} |`),
-		'',
-		`This workspace exports **${exported.length} collections**${withheldCollections.length ? ` (${withheldCollections.length} withheld)` : ''}, so one source per collection needs a plan with at least that many slots — before any collection is split.`,
-		'',
-		'- **Per source:** 500,000 words or 200 MB, per Google. ⚠ A CSV source fails well below that: measured on a large private workspace, files at or under 805,081 bytes indexed and files at or above 881,828 bytes did not, so 700,000 bytes is the working ceiling.',
-		'- **Persona:** 10,000 characters. The block above is generated to stay inside it; adding to it by hand can push it over, and `configure` refuses the whole call rather than truncating.',
-		'- **Auto-sync follows native Google Docs, Sheets and Slides only.** An uploaded file — CSV, PDF, Markdown — is a SNAPSHOT: re-export means re-adding those sources.',
-		'- ⚠ **`source add` reports success whether or not the file indexes.** Read `source list --json` back and require `type` to be the format you uploaded; a source that failed reads `type: unknown, status: error` with no message anywhere.',
-		'- ⚠ **An answer is real only with non-blank text AND at least one reference.** Exit 0 with an empty answer is a real outcome, reached by scoping a broad question with `-s`.',
-	];
-	return lines.join('\n');
-}
-
 // 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) {
@@ -295,7 +251,6 @@ function buildCollectionsIndex(entries) {
 			// the domain listing — the visible failure rather than the silent one.
 			systemGroup: d.group === 'system',
 			generated: d.storage?.base === 'runtime',
-			driver: d.storage?.driver ?? null,
 			description: flat(d.description),
 			useWhen: flat(d.use_when),
 			module: d.module ?? '',
@@ -336,18 +291,16 @@ function buildModulesIndex(entries) {
 		let d = {};
 		try { d = load(e.bytes.toString('utf8')) ?? {}; } catch { /* unparseable record */ }
 		const p = !d.path || d.path === '.' ? '' : `${d.path}/`;
-		mods.push({ id: m[1], title: d.title ?? m[1], description: flat(d.description), namespaces: d.namespaces ?? [], path: p, bin: d.bin ?? [], skills: [], commands: [], proofs: [] });
+		mods.push({ id: m[1], title: d.title ?? m[1], description: flat(d.description), namespaces: d.namespaces ?? [], path: p, bin: d.bin ?? [], skills: [], commands: [] });
 	}
 	mods.sort((a, b) => b.path.length - a.path.length); // longest prefix first
 	for (const [rt, e] of entries) {
-		const kind = /^skills\/([^/]+)\/SKILL\.md$/.exec(rt) ? 'skills' : /^commands\/(.+)\.command\.md$/.exec(rt) ? 'commands' : /^proofs\/(.+)\.proof\.yaml$/.exec(rt) ? 'proofs' : null;
+		const kind = /^skills\/([^/]+)\/SKILL\.md$/.exec(rt) ? 'skills' : /^commands\/(.+)\.command\.md$/.exec(rt) ? 'commands' : null;
 		if (!kind) continue;
 		const src = e.sources?.[0]?.path ?? '';
 		const owner = mods.find((mod) => src.startsWith(mod.path));
-		if (owner) owner[kind].push(kind === 'skills' ? rt.split('/')[1] : path.basename(rt).replace(/\.(command\.md|proof\.yaml)$/, ''));
+		if (owner) owner[kind].push(kind === 'skills' ? rt.split('/')[1] : path.basename(rt).replace(/\.command\.md$/, ''));
 	}
-	// `proofs` is COUNTED, never listed (see the module filter below), so it is deliberately not
-	// sorted — an order nothing reads is work that reads as a promise the output does not keep.
 	for (const mod of mods) { mod.skills.sort(); mod.commands.sort(); }
 	return mods;
 }
@@ -404,7 +357,7 @@ function collectionsSection(index, modules, workspaceModule) {
 	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.systemGroup) || (!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)); })
 		.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(' · ')}`] : [])];
@@ -419,10 +372,7 @@ function collectionsSection(index, modules, workspaceModule) {
 	}
 	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 && !c.driver).map((c) => c.name);
-	// A DRIVER collection is neither build output nor files: its verbs are answered by a driver over
-	// something that runs (Docker), so it gets its own clause rather than being called either.
-	const driven = sys.filter((c) => c.driver).map((c) => `${c.name} (${c.driver})`);
+	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
@@ -432,7 +382,7 @@ function collectionsSection(index, modules, workspaceModule) {
 	// 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(' · ')}.` : ''}${driven.length ? ` Answered by a DRIVER, not files — nothing under data/, nothing to commit, the same verbs plus start · stop · open: ${driven.join(' · ')}` : ''}`);
+		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;
 }
@@ -523,7 +473,7 @@ function bindingsSection(entries) {
  *  agent that splits `health/doctors/dana-levi` at the first slash reads a collection that does not
  *  exist. Naming the declared list is what makes the grammar decidable from this block alone, without
  *  the agent having to go read the manifest. A workspace with no namespaces gets no extra sentence. */
-function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown', entries = new Map(), workspaceModule = '') {
+function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces = [], version = 'unknown', entries = new Map(), workspaceModule = '', extra = { kinds: [], paragraphs: [] }) {
 	const sourcesLine = {
 		flat: '`modules/<module>/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
 		nested: '`modules/<module>/system/<kind>/` — `collections/`, `skills/`, `agents/`, `commands/`,',
@@ -538,17 +488,14 @@ function orientationBlock(flavor, skillsIndex, sourceLayout = 'flat', namespaces
 		'nouns. **read the `using-dreamteamer` skill before working with data or changing what the',
 		'workspace keeps or does.** schemas (read): `.dreamteamer/collections/` (provenance:',
 		'`.dreamteamer/manifest.yaml`). sources (write): ' + sourcesLine,
-		'`command-bindings/`, `ui-views/`, `collection-templates/`, `proofs/`',
+		`\`command-bindings/\`, \`ui-views/\`, \`collection-templates/\`${extra.kinds.map((k) => `, \`${k}/\``).join('')}`,
 		'(see manifest for channels). data: `data/`. 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',
-		// ⚠ ONE sentence, APPENDED to the line above rather than given one of its own: this block is
-		// committed prose in every workspace and its budget is asserted (compile.test.js, "a workspace
-		// that has added nothing gets a SMALL block"), so a clause that earns its place still may not
-		// spend a line. It says the one thing a session cannot derive from the schema — that a claim
-		// an artifact works is a claim about the RUNNING system, and which instrument produces one.
-		'source or installing modules. before saying an artifact works, run `dreamteamer prove <artifact>` and quote its result.',
+		'source or installing modules.',
 	];
+	// an installed extension's own paragraph — how an optional tool tells every session it exists
+	for (const p of extra.paragraphs) lines.push(p.trim());
 	// ⚠ Only when the workspace HAS namespaces. Telling an agent about a feature this workspace does
 	// not use is the same failure as telling it the wrong source layout — prose that contradicts the
 	// workspace is worse than no prose.
@@ -647,7 +594,7 @@ function pruneEmptyDirs(dir) {
 	for (const name of fs.readdirSync(dir)) {
 		// ⚠ a LIVE linked worktree may sit at `.claude/worktrees/<name>` — a harness can park one
 		// there itself. Its empty directories belong to whoever checked it out; compile must never
-		// walk it. (`dt land` places worktrees under `.worktrees/` for the same reason.)
+		// walk it. (the workflows extension places worktrees under `.worktrees/` for the same reason.)
 		if (name === 'worktrees' && path.basename(dir) === '.claude') continue;
 		const p = path.join(dir, name);
 		if (fs.statSync(p).isDirectory()) pruneEmptyDirs(p);

package/src/init.js

@@ -154,13 +154,19 @@ export function init({ flags = {} } = {}) {
 	ensureEditorRecommendation(root);
 	if (!fs.existsSync(path.join(root, '.env.example'))) fs.writeFileSync(path.join(root, '.env.example'), ENV_EXAMPLE);
 
-	// one init commit (if we're in a git repo)
+	// one init commit (if we're in a git repo) — of the files init WROTE, and nothing else. It used to
+	// `git add --all`, which in an existing repo swept every unrelated staged and unstaged change into
+	// a commit titled "init workspace": the one write in this engine that was not pathspec-scoped.
+	// `commit -- <paths>` also leaves anything the operator had already staged exactly as it was.
+	const written = ['package.json', '.gitignore', '.env.example', '.vscode/extensions.json',
+		...(wm ? [path.join('modules', wm, 'package.json')] : []), path.relative(root, starter)]
+		.filter((f) => fs.existsSync(path.join(root, f)));
 	try {
 		// stdio ignored on purpose: this whole block is best-effort, and execFileSync forwards the
 		// child's stderr to ours by default — so a plain `dreamteamer init` in a non-git folder
 		// printed git's raw "fatal: not a git repository" above our own handled warning.
-		execFileSync('git', ['add', '--all'], { cwd: root, stdio: 'ignore' });
-		execFileSync('git', ['commit', '--quiet', '-m', `dreamteamer: init workspace ${name}`], { cwd: root, stdio: 'ignore' });
+		execFileSync('git', ['add', '--', ...written], { cwd: root, stdio: 'ignore' });
+		execFileSync('git', ['commit', '--quiet', '-m', `dreamteamer: init workspace ${name}`, '--', ...written], { cwd: root, stdio: 'ignore' });
 	} catch { console.warn('⚠ not a git repo (or nothing to commit) — init files written, no commit'); }
 
 	console.log(`✔ workspace ${name} initialized — run \`dreamteamer compile\` to materialize the runtime`);