primitive-admin 1.0.61 → 1.0.63

package/dist/src/commands/init.js

@@ -1,15 +1,32 @@
-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 { deriveCallbackScheme, linkOptInGuidance, missingUrlTypeGuidance, stampCallbackScheme, universalLinkGuidance, } from "../lib/init-ios-links.js";
+import { appHasBothPlatforms, detectClientPlatform, discoverClientPlatforms, } from "../lib/init-client-platforms.js";
+import { planEmailRedirectUriMerge } from "../lib/init-email-redirect-uris.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";
-import { INIT_CONFIG_FILENAME, loadInitConfig, parseInitConfigToml, resolveUseExistingAppId, validateInitConfig, } from "../lib/init-config.js";
-import { resolvePlatform, } from "../lib/resolve-platform.js";
+import { isProjectMode, seedCredentialsForEnvInProject, } from "../lib/credentials-store.js";
+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 { 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, PRODUCTION_SERVER_URL } from "../lib/constants.js";
 import { divider, error, info, keyValue, success, warn, } from "../lib/output.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";
-const DEFAULT_SERVER_URL = process.env.PRIMITIVE_SERVER_URL || "https://primitiveapi.com";
+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, configurePrimitiveJson, updateViteConfig, } from "../lib/template.js";
 /**
  * The .gitignore lines `init` writes for Primitive CLI local state.
  *
@@ -24,56 +41,94 @@ const DEFAULT_SERVER_URL = process.env.PRIMITIVE_SERVER_URL || "https://primitiv
  * the restored `.primitive-sync.json` baseline — can never surface as untracked
  * files in a tracked custom config dir.
  */
+/**
+ * The origin a local dev server is served from. ONE spelling: the app's CORS
+ * origins, its `emailRedirectUris` seed and the environment's `webUrl` all
+ * name this, and a second spelling would be a 400 on the scaffolded app's
+ * first sign-in (#2982).
+ */
+export function localDevOrigin(port) {
+    return `http://localhost:${port}`;
+}
+/**
+ * Point an existing environment at the app's web counterpart.
+ *
+ * Returns false — and writes nothing — when there is no config to write, the
+ * environment is not in it, or the file cannot be read: an adopting run does
+ * not own the project config, and a seed is never worth failing an init over.
+ */
+export function seedEnvironmentWebUrl(projectRoot, environment, webUrl) {
+    const configPath = join(projectRoot, PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+    if (!existsSync(configPath))
+        return false;
+    let config;
+    try {
+        config = loadProjectConfigFromPath(configPath);
+    }
+    catch {
+        return false;
+    }
+    const entry = config.environments[environment];
+    if (!entry)
+        return false;
+    if (entry.webUrl === webUrl)
+        return true;
+    entry.webUrl = webUrl;
+    saveProjectConfig(configPath, config);
+    return true;
+}
+/**
+ * Make sure this app allows the dev sign-in callback, so pointing the
+ * environment at the web client cannot break email sign-in (#2982).
+ *
+ * Returns true when the callback is on the app's `emailRedirectUris` — already
+ * there, or merged in here. Returns false when it is not and this run must not
+ * put it there: no credentials to ask the server with, an app whose allow-list
+ * would be NARROWED by writing one (see `planEmailRedirectUriMerge`), or an API
+ * call that failed. A false answer costs nothing but the automatic seed: the
+ * caller prints the manual step instead, and the app keeps working code-only.
+ */
+async function devCallbackIsAllowListed(appId, callbackUri, credentials) {
+    if (!credentials)
+        return false;
+    try {
+        const apiClient = new ApiClient();
+        const settings = await apiClient.getAppSettings(appId);
+        const plan = planEmailRedirectUriMerge(settings?.emailRedirectUris, callbackUri);
+        if (plan.action === "already-listed")
+            return true;
+        if (plan.action === "leave-alone") {
+            warn(`Not touching this app's sign-in link allow-list: ${plan.reason}.`);
+            return false;
+        }
+        await apiClient.updateAppSettings(appId, { emailRedirectUris: plan.uris });
+        success(`Allow-listed the dev sign-in link: ${callbackUri}`);
+        return true;
+    }
+    catch (err) {
+        warn(`Could not check this app's sign-in link allow-list: ${err.message}`);
+        return false;
+    }
+}
 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
@@ -86,7 +141,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 = [];
@@ -131,18 +186,52 @@ async function scaffoldProjectConfig(opts) {
             // Non-fatal
         }
     }
