@mindflight/mindbrain-personal-studio 0.6.1

package/scripts/create-serenity-production-v6.mjs

@@ -0,0 +1,627 @@
+#!/usr/bin/env node
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const SOURCE_WORKSPACE = 'serenity-production-v5';
+const TARGET_WORKSPACE = 'serenity-production-v6';
+const REVIEW_WORKSPACES = ['serenity-v4', 'serenity-v4-s2'];
+const DEFAULT_DB = '/home/dlamotte/.ghostcrab/databases/ghostcrab-serenity-v4-demos.sqlite';
+const DEFAULT_OUT_DIR = 'docs/demo/export-audit/2026-06-26/serenity-production-v6-migration';
+const ENTITY_OFFSET = 1_000_000;
+const RELATION_OFFSET = 1_000_000;
+
+const args = new Set(process.argv.slice(2));
+const apply = args.has('--apply');
+const dbPath = valueAfter('--db') ?? process.env.GHOSTCRAB_SQLITE_PATH ?? DEFAULT_DB;
+const outDir = valueAfter('--out-dir') ?? DEFAULT_OUT_DIR;
+
+function valueAfter(flag) {
+	const index = process.argv.indexOf(flag);
+	return index >= 0 ? process.argv[index + 1] : null;
+}
+
+function runSql(sql, { json = false, readonly = false } = {}) {
+	const argv = [];
+	if (readonly) argv.push('-readonly');
+	if (json) argv.push('-json');
+	argv.push(dbPath, sql);
+	const result = spawnSync('sqlite3', argv, { encoding: 'utf8', maxBuffer: 1024 * 1024 * 128 });
+	if (result.status !== 0) {
+		throw new Error(result.stderr || result.stdout || `sqlite3 failed for ${sql.slice(0, 120)}`);
+	}
+	return json ? JSON.parse(result.stdout || '[]') : result.stdout;
+}
+
+function runSqlFile(sql) {
+	const result = spawnSync('sqlite3', [dbPath], {
+		encoding: 'utf8',
+		input: sql,
+		maxBuffer: 1024 * 1024 * 128
+	});
+	if (result.status !== 0) {
+		throw new Error(result.stderr || result.stdout || 'sqlite3 transaction failed');
+	}
+	return result.stdout;
+}
+
+function quote(value) {
+	if (value === null || value === undefined) return 'NULL';
+	if (typeof value === 'number') return Number.isFinite(value) ? String(value) : 'NULL';
+	return `'${String(value).replaceAll("'", "''")}'`;
+}
+
+function replaceText(value) {
+	if (value === null || value === undefined) return value;
+	return String(value)
+		.replaceAll('serenity-production-v5', TARGET_WORKSPACE)
+		.replaceAll('serenity_production_v5', 'serenity_production_v6')
+		.replaceAll('Serenity Production V5', 'Serenity Production V6');
+}
+
+function replaceOrPrefixId(value, prefix) {
+	const replaced = replaceText(value);
+	if (replaced === null || replaced === undefined) return replaced;
+	return replaced === String(value) ? `${prefix}:${TARGET_WORKSPACE}:${value}` : replaced;
+}
+
+function insert(table, columns, row) {
+	const values = columns.map((column) => quote(row[column])).join(', ');
+	return `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${values});`;
+}
+
+function rows(sql) {
+	return runSql(sql, { json: true, readonly: true });
+}
+
+function cloneRows(table, columns, sourceRows, mapRow) {
+	return sourceRows.map((row, index) => insert(table, columns, mapRow(row, index)));
+}
+
+function objectMapValues(obj, fn) {
+	return Object.fromEntries(Object.entries(obj).map(([key, value]) => [key, fn(value, key)]));
+}
+
+function cloneSimpleTextRow(row, overrides = {}) {
+	return { ...objectMapValues(row, replaceText), ...overrides };
+}
+
+function sqlIn(values) {
+	return values.map(quote).join(', ');
+}
+
+function ensureNoTargetWorkspace() {
+	const existing = rows(
+		`SELECT workspace_id FROM workspaces WHERE workspace_id = ${quote(TARGET_WORKSPACE)} OR id = ${quote(TARGET_WORKSPACE)}`
+	);
+	if (existing.length > 0) {
+		throw new Error(`${TARGET_WORKSPACE} already exists; refusing to overwrite`);
+	}
+}
+
+function readSourceData() {
+	const ontologyIds = rows(
+		`SELECT ontology_id FROM ontologies WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY ontology_id`
+	).map((row) => row.ontology_id);
+	const artifactIds = rows(
+		`SELECT artifact_id FROM mindbrain_answer_artifacts WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY artifact_id`
+	).map((row) => row.artifact_id);
+	return {
+		workspaces: rows(`SELECT * FROM workspaces WHERE workspace_id = ${quote(SOURCE_WORKSPACE)}`),
+		ontologies: rows(`SELECT * FROM ontologies WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY ontology_id`),
+		ontologyEntityTypes: rows(
+			`SELECT * FROM ontology_entity_types WHERE ontology_id IN (${sqlIn(ontologyIds)}) ORDER BY ontology_id, entity_type`
+		),
+		ontologyEdgeTypes: rows(
+			`SELECT * FROM ontology_edge_types WHERE ontology_id IN (${sqlIn(ontologyIds)}) ORDER BY ontology_id, edge_type`
+		),
+		ontologyTriples: rows(
+			`SELECT * FROM ontology_triples_raw WHERE ontology_id IN (${sqlIn(ontologyIds)}) ORDER BY ontology_id, triple_index`
+		),
+		agentFacts: rows(`SELECT * FROM agent_facts WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY id`),
+		graphEntities: rows(`SELECT * FROM graph_entity WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY entity_id`),
+		graphRelations: rows(`SELECT * FROM graph_relation WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY relation_id`),
+		answerArtifacts: rows(
+			`SELECT * FROM mindbrain_answer_artifacts WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} ORDER BY artifact_id`
+		),
+		answerEvents:
+			artifactIds.length === 0
+				? []
+				: rows(
+						`SELECT * FROM mindbrain_answer_events WHERE artifact_id IN (${sqlIn(artifactIds)}) ORDER BY event_id`
+					)
+	};
+}
+
+function buildCloneSql(data) {
+	const statements = [];
+	const entityIdMap = new Map();
+	for (const entity of data.graphEntities) entityIdMap.set(entity.entity_id, entity.entity_id + ENTITY_OFFSET);
+	const relationIdMap = new Map();
+	for (const relation of data.graphRelations) relationIdMap.set(relation.relation_id, relation.relation_id + RELATION_OFFSET);
+
+	statements.push(
+		...cloneRows(
+			'workspaces',
+			[
+				'id',
+				'workspace_id',
+				'label',
+				'pg_schema',
+				'description',
+				'created_by',
+				'status',
+				'domain_profile',
+				'domain_profile_json',
+				'created_at',
+				'updated_at'
+			],
+			data.workspaces,
+			(row) =>
+				cloneSimpleTextRow(row, {
+					id: TARGET_WORKSPACE,
+					workspace_id: TARGET_WORKSPACE,
+					label: 'Serenity Production V6',
+					description:
+						'Clone of Serenity Production V5 prepared for SOP-governed model extension; no V4 relations promoted automatically.'
+				})
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'ontologies',
+			['ontology_id', 'workspace_id', 'name', 'version', 'frozen', 'source_kind', 'metadata_json', 'created_at'],
+			data.ontologies,
+			(row) => cloneSimpleTextRow(row, { workspace_id: TARGET_WORKSPACE })
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'ontology_entity_types',
+			['ontology_id', 'entity_type', 'label', 'metadata_json'],
+			data.ontologyEntityTypes,
+			(row) => cloneSimpleTextRow(row)
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'ontology_edge_types',
+			['ontology_id', 'edge_type', 'directed', 'source_entity_type', 'target_entity_type', 'metadata_json'],
+			data.ontologyEdgeTypes,
+			(row) => cloneSimpleTextRow(row)
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'ontology_triples_raw',
+			[
+				'ontology_id',
+				'triple_index',
+				'subject_kind',
+				'subject',
+				'predicate',
+				'object_kind',
+				'object_value',
+				'object_datatype',
+				'object_language',
+				'source_line',
+				'metadata_json'
+			],
+			data.ontologyTriples,
+			(row) => cloneSimpleTextRow(row)
+		)
+	);
+
+	const maxDocId =
+		rows(`SELECT COALESCE(MAX(doc_id), 0) AS max_doc_id FROM agent_facts`)[0]?.max_doc_id ?? 0;
+	statements.push(
+		...cloneRows(
+			'agent_facts',
+			[
+				'id',
+				'schema_id',
+				'content',
+				'facets',
+				'facets_json',
+				'embedding_blob',
+				'embedding',
+				'created_by',
+				'created_at',
+				'created_at_unix',
+				'updated_at',
+				'updated_at_unix',
+				'version',
+				'supersedes',
+				'valid_from_unix',
+				'valid_until_unix',
+				'workspace_id',
+				'source_ref',
+				'doc_id'
+			],
+			data.agentFacts,
+			(row, index) =>
+				cloneSimpleTextRow(row, {
+					id: replaceOrPrefixId(row.id, 'agent-fact'),
+					workspace_id: TARGET_WORKSPACE,
+					source_ref: row.source_ref ? replaceOrPrefixId(row.source_ref, 'source-ref') : null,
+					doc_id: maxDocId + index + 1
+				})
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'graph_entity',
+			[
+				'entity_id',
+				'workspace_id',
+				'entity_type',
+				'name',
+				'confidence',
+				'deprecated_at',
+				'metadata_json',
+				'created_at_unix'
+			],
+			data.graphEntities,
+			(row) =>
+				cloneSimpleTextRow(row, {
+					entity_id: entityIdMap.get(row.entity_id),
+					workspace_id: TARGET_WORKSPACE
+				})
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'graph_relation',
+			[
+				'relation_id',
+				'workspace_id',
+				'relation_type',
+				'source_id',
+				'target_id',
+				'valid_from_unix',
+				'valid_to_unix',
+				'confidence',
+				'deprecated_at',
+				'run_id',
+				'patch_id',
+				'metadata_json',
+				'created_at_unix'
+			],
+			data.graphRelations,
+			(row) =>
+				cloneSimpleTextRow(row, {
+					relation_id: relationIdMap.get(row.relation_id),
+					workspace_id: TARGET_WORKSPACE,
+					source_id: entityIdMap.get(row.source_id),
+					target_id: entityIdMap.get(row.target_id)
+				})
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'mindbrain_answer_artifacts',
+			[
+				'artifact_id',
+				'slug',
+				'workspace_id',
+				'agent_id',
+				'scope',
+				'artifact_kind',
+				'public_label_key',
+				'public_label',
+				'lifecycle',
+				'state',
+				'current_version',
+				'payload_json',
+				'legacy_ref',
+				'created_at_unix',
+				'updated_at_unix'
+			],
+			data.answerArtifacts,
+			(row) => cloneSimpleTextRow(row, { workspace_id: TARGET_WORKSPACE })
+		)
+	);
+
+	statements.push(
+		...cloneRows(
+			'mindbrain_answer_events',
+			[
+				'event_id',
+				'artifact_id',
+				'event_kind',
+				'from_version',
+				'to_version',
+				'signal_json',
+				'created_at_unix'
+			],
+			data.answerEvents,
+			(row) =>
+				cloneSimpleTextRow(row, {
+					event_id: replaceOrPrefixId(row.event_id, 'answer-event')
+				})
+		)
+	);
+
+	return { entityIdMap, relationIdMap, sql: statements.join('\n') };
+}
+
+function parseJsonField(row, key) {
+	try {
+		return JSON.parse(row[key] || '{}');
+	} catch {
+		return {};
+	}
+}
+
+function stableSources(sourceString) {
+	return String(sourceString || '')
+		.split(',')
+		.filter(Boolean)
+		.sort();
+}
+
+function relationDecision(candidate, supportedByScenarios) {
+	const relation = candidate.relation_type;
+	const sources = stableSources(candidate.sources);
+	const hasScenario = supportedByScenarios.has(relation);
+	const hasOnlyWeakSources =
+		sources.length > 0 &&
+		sources.every((source) =>
+			['fake_data', 'serenity_v4_fake_data_smoke', 'snapshot_claims_evidence_matrix'].includes(source)
+		);
+	const isGeneric = ['referencer', 'supported_by'].includes(relation);
+	if (hasScenario) return 'review_required';
+	if (isGeneric) return 'reject_generic_relation';
+	if (hasOnlyWeakSources) return 'reject_weak_source_only';
+	return 'reject_no_sop_or_scenario';
+}
+
+function buildReviewReports() {
+	const scenarioRows = rows(
+		`SELECT artifact_id, slug, scope, public_label, payload_json
+		 FROM mindbrain_answer_artifacts
+		 WHERE workspace_id = ${quote(SOURCE_WORKSPACE)}
+		   AND artifact_kind = 'analysis_plan'
+		 ORDER BY slug`
+	);
+	const scenarios = scenarioRows.map((row) => {
+		const payload = parseJsonField(row, 'payload_json');
+		return {
+			artifact_id: row.artifact_id,
+			slug: row.slug,
+			scope: row.scope,
+			public_label: row.public_label,
+			workflow: String(payload.description || '').match(/workflow=([^;]+)/)?.[1] ?? null,
+			projection_id: payload.projection_id ?? null,
+			required_edges: Array.isArray(payload.required_edges) ? payload.required_edges : [],
+			required_schemas: Array.isArray(payload.required_schemas) ? payload.required_schemas : [],
+			required_facets: Array.isArray(payload.required_facets) ? payload.required_facets : [],
+			scenario_refs: Array.isArray(payload.scenario_refs) ? payload.scenario_refs : []
+		};
+	});
+	const supportedByEdge = new Map();
+	for (const scenario of scenarios) {
+		for (const edge of scenario.required_edges) {
+			if (!supportedByEdge.has(edge)) supportedByEdge.set(edge, []);
+			supportedByEdge.get(edge).push({
+				artifact_id: scenario.artifact_id,
+				slug: scenario.slug,
+				scope: scenario.scope,
+				workflow: scenario.workflow,
+				scenario_refs: scenario.scenario_refs
+			});
+		}
+	}
+
+	const relationCandidates = rows(
+		`SELECT workspace_id, relation_type, COUNT(*) AS instance_count,
+		        group_concat(DISTINCT json_extract(metadata_json, '$.source')) AS sources,
+		        group_concat(DISTINCT json_extract(metadata_json, '$.linkml_class')) AS linkml_classes
+		 FROM graph_relation
+		 WHERE workspace_id IN (${sqlIn(REVIEW_WORKSPACES)})
+		 GROUP BY workspace_id, relation_type
+		 ORDER BY workspace_id, instance_count DESC, relation_type`
+	).map((candidate) => ({
+		...candidate,
+		decision: relationDecision(candidate, supportedByEdge),
+		supported_scenarios: supportedByEdge.get(candidate.relation_type) ?? [],
+		reason:
+			relationDecision(candidate, supportedByEdge) === 'review_required'
+				? 'Referenced by at least one V5 analysis_plan required_edges entry; requires human SOP review before promotion.'
+				: relationDecision(candidate, supportedByEdge) === 'reject_generic_relation'
+					? 'Relation is too generic to promote without a precise SOP.'
+					: relationDecision(candidate, supportedByEdge) === 'reject_weak_source_only'
+						? 'Relation only appears in weak/generated smoke data sources.'
+						: 'No V5 SOP/scenario required_edges evidence found.'
+	}));
+
+	const acceptedRelations = relationCandidates.filter((candidate) => candidate.decision === 'promote');
+	const reviewRequiredRelations = relationCandidates.filter(
+		(candidate) => candidate.decision === 'review_required'
+	);
+	const rejectedRelations = relationCandidates.filter((candidate) => candidate.decision.startsWith('reject_'));
+
+	const v5SchemaRows = rows(
+		`SELECT COALESCE(NULLIF(json_extract(facets_json, '$.schema_id'), ''),
+		                NULLIF(json_extract(content, '$.schema_id'), ''),
+		                id) AS schema_id
+		 FROM agent_facts
+		 WHERE workspace_id = ${quote(SOURCE_WORKSPACE)} AND schema_id = 'mindbrain:schema'`
+	).map((row) => row.schema_id);
+	const v5SchemaSet = new Set(v5SchemaRows);
+	const requiredSchemas = new Map();
+	for (const scenario of scenarios) {
+		for (const schema of scenario.required_schemas) {
+			const candidates = [
+				schema,
+				`${SOURCE_WORKSPACE}:${schema}`,
+				`${TARGET_WORKSPACE}:${schema}`,
+				replaceText(schema)
+			];
+			const existsInV5 = candidates.some((candidate) => v5SchemaSet.has(candidate));
+			if (!existsInV5) {
+				if (!requiredSchemas.has(schema)) requiredSchemas.set(schema, []);
+				requiredSchemas.get(schema).push({
+					artifact_id: scenario.artifact_id,
+					slug: scenario.slug,
+					scope: scenario.scope,
+					workflow: scenario.workflow
+				});
+			}
+		}
+	}
+	const missingSchemasRequiredBySop = [...requiredSchemas.entries()]
+		.map(([schema_id, required_by]) => ({ schema_id, required_by }))
+		.sort((a, b) => a.schema_id.localeCompare(b.schema_id));
+
+	const summary = {
+		source_workspace: SOURCE_WORKSPACE,
+		target_workspace: TARGET_WORKSPACE,
+		review_workspaces: REVIEW_WORKSPACES,
+		policy: {
+			auto_promote_v4_relations: false,
+			default_relation_decision: 'reject unless supported by SOP/scenario and manually reviewed',
+			sop_source: 'serenity-production-v5 analysis_plan required_edges/workflow/scenario payloads'
+		},
+		counts: {
+			scenarios_reviewed: scenarios.length,
+			relation_candidates: relationCandidates.length,
+			accepted_relations: acceptedRelations.length,
+			review_required_relations: reviewRequiredRelations.length,
+			rejected_relations: rejectedRelations.length,
+			missing_schemas_required_by_sop: missingSchemasRequiredBySop.length
+		}
+	};
+
+	return {
+		summary,
+		scenarioSopMap: scenarios,
+		acceptedRelations,
+		reviewRequiredRelations,
+		rejectedRelations,
+		missingSchemasRequiredBySop
+	};
+}
+
+function writeReports(reports) {
+	mkdirSync(outDir, { recursive: true });
+	for (const [name, value] of Object.entries({
+		'migration-summary.json': reports.summary,
+		'scenario_sop_map.json': reports.scenarioSopMap,
+		'accepted_relations.json': reports.acceptedRelations,
+		'review_required_relations.json': reports.reviewRequiredRelations,
+		'rejected_relations.json': reports.rejectedRelations,
+		'missing_schemas_required_by_sop.json': reports.missingSchemasRequiredBySop
+	})) {
+		writeFileSync(join(outDir, name), `${JSON.stringify(value, null, 2)}\n`);
+	}
+}
+
+function writeMarkdownReport(reports, applied) {
+	const md = `# Serenity Production V6 Migration
+
+Generated with \`scripts/create-serenity-production-v6.mjs${applied ? ' --apply' : ''}\`.
+
+## Policy
+
+- V6 starts as a clone of \`${SOURCE_WORKSPACE}\`.
+- V4/V4-S2 relations are candidates only.
+- No V4 relation is promoted automatically.
+- A relation must be tied to a SOP/scenario before promotion.
+
+## Counts
+
+| Metric | Count |
+|---|---:|
+| V5 scenarios reviewed | ${reports.summary.counts.scenarios_reviewed} |
+| V4/V4-S2 relation candidates | ${reports.summary.counts.relation_candidates} |
+| Accepted relations | ${reports.summary.counts.accepted_relations} |
+| Review-required relations | ${reports.summary.counts.review_required_relations} |
+| Rejected relations | ${reports.summary.counts.rejected_relations} |
+| Missing schemas required by SOP | ${reports.summary.counts.missing_schemas_required_by_sop} |
+
+## Files
+
+- \`migration-summary.json\`
+- \`scenario_sop_map.json\`
+- \`accepted_relations.json\`
+- \`review_required_relations.json\`
+- \`rejected_relations.json\`
+- \`missing_schemas_required_by_sop.json\`
+
+## Apply Status
+
+${applied ? `\`${TARGET_WORKSPACE}\` was created in the SQLite database.` : 'Dry run only; no database writes were performed.'}
+`;
+	writeFileSync(join(outDir, 'README.md'), md);
+}
+
+function countsFor(workspaceId) {
+	const [countRow] = rows(`WITH ws(workspace_id) AS (VALUES(${quote(workspaceId)}))
+		SELECT ws.workspace_id AS workspace,
+		       (SELECT COUNT(*) FROM graph_entity ge WHERE ge.workspace_id=ws.workspace_id) AS graph_entities,
+		       (SELECT COUNT(*) FROM graph_relation gr WHERE gr.workspace_id=ws.workspace_id) AS graph_relations,
+		       (SELECT COUNT(*) FROM ontologies o WHERE o.workspace_id=ws.workspace_id) AS ontologies,
+		       (SELECT COUNT(*) FROM ontology_entity_types et WHERE et.ontology_id IN (SELECT ontology_id FROM ontologies WHERE workspace_id=ws.workspace_id)) AS ontology_entity_types,
+		       (SELECT COUNT(*) FROM ontology_edge_types edge WHERE edge.ontology_id IN (SELECT ontology_id FROM ontologies WHERE workspace_id=ws.workspace_id)) AS ontology_edge_types,
+		       (SELECT COUNT(*) FROM ontology_triples_raw tr WHERE tr.ontology_id IN (SELECT ontology_id FROM ontologies WHERE workspace_id=ws.workspace_id)) AS ontology_triples,
+		       (SELECT COUNT(*) FROM agent_facts af WHERE af.workspace_id=ws.workspace_id) AS agent_facts,
+		       (SELECT COUNT(*) FROM mindbrain_answer_artifacts a WHERE a.workspace_id=ws.workspace_id) AS artifacts
+		FROM ws`);
+	return countRow;
+}
+
+function backupDatabase() {
+	const backupPath = `/tmp/${TARGET_WORKSPACE}-precreate-${new Date().toISOString().replaceAll(':', '-')}.sqlite`;
+	const result = spawnSync('sqlite3', [dbPath, `.backup '${backupPath}'`], { encoding: 'utf8' });
+	if (result.status !== 0) throw new Error(result.stderr || result.stdout || 'sqlite backup failed');
+	return backupPath;
+}
+
+function main() {
+	ensureNoTargetWorkspace();
+	const sourceData = readSourceData();
+	const clone = buildCloneSql(sourceData);
+	const reports = buildReviewReports();
+	reports.summary.source_counts = countsFor(SOURCE_WORKSPACE);
+	reports.summary.target_counts_before = countsFor(TARGET_WORKSPACE);
+	reports.summary.clone_plan = {
+		entity_id_offset: ENTITY_OFFSET,
+		relation_id_offset: RELATION_OFFSET,
+		sql_statement_count: clone.sql.split('\n').filter(Boolean).length
+	};
+	writeReports(reports);
+	writeMarkdownReport(reports, false);
+
+	if (!apply) {
+		console.log(`dry-run ok; wrote reports to ${outDir}`);
+		console.log(JSON.stringify(reports.summary, null, 2));
+		return;
+	}
+
+	const backupPath = backupDatabase();
+	const tx = `.bail on\nPRAGMA foreign_keys=ON;\nBEGIN IMMEDIATE;\n${clone.sql}\nCOMMIT;\n`;
+	runSqlFile(tx);
+	const targetCounts = countsFor(TARGET_WORKSPACE);
+	reports.summary.target_counts_after = targetCounts;
+	reports.summary.backup_path = backupPath;
+	writeReports(reports);
+	writeMarkdownReport(reports, true);
+	console.log(`created ${TARGET_WORKSPACE}`);
+	console.log(`backup: ${backupPath}`);
+	console.log(JSON.stringify(reports.summary, null, 2));
+}
+
+try {
+	main();
+} catch (error) {
+	console.error(error instanceof Error ? error.message : error);
+	process.exit(1);
+}

package/scripts/dev-sqlite.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+	healthOk,
+	loadDotEnv,
+	readRuntimeJson,
+	resolveStudioDataTarget,
+	runtimePathsForSqlite,
+	studioRootFromScript
+} from "./lib/sqlite-runtime.mjs";
+
+const studioRoot = studioRootFromScript(import.meta.url);
+loadDotEnv(studioRoot);
+const { sqlitePath, passthrough, mode, fallbackReason } = resolveStudioDataTarget(studioRoot, process.argv.slice(2));
+const paths = runtimePathsForSqlite(studioRoot, sqlitePath);
+const explicitUrl = process.env.MINDBRAIN_HTTP_URL?.trim() || process.env.GHOSTCRAB_MINDBRAIN_URL?.trim();
+const runtime = readRuntimeJson(paths.jsonPath);
+const baseUrl = explicitUrl || runtime?.base_url;
+
+if (!existsSync(sqlitePath)) {
+	console.error(`error: SQLite not found at ${sqlitePath}`);
+	console.error("Pass --sqlite /path/to/db.sqlite, or set GHOSTCRAB_SQLITE_PATH.");
+	process.exit(1);
+}
+
+if (fallbackReason) {
+	console.error(`==> ${fallbackReason}; using packaged demo fixture.`);
+}
+
+if (mode === "sqlite-demo") {
+	console.error(`==> Studio dev demo | SQLite: ${sqlitePath}`);
+	const child = spawn(process.execPath, ["./node_modules/vite/bin/vite.js", "dev", ...passthrough], {
+		cwd: studioRoot,
+		env: {
+			...process.env,
+			GHOSTCRAB_SQLITE_PATH: sqlitePath,
+			DATA_SOURCE: "sqlite-demo",
+			MINDBRAIN_RUNTIME_SOURCE: "demo-fixture"
+		},
+		stdio: "inherit"
+	});
+	child.on("exit", (code, signal) => {
+		process.exitCode = code ?? (signal ? 128 : 0);
+	});
+} else {
+if (!baseUrl) {
+	console.error(`error: no backend runtime found at ${paths.jsonPath}`);
+	console.error(`Run: pnpm backend -- --sqlite "${sqlitePath}"`);
+	process.exit(1);
+}
+
+if (!explicitUrl && runtime?.sqlite_path !== sqlitePath) {
+	console.error("error: backend runtime points at a different SQLite database");
+	console.error(`  runtime: ${runtime?.sqlite_path ?? "unknown"}`);
+	console.error(`  expected: ${sqlitePath}`);
+	process.exit(1);
+}
+
+if (!(await healthOk(baseUrl, 1500))) {
+	console.error(`error: GhostCrab backend is not healthy at ${baseUrl}`);
+	console.error(`Run: pnpm backend -- --sqlite "${sqlitePath}"`);
+	process.exit(1);
+}
+
+console.error(`==> Studio dev | SQLite: ${sqlitePath} | Backend: ${baseUrl}`);
+
+const viteArgs = ["./node_modules/vite/bin/vite.js", "dev", ...passthrough];
+const child = spawn(process.execPath, viteArgs, {
+	cwd: studioRoot,
+	env: {
+		...process.env,
+		GHOSTCRAB_SQLITE_PATH: sqlitePath,
+		DATA_SOURCE: "brain",
+		MINDBRAIN_HTTP_URL: baseUrl,
+		MINDBRAIN_RUNTIME_SOURCE: explicitUrl ? "env" : "runtime-json",
+		MINDBRAIN_RUNTIME_PATH: explicitUrl ? "" : paths.jsonPath
+	},
+	stdio: "inherit"
+});
+
+child.on("exit", (code, signal) => {
+	process.exitCode = code ?? (signal ? 128 : 0);
+});
+}