everything-dev 1.53.2 → 2.0.0-rc.1

package/dist/cli/init.mjs

@@ -1,32 +1,117 @@
 import { buildAuthContractStub, buildAuthExportStub, buildAuthTypesGenContent } from "../auth-types-gen.mjs";
 import { fetchResponse } from "../http-client.mjs";
 import { fetchBosConfigFromFastKv } from "../fastkv.mjs";
+import { findConfigPath, isAppDescriptorPath, loadAppDescriptorConfig } from "../config.mjs";
+import { serializeAppDescriptorSource } from "../descriptor/serialize.mjs";
+import { readWorkspaceCatalog as readWorkspaceCatalog$1 } from "../workspace-catalog.mjs";
 import { loadManifestNormalizationSpec, normalizePackageManifestsInTree } from "../internal/manifest-normalizer.mjs";
 import { saveBosConfig } from "../utils/save-config.mjs";
+import { computeSnapshotHash } from "../utils/snapshot-hash.mjs";
 import { writeSnapshot } from "./snapshot.mjs";
-import { getExtendsRef, parseBosRef, readJsonFile } from "./utils/helpers.mjs";
-import { createRequire } from "node:module";
+import { getExtendsRef, parseBosRef } from "./utils/helpers.mjs";
+import { runDockerComposeUp } from "../infra/docker.mjs";
+import { walkExtendsChain } from "../resolution/session.mjs";
 import { createWriteStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
-import { createHash } from "node:crypto";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { tmpdir } from "node:os";
-import { execa } from "execa";
 import { pipeline } from "node:stream/promises";
+import { execa } from "execa";
 import { glob } from "glob";
+import { extract } from "tar";
+import { parse, stringify } from "yaml";
 
 //#region src/cli/init.ts
-const require = createRequire(import.meta.url);
+const PNPM_PACKAGE_MANAGER = "pnpm@12.10.1";
+/**
+* Transitive-singleton overrides every workspace in the fleet must agree on
+* (ticket 05's deviation log: isolated resolution splits better-auth
+* peer-context identities across the plugin fleet). Values derive from the
+* catalog so sync keeps them current; keys absent from the catalog are left
+* unpinned.
+*/
+const CHILD_OVERRIDE_KEYS = [
+	"@better-fetch/fetch",
+	"@rspack/core",
+	"better-auth",
+	"react",
+	"react-dom"
+];
+/**
+* The child's workspace manifest: pnpm-workspace.yaml is canonical (v2, ADR
+* 0026) — packages globs synthesized from the child's override sections, the
+* catalog merged over any local entry, plus the fleet-wide linker posture and
+* singleton overrides. Re-running (sync/upgrade) merges instead of clobbering.
+*/
+function writeChildWorkspaceYaml(projectDir, next) {
+	const yamlPath = join(projectDir, "pnpm-workspace.yaml");
+	let doc = {};
+	if (existsSync(yamlPath)) try {
+		const parsed = parse(readFileSync(yamlPath, "utf-8"));
+		if (parsed && typeof parsed === "object") doc = parsed;
+	} catch {
+		doc = {};
+	}
+	let changed = !existsSync(yamlPath);
+	const packages = [.../* @__PURE__ */ new Set([...doc.packages ?? [], ...next.packages])].sort();
+	if (JSON.stringify(packages) !== JSON.stringify(doc.packages)) {
+		doc.packages = packages;
+		changed = true;
+	}
+	const catalog = { ...doc.catalog ?? {} };
+	for (const [name, version] of Object.entries(next.catalog)) if (catalog[name] !== version) {
+		catalog[name] = version;
+		changed = true;
+	}
+	if (Object.keys(catalog).length > 0 && Object.keys(catalog).length !== Object.keys(doc.catalog ?? {}).length) changed = true;
+	if (changed || !doc.catalog) doc.catalog = Object.fromEntries(Object.entries(catalog).sort(([a], [b]) => a.localeCompare(b)));
+	if (doc.nodeLinker !== "hoisted") {
+		doc.nodeLinker = "hoisted";
+		changed = true;
+	}
+	if (doc.linkWorkspacePackages !== true) {
+		doc.linkWorkspacePackages = true;
+		changed = true;
+	}
+	if (doc.ignoreScripts !== true) {
+		doc.ignoreScripts = true;
+		changed = true;
+	}
+	const overrides = { ...doc.overrides ?? {} };
+	for (const key of CHILD_OVERRIDE_KEYS) if (catalog[key] && overrides[key] !== catalog[key]) {
+		overrides[key] = catalog[key];
+		changed = true;
+	}
+	if (Object.keys(overrides).length > 0) doc.overrides = Object.fromEntries(Object.entries(overrides).sort(([a], [b]) => a.localeCompare(b)));
+	if (changed) {
+		writeFileSync(yamlPath, `${stringify(doc, { lineWidth: 0 }).trimEnd()}\n`);
+		return true;
+	}
+	return false;
+}
+/**
+* Init must never reuse a lockfile left in the target (copied from a parent
+* checkout or left by a previous run) — stale framework resolutions would
+* survive the fresh install. Bun's bun.lock is deleted on sight (ADR 0026's
+* silent-revert footgun); the child's own pnpm-lock.yaml is re-resolved.
+*/
+function removeStrayLockfiles(projectDir) {
+	for (const lockfile of ["pnpm-lock.yaml", "bun.lock"]) {
+		const lockfilePath = join(projectDir, lockfile);
+		if (existsSync(lockfilePath)) rmSync(lockfilePath, { force: true });
+	}
+}
 const INIT_ROOT_PATTERNS = [
 	"bos.config.json",
 	"package.json",
 	".env.example",
 	".gitignore",
 	"biome.json",
-	"bunfig.toml",
-	"Dockerfile",
 	"railway.json",
 	"railway.toml",
 	"AGENTS.md",
+	".agents/skills/**",
+	"skills-lock.json",
+	"docs/agents/**",
 	".changeset/config.json",
 	".changeset/README.md",
 	"README.md",
@@ -40,75 +125,43 @@ const OVERRIDE_WORKSPACE_MAP = {
 	plugins: []
 };
 function readWorkspaceCatalog(sourceDir) {
-	const pkgPath = join(sourceDir, "package.json");
-	if (!existsSync(pkgPath)) return {};
-	return { ...readJsonFile(pkgPath).workspaces?.catalog ?? {} };
+	return readWorkspaceCatalog$1(sourceDir);
 }
 async function resolveCatalogChainSource(opts) {
+	const entry = opts.sourceDir ? findConfigPath(resolve(opts.sourceDir)) ?? join(resolve(opts.sourceDir), "bos.config.json") : `bos://${opts.extendsAccount}/${opts.extendsGateway}`;
 	const catalogs = [];
 	const cleanups = [];
-	const extendsChain = [];
-	const visited = /* @__PURE__ */ new Set();
+	const resolvedRefs = [];
 	let repository;
-	let currentRef = `bos://${opts.extendsAccount}/${opts.extendsGateway}`;
-	let sourceDir = opts.sourceDir ? resolve(opts.sourceDir) : void 0;
-	let configPath = sourceDir ? join(sourceDir, "bos.config.json") : void 0;
 	try {
-		while (true) {
-			if (visited.has(currentRef)) throw new Error(`Circular extends detected while resolving catalog source: ${currentRef}`);
-			visited.add(currentRef);
-			extendsChain.push(currentRef);
-			let config;
-			let currentSourceDir = sourceDir;
-			let cleanup = async () => {};
-			if (configPath) {
-				config = readJsonFile(configPath);
-				currentSourceDir = dirname(configPath);
-			} else {
-				const parsed = parseBosRef(currentRef);
-				if (!parsed) break;
-				const sourceResult = await resolveSourceDir({
-					extendsAccount: parsed.account,
-					extendsGateway: parsed.gateway
-				});
-				config = sourceResult.parentConfig;
-				currentSourceDir = sourceResult.sourceDir || void 0;
-				cleanup = sourceResult.cleanup;
+		await walkExtendsChain(entry, {
+			env: "production",
+			collectCatalogs: true,
+			registerCleanup: (fn) => cleanups.push(fn),
+			visit: async (link) => {
+				resolvedRefs.unshift(link.ref.startsWith("bos://") ? link.ref : join(link.baseDir, basename(link.ref)));
+				catalogs.push(readWorkspaceCatalog(link.sourceDir ?? link.baseDir));
+				const repositoryValue = link.config.repository;
+				if (typeof repositoryValue === "string" && repository === void 0) repository = repositoryValue;
 			}
-			cleanups.push(cleanup);
-			catalogs.push(currentSourceDir ? readWorkspaceCatalog(currentSourceDir) : {});
-			if (typeof config.repository === "string") repository = config.repository;
-			const nextExtendsRef = getExtendsRef(config);
-			if (!nextExtendsRef) break;
-			if (nextExtendsRef.startsWith("bos://")) {
-				currentRef = nextExtendsRef;
-				sourceDir = void 0;
-				configPath = void 0;
-				continue;
-			}
-			if (!currentSourceDir) break;
-			const nextConfigPath = resolve(currentSourceDir, nextExtendsRef);
-			if (!existsSync(nextConfigPath)) break;
-			currentRef = nextConfigPath;
-			sourceDir = dirname(nextConfigPath);
-			configPath = nextConfigPath;
-		}
+		});
 	} finally {
-		for (const cleanup of cleanups.reverse()) await cleanup();
+		for (const cleanup of [...cleanups].reverse()) await cleanup();
 	}
 	return {
-		catalog: Object.assign({}, ...catalogs.reverse()),
+		catalog: Object.assign({}, ...catalogs),
 		repository,
-		extendsChain
+		extendsChain: opts.sourceDir ? [`bos://${opts.extendsAccount}/${opts.extendsGateway}`, ...resolvedRefs.slice(1)] : resolvedRefs
 	};
 }
 async function resolveSourceDir(opts) {
 	if (opts.source) {
 		const sourceDir = resolve(opts.source);
-		if (!existsSync(join(sourceDir, "bos.config.json"))) throw new Error(`No bos.config.json found in source directory: ${sourceDir}`);
+		const configPath = findConfigPath(sourceDir);
+		if (!configPath) throw new Error(`No authored config (bos.app.ts or bos.config.json) found in source directory: ${sourceDir}`);
 		return {
 			sourceDir,
-			parentConfig: JSON.parse(readFileSync(join(sourceDir, "bos.config.json"), "utf-8")),
+			parentConfig: isAppDescriptorPath(configPath) ? await loadAppDescriptorConfig(configPath) : JSON.parse(readFileSync(configPath, "utf-8")),
 			cleanup: async () => {}
 		};
 	}
@@ -140,7 +193,8 @@ function buildInitPatterns(overrides, plugins, pluginDirMap) {
 	const has = (section) => overrides.includes(section);
 	const patterns = [...INIT_ROOT_PATTERNS];
 	if (has("ui")) patterns.push("ui/**");
-	if (has("api")) patterns.push("api/**");
+	if (has("api")) patterns.push(API_TEMPLATE_PATTERN);
+	if (has("api") || has("host")) patterns.push(COMPOSE_TEMPLATE_PATTERN);
 	if (has("host")) patterns.push("host/**");
 	if (has("plugins")) for (const plugin of plugins ?? []) {
 		const dirName = pluginDirMap?.[plugin] ?? plugin;
@@ -148,6 +202,16 @@ function buildInitPatterns(overrides, plugins, pluginDirMap) {
 	}
 	return patterns;
 }
+/** api-override children get the slim generic shell, never the parent's domain API. */
+const API_TEMPLATE_PATTERN = ".github/templates/api/**";
+/** Child-sized compose (api + api-test databases) for local compute overrides. */
+const COMPOSE_TEMPLATE_PATTERN = ".github/templates/docker-compose.yml";
+function isApiTemplatePath(filePath) {
+	return filePath.startsWith(".github/templates/api/");
+}
+function isComposeTemplatePath(filePath) {
+	return filePath === COMPOSE_TEMPLATE_PATTERN;
+}
 function buildPluginRouteExclusions(parentConfig, selectedPlugins) {
 	if (!parentConfig?.plugins) return [];
 	const selected = new Set(selectedPlugins);
@@ -161,6 +225,54 @@ function buildPluginRouteExclusions(parentConfig, selectedPlugins) {
 	}
 	return claimedByUnselected.filter((route) => !claimedBySelected.has(route));
 }
+const STARTER_PRODUCT_EXCLUSIONS = [
+	"_public/explore.tsx",
+	"_public/stake.tsx",
+	"_public/n/**",
+	"_public/$accountId.tsx",
+	"_public/$accountId/**",
+	"_public/activity/**",
+	"_public/-stake-*",
+	"_authenticated/_dashboard/dashboard/node/**",
+	"_authenticated/_dashboard/nodes/**",
+	"_authenticated/_dashboard/tenant.*",
+	"_authenticated/_dashboard/discover.tsx",
+	"_authenticated/_dashboard/apply.tsx",
+	"_authenticated/_dashboard/prototype-staking-poc.tsx",
+	"_authenticated/onboarding/**",
+	"_admin/_dashboard/_dashboard/admin/nodes/**",
+	"_admin/_dashboard/_dashboard/admin/proposals/**",
+	"_admin/_dashboard/_dashboard/admin/tenants/**",
+	"_admin/_dashboard/_dashboard/admin/relayer.tsx",
+	"_admin/_dashboard/_dashboard/admin/organizations.tsx"
+];
+const STARTER_SIMPLE_EXCLUSIONS = [
+	"_authenticated.tsx",
+	"_authenticated/**",
+	"_admin.tsx",
+	"_admin/**"
+];
+/**
+* Route-file globs (relative to the child's `ui/src/routes/`) that a starter
+* of the given level must not receive. Parent `starter` config can add
+* exclusions (`exclude`, `levels[level].exclude`) or reclaim routes for a
+* level (`levels[level].include`). Entries are prefixed with
+* `ui/src/routes/` so they compose with `copyFilteredFiles`'s ignore list.
+*/
+function buildStarterRouteExclusions(level, parentConfig) {
+	const excluded = /* @__PURE__ */ new Set([...STARTER_PRODUCT_EXCLUSIONS]);
+	if (level === "simple") for (const entry of STARTER_SIMPLE_EXCLUSIONS) excluded.add(entry);
+	const starter = parentConfig?.starter;
+	if (starter) {
+		for (const entry of starter.exclude ?? []) excluded.add(entry);
+		const levelConfig = starter.levels?.[level];
+		if (levelConfig) {
+			for (const entry of levelConfig.exclude ?? []) excluded.add(entry);
+			for (const entry of levelConfig.include ?? []) excluded.delete(entry);
+		}
+	}
+	return [...excluded].map((entry) => `ui/src/routes/${entry}`);
+}
 function extractPluginRoutes(entry) {
 	if (typeof entry !== "object" || entry === null) return void 0;
 	const routes = entry.routes;
@@ -168,10 +280,13 @@ function extractPluginRoutes(entry) {
 	return routes.filter((r) => typeof r === "string");
 }
 function sourcePathToDestinationPath(filePath) {
+	if (isApiTemplatePath(filePath)) return filePath.replace(/^\.github\/templates\/api\//, "api/");
+	if (isComposeTemplatePath(filePath)) return "docker-compose.yml";
 	return filePath.startsWith(".github/templates/") ? filePath.replace(/^\.github\/templates\//, ".github/") : filePath;
 }
 async function fetchParentConfig(extendsAccount, extendsGateway) {
-	return fetchBosConfigFromFastKv(`bos://${extendsAccount}/${extendsGateway}`);
+	const bosUrl = `bos://${extendsAccount}/${extendsGateway}`;
+	return fetchBosConfigFromFastKv(bosUrl);
 }
 async function resolveRepositoryViaExtendsChain(extendsAccount, extendsGateway, visited = /* @__PURE__ */ new Set()) {
 	const key = `bos://${extendsAccount}/${extendsGateway}`;
@@ -185,7 +300,8 @@ async function resolveRepositoryViaExtendsChain(extendsAccount, extendsGateway,
 		};
 		const extendsRef = getExtendsRef(config);
 		if (extendsRef) {
-			const parsed = parseBosRef(extendsRef.startsWith("bos://") ? extendsRef : `bos://${extendsRef}`);
+			const normalized = extendsRef.startsWith("bos://") ? extendsRef : `bos://${extendsRef}`;
+			const parsed = parseBosRef(normalized);
 			if (parsed) {
 				const result = await resolveRepositoryViaExtendsChain(parsed.account, parsed.gateway, visited);
 				if (result) return result;
@@ -246,7 +362,7 @@ async function downloadTarball(repoUrl) {
 	await pipeline(reader, fileStream);
 	const extractDir = mkTmpDir("bos-init-extract-");
 	try {
-		await require("tar").extract({
+		await extract({
 			cwd: extractDir,
 			file: tarballPath,
 			strip: 1
@@ -276,12 +392,12 @@ async function downloadTarball(repoUrl) {
 }
 function parseGitHubUrl(url) {
 	const httpsMatch = url.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?(?:\/.*)?$/);
-	if (httpsMatch) return {
+	if (httpsMatch?.[1] && httpsMatch[2]) return {
 		owner: httpsMatch[1],
 		repo: httpsMatch[2]
 	};
 	const sshMatch = url.match(/^git@github\.com:([^/]+)\/([^/]+?)(?:\.git)?$/);
-	if (sshMatch) return {
+	if (sshMatch?.[1] && sshMatch[2]) return {
 		owner: sshMatch[1],
 		repo: sshMatch[2]
 	};
@@ -307,14 +423,22 @@ async function copyFilteredFiles(sourceDir, destination, patterns, options) {
 		});
 		for (const match of matches) allFiles.add(match);
 	}
+	if (!options.overrides.includes("api")) {
+		for (const match of allFiles) if (isApiTemplatePath(match)) allFiles.delete(match);
+	}
+	if (!options.overrides.includes("api") && !options.overrides.includes("host")) {
+		for (const match of allFiles) if (isComposeTemplatePath(match)) allFiles.delete(match);
+	}
 	mkdirSync(destination, { recursive: true });
 	let count = 0;
 	for (const filePath of allFiles) {
 		const src = join(sourceDir, filePath);
 		if (!lstatSync(src).isFile()) continue;
-		const dest = join(destination, sourcePathToDestinationPath(filePath));
+		const destPath = sourcePathToDestinationPath(filePath);
+		const dest = join(destination, destPath);
 		mkdirSync(dirname(dest), { recursive: true });
-		writeFileSync(dest, readFileSync(src));
+		const content = readFileSync(src);
+		writeFileSync(dest, content);
 		count++;
 	}
 	return count;
@@ -324,13 +448,52 @@ function stripProductionFields(entry) {
 	delete entry.integrity;
 	delete entry.ssr;
 	delete entry.ssrIntegrity;
+	delete entry.pin;
+}
+/**
+* Scaffold the authored config as the TS form: the personalized
+* bos.config.json materializes into an authored `bos.app.ts` descriptor and
+* the JSON copy is removed — publish/sync still canonicalize to JSON for
+* FastKV from the resolved config. Returns the config that was converted, so
+* callers that need it (before the child has node_modules to import the
+* descriptor) can pass it onward.
+*/
+async function convertChildConfigToAppForm(destination) {
+	const configPath = join(destination, "bos.config.json");
+	if (!existsSync(configPath)) return null;
+	const config = JSON.parse(readFileSync(configPath, "utf-8"));
+	writeFileSync(join(destination, "bos.app.ts"), serializeAppDescriptorSource(config));
+	rmSync(configPath);
+	return config;
+}
+/**
+* Scaffold the root dev-overlay starter (`bos.dev.ts`). Idempotent — never
+* overwrites an existing overlay. Dev overlays are merged child-wins over
+* the resolved config in development and are never published.
+*/
+function writeDevOverlayTemplate(destination, opts = {}) {
+	const overlayPath = join(destination, "bos.dev.ts");
+	if (existsSync(overlayPath)) return;
+	const extendsLine = opts.extendsRef ? `\n// Inherited base: ${opts.extendsRef}\n` : "";
+	writeFileSync(overlayPath, `import type { AppDescriptor } from "everything-dev/descriptor";
+${extendsLine}
+/**
+ * Development-only overlay for bos.app.ts — merged child-wins over the
+ * resolved config when the environment is development. Never published.
+ * Example: pin the auth attachment to a running dev server instead of
+ * letting the dev harness spawn it.
+ */
+export default {
+  // auth: { development: "http://localhost:3006" },
+} satisfies Partial<AppDescriptor>;
+`);
 }
 function buildRootTypecheckScript(sections) {
-	const commands = ["bun run types:gen"];
-	if (sections.ui) commands.push("if [ -d ui ]; then bun run --cwd ui typecheck; fi");
-	if (sections.api) commands.push("if [ -d api ]; then bun run --cwd api typecheck; fi");
-	if (sections.host) commands.push("if [ -d host ]; then bun run --cwd host typecheck; fi");
-	if (sections.plugins) commands.push("if [ -d plugins ]; then for dir in plugins/*; do if [ -f \"$dir/package.json\" ]; then bun run --cwd \"$dir\" typecheck; fi; done; fi");
+	const commands = ["pnpm run types:gen"];
+	if (sections.ui) commands.push("if [ -d ui ]; then pnpm --dir ui run typecheck; fi");
+	if (sections.api) commands.push("if [ -d api ]; then pnpm --dir api run typecheck; fi");
+	if (sections.host) commands.push("if [ -d host ]; then pnpm --dir host run typecheck; fi");
+	if (sections.plugins) commands.push("if [ -d plugins ]; then for dir in plugins/*; do if [ -f \"$dir/package.json\" ]; then pnpm --dir \"$dir\" run typecheck; fi; done; fi");
 	return commands.join(" && ");
 }
 function getParentOnlyScriptKeys(projectDir) {
@@ -355,7 +518,7 @@ function buildChildRootScripts(sections) {
 		dev: "bos dev",
 		"dev:proxy": "bos dev --proxy",
 		build: "bos build",
-		deploy: "bos build --deploy",
+		deploy: "bos deploy",
 		publish: "bos publish",
 		start: "bos start",
 		typecheck: buildRootTypecheckScript(sections),
@@ -366,29 +529,28 @@ function buildChildRootScripts(sections) {
 		changeset: "changeset",
 		version: "changeset version",
 		release: "echo 'Packages versioned - app release handled by workflow'",
-		postinstall: "node node_modules/.bin/bos types gen || true",
-		"types:gen": "node node_modules/.bin/bos types gen",
+		"types:gen": "bos types gen",
 		bos: "bos"
 	};
 	if (sections.api) {
-		scripts["db:push"] = "bun run --cwd api drizzle-kit push";
+		scripts["db:push"] = "pnpm --dir api exec drizzle-kit push";
 		scripts["db:studio"] = "bos db:studio";
 		scripts["db:doctor"] = "bos db:doctor";
 		scripts["db:repair"] = "bos db:repair";
-		scripts["db:generate"] = "bun run --cwd api drizzle-kit generate";
-		scripts["db:migrate"] = "bun run --cwd api drizzle-kit migrate";
-		scripts["test:api"] = "bun run --cwd api test --if-present";
-		scripts["test:integration"] = "bun run --cwd api test tests/integration/ --if-present";
+		scripts["db:generate"] = "pnpm --dir api exec drizzle-kit generate";
+		scripts["db:migrate"] = "pnpm --dir api exec drizzle-kit migrate";
+		scripts["test:api"] = "pnpm --dir api run test --if-present";
+		scripts["test:integration"] = "pnpm --dir api run test tests/integration/ --if-present";
 	}
-	if (sections.host) scripts["test:e2e"] = "bun run --cwd host test --if-present";
+	if (sections.host) scripts["test:e2e"] = "pnpm --dir host run test --if-present";
 	const testTargets = [];
-	if (sections.api) testTargets.push("bun run --cwd api test --if-present");
-	if (sections.host) testTargets.push("bun run --cwd host test --if-present");
-	if (sections.ui) testTargets.push("bun run --cwd ui test --if-present");
-	if (sections.plugins) testTargets.push("for d in plugins/*; do [ -f \"$d/package.json\" ] && bun run --cwd \"$d\" test --if-present; done");
+	if (sections.api) testTargets.push("pnpm --dir api run test --if-present");
+	if (sections.host) testTargets.push("pnpm --dir host run test --if-present");
+	if (sections.ui) testTargets.push("pnpm --dir ui run test --if-present");
+	if (sections.plugins) testTargets.push("for d in plugins/*; do [ -f \"$d/package.json\" ] && pnpm --dir \"$d\" run test --if-present; done");
 	scripts.test = testTargets.length > 0 ? testTargets.join(" && ") : "echo \"No workspace directories configured\"";
 	if (sections.api || sections.host) {
-		scripts["dev:postgres"] = "docker compose up -d --wait && bun run dev";
+		scripts["dev:postgres"] = "docker compose up -d --wait && pnpm run dev";
 		scripts["dev:postgres:down"] = "docker compose down";
 		scripts["dev:postgres:reset"] = "docker compose down -v && docker compose up -d --wait";
 	}
@@ -399,6 +561,10 @@ function buildChildRootScripts(sections) {
 async function personalizeConfig(destination, opts) {
 	const has = (section) => opts.overrides.includes(section);
 	const preservedAuth = (opts.mode === "sync" && opts.existingConfig?.app && typeof opts.existingConfig.app === "object" ? opts.existingConfig.app : void 0)?.auth;
+	const applyStarter = (config) => {
+		if (opts.starter) config.starter = opts.starter;
+		else if (opts.mode !== "sync") delete config.starter;
+	};
 	const explicitRootKeys = new Set(Object.entries(opts).filter(([key, value]) => value !== void 0 && ![
 		"extendsAccount",
 		"extendsGateway",
@@ -409,6 +575,63 @@ async function personalizeConfig(destination, opts) {
 		"mode",
 		"existingConfig"
 	].includes(key)).map(([key]) => key));
+	const jsonConfigPath = join(destination, "bos.config.json");
+	const appConfigPath = join(destination, "bos.app.ts");
+	if (!existsSync(jsonConfigPath) && existsSync(appConfigPath)) {
+		const config = await loadAppDescriptorConfig(appConfigPath);
+		config.extends = `bos://${opts.extendsAccount}/${opts.extendsGateway}`;
+		if (opts.account) config.account = opts.account;
+		if (opts.domain) config.domain = opts.domain;
+		if (opts.repository) config.repository = opts.repository;
+		else delete config.repository;
+		for (const field of [
+			"title",
+			"description",
+			"testnet",
+			"staging"
+		]) if (!(field in opts)) delete config[field];
+		applyStarter(config);
+		if (config.app && typeof config.app === "object") {
+			const app = config.app;
+			for (const entryKey of Object.keys(app)) {
+				if (!has(entryKey) && (entryKey === "host" || entryKey === "ui" || entryKey === "api")) {
+					delete app[entryKey];
+					continue;
+				}
+				if (entryKey === "auth") {
+					delete app[entryKey];
+					continue;
+				}
+				const entry = app[entryKey];
+				if (entry && typeof entry === "object") stripProductionFields(entry);
+			}
+			if (preservedAuth !== void 0) app.auth = preservedAuth;
+			if (Object.keys(app).length === 0) delete config.app;
+		}
+		if (has("plugins")) {
+			if (config.plugins && typeof config.plugins === "object") {
+				const plugins = config.plugins;
+				if (opts.plugins !== void 0) {
+					for (const pluginKey of Object.keys(plugins)) if (!opts.plugins.includes(pluginKey)) delete plugins[pluginKey];
+				}
+				for (const pluginKey of Object.keys(plugins)) {
+					const plugin = plugins[pluginKey];
+					let pluginObj;
+					if (typeof plugin === "string") {
+						pluginObj = { extends: plugin };
+						plugins[pluginKey] = pluginObj;
+					} else if (plugin && typeof plugin === "object") {
+						pluginObj = { ...plugin };
+						plugins[pluginKey] = pluginObj;
+					} else continue;
+					stripProductionFields(pluginObj);
+				}
+				if (Object.keys(plugins).length === 0) config.plugins = {};
+			}
+		} else config.plugins = {};
+		writeFileSync(appConfigPath, serializeAppDescriptorSource(config));
+		return;
+	}
 	const configPath = join(destination, "bos.config.json");
 	if (existsSync(configPath)) {
 		const config = JSON.parse(readFileSync(configPath, "utf-8"));
@@ -423,6 +646,7 @@ async function personalizeConfig(destination, opts) {
 			"testnet",
 			"staging"
 		]) if (!(field in opts)) delete config[field];
+		applyStarter(config);
 		if (config.app && typeof config.app === "object") {
 			const app = config.app;
 			for (const entryKey of Object.keys(app)) {
@@ -497,30 +721,24 @@ async function personalizeConfig(destination, opts) {
 		if (typeof pkg.name !== "string" || pkg.name.length === 0) pkg.name = "monorepo";
 		pkg.private = true;
 		pkg.type = "module";
+		pkg.packageManager = PNPM_PACKAGE_MANAGER;
 		delete pkg.module;
 		delete pkg.peerDependencies;
-		if (pkg.workspaces && typeof pkg.workspaces === "object") {
-			const ws = pkg.workspaces;
-			if (Array.isArray(ws.packages)) {
-				ws.packages = ws.packages.filter((p) => {
-					if (p.startsWith("packages/")) return false;
-					if (p === "ui") return has("ui");
-					if (p === "api") return has("api");
-					if (p === "host") return has("host");
-					if (p.startsWith("plugins/")) return false;
-					return true;
-				});
-				if (has("plugins")) {
-					if (!ws.packages.includes("plugins/*")) ws.packages.push("plugins/*");
-				}
-			}
-		}
+		delete pkg.patchedDependencies;
+		const childWorkspaces = [];
+		if (has("host")) childWorkspaces.push("host");
+		if (has("ui")) childWorkspaces.push("ui");
+		if (has("api")) childWorkspaces.push("api");
+		if (has("plugins")) childWorkspaces.push("plugins/*");
+		const localCatalog = pkg.workspaces && typeof pkg.workspaces === "object" ? pkg.workspaces.catalog ?? {} : {};
+		delete pkg.workspaces;
 		if (!pkg.scripts || typeof pkg.scripts !== "object") pkg.scripts = {};
 		const scripts = pkg.scripts;
 		for (const [key, value] of Object.entries(childScripts)) scripts[key] = value;
 		for (const obsoleteScript of [
 			...getParentOnlyScriptKeys(destination),
 			"init",
+			"prepare",
 			"sync-catalog",
 			"db:push",
 			"db:studio",
@@ -543,28 +761,32 @@ async function personalizeConfig(destination, opts) {
 			delete deps["every-plugin"];
 			delete deps["everything-dev"];
 		}
-		if (!pkg.workspaces || typeof pkg.workspaces !== "object") pkg.workspaces = {
-			packages: [],
-			catalog: {}
+		const catalog = { ...localCatalog };
+		pkg.dependencies = {
+			"everything-dev": "catalog:",
+			"every-plugin": "catalog:"
 		};
-		const workspaces = pkg.workspaces;
-		if (!workspaces.catalog || typeof workspaces.catalog !== "object") workspaces.catalog = {};
-		if (!pkg.dependencies) pkg.dependencies = {};
 		const deps = pkg.dependencies;
 		const spec = opts.workspaceOpts?.sourceDir ? loadManifestNormalizationSpec(opts.workspaceOpts.sourceDir) : null;
 		if (spec) {
-			workspaces.catalog["everything-dev"] = spec.rootCatalog["everything-dev"];
-			workspaces.catalog["every-plugin"] = spec.rootCatalog["every-plugin"];
+			const rootCatalogEverythingDev = spec.rootCatalog["everything-dev"];
+			const rootCatalogEveryPlugin = spec.rootCatalog["every-plugin"];
+			if (rootCatalogEverythingDev) catalog["everything-dev"] = rootCatalogEverythingDev;
+			if (rootCatalogEveryPlugin) catalog["every-plugin"] = rootCatalogEveryPlugin;
 		}
 		const frameworkCatalog = (await resolveCatalogChainSource({
 			extendsAccount: opts.extendsAccount,
 			extendsGateway: opts.extendsGateway,
 			sourceDir: opts.workspaceOpts?.sourceDir
 		})).catalog;
-		for (const [name, version] of Object.entries(frameworkCatalog)) workspaces.catalog[name] = version;
+		for (const [name, version] of Object.entries(frameworkCatalog)) catalog[name] = version;
 		if (!deps["everything-dev"]) deps["everything-dev"] = "catalog:";
 		if (!deps["every-plugin"]) deps["every-plugin"] = "catalog:";
 		writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+		writeChildWorkspaceYaml(destination, {
+			packages: childWorkspaces,
+			catalog
+		});
 	}
 	const apiTsConfigPath = join(destination, "api", "tsconfig.json");
 	if (existsSync(apiTsConfigPath)) {
@@ -585,12 +807,30 @@ async function personalizeConfig(destination, opts) {
 			mkdirSync(dirname(genContractPath), { recursive: true });
 			writeFileSync(genContractPath, `export type ApiContract = Record<string, never>;\n`);
 		}
+		const publicDir = join(destination, "ui", "public");
+		if (!existsSync(publicDir)) mkdirSync(publicDir, { recursive: true });
+		const llmsTxtPath = join(publicDir, "llms.txt");
+		if (!existsSync(llmsTxtPath)) {
+			const title = opts.title ?? opts.account ?? "app";
+			writeFileSync(llmsTxtPath, buildChildLlmsTxt(title));
+		}
+		const skillMdPath = join(publicDir, "skill.md");
+		if (!existsSync(skillMdPath)) {
+			const title = opts.title ?? opts.account ?? "app";
+			const repository = opts.repository ?? "";
+			writeFileSync(skillMdPath, buildChildSkillMd(title, repository));
+		}
+		for (const agentFilePath of [llmsTxtPath, skillMdPath]) {
+			const content = readFileSync(agentFilePath, "utf-8");
+			if (content.includes(WORKFLOW_SKILLS_MARKER)) continue;
+			writeFileSync(agentFilePath, `${content.replace(/\n*$/, "\n")}${WORKFLOW_SKILLS_NOTE}`);
+		}
 	}
 	if (has("api")) {
 		const pluginsClientGenPath = join(destination, "api", "src", "lib", "plugins-types.gen.ts");
 		if (!existsSync(pluginsClientGenPath)) {
 			mkdirSync(dirname(pluginsClientGenPath), { recursive: true });
-			writeFileSync(pluginsClientGenPath, `import type { ContractRouterClient, AnyContractRouter } from "@orpc/contract";\ntype ClientFactory<C extends AnyContractRouter> = (context?: Record<string, unknown>) => ContractRouterClient<C>;\nexport type PluginsClient = Record<string, never>;\n`);
+			writeFileSync(pluginsClientGenPath, `import type { RouterContractClient, RouterContract } from "@orpc/contract";\ntype ClientFactory<C extends RouterContract> = (context?: Record<string, unknown>) => RouterContractClient<C>;\nexport type PluginsClient = Record<string, never>;\n`);
 		}
 	}
 	const authTypesPaths = [];
@@ -599,7 +839,9 @@ async function personalizeConfig(destination, opts) {
 	if (has("host") && existsSync(join(destination, "host", "src"))) authTypesPaths.push(join(destination, "host", "src", "lib", "auth-types.gen.ts"));
 	for (const authTypesGenPath of authTypesPaths) if (!existsSync(authTypesGenPath)) {
 		mkdirSync(dirname(authTypesGenPath), { recursive: true });
-		writeFileSync(authTypesGenPath, buildAuthTypesGenContent(toRelativeImportPath(join(destination, ".bos", "generated", "auth", "auth-export.d.ts"), authTypesGenPath), toRelativeImportPath(join(destination, ".bos", "generated", "auth", "contract.d.ts"), authTypesGenPath)));
+		const authExportRel = toRelativeImportPath(join(destination, ".bos", "generated", "auth", "auth-export.d.ts"), authTypesGenPath);
+		const contractRel = toRelativeImportPath(join(destination, ".bos", "generated", "auth", "contract.d.ts"), authTypesGenPath);
+		writeFileSync(authTypesGenPath, buildAuthTypesGenContent(authExportRel, contractRel));
 	}
 	if (authTypesPaths.length > 0) {
 		const authDir = join(destination, ".bos", "generated", "auth");
@@ -622,11 +864,11 @@ function toRelativeImportPath(fromPath, toPath) {
 	const rel = relative(dirname(toPath), fromPath);
 	return rel.startsWith(".") ? rel : `./${rel}`;
 }
-async function runBunInstall(destination, opts) {
-	await runWithProgress("bun", ["install", "--ignore-scripts"], destination, opts?.spinner, "Installing dependencies");
+async function runPnpmInstall(destination, opts) {
+	await runWithProgress("pnpm", ["install", "--ignore-scripts"], destination, opts?.spinner, "Installing dependencies");
 }
-async function runBunInstallForUpgrade(destination, opts) {
-	await runWithProgress("bun", ["install", "--force"], destination, opts?.spinner, "Installing dependencies");
+async function runPnpmInstallForUpgrade(destination, opts) {
+	await runWithProgress("pnpm", ["install", "--force"], destination, opts?.spinner, "Installing dependencies");
 }
 async function runTypesGen(destination, opts) {
 	const bosModule = join(destination, "node_modules", "everything-dev", "dist", "cli.mjs");
@@ -642,19 +884,12 @@ async function runTypesGen(destination, opts) {
 	}
 	throw new Error("Unable to locate bos CLI for types generation");
 }
-async function runDockerComposeUp(destination) {
-	await execCommand("docker", [
-		"compose",
-		"up",
-		"-d",
-		"--wait"
-	], destination, { stdio: "inherit" });
-}
 async function runWithProgress(command, args, cwd, spinner, label) {
+	const timeout = COMMAND_TIMEOUTS[command] ?? 12e4;
 	const child = execa(command, args, {
 		cwd,
 		stdio: "inherit",
-		timeout: COMMAND_TIMEOUTS[command] ?? 2 * 6e4,
+		timeout,
 		env: {
 			...process.env,
 			BOS_NO_BANNER: "1"
@@ -673,33 +908,6 @@ async function runWithProgress(command, args, cwd, spinner, label) {
 		}
 	} else await child;
 }
-function stripOrphanedWorkspacesFromLockfile(lockfilePath, allowedWorkspaces) {
-	if (!existsSync(lockfilePath)) return;
-	const content = readFileSync(lockfilePath, "utf-8");
-	let lockfile;
-	try {
-		lockfile = JSON.parse(content);
-	} catch {
-		return;
-	}
-	const workspaces = lockfile.workspaces;
-	if (!workspaces || typeof workspaces !== "object") return;
-	const workspaceMap = workspaces;
-	const allowed = /* @__PURE__ */ new Set(["", ...allowedWorkspaces]);
-	const keys = Object.keys(workspaceMap);
-	let changed = false;
-	for (const key of keys) {
-		if (allowed.has(key)) continue;
-		if (allowedWorkspaces.some((pattern) => pattern.endsWith("/*") && key.startsWith(pattern.slice(0, -1)))) continue;
-		delete workspaceMap[key];
-		changed = true;
-	}
-	if (changed) writeFileSync(lockfilePath, `${JSON.stringify(lockfile, null, 2)}\n`);
-}
-function removeInitLockfile(lockfilePath) {
-	if (!existsSync(lockfilePath)) return;
-	rmSync(lockfilePath, { force: true });
-}
 async function scaffoldMinimalProject(destination, parentConfig, opts) {
 	mkdirSync(destination, { recursive: true });
 	const has = (section) => opts.overrides.includes(section);
@@ -709,7 +917,8 @@ async function scaffoldMinimalProject(destination, parentConfig, opts) {
 		...opts.domain ? { domain: opts.domain } : {},
 		...opts.repository ? { repository: opts.repository } : {},
 		...opts.title ? { title: opts.title } : {},
-		...opts.description ? { description: opts.description } : {}
+		...opts.description ? { description: opts.description } : {},
+		...opts.starter ? { starter: opts.starter } : {}
 	};
 	if (parentConfig.app && typeof parentConfig.app === "object") {
 		const app = {};
@@ -732,11 +941,13 @@ async function scaffoldMinimalProject(destination, parentConfig, opts) {
 		const plugins = {};
 		for (const key of opts.plugins) {
 			const parentPlugin = parentConfig.plugins?.[key];
-			if (parentPlugin) if (typeof parentPlugin === "string") plugins[key] = { extends: parentPlugin };
-			else {
-				const pluginCopy = { ...parentPlugin };
-				stripProductionFields(pluginCopy);
-				plugins[key] = pluginCopy;
+			if (parentPlugin) {
+				if (typeof parentPlugin === "string") plugins[key] = { extends: parentPlugin };
+				else {
+					const pluginCopy = { ...parentPlugin };
+					stripProductionFields(pluginCopy);
+					plugins[key] = pluginCopy;
+				}
 			}
 		}
 		config.plugins = plugins;
@@ -747,12 +958,14 @@ async function scaffoldMinimalProject(destination, parentConfig, opts) {
 	if (has("plugins")) workspacePackages.push("plugins/*");
 	const catalog = (await resolveCatalogChainSource({
 		extendsAccount: opts.extendsAccount,
-		extendsGateway: opts.extendsGateway
+		extendsGateway: opts.extendsGateway,
+		sourceDir: opts.catalogSourceDir
 	})).catalog;
 	const pkg = {
 		name: "monorepo",
 		private: true,
 		type: "module",
+		packageManager: PNPM_PACKAGE_MANAGER,
 		scripts: buildChildRootScripts({
 			ui: has("ui"),
 			api: has("api"),
@@ -763,13 +976,13 @@ async function scaffoldMinimalProject(destination, parentConfig, opts) {
 			"everything-dev": "catalog:",
 			"every-plugin": "catalog:"
 		},
-		devDependencies: {},
-		workspaces: {
-			packages: workspacePackages,
-			catalog
-		}
+		devDependencies: {}
 	};
 	writeFileSync(join(destination, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
+	writeChildWorkspaceYaml(destination, {
+		packages: workspacePackages,
+		catalog
+	});
 	writeFileSync(join(destination, ".gitignore"), generateGitignore());
 	return 4;
 }
@@ -801,22 +1014,27 @@ async function writeInitSnapshot(destination, extendsAccount, extendsGateway, so
 		});
 		for (const match of matches) allFiles.add(match);
 	}
+	if (!options.overrides.includes("api")) {
+		for (const match of allFiles) if (isApiTemplatePath(match)) allFiles.delete(match);
+	}
+	if (!options.overrides.includes("api") && !options.overrides.includes("host")) {
+		for (const match of allFiles) if (isComposeTemplatePath(match)) allFiles.delete(match);
+	}
 	const fileHashes = {};
 	for (const filePath of allFiles) {
 		const src = join(sourceDir, filePath);
 		if (!lstatSync(src).isFile()) continue;
-		const content = readFileSync(src);
 		const destPath = sourcePathToDestinationPath(filePath);
-		fileHashes[destPath] = computeHash(content);
+		if (!existsSync(join(destination, destPath))) continue;
+		const content = readFileSync(src);
+		fileHashes[destPath] = computeSnapshotHash(content);
 	}
 	await writeSnapshot(destination, {
 		parentRef: `bos://${extendsAccount}/${extendsGateway}`,
-		files: fileHashes
+		files: fileHashes,
+		starter: options.starter
 	});
 }
-function computeHash(data) {
-	return createHash("sha256").update(data).digest("hex").substring(0, 16);
-}
 function mkTmpDir(prefix) {
 	return mkdtempSync(join(tmpdir(), `${prefix}-`));
 }
@@ -833,17 +1051,23 @@ async function generateDatabaseMigrations(destination) {
 		const pkgPath = join(destination, workspaceDir, "package.json");
 		if (!existsSync(pkgPath)) continue;
 		if (!JSON.parse(readFileSync(pkgPath, "utf-8")).scripts?.["db:generate"]) continue;
-		await execCommand("bun", ["run", "db:generate"], join(destination, workspaceDir));
+		await execCommand("pnpm", [
+			"--dir",
+			"api",
+			"exec",
+			"drizzle-kit",
+			"generate"
+		], join(destination, workspaceDir));
 	}
 }
 const COMMAND_TIMEOUTS = {
-	bun: 5 * 6e4,
-	docker: 5 * 6e4,
-	node_modules: 2 * 6e4,
+	pnpm: 3e5,
+	docker: 3e5,
+	node_modules: 12e4,
 	tar: 6e4
 };
 async function execCommand(command, args, cwd, options) {
-	const timeout = COMMAND_TIMEOUTS[command] ?? 2 * 6e4;
+	const timeout = COMMAND_TIMEOUTS[command] ?? 12e4;
 	await execa(command, args, {
 		cwd,
 		stdio: options?.stdio ?? "pipe",
@@ -865,9 +1089,8 @@ This document provides operational guidance for AI agents working in this everyt
 
 **Start Development:**
 \`\`\`bash
-cp .env.example .env   # First time only
-bun install
-bun run dev
+pnpm install
+pnpm run dev
 \`\`\`
 
 **Check Status:**
@@ -875,7 +1098,51 @@ bun run dev
 bos ps        # List running processes
 bos status    # Project health check
 bos info      # Show configuration
-\`\`\``);
+\`\`\`
+
+**Deploy:**
+
+[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/everything-dev-template?referralCode=MuB_vg&utm_medium=integration&utm_source=template&utm_campaign=generic)
+
+The Railway template deploys the everything.dev Docker image. Set these variables:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| \`BOS_ACCOUNT\` | The NEAR account that owns this app's published configuration on-chain | \`myapp.near\` |
+| \`BOS_GATEWAY\` | The core domain where this app is served | \`myapp.com\` |
+| \`BETTER_AUTH_SECRET\` | Secret for session encryption — generate with \`openssl rand -base64 32\` | (random) |
+
+**Self-deployed production:**
+
+You don't need to wait for a PR to merge and run through CI/CD. Publish your own config on-chain under your own NEAR account and run your own host instance, inheriting the base platform via \`extends\`.
+
+1. **Install near-cli-rs** (the \`bos\` CLI shells out to it for \`bos publish\` and \`bos key generate\`):
+   \`\`\`bash
+   curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/download/v0.23.5/near-cli-rs-installer.sh | sh
+   \`\`\`
+2. **Create a NEAR account** (testnet or mainnet). Named accounts can own subaccounts; implicit hex accounts cannot:
+   \`\`\`bash
+   near account create-account fund-my-account <your-account>.testnet use-faucet network-config testnet
+   \`\`\`
+3. **Generate a publish key** — a function-call key scoped to the FastKV registry contract:
+   \`\`\`bash
+   bos key generate
+   # Output: NEAR_PRIVATE_KEY=ed25519:...
+   \`\`\`
+   Add the key to your account via near-cli-rs, then set \`NEAR_PRIVATE_KEY\` in \`.env\` or CI secrets.
+4. **Update \`bos.app.ts\`** — set \`account\` to your NEAR account, add \`extends\` to inherit the base platform, keep \`domain\` as the gateway:
+   \`\`\`ts
+   { "extends": "bos://<parent-account>/<parent-gateway>", "account": "<your-account>.near", "domain": "<parent-gateway>" }
+   \`\`\`
+ 5. **Publish and deploy:**
+    \`\`\`bash
+    bos deploy           # preflight → build → upload bundles → publish config to FastKV at bos://<your-account>/<gateway> → image/Railway when configured
+    \`\`\`
+6. **Deploy to Railway** (one-click template or \`railway up\`), set \`BOS_ACCOUNT\`, \`BOS_GATEWAY\` (same gateway as parent), and \`BETTER_AUTH_SECRET\`. Your Railway host fetches your config from FastKV and serves live.
+
+\`BOS_GATEWAY\` is the **FastKV lookup key**, not the DNS domain your Railway instance serves on. By keeping the same gateway while using your own \`BOS_ACCOUNT\`, your config lives at a separate FastKV path that \`extends\` the base runtime — you inherit the full platform and override only what you change.
+
+**Tenant creation** (for the admin wizard) is DAO-owned: connect a sputnik-dao account via the Trezu wallet in the admin wizard; the wizard publishes the tenant runtime config under \`bos://<dao-account>/<gateway>\`. No server-side subaccount keys are needed.`);
 	const archLines = ["This is an everything.dev child project. Depending on your overrides, it may include:"];
 	if (has("ui")) archLines.push("- **UI** — React 19 + TanStack Router frontend, loaded via Module Federation");
 	if (has("api")) archLines.push("- **API** — Hono.js + oRPC backend with Effect services");
@@ -886,9 +1153,9 @@ bos info      # Show configuration
 	parts.push(`## Development Workflow
 
 ### Starting Development
-1. \`cp .env.example .env\` (first time)
-2. \`bun install\`
-3. \`bun run dev\``);
+1. \`pnpm install\`
+2. \`pnpm run dev\`
+3. \`bos dev\` creates \`.env\` on first run and starts local Postgres via docker compose when it is down`);
 	parts.push(`### Debugging Issues
 
 **API not responding:**
@@ -901,7 +1168,7 @@ bos info      # Show configuration
 - Clear browser cache and retry
 
 **Type errors:**
-- Run \`bun run typecheck\``);
+- Run \`pnpm run typecheck\``);
 	const changeLines = ["### Making Changes"];
 	if (has("ui")) changeLines.push("- **UI Changes**: Edit `ui/src/` files → hot reload automatically");
 	if (has("api")) changeLines.push("- **API Changes**: Edit `api/src/` files → hot reload automatically");
@@ -934,14 +1201,14 @@ The API plugin receives typed client factories for all other plugins via \`creat
 
 ### Generated Types
 
-\`api/src/lib/plugins-types.gen.ts\`, \`api/src/lib/auth-types.gen.ts\`, \`ui/src/lib/api-types.gen.ts\`, and \`ui/src/lib/auth-types.gen.ts\` are generated by \`bos types gen\` from \`bos.config.json\`. These files are gitignored and auto-regenerated on \`bun install\`, \`typecheck\`, \`bos dev\`, \`bos build\`, and bos plugin management commands.
+\`api/src/lib/plugins-types.gen.ts\`, \`api/src/lib/auth-types.gen.ts\`, \`ui/src/lib/api-types.gen.ts\`, and \`ui/src/lib/auth-types.gen.ts\` are generated by \`bos types gen\` from \`bos.app.ts\`. These files are gitignored and auto-regenerated on \`pnpm install\`, \`typecheck\`, \`bos dev\`, \`bos build\`, and bos plugin management commands.
 
-If you hand-edit \`bos.config.json\`, run \`bos types gen\` or restart \`bos dev\` to regenerate.`);
+If you hand-edit \`bos.app.ts\`, run \`bos types gen\` or restart \`bos dev\` to regenerate.`);
 	const testCommands = [];
 	if (has("api") || has("host") || has("ui")) {
-		testCommands.push("bun run test    # Run all tests");
-		testCommands.push("bun typecheck   # Type check all packages");
-		testCommands.push("bun lint        # Run linting");
+		testCommands.push("pnpm run test    # Run all tests");
+		testCommands.push("pnpm run typecheck   # Type check all packages");
+		testCommands.push("pnpm run lint        # Run linting");
 	}
 	if (testCommands.length > 0) parts.push(`## Testing & Quality
 
@@ -973,31 +1240,64 @@ function MyComponent() {
   const { data } = await apiClient.ping();
 }
 \`\`\``);
+	parts.push(`## Workflow Skills
+
+This repo ships agent workflow skills in \`.agents/skills/\` — the ordered development flow (grill → spec → tickets → implement/tdd → code-review). Start \`/everything-dev-app\` to orient and pick the right next step; \`/ask-matt\` is the router if unsure.
+
+- \`/grill-with-docs\` — sharpen an idea by interview, leaving a paper trail in \`GLOSSARY.md\` and ADRs
+- \`/to-spec\` / \`/to-tickets\` — turn a plan into a spec, then tracer-bullet tickets under \`.scratch/<feature>/issues/\`
+- \`/implement\` + \`/tdd\` — build a ticket test-first at pre-agreed seams
+- \`/code-review\` — two-axis review (Standards + Spec) of the diff since a fixed point
+- \`/diagnosing-bugs\` — diagnosis loop for hard bugs and performance regressions
+
+Run \`/setup-matt-pocock-skills\` once before first use. Tracker and triage conventions live in \`docs/agents/\`.`);
+	parts.push(`## Agent Communication Surface
+
+The host exposes several surfaces for programmatic agent access:
+
+| Surface | Endpoint | Auth | Use |
+|---------|----------|------|-----|
+| MCP | \`POST /api/mcp\` | \`x-api-key\` header or session cookie | MCP clients — auto-generated tools from OpenAPI spec, stateless Streamable HTTP transport |
+| REST/OpenAPI | \`GET/POST/... /api/{path}\` | \`x-api-key\` header or session cookie | Standard REST; Scalar docs at \`GET /api\`, spec at \`GET /api/spec.json\` |
+| oRPC RPC | \`POST /api/rpc/{procedure}\` | \`x-api-key\` header or session cookie | Typed JSON-RPC for all API procedures |
+| Plugin RPC | \`POST /api/rpc/{plugin}/{procedure}\` | \`x-api-key\` header or session cookie | Per-plugin RPC (e.g. \`/api/rpc/auth/getSession\`) |
+| MCP discovery | \`GET /.well-known/mcp.json\` | None | JSON descriptor with server name, endpoint, and auth scheme |
+
+### Authentication for agents
+
+1. Sign in with your NEAR wallet (SIWN) at the website.
+2. Navigate to **Settings → API Keys** at \`/settings/api-keys\`.
+3. Create a new key — the full secret (\`edk_...\`) is shown once. Copy it immediately.
+4. Pass it on every request: \`x-api-key: edk_your_key_here\`
+
+### Architecture note: remotes are code bundles
+
+Remotes in \`bos.app.ts\` are **not hosted APIs** — they are code bundles loaded via Module Federation at runtime. The UI, API, auth, and plugins all run in the same host process. There is no remote server to call; everything is loaded in-process through Module Federation and \`every-plugin\`.`);
 	parts.push(`## Troubleshooting
 
 **Process won't start:**
 \`\`\`bash
 bos kill        # Kill all tracked processes
-bun install     # Ensure dependencies
-bun run dev     # Restart
+pnpm install    # Ensure dependencies
+pnpm run dev    # Restart
 \`\`\`
 
 **Module Federation errors:**
-- Check \`bos.config.json\` URLs are accessible
+- Check \`bos.app.ts\` URLs are accessible
 - Verify shared dependency versions match in package.json
 - Clear browser cache
 
 **Database issues:**
 \`\`\`bash
-bun run db:push   # Push schema changes
-bun run db:studio # Open Drizzle Studio
+pnpm run db:push   # Push schema changes
+pnpm run db:studio # Open Drizzle Studio
 \`\`\`
 
 ## Environment
 
 **Required files:**
 - \`.env\` — Secrets (see \`.env.example\`)
-- \`bos.config.json\` — Runtime configuration (committed)`);
+- \`bos.app.ts\` — Runtime configuration (committed)`);
 	return `${parts.join("\n\n")}\n`;
 }
 function buildChildAgentsMd(skillsBlock, opts) {
@@ -1008,7 +1308,8 @@ async function personalizeAgentsMd(destination, opts) {
 	if (!existsSync(agentsMdPath)) return;
 	const skillsBlock = extractSkillsBlock(readFileSync(agentsMdPath, "utf-8"));
 	if (!skillsBlock) return;
-	writeFileSync(agentsMdPath, buildChildAgentsMd(skillsBlock, opts));
+	const childContent = buildChildAgentsMd(skillsBlock, opts);
+	writeFileSync(agentsMdPath, childContent);
 }
 function generateGitignore() {
 	return `node_modules/
@@ -1020,7 +1321,125 @@ docker-compose.yml
 *.gen.tsx
 `;
 }
+const WORKFLOW_SKILLS_MARKER = "everything-dev-app";
+const WORKFLOW_SKILLS_NOTE = `
+
+## Workflow skills
+
+This repo ships agent workflow skills in \`.agents/skills/\` — the ordered development flow (grill → spec → tickets → implement/tdd → code-review). Start with \`/everything-dev-app\` to orient and pick the right next step. See \`AGENTS.md\` → Workflow Skills.
+`;
+function buildChildLlmsTxt(title) {
+	return `# ${title}
+
+> Application running on the everything.dev runtime.
+
+## Skills
+
+- [Skill](/skill.md): Agent-ready prompt for talking to, running, editing, and publishing this runtime.
+- Workflow skills (in the repo): \`.agents/skills/\` — start with \`everything-dev-app\` for the ordered development flow.
+
+## API
+
+- [OpenAPI docs](/api): Interactive API reference (Scalar)
+- [OpenAPI spec](/api/spec.json): Machine-readable OpenAPI JSON
+- [oRPC RPC](/api/rpc): Typed JSON-RPC endpoint for all API procedures
+- [Plugin RPC](/api/rpc/auth): Auth plugin RPC (session, NEAR SIWN, relay, API keys, organizations)
+
+## MCP
+
+- [MCP server](/api/mcp): Model Context Protocol server (Streamable HTTP, stateless). Auto-generates tools from the API's OpenAPI spec.
+- [MCP discovery](/.well-known/mcp.json): JSON descriptor with server name, endpoint URL, and auth scheme.
+
+## Auth
+
+Authenticate to the API using an API key:
+
+1. Sign in with your NEAR wallet (SIWN) at the website.
+2. Go to **Settings → API Keys** at \`/settings/api-keys\`.
+3. Create a key — the full secret (\`edk_...\`) is shown once.
+4. Pass it on every request: \`x-api-key: edk_your_key_here\`
+
+The \`x-api-key\` header works for \`/api/*\` (REST), \`/api/rpc/*\` (oRPC), and \`/api/mcp\` (MCP).
+
+## Source
+
+- [Repository](https://github.com/NEARBuilders/everything-dev): Clone and read \`AGENTS.md\` for full development instructions, TanStack Intent skills, and workflow guidance.
+`;
+}
+function buildChildSkillMd(title, repository) {
+	return `# ${title} skill
+
+Use this when you want an agent to run, edit, and publish **${title}** — an everything.dev app composed at runtime from \`bos.app.ts\`.
+
+There are two ways to work with this app:
+
+1. **Talk to the app** — use the API via MCP or REST to read/write data without cloning anything.
+2. **Clone and modify** — clone the repository, run locally, edit code, and publish.
+
+## Mode 1: Talk to the app
+
+### MCP endpoint
+
+\`\`\`
+POST /api/mcp
+\`\`\`
+
+Transport: Streamable HTTP (stateless). Connect your MCP client to \`{origin}/api/mcp\` to discover all available tools automatically.
+
+### Authentication
+
+Use an **API key**:
+
+1. Sign in with your NEAR wallet at the website (SIWN).
+2. Navigate to **Settings → API Keys** at \`/settings/api-keys\`.
+3. Create a key — the full secret (\`edk_...\`) is shown once.
+4. Pass it on every request: \`x-api-key: edk_your_key_here\`
+
+### REST / OpenAPI
+
+- **API docs**: \`GET /api\`
+- **OpenAPI spec**: \`GET /api/spec.json\`
+- **oRPC RPC**: \`POST /api/rpc/{procedure}\`
+- **MCP discovery**: \`GET /.well-known/mcp.json\`
+
+## Mode 2: Clone and modify
+
+### TanStack Intent
+
+- Registry entry: \`https://tanstack.com/intent/registry/everything-dev\`
+- Load with TanStack Intent: \`npx @tanstack/intent@latest load everything-dev\`
+
+### Read AGENTS.md first
+
+After cloning, read **\`AGENTS.md\`** at the repo root. It contains operational guidance, TanStack Intent skills, and workflow instructions.
+
+### Workflow skills
+
+The repo ships agent workflow skills in \`.agents/skills/\` — start with \`everything-dev-app\` for the ordered development flow (grill → spec → tickets → implement/tdd → code-review).
+
+### Architecture note
+
+Remotes in \`bos.app.ts\` are **not hosted APIs** — they are code bundles loaded via Module Federation at runtime. Everything runs in the same host process.
+
+### Run locally
+
+\`\`\`bash
+pnpm install
+bos dev
+\`\`\`
+
+### Publish
+
+\`\`\`bash
+bos deploy
+\`\`\`
+
+## Source
+
+${repository ? `- [Repository](${repository}): Clone and read \`AGENTS.md\` for full development instructions.` : `- Clone the repository and read \`AGENTS.md\` for full development instructions.`}
+`;
+}
 
 //#endregion
-export { INIT_ROOT_PATTERNS, buildChildAgentsMd, buildChildRootScripts, buildInitPatterns, buildPluginRouteExclusions, copyFilteredFiles, detectGitRemoteUrl, downloadTarball, execCommand, extractSkillsBlock, fetchParentConfig, generateDatabaseMigrations, getParentOnlyScriptKeys, personalizeAgentsMd, personalizeConfig, removeInitLockfile, resolveCatalogChainSource, resolveRepositoryViaExtendsChain, resolveSourceDir, runBunInstall, runBunInstallForUpgrade, runDockerComposeUp, runTypesGen, scaffoldMinimalProject, sourcePathToDestinationPath, stripOrphanedWorkspacesFromLockfile, writeInitSnapshot };
+export { INIT_ROOT_PATTERNS, PNPM_PACKAGE_MANAGER, buildChildAgentsMd, buildChildLlmsTxt, buildChildRootScripts, buildChildSkillMd, buildInitPatterns, buildPluginRouteExclusions, buildStarterRouteExclusions, convertChildConfigToAppForm, copyFilteredFiles, detectGitRemoteUrl, downloadTarball, execCommand, extractSkillsBlock, fetchParentConfig, generateDatabaseMigrations, getParentOnlyScriptKeys, isApiTemplatePath, isComposeTemplatePath, personalizeAgentsMd, personalizeConfig, readWorkspaceCatalog, removeStrayLockfiles, resolveCatalogChainSource, resolveRepositoryViaExtendsChain, resolveSourceDir, runDockerComposeUp, runPnpmInstall, runPnpmInstallForUpgrade, runTypesGen, scaffoldMinimalProject, sourcePathToDestinationPath, writeChildWorkspaceYaml, writeDevOverlayTemplate, writeInitSnapshot };
 //# sourceMappingURL=init.mjs.map