-    success(`Wrote ${PROJECT_CONFIG_DISPLAY_NAME} with dev environment`);
 }
-function validateServerUrl(url) {
-    if (!url.trim())
-        return "Server URL cannot be empty";
-    try {
-        new URL(url);
-        return true;
+/**
+ * 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";
+        }
     }
-    catch {
-        return "Please enter a valid URL (e.g., https://example.com)";
+    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`);
 }
 /**
  * Prompts for login when credentials are missing or the server has changed.
@@ -195,6 +284,23 @@ async function ensureAuthenticated(credentials, serverUrl, serverChanged, contex
     success(`Logged in as ${result.credentials.email}`);
     return result.credentials;
 }
+/**
+ * Finds the name of the project-config environment (if any) whose `apiUrl`
+ * matches `serverUrl`, so the project-mode "not logged in" remedy can name a
+ * real, working environment instead of a placeholder. Comparison uses the
+ * same canonicalization as `resolveInitServer` (trailing-slash-insensitive)
+ * so `https://host/` in `.primitive/config.json` still matches.
+ */
+function findEnvironmentForServer(serverUrl) {
+    const project = getProjectConfig();
+    if (!project)
+        return undefined;
+    const canonicalTarget = normalizeServerUrl(serverUrl) ?? serverUrl;
+    return Object.keys(project.environments).find((name) => {
+        const apiUrl = project.environments[name].apiUrl;
+        return (normalizeServerUrl(apiUrl) ?? apiUrl) === canonicalTarget;
+    });
+}
 /**
  * Loads the init config from --config flag or auto-discovers it in CWD.
  * Returns null if no config file is found/specified.
@@ -245,55 +351,97 @@ 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)
-    skip_install = false       # Skip pnpm install (optional)
-    server = "https://..."     # Custom server URL (optional)
+    dev_port = 5173            # Dev server port (optional). Set it to skip the
+                               # port prompt: init pins the port in
+                               # vite.config.ts and .env and adds
+                               # http://localhost:<port> to the app's CORS
+                               # allowed origins and redirect URIs.
+    skip_install = false       # Skip pnpm install (optional). Same effect as
+                               # --skip-install; the flag wins if both are set.
+    server = "https://..."     # Server to create the app on (optional).
+                               # Same effect as -s/--server; the flag wins if
+                               # both are set. If the CLI already points at a
+                               # different server, init stops and tells you how
+                               # to point it here first. Outside a Primitive
+                               # project, if you are not logged in at all, init
+                               # logs in to this one; inside a project the
+                               # selected environment's apiUrl is the target
+                               # even when logged out, so a different value
+                               # here stops the run.
     invite_emails = ["a@b.com"] # Emails to invite (optional, for invite-only)
     allowed_domains = ["b.com"] # Allowed domains (optional, for domain 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
     // rest of this function uses it to skip prompts.
     const initConfig = loadInitConfigFromOptions(options);
+    // Whether to skip the dependency install (steps 7-8). Both the
+    // `--skip-install` flag and the config's `skip_install` key request it; the
+    // flag wins. Reading only the flag is what made the documented config key a
+    // no-op (#2720).
+    const { skipInstall, source: skipInstallSource } = resolveSkipInstall(options.skipInstall, initConfig);
+    const skipInstallReason = skipInstallSource === "config" ? "skip_install = true in config" : "--skip-install";
     // Resolve the target platform per the 4-case interactivity contract:
     //   (a) explicit --platform flag    -> use it (never prompt)
     //   (b) init-config TOML present     -> use its platform or fall back to web
@@ -301,23 +449,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.");
@@ -331,14 +486,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";
@@ -349,19 +517,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,
@@ -372,34 +574,53 @@ async function handleInit(projectDirArg, options) {
             }
         }
     }
-    // Step 2.5: Determine target server
-    let serverUrl;
-    let serverChanged = false;
-    if (options.server) {
+    // Step 2.5: Determine target server. Precedence: `--server` flag, then the
+    // init-config `server` key, then the current login, then the default. The
+    // config key used to be dropped on the floor here (#2376).
+    if (options.server !== undefined) {
         const validation = validateServerUrl(options.server);
         if (validation !== true) {
             error(validation);
             process.exit(1);
         }
-        serverUrl = options.server;
-        // Check if explicit --server differs from current credentials
-        const existingCredentials = loadCredentials();
-        if (existingCredentials?.serverUrl &&
-            existingCredentials.serverUrl !== options.server) {
-            serverChanged = true;
-        }
     }
-    else {
-        const existingCredentials = loadCredentials();
-        const currentServer = existingCredentials?.serverUrl;
-        if (currentServer && currentServer !== DEFAULT_SERVER_URL && !initConfig) {
+    const existingCredentials = loadCredentials();
+    // In project mode the CLI is pinned to the selected environment's `apiUrl`
+    // even before that environment has any credentials: `saveCredentialsStore()`
+    // writes tokens into the environment's slot and discards the server they were
+    // minted for, and `loadCredentialsStore()` blends them back with
+    // `env.config.apiUrl`. So "logged out" does not mean "no current server"
+    // there — the environment still fixes the target, and the mismatch check
+    // below has to compare against it. Reading only the credentials' `serverUrl`
+    // let a logged-out environment slip past the guard: init would log in to the
+    // config's server and then send every later call to the environment's own
+    // `apiUrl`.
+    const currentEnvironment = getCurrentEnvironment();
+    // 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,
+        // 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;
             console.log();
             const serverChoice = await select({
-                message: `The Primitive CLI is currently using ${currentServer}.\nWhere do you want to create this app?`,
+                message: `The Primitive CLI is currently using ${current}.\nWhere do you want to create this app?`,
                 choices: [
                     {
-                        value: currentServer,
-                        name: `Current server (${currentServer})`,
+                        value: current,
+                        name: `Current server (${current})`,
                     },
                     {
                         value: DEFAULT_SERVER_URL,
@@ -412,60 +633,195 @@ async function handleInit(projectDirArg, options) {
                 ],
                 default: currentServer,
             });
-            if (serverChoice === "__custom__") {
-                serverUrl = await input({
-                    message: "Enter the server URL:",
-                    validate: validateServerUrl,
-                });
+            if (serverChoice !== "__custom__")
+                return serverChoice;
+            return input({
+                message: "Enter the server URL:",
+                validate: validateServerUrl,
+            });
+        },
+    });
+    const serverUrl = resolvedServer.serverUrl;
+    const serverChanged = resolvedServer.serverChanged;
+    if (resolvedServer.source === "config") {
+        info(`Server: ${serverUrl} (from config)`);
+    }
+    // A run that can't get usable credentials for the resolved server must fail
+    // loudly here rather than hang on the OAuth callback — or, as in #2376,
+    // quietly build the app on the current server. Two cases qualify:
+    //
+    //   * a non-interactive init-config run, which has no way to drive a browser;
+    //   * any project-mode run, because a login always lands in the selected
+    //     environment's slot and is read back with that environment's `apiUrl`.
+    //     Logging in to a different server there would leave the project holding
+    //     credentials the rest of the CLI sends somewhere else.
+    //
+    // 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() || plan.mode === "add-client";
+    if (serverChanged && (initConfig || inProjectMode)) {
+        const requestedBy = resolvedServer.source === "flag"
+            ? "--server"
+            : resolvedServer.source === "config"
+                ? "the init config's `server`"
+                : "the server you selected";
+        // `currentServer` is the stored login's server when there is one, and
+        // otherwise the selected environment's `apiUrl` — say which, so the user
+        // 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 "${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
+        // through `getConfiguredServerUrl()`, which returns the active
+        // environment's `apiUrl` whenever a project config is in scope and ignores
+        // `PRIMITIVE_SERVER_URL` there. Printing the legacy-mode hint inside a
+        // project would send the user in circles.
+        if (inProjectMode) {
+            error(`Inside a Primitive project, \`primitive login\` targets the selected environment's server, so PRIMITIVE_SERVER_URL has no effect here.`);
+            // `primitive -e <env> login` only resolves the mismatch if `<env>` is
+            // both logged into AND passed to the init re-run — `currentServer` is
+            // always the *selected* environment's apiUrl (that's what made this
+            // serverChanged in the first place), so re-running `primitive login`
+            // or `primitive init` without `-e` reproduces the identical error.
+            // Look up which configured environment (if any) actually targets
+            // `serverUrl` so the hint names a real, working command instead of a
+            // placeholder.
+            const targetEnvName = findEnvironmentForServer(serverUrl);
+            // The re-run has to resolve to the same server, and it re-reads every
+            // input from scratch. Only a config-selected server survives on its own:
+            // when the flag (or the interactive prompt) is what won here, an
+            // otherwise-identical re-run would fall back to the config's `server` —
+            // or prompt again — and reproduce this exact error. Pin it with
+            // `--server`, which outranks both.
+            const serverFlag = resolvedServer.source === "config" ? "" : ` --server ${serverUrl}`;
+            if (targetEnvName) {
+                const configFlag = options.config ? ` --config ${options.config}` : "";
+                error(`Log in to the "${targetEnvName}" environment and run init against it: ` +
+                    `\`primitive -e ${targetEnvName} login\` then ` +
+                    `\`primitive -e ${targetEnvName} init${configFlag}${serverFlag}\`.`);
             }
             else {
-                serverUrl = serverChoice;
+                error(`This project has no environment configured for ${serverUrl}. ` +
+                    `Add one (\`primitive env add <name> --api-url ${serverUrl}\`) and ` +
+                    `re-run with \`-e <name>${serverFlag}\`, or re-run init outside the project directory.`);
             }
-            serverChanged = currentServer !== serverUrl;
         }
         else {
-            serverUrl = currentServer || DEFAULT_SERVER_URL;
+            error(`Log in to the target server first: PRIMITIVE_SERVER_URL=${serverUrl} primitive login`);
         }
+        warn("No project files were written.");
+        process.exit(1);
     }
-    // Step 4: Check authentication
-    let credentials = loadCredentials();
+    // 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;
+    /**
+     * Whether THIS run created the app. A created app is seeded with
+     * `http://localhost:5173/oauth/callback` in `emailRedirectUris`; an adopted
+     * one carries whatever allow-list it already had, which is why the combined
+     * app's `webUrl` seed asks the server before pointing the sign-in link at a
+     * dev callback (#2982).
+     */
+    let appWasCreatedByThisRun = false;
+    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,
@@ -474,7 +830,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
@@ -528,6 +926,7 @@ async function handleInit(projectDirArg, options) {
                 throw new Error("App created but no appId returned");
             }
             appId = id;
+            appWasCreatedByThisRun = true;
             success(`App created: ${appName}`);
             keyValue("App ID", appId);
         }
@@ -549,7 +948,7 @@ async function handleInit(projectDirArg, options) {
         else {
             console.log();
             info("Let's configure who can access your app.");
-            info("(You can change this later with 'primitive apps update')");
+            info("(You can change this later in app.toml, then 'primitive config push --only app')");
             accessMode = await select({
                 message: "Who should be able to sign up for your app?",
                 choices: [
@@ -675,13 +1074,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}`);
@@ -691,128 +1093,322 @@ 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}`);
+        }
     }
-    // Steps 5-8: Platform-specific configuration and dependency installation
-    if (isApple) {
-        // ── Apple (SwiftUI) path ──────────────────────────────────────────
-        // Step 5: Update primitive.json
-        info("Configuring primitive.json...");
+    // 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.
+    if (plan.writesProjectConfig) {
         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.");
+            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}`);
+        }
+    }
+    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 {
+            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 (!options.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 (--skip-install).");
-        }
     }
-    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,
+        });
+    /**
+     * The URL scheme derived for each Apple client, for the final summary.
+     * `registered` is false when the client's plist had no `PrimitiveAuth` URL
+     * type to stamp it into, so the summary and the opt-in guidance describe a
+     * candidate scheme rather than a registered one.
+     */
+    const iosCallbackSchemes = [];
+    /**
+     * An app with BOTH clients emails ONE https sign-in link — the web app's
+     * callback, which opens the iOS app where it is installed (#2982). "Both"
+     * counts the clients already in the repository, including one that IS the
+     * project root (the flat single-client layout gaining its second platform).
+     */
+    const combinedApp = appHasBothPlatforms(plan.clients.map((client) => client.platform), discoverClientPlatforms(plan.projectRoot));
+    /** The web dev origin this run settled on, for the environment's `webUrl`. */
+    let webDevOrigin = null;
+    /**
+     * Whether that origin's `/oauth/callback` is known to be on the app's
+     * magic-link allow-list already — because the app was created here with the
+     * default-port seed, or because the dev-port step merged it (#2982). Anything
+     * else has to be asked about before the environment points a sign-in link at
+     * it.
+     */
+    let devCallbackAllowListed = false;
+    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 5b: Give this client its own URL scheme (#2969).
+            //
+            // The template ships `primitiveapp` registered, which every app
+            // scaffolded from it would otherwise share — iOS then picks arbitrarily
+            // between two of them for an incoming link. The stamped scheme carries
+            // the app id, so no two apps collide.
+            //
+            // Nothing is written to the app's `emailRedirectUris`, here or on the
+            // server: the manager sends no redirect target by default, so this app's
+            // email sign-in works immediately and code-only. The link is the
+            // developer's opt-in, and this run only prints what it takes.
+            const callbackScheme = deriveCallbackScheme(appName, appId, basename(client.dir));
+            const stamped = stampCallbackScheme(client.dir, callbackScheme);
+            iosCallbackSchemes.push({
+                dir: client.dir,
+                scheme: callbackScheme,
+                registered: stamped.outcome !== "not-found",
+            });
+            if (stamped.outcome === "not-found") {
+                for (const line of missingUrlTypeGuidance(callbackScheme))
+                    warn(line);
+            }
+            else {
+                success(`Callback URL scheme registered: ${callbackScheme}`);
+            }
+            // 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: Confirm the dev port to use. Default to 5173; warn about taken ports.
+        // 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
+        // — this was the one branch in the command that prompted unconditionally,
+        // so the documented key was ignored and a closed stdin threw
+        // ERR_USE_AFTER_CLOSE into the catch below (#2720).
         try {
-            console.log();
-            const defaultPort = 5173;
-            const defaultOrigin = `http://localhost:${defaultPort}`;
-            // Scan up to 10 ports starting from 5173 to surface what's already in use
-            const takenPorts = [];
-            for (let p = defaultPort; p < defaultPort + 10; p++) {
-                if (!(await isPortFree(p)))
-                    takenPorts.push(p);
-                else
-                    break;
-            }
-            if (takenPorts.length > 0) {
-                warn(`Port${takenPorts.length > 1 ? "s" : ""} ${takenPorts.join(", ")} ${takenPorts.length > 1 ? "are" : "is"} already in use.`);
-            }
-            const portInput = await input({
-                message: "Dev server port for this project:",
-                default: String(defaultPort),
-                validate: (val) => {
-                    const n = parseInt(val, 10);
-                    if (isNaN(n) || n < 1 || n > 65535)
-                        return "Enter a valid port number.";
-                    return true;
+            const defaultPort = DEFAULT_DEV_PORT;
+            const defaultOrigin = localDevOrigin(defaultPort);
+            const resolvedPort = await resolveDevPort({
+                configPort: initConfig?.dev_port,
+                hasConfig: initConfig != null,
+                isTTY: Boolean(process.stdin.isTTY),
+                defaultPort,
+                promptFn: async () => {
+                    console.log();
+                    // Scan up to 10 ports starting from 5173 to surface what's already in use
+                    const takenPorts = [];
+                    for (let p = defaultPort; p < defaultPort + 10; p++) {
+                        if (!(await isPortFree(p)))
+                            takenPorts.push(p);
+                        else
+                            break;
+                    }
+                    if (takenPorts.length > 0) {
+                        warn(`Port${takenPorts.length > 1 ? "s" : ""} ${takenPorts.join(", ")} ${takenPorts.length > 1 ? "are" : "is"} already in use.`);
+                    }
+                    const portInput = await input({
+                        message: "Dev server port for this project:",
+                        default: String(defaultPort),
+                        validate: validateDevPort,
+                    });
+                    return parseInt(portInput, 10);
                 },
             });
-            const chosenPort = parseInt(portInput, 10);
+            const chosenPort = resolvedPort.port;
+            // The same origin the app's CORS list and `emailRedirectUris` are seeded
+            // with, so a combined app's first sign-in link is already allow-listed.
+            webDevOrigin = localDevOrigin(chosenPort);
+            // …but only for an app this run created: that seed happens at creation.
+            // An adopted app on the default port has been through neither the seed
+            // nor the port step below, so nothing here can vouch for its allow-list.
+            devCallbackAllowListed = appWasCreatedByThisRun && chosenPort === defaultPort;
+            if (resolvedPort.source === "config") {
+                info(`Dev server port: ${chosenPort} (from config)`);
+            }
             if (chosenPort !== defaultPort) {
-                const devOrigin = `http://localhost:${chosenPort}`;
-                // Pin the port in vite.config.ts and update .env
-                updateViteConfig(targetDir, chosenPort);
-                updateEnvPort(targetDir, chosenPort);
+                const devOrigin = localDevOrigin(chosenPort);
+                // 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(client.dir, chosenPort);
+                if (!viteUpdated) {
+                    warn(`Could not pin port ${chosenPort} in vite.config.ts — set \`server.port\` there manually.`);
+                }
+                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 {
@@ -820,19 +1416,49 @@ 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,
-                        });
-                        success(`Dev port set to ${chosenPort}: vite.config.ts, .env, CORS, redirect URIs, and base URL updated.`);
+                        };
+                        // 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);
+                        // This merge is what puts the chosen port's callback on the
+                        // allow-list, whoever created the app (#2982).
+                        devCallbackAllowListed = true;
+                        success(`Dev port set to ${chosenPort}: ${viteUpdated ? "vite.config.ts, " : ""}.env, CORS, redirect URIs, and base URL updated.`);
                     }
                     catch (err) {
                         warn(`Could not update app settings: ${err.message}`);
@@ -840,18 +1466,32 @@ async function handleInit(projectDirArg, options) {
                 }
             }
         }
-        catch {
-            // Non-fatal: port detection or settings update failed silently
+        catch (err) {
+            // Non-fatal — but say so. A silent swallow here is what hid the closed
+            // stdin crash in #2720: the run kept 5173 and still exited 0.
+            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 {
@@ -865,10 +1505,10 @@ async function handleInit(projectDirArg, options) {
             }
         }
         // Step 8: Install dependencies with pnpm (via npx to handle version management)
-        if (!options.skipInstall) {
+        if (!skipInstall) {
             info("Installing dependencies...");
             try {
-                await runPnpmInstall(targetDir);
+                await runPnpmInstall(client.dir);
                 success("Dependencies installed.");
             }
             catch (err) {
@@ -877,7 +1517,7 @@ async function handleInit(projectDirArg, options) {
             }
         }
         else {
-            info("Skipping dependency installation (--skip-install).");
+            info(`Skipping dependency installation (${skipInstallReason}).`);
         }
     }
     // Step 9: Install primitive CLI globally if not already installed
@@ -892,7 +1532,7 @@ async function handleInit(projectDirArg, options) {
             }
             catch (err) {
                 warn(`Could not install CLI: ${err.message}`);
-                warn("You can install it manually with: npm install -g primitive-admin");
+                warn(`You can install it manually with: ${installCommand(PRIMITIVE_CLI_PACKAGE)}`);
             }
         }
         else {
@@ -910,11 +1550,37 @@ async function handleInit(projectDirArg, options) {
                 }
                 catch (err) {
                     warn(`Could not install CLI: ${err.message}`);
-                    warn("You can install it manually with: npm install -g primitive-admin");
+                    warn(`You can install it manually with: ${installCommand(PRIMITIVE_CLI_PACKAGE)}`);
                 }
             }
         }
     }
+    // The combined app's dev sign-in link (#2982): the environment learns the
+    // web origin this run settled on, so the iOS client's emailed link opens the
+    // local web app instead of a scheme that is dead in the Simulator. Only when
+    // this run owns the project config — an adopting run gets the guidance and
+    // decides for itself.
+    //
+    // And only once the app actually allows that callback. Setting `webUrl` is
+    // what turns a code-only email into a link, and a link the server refuses is
+    // a 400 on every sign-in request — strictly worse than the code-only default
+    // this app has today. An app created here was seeded with the callback; an
+    // adopted one is asked about, and when the answer is no or unavailable the
+    // seed is skipped in favour of printing the step.
+    let seededWebOrigin = null;
+    let unverifiedDevCallback = null;
+    if (combinedApp && plan.writesProjectConfig && webDevOrigin) {
+        const devCallback = `${webDevOrigin}/oauth/callback`;
+        const allowed = devCallbackAllowListed ||
+            (await devCallbackIsAllowListed(appId, devCallback, credentials));
+        if (allowed && seedEnvironmentWebUrl(plan.projectRoot, "dev", webDevOrigin)) {
+            seededWebOrigin = webDevOrigin;
+            success(`Environment "dev" points at the web client: webUrl ${webDevOrigin}`);
+        }
+        else if (!allowed) {
+            unverifiedDevCallback = devCallback;
+        }
+    }
     // Step 10: Offer to install Claude Code skill if not already installed
     try {
         const { isSkillInstalled, installSkillExplicit, checkSkillStatus } = await import("../lib/skill-installer.js");
@@ -941,39 +1607,288 @@ 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);
+    }
+    for (const { scheme, registered } of iosCallbackSchemes) {
+        keyValue("Callback URL scheme", registered ? scheme : `${scheme} (not registered — see the warning above)`);
+    }
     divider();
+    // Email sign-in already works for the scaffolded app — code-only, no app
+    // settings — so this is an opt-in, not a step (#2969). An app with both
+    // clients gets the https link instead, which needs a different checklist
+    // (#2982).
+    if (combinedApp) {
+        for (const line of universalLinkGuidance({
+            webOrigin: seededWebOrigin ?? undefined,
+            unverifiedDevCallback: unverifiedDevCallback ?? undefined,
+        })) {
+            info(line);
+        }
+        divider();
+    }
+    else {
+        for (const { scheme, registered } of iosCallbackSchemes) {
+            for (const line of linkOptInGuidance(scheme, { registered }))
+                info(line);
+            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 (options.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;
+        // The same template signals the both-platforms predicate reads, so the
+        // layout description and the universal-link wiring cannot disagree about
+        // what counts as a client.
+        const platform = detectClientPlatform(join(projectRoot, entry.name));
+        if (platform)
+            found.push({ platform, 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 (options.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