primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/commands/init.js

@@ -1,107 +1,851 @@
-import { existsSync } from "fs";
-import { resolve, basename } from "path";
-import { input, confirm, select } from "@inquirer/prompts";
-import { loadCredentials } from "../lib/config.js";
-import { browserLogin } from "../lib/auth-flow.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_TREE_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 { downloadAndExtractTemplate, updateEnvFile, runPnpmInstall, isDirectoryEmpty, isPnpmInstalled, installPnpmGlobally, isPrimitiveCliInstalled, installPrimitiveCli, } from "../lib/template.js";
-import { success, error, info, warn, keyValue, divider, } from "../lib/output.js";
-const DEFAULT_SERVER_URL = process.env.PRIMITIVE_SERVER_URL || "https://primitiveapi.com";
+import { browserLogin } from "../lib/auth-flow.js";
+import { loadCredentials } from "../lib/config.js";
+import { allowGlobalCredentials } from "../lib/credentials-store.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 { 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 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_TREE_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;
+    }
+}
+/**
+ * The .gitignore lines `init` writes for Primitive CLI local state — one line,
+ * with no per-file exception (#3153, intent criterion 2).
+ *
+ * That is the whole point of the move: `primitive/` is committed (the config
+ * and every environment's TOML, including the shared `.sync-state.json`
+ * baseline) and `.primitive/` is machine-local (credentials, this machine's
+ * `primitive env use` selection, pre-pull snapshot backups). Before the move
+ * one directory meant both things, so the list needed six entries and a
+ * comment explaining which files inside it were committed anyway.
+ */
+export const GITIGNORE_LOCAL_STATE_ENTRIES = [".primitive/"];
+/**
+ * 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.
+ */
+export function ensureGitignoreLocalState(targetDir) {
+    // One rule: `.primitive/` is machine-local and never committed, `primitive/`
+    // is the committed tree. Narrower `.primitive/...` entries left over from an
+    // older init are harmless subsets of this line, so they are left alone — the
+    // migration document owns tidying an adopted project's .gitignore.
+    const gitignorePath = join(targetDir, ".gitignore");
+    const gitignoreEntries = [...GITIGNORE_LOCAL_STATE_ENTRIES];
+    let linesToAdd = [];
+    if (existsSync(gitignorePath)) {
+        const existing = readFileSync(gitignorePath, "utf-8")
+            .split(/\r?\n/)
+            .map((l) => l.trim());
+        for (const entry of gitignoreEntries) {
+            if (!existing.includes(entry)) {
+                linesToAdd.push(entry);
+            }
+        }
+    }
+    else {
+        linesToAdd = [...gitignoreEntries];
+    }
+    if (linesToAdd.length > 0) {
+        try {
+            const prefix = existsSync(gitignorePath) ? "\n# Primitive CLI local state\n" : "# Primitive CLI local state\n";
+            appendFileSync(gitignorePath, prefix + linesToAdd.join("\n") + "\n");
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+/**
+ * Writes primitive/config.json into the project directory and ensures the
+ * .gitignore entry for local state exists. Safe to call in a directory that
+ * already has a config — in that case we add/update the "dev" environment
+ * instead of overwriting the file.
+ */
+async function scaffoldProjectConfig(opts) {
+    const configPath = join(opts.targetDir, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME);
+    let config;
+    if (existsSync(configPath)) {
+        // Respect an existing config: merge in the new dev env if missing.
+        try {
+            config = loadProjectConfigFromPath(configPath);
+        }
+        catch {
+            // Existing file is broken — don't clobber it; just warn and skip.
+            warn(`${PROJECT_CONFIG_DISPLAY_NAME} exists but is invalid. Skipping project config scaffold.`);
+            return;
+        }
+        if (!config.environments.dev) {
+            config.environments.dev = {
+                apiUrl: opts.serverUrl,
+                appId: opts.appId,
+                appName: opts.appName,
+            };
+            if (!config.defaultEnvironment)
+                config.defaultEnvironment = "dev";
+        }
+    }
+    else {
+        config = {
+            version: CURRENT_CONFIG_VERSION,
+            defaultEnvironment: "dev",
+            environments: {
+                dev: {
+                    apiUrl: opts.serverUrl,
+                    appId: opts.appId,
+                    appName: opts.appName,
+                },
+            },
+        };
+    }
+    saveProjectConfig(configPath, config);
+    ensureGitignoreLocalState(opts.targetDir);
+    success(`Wrote ${PROJECT_CONFIG_DISPLAY_NAME} with dev environment`);
+}
+/**
+ * Prompts for login when credentials are missing or the server has changed.
+ * Returns updated credentials on success, or exits/warns on failure.
+ * In non-interactive mode, auto-proceeds with login (no confirmation prompt).
+ */
+async function ensureAuthenticated(credentials, serverUrl, serverChanged, context) {
+    if (credentials && !serverChanged)
+        return credentials;
+    if (serverChanged) {
+        info(`Switching to ${serverUrl}. You need to log in.`);
+    }
+    else {
+        info(`You need to log in to ${context.reason}.`);
+    }
+    if (context.nonInteractive && context.allowSkip) {
+        warn(`Skipping ${context.reason}; no authentication is available.`);
+        warn(`Make sure the app ID is correct.`);
+        return null;
+    }
+    let shouldLogin;
+    if (context.nonInteractive) {
+        // In non-interactive mode, auto-proceed with login
+        shouldLogin = true;
+        info("Attempting automatic login...");
+    }
+    else {
+        shouldLogin = await confirm({
+            message: "Log in now?",
+            default: true,
+        });
+    }
+    if (!shouldLogin) {
+        if (!context.allowSkip) {
+            error(`Cannot ${context.reason} without authentication. Use --use-existing-app-id to skip app creation.`);
+            // Authentication happens before template prep, so a bail-out here leaves
+            // nothing on disk.
+            warn(`No project files were written. Re-run \`primitive init\` once you can authenticate.`);
+            process.exit(1);
+        }
+        warn(`Skipping. Make sure the app ID is correct.`);
+        return null;
+    }
+    const result = await browserLogin(serverUrl);
+    if (!result.success) {
+        error(`Login failed: ${result.error}`);
+        warn(`No project files were written. Re-run \`primitive init\` once you can authenticate.`);
+        process.exit(1);
+    }
+    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.
+ * Exits with error if config file is specified but invalid.
+ */
+function loadInitConfigFromOptions(options) {
+    let config = null;
+    if (options.config) {
+        // Explicit config path
+        const configPath = resolve(process.cwd(), options.config);
+        if (!existsSync(configPath)) {
+            error(`Config file not found: ${configPath}`);
+            process.exit(1);
+        }
+        try {
+            const content = readFileSync(configPath, "utf-8");
+            config = parseInitConfigToml(content);
+        }
+        catch (err) {
+            error(`Failed to parse config file: ${err.message}`);
+            process.exit(1);
+        }
+    }
+    else {
+        // Auto-discover in CWD
+        config = loadInitConfig(process.cwd());
+    }
+    if (!config)
+        return null;
+    // Validate
+    info(`Using config file for non-interactive init`);
+    const validation = validateInitConfig(config);
+    if (!validation.valid) {
+        error("Invalid config file:");
+        for (const err of validation.errors) {
+            error(`  - ${err}`);
+        }
+        process.exit(1);
+    }
+    return config;
+}
 export function registerInitCommand(program) {
     program
         .command("init")
         .description("Create a new Primitive app from template")
         .argument("[directory]", "Directory to create the project in (default: current directory)")
         .option("--use-existing-app-id <id>", "Use an existing app ID instead of creating a new one")
-        .option("-s, --server <url>", "Server URL", DEFAULT_SERVER_URL)
-        .option("--skip-install", "Skip running pnpm install")
+        .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 <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 in ./my-app, prompt for app name
-  $ primitive init                     # Interactive: prompt for directory and app name
+  $ 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", "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", "ios", "web,ios", or ["web", "ios"]
+                               # (optional, defaults to web)
+    promote_schema = false     # Only with action = "add-client". Consent to move
+                               # an existing single-client repo's models.toml to
+                               # <project root>/models/models.toml so every client
+                               # reads one copy.
+    access_mode = "invite-only" # "public", "domain", or "invite-only" (optional)
+    dev_port = 5173            # Dev server port (optional). Set it to skip the
+                               # port prompt: init pins the port in
+                               # 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
-  2. Prompt for an app name and create it on the Primitive server (or use existing)
-  3. Configure the project with your app ID
-  4. Install dependencies with pnpm
+  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) {
-    const serverUrl = options.server || DEFAULT_SERVER_URL;
+    // `init` is what CREATES a project, so by definition it runs before one
+    // exists — and it has to call the API to do it. One of the four commands
+    // permitted to reach the global credentials file with no project in scope
+    // (#3154, intent criterion 5).
+    allowGlobalCredentials();
+    // Validate an explicitly-passed `--platform` flag up front. Only `web` and
+    // `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
+    //   (c) interactive TTY, no flag/cfg -> prompt
+    //   (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.
+    // 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: () => checkbox({
+            message: "Which clients are you building? (space to select)",
+            choices: [
+                { value: "web", name: "web (Vue 3 + TypeScript + Tailwind)", checked: true },
+                { value: "ios", name: "ios (Swift + SwiftUI)" },
+            ],
+            // 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 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.");
+        process.exit(1);
+    }
+    if (isApple) {
+        const xcodeAvailable = await isXcodeInstalled();
+        if (!xcodeAvailable) {
+            error("Xcode command-line tools are required for Apple development. Install them with: xcode-select --install");
+            process.exit(1);
+        }
+    }
     // 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: "Where would you like to create the project?",
-            default: ".",
+            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 "Directory cannot be empty";
+                    return "Project name cannot be empty";
                 return true;
             },
         });
     }
     const targetDir = resolve(process.cwd(), projectDir);
     // Used as the default app name suggestion when prompting
