hatchkit 0.1.41 → 0.1.43

package/dist/adopt.js

@@ -33,7 +33,7 @@
  * a second run on the same dir notices the existing manifest and
  * exits early with a "use `hatchkit update` instead" hint.
  */
-import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, relative } from "node:path";
 import { Separator, confirm, input, select } from "@inquirer/prompts";
 import chalk from "chalk";
@@ -43,6 +43,7 @@ import { pushInitialBranch } from "./deploy/github.js";
 import { pushProjectKeyToCoolify, pushProjectKeyToGh } from "./deploy/keys.js";
 import { handleAdoptFailure } from "./deploy/rollback.js";
 import { runProvision } from "./provision/index.js";
+import { readEnvKeys } from "./provision/write-env.js";
 import { detectBuildPipeline, scaffoldBuildPipeline } from "./scaffold/build-pipeline.js";
 import { MANIFEST_FILENAME, readManifest, writeManifest, } from "./scaffold/manifest.js";
 import { installCancelHandler, isCancelInProgress, uninstallCancelHandler, } from "./utils/cancel-handler.js";
@@ -143,7 +144,13 @@ export async function runAdopt(cwd, opts = {}) {
         //      private one and produces "permission denied" on deploy.
         isPrivate: state.gitRemoteIsPrivate ?? true,
         appPort: "3000",
-        scaffoldBuildPipeline: true,
+        // Pipeline scaffold defaults OFF when the layout is unrecognised.
+        // The Dockerfile templates assume a single-package project rooted
+        // at /; for a workspace with no standard server/client dirs the
+        // generated files build the wrong thing (or nothing). User can
+        // still flip this on in the review loop — buildAdoptGroups parks
+        // the cursor on the row in this case so the choice is explicit.
+        scaffoldBuildPipeline: !state.unknownWorkspaceLayout,
         // Provisioning is opt-in. Each service mints real resources on a
         // third-party (GlitchTip project, OpenPanel project, Resend API
         // key) and cleaning those up after the fact is a chore — better
@@ -209,7 +216,7 @@ export async function runAdopt(cwd, opts = {}) {
 // ---------------------------------------------------------------------------
 // Detection
 // ---------------------------------------------------------------------------
-async function detectProject(projectDir) {
+export async function detectProject(projectDir) {
     const hasManifest = existsSync(join(projectDir, MANIFEST_FILENAME));
     const existingManifest = hasManifest ? (readManifest(projectDir) ?? undefined) : undefined;
     let packageName;
@@ -228,6 +235,31 @@ async function detectProject(projectDir) {
     catch {
         // No package.json at root — that's fine for a non-Node project.
     }
+    // Workspace markers — pnpm, yarn/npm, turbo, lerna, rush. When a
+    // marker is present but the standard server/client dir scan below
+    // turns up nothing, we're looking at a layout the scaffolder's
+    // surface-based Dockerfile templates can't handle. Flagged below as
+    // `unknownWorkspaceLayout`.
+    const workspaceMarkers = [
+        "pnpm-workspace.yaml",
+        "pnpm-workspace.yml",
+        "turbo.json",
+        "lerna.json",
+        "rush.json",
+    ];
+    let hasWorkspaceMarker = workspaceMarkers.some((f) => existsSync(join(projectDir, f)));
+    if (!hasWorkspaceMarker) {
+        // npm/yarn workspaces live as a `workspaces` field inside the root
+        // package.json (string array or { packages: [...] } object).
+        try {
+            const rootPkg = JSON.parse(readFileSync(join(projectDir, "package.json"), "utf-8"));
+            if (rootPkg.workspaces)
+                hasWorkspaceMarker = true;
+        }
+        catch {
+            // No / unreadable root package.json — leave hasWorkspaceMarker false.
+        }
+    }
     // Walk a generous set of common monorepo layouts.
     const serverDir = firstExisting(projectDir, [
         "packages/server",
@@ -349,6 +381,10 @@ async function detectProject(projectDir) {
             // undefined and let the stepper fall back to a sensible default.
         }
     }
+    const unknownWorkspaceLayout = hasWorkspaceMarker && !serverDir && !clientDir;
+    const standaloneBuildCandidates = unknownWorkspaceLayout
+        ? findStandaloneBuildCandidates(projectDir)
+        : [];
     return {
         projectDir,
         packageName,
@@ -356,6 +392,8 @@ async function detectProject(projectDir) {
         hasManifest,
         serverDir,
         clientDir,
+        unknownWorkspaceLayout,
+        standaloneBuildCandidates,
         features,
         prodEnvIsEncrypted,
         hasEnvKeys,
@@ -368,6 +406,57 @@ async function detectProject(projectDir) {
         existingManifest,
     };
 }
+/** Scan first-level subdirs for a standalone-buildable project — own
+ *  `package.json` AND its own lockfile (the marker that pnpm/npm/yarn
+ *  would install it independently of the parent workspace). `.npmrc`
+ *  with `ignore-workspace=true` is a stronger signal: that's the
+ *  explicit "treat me as standalone" toggle Docusaurus / marketing
+ *  sites use when they live next to a CLI workspace.
+ *
+ *  Returns first-level matches only; we don't recurse because the
+ *  intent is "show the user a starting point", not enumerate every
+ *  buildable subtree. */
+function findStandaloneBuildCandidates(projectDir) {
+    const out = [];
+    let entries;
+    try {
+        entries = readdirSync(projectDir);
+    }
+    catch {
+        return out;
+    }
+    for (const name of entries) {
+        if (name.startsWith(".") || name === "node_modules")
+            continue;
+        const dir = join(projectDir, name);
+        let isDir = false;
+        try {
+            isDir = statSync(dir).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir)
+            continue;
+        if (!existsSync(join(dir, "package.json")))
+            continue;
+        const hasOwnLockfile = existsSync(join(dir, "pnpm-lock.yaml")) ||
+            existsSync(join(dir, "package-lock.json")) ||
+            existsSync(join(dir, "yarn.lock"));
+        if (!hasOwnLockfile)
+            continue;
+        let hasIgnoreWorkspace = false;
+        try {
+            const npmrc = readFileSync(join(dir, ".npmrc"), "utf-8");
+            hasIgnoreWorkspace = /^\s*ignore-workspace\s*=\s*true\s*$/m.test(npmrc);
+        }
+        catch {
+            // No .npmrc — still a candidate (own lockfile is the main signal).
+        }
+        out.push({ dir, hasIgnoreWorkspace });
+    }
+    return out;
+}
 function firstExisting(root, candidates) {
     for (const c of candidates) {
         const full = join(root, c);
@@ -500,6 +589,22 @@ function printDetected(state) {
             ? chalk.yellow("repo present, no `origin` set")
             : chalk.dim("not a git repo yet")));
     lines.push(row("features (guess)", state.features.length > 0 ? state.features.join(", ") : chalk.dim("none detected")));
+    if (state.unknownWorkspaceLayout) {
+        lines.push("");
+        lines.push(chalk.yellow("  ! Workspace marker detected (pnpm-workspace.yaml / workspaces / turbo / lerna)"));
+        lines.push(chalk.yellow("    but no standard server/client dir matched. Adopt will skip the Docker"));
+        lines.push(chalk.yellow("    + GH Actions pipeline scaffold — the templates assume a single-package"));
+        lines.push(chalk.yellow("    project and would build the wrong thing here."));
+        if (state.standaloneBuildCandidates.length > 0) {
+            lines.push("");
+            lines.push(chalk.dim("    Standalone-buildable subdirs (own lockfile):"));
+            for (const c of state.standaloneBuildCandidates) {
+                const tag = c.hasIgnoreWorkspace ? chalk.green("  ignore-workspace=true") : "";
+                lines.push(chalk.dim(`      · ${relativeTo(c.dir)}${tag}`));
+            }
+            lines.push(chalk.dim("    Point a hand-authored Dockerfile at one of those and re-run adopt."));
+        }
+    }
     for (const l of lines)
         console.log(l);
     console.log();
@@ -677,7 +782,10 @@ function buildAdoptGroups(state, plan) {
                         {
                             key: "scaffoldBuildPipeline",
                             label: "Docker + GH Actions",
-                            set: true,
+                            // Park cursor here when the layout is unrecognised — the
+                            // user should make an explicit yes/no rather than walk
+                            // past a defaulted-off row without seeing it.
+                            set: !state.unknownWorkspaceLayout,
                             summary: renderBuildPipelineSummary(state, plan),
                         },
                     ],
@@ -834,7 +942,9 @@ async function editAdoptStep(state, plan, step) {
         // Also: switching away from client-only invalidates gh-pages
         // (Pages can't host a backend). Snap deploymentMode back to
         // coolify in that case so the user doesn't keep an invalid combo.
-        const nextDeploymentMode = plan.deploymentMode === "gh-pages" && next !== "client-only" ? "coolify" : plan.deploymentMode;
+        const nextDeploymentMode = plan.deploymentMode === "gh-pages" && next !== "client-only"
+            ? "coolify"
+            : plan.deploymentMode;
         if (plan.deploymentMode === "gh-pages" && next !== "client-only") {
             console.log(chalk.yellow("  ⚠ gh-pages requires client-only surfaces — switched deployment mode back to coolify."));
         }
@@ -958,10 +1068,15 @@ async function editAdoptStep(state, plan, step) {
                     checked: plan.services.includes("openpanel"),
                 },
                 {
-                    name: "Resend (email)",
+                    name: "Resend (transactional email)",
                     value: "resend",
                     checked: plan.services.includes("resend"),
                 },
+                {
+                    name: "Email forwarding (Cloudflare Email Routing → your inbox)",
+                    value: "email",
+                    checked: plan.services.includes("email"),
+                },
             ],
         });
         return { ...plan, services };
@@ -1041,6 +1156,47 @@ async function editAdoptStep(state, plan, step) {
     }
     return plan;
 }
+/** Canonical env key per service — used by `filterServicesForResume`
+ *  to decide whether a service's credentials are already wired into
+ *  the project's env files. If the key is present, re-minting on a
+ *  resume would orphan whatever's there (Resend mints a fresh API
+ *  key each call; OpenPanel mints a fresh project; Stripe re-creates
+ *  the webhook endpoint). `email` is intentionally absent — Email
+ *  Routing is zone-state with no env footprint, and its provisioner
+ *  is already 409-idempotent. */
+const RESUME_SERVICE_ENV_KEY = {
+    glitchtip: { server: "GLITCHTIP_DSN", client: "PUBLIC_GLITCHTIP_DSN" },
+    openpanel: { server: "OPENPANEL_CLIENT_ID", client: "PUBLIC_OPENPANEL_CLIENT_ID" },
+    resend: { server: "RESEND_API_KEY" },
+    s3: { server: "R2_ENDPOINT" },
+    email: {},
+};
+/** Filter the services list for `runProvision` on `--resume`: drop
+ *  every service whose canonical env keys are already in the target
+ *  env files. A non-resume run returns the list unchanged. */
+function filterServicesForResume(args) {
+    if (!args.resume)
+        return args.services;
+    const serverKeys = args.serverEnvPath ? readEnvKeys(args.serverEnvPath) : new Set();
+    const clientKeys = args.clientEnvPath ? readEnvKeys(args.clientEnvPath) : new Set();
+    const kept = [];
+    for (const svc of args.services) {
+        const want = RESUME_SERVICE_ENV_KEY[svc];
+        if (!want || (!want.server && !want.client)) {
+            kept.push(svc);
+            continue;
+        }
+        const serverOk = !want.server || serverKeys.has(want.server);
+        const clientOk = !want.client || clientKeys.has(want.client);
+        if (serverOk && clientOk) {
+            const which = [want.server, want.client].filter(Boolean).join(" + ");
+            console.log(chalk.dim(`  · Skipping ${svc} on --resume — ${which} already in .env.production.`));
+            continue;
+        }
+        kept.push(svc);
+    }
+    return kept;
+}
 async function executePlan(state, plan, opts = { resume: false }) {
     console.log(chalk.bold("\n  ── Adopting ──────────────────────────────────────────────\n"));
     const caveats = [];
@@ -1127,10 +1283,14 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // Gated on coolify mode — the Coolify-targeted Dockerfile + deploy
         // webhook workflow aren't useful for gh-pages, which uses its own
         // `gh-pages.yml` workflow written later in step 3c-pages.
+        let scaffoldedAbsPaths = [];
+        let overwrittenAbsPaths = [];
         if (plan.scaffoldBuildPipeline && plan.deploymentMode === "coolify") {
             const pipeResult = await scaffoldBuildPipelineNow(state, plan, remoteUrl, {
                 force: !!opts.regeneratePipeline,
             });
+            scaffoldedAbsPaths = pipeResult.createdAbsPaths;
+            overwrittenAbsPaths = pipeResult.overwrittenAbsPaths;
             // Record only files we *created*. The `overwritten` list is
             // deliberately not recorded — those files existed before this
             // run (the user's), and a later `hatchkit destroy` must never
@@ -1258,16 +1418,38 @@ async function executePlan(state, plan, opts = { resume: false }) {
         //
         // Skipped for gh-pages — there's no Coolify webhook to hit.
         const appUuidForSecrets = coolifyResult?.appUuid ?? state.coolifyAppMatch?.uuid;
-        if (plan.scaffoldBuildPipeline &&
-            plan.deploymentMode === "coolify" &&
-            appUuidForSecrets) {
+        if (plan.scaffoldBuildPipeline && plan.deploymentMode === "coolify" && appUuidForSecrets) {
             const slug = repoSlugFromRemote(remoteUrl);
             if (slug) {
-                await setCoolifyDeploySecrets({
-                    projectDir: state.projectDir,
-                    repoSlug: slug,
-                    apps: [{ uuid: appUuidForSecrets }],
-                });
+                // --resume gate: if every secret this step would push is
+                // already present on the repo, skip the push. The values
+                // themselves aren't readable through `gh secret list` (write-
+                // only), so we trust name-presence as the signal — same
+                // contract `ghSecretExists` uses for the ledger-record gate
+                // below. The user's recourse for a rotated Coolify token is
+                // re-running adopt *without* --resume.
+                const coolifySecretNames = [
+                    "COOLIFY_BASE_URL",
+                    "COOLIFY_API_TOKEN",
+                    "COOLIFY_TOKEN",
+                    "COOLIFY_WEBHOOK_URL",
+                    "COOLIFY_RESOURCE_UUID",
+                ];
+                let skipCoolifySecrets = false;
+                if (opts.resume) {
+                    const checks = await Promise.all(coolifySecretNames.map((n) => ghSecretExists(state.projectDir, slug, n)));
+                    if (checks.every(Boolean)) {
+                        skipCoolifySecrets = true;
+                        console.log(chalk.dim(`  · Skipping Coolify GH Actions secrets on --resume — all ${coolifySecretNames.length} already on ${slug}.`));
+                    }
+                }
+                if (!skipCoolifySecrets) {
+                    await setCoolifyDeploySecrets({
+                        projectDir: state.projectDir,
+                        repoSlug: slug,
+                        apps: [{ uuid: appUuidForSecrets }],
+                    });
+                }
             }
             else {
                 console.log(chalk.dim("  · Couldn't resolve owner/repo from git remote — set the deploy secrets manually."));
@@ -1296,21 +1478,26 @@ async function executePlan(state, plan, opts = { resume: false }) {
                 // we're the creator preserves the "destroy never deletes
                 // pre-existing user data" invariant — see LedgerStep doc.
                 const preExisted = await ghSecretExists(state.projectDir, slug, secretName);
-                try {
-                    await pushProjectKeyToGh(plan.name, slug);
-                    if (!preExisted) {
-                        ledger.record({ kind: "ghActionsSecret", repo: slug, name: secretName });
-                    }
+                if (opts.resume && preExisted) {
+                    console.log(chalk.dim(`  · Skipping ${secretName} push on --resume — secret already on ${slug}.`));
                 }
-                catch (err) {
-                    caveats.push({
-                        title: `${secretName} not set on GitHub Actions`,
-                        reason: err.message,
-                        recovery: [
-                            `hatchkit keys push ${plan.name} --target gh --repo ${slug}`,
-                            `(or copy from \`hatchkit keys show ${plan.name}\` and run \`gh secret set ${secretName} --repo ${slug} --body <key>\`)`,
-                        ],
-                    });
+                else {
+                    try {
+                        await pushProjectKeyToGh(plan.name, slug);
+                        if (!preExisted) {
+                            ledger.record({ kind: "ghActionsSecret", repo: slug, name: secretName });
+                        }
+                    }
+                    catch (err) {
+                        caveats.push({
+                            title: `${secretName} not set on GitHub Actions`,
+                            reason: err.message,
+                            recovery: [
+                                `hatchkit keys push ${plan.name} --target gh --repo ${slug}`,
+                                `(or copy from \`hatchkit keys show ${plan.name}\` and run \`gh secret set ${secretName} --repo ${slug} --body <key>\`)`,
+                            ],
+                        });
+                    }
                 }
             }
             else if (remoteUrl) {
@@ -1385,13 +1572,36 @@ async function executePlan(state, plan, opts = { resume: false }) {
                 });
             }
         }
-        // Step 3d: push the working branch to origin. Done AFTER secrets
-        // are set so the workflow's first run can hit the Coolify webhook
-        // without falling through to the "secret not set" branch. Skipped
-        // when there's no remote yet (e.g. user opted out of GitHub) or
-        // when origin already had history before adopt.
-        if (plan.setupGitHub && remoteUrl && !state.gitRemoteUrl) {
-            await pushInitialBranch(state.projectDir);
+        // Step 3d: push to origin so GitHub Actions builds + pushes the
+        // GHCR image. Done AFTER Coolify wiring + secrets so the workflow's
+        // first run can hit the redeploy webhook on its own.
+        //
+        // Two paths:
+        //   · Brand-new remote (this run just ran `gh repo create`) →
+        //     pushInitialBranch pushes the whole tree.
+        //   · Pre-existing remote → commitAndPushScaffold makes a
+        //     pathspec-scoped commit of just the files hatchkit wrote
+        //     (manifest + build-pipeline scaffold) and pushes it. Without
+        //     this push the workflow file lives only in the working tree,
+        //     Actions never fires, and the GHCR-wait below times out.
+        //
+        // `pushedThisRun` gates the GHCR step below — we only wait for a
+        // new image when a push actually went out.
+        let pushedThisRun = false;
+        if (remoteUrl) {
+            if (plan.setupGitHub && !state.gitRemoteUrl) {
+                pushedThisRun = await pushInitialBranch(state.projectDir);
+            }
+            else if (state.gitRemoteUrl) {
+                const result = await commitAndPushScaffold(state, {
+                    scaffoldedAbsPaths,
+                    overwrittenAbsPaths,
+                    manifestPath,
+                });
+                pushedThisRun = result.pushed;
+                if (result.caveat)
+                    caveats.push(result.caveat);
+            }
         }
         // Step 3e: GHCR setup. Two paths, gated on the user's earlier
         // public/private choice:
@@ -1414,7 +1624,25 @@ async function executePlan(state, plan, opts = { resume: false }) {
             remoteUrl &&
             coolifyResult !== undefined) {
             const slug = repoSlugFromRemote(remoteUrl);
-            if (slug) {
+            if (slug && !pushedThisRun && !plan.isPrivate) {
+                // No push went out (either nothing changed on disk this run,
+                // or the auto-commit-push failed). Without a push the
+                // build-and-deploy workflow doesn't run, so polling GHCR for
+                // a brand-new image would just time out. Defer the visibility
+                // PATCH to the next `--resume` once the user has pushed.
+                caveats.push({
+                    title: "GHCR visibility not set — no push triggered",
+                    reason: "Adopt didn't push to origin this run, so the build-and-deploy workflow hasn't been triggered to publish the GHCR image.",
+                    recovery: [
+                        "Commit + push so the workflow runs:",
+                        `  cd ${state.projectDir}`,
+                        `  git add . && git commit -m "chore: adopt hatchkit"`,
+                        `  git push`,
+                        "Then re-run: hatchkit adopt --resume",
+                    ],
+                });
+            }
+            else if (slug) {
                 const { makeGhcrPackagePublic, registerGhcrCredsWithCoolify } = await import("./deploy/ghcr.js");
                 if (plan.isPrivate) {
                     // Read the full GHCR config (token + the PAT owner's GitHub
@@ -1463,7 +1691,23 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // to a normal `hatchkit add`. Forward the surface choice — runProvision
         // uses the same vocabulary, so a client-only adopt produces a
         // client-only `add`.
-        if (plan.services.length > 0) {
+        //
+        // --resume contract: filter out services whose canonical env keys
+        // are already present in the target env files. Re-minting Resend
+        // keys / OpenPanel projects / Stripe webhooks on every resume
+        // orphans live credentials and rotates secrets the user didn't
+        // ask to rotate. The keychain caches some of these per-service,
+        // but those caches don't survive a fresh machine — the env file
+        // is the durable signal, so we trust it. A service is re-included
+        // if it's newly in `plan.services` (added since the last attempt)
+        // or its canonical env key is missing.
+        const resumeServices = filterServicesForResume({
+            services: plan.services,
+            resume: opts.resume === true,
+            serverEnvPath: plan.serverDir ? join(plan.serverDir, ".env.production") : null,
+            clientEnvPath: plan.clientDir ? join(plan.clientDir, ".env.production") : null,
+        });
+        if (resumeServices.length > 0) {
             console.log();
             const provisionMode = plan.surfaces === "both"
                 ? "shared"
@@ -1472,7 +1716,7 @@ async function executePlan(state, plan, opts = { resume: false }) {
                     : "client-only";
             await runProvision({
                 baseName: plan.name,
-                services: plan.services,
+                services: resumeServices,
                 surfaces: {
                     mode: provisionMode,
                     serverEnvDir: plan.serverDir,
@@ -1492,6 +1736,44 @@ async function executePlan(state, plan, opts = { resume: false }) {
                     else if (event.service === "resend") {
                         ledger.record({ kind: "resend", client: event.client });
                     }
+                    else if (event.service === "email") {
+                        // Email setup creates three kinds of mutable state on
+                        // Cloudflare: the destination address (account-scoped), the
+                        // forwarding rules (zone-scoped), and the apex MX/SPF/DMARC
+                        // records (also zone-scoped). We only record what THIS run
+                        // created — `destinationCreatedThisRun` and `r.created` /
+                        // `dnsRecords` (which the provision orchestrator already
+                        // pre-filtered to `created: true` entries). MX/SPF/DMARC
+                        // upserts on a zone that already had them stay out of the
+                        // ledger so destroy never yanks pre-existing records.
+                        if (event.destinationCreatedThisRun) {
+                            ledger.record({
+                                kind: "cloudflareEmailDestination",
+                                accountId: event.accountId,
+                                destinationId: event.destinationId,
+                                email: event.destinationEmail,
+                            });
+                        }
+                        for (const dns of event.dnsRecords) {
+                            ledger.record({
+                                kind: "cloudflareDnsRecord",
+                                zoneId: event.zoneId,
+                                recordId: dns.id,
+                                name: dns.name,
+                                type: dns.type,
+                            });
+                        }
+                        for (const rule of event.rules) {
+                            if (!rule.created)
+                                continue;
+                            ledger.record({
+                                kind: "cloudflareEmailRoutingRule",
+                                zoneId: event.zoneId,
+                                ruleId: rule.id,
+                                address: rule.address,
+                            });
+                        }
+                    }
                 },
             });
         }
@@ -1504,96 +1786,117 @@ async function executePlan(state, plan, opts = { resume: false }) {
         // (globally via `hatchkit config add s3 r2`, which re-pastes +
         // verifies it) and re-run `hatchkit provision s3` to finish.
         if (plan.features.includes("s3")) {
-            try {
-                const { provisionS3ForProject, defaultBucketHostname, existingCustomHostname } = await import("./provision/s3-buckets.js");
-                // Resolve the public assets-bucket custom domain. If a previous
-                // run already attached one, the manifest records it — reuse
-                // that without re-prompting. Only ask on first adopt (or when
-                // the manifest has no hostname yet, e.g. a previous run picked
-                // the managed r2.dev URL or never got that far). Blank answer →
-                // managed r2.dev.
-                let publicHostname;
-                const existingManifest = readManifest(state.projectDir);
-                const recordedHostname = existingManifest ? existingCustomHostname(existingManifest) : null;
-                if (recordedHostname) {
-                    publicHostname = recordedHostname;
-                }
-                else if (process.stdin.isTTY) {
-                    const answer = (await input({
-                        message: "Custom domain for the public assets bucket (leave empty to use the managed r2.dev URL):",
-                        default: defaultBucketHostname(plan.domain),
-                    })).trim();
-                    publicHostname = answer === "" ? null : answer;
-                }
-                // Only create the public assets bucket here. The private "state"
-                // bucket is an explicit opt-in even when the project has a
-                // server — most don't need it, and adding one silently means
-                // an extra R2 bucket + env var the user has to clean up later.
-                // Users who want one re-run `hatchkit provision s3 --with-state-bucket`.
-                const r = await provisionS3ForProject({
-                    projectDir: state.projectDir,
-                    publicHostname,
-                });
-                // Ledger: record any *fresh* bucket creations + a fresh token
-                // mint so destroy can revoke them. Reused buckets/tokens (from
-                // a prior adopt run) stay out — those are already in the
-                // earlier run's ledger or pre-existed before hatchkit ran.
-                if (r.assets.created) {
-                    ledger.record({
-                        kind: "r2Bucket",
-                        bucketName: r.assets.name,
-                        accountId: r.accountId,
-                    });
-                }
-                if (r.state?.created) {
-                    ledger.record({
-                        kind: "r2Bucket",
-                        bucketName: r.state.name,
-                        accountId: r.accountId,
+            // --resume gate: when the manifest already records the assets
+            // bucket AND .env.production has a working access/secret pair,
+            // there's nothing to provision. Skip the whole step rather than
+            // re-attaching custom domains / re-reconciling CORS / re-probing
+            // tokens, all of which are network round-trips with no payoff
+            // when nothing has changed since the last attempt.
+            const s3ManifestSnapshot = readManifest(state.projectDir);
+            const s3EnvPath = join(state.projectDir, ".env.production");
+            const s3EnvKeys = readEnvKeys(s3EnvPath);
+            const s3HasEnvCreds = (s3EnvKeys.has("R2_ACCESS_KEY_ID") && s3EnvKeys.has("R2_SECRET_ACCESS_KEY")) ||
+                (s3EnvKeys.has("S3_ACCESS_KEY_ID") && s3EnvKeys.has("S3_SECRET_ACCESS_KEY")) ||
+                (s3EnvKeys.has("AWS_ACCESS_KEY_ID") && s3EnvKeys.has("AWS_SECRET_ACCESS_KEY"));
+            const s3ManifestComplete = !!s3ManifestSnapshot?.s3Buckets?.assets?.name;
+            const s3AlreadyWired = opts.resume && s3HasEnvCreds && s3ManifestComplete;
+            if (s3AlreadyWired) {
+                console.log(chalk.dim(`  · Skipping S3 on --resume — manifest records ${s3ManifestSnapshot?.s3Buckets?.assets?.name} and .env.production has access/secret keys.`));
+            }
+            else {
+                try {
+                    const { provisionS3ForProject, defaultBucketHostname, existingCustomHostname } = await import("./provision/s3-buckets.js");
+                    // Resolve the public assets-bucket custom domain. If a previous
+                    // run already attached one, the manifest records it — reuse
+                    // that without re-prompting. Only ask on first adopt (or when
+                    // the manifest has no hostname yet, e.g. a previous run picked
+                    // the managed r2.dev URL or never got that far). Blank answer →
+                    // managed r2.dev.
+                    let publicHostname;
+                    const existingManifest = readManifest(state.projectDir);
+                    const recordedHostname = existingManifest
+                        ? existingCustomHostname(existingManifest)
+                        : null;
+                    if (recordedHostname) {
+                        publicHostname = recordedHostname;
+                    }
+                    else if (process.stdin.isTTY) {
+                        const answer = (await input({
+                            message: "Custom domain for the public assets bucket (leave empty to use the managed r2.dev URL):",
+                            default: defaultBucketHostname(plan.domain),
+                        })).trim();
+                        publicHostname = answer === "" ? null : answer;
+                    }
+                    // Only create the public assets bucket here. The private "state"
+                    // bucket is an explicit opt-in even when the project has a
+                    // server — most don't need it, and adding one silently means
+                    // an extra R2 bucket + env var the user has to clean up later.
+                    // Users who want one re-run `hatchkit provision s3 --with-state-bucket`.
+                    const r = await provisionS3ForProject({
+                        projectDir: state.projectDir,
+                        publicHostname,
                     });
+                    // Ledger: record any *fresh* bucket creations + a fresh token
+                    // mint so destroy can revoke them. Reused buckets/tokens (from
+                    // a prior adopt run) stay out — those are already in the
+                    // earlier run's ledger or pre-existed before hatchkit ran.
+                    if (r.assets.created) {
+                        ledger.record({
+                            kind: "r2Bucket",
+                            bucketName: r.assets.name,
+                            accountId: r.accountId,
+                        });
+                    }
+                    if (r.state?.created) {
+                        ledger.record({
+                            kind: "r2Bucket",
+                            bucketName: r.state.name,
+                            accountId: r.accountId,
+                        });
+                    }
+                    if (r.tokenCreated) {
+                        ledger.record({
+                            kind: "r2Token",
+                            tokenId: r.tokenCreated.tokenId,
+                            accountId: r.accountId,
+                            audience: r.tokenCreated.audience,
+                        });
+                    }
+                    console.log(chalk.green(`  ✓ S3 assets bucket ready — ${r.assets.publicUrl}`));
+                    console.log(chalk.dim(`    Wrote ${r.envWritten.length} encrypted entries. ` +
+                        "(Need a private server-side bucket too? Run `hatchkit provision s3 --with-state-bucket`.)"));
+                    // The fresh bucket is empty. Existing projects almost always
+                    // have assets sitting in some other store — surface the one
+                    // command that copies them in. Cheap line to print, easy to
+                    // miss without it.
+                    console.log(chalk.dim(`    Have existing assets to bring over? hatchkit assets migrate \\\n` +
+                        `      --from-endpoint=<old-s3-endpoint> --from-bucket=<name> \\\n` +
+                        `      --from-key=<access-key> --from-secret=<secret>`));
                 }
-                if (r.tokenCreated) {
-                    ledger.record({
-                        kind: "r2Token",
-                        tokenId: r.tokenCreated.tokenId,
-                        accountId: r.accountId,
-                        audience: r.tokenCreated.audience,
+                catch (err) {
+                    console.log(chalk.yellow(`\n  ✗ S3 bucket provisioning failed: ${err.message.split("\n")[0]}`));
+                    // Two kinds of recovery — pick based on whether the underlying
+                    // error looks like an admin-token problem (global) vs. a
+                    // bucket-side problem (per-project). Admin-token failures point
+                    // the user at the global config command (which validates the
+                    // token); everything else points at the per-project re-runner.
+                    const msg = err.message;
+                    const isAdminTokenIssue = /admin token|invalid api token|9109|10000|10001|HTTP 401|HTTP 403/i.test(msg);
+                    caveats.push({
+                        title: "S3 buckets not provisioned",
+                        reason: msg,
+                        recovery: isAdminTokenIssue
+                            ? [
+                                "Looks like an R2 admin-token problem.",
+                                "Fix globally with: hatchkit config add s3 r2  (re-paste + verify perms)",
+                                `Then re-run from the project dir: cd ${plan.name} && hatchkit provision s3`,
+                            ]
+                            : [
+                                "Once fixed, finish with: hatchkit provision s3",
+                                "(safe to re-run — bucket creation and env writes are idempotent)",
+                            ],
                     });
                 }
-                console.log(chalk.green(`  ✓ S3 assets bucket ready — ${r.assets.publicUrl}`));
-                console.log(chalk.dim(`    Wrote ${r.envWritten.length} encrypted entries. ` +
-                    "(Need a private server-side bucket too? Run `hatchkit provision s3 --with-state-bucket`.)"));
-                // The fresh bucket is empty. Existing projects almost always
-                // have assets sitting in some other store — surface the one
-                // command that copies them in. Cheap line to print, easy to
-                // miss without it.
-                console.log(chalk.dim(`    Have existing assets to bring over? hatchkit assets migrate \\\n` +
-                    `      --from-endpoint=<old-s3-endpoint> --from-bucket=<name> \\\n` +
-                    `      --from-key=<access-key> --from-secret=<secret>`));
-            }
-            catch (err) {
-                console.log(chalk.yellow(`\n  ✗ S3 bucket provisioning failed: ${err.message.split("\n")[0]}`));
-                // Two kinds of recovery — pick based on whether the underlying
-                // error looks like an admin-token problem (global) vs. a
-                // bucket-side problem (per-project). Admin-token failures point
-                // the user at the global config command (which validates the
-                // token); everything else points at the per-project re-runner.
-                const msg = err.message;
-                const isAdminTokenIssue = /admin token|invalid api token|9109|10000|10001|HTTP 401|HTTP 403/i.test(msg);
-                caveats.push({
-                    title: "S3 buckets not provisioned",
-                    reason: msg,
-                    recovery: isAdminTokenIssue
-                        ? [
-                            "Looks like an R2 admin-token problem.",
-                            "Fix globally with: hatchkit config add s3 r2  (re-paste + verify perms)",
-                            `Then re-run from the project dir: cd ${plan.name} && hatchkit provision s3`,
-                        ]
-                        : [
-                            "Once fixed, finish with: hatchkit provision s3",
-                            "(safe to re-run — bucket creation and env writes are idempotent)",
-                        ],
-                });
             }
         }
         // Step 4c: Stripe — strictly separate from `create`'s Stripe block
@@ -1620,55 +1923,69 @@ async function executePlan(state, plan, opts = { resume: false }) {
                     });
                 }
                 else {
-                    const result = await provisionStripeProject({
-                        projectName: plan.name,
-                        domain: plan.domain,
-                    });
+                    // --resume gate: if Stripe keys are already encrypted in
+                    // .env.production AND set in .env.development, the env is
+                    // wired — skip the provisioner entirely. Re-running it on
+                    // a cache miss (e.g. fresh machine) would reprompt for the
+                    // sk/pk and re-create the webhook endpoint, leaving the
+                    // old endpoint orphaned in the user's Stripe dashboard.
                     const devEnvPath = join(plan.serverDir, ".env.development");
                     const prodEnvPath = join(plan.serverDir, ".env.production");
-                    const devLabel = relative(state.projectDir, devEnvPath);
-                    const prodLabel = relative(state.projectDir, prodEnvPath);
-                    if (result.test) {
-                        if (result.test.kind === "skipped") {
-                            appendCommentBlock(devEnvPath, renderStripeSkipComment("test", devLabel));
-                        }
-                        const pairs = parseEnvLines(renderStripeEnv(result.test));
-                        writeDevEnv(devEnvPath, pairs);
-                        if (result.test.kind === "configured") {
-                            ledger.record({
-                                kind: "keychain",
-                                account: SECRET_KEYS.stripeProjectWebhookId(plan.name, "test"),
-                            });
-                        }
-                        console.log(chalk.green(result.test.kind === "skipped"
-                            ? `  ✓ Stripe sandbox placeholders → ${devLabel} (fill in later)`
-                            : `  ✓ Stripe sandbox creds → ${devLabel} (${pairs.length} keys)`));
+                    const stripeAlreadyWired = opts.resume &&
+                        readEnvKeys(prodEnvPath).has("STRIPE_SECRET_KEY") &&
+                        readEnvKeys(devEnvPath).has("STRIPE_SECRET_KEY");
+                    if (stripeAlreadyWired) {
+                        console.log(chalk.dim(`  · Skipping Stripe on --resume — STRIPE_SECRET_KEY present in both .env.production and .env.development.`));
                     }
-                    if (result.live) {
-                        if (result.live.kind === "skipped") {
-                            appendCommentBlock(prodEnvPath, renderStripeSkipComment("live", prodLabel));
+                    else {
+                        const result = await provisionStripeProject({
+                            projectName: plan.name,
+                            domain: plan.domain,
+                        });
+                        const devLabel = relative(state.projectDir, devEnvPath);
+                        const prodLabel = relative(state.projectDir, prodEnvPath);
+                        if (result.test) {
+                            if (result.test.kind === "skipped") {
+                                appendCommentBlock(devEnvPath, renderStripeSkipComment("test", devLabel));
+                            }
+                            const pairs = parseEnvLines(renderStripeEnv(result.test));
+                            writeDevEnv(devEnvPath, pairs);
+                            if (result.test.kind === "configured") {
+                                ledger.record({
+                                    kind: "keychain",
+                                    account: SECRET_KEYS.stripeProjectWebhookId(plan.name, "test"),
+                                });
+                            }
+                            console.log(chalk.green(result.test.kind === "skipped"
+                                ? `  ✓ Stripe sandbox placeholders → ${devLabel} (fill in later)`
+                                : `  ✓ Stripe sandbox creds → ${devLabel} (${pairs.length} keys)`));
                         }
-                        const pairs = parseEnvLines(renderStripeEnv(result.live));
-                        writeProdEnv(prodEnvPath, pairs);
-                        if (result.live.kind === "configured") {
-                            ledger.record({
-                                kind: "keychain",
-                                account: SECRET_KEYS.stripeProjectWebhookId(plan.name, "live"),
+                        if (result.live) {
+                            if (result.live.kind === "skipped") {
+                                appendCommentBlock(prodEnvPath, renderStripeSkipComment("live", prodLabel));
+                            }
+                            const pairs = parseEnvLines(renderStripeEnv(result.live));
+                            writeProdEnv(prodEnvPath, pairs);
+                            if (result.live.kind === "configured") {
+                                ledger.record({
+                                    kind: "keychain",
+                                    account: SECRET_KEYS.stripeProjectWebhookId(plan.name, "live"),
+                                });
+                            }
+                            console.log(chalk.green(result.live.kind === "skipped"
+                                ? `  ✓ Stripe live placeholders → ${prodLabel} (encrypted CHANGE_ME values, fill in later)`
+                                : `  ✓ Stripe live creds → ${prodLabel} (encrypted, ${pairs.length} keys)`));
+                        }
+                        if (!result.test && !result.live) {
+                            caveats.push({
+                                title: "Stripe wiring skipped",
+                                reason: "No Stripe master key configured — neither test nor live mode could be wired.",
+                                recovery: [
+                                    "Run `hatchkit config add stripe` to add at least one master key,",
+                                    `then re-run \`hatchkit adopt --resume\` from ${state.projectDir}.`,
+                                ],
                             });
                         }
-                        console.log(chalk.green(result.live.kind === "skipped"
-                            ? `  ✓ Stripe live placeholders → ${prodLabel} (encrypted CHANGE_ME values, fill in later)`
-                            : `  ✓ Stripe live creds → ${prodLabel} (encrypted, ${pairs.length} keys)`));
-                    }
-                    if (!result.test && !result.live) {
-                        caveats.push({
-                            title: "Stripe wiring skipped",
-                            reason: "No Stripe master key configured — neither test nor live mode could be wired.",
-                            recovery: [
-                                "Run `hatchkit config add stripe` to add at least one master key,",
-                                `then re-run \`hatchkit adopt --resume\` from ${state.projectDir}.`,
-                            ],
-                        });
                     }
                 }
             }
@@ -1942,6 +2259,267 @@ async function ensureEnvProductionCommitted(state, plan) {
             `      git -C ${relativeTo(state.projectDir)} commit -m "chore(dotenvx): commit encrypted .env.production" -- ${relativeTo(prodPath, state.projectDir)}`));
     }
 }
+/**
+ * Sniff the working tree for state that would make auto-commit + push
+ * surprising or destructive. We refuse to touch git when:
+ *
+ *   · A merge / rebase / cherry-pick / revert / bisect is in progress
+ *     — adopt isn't allowed to add commits on top of half-resolved
+ *     conflicts.
+ *   · Any tracked file *outside* hatchkit's path list has unstaged or
+ *     staged changes. Even though the commit itself is pathspec-scoped
+ *     (so the user's modifications wouldn't be swept in), the push
+ *     would still land hatchkit's commit on top of the user's WIP on
+ *     the same branch — entangling their unpushed work with the
+ *     hatchkit commit on origin. Make them park or commit it first.
+ *
+ * Untracked files (status `??`) are deliberately ignored — they're
+ * common debris (editor swaps, build artifacts not in gitignore, etc.)
+ * and never end up in our pathspec commit anyway.
+ */
+async function detectUserWip(projectDir, hatchkitAbsPaths) {
+    // In-progress operations: probe the .git dir for marker files. We
+    // resolve --git-dir via git itself so this works in worktrees (where
+    // .git is a file, not a directory) and submodules.
+    const gitDirRes = await exec("git", ["rev-parse", "--git-dir"], {
+        cwd: projectDir,
+        silent: true,
+    });
+    if (gitDirRes.exitCode === 0) {
+        const raw = gitDirRes.stdout.trim();
+        const gitDir = raw.startsWith("/") ? raw : join(projectDir, raw);
+        const markers = [
+            ["MERGE_HEAD", "merge"],
+            ["CHERRY_PICK_HEAD", "cherry-pick"],
+            ["REVERT_HEAD", "revert"],
+            ["rebase-merge", "rebase"],
+            ["rebase-apply", "rebase"],
+            ["BISECT_LOG", "bisect"],
+        ];
+        for (const [marker, op] of markers) {
+            if (existsSync(join(gitDir, marker)))
+                return { kind: "in-progress", op };
+        }
+    }
+    // Repo-root-relative path matching. `git status --porcelain` emits
+    // paths relative to the repo root, not necessarily our cwd, so we
+    // normalize hatchkit's absolute paths the same way before comparing.
+    const rootRes = await exec("git", ["rev-parse", "--show-toplevel"], {
+        cwd: projectDir,
+        silent: true,
+    });
+    if (rootRes.exitCode !== 0) {
+        return { kind: "error", reason: "git rev-parse --show-toplevel failed" };
+    }
+    const repoRoot = rootRes.stdout.trim();
+    const hatchkitRelToRoot = new Set(hatchkitAbsPaths.map((p) => relative(repoRoot, p)));
+    const status = await exec("git", ["status", "--porcelain", "--untracked-files=no"], {
+        cwd: projectDir,
+        silent: true,
+    });
+    if (status.exitCode !== 0) {
+        return { kind: "error", reason: "git status failed" };
+    }
+    const userFiles = [];
+    for (const line of status.stdout.split("\n")) {
+        if (line.length < 4)
+            continue;
+        const code = line.slice(0, 2);
+        let rest = line.slice(3);
+        // Renames/copies show up as "OLD -> NEW". We want the new path.
+        if (rest.includes(" -> "))
+            rest = rest.split(" -> ").pop() ?? rest;
+        // Git quotes paths with special chars in C-style. If a path is
+        // quoted we conservatively treat it as user WIP rather than try
+        // to unquote and risk a false negative.
+        const path = rest.startsWith('"') && rest.endsWith('"') ? rest.slice(1, -1) : rest;
+        if (!hatchkitRelToRoot.has(path)) {
+            userFiles.push({ status: code, path });
+        }
+    }
+    if (userFiles.length > 0)
+        return { kind: "user-changes", files: userFiles };
+    return { kind: "ok" };
+}
+/**
+ * Commit + push the files hatchkit wrote this run (manifest +
+ * scaffolded build pipeline) to a pre-existing remote so the
+ * build-and-deploy workflow fires.
+ *
+ * Pathspec-scoped on purpose: a plain `git add -A` would sweep up
+ * whatever WIP the user happened to have in the working tree —
+ * surprising behavior for an adopt. By listing only the paths
+ * hatchkit just wrote, the resulting commit is exactly "the adopt
+ * step", and anything else stays staged in the user's hands.
+ *
+ * Hard-stops with a caveat when `detectUserWip` finds unrelated user
+ * changes or an in-progress git operation. The push would otherwise
+ * land hatchkit's commit on top of WIP that isn't part of adopt — a
+ * surprise we explicitly refuse to do.
+ *
+ * Returns `{ pushed: false }` (no caveat) for the idempotent case —
+ * everything hatchkit wrote was already byte-identical to HEAD, so
+ * there was nothing to push. Failures during commit/push surface as
+ * a caveat with a copy-pasteable manual recipe.
+ */
+async function commitAndPushScaffold(state, paths) {
+    const all = [
+        ...paths.scaffoldedAbsPaths,
+        ...paths.overwrittenAbsPaths,
+        paths.manifestPath,
+    ].filter((p, i, arr) => arr.indexOf(p) === i && existsSync(p));
+    if (all.length === 0)
+        return { pushed: false };
+    // Hard stop: refuse to auto-commit on top of in-progress git ops
+    // or unrelated user changes. See detectUserWip docstring for the
+    // exact policy.
+    const wip = await detectUserWip(state.projectDir, all);
+    if (wip.kind === "in-progress") {
+        return {
+            pushed: false,
+            caveat: {
+                title: `Refusing to auto-commit — git ${wip.op} in progress`,
+                reason: `A ${wip.op} is in progress in ${state.projectDir}. Adopt won't stack commits on top of half-resolved git state.`,
+                recovery: [
+                    `Finish or abort the ${wip.op}, then re-run adopt:`,
+                    wip.op === "rebase"
+                        ? `  git rebase --continue   # or: git rebase --abort`
+                        : `  git ${wip.op} --abort   # or finish it manually and commit`,
+                    "Then: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    if (wip.kind === "user-changes") {
+        const preview = wip.files.slice(0, 8).map((f) => `    ${f.status} ${f.path}`);
+        const extra = wip.files.length > 8 ? [`    ... and ${wip.files.length - 8} more`] : [];
+        return {
+            pushed: false,
+            caveat: {
+                title: "Refusing to auto-commit — working tree has unrelated changes",
+                reason: `Found ${wip.files.length} modified file(s) outside the hatchkit scaffold. Auto-committing + pushing now would land the adopt commit on top of WIP that isn't part of the adopt step.`,
+                recovery: [
+                    "Hatchkit wanted to commit + push these files:",
+                    ...all.map((p) => `    + ${relativeTo(p, state.projectDir)}`),
+                    "",
+                    "Your working tree also has changes to:",
+                    ...preview,
+                    ...extra,
+                    "",
+                    "Park, commit, or discard your WIP first — whichever fits:",
+                    `  git stash push -u -m "pre-hatchkit-adopt"   # park on the side`,
+                    `  # or: git add . && git commit -m "..."        # keep in history`,
+                    `  # or: git checkout -- <file>                 # discard a file`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    if (wip.kind === "error") {
+        return {
+            pushed: false,
+            caveat: {
+                title: "Refusing to auto-commit — couldn't verify a clean working tree",
+                reason: `Working-tree detection failed: ${wip.reason}. Adopt won't auto-commit without knowing what else is in the tree.`,
+                recovery: [
+                    "Commit + push the scaffold manually:",
+                    `  cd ${state.projectDir}`,
+                    `  git add ${all.map((p) => relativeTo(p, state.projectDir)).join(" ")}`,
+                    `  git commit -m "chore(hatchkit): adopt scaffold + manifest"`,
+                    `  git push`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    // Definitive pre-commit notice. The user opted into adopt, but an
+    // auto-commit-and-push on a pre-existing remote is a meaningful
+    // side effect — they should see exactly what's happening before it
+    // lands on origin.
+    console.log();
+    console.log(chalk.bold.yellow("  ⚠ hatchkit is about to commit + push to origin:"));
+    for (const p of all) {
+        console.log(chalk.yellow(`      + ${relativeTo(p, state.projectDir)}`));
+    }
+    console.log(chalk.dim("    (working tree verified clean of unrelated changes — auto-commit is safe)"));
+    console.log();
+    // Pathspec stage: only the hatchkit-owned files. `--` separates
+    // pathspecs from refs so a file named "main" doesn't get confused
+    // for a branch.
+    const stage = await exec("git", ["add", "--", ...all], {
+        cwd: state.projectDir,
+        silent: true,
+    });
+    if (stage.exitCode !== 0) {
+        return {
+            pushed: false,
+            caveat: {
+                title: "Couldn't stage hatchkit scaffold for commit",
+                reason: (stage.stderr || stage.stdout).split(/\r?\n/)[0] || "git add failed",
+                recovery: [
+                    "Stage + commit + push manually so the workflow runs:",
+                    `  cd ${state.projectDir}`,
+                    `  git add ${all.map((p) => relativeTo(p, state.projectDir)).join(" ")}`,
+                    `  git commit -m "chore(hatchkit): adopt scaffold + manifest"`,
+                    `  git push`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    // Nothing in the staged index means every file was byte-identical
+    // to HEAD — this is the idempotent re-run case. No push needed.
+    const cleanStaged = await execOk("git", ["diff", "--cached", "--quiet"], {
+        cwd: state.projectDir,
+    });
+    if (cleanStaged)
+        return { pushed: false };
+    // Pathspec on the commit too — anything else the user happened to
+    // stage themselves before running adopt stays out of this commit.
+    const commit = await exec("git", ["commit", "-m", "chore(hatchkit): adopt scaffold + manifest", "--", ...all], { cwd: state.projectDir, silent: true });
+    if (commit.exitCode !== 0) {
+        return {
+            pushed: false,
+            caveat: {
+                title: "Couldn't commit hatchkit scaffold automatically",
+                reason: (commit.stderr || commit.stdout).split(/\r?\n/)[0] || "git commit failed",
+                recovery: [
+                    "Commit + push the scaffold manually:",
+                    `  cd ${state.projectDir}`,
+                    `  git commit -m "chore(hatchkit): adopt scaffold + manifest" -- ${all.map((p) => relativeTo(p, state.projectDir)).join(" ")}`,
+                    `  git push`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    console.log(chalk.green(`  ✓ Committed hatchkit scaffold (${all.length} files)`));
+    const headRes = await exec("git", ["symbolic-ref", "--short", "HEAD"], {
+        cwd: state.projectDir,
+        silent: true,
+    });
+    const branch = headRes.exitCode === 0 ? headRes.stdout.trim() : "main";
+    const push = await exec("git", ["push", "origin", branch], {
+        cwd: state.projectDir,
+        spinner: `Pushing ${branch} to origin...`,
+    });
+    if (push.exitCode !== 0) {
+        return {
+            pushed: false,
+            caveat: {
+                title: `Couldn't push ${branch} to origin`,
+                reason: (push.stderr || push.stdout).split(/\r?\n/)[0] || `git push exited ${push.exitCode}`,
+                recovery: [
+                    "Push the new commit so Actions can build the image:",
+                    `  cd ${state.projectDir}`,
+                    `  git push origin ${branch}`,
+                    "Then re-run: hatchkit adopt --resume",
+                ],
+            },
+        };
+    }
+    return { pushed: true };
+}
 async function setupGitHubRemote(state, plan) {
     // Pre-flight gh CLI auth. ensureGitHub prompts the user to log in
     // when needed; if they cancel, surface a clear "you can do this
@@ -2092,8 +2670,11 @@ async function listStagedFiles(cwd) {
  *  noting which files already exist (will be left alone) vs which
  *  will be scaffolded. */
 function renderBuildPipelineSummary(state, plan) {
-    if (!plan.scaffoldBuildPipeline)
-        return chalk.dim("no — leave files as-is");
+    if (!plan.scaffoldBuildPipeline) {
+        return state.unknownWorkspaceLayout
+            ? chalk.dim("no — unrecognised workspace layout, hand-author your own")
+            : chalk.dim("no — leave files as-is");
+    }
     const pipe = detectBuildPipeline(state.projectDir);
     const willWrite = [];
     const kept = [];
@@ -2113,7 +2694,13 @@ function renderBuildPipelineSummary(state, plan) {
         return chalk.dim("all files already present — nothing to write");
     const writePart = `write ${willWrite.join(", ")}`;
     const keepPart = kept.length > 0 ? chalk.dim(` · keep ${kept.join(", ")}`) : "";
-    return `${writePart}${keepPart}`;
+    // Strong warning when the user has overridden the unknown-layout
+    // default. We still write the files (their call), but flag that the
+    // templates' single-package assumption probably doesn't fit this repo.
+    const layoutWarn = state.unknownWorkspaceLayout
+        ? `  ${chalk.yellow("(unrecognised workspace — templates may build the wrong thing)")}`
+        : "";
+    return `${writePart}${keepPart}${layoutWarn}`;
 }
 function detectDockerComposeDomainServiceName(projectDir, surfaces) {
     const pipe = detectBuildPipeline(projectDir);