anhedral 0.1.9 → 0.3.0

package/dist/scaffold.js

@@ -1,1305 +1,1613 @@
-import { readdirSync } from 'node:fs';
+import { lstatSync, mkdirSync, readFileSync, readdirSync, rmdirSync, rmSync } from 'node:fs';
 import path from 'node:path';
 import { env } from 'node:process';
 import { anhedralPrint } from './print.js';
-import { appendGitignore, writeFile } from './util.js';
-import { getSkillCommands } from './commands.js';
-import { API_CLIENT_DEPENDENCIES, CONTRACTS_DEPENDENCIES, PACKAGE_MANAGER, ROOT_DEPENDENCIES, SHARED_DB_DEPENDENCIES, SHARED_PACKAGE_DEPENDENCIES, dependencyManifest, } from './dependencies.js';
-import { resolveToolchain } from './toolchain.js';
-import { scaffoldBackend } from './templates/backend.js';
+import { appendGitignore, execFile, writeFile } from './util.js';
+import { MOBILE_NODE_ENGINE, NODE_ENGINE, PACKAGE_MANAGER, ROOT_DEPENDENCIES, TOOLCHAIN_DEPENDENCIES } from './dependencies.js';
+import { resolveToolchainChannel } from './toolchain.js';
+import { scaffoldApi } from './templates/api.js';
+import { r2BucketName, scaffoldAssetsPrivateProxy } from './templates/assets-private-proxy.js';
+import { scaffoldDesktop } from './templates/desktop.js';
 import { scaffoldExtension } from './templates/extension.js';
-import { scaffoldFrontend } from './templates/frontend.js';
-const SHARED_ENV_GITIGNORE_LINES = ['.env', '.env.*', '!.env.example'];
-const SHARED_TYPESCRIPT_GITIGNORE_LINES = ['*.tsbuildinfo'];
-const ASCII_LOGO = [
-    '  .:-:.',
-    '  .----:.',
-    '  .-------:.',
-    '  :---------:..',
-    '  :--------..--:.',
-    '  :-------.  :----::.',
-    '  :------:   :-------:.',
-    '  :------:  .---------::',
-    '  :-------.  :::::::::.',
-    '  :-------.',
-    '  :-----:.',
-    '  :----:.',
-    '  :-:.',
-];
-const ASCII_LOGO_LINE_DELAY_MS = 30;
-async function printAsciiLogo() {
-    console.log('');
-    for (let index = 0; index < ASCII_LOGO.length; index += 1) {
-        console.log(ASCII_LOGO[index]);
-        if (index < ASCII_LOGO.length - 1) {
-            await new Promise((resolve) => {
-                setTimeout(resolve, ASCII_LOGO_LINE_DELAY_MS);
-            });
-        }
+import { scaffoldMobile } from './templates/mobile.js';
+import { scaffoldSharedPackages } from './templates/shared.js';
+import { scaffoldWeb } from './templates/web.js';
+import { assertPackageName, markdownHeading } from './render.js';
+import { runStagedTransaction } from './transaction.js';
+import { buildGenerationPlan, createManifest, hashContent, readManifest, resolveModules, serializeManifest, } from './architecture/index.js';
+import { GENERATOR_VERSION } from './version.js';
+import { collectModuleContributions } from './architecture/contributions.js';
+import { composeRootEnvironment, composeVercelCrons } from './composers/root.js';
+import { assertTemplateProvenance, materializeTemplates, } from './template-source.js';
+import { desiredWorkspacePolicy, mergeWorkspaceFile, } from './workspace-config.js';
+import { UI_TARGETS, installUiComponents, mergeUiInstalls, resolveUiInstalls, uiInstallKey, } from './ui.js';
+export function supportsMobileInstallNode(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
+    if (!match)
+        return false;
+    const major = Number(match[1]);
+    const minor = Number(match[2]);
+    if (major === 22)
+        return minor >= 13;
+    if (major === 24)
+        return minor >= 3;
+    return major >= 25;
+}
+function assertInstallNodeCompatibility(options) {
+    if (options.apps.mobile
+        && !options.skipInstall
+        && !options.dryRun
+        && !supportsMobileInstallNode(process.versions.node)) {
+        throw new Error(`Installing an Expo mobile workspace requires Node ${MOBILE_NODE_ENGINE}; current Node is ${process.versions.node}. `
+            + 'Switch Node versions or rerun with --skip-install.');
+    }
+}
+const ACTIONS = {
+    checkout: 'actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10',
+    pnpm: 'pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271',
+    node: 'actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38',
+};
+const ROOT_MERGEABLE_FILES = new Set([
+    '.env.example',
+    '.gitignore',
+    '.vercelignore',
+    'package.json',
+    'pnpm-workspace.yaml',
+    'turbo.json',
+    'vercel.json',
+]);
+const GENERATED_CACHE_NAMES = new Set([
+    '.git', '.next', '.output', '.turbo', '.wxt', 'dist', 'node_modules', 'release',
+]);
+function lstatIfPresent(target) {
+    try {
+        return lstatSync(target);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+}
+function pathEntryExists(target) {
+    return lstatIfPresent(target) !== null;
+}
+function normalizedFileMode(mode) {
+    // Windows exposes a synthetic subset of stat mode bits that cannot represent
+    // Unix permissions reliably. Keep the manifest portable by treating those
+    // permissions as unknown and disabling ownership checks on that platform.
+    return process.platform === 'win32' ? null : Number(mode) & 0o777;
+}
+function displayFileMode(mode) {
+    return `0o${mode.toString(8).padStart(3, '0')}`;
+}
+function assertManagedFileMode(relativePath, record, actualStat) {
+    if (record.ownership !== 'managed' || record.mode === null)
+        return;
+    const actualMode = normalizedFileMode(actualStat.mode);
+    if (actualMode === null || actualMode === record.mode)
+        return;
+    throw new Error(`Managed file mode has user modifications: ${relativePath} `
+        + `(expected ${displayFileMode(record.mode)}, found ${displayFileMode(actualMode)}).`);
+}
+function assertManagedFileModes(root, manifest) {
+    for (const [relativePath, record] of Object.entries(manifest.files)) {
+        if (record.ownership !== 'managed' || record.mode === null)
+            continue;
+        const actualStat = lstatIfPresent(path.join(root, relativePath));
+        if (!actualStat || !actualStat.isFile() || actualStat.isSymbolicLink())
+            continue;
+        assertManagedFileMode(relativePath, record, actualStat);
     }
-    console.log('');
 }
-function getUsedToolchain(options, toolchain) {
+function isTransactionMetadata(relativePath) {
+    if (relativePath.includes('/'))
+        return false;
+    return relativePath === '.anhedral-txn'
+        || relativePath === '.anhedral.lock'
+        || relativePath === '.anhedral.lock.reclaim'
+        || /^\.anhedral\.lock\..+\.tmp$/.test(relativePath)
+        || relativePath === '.anhedral-journal.json'
+        || /^\.anhedral-journal\.json\.tmp-.+$/.test(relativePath);
+}
+function projectOptions(options) {
     return {
-        verifiedAt: toolchain.verifiedAt,
-        shadcn: toolchain.shadcn,
-        reactNativeReusables: toolchain.reactNativeReusables,
-        wxt: toolchain.wxt,
+        projectName: options.projectName,
+        displayName: options.displayName,
+        apps: options.apps,
+        features: options.features,
+        skipInstall: options.skipInstall || options.dryRun,
+        nativeStyling: options.nativeStyling,
     };
 }
-function normalizeStack(options, generatedPaths) {
-    const toolchain = resolveToolchain(options.toolchainChannel);
+function selectionsFromModules(modules) {
+    const selected = new Set(modules);
     return {
-        schema_version: '2.0.0',
-        mode: 'fullstack',
-        project_name: options.projectName,
-        display_name: options.displayName,
-        frontend: 'expo_react_native_reusables',
-        extension: 'wxt_chrome_extension',
-        backend: 'fastify',
-        auth: options.auth,
-        payments: options.payments,
-        storage: 'cloudflare_r2_via_aws_s3_sdk',
-        database: 'neon_plus_drizzle',
-        skills: getSkillCommands(),
-        outputs: {
-            monorepo: true,
-            package_manager: 'pnpm',
-            dependency_manifest: dependencyManifest(),
-            toolchain_channel: options.toolchainChannel,
-            toolchain: getUsedToolchain(options, toolchain),
-            generated_paths: generatedPaths,
+        apps: {
+            web: selected.has('web'),
+            mobile: selected.has('mobile'),
+            api: selected.has('api'),
+            desktop: selected.has('desktop'),
+            extension: selected.has('extension'),
+        },
+        features: {
+            database: selected.has('db'),
+            auth: selected.has('auth'),
+            billing: selected.has('billing'),
+            storage: selected.has('storage'),
+            nativeSubscriptions: selected.has('native-subscriptions'),
         },
     };
 }
-function writeJsonFile(filePath, payload) {
-    writeFile(filePath, JSON.stringify(payload, null, 2) + '\n');
+function canonicalInitOptions(options) {
+    assertPackageName(options.projectName);
+    const resolution = resolveModules(options.modules);
+    return {
+        ...options,
+        uiComponents: options.uiComponents ?? [],
+        nativeStyling: options.nativeStyling ?? 'nativewind',
+        modules: [...resolution.requestedModules],
+        ...selectionsFromModules(resolution.resolvedModules),
+    };
+}
+function optionsFromManifest(manifest, addOptions, modules) {
+    const resolution = resolveModules(modules);
+    return {
+        projectName: manifest.project.name,
+        displayName: manifest.project.displayName,
+        modules: [...resolution.requestedModules],
+        ...selectionsFromModules(resolution.resolvedModules),
+        skipInstall: addOptions.skipInstall,
+        dryRun: addOptions.dryRun,
+        json: addOptions.json,
+        toolchainChannel: addOptions.toolchainChannel ?? toolchainChannelFromManifest(manifest),
+        uiComponents: [],
+        nativeStyling: manifest.ui.nativeStyling,
+    };
+}
+function toolchainChannelFromManifest(manifest) {
+    return resolveToolchainChannel(manifest.toolchain);
 }
 function ensureScaffoldRoot(root) {
-    const allowedEntries = new Set(['.git', '.gitignore', '.DS_Store']);
-    const unexpected = readdirSync(root).filter((entry) => !allowedEntries.has(entry));
+    const rootStat = lstatIfPresent(root);
+    if (!rootStat)
+        throw new Error(`Scaffold destination is not a directory: ${root}`);
+    if (rootStat.isSymbolicLink())
+        throw new Error(`Refusing scaffold destination that is a symbolic link: ${root}`);
+    if (!rootStat.isDirectory())
+        throw new Error(`Scaffold destination is not a directory: ${root}`);
+    const allowed = new Set(['.git', '.gitignore', '.DS_Store', '.anhedral.lock']);
+    const unexpected = readdirSync(root).filter((entry) => !allowed.has(entry));
     if (unexpected.length > 0) {
-        throw new Error(`Current directory is not empty. Remove existing files before running anhedral init. Found: ${unexpected.join(', ')}`);
+        throw new Error(`Current directory is not empty. Found: ${unexpected.join(', ')}`);
     }
 }
-function writeRootPackageJson(root, projectName, scripts, workspaces, extraFields) {
-    const packageJson = {
-        name: projectName,
+function selectedAppFilters(apps) {
+    return Object.entries(apps)
+        .filter(([, enabled]) => enabled)
+        .map(([name]) => `./apps/${name}`);
+}
+function rootScripts(options) {
+    const filters = selectedAppFilters(options.apps);
+    const scripts = {
+        dev: filters.length ? `turbo dev --parallel ${filters.map((entry) => `--filter=${entry}`).join(' ')}` : 'echo "No app surfaces selected."',
+        build: 'turbo build',
+        typecheck: 'turbo typecheck',
+    };
+    const verify = [];
+    if (options.apps.web) {
+        scripts['dev:web'] = 'pnpm --filter ./apps/web dev';
+        scripts['verify:web'] = 'pnpm --filter ./apps/web typecheck && pnpm --filter ./apps/web build';
+        verify.push('pnpm verify:web');
+    }
+    if (options.apps.web || options.apps.api) {
+        scripts['deploy:vercel:link'] = `pnpm dlx vercel@${TOOLCHAIN_DEPENDENCIES.vercel} link`;
+        scripts['deploy:vercel:preview'] = `pnpm dlx vercel@${TOOLCHAIN_DEPENDENCIES.vercel} deploy`;
+        scripts['deploy:vercel:production'] = `pnpm dlx vercel@${TOOLCHAIN_DEPENDENCIES.vercel} deploy --prod`;
+        scripts['deploy:vercel:inspect'] = `pnpm dlx vercel@${TOOLCHAIN_DEPENDENCIES.vercel} inspect`;
+        scripts['deploy:vercel:domain:inspect'] = `pnpm dlx vercel@${TOOLCHAIN_DEPENDENCIES.vercel} domains inspect`;
+    }
+    if (options.apps.mobile) {
+        scripts['dev:mobile'] = 'pnpm --filter ./apps/mobile dev';
+        scripts['verify:mobile'] = 'pnpm --filter ./apps/mobile typecheck && pnpm --filter ./apps/mobile build:web';
+        verify.push('pnpm verify:mobile');
+        const eas = `pnpm --dir apps/mobile dlx eas-cli@${TOOLCHAIN_DEPENDENCIES['eas-cli']}`;
+        scripts['mobile:eas:login'] = `${eas} login`;
+        scripts['mobile:eas:init'] = `${eas} init`;
+        scripts['mobile:build:internal:ios'] = `${eas} build --platform ios --profile preview`;
+        scripts['mobile:build:internal:android'] = `${eas} build --platform android --profile preview`;
+        scripts['mobile:build:production:ios'] = `${eas} build --platform ios --profile production`;
+        scripts['mobile:build:production:android'] = `${eas} build --platform android --profile production`;
+        scripts['mobile:submit:ios'] = `${eas} submit --platform ios --profile production --latest`;
+        scripts['mobile:submit:android'] = `${eas} submit --platform android --profile production --latest`;
+    }
+    if (options.apps.api) {
+        scripts['dev:api'] = 'pnpm --filter ./apps/api dev';
+        scripts['verify:api'] = 'pnpm --filter ./apps/api test:coverage && pnpm --filter ./apps/api build';
+        verify.push('pnpm verify:api');
+    }
+    if (options.apps.desktop) {
+        scripts['dev:desktop'] = 'pnpm --filter ./apps/desktop dev';
+        scripts['desktop:build'] = 'pnpm --filter ./apps/desktop package';
+        scripts['verify:desktop'] = 'pnpm --filter ./apps/desktop typecheck && pnpm --filter ./apps/desktop build';
+        verify.push('pnpm verify:desktop');
+    }
+    if (options.apps.extension) {
+        scripts['dev:extension'] = 'pnpm --filter ./apps/extension dev';
+        scripts['extension:zip'] = 'pnpm --filter ./apps/extension zip';
+        scripts['verify:extension'] = 'pnpm --filter ./apps/extension typecheck && pnpm --filter ./apps/extension zip';
+        verify.push('pnpm verify:extension');
+    }
+    if (options.features.database) {
+        scripts['neon:login'] = `pnpm dlx neonctl@${TOOLCHAIN_DEPENDENCIES.neonctl} auth`;
+        scripts['neon:project:create'] = `pnpm dlx neonctl@${TOOLCHAIN_DEPENDENCIES.neonctl} projects create`;
+        scripts['db:generate'] = 'pnpm --filter @shared/db db:generate';
+        scripts['db:migrate'] = 'pnpm --filter @shared/db db:migrate';
+        scripts['db:check'] = 'pnpm --filter @shared/db db:check';
+        scripts['db:studio'] = 'pnpm --filter @shared/db db:studio';
+        scripts['verify:db'] = 'node scripts/verify-db-migrations.mjs && pnpm db:check';
+        verify.push('pnpm verify:db');
+    }
+    if (options.features.storage) {
+        const bucketName = r2BucketName(options.projectName);
+        scripts['r2:login'] = `pnpm dlx wrangler@${TOOLCHAIN_DEPENDENCIES.wrangler} login`;
+        scripts['r2:bucket:create'] = `pnpm dlx wrangler@${TOOLCHAIN_DEPENDENCIES.wrangler} r2 bucket create ${bucketName}`;
+        scripts['r2:cors:list'] = `pnpm dlx wrangler@${TOOLCHAIN_DEPENDENCIES.wrangler} r2 bucket cors list ${bucketName}`;
+        scripts['r2:cors:set'] = `pnpm dlx wrangler@${TOOLCHAIN_DEPENDENCIES.wrangler} r2 bucket cors set ${bucketName} --file cloudflare/r2-cors.template.json`;
+        scripts['assets:proxy:check'] = 'pnpm --filter ./apps/assets-private-proxy check';
+        scripts['assets:proxy:dev'] = 'pnpm --filter ./apps/assets-private-proxy dev';
+        scripts['assets:proxy:deploy'] = 'pnpm --filter ./apps/assets-private-proxy deploy';
+        scripts['verify:assets-proxy'] = 'pnpm assets:proxy:check';
+        verify.push('pnpm verify:assets-proxy');
+    }
+    if (!Object.values(options.apps).some(Boolean))
+        verify.unshift('pnpm typecheck');
+    scripts.verify = verify.join(' && ');
+    return scripts;
+}
+function desiredRootPackage(options) {
+    const workspaces = [
+        Object.values(options.apps).some(Boolean) ? 'apps/*' : null,
+        options.apps.api || options.features.database ? 'packages/*' : null,
+    ].filter((value) => value !== null);
+    return {
+        name: options.projectName,
         private: true,
         version: '0.1.0',
         packageManager: PACKAGE_MANAGER,
-        scripts,
-        ...extraFields,
+        engines: { node: options.apps.mobile ? MOBILE_NODE_ENGINE : NODE_ENGINE },
+        scripts: rootScripts(options),
+        workspaces,
+        devDependencies: ROOT_DEPENDENCIES.devDependencies,
     };
-    if (workspaces && workspaces.length > 0) {
-        packageJson.workspaces = workspaces;
+}
+function sameJson(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        return Array.isArray(left)
+            && Array.isArray(right)
+            && left.length === right.length
+            && left.every((entry, index) => sameJson(entry, right[index]));
     }
-    writeJsonFile(path.join(root, 'package.json'), packageJson);
+    if (!isJsonRecord(left) || !isJsonRecord(right))
+        return false;
+    const leftKeys = Object.keys(left).sort();
+    const rightKeys = Object.keys(right).sort();
+    return leftKeys.length === rightKeys.length
+        && leftKeys.every((key, index) => key === rightKeys[index] && sameJson(left[key], right[key]));
 }
-function writePnpmWorkspace(root, packages) {
-    const serializedPackages = packages.map((entry) => `  - '${entry}'`).join('\n');
-    writeFile(path.join(root, 'pnpm-workspace.yaml'), `packages:\n${serializedPackages}\n`);
+function isJsonRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function writeSkillsGuide(root, commands) {
-    const commandBlock = commands.map((command) => `${command}\n`).join('\n');
-    writeFile(path.join(root, 'install-skills.sh'), `#!/usr/bin/env bash
-# Manual skill installation guide for this project.
-#
-# Run the commands below after setup. The skills CLI will prompt you to:
-# - choose which agents to install to
-# - choose whether the install should be project-scoped or global
-#
-# If you want the skill files tracked with this project, choose the project scope.
-# Run each command one at a time if you want to review each prompt separately.
-
-${commandBlock}`);
+const MISSING_JSON_VALUE = Symbol('missing-json-value');
+function includesJson(values, candidate) {
+    return values.some((value) => sameJson(value, candidate));
 }
-function writeRootDocs(root, options, stack) {
-    const toolchainLine = stack.outputs.toolchain.verifiedAt
-        ? `${options.toolchainChannel} (verified ${stack.outputs.toolchain.verifiedAt})`
-        : `${options.toolchainChannel} (floating latest)`;
-    const generatedPaths = stack.outputs.generated_paths.map((entry) => `- \`${entry}\``).join('\n') || '- `.`';
-    writeFile(path.join(root, 'README.md'), `# ${options.displayName}
-
-Generated by anhedral.
-
-## Stack
+function mergeChangedArrays(current, desired, previous) {
+    const merged = [];
+    for (const entry of desired) {
+        if ((!includesJson(previous, entry) || includesJson(current, entry)) && !includesJson(merged, entry)) {
+            merged.push(entry);
+        }
+    }
+    for (const entry of current) {
+        if (!includesJson(previous, entry) && !includesJson(merged, entry))
+            merged.push(entry);
+    }
+    return merged;
+}
+function mergeGeneratedThreeWay(current, desired, previous, fieldPath) {
+    if (current === MISSING_JSON_VALUE) {
+        if (desired === MISSING_JSON_VALUE)
+            return MISSING_JSON_VALUE;
+        if (previous === MISSING_JSON_VALUE)
+            return desired;
+        if (sameJson(desired, previous))
+            return MISSING_JSON_VALUE;
+        throw new Error(`Conflict in ${fieldPath}: a generated value changed after the user removed it.`);
+    }
+    if (desired === MISSING_JSON_VALUE) {
+        if (previous === MISSING_JSON_VALUE)
+            return current;
+        if (sameJson(current, previous))
+            return MISSING_JSON_VALUE;
+        return current;
+    }
+    if (previous === MISSING_JSON_VALUE) {
+        if (sameJson(current, desired))
+            return desired;
+        if (isJsonRecord(current) && isJsonRecord(desired)) {
+            return mergeGeneratedRecords(current, desired, {}, fieldPath, true);
+        }
+        if (Array.isArray(current) && Array.isArray(desired)) {
+            return [...desired, ...current.filter((entry) => !includesJson(desired, entry))];
+        }
+        throw new Error(`Conflict in ${fieldPath}: a newly generated value collides with a user-defined value.`);
+    }
+    if (sameJson(current, desired))
+        return current;
+    if (sameJson(current, previous))
+        return desired;
+    if (sameJson(desired, previous))
+        return current;
+    if (isJsonRecord(current) && isJsonRecord(desired) && isJsonRecord(previous)) {
+        return mergeGeneratedRecords(current, desired, previous, fieldPath, true);
+    }
+    if (Array.isArray(current) && Array.isArray(desired) && Array.isArray(previous)) {
+        return mergeChangedArrays(current, desired, previous);
+    }
+    throw new Error(`Conflict in ${fieldPath}: both the generator and the user changed the value.`);
+}
+function mergeGeneratedOwned(current, desired, fieldPath) {
+    if (desired === MISSING_JSON_VALUE)
+        return current;
+    if (current === MISSING_JSON_VALUE)
+        return desired;
+    if (isJsonRecord(current) && isJsonRecord(desired)) {
+        return mergeGeneratedRecords(current, desired, {}, fieldPath, false);
+    }
+    if (Array.isArray(current) && Array.isArray(desired)) {
+        return [...desired, ...current.filter((entry) => !includesJson(desired, entry))];
+    }
+    if (isJsonRecord(current)
+        || isJsonRecord(desired)
+        || Array.isArray(current)
+        || Array.isArray(desired)) {
+        throw new Error(`Conflict in ${fieldPath}: the generator version changed and the value shape is ambiguous.`);
+    }
+    // Without a trustworthy previous-generator snapshot, an existing scalar may
+    // be user-authored. Preserve it instead of silently resetting it to today's
+    // default. Newly introduced keys still take the desired value above.
+    return current;
+}
+function mergeGeneratedRecords(current, desired, previous, fieldPath, trustPrevious) {
+    const keys = [...new Set([...Object.keys(desired), ...Object.keys(current), ...Object.keys(previous)])];
+    const entries = [];
+    for (const key of keys) {
+        const currentValue = Object.hasOwn(current, key) ? current[key] : MISSING_JSON_VALUE;
+        const desiredValue = Object.hasOwn(desired, key) ? desired[key] : MISSING_JSON_VALUE;
+        const previousValue = Object.hasOwn(previous, key) ? previous[key] : MISSING_JSON_VALUE;
+        const value = trustPrevious
+            ? mergeGeneratedThreeWay(currentValue, desiredValue, previousValue, `${fieldPath}.${key}`)
+            : mergeGeneratedOwned(currentValue, desiredValue, `${fieldPath}.${key}`);
+        if (value !== MISSING_JSON_VALUE)
+            entries.push([key, value]);
+    }
+    return Object.fromEntries(entries);
+}
+function mergeGeneratedStructure(current, desired, previous, fieldPath, trustPrevious) {
+    if (isJsonRecord(current) && isJsonRecord(desired)) {
+        return mergeGeneratedRecords(current, desired, isJsonRecord(previous) ? previous : {}, fieldPath, trustPrevious);
+    }
+    return trustPrevious
+        ? mergeGeneratedThreeWay(current, desired, previous, fieldPath)
+        : mergeGeneratedOwned(current, desired, fieldPath);
+}
+function mergeStringMap(current, desired, previousGenerated, filePath, allowGeneratedUpdates) {
+    const existing = current && typeof current === 'object' ? current : {};
+    const generated = desired && typeof desired === 'object' ? desired : {};
+    const previous = previousGenerated && typeof previousGenerated === 'object'
+        ? previousGenerated
+        : {};
+    const merged = { ...existing };
+    for (const [key, value] of Object.entries(generated)) {
+        if (merged[key] === undefined || merged[key] === value || allowGeneratedUpdates || merged[key] === previous[key])
+            merged[key] = value;
+        else
+            throw new Error(`Conflict in ${filePath}: key ${key} has a user-defined value.`);
+    }
+    return Object.fromEntries(Object.entries(merged).sort(([left], [right]) => left.localeCompare(right)));
+}
+function writeRootPackage(root, options, mode, allowGeneratedUpdates, previousGenerated) {
+    const filePath = path.join(root, 'package.json');
+    const desired = desiredRootPackage(options);
+    if (mode === 'init' || !pathEntryExists(filePath)) {
+        writeFile(filePath, JSON.stringify(desired, null, 2) + '\n');
+        return;
+    }
+    const current = JSON.parse(readFileSync(filePath, 'utf8'));
+    const desiredWorkspaces = desired.workspaces;
+    const currentWorkspaces = Array.isArray(current.workspaces) ? current.workspaces.filter((value) => typeof value === 'string') : [];
+    const mergeMetadataField = (field) => {
+        const currentValue = current[field];
+        const desiredValue = desired[field];
+        const previousValue = previousGenerated?.[field];
+        if (allowGeneratedUpdates
+            || currentValue === undefined
+            || (previousValue !== undefined && sameJson(currentValue, previousValue))) {
+            return desiredValue;
+        }
+        if (previousValue !== undefined && !sameJson(previousValue, desiredValue)) {
+            throw new Error(`Conflict in package.json: ${field} was user-modified and must satisfy the newly selected modules.`);
+        }
+        return currentValue;
+    };
+    const merged = {
+        ...desired,
+        ...current,
+        private: true,
+        packageManager: mergeMetadataField('packageManager'),
+        engines: mergeMetadataField('engines'),
+        workspaces: [...new Set([...currentWorkspaces, ...desiredWorkspaces])].sort(),
+        scripts: mergeStringMap(current.scripts, desired.scripts, previousGenerated?.scripts, 'package.json scripts', allowGeneratedUpdates),
+        devDependencies: mergeStringMap(current.devDependencies, desired.devDependencies, previousGenerated?.devDependencies, 'package.json devDependencies', allowGeneratedUpdates),
+    };
+    writeFile(filePath, JSON.stringify(merged, null, 2) + '\n');
+}
+function mergeJsonConfig(root, relativePath, desired, previousGenerated, trustPreviousGenerated) {
+    const filePath = path.join(root, relativePath);
+    if (!pathEntryExists(filePath)) {
+        writeFile(filePath, JSON.stringify(desired, null, 2) + '\n');
+        return;
+    }
+    const current = JSON.parse(readFileSync(filePath, 'utf8'));
+    const merged = mergeGeneratedStructure(current, desired, previousGenerated, relativePath, trustPreviousGenerated);
+    writeFile(filePath, JSON.stringify(merged, null, 2) + '\n');
+}
+function writeRootEnv(root, options) {
+    const corsOrigins = [
+        options.apps.web ? 'http://localhost:3000' : null,
+        options.apps.mobile ? 'http://localhost:8081' : null,
+        options.apps.desktop ? 'http://127.0.0.1:5173' : null,
+        options.apps.desktop ? 'null' : null,
+    ].filter((value) => value !== null);
+    const lines = composeRootEnvironment(collectModuleContributions(options.modules), { corsOrigins });
+    const filePath = path.join(root, '.env.example');
+    const current = pathEntryExists(filePath) ? readFileSync(filePath, 'utf8') : '';
+    const existingKeys = new Set([...current.matchAll(/^([A-Z][A-Z0-9_]*)=/gm)].map((match) => match[1]));
+    const additions = lines.filter((line) => !existingKeys.has(line.slice(0, line.indexOf('='))));
+    const separator = current && additions.length ? (current.endsWith('\n') ? '\n' : '\n\n') : '';
+    writeFile(filePath, `${current}${separator}${additions.join('\n')}${additions.length ? '\n' : ''}`);
+}
+function desiredTurboConfig() {
+    return {
+        $schema: 'https://turborepo.dev/schema.json',
+        tasks: {
+            build: {
+                dependsOn: ['^build'],
+                outputs: ['.next/**', '!.next/cache/**', '.output/**', 'dist/**'],
+            },
+            typecheck: { dependsOn: ['^build'] },
+            dev: { cache: false, persistent: true },
+        },
+    };
+}
+function desiredVercelConfig(options) {
+    const services = {};
+    if (options.apps.api) {
+        services.api = { root: 'apps/api' };
+    }
+    if (options.apps.web) {
+        services.web = { root: 'apps/web', framework: 'nextjs' };
+    }
+    const rewrites = [
+        options.apps.api ? { source: '/api/(.*)', destination: { service: 'api' } } : null,
+        options.apps.web ? { source: '/(.*)', destination: { service: 'web' } } : null,
+    ].filter((rewrite) => rewrite !== null);
+    const crons = composeVercelCrons(collectModuleContributions(options.modules));
+    return {
+        $schema: 'https://openapi.vercel.sh/vercel.json',
+        ...(Object.keys(services).length > 0 ? { services } : {}),
+        ...(rewrites.length > 0 ? { rewrites } : {}),
+        ...(crons.length > 0 ? { crons } : {}),
+    };
+}
+function generatedCi(options) {
+    const nodeVersion = options.apps.mobile ? '22.13.0' : '20.19.0';
+    const commands = [
+        'pnpm typecheck',
+        options.apps.api ? 'pnpm --filter ./apps/api test:coverage' : null,
+        'pnpm build',
+    ].filter((value) => value !== null).join('\n          ');
+    const databaseSteps = options.features.database ? `
+      - name: Verify committed database migration history
+        run: pnpm verify:db
+      - name: Verify database schema and migration parity
+        run: |
+          pnpm db:generate
+          git diff --exit-code -- packages/db/migrations
+          if [[ -n "$(git status --porcelain --untracked-files=all -- packages/db/migrations)" ]]; then
+            echo "drizzle-kit generated uncommitted migration artifacts:"
+            git status --short --untracked-files=all -- packages/db/migrations
+            exit 1
+          fi
+` : '';
+    return `name: Anhedral CI
 
-- Mode: fullstack
-- Frontend: Expo + React Native Reusables
-- Backend: Fastify
-- Extension: WXT Chrome extension
-- Shared packages: \`packages/*\`
-- Auth: ${options.auth}
-- Payments: ${options.payments}
-- Database: ${options.db} + ${options.orm}
-- Storage: ${options.storage}
-- API: ${options.api ?? 'framework-native'}
-- Toolchain: ${toolchainLine}
-- Dependency manifest: recorded in \`stack.json\`
+on:
+  pull_request:
+  push:
+    branches: [main]
 
-## Generated paths
+permissions:
+  contents: read
 
-${generatedPaths}
+concurrency:
+  group: anhedral-ci-\${{ github.ref }}
+  cancel-in-progress: true
 
-## First Run
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: ${ACTIONS.checkout} # v6
+        with:
+          persist-credentials: false
+      - uses: ${ACTIONS.pnpm} # v6
+        with:
+          version: ${PACKAGE_MANAGER.replace('pnpm@', '')}
+      - uses: ${ACTIONS.node} # v6
+        with:
+          node-version: ${nodeVersion}
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+${databaseSteps}      - name: Verify generated workspace
+        run: |
+          ${commands}
+`;
+}
+function writeDatabaseVerificationScript(root, options) {
+    if (!options.features.database)
+        return;
+    writeFile(path.join(root, 'scripts/verify-db-migrations.mjs'), `import { readdirSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
-\`\`\`bash
-pnpm install
-cp .env.example .env
-# Frontend/.env is generated for local Expo development
-cp Extension/.env.example Extension/.env
-pnpm db:generate
-pnpm db:migrate
-pnpm verify
-pnpm dev:backend
-pnpm dev:frontend
-pnpm dev:extension
-\`\`\`
+const projectRoot = process.cwd();
+const migrationsRoot = path.join(projectRoot, 'packages/db/migrations');
 
-The generated env files intentionally contain placeholder provider values. That is enough to inspect the project structure and run backend smoke tests, but the full UI needs real provider keys before auth, billing, uploads, and extension sign-in behave like production.
-
-For a provider-free backend smoke test, keep \`ANHEDRAL_DEMO=true\` in \`Backend/.env\`. Demo mode returns a signed-in sample user and active subscription responses without Clerk, RevenueCat, or Stripe credentials. It is for local development only.
-
-## Provider Setup
-
-Use this order so each service has the domains and callback URLs it needs:
-
-1. Neon database
-   - Create a Neon project and database: https://neon.com/docs/get-started-with-neon/connect-neon
-   - Put the pooled connection string in \`DATABASE_URL\` in \`.env\`, \`Backend/.env\`, and the Backend Vercel project.
-   - Run \`pnpm db:generate\` and \`pnpm db:migrate\` after \`DATABASE_URL\` is real.
-
-2. Clerk auth
-   - Expo setup: https://docs.expo.dev/guides/using-clerk/
-   - Clerk Expo quickstart: https://clerk.com/docs/quickstarts/get-started-with-expo
-   - Set \`EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY\` in \`Frontend/.env\`, Vercel Frontend, and EAS.
-   - Set \`CLERK_PUBLISHABLE_KEY\` and \`CLERK_SECRET_KEY\` in \`Backend/.env\` and Vercel Backend.
-   - Set \`VITE_CLERK_PUBLISHABLE_KEY\` in \`Extension/.env\`.
-   - Add allowed origins for \`http://localhost:8081\`, the Frontend Vercel domain, and the extension origin after Chrome assigns an extension id.
-
-3. RevenueCat + Stripe
-   - RevenueCat Web overview: https://www.revenuecat.com/docs/web/overview
-   - RevenueCat Stripe Billing integration: https://www.revenuecat.com/docs/web/integrations/stripe
-   - Stripe API keys: https://docs.stripe.com/keys
-   - Create an entitlement named \`pro\`.
-   - Create iOS, Android, and Web apps in RevenueCat and copy their public SDK keys into \`EXPO_PUBLIC_RC_API_KEY_IOS\`, \`EXPO_PUBLIC_RC_API_KEY_ANDROID\`, and \`EXPO_PUBLIC_RC_WEB_API_KEY\`.
-   - Set \`EXPO_PUBLIC_RC_ENTITLEMENT_ID=pro\`.
-   - Set \`RC_SECRET_API_KEY\` and \`RC_WEBHOOK_SECRET\` only in Backend envs.
-   - Point the RevenueCat webhook to \`https://<backend-domain>/webhooks/revenuecat\`.
-
-4. Cloudflare R2/CDN
-   - R2 S3-compatible setup: https://developers.cloudflare.com/r2/get-started/s3/
-   - R2 API tokens: https://developers.cloudflare.com/r2/api/tokens/
-   - Create a bucket and least-privilege API token.
-   - Set \`R2_ACCOUNT_ID\`, \`R2_ACCESS_KEY_ID\`, \`R2_SECRET_ACCESS_KEY\`, and \`R2_BUCKET\` only in Backend envs.
-   - If you use a public CDN/custom domain for uploaded files, add that URL to your own app config before exposing uploads broadly.
-
-5. Vercel web/API deploys
-   - Monorepo docs: https://vercel.com/docs/monorepos
-   - Monorepo FAQ for source outside root: https://vercel.com/docs/monorepos/monorepo-faq
-   - Import this same Git repository twice. Use \`Frontend\` as the root directory for the Expo web project and \`Backend\` as the root directory for the Fastify API project.
-   - Enable access to source files outside each project root so workspace packages under \`packages/*\` are available during builds.
-   - Frontend build command: \`pnpm build:web\`; output directory: \`dist\`.
-   - Backend build command: \`pnpm build\`; Vercel detects \`Backend/src/index.ts\` as the Fastify entrypoint.
-
-6. EAS native app builds
-   - EAS docs: https://docs.expo.dev/eas/
-   - Store submission docs: https://docs.expo.dev/deploy/submit-to-app-stores/
-   - Use \`Frontend\` as the Expo project root for iOS and Android builds. Vercel deploys the web export from the same source.
-
-7. Chrome Web Store
-   - WXT publishing: https://wxt.dev/guide/essentials/publishing.html
-   - Chrome publishing: https://developer.chrome.com/docs/webstore/publish
-   - Build with \`pnpm extension:zip\`, then upload \`Extension/.output/*-chrome.zip\` in the Chrome Web Store Developer Dashboard.
-
-## Setup Notes
-
-1. Copy \`.env.example\` into the runtime env files your apps need and fill in provider values.
-2. Review \`install-skills.sh\` and run the listed skill commands manually so you can choose scope and agent targets.
-3. Add the real provider configuration for Clerk, RevenueCat, Stripe web billing, Neon, and R2 where the scaffolded helper files indicate.
-4. Use \`stack.json\` when debugging generated projects; it records the verified dependency manifest used by this init run.
-5. Review \`PRODUCTION.md\` before connecting live provider projects.
-6. Run database generation and migrations from the shared DB package:
-
-\`\`\`bash
-pnpm db:generate
-pnpm db:migrate
-\`\`\`
+function collectSqlFiles(directory, relativeDirectory = '') {
+  const files = [];
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    const relativePath = path.posix.join(relativeDirectory, entry.name);
+    if (entry.isDirectory()) files.push(...collectSqlFiles(path.join(directory, entry.name), relativePath));
+    else if (entry.isFile() && entry.name.endsWith('.sql')) files.push(path.posix.join('packages/db/migrations', relativePath));
+  }
+  return files.sort();
+}
 
-Run deployment readiness checks before pushing:
+const sqlFiles = collectSqlFiles(migrationsRoot);
+if (sqlFiles.length === 0) {
+  throw new Error('No database migration SQL is committed. Run \`pnpm db:generate\`, review packages/db/migrations, and commit the generated migration before verification.');
+}
 
-\`\`\`bash
-pnpm verify
-pnpm verify:frontend
-pnpm verify:backend
-pnpm verify:extension
-\`\`\`
+const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+  cwd: projectRoot,
+  encoding: 'utf8',
+  stdio: ['ignore', 'pipe', 'ignore'],
+});
 
-7. Build or run the extension separately. It is not deployed by Vercel:
+if (gitRoot.status === 0) {
+  const repositoryRoot = String(gitRoot.stdout).trim();
+  const tracked = spawnSync('git', ['ls-files', '--full-name', '-z', '--', 'packages/db/migrations'], {
+    cwd: projectRoot,
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  if (tracked.status !== 0) {
+    throw new Error('Unable to inspect committed database migrations: ' + String(tracked.stderr).trim());
+  }
+  const trackedFiles = new Set(String(tracked.stdout)
+    .split('\\0')
+    .filter(Boolean)
+    .map((entry) => path.resolve(repositoryRoot, entry)));
+  const untrackedSql = sqlFiles.filter((entry) => !trackedFiles.has(path.resolve(projectRoot, entry)));
+  if (untrackedSql.length > 0) {
+    throw new Error('Database migration SQL must be tracked by Git before verification: ' + untrackedSql.join(', '));
+  }
+} else if (process.env.CI) {
+  throw new Error('CI must run database migration verification inside a Git worktree.');
+}
 
-\`\`\`bash
-pnpm dev:extension
-pnpm extension:zip
-\`\`\`
+console.log('Database migration baseline is present' + (gitRoot.status === 0 ? ' and tracked by Git.' : '.'));
 `);
 }
-function writeProductionGuide(root, options) {
-    writeFile(path.join(root, 'PRODUCTION.md'), `# ${options.displayName} Production Guide
-
-## Project Structure
-
-The generated app is one pnpm monorepo:
-
-\`\`\`txt
-.
-├─ Frontend/        Expo + React Native Reusables app
-├─ Backend/         Fastify API
-├─ Extension/       WXT Chrome extension
-├─ packages/
-│  ├─ api-client/   shared typed API client
-│  ├─ config/       shared config constants/helpers
-│  ├─ contracts/    shared Zod request/response contracts
-│  ├─ db/           Drizzle schema, Neon client, migrations
-│  └─ types/        shared TypeScript types
-├─ PRODUCTION.md    development and deployment guide
-├─ turbo.json       workspace build graph
-└─ package.json     root scripts
-\`\`\`
-
-## Frontend
-
-\`Frontend\` is the single Expo source for:
-
-- Web on Vercel
-- iOS through EAS
-- Android through EAS
-
-Important files:
-
-- \`Frontend/package.json\`: Expo scripts
-- \`Frontend/vercel.json\`: Vercel web export config
-- \`Frontend/eas.json\`: native build profiles
-- \`Frontend/app\`: Expo Router screens
-
-Build output goes to \`Frontend/dist\`.
-
-## Backend
-
-\`Backend\` is the Fastify API.
-
-Important files:
+function isRecordedFileUnmodified(root, manifest, relativePath) {
+    if (!manifest)
+        return true;
+    const record = manifest.files[relativePath];
+    if (!record?.hash)
+        return false;
+    const filePath = path.join(root, relativePath);
+    return pathEntryExists(filePath) && hashContent(readFileSync(filePath)) === record.hash;
+}
+function writeRootFiles(root, options, mode, currentRoot, manifest) {
+    const packageUnmodified = isRecordedFileUnmodified(currentRoot, manifest, 'package.json');
+    const workspaceUnmodified = manifest !== undefined
+        && isRecordedFileUnmodified(currentRoot, manifest, 'pnpm-workspace.yaml');
+    const previousOptions = manifest
+        ? { ...options, ...selectionsFromModules(manifest.modules), modules: [...manifest.modules] }
+        : undefined;
+    const previousPackage = previousOptions ? desiredRootPackage(previousOptions) : undefined;
+    writeRootPackage(root, options, mode, packageUnmodified, previousPackage);
+    const workspacePackages = [
+        Object.values(options.apps).some(Boolean) ? 'apps/*' : null,
+        options.apps.api || options.features.database ? 'packages/*' : null,
+    ].filter((value) => value !== null);
+    mergeWorkspaceFile(root, workspacePackages, desiredWorkspacePolicy(), workspaceUnmodified);
+    mergeJsonConfig(root, 'turbo.json', desiredTurboConfig(), desiredTurboConfig(), true);
+    mergeJsonConfig(root, 'vercel.json', desiredVercelConfig(options), previousOptions ? desiredVercelConfig(previousOptions) : {}, true);
+    appendGitignore(root, [
+        'node_modules',
+        '.turbo',
+        '.next',
+        '.output',
+        '.wxt',
+        '.expo',
+        'coverage',
+        'dist',
+        'release',
+        '.env',
+        '.env.*',
+        '!.env.example',
+        '*.tsbuildinfo',
+    ]);
+    writeRootEnv(root, options);
+    writeDatabaseVerificationScript(root, options);
+    const vercelIgnore = path.join(root, '.vercelignore');
+    const currentIgnore = pathEntryExists(vercelIgnore) ? readFileSync(vercelIgnore, 'utf8') : '';
+    const ignoreLines = [...new Set([...currentIgnore.split('\n').filter(Boolean), 'apps/extension/.output', 'apps/mobile/dist', 'apps/desktop/release', 'apps/assets-private-proxy'])];
+    writeFile(vercelIgnore, ignoreLines.join('\n') + '\n');
+    writeFile(path.join(root, '.github/workflows/anhedral-ci.yml'), generatedCi(options));
+}
+function enabledModuleNames(options) {
+    return resolveModules(options.modules).resolvedModules;
+}
+function writeProjectDocs(root, options, includeUserDocs) {
+    const modules = enabledModuleNames(options);
+    const storageBucketName = r2BucketName(options.projectName);
+    const commands = [
+        'pnpm install',
+        options.apps.api ? 'cp apps/api/.env.example apps/api/.env' : null,
+        options.features.database ? 'cp packages/db/.env.example packages/db/.env' : null,
+        options.apps.web ? 'cp apps/web/.env.example apps/web/.env.local' : null,
+        options.apps.mobile ? 'cp apps/mobile/.env.example apps/mobile/.env' : null,
+        options.apps.desktop ? 'cp apps/desktop/.env.example apps/desktop/.env' : null,
+        options.apps.extension ? 'cp apps/extension/.env.example apps/extension/.env' : null,
+        options.features.database ? 'pnpm db:generate' : null,
+        options.features.database ? 'git add packages/db/migrations' : null,
+        'pnpm verify',
+        options.features.database ? 'pnpm db:migrate' : null,
+    ].filter((value) => value !== null).join('\n');
+    const deploymentRows = [
+        options.apps.web || options.apps.api ? '| Web/API | Vercel Git integration | Import this repository once; branch pushes create previews and the production branch deploys automatically. |' : null,
+        options.apps.mobile ? '| Mobile | EAS Build + App Store Connect + Google Play Console | EAS creates signed binaries; Apple TestFlight/App Review and Google testing tracks/store review control release. |' : null,
+        options.features.database ? '| Database | Neon | Provision the project, set `DATABASE_URL`, review/apply Drizzle migrations, and use separate branches or projects for preview and production. |' : null,
+        options.features.storage ? '| Object storage | Private Cloudflare R2 + `assets-private-proxy` Worker | Authenticated uploads use presigned R2 URLs; the Worker streams known-key GET/HEAD downloads through `assets.<domain>` while direct bucket access stays disabled. |' : null,
+        options.apps.extension ? '| Chrome extension | Chrome Web Store | Build the production ZIP, test it as an unpublished/trusted-tester item, complete privacy disclosures, and submit it for review. |' : null,
+        options.apps.desktop ? '| Desktop | electron-builder artifacts | Build and sign on each target OS, then publish through the release channel chosen for the product. |' : null,
+    ].filter((value) => value !== null).join('\n');
+    const deploymentCommands = [
+        options.apps.web || options.apps.api ? 'pnpm deploy:vercel:link' : null,
+        options.apps.web || options.apps.api ? 'pnpm deploy:vercel:preview' : null,
+        options.apps.web || options.apps.api ? 'pnpm deploy:vercel:production' : null,
+        options.apps.mobile ? 'pnpm mobile:eas:login' : null,
+        options.apps.mobile ? 'pnpm mobile:build:internal:ios' : null,
+        options.apps.mobile ? 'pnpm mobile:build:internal:android' : null,
+        options.features.database ? `pnpm neon:project:create -- --name ${options.projectName}` : null,
+        options.features.storage ? 'pnpm r2:bucket:create' : null,
+        options.features.storage ? 'pnpm assets:proxy:check' : null,
+        options.features.storage ? 'pnpm assets:proxy:deploy' : null,
+        options.apps.extension ? 'pnpm extension:zip' : null,
+    ].filter((value) => value !== null).join('\n');
+    const sourceRows = [
+        options.apps.web ? '| Web frontend | `apps/web/app/`, `apps/web/components/`, `apps/web/lib/` | Next.js App Router pages, layouts, components, and web utilities. |' : null,
+        options.apps.mobile ? '| Mobile frontend | `apps/mobile/app/`, `apps/mobile/components/` | Expo Router screens, layouts, and native UI. |' : null,
+        options.apps.api ? '| Backend API | `apps/api/src/routes/`, `apps/api/src/services/` | Fastify routes and server-only business/provider code. |' : null,
+        options.apps.desktop ? '| Desktop app | `apps/desktop/src/renderer/`, `apps/desktop/src/main/` | React UI and privileged Electron main-process code. |' : null,
+        options.apps.extension ? '| Browser extension | `apps/extension/entrypoints/`, `apps/extension/components/` | WXT entrypoints and extension UI. |' : null,
+        options.apps.api ? '| Shared API contracts | `packages/contracts/src/` | Zod request and response schemas imported by clients and the API. |' : null,
+        options.apps.api ? '| Typed API client | `packages/api-client/src/` | Shared fetch client used by every selected frontend. |' : null,
+        options.features.database ? '| Database | `packages/db/src/schema.ts`, `packages/db/migrations/` | Drizzle tables, queries, and reviewed SQL migrations for managed Neon Postgres. |' : null,
+    ].filter((value) => value !== null).join('\n');
+    const moduleCommands = [
+        options.apps.web ? '- Web: `pnpm dev:web`' : null,
+        options.apps.mobile ? '- Mobile: `pnpm dev:mobile`' : null,
+        options.apps.api ? '- API: `pnpm dev:api`' : null,
+        options.apps.desktop ? '- Desktop: `pnpm dev:desktop`' : null,
+        options.apps.extension ? '- Extension: `pnpm dev:extension`' : null,
+    ].filter((value) => value !== null).join('\n');
+    const toolRows = [
+        options.apps.web ? '| Next.js | Web routes and rendering | `apps/web` | https://nextjs.org/docs/app/getting-started |' : null,
+        options.apps.mobile ? '| Expo Router | iOS and Android app | `apps/mobile` | https://docs.expo.dev/router/introduction/ |' : null,
+        options.apps.api ? '| Fastify | HTTP API | `apps/api` | https://fastify.dev/docs/latest/ |' : null,
+        options.features.database ? '| Neon | Managed Postgres; no local Postgres | `DATABASE_URL` | https://neon.com/docs/introduction |' : null,
+        options.features.database ? '| Drizzle | SQL schema, queries, migrations | `packages/db` | https://orm.drizzle.team/docs/get-started |' : null,
+        options.features.auth ? '| Clerk | Identity and sessions | generated auth files | https://clerk.com/docs/getting-started/quickstart/overview |' : null,
+        options.features.storage ? '| Cloudflare R2 | Private object storage | upload API and `apps/assets-private-proxy` | https://developers.cloudflare.com/r2/ |' : null,
+        options.features.billing ? '| RevenueCat | Subscription authority | API and native client | https://www.revenuecat.com/docs |' : null,
+        options.features.billing ? '| Ably | Realtime invalidation | `packages/realtime` | https://ably.com/docs |' : null,
+        options.apps.desktop ? '| Electron | Desktop runtime | `apps/desktop` | https://www.electronjs.org/docs/latest/ |' : null,
+        options.apps.extension ? '| WXT | Browser extension tooling | `apps/extension` | https://wxt.dev/guide/installation.html |' : null,
+        options.apps.web || options.apps.desktop || options.apps.extension ? '| shadcn/ui | Source-owned DOM UI | each DOM app\'s `components/ui` | https://ui.shadcn.com/docs |' : null,
+        '| Turborepo | Workspace tasks | root `turbo.json` | https://turborepo.com/docs |',
+    ].filter((value) => value !== null).join('\n');
+    const developmentSteps = [
+        options.apps.api ? 'Define shared Zod schemas in `packages/contracts/src/` so the network boundary has one definition.' : null,
+        options.features.database ? 'Define persistent state in `packages/db/src/schema.ts`. Run `pnpm db:generate`, review the SQL, and commit it. This project uses managed Neon—do not add a local Postgres container.' : null,
+        options.apps.api ? 'Put business logic and provider calls in `apps/api/src/services/`. Keep `apps/api/src/routes/` focused on auth, validation, calling the service, and returning the contract.' : null,
+        options.apps.api ? 'Expose client-safe methods from `packages/api-client/src/`; never import API implementation files into a frontend.' : null,
+        options.apps.web ? 'Add web routes in `apps/web/app/<route>/page.tsx` and reusable UI in `apps/web/components/`. Use a client component only for browser state, events, or hooks.' : null,
+        options.apps.mobile ? 'Add mobile routes in `apps/mobile/app/` and reusable native UI in `apps/mobile/components/`. Keep platform-only APIs in platform-specific modules.' : null,
+        'Test the smallest affected package first, then run `pnpm verify`.',
+    ].filter((value) => value !== null).map((value, index) => `${index + 1}. ${value}`).join('\n');
+    const commonTaskSections = [
+        options.apps.web ? `### Add a web page
+
+Create \`apps/web/app/<route>/page.tsx\`. Follow Next.js App Router conventions directly. Put reusable components under \`apps/web/components/<feature>/\` and web-only helpers under \`apps/web/lib/\`.` : null,
+        options.apps.api ? `### Add an API endpoint
+
+Define its Zod contract in \`packages/contracts/src/\`, add a service function in \`apps/api/src/services/\`, and register a Fastify route in \`apps/api/src/routes/\`. Authenticate on the server and derive the user ID from the verified session.` : null,
+        options.features.database ? `### Change the database
+
+Edit \`packages/db/src/schema.ts\`, then run:
 
-- \`Backend/src/index.ts\`: Vercel Fastify entrypoint
-- \`Backend/src/app.ts\`: Fastify app construction
-- \`Backend/vercel.json\`: minimal Vercel config
-- \`Backend/src/routes\`: health/auth/subscription/storage routes
+\`\`\`sh
+pnpm db:generate
+pnpm verify:db
+pnpm db:migrate
+\`\`\`
 
-## Extension
+Review generated SQL before applying it. \`DATABASE_URL\` points to a managed Neon branch or project; there is intentionally no local Postgres service.` : null,
+        options.features.auth ? `### Use authentication
 
-\`Extension\` is the WXT Chrome extension using the Side Panel API.
+Frontend applications use their generated Clerk provider and hooks. The API verifies Clerk sessions. Public keys may use a framework public environment prefix; \`CLERK_SECRET_KEY\` remains in the API environment only.` : null,
+        options.features.storage ? `### Upload a file
 
-Important files:
+Use \`@shared/api-client\`. The API authorizes the user and creates a short-lived signed R2 upload; the client uploads directly and confirms through the API. Never put R2 credentials in a client or make the bucket public.` : null,
+    ].filter((value) => value !== null).join('\n\n');
+    const dependencyLines = [
+        options.apps.api ? 'frontend apps -> @shared/api-client -> HTTP -> apps/api' : null,
+        options.apps.api ? 'frontend apps -> @shared/contracts <- apps/api' : null,
+        options.apps.api && options.features.database ? 'apps/api      -> @shared/db -> managed Neon Postgres' : null,
+    ].filter((value) => value !== null).join('\n');
+    const uiTaskSection = Object.values(options.apps).some(Boolean) && (options.apps.web || options.apps.mobile || options.apps.desktop || options.apps.extension)
+        ? `### Add UI primitives
 
-- \`Extension/wxt.config.ts\`: manifest, side panel, permissions
-- \`Extension/src/entrypoints/sidepanel\`: side panel UI
-- \`Extension/src/entrypoints/background.ts\`: side panel behavior
+\`\`\`sh
+anhedral ui add dialog
+${options.apps.web ? 'anhedral ui add data-table --target web\n' : ''}\`\`\`
 
-ZIP output goes to \`Extension/.output\`.
+DOM apps receive source-owned shadcn/ui files. Mobile receives React Native Reusables files. Customize those files normally.`
+        : '';
+    if (includeUserDocs) {
+        writeFile(path.join(root, 'README.md'), `# ${markdownHeading(options.displayName)}
 
-## Develop
+This is a complete, readable TypeScript product stack generated by Anhedral ${GENERATOR_VERSION}. Anhedral assembled and connected the tools; application code remains normal framework code.
 
-From the repository root:
+## Start here
 
 \`\`\`sh
 pnpm install
 pnpm dev
 \`\`\`
 
-Or run one surface at a time:
-
-\`\`\`sh
-pnpm dev:frontend
-pnpm dev:backend
-pnpm dev:extension
-\`\`\`
-
-Use these before deploy:
-
-\`\`\`sh
-pnpm verify
-pnpm verify:frontend
-pnpm verify:backend
-pnpm verify:extension
-\`\`\`
-
-Database workflow:
-
-\`\`\`sh
-pnpm db:generate
-pnpm db:migrate
-pnpm db:studio
-pnpm db:check
-\`\`\`
+\`pnpm dev\` starts every selected application. To run one surface:
 
-Local demo mode is enabled through generated \`.env\` files. Real provider behavior needs Clerk, RevenueCat/Stripe, Neon, and R2 credentials.
+${moduleCommands}
 
-The generated placeholder values are intentionally non-production. They let you inspect files and run backend demo checks, but browser auth, paid subscriptions, uploads, and extension sign-in require the setup below.
+There is no hidden Anhedral application runtime. Open the framework directory you want and write ordinary TypeScript there.
 
-## Environment Variables
+## Where to write code
 
-- Root/local: \`DATABASE_URL\` for shared Drizzle commands.
-- Frontend/Vercel Frontend: only \`EXPO_PUBLIC_*\` values.
-- Backend/Vercel Backend: server secrets such as \`DATABASE_URL\`, \`CLERK_SECRET_KEY\`, \`RC_SECRET_API_KEY\`, \`RC_WEBHOOK_SECRET\`, and R2 credentials.
-- Extension: \`VITE_API_URL\`, \`VITE_CLERK_PUBLISHABLE_KEY\`, and optionally \`VITE_CRX_PUBLIC_KEY\`.
-- EAS: add native app public keys with \`eas secret:create\` or the EAS dashboard.
+| Concern | Location | What belongs there |
+| --- | --- | --- |
+${sourceRows}
 
-## Provider Setup
+${options.apps.api ? 'For an end-to-end feature, define shared contracts first, implement server and persistence behavior, expose it through the typed client, then build each frontend.' : 'Build product features directly inside each selected application using its native framework conventions.'} Read [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for concrete recipes and [docs/STACK.md](docs/STACK.md) for every selected tool and its official documentation.
 
-### Neon + Drizzle
+## Selected modules
 
-Docs:
+${modules.map((moduleName) => `- \`${moduleName}\``).join('\n')}
 
-- https://neon.com/docs/get-started-with-neon/connect-neon
-- https://orm.drizzle.team/docs/tutorials/drizzle-with-neon
+## UI and customization
 
-Steps:
+DOM clients use source-owned shadcn/ui. Expo uses React Native Reusables with ${options.nativeStyling}. Add components with \`anhedral ui add <component>\`; use \`--target\` when a component belongs to one client. Customize the resulting source normally.
 
-1. Create a Neon project and Postgres database.
-2. Copy the pooled connection string.
-3. Set \`DATABASE_URL\` in the root \`.env\`, \`Backend/.env\`, and the Backend Vercel project.
-4. Run:
+## Environment and first verification
 
 \`\`\`sh
-pnpm db:generate
-pnpm db:migrate
+${commands}
 \`\`\`
 
-### Clerk
-
-Docs:
+## Deployment
 
-- https://docs.expo.dev/guides/using-clerk/
-- https://clerk.com/docs/quickstarts/get-started-with-expo
+Only selected surfaces and providers contribute deployment scripts. Exact-version deployment CLIs run on demand instead of inflating the application lockfile.
 
-Steps:
+| Selection | Delivery target | Strategy |
+| --- | --- | --- |
+${deploymentRows}
 
-1. Create a Clerk application.
-2. Set \`EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY\` in \`Frontend/.env\`, the Frontend Vercel project, and EAS.
-3. Set \`CLERK_PUBLISHABLE_KEY\` and \`CLERK_SECRET_KEY\` in \`Backend/.env\` and the Backend Vercel project.
-4. Set \`VITE_CLERK_PUBLISHABLE_KEY\` in \`Extension/.env\`.
-5. Add allowed origins for local Expo web, the deployed Frontend Vercel domain, and the Chrome extension origin after the extension id is stable.
-6. Configure native redirect/deep-link settings for the Expo scheme in \`Frontend/app.json\`.
-
-### RevenueCat + Stripe
+\`\`\`sh
+${deploymentCommands}
+\`\`\`
 
-Docs:
+Read \`PRODUCTION.md\` before creating accounts or production resources. Generated ownership and tool versions are recorded in \`anhedral.json\`. Run \`anhedral doctor\` before structural changes and preview them with \`--dry-run\`.
+`);
+    }
+    writeFile(path.join(root, 'docs/DEVELOPMENT.md'), `# Developing ${markdownHeading(options.displayName)}
 
-- https://www.revenuecat.com/docs/web/overview
-- https://www.revenuecat.com/docs/web/integrations/stripe
-- https://docs.stripe.com/keys
+Anhedral generated this stack; it does not replace the frameworks inside it. Use official framework APIs and keep product logic in ordinary source files.
 
-Steps:
+## End-to-end feature loop
 
-1. Create the RevenueCat project.
-2. Create an entitlement named \`pro\`.
-3. Create iOS, Android, and Web apps in RevenueCat.
-4. Copy the public SDK keys into \`EXPO_PUBLIC_RC_API_KEY_IOS\`, \`EXPO_PUBLIC_RC_API_KEY_ANDROID\`, and \`EXPO_PUBLIC_RC_WEB_API_KEY\`.
-5. Set \`EXPO_PUBLIC_RC_ENTITLEMENT_ID=pro\`.
-6. Connect Stripe as the RevenueCat web billing source.
-7. Set \`RC_SECRET_API_KEY\` and \`RC_WEBHOOK_SECRET\` only in Backend envs.
-8. Configure the RevenueCat webhook URL as \`https://<backend-domain>/webhooks/revenuecat\`.
+${developmentSteps}
 
-### Cloudflare R2/CDN
+## Common tasks
 
-Docs:
+${commonTaskSections}
 
-- https://developers.cloudflare.com/r2/get-started/s3/
-- https://developers.cloudflare.com/r2/api/tokens/
+${uiTaskSection}
 
-Steps:
+### Add another app surface
 
-1. Create an R2 bucket.
-2. Create a least-privilege API token for that bucket.
-3. Set \`R2_ACCOUNT_ID\`, \`R2_ACCESS_KEY_ID\`, \`R2_SECRET_ACCESS_KEY\`, and \`R2_BUCKET\` only in Backend envs.
-4. Use \`POST /storage/uploads\` to create signed upload URLs, then \`GET /storage/files/:key\` or \`DELETE /storage/files/:key\` for user-owned objects.
-5. Configure a public bucket URL or custom domain if uploaded assets need public CDN delivery.
+\`\`\`sh
+anhedral add mobile --dry-run
+anhedral add mobile
+\`\`\`
 
-## Deploy
+Anhedral refuses ownership conflicts instead of overwriting product changes. Run \`anhedral doctor\` when an add cannot proceed.
 
-Vercel deployment is two Vercel projects from the same Git repo:
+## Verification
 
-1. Frontend Vercel project
-   - Root Directory: \`Frontend\`
-   - Build command: \`pnpm build:web\`
-   - Output directory: \`dist\`
+- While iterating, run the affected package's typecheck or tests.
+- Before handoff, run \`pnpm verify\`.
+- Before generation, run \`anhedral doctor\` and use \`--dry-run\`.
+- For schema changes, commit reviewed migration SQL and run \`pnpm verify:db\`.
+`);
+    writeFile(path.join(root, 'docs/STACK.md'), `# Stack guide
 
-2. Backend Vercel project
-   - Root Directory: \`Backend\`
-   - Build command: \`pnpm build\`
-   - Fastify entrypoint: \`src/index.ts\`
+This maps generated source to upstream documentation. Anhedral owns initial integration and safe incremental generation. Each framework owns its runtime and programming model.
 
-Enable Vercel access to source files outside each project root so \`packages/*\` workspace packages resolve.
+| Tool | Responsibility | Generated location | Official documentation |
+| --- | --- | --- | --- |
+${toolRows}
 
-Native app deployment:
+## Dependency direction
 
-\`\`\`sh
-cd Frontend
-pnpm dlx eas-cli@latest login
-pnpm dlx eas-cli@latest init
-pnpm dlx eas-cli@latest build --platform all --profile production
-pnpm dlx eas-cli@latest submit --platform all --latest --profile production
+\`\`\`text
+${dependencyLines || 'selected applications are independent framework projects'}
 \`\`\`
 
-Chrome extension deployment:
+Clients may import contracts and the API client. They must not import API services, database connections, or server environment modules. Provider secrets terminate at the API or provider-specific Worker.
 
-\`\`\`sh
-pnpm extension:zip
-\`\`\`
-
-Upload \`Extension/.output/*-chrome.zip\` to the Chrome Web Store Developer Dashboard.
-
-## Production Checklist
-
-- Replace every \`*_placeholder\` value before production deploy.
-- Keep server secrets out of Frontend, Extension, and EAS public envs.
-- Confirm Clerk works on local web, Vercel web, iOS, Android, and the Chrome extension.
-- Confirm RevenueCat returns the \`pro\` entitlement after Stripe web purchase and native store purchase.
-- Confirm \`pnpm db:migrate\` has run against the production Neon database.
-- Confirm R2 upload, signed URL retrieval, and deletion work from the deployed Backend domain.
-- Confirm both Vercel projects can resolve \`packages/*\` workspace packages.
-- Confirm the Chrome extension ZIP is tested locally with \`chrome://extensions\` before Chrome Web Store upload.
-
-## Relevant Docs
-
-- [Vercel monorepos](https://vercel.com/docs/monorepos)
-- [Vercel monorepo FAQ](https://vercel.com/docs/monorepos/monorepo-faq)
-- [Expo web publishing](https://docs.expo.dev/guides/publishing-websites/)
-- [Expo EAS](https://docs.expo.dev/eas/)
-- [Expo store submissions](https://docs.expo.dev/deploy/submit-to-app-stores/)
-- [Clerk with Expo](https://docs.expo.dev/guides/using-clerk/)
-- [Clerk Expo quickstart](https://clerk.com/docs/quickstarts/get-started-with-expo)
-- [Neon connection strings](https://neon.com/docs/get-started-with-neon/connect-neon)
-- [Drizzle with Neon](https://orm.drizzle.team/docs/tutorials/drizzle-with-neon)
-- [RevenueCat Web](https://www.revenuecat.com/docs/web/overview)
-- [RevenueCat Stripe Billing](https://www.revenuecat.com/docs/web/integrations/stripe)
-- [Stripe API keys](https://docs.stripe.com/keys)
-- [Cloudflare R2 S3 API](https://developers.cloudflare.com/r2/get-started/s3/)
-- [Cloudflare R2 API tokens](https://developers.cloudflare.com/r2/api/tokens/)
-- [WXT publishing](https://wxt.dev/guide/essentials/publishing.html)
-- [Chrome Web Store publishing](https://developer.chrome.com/docs/webstore/publish)
+\`anhedral add\` adds modules and integration files. \`anhedral ui add\` adds source-owned UI. \`anhedral doctor\` checks recorded ownership. Product features, models, pages, routes, and services remain developer-owned TypeScript.
 `);
-}
-function writeStackFile(root, stack) {
-    writeFile(path.join(root, 'stack.json'), JSON.stringify(stack, null, 2) + '\n');
-}
-function writeSharedPackages(root) {
-    const dbRoot = path.join(root, 'packages/db');
-    writeFile(path.join(dbRoot, 'package.json'), JSON.stringify({
-        name: '@shared/db',
-        version: '0.1.0',
-        private: true,
-        type: 'module',
-        exports: {
-            '.': './src/index.ts',
-            './schema': './src/schema.ts',
-            './queries': './src/queries/index.ts',
-            './migrate': './src/migrate.ts',
-        },
-        scripts: {
-            build: 'pnpm typecheck',
-            typecheck: 'tsc --noEmit',
-            'db:generate': 'drizzle-kit generate',
-            'db:migrate': 'tsx --env-file=../../.env src/migrate.ts',
-            'db:studio': 'drizzle-kit studio',
-            'db:check': 'drizzle-kit check',
-        },
-        dependencies: SHARED_DB_DEPENDENCIES.dependencies,
-        devDependencies: SHARED_DB_DEPENDENCIES.devDependencies,
-    }, null, 2) + '\n');
-    writeFile(path.join(dbRoot, 'tsconfig.json'), JSON.stringify({
-        compilerOptions: {
-            target: 'ESNext',
-            module: 'ESNext',
-            moduleResolution: 'Bundler',
-            strict: true,
-            skipLibCheck: true,
-            noEmit: true,
-            types: ['node'],
-        },
-        include: ['src/**/*', 'drizzle.config.ts'],
-    }, null, 2) + '\n');
-    writeFile(path.join(dbRoot, 'drizzle.config.ts'), `import type { Config } from 'drizzle-kit';
-
-export default {
-  schema: './src/schema.ts',
-  out: './migrations',
-  dialect: 'postgresql',
-  dbCredentials: {
-    url: process.env.DATABASE_URL!,
-  },
-} satisfies Config;
+    if (includeUserDocs) {
+        const productionItems = [
+            options.apps.api ? '- Keep `ANHEDRAL_DEMO=false` in production.' : null,
+            options.apps.api ? '- Set `TRUST_PROXY_HOPS` only to the number of trusted reverse-proxy hops.' : null,
+            options.apps.api ? '- Store server secrets only in the API deployment environment.' : null,
+            options.apps.api || options.apps.web ? '- Select the Vercel Services framework preset and deploy from the repository root.' : null,
+            options.apps.api && options.apps.web ? '- Keep the top-level `/api/(.*)` service rewrite before the web catch-all rewrite.' : null,
+            options.apps.api && options.apps.web ? '- The web client defaults to same-origin `/api` in production; override `NEXT_PUBLIC_API_URL` only when the API uses another origin.' : null,
+            options.features.storage ? '- Set a strong `CRON_SECRET` and verify Vercel invokes `/api/internal/storage/cleanup` on schedule.' : null,
+            options.features.billing ? '- Configure `ABLY_API_KEY`, set a strong `CRON_SECRET`, and verify Vercel invokes `/api/internal/realtime/flush` every five minutes to retry the transactional outbox.' : null,
+            options.features.billing ? '- Use a dedicated RevenueCat secret REST API key with customer-read access; keep it server-only and rotate it independently from the 32+ character webhook authorization secret.' : null,
+            options.features.storage ? '- List the live R2 CORS policy, merge every exact browser origin into `cloudflare/r2-cors.template.json`, then apply the complete replacement policy and verify preflight plus signed PUT.' : null,
+            options.features.storage ? '- Configure an R2 lifecycle rule for the `storage/staging/` prefix as a backstop, with an age longer than the application cleanup grace period.' : null,
+            options.features.database ? '- Commit every reviewed Drizzle SQL migration and its metadata with the schema change; `pnpm verify:db` rejects a missing or untracked SQL baseline and validates migration history.' : null,
+            options.features.database ? '- Generated CI runs `pnpm db:generate` and fails when `packages/db/migrations` changes, preventing schema changes without a matching migration.' : null,
+            '- Run `pnpm verify` before deployment.',
+            '- Run `anhedral doctor` before incremental generation.',
+        ].filter((item) => item !== null);
+        const productionSections = [
+            options.apps.web || options.apps.api || options.features.storage ? `## Domain registration and Cloudflare control plane
+
+Registration and DNS hosting are separate jobs. You can buy the domain at GoDaddy while Cloudflare becomes authoritative DNS immediately; transferring the registrar later is optional.
+
+1. Buy the domain at GoDaddy under an organization-controlled account. Enable auto-renewal, MFA, accurate registrant contact details, and record renewal ownership.
+2. Add the domain as a website/zone in Cloudflare. Before changing nameservers, copy every existing DNS record—especially MX, TXT, DKIM, SPF, DMARC, verification, and subdomain records—and disable DNSSEC/DS records at GoDaddy if enabled.
+3. Cloudflare assigns two authoritative nameservers. Replace the GoDaddy nameservers with those exact values, then wait until Cloudflare marks the zone **Active**. Recreate and verify mail and other records before considering the migration complete. Re-enable DNSSEC in Cloudflare after activation.
+4. Optional registrar transfer: after the domain is eligible (commonly not within 60 days of registration, a prior transfer, or certain registrant changes), unlock it at GoDaddy, request its EPP/authorization code, and start **Transfer Domains** in Cloudflare. Approve the transfer and payment. DNS can remain live throughout because Cloudflare was already authoritative.
+5. Keep Cloudflare as the shared domain control plane: DNS and DNSSEC at the zone; Workers and R2 for the asset hostname; and optional Queues, Workflows, Durable Objects, WAF, Turnstile, or other compute/security products when the application actually needs them. Vercel remains the web/API runtime.
+
+Use organization-owned Cloudflare and GoDaddy accounts with MFA and least-privilege member roles. Do not confuse changing nameservers (DNS delegation) with transferring the registration (registrar/billing ownership). Follow the current [GoDaddy nameserver instructions](https://help.dc-aws.godaddy.com/help/edit-my-domain-nameservers-664), [GoDaddy transfer-away sequence](https://www.godaddy.com/en-ca/help/transfer-my-domain-away-from-godaddy-3560), [Cloudflare nameserver guidance](https://developers.cloudflare.com/dns/nameservers/update-nameservers/), and [Cloudflare registrar-transfer sequence](https://developers.cloudflare.com/registrar/get-started/transfer-domain-to-cloudflare/).` : null,
+            options.apps.web || options.apps.api ? `## Vercel: web and API
+
+1. Push the repository to GitHub and import it in Vercel. Choose the **Services** framework preset and keep the repository root as the project root; \`vercel.json\` maps the selected \`apps/web\` and \`apps/api\` services.
+2. Add every required variable from the package-local \`.env.example\` files to Vercel's Development, Preview, and Production environments. Server secrets belong only to the API service. Never put a secret in a \`NEXT_PUBLIC_*\` variable.
+3. Run \`pnpm deploy:vercel:link\` for local CLI access. The normal release path is Git: every non-production branch/PR receives a preview deployment, and merging to the configured production branch creates production automatically. The explicit \`deploy:vercel:preview\` and \`deploy:vercel:production\` scripts are escape hatches for manual releases.
+4. Run \`pnpm deploy:vercel:inspect -- <deployment-url>\` when diagnosing a deployment. Verify health, authentication, scheduled jobs, and provider callbacks in Preview before merging.
+5. Add \`app.example.com\` in Vercel **Project → Settings → Domains** before changing DNS. Inspect it with \`pnpm deploy:vercel:domain:inspect -- app.example.com\`, then create the exact A/CNAME/TXT records Vercel reports in Cloudflare DNS. Leave the Vercel A/CNAME record **DNS only** (gray cloud), because placing Cloudflare's reverse proxy in front of Vercel hides traffic signals, adds another CDN hop, and can interfere with Vercel caching/firewall behavior. Ownership-verification TXT records are also DNS only. Vercel provisions TLS after validation.
+
+When web and API are both selected, keep the generated \`/api/(.*)\` route before the web catch-all. The browser uses same-origin \`/api\`; mobile, desktop, and extension builds need the absolute production API URL.` : null,
+            options.features.auth ? `## Clerk: production identity
+
+1. Create the Clerk application for development, then create its separate **Production** instance. Copy \`pk_live_*\` and \`sk_live_*\` keys into the production environments; keep \`CLERK_SECRET_KEY\` server-only.
+2. Add the production root domain in Clerk and publish the DNS records shown on **Domains**. Configure a subdomain allowlist, production OAuth credentials, allowlisted redirect URLs, webhook URLs/signing secrets, and native application identifiers that apply to the selected clients.
+3. Use development keys locally and production keys only for production builds. Vercel Preview deployments should use a separate Clerk application/domain when stable preview auth is required; do not point previews at live user data.
+4. Redeploy every selected client after changing public Clerk keys. Test sign-in, sign-out, token refresh, deep links, and physical-device behavior before release.${options.apps.extension ? '\n5. For the extension, create a stable CRX ID, configure Clerk Chrome Extension deployment for that ID, and set `VITE_CLERK_FRONTEND_API_URL` plus `VITE_CLERK_SYNC_HOST` when using web-to-extension session sync. OAuth and email-link flows require Sync Host.' : ''}` : null,
+            options.features.database ? `## Neon and Drizzle: database
+
+1. Create a Neon account, then run \`pnpm neon:login\` and \`pnpm neon:project:create -- --name ${options.projectName}\`, or create the project in the Neon console.
+2. Copy the pooled Postgres connection string to \`DATABASE_URL\` in \`packages/db/.env\` locally and the API's Vercel environment in production. Keep preview and production databases isolated with Neon branches or separate projects.
+3. Change the Drizzle schema, run \`pnpm db:generate\`, review and commit the SQL and metadata, then run \`pnpm verify:db\`.
+4. Apply \`pnpm db:migrate\` against the intended database as a controlled release step before sending production traffic to code that requires the new schema. Backward-compatible migrations make rollback safer; never run unreviewed migration generation during a Vercel build.
+5. Enable Neon backups/restore controls appropriate to the plan, restrict credentials, and rotate a leaked connection string immediately.` : null,
+            options.features.storage ? `## Cloudflare R2: private bucket and generated Worker
+
+1. Run \`pnpm r2:login\` and \`pnpm r2:bucket:create\` to create \`${storageBucketName}\`, or create that bucket in **R2 → Overview**. Keep both the \`r2.dev\` development URL and R2 bucket custom-domain access disabled; the bucket itself remains private.
+2. Create an Object Read & Write S3 API token scoped to this bucket. Put \`BASE_URL\`, \`R2_ACCOUNT_ID\`, \`R2_ACCESS_KEY_ID\`, \`R2_SECRET_ACCESS_KEY\`, \`R2_BUCKET_NAME=${storageBucketName}\`, \`R2_PREFIX=storage\`, and \`R2_PROXY_READ_URL_TTL_SECONDS=600\` in the API deployment. The Worker uses the in-process \`ASSETS\` binding instead of these S3 credentials. Keep \`CLOUDFLARE_API_TOKEN\` operations/CI-only for Wrangler.
+3. Direct browser uploads continue to use short-lived presigned PUT URLs on \`<ACCOUNT_ID>.r2.cloudflarestorage.com\`. Presigned URLs do **not** work on custom domains. Run \`pnpm r2:cors:list\`, edit the user-owned \`cloudflare/r2-cors.template.json\`, then run \`pnpm r2:cors:set\`. The set command replaces the complete live policy, so retain every exact uploading origin.
+4. Open \`apps/assets-private-proxy/wrangler.jsonc\`. Replace both \`assets.example.com\` values with \`assets.yourdomain.com\`. The generated config names the Worker \`assets-private-proxy\`, disables \`workers.dev\` and preview URLs, binds \`${storageBucketName}\` as \`ASSETS\`, sets \`R2_PREFIX=storage\`, enables logs, and declares the hostname as a Worker Custom Domain.
+5. Run \`pnpm assets:proxy:check\`, then \`pnpm assets:proxy:deploy\`. Wrangler creates or updates the Worker, R2 binding, managed proxied DNS record, TLS certificate, and custom domain. The dashboard equivalent is **Workers & Pages → assets-private-proxy → Settings → Bindings** (R2, variable \`ASSETS\`, bucket \`${storageBucketName}\`) and **Domains & Routes → Add → Custom domain**.
+6. The Worker streams GET/HEAD bodies, preserves metadata/ranges/conditionals, caches complete public responses, rejects other methods and unexpected hosts, and never lists the bucket. It exposes only \`storage/confirmed/\` by unguessable key; \`storage/staging/\` and \`generation-inputs\` return 404. Authenticated private reads use \`GET /api/storage/uploads/:uploadId/read-url\`, which verifies ownership before returning a short-lived S3 URL.
+7. Add an R2 lifecycle rule for \`storage/staging/\` longer than the API cleanup grace period. Set a strong \`CRON_SECRET\` in Vercel and verify cleanup. Test missing keys, invalid encodings, GET, HEAD, range, conditional, cache HIT/MISS, forbidden methods, private-prefix rejection, authenticated read authorization, TTL bounds, and direct bucket inaccessibility.
+
+\`app.yourdomain.com\` is a Cloudflare DNS-only record targeting Vercel. \`assets.yourdomain.com\` is a Cloudflare-managed Worker Custom Domain and stays proxied. Never connect the asset hostname directly to R2, never CNAME it to \`r2.dev\`, and never expose S3 credentials in a client bundle.` : null,
+            options.apps.mobile ? `## Expo, TestFlight, and app stores
+
+Accounts required: an Expo/EAS account, an Apple Developer Program membership with App Store Connect access for iOS, and a Google Play Console developer account for Android. Create unique iOS bundle and Android package identifiers before the first store build.
+
+1. Run \`pnpm mobile:eas:login\`, then \`pnpm mobile:eas:init\` from the repository root to create/link the EAS project. Review and commit the project ID/configuration that EAS adds.
+2. Put public build-time values in the matching EAS environment/profile; keep server secrets out of Expo. Configure Apple/Google credentials with EAS and test sign-in/deep links on physical devices.
+3. Internal EAS distribution: run \`pnpm mobile:build:internal:ios\` and/or \`pnpm mobile:build:internal:android\`. iOS ad hoc distribution requires registered device UDIDs; Android internal builds can be installed from the EAS share URL. These builds do not require a development server.
+4. TestFlight: run \`pnpm mobile:build:production:ios\`, then \`pnpm mobile:submit:ios\`. After App Store Connect processes the build, assign it to internal testers. External testers require TestFlight Beta App Review. TestFlight approval is not App Store production approval.
+5. Google Play: create the app/listing and required policy declarations in Play Console. Run \`pnpm mobile:build:production:android\`, then \`pnpm mobile:submit:android\`. Start with the internal testing track, promote through closed/open testing as appropriate, and only then roll out production. A brand-new Play app may require its first binary to be uploaded manually before API-based submissions work.
+6. Complete store metadata, screenshots, privacy/data-safety declarations, content ratings, export compliance, pricing/availability, review credentials, and release notes. Submit for store review and use staged/phased rollout where appropriate.` : null,
+            options.apps.extension ? `## Chrome Web Store
+
+1. Register a Chrome Web Store developer account, verify its contact email, accept the agreement, and pay Google's one-time registration fee.
+2. Configure production extension environment values and a stable CRX public key/ID, then run \`pnpm verify:extension\` and \`pnpm extension:zip\`. Load the unpacked production build in Chrome first and test install, update, permissions, authentication, API calls, and sign-out.
+3. In the Developer Dashboard, create an item and upload the ZIP from \`apps/extension/.output\`. Complete the listing (description, icons, screenshots, category, regions) and keep the manifest version higher for every update.
+4. State one narrow purpose, justify every permission/host permission, disclose all handled data, certify limited use, and provide a public privacy-policy URL consistent with actual behavior. Clerk login counts as handling authentication data. Supply reviewer test instructions and credentials when features are gated.
+5. Publish first to trusted testers/unlisted visibility, verify the store-installed CRX ID matches Clerk and backend allowlists, then submit the production listing for review. Store review and rollout are separate from GitHub/Vercel deployment.` : null,
+            options.apps.desktop ? `## Electron desktop
+
+Builds are platform-specific: produce macOS, Windows, and Linux artifacts on their matching CI runners with the package's \`build:mac\`, \`build:win\`, and \`build:linux\` scripts. Configure signing/notarization credentials in CI, never in the repository. Test clean install, upgrade, deep links, Clerk return flow, auto-update strategy, and OS security warnings before publishing artifacts to the chosen release channel.` : null,
+        ].filter((section) => section !== null);
+        writeFile(path.join(root, 'PRODUCTION.md'), `# ${markdownHeading(options.displayName)} production guide
+
+This guide includes only the surfaces and providers selected when the project was generated. Provision separate Preview and Production resources, use least-privilege credentials, and keep account ownership with the organization rather than an individual developer.
+
+## Release gate
+
+${productionItems.join('\n')}
+
+${productionSections.join('\n\n')}
+
+## Final release order
+
+- Run \`pnpm verify\` and \`anhedral doctor\`; review the exact production diff.
+${options.features.database ? '- Apply reviewed, backward-compatible database migrations.' : ''}
+${options.apps.web || options.apps.api ? '- Deploy provider infrastructure and secrets, then deploy API/web.' : ''}
+${options.apps.mobile || options.apps.extension || options.apps.desktop ? '- Build immutable client artifacts only after production URLs and public keys are final.\n- Release to internal testers, verify telemetry and rollback, then promote through each store review/rollout.' : ''}
 `);
-    writeFile(path.join(dbRoot, 'src/index.ts'), `import { drizzle } from 'drizzle-orm/neon-http';
-import { neon } from '@neondatabase/serverless';
-import * as schema from './schema';
-
-export function createDb(databaseUrl = process.env.DATABASE_URL) {
-  if (!databaseUrl) {
-    throw new Error('DATABASE_URL is not defined');
-  }
-
-  const sql = neon(databaseUrl);
-  return drizzle(sql, { schema });
-}
-
-export type Database = ReturnType<typeof createDb>;
-
-let cachedDb: Database | undefined;
+    }
+    writeFile(path.join(root, 'ANHEDRAL.md'), `# Anhedral-managed project information
 
-function getDb() {
-  cachedDb ??= createDb();
-  return cachedDb;
-}
+Generator: ${GENERATOR_VERSION}
 
-export const db = new Proxy({} as Database, {
-  get(_target, prop, receiver) {
-    return Reflect.get(getDb(), prop, receiver);
-  },
-});
+Resolved modules: ${modules.join(', ')}
 
-export * from './schema';
+- \`anhedral add <module> --dry-run\` previews incremental changes.
+- \`anhedral ui add <component> --dry-run\` previews platform-routed component additions.
+- \`anhedral doctor\` reports manifest and filesystem drift before incremental changes.
+- README and existing user workflows are never rewritten by \`anhedral add\`.
 `);
-    writeFile(path.join(dbRoot, 'src/schema.ts'), `import { boolean, index, integer, jsonb, pgTable, text, timestamp } from 'drizzle-orm/pg-core';
-import type { InferInsertModel, InferSelectModel } from 'drizzle-orm';
+    const surfaceGuidance = [
+        options.apps.web ? '- Web lives in `apps/web`: use Next.js App Router, server-first rendering, and shadcn/ui source components.' : null,
+        options.apps.mobile ? `- Mobile lives in \`apps/mobile\`: use Expo Router and React Native Reusables with ${options.nativeStyling}. Keep native-only APIs behind platform-safe modules.` : null,
+        options.apps.api ? '- HTTP and provider integration lives in `apps/api`: keep Fastify routes thin, validate boundaries, and put secrets only in server environment files.' : null,
+        options.apps.desktop ? '- Desktop lives in `apps/desktop`: keep Electron main/preload privileges minimal and application UI in the sandboxed React renderer.' : null,
+        options.apps.extension ? '- Browser extension code lives in `apps/extension`: use WXT entrypoints and request only permissions required by the feature.' : null,
+        options.features.storage ? '- Private-bucket asset delivery lives in `apps/assets-private-proxy`: preserve the `ASSETS` R2 binding, streaming responses, method/host restrictions, and Cloudflare-managed custom domain.' : null,
+    ].filter((value) => value !== null).join('\n');
+    const featureGuidance = [
+        options.apps.api ? '- Reuse `@shared/contracts` at every network boundary and call the API through `@shared/api-client`; clients must not import server implementation modules.' : null,
+        options.features.database ? '- Neon/Drizzle state is authoritative. Change `packages/db/src/schema.ts`, generate SQL with `pnpm db:generate`, review it, and Git-track the migration.' : null,
+        options.features.auth ? '- Clerk owns identity and sessions. Never trust a client-supplied user ID; derive identity from verified server authentication.' : null,
+        options.features.billing ? '- RevenueCat events reconcile into Neon before Ably publishes an invalidation. Clients refetch entitlements instead of treating realtime payloads as authority.' : null,
+        options.features.storage ? '- R2 credentials and signed-upload policy stay in the API. The `assets-private-proxy` Worker uses its binding instead of S3 credentials and publicly serves GET/HEAD only by known unguessable key.' : null,
+    ].filter((value) => value !== null).join('\n');
+    const skillFeatureSteps = [
+        options.apps.api ? 'Define shared network schemas in `packages/contracts/src/`.' : null,
+        options.features.database ? 'Define persistent state in `packages/db/src/schema.ts`; generate, review, and commit Drizzle SQL. Use managed Neon, never a generated local Postgres service.' : null,
+        options.apps.api ? 'Put backend behavior in `apps/api/src/services/` and keep `apps/api/src/routes/` thin.' : null,
+        options.apps.api ? 'Add client-safe calls to `packages/api-client/src/`; frontends must not import server implementations.' : null,
+        options.apps.web ? 'Write web product code with normal Next.js App Router conventions in `apps/web`.' : null,
+        options.apps.mobile ? 'Write native product code with normal Expo Router conventions in `apps/mobile`.' : null,
+        'Verify the affected package, then run the root verification before handoff.',
+    ].filter((value) => value !== null).map((value, index) => `${index + 1}. ${value}`).join('\n');
+    writeFile(path.join(root, 'SKILL.md'), `---
+name: anhedral-project
+description: Build and extend this Anhedral-generated ${modules.join(', ')} TypeScript application while preserving its framework, ownership, security, and verification conventions.
+---
 
-export const SUBSCRIPTION_TIERS = ['free', 'pro'] as const;
-export type SubscriptionTier = (typeof SUBSCRIPTION_TIERS)[number];
+# Anhedral project
 
-export const SUBSCRIPTION_STATUSES = ['active', 'expired', 'canceled'] as const;
-export type SubscriptionStatus = (typeof SUBSCRIPTION_STATUSES)[number];
+Use this skill whenever you plan, implement, review, or diagnose work in this repository.
 
-export const SUBSCRIPTION_METHODS = ['trialing', 'redeemed', 'paid'] as const;
-export type SubscriptionMethod = (typeof SUBSCRIPTION_METHODS)[number];
+## Product model
 
-export const SUBSCRIPTION_ORIGINS = ['web', 'apple', 'google'] as const;
-export type SubscriptionOrigin = (typeof SUBSCRIPTION_ORIGINS)[number];
+This is a standard TypeScript monorepo assembled by Anhedral, not an application running inside an Anhedral framework. Write normal Next.js, Expo Router, Fastify, Drizzle, Electron, or WXT code in the generated workspace. Use Anhedral only for structural operations such as adding a module, adding source-owned UI, and checking generated-file ownership.
 
-export const SUBSCRIPTION_EVENT_TYPES = [
-  'trial_started', 'trial_converted', 'trial_expired',
-  'initial_purchase', 'renewal', 'product_change',
-  'cancellation_scheduled', 'cancellation_unscheduled', 'subscription_expired', 'subscription_canceled',
-  'billing_issue', 'billing_recovered',
-] as const;
-export type SubscriptionEventType = (typeof SUBSCRIPTION_EVENT_TYPES)[number];
+Before implementing a feature, read \`README.md\` for the source map, \`docs/DEVELOPMENT.md\` for task recipes, and \`docs/STACK.md\` when you need the selected tools' responsibility boundaries and official documentation.
 
-export type SubscriptionMetadata = {
-  revenueCatProductId?: string;
-  lastWebhookUpdate?: string;
-  cancelReason?: string;
-};
+## Start safely
 
-export type SubscriptionEventMetadata = {
-  revenueCatEventType?: string;
-  revenueCatProductId?: string;
-  billingPeriod?: string;
-  price?: { amount: number; currency: string };
-  store?: string;
-  transactionId?: string;
-  reason?: string;
-};
+1. Read \`anhedral.json\` for the selected modules, native styling provider, installed UI components, and file ownership.
+2. Run \`pnpm dlx anhedral@${GENERATOR_VERSION} doctor\` before generator operations.
+3. Preview structural changes with \`anhedral add <module> --dry-run\` or \`anhedral ui add <component> --dry-run\`.
+4. Never hand-edit \`anhedral.json\`, ownership hashes, or bundled-template provenance.
 
-export const users = pgTable('users', {
-  id: text('id').primaryKey(),
-  clerkUserId: text('clerk_user_id').unique(),
-  email: text('email').notNull().unique(),
-  displayName: text('display_name'),
-  lastLoginAt: timestamp('last_login_at'),
-  profileImageUrl: text('profile_image_url'),
-  subscriptionTier: text('subscription_tier').notNull().default('free'),
-  subscriptionStatus: text('subscription_status').notNull().default('active'),
-  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
-  updatedAt: timestamp('updated_at').$defaultFn(() => new Date()).notNull(),
-}, (t) => [
-  index('users_clerk_user_id_idx').on(t.clerkUserId),
-  index('users_email_idx').on(t.email),
-]);
+Resolved modules: ${modules.map((moduleName) => `\`${moduleName}\``).join(', ')}.
 
-export const uploads = pgTable('uploads', {
-  id: text('id').primaryKey(),
-  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
-  objectKey: text('object_key').notNull().unique(),
-  bucket: text('bucket').notNull(),
-  contentType: text('content_type'),
-  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
-});
+## Repository boundaries
 
-export const subscriptions = pgTable('subscriptions', {
-  id: text('id').primaryKey(),
-  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }).unique(),
-  tier: text('tier').$type<SubscriptionTier>().notNull().default('free'),
-  status: text('status').$type<SubscriptionStatus>().notNull().default('active'),
-  method: text('method').$type<SubscriptionMethod>(),
-  origin: text('origin').$type<SubscriptionOrigin>(),
-  billingPeriod: text('billing_period'),
-  currentPeriodStart: timestamp('current_period_start'),
-  currentPeriodEnd: timestamp('current_period_end'),
-  canceledAt: timestamp('canceled_at'),
-  cancelAtPeriodEnd: boolean('cancel_at_period_end').notNull().default(false),
-  trialStart: timestamp('trial_start'),
-  trialEnd: timestamp('trial_end'),
-  dailyLimit: integer('daily_limit'),
-  metadata: jsonb('metadata').$type<SubscriptionMetadata>(),
-  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
-  updatedAt: timestamp('updated_at').$defaultFn(() => new Date()).notNull(),
-}, (t) => [
-  index('subscriptions_user_idx').on(t.userId),
-  index('subscriptions_status_idx').on(t.status),
-  index('subscriptions_tier_idx').on(t.tier),
-  index('subscriptions_period_end_idx').on(t.currentPeriodEnd),
-]);
+${surfaceGuidance}
 
-export const subscriptionEvents = pgTable('subscription_events', {
-  id: text('id').primaryKey(),
-  userId: text('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
-  subscriptionId: text('subscription_id').references(() => subscriptions.id, { onDelete: 'set null' }),
-  eventType: text('event_type').$type<SubscriptionEventType>().notNull(),
-  previousTier: text('previous_tier').$type<SubscriptionTier>(),
-  previousStatus: text('previous_status').$type<SubscriptionStatus>(),
-  previousMethod: text('previous_method').$type<SubscriptionMethod>(),
-  newTier: text('new_tier').$type<SubscriptionTier>(),
-  newStatus: text('new_status').$type<SubscriptionStatus>(),
-  newMethod: text('new_method').$type<SubscriptionMethod>(),
-  revenueCatEventType: text('revenuecat_event_type'),
-  revenueCatProductId: text('revenuecat_product_id'),
-  origin: text('origin').$type<SubscriptionOrigin>(),
-  periodStart: timestamp('period_start'),
-  periodEnd: timestamp('period_end'),
-  metadata: jsonb('metadata').$type<SubscriptionEventMetadata>(),
-  createdAt: timestamp('created_at').$defaultFn(() => new Date()).notNull(),
-}, (t) => [
-  index('sub_events_user_idx').on(t.userId),
-  index('sub_events_user_created_idx').on(t.userId, t.createdAt),
-  index('sub_events_type_idx').on(t.eventType),
-]);
+- Shared source belongs in focused packages under \`packages/\`; do not create a second workspace, lockfile, or nested dependency island.
+${featureGuidance}
 
-export const trialClaims = pgTable('trial_claims', {
-  id: text('id').primaryKey(),
-  userId: text('user_id').references(() => users.id, { onDelete: 'set null' }),
-  email: text('email').notNull().unique(),
-  claimedAt: timestamp('claimed_at').$defaultFn(() => new Date()).notNull(),
-}, (t) => [index('trial_claims_email_idx').on(t.email)]);
-
-export type Users = InferSelectModel<typeof users>;
-export type NewUsers = InferInsertModel<typeof users>;
-export type Uploads = InferSelectModel<typeof uploads>;
-export type NewUploads = InferInsertModel<typeof uploads>;
-export type Subscriptions = InferSelectModel<typeof subscriptions>;
-export type NewSubscriptions = InferInsertModel<typeof subscriptions>;
-export type SubscriptionEvents = InferSelectModel<typeof subscriptionEvents>;
-export type NewSubscriptionEvents = InferInsertModel<typeof subscriptionEvents>;
-export type TrialClaims = InferSelectModel<typeof trialClaims>;
-export type NewTrialClaims = InferInsertModel<typeof trialClaims>;
-`);
-    writeFile(path.join(dbRoot, 'src/queries/users.ts'), `import { eq } from 'drizzle-orm';
-import { db } from '../index';
-import { uploads, users } from '../schema';
-
-type SyncUserInput = {
-  clerkUserId: string;
-  email: string;
-  displayName: string | null;
-};
+## Feature workflow
 
-export async function findUserByClerkId(clerkUserId: string) {
-  return db.query.users.findFirst({
-    where: eq(users.clerkUserId, clerkUserId),
-  });
-}
+${skillFeatureSteps}
 
-export async function syncUserProfile(input: SyncUserInput) {
-  await db
-    .insert(users)
-    .values({
-      id: input.clerkUserId,
-      clerkUserId: input.clerkUserId,
-      email: input.email,
-      displayName: input.displayName,
-    })
-    .onConflictDoUpdate({
-      target: users.clerkUserId,
-      set: {
-        email: input.email,
-        displayName: input.displayName,
-        updatedAt: new Date(),
-      },
-    });
+## UI conventions
 
-  return findUserByClerkId(input.clerkUserId);
-}
+- Add source-owned components with \`pnpm dlx anhedral@${GENERATOR_VERSION} ui add <component>\`; use \`--target\` only when the component should not exist in every selected client.
+- Web, desktop, and extension components come from shadcn/ui. Mobile components come from React Native Reusables using ${options.nativeStyling}.
+- Compose application-specific UI around installed primitives. Preserve accessibility, keyboard behavior, focus handling, and platform conventions.
+- Use lowercase kebab-case filenames, PascalCase component exports, and \`use-\` prefixes for hooks.
 
-export async function createUploadRecord(
-  clerkUserId: string,
-  input: { objectKey: string; bucket: string; contentType: string | null },
-) {
-  await db.insert(uploads).values({
-    id: crypto.randomUUID(),
-    userId: clerkUserId,
-    objectKey: input.objectKey,
-    bucket: input.bucket,
-    contentType: input.contentType,
-  });
-}
-`);
-    writeFile(path.join(dbRoot, 'src/queries/uploads.ts'), `import { eq } from 'drizzle-orm';
-import { db } from '../index';
-import { uploads } from '../schema';
+## Ownership rules
 
-export async function listUploadsForUser(userId: string) {
-  return db.query.uploads.findMany({
-    where: eq(uploads.userId, userId),
-  });
-}
-`);
-    writeFile(path.join(dbRoot, 'src/queries/index.ts'), `export * from './uploads';
-export * from './users';
-`);
-    writeFile(path.join(dbRoot, 'src/migrate.ts'), `import { drizzle } from 'drizzle-orm/neon-http';
-import { migrate } from 'drizzle-orm/neon-http/migrator';
-import { neon } from '@neondatabase/serverless';
-import dotenv from 'dotenv';
+- \`README.md\` and \`PRODUCTION.md\` are user-owned. Root JSON/YAML configuration is mergeable. Other recorded files are generator-managed unless \`anhedral.json\` says otherwise.
+- Prefer new application files and narrow composition points over editing managed substrate files. If a managed file must change, understand that future \`anhedral add\` operations will stop until the project is reconciled.
+- Never overwrite user changes, bypass a generator conflict, or replace a failed ownership check with fabricated hashes.
 
-dotenv.config({ path: '../../.env', quiet: true });
-dotenv.config({ quiet: true });
+## Environment and security
 
-if (!process.env.DATABASE_URL) {
-  throw new Error('DATABASE_URL is not defined');
-}
+- The root \`.env.example\` is an inventory, not a runtime environment file. Copy package-local examples and keep real environment files uncommitted.
+- Keep server secrets out of browser, Expo, Electron renderer, and extension bundles. Only variables with the framework's explicit public prefix may enter client code.
+- Validate external input at the API boundary, use parameterized Drizzle queries, and keep privileged Electron functionality behind a narrow context-isolated preload bridge.
 
-const client = neon(process.env.DATABASE_URL);
-const database = drizzle(client);
+## Deployment conventions
 
-console.log('Running migrations...');
-const start = Date.now();
-await migrate(database, { migrationsFolder: './migrations' });
-console.log('Migrations completed in', Date.now() - start, 'ms');
-`);
-    writeFile(path.join(dbRoot, 'migrations/.gitkeep'), '');
-    const simplePackages = [
-        ['contracts', {
-                exports: { '.': './src/index.ts' },
-                dependencies: CONTRACTS_DEPENDENCIES.dependencies,
-            }, `import { z } from 'zod';
-
-export const ClientPlatformSchema = z.enum(['frontend', 'extension']);
-export type ClientPlatform = z.infer<typeof ClientPlatformSchema>;
-
-export const ApiErrorSchema = z.object({
-  error: z.string(),
-  message: z.string(),
-});
-export type ApiError = z.infer<typeof ApiErrorSchema>;
-
-export const AuthMeResponseSchema = z.object({
-  user: z.object({
-    id: z.string(),
-    email: z.string().email(),
-    firstName: z.string().nullable().optional(),
-    lastName: z.string().nullable().optional(),
-    displayName: z.string(),
-    imageUrl: z.string().url().nullable().optional(),
-  }),
-});
-export type AuthMeResponse = z.infer<typeof AuthMeResponseSchema>;
-
-export const PricingResponseSchema = z.object({
-  tiers: z.array(z.object({
-    tier: z.enum(['free', 'pro']),
-    displayName: z.string(),
-    description: z.string(),
-    priceMonthly: z.number().nullable(),
-    priceYearly: z.number().nullable(),
-    currency: z.string(),
-    limits: z.object({
-      dailyLimit: z.number().nullable(),
-    }),
-    paymentInfo: z.object({
-      revenueCatEntitlementId: z.string(),
-      revenueCatOfferingId: z.string(),
-    }).optional(),
-  })),
-});
-export type PricingResponse = z.infer<typeof PricingResponseSchema>;
-
-export const SubscriptionEntitlementsSchema = z.object({
-  pro: z.boolean(),
-  inTrial: z.boolean(),
-  trialEndsAt: z.string().optional(),
-  expiresAt: z.string().optional(),
-  periodStart: z.string().optional(),
-  periodEnd: z.string().optional(),
-  method: z.enum(['trialing', 'redeemed', 'paid']).nullable().optional(),
-  managementUrl: z.string().url().optional(),
-  cancelAtPeriodEnd: z.boolean().optional(),
-});
-export type SubscriptionEntitlements = z.infer<typeof SubscriptionEntitlementsSchema>;
+- Read \`PRODUCTION.md\` before provisioning or changing production resources. It is tailored to this project's selected surfaces and providers.
+${options.apps.web || options.apps.api ? '- Prefer GitHub-triggered Vercel Preview and Production deployments. Keep the generated Services routing intact; use manual `deploy:vercel:*` scripts only when explicitly required.' : ''}
+${options.features.database ? '- Treat reviewed, committed Drizzle SQL as the release artifact. Apply migrations as a controlled step against the intended Neon environment; never generate migrations during an application build.' : ''}
+${options.features.storage ? '- Keep the R2 bucket private and deploy `assets-private-proxy` at the Cloudflare Worker custom domain. Expose only `storage/confirmed/` publicly; use the owner-authorized read-URL endpoint for private objects and keep `CLOUDFLARE_API_TOKEN` operations-only.' : ''}
+${options.apps.mobile ? '- Promote mobile artifacts through EAS internal distribution, TestFlight/Google Play testing, then store review. Build-time public variables are not secrets.' : ''}
+${options.apps.extension ? '- Publish the exact verified WXT ZIP through trusted/unlisted Chrome Web Store testing before production review; preserve a stable CRX ID and least-privilege permissions.' : ''}
 
-export const SignOutResponseSchema = z.object({
-  success: z.boolean(),
-});
-export type SignOutResponse = z.infer<typeof SignOutResponseSchema>;
+## Verify changes
 
-export const CreateUploadRequestSchema = z.object({
-  fileName: z.string().min(1).max(200).optional(),
-  contentType: z.string().min(1).max(200),
-});
-export type CreateUploadRequest = z.infer<typeof CreateUploadRequestSchema>;
+Run the strongest applicable checks before handing work back:
 
-export const CreateUploadResponseSchema = z.object({
-  objectKey: z.string(),
-  uploadUrl: z.string().url(),
-  expiresIn: z.number(),
-  headers: z.record(z.string(), z.string()),
-});
-export type CreateUploadResponse = z.infer<typeof CreateUploadResponseSchema>;
+\`\`\`sh
+pnpm typecheck
+pnpm verify
+pnpm build
+pnpm dlx anhedral@${GENERATOR_VERSION} doctor
+\`\`\`
 
-export const StorageFileResponseSchema = z.object({
-  objectKey: z.string(),
-  downloadUrl: z.string().url(),
-  expiresIn: z.number(),
-});
-export type StorageFileResponse = z.infer<typeof StorageFileResponseSchema>;
-`],
-        ['types', {
-                exports: { '.': './src/index.ts' },
-                dependencies: { '@shared/contracts': 'workspace:*' },
-            }, `export type ApiEnvelope<T> = { data: T } | { error: string; message: string };
-export type {
-  AuthMeResponse,
-  ClientPlatform,
-  CreateUploadRequest,
-  CreateUploadResponse,
-  PricingResponse,
-  SignOutResponse,
-  StorageFileResponse,
-  SubscriptionEntitlements,
-} from '@shared/contracts';
-`],
-        ['config', { exports: { '.': './src/index.ts' } }, `export const DEFAULT_API_PATH_PREFIX = '/api';
-export const DEFAULT_LOCAL_API_URL = 'http://localhost:8787';
-export const DEFAULT_FRONTEND_URL = 'http://localhost:8081';
-export const DEFAULT_EXTENSION_URL = 'chrome-extension://';
-
-export function joinApiUrl(baseUrl: string, path: string) {
-  const base = baseUrl.replace(/\\/$/, '');
-  const suffix = path.startsWith('/') ? path : \`/\${path}\`;
-  return \`\${base}\${suffix}\`;
-}
-`],
-        ['api-client', {
-                exports: { '.': './src/index.ts' },
-                dependencies: API_CLIENT_DEPENDENCIES.dependencies,
-            }, `import type { ZodType } from 'zod';
-import { joinApiUrl } from '@shared/config';
-import {
-  AuthMeResponseSchema,
-  CreateUploadResponseSchema,
-  PricingResponseSchema,
-  SignOutResponseSchema,
-  StorageFileResponseSchema,
-  SubscriptionEntitlementsSchema,
-  type AuthMeResponse,
-  type ClientPlatform,
-  type CreateUploadRequest,
-  type CreateUploadResponse,
-  type PricingResponse,
-  type SignOutResponse,
-  type StorageFileResponse,
-  type SubscriptionEntitlements,
-} from '@shared/contracts';
-
-export class APIRequestError extends Error {
-  constructor(
-    public statusCode: number,
-    message: string,
-    public errorCode?: string,
-  ) {
-    super(message);
-    this.name = 'APIRequestError';
-  }
+Use the package-specific \`verify:*\` scripts while iterating. A database schema change is incomplete until its reviewed migration is Git-tracked. Report exact failing packages and commands; do not weaken checks to make a change pass.
+`);
 }
-
-export type ApiClientOptions = {
-  baseUrl: string;
-  platform: ClientPlatform;
-  getToken?: () => Promise<string | null>;
-};
-
-export class ApiClient {
-  constructor(private readonly options: ApiClientOptions) {}
-
-  async request<T>(path: string, init: RequestInit = {}, schema?: ZodType<T>): Promise<T> {
-    const token = await this.options.getToken?.();
-    const headers = new Headers(init.headers);
-    if (init.body != null) {
-      headers.set('Content-Type', headers.get('Content-Type') ?? 'application/json');
+function collectFiles(root, relativeRoot = '') {
+    const absoluteRoot = path.join(root, relativeRoot);
+    if (!pathEntryExists(absoluteRoot))
+        return [];
+    const files = [];
+    for (const entry of readdirSync(absoluteRoot, { withFileTypes: true })) {
+        if (GENERATED_CACHE_NAMES.has(entry.name))
+            continue;
+        const relativePath = relativeRoot ? `${relativeRoot}/${entry.name}` : entry.name;
+        if (relativePath === 'anhedral.json' || isTransactionMetadata(relativePath))
+            continue;
+        if (entry.isDirectory())
+            files.push(...collectFiles(root, relativePath));
+        else if (entry.isFile())
+            files.push(relativePath);
     }
-    headers.set('X-Platform', this.options.platform);
-    if (token) headers.set('Authorization', \`Bearer \${token}\`);
-
-    const response = await fetch(joinApiUrl(this.options.baseUrl, path), {
-      ...init,
-      headers,
-    });
-
-    if (!response.ok) {
-      let error: { error?: string; message?: string } = {};
-      try { error = await response.json(); } catch {}
-      throw new APIRequestError(
-        response.status,
-        error.message || \`API request failed: \${response.status}\`,
-        error.error,
-      );
+    return files.sort();
+}
+function ownerForPath(relativePath) {
+    if (relativePath.startsWith('apps/assets-private-proxy/'))
+        return 'storage';
+    if (relativePath.startsWith('cloudflare/'))
+        return 'storage';
+    const app = /^apps\/(web|mobile|api|desktop|extension)(?:\/|$)/.exec(relativePath);
+    if (app)
+        return app[1];
+    if (relativePath.startsWith('packages/db/'))
+        return 'db';
+    return 'root';
+}
+function defaultOwnership(relativePath) {
+    if (relativePath === 'README.md' || relativePath === 'PRODUCTION.md')
+        return 'user';
+    if (relativePath === 'apps/assets-private-proxy/wrangler.jsonc')
+        return 'user';
+    if (relativePath === 'cloudflare/r2-cors.template.json')
+        return 'user';
+    if (ROOT_MERGEABLE_FILES.has(relativePath))
+        return 'mergeable';
+    return 'managed';
+}
+function createProjectManifest(root, options, operation, templates, previous, components = previous?.ui.components ?? []) {
+    const contributions = new Map();
+    for (const relativePath of collectFiles(root)) {
+        const previousRecord = previous?.files[relativePath];
+        const ownership = previousRecord?.ownership ?? defaultOwnership(relativePath);
+        const owner = previousRecord?.owner ?? ownerForPath(relativePath);
+        const files = contributions.get(owner) ?? [];
+        files.push({
+            path: relativePath,
+            ownership,
+            content: readFileSync(path.join(root, relativePath), 'utf8'),
+        });
+        contributions.set(owner, files);
     }
-
-    if (response.status === 204) return {} as T;
-    const data = await response.json();
-    return schema ? schema.parse(data) : data as T;
-  }
-
-  getMe() {
-    return this.request<AuthMeResponse>('/auth/me', {}, AuthMeResponseSchema);
-  }
-
-  getPricing() {
-    return this.request<PricingResponse>('/subscriptions/pricing', {}, PricingResponseSchema);
-  }
-
-  getSubscriptionPricing() {
-    return this.getPricing();
-  }
-
-  getSubscriptionEntitlements(options?: { refresh?: boolean }) {
-    return this.request<SubscriptionEntitlements>(
-      options?.refresh ? '/subscriptions/entitlements/me?refresh=true' : '/subscriptions/entitlements/me',
-      {},
-      SubscriptionEntitlementsSchema,
-    );
-  }
-
-  signOut() {
-    return this.request<SignOutResponse>('/auth/signout', {
-      method: 'POST',
-    }, SignOutResponseSchema);
-  }
-
-  deleteAccount() {
-    return this.request<void>('/auth/account', {
-      method: 'DELETE',
+    const plan = buildGenerationPlan({
+        operation,
+        requestedModules: options.modules,
+        contributions: [...contributions].map(([module, files]) => ({ module, files })),
     });
-  }
-
-  createUpload(input: CreateUploadRequest) {
-    return this.request<CreateUploadResponse>('/storage/uploads', {
-      method: 'POST',
-      body: JSON.stringify(input),
-    }, CreateUploadResponseSchema);
-  }
-
-  getStorageFile(objectKey: string) {
-    return this.request<StorageFileResponse>(
-      \`/storage/files/\${encodeURIComponent(objectKey)}\`,
-      {},
-      StorageFileResponseSchema,
-    );
-  }
-
-  deleteStorageFile(objectKey: string) {
-    return this.request<void>(\`/storage/files/\${encodeURIComponent(objectKey)}\`, {
-      method: 'DELETE',
+    const manifest = createManifest({
+        generatorVersion: GENERATOR_VERSION,
+        project: { name: options.projectName, displayName: options.displayName },
+        plan,
+        toolchain: options.toolchainChannel,
+        templates,
+        nativeStyling: options.nativeStyling,
+        components,
     });
-  }
+    const files = Object.freeze(Object.fromEntries(Object.entries(manifest.files).map(([relativePath, record]) => [
+        relativePath,
+        Object.freeze({
+            ...record,
+            hash: hashContent(readFileSync(path.join(root, relativePath))),
+            mode: normalizedFileMode(lstatSync(path.join(root, relativePath)).mode),
+        }),
+    ])));
+    return Object.freeze({ ...manifest, files });
 }
-`],
-    ];
-    for (const [name, packageFields, source] of simplePackages) {
-        const packageRoot = path.join(root, `packages/${name}`);
-        writeFile(path.join(packageRoot, 'package.json'), JSON.stringify({
-            name: `@shared/${name}`,
-            version: '0.1.0',
-            private: true,
-            type: 'module',
-            scripts: {
-                build: 'pnpm typecheck',
-                typecheck: 'tsc --noEmit',
-            },
-            devDependencies: SHARED_PACKAGE_DEPENDENCIES.devDependencies,
-            ...packageFields,
-        }, null, 2) + '\n');
-        writeFile(path.join(packageRoot, 'tsconfig.json'), JSON.stringify({
-            compilerOptions: {
-                target: 'ESNext',
-                module: 'ESNext',
-                moduleResolution: 'Bundler',
-                strict: true,
-                skipLibCheck: true,
-                noEmit: true,
-            },
-            include: ['src/**/*'],
-        }, null, 2) + '\n');
-        writeFile(path.join(packageRoot, 'src/index.ts'), source);
+function writeManifest(root, manifest) {
+    writeFile(path.join(root, 'anhedral.json'), serializeManifest(manifest));
+}
+function readProjectManifest(root) {
+    const filePath = path.join(root, 'anhedral.json');
+    if (!pathEntryExists(filePath))
+        throw new Error('anhedral.json was not found. Run anhedral init first.');
+    const manifest = readManifest(readFileSync(filePath, 'utf8'));
+    if (manifest.generatorVersion !== GENERATOR_VERSION) {
+        throw new Error(`This project was generated by Anhedral ${manifest.generatorVersion}; current CLI ${GENERATOR_VERSION} only supports exact-current projects. `
+            + 'Regenerate the project with the current CLI before adding modules.');
     }
+    assertTemplateProvenance(manifest.modules, manifest.templates);
+    return manifest;
 }
-function writeRootEnvExample(root) {
-    const frontendUrl = 'http://localhost:8081';
-    const expoEnv = `EXPO_PUBLIC_API_URL=http://localhost:8787
-EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_***
-EXPO_PUBLIC_RC_ENTITLEMENT_ID=pro
-EXPO_PUBLIC_RC_API_KEY_IOS=
-EXPO_PUBLIC_RC_API_KEY_ANDROID=
-EXPO_PUBLIC_RC_WEB_API_KEY=
-`;
-    const extensionEnv = `VITE_API_URL=http://localhost:8787
-VITE_WEBSITE_URL=${frontendUrl}
-VITE_CLERK_PUBLISHABLE_KEY=pk_test_***
-VITE_CRX_PUBLIC_KEY=
-VITE_RC_BILLING_URL=
-`;
-    const paymentsEnv = `# RevenueCat
-RC_SECRET_API_KEY=
-RC_WEBHOOK_SECRET=
-RC_ENTITLEMENT_ID=pro
-RC_OFFERING_ID=default
-`;
-    writeFile(path.join(root, '.env.example'), `# Apps
-FRONTEND_URL=${frontendUrl}
-ANHEDRAL_DEMO=false
-${expoEnv}${extensionEnv}
-
-# Server
-PORT=8787
-DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-1.aws.neon.tech/dbname?sslmode=require
-
-# Clerk
-CLERK_PUBLISHABLE_KEY=pk_test_***
-CLERK_SECRET_KEY=sk_test_***
-
-# Cloudflare R2
-R2_ACCOUNT_ID=
-R2_ACCESS_KEY_ID=
-R2_SECRET_ACCESS_KEY=
-R2_BUCKET=
-
-${paymentsEnv}`);
+function cleanNestedArtifacts(root) {
+    rmSync(path.join(root, 'node_modules'), { recursive: true, force: true });
+    const appsRoot = path.join(root, 'apps');
+    if (!pathEntryExists(appsRoot))
+        return;
+    for (const app of readdirSync(appsRoot, { withFileTypes: true })) {
+        if (!app.isDirectory())
+            continue;
+        for (const artifact of ['.git', 'node_modules', 'package-lock.json', 'pnpm-lock.yaml', 'pnpm-workspace.yaml', 'yarn.lock']) {
+            rmSync(path.join(appsRoot, app.name, artifact), { recursive: true, force: true });
+        }
+    }
 }
-function writeRootVercelFiles(root) {
-    writeFile(path.join(root, '.vercelignore'), `Extension/.output
-Extension/.wxt
-Extension/dist
-`);
+function selectedUiTargets(options) {
+    return UI_TARGETS.filter((target) => options.apps[target]);
 }
-function writeGeneratedCiWorkflow(root) {
-    writeFile(path.join(root, '.github/workflows/ci.yml'), `name: CI
-
-on:
-  pull_request:
-  push:
-    branches:
-      - main
-
-permissions:
-  contents: read
-
-concurrency:
-  group: ci-\${{ github.workflow }}-\${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  verify:
-    runs-on: ubuntu-latest
-    timeout-minutes: 45
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 10.15.1
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: pnpm
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Check Expo dependency alignment
-        run: pnpm --filter ./Frontend exec expo install --check
-
-      - name: Build Expo web
-        run: pnpm --filter ./Frontend build:web
-
-      - name: Test API
-        run: pnpm --filter ./Backend test
-
-      - name: Build API
-        run: pnpm --filter ./Backend build
-
-      - name: Build extension
-        run: pnpm --filter ./Extension build
-
-      - name: Zip extension
-        run: pnpm --filter ./Extension zip
-
-      - name: Build workspace
-        run: pnpm build
-`);
+function installSelectedUiComponents(root, options) {
+    const installs = resolveUiInstalls(options.uiComponents, selectedUiTargets(options), options.nativeStyling);
+    if (installs.length > 0 && !options.dryRun)
+        installUiComponents(root, installs);
+    return installs;
 }
-function writeFullstackRootFiles(root, options) {
-    const appFilters = [
-        './Frontend',
-        './Backend',
-        './Extension',
-    ];
-    const parallelFilters = appFilters.map((entry) => `--filter=${entry}`).join(' ');
-    const scripts = {
-        dev: `turbo dev --parallel ${parallelFilters}`,
-        'dev:backend': 'pnpm --filter ./Backend dev',
-        build: 'turbo build',
-        typecheck: 'turbo typecheck',
-        verify: 'pnpm verify:frontend && pnpm verify:backend && pnpm verify:extension',
-        'verify:frontend': 'pnpm --filter ./Frontend exec expo install --check && pnpm --filter ./Frontend build:web',
-        'verify:backend': 'pnpm --filter ./Backend test && pnpm --filter ./Backend build',
-        'verify:extension': 'pnpm --filter ./Extension typecheck && pnpm --filter ./Extension zip',
-        'db:generate': 'pnpm --filter @shared/db db:generate',
-        'db:migrate': 'pnpm --filter @shared/db db:migrate',
-        'db:studio': 'pnpm --filter @shared/db db:studio',
-        'db:check': 'pnpm --filter @shared/db db:check',
-    };
-    scripts['dev:frontend'] = 'pnpm --filter ./Frontend dev';
-    scripts['dev:extension'] = 'pnpm --filter ./Extension dev';
-    scripts['extension:zip'] = 'pnpm --filter ./Extension zip';
-    writeRootPackageJson(root, options.projectName, scripts, ['Frontend', 'Backend', 'Extension', 'packages/*'], {
-        devDependencies: ROOT_DEPENDENCIES.devDependencies,
+function installWorkspaceDependencies(root) {
+    const executable = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+    execFile(executable, ['install', '--no-frozen-lockfile'], root);
+}
+async function writeSelectedModules(root, options) {
+    const templates = materializeTemplates(root, resolveModules(options.modules).resolvedModules);
+    const shared = projectOptions(options);
+    scaffoldSharedPackages(root, shared);
+    if (options.apps.api)
+        await scaffoldApi(root, shared);
+    if (options.apps.mobile)
+        await scaffoldMobile(root, shared);
+    if (options.apps.web)
+        await scaffoldWeb(root, shared);
+    if (options.apps.desktop)
+        await scaffoldDesktop(root, shared);
+    if (options.apps.extension)
+        await scaffoldExtension(root, shared);
+    if (options.features.storage)
+        scaffoldAssetsPrivateProxy(root, shared);
+    return templates;
+}
+function printPlan(operation, paths, json) {
+    if (json) {
+        console.log(JSON.stringify({ operation, paths }, null, 2));
+        return;
+    }
+    anhedralPrint.info(`${operation} plan: ${paths.length} path${paths.length === 1 ? '' : 's'}`);
+    for (const relativePath of paths)
+        console.log(`  ${relativePath}`);
+}
+function assertSafeChangedPaths(root, stageRoot, manifest, paths, deleting = new Set()) {
+    for (const relativePath of paths) {
+        if (relativePath === 'anhedral.json')
+            continue;
+        const target = path.join(root, relativePath);
+        const record = manifest.files[relativePath];
+        const targetStat = lstatIfPresent(target);
+        if (targetStat?.isSymbolicLink())
+            throw new Error(`Refusing to modify symbolic-link path: ${relativePath}`);
+        if (targetStat && !record) {
+            throw new Error(`Refusing to overwrite unowned path: ${relativePath}`);
+        }
+        if (!record || !targetStat)
+            continue;
+        assertManagedFileMode(relativePath, record, targetStat);
+        const actualHash = hashContent(readFileSync(target));
+        if (record.ownership === 'user') {
+            throw new Error(`Refusing to modify user-owned path: ${relativePath}`);
+        }
+        if (record.ownership === 'managed' && actualHash !== record.hash) {
+            throw new Error(`Managed file has user modifications: ${relativePath}`);
+        }
+        if (!deleting.has(relativePath) && !pathEntryExists(path.join(stageRoot, relativePath))) {
+            throw new Error(`Internal plan error: staged path is missing: ${relativePath}`);
+        }
+    }
+}
+function stagedFileDiff(root, stageRoot, manifest) {
+    const changed = [...collectFiles(stageRoot), 'anhedral.json'].filter((relativePath) => {
+        const target = path.join(root, relativePath);
+        const targetStat = lstatIfPresent(target);
+        if (!targetStat)
+            return true;
+        if (targetStat.isSymbolicLink())
+            throw new Error(`Refusing to compare symbolic-link path: ${relativePath}`);
+        const stagedTarget = path.join(stageRoot, relativePath);
+        const stagedStat = lstatSync(stagedTarget);
+        const targetMode = normalizedFileMode(targetStat.mode);
+        const stagedMode = normalizedFileMode(stagedStat.mode);
+        return !readFileSync(target).equals(readFileSync(stagedTarget))
+            || (targetMode !== null && stagedMode !== null && targetMode !== stagedMode);
     });
-    writePnpmWorkspace(root, ['Frontend', 'Backend', 'Extension', 'packages/*']);
-    writeFile(path.join(root, 'turbo.json'), JSON.stringify({
-        $schema: 'https://turborepo.dev/schema.json',
-        tasks: {
-            build: {
-                dependsOn: ['^build'],
-                outputs: [],
+    const deleted = Object.keys(manifest?.files ?? {}).filter((relativePath) => pathEntryExists(path.join(root, relativePath)) && !pathEntryExists(path.join(stageRoot, relativePath)));
+    return { changed, deleted };
+}
+export async function scaffoldProject(inputOptions) {
+    const options = canonicalInitOptions(inputOptions);
+    assertInstallNodeCompatibility(options);
+    const root = path.resolve(options.rootDirectory ?? process.cwd());
+    let createdRoot = false;
+    if (!pathEntryExists(root)) {
+        mkdirSync(root);
+        createdRoot = true;
+    }
+    const previousChannel = env.ANHEDRAL_TOOLCHAIN;
+    env.ANHEDRAL_TOOLCHAIN = options.toolchainChannel;
+    const commitPaths = [];
+    const seedPaths = [];
+    try {
+        anhedralPrint.banner(`Initializing ${options.displayName}`);
+        const planned = await runStagedTransaction(root, {
+            commitPaths,
+            seedPaths,
+            dryRun: options.dryRun,
+            prepare: () => {
+                ensureScaffoldRoot(root);
+                if (pathEntryExists(path.join(root, '.gitignore')))
+                    seedPaths.push('.gitignore');
             },
-            typecheck: {
-                dependsOn: ['^build'],
+            build: async (stageRoot) => {
+                writeRootFiles(stageRoot, options, 'init', root);
+                const templates = await writeSelectedModules(stageRoot, options);
+                const components = installSelectedUiComponents(stageRoot, options);
+                writeProjectDocs(stageRoot, options, true);
+                cleanNestedArtifacts(stageRoot);
+                rmSync(path.join(stageRoot, 'pnpm-lock.yaml'), { force: true });
+                writeManifest(stageRoot, createProjectManifest(stageRoot, options, 'init', templates, undefined, components));
+                commitPaths.push(...readdirSync(stageRoot));
             },
-            dev: {
-                cache: false,
-                persistent: true,
+            afterCommit: () => {
+                if (!options.skipInstall) {
+                    anhedralPrint.section('Workspace install');
+                    installWorkspaceDependencies(root);
+                }
             },
-        },
-    }, null, 2) + '\n');
-    appendGitignore(root, [
-        'node_modules',
-        '.turbo',
-        'Frontend/node_modules',
-        'Backend/node_modules',
-        'Extension/node_modules',
-        'packages/*/node_modules',
-        ...SHARED_ENV_GITIGNORE_LINES,
-        ...SHARED_TYPESCRIPT_GITIGNORE_LINES,
-    ]);
-    writeRootEnvExample(root);
-    writeRootVercelFiles(root);
-    writeGeneratedCiWorkflow(root);
+        });
+        if (options.dryRun)
+            printPlan('init', planned, options.json);
+        if (!options.dryRun)
+            anhedralPrint.done(`Committed ${planned.length} paths`);
+        if (!options.dryRun && options.json)
+            printPlan('init', planned, true);
+    }
+    finally {
+        if (previousChannel == null)
+            delete env.ANHEDRAL_TOOLCHAIN;
+        else
+            env.ANHEDRAL_TOOLCHAIN = previousChannel;
+        if (createdRoot && pathEntryExists(root) && readdirSync(root).length === 0)
+            rmdirSync(root);
+    }
 }
-async function scaffoldFullstack(root, options) {
-    anhedralPrint.section('Workspace root');
-    anhedralPrint.step('Writing root config (package.json, pnpm workspace, env, vercel)');
-    writeFullstackRootFiles(root, options);
-    anhedralPrint.done('Root config written');
-    anhedralPrint.section('Shared packages');
-    anhedralPrint.step('Writing @shared/db, types, config, api-client');
-    writeSharedPackages(root);
-    anhedralPrint.done('Shared packages written');
-    const frontendUrl = 'http://localhost:8081';
-    await scaffoldBackend(root, {
-        projectName: options.projectName,
-        displayName: options.displayName,
-        githubOrg: null,
-        frontendUrl,
-        skipInstall: options.skipInstall,
-    });
-    await scaffoldFrontend(root, {
-        projectName: options.projectName,
-        displayName: options.displayName,
-        githubOrg: null,
-        frontendUrl,
-        skipInstall: options.skipInstall,
-    });
-    await scaffoldExtension(root, {
-        projectName: options.projectName,
-        displayName: options.displayName,
-        githubOrg: null,
-        frontendUrl,
-        skipInstall: options.skipInstall,
-    });
-    return [
-        '.github/workflows/ci.yml',
-        'PRODUCTION.md',
-        'Frontend',
-        'Backend',
-        'Extension',
-        'packages/db',
-        'packages/types',
-        'packages/config',
-        'packages/api-client',
-    ];
+export async function scaffoldUiComponents(uiOptions) {
+    const root = path.resolve(process.cwd());
+    let manifest;
+    let options;
+    let additions = [];
+    let components = [];
+    let noOp = false;
+    const seedPaths = [];
+    const commitPaths = [];
+    const previousChannel = env.ANHEDRAL_TOOLCHAIN;
+    try {
+        const planned = await runStagedTransaction(root, {
+            seedPaths,
+            commitPaths,
+            dryRun: uiOptions.dryRun,
+            prepare: () => {
+                manifest = readProjectManifest(root);
+                assertManagedFileModes(root, manifest);
+                const installedTargets = UI_TARGETS.filter((target) => manifest.modules.includes(target));
+                const targets = uiOptions.targets.length > 0 ? uiOptions.targets : installedTargets;
+                if (targets.length === 0)
+                    throw new Error('This project has no UI client. Add web, mobile, desktop, or extension first.');
+                for (const target of targets) {
+                    if (!manifest.modules.includes(target))
+                        throw new Error(`UI target is not installed: ${target}`);
+                }
+                const requested = resolveUiInstalls(uiOptions.components, targets, manifest.ui.nativeStyling);
+                const installedKeys = new Set(manifest.ui.components.map(uiInstallKey));
+                additions = requested.filter((entry) => !installedKeys.has(uiInstallKey(entry)));
+                components = mergeUiInstalls(manifest.ui.components, additions);
+                if (additions.length === 0) {
+                    noOp = true;
+                    return false;
+                }
+                options = {
+                    projectName: manifest.project.name,
+                    displayName: manifest.project.displayName,
+                    modules: [...manifest.modules],
+                    ...selectionsFromModules(manifest.modules),
+                    skipInstall: uiOptions.skipInstall,
+                    dryRun: uiOptions.dryRun,
+                    json: uiOptions.json,
+                    toolchainChannel: toolchainChannelFromManifest(manifest),
+                    uiComponents: [],
+                    nativeStyling: manifest.ui.nativeStyling,
+                };
+                env.ANHEDRAL_TOOLCHAIN = options.toolchainChannel;
+                seedPaths.push(...new Set([
+                    ...Object.keys(manifest.files).filter((relativePath) => pathEntryExists(path.join(root, relativePath))),
+                    'anhedral.json',
+                ]));
+                anhedralPrint.banner(`Adding UI components`);
+            },
+            build: async (stageRoot) => {
+                if (!manifest || !options)
+                    throw new Error('Internal UI plan was not prepared.');
+                if (!uiOptions.dryRun)
+                    installUiComponents(stageRoot, additions);
+                cleanNestedArtifacts(stageRoot);
+                rmSync(path.join(stageRoot, 'pnpm-lock.yaml'), { force: true });
+                writeManifest(stageRoot, createProjectManifest(stageRoot, options, 'add', manifest.templates, manifest, components));
+                const diff = stagedFileDiff(root, stageRoot, manifest);
+                assertSafeChangedPaths(root, stageRoot, manifest, [...diff.changed, ...diff.deleted], new Set(diff.deleted));
+                commitPaths.push(...diff.changed);
+            },
+            afterCommit: () => {
+                if (!uiOptions.skipInstall)
+                    installWorkspaceDependencies(root);
+            },
+        });
+        if (noOp) {
+            if (uiOptions.json)
+                console.log(JSON.stringify({ operation: 'ui-add', paths: [], components: [] }, null, 2));
+            else
+                anhedralPrint.info('All requested UI components are already installed in the selected clients.');
+            return;
+        }
+        const componentPlan = additions.map((entry) => ({
+            component: entry.name,
+            target: entry.target,
+            provider: entry.provider,
+            source: entry.source,
+        }));
+        if (uiOptions.json) {
+            console.log(JSON.stringify({ operation: 'ui-add', paths: planned, components: componentPlan }, null, 2));
+        }
+        else {
+            anhedralPrint.info(`ui-add plan: ${componentPlan.length} installation${componentPlan.length === 1 ? '' : 's'}`);
+            for (const entry of componentPlan)
+                console.log(`  ${entry.target}: ${entry.component} (${entry.provider})`);
+            for (const relativePath of planned)
+                console.log(`  ${relativePath}`);
+        }
+    }
+    finally {
+        if (previousChannel == null)
+            delete env.ANHEDRAL_TOOLCHAIN;
+        else
+            env.ANHEDRAL_TOOLCHAIN = previousChannel;
+    }
 }
-export async function scaffoldProject(options) {
+export async function scaffoldAddModules(addOptions) {
     const root = path.resolve(process.cwd());
-    ensureScaffoldRoot(root);
-    const previousToolchain = env.ANHEDRAL_TOOLCHAIN;
-    env.ANHEDRAL_TOOLCHAIN = options.toolchainChannel;
+    let manifest;
+    let options;
+    let missing = [];
+    let noOp = false;
+    const seedPaths = [];
+    const commitPaths = [];
+    const deletePaths = [];
+    const previousChannel = env.ANHEDRAL_TOOLCHAIN;
     try {
-        await printAsciiLogo();
-        anhedralPrint.banner(`Initializing ${options.displayName} in ${root}`);
-        const generatedPaths = await scaffoldFullstack(root, options);
-        anhedralPrint.section('Project metadata');
-        anhedralPrint.step('Writing skills guide, README, and stack.json');
-        const skillCommands = getSkillCommands();
-        writeSkillsGuide(root, skillCommands);
-        const stack = normalizeStack(options, generatedPaths);
-        writeRootDocs(root, options, stack);
-        writeProductionGuide(root, options);
-        writeStackFile(root, stack);
-        anhedralPrint.done('Project metadata written');
-        console.log('');
-        anhedralPrint.banner(`${options.displayName} is ready`);
-        for (const generatedPath of generatedPaths) {
-            anhedralPrint.done(generatedPath);
+        const planned = await runStagedTransaction(root, {
+            commitPaths,
+            deletePaths,
+            seedPaths,
+            dryRun: addOptions.dryRun,
+            prepare: () => {
+                manifest = readProjectManifest(root);
+                assertManagedFileModes(root, manifest);
+                const desiredRequested = [...new Set([...manifest.modules, ...addOptions.modules])];
+                const resolution = resolveModules(desiredRequested);
+                const installed = new Set(manifest.modules);
+                missing = resolution.resolvedModules.filter((moduleId) => !installed.has(moduleId));
+                if (!missing.length) {
+                    noOp = true;
+                    return false;
+                }
+                options = optionsFromManifest(manifest, addOptions, resolution.requestedModules);
+                assertInstallNodeCompatibility(options);
+                env.ANHEDRAL_TOOLCHAIN = options.toolchainChannel;
+                seedPaths.push(...new Set([
+                    ...Object.keys(manifest.files).filter((relativePath) => pathEntryExists(path.join(root, relativePath))),
+                    'anhedral.json',
+                ]));
+                anhedralPrint.banner(`Adding ${missing.join(', ')}`);
+            },
+            build: async (stageRoot) => {
+                if (!manifest || !options)
+                    throw new Error('Internal add plan was not prepared.');
+                writeRootFiles(stageRoot, options, 'add', root, manifest);
+                const templates = await writeSelectedModules(stageRoot, options);
+                writeProjectDocs(stageRoot, options, false);
+                cleanNestedArtifacts(stageRoot);
+                writeManifest(stageRoot, createProjectManifest(stageRoot, options, 'add', templates, manifest));
+                const diff = stagedFileDiff(root, stageRoot, manifest);
+                assertSafeChangedPaths(root, stageRoot, manifest, [...diff.changed, ...diff.deleted], new Set(diff.deleted));
+                commitPaths.push(...diff.changed);
+                deletePaths.push(...diff.deleted);
+            },
+            afterCommit: () => {
+                if (!addOptions.skipInstall)
+                    installWorkspaceDependencies(root);
+            },
+        });
+        if (noOp) {
+            if (addOptions.json)
+                console.log(JSON.stringify({ operation: 'add', paths: [] }, null, 2));
+            else
+                anhedralPrint.info('All requested modules are already installed.');
+            return;
         }
-        console.log('');
-        anhedralPrint.info('Next commands:');
-        console.log('  pnpm install');
-        console.log('  cp .env.example .env');
-        console.log('  cp Extension/.env.example Extension/.env');
-        console.log('  pnpm db:generate && pnpm db:migrate');
-        console.log('  pnpm verify');
-        console.log('  pnpm dev:backend');
-        console.log('  pnpm dev:frontend');
-        console.log('  pnpm dev:extension');
-        console.log('');
+        if (addOptions.dryRun || !addOptions.json)
+            printPlan('add', planned, addOptions.json);
+        if (!addOptions.dryRun && addOptions.json)
+            printPlan('add', planned, true);
     }
     finally {
-        if (previousToolchain == null) {
+        if (previousChannel == null)
             delete env.ANHEDRAL_TOOLCHAIN;
+        else
+            env.ANHEDRAL_TOOLCHAIN = previousChannel;
+    }
+}
+export function doctorProject() {
+    const root = path.resolve(process.cwd());
+    const filePath = path.join(root, 'anhedral.json');
+    if (!pathEntryExists(filePath))
+        throw new Error('anhedral.json was not found. Run anhedral init first.');
+    const manifest = readManifest(readFileSync(filePath, 'utf8'));
+    const issues = [];
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (!isTransactionMetadata(entry.name))
+            continue;
+        if (entry.name === '.anhedral-journal.json') {
+            issues.push({ path: entry.name, severity: 'error', message: 'An interrupted transaction requires recovery by init or add.' });
+        }
+        else if (entry.name.startsWith('.anhedral-journal.json.tmp-')) {
+            issues.push({ path: entry.name, severity: 'error', message: 'An incomplete transaction journal artifact requires manual inspection.' });
         }
         else {
-            env.ANHEDRAL_TOOLCHAIN = previousToolchain;
+            issues.push({ path: entry.name, severity: 'error', message: 'An Anhedral operation is running or left a transaction-lock artifact.' });
         }
     }
+    if (manifest.generatorVersion !== GENERATOR_VERSION) {
+        issues.push({
+            path: 'anhedral.json',
+            severity: 'error',
+            message: `Project generator ${manifest.generatorVersion} differs from CLI ${GENERATOR_VERSION}; regenerate with the current CLI.`,
+        });
+    }
+    try {
+        assertTemplateProvenance(manifest.modules, manifest.templates);
+    }
+    catch (error) {
+        issues.push({
+            path: 'anhedral.json',
+            severity: 'error',
+            message: error instanceof Error ? error.message : 'Template provenance is invalid.',
+        });
+    }
+    for (const [relativePath, record] of Object.entries(manifest.files)) {
+        const target = path.join(root, relativePath);
+        const targetStat = lstatIfPresent(target);
+        if (!targetStat) {
+            issues.push({ path: relativePath, severity: 'error', message: 'Recorded file is missing.' });
+            continue;
+        }
+        if (targetStat.isSymbolicLink()) {
+            issues.push({ path: relativePath, severity: 'error', message: 'Recorded path is a symbolic link.' });
+            continue;
+        }
+        if (!targetStat.isFile()) {
+            issues.push({ path: relativePath, severity: 'error', message: 'Recorded path is not a regular file.' });
+            continue;
+        }
+        const actual = hashContent(readFileSync(target));
+        if (actual !== record.hash) {
+            issues.push({
+                path: relativePath,
+                severity: record.ownership === 'managed' ? 'error' : 'warning',
+                message: `${record.ownership} file differs from its recorded hash.`,
+            });
+        }
+        if (record.mode !== null) {
+            const actualMode = normalizedFileMode(targetStat.mode);
+            if (actualMode !== null && actualMode !== record.mode) {
+                issues.push({
+                    path: relativePath,
+                    severity: record.ownership === 'managed' ? 'error' : 'warning',
+                    message: `${record.ownership} file mode differs from its recorded mode `
+                        + `(${displayFileMode(record.mode)} expected, ${displayFileMode(actualMode)} found).`,
+                });
+            }
+        }
+    }
+    return {
+        ok: !issues.some((issue) => issue.severity === 'error'),
+        schemaVersion: manifest.schemaVersion,
+        generatorVersion: manifest.generatorVersion,
+        issues,
+    };
 }