-    const defaultAppName = projectDir === "." ? basename(targetDir) : projectDir;
-    // Step 2: Check if directory exists and is non-empty
-    if (existsSync(targetDir) && !isDirectoryEmpty(targetDir)) {
-        warn(`Directory "${projectDir}" already exists and is not empty.`);
-        const overwrite = await confirm({
-            message: "Do you want to overwrite the existing contents?",
-            default: false,
-        });
-        if (!overwrite) {
-            error("Aborted. Please choose a different project name.");
+    const defaultAppName = projectDir === "." ? basename(targetDir) : basename(projectDir);
+    // ── 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 3: Download template
-    info("Setting up your project...");
-    try {
-        await downloadAndExtractTemplate({
-            targetDir,
-            onProgress: info,
-        });
+    // 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 "${label}" already exists and is not empty.`);
+                error('Set overwrite = true in your config file to allow overwriting.');
+                process.exit(1);
+            }
+            warn(`Directory "${label}" already exists and is not empty. Overwriting (overwrite = true in config).`);
+        }
+        else {
+            warn(`Directory "${label}" already exists and is not empty.`);
+            const overwrite = await confirm({
+                message: "Do you want to overwrite the existing contents?",
+                default: false,
+            });
+            if (!overwrite) {
+                error("Aborted. Please choose a different project name.");
+                process.exit(1);
+            }
+        }
     }
