primitive-admin 1.1.0-alpha.65 → 1.1.0-alpha.67

package/dist/src/commands/init.js

@@ -1,7 +1,14 @@
-import { confirm, input, select } from "@inquirer/prompts";
-import { appendFileSync, existsSync, readFileSync, writeFileSync } from "fs";
-import { basename, join, resolve } from "path";
-import { CURRENT_CONFIG_VERSION, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, saveProjectConfig, loadProjectConfigFromPath, } from "../lib/project-config.js";
+import { checkbox, confirm, input, select } from "@inquirer/prompts";
+import { appendFileSync, existsSync, readFileSync, readdirSync, writeFileSync, } from "fs";
+import { basename, join, relative, resolve } from "path";
+import { CURRENT_CONFIG_VERSION, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME, PROJECT_CONFIG_DISPLAY_NAME, findProjectRoot, saveProjectConfig, loadProjectConfigFromPath, } from "../lib/project-config.js";
+import { resolveAdoptedEnvironment } from "../lib/init-adopt.js";
+import { CANONICAL_SCHEMA_HEADER, FALLBACK_STARTER_SCHEMA, platformLabel, rootAgentsMarkdown, } from "../lib/init-assets.js";
+import { checkInitGuards, planInit } from "../lib/init-plan.js";
+import { resolveProductionRuntime } from "../lib/init-production-env.js";
+import { checkClientWiring, composeSchemaContent, declaredModelNames, findClientSchema, wireClientToSchema, writeCanonicalSchema, } from "../lib/init-schema.js";
+import { declareSharedProjectConfig } from "../lib/init-xcode.js";
+import { getExplicitEnvName } from "../lib/env-resolver.js";
 import { ApiClient } from "../lib/api-client.js";
 import { browserLogin } from "../lib/auth-flow.js";
 import { loadCredentials, setCurrentApp } from "../lib/config.js";
@@ -9,13 +16,14 @@ import { isProjectMode, seedCredentialsForEnvInProject, } from "../lib/credentia
 import { getCurrentEnvironment, getProjectConfig } from "../lib/env-resolver.js";
 import { normalizeServerUrl } from "../lib/channel.js";
 import { INIT_CONFIG_FILENAME, loadInitConfig, parseInitConfigToml, resolveSkipInstall, resolveUseExistingAppId, validateInitConfig, } from "../lib/init-config.js";
-import { resolvePlatform, } from "../lib/resolve-platform.js";
-import { resolveInitServer, validateServerUrl, } from "../lib/resolve-init-server.js";
+import { parsePlatformList, resolvePlatforms, } from "../lib/resolve-platform.js";
+import { resolveInitServer } from "../lib/resolve-init-server.js";
+import { validateServerUrl } from "../lib/server-url.js";
 import { DEFAULT_DEV_PORT, resolveDevPort, validateDevPort, } from "../lib/resolve-init-dev-port.js";
-import { DEFAULT_SERVER_URL } from "../lib/constants.js";
+import { DEFAULT_SERVER_URL, PRODUCTION_SERVER_URL } from "../lib/constants.js";
 import { divider, error, info, keyValue, success, warn, } from "../lib/output.js";
 import { installCommand, PRIMITIVE_CLI_PACKAGE } from "../lib/package-manager.js";
-import { gitInitialCommit, gitInitRepo, installPnpmGlobally, installPrimitiveCli, isDirectoryEmpty, isPnpmInstalled, isPortFree, isPrimitiveCliInstalled, isXcodeInstalled, iosTemplateUrl, vueTemplateUrl, resolveTemplateBranch, prepareTemplate, runPnpmInstall, runSwiftPackageResolve, updateEnvFile, updateEnvPort, updatePrimitiveJson, updateViteConfig, } from "../lib/template.js";
+import { gitInitialCommit, gitInitRepo, installPnpmGlobally, installPrimitiveCli, isDirectoryEmpty, isPnpmInstalled, isPortFree, isPrimitiveCliInstalled, isXcodeInstalled, iosTemplateUrl, vueTemplateUrl, resolveTemplateBranch, prepareTemplate, runPnpmInstall, runSwiftPackageResolve, updateEnvFile, updateEnvPort, configurePrimitiveJson, updateViteConfig, } from "../lib/template.js";
 /**
  * The .gitignore lines `init` writes for Primitive CLI local state.
  *
@@ -32,54 +40,23 @@ import { gitInitialCommit, gitInitRepo, installPnpmGlobally, installPrimitiveCli
  */
 export const GITIGNORE_LOCAL_STATE_ENTRIES = [
     ".primitive/credentials.json",
+    // This machine's Primitive environment selection (`primitive env use`).
+    // The committed `defaultEnvironment` is the team default; the selection is
+    // per-machine and must never be committable (#2873).
+    ".primitive/local.json",
     ".primitive/sync/**/.primitive-sync.json",
     ".primitive/sync-backups/",
     ".snapshots/",
     "config-snapshots/",
 ];
 /**
- * Writes .primitive/config.json into the project directory and ensures the
- * .gitignore entry for local state exists. Safe to call in a directory that
- * already has a config — in that case we add/update the "dev" environment
- * instead of overwriting the file.
+ * Ensures the project root's .gitignore lists the Primitive CLI's local state.
+ *
+ * Split out of `scaffoldProjectConfig` because a run that ADOPTS an existing
+ * project (#2890) must not rewrite its config, but still has to make sure the
+ * per-machine state a new client's environment produces cannot be committed.
  */