-    catch (err) {
-        error(`Failed to download template: ${err.message}`);
-        error("Check your internet connection and try again.");
+    // 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);
+        }
+    }
+    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 ${current}.\nWhere do you want to create this app?`,
+                choices: [
+                    {
+                        value: current,
+                        name: `Current server (${current})`,
+                    },
+                    {
+                        value: DEFAULT_SERVER_URL,
+                        name: `Production (${DEFAULT_SERVER_URL})`,
+                    },
+                    {
+                        value: "__custom__",
+                        name: "Other server",
+                    },
+                ],
+                default: currentServer,
+            });
+            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 {
+                error(`This project has no environment configured for ${serverUrl}. ` +
+                    `Add one (\`primitive env add <name> --api-url ${serverUrl} --app-id <app-id>\`) and ` +
+                    `re-run with \`-e <name>${serverFlag}\`, or re-run init outside the project directory.`);
+            }
+        }
+        else {
+            error(`Log in to the target server first: PRIMITIVE_SERVER_URL=${serverUrl} primitive login`);
+        }
+        warn("No project files were written.");
+        process.exit(1);
+    }
+    // Everything this run must be refused for, before a download or a write.
+    const guardError = checkInitGuards({
+        action: initConfig?.action,
+        hasConfig: initConfig != null,
+        ancestorProjectRoot: adoptedRoot,
+        configAppId: initConfig?.app_id,
+        flagAppId: options.useExistingAppId,
+        environmentAppId: adopted?.config.appId,
+        environmentName: adopted?.name,
+    });
+    if (guardError) {
+        error(guardError);
+        warn("No project files were written.");
         process.exit(1);
     }
-    // Step 4: Check authentication
-    let credentials = loadCredentials();
+    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;
-    if (options.useExistingAppId) {
-        // Using existing app ID - verify it exists
-        appId = options.useExistingAppId;
-        appName = "(existing app)"; // Default if we can't verify
-        if (!credentials) {
-            info("You need to log in to verify the app.");
-            const shouldLogin = await confirm({
-                message: "Log in now?",
-                default: true,
+    /**
+     * 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 = () => {
+        for (const prepared of preparedTemplates.values()) {
+            try {
+                prepared.cleanup();
+            }
+            catch {
+                // Non-fatal cleanup best effort
+            }
+        }
+        preparedTemplates.clear();
+    };
+    const prepareTemplateOrExit = async () => {
+        // 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,
+    // or `action = "use-existing"` + `app_id` in the init-config TOML. Reading
+    // only the flag (the old behavior) made a use-existing TOML fall through to
+    // the create branch and prompt for an app name — hanging non-interactive
+    // runs. (#1217)
+    const useExistingAppId = resolveUseExistingAppId(options.useExistingAppId, initConfig);
+    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 (shouldLogin) {
-                const result = await browserLogin(serverUrl);
-                if (!result.success) {
-                    error(`Login failed: ${result.error}`);
-                    warn(`Template files were extracted to "${targetDir}" but VITE_APP_ID is not configured.`);
-                    warn("You'll need to manually set VITE_APP_ID in your .env file to use this project.");
-                    process.exit(1);
-                }
-                credentials = result.credentials;
-                success(`Logged in as ${credentials.email}`);
+        }
+        if (!appName && credentials) {
+            try {
+                const client = new ApiClient();
+                appName = (await client.getApp(appId)).name;
             }
-            else {
-                warn("Skipping app verification. Make sure the app ID is correct.");
+            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
+        credentials = await ensureAuthenticated(credentials, serverUrl, serverChanged, {
+            reason: "verify the app",
+            allowSkip: true,
+            nonInteractive: !!initConfig,
+        });
         if (credentials) {
             try {
                 const client = new ApiClient();
@@ -113,36 +857,27 @@ async function handleInit(projectDirArg, options) {
                 warn(`Could not verify app: ${err.message}`);
             }
         }
+        await prepareTemplateOrExit();
     }
     else {
         // Creating new app - authentication required
-        if (!credentials) {
-            info("You need to log in to create an app.");
-            const shouldLogin = await confirm({
-                message: "Log in now?",
-                default: true,
+        credentials = await ensureAuthenticated(credentials, serverUrl, serverChanged, {
+            reason: "create an app",
+            allowSkip: false,
+            nonInteractive: !!initConfig,
+        });
+        // Determine app name
+        if (initConfig?.app_name) {
+            appName = initConfig.app_name;
+            info(`App name: ${appName} (from config)`);
+        }
+        else {
+            appName = await input({
+                message: "What would you like to name your app?",
+                default: defaultAppName,
             });
-            if (!shouldLogin) {
-                error("Cannot create app without authentication. Use --use-existing-app-id to skip app creation.");
-                warn(`Template files were extracted to "${targetDir}" but VITE_APP_ID is not configured.`);
-                warn("You'll need to manually set VITE_APP_ID in your .env file to use this project.");
-                process.exit(1);
-            }
-            const result = await browserLogin(serverUrl);
-            if (!result.success) {
-                error(`Login failed: ${result.error}`);
-                warn(`Template files were extracted to "${targetDir}" but VITE_APP_ID is not configured.`);
-                warn("You'll need to manually set VITE_APP_ID in your .env file to use this project.");
-                process.exit(1);
-            }
-            credentials = result.credentials;
-            success(`Logged in as ${credentials.email}`);
         }
-        // Prompt for app name
-        appName = await input({
-            message: "What would you like to name your app?",
-            default: defaultAppName,
-        });
+        await prepareTemplateOrExit();
         // Create app
         info("Creating app on Primitive server...");
         try {
@@ -156,58 +891,75 @@ 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);
         }
         catch (err) {
             error(`Failed to create app: ${err.message}`);
             error("You can try again or use --use-existing-app-id with an existing app.");
-            warn(`Template files were extracted to "${targetDir}" but VITE_APP_ID is not configured.`);
-            warn("You'll need to manually set VITE_APP_ID in your .env file to use this project.");
+            // The template archive has been validated in a temp directory, but it has
+            // not been installed into targetDir yet (#1218).
+            warn("No project files were written. Re-run `primitive init` after resolving the app creation error.");
+            cleanupPreparedTemplate();
             process.exit(1);
         }
         // Configure app access mode
-        console.log();
-        info("Let's configure who can access your app.");
-        info("(You can change this later with 'primitive apps update')");
-        const accessMode = await select({
-            message: "Who should be able to sign up for your app?",
-            choices: [
-                {
-                    value: "public",
-                    name: "Anyone (public)",
-                    description: "Anyone can create an account",
-                },
-                {
-                    value: "domain",
-                    name: "Domain restricted",
-                    description: "Only users with email addresses from specific domains",
-                },
-                {
-                    value: "invite-only",
-                    name: "Invite only",
-                    description: "Only users you explicitly invite can sign up",
-                },
-            ],
-            default: "invite-only",
-        });
+        let accessMode;
+        if (initConfig?.access_mode) {
+            accessMode = initConfig.access_mode;
+            info(`Access mode: ${accessMode} (from config)`);
+        }
+        else {
+            console.log();
+            info("Let's configure who can access your app.");
+            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: [
+                    {
+                        value: "public",
+                        name: "Anyone (public)",
+                        description: "Anyone can create an account",
+                    },
+                    {
+                        value: "domain",
+                        name: "Domain restricted",
+                        description: "Only users with email addresses from specific domains",
+                    },
+                    {
+                        value: "invite-only",
+                        name: "Invite only",
+                        description: "Only users you explicitly invite can sign up",
+                    },
+                ],
+                default: "invite-only",
+            });
+        }
         const client = new ApiClient();
         const settingsPayload = {
             mode: accessMode,
         };
         if (accessMode === "domain") {
-            const domainsInput = await input({
-                message: "Enter allowed email domain(s) (comma-separated, e.g., 'acme.com, example.org'):",
-                validate: (value) => {
-                    if (!value.trim())
-                        return "Please enter at least one domain";
-                    return true;
-                },
-            });
-            const allowedDomains = domainsInput
-                .split(",")
-                .map((d) => d.trim().toLowerCase())
-                .filter((d) => d.length > 0);
+            let allowedDomains;
+            if (initConfig?.allowed_domains && initConfig.allowed_domains.length > 0) {
+                allowedDomains = initConfig.allowed_domains;
+                info(`Allowed domains: ${allowedDomains.join(", ")} (from config)`);
+            }
+            else {
+                const domainsInput = await input({
+                    message: "Enter allowed email domain(s) (comma-separated, e.g., 'acme.com, example.org'):",
+                    validate: (value) => {
+                        if (!value.trim())
+                            return "Please enter at least one domain";
+                        return true;
+                    },
+                });
+                allowedDomains = domainsInput
+                    .split(",")
+                    .map((d) => d.trim().toLowerCase())
+                    .filter((d) => d.length > 0);
+            }
             settingsPayload.allowedDomains = allowedDomains;
         }
         // Update app settings with the chosen mode
@@ -218,34 +970,57 @@ async function handleInit(projectDirArg, options) {
         catch (err) {
             warn(`Could not update app settings: ${err.message}`);
         }
-        // If invite-only, offer to add initial allowed users
+        // If invite-only, auto-add the authenticated user and offer to add others
         if (accessMode === "invite-only") {
-            const inviteNow = await confirm({
-                message: "Would you like to add initial users who can sign up? (no emails will be sent)",
-                default: false,
-            });
-            if (inviteNow) {
-                const emailsInput = await input({
-                    message: "Enter email address(es) to allow (comma-separated):",
-                    validate: (value) => {
-                        if (!value.trim())
-                            return "Please enter at least one email";
-                        const emails = value.split(",").map((e) => e.trim());
-                        for (const email of emails) {
-                            if (!email.includes("@")) {
-                                return `Invalid email: ${email}`;
-                            }
-                        }
-                        return true;
-                    },
+            try {
+                await client.createInvitation(appId, {
+                    email: credentials.email,
+                    role: "member",
+                    sendEmail: false,
                 });
-                const emails = emailsInput
-                    .split(",")
-                    .map((e) => e.trim())
-                    .filter((e) => e.length > 0);
+                success(`${credentials.email} added to the invite list.`);
+            }
+            catch (err) {
+                if (!err.message?.includes("already has a pending invitation")) {
+                    warn(`Could not add your email to the invite list: ${err.message}`);
+                }
+            }
+            // Determine emails to invite
+            let emailsToInvite = [];
+            if (initConfig?.invite_emails && initConfig.invite_emails.length > 0) {
+                emailsToInvite = initConfig.invite_emails;
+                info(`Inviting users from config: ${emailsToInvite.join(", ")}`);
+            }
+            else if (!initConfig) {
+                const inviteNow = await confirm({
+                    message: "Would you like to add initial users who can sign up? (no emails will be sent)",
+                    default: false,
+                });
+                if (inviteNow) {
+                    const emailsInput = await input({
+                        message: "Enter email address(es) to allow (comma-separated):",
+                        validate: (value) => {
+                            if (!value.trim())
+                                return "Please enter at least one email";
+                            const emails = value.split(",").map((e) => e.trim());
+                            for (const email of emails) {
+                                if (!email.includes("@")) {
+                                    return `Invalid email: ${email}`;
+                                }
+                            }
+                            return true;
+                        },
+                    });
+                    emailsToInvite = emailsInput
+                        .split(",")
+                        .map((e) => e.trim())
+                        .filter((e) => e.length > 0);
+                }
+            }
+            if (emailsToInvite.length > 0) {
                 info("Adding invited users...");
                 let inviteCount = 0;
-                for (const email of emails) {
+                for (const email of emailsToInvite) {
                     try {
                         await client.createInvitation(appId, {
                             email,
@@ -264,98 +1039,808 @@ async function handleInit(projectDirArg, options) {
             }
         }
     }
-    // Step 5: Update .env file
-    info("Configuring environment...");
+    // ── Install every selected template ─────────────────────────────────
+    //
+    // The network download and archive validation already happened above,
+    // without touching any target directory.
     try {
-        const envResult = updateEnvFile(targetDir, appId);
-        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.`);
+        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}`);
+        cleanupPreparedTemplate();
+        process.exit(1);
+    }
+    finally {
+        cleanupPreparedTemplate();
+    }
+    // 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);
         }
-        else if (!envResult.envProductionUpdated) {
-            info(".env configured. No .env.production file found (this is optional).");
+        catch {
+            // Non-fatal: git may not be installed, or already a git repo
         }
-        else {
-            success("Environment configured (.env and .env.production).");
+    }
+    // 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 {
+            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}`);
         }
     }
-    catch (err) {
-        warn(`Could not update .env file: ${err.message}`);
-        warn(`Please manually set VITE_APP_ID=${appId} in your .env file.`);
-    }
-    // Step 6: Check if pnpm is installed globally, offer to install if not
-    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,
-        });
-        if (installPnpm) {
-            info("Installing pnpm...");
+    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 .gitignore: ${err.message}`);
+        }
+    }
+    // ── 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 installPnpmGlobally();
-                success("pnpm installed globally. You can now use 'pnpm' commands.");
+                // 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(`Could not install pnpm: ${err.message}`);
-                warn("Will use npx to run pnpm for dependency installation.");
+                warn(`Could not write AGENTS.md: ${err.message}`);
             }
         }
     }
-    // Step 7: Install dependencies with pnpm (via npx to handle version management)
-    if (!options.skipInstall) {
-        info("Installing dependencies...");
+    // ── 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, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME))}.`);
+                }
+            }
+            // 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: 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 {
-            await runPnpmInstall(targetDir);
-            success("Dependencies installed.");
+            const envResult = updateEnvFile(client.dir, appId, serverUrl, appName, production);
+            if (!envResult.envUpdated) {
+                info("No .env file in this template — identity comes from primitive/config.json.");
+            }
+            else {
+                success("Environment configured.");
+            }
         }
         catch (err) {
-            warn(`Dependency installation failed: ${err.message}`);
-            warn("You can try running 'npx pnpm install' manually.");
+            warn(`Could not update .env file: ${err.message}`);
+        }
+        // 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 {
+            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 = 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 = 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 apiClient = new ApiClient();
+                        let existingOrigins = [];
+                        let existingEmailRedirectUris = [];
+                        let existingGoogleClients = null;
+                        try {
+                            const currentSettings = await apiClient.getAppSettings(appId);
+                            if (currentSettings.corsMode === "custom" &&
+                                Array.isArray(currentSettings.corsAllowedOrigins)) {
+                                existingOrigins = currentSettings.corsAllowedOrigins;
+                            }
+                            if (Array.isArray(currentSettings.emailRedirectUris)) {
+                                existingEmailRedirectUris = currentSettings.emailRedirectUris;
+                            }
+                            if (currentSettings.googleClients) {
+                                existingGoogleClients = currentSettings.googleClients;
+                            }
+                        }
+                        catch {
+                            // Ignore — will set a fresh config
+                        }
+                        // Always include 5173 since it's the universal localhost default
+                        const corsOrigins = Array.from(new Set([...existingOrigins, defaultOrigin, devOrigin]));
+                        // 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`,
+                        ]));
+                        const settingsUpdate = {
+                            corsMode: "custom",
+                            corsAllowedOrigins: corsOrigins,
+                            corsAllowCredentials: true,
+                            emailRedirectUris,
+                            baseUrl: devOrigin,
+                        };
+                        // A Google web client redirects to this dev origin too, so its own
+                        // `redirectUris` needs the callback. A PUT replaces the WHOLE map,
+                        // so the complete map is sent back — an entry for a platform this
+                        // scaffold does not touch (ios, desktop, …) would otherwise be
+                        // deleted as a side effect of choosing a dev port.
+                        const webEntry = existingGoogleClients?.clients?.web;
+                        if (webEntry) {
+                            settingsUpdate.googleClients = {
+                                ...existingGoogleClients,
+                                clients: {
+                                    ...existingGoogleClients.clients,
+                                    web: {
+                                        ...webEntry,
+                                        redirectUris: Array.from(new Set([
+                                            ...(webEntry.redirectUris ?? []),
+                                            `${defaultOrigin}/oauth/callback`,
+                                            `${devOrigin}/oauth/callback`,
+                                        ])),
+                                    },
+                                },
+                            };
+                        }
+                        await apiClient.updateAppSettings(appId, settingsUpdate);
+                        // 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}`);
+                    }
+                }
+            }
+        }
+        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.
+        //
+        // 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 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 {
+                    await installPnpmGlobally();
+                    success("pnpm installed globally. You can now use 'pnpm' commands.");
+                }
+                catch (err) {
+                    warn(`Could not install pnpm: ${err.message}`);
+                    warn("Will use npx to run pnpm for dependency installation.");
+                }
+            }
+        }
+        // Step 8: Install dependencies with pnpm (via npx to handle version management)
+        if (!skipInstall) {
+            info("Installing dependencies...");
+            try {
+                await runPnpmInstall(client.dir);
+                success("Dependencies installed.");
+            }
+            catch (err) {
+                warn(`Dependency installation failed: ${err.message}`);
+                warn("You can try running 'npx pnpm install' manually.");
+            }
+        }
+        else {
+            info(`Skipping dependency installation (${skipInstallReason}).`);
         }
     }
-    else {
-        info("Skipping dependency installation (--skip-install).");
-    }
-    // Step 8: Install primitive CLI globally if not already installed
+    // Step 9: Install primitive CLI globally if not already installed
     const cliInstalled = await isPrimitiveCliInstalled();
     if (!cliInstalled) {
-        console.log();
-        info("The Primitive CLI helps you manage your app from the command line.");
-        const installCli = await confirm({
-            message: "Install the Primitive CLI globally?",
-            default: true,
-        });
-        if (installCli) {
+        if (initConfig) {
+            // Non-interactive: auto-install CLI
             info("Installing Primitive CLI...");
             try {
                 await installPrimitiveCli();
-                success("Primitive CLI installed. You can now use 'primitive' commands.");
+                success("Primitive CLI installed.");
             }
             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 {
+            console.log();
+            info("The Primitive CLI helps you manage your app from the command line.");
+            const installCli = await confirm({
+                message: "Install the Primitive CLI globally?",
+                default: true,
+            });
+            if (installCli) {
+                info("Installing Primitive CLI...");
+                try {
+                    await installPrimitiveCli();
+                    success("Primitive CLI installed. You can now use 'primitive' commands.");
+                }
+                catch (err) {
+                    warn(`Could not install CLI: ${err.message}`);
+                    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");
+        if (isSkillInstalled()) {
+            // Already installed — silently auto-update if a newer version is bundled
+            await checkSkillStatus();
+        }
+        else if (initConfig) {
+            // Non-interactive: auto-install skill
+            await installSkillExplicit();
+        }
+        else {
+            console.log();
+            info("The Primitive platform skill gives Claude Code expertise with Primitive APIs and patterns.");
+            const installSkill = await confirm({
+                message: "Install the Primitive platform skill for Claude Code?",
+                default: true,
+            });
+            if (installSkill) {
+                await installSkillExplicit();
             }
         }
     }
-    // Step 9: Show success message
+    catch {
+        // Non-fatal: skill installation should never block init
+    }
+    // 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);
+    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();
-    info("Next steps:");
-    if (projectDir !== ".") {
-        console.log(`  cd ${projectDir}`);
+    // 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();
     }
-    if (options.skipInstall) {
-        console.log("  pnpm install");
+    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:");
+    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");
+        }
     }
-    console.log("  pnpm run dev");
     console.log();
 }
+/** Where a project root's environments live, for the production derivation. */
+function readProjectEnvironments(projectRoot) {
+    const configPath = join(projectRoot, PROJECT_TREE_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 : []);
+        }
+    }
+    else {
+        const composed = composeSchemaContent({
+            base: readFileSync(schemaPath, "utf-8"),
+            starters,
+        });
+        if (composed.added.length > 0) {
+            writeFileSync(schemaPath, composed.content);
+            reportAddedModels(composed.added);
+        }
+    }
+    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