-async function scaffoldProjectConfig(opts) {
-    const configPath = join(opts.targetDir, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
-    let config;
-    if (existsSync(configPath)) {
-        // Respect an existing config: merge in the new dev env if missing.
-        try {
-            config = loadProjectConfigFromPath(configPath);
-        }
-        catch {
-            // Existing file is broken — don't clobber it; just warn and skip.
-            warn(`${PROJECT_CONFIG_DISPLAY_NAME} exists but is invalid. Skipping project config scaffold.`);
-            return;
-        }
-        if (!config.environments.dev) {
-            config.environments.dev = {
-                apiUrl: opts.serverUrl,
-                appId: opts.appId,
-                appName: opts.appName,
-            };
-            if (!config.defaultEnvironment)
-                config.defaultEnvironment = "dev";
-        }
-    }
-    else {
-        config = {
-            version: CURRENT_CONFIG_VERSION,
-            defaultEnvironment: "dev",
-            environments: {
-                dev: {
-                    apiUrl: opts.serverUrl,
-                    appId: opts.appId,
-                    appName: opts.appName,
-                },
-            },
-        };
-    }
-    saveProjectConfig(configPath, config);
+export function ensureGitignoreLocalState(targetDir) {
     // Ensure .primitive/ local state (credentials, per-machine sync state) is
     // gitignored. The config.json itself lives in .primitive/ too, but we
     // gitignore only the sensitive / per-machine artifacts — config.json and
@@ -92,7 +69,7 @@ async function scaffoldProjectConfig(opts) {
     // which incorrectly hid the TOML export tree from `git status`. If we see
     // that legacy entry, replace it with the targeted pattern in-place so
     // users who re-run init pick up the fix.
-    const gitignorePath = join(opts.targetDir, ".gitignore");
+    const gitignorePath = join(targetDir, ".gitignore");
     const LEGACY_SYNC_IGNORE = ".primitive/sync/";
     const gitignoreEntries = [...GITIGNORE_LOCAL_STATE_ENTRIES];
     let linesToAdd = [];
@@ -137,6 +114,51 @@ async function scaffoldProjectConfig(opts) {
             // Non-fatal
         }
     }
+}
+/**
+ * Writes .primitive/config.json into the project directory and ensures the
+ * .gitignore entry for local state exists. Safe to call in a directory that
+ * already has a config — in that case we add/update the "dev" environment
+ * instead of overwriting the file.
+ */
+async function scaffoldProjectConfig(opts) {
+    const configPath = join(opts.targetDir, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+    let config;
+    if (existsSync(configPath)) {
+        // Respect an existing config: merge in the new dev env if missing.
+        try {
+            config = loadProjectConfigFromPath(configPath);
+        }
+        catch {
+            // Existing file is broken — don't clobber it; just warn and skip.
+            warn(`${PROJECT_CONFIG_DISPLAY_NAME} exists but is invalid. Skipping project config scaffold.`);
+            return;
+        }
+        if (!config.environments.dev) {
+            config.environments.dev = {
+                apiUrl: opts.serverUrl,
+                appId: opts.appId,
+                appName: opts.appName,
+            };
+            if (!config.defaultEnvironment)
+                config.defaultEnvironment = "dev";
+        }
+    }
+    else {
+        config = {
+            version: CURRENT_CONFIG_VERSION,
+            defaultEnvironment: "dev",
+            environments: {
+                dev: {
+                    apiUrl: opts.serverUrl,
+                    appId: opts.appId,
+                    appName: opts.appName,
+                },
+            },
+        };
+    }
+    saveProjectConfig(configPath, config);
+    ensureGitignoreLocalState(opts.targetDir);
     success(`Wrote ${PROJECT_CONFIG_DISPLAY_NAME} with dev environment`);
 }
 /**
@@ -257,25 +279,41 @@ export function registerInitCommand(program) {
         .option("-s, --server <url>", "Server URL (default: current CLI server or https://primitiveapi.com)")
         .option("--skip-install", "Skip dependency installation")
         .option("--config <path>", `Path to an init config file for non-interactive setup (default: auto-discover ${INIT_CONFIG_FILENAME} in the current directory)`)
-        .option("-p, --platform <platform>", "Target platform: web or ios (SwiftUI). Omit to be prompted interactively.")
+        .option("-p, --platform <platforms>", "Client platform(s) to scaffold: web, ios (SwiftUI), or both as a comma-separated list (web,ios). Omit to be prompted interactively.")
         .addHelpText("after", `
 Examples:
   $ primitive init my-app                            # Create web app in ./my-app
   $ primitive init                                   # Interactive: prompt for directory and app name
   $ primitive init my-app --platform ios             # Create an iOS (SwiftUI) app
+  $ primitive init my-app --platform web,ios         # One app, a web client and an iOS client
+  $ primitive init ios --platform ios                # Add an iOS client to the app of the surrounding project
   $ primitive init . --use-existing-app-id 01HXY...  # Use existing app in current dir
   $ primitive init my-app --skip-install             # Skip dependency install
   $ primitive init --config .primitive-init.toml     # Non-interactive from config file
 
+One app, several clients:
+  Selecting more than one platform scaffolds them side by side under one project:
+  each client in its own directory (web/, ios/), with .primitive/config.json, the
+  git repository and the shared models/models.toml at the root. Run inside a
+  directory that already has an ancestor .primitive/config.json and init ADDS the
+  client to that app instead: it reuses the selected environment's app, writes no
+  nested .primitive/ or .git/, makes no commit, and leaves the files for you to
+  review and commit in the outer repository.
+
 Non-interactive mode:
   Create a ${INIT_CONFIG_FILENAME} file (or pass --config <path>) to skip all prompts.
   The config file uses TOML format:
 
-    action = "create"          # "create" or "use-existing"
+    action = "create"          # "create", "use-existing", or "add-client"
     app_name = "My App"        # Required for action = "create"
     app_id = "01HXY..."        # Required for action = "use-existing"
     dir = "my-app"             # Project directory (optional)
-    platform = "web"           # "web" or "ios" (optional, defaults to web)
+    platform = "web"           # "web", "ios", "web,ios", or ["web", "ios"]
+                               # (optional, defaults to web)
+    promote_schema = false     # Only with action = "add-client". Consent to move
+                               # an existing single-client repo's models.toml to
+                               # <project root>/models/models.toml so every client
+                               # reads one copy.
     access_mode = "invite-only" # "public", "domain", or "invite-only" (optional)
     dev_port = 5173            # Dev server port (optional). Set it to skip the
                                # port prompt: init pins the port in
@@ -299,22 +337,28 @@ Non-interactive mode:
     overwrite = false           # Overwrite non-empty target directory (optional)
 
 This command will:
-  1. Download the Primitive app template (web or Apple SwiftUI)
-  2. Prompt for an app name and create it on the Primitive server (or use existing)
-  3. Configure the project with your app ID
+  1. Download a Primitive app template for each selected platform (web, Apple SwiftUI)
+  2. Prompt for an app name and create it on the Primitive server (or use existing,
+     or adopt the app of the project it is run inside)
+  3. Configure the project with your app ID and point every client at one model schema
   4. Install dependencies (pnpm for web, swift package resolve for Apple)
 `)
         .action(handleInit);
 }
 async function handleInit(projectDirArg, options) {
     // Validate an explicitly-passed `--platform` flag up front. Only `web` and
-    // `ios` are supported (#1009 removed `macos`). An omitted flag is
-    // `undefined` (the commander default was dropped) and is resolved below.
-    if (options.platform !== undefined &&
-        options.platform !== "web" &&
-        options.platform !== "ios") {
-        error(`Unknown platform "${options.platform}". Supported platforms: web, ios`);
-        process.exit(1);
+    // `ios` are supported (#1009 removed `macos`), and the flag names a LIST —
+    // `--platform web,ios` scaffolds both clients of one app (#2890). An omitted
+    // flag is `undefined` (the commander default was dropped) and is resolved
+    // below.
+    let flagPlatforms;
+    if (options.platform !== undefined) {
+        const parsed = parsePlatformList(options.platform);
+        if (!parsed.ok) {
+            error(parsed.error);
+            process.exit(1);
+        }
+        flagPlatforms = parsed.platforms;
     }
     // `initConfig` is the parsed-and-validated `primitive-init.toml` for
     // non-interactive runs (CI, scripted scaffolding). When non-null, the
@@ -333,23 +377,30 @@ async function handleInit(projectDirArg, options) {
     //   (d) non-TTY, no flag/cfg         -> fall back to web (no hang/crash)
     // The prompt is TTY-guarded inside `resolvePlatform` so a piped/CI stdin
     // never triggers the `@inquirer/prompts` `ERR_USE_AFTER_CLOSE` crash.
-    const platform = await resolvePlatform({
-        flag: options.platform,
-        configPlatform: initConfig?.platform,
+    // The init config's `platform` was validated above, so it parses.
+    const configPlatforms = initConfig?.platform !== undefined
+        ? parsePlatformList(initConfig.platform).platforms
+        : undefined;
+    const platforms = await resolvePlatforms({
+        flag: flagPlatforms,
+        configPlatform: configPlatforms,
         hasConfig: initConfig != null,
         isTTY: Boolean(process.stdin.isTTY),
-        promptFn: () => select({
-            message: "What platform are you building for?",
+        promptFn: () => checkbox({
+            message: "Which clients are you building? (space to select)",
             choices: [
-                { value: "web", name: "web (Vue 3 + TypeScript + Tailwind)" },
+                { value: "web", name: "web (Vue 3 + TypeScript + Tailwind)", checked: true },
                 { value: "ios", name: "ios (Swift + SwiftUI)" },
             ],
-            default: "web",
+            // A run with nothing selected has nothing to scaffold; re-ask rather
+            // than proceeding with an empty list.
+            validate: (choices) => choices.length > 0 ? true : "Select at least one client.",
         }),
     });
-    // iOS shares the SwiftUI template, Xcode toolchain, and primitive.json
-    // config path. (macOS was removed in #1009.)
-    const isApple = platform === "ios";
+    // iOS brings the SwiftUI template, the Xcode toolchain and the
+    // primitive.json config path — whether it is the only client or one of
+    // several. (macOS was removed in #1009.)
+    const isApple = platforms.includes("ios");
     // Apple-family platforms require macOS with Xcode.
     if (isApple && process.platform !== "darwin") {
         error("iOS apps require macOS with Xcode installed.");
@@ -363,14 +414,27 @@ async function handleInit(projectDirArg, options) {
         }
     }
     // Step 1: Determine project directory
+    //
+    // Run from inside an existing Primitive app, one platform goes in a
+    // directory named after itself (`ios/`, `web/`) rather than in a new
+    // project's. That default is also what makes an `add-client` init config
+    // non-interactive without a `dir` key (#2890). A run selecting several
+    // platforms names the directory their subdirectories go under, which has no
+    // obvious default, so it is asked for as before.
     let projectDir = projectDirArg;
     if (!projectDir && initConfig?.dir) {
         projectDir = initConfig.dir;
     }
+    const clientDirDefault = platforms.length === 1 && findProjectRoot(process.cwd()) ? platforms[0] : null;
+    if (!projectDir && clientDirDefault && initConfig) {
+        projectDir = clientDirDefault;
+    }
     if (!projectDir) {
         projectDir = await input({
-            message: "Project name (a new directory will be created):",
-            default: "my-primitive-app",
+            message: clientDirDefault
+                ? "Directory for the new client:"
+                : "Project name (a new directory will be created):",
+            default: clientDirDefault ?? "my-primitive-app",
             validate: (value) => {
                 if (!value.trim())
                     return "Project name cannot be empty";
@@ -381,19 +445,53 @@ async function handleInit(projectDirArg, options) {
     const targetDir = resolve(process.cwd(), projectDir);
     // Used as the default app name suggestion when prompting
     const defaultAppName = projectDir === "." ? basename(targetDir) : basename(projectDir);
-    // Step 2: Check if directory exists and is non-empty
-    if (existsSync(targetDir) && !isDirectoryEmpty(targetDir)) {
+    // ── Which layout is this run producing? (#2890) ────────────────────────
+    //
+    // A `.primitive/config.json` in an ANCESTOR of the target means this app
+    // already exists and this run adds a client to it. Passing the ancestor only
+    // when it differs from the target keeps `primitive init .` at a project root
+    // on its existing merge behavior.
+    const ancestorRoot = findProjectRoot(targetDir);
+    const adoptedRoot = ancestorRoot && resolve(ancestorRoot) !== resolve(targetDir) ? ancestorRoot : null;
+    const plan = planInit({
+        platforms,
+        targetDir,
+        ancestorProjectRoot: adoptedRoot,
+    });
+    // The adopted app's identity comes from the project config's selected
+    // environment — never from a flag or a prompt.
+    let adopted = null;
+    if (adoptedRoot) {
+        try {
+            adopted = resolveAdoptedEnvironment(adoptedRoot, {
+                explicitEnvName: getExplicitEnvName(),
+                envVarName: process.env.PRIMITIVE_ENV || null,
+            });
+        }
+        catch (err) {
+            error(`Could not read the Primitive project at ${adoptedRoot}: ${err.message}`);
+            warn("No project files were written.");
+            process.exit(1);
+        }
+    }
+    // Step 2: Check if the target — and each client directory under it — exists
+    // and is non-empty. Each directory follows the same overwrite contract.
+    const directoriesToGuard = [targetDir, ...plan.clients.map((c) => c.dir)].filter((dir, index, all) => all.indexOf(dir) === index);
+    for (const dir of directoriesToGuard) {
+        if (!existsSync(dir) || isDirectoryEmpty(dir))
+            continue;
+        const label = dir === targetDir ? projectDir : relative(process.cwd(), dir);
         if (initConfig) {
             // Non-interactive: require explicit overwrite opt-in
             if (!initConfig.overwrite) {
-                error(`Directory "${projectDir}" already exists and is not empty.`);
+                error(`Directory "${label}" already exists and is not empty.`);
                 error('Set overwrite = true in your config file to allow overwriting.');
                 process.exit(1);
             }
-            warn(`Directory "${projectDir}" already exists and is not empty. Overwriting (overwrite = true in config).`);
+            warn(`Directory "${label}" already exists and is not empty. Overwriting (overwrite = true in config).`);
         }
         else {
-            warn(`Directory "${projectDir}" already exists and is not empty.`);
+            warn(`Directory "${label}" already exists and is not empty.`);
             const overwrite = await confirm({
                 message: "Do you want to overwrite the existing contents?",
                 default: false,
@@ -426,14 +524,21 @@ async function handleInit(projectDirArg, options) {
     // config's server and then send every later call to the environment's own
     // `apiUrl`.
     const currentEnvironment = getCurrentEnvironment();
-    const currentServer = existingCredentials?.serverUrl ?? currentEnvironment?.config.apiUrl;
+    // When adopting, the app already lives somewhere: the environment being
+    // adopted fixes the server, and a `--server` that disagrees is a mistake
+    // rather than a choice.
+    const currentServer = adopted
+        ? adopted.config.apiUrl
+        : existingCredentials?.serverUrl ?? currentEnvironment?.config.apiUrl;
     const resolvedServer = await resolveInitServer({
         flagServer: options.server,
         configServer: initConfig?.server,
         hasConfig: initConfig != null,
         currentServer,
         defaultServer: DEFAULT_SERVER_URL,
-        isTTY: Boolean(process.stdin.isTTY),
+        // An adopt run has nowhere else to put the client: the environment it is
+        // adopting names the server, so there is nothing to ask about.
+        isTTY: Boolean(process.stdin.isTTY) && plan.mode !== "add-client",
         promptFn: async () => {
             // Only reached when a current server exists (see resolveInitServer).
             const current = currentServer ?? DEFAULT_SERVER_URL;
@@ -481,7 +586,7 @@ async function handleInit(projectDirArg, options) {
     //
     // In legacy mode an interactive run can still log in to the requested server
     // and have it stored correctly, so it goes through the login flow below.
-    const inProjectMode = isProjectMode();
+    const inProjectMode = isProjectMode() || plan.mode === "add-client";
     if (serverChanged && (initConfig || inProjectMode)) {
         const requestedBy = resolvedServer.source === "flag"
             ? "--server"
@@ -493,7 +598,7 @@ async function handleInit(projectDirArg, options) {
         // isn't told they're "logged in to" a server they never logged in to.
         const currentDescription = existingCredentials
             ? `the CLI is logged in to ${currentServer}`
-            : `this project's "${currentEnvironment?.name}" environment targets ${currentServer}`;
+            : `this project's "${adopted?.name ?? currentEnvironment?.name}" environment targets ${currentServer}`;
         error(`Not logged in to ${serverUrl}.`);
         error(`${requestedBy} requests ${serverUrl}, but ${currentDescription}.`);
         // The remedy differs by mode: `primitive login` resolves its target
@@ -537,46 +642,106 @@ async function handleInit(projectDirArg, options) {
         warn("No project files were written.");
         process.exit(1);
     }
+    // Everything this run must be refused for, before a download or a write.
+    const guardError = checkInitGuards({
+        action: initConfig?.action,
+        hasConfig: initConfig != null,
+        ancestorProjectRoot: adoptedRoot,
+        configAppId: initConfig?.app_id,
+        flagAppId: options.useExistingAppId,
+        environmentAppId: adopted?.config.appId,
+        environmentName: adopted?.name,
+    });
+    if (guardError) {
+        error(guardError);
+        warn("No project files were written.");
+        process.exit(1);
+    }
+    if (plan.mode === "add-client") {
+        info(`Found an existing Primitive project at ${adoptedRoot} (environment "${adopted.name}").`);
+        // A run driven by a config already said what it wants; anything else asks,
+        // and a piped stdin gets the key that says it non-interactively rather than
+        // `confirmPrompt`'s `--yes` remedy, which init has no flag for.
+        if (!initConfig) {
+            if (!process.stdin.isTTY) {
+                error(`Adding a client to the project at ${adoptedRoot} needs a confirmation, and stdin is not interactive.`);
+                error(`Re-run with an init config containing \`action = "add-client"\` to confirm non-interactively.`);
+                warn("No project files were written.");
+                process.exit(1);
+            }
+            const proceed = await confirm({
+                message: `Add this client to app ${adopted.config.appName ?? adopted.config.appId} in ${adoptedRoot}?`,
+                default: true,
+            });
+            if (!proceed) {
+                error("Aborted. No project files were written.");
+                process.exit(1);
+            }
+        }
+    }
+    // ── The one schema (#2890) ─────────────────────────────────────────────
+    //
+    // Decided here, before anything is downloaded or written, because the answer
+    // can be "stop": an adopted repository whose client keeps its schema
+    // somewhere this run does not recognize, or one whose owner declines the
+    // move, must end with nothing changed.
+    const schemaPlan = plan.canonicalSchemaPath
+        ? await resolveSchemaComposition({
+            plan,
+            promoteConsent: initConfig?.promote_schema === true,
+            interactive: initConfig == null && Boolean(process.stdin.isTTY),
+            nonInteractive: initConfig != null,
+        })
+        : null;
     // Step 4: Check authentication (credentials were loaded for the server
     // resolution above — reuse them rather than re-reading the file).
     let credentials = existingCredentials;
     let appId;
     let appName;
-    let preparedTemplate = null;
+    const preparedTemplates = new Map();
     const cleanupPreparedTemplate = () => {
-        try {
-            preparedTemplate?.cleanup();
-        }
-        catch {
-            // Non-fatal cleanup best effort
+        for (const prepared of preparedTemplates.values()) {
+            try {
+                prepared.cleanup();
+            }
+            catch {
+                // Non-fatal cleanup best effort
+            }
         }
-        preparedTemplate = null;
+        preparedTemplates.clear();
     };
     const prepareTemplateOrExit = async () => {
-        if (preparedTemplate)
-            return;
-        // Download and validate the archive before app creation, but keep it staged
-        // in a temp directory. That avoids both failure modes: app-creation failure
-        // leaves no scaffold, and template-download failure leaves no orphaned app.
-        info(`Preparing your ${platform === "ios" ? "iOS" : "web"} project template...`);
-        // The branch is the channel (issue #1934): scaffolding against the alpha
-        // server pulls the alpha template branch, whose Primitive deps pin the
-        // alpha prerelease libraries. Falls back to main (with a warning) if the
-        // channel branch isn't available.
-        const templateBranch = resolveTemplateBranch(serverUrl);
-        const templateUrlFor = isApple ? iosTemplateUrl : vueTemplateUrl;
-        try {
-            preparedTemplate = await prepareTemplate({
-                templateUrl: templateUrlFor(templateBranch),
-                fallbackTemplateUrl: templateBranch !== "main" ? templateUrlFor("main") : undefined,
-                onFallback: (reason) => warn(`Template branch "${templateBranch}" unavailable (${reason}) — falling back to main.`),
-                onProgress: info,
-            });
-        }
-        catch (err) {
-            error(`Failed to download template: ${err.message}`);
-            error("Check your internet connection and try again.");
-            process.exit(1);
+        // EVERY selected template downloads and validates before the app is
+        // created, and none of them touches the target directory yet. That keeps
+        // both failure modes covered with several clients in play: app-creation
+        // failure leaves no scaffold, and a download failure — of either template —
+        // leaves no orphaned app and nothing half-written (#1218, #2890).
+        for (const client of plan.clients) {
+            if (preparedTemplates.has(client.platform))
+                continue;
+            info(`Preparing your ${platformLabel(client.platform)} project template...`);
+            // The branch is the channel (issue #1934): scaffolding against the alpha
+            // server pulls the alpha template branch, whose Primitive deps pin the
+            // alpha prerelease libraries. Falls back to main (with a warning) if the
+            // channel branch isn't available.
+            const templateBranch = resolveTemplateBranch(serverUrl);
+            const templateUrlFor = client.platform === "ios" ? iosTemplateUrl : vueTemplateUrl;
+            try {
+                preparedTemplates.set(client.platform, await prepareTemplate({
+                    templateUrl: templateUrlFor(templateBranch),
+                    fallbackTemplateUrl: templateBranch !== "main" ? templateUrlFor("main") : undefined,
+                    onFallback: (reason) => warn(`Template branch "${templateBranch}" unavailable (${reason}) — falling back to main.`),
+                    onProgress: info,
+                }));
+            }
+            catch (err) {
+                error(`Failed to download template: ${err.message}`);
+                error("Check your internet connection and try again.");
+                // A template that already downloaded must not survive as a temp
+                // directory when the run stops here.
+                cleanupPreparedTemplate();
+                process.exit(1);
+            }
         }
     };
     // An existing app can be selected two ways: the `--use-existing-app-id` flag,
@@ -585,7 +750,49 @@ async function handleInit(projectDirArg, options) {
     // the create branch and prompt for an app name — hanging non-interactive
     // runs. (#1217)
     const useExistingAppId = resolveUseExistingAppId(options.useExistingAppId, initConfig);
-    if (useExistingAppId) {
+    if (plan.mode === "add-client") {
+        // ── Adopt: the app is the one this project already targets ──────────
+        //
+        // `appName` is OPTIONAL in a valid environment, so it is resolved rather
+        // than assumed: the environment's name, else the app's name from the API
+        // when we are authenticated, else the client directory's own name. No
+        // downstream writer ever receives an undefined display name, and no
+        // scaffold ships an unresolved placeholder.
+        appId = adopted.config.appId;
+        appName = adopted.config.appName ?? "";
+        // Credentials are resolved from the working directory, while the app comes
+        // from the project the TARGET sits in — a target inside a different project
+        // (or a run from outside any) can leave the CLI holding another server's
+        // token, and every API call here would go there with this app's id. The
+        // run continues unauthenticated instead: nothing it writes needs the API.
+        const credentialServer = credentials ? normalizeServerUrl(credentials.serverUrl) : null;
+        if (credentialServer && credentialServer !== normalizeServerUrl(adopted.config.apiUrl)) {
+            warn(`The CLI is logged in to ${credentials.serverUrl}, but the "${adopted.name}" environment in ${adoptedRoot} targets ${adopted.config.apiUrl}.`);
+            warn(`Continuing without contacting either server. Run init from inside that project, or log in to ${adopted.config.apiUrl}, to have the app verified.`);
+            credentials = null;
+        }
+        else {
+            credentials = await ensureAuthenticated(credentials, serverUrl, serverChanged, {
+                reason: "verify the app",
+                allowSkip: true,
+                nonInteractive: !!initConfig,
+            });
+        }
+        if (!appName && credentials) {
+            try {
+                const client = new ApiClient();
+                appName = (await client.getApp(appId)).name;
+            }
+            catch (err) {
+                warn(`Could not look up the app's name: ${err.message}`);
+            }
+        }
+        if (!appName)
+            appName = basename(plan.clients[0].dir);
+        info(`Adding a ${plan.clients.map((c) => platformLabel(c.platform)).join(" and ")} client to ${appName} (${appId}).`);
+        await prepareTemplateOrExit();
+    }
+    else if (useExistingAppId) {
         // Using existing app ID - verify it exists
         appId = useExistingAppId;
         appName = "(existing app)"; // Default if we can't verify
@@ -786,13 +993,16 @@ async function handleInit(projectDirArg, options) {
             }
         }
     }
-    // Step 3 (deferred): install the already-prepared template + init git, now
-    // that the app exists. The network download and archive validation already
-    // happened before createApp, without touching targetDir.
-    info(`Setting up your ${platform === "ios" ? "iOS" : "web"} project...`);
+    // ── Install every selected template ─────────────────────────────────
+    //
+    // The network download and archive validation already happened above,
+    // without touching any target directory.
     try {
-        preparedTemplate.install(targetDir);
-        success("Template extracted successfully.");
+        for (const client of plan.clients) {
+            info(`Setting up your ${platformLabel(client.platform)} project...`);
+            preparedTemplates.get(client.platform).install(client.dir);
+            success(`${platformLabel(client.platform)} template extracted into ${client.dir}.`);
+        }
     }
     catch (err) {
         error(`Failed to write template files: ${err.message}`);
@@ -802,92 +1012,196 @@ async function handleInit(projectDirArg, options) {
     finally {
         cleanupPreparedTemplate();
     }
-    // Initialize git repository (commit happens later, after env + install)
-    try {
-        await gitInitRepo(targetDir);
-    }
-    catch {
-        // Non-fatal: git may not be installed, or already a git repo
-    }
-    // Step 4.5: Update CLI to point at this app
-    try {
-        setCurrentApp(appId, appName);
-        info(`CLI now using app: ${appName} (${appId})`);
+    // Initialize git repository (commit happens later, after env + install).
+    // An adopted repository already has one, and a nested repository inside it is
+    // exactly what this change stops producing.
+    if (plan.initsGit) {
+        try {
+            await gitInitRepo(plan.projectRoot);
+        }
+        catch {
+            // Non-fatal: git may not be installed, or already a git repo
+        }
     }
-    catch (err) {
-        // Not critical - user may not be logged in (e.g. used --use-existing-app-id without login)
-        warn(`Could not set current app in CLI config: ${err.message}`);
+    // Step 4.5: Update CLI to point at this app. Adopting does not: the app is
+    // already the project's, and the CLI's global selection is not this run's to
+    // move.
+    if (plan.ownsApp) {
+        try {
+            setCurrentApp(appId, appName);
+            info(`CLI now using app: ${appName} (${appId})`);
+        }
+        catch (err) {
+            // Not critical - user may not be logged in (e.g. used --use-existing-app-id without login)
+            warn(`Could not set current app in CLI config: ${err.message}`);
+        }
     }
     // Step 4.6: Scaffold .primitive/config.json with a "dev" environment bound
     // to this app, and seed its credential slot with the session we just
     // authenticated — so `primitive` commands run from inside the project pick
     // up project mode without a second login.
-    try {
-        await scaffoldProjectConfig({ targetDir, appId, appName, serverUrl });
-        if (credentials) {
-            seedCredentialsForEnvInProject(targetDir, "dev", credentials);
+    if (plan.writesProjectConfig) {
+        try {
+            await scaffoldProjectConfig({
+                targetDir: plan.projectRoot,
+                appId,
+                appName,
+                serverUrl,
+            });
+            if (credentials) {
+                seedCredentialsForEnvInProject(plan.projectRoot, "dev", credentials);
+            }
+            success(`Project environment "dev" configured (.primitive/config.json).`);
+        }
+        catch (err) {
+            warn(`Could not scaffold .primitive/config.json: ${err.message}`);
         }
-        success(`Project environment "dev" configured (.primitive/config.json).`);
-    }
-    catch (err) {
-        warn(`Could not scaffold .primitive/config.json: ${err.message}`);
     }
-    // Steps 5-8: Platform-specific configuration and dependency installation
-    if (isApple) {
-        // ── Apple (SwiftUI) path ──────────────────────────────────────────
-        // Step 5: Update primitive.json
-        info("Configuring primitive.json...");
+    else {
+        // Adopting: the config is the project's own. Only make sure the local state
+        // a new client's environment produces stays out of the repository.
         try {
-            const updated = updatePrimitiveJson(targetDir, appId, serverUrl, appName);
-            if (!updated) {
-                warn("No primitive.json file found in template.");
-                warn(`Please manually set appId to "${appId}" in your primitive.json.`);
-            }
-            else {
-                success("primitive.json configured.");
-            }
+            ensureGitignoreLocalState(plan.projectRoot);
         }
         catch (err) {
-            warn(`Could not update primitive.json: ${err.message}`);
-            warn(`Please manually set appId to "${appId}" in your primitive.json.`);
+            warn(`Could not update .gitignore: ${err.message}`);
         }
-        // Step 6-7: Skip port selection and pnpm (not applicable to Apple)
-        // Step 8: Resolve Swift packages
-        if (!skipInstall) {
-            info("Resolving Swift packages (this may take a few minutes)...");
+    }
+    // ── The one model schema (#2890) ────────────────────────────────────
+    if (plan.canonicalSchemaPath && schemaPlan) {
+        composeSchema({ plan, schemaPlan });
+    }
+    // ── The app-wide AGENTS.md ──────────────────────────────────────────
+    if (plan.writesRootAgents) {
+        const agentsPath = join(plan.projectRoot, "AGENTS.md");
+        if (!existsSync(agentsPath)) {
             try {
-                await runSwiftPackageResolve(targetDir);
-                success("Swift packages resolved.");
+                // The clients this run wrote, plus any the repository already had —
+                // adding iOS to a web app describes a repository with two clients.
+                const written = plan.clients.map((client) => ({
+                    platform: client.platform,
+                    dir: relative(plan.projectRoot, client.dir) || ".",
+                }));
+                const clients = [
+                    ...written,
+                    ...discoverExistingClients(plan.projectRoot).filter((existing) => !written.some((client) => client.dir === existing.dir)),
+                ];
+                writeFileSync(agentsPath, rootAgentsMarkdown({ appName, clients }));
+                success("Wrote AGENTS.md describing the app layout.");
             }
             catch (err) {
-                warn(`Swift package resolution failed: ${err.message}`);
-                warn("You can try running 'swift package resolve' manually.");
+                warn(`Could not write AGENTS.md: ${err.message}`);
             }
         }
-        else {
-            info(`Skipping dependency installation (${skipInstallReason}).`);
-        }
     }
-    else {
+    // ── Per-client configuration and dependency installation ────────────
+    //
+    // The production runtime target is derived once from the project's own
+    // environments, so a client built for production talks to a backend the app
+    // id actually exists on (#2890).
+    const production = plan.mode === "standalone"
+        ? undefined
+        : resolveProductionRuntime({
+            environments: (adopted?.projectConfig.environments ??
+                readProjectEnvironments(plan.projectRoot)),
+            selectedServerUrl: serverUrl,
+            selectedAppId: appId,
+            selectedAppName: appName,
+            productionServerUrl: PRODUCTION_SERVER_URL,
+        });
+    for (const client of plan.clients) {
+        if (client.platform === "ios") {
+            // ── Apple (SwiftUI) path ────────────────────────────────────────
+            // The Xcode build phases name the project config as a declared input,
+            // and inside Xcode's script sandbox a phase may read only what it
+            // declared. When the config lives above this client, both the generated
+            // spec and the checked-in .xcodeproj have to say so — otherwise a fresh
+            // clone (primitive.json is gitignored) cannot build in Xcode at all, and
+            // a working copy that has one keeps whichever environment wrote it.
+            if (resolve(client.dir) !== resolve(plan.projectRoot)) {
+                const declared = declareSharedProjectConfig(client.dir, plan.projectRoot);
+                if (declared.length > 0) {
+                    success(`Xcode build phases read ${relative(client.dir, join(plan.projectRoot, ".primitive", "config.json"))}.`);
+                }
+            }
+            // Step 5: Generate primitive.json from the environment.
+            //
+            // In a current template the file is a build product, written by
+            // `scripts/resolve-primitive-config.sh` from `.primitive/config.json`
+            // (#2873) — it walks up to the project root, so a client inside a
+            // composed repository resolves the same one every other command does. A
+            // template that predates the change has no such script and a tracked
+            // primitive.json instead; fill that in the old way.
+            info("Configuring primitive.json...");
+            try {
+                const result = configurePrimitiveJson(client.dir, appId, serverUrl, appName, {
+                    // Adopting resolved an environment of the project's own — the one
+                    // whose app this client is being added to. The script has to be told
+                    // which, or it re-resolves from this machine and can configure the
+                    // client for a different app on a different backend.
+                    environmentName: adopted?.name,
+                });
+                if (result.outcome === "generated") {
+                    success("primitive.json generated from .primitive/config.json.");
+                }
+                else if (result.outcome === "filled") {
+                    success("primitive.json configured.");
+                }
+                else if (result.outcome === "failed") {
+                    warn(`Could not generate primitive.json: ${result.detail}`);
+                    warn("Run 'bash scripts/resolve-primitive-config.sh' in the project to retry.");
+                }
+                else {
+                    // Neither the resolve script nor a template primitive.json — an
+                    // unexpectedly old or trimmed template. The remedy is still never
+                    // "type the app ID somewhere else": it is already in
+                    // .primitive/config.json, which is where every reader looks.
+                    warn("This template has neither scripts/resolve-primitive-config.sh nor a primitive.json.");
+                    warn(`The project config holds the app ID; update the template to generate primitive.json from it.`);
+                }
+            }
+            catch (err) {
+                warn(`Could not configure primitive.json: ${err.message}`);
+                warn("Run 'bash scripts/resolve-primitive-config.sh' in the project to retry.");
+            }
+            // Step 6-7: Skip port selection and pnpm (not applicable to Apple)
+            // Step 8: Resolve Swift packages
+            if (!skipInstall) {
+                info("Resolving Swift packages (this may take a few minutes)...");
+                try {
+                    await runSwiftPackageResolve(client.dir);
+                    success("Swift packages resolved.");
+                }
+                catch (err) {
+                    warn(`Swift package resolution failed: ${err.message}`);
+                    warn("You can try running 'swift package resolve' manually.");
+                }
+            }
+            else {
+                info(`Skipping dependency installation (${skipInstallReason}).`);
+            }
+            continue;
+        }
         // ── Web path ──────────────────────────────────────────────────────
-        // Step 5: Update .env file
+        // Step 5: Fill in an OLD template's .env identity keys.
+        //
+        // A current template does not author them at all — `primitiveEnv()` reads
+        // `.primitive/config.json`, which it finds by walking up — so "no keys to
+        // replace" is the expected outcome, not a problem (#2873). The fill-in
+        // survives only so a new CLI still produces a working scaffold from a
+        // template that predates the change.
         info("Configuring environment...");
         try {
-            const envResult = updateEnvFile(targetDir, appId, serverUrl, appName);
+            const envResult = updateEnvFile(client.dir, appId, serverUrl, appName, production);
             if (!envResult.envUpdated) {
-                warn("No .env or .env.example file found in template.");
-                warn(`Please manually set VITE_APP_ID=${appId} in your .env file.`);
-            }
-            else if (!envResult.envProductionUpdated) {
-                info(".env configured. No .env.production file found (this is optional).");
+                info("No .env file in this template — identity comes from .primitive/config.json.");
             }
             else {
-                success("Environment configured (.env and .env.production).");
+                success("Environment configured.");
             }
         }
         catch (err) {
             warn(`Could not update .env file: ${err.message}`);
-            warn(`Please manually set VITE_APP_ID=${appId} in your .env file.`);
         }
         // Step 6: Determine the dev port. Default to 5173; warn about taken ports
         // when prompting. The init config's `dev_port` decides it non-interactively
@@ -932,28 +1246,32 @@ async function handleInit(projectDirArg, options) {
                 // Pin the port in vite.config.ts and update .env. A vite config whose
                 // shape we can't patch must be said out loud — otherwise the dev
                 // server keeps 5173 while .env and the redirect URIs point elsewhere.
-                const viteUpdated = updateViteConfig(targetDir, chosenPort);
+                const viteUpdated = updateViteConfig(client.dir, chosenPort);
                 if (!viteUpdated) {
                     warn(`Could not pin port ${chosenPort} in vite.config.ts — set \`server.port\` there manually.`);
                 }
-                updateEnvPort(targetDir, chosenPort);
+                updateEnvPort(client.dir, chosenPort);
                 // Update app settings: CORS, redirect URIs, baseUrl
                 if (!credentials) {
                     info(`Local files updated. Skipping server CORS/redirect config — not authenticated.`);
                 }
                 else {
                     try {
-                        const client = new ApiClient();
+                        const apiClient = new ApiClient();
                         let existingOrigins = [];
-                        let existingRedirectUris = [];
+                        let existingEmailRedirectUris = [];
+                        let existingGoogleClients = null;
                         try {
-                            const currentSettings = await client.getAppSettings(appId);
+                            const currentSettings = await apiClient.getAppSettings(appId);
                             if (currentSettings.corsMode === "custom" &&
                                 Array.isArray(currentSettings.corsAllowedOrigins)) {
                                 existingOrigins = currentSettings.corsAllowedOrigins;
                             }
-                            if (Array.isArray(currentSettings.redirectUris)) {
-                                existingRedirectUris = currentSettings.redirectUris;
+                            if (Array.isArray(currentSettings.emailRedirectUris)) {
+                                existingEmailRedirectUris = currentSettings.emailRedirectUris;
+                            }
+                            if (currentSettings.googleClients) {
+                                existingGoogleClients = currentSettings.googleClients;
                             }
                         }
                         catch {
@@ -961,18 +1279,45 @@ async function handleInit(projectDirArg, options) {
                         }
                         // Always include 5173 since it's the universal localhost default
                         const corsOrigins = Array.from(new Set([...existingOrigins, defaultOrigin, devOrigin]));
-                        const redirectUris = Array.from(new Set([
-                            ...existingRedirectUris,
+                        // MERGED into the creation-time seed, never replacing it (#2891):
+                        // `emailRedirectUris` matching is fail-closed, so blindly writing
+                        // only this port's callback would break every other environment the
+                        // app already serves.
+                        const emailRedirectUris = Array.from(new Set([
+                            ...existingEmailRedirectUris,
                             `${defaultOrigin}/oauth/callback`,
                             `${devOrigin}/oauth/callback`,
                         ]));
-                        await client.updateAppSettings(appId, {
+                        const settingsUpdate = {
                             corsMode: "custom",
                             corsAllowedOrigins: corsOrigins,
                             corsAllowCredentials: true,
-                            redirectUris,
+                            emailRedirectUris,
                             baseUrl: devOrigin,
-                        });
+                        };
+                        // A Google web client redirects to this dev origin too, so its own
+                        // `redirectUris` needs the callback. A PUT replaces the WHOLE map,
+                        // so the complete map is sent back — an entry for a platform this
+                        // scaffold does not touch (ios, desktop, …) would otherwise be
+                        // deleted as a side effect of choosing a dev port.
+                        const webEntry = existingGoogleClients?.clients?.web;
+                        if (webEntry) {
+                            settingsUpdate.googleClients = {
+                                ...existingGoogleClients,
+                                clients: {
+                                    ...existingGoogleClients.clients,
+                                    web: {
+                                        ...webEntry,
+                                        redirectUris: Array.from(new Set([
+                                            ...(webEntry.redirectUris ?? []),
+                                            `${defaultOrigin}/oauth/callback`,
+                                            `${devOrigin}/oauth/callback`,
+                                        ])),
+                                    },
+                                },
+                            };
+                        }
+                        await apiClient.updateAppSettings(appId, settingsUpdate);
                         success(`Dev port set to ${chosenPort}: ${viteUpdated ? "vite.config.ts, " : ""}.env, CORS, redirect URIs, and base URL updated.`);
                     }
                     catch (err) {
@@ -987,15 +1332,26 @@ async function handleInit(projectDirArg, options) {
             warn(`Could not configure the dev server port: ${err.message}`);
             warn("The project keeps the default port 5173.");
         }
-        // Step 7: Check if pnpm is installed globally, offer to install if not
+        // Step 7: Check if pnpm is installed globally, offer to install if not.
+        //
+        // An offer, so only where there is someone to ask: a config-driven run
+        // answers no questions, and a piped stdin has no answer to give. Either way
+        // the install below still runs pnpm through npx, so the client gets its
+        // dependencies — this is about the machine, not about this project.
         const pnpmInstalled = await isPnpmInstalled();
         if (!pnpmInstalled) {
             console.log();
             info("pnpm is not installed globally on your system.");
-            const installPnpm = await confirm({
-                message: "Install pnpm globally? (recommended for future use)",
-                default: true,
-            });
+            const canAsk = initConfig == null && Boolean(process.stdin.isTTY);
+            const installPnpm = canAsk
+                ? await confirm({
+                    message: "Install pnpm globally? (recommended for future use)",
+                    default: true,
+                })
+                : false;
+            if (!canAsk) {
+                info("Using npx to run pnpm. Install it globally later with: npm install -g pnpm");
+            }
             if (installPnpm) {
                 info("Installing pnpm...");
                 try {
@@ -1012,7 +1368,7 @@ async function handleInit(projectDirArg, options) {
         if (!skipInstall) {
             info("Installing dependencies...");
             try {
-                await runPnpmInstall(targetDir);
+                await runPnpmInstall(client.dir);
                 success("Dependencies installed.");
             }
             catch (err) {
@@ -1085,39 +1441,275 @@ async function handleInit(projectDirArg, options) {
     catch {
         // Non-fatal: skill installation should never block init
     }
-    // Step 11: Create initial git commit (captures env config + installed dependencies)
-    try {
-        await gitInitialCommit(targetDir);
-    }
-    catch {
-        // Non-fatal: git may not be installed, or already committed
+    // Step 11: Create initial git commit (captures env config + installed
+    // dependencies). Not when adopting: the surrounding repository owns its
+    // history, and the new files are the user's to review and commit.
+    if (plan.initsGit) {
+        try {
+            await gitInitialCommit(plan.projectRoot);
+        }
+        catch {
+            // Non-fatal: git may not be installed, or already committed
+        }
     }
     // Step 12: Show success message
     divider();
-    success("Project initialized successfully!");
+    success(plan.mode === "add-client"
+        ? "Client added successfully!"
+        : "Project initialized successfully!");
     divider();
-    keyValue("Directory", targetDir);
+    keyValue("Project", plan.projectRoot);
     keyValue("App Name", appName);
     keyValue("App ID", appId);
-    keyValue("Platform", platform === "ios" ? "iOS (SwiftUI)" : "Web");
+    for (const client of plan.clients) {
+        keyValue(platformLabel(client.platform), client.dir);
+    }
+    if (plan.canonicalSchemaPath) {
+        keyValue("Model schema", plan.canonicalSchemaPath);
+    }
     divider();
+    if (plan.mode === "add-client") {
+        info(`No .primitive/ and no .git/ were created inside the new client — this app has one of each, at ${plan.projectRoot}.`);
+        info(`The new files are uncommitted: review them with \`git status\` in ${plan.projectRoot} and commit when you are happy.`);
+        divider();
+    }
     info("Next steps:");
-    if (projectDir !== ".") {
-        console.log(`  cd ${projectDir}`);
+    for (const client of plan.clients) {
+        const relativeDir = relative(process.cwd(), client.dir);
+        // A target outside the working directory reads better as its own path than
+        // as a chain of `../`.
+        const where = relativeDir.startsWith("..") ? client.dir : relativeDir || ".";
+        if (where !== ".")
+            console.log(`  cd ${where}`);
+        if (client.platform === "ios") {
+            if (skipInstall)
+                console.log("  swift package resolve");
+            // The Xcode project lists its sources explicitly, and the shared schema
+            // brings models the checked-in project does not compile yet — so the
+            // first build regenerates. `run-ios.sh` runs codegen and xcodegen in that
+            // order; a build straight from Xcode before that stops and says so.
+            if (resolve(client.dir) !== resolve(plan.projectRoot)) {
+                console.log("  ./run-ios.sh    # codegen + xcodegen, then the Simulator");
+                console.log("  # then: open *.xcodeproj");
+            }
+            else {
+                console.log("  open *.xcodeproj");
+                console.log("  # or: ./run-ios.sh (iOS Simulator)");
+            }
+        }
+        else {
+            if (skipInstall)
+                console.log("  pnpm install");
+            console.log("  pnpm dev");
+        }
     }
-    if (isApple) {
-        if (skipInstall) {
-            console.log("  swift package resolve");
+    console.log();
+}
+/** Where a project root's environments live, for the production derivation. */
+function readProjectEnvironments(projectRoot) {
+    const configPath = join(projectRoot, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        return loadProjectConfigFromPath(configPath).environments;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The clients a repository already has, for the app-wide `AGENTS.md`.
+ *
+ * A run that adds a client to an existing app knows only about the one it is
+ * writing, and a layout description that names one client of two describes the
+ * repository wrongly to the next agent that reads it. The signals are the ones
+ * the templates ship — a Swift package or Xcode project, a Vite project — so a
+ * `functions/` directory with a `package.json` is not mistaken for a client.
+ */
+function discoverExistingClients(projectRoot) {
+    let entries;
+    try {
+        entries = readdirSync(projectRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.startsWith("."))
+            continue;
+        const dir = join(projectRoot, entry.name);
+        const hasXcodeProject = (() => {
+            try {
+                return readdirSync(dir).some((name) => name.endsWith(".xcodeproj"));
+            }
+            catch {
+                return false;
+            }
+        })();
+        if (existsSync(join(dir, "Package.swift")) || hasXcodeProject) {
+            found.push({ platform: "ios", dir: entry.name });
+        }
+        else if (existsSync(join(dir, "package.json")) &&
+            existsSync(join(dir, "vite.config.ts"))) {
+            found.push({ platform: "web", dir: entry.name });
+        }
+    }
+    return found;
+}
+/**
+ * Decides how this run gets to ONE schema — before anything is downloaded or
+ * written, because the answer can be "stop".
+ */
+async function resolveSchemaComposition(input) {
+    const schemaPath = input.plan.canonicalSchemaPath;
+    if (existsSync(schemaPath))
+        return { alreadyPresent: true };
+    // A fresh composition seeds the shared schema from the clients it is about
+    // to scaffold; there is nothing to move and nobody to ask.
+    if (input.plan.mode !== "add-client")
+        return { alreadyPresent: false };
+    const root = input.plan.projectRoot;
+    const existing = ["web", "ios"]
+        .map((platform) => ({ platform, schemaPath: findClientSchema(root, platform) }))
+        .find((candidate) => candidate.schemaPath !== null);
+    if (existing) {
+        // The flat single-client layout `primitive init` still produces: the client
+        // IS the repository root, and its schema has to become the app's.
+        const from = relative(root, existing.schemaPath);
+        // Moving the schema is only half of it — what reads the schema has to be
+        // able to name the new location. A client that cannot be rewired would keep
+        // its own copy beside the app's, which is the drift the one schema exists
+        // to prevent, so the run stops here: before the download, before the move,
+        // with the repository exactly as it was.
+        const blocked = checkClientWiring(root, existing.platform, schemaPath);
+        if (blocked) {
+            error(`The ${platformLabel(existing.platform)} client at ${root} cannot be pointed at ${relative(root, schemaPath)}: ${blocked}.`);
+            error(`Every client of an app reads one schema, so ${from} stays where it is. Restore that file to its template shape, or move the schema and rewire the client by hand, then re-run this command.`);
+            warn("No project files were written.");
+            process.exit(1);
+        }
+        info(`This repository's model schema is at ${from}. Adding a second client means moving it to models/models.toml so both clients read one copy.`);
+        if (!input.promoteConsent) {
+            if (!input.interactive) {
+                error(`Adding a client needs the schema at models/models.toml, and moving ${from} there needs your consent.`);
+                error(input.nonInteractive
+                    ? 'Set `promote_schema = true` alongside `action = "add-client"` in the init config to allow the move.'
+                    : "Re-run from an interactive terminal, or with an init config setting `promote_schema = true`, to allow the move.");
+                warn("No project files were written.");
+                process.exit(1);
+            }
+            const proceed = await confirm({
+                message: `Move ${from} to models/models.toml and point both clients at it?`,
+                default: true,
+            });
+            if (!proceed) {
+                error("Aborted. No project files were written.");
+                process.exit(1);
+            }
+        }
+        return {
+            alreadyPresent: false,
+            promoteFrom: { dir: root, platform: existing.platform, schemaPath: existing.schemaPath },
+        };
+    }
+    // A root that looks like a client but keeps its schema somewhere neither
+    // template does: say exactly what to do, and write nothing.
+    const looksLikeClient = existsSync(join(root, "package.json")) || existsSync(join(root, "Package.swift"));
+    if (looksLikeClient) {
+        error(`The project at ${root} has a client, but no model schema where either template keeps one (src/models/models.toml, or Sources/<App>/Models/models.toml).`);
+        error(`Move that client's schema to ${root}/models/models.toml and point its codegen at it, then re-run this command.`);
+        warn("No project files were written.");
+        process.exit(1);
+    }
+    return { alreadyPresent: false };
+}
+/**
+ * Writes the app's one schema and points every client at it.
+ *
+ * The promoted file and the new wiring are written BEFORE the old client-local
+ * copy goes away, so an interrupted promotion leaves a client with a schema
+ * rather than one with neither.
+ */
+function composeSchema(input) {
+    const { plan, schemaPlan } = input;
+    const schemaPath = plan.canonicalSchemaPath;
+    const reportAddedModels = (added) => {
+        if (added.length === 0)
+            return;
+        info(`Added ${added.map((model) => `\`${model}\``).join(", ")} to ${relative(plan.projectRoot, schemaPath)} — the models the added client's own code reads. Models the app already declares are untouched.`);
+    };
+    const clientsToWire = [
+        ...(schemaPlan.promoteFrom
+            ? [{ platform: schemaPlan.promoteFrom.platform, dir: schemaPlan.promoteFrom.dir }]
+            : []),
+        ...plan.clients,
+    ];
+    // Asked of every client before the shared schema exists. A client that cannot
+    // be pointed at it keeps its own copy — so writing the shared one anyway, and
+    // wiring whichever clients did work, would leave the app with two schemas and
+    // the run reporting success. One schema, or none: the existing client's
+    // shape was already checked before the download, so this catches an installed
+    // template whose wiring this CLI no longer recognizes.
+    const unreachable = clientsToWire
+        .map((client) => ({
+        client,
+        reason: checkClientWiring(client.dir, client.platform, schemaPath),
+    }))
+        .filter((checked) => checked.reason !== null);
+    if (unreachable.length > 0) {
+        for (const { client, reason } of unreachable) {
+            error(`The ${platformLabel(client.platform)} client at ${client.dir} cannot be pointed at ${schemaPath}: ${reason}.`);
+        }
+        error("Every client of an app reads one model schema, so nothing was moved and no client was rewired.");
+        warn(`The templates this run installed are still in place; remove them and re-run, or point each client at ${schemaPath} by hand.`);
+        process.exit(1);
+    }
+    // Every client this run installs ships a starter schema AND code generated
+    // from it — the web template's store reads `UserPref`, and its generator
+    // refuses a schema with no models at all. So the app's schema has to declare
+    // what each client reads, whether it is being written now or was already
+    // there: a promoted comment-only Swift starter would otherwise hand a new web
+    // client a schema it cannot generate from, and the run would report success.
+    const starters = plan.clients
+        .map((client) => findClientSchema(client.dir, client.platform))
+        .filter((found) => found !== null)
+        .map((found) => readFileSync(found, "utf-8"));
+    if (!schemaPlan.alreadyPresent) {
+        // The base is the promoted client's schema when one is being promoted —
+        // its models are the app's — else the richest starter this run installs.
+        const base = (schemaPlan.promoteFrom
+            ? readFileSync(schemaPlan.promoteFrom.schemaPath, "utf-8")
+            : starters.find((starter) => declaredModelNames(starter).length > 0)) ??
+            starters[0] ??
+            FALLBACK_STARTER_SCHEMA;
+        const composed = composeSchemaContent({ base, starters });
+        if (writeCanonicalSchema(schemaPath, `${CANONICAL_SCHEMA_HEADER}\n${composed.content}`)) {
+            success(`Wrote ${relative(plan.projectRoot, schemaPath)} — the app's one model schema.`);
+            reportAddedModels(schemaPlan.promoteFrom ? composed.added : []);
         }
-        console.log("  open *.xcodeproj");
-        console.log("  # or: ./run-ios.sh (iOS Simulator)");
     }
     else {
-        if (skipInstall) {
-            console.log("  pnpm install");
+        const composed = composeSchemaContent({
+            base: readFileSync(schemaPath, "utf-8"),
+            starters,
+        });
+        if (composed.added.length > 0) {
+            writeFileSync(schemaPath, composed.content);
+            reportAddedModels(composed.added);
         }
-        console.log("  pnpm dev");
     }
-    console.log();
+    for (const client of clientsToWire) {
+        const result = wireClientToSchema(client.dir, client.platform, schemaPath);
+        if (result.error) {
+            // The check above said this client could be wired, so an error here is
+            // the filesystem changing under the run — still not something to finish
+            // on top of, because it is a client reading a schema of its own.
+            error(`Could not point the ${platformLabel(client.platform)} client at the shared schema: ${result.error}.`);
+            error(`Point it at ${schemaPath} before using this repository.`);
+            process.exit(1);
+        }
+        success(`${platformLabel(client.platform)} client reads ${relative(client.dir, schemaPath)}.`);
+    }
 }
 //# sourceMappingURL=init.js.map