diff --git a/README.md b/README.md
index 5285ec8..b64bfdf 100644
--- a/README.md
+++ b/README.md
@@ -91,8 +91,8 @@ is available to every v2 command. `login`, `logout`, `whoami`, and global
 Create API keys for automation or other non-interactive clients. Keys belong to a
 user and carry explicit capabilities; use the smallest capability set the task
 needs. The `--workspace` option further restricts Kubernetes access to one
-workspace. Capabilities describe *what* the key may do, while workspace scope
-describes *where* its Kubernetes access applies; neither replaces the other.
+workspace. Capabilities describe _what_ the key may do, while workspace scope
+describes _where_ its Kubernetes access applies; neither replaces the other.
 
 Valid capabilities are `kubernetes:read`, `kubernetes:write`,
 `kubernetes:exec`, `users:read`, `users:write`, `sessions:revoke`, and
@@ -458,6 +458,123 @@ your shell configuration. Fish and PowerShell are also supported through
 Lifecycle commands (`restart`, `stop`, `rollback`, `down`) are idempotent:
 identical requests are deduplicated server-side and tracked as operations.
 
+When an API response advertises a newer kuber version, the CLI quietly starts a
+cross-platform install with the current runtime's package manager and inherited
+environment. The CLI waits for the result, bounded by 30 seconds, and reports
+whether the update succeeded or a new version remains available. It does not
+replay the command; rerun it yourself if needed.
+
+### Initialize a project or add an app
+
+`kuber init` creates a project Compose file and adds its first app. In an empty
+directory, the default app uses `nginx:stable` as its image; initialization
+always adds a service. Choose a different source or image with the app options:
+
+```bash
+kuber init
+kuber init --project my-site --name web --path apps/web --source image --image nginx:stable
+```
+
+With an interactive terminal, `init` prompts for missing project and app
+details, and its default flow logs in automatically when needed. The project
+trust is granted for the current directory as part of initialization, so a
+first `kuber up` can proceed without separately running `kuber trust`. Use
+`--non-interactive` to disable prompts; provide required values as flags. The
+project name is optional and defaults from the current project context. If
+project configuration already fixes a project name, `--project` must match it.
+
+`kuber add app` adds another service to an existing project without replacing
+existing services. Its syntax and the shared app options are:
+
+```text
+kuber add app [--name <name>] [--path <path>]
+  [--source image|auto|template] [--image <image>] [--template <template>]
+  [--postgres <claim>] [--s3 <claim>] [--cpu <cores>] [--memory <limit>]
+  [--replicas <count>] [--non-interactive]
+```
+
+`kuber init` accepts the same app options, plus `--project <name>` for the
+Kubernetes namespace/project name and `--config-path <path>` for the project
+config file (normally set through the global `--config` option).
+
+For example, add an app using a published starter image:
+
+```bash
+kuber add app --name web --path apps/web --source image --image nginx:stable --non-interactive
+```
+
+In interactive mode, omitted values are prompted for. The app path is chosen
+from detected app roots when there is exactly one; when there are several, the
+prompt asks you to select one. Supply `--path` to select a subproject explicitly.
+Non-interactive mode never prompts: supply values needed for the selected
+source, and for multiple detected roots explicitly supply `--path`. With no
+detected app roots the path defaults to `.`. If no source is supplied, a
+repository with detected app roots defaults to `auto`; otherwise it defaults to
+`image` (`nginx:stable`). Optional Postgres/S3 claims and CPU, memory, and
+replica settings can be provided by flags or interactively.
+
+#### App sources
+
+- `--source image --image <image>` deploys an existing image, with no build.
+- `--source template --template <id>` writes an embedded Dockerfile and
+  `.dockerignore` into the selected app directory and configures a Dockerfile
+  build. The eight template IDs are `bun-service`, `bun-next`, `bun-compiled`,
+  `node-pnpm`, `python-web`, `go-static`, `rust-static`, and `static-nginx`.
+  For example, `--template static-nginx` scaffolds a static-site Dockerfile
+  that copies `dist/` into nginx.
+- `--source auto` configures `build: auto`. **This always uses CNB Buildpacks**;
+  kuber does not inspect or use a Dockerfile for this source, and there is no
+  fallback to BuildKit. The Dockerfile path for ordinary Dockerfile builds is
+  left unchanged.
+- Compose may also set `build: auto:<release-url>` to use a custom buildpack:
+  the URL must be an HTTPS GitHub release `.cnb` asset, optionally followed by
+  `#sha256=<64-lowercase-hex>` to verify its SHA-256 digest. Without a pin, the
+  release URL is mutable and the bytes it serves may change between builds.
+  For an ARM64 Linux build, substitute the publisher's GitHub repository in
+  this v1.0.0 release-asset URL pattern:
+
+  ```yaml
+  services:
+    web:
+      build: auto:https://github.com/OWNER/REPO/releases/download/v1.0.0/buildpack-bun.cnb
+      platform: linux/arm64
+  ```
+
+  Only GitHub release URLs are accepted; redirects are allowed only to
+  `release-assets.githubusercontent.com`. A package must contain a single-image
+  or layer buildpack using Buildpack API `0.10`, with a target matching the
+  build's Linux architecture (`amd64` or `arm64`). Custom buildpack code runs in
+  the build Job with access to the workspace, so only use artifacts from sources
+  you trust. Configuring a release URL does not claim or guarantee a successful
+  live build.
+
+`build: auto` requires the app to be inside a Git repository. Kuber sends the
+Git worktree files selected by Git, excluding paths matched by `.gitignore`;
+that filtering also excludes tracked files that currently match ignore rules.
+`.dockerignore` does not govern this workspace selection. When the app is a
+subproject, kuber sets `x-kuber-build-context` to that selected app directory so
+Buildpacks builds from the subproject rather than the repository root.
+
+The server runs a pinned, multi-architecture Buildpacks builder. The configured
+registry must be usable for the build output and cache, and the server must have
+the credentials and registry access needed to push and resolve the image. Extra
+`build.tags` are supported only when they name additional output tags in the
+same registry; cross-registry output destinations are not supported. Buildpacks
+does not support Dockerfile-specific behavior such as selecting a Dockerfile,
+target stage, or BuildKit options.
+
+#### Compose marker
+
+Kuber-created Compose files begin with this literal line:
+
+```yaml
+managedBy: kuber # See https://npmx.dev/@dmgnr/kuber for documentation.
+```
+
+This marker identifies the file as kuber-managed. It is intentional, but it is
+not part of the ordinary Docker Compose schema: running `docker compose` on the
+file directly will reject it. Use kuber to read and deploy this project.
+
 ## Configuration
 
 Kuber optionally loads `.kuberrc.ts` from the working directory. The file must
@@ -799,6 +916,10 @@ without rebuilding, and fail if a buildable service has no published image yet.
 (because it cannot call the server to generate credentials) and instead tells
 you to run `kuber up` or remove the managed provider claims.
 
+During `kuber up`, context-upload progress is shown as one aggregate task. It
+deduplicates shared blobs across build workspaces and includes bytes already
+present from resumed uploads.
+
 ## Rollback
 
 `kuber rollback [deployment]` (alias `fuck`) rewinds managed Deployments to the
diff --git a/changelogs/2.7.0.md b/changelogs/2.7.0.md
new file mode 100644
index 0000000..3873d17
--- /dev/null
+++ b/changelogs/2.7.0.md
@@ -0,0 +1,37 @@
+# 2.7.0-rc2
+
+- Simplify the cross-platform passive updater with explicit inherited environment and `process.execPath`, a bounded wait for the install outcome before CLI exit, and no TTY workaround or external timeout helper.
+- Show aggregate context-upload progress in an `Uploading context` child task, deduplicating shared blobs and accounting for resumed uploads.
+- Support `build: auto:<GitHub HTTPS .cnb URI>` with optional `#sha256=<hex>` pinning. The real `kilterset/bun` 1.0.0 package was fetched and validated for Linux ARM64; its architecture mismatch was correctly rejected for AMD64.
+- Live CNB Kubernetes Job execution and registry push remain unverified.
+
+# 2.7.0-rc1
+
+## Added
+
+- Add `kuber init` to create `compose.yml` with a first app, log in when needed, and register trust for the current directory. Add `kuber add app` to insert another service into an existing project while preserving existing services and YAML content.
+- Support interactive and non-interactive scaffolding with app-root detection, image, Buildpacks, or Dockerfile-template sources, Postgres/S3 claims, resource limits, and replicas.
+- Bundle eight Dockerfile and `.dockerignore` templates: `bun-service`, `bun-next`, `bun-compiled`, `node-pnpm`, `python-web`, `go-static`, `rust-static`, and `static-nginx`.
+- Support bare `build: auto` through CNB Buildpacks, including subproject contexts through `x-kuber-build-context`. Auto builds require Git and use Git-selected worktree files with `.gitignore` filtering, including tracked files matched by ignore rules; `.dockerignore` does not control this selection.
+- Support `build: auto:<URI>` for an HTTPS GitHub release `.cnb` package, optionally pinned with `#sha256=<hex>`, with server-side package staging, digest verification, and target-architecture validation.
+
+## Changed
+
+- Begin generated Compose files with `managedBy: kuber # See https://npmx.dev/@dmgnr/kuber for documentation.` and accept the marker in kuber's Compose schema.
+- Show aggregate context-upload bytes and percentage as a separate task during `kuber up`, deduplicating shared blobs across workspaces and accounting for resumed uploads.
+- Simplify the passive updater to launch the current Bun executable with the inherited runtime environment, without Linux terminal helpers or an external `timeout` command. Wait for the bounded install outcome and its success or available-version notice before CLI exit; suppress automatic installs in tests and source-tree development.
+
+## Fixed
+
+- Validate scaffold paths and options, refuse to overwrite existing generated files, detect concurrent Compose edits, and roll back newly generated files on failures. Initialization preserves files needed to repair local trust after successful remote registration.
+- Reject potential credential files selected for auto-build snapshots and require unsafe paths to be excluded through `.gitignore`.
+- Reject symlinked workspace parents and unsafe snapshot symlink traversal; validate server-side symlink chains and cycles before materialization.
+- Remove malformed or expired session files, including sessions with invalid expiry timestamps.
+- Bound registry manifest reads, validate supported manifest structure, verify advertised digests against the response bytes, and avoid exposing registry error-response bodies.
+- Reject unknown top-level Compose properties while retaining supported fields and `x-` extensions.
+
+## Release notes
+
+- Auto builds always use CNB Buildpacks, even when a Dockerfile exists; there is no BuildKit fallback. Ordinary Dockerfile builds retain the BuildKit path.
+- The `managedBy` marker is kuber-specific; ordinary `docker compose` rejects generated files containing it.
+- Live CNB Kubernetes Job execution and registry push have not been verified for this release candidate.
diff --git a/command/add.ts b/command/add.ts
new file mode 100644
index 0000000..c519147
--- /dev/null
+++ b/command/add.ts
@@ -0,0 +1,238 @@
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { basename } from "node:path";
+import { defineCommand } from "citty";
+import { ctx } from "../lib/context";
+import {
+  addAppToCompose,
+  checkedAppPath,
+  detectAppPaths,
+  type AppOptions,
+  type Source,
+} from "../lib/scaffold";
+import {
+  listDockerfileTemplates,
+  templateIds,
+} from "../lib/scaffold-templates";
+
+export type ScaffoldPrompt = (
+  question: string,
+  defaultValue?: string,
+) => Promise<string>;
+
+export const terminalPrompt: ScaffoldPrompt = async (
+  question,
+  defaultValue,
+) => {
+  if (!stdin.isTTY)
+    throw new Error(`${question}: supply flags or use an interactive terminal`);
+  const readline = createInterface({ input: stdin, output: stdout });
+  try {
+    const result = (
+      await readline.question(
+        `${question}${defaultValue ? ` [${defaultValue}]` : ""}: `,
+      )
+    ).trim();
+    return result || defaultValue || "";
+  } finally {
+    readline.close();
+  }
+};
+
+export type AppInput = Partial<Omit<AppOptions, "source">> & {
+  source?: "image" | "auto" | "template";
+  image?: string;
+  template?: string;
+  nonInteractive?: boolean;
+};
+
+async function answer(
+  value: string | undefined,
+  question: string,
+  fallback: string | undefined,
+  prompt: ScaffoldPrompt,
+  nonInteractive: boolean,
+): Promise<string> {
+  if (value !== undefined) return value;
+  if (nonInteractive) {
+    if (fallback !== undefined) return fallback;
+    throw new Error(`${question} is required in non-interactive mode`);
+  }
+  return prompt(question, fallback);
+}
+
+export async function resolveAppInput(
+  root: string,
+  input: AppInput,
+  prompt: ScaffoldPrompt = terminalPrompt,
+): Promise<AppOptions> {
+  const detected = await detectAppPaths(root);
+  let path: string;
+  if (input.path !== undefined) path = input.path;
+  else if (detected.length === 0) path = ".";
+  else if (detected.length === 1) path = detected[0]!;
+  else {
+    if (input.nonInteractive)
+      throw new Error(
+        `Multiple app roots found (${detected.join(", ")}); specify --path`,
+      );
+    path = await prompt(`App path (${detected.join(", ")})`);
+    if (!detected.includes(path))
+      throw new Error(
+        `Select one of the detected app roots: ${detected.join(", ")}`,
+      );
+  }
+  path = await checkedAppPath(root, path);
+  const suggestedName =
+    basename(path === "." ? root : path)
+      .toLowerCase()
+      .replace(/[^a-z0-9-]/g, "-")
+      .replace(/^-+|-+$/g, "") || "app";
+  const name = await answer(
+    input.name,
+    "Service name",
+    /^[a-z]/.test(suggestedName) ? suggestedName : `app-${suggestedName}`,
+    prompt,
+    !!input.nonInteractive,
+  );
+  const defaultSource = detected.length === 0 ? "image" : "auto";
+  const selectedSource = await answer(
+    input.source,
+    "Source (image/auto/template)",
+    defaultSource,
+    prompt,
+    !!input.nonInteractive,
+  );
+  let source: Source;
+  if (selectedSource === "image")
+    source = {
+      kind: "image",
+      image: await answer(
+        input.image,
+        "Image",
+        "nginx:stable",
+        prompt,
+        !!input.nonInteractive,
+      ),
+    };
+  else if (selectedSource === "auto") source = { kind: "auto" };
+  else if (selectedSource === "template") {
+    const choices = listDockerfileTemplates()
+      .map(({ id, label }) => `${id} (${label})`)
+      .join(", ");
+    const template = await answer(
+      input.template,
+      `Dockerfile template (${choices})`,
+      undefined,
+      prompt,
+      !!input.nonInteractive,
+    );
+    if (!templateIds.includes(template as (typeof templateIds)[number]))
+      throw new Error(`Unknown Dockerfile template: ${template}`);
+    source = {
+      kind: "template",
+      template: template as (typeof templateIds)[number],
+    };
+  } else throw new Error("Source must be image, auto, or template");
+  const postgres = input.nonInteractive
+    ? input.postgres
+    : await prompt(
+        "Postgres claim (name or user/database; blank for none)",
+        input.postgres,
+      );
+  const s3 = input.nonInteractive
+    ? input.s3
+    : await prompt("S3 claim (name or key/bucket; blank for none)", input.s3);
+  const cpu = input.nonInteractive
+    ? input.cpu
+    : await prompt("CPU limit in cores (blank for default)", input.cpu);
+  const memory = input.nonInteractive
+    ? input.memory
+    : await prompt("Memory limit (blank for default)", input.memory);
+  const replicasAnswer = input.nonInteractive
+    ? input.replicas?.toString()
+    : await prompt("Replicas (blank for default)", input.replicas?.toString());
+  return {
+    name,
+    path,
+    source,
+    ...(postgres ? { postgres } : {}),
+    ...(s3 ? { s3 } : {}),
+    ...(cpu ? { cpu } : {}),
+    ...(memory ? { memory } : {}),
+    ...(replicasAnswer ? { replicas: Number(replicasAnswer) } : {}),
+  };
+}
+
+export const appArgs = {
+  name: { type: "string" as const, description: "Service name" },
+  path: {
+    type: "string" as const,
+    description: "App directory relative to the project",
+  },
+  source: {
+    type: "string" as const,
+    description: "image, auto (Buildpacks), or template",
+  },
+  image: {
+    type: "string" as const,
+    description: "Image reference when source=image",
+  },
+  template: {
+    type: "string" as const,
+    description: "Dockerfile template ID when source=template",
+  },
+  postgres: {
+    type: "string" as const,
+    description: "Postgres claim name or user/database",
+  },
+  s3: { type: "string" as const, description: "S3 claim name or key/bucket" },
+  cpu: { type: "string" as const, description: "CPU limit in cores" },
+  memory: { type: "string" as const, description: "Memory limit, e.g. 512m" },
+  replicas: { type: "string" as const, description: "Replica count" },
+  "non-interactive": {
+    type: "boolean" as const,
+    description: "Use defaults and require explicit choices when ambiguous",
+  },
+};
+
+export function appInputFromArgs(args: Record<string, unknown>): AppInput {
+  return {
+    ...Object.fromEntries(
+      [
+        "name",
+        "path",
+        "source",
+        "image",
+        "template",
+        "postgres",
+        "s3",
+        "cpu",
+        "memory",
+      ]
+        .filter((key) => args[key] !== undefined)
+        .map((key) => [key, String(args[key])]),
+    ),
+    ...(args.replicas !== undefined ? { replicas: Number(args.replicas) } : {}),
+    nonInteractive: Boolean(args["non-interactive"]),
+  };
+}
+
+export const add = defineCommand({
+  meta: { name: "add", description: "Add a resource to this project" },
+  subCommands: {
+    app: defineCommand({
+      meta: {
+        name: "app",
+        description: "Add a service without changing existing services",
+      },
+      args: appArgs,
+      async run({ args }) {
+        const { cwd, path } = ctx();
+        const app = await resolveAppInput(cwd, appInputFromArgs(args));
+        const composePath = await addAppToCompose(cwd, app, await path());
+        console.log(`Added ${app.name} to ${composePath}`);
+      },
+    }),
+  },
+});
diff --git a/command/auth.ts b/command/auth.ts
index b76d083..ba0f06c 100644
--- a/command/auth.ts
+++ b/command/auth.ts
@@ -75,6 +75,19 @@ export async function loginUser(
   return session;
 }
 
+/** Share the CLI's credential prompt with onboarding without exposing passwords. */
+export async function interactiveLogin(): Promise<LoginResponse> {
+  if (!stdin.isTTY)
+    throw new Error(
+      "Login requires an interactive terminal; run kuber login first",
+    );
+  const username = await promptUsername();
+  if (!username) throw new Error("Username is required");
+  const session = await loginUser(username, await promptPassword(), false);
+  console.log(`Logged in as ${session.user.username}`);
+  return session;
+}
+
 export const login = defineCommand({
   meta: {
     name: "login",
diff --git a/command/init.ts b/command/init.ts
new file mode 100644
index 0000000..a15b774
--- /dev/null
+++ b/command/init.ts
@@ -0,0 +1,183 @@
+import { defineCommand } from "citty";
+import { apiRequest, KuberApiError, type ApiRequestInit } from "../lib/api";
+import { readSession, type KuberSession } from "../lib/session";
+import { resolveTrustIdentity, updateTrust } from "../lib/trust";
+import type { WorkspaceTrustResponse } from "../shared/api";
+import { interactiveLogin } from "./auth";
+import { createCompose, projectName } from "../lib/scaffold";
+import {
+  appArgs,
+  appInputFromArgs,
+  resolveAppInput,
+  terminalPrompt,
+  type AppInput,
+  type ScaffoldPrompt,
+} from "./add";
+import { resolveComposeFile } from "../lib/yaml";
+import { basename } from "node:path";
+import { join } from "node:path";
+import { readFile, rm } from "node:fs/promises";
+import { renderDockerfileTemplate } from "../lib/scaffold-templates";
+import { loadConfig } from "../lib/config";
+
+type Requester = <T>(path: string, init?: ApiRequestInit) => Promise<T>;
+export type InitDependencies = {
+  configPath?: string;
+  prompt?: ScaffoldPrompt;
+  session?: () => Promise<KuberSession | undefined>;
+  login?: () => Promise<KuberSession>;
+  request?: Requester;
+  persistTrust?: typeof updateTrust;
+};
+
+/** Creates a project and registers trust after a successful authenticated server grant. */
+export async function initializeProject(
+  root: string,
+  input: AppInput & { project?: string },
+  dependencies: InitDependencies = {},
+): Promise<string> {
+  if (await resolveComposeFile(root))
+    throw new Error("A Compose file already exists; use kuber add app instead");
+  const config = await loadConfig(root, dependencies.configPath);
+  if (config.composeFile && config.composeFile !== join(root, "compose.yml"))
+    throw new Error(
+      `Existing config expects ${config.composeFile}; kuber init creates compose.yml`,
+    );
+  if (
+    config.projectConfigured &&
+    projectName(config.project) !== config.project
+  )
+    throw new Error(
+      `Configured project ${config.project} must be a lowercase Kubernetes name`,
+    );
+  const prompt = dependencies.prompt ?? terminalPrompt;
+  if (
+    config.projectConfigured &&
+    input.project &&
+    input.project !== config.project
+  )
+    throw new Error(
+      `Existing config selects project ${config.project}; use that project for init`,
+    );
+  const defaultProject = projectName(
+    config.projectConfigured ? config.project : basename(root),
+  );
+  const project = projectName(
+    input.project ??
+      (input.nonInteractive
+        ? defaultProject
+        : await prompt("Project name", defaultProject)),
+  );
+  const app = await resolveAppInput(root, input, prompt);
+  const login = dependencies.login ?? interactiveLogin;
+  let session = await (dependencies.session ?? readSession)();
+  if (!session) session = await login();
+  const composePath = await createCompose(root, project, app);
+  const createdCompose = await readFile(composePath, "utf8");
+  const identity = await resolveTrustIdentity(project, root);
+  const request = dependencies.request ?? apiRequest;
+  const trustPath = `/workspaces/${encodeURIComponent(project)}/trust`;
+  let retried = false;
+  let remoteRegistered = false;
+  try {
+    while (true) {
+      try {
+        const remote = await request<WorkspaceTrustResponse>(trustPath);
+        if (!Array.isArray(remote?.fingerprints))
+          throw new Error("Could not verify existing server trust");
+        const alreadyTrusted = remote.fingerprints.includes(
+          identity.fingerprint,
+        );
+        // The server grant is idempotent. A GET cannot establish ownership of it:
+        // another client may grant the same fingerprint before our POST.
+        if (!alreadyTrusted)
+          await request(trustPath, {
+            method: "POST",
+            json: { fingerprint: identity.fingerprint },
+          });
+        remoteRegistered = true;
+        try {
+          await (dependencies.persistTrust ?? updateTrust)((records) => [
+            ...records.filter(
+              (record) =>
+                record.project !== identity.project ||
+                record.fingerprint !== identity.fingerprint,
+            ),
+            identity,
+          ]);
+        } catch {
+          throw new Error(
+            "Server registration exists, but local trust could not be confirmed. Generated project files were kept; run kuber trust to repair local trust.",
+          );
+        }
+        break;
+      } catch (error) {
+        if (
+          retried ||
+          !(error instanceof KuberApiError) ||
+          error.status !== 401
+        )
+          throw error;
+        retried = true;
+        session = await login();
+      }
+    }
+  } catch (error) {
+    // Once registered remotely, keep the files needed to repair local trust.
+    // On remote failure, only roll back files still identical to ours.
+    if (
+      !remoteRegistered &&
+      (await readFile(composePath, "utf8").catch(() => undefined)) ===
+        createdCompose
+    ) {
+      await rm(composePath, { force: true });
+      if (app.source.kind === "template") {
+        const { dockerfile, dockerignore } = renderDockerfileTemplate(
+          app.source.template,
+        );
+        for (const [name, content] of [
+          ["Dockerfile", dockerfile],
+          [".dockerignore", dockerignore],
+        ] as const) {
+          const file = join(root, app.path, name);
+          if ((await readFile(file, "utf8").catch(() => undefined)) === content)
+            await rm(file, { force: true });
+        }
+      }
+    }
+    throw error;
+  }
+  console.log(`Trusted this directory for namespace ${identity.project}`);
+  console.log(`Initialized ${project} in ${composePath}`);
+  return composePath;
+}
+
+export const init = defineCommand({
+  meta: {
+    name: "init",
+    description: "Initialize a Compose project and trust this directory",
+  },
+  args: {
+    ...appArgs,
+    project: {
+      type: "string",
+      description: "Kubernetes namespace/project name",
+    },
+    "config-path": {
+      type: "string",
+      description: "Project config path (usually passed as global --config)",
+    },
+  },
+  async run({ args }) {
+    await initializeProject(
+      process.cwd(),
+      {
+        ...appInputFromArgs(args),
+        ...(args.project !== undefined
+          ? { project: String(args.project) }
+          : {}),
+      },
+      { configPath: args["config-path"] },
+    );
+  },
+});
diff --git a/command/main.ts b/command/main.ts
index f5745be..aa861b6 100644
--- a/command/main.ts
+++ b/command/main.ts
@@ -37,7 +37,7 @@ function cloneCommand<T extends object>(command: T): T {
 export const main = defineCommand({
   meta: {
     name: "kuber",
-    version: "2.6.2-rc2",
+    version: "2.7.0-rc2",
     description: "Docker Compose -> K8s translation layer",
   },
   args: {
@@ -47,12 +47,14 @@ export const main = defineCommand({
     },
   },
   subCommands: {
+    add: lazyCommand(() => import("./add").then((m) => m.add)),
     audit: lazyCommand(() => import("./audit").then((m) => m.audit)),
     ci: lazyCommand(() => import("./ci").then((m) => m.ci)),
     db: lazyCommand(() => import("./db").then((m) => m.db)),
     down: lazyCommand(() => import("./down").then((m) => m.down)),
     export: lazyCommand(() => import("./export").then((m) => m.exportCommand)),
     exec: lazyCommand(() => import("./exec").then((m) => m.exec)),
+    init: lazyCommand(() => import("./init").then((m) => m.init)),
     logs: lazyCommand(() => import("./logs").then((m) => m.logs)),
     maintenance: lazyCommand(() =>
       import("./maintenance").then((m) => m.maintenance),
@@ -76,7 +78,7 @@ export const main = defineCommand({
 });
 
 type Completion = Awaited<
-  ReturnType<typeof import("@bomb.sh/tab/citty")["default"]>
+  ReturnType<(typeof import("@bomb.sh/tab/citty"))["default"]>
 >;
 let completion: Promise<Completion> | undefined;
 
diff --git a/command/up.ts b/command/up.ts
index 3fbd3b5..6ea72e1 100644
--- a/command/up.ts
+++ b/command/up.ts
@@ -625,7 +625,12 @@ export async function reconcileResources(
   request: ApiRequester = apiRequest,
   resumeOptions: OperationResumeOptions = {},
 ): Promise<ResourcePlan> {
-  const plan = await planResources(project, resources, request, resumeOptions.signal);
+  const plan = await planResources(
+    project,
+    resources,
+    request,
+    resumeOptions.signal,
+  );
   await applyResourcePlan(
     project,
     plan,
@@ -792,6 +797,30 @@ export async function runUp(
               new Promise((resolve) => pending.set(name, resolve)),
             ]),
           );
+          let settleUpload!: (error?: unknown) => void;
+          const uploaded = new Promise<unknown>((resolve) => {
+            settleUpload = resolve;
+          });
+          let uploadChild: ListrTaskWrapper<UpContext, any, any> | undefined;
+          let uploadedBytes = 0;
+          let totalBytes = 0;
+          const formatBytes = (bytes: number): string => {
+            if (bytes < 1024) return `${bytes} B`;
+            const unit = bytes < 1024 ** 2 ? "KiB" : "MiB";
+            const divisor = unit === "KiB" ? 1024 : 1024 ** 2;
+            return `${Number((bytes / divisor).toFixed(1))} ${unit}`;
+          };
+          const uploadTitle = (
+            bytes: number,
+            total: number,
+            finished = false,
+          ): string =>
+            `Uploading context: ${formatBytes(bytes)}/${formatBytes(total)} (${finished ? 100 : total === 0 ? 0 : Math.min(99, Math.floor((100 * bytes) / total))}%)`;
+          const finishUpload = (error?: unknown) => {
+            if (!error && uploadChild)
+              uploadChild.title = uploadTitle(uploadedBytes, totalBytes, true);
+            settleUpload(error);
+          };
           let result: Awaited<ReturnType<typeof buildServices>> | undefined;
           let operationFailure: Error | undefined;
           let operation: Promise<void> | undefined;
@@ -801,19 +830,27 @@ export async function runUp(
               taskCtx.compose!,
               cwd,
               {
-                progress: (message) => {
-                  if (
-                    !/^Build (?:queued|creating|starting|running|done)\b/.test(message) &&
-                    task.output !== message
-                  ) task.output = message;
+                upload: (bytes, total) => {
+                  uploadedBytes = bytes;
+                  totalBytes = total;
+                  if (uploadChild)
+                    uploadChild.title = uploadTitle(bytes, total);
                 },
+                uploadSettled: finishUpload,
                 service: (name) => {
-                  let stream: ReturnType<ListrTaskWrapper<UpContext, any, any>["stdout"]> | undefined;
+                  let stream:
+                    | ReturnType<
+                        ListrTaskWrapper<UpContext, any, any>["stdout"]
+                      >
+                    | undefined;
                   return {
                     progress: (message) => {
                       const child = children.get(name);
                       if (!child) return;
-                      const phase = /^Build (queued|creating|starting|running|done)\b/.exec(message)?.[1];
+                      const phase =
+                        /^Build (queued|creating|starting|running|done)\b/.exec(
+                          message,
+                        )?.[1];
                       if (phase) child.title = `Build ${name}: ${phase}`;
                       // A failed status includes the full error; the parent bottom bar owns it.
                     },
@@ -845,6 +882,7 @@ export async function runUp(
                   error instanceof Error ? error : new Error(String(error));
                 operationFailure = failure;
                 task.output = failure.stack ?? failure.message;
+                finishUpload(failure);
                 for (const resolve of pending.values()) resolve(failure);
                 pending.clear();
               },
@@ -853,6 +891,19 @@ export async function runUp(
           };
           return task.newListr<UpContext>(
             [
+              {
+                title: uploadTitle(0, 0),
+                exitOnError: false,
+                task: async (_ctx, child) => {
+                  uploadChild = child;
+                  if (children.size === services.length) start();
+                  const error = await uploaded;
+                  if (error) {
+                    child.title = "Uploading context: failed";
+                    throw error;
+                  }
+                },
+              },
               ...services.map((name) => ({
                 title: `Build ${name}`,
                 rendererOptions: { outputBar: 10, persistentOutput: true },
@@ -863,7 +914,7 @@ export async function runUp(
                 ) => {
                   children.set(name, child);
                   child.title = `Build ${name}: queued`;
-                  if (children.size === services.length) start();
+                  if (children.size === services.length && uploadChild) start();
                   const error = await completed.get(name);
                   if (error) {
                     child.title = `Build ${name}: failed`;
@@ -948,7 +999,8 @@ export async function runUp(
                       { method: "POST", json: { compose: taskCtx.compose } },
                     );
                   } catch (error) {
-                    task.output = error instanceof Error ? error.message : String(error);
+                    task.output =
+                      error instanceof Error ? error.message : String(error);
                     throw error;
                   }
                   taskCtx.databaseEnv = operationEnvironment(response);
@@ -957,8 +1009,7 @@ export async function runUp(
               },
               {
                 title: "Reconcile S3 storage",
-                enabled: () =>
-                  getComposeS3Claims(taskCtx.compose!).length > 0,
+                enabled: () => getComposeS3Claims(taskCtx.compose!).length > 0,
                 task: async (_ctx, child) => {
                   let response: Record<string, unknown>;
                   try {
@@ -969,7 +1020,8 @@ export async function runUp(
                       { method: "POST", json: { compose: taskCtx.compose } },
                     );
                   } catch (error) {
-                    task.output = error instanceof Error ? error.message : String(error);
+                    task.output =
+                      error instanceof Error ? error.message : String(error);
                     throw error;
                   }
                   taskCtx.storageEnv = operationEnvironment(response);
@@ -1110,7 +1162,12 @@ export async function runUp(
       renderer: "default",
       // Only redraw when a task changes; a queued build should not generate
       // another frame on each spinner tick. Keep the renderer's task tree.
-      rendererOptions: { collapseErrors: false, collapseSubtasks: false, showErrorMessage: false, lazy: true },
+      rendererOptions: {
+        collapseErrors: false,
+        collapseSubtasks: false,
+        showErrorMessage: false,
+        lazy: true,
+      },
     },
   ).run();
 
diff --git a/index.ts b/index.ts
index 377b217..08e0ae8 100644
--- a/index.ts
+++ b/index.ts
@@ -5,6 +5,7 @@ import { initializeCompletion, main } from "./command/main";
 import { provideContext } from "./lib/context";
 import { extractConfigArgument } from "./lib/config";
 import { formatUnknownError, wrapCommandErrors } from "./lib/error";
+import { waitForVersionUpdate } from "./lib/version-update";
 
 async function run() {
   const { configPath, rawArgs } = extractConfigArgument(process.argv.slice(2));
@@ -19,7 +20,15 @@ async function run() {
     await initializeCompletion();
   wrapCommandErrors(main);
   const cli = createMain(main);
-  const contextFree = new Set(["login", "logout", "whoami", "maintenance"]);
+  if (rawArgs[0] === "init" && configPath)
+    rawArgs.push("--config-path", configPath);
+  const contextFree = new Set([
+    "login",
+    "logout",
+    "whoami",
+    "maintenance",
+    "init",
+  ]);
   if (rawArgs[0] && contextFree.has(rawArgs[0])) {
     await cli({ rawArgs });
     return;
@@ -27,7 +36,9 @@ async function run() {
   await provideContext(() => cli({ rawArgs }), configPath);
 }
 
-run().catch((e) => {
-  console.error(formatUnknownError(e));
-  process.exitCode = 1;
-});
+run()
+  .catch((e) => {
+    console.error(formatUnknownError(e));
+    process.exitCode = 1;
+  })
+  .finally(waitForVersionUpdate);
diff --git a/lib/build.ts b/lib/build.ts
index b875978..0d3e660 100644
--- a/lib/build.ts
+++ b/lib/build.ts
@@ -6,6 +6,7 @@ import type { Writable } from "node:stream";
 import type { ComposeSpecification, Service } from "../schema/docker.d";
 import {
   BUILD_PROTOCOL_VERSION,
+  validateBuildpackUri,
   type BuildEvent,
   type BuildRequest,
   type BuildStatus,
@@ -184,6 +185,8 @@ type BuildPlan = {
   name: string;
   image: string;
   context: string;
+  builder?: "buildpacks";
+  buildpackUri?: string;
   dockerfile?: string;
   target?: string;
   buildArgs: string[];
@@ -192,6 +195,8 @@ type BuildPlan = {
 type ProgressReporter = (message: string) => void | Promise<void>;
 type BuildReporter = {
   progress?: ProgressReporter;
+  upload?: (uploaded: number, total: number) => void;
+  uploadSettled?: (error?: unknown) => void;
   stream?: Writable;
   /** Per-image output and lifecycle hooks, including for queued images. */
   service?: (name: string) => BuildReporter | undefined;
@@ -210,6 +215,45 @@ type SnapshotNegotiation = {
   ready: boolean;
 };
 
+class UploadTracker {
+  private readonly sizes = new Map<Sha256Digest, number>();
+  private readonly offsets = new Map<Sha256Digest, number>();
+
+  constructor(
+    private readonly report?: (uploaded: number, total: number) => void,
+  ) {}
+
+  register(
+    missing: Sha256Digest[],
+    blobs: Map<Sha256Digest, Uint8Array>,
+    emit = true,
+  ): void {
+    for (const digest of missing) {
+      const data = blobs.get(digest);
+      if (!data)
+        throw new Error(`Server requested unknown workspace blob ${digest}`);
+      this.sizes.set(digest, data.byteLength);
+    }
+    if (emit) this.emit();
+  }
+
+  advance(digest: Sha256Digest, offset: number): void {
+    this.offsets.set(digest, Math.max(this.offsets.get(digest) ?? 0, offset));
+    this.emit();
+  }
+
+  complete(): void {
+    this.emit();
+  }
+
+  private emit(): void {
+    this.report?.(
+      [...this.offsets.values()].reduce((sum, bytes) => sum + bytes, 0),
+      [...this.sizes.values()].reduce((sum, bytes) => sum + bytes, 0),
+    );
+  }
+}
+
 type ImageResult = {
   image: string;
   digest: Sha256Digest;
@@ -259,8 +303,35 @@ function resolveBuildPlan(
 ): BuildPlan | undefined {
   if (!service.build) return;
   const build = service.build;
-  const contextInput =
-    typeof build === "string" ? build : (build.context ?? ".");
+  const auto =
+    build === "auto" ||
+    (typeof build === "string" && build.startsWith("auto:"));
+  const buildpackUri =
+    typeof build === "string" && build.startsWith("auto:")
+      ? build.slice(5)
+      : undefined;
+  if (buildpackUri !== undefined) validateBuildpackUri(buildpackUri);
+  const autoContext = service["x-kuber-build-context"];
+  if (
+    auto &&
+    autoContext !== undefined &&
+    (typeof autoContext !== "string" ||
+      autoContext.length === 0 ||
+      autoContext.includes("\\") ||
+      autoContext.includes("\0") ||
+      isAbsolute(autoContext) ||
+      /^[A-Za-z]:/.test(autoContext) ||
+      autoContext.split("/").some((part) => part === ".." || part === ""))
+  ) {
+    throw new Error(
+      `Invalid x-kuber-build-context for service ${name}; expected a relative path inside the workspace`,
+    );
+  }
+  const contextInput = auto
+    ? ((autoContext as string | undefined) ?? ".")
+    : typeof build === "string"
+      ? build
+      : (build.context ?? ".");
   if (contextInput.includes("://"))
     throw new Error(
       `Remote build context is not supported for service ${name}`,
@@ -268,7 +339,7 @@ function resolveBuildPlan(
   if (typeof build !== "string" && build.dockerfile_inline)
     throw new Error(`dockerfile_inline is not supported for service ${name}`);
 
-  const contextPath = resolve(cwd, contextInput);
+  const contextPath = resolve(auto ? repoRoot : cwd, contextInput);
   const context = assertInsideRepo(
     repoRoot,
     contextPath,
@@ -285,6 +356,8 @@ function resolveBuildPlan(
     // The server replaces this requested name with its configured imageName.
     image: getBuildImageName(project, name, registry),
     context,
+    ...(auto && { builder: "buildpacks" as const }),
+    ...(buildpackUri && { buildpackUri }),
     dockerfile: dockerfilePath
       ? assertInsideRepo(repoRoot, dockerfilePath, "Dockerfile", name)
       : undefined,
@@ -347,6 +420,7 @@ async function uploadBlob(
   scheduler: TaskScheduler,
   project?: string,
   signal?: AbortSignal,
+  tracker?: UploadTracker,
 ): Promise<void> {
   const uploadPath = `/blobs/${encodeURIComponent(digest)}/uploads`;
   const projectQuery = project ? `?project=${encodeURIComponent(project)}` : "";
@@ -359,6 +433,7 @@ async function uploadBlob(
     }),
   );
   let offset = progress.offset;
+  tracker?.advance(digest, offset);
   while (!progress.complete && offset < data.byteLength) {
     const chunk = data.subarray(offset, offset + UPLOAD_CHUNK_BYTES);
     const uploaded = await scheduler.run(() =>
@@ -375,6 +450,7 @@ async function uploadBlob(
     if (uploaded.offset <= offset)
       throw new Error(`Blob upload for ${digest} made no progress`);
     offset = uploaded.offset;
+    tracker?.advance(digest, offset);
   }
   if (!progress.complete) {
     await scheduler.run(() =>
@@ -394,37 +470,46 @@ export async function uploadWorkspaceSnapshot(
   scheduler?: TaskScheduler,
   project?: string,
   signal?: AbortSignal,
+  tracker = new UploadTracker(reporter?.upload),
+  initial?: SnapshotNegotiation,
 ): Promise<void> {
   const blobs = new Map(snapshot.blobs.map((blob) => [blob.digest, blob.data]));
   blobs.set(snapshot.digest, serializeWorkspaceManifest(snapshot.manifest));
   const requestScheduler = scheduler ?? new TaskScheduler();
 
+  let first = initial;
   for (;;) {
     signal?.throwIfAborted();
-    const negotiation = await requestScheduler.run(() =>
-      request<SnapshotNegotiation>(
-        "/snapshots/negotiate",
-        {
-          method: "POST",
-          json: { workspace: snapshot.digest, ...(project && { project }) },
-          signal,
-        },
-        { timeoutMs: 300_000 },
-      ),
-    );
-    if (negotiation.ready) return;
+    const negotiation =
+      first ??
+      (await requestScheduler.run(() =>
+        request<SnapshotNegotiation>(
+          "/snapshots/negotiate",
+          {
+            method: "POST",
+            json: { workspace: snapshot.digest, ...(project && { project }) },
+            signal,
+          },
+          { timeoutMs: 300_000 },
+        ),
+      ));
+    first = undefined;
+    if (negotiation.ready) {
+      tracker.complete();
+      return;
+    }
     if (negotiation.missing.length === 0)
       throw new Error(
         "Snapshot negotiation is incomplete but reported no missing blobs",
       );
+    tracker.register(negotiation.missing, blobs);
     await runConcurrent(
-      negotiation.missing,
+      [...new Set(negotiation.missing)],
       requestScheduler.maxConcurrent,
       async (digest) => {
         const data = blobs.get(digest);
         if (!data)
           throw new Error(`Server requested unknown workspace blob ${digest}`);
-        await reporter?.progress?.(`Uploading ${digest}`);
         await uploadBlob(
           digest,
           data,
@@ -432,6 +517,7 @@ export async function uploadWorkspaceSnapshot(
           requestScheduler,
           project,
           signal,
+          tracker,
         );
       },
     );
@@ -701,8 +787,13 @@ export async function buildServices(
     throw new RangeError("buildConcurrency must be a positive integer");
 
   const request = options.request ?? apiRequest;
+  const hasAuto = Object.values(compose.services ?? {}).some(
+    (service) =>
+      service.build === "auto" ||
+      (typeof service.build === "string" && service.build.startsWith("auto:")),
+  );
   let repoRoot = options.workspaceRoot;
-  if (!repoRoot && !options.snapshot) {
+  if (!repoRoot && (!options.snapshot || hasAuto)) {
     try {
       repoRoot = await getRepoRoot(cwd);
     } catch (error) {
@@ -710,7 +801,6 @@ export async function buildServices(
     }
   }
   repoRoot ??= cwd;
-  const snapshot = options.snapshot ?? (await enumerateWorkspace(repoRoot));
   const plans = Object.entries(compose.services ?? {}).flatMap(
     ([name, service]) => {
       const plan = resolveBuildPlan(
@@ -724,14 +814,70 @@ export async function buildServices(
       return plan ? [plan] : [];
     },
   );
-  await uploadWorkspaceSnapshot(
-    snapshot,
-    request,
-    reporter,
-    options.scheduler,
-    project,
-    options.signal,
+  const hasDockerfile = plans.some((plan) => !plan.builder);
+  const snapshot = hasDockerfile
+    ? (options.snapshot ?? (await enumerateWorkspace(repoRoot)))
+    : undefined;
+  const autoSnapshot = hasAuto
+    ? await enumerateWorkspace(repoRoot, "auto")
+    : undefined;
+  const workspaces = [snapshot, autoSnapshot].filter(
+    (workspace): workspace is WorkspaceSnapshot => workspace !== undefined,
   );
+  try {
+    const scheduler = options.scheduler ?? new TaskScheduler();
+    const tracker = new UploadTracker(reporter?.upload);
+    // Know both denominators before reporting progress for mixed builders.
+    const initial =
+      reporter?.upload && workspaces.length > 1
+        ? await Promise.all(
+            workspaces.map((workspace) =>
+              scheduler.run(() =>
+                request<SnapshotNegotiation>(
+                  "/snapshots/negotiate",
+                  {
+                    method: "POST",
+                    json: { workspace: workspace.digest, project },
+                    signal: options.signal,
+                  },
+                  { timeoutMs: 300_000 },
+                ),
+              ),
+            ),
+          )
+        : undefined;
+    if (initial) {
+      initial.forEach((negotiation, index) => {
+        const workspace = workspaces[index]!;
+        const blobs = new Map(
+          workspace.blobs.map((blob) => [blob.digest, blob.data]),
+        );
+        blobs.set(
+          workspace.digest,
+          serializeWorkspaceManifest(workspace.manifest),
+        );
+        tracker.register(negotiation.missing ?? [], blobs, false);
+      });
+      tracker.complete();
+    }
+    for (const [index, workspace] of workspaces.entries())
+      await uploadWorkspaceSnapshot(
+        workspace,
+        request,
+        reporter,
+        scheduler,
+        project,
+        options.signal,
+        tracker,
+        initial?.[index],
+      );
+    reporter?.uploadSettled?.();
+  } catch (error) {
+    reporter?.uploadSettled?.(error);
+    throw error;
+  }
+  const snapshotFor = (plan: BuildPlan): WorkspaceSnapshot =>
+    (plan.builder ? autoSnapshot : snapshot)!;
 
   const references: string[] = new Array(plans.length);
   const reporters = new Map(
@@ -744,7 +890,9 @@ export async function buildServices(
   const groups = new Map<string, number[]>();
   plans.forEach((plan, index) => {
     const key = JSON.stringify({
-      workspace: snapshot.digest,
+      builder: plan.builder ?? "dockerfile",
+      buildpackUri: plan.buildpackUri,
+      workspace: snapshotFor(plan).digest,
       architecture,
       context: plan.context,
       dockerfile: plan.dockerfile,
@@ -810,10 +958,12 @@ export async function buildServices(
         architecture,
         image: plan.image,
         context: plan.context,
-        dockerfile: plan.dockerfile,
+        ...(plan.builder && { builder: plan.builder }),
+        ...(plan.buildpackUri && { buildpackUri: plan.buildpackUri }),
+        ...(!plan.builder && { dockerfile: plan.dockerfile }),
         target: plan.target,
         buildArgs: plan.buildArgs,
-        workspace: snapshot.digest,
+        workspace: snapshotFor(plan).digest,
       },
     };
     const initial = await request<BuildStatus>(
diff --git a/lib/scaffold-templates.ts b/lib/scaffold-templates.ts
new file mode 100644
index 0000000..76bb33a
--- /dev/null
+++ b/lib/scaffold-templates.ts
@@ -0,0 +1,262 @@
+/** Embedded templates are bundled with the CLI; no files are read at runtime. */
+export const templateIds = [
+  "bun-service",
+  "bun-next",
+  "bun-compiled",
+  "node-pnpm",
+  "python-web",
+  "go-static",
+  "rust-static",
+  "static-nginx",
+] as const;
+
+export type DockerfileTemplateId = (typeof templateIds)[number];
+
+export type DockerfileTemplate = {
+  id: DockerfileTemplateId;
+  label: string;
+  description: string;
+};
+
+export type RenderedDockerfileTemplate = {
+  dockerfile: string;
+  dockerignore: string;
+};
+
+const commonIgnore = `# Local state and credentials must not enter the build context.
+.git
+.github
+.env
+.env.*
+**/.env
+**/.env.*
+*.pem
+*.key
+*.p12
+id_rsa*
+credentials.json
+*.log
+.DS_Store
+`;
+
+const templates: Record<
+  DockerfileTemplateId,
+  DockerfileTemplate & RenderedDockerfileTemplate
+> = {
+  "bun-service": {
+    id: "bun-service",
+    label: "Bun service",
+    description:
+      "Bun app with package.json and bun.lock; starts src/index.ts on port 3000.",
+    dockerfile: `FROM oven/bun:1-alpine AS deps
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile --production
+
+FROM oven/bun:1-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=deps /app/node_modules ./node_modules
+COPY package.json ./
+COPY src ./src
+USER bun
+EXPOSE 3000
+CMD ["bun", "src/index.ts"]
+`,
+    dockerignore: `${commonIgnore}node_modules
+dist
+.next
+coverage
+`,
+  },
+  "bun-next": {
+    id: "bun-next",
+    label: "Bun / Next.js standalone",
+    description:
+      "Next.js app with bun.lock and output: 'standalone' in next.config; starts generated server.js on port 3000.",
+    dockerfile: `FROM oven/bun:1-alpine AS build
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN mkdir -p public && bun run build
+
+FROM oven/bun:1-alpine
+WORKDIR /app
+ENV NODE_ENV=production HOSTNAME=0.0.0.0 PORT=3000
+COPY --from=build /app/.next/standalone ./
+COPY --from=build /app/.next/static ./.next/static
+COPY --from=build /app/public ./public
+USER bun
+EXPOSE 3000
+CMD ["bun", "server.js"]
+`,
+    dockerignore: `${commonIgnore}node_modules
+.next
+dist
+coverage
+`,
+  },
+  "bun-compiled": {
+    id: "bun-compiled",
+    label: "Compiled Bun executable",
+    description:
+      "Bun app with bun.lock and src/index.ts; compiles a Linux executable named app.",
+    dockerfile: `FROM oven/bun:1 AS build
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+COPY . .
+RUN bun build src/index.ts --compile --outfile /app/app
+
+FROM oven/bun:1-slim
+WORKDIR /app
+COPY --from=build /app/app ./app
+USER bun
+EXPOSE 3000
+CMD ["./app"]
+`,
+    dockerignore: `${commonIgnore}node_modules
+dist
+.next
+coverage
+`,
+  },
+  "node-pnpm": {
+    id: "node-pnpm",
+    label: "Node / pnpm service",
+    description:
+      "Node app with pnpm-lock.yaml, a build script producing dist/index.js, and a packageManager pin in package.json.",
+    dockerfile: `FROM node:22-alpine AS build
+WORKDIR /app
+RUN corepack enable
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm run build && pnpm prune --prod
+
+FROM node:22-alpine
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=build /app/package.json ./
+COPY --from=build /app/node_modules ./node_modules
+COPY --from=build /app/dist ./dist
+USER node
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+`,
+    dockerignore: `${commonIgnore}node_modules
+dist
+coverage
+.next
+`,
+  },
+  "python-web": {
+    id: "python-web",
+    label: "Python web service",
+    description:
+      "Python app with requirements.txt and an ASGI app object at app:app; serves on port 8000 via uvicorn (include it in requirements.txt).",
+    dockerfile: `FROM python:3.12-slim AS build
+WORKDIR /app
+RUN python -m venv /opt/venv
+ENV PATH=/opt/venv/bin:$PATH
+COPY requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+FROM python:3.12-slim
+WORKDIR /app
+ENV PATH=/opt/venv/bin:$PATH PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
+COPY --from=build /opt/venv /opt/venv
+COPY . .
+USER 10001:10001
+EXPOSE 8000
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "8000"]
+`,
+    dockerignore: `${commonIgnore}__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+dist/
+`,
+  },
+  "go-static": {
+    id: "go-static",
+    label: "Static Go binary",
+    description:
+      "Go module with go.mod and a main package at module root; builds a CGO-free app binary on port 8080.",
+    dockerfile: `FROM golang:1.24-alpine AS build
+WORKDIR /src
+COPY go.mod go.sum* ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -trimpath -o /app .
+
+FROM scratch
+COPY --from=build /app /app
+COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
+USER 65532:65532
+EXPOSE 8080
+ENTRYPOINT ["/app"]
+`,
+    dockerignore: `${commonIgnore}vendor/
+bin/
+coverage/
+`,
+  },
+  "rust-static": {
+    id: "rust-static",
+    label: "Static Rust binary",
+    description:
+      "Cargo project with Cargo.lock and a binary named app (src/main.rs); no dynamic native-library dependencies; serves on port 8080.",
+    dockerfile: `FROM rust:1-alpine AS build
+WORKDIR /app
+RUN apk add --no-cache musl-dev
+COPY Cargo.toml Cargo.lock ./
+COPY src ./src
+RUN cargo build --release --locked --bin app
+
+FROM scratch
+COPY --from=build /app/target/release/app /server
+USER 65532:65532
+EXPOSE 8080
+ENTRYPOINT ["/server"]
+`,
+    dockerignore: `${commonIgnore}target/
+coverage/
+`,
+  },
+  "static-nginx": {
+    id: "static-nginx",
+    label: "Static site / nginx",
+    description:
+      "Static site with ready-to-serve files in dist/; nginx serves them on port 80.",
+    dockerfile: `FROM nginx:1-alpine
+COPY dist/ /usr/share/nginx/html/
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]
+`,
+    dockerignore: `${commonIgnore}node_modules
+.next
+coverage
+`,
+  },
+};
+
+export function listDockerfileTemplates(): DockerfileTemplate[] {
+  return templateIds.map((id) => {
+    const { label, description } = templates[id];
+    return { id, label, description };
+  });
+}
+
+export function renderDockerfileTemplate(
+  id: DockerfileTemplateId,
+): RenderedDockerfileTemplate {
+  const template = templates[id];
+  if (!template) throw new Error(`Unknown Dockerfile template: ${id}`);
+  return {
+    dockerfile: template.dockerfile,
+    dockerignore: template.dockerignore,
+  };
+}
diff --git a/lib/scaffold.ts b/lib/scaffold.ts
new file mode 100644
index 0000000..f12777d
--- /dev/null
+++ b/lib/scaffold.ts
@@ -0,0 +1,327 @@
+import {
+  open,
+  readFile,
+  readdir,
+  realpath,
+  rename,
+  rm,
+  stat,
+} from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { YAML } from "bun";
+import type { Service } from "../schema/docker.d";
+import { readCompose, resolveComposeFile } from "./yaml";
+import {
+  renderDockerfileTemplate,
+  templateIds,
+  type DockerfileTemplateId,
+} from "./scaffold-templates";
+
+export const managedHeader =
+  "managedBy: kuber # See https://npmx.dev/@dmgnr/kuber for documentation.";
+const manifests = new Set([
+  "package.json",
+  "bun.lock",
+  "bun.lockb",
+  "pnpm-lock.yaml",
+  "pyproject.toml",
+  "requirements.txt",
+  "go.mod",
+  "Cargo.toml",
+]);
+const excluded = new Set([
+  ".git",
+  "node_modules",
+  ".next",
+  "dist",
+  "build",
+  "target",
+  ".venv",
+  "vendor",
+]);
+const serviceNamePattern = /^[a-z][a-z0-9-]*$/;
+
+export type Source =
+  | { kind: "image"; image: string }
+  | { kind: "auto" }
+  | { kind: "template"; template: DockerfileTemplateId };
+export type AppOptions = {
+  name: string;
+  path: string;
+  source: Source;
+  postgres?: string;
+  s3?: string;
+  cpu?: string;
+  memory?: string;
+  replicas?: number;
+};
+
+export function projectName(name: string): string {
+  const value = name
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 63)
+    .replace(/-+$/, "");
+  if (!value) throw new Error("Project name must contain letters or numbers");
+  return value;
+}
+
+export function validateAppPath(path: string): string {
+  const normalized = path.replaceAll("\\", "/").replace(/\/$/, "") || ".";
+  if (
+    isAbsolute(normalized) ||
+    normalized.split("/").some((part) => part === ".." || part === "")
+  )
+    throw new Error("App path must be relative and stay within the project");
+  return normalized;
+}
+
+export async function checkedAppPath(
+  root: string,
+  path: string,
+): Promise<string> {
+  const normalized = validateAppPath(path);
+  const absolute = resolve(root, normalized);
+  const [realRoot, realTarget, info] = await Promise.all([
+    realpath(root),
+    realpath(absolute),
+    stat(absolute),
+  ]);
+  if (
+    !info.isDirectory() ||
+    (realTarget !== realRoot && !realTarget.startsWith(`${realRoot}${sep}`))
+  )
+    throw new Error("App path must be a directory inside the project");
+  return normalized;
+}
+
+export async function detectAppPaths(root: string): Promise<string[]> {
+  const results: string[] = [];
+  async function visit(path: string, depth: number): Promise<void> {
+    const entries = await readdir(join(root, path), { withFileTypes: true });
+    if (entries.some((entry) => entry.isFile() && manifests.has(entry.name)))
+      results.push(path);
+    if (depth >= 3) return;
+    for (const entry of entries) {
+      if (
+        entry.isDirectory() &&
+        !excluded.has(entry.name) &&
+        !entry.name.startsWith(".")
+      )
+        await visit(
+          path === "." ? entry.name : `${path}/${entry.name}`,
+          depth + 1,
+        );
+    }
+  }
+  await visit(".", 0);
+  return results;
+}
+
+export function serviceForApp(app: AppOptions): Service {
+  if (!serviceNamePattern.test(app.name) || app.name.length > 63)
+    throw new Error(
+      "Service name must be lowercase letters, digits and hyphens, starting with a letter (max 63)",
+    );
+  const path = validateAppPath(app.path);
+  const service: Service = {};
+  if (app.source.kind === "image") {
+    if (!app.source.image.trim()) throw new Error("Image must not be empty");
+    service.image = app.source.image.trim();
+  } else {
+    if (
+      app.source.kind === "template" &&
+      !templateIds.includes(app.source.template)
+    )
+      throw new Error(`Unknown Dockerfile template: ${app.source.template}`);
+    service.build = app.source.kind === "auto" ? "auto" : path;
+    if (app.source.kind === "auto" && path !== ".")
+      service["x-kuber-build-context"] = path;
+  }
+  const volumes: string[] = [];
+  for (const [claim, value] of [
+    ["postgresql", app.postgres],
+    ["s3", app.s3],
+  ] as const) {
+    if (value) {
+      if (!/^[a-z0-9][a-z0-9-]*(?:\/[a-z0-9][a-z0-9-]*)?$/.test(value))
+        throw new Error(`Invalid ${claim} claim: ${value}`);
+      volumes.push(`${claim}:${value}`);
+    }
+  }
+  if (volumes.length) service.volumes = volumes;
+  if (
+    app.cpu !== undefined ||
+    app.memory !== undefined ||
+    app.replicas !== undefined
+  ) {
+    if (
+      app.cpu !== undefined &&
+      (!/^\d+(?:\.\d+)?$/.test(app.cpu) || Number(app.cpu) <= 0)
+    )
+      throw new Error("CPU must be a positive number of cores");
+    if (
+      app.memory !== undefined &&
+      (!/^\d+(?:\.\d+)?(?:[kKmMgGtT]|[KMGT]i|[KMGT][bB])?$/.test(app.memory) ||
+        Number.parseFloat(app.memory) <= 0)
+    )
+      throw new Error("Memory must be a positive quantity (e.g. 512m)");
+    if (
+      app.replicas !== undefined &&
+      (!Number.isSafeInteger(app.replicas) || app.replicas < 1)
+    )
+      throw new Error("Replicas must be a positive integer");
+    service.deploy = {
+      ...(app.replicas !== undefined ? { replicas: app.replicas } : {}),
+      ...(app.cpu !== undefined || app.memory !== undefined
+        ? {
+            resources: {
+              limits: {
+                ...(app.cpu !== undefined ? { cpus: app.cpu } : {}),
+                ...(app.memory !== undefined ? { memory: app.memory } : {}),
+              },
+            },
+          }
+        : {}),
+    };
+  }
+  return service;
+}
+
+function serviceBlock(name: string, service: Service): string {
+  const text = YAML.stringify({ [name]: service }, null, 2).trimEnd();
+  return `${text
+    .split("\n")
+    .map((line) => `  ${line}`)
+    .join("\n")}\n`;
+}
+
+async function writeExclusive(path: string, content: string): Promise<void> {
+  const file = await open(path, "wx");
+  try {
+    await file.writeFile(content);
+  } catch (error) {
+    await file.close();
+    await rm(path, { force: true });
+    throw error;
+  }
+  await file.close();
+}
+
+/** Existing YAML is kept byte-for-byte; only the new service block is inserted. */
+export async function addAppToCompose(
+  root: string,
+  app: AppOptions,
+  composeFile?: string,
+): Promise<string> {
+  const path = composeFile ?? (await resolveComposeFile(root));
+  if (!path)
+    throw new Error("Compose file cannot be found. Run kuber init first.");
+  await checkedAppPath(root, app.path);
+  const service = serviceForApp(app);
+  const compose = await readCompose(path);
+  if (Object.hasOwn(compose.services ?? {}, app.name))
+    throw new Error(`Service ${app.name} already exists`);
+  const generated: string[] = [];
+  const lock = await open(`${path}.kuber.lock`, "wx");
+  try {
+    const original = await readFile(path, "utf8");
+    const source = app.source;
+    if (source.kind === "template") {
+      const templates = renderDockerfileTemplate(source.template);
+      for (const [file, content] of [
+        ["Dockerfile", templates.dockerfile],
+        [".dockerignore", templates.dockerignore],
+      ] as const) {
+        const target = join(root, app.path, file);
+        await writeExclusive(target, content);
+        generated.push(target);
+      }
+    }
+    const lines = original.split("\n");
+    const serviceIndex = lines.findIndex((line) =>
+      /^services:\s*(?:#.*)?$/.test(line),
+    );
+    const inlineServicesIndex = lines.findIndex((line) =>
+      /^services:\s*\{\}\s*(?:#.*)?$/.test(line),
+    );
+    if (serviceIndex < 0 && Object.hasOwn(compose, "services"))
+      if (inlineServicesIndex < 0)
+        throw new Error(
+          "Cannot safely insert a service into this Compose file",
+        );
+    let updated: string;
+    if (inlineServicesIndex >= 0) {
+      const line = lines[inlineServicesIndex]!;
+      const match = /^(services:\s*)\{\}(\s*(?:#.*)?)$/.exec(line)!;
+      lines[inlineServicesIndex] =
+        `${match[1]!.trimEnd()}${match[2]!.trimEnd()}`;
+      const prefix = lines.slice(0, inlineServicesIndex + 1).join("\n") + "\n";
+      updated =
+        prefix +
+        serviceBlock(app.name, service) +
+        lines.slice(inlineServicesIndex + 1).join("\n");
+    } else if (serviceIndex < 0)
+      updated = `${original.trimEnd()}\nservices:\n${serviceBlock(app.name, service)}`;
+    else {
+      let end = serviceIndex + 1;
+      while (end < lines.length && !/^[^\s#][^:]*:/.test(lines[end]!)) end++;
+      const prefix = lines.slice(0, end).join("\n").replace(/\n*$/, "\n");
+      updated =
+        prefix + serviceBlock(app.name, service) + lines.slice(end).join("\n");
+    }
+    if ((await readFile(path, "utf8")) !== original)
+      throw new Error("Compose file changed while adding the service");
+    const temporary = join(
+      dirname(path),
+      `.${basename(path)}.${randomUUID()}.tmp`,
+    );
+    try {
+      await writeExclusive(temporary, updated);
+      await rename(temporary, path);
+    } finally {
+      await rm(temporary, { force: true });
+    }
+    return path;
+  } catch (error) {
+    await Promise.all(generated.map((file) => rm(file, { force: true })));
+    throw error;
+  } finally {
+    await lock.close();
+    await rm(`${path}.kuber.lock`, { force: true });
+  }
+}
+
+export async function createCompose(
+  root: string,
+  project: string,
+  app: AppOptions,
+): Promise<string> {
+  if (await resolveComposeFile(root))
+    throw new Error("A Compose file already exists; use kuber add app instead");
+  await checkedAppPath(root, app.path);
+  const service = serviceForApp(app);
+  const path = join(root, "compose.yml");
+  const content = `${managedHeader}\nname: ${JSON.stringify(project)}\nservices:\n${serviceBlock(app.name, service)}`;
+  const generated: string[] = [];
+  try {
+    if (app.source.kind === "template") {
+      const template = renderDockerfileTemplate(app.source.template);
+      for (const [file, text] of [
+        ["Dockerfile", template.dockerfile],
+        [".dockerignore", template.dockerignore],
+      ] as const) {
+        const target = join(root, app.path, file);
+        await writeExclusive(target, text);
+        generated.push(target);
+      }
+    }
+    await writeExclusive(path, content);
+    return path;
+  } catch (error) {
+    await Promise.all(generated.map((file) => rm(file, { force: true })));
+    throw error;
+  }
+}
diff --git a/lib/session.ts b/lib/session.ts
index 8975d4b..89cb029 100644
--- a/lib/session.ts
+++ b/lib/session.ts
@@ -52,6 +52,7 @@ function isSession(value: unknown): value is KuberSession {
   return (
     typeof session.token === "string" &&
     typeof session.expiresAt === "string" &&
+    Number.isFinite(Date.parse(session.expiresAt)) &&
     Boolean(session.user) &&
     typeof session.user?.username === "string" &&
     Array.isArray(session.user.roles) &&
@@ -64,7 +65,10 @@ async function readSessionFile(
 ): Promise<KuberSession | undefined> {
   try {
     const value: unknown = JSON.parse(await readFile(path, "utf8"));
-    if (!isSession(value)) return;
+    if (!isSession(value)) {
+      await rm(path, { force: true });
+      return;
+    }
     if (Date.parse(value.expiresAt) <= Date.now()) {
       await rm(path, { force: true });
       return;
diff --git a/lib/version-update.ts b/lib/version-update.ts
index eb73504..894ea89 100644
--- a/lib/version-update.ts
+++ b/lib/version-update.ts
@@ -1,5 +1,4 @@
 import { KUBER_VERSION } from "../shared/version";
-import { readlinkSync, statSync } from "node:fs";
 
 type SemVer = {
   major: bigint;
@@ -15,66 +14,6 @@ const INSTALL_TIMEOUT_SECONDS = 30;
 const gray = (line: string) => `\x1b[90m${line}\x1b[0m\n`;
 const reportToStderr = (line: string) => process.stderr.write(line);
 
-// This process owns the install result when the invoking CLI has already exited.
-// It opens only the original terminal (never the parent's pipe or stdout), and
-// checks its identity before writing in case the pty path has been recycled.
-const TTY_HELPER = `
-const { openSync, closeSync, fstatSync, writeSync, constants } = require('node:fs');
-const [version, seconds, path, dev, ino, rdev, uid] = process.argv.slice(1);
-let success = false;
-try {
-  const child = Bun.spawn(['timeout', '--signal=TERM', '--kill-after=2s', seconds + 's',
-    'bun', 'i', '-g', '--no-cache', '@dmgnr/kuber@' + version],
-    { stdin: 'ignore', stdout: 'ignore', stderr: 'ignore' });
-  success = (await child.exited) === 0;
-} catch {}
-try {
-  const fd = openSync(path, constants.O_WRONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
-  try {
-    const stat = fstatSync(fd);
-    if (stat.isCharacterDevice() && String(stat.dev) === dev &&
-        String(stat.ino) === ino && String(stat.rdev) === rdev && String(stat.uid) === uid) {
-      writeSync(fd, '\\x1b[90m+ ' + (success ? 'Updated to ' : 'New version available: ') +
-        version + '\\x1b[0m\\n');
-    }
-  } finally { closeSync(fd); }
-} catch {}
-`;
-
-function originalTerminal(): string[] | undefined {
-  if (!process.stderr.isTTY) return;
-  try {
-    const path = readlinkSync("/proc/self/fd/2");
-    if (!/^\/dev\/pts\/[0-9]+$/.test(path)) return;
-    const stat = statSync(path);
-    if (!stat.isCharacterDevice()) return;
-    return [
-      path,
-      String(stat.dev),
-      String(stat.ino),
-      String(stat.rdev),
-      String(stat.uid),
-    ];
-  } catch {
-    return;
-  }
-}
-
-function installWithTerminalReport(version: string, tty: string[]): void {
-  const child = Bun.spawn(
-    [
-      process.execPath,
-      "-e",
-      TTY_HELPER,
-      version,
-      String(INSTALL_TIMEOUT_SECONDS),
-      ...tty,
-    ],
-    { stdin: "ignore", stdout: "ignore", stderr: "ignore", detached: true },
-  );
-  child.unref();
-}
-
 function parseVersion(value: string | null): SemVer | undefined {
   if (!value || value.length > 128) return;
   const match = SEMVER.exec(value);
@@ -124,7 +63,7 @@ export type VersionInstallRunner = (version: string) => Promise<boolean>;
 
 type InstallProcess = {
   exited: Promise<number>;
-  unref?(): void;
+  kill(signal?: NodeJS.Signals): void;
 };
 type InstallSpawn = (
   argv: string[],
@@ -132,7 +71,7 @@ type InstallSpawn = (
     stdin: "ignore";
     stdout: "ignore";
     stderr: "ignore";
-    detached: true;
+    env: NodeJS.ProcessEnv;
   },
 ) => InstallProcess;
 
@@ -149,24 +88,51 @@ export async function installVersion(
     timeoutSeconds > 300
   )
     return false;
-  const child = spawn(
-    [
-      "timeout",
-      "--signal=TERM",
-      "--kill-after=2s",
-      `${timeoutSeconds}s`,
-      "bun",
-      "i",
-      "-g",
-      "--no-cache",
-      `@dmgnr/kuber@${version}`,
-    ],
-    { stdin: "ignore", stdout: "ignore", stderr: "ignore", detached: true },
-  );
-  // The detached timeout owns its bounded lifetime; it must not keep a short
-  // CLI invocation alive. Its result can still be observed while the parent lives.
-  child.unref?.();
-  return child.exited.then((code) => code === 0);
+  try {
+    const child = spawn(
+      [process.execPath, "i", "-g", "--no-cache", `@dmgnr/kuber@${version}`],
+      { stdin: "ignore", stdout: "ignore", stderr: "ignore", env: process.env },
+    );
+    return await new Promise<boolean>((resolve) => {
+      // Allow a short grace period to reap a child that ignores termination.
+      let timedOut = false;
+      const deadline = setTimeout(
+        () => {
+          timedOut = true;
+          try {
+            child.kill();
+          } catch {}
+          const force = setTimeout(() => {
+            try {
+              child.kill("SIGKILL");
+            } catch {}
+            resolve(false);
+          }, 1_000);
+          void child.exited.finally(() => clearTimeout(force)).catch(() => {});
+        },
+        timeoutSeconds * 1_000 - 1_000,
+      );
+      void child.exited.then(
+        (code) => {
+          clearTimeout(deadline);
+          resolve(!timedOut && code === 0);
+        },
+        () => {
+          clearTimeout(deadline);
+          resolve(false);
+        },
+      );
+    });
+  } catch {
+    return false;
+  }
+}
+
+const pendingUpdates = new Set<Promise<void>>();
+
+/** Wait for an update observed during this CLI invocation, including its notice. */
+export async function waitForVersionUpdate(): Promise<void> {
+  await Promise.all(pendingUpdates);
 }
 
 export function createVersionObserver({
@@ -184,45 +150,34 @@ export function createVersionObserver({
       return;
     attempted = true;
     // Defer install work beyond the response headers; never block body consumption.
-    setTimeout(() => {
-      // The global observer must not install packages in tests or source-tree
-      // development commands. Explicitly injected runners remain testable.
-      if (
-        runner === installVersion &&
-        (process.env.NODE_ENV === "test" ||
-          process.env.NODE_ENV === "development" ||
-          process.argv[1]?.endsWith(".ts"))
-      )
-        return;
-      if (runner === installVersion && report === reportToStderr) {
-        const tty = originalTerminal();
-        if (tty) {
-          try {
-            installWithTerminalReport(version, tty);
-          } catch {
-            try {
-              report(gray(`+ New version available: ${version}`));
-            } catch {}
-          }
-          return;
-        }
-      }
-      void Promise.resolve()
-        .then(() => runner(version))
-        .then(
-          (success) => {
-            report(
-              gray(
-                `+ ${success ? "Updated to " : "New version available: "}${version}`,
-              ),
-            );
-          },
-          () => report(gray(`+ New version available: ${version}`)),
+    const pending = new Promise<void>((resolve) => setTimeout(resolve, 0)).then(
+      async () => {
+        // The global observer must not install packages in tests or source-tree
+        // development commands. Explicitly injected runners remain testable.
+        if (
+          runner === installVersion &&
+          (process.env.NODE_ENV === "test" ||
+            process.env.NODE_ENV === "development" ||
+            process.argv[1]?.endsWith(".ts"))
         )
-        .catch(() => {
+          return;
+        let success = false;
+        try {
+          success = await runner(version);
+        } catch {}
+        try {
+          report(
+            gray(
+              `+ ${success ? "Updated to " : "New version available: "}${version}`,
+            ),
+          );
+        } catch {
           // A broken stderr must never affect an API request or command exit status.
-        });
-    }, 0);
+        }
+      },
+    );
+    pendingUpdates.add(pending);
+    void pending.finally(() => pendingUpdates.delete(pending));
   };
 }
 
diff --git a/lib/workspace.ts b/lib/workspace.ts
index d0b2d82..f68d7a0 100644
--- a/lib/workspace.ts
+++ b/lib/workspace.ts
@@ -14,7 +14,14 @@ import {
   readFile,
 } from "node:fs/promises";
 import type { Stats } from "node:fs";
-import { delimiter, dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import {
+  delimiter,
+  dirname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+} from "node:path";
 import { promisify } from "node:util";
 import {
   BUILD_PROTOCOL_VERSION,
@@ -30,9 +37,14 @@ export async function gitAvailable(): Promise<boolean> {
   for (const directory of (process.env.PATH ?? "").split(delimiter)) {
     if (!directory) continue;
     try {
-      await access(resolve(directory, process.platform === "win32" ? "git.exe" : "git"), constants.X_OK);
+      await access(
+        resolve(directory, process.platform === "win32" ? "git.exe" : "git"),
+        constants.X_OK,
+      );
       return true;
-    } catch { /* Continue searching PATH. */ }
+    } catch {
+      /* Continue searching PATH. */
+    }
   }
   return false;
 }
@@ -76,6 +88,36 @@ function isWithin(root: string, candidate: string): boolean {
   );
 }
 
+function assertSafeSymlinkTarget(
+  root: string,
+  path: string,
+  target: string,
+  symlinks: Set<string>,
+): void {
+  const source = resolve(root, path);
+  if (
+    target.includes("\0") ||
+    isAbsolute(target) ||
+    !isWithin(root, resolve(dirname(source), target))
+  )
+    throw new Error(`Symlink escapes workspace: ${path} -> ${target}`);
+
+  // Inspect raw components before normalization: `sub/..` still traverses
+  // `sub` when it is a symlink, even though it resolves lexically to `.`.
+  const components = path.split("/").slice(0, -1);
+  for (const part of target.split(sep === "\\" ? /[\\/]/ : "/")) {
+    if (!part || part === ".") continue;
+    if (part === "..") components.pop();
+    else {
+      components.push(part);
+      if (symlinks.has(components.join("/")))
+        throw new Error(
+          `Symlink traverses snapshot symlink: ${path} -> ${target}`,
+        );
+    }
+  }
+}
+
 async function gitFiles(root: string, args: string[]): Promise<string[]> {
   const { stdout } = await execFileAsync(
     "git",
@@ -116,16 +158,127 @@ async function selectedFiles(root: string): Promise<string[]> {
   );
 }
 
+async function selectedAutoFiles(root: string): Promise<string[]> {
+  // ls-files includes tracked files even when they now match .gitignore.
+  // --no-index makes check-ignore apply the same rules to those paths too.
+  const candidates = await gitFiles(root, [
+    "--cached",
+    "--others",
+    "--exclude-standard",
+  ]);
+  if (candidates.length === 0) return [];
+  const child = spawn("git", [
+    "-C",
+    root,
+    "check-ignore",
+    "--no-index",
+    "--stdin",
+    "-z",
+  ]);
+  const output: Buffer[] = [];
+  const errors: Buffer[] = [];
+  child.stdout.on("data", (chunk: Buffer) => output.push(chunk));
+  child.stderr.on("data", (chunk: Buffer) => errors.push(chunk));
+  const completed = new Promise<void>((resolveExit, rejectExit) => {
+    child.once("error", rejectExit);
+    child.once("close", (code) => {
+      if (code === 0 || code === 1) resolveExit();
+      else
+        rejectExit(
+          new Error(
+            Buffer.concat(errors).toString("utf8") ||
+              `git check-ignore exited with ${code}`,
+          ),
+        );
+    });
+  });
+  child.stdin.end(Buffer.from(`${candidates.join("\0")}\0`));
+  await completed;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  // Decode strictly, like ls-files, so an invalid path cannot silently alias another.
+  const ignored = new Set<string>();
+  const bytes = Buffer.concat(output);
+  let start = 0;
+  for (let end = bytes.indexOf(0); end !== -1; end = bytes.indexOf(0, start)) {
+    if (end > start) ignored.add(decoder.decode(bytes.subarray(start, end)));
+    start = end + 1;
+  }
+  const selected = candidates
+    .filter((path) => !ignored.has(path))
+    .sort((a, b) => Buffer.from(a).compare(Buffer.from(b)));
+  rejectSelectedAutoSecrets(selected);
+  return selected;
+}
+
+function rejectSelectedAutoSecrets(paths: string[]): void {
+  const unsafe = paths.find((path) => {
+    const parts = path.split("/");
+    const name = parts.at(-1)!.toLowerCase();
+    const directories = parts.slice(0, -1).map((part) => part.toLowerCase());
+    const dotenv =
+      /^\.env(?:$|[._-]|rc$)/.test(name) &&
+      !/^\.env[._-](?:example|sample|template)(?:$|[._-])/.test(name);
+    const credentialDirectory = directories.some((part) =>
+      [
+        ".aws",
+        ".azure",
+        ".gnupg",
+        ".ssh",
+        ".kube",
+        ".docker",
+        "credentials",
+        "secrets",
+      ].includes(part),
+    );
+    const conventionalCredential =
+      [".npmrc", ".pypirc", ".netrc"].includes(name) ||
+      /^(?:id_(?:rsa|dsa|ecdsa|ed25519)|identity)(?:$|\.)/.test(name) ||
+      /^(?:credentials?|.*_credentials?)(?:\.|$)/.test(name) ||
+      /\.(?:pem|key|p12|pfx|keystore)$/.test(name);
+    return dotenv || credentialDirectory || conventionalCredential;
+  });
+  if (unsafe) {
+    throw new Error(
+      `build: auto refuses to snapshot potential credentials at ${unsafe}; add it to .gitignore and retry`,
+    );
+  }
+}
+
 async function filesystemFiles(root: string): Promise<string[]> {
   const files: string[] = [];
   const ignoredDirectories = new Set([
-    ".git", ".hg", ".svn", "node_modules", "vendor", "bower_components",
-    ".venv", "venv", "__pycache__", ".tox", ".mypy_cache", ".pytest_cache",
-    ".next", ".nuxt", ".svelte-kit", ".cache", ".turbo", "dist", "build", "coverage",
-    "target", "out", "tmp", "temp",
+    ".git",
+    ".hg",
+    ".svn",
+    "node_modules",
+    "vendor",
+    "bower_components",
+    ".venv",
+    "venv",
+    "__pycache__",
+    ".tox",
+    ".mypy_cache",
+    ".pytest_cache",
+    ".next",
+    ".nuxt",
+    ".svelte-kit",
+    ".cache",
+    ".turbo",
+    "dist",
+    "build",
+    "coverage",
+    "target",
+    "out",
+    "tmp",
+    "temp",
   ]);
-  const sensitiveDirectory = /(?:^|[-_.])(?:secrets?|credentials?|configs?)(?:$|[-_.])/i;
-  const ignoreRules: Array<{ base: string; pattern: string; directory: boolean }> = [];
+  const sensitiveDirectory =
+    /(?:^|[-_.])(?:secrets?|credentials?|configs?)(?:$|[-_.])/i;
+  const ignoreRules: Array<{
+    base: string;
+    pattern: string;
+    directory: boolean;
+  }> = [];
   const loadIgnore = async (directory: string): Promise<void> => {
     try {
       const content = await readFile(resolve(directory, ".gitignore"), "utf8");
@@ -136,7 +289,12 @@ async function filesystemFiles(root: string): Promise<string[]> {
         // Git's parent-directory semantics, so fallback stays fail-closed.
         if (line.startsWith("!")) continue;
         const rule = line.replace(/^\//, "");
-        if (rule) ignoreRules.push({ base: relative(root, directory).split(sep).join("/"), pattern: rule.replace(/\/$/, ""), directory: line.endsWith("/") });
+        if (rule)
+          ignoreRules.push({
+            base: relative(root, directory).split(sep).join("/"),
+            pattern: rule.replace(/\/$/, ""),
+            directory: line.endsWith("/"),
+          });
       }
     } catch (error) {
       if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
@@ -147,11 +305,22 @@ async function filesystemFiles(root: string): Promise<string[]> {
     for (const rule of ignoreRules) {
       const prefix = rule.base ? `${rule.base}/` : "";
       if (rule.base && path !== rule.base && !path.startsWith(prefix)) continue;
-      const local = rule.base && path.startsWith(prefix) ? path.slice(prefix.length) : path;
-      const glob = rule.pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "__DOUBLESTAR__").replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]").replace(/__DOUBLESTAR__/g, ".*");
+      const local =
+        rule.base && path.startsWith(prefix) ? path.slice(prefix.length) : path;
+      const glob = rule.pattern
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*\*/g, "__DOUBLESTAR__")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]")
+        .replace(/__DOUBLESTAR__/g, ".*");
       const matcher = new RegExp(`^(?:${glob})(?:/.*)?$`);
       const basenameMatcher = new RegExp(`^(?:${glob})$`);
-      if ((matcher.test(local) || local.split("/").some((part) => basenameMatcher.test(part))) && (!rule.directory || isDirectory || local.includes("/"))) ignored = true;
+      if (
+        (matcher.test(local) ||
+          local.split("/").some((part) => basenameMatcher.test(part))) &&
+        (!rule.directory || isDirectory || local.includes("/"))
+      )
+        ignored = true;
     }
     return ignored;
   };
@@ -161,15 +330,30 @@ async function filesystemFiles(root: string): Promise<string[]> {
       const source = resolve(directory, entry.name);
       const path = relative(root, source).split(sep).join("/");
       if (entry.isDirectory()) {
-        if (ignoredDirectories.has(entry.name) || sensitiveDirectory.test(entry.name) || ignoredByRules(path, true)) continue;
+        if (
+          ignoredDirectories.has(entry.name) ||
+          sensitiveDirectory.test(entry.name) ||
+          ignoredByRules(path, true)
+        )
+          continue;
         await visit(source);
-      }
-      else if (entry.isFile() || entry.isSymbolicLink()) {
+      } else if (entry.isFile() || entry.isSymbolicLink()) {
         if (ignoredByRules(path, false)) continue;
-        if (/^\.env/i.test(entry.name) || /(?:secret|credential|password|token|private[-_.]?key)/i.test(entry.name) || /^(?:id_rsa|id_ed25519|known_hosts|config\.json|\.npmrc|\.pypirc|\.netrc)$/i.test(entry.name)) continue;
+        if (
+          /^\.env/i.test(entry.name) ||
+          /(?:secret|credential|password|token|private[-_.]?key)/i.test(
+            entry.name,
+          ) ||
+          /^(?:id_rsa|id_ed25519|known_hosts|config\.json|\.npmrc|\.pypirc|\.netrc)$/i.test(
+            entry.name,
+          )
+        )
+          continue;
         files.push(path);
       } else {
-        throw new Error(`Special files are not allowed in workspaces: ${relative(root, source).split(sep).join("/")}`);
+        throw new Error(
+          `Special files are not allowed in workspaces: ${relative(root, source).split(sep).join("/")}`,
+        );
       }
     }
   };
@@ -187,7 +371,12 @@ async function isGitRepository(root: string): Promise<boolean> {
     const exitCode = (error as { exitCode?: number }).exitCode;
     const message = error instanceof Error ? error.message : String(error);
     if (code === "ENOENT") return false;
-    if (exitCode === 128 || code === 128 || /not a git repository/i.test(message)) return false;
+    if (
+      exitCode === 128 ||
+      code === 128 ||
+      /not a git repository/i.test(message)
+    )
+      return false;
     throw error;
   }
 }
@@ -347,15 +536,23 @@ export function validateWorkspaceManifest(manifest: WorkspaceManifest): void {
 
 export async function enumerateWorkspace(
   root: string,
+  mode: "default" | "auto" = "default",
 ): Promise<WorkspaceSnapshot> {
   const repository = await realpath(root);
   const gitBacked = await isGitRepository(repository);
-  const paths = gitBacked
-    ? await (async () => {
-        await rejectSelectedSpecialFiles(repository);
-        return selectedFiles(repository);
-      })()
-    : await filesystemFiles(repository);
+  if (mode === "auto" && !gitBacked)
+    throw new Error(
+      "build: auto requires Git and a Git repository to apply .gitignore rules safely",
+    );
+  const paths =
+    mode === "auto"
+      ? await selectedAutoFiles(repository)
+      : gitBacked
+        ? await (async () => {
+            await rejectSelectedSpecialFiles(repository);
+            return selectedFiles(repository);
+          })()
+        : await filesystemFiles(repository);
   const files: WorkspaceFile[] = [];
   const blobs = new Map<Sha256Digest, Uint8Array>();
 
@@ -364,6 +561,19 @@ export async function enumerateWorkspace(
     const source = resolve(repository, path);
     if (!isWithin(repository, source))
       throw new Error(`Workspace path escapes root: ${path}`);
+    // Git's index can retain files beneath a directory replaced by a symlink.
+    // A leaf O_NOFOLLOW does not protect against following that parent.
+    let parent = repository;
+    for (const part of path.split("/").slice(0, -1)) {
+      parent = resolve(parent, part);
+      try {
+        if (!(await lstat(parent)).isDirectory())
+          throw new Error(`Unsafe workspace parent: ${path}`);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") break;
+        throw error;
+      }
+    }
 
     let stat: Stats;
     try {
@@ -377,11 +587,6 @@ export async function enumerateWorkspace(
     let entry: WorkspaceFile;
     if (stat.isSymbolicLink()) {
       const target = await readlink(source);
-      if (
-        isAbsolute(target) ||
-        !isWithin(repository, resolve(dirname(source), target))
-      )
-        throw new Error(`Symlink escapes workspace: ${path} -> ${target}`);
       data = Buffer.from(target);
       entry = {
         path,
@@ -422,6 +627,18 @@ export async function enumerateWorkspace(
     version: BUILD_PROTOCOL_VERSION,
     files,
   } satisfies WorkspaceManifest;
+  const symlinks = new Set(
+    files.filter((file) => file.type === "symlink").map((file) => file.path),
+  );
+  for (const file of files) {
+    if (file.type === "symlink")
+      assertSafeSymlinkTarget(
+        repository,
+        file.path,
+        Buffer.from(blobs.get(file.digest)!).toString("utf8"),
+        symlinks,
+      );
+  }
   return {
     manifest,
     digest: workspaceManifestDigest(manifest),
@@ -465,6 +682,21 @@ export async function materializeWorkspace(
   reader: BlobReader,
 ): Promise<void> {
   validateWorkspaceManifest(manifest);
+  const symlinks = new Set(
+    manifest.files
+      .filter((file) => file.type === "symlink")
+      .map((file) => file.path),
+  );
+  const linkTargets = new Map<string, string>();
+  for (const file of manifest.files) {
+    if (file.type !== "symlink") continue;
+    const data = await readBlob(reader, file.digest);
+    if (data.byteLength !== file.size || digest(data) !== file.digest)
+      throw new Error(`Blob verification failed for ${file.path}`);
+    const linkTarget = Buffer.from(data).toString("utf8");
+    assertSafeSymlinkTarget(destination, file.path, linkTarget, symlinks);
+    linkTargets.set(file.path, linkTarget);
+  }
   await mkdir(destination, { recursive: false, mode: 0o755 });
   const root = await realpath(destination);
 
@@ -492,19 +724,8 @@ export async function materializeWorkspace(
     (entry) => entry.type === "symlink",
   )) {
     await ensureParentDirectories(root, file.path);
-    const data = await readBlob(reader, file.digest);
-    if (data.byteLength !== file.size || digest(data) !== file.digest)
-      throw new Error(`Blob verification failed for ${file.path}`);
-    const linkTarget = Buffer.from(data).toString("utf8");
+    const linkTarget = linkTargets.get(file.path)!;
     const target = resolve(root, file.path);
-    if (
-      linkTarget.includes("\0") ||
-      isAbsolute(linkTarget) ||
-      !isWithin(root, resolve(dirname(target), linkTarget))
-    )
-      throw new Error(
-        `Symlink escapes workspace: ${file.path} -> ${linkTarget}`,
-      );
     await symlink(linkTarget, target);
   }
 }
diff --git a/lib/yaml.ts b/lib/yaml.ts
index a416007..7557e54 100644
--- a/lib/yaml.ts
+++ b/lib/yaml.ts
@@ -16,10 +16,28 @@ let composeSchema: Promise<z.ZodType<ComposeSpecification>> | undefined;
 function getComposeSchema(): Promise<z.ZodType<ComposeSpecification>> {
   if (!composeSchema) {
     composeSchema = import("../schema/docker.ts")
-      .then(({ default: schema }) =>
-        z.fromJSONSchema(
-          schema as unknown as Parameters<typeof z.fromJSONSchema>[0],
-        ) as z.ZodType<ComposeSpecification>,
+      .then(
+        ({ default: schema }) =>
+          z
+            .fromJSONSchema(
+              schema as unknown as Parameters<typeof z.fromJSONSchema>[0],
+            )
+            .superRefine((value, context) => {
+              if (!value || typeof value !== "object" || Array.isArray(value))
+                return;
+              for (const key of Object.keys(value)) {
+                if (
+                  Object.hasOwn(schema.properties, key) ||
+                  key.startsWith("x-")
+                )
+                  continue;
+                context.addIssue({
+                  code: "custom",
+                  path: [key],
+                  message: `Unrecognized Compose property: ${key}`,
+                });
+              }
+            }) as z.ZodType<ComposeSpecification>,
       )
       .catch((error) => {
         composeSchema = undefined;
diff --git a/package.json b/package.json
index ae54cce..0cc66ac 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@dmgnr/kuber",
-  "version": "2.6.2-rc2",
+  "version": "2.7.0-rc2",
   "description": "Docker Compose to Kubernetes translation layer",
   "bin": {
     "kuber": "dist/index.js"
diff --git a/schema/docker.d.ts b/schema/docker.d.ts
index b06d507..a308725 100644
--- a/schema/docker.d.ts
+++ b/schema/docker.d.ts
@@ -1164,6 +1164,7 @@ export type Volume1 = {
  * The Compose file is a YAML file defining a multi-containers based application.
  */
 export interface ComposeSpecification {
+  managedBy?: "kuber";
   /**
    * @deprecated
    * declared for backward compatibility, ignored. Please remove it.
@@ -1518,7 +1519,10 @@ export interface Service {
           /**
            * Condition to wait for. 'service_started' waits until the service has started, 'service_healthy' waits until the service is healthy (as defined by its healthcheck), 'service_completed_successfully' waits until the service has completed successfully.
            */
-          condition: "service_started" | "service_healthy" | "service_completed_successfully";
+          condition:
+            | "service_started"
+            | "service_healthy"
+            | "service_completed_successfully";
           /**
            * This interface was referenced by `undefined`'s JSON-Schema definition
            * via the `patternProperty` "^x-".
diff --git a/schema/docker.ts b/schema/docker.ts
index 4ed581f..f989d60 100644
--- a/schema/docker.ts
+++ b/schema/docker.ts
@@ -6,6 +6,9 @@ export default {
   description:
     "The Compose file is a YAML file defining a multi-containers based application.",
   properties: {
+    managedBy: {
+      const: "kuber",
+    },
     version: {
       type: "string",
       deprecated: true,
diff --git a/server/build-controller.ts b/server/build-controller.ts
index d68647e..8cd3b51 100644
--- a/server/build-controller.ts
+++ b/server/build-controller.ts
@@ -4,12 +4,18 @@ import { join } from "node:path";
 import {
   BUILD_PROTOCOL_VERSION,
   assertSha256Digest,
+  validateBuildpackUri,
   type BuildEvent,
   type BuildRequest,
   type BuildStatus,
   type Sha256Digest,
 } from "../shared/build-protocol";
 import { createBuildJob, type KubernetesJob } from "./build-job";
+import {
+  createBuildpacksJob,
+  DEFAULT_BUILDPACKS_IMAGE,
+  validateBuildpacksImage,
+} from "./buildpacks-job";
 import {
   BUILD_RECORD_API_VERSION,
   BuildStoreConflictError,
@@ -26,6 +32,7 @@ import {
   type MaterializeTiming,
 } from "./materialize";
 import { parseImageReference, resolveRegistryDigest } from "./registry";
+import { stageBuildpackPackage } from "./buildpack-package";
 
 export const DEFAULT_MAX_BLOB_BYTES = 1024 * 1024 * 1024;
 export const DEFAULT_MAX_UPLOAD_CHUNK_BYTES = 8 * 1024 * 1024;
@@ -40,7 +47,12 @@ export interface BuildCas extends MaterializeCas {
 }
 
 export type JobPhase =
-  "queued" | "creating" | "starting" | "running" | "succeeded" | "failed";
+  | "queued"
+  | "creating"
+  | "starting"
+  | "running"
+  | "succeeded"
+  | "failed";
 
 export interface BuildJobObservation {
   phase: JobPhase;
@@ -79,6 +91,8 @@ export interface BuildControllerOptions {
   pushRegistryInsecure?: boolean;
   cacheRegistryInsecure?: boolean;
   buildkitImage?: string;
+  buildpacksImage?: string;
+  stageBuildpack?: typeof stageBuildpackPackage;
   serviceAccountName?: string;
   registrySecretName?: string;
   nodeSelector?: Record<string, string>;
@@ -182,6 +196,33 @@ function validateRequest(request: BuildRequest): void {
     throw new BuildValidationError("Build ID is too long");
   if (!request.spec || !["amd64", "arm64"].includes(request.spec.architecture))
     throw new BuildValidationError("Invalid build architecture");
+  if (
+    request.spec.builder !== undefined &&
+    request.spec.builder !== "buildkit" &&
+    request.spec.builder !== "buildpacks"
+  )
+    throw new BuildValidationError("Invalid build builder");
+  if (request.spec.buildpackUri !== undefined) {
+    if (request.spec.builder !== "buildpacks")
+      throw new BuildValidationError(
+        "buildpackUri requires the buildpacks builder",
+      );
+    try {
+      validateBuildpackUri(request.spec.buildpackUri);
+    } catch (error) {
+      throw new BuildValidationError((error as Error).message);
+    }
+  }
+  if (request.spec.builder === "buildpacks") {
+    if (
+      request.spec.dockerfile !== undefined ||
+      request.spec.target !== undefined ||
+      request.spec.buildArgs?.length
+    )
+      throw new BuildValidationError(
+        "Buildpacks does not support dockerfile, target, or buildArgs",
+      );
+  }
   if (
     !Array.isArray(request.spec.buildArgs) ||
     !request.spec.buildArgs.every((value) => typeof value === "string")
@@ -446,6 +487,15 @@ export class BuildController {
         }),
       }));
     validateRequest(request);
+    if (request.spec.builder === "buildpacks") {
+      try {
+        validateBuildpacksImage(
+          this.options.buildpacksImage ?? DEFAULT_BUILDPACKS_IMAGE,
+        );
+      } catch (error) {
+        throw new BuildValidationError((error as Error).message);
+      }
+    }
     const imageKey = `${request.project}\0${request.service}\0${request.spec.image}`;
     const started = performance.now();
     const previous =
@@ -585,6 +635,13 @@ export class BuildController {
             join(this.options.workspaceRoot, superseded.spec.workspaceSubPath),
             { recursive: true, force: true },
           ).catch(() => undefined);
+          await rm(
+            join(
+              this.options.workspaceRoot,
+              `${superseded.spec.workspaceSubPath}-buildpack`,
+            ),
+            { recursive: true, force: true },
+          ).catch(() => undefined);
         }
       });
       if (!result.created) return recordStatus(stored);
@@ -615,6 +672,15 @@ export class BuildController {
           materialize,
         ),
       );
+      const packageSubPath = `${stored.spec.workspaceSubPath}-buildpack`;
+      if (request.spec.buildpackUri)
+        await timed("buildpackStageMs", () =>
+          (this.options.stageBuildpack ?? stageBuildpackPackage)(
+            request.spec.buildpackUri!,
+            request.spec.architecture,
+            join(this.options.workspaceRoot, packageSubPath),
+          ),
+        );
       if (
         this.options.store.ownsBuild &&
         !(await timed("finalOwnershipMs", () =>
@@ -625,10 +691,29 @@ export class BuildController {
           `Build '${request.id}' lost image lock before Job creation`,
         );
       const job = await timed("jobSpecMs", async () => {
-        const cacheImage =
+        let cacheImage =
           typeof this.options.cacheImage === "function"
             ? this.options.cacheImage(request)
             : this.options.cacheImage;
+        if (request.spec.buildpackUri) {
+          const suffix = createHash("sha256")
+            .update(
+              JSON.stringify([
+                cacheImage,
+                request.spec.architecture,
+                request.spec.buildpackUri,
+              ]),
+            )
+            .digest("hex")
+            .slice(0, 24);
+          const colon = cacheImage.lastIndexOf(":");
+          const slash = cacheImage.lastIndexOf("/");
+          if (cacheImage.includes("@"))
+            throw new BuildValidationError(
+              "Build cache must be a tag, not a digest",
+            );
+          cacheImage = `${colon > slash ? cacheImage.slice(0, colon) : cacheImage}:buildpack-${suffix}`;
+        }
         const pushImage = this.options.pushImage
           ? this.options.pushImage(request)
           : request.spec.image;
@@ -642,7 +727,7 @@ export class BuildController {
               })
             : destination.image,
         );
-        return createBuildJob({
+        const jobOptions = {
           name: jobName,
           namespace: this.options.namespace,
           spec: request.spec,
@@ -663,7 +748,22 @@ export class BuildController {
           registrySecretName: this.options.registrySecretName,
           nodeSelector: this.options.nodeSelector,
           tolerations: this.options.tolerations,
-        });
+        };
+        return request.spec.builder === "buildpacks"
+          ? createBuildpacksJob({
+              ...jobOptions,
+              buildpacksImage: this.options.buildpacksImage,
+              ...(request.spec.buildpackUri && {
+                buildpackSubPath: jobWorkspaceSubPath(
+                  this.options.workspaceRoot,
+                  packageSubPath,
+                ),
+              }),
+              cacheRegistryInsecure:
+                this.options.cacheRegistryInsecure ??
+                this.options.pushRegistryInsecure,
+            })
+          : createBuildJob(jobOptions);
       });
       await timed("jobCreateMs", () => this.options.kubernetes.createJob(job));
       markJobCreated();
@@ -680,6 +780,17 @@ export class BuildController {
         } catch {
           // Job cleanup is best effort; the record still releases its lock.
         }
+        await rm(
+          join(this.options.workspaceRoot, stored.spec.workspaceSubPath),
+          { recursive: true, force: true },
+        ).catch(() => undefined);
+        await rm(
+          join(
+            this.options.workspaceRoot,
+            `${stored.spec.workspaceSubPath}-buildpack`,
+          ),
+          { recursive: true, force: true },
+        ).catch(() => undefined);
         await this.failBuild(
           stored.metadata.name,
           error instanceof Error ? error.message : String(error),
@@ -975,6 +1086,13 @@ export class BuildController {
       recursive: true,
       force: true,
     });
+    await rm(
+      join(
+        this.options.workspaceRoot,
+        `${record.spec.workspaceSubPath}-buildpack`,
+      ),
+      { recursive: true, force: true },
+    );
   }
 
   async getBuildResult(id: string): Promise<{
diff --git a/server/buildpack-package.ts b/server/buildpack-package.ts
new file mode 100644
index 0000000..78c0756
--- /dev/null
+++ b/server/buildpack-package.ts
@@ -0,0 +1,436 @@
+import { createHash } from "node:crypto";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { gunzipSync } from "node:zlib";
+import {
+  validateBuildpackUri,
+  type BuildArchitecture,
+} from "../shared/build-protocol";
+
+export const BUILDPACK_LIMITS = {
+  download: 64 * 1024 * 1024,
+  expanded: 256 * 1024 * 1024,
+  file: 32 * 1024 * 1024,
+  entries: 10000,
+  redirects: 5,
+  timeoutMs: 60000,
+};
+type Entry = { path: string; data: Buffer; mode: number; directory: boolean };
+const hash = (data: Uint8Array) =>
+  `sha256:${createHash("sha256").update(data).digest("hex")}`;
+const fail = (message: string): never => {
+  throw new Error(`Invalid buildpack package: ${message}`);
+};
+
+/** Redirects are checked before any network request, with one deadline for the entire transfer. */
+export type PackageFetcher = (
+  url: string,
+  init?: RequestInit,
+) => Promise<Response>;
+export async function fetchBuildpackPackage(
+  uri: string,
+  fetcher: PackageFetcher = fetch,
+): Promise<Buffer> {
+  validateBuildpackUri(uri);
+  let url = new URL(uri);
+  const pin = url.hash.slice("#sha256=".length);
+  url.hash = "";
+  const signal = AbortSignal.timeout(BUILDPACK_LIMITS.timeoutMs);
+  for (
+    let redirects = 0;
+    redirects <= BUILDPACK_LIMITS.redirects;
+    redirects++
+  ) {
+    if (
+      url.protocol !== "https:" ||
+      url.username ||
+      url.password ||
+      url.port ||
+      !["github.com", "release-assets.githubusercontent.com"].includes(
+        url.hostname,
+      )
+    )
+      fail("redirect must remain on an allowed HTTPS release host");
+    const response = await fetcher(url.href, {
+      redirect: "manual",
+      signal,
+      headers: { Accept: "application/octet-stream" },
+    });
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      await response.body?.cancel();
+      const location = response.headers.get("location");
+      if (!location || redirects === BUILDPACK_LIMITS.redirects)
+        fail("redirect limit or missing Location");
+      url = new URL(location!, url);
+      if (url.hash) fail("redirect fragment is unsupported");
+      continue;
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      fail(`download HTTP ${response.status}`);
+    }
+    const size = response.headers.get("content-length");
+    if (
+      size &&
+      (!/^\d+$/.test(size) || Number(size) > BUILDPACK_LIMITS.download)
+    ) {
+      await response.body?.cancel();
+      fail("download exceeds size limit");
+    }
+    if (!response.body) fail("empty download");
+    const reader = response.body!.getReader();
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    try {
+      for (;;) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        total += value.byteLength;
+        if (total > BUILDPACK_LIMITS.download)
+          fail("download exceeds size limit");
+        chunks.push(value);
+      }
+    } catch (error) {
+      await reader.cancel().catch(() => {});
+      throw error;
+    } finally {
+      reader.releaseLock();
+    }
+    const bytes = Buffer.concat(chunks, total);
+    if (pin && hash(bytes) !== `sha256:${pin}`)
+      fail("download SHA-256 mismatch");
+    return bytes;
+  }
+  return fail("redirect limit");
+}
+
+function expand(bytes: Buffer): Buffer {
+  if (bytes[0] === 0x1f && bytes[1] === 0x8b)
+    return gunzipSync(bytes, { maxOutputLength: BUILDPACK_LIMITS.expanded });
+  if (bytes.length > BUILDPACK_LIMITS.expanded) fail("expanded size limit");
+  return bytes;
+}
+
+/** Only regular files/directories, strict ustar paths, no links/PAX/GNU extension interpretation. */
+export function parseBuildpackTar(
+  bytes: Buffer,
+  kind: "oci" | "layer",
+): Entry[] {
+  bytes = expand(bytes);
+  const entries: Entry[] = [];
+  const seen = new Map<string, boolean>();
+  const implicitDirectories = new Set<string>();
+  const text = (b: Buffer) => b.toString("utf8").split("\0")[0]!;
+  const octal = (b: Buffer) => {
+    const value = text(b).trim();
+    if (!/^[0-7]+$/.test(value)) return fail("invalid tar numeric field");
+    const number = parseInt(value, 8);
+    if (!Number.isSafeInteger(number)) fail("invalid tar numeric field");
+    return number;
+  };
+  for (let offset = 0; offset + 512 <= bytes.length;) {
+    const header = bytes.subarray(offset, offset + 512);
+    if (header.every((byte) => byte === 0)) {
+      if (
+        bytes.length - offset < 1024 ||
+        !bytes.subarray(offset).every((byte) => byte === 0)
+      )
+        fail("invalid tar trailer");
+      return entries;
+    }
+    if (text(header.subarray(257, 263)) !== "ustar")
+      fail("unsupported tar format");
+    const checksum = header.reduce(
+      (sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte),
+      0,
+    );
+    if (checksum !== octal(header.subarray(148, 156)))
+      fail("tar checksum mismatch");
+    const type = header[156];
+    if (![0, 48, 53].includes(type!))
+      fail("tar links and special entries are unsupported");
+    const directory = type === 53;
+    const prefix = text(header.subarray(345, 500));
+    let path = `${prefix ? `${prefix}/` : ""}${text(header.subarray(0, 100))}`;
+    // pack emits these known absolute OCI/CNB roots. No general absolute-path stripping.
+    if (
+      kind === "oci" &&
+      /^\/(?:blobs(?:\/|$)|index\.json$|oci-layout$)/.test(path)
+    )
+      path = path.slice(1);
+    if (
+      kind === "layer" &&
+      (path.startsWith("/cnb/buildpacks/") ||
+        (directory && ["/cnb", "/cnb/", "/cnb/buildpacks"].includes(path)))
+    )
+      path = path.slice(1);
+    if (path.startsWith("./")) path = path.slice(2);
+    if (directory && path.endsWith("/")) path = path.slice(0, -1);
+    if (
+      !path ||
+      path.includes("\\") ||
+      [...path].some(
+        (char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127,
+      ) ||
+      path.split("/").some((part) => !part || part === "." || part === "..") ||
+      /^[A-Za-z]:/.test(path)
+    )
+      fail("unsafe tar path");
+    if (seen.has(path)) fail("duplicate tar path");
+    for (let parent = dirname(path); parent !== "."; parent = dirname(parent)) {
+      if (seen.get(parent) === false) fail("tar file used as directory");
+      implicitDirectories.add(parent);
+    }
+    if (!directory && implicitDirectories.has(path))
+      fail("tar directory replaced by file");
+    const size = octal(header.subarray(124, 136));
+    if (size > BUILDPACK_LIMITS.file || (directory && size !== 0))
+      fail("tar file size limit");
+    const end = offset + 512 + Math.ceil(size / 512) * 512;
+    if (end > bytes.length) fail("truncated tar entry");
+    entries.push({
+      path,
+      directory,
+      mode: octal(header.subarray(100, 108)) & 0o111 ? 0o755 : 0o644,
+      data: bytes.subarray(offset + 512, offset + 512 + size),
+    });
+    seen.set(path, directory);
+    if (entries.length > BUILDPACK_LIMITS.entries) fail("tar entry limit");
+    offset = end;
+  }
+  return fail("missing tar trailer");
+}
+
+function json(data: Uint8Array): any {
+  if (data.byteLength > 1024 * 1024) fail("JSON metadata size limit");
+  try {
+    const value = JSON.parse(Buffer.from(data).toString());
+    if (!value || typeof value !== "object" || Array.isArray(value))
+      fail("expected JSON metadata object");
+    return value;
+  } catch {
+    return fail("invalid JSON metadata");
+  }
+}
+
+/** Validate the complete OCI descriptor chain before writing any package files. */
+export function unpackBuildpackPackage(
+  bytes: Buffer,
+  architecture: BuildArchitecture,
+): { id: string; version: string; entries: Entry[] } {
+  const outer = parseBuildpackTar(bytes, "oci");
+  if (
+    outer.some(
+      (entry) =>
+        !/^(?:blobs(?:\/sha256(?:\/[a-f0-9]{64})?)?|index\.json|oci-layout)$/.test(
+          entry.path,
+        ),
+    )
+  )
+    fail("unexpected OCI path");
+  const files = new Map(
+    outer
+      .filter((entry) => !entry.directory)
+      .map((entry) => [entry.path, entry.data]),
+  );
+  const required = (path: string) => files.get(path) ?? fail(`missing ${path}`);
+  if (json(required("oci-layout")).imageLayoutVersion !== "1.0.0")
+    fail("unsupported OCI layout");
+  const blob = (descriptor: any, media: string[]) => {
+    if (
+      !descriptor ||
+      !/^sha256:[a-f0-9]{64}$/.test(descriptor.digest) ||
+      !Number.isSafeInteger(descriptor.size) ||
+      descriptor.size < 0 ||
+      !media.includes(descriptor.mediaType)
+    )
+      fail("invalid OCI descriptor");
+    const data = required(`blobs/sha256/${descriptor.digest.slice(7)}`);
+    if (data.length !== descriptor.size || hash(data) !== descriptor.digest)
+      fail("OCI descriptor size/digest mismatch");
+    return data;
+  };
+  const index = json(required("index.json"));
+  if (
+    index.schemaVersion !== 2 ||
+    !Array.isArray(index.manifests) ||
+    index.manifests.length !== 1
+  )
+    fail("expected one OCI image manifest");
+  const manifest = json(
+    blob(index.manifests[0], [
+      "application/vnd.oci.image.manifest.v1+json",
+      "application/vnd.docker.distribution.manifest.v2+json",
+    ]),
+  );
+  if (
+    manifest.schemaVersion !== 2 ||
+    !Array.isArray(manifest.layers) ||
+    manifest.layers.length !== 1
+  )
+    fail("only single-buildpack, single-layer packages are supported");
+  const config = json(
+    blob(manifest.config, [
+      "application/vnd.oci.image.config.v1+json",
+      "application/vnd.docker.container.image.v1+json",
+    ]),
+  );
+  if (config.os !== "linux" || config.architecture !== architecture)
+    fail(
+      `package target ${config.os}/${config.architecture} does not match linux/${architecture}`,
+    );
+  const labels = config.config?.Labels;
+  const metadata = json(
+    Buffer.from(labels?.["io.buildpacks.buildpackage.metadata"] ?? ""),
+  );
+  const { id, version } = metadata;
+  if (
+    typeof id !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9./-]*$/.test(id) ||
+    id.split("/").some((part) => !part || part === "." || part === "..") ||
+    typeof version !== "string" ||
+    !/^[a-zA-Z0-9][a-zA-Z0-9.+-]*$/.test(version)
+  )
+    fail("invalid buildpack ID/version");
+  const layers = json(
+    Buffer.from(labels?.["io.buildpacks.buildpack.layers"] ?? ""),
+  );
+  if (
+    Object.keys(layers).length !== 1 ||
+    Object.keys(layers[id] ?? {}).length !== 1 ||
+    !layers[id]?.[version]
+  )
+    fail("dependencies/composite packages are unsupported");
+  const layerMetadata = layers[id][version];
+  const layer = expand(
+    blob(manifest.layers[0], [
+      "application/vnd.oci.image.layer.v1.tar",
+      "application/vnd.oci.image.layer.v1.tar+gzip",
+      "application/vnd.docker.image.rootfs.diff.tar.gzip",
+    ]),
+  );
+  if (
+    config.rootfs?.type !== "layers" ||
+    config.rootfs.diff_ids?.length !== 1 ||
+    hash(layer) !== config.rootfs.diff_ids[0] ||
+    hash(layer) !== layerMetadata.layerDiffID
+  )
+    fail("layer diff digest mismatch");
+  const root = `cnb/buildpacks/${id.replaceAll("/", "_")}/${version}`;
+  const entries = parseBuildpackTar(layer, "layer");
+  if (
+    entries.some(
+      (entry) =>
+        entry.path !== root &&
+        !entry.path.startsWith(`${root}/`) &&
+        !(entry.directory && root.startsWith(`${entry.path}/`)),
+    )
+  )
+    fail("layer contains files outside the declared buildpack");
+  const descriptor = entries.find(
+    (entry) => entry.path === `${root}/buildpack.toml` && !entry.directory,
+  );
+  if (!descriptor || descriptor.data.length > 1024 * 1024)
+    fail("missing buildpack.toml");
+  let toml: any;
+  try {
+    toml = Bun.TOML.parse(descriptor!.data.toString());
+  } catch {
+    return fail("invalid buildpack.toml (requires Bun TOML support)");
+  }
+  if (
+    toml.buildpack?.id !== id ||
+    toml.buildpack?.version !== version ||
+    toml.api !== layerMetadata.api
+  )
+    fail("buildpack descriptor does not match config metadata");
+  if (toml.api !== "0.10")
+    fail("only Buildpack API 0.10 is currently supported");
+  if (toml.order || toml.buildpack?.extensions)
+    fail("composite/extension buildpacks are unsupported");
+  for (const stacks of [metadata.stacks, layerMetadata.stacks, toml.stacks])
+    if (
+      stacks !== undefined &&
+      (!Array.isArray(stacks) || !stacks.some((stack: any) => stack.id === "*"))
+    )
+      fail("stack-specific buildpacks are unsupported");
+  for (const targets of [
+    metadata.targets,
+    toml.targets,
+    layerMetadata.targets,
+  ]) {
+    if (
+      Array.isArray(targets) &&
+      targets.some((target: any) => target.distros?.length || target.variant)
+    )
+      fail("distro/variant-specific buildpacks are unsupported");
+    if (
+      targets !== undefined &&
+      (!Array.isArray(targets) ||
+        !targets.some(
+          (target: any) =>
+            target.os === "linux" &&
+            (!target.arch || target.arch === architecture),
+        ))
+    )
+      fail(`buildpack targets do not support linux/${architecture}`);
+  }
+  for (const bin of ["detect", "build"]) {
+    if (
+      !entries.some(
+        (entry) =>
+          entry.path === `${root}/bin/${bin}` &&
+          !entry.directory &&
+          entry.mode === 0o755,
+      )
+    )
+      fail(`missing executable bin/${bin}`);
+  }
+  return {
+    id,
+    version,
+    entries: entries
+      .filter(
+        (entry) => entry.path.startsWith(`${root}/`) || entry.path === root,
+      )
+      .map((entry) => ({
+        ...entry,
+        path: entry.path.slice("cnb/buildpacks/".length),
+      })),
+  };
+}
+
+export async function stageBuildpackPackage(
+  uri: string,
+  architecture: BuildArchitecture,
+  destination: string,
+  fetcher?: PackageFetcher,
+): Promise<void> {
+  const pkg = unpackBuildpackPackage(
+    await fetchBuildpackPackage(uri, fetcher),
+    architecture,
+  );
+  await rm(destination, { recursive: true, force: true });
+  try {
+    await mkdir(join(destination, "buildpacks"), {
+      recursive: true,
+      mode: 0o755,
+    });
+    for (const entry of pkg.entries) {
+      const path = join(destination, "buildpacks", entry.path);
+      if (entry.directory) await mkdir(path, { recursive: true, mode: 0o755 });
+      else {
+        await mkdir(dirname(path), { recursive: true, mode: 0o755 });
+        await writeFile(path, entry.data, { mode: entry.mode, flag: "wx" });
+      }
+    }
+    await writeFile(
+      join(destination, "order.toml"),
+      `[[order]]\n[[order.group]]\nid = ${JSON.stringify(pkg.id)}\nversion = ${JSON.stringify(pkg.version)}\n`,
+      { mode: 0o644, flag: "wx" },
+    );
+  } catch (error) {
+    await rm(destination, { recursive: true, force: true });
+    throw error;
+  }
+}
diff --git a/server/buildpacks-job.ts b/server/buildpacks-job.ts
new file mode 100644
index 0000000..3b6cb89
--- /dev/null
+++ b/server/buildpacks-job.ts
@@ -0,0 +1,312 @@
+import type { BuildJobOptions, KubernetesJob } from "./build-job";
+
+// The Heroku 26 builder is multi-architecture and ships lifecycle 0.21.22.
+export const DEFAULT_BUILDPACKS_IMAGE =
+  "docker.io/heroku/builder:26@sha256:d71287feea697567159584a0e8fa9c1af8d8419b07829bf40dd793cc26c7f7ad";
+
+export function validateBuildpacksImage(image: string): void {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._:/-]*@sha256:[a-f0-9]{64}$/.test(image))
+    throw new Error("Buildpacks builder image must be digest-pinned (sha256)");
+}
+
+function safePath(path: string, name: string): string {
+  const normalized = path === "." ? "" : path.replace(/^\.\//, "");
+  if (
+    !path ||
+    path.startsWith("/") ||
+    path.includes("\\") ||
+    path.includes("\0") ||
+    (normalized &&
+      normalized
+        .split("/")
+        .some((part) => !part || part === "." || part === ".."))
+  )
+    throw new Error(`${name} must be a safe workspace-relative path`);
+  return normalized;
+}
+
+function registry(image: string): string {
+  const first = image.split("/")[0]!;
+  return first.includes(".") || first.includes(":") || first === "localhost"
+    ? first
+    : "docker.io";
+}
+
+export function createBuildpacksJob(
+  options: BuildJobOptions & {
+    buildpacksImage?: string;
+    buildpackSubPath?: string;
+  },
+): KubernetesJob {
+  const builderImage = options.buildpacksImage ?? DEFAULT_BUILDPACKS_IMAGE;
+  validateBuildpacksImage(builderImage);
+  if (options.spec.builder !== "buildpacks")
+    throw new Error("Buildpacks Job requires the buildpacks builder");
+  if (
+    options.spec.dockerfile !== undefined ||
+    options.spec.target !== undefined ||
+    options.spec.buildArgs.length
+  )
+    throw new Error(
+      "Buildpacks does not support dockerfile, target, or buildArgs",
+    );
+  if (
+    !/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(options.name) ||
+    options.name.length > 63
+  )
+    throw new Error("Job name must be a valid DNS label");
+  const context = safePath(options.spec.context, "Build context");
+  const subPath = options.workspaceSubPath
+    ? safePath(options.workspaceSubPath, "Workspace subPath")
+    : undefined;
+  if (!!options.spec.buildpackUri !== !!options.buildpackSubPath)
+    throw new Error("Custom buildpack URI requires a staged package path");
+  const packagePath = options.buildpackSubPath
+    ? safePath(options.buildpackSubPath, "Buildpack subPath")
+    : undefined;
+  const packageMounts = packagePath
+    ? [
+        {
+          name: "workspace",
+          mountPath: "/package",
+          subPath: packagePath,
+          readOnly: true,
+        },
+      ]
+    : [];
+  const customMounts = packagePath
+    ? [
+        {
+          name: "custom-buildpacks",
+          mountPath: "/custom-buildpacks",
+          readOnly: true,
+        },
+        ...packageMounts,
+      ]
+    : [];
+  const images = [
+    options.pushImage ?? options.spec.image,
+    ...(options.pushImages ?? []),
+  ];
+  if (images.some((image) => !image || /[,"\r\n\s]/.test(image)))
+    throw new Error("Invalid Buildpacks output image name");
+  // The lifecycle's registry exporter rejects tags spanning registries.
+  if (new Set(images.map(registry)).size > 1)
+    throw new Error("Buildpacks output images must use the same registry");
+  if (!options.cacheImage || /[,"\r\n\s]/.test(options.cacheImage))
+    throw new Error("Invalid Buildpacks cache image name");
+  const insecureRegistries = new Set<string>();
+  if (options.pushRegistryInsecure)
+    images.forEach((image) => {
+      insecureRegistries.add(registry(image));
+    });
+  if (options.cacheRegistryInsecure)
+    insecureRegistries.add(registry(options.cacheImage));
+  const labels = {
+    "app.kubernetes.io/name": "kuber-buildpacks",
+    "app.kubernetes.io/managed-by": "kuber",
+    "kuber.astrxl.dev/build": options.name,
+    ...options.labels,
+  };
+  const tolerations = [...(options.tolerations ?? [])];
+  const amd64Toleration = {
+    key: "arch",
+    operator: "Equal",
+    value: "amd64",
+    effect: "NoExecute",
+  };
+  if (
+    options.spec.architecture === "amd64" &&
+    !tolerations.some(
+      (value) =>
+        Object.keys(amd64Toleration).length === Object.keys(value).length &&
+        Object.entries(amd64Toleration).every(
+          ([key, entry]) => value[key] === entry,
+        ),
+    )
+  )
+    tolerations.push(amd64Toleration);
+  const env = [
+    // lifecycle 0.21.22 requires this input; 0.15 enables --insecure-registry.
+    { name: "CNB_PLATFORM_API", value: "0.15" },
+    { name: "TMPDIR", value: "/tmp" },
+    ...(options.registrySecretName
+      ? [{ name: "DOCKER_CONFIG", value: "/docker-config" }]
+      : []),
+  ];
+  const writableMounts = [
+    { name: "app", mountPath: "/cnb-app" },
+    { name: "layers", mountPath: "/layers" },
+    { name: "cache", mountPath: "/cache" },
+    { name: "platform", mountPath: "/platform" },
+    { name: "tmp", mountPath: "/tmp" },
+  ];
+  const authMounts = options.registrySecretName
+    ? [{ name: "registry-auth", mountPath: "/docker-config", readOnly: true }]
+    : [];
+  return {
+    apiVersion: "batch/v1",
+    kind: "Job",
+    metadata: {
+      name: options.name,
+      namespace: options.namespace,
+      labels,
+      annotations: { "kuber.astrxl.dev/workspace": options.spec.workspace },
+    },
+    spec: {
+      backoffLimit: options.backoffLimit ?? 0,
+      ttlSecondsAfterFinished: options.ttlSecondsAfterFinished ?? 3600,
+      template: {
+        metadata: { labels },
+        spec: {
+          restartPolicy: "Never",
+          ...(options.serviceAccountName
+            ? { serviceAccountName: options.serviceAccountName }
+            : {}),
+          automountServiceAccountToken: false,
+          nodeSelector: {
+            ...options.nodeSelector,
+            "kubernetes.io/arch": options.spec.architecture,
+          },
+          ...(tolerations.length ? { tolerations } : {}),
+          securityContext: {
+            runAsNonRoot: true,
+            runAsUser: 1000,
+            runAsGroup: 1000,
+            fsGroup: 1000,
+            seccompProfile: { type: "RuntimeDefault" },
+          },
+          ...(options.registrySecretName
+            ? { imagePullSecrets: [{ name: options.registrySecretName }] }
+            : {}),
+          initContainers: [
+            ...(packagePath
+              ? [
+                  {
+                    name: "prepare-buildpacks",
+                    image: builderImage,
+                    imagePullPolicy: "IfNotPresent",
+                    command: ["/bin/sh", "-ec"],
+                    args: [
+                      'cp -R /cnb/buildpacks/. /custom-buildpacks/; for directory in /package/buildpacks/*; do rm -rf "/custom-buildpacks/${directory##*/}"; done; cp -R /package/buildpacks/. /custom-buildpacks/',
+                    ],
+                    securityContext: {
+                      allowPrivilegeEscalation: false,
+                      runAsNonRoot: true,
+                      runAsUser: 1000,
+                      runAsGroup: 1000,
+                    },
+                    volumeMounts: [
+                      ...packageMounts,
+                      {
+                        name: "custom-buildpacks",
+                        mountPath: "/custom-buildpacks",
+                      },
+                    ],
+                  },
+                ]
+              : []),
+            {
+              name: "copy-source",
+              image: builderImage,
+              imagePullPolicy: "IfNotPresent",
+              command: ["/bin/sh", "-ec"],
+              args: [
+                'cp -R "$1/." /cnb-app/ && chmod -R u+rwX /cnb-app',
+                "--",
+                context ? `/workspace/${context}` : "/workspace",
+              ],
+              securityContext: {
+                allowPrivilegeEscalation: false,
+                runAsNonRoot: true,
+                runAsUser: 1000,
+                runAsGroup: 1000,
+              },
+              volumeMounts: [
+                {
+                  name: "workspace",
+                  mountPath: "/workspace",
+                  readOnly: true,
+                  ...(subPath ? { subPath } : {}),
+                },
+                { name: "app", mountPath: "/cnb-app" },
+                { name: "tmp", mountPath: "/tmp" },
+              ],
+            },
+          ],
+          containers: [
+            {
+              // The existing Kubernetes observer selects this name for logs/status.
+              name: "buildkit",
+              image: builderImage,
+              imagePullPolicy: "IfNotPresent",
+              command: ["/cnb/lifecycle/creator"],
+              args: [
+                "--app",
+                "/cnb-app",
+                "--layers",
+                "/layers",
+                "--platform",
+                "/platform",
+                ...(packagePath
+                  ? [
+                      "--buildpacks",
+                      "/custom-buildpacks",
+                      "--order",
+                      "/package/order.toml",
+                    ]
+                  : []),
+                "--cache-image",
+                options.cacheImage,
+                "--uid",
+                "1000",
+                "--gid",
+                "1000",
+                ...[...insecureRegistries].flatMap((host) => [
+                  "--insecure-registry",
+                  host,
+                ]),
+                ...images.slice(1).flatMap((image) => ["--tag", image]),
+                images[0],
+              ],
+              env,
+              securityContext: {
+                allowPrivilegeEscalation: false,
+                runAsNonRoot: true,
+                runAsUser: 1000,
+                runAsGroup: 1000,
+              },
+              volumeMounts: [...writableMounts, ...authMounts, ...customMounts],
+            },
+          ],
+          volumes: [
+            {
+              name: "workspace",
+              persistentVolumeClaim: { claimName: options.workspaceClaimName },
+            },
+            ...["app", "layers", "cache", "platform", "tmp"].map((name) => ({
+              name,
+              emptyDir: {},
+            })),
+            ...(packagePath
+              ? [{ name: "custom-buildpacks", emptyDir: {} }]
+              : []),
+            ...(options.registrySecretName
+              ? [
+                  {
+                    name: "registry-auth",
+                    secret: {
+                      secretName: options.registrySecretName,
+                      items: [
+                        { key: ".dockerconfigjson", path: "config.json" },
+                      ],
+                    },
+                  },
+                ]
+              : []),
+          ],
+        },
+      },
+    },
+  };
+}
diff --git a/server/index.ts b/server/index.ts
index 45ac69a..ba9242c 100644
--- a/server/index.ts
+++ b/server/index.ts
@@ -229,7 +229,7 @@ const builds = new BuildController({
   workspaceClaimName:
     process.env.KUBER_BUILD_DATA_CLAIM?.trim() || "kuber-build-data",
   cacheImage: (request) =>
-    `${internalRegistryHost ?? registry}/kuber/cache-${request.project}-${request.service}`,
+    `${internalRegistryHost ?? registry}/kuber/cache-${request.project}-${request.service}${request.spec.builder === "buildpacks" ? `-cnb-${request.spec.architecture}` : ""}`,
   imageName: (request) =>
     buildImageName(registry, request.project, request.service),
   pushImage: internalRegistryHost
@@ -240,6 +240,7 @@ const builds = new BuildController({
     ? internalRegistryInsecure
     : undefined,
   buildkitImage: process.env.KUBER_BUILDKIT_IMAGE?.trim() || undefined,
+  buildpacksImage: process.env.KUBER_BUILDPACKS_IMAGE?.trim() || undefined,
   registrySecretName: process.env.KUBER_REGISTRY_SECRET?.trim() || undefined,
   maxLogBytes: Number(process.env.KUBER_BUILD_LOG_BYTES ?? 512 * 1024),
   resolveDigest: async (image) =>
diff --git a/server/materialize.ts b/server/materialize.ts
index f5e3240..873d894 100644
--- a/server/materialize.ts
+++ b/server/materialize.ts
@@ -9,14 +9,7 @@ import {
   rm,
   symlink,
 } from "node:fs/promises";
-import {
-  basename,
-  dirname,
-  isAbsolute,
-  join,
-  relative,
-  resolve,
-} from "node:path";
+import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import {
   BUILD_PROTOCOL_VERSION,
   assertSha256Digest,
@@ -129,16 +122,50 @@ export function parseWorkspaceManifest(data: Uint8Array): WorkspaceManifest {
   return manifest as WorkspaceManifest;
 }
 
-function safeSymlinkTarget(filePath: string, target: string): boolean {
-  if (
-    !target ||
-    isAbsolute(target) ||
-    target.includes("\\") ||
-    target.includes("\0")
-  )
-    return false;
-  const resolved = resolve("/workspace", dirname(filePath), target);
-  return resolved === "/workspace" || resolved.startsWith("/workspace/");
+function validateSymlinkTargets(targets: Map<string, string>): void {
+  for (const [path, target] of targets) {
+    if (
+      !target ||
+      isAbsolute(target) ||
+      target.includes("\\") ||
+      target.includes("\0")
+    ) {
+      throw new Error(`Unsafe symlink target for ${path}`);
+    }
+
+    // Resolve components in filesystem order: a symlink is expanded before
+    // processing the following `..`, unlike node:path.resolve's lexical result.
+    const pending: (string | { end: string })[] = [
+      ...dirname(path).split("/"),
+      ...target.split("/"),
+    ];
+    const resolved: string[] = [];
+    const visited = new Set<string>();
+    while (pending.length > 0) {
+      const component = pending.shift()!;
+      if (typeof component !== "string") {
+        visited.delete(component.end);
+        continue;
+      }
+      if (!component || component === ".") continue;
+      if (component === "..") {
+        if (resolved.length === 0)
+          throw new Error(`Unsafe symlink target for ${path}`);
+        resolved.pop();
+        continue;
+      }
+      const candidate = [...resolved, component].join("/");
+      const link = targets.get(candidate);
+      if (link === undefined) {
+        resolved.push(component);
+        continue;
+      }
+      if (visited.has(candidate))
+        throw new Error(`Unsafe symlink cycle for ${path}`);
+      visited.add(candidate);
+      pending.unshift(...link.split("/"), { end: candidate });
+    }
+  }
 }
 
 export async function materializeWorkspace(
@@ -171,6 +198,21 @@ export async function materializeWorkspace(
   const manifestData = await read(manifestDigest);
   if (timing) timing.manifestBytes = manifestData.byteLength;
   const manifest = parseWorkspaceManifest(manifestData);
+  const symlinkData = new Map<string, Uint8Array>();
+  const symlinkTargets = new Map<string, string>();
+  await mapConcurrent(
+    manifest.files.filter((file) => file.type === "symlink"),
+    async (file) => {
+      const data = await read(file.digest);
+      if (data.byteLength !== file.size) {
+        throw new Error(`Workspace blob size mismatch for ${file.path}`);
+      }
+      const link = new TextDecoder("utf-8", { fatal: true }).decode(data);
+      symlinkData.set(file.path, data);
+      symlinkTargets.set(file.path, link);
+    },
+  );
+  validateSymlinkTargets(symlinkTargets);
   if (timing) {
     timing.fileCount = manifest.files.length;
     timing.fileBytes = manifest.files.reduce(
@@ -199,15 +241,15 @@ export async function materializeWorkspace(
       await write(() =>
         mkdir(dirname(target), { recursive: true, mode: 0o755 }),
       );
-      const data = await read(file.digest);
+      const data =
+        file.type === "symlink"
+          ? symlinkData.get(file.path)!
+          : await read(file.digest);
       if (data.byteLength !== file.size) {
         throw new Error(`Workspace blob size mismatch for ${file.path}`);
       }
       if (file.type === "symlink") {
-        const link = new TextDecoder("utf-8", { fatal: true }).decode(data);
-        if (!safeSymlinkTarget(file.path, link))
-          throw new Error(`Unsafe symlink target for ${file.path}`);
-        await write(() => symlink(link, target));
+        await write(() => symlink(symlinkTargets.get(file.path)!, target));
       } else {
         const handle = await write(() =>
           open(
diff --git a/server/registry.ts b/server/registry.ts
index 9b5a021..10ac2e9 100644
--- a/server/registry.ts
+++ b/server/registry.ts
@@ -10,6 +10,13 @@ const ACCEPT = [
   "application/vnd.docker.distribution.manifest.list.v2+json",
   "application/vnd.docker.distribution.manifest.v2+json",
 ].join(", ");
+const MAX_MANIFEST_BYTES = 4 * 1024 * 1024;
+const MANIFEST_MEDIA_TYPES = new Set([
+  "application/vnd.oci.image.index.v1+json",
+  "application/vnd.oci.image.manifest.v1+json",
+  "application/vnd.docker.distribution.manifest.list.v2+json",
+  "application/vnd.docker.distribution.manifest.v2+json",
+]);
 
 export type RegistryCredentials = { username: string; password: string };
 export type RegistryFetch = (
@@ -103,10 +110,67 @@ function bearerParameters(
 }
 
 async function responseError(response: Response): Promise<Error> {
-  const detail = (await response.text()).slice(0, 512).trim();
-  return new Error(
-    `Registry request failed (${response.status})${detail ? `: ${detail}` : ""}`,
-  );
+  await response.body?.cancel().catch(() => {});
+  return new Error(`Registry request failed (${response.status})`);
+}
+
+async function readManifestBody(response: Response): Promise<Uint8Array> {
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error("Registry returned an invalid manifest");
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      length += value.byteLength;
+      if (length > MAX_MANIFEST_BYTES) {
+        await reader.cancel();
+        throw new Error("Registry manifest exceeds the size limit");
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+  const body = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(body),
+    );
+  } catch {
+    throw new Error("Registry returned an invalid manifest");
+  }
+  if (
+    !manifest ||
+    typeof manifest !== "object" ||
+    Array.isArray(manifest) ||
+    (manifest as { schemaVersion?: unknown }).schemaVersion !== 2
+  )
+    throw new Error("Registry returned an invalid manifest");
+  const record = manifest as Record<string, unknown>;
+  const mediaType = record.mediaType;
+  if (typeof mediaType !== "string" || !MANIFEST_MEDIA_TYPES.has(mediaType))
+    throw new Error("Registry returned an invalid manifest");
+  const isIndex =
+    mediaType.endsWith("image.index.v1+json") ||
+    mediaType.endsWith("manifest.list.v2+json");
+  if (
+    isIndex
+      ? !Array.isArray(record.manifests)
+      : !record.config ||
+        typeof record.config !== "object" ||
+        Array.isArray(record.config) ||
+        !Array.isArray(record.layers)
+  )
+    throw new Error("Registry returned an invalid manifest");
+  return body;
 }
 
 export async function resolveRegistryDigest(
@@ -191,17 +255,19 @@ export async function resolveRegistryDigest(
   }
   if (!response.ok) throw await responseError(response);
 
-  const body = new Uint8Array(await response.arrayBuffer());
+  const body = await readManifestBody(response);
   const advertised = response.headers
     .get("docker-content-digest")
     ?.trim()
     ?.toLowerCase();
-  let digest: Sha256Digest;
+  const digest =
+    `sha256:${createHash("sha256").update(body).digest("hex")}` as Sha256Digest;
   if (advertised !== undefined) {
     assertSha256Digest(advertised);
-    digest = advertised;
-  } else {
-    digest = `sha256:${createHash("sha256").update(body).digest("hex")}`;
+    if (advertised !== digest)
+      throw new Error(
+        "Registry manifest digest does not match Docker-Content-Digest",
+      );
   }
   if (cacheTtlMs && cacheMaxEntries) {
     digestCache.delete(cacheKey);
diff --git a/shared/build-protocol.ts b/shared/build-protocol.ts
index b7e8fa7..178dc8b 100644
--- a/shared/build-protocol.ts
+++ b/shared/build-protocol.ts
@@ -17,6 +17,10 @@ export type WorkspaceManifest = {
 };
 
 export type BuildSpec = {
+  /** Absent means the legacy BuildKit Dockerfile builder. */
+  builder?: "buildkit" | "buildpacks";
+  /** GitHub release CNB package, optionally pinned with #sha256=<hex>. */
+  buildpackUri?: string;
   architecture: BuildArchitecture;
   image: string;
   context: string;
@@ -65,6 +69,32 @@ export function isSha256Digest(value: unknown): value is Sha256Digest {
   return typeof value === "string" && /^sha256:[a-f0-9]{64}$/.test(value);
 }
 
+export function validateBuildpackUri(value: unknown): asserts value is string {
+  if (typeof value !== "string" || value.length > 4096 || /[\s\\]/.test(value))
+    throw new Error("Invalid buildpack URI");
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error("Invalid buildpack URI");
+  }
+  if (
+    url.protocol !== "https:" ||
+    url.hostname !== "github.com" ||
+    url.port ||
+    url.username ||
+    url.password ||
+    url.search ||
+    !/^\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+\/releases\/download\/[^/]+\/[^/]+\.cnb$/.test(
+      url.pathname,
+    ) ||
+    (url.hash && !/^#sha256=[a-f0-9]{64}$/.test(url.hash))
+  )
+    throw new Error(
+      "Buildpack URI must be an HTTPS GitHub release .cnb URL (optional #sha256=<hex>)",
+    );
+}
+
 export function assertSha256Digest(
   value: unknown,
 ): asserts value is Sha256Digest {
diff --git a/tests/command/add.test.ts b/tests/command/add.test.ts
new file mode 100644
index 0000000..df83aea
--- /dev/null
+++ b/tests/command/add.test.ts
@@ -0,0 +1,158 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { YAML } from "bun";
+import {
+  addAppToCompose,
+  createCompose,
+  type AppOptions,
+} from "../../lib/scaffold";
+import { resolveAppInput } from "../../command/add";
+import { readCompose } from "../../lib/yaml";
+
+const roots: string[] = [];
+afterEach(async () => {
+  for (const path of roots.splice(0))
+    await rm(path, { recursive: true, force: true });
+});
+async function root() {
+  const path = await mkdtemp(join(tmpdir(), "kuber-add-test-"));
+  roots.push(path);
+  return path;
+}
+
+test("add preserves compose metadata, existing services and comments while adding claims/resources", async () => {
+  const cwd = await root();
+  const original =
+    "name: shop\nx-owner: team\nservices:\n  api:\n    image: example/api:1 # keep this comment\nx-hook: untouched\n";
+  await writeFile(join(cwd, "compose.yml"), original);
+  await addAppToCompose(cwd, {
+    name: "worker",
+    path: ".",
+    source: { kind: "image", image: "example/worker:2" },
+    postgres: "user/db",
+    s3: "key/bucket",
+    cpu: "0.5",
+    memory: "512m",
+    replicas: 2,
+  });
+  const updated = await readFile(join(cwd, "compose.yml"), "utf8");
+  expect(updated).toContain("image: example/api:1 # keep this comment");
+  expect(updated).toContain("x-hook: untouched");
+  const compose = await readCompose(join(cwd, "compose.yml"));
+  expect(compose.services?.worker).toMatchObject({
+    image: "example/worker:2",
+    volumes: ["postgresql:user/db", "s3:key/bucket"],
+    deploy: {
+      replicas: 2,
+      resources: { limits: { cpus: "0.5", memory: "512m" } },
+    },
+  });
+  expect(compose.services?.api?.image).toBe("example/api:1");
+  await expect(
+    addAppToCompose(cwd, {
+      name: "api",
+      path: ".",
+      source: { kind: "image", image: "x" },
+    }),
+  ).rejects.toThrow("already exists");
+});
+
+test("add inserts into an inline empty services mapping and preserves surrounding content", async () => {
+  const cwd = await root();
+  const original =
+    "# before marker\nname: demo\nservices: {}\n# after marker\nx-hook: untouched\n";
+  await writeFile(join(cwd, "compose.yml"), original);
+
+  await addAppToCompose(cwd, {
+    name: "web",
+    path: ".",
+    source: { kind: "image", image: "example/web:1" },
+  });
+
+  const updated = await readFile(join(cwd, "compose.yml"), "utf8");
+  expect(updated).toContain("# before marker\nname: demo\nservices:\n");
+  expect(updated).toContain("# after marker\nx-hook: untouched\n");
+  expect(
+    (await readCompose(join(cwd, "compose.yml"))).services?.web?.image,
+  ).toBe("example/web:1");
+});
+
+test("unsupported inline services mappings fail without changing the compose file", async () => {
+  const cwd = await root();
+  const original =
+    "# before marker\nname: demo\nservices: {existing: {image: busybox}}\n# after marker\n";
+  await writeFile(join(cwd, "compose.yml"), original);
+
+  await expect(
+    addAppToCompose(cwd, {
+      name: "web",
+      path: ".",
+      source: { kind: "image", image: "example/web:1" },
+    }),
+  ).rejects.toThrow("Cannot safely insert a service");
+
+  expect(await readFile(join(cwd, "compose.yml"), "utf8")).toBe(original);
+});
+
+test("template creates paired files exclusively; collision rolls back and preserves compose", async () => {
+  const cwd = await root();
+  await mkdir(join(cwd, "app"));
+  await createCompose(cwd, "sample", {
+    name: "starter",
+    path: ".",
+    source: { kind: "image", image: "nginx:stable" },
+  });
+  const original = await readFile(join(cwd, "compose.yml"), "utf8");
+  const app: AppOptions = {
+    name: "app",
+    path: "app",
+    source: { kind: "template", template: "bun-service" },
+  };
+  await writeFile(join(cwd, "app", ".dockerignore"), "custom\n");
+  await expect(addAppToCompose(cwd, app)).rejects.toThrow();
+  expect(await readFile(join(cwd, "compose.yml"), "utf8")).toBe(original);
+  expect(await Bun.file(join(cwd, "app", "Dockerfile")).exists()).toBe(false);
+  expect(await readFile(join(cwd, "app", ".dockerignore"), "utf8")).toBe(
+    "custom\n",
+  );
+  await rm(join(cwd, "app", ".dockerignore"));
+  await addAppToCompose(cwd, app);
+  expect(await Bun.file(join(cwd, "app", "Dockerfile")).exists()).toBe(true);
+  expect(await Bun.file(join(cwd, "app", ".dockerignore")).exists()).toBe(true);
+});
+
+test("auto selects subproject and emits Buildpacks mode with path", async () => {
+  const cwd = await root();
+  await mkdir(join(cwd, "web"));
+  await writeFile(join(cwd, "web", "package.json"), "{}");
+  const app = await resolveAppInput(cwd, { nonInteractive: true });
+  expect(app).toMatchObject({ path: "web", source: { kind: "auto" } });
+  await createCompose(cwd, "sample", app);
+  const compose = YAML.parse(
+    await readFile(join(cwd, "compose.yml"), "utf8"),
+  ) as { services: Record<string, Record<string, unknown>> };
+  expect(compose.services[app.name]!.build).toBe("auto");
+  expect(compose.services[app.name]!["x-kuber-build-context"]).toBe("web");
+  expect(
+    (await readCompose(join(cwd, "compose.yml"))).services?.[app.name]?.build,
+  ).toBe("auto");
+  expect(await Bun.file(join(cwd, "web", "Dockerfile")).exists()).toBe(false);
+});
+
+test("rejects path traversal and symlink outside the project", async () => {
+  const cwd = await root();
+  await createCompose(cwd, "sample", {
+    name: "main",
+    path: ".",
+    source: { kind: "image", image: "nginx" },
+  });
+  await expect(
+    addAppToCompose(cwd, {
+      name: "bad",
+      path: "../elsewhere",
+      source: { kind: "auto" },
+    }),
+  ).rejects.toThrow();
+});
diff --git a/tests/command/init.test.ts b/tests/command/init.test.ts
new file mode 100644
index 0000000..7612213
--- /dev/null
+++ b/tests/command/init.test.ts
@@ -0,0 +1,430 @@
+import { afterEach, describe, expect, test, spyOn } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { YAML } from "bun";
+import { initializeProject } from "../../command/init";
+import { managedHeader } from "../../lib/scaffold";
+import { readTrust, resolveTrustIdentity, updateTrust } from "../../lib/trust";
+import { KuberApiError } from "../../lib/api";
+
+const roots: string[] = [];
+const originalConfig = process.env.XDG_CONFIG_HOME;
+afterEach(async () => {
+  for (const root of roots.splice(0))
+    await rm(root, { recursive: true, force: true });
+  if (originalConfig === undefined) delete process.env.XDG_CONFIG_HOME;
+  else process.env.XDG_CONFIG_HOME = originalConfig;
+});
+async function root() {
+  const path = await mkdtemp(join(tmpdir(), "kuber-init-test-"));
+  roots.push(path);
+  process.env.XDG_CONFIG_HOME = join(path, "config");
+  return path;
+}
+
+describe("kuber init", () => {
+  test("uses an existing configured project for Compose and trust", async () => {
+    const cwd = await root();
+    await writeFile(
+      join(cwd, ".kuberrc.ts"),
+      'export default { project: "configured" };\n',
+    );
+    const paths: string[] = [];
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      await initializeProject(
+        cwd,
+        { nonInteractive: true },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async (path, init) => {
+            paths.push(path);
+            return (
+              init?.method === "POST" ? undefined : { fingerprints: [] }
+            ) as never;
+          },
+        },
+      );
+      expect(
+        YAML.parse(await readFile(join(cwd, "compose.yml"), "utf8")),
+      ).toMatchObject({ name: "configured" });
+      expect(paths).toEqual([
+        "/workspaces/configured/trust",
+        "/workspaces/configured/trust",
+      ]);
+    } finally {
+      log.mockRestore();
+    }
+  });
+  test("empty directory creates documented image-only example and trusts selected project", async () => {
+    const cwd = await root();
+    const calls: string[] = [];
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      await initializeProject(
+        cwd,
+        { nonInteractive: true, project: "demo" },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async (path, init) => {
+            calls.push(path);
+            return (
+              init?.method === "POST" ? undefined : { fingerprints: [] }
+            ) as never;
+          },
+        },
+      );
+      const content = await readFile(join(cwd, "compose.yml"), "utf8");
+      expect(content.split("\n")[0]).toBe(managedHeader);
+      const compose = YAML.parse(content);
+      expect(compose).toMatchObject({
+        managedBy: "kuber",
+        name: "demo",
+        services: {
+          [join(cwd).split("/").at(-1)!.toLowerCase()]: {
+            image: "nginx:stable",
+          },
+        },
+      });
+      expect(calls).toEqual([
+        "/workspaces/demo/trust",
+        "/workspaces/demo/trust",
+      ]);
+      expect(await readTrust()).toHaveLength(1);
+      expect(await Bun.file(join(cwd, "Dockerfile")).exists()).toBe(false);
+    } finally {
+      log.mockRestore();
+    }
+  });
+
+  test("multiple manifests require explicit selection in noninteractive mode", async () => {
+    const cwd = await root();
+    for (const name of ["one", "two"]) {
+      await mkdir(join(cwd, name));
+      await writeFile(join(cwd, name, "package.json"), "{}");
+    }
+    await expect(
+      initializeProject(
+        cwd,
+        { nonInteractive: true },
+        { session: async () => undefined },
+      ),
+    ).rejects.toThrow("specify --path");
+    expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(false);
+  });
+
+  test("revoked session retries once without duplicating trust; failed grant never writes local trust", async () => {
+    const cwd = await root();
+    let attempts = 0;
+    let logins = 0;
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      await initializeProject(
+        cwd,
+        { nonInteractive: true, project: "demo" },
+        {
+          session: async () => ({
+            token: "old",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          login: async () => {
+            logins++;
+            return {
+              token: "new",
+              expiresAt: "2099-01-01",
+              user: { username: "a", roles: [] },
+            };
+          },
+          request: async (_path, init) => {
+            if (++attempts === 1) throw new KuberApiError("revoked", 401);
+            return (
+              init?.method === "POST" ? undefined : { fingerprints: [] }
+            ) as never;
+          },
+        },
+      );
+      expect([attempts, logins]).toEqual([3, 1]);
+      expect(await readTrust()).toHaveLength(1);
+    } finally {
+      log.mockRestore();
+    }
+    const other = await root();
+    await expect(
+      initializeProject(
+        other,
+        { nonInteractive: true, project: "bad" },
+        {
+          session: async () => undefined,
+          login: async () => ({
+            token: "new",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async () => {
+            throw new KuberApiError("failed", 503);
+          },
+        },
+      ),
+    ).rejects.toThrow("failed");
+    expect(await readTrust()).toEqual([]);
+    expect(await Bun.file(join(other, "compose.yml")).exists()).toBe(false);
+  });
+
+  test("successful grant with failed local persistence keeps registration and generated files", async () => {
+    const cwd = await root();
+    const identity = await resolveTrustIdentity("demo", cwd);
+    const trusted = new Set<string>();
+    const calls: string[] = [];
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const failure = await initializeProject(
+        cwd,
+        {
+          nonInteractive: true,
+          project: "demo",
+          source: "template",
+          template: "static-nginx",
+        },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async (path, init) => {
+            calls.push(init?.method ?? "GET");
+            if (init?.method === "POST")
+              trusted.add((init.json as { fingerprint: string }).fingerprint);
+            expect(path).toBe("/workspaces/demo/trust");
+            return (
+              init?.method ? undefined : { fingerprints: [...trusted] }
+            ) as never;
+          },
+          persistTrust: async () => {
+            throw new Error("disk full: secret-token");
+          },
+        },
+      ).catch((error: unknown) => error);
+      expect(failure).toBeInstanceOf(Error);
+      expect((failure as Error).message).toMatch(
+        /Server registration exists.*kuber trust/,
+      );
+      expect((failure as Error).message).not.toContain("secret-token");
+      expect((failure as Error).cause).toBeUndefined();
+      expect(calls).toEqual(["GET", "POST"]);
+      expect(trusted.has(identity.fingerprint)).toBe(true);
+      expect(await readTrust()).toEqual([]);
+      expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(true);
+      expect(await Bun.file(join(cwd, "Dockerfile")).exists()).toBe(true);
+      expect(await Bun.file(join(cwd, ".dockerignore")).exists()).toBe(true);
+      expect(log).not.toHaveBeenCalled();
+    } finally {
+      log.mockRestore();
+    }
+  });
+
+  test("pre-existing server grant and local trust survive local persistence failure", async () => {
+    const cwd = await root();
+    const identity = await resolveTrustIdentity("demo", cwd);
+    const existing = await resolveTrustIdentity("other", cwd);
+    await updateTrust(() => [existing]);
+    const calls: string[] = [];
+    await expect(
+      initializeProject(
+        cwd,
+        { nonInteractive: true, project: "demo" },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async (_path, init) => {
+            calls.push(init?.method ?? "GET");
+            return { fingerprints: [identity.fingerprint] } as never;
+          },
+          persistTrust: async () => {
+            throw new Error("disk full");
+          },
+        },
+      ),
+    ).rejects.toThrow(/Server registration exists.*kuber trust/);
+    expect(calls).toEqual(["GET"]);
+    expect(await readTrust()).toEqual([existing]);
+    expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(true);
+  });
+
+  test("concurrent grant between GET and POST is never revoked on local failure", async () => {
+    const cwd = await root();
+    const identity = await resolveTrustIdentity("demo", cwd);
+    const calls: string[] = [];
+    const trusted = new Set<string>();
+    await expect(
+      initializeProject(
+        cwd,
+        { nonInteractive: true, project: "demo" },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async (_path, init) => {
+            calls.push(init?.method ?? "GET");
+            if (!init?.method) {
+              trusted.add(identity.fingerprint); // Another client grants after our GET snapshot.
+              return { fingerprints: [] } as never;
+            }
+            if (init.method === "POST") {
+              expect(trusted.has(identity.fingerprint)).toBe(true);
+              return undefined as never; // Idempotent POST did not create this grant.
+            }
+            throw new Error(`Unexpected ${init.method}`);
+          },
+          persistTrust: async () => {
+            throw new Error("disk full");
+          },
+        },
+      ),
+    ).rejects.toThrow(/Server registration exists.*kuber trust/);
+    expect(calls).toEqual(["GET", "POST"]);
+    expect(trusted.has(identity.fingerprint)).toBe(true);
+    expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(true);
+  });
+
+  test("partial local write still reports failure without revoking remote trust", async () => {
+    const cwd = await root();
+    const identity = await resolveTrustIdentity("demo", cwd);
+    const calls: string[] = [];
+    const log = spyOn(console, "log").mockImplementation(() => {});
+    try {
+      await expect(
+        initializeProject(
+          cwd,
+          { nonInteractive: true, project: "demo" },
+          {
+            session: async () => ({
+              token: "test",
+              expiresAt: "2099-01-01",
+              user: { username: "a", roles: [] },
+            }),
+            request: async (_path, init) => {
+              calls.push(init?.method ?? "GET");
+              return (init?.method ? undefined : { fingerprints: [] }) as never;
+            },
+            persistTrust: async (update) => {
+              await updateTrust(update); // Simulates rename succeeding before chmod fails.
+              throw new Error("chmod failed");
+            },
+          },
+        ),
+      ).rejects.toThrow(/Server registration exists.*kuber trust/);
+      expect(calls).toEqual(["GET", "POST"]);
+      expect(await readTrust()).toEqual([identity]);
+      expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(true);
+      expect(log).not.toHaveBeenCalled();
+    } finally {
+      log.mockRestore();
+    }
+  });
+
+  test("failed POST rolls back generated files without altering existing trust", async () => {
+    const cwd = await root();
+    const existing = await resolveTrustIdentity("other", cwd);
+    await updateTrust(() => [existing]);
+    const calls: string[] = [];
+    await expect(
+      initializeProject(
+        cwd,
+        {
+          nonInteractive: true,
+          project: "demo",
+          source: "template",
+          template: "static-nginx",
+        },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async (_path, init) => {
+            calls.push(init?.method ?? "GET");
+            if (init?.method === "POST")
+              throw new KuberApiError("grant failed", 503);
+            return { fingerprints: [] } as never;
+          },
+        },
+      ),
+    ).rejects.toThrow("grant failed");
+    expect(calls).toEqual(["GET", "POST"]);
+    expect(await readTrust()).toEqual([existing]);
+    expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(false);
+    expect(await Bun.file(join(cwd, "Dockerfile")).exists()).toBe(false);
+    expect(await Bun.file(join(cwd, ".dockerignore")).exists()).toBe(false);
+  });
+
+  test("existing Compose file is not overwritten and no grant is attempted", async () => {
+    const cwd = await root();
+    const composePath = join(cwd, "compose.yml");
+    const existing = "name: existing\nservices: {}\n";
+    await writeFile(composePath, existing);
+    let requested = false;
+    await expect(
+      initializeProject(
+        cwd,
+        { nonInteractive: true, project: "demo" },
+        {
+          request: async () => {
+            requested = true;
+            return undefined as never;
+          },
+        },
+      ),
+    ).rejects.toThrow("A Compose file already exists");
+    expect(await readFile(composePath, "utf8")).toBe(existing);
+    expect(requested).toBe(false);
+  });
+
+  test("existing Dockerfile is not overwritten by template init", async () => {
+    const cwd = await root();
+    const dockerfile = join(cwd, "Dockerfile");
+    await writeFile(dockerfile, "FROM private-image\n");
+    let requested = false;
+    await expect(
+      initializeProject(
+        cwd,
+        {
+          nonInteractive: true,
+          project: "demo",
+          source: "template",
+          template: "static-nginx",
+        },
+        {
+          session: async () => ({
+            token: "test",
+            expiresAt: "2099-01-01",
+            user: { username: "a", roles: [] },
+          }),
+          request: async () => {
+            requested = true;
+            return undefined as never;
+          },
+        },
+      ),
+    ).rejects.toThrow();
+    expect(await readFile(dockerfile, "utf8")).toBe("FROM private-image\n");
+    expect(await Bun.file(join(cwd, "compose.yml")).exists()).toBe(false);
+    expect(requested).toBe(false);
+  });
+});
diff --git a/tests/command/startup.test.ts b/tests/command/startup.test.ts
index 0aac6ca..776fe29 100644
--- a/tests/command/startup.test.ts
+++ b/tests/command/startup.test.ts
@@ -1,81 +1,24 @@
-import { describe, expect, test } from "bun:test";
-import { join } from "node:path";
+import { expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 
-const entry = join(import.meta.dir, "../../index.ts");
-
-function cli(...args: string[]) {
-  const result = Bun.spawnSync([process.execPath, entry, ...args], {
-    cwd: import.meta.dir,
-    env: { ...process.env, TERM: "dumb", NO_COLOR: "1" },
-  });
-  return {
-    status: result.exitCode,
-    output: new TextDecoder().decode(result.stdout),
-    error: new TextDecoder().decode(result.stderr),
-  };
-}
-
-describe("CLI startup", () => {
-  test("registers all original names as lazy commands", () => {
-    const probe = Bun.spawnSync([
-      process.execPath,
-      "-e",
-      `import { main } from ${JSON.stringify(join(import.meta.dir, "../../command/main.ts"))}; console.log(JSON.stringify(Object.entries(main.subCommands).map(([name, command]) => [name, typeof command])));`,
+test("init help starts in an empty directory without requiring Compose", async () => {
+  const cwd = await mkdtemp(join(tmpdir(), "kuber-startup-test-"));
+  try {
+    const process = Bun.spawn(
+      ["bun", resolve(import.meta.dir, "../../index.ts"), "init", "--help"],
+      { cwd, stdout: "pipe", stderr: "pipe" },
+    );
+    const [status, out, err] = await Promise.all([
+      process.exited,
+      new Response(process.stdout).text(),
+      new Response(process.stderr).text(),
     ]);
-    expect(probe.exitCode).toBe(0);
-    const commands = JSON.parse(new TextDecoder().decode(probe.stdout)) as [
-      string,
-      string,
-    ][];
-    expect(commands.map(([name]) => name)).toEqual([
-      "audit",
-      "ci",
-      "db",
-      "down",
-      "export",
-      "exec",
-      "logs",
-      "maintenance",
-      "login",
-      "logout",
-      "operations",
-      "ps",
-      "restart",
-      "rollback",
-      "s3",
-      "start",
-      "stop",
-      "up",
-      "users",
-      "trust",
-      "whoami",
-    ]);
-    expect(commands.every(([, type]) => type === "function")).toBe(true);
-  });
-
-  test("root help retains descriptions, alias, and completion command", () => {
-    const result = cli("--help");
-    expect(result.status).toBe(0);
-    expect(result.output).toContain("rollback, fuck");
-    expect(result.output).toContain("complete");
-    expect(result.output).toContain("Create and start deployments");
-
-    const missingCommand = cli();
-    expect(missingCommand.status).toBe(1);
-    expect(missingCommand.output).toContain("complete");
-  });
-
-  test("alias and named subcommand have the same help", () => {
-    const alias = cli("fuck", "--help");
-    const named = cli("rollback", "--help");
-    expect(alias.status).toBe(0);
-    expect(alias.output).toBe(named.output);
-    expect(alias.output).toContain("DEPLOYMENT");
-  });
-
-  test("completion still resolves flags from nested commands", () => {
-    const result = cli("complete", "--", "logs", "--");
-    expect(result.status).toBe(0);
-    expect(result.output).toContain("--follow");
-  });
+    expect(status).toBe(0);
+    expect(out + err).toContain("init");
+    expect(out + err).not.toContain("Compose file cannot be found");
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
 });
diff --git a/tests/command/up-api.test.ts b/tests/command/up-api.test.ts
index ff9e09e..bbeb8d8 100644
--- a/tests/command/up-api.test.ts
+++ b/tests/command/up-api.test.ts
@@ -46,21 +46,38 @@ describe("up API pipeline", () => {
     const tty = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
     const frames: string[] = [];
     const create = DefaultRenderer.prototype.create;
-    const renderSpy = spyOn(DefaultRenderer.prototype, "create").mockImplementation(function (this: DefaultRenderer, options) {
+    const renderSpy = spyOn(
+      DefaultRenderer.prototype,
+      "create",
+    ).mockImplementation(function (this: DefaultRenderer, options) {
       const frame = create.call(this, options);
       frames.push(frame);
       return frame;
     });
-    const writes = spyOn(process.stdout, "write").mockImplementation((() => true) as typeof process.stdout.write);
+    const writes = spyOn(process.stdout, "write").mockImplementation(
+      (() => true) as typeof process.stdout.write,
+    );
     const polls = new Map<string, number>();
     const builds = new Map<string, string>();
     try {
-      Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: true });
-      await writeFile(join(root, "compose.yml"), "services:\n  app:\n    build: .\n  client:\n    build:\n      context: .\n      args:\n        ROLE: client\n");
-      await writeFile(join(root, ".kuberrc.ts"), 'export default { project: "shop" };\n');
+      Object.defineProperty(process.stdout, "isTTY", {
+        configurable: true,
+        value: true,
+      });
+      await writeFile(
+        join(root, "compose.yml"),
+        "services:\n  app:\n    build: .\n  client:\n    build:\n      context: .\n      args:\n        ROLE: client\n",
+      );
+      await writeFile(
+        join(root, ".kuberrc.ts"),
+        'export default { project: "shop" };\n',
+      );
       process.chdir(root);
       const trust = await resolveTrustIdentity("shop", root);
-      const request: ApiRequester = async <T>(path: string, init?: ApiRequestInit) => {
+      const request: ApiRequester = async <T>(
+        path: string,
+        init?: ApiRequestInit,
+      ) => {
         if (path === "/snapshots/negotiate") return { ready: true } as T;
         if (path === "/builds") {
           const build = init!.json as { id: string; service: string };
@@ -70,27 +87,42 @@ describe("up API pipeline", () => {
         const id = path.split("/")[2]!;
         const service = builds.get(id)!;
         if (path.includes("/events"))
-          return [{ type: "status", status: {
-            state: "queued",
-            phase: ["queued", "creating", "starting", "running", "done"][polls.get(service) ?? 0],
-          } }] as T;
+          return [
+            {
+              type: "status",
+              status: {
+                state: "queued",
+                phase: ["queued", "creating", "starting", "running", "done"][
+                  polls.get(service) ?? 0
+                ],
+              },
+            },
+          ] as T;
         if (path.endsWith("/reconcile")) {
           const count = (polls.get(service) ?? 0) + 1;
           polls.set(service, count);
           await Bun.sleep(110);
           return count < 4
-            ? { state: "queued" } as T
+            ? ({ state: "queued" } as T)
             : service === "client"
-              ? { state: "failed", error: "build stopped\nstack detail" } as T
-              : { state: "succeeded" } as T;
+              ? ({ state: "failed", error: "build stopped\nstack detail" } as T)
+              : ({ state: "succeeded" } as T);
         }
         if (path.endsWith("/result")) return { reference: "image:app" } as T;
         throw new Error(path);
       };
-      await expect(provideContext(() => runUp(true, request, { trust }))).rejects.toThrow("build stopped");
+      await expect(
+        provideContext(() => runUp(true, request, { trust })),
+      ).rejects.toThrow("build stopped");
       expect(polls.get("client")).toBe(4);
-      const active = frames.map(frameRows).filter((rows) =>
-        taskRow(rows, "Build images") && taskRow(rows, "Build app") && taskRow(rows, "Build client"));
+      const active = frames
+        .map(frameRows)
+        .filter(
+          (rows) =>
+            taskRow(rows, "Build images") &&
+            taskRow(rows, "Build app") &&
+            taskRow(rows, "Build client"),
+        );
       expect(active.length).toBeGreaterThan(0);
       for (const rows of active) {
         const parent = taskRow(rows, "Build images");
@@ -99,10 +131,22 @@ describe("up API pipeline", () => {
           expect(children).toHaveLength(1);
           expect(depth(children[0]!)).toBeGreaterThan(depth(parent));
         }
-        expect(rows.filter((row) => /^\s*› Build (?:queued|creating|starting|running|done)/.test(row))).toHaveLength(0);
+        const upload = taskRow(rows, "Uploading context:");
+        expect(upload).toBeTruthy();
+        expect(depth(upload)).toBeGreaterThan(depth(parent));
+        expect(rows.indexOf(upload)).toBeLessThan(
+          rows.indexOf(taskRow(rows, "Build app")),
+        );
+        expect(
+          rows.filter((row) =>
+            /^\s*› Build (?:queued|creating|starting|running|done)/.test(row),
+          ),
+        ).toHaveLength(0);
       }
       for (const phase of ["queued", "creating", "starting", "running", "done"])
-        expect(frames.some((frame) => frame.includes(`Build app: ${phase}`))).toBe(true);
+        expect(
+          frames.some((frame) => frame.includes(`Build app: ${phase}`)),
+        ).toBe(true);
       const final = frameRows(frames.at(-1)!);
       expect(taskRow(final, "Build app: done")).toMatch(/✔/);
       expect(taskRow(final, "Build client: failed")).toMatch(/✖/);
@@ -119,43 +163,170 @@ describe("up API pipeline", () => {
     }
   }, 5_000);
 
+  test("shows one aggregate upload child during transfer and completes it before builds", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-up-upload-"));
+    const previousCwd = process.cwd();
+    const tty = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
+    const frames: string[] = [];
+    const create = DefaultRenderer.prototype.create;
+    const renderSpy = spyOn(
+      DefaultRenderer.prototype,
+      "create",
+    ).mockImplementation(function (this: DefaultRenderer, options) {
+      const frame = create.call(this, options);
+      frames.push(frame);
+      return frame;
+    });
+    const writes = spyOn(process.stdout, "write").mockImplementation(
+      (() => true) as typeof process.stdout.write,
+    );
+    let release!: () => void;
+    let started!: () => void;
+    const held = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const patchStarted = new Promise<void>((resolve) => {
+      started = resolve;
+    });
+    try {
+      Object.defineProperty(process.stdout, "isTTY", {
+        configurable: true,
+        value: true,
+      });
+      await writeFile(
+        join(root, "compose.yml"),
+        "services:\n  web:\n    build: .\n",
+      );
+      await writeFile(
+        join(root, ".kuberrc.ts"),
+        'export default { project: "shop" };\n',
+      );
+      process.chdir(root);
+      const trust = await resolveTrustIdentity("shop", root);
+      let missing = "";
+      let negotiations = 0;
+      let submitted = false;
+      const request: ApiRequester = async <T>(
+        path: string,
+        init?: ApiRequestInit,
+      ) => {
+        if (path === "/snapshots/negotiate") {
+          negotiations++;
+          missing = (init!.json as { workspace: string }).workspace;
+          return (
+            negotiations === 1
+              ? { ready: false, missing: [missing] }
+              : { ready: true, missing: [] }
+          ) as T;
+        }
+        if (path.includes("/uploads")) {
+          if (init?.method === "PATCH") {
+            started();
+            await held;
+            return { offset: (init.body as Uint8Array).byteLength } as T;
+          }
+          return { offset: 0, complete: false } as T;
+        }
+        if (path === "/builds") {
+          submitted = true;
+          return { state: "failed", error: "build stopped" } as T;
+        }
+        if (path.includes("/events")) return [] as T;
+        if (path.endsWith("/result")) return { reference: "image:web" } as T;
+        throw new Error(path);
+      };
+      const run = provideContext(() => runUp(true, request, { trust }));
+      await patchStarted;
+      expect(submitted).toBe(false);
+      const active = frames
+        .map(frameRows)
+        .filter(
+          (rows) =>
+            taskRow(rows, "Uploading context:") && taskRow(rows, "Build web"),
+        );
+      expect(active.length).toBeGreaterThan(0);
+      for (const rows of active) {
+        const parent = taskRow(rows, "Build images");
+        const upload = taskRow(rows, "Uploading context:");
+        expect(rows.indexOf(parent)).toBeLessThan(rows.indexOf(upload));
+        expect(rows.indexOf(upload)).toBeLessThan(
+          rows.indexOf(taskRow(rows, "Build web")),
+        );
+        expect(depth(upload)).toBeGreaterThan(depth(parent));
+        expect(
+          rows.filter((row) => row.includes("Uploading sha256:")),
+        ).toHaveLength(0);
+      }
+      release();
+      await expect(run).rejects.toThrow("build stopped");
+      expect(submitted).toBe(true);
+      expect(
+        frames.some((frame) =>
+          /Uploading context: .*\/.* \(100%\)/.test(frame),
+        ),
+      ).toBe(true);
+    } finally {
+      release();
+      renderSpy.mockRestore();
+      writes.mockRestore();
+      if (tty) Object.defineProperty(process.stdout, "isTTY", tty);
+      else Reflect.deleteProperty(process.stdout, "isTTY");
+      process.chdir(previousCwd);
+      await rm(root, { recursive: true, force: true });
+    }
+  }, 5_000);
+
   test("attaches each build log to its started image child", async () => {
     const root = await mkdtemp(join(tmpdir(), "kuber-up-api-"));
     const previousCwd = process.cwd();
     const originalRun = Listr.prototype.run;
     const lines = new Map<string, string[]>();
     const acquired: string[] = [];
-    const runSpy = spyOn(Listr.prototype, "run").mockImplementation(function (this: Listr) {
-      if (this.tasks[0]?.title === "Build web") {
-        for (const entry of this.tasks) {
-          if (!entry.title) continue;
-          const name = entry.title.replace(/^Build /, "");
-          const executable = entry as unknown as { taskFn: typeof entry.task.task };
-          const originalTask = executable.taskFn;
-          executable.taskFn = async (ctx, child) => {
-            const output: string[] = [];
-            lines.set(name, output);
-            child.stdout = () => {
-              acquired.push(name);
-              return new Writable({ write(chunk, _encoding, done) {
-                output.push(String(chunk));
-                done();
-              } });
+    const runSpy = spyOn(Listr.prototype, "run").mockImplementation(
+      function (this: Listr) {
+        if (this.tasks.some((entry) => entry.title === "Build web")) {
+          for (const entry of this.tasks) {
+            if (!entry.title?.startsWith("Build ")) continue;
+            const name = entry.title.replace(/^Build /, "");
+            const executable = entry as unknown as {
+              taskFn: typeof entry.task.task;
             };
-            return originalTask(ctx, child);
-          };
+            const originalTask = executable.taskFn;
+            executable.taskFn = async (ctx, child) => {
+              const output: string[] = [];
+              lines.set(name, output);
+              child.stdout = () => {
+                acquired.push(name);
+                return new Writable({
+                  write(chunk, _encoding, done) {
+                    output.push(String(chunk));
+                    done();
+                  },
+                });
+              };
+              return originalTask(ctx, child);
+            };
+          }
         }
-      }
-      return originalRun.call(this);
-    });
+        return originalRun.call(this);
+      },
+    );
     try {
-      await writeFile(join(root, "compose.yml"),
-        "services:\n  web:\n    build: .\n  worker:\n    build: .\n  admin:\n    build:\n      context: .\n      args:\n        ROLE: admin\n");
-      await writeFile(join(root, ".kuberrc.ts"), 'export default { project: "shop" };\n');
+      await writeFile(
+        join(root, "compose.yml"),
+        "services:\n  web:\n    build: .\n  worker:\n    build: .\n  admin:\n    build:\n      context: .\n      args:\n        ROLE: admin\n",
+      );
+      await writeFile(
+        join(root, ".kuberrc.ts"),
+        'export default { project: "shop" };\n',
+      );
       process.chdir(root);
       const trust = await resolveTrustIdentity("shop", root);
       const builds = new Map<string, string>();
-      const request: ApiRequester = async <T>(path: string, init?: ApiRequestInit) => {
+      const request: ApiRequester = async <T>(
+        path: string,
+        init?: ApiRequestInit,
+      ) => {
         if (path === "/snapshots/negotiate") return { ready: true } as T;
         if (path === "/builds") {
           const build = init!.json as { id: string; service: string };
@@ -165,15 +336,23 @@ describe("up API pipeline", () => {
         const service = builds.get(path.split("/")[2]!)!;
         if (path.includes("/events"))
           return path.includes("after=0")
-            ? [{ type: "log", sequence: 1, message: `${service} log\n` }] as T
-            : [] as T;
+            ? ([{ type: "log", sequence: 1, message: `${service} log\n` }] as T)
+            : ([] as T);
         if (path.endsWith("/reconcile"))
-          return { state: service === "admin" ? "failed" : "succeeded", error: "admin failed" } as T;
+          return {
+            state: service === "admin" ? "failed" : "succeeded",
+            error: "admin failed",
+          } as T;
         if (path.endsWith("/result"))
-          return { reference: "image:web", references: { worker: "image:worker" } } as T;
+          return {
+            reference: "image:web",
+            references: { worker: "image:worker" },
+          } as T;
         throw new Error(path);
       };
-      await expect(provideContext(() => runUp(true, request, { trust }))).rejects.toThrow("admin failed");
+      await expect(
+        provideContext(() => runUp(true, request, { trust })),
+      ).rejects.toThrow("admin failed");
       expect(builds.size).toBe(2);
       expect(acquired.sort()).toEqual(["admin", "web", "worker"]);
       expect(lines.get("web")).toEqual(["web log\n"]);
@@ -190,22 +369,40 @@ describe("up API pipeline", () => {
     const root = await mkdtemp(join(tmpdir(), "kuber-up-api-"));
     const previousCwd = process.cwd();
     const rendered: string[] = [];
-    const writes = spyOn(process.stdout, "write").mockImplementation(((chunk: string | Uint8Array) => {
+    const writes = spyOn(process.stdout, "write").mockImplementation(((
+      chunk: string | Uint8Array,
+    ) => {
       rendered.push(String(chunk));
       return true;
     }) as typeof process.stdout.write);
     try {
-      await writeFile(join(root, "compose.yml"), "services:\n  client:\n    build: .\n  server:\n    build: .\n");
-      await writeFile(join(root, ".kuberrc.ts"), 'export default { project: "shop" };\n');
+      await writeFile(
+        join(root, "compose.yml"),
+        "services:\n  client:\n    build: .\n  server:\n    build: .\n",
+      );
+      await writeFile(
+        join(root, ".kuberrc.ts"),
+        'export default { project: "shop" };\n',
+      );
       process.chdir(root);
       const trust = await resolveTrustIdentity("shop", root);
-      const request: ApiRequester = async <T>(path: string, init?: ApiRequestInit) => {
+      const request: ApiRequester = async <T>(
+        path: string,
+        init?: ApiRequestInit,
+      ) => {
         if (path === "/snapshots/negotiate") return { ready: true } as T;
-        if (path === "/builds") return { id: (init!.json as { id: string }).id, state: "failed", error: "buildkit failed\nstack detail" } as T;
+        if (path === "/builds")
+          return {
+            id: (init!.json as { id: string }).id,
+            state: "failed",
+            error: "buildkit failed\nstack detail",
+          } as T;
         if (path.includes("/events")) return [] as T;
         throw new Error(path);
       };
-      await expect(provideContext(() => runUp(true, request, { trust }))).rejects.toThrow();
+      await expect(
+        provideContext(() => runUp(true, request, { trust })),
+      ).rejects.toThrow();
       const output = rendered.join("");
       expect(output).toContain("Build client");
       expect(output).toContain("Build server");
@@ -288,11 +485,15 @@ describe("up API pipeline", () => {
       expect(
         new Headers(build.init?.headers).get("x-kuber-trust-project"),
       ).toBe("shop");
-      const plans = calls.filter(({ path }) => path === "/workspaces/shop/resources/plan");
+      const plans = calls.filter(
+        ({ path }) => path === "/workspaces/shop/resources/plan",
+      );
       expect(plans).toHaveLength(1);
       expect(plans[0]?.options).toEqual({ timeoutMs: 120_000 });
       expect(plans[0]?.init?.signal).toBeInstanceOf(AbortSignal);
-      expect(new Headers(plans[0]?.init?.headers).get("x-kuber-trust-project")).toBe("shop");
+      expect(
+        new Headers(plans[0]?.init?.headers).get("x-kuber-trust-project"),
+      ).toBe("shop");
     } finally {
       process.chdir(previousCwd);
       if (previousConfigHome === undefined) delete process.env.XDG_CONFIG_HOME;
@@ -310,17 +511,24 @@ describe("up API pipeline", () => {
     const originalRun = Listr.prototype.run;
     const frames: string[] = [];
     const create = DefaultRenderer.prototype.create;
-    const renderSpy = spyOn(DefaultRenderer.prototype, "create").mockImplementation(function (this: DefaultRenderer, options) {
+    const renderSpy = spyOn(
+      DefaultRenderer.prototype,
+      "create",
+    ).mockImplementation(function (this: DefaultRenderer, options) {
       const frame = create.call(this, options);
       frames.push(frame);
       return frame;
     });
     const tty = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
-    const writes = spyOn(process.stdout, "write").mockImplementation((() => true) as typeof process.stdout.write);
-    const runSpy = spyOn(Listr.prototype, "run").mockImplementation(function (this: Listr) {
-      if (this.tasks[0]?.title === "Read compose") rootTasks = this.tasks;
-      return originalRun.call(this);
-    });
+    const writes = spyOn(process.stdout, "write").mockImplementation(
+      (() => true) as typeof process.stdout.write,
+    );
+    const runSpy = spyOn(Listr.prototype, "run").mockImplementation(
+      function (this: Listr) {
+        if (this.tasks[0]?.title === "Read compose") rootTasks = this.tasks;
+        return originalRun.call(this);
+      },
+    );
     let bothReady!: () => void;
     const bothStarted = new Promise<void>((resolve) => {
       bothReady = resolve;
@@ -334,7 +542,10 @@ describe("up API pipeline", () => {
       releaseStorage = resolve;
     });
     try {
-      Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: true });
+      Object.defineProperty(process.stdout, "isTTY", {
+        configurable: true,
+        value: true,
+      });
       await writeFile(
         join(root, "compose.yml"),
         "services:\n  app:\n    image: nginx\n    volumes:\n      - postgresql:app\n      - s3:assets\n",
@@ -348,7 +559,8 @@ describe("up API pipeline", () => {
       const trust = await resolveTrustIdentity("shop", root);
       const request: ApiRequester = async <T>(path: string) => {
         order.push(path);
-        if (path === "/workspaces/shop") throw new KuberApiError("missing", 404);
+        if (path === "/workspaces/shop")
+          throw new KuberApiError("missing", 404);
         if (path === "/workspaces")
           return {
             metadata: { name: "shop", uid: "workspace", resourceVersion: "1" },
@@ -358,7 +570,9 @@ describe("up API pipeline", () => {
           started.push("database");
           if (started.length === 2) bothReady();
           await database;
-          return { app: { DATABASE_URL: "postgresql://app", SHARED: "database" } } as T;
+          return {
+            app: { DATABASE_URL: "postgresql://app", SHARED: "database" },
+          } as T;
         }
         if (path.endsWith("/storage")) {
           started.push("storage");
@@ -379,22 +593,34 @@ describe("up API pipeline", () => {
         expect(titles.indexOf("Render manifests")).toBeLessThan(
           titles.indexOf("Reconcile resources"),
         );
-        const backing = rootTasks!.find(({ title }) => title === "Reconcile backing services")!;
+        const backing = rootTasks!.find(
+          ({ title }) => title === "Reconcile backing services",
+        )!;
         expect(backing.subtasks.map(({ title }) => title)).toEqual([
           "Reconcile databases",
           "Reconcile S3 storage",
         ]);
-        const active = frames.map(frameRows).filter((rows) =>
-          taskRow(rows, "Reconcile backing services") &&
-          taskRow(rows, "Reconcile databases") &&
-          taskRow(rows, "Reconcile S3 storage"));
+        const active = frames
+          .map(frameRows)
+          .filter(
+            (rows) =>
+              taskRow(rows, "Reconcile backing services") &&
+              taskRow(rows, "Reconcile databases") &&
+              taskRow(rows, "Reconcile S3 storage"),
+          );
         expect(active.length).toBeGreaterThan(0);
         for (const rows of active) {
           const parent = taskRow(rows, "Reconcile backing services");
-          expect(depth(taskRow(rows, "Reconcile databases"))).toBeGreaterThan(depth(parent));
-          expect(depth(taskRow(rows, "Reconcile S3 storage"))).toBeGreaterThan(depth(parent));
+          expect(depth(taskRow(rows, "Reconcile databases"))).toBeGreaterThan(
+            depth(parent),
+          );
+          expect(depth(taskRow(rows, "Reconcile S3 storage"))).toBeGreaterThan(
+            depth(parent),
+          );
         }
-        expect(rootTasks!.filter(({ title }) => title === "Reconcile databases")).toEqual([]);
+        expect(
+          rootTasks!.filter(({ title }) => title === "Reconcile databases"),
+        ).toEqual([]);
         expect(started).toEqual(["database", "storage"]);
         expect(order.indexOf("/workspaces/shop/adopt")).toBeLessThan(
           order.indexOf("/workspaces/shop/databases"),
@@ -412,9 +638,9 @@ describe("up API pipeline", () => {
             AWS_ACCESS_KEY_ID: "key",
           },
         });
-        expect(order.indexOf("/workspaces/shop/resources/plan")).toBeGreaterThan(
-          order.indexOf("/workspaces/shop/storage"),
-        );
+        expect(
+          order.indexOf("/workspaces/shop/resources/plan"),
+        ).toBeGreaterThan(order.indexOf("/workspaces/shop/storage"));
       } finally {
         releaseStorage();
         releaseDatabase();
@@ -436,34 +662,61 @@ describe("up API pipeline", () => {
     const previousCwd = process.cwd();
     const frames: string[] = [];
     const create = DefaultRenderer.prototype.create;
-    const renderSpy = spyOn(DefaultRenderer.prototype, "create").mockImplementation(function (this: DefaultRenderer, options) {
+    const renderSpy = spyOn(
+      DefaultRenderer.prototype,
+      "create",
+    ).mockImplementation(function (this: DefaultRenderer, options) {
       const frame = create.call(this, options);
       frames.push(frame);
       return frame;
     });
     const tty = Object.getOwnPropertyDescriptor(process.stdout, "isTTY");
-    const writes = spyOn(process.stdout, "write").mockImplementation((() => true) as typeof process.stdout.write);
+    const writes = spyOn(process.stdout, "write").mockImplementation(
+      (() => true) as typeof process.stdout.write,
+    );
     const calls: string[] = [];
     try {
-      Object.defineProperty(process.stdout, "isTTY", { configurable: true, value: true });
-      await writeFile(join(root, "compose.yml"), "services:\n  web:\n    image: nginx\n    volumes:\n      - postgresql:web_db\n");
-      await writeFile(join(root, ".kuberrc.ts"), 'export default { project: "shop" };\n');
+      Object.defineProperty(process.stdout, "isTTY", {
+        configurable: true,
+        value: true,
+      });
+      await writeFile(
+        join(root, "compose.yml"),
+        "services:\n  web:\n    image: nginx\n    volumes:\n      - postgresql:web_db\n",
+      );
+      await writeFile(
+        join(root, ".kuberrc.ts"),
+        'export default { project: "shop" };\n',
+      );
       process.chdir(root);
       const trust = await resolveTrustIdentity("shop", root);
-      const detail = "Database reconciliation failed during database apply for database web_db (service web, role web): Forbidden";
+      const detail =
+        "Database reconciliation failed during database apply for database web_db (service web, role web): Forbidden";
       const request: ApiRequester = async <T>(path: string) => {
         calls.push(path);
-        if (path === "/workspaces/shop") throw new KuberApiError("missing", 404);
-        if (path === "/workspaces") return { metadata: { name: "shop", uid: "workspace", resourceVersion: "1" } } as T;
+        if (path === "/workspaces/shop")
+          throw new KuberApiError("missing", 404);
+        if (path === "/workspaces")
+          return {
+            metadata: { name: "shop", uid: "workspace", resourceVersion: "1" },
+          } as T;
         if (path.endsWith("/adopt")) return { resourcesAdopted: 0 } as T;
-        if (path.endsWith("/databases")) throw new KuberApiError(detail, 500, {
-          title: "Operation failed", status: 500, code: "DATABASE_RECONCILE_FAILED", detail,
-        });
+        if (path.endsWith("/databases"))
+          throw new KuberApiError(detail, 500, {
+            title: "Operation failed",
+            status: 500,
+            code: "DATABASE_RECONCILE_FAILED",
+            detail,
+          });
         throw new Error(`Unexpected request: ${path}`);
       };
-      await expect(provideContext(() => runUp(false, request, { trust }))).rejects.toThrow(detail);
+      await expect(
+        provideContext(() => runUp(false, request, { trust })),
+      ).rejects.toThrow(detail);
       const rows = frameRows(frames.at(-1)!);
-      expect(depth(taskRow(rows, "Reconcile databases"))).toBeGreaterThan(depth(taskRow(rows, "Reconcile backing services")));
+      expect(depth(taskRow(rows, "Reconcile databases"))).toBeGreaterThan(
+        depth(taskRow(rows, "Reconcile backing services")),
+      );
       expect(taskRow(rows, "Reconcile databases")).toMatch(/✖/);
       const visible = rows.join(" ").replace(/\s+/g, " ");
       expect(visible.split(detail)).toHaveLength(2);
@@ -733,7 +986,8 @@ describe("up API pipeline", () => {
         expect(init?.signal).toBe(controller.signal);
         // Scale 1 simulated second to 1ms: the plan completes at 35s.
         const deadline = options?.timeoutMs ?? 30_000;
-        if (deadline < 35_000) throw new DOMException("Timed out", "TimeoutError");
+        if (deadline < 35_000)
+          throw new DOMException("Timed out", "TimeoutError");
         await Bun.sleep(35);
         return { desired: [], stale: [] } as T;
       }
@@ -752,13 +1006,23 @@ describe("up API pipeline", () => {
     const cancelled = new DOMException("Cancelled", "AbortError");
     const calls: string[] = [];
     let planStarted!: () => void;
-    const started = new Promise<void>((resolve) => { planStarted = resolve; });
-    const request: ApiRequester = async <T>(path: string, init?: ApiRequestInit) => {
+    const started = new Promise<void>((resolve) => {
+      planStarted = resolve;
+    });
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
       calls.push(path);
-      if (!path.endsWith("/plan")) throw new Error(`Unexpected request: ${path}`);
+      if (!path.endsWith("/plan"))
+        throw new Error(`Unexpected request: ${path}`);
       expect(init?.signal).toBe(controller.signal);
       return new Promise<T>((_resolve, reject) => {
-        init?.signal?.addEventListener("abort", () => reject(init.signal?.reason), { once: true });
+        init?.signal?.addEventListener(
+          "abort",
+          () => reject(init.signal?.reason),
+          { once: true },
+        );
         planStarted();
       });
     };
@@ -778,7 +1042,9 @@ describe("up API pipeline", () => {
       calls.push(path);
       throw failure;
     };
-    await expect(reconcileResources("shop", [], 1, undefined, request)).rejects.toBe(failure);
+    await expect(
+      reconcileResources("shop", [], 1, undefined, request),
+    ).rejects.toBe(failure);
     expect(calls).toEqual(["/workspaces/shop/resources/plan"]);
   });
 
diff --git a/tests/lib/build-api.test.ts b/tests/lib/build-api.test.ts
index aa2ed29..7aab842 100644
--- a/tests/lib/build-api.test.ts
+++ b/tests/lib/build-api.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, rm } from "node:fs/promises";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { Writable } from "node:stream";
@@ -14,6 +14,8 @@ import {
   MAX_REQUESTS_PER_SECOND,
 } from "../../lib/build";
 import {
+  enumerateWorkspace,
+  serializeWorkspaceManifest,
   workspaceManifestDigest,
   type WorkspaceSnapshot,
 } from "../../lib/workspace";
@@ -22,6 +24,84 @@ import { ApiStreamUnsupportedError } from "../../lib/api";
 
 const directories: string[] = [];
 
+test("auto URI is submitted and grouped by exact package identity while bare auto stays distinct", async () => {
+  const root = await mkdtemp(join(tmpdir(), "kuber-auto-uri-"));
+  directories.push(root);
+  expect(await Bun.spawn(["git", "init", "-q", root]).exited).toBe(0);
+  await writeFile(join(root, "package.json"), "{}\n");
+  const uri =
+    "https://github.com/example/bun/releases/download/v1/buildpack.cnb";
+  const submitted: BuildRequest[] = [];
+  const request: ApiRequester = async <T>(
+    path: string,
+    init?: ApiRequestInit,
+  ) => {
+    if (path === "/snapshots/negotiate") return { ready: true } as T;
+    if (path.includes("/events")) return [] as T;
+    if (path === "/builds") {
+      const build = init!.json as BuildRequest;
+      submitted.push(build);
+      return { state: "succeeded", id: build.id } as T;
+    }
+    if (path.endsWith("/result")) {
+      const build = submitted.find((build) => path.includes(build.id))!;
+      return {
+        reference: `image:${build.service}`,
+        references: Object.fromEntries(
+          (build.destinations ?? []).map(({ service }) => [
+            service,
+            `image:${service}`,
+          ]),
+        ),
+      } as T;
+    }
+    throw new Error(path);
+  };
+  const result = await buildServices(
+    "shop",
+    {
+      services: {
+        one: { build: `auto:${uri}` },
+        same: { build: `auto:${uri}` },
+        other: { build: `auto:${uri.replace("/v1/", "/v2/")}` },
+        bare: { build: "auto" },
+      },
+    },
+    root,
+    undefined,
+    { request, sleep: async () => {}, workspaceRoot: root },
+  );
+  expect(result.built).toHaveLength(4);
+  expect(submitted).toHaveLength(3);
+  expect(
+    submitted.every(
+      ({ spec }) =>
+        spec.builder === "buildpacks" &&
+        spec.context === "." &&
+        spec.dockerfile === undefined,
+    ),
+  ).toBe(true);
+  expect(
+    submitted.find(({ service }) => service === "one")?.destinations?.[0]
+      ?.service,
+  ).toBe("same");
+  expect(
+    submitted.find(({ service }) => service === "one")?.spec.buildpackUri,
+  ).toBe(uri);
+  expect(
+    submitted.find(({ service }) => service === "bare")?.spec.buildpackUri,
+  ).toBeUndefined();
+  await expect(
+    buildServices(
+      "shop",
+      { services: { bad: { build: "auto:http://localhost/package.cnb" } } },
+      root,
+      undefined,
+      { request, workspaceRoot: root },
+    ),
+  ).rejects.toThrow(/URI/);
+});
+
 function emptySnapshot(): WorkspaceSnapshot {
   const manifest = { version: 1 as const, files: [] };
   return { manifest, digest: workspaceManifestDigest(manifest), blobs: [] };
@@ -72,6 +152,411 @@ afterEach(async () => {
 });
 
 describe("authenticated build API pipeline", () => {
+  test("reports aggregate unique missing bytes per chunk through renegotiation", async () => {
+    const snapshot = createSnapshotWithBlobs(2, 1024);
+    const [first, second] = snapshot.blobs;
+    const total =
+      first!.data.byteLength +
+      second!.data.byteLength +
+      serializeWorkspaceManifest(snapshot.manifest).byteLength;
+    const reports: Array<[number, number]> = [];
+    let release!: () => void;
+    let patchStarted!: () => void;
+    const held = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const started = new Promise<void>((resolve) => {
+      patchStarted = resolve;
+    });
+    let negotiations = 0;
+    const patches = new Map<string, number>();
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
+      if (path === "/snapshots/negotiate") {
+        negotiations++;
+        return (
+          negotiations === 1
+            ? {
+                ready: false,
+                missing: [
+                  first!.digest,
+                  first!.digest,
+                  second!.digest,
+                  snapshot.digest,
+                ],
+              }
+            : negotiations === 2
+              ? { ready: false, missing: [first!.digest, snapshot.digest] }
+              : { ready: true, missing: [] }
+        ) as T;
+      }
+      const digest = decodeURIComponent(path.split("/")[2]!);
+      if (init?.method === "PATCH") {
+        if (digest === first!.digest) {
+          patchStarted();
+          await held;
+        }
+        patches.set(digest, (patches.get(digest) ?? 0) + 1);
+        return { offset: (init.body as Uint8Array).byteLength } as T;
+      }
+      if (init?.method === "POST" && !path.includes("/complete"))
+        return {
+          offset: patches.has(digest)
+            ? digest === snapshot.digest
+              ? total - 2048
+              : 1024
+            : 0,
+          complete: patches.has(digest),
+        } as T;
+      return { complete: true } as T;
+    };
+    const upload = uploadWorkspaceSnapshot(snapshot, request, {
+      upload: (bytes, size) => reports.push([bytes, size]),
+    });
+    await started;
+    expect(reports.at(-1)?.[1]).toBe(total);
+    expect(reports.at(-1)?.[0]).toBeLessThan(total);
+    release();
+    await upload;
+    expect(patches.get(first!.digest)).toBe(1);
+    expect(patches.get(second!.digest)).toBe(1);
+    expect(patches.get(snapshot.digest)).toBe(1);
+    expect(reports.at(-1)).toEqual([total, total]);
+    expect(
+      reports.every(([bytes, size]) => bytes <= size && size === total),
+    ).toBe(true);
+  });
+
+  test("settles the upload with its original error before starting a build", async () => {
+    const snapshot = emptySnapshot();
+    const failure = new Error("upload interrupted");
+    let builds = 0;
+    const settled: unknown[] = [];
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
+      if (path === "/snapshots/negotiate")
+        return { ready: false, missing: [snapshot.digest] } as T;
+      if (path === "/builds") {
+        builds++;
+        throw new Error("unexpected build");
+      }
+      if (init?.method === "PATCH") throw failure;
+      return { offset: 0, complete: false } as T;
+    };
+    await expect(
+      buildServices(
+        "shop",
+        { services: { web: { build: "." } } },
+        process.cwd(),
+        {
+          uploadSettled: (error) => {
+            settled.push(error);
+          },
+        },
+        { request, snapshot },
+      ),
+    ).rejects.toBe(failure);
+    expect(settled).toEqual([failure]);
+    expect(builds).toBe(0);
+  });
+
+  test("keeps builder groups separate even when snapshot digests coincide", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-same-digest-"));
+    directories.push(root);
+    expect(await Bun.spawn(["git", "init", "-q", root]).exited).toBe(0);
+    const snapshot = emptySnapshot();
+    const submissions: BuildRequest[] = [];
+    const uploads: string[] = [];
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
+      if (path === "/snapshots/negotiate") {
+        uploads.push((init!.json as { workspace: string }).workspace);
+        return { ready: true } as T;
+      }
+      if (path === "/builds") {
+        const build = init!.json as BuildRequest;
+        submissions.push(build);
+        return { state: "queued", id: build.id } as T;
+      }
+      if (path.includes("/events")) return [] as T;
+      if (path.endsWith("/reconcile")) return { state: "succeeded" } as T;
+      if (path.endsWith("/result")) return { reference: "image:built" } as T;
+      throw new Error(path);
+    };
+    await buildServices(
+      "shop",
+      {
+        services: {
+          docker: { build: "." },
+          auto: { build: "auto" },
+        },
+      },
+      root,
+      undefined,
+      { request, snapshot, sleep: async () => {}, pollIntervalMs: 0 },
+    );
+    expect(uploads).toEqual([snapshot.digest, snapshot.digest]);
+    expect(submissions).toHaveLength(2);
+    expect(submissions.map(({ spec }) => spec.workspace)).toEqual([
+      snapshot.digest,
+      snapshot.digest,
+    ]);
+    expect(submissions[0]?.spec).not.toHaveProperty("builder");
+    expect(submissions[1]?.spec).toHaveProperty("builder", "buildpacks");
+  });
+
+  test("auto fails before uploading when no Git repository is available", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-auto-gitless-"));
+    directories.push(root);
+    const calls: string[] = [];
+    const request: ApiRequester = async <T>(path: string) => {
+      calls.push(path);
+      return { ready: true } as T;
+    };
+    await expect(
+      buildServices(
+        "shop",
+        { services: { web: { build: "auto" } } },
+        root,
+        undefined,
+        { request, snapshot: emptySnapshot() },
+      ),
+    ).rejects.toThrow(/requires Git and a Git repository/);
+    expect(calls).toEqual([]);
+  });
+
+  test("auto uses a contained selected subproject context and Git-filtered snapshot", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-auto-subproject-"));
+    directories.push(root);
+    expect(await Bun.spawn(["git", "init", "-q", root]).exited).toBe(0);
+    await writeFile(join(root, ".gitignore"), "*.secret\n");
+    await mkdir(join(root, "apps", "web"), { recursive: true });
+    await writeFile(join(root, "apps", "web", "package.json"), "{}\n");
+    await writeFile(join(root, "apps", "web", "app.secret"), "private");
+
+    const submitted: BuildRequest[] = [];
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
+      if (path === "/snapshots/negotiate") return { ready: true } as T;
+      if (path === "/builds") {
+        const build = init!.json as BuildRequest;
+        submitted.push(build);
+        return { state: "queued", id: build.id } as T;
+      }
+      if (path.includes("/events")) return [] as T;
+      if (path.endsWith("/reconcile")) return { state: "succeeded" } as T;
+      if (path.endsWith("/result")) return { reference: "image:built" } as T;
+      throw new Error(path);
+    };
+
+    await buildServices(
+      "shop",
+      {
+        services: {
+          selected: { build: "auto", "x-kuber-build-context": "apps/web" },
+          root: { build: "auto" },
+        },
+      },
+      root,
+      undefined,
+      { request, sleep: async () => {}, pollIntervalMs: 0 },
+    );
+
+    expect(submitted.map(({ spec }) => spec.context)).toEqual([
+      "apps/web",
+      ".",
+    ]);
+    expect(
+      submitted.every(
+        ({ spec }) =>
+          (spec as BuildRequest["spec"] & { builder?: string }).builder ===
+          "buildpacks",
+      ),
+    ).toBe(true);
+    const autoSnapshot = await enumerateWorkspace(root, "auto");
+    expect(autoSnapshot.manifest.files.map(({ path }) => path)).toContain(
+      "apps/web/package.json",
+    );
+    expect(autoSnapshot.manifest.files.map(({ path }) => path)).not.toContain(
+      "apps/web/app.secret",
+    );
+  });
+
+  test("auto rejects traversal and absolute selected contexts", async () => {
+    const root = await mkdtemp(
+      join(tmpdir(), "kuber-auto-context-validation-"),
+    );
+    directories.push(root);
+    expect(await Bun.spawn(["git", "init", "-q", root]).exited).toBe(0);
+    const request: ApiRequester = async <T>() => ({ ready: true }) as T;
+
+    for (const context of [
+      "../outside",
+      "apps/../../outside",
+      "/tmp/outside",
+      "C:/outside",
+    ]) {
+      await expect(
+        buildServices(
+          "shop",
+          {
+            services: {
+              web: { build: "auto", "x-kuber-build-context": context },
+            },
+          },
+          root,
+          undefined,
+          { request, snapshot: emptySnapshot() },
+        ),
+      ).rejects.toThrow(/x-kuber-build-context/);
+    }
+  });
+
+  test("uploads distinct auto and Dockerfile snapshots and groups only matching builders", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-mixed-build-"));
+    directories.push(root);
+    expect(await Bun.spawn(["git", "init", "-q", root]).exited).toBe(0);
+    await writeFile(join(root, ".gitignore"), "tracked.secret\n.env*\n");
+    await writeFile(join(root, "tracked.secret"), "private");
+    expect(
+      await Bun.spawn(["git", "-C", root, "add", "-f", "tracked.secret"])
+        .exited,
+    ).toBe(0);
+    await writeFile(join(root, "Dockerfile"), "FROM scratch\n");
+    await writeFile(join(root, ".dockerignore"), "app.txt\n");
+    await writeFile(join(root, "app.txt"), "app");
+    const regular = await enumerateWorkspace(root);
+    const auto = await enumerateWorkspace(root, "auto");
+    const negotiations: string[] = [];
+    const uploadedManifests = new Map<string, string>();
+    const submissions: BuildRequest[] = [];
+    const progress: Array<[number, number]> = [];
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
+      if (path === "/snapshots/negotiate") {
+        const workspace = (init!.json as { workspace: string }).workspace;
+        negotiations.push(workspace);
+        return {
+          workspace,
+          missing:
+            negotiations.filter((digest) => digest === workspace).length === 1
+              ? [workspace]
+              : [],
+          ready:
+            negotiations.filter((digest) => digest === workspace).length !== 1,
+        } as T;
+      }
+      if (path.includes("/uploads")) {
+        if (init?.method === "PATCH") {
+          const digest = decodeURIComponent(path.split("/")[2]!);
+          uploadedManifests.set(
+            digest,
+            Buffer.from(init.body as Uint8Array).toString(),
+          );
+          return { offset: (init.body as Uint8Array).byteLength } as T;
+        }
+        return { offset: 0, complete: false } as T;
+      }
+      if (path === "/builds") {
+        const build = init?.json as BuildRequest;
+        submissions.push(build);
+        return { state: "queued", id: build.id } as T;
+      }
+      if (path.endsWith("/reconcile")) return { state: "succeeded" } as T;
+      if (path.includes("/events")) return [] as T;
+      if (path.endsWith("/result")) {
+        const build = submissions.find(({ id }) => path.includes(id))!;
+        return {
+          reference: `image:${build.service}`,
+          references: Object.fromEntries(
+            (build.destinations ?? []).map(({ service }) => [
+              service,
+              `image:${service}`,
+            ]),
+          ),
+        } as T;
+      }
+      throw new Error(path);
+    };
+    const result = await buildServices(
+      "shop",
+      {
+        services: {
+          docker: { build: "." },
+          auto: { build: "auto" },
+          second: { build: "auto" },
+        },
+      },
+      root,
+      {
+        upload: (uploaded, total) => {
+          progress.push([uploaded, total]);
+        },
+      },
+      { request, sleep: async () => {}, pollIntervalMs: 0 },
+    );
+    expect(negotiations).toEqual([
+      regular.digest,
+      auto.digest,
+      regular.digest,
+      auto.digest,
+    ]);
+    const totalBytes =
+      serializeWorkspaceManifest(regular.manifest).byteLength +
+      serializeWorkspaceManifest(auto.manifest).byteLength;
+    expect(progress[0]).toEqual([0, totalBytes]);
+    expect(progress.at(-1)).toEqual([totalBytes, totalBytes]);
+    expect(
+      progress.every(
+        ([uploaded, total]) => uploaded <= total && total === totalBytes,
+      ),
+    ).toBe(true);
+    expect([...uploadedManifests.keys()]).toEqual([
+      regular.digest,
+      auto.digest,
+    ]);
+    expect(
+      JSON.parse(uploadedManifests.get(regular.digest)!).files.map(
+        (file: { path: string }) => file.path,
+      ),
+    ).toContain("tracked.secret");
+    expect(
+      JSON.parse(uploadedManifests.get(auto.digest)!).files.map(
+        (file: { path: string }) => file.path,
+      ),
+    ).not.toContain("tracked.secret");
+    expect(submissions).toHaveLength(2);
+    expect(submissions[0]?.spec).toMatchObject({
+      workspace: regular.digest,
+      context: ".",
+    });
+    expect(submissions[0]?.spec).not.toHaveProperty("builder");
+    expect(submissions[1]?.spec).toMatchObject({
+      workspace: auto.digest,
+      context: ".",
+      builder: "buildpacks",
+    });
+    expect(submissions[1]?.spec).not.toHaveProperty("dockerfile");
+    expect(submissions[1]?.destinations).toEqual([
+      { service: "second", image: expect.any(String) },
+    ]);
+    expect(result.images).toEqual({
+      docker: "image:docker",
+      auto: "image:auto",
+      second: "image:second",
+    });
+  });
+
   test("negotiates and uploads the manifest through resumable blob routes", async () => {
     const snapshot = emptySnapshot();
     const controller = new AbortController();
@@ -615,29 +1100,88 @@ describe("authenticated build API pipeline", () => {
       calls.push(path);
       if (path === "/snapshots/negotiate") return { ready: true } as T;
       if (path === "/builds") return { state: "queued" } as T;
-      if (path.endsWith("/result")) return { reference: "image:web", references: { worker: "image:worker" } } as T;
+      if (path.endsWith("/result"))
+        return {
+          reference: "image:web",
+          references: { worker: "image:worker" },
+        } as T;
       throw new Error(`Unexpected JSON request ${path}`);
     };
-    const result = await buildServices("shop", {
-      services: { web: { build: "." }, worker: { build: "." } },
-    }, process.cwd(), { stream: new Writable({ write(chunk, _, done) {
-      output.push(String(chunk)); done();
-    } }) }, { request, snapshot, pollIntervalMs: 0, sleep: async () => {},
-      streamEvents: async function* (_path, after) {
-        cursors.push(after);
-        if (after === 0) {
-          yield { id: 1, event: { type: "log", sequence: 1, id: "build", message: "once\n" } };
-          yield { event: { type: "status", status: { version: 1, id: "build", state: "running", createdAt: "now" } } };
-        } else {
-          yield { id: 1, event: { type: "log", sequence: 1, id: "build", message: "once\n" } };
-          yield { event: { type: "status", status: { version: 1, id: "build", state: "succeeded", createdAt: "now" } } };
-        }
+    const result = await buildServices(
+      "shop",
+      {
+        services: { web: { build: "." }, worker: { build: "." } },
       },
-    });
+      process.cwd(),
+      {
+        stream: new Writable({
+          write(chunk, _, done) {
+            output.push(String(chunk));
+            done();
+          },
+        }),
+      },
+      {
+        request,
+        snapshot,
+        pollIntervalMs: 0,
+        sleep: async () => {},
+        streamEvents: async function* (_path, after) {
+          cursors.push(after);
+          if (after === 0) {
+            yield {
+              id: 1,
+              event: {
+                type: "log",
+                sequence: 1,
+                id: "build",
+                message: "once\n",
+              },
+            };
+            yield {
+              event: {
+                type: "status",
+                status: {
+                  version: 1,
+                  id: "build",
+                  state: "running",
+                  createdAt: "now",
+                },
+              },
+            };
+          } else {
+            yield {
+              id: 1,
+              event: {
+                type: "log",
+                sequence: 1,
+                id: "build",
+                message: "once\n",
+              },
+            };
+            yield {
+              event: {
+                type: "status",
+                status: {
+                  version: 1,
+                  id: "build",
+                  state: "succeeded",
+                  createdAt: "now",
+                },
+              },
+            };
+          }
+        },
+      },
+    );
     expect(result.images).toEqual({ web: "image:web", worker: "image:worker" });
     expect(cursors).toEqual([0, 1]);
     expect(output).toEqual(["[web] once\n"]);
-    expect(calls.filter((path) => path.includes("/events") || path.includes("/reconcile"))).toEqual([]);
+    expect(
+      calls.filter(
+        (path) => path.includes("/events") || path.includes("/reconcile"),
+      ),
+    ).toEqual([]);
   });
 
   test("falls back to JSON events/reconcile only after SSE is unsupported", async () => {
@@ -646,16 +1190,35 @@ describe("authenticated build API pipeline", () => {
       calls.push(path);
       if (path === "/snapshots/negotiate") return { ready: true } as T;
       if (path === "/builds") return { state: "queued" } as T;
-      if (path.includes("/events")) return [{ type: "log", sequence: 1, message: "fallback\n" }] as T;
+      if (path.includes("/events"))
+        return [{ type: "log", sequence: 1, message: "fallback\n" }] as T;
       if (path.endsWith("/reconcile")) return { state: "succeeded" } as T;
       if (path.endsWith("/result")) return { reference: "image:web" } as T;
       throw new Error(path);
     };
-    expect((await buildServices("shop", { services: { web: { build: "." } } },
-      process.cwd(), undefined, { request, snapshot: emptySnapshot(),
-        streamEvents: async function* () { yield* []; throw new ApiStreamUnsupportedError(); },
-      })).images).toEqual({ web: "image:web" });
-    expect(calls.filter((path) => path.includes("/events") || path.includes("/reconcile"))).toEqual([
+    expect(
+      (
+        await buildServices(
+          "shop",
+          { services: { web: { build: "." } } },
+          process.cwd(),
+          undefined,
+          {
+            request,
+            snapshot: emptySnapshot(),
+            streamEvents: async function* () {
+              yield* [];
+              throw new ApiStreamUnsupportedError();
+            },
+          },
+        )
+      ).images,
+    ).toEqual({ web: "image:web" });
+    expect(
+      calls.filter(
+        (path) => path.includes("/events") || path.includes("/reconcile"),
+      ),
+    ).toEqual([
       expect.stringContaining("/events?after=0"),
       expect.stringContaining("/reconcile"),
       expect.stringContaining("/events?after=1"),
@@ -666,7 +1229,9 @@ describe("authenticated build API pipeline", () => {
     const controller = new AbortController();
     const reason = new DOMException("Stopped", "AbortError");
     let listening!: () => void;
-    const ready = new Promise<void>((resolve) => { listening = resolve; });
+    const ready = new Promise<void>((resolve) => {
+      listening = resolve;
+    });
     const calls: string[] = [];
     const request: ApiRequester = async <T>(path: string) => {
       calls.push(path);
@@ -674,14 +1239,26 @@ describe("authenticated build API pipeline", () => {
       if (path === "/builds") return { state: "queued" } as T;
       throw new Error(path);
     };
-    const result = buildServices("shop", { services: { web: { build: "." } } },
-      process.cwd(), undefined, { request, snapshot: emptySnapshot(), signal: controller.signal,
+    const result = buildServices(
+      "shop",
+      { services: { web: { build: "." } } },
+      process.cwd(),
+      undefined,
+      {
+        request,
+        snapshot: emptySnapshot(),
+        signal: controller.signal,
         streamEvents: async function* (_path, _after, signal) {
           yield* [];
           listening();
-          await new Promise<void>((_resolve, reject) => signal?.addEventListener("abort", () => reject(signal.reason), { once: true }));
+          await new Promise<void>((_resolve, reject) =>
+            signal?.addEventListener("abort", () => reject(signal.reason), {
+              once: true,
+            }),
+          );
         },
-      });
+      },
+    );
     await ready;
     controller.abort(reason);
     await expect(result).rejects.toBe(reason);
@@ -763,8 +1340,13 @@ describe("authenticated build API pipeline", () => {
     const output = new Map<string, string[]>();
     let started = 0;
     let release!: () => void;
-    const bothStarted = new Promise<void>((resolve) => { release = resolve; });
-    const request: ApiRequester = async <T>(path: string, init?: ApiRequestInit) => {
+    const bothStarted = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const request: ApiRequester = async <T>(
+      path: string,
+      init?: ApiRequestInit,
+    ) => {
       if (path === "/snapshots/negotiate") return { ready: true } as T;
       if (path === "/builds") {
         const build = init!.json as BuildRequest;
@@ -776,11 +1358,14 @@ describe("authenticated build API pipeline", () => {
       const build = submissions.get(id)!;
       if (path.includes("/events"))
         return path.includes("after=0")
-          ? [
-              { type: "status", status: { state: "running", phase: "running" } },
+          ? ([
+              {
+                type: "status",
+                status: { state: "running", phase: "running" },
+              },
               { type: "log", sequence: 1, message: `${build.service} log\n` },
-            ] as T
-          : [] as T;
+            ] as T)
+          : ([] as T);
       if (path.endsWith("/reconcile")) {
         await bothStarted;
         return { state: "succeeded" } as T;
@@ -794,34 +1379,60 @@ describe("authenticated build API pipeline", () => {
     };
     const result = await buildServices(
       "shop",
-      { services: {
-        web: { build: "." },
-        worker: { build: "." },
-        admin: { build: { context: ".", args: { ROLE: "admin" } } },
-      } },
+      {
+        services: {
+          web: { build: "." },
+          worker: { build: "." },
+          admin: { build: { context: ".", args: { ROLE: "admin" } } },
+        },
+      },
       process.cwd(),
-      { service: (name) => {
-        const lines: string[] = [];
-        output.set(name, lines);
-        return {
-          progress: (message) => { lines.push(message); },
-          stream: new Writable({ write(chunk, _encoding, done) {
-            lines.push(String(chunk));
-            done();
-          } }),
-        };
-      } },
-      { request, snapshot, buildConcurrency: 2, pollIntervalMs: 0, sleep: async () => {} },
+      {
+        service: (name) => {
+          const lines: string[] = [];
+          output.set(name, lines);
+          return {
+            progress: (message) => {
+              lines.push(message);
+            },
+            stream: new Writable({
+              write(chunk, _encoding, done) {
+                lines.push(String(chunk));
+                done();
+              },
+            }),
+          };
+        },
+      },
+      {
+        request,
+        snapshot,
+        buildConcurrency: 2,
+        pollIntervalMs: 0,
+        sleep: async () => {},
+      },
     );
     expect(submissions.size).toBe(2);
-    expect([...submissions.values()].find(({ service }) => service === "web")?.destinations?.map(({ service }) => service)).toEqual(["worker"]);
-    expect(result.images).toEqual({ web: "image:web", worker: "image:worker", admin: "image:admin" });
+    expect(
+      [...submissions.values()]
+        .find(({ service }) => service === "web")
+        ?.destinations?.map(({ service }) => service),
+    ).toEqual(["worker"]);
+    expect(result.images).toEqual({
+      web: "image:web",
+      worker: "image:worker",
+      admin: "image:admin",
+    });
     for (const name of ["web", "worker"]) {
-      expect(output.get(name)?.filter((line) => line === "web log\n")).toHaveLength(1);
+      expect(
+        output.get(name)?.filter((line) => line === "web log\n"),
+      ).toHaveLength(1);
       expect(output.get(name)?.join("")).not.toContain("admin log");
       expect(output.get(name)).toContain("Build running");
     }
-    expect(output.get("admin")?.filter((line) => line === "admin log\n")).toHaveLength(1);
+    expect(
+      output.get("admin")?.filter((line) => line === "admin log\n"),
+    ).toHaveLength(1);
     expect(output.get("admin")?.join("")).not.toContain("web log");
   });
 
@@ -832,22 +1443,36 @@ describe("authenticated build API pipeline", () => {
       if (path === "/builds") return { state: "queued" } as T;
       if (path.includes("/events"))
         return path.includes("after=0")
-          ? [{ type: "log", sequence: 1, message: "one physical build\n" }] as T
-          : [] as T;
+          ? ([
+              { type: "log", sequence: 1, message: "one physical build\n" },
+            ] as T)
+          : ([] as T);
       if (path.endsWith("/reconcile")) return { state: "succeeded" } as T;
       if (path.endsWith("/result"))
-        return { reference: "image:web", references: { worker: "image:worker" } } as T;
+        return {
+          reference: "image:web",
+          references: { worker: "image:worker" },
+        } as T;
       throw new Error(path);
     };
     await buildServices(
       "shop",
       { services: { web: { build: "." }, worker: { build: "." } } },
       process.cwd(),
-      { stream: new Writable({ write(chunk, _encoding, done) {
-        output.push(String(chunk));
-        done();
-      } }) },
-      { request, snapshot: emptySnapshot(), sleep: async () => {}, pollIntervalMs: 0 },
+      {
+        stream: new Writable({
+          write(chunk, _encoding, done) {
+            output.push(String(chunk));
+            done();
+          },
+        }),
+      },
+      {
+        request,
+        snapshot: emptySnapshot(),
+        sleep: async () => {},
+        pollIntervalMs: 0,
+      },
     );
     expect(output).toEqual(["[web] one physical build\n"]);
   });
diff --git a/tests/lib/scaffold-templates.test.ts b/tests/lib/scaffold-templates.test.ts
new file mode 100644
index 0000000..8e990b2
--- /dev/null
+++ b/tests/lib/scaffold-templates.test.ts
@@ -0,0 +1,119 @@
+import { describe, expect, test } from "bun:test";
+import {
+  listDockerfileTemplates,
+  renderDockerfileTemplate,
+  templateIds,
+  type DockerfileTemplateId,
+} from "../../lib/scaffold-templates";
+
+// Parse each Dockerfile's instructions and JSON commands to catch malformed
+// templates without requiring a Docker daemon in the test environment.
+function parseDockerfile(source: string): {
+  stages: string[];
+  commands: string[][];
+} {
+  const stages: string[] = [];
+  const commands: string[][] = [];
+  let stageCount = 0;
+  for (const line of source.split("\n")) {
+    const text = line.trim();
+    if (!text || text.startsWith("#")) continue;
+    const match = /^([A-Z]+)\s+(.+)$/.exec(text);
+    expect(match, `Invalid Dockerfile instruction: ${text}`).not.toBeNull();
+    const [, instruction, argument] = match!;
+    expect([
+      "FROM",
+      "WORKDIR",
+      "COPY",
+      "RUN",
+      "ENV",
+      "USER",
+      "EXPOSE",
+      "CMD",
+      "ENTRYPOINT",
+    ]).toContain(instruction!);
+    if (instruction === "FROM") {
+      stageCount++;
+      const alias = /\s+AS\s+(\w+)$/i.exec(argument!)?.[1];
+      if (alias) stages.push(alias);
+    } else {
+      expect(stageCount, `${instruction} must follow FROM`).toBeGreaterThan(0);
+    }
+    if (instruction === "COPY") {
+      const from = /^--from=(\w+)\s/.exec(argument!)?.[1];
+      if (from) expect(stages).toContain(from);
+    }
+    if (instruction === "CMD" || instruction === "ENTRYPOINT") {
+      const parsed: unknown = JSON.parse(argument!);
+      expect(Array.isArray(parsed)).toBe(true);
+      expect(
+        (parsed as unknown[]).every((value) => typeof value === "string"),
+      ).toBe(true);
+      commands.push(parsed as string[]);
+    }
+  }
+  expect(stageCount).toBeGreaterThan(0);
+  expect(commands).toHaveLength(1);
+  return { stages, commands };
+}
+
+describe("embedded scaffold templates", () => {
+  test("lists eight selectable, distinct templates in stable order", () => {
+    const options = listDockerfileTemplates();
+    expect(options.map(({ id }) => id)).toEqual([...templateIds]);
+    expect(new Set(templateIds).size).toBe(8);
+    for (const { id, label, description } of options) {
+      expect(label.trim()).not.toBe("");
+      expect(description.trim()).not.toBe("");
+      expect(description).toMatch(
+        /src\/|server\.js|dist\/|app:app|binary|port/i,
+      );
+      expect(renderDockerfileTemplate(id).dockerfile).toContain("FROM ");
+    }
+    expect(listDockerfileTemplates()).toEqual(options);
+  });
+
+  test.each([...templateIds])(
+    "renders and parses %s with a safe build context",
+    (id) => {
+      const { dockerfile, dockerignore } = renderDockerfileTemplate(id);
+      expect(dockerfile.length).toBeGreaterThan(50);
+      expect(dockerignore.length).toBeGreaterThan(50);
+      expect(dockerfile.endsWith("\n")).toBe(true);
+      expect(dockerignore.endsWith("\n")).toBe(true);
+      parseDockerfile(dockerfile);
+      const patterns = dockerignore
+        .split("\n")
+        .filter((line) => line && !line.startsWith("#"));
+      expect(patterns).toContain(".git");
+      expect(patterns).toContain(".env");
+      expect(patterns).toContain(".env.*");
+      expect(patterns).toContain("**/.env");
+      expect(patterns).toContain("**/.env.*");
+      expect(dockerfile).not.toMatch(
+        /COPY\s+.*(?:\.env|credentials|\.pem|\.key)/i,
+      );
+      expect(dockerfile).not.toMatch(
+        /\/home\/dmgnr|\/home\/container|hamsterstore|kuber-server/,
+      );
+    },
+  );
+
+  test("static site includes built output while app builders omit it", () => {
+    expect(renderDockerfileTemplate("static-nginx").dockerignore).not.toMatch(
+      /^dist\/?$/m,
+    );
+    expect(renderDockerfileTemplate("static-nginx").dockerfile).toContain(
+      "COPY dist/",
+    );
+    for (const id of ["bun-compiled", "node-pnpm"] as const) {
+      expect(renderDockerfileTemplate(id).dockerignore).toMatch(/^dist$/m);
+    }
+  });
+
+  test("rejects unknown selections", () => {
+    expect(() =>
+      renderDockerfileTemplate("missing" as DockerfileTemplateId),
+    ).toThrow("Unknown Dockerfile template: missing");
+  });
+});
diff --git a/tests/lib/session.test.ts b/tests/lib/session.test.ts
index 9b5f7f0..fa233c1 100644
--- a/tests/lib/session.test.ts
+++ b/tests/lib/session.test.ts
@@ -1,6 +1,13 @@
 import { afterEach, describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
-import { join } from "node:path";
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { dirname, join } from "node:path";
 import { tmpdir } from "node:os";
 import {
   getSessionPath,
@@ -69,6 +76,35 @@ describe("API sessions", () => {
     expect(await readSession()).toBeUndefined();
   });
 
+  test("removes malformed runtime sessions without caching them", async () => {
+    await setupDirectories();
+    const path = getSessionPath(false);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(
+      path,
+      JSON.stringify({ ...session, expiresAt: "not-a-date" }),
+    );
+
+    expect(await readSession()).toBeUndefined();
+    await expect(stat(path)).rejects.toMatchObject({ code: "ENOENT" });
+    expect(await readSession()).toBeUndefined();
+    await writeSession(session, false);
+    expect(await readSession()).toEqual(session);
+  });
+
+  test("removes malformed persistent sessions", async () => {
+    await setupDirectories();
+    const path = getSessionPath(true);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(
+      path,
+      JSON.stringify({ ...session, expiresAt: "not-a-date" }),
+    );
+
+    expect(await readSession()).toBeUndefined();
+    await expect(stat(path)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
   test("invalidates a memoized missing session after writing", async () => {
     await setupDirectories();
     expect(await readSession()).toBeUndefined();
diff --git a/tests/lib/version-update-process.test.ts b/tests/lib/version-update-process.test.ts
index f34d75c..1e6cf5a 100644
--- a/tests/lib/version-update-process.test.ts
+++ b/tests/lib/version-update-process.test.ts
@@ -1,51 +1,62 @@
 import { expect, test } from "bun:test";
 
-test("a short CLI exits while its version updater remains pending", async () => {
-  const moduleUrl = new URL("../../lib/version-update.ts", import.meta.url)
-    .href;
-  const script = `
-    const { createVersionObserver } = await import(${JSON.stringify(moduleUrl)});
-    createVersionObserver({
-      currentVersion: "2.6.1-rc3",
-      runner: () => new Promise(() => {}),
-    })("2.7.0");
-  `;
-  const child = Bun.spawn([process.execPath, "-e", script], {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-  const exit = await Promise.race([
-    child.exited,
-    new Promise<never>((_, reject) =>
-      setTimeout(() => reject(new Error("short CLI stayed alive")), 1_000),
-    ),
-  ]);
-
-  expect(exit).toBe(0);
-  expect(await new Response(child.stderr).text()).toBe("");
-});
+const updaterUrl = new URL("../../lib/version-update.ts", import.meta.url).href;
+const entryUrl = new URL("../../index.ts", import.meta.url).href;
+const mainUrl = new URL("../../command/main.ts", import.meta.url).href;
+const errorUrl = new URL("../../lib/error.ts", import.meta.url).href;
 
 test.each([
   ["success", "return true", "+ Updated to 2.7.0"],
-  ["failure", "throw new Error('install failed')", "+ New version available: 2.7.0"],
-])("reports exactly one %s outcome when it settles", async (_name, outcome, message) => {
-  const moduleUrl = new URL("../../lib/version-update.ts", import.meta.url).href;
-  const script = `
-    const { createVersionObserver } = await import(${JSON.stringify(moduleUrl)});
-    createVersionObserver({
-      currentVersion: "2.6.1-rc3",
-      runner: async () => { ${outcome}; },
-    })("2.7.0");
-    await new Promise((resolve) => setTimeout(resolve, 25));
+  ["command error", "return true", "+ Updated to 2.7.0"],
+  ["failure", "throw new Error('offline')", "+ New version available: 2.7.0"],
+  [
+    "timeout",
+    "return await installVersion(version, () => ({ exited: new Promise(() => {}), kill: () => {} }), 1)",
+    "+ New version available: 2.7.0",
+  ],
+])(
+  "CLI waits for a %s update and preserves its exit status",
+  async (_name, outcome, message) => {
+    const script = `
+    import { mock } from "bun:test";
+    const { createVersionObserver, installVersion } = await import(${JSON.stringify(updaterUrl)});
+    const observe = createVersionObserver({ currentVersion: "2.6.1", runner: async (version) => {
+      if (${JSON.stringify(_name)} !== "timeout") await new Promise(resolve => setTimeout(resolve, 80));
+      ${outcome};
+    }});
+    mock.module("citty", () => ({ createMain: () => async () => {
+      observe("2.7.0");
+      observe("2.8.0");
+      if (${JSON.stringify(_name)} === "command error") throw new Error("command failed");
+      process.exitCode = 7;
+    }}));
+    mock.module(${JSON.stringify(mainUrl)}, () => ({ main: {}, initializeCompletion: async () => {} }));
+    mock.module(${JSON.stringify(errorUrl)}, () => ({ formatUnknownError: String, wrapCommandErrors: () => {} }));
+    await import(${JSON.stringify(entryUrl)});
   `;
-  const child = Bun.spawn([process.execPath, "-e", script], {
-    stdin: "ignore",
-    stdout: "pipe",
-    stderr: "pipe",
-  });
-
-  expect(await child.exited).toBe(0);
-  const stderr = await new Response(child.stderr).text();
-  expect(stderr.split("\n").filter((line) => line.includes(message))).toHaveLength(1);
-});
+    const started = Date.now();
+    const child = Bun.spawn([process.execPath, "-e", script, "login"], {
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const timer = setTimeout(() => child.kill(), 5_000);
+    try {
+      const [code, stdout, stderr] = await Promise.all([
+        child.exited,
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+      ]);
+      expect(code).toBe(_name === "command error" ? 1 : 7);
+      expect(Date.now() - started).toBeGreaterThanOrEqual(
+        _name === "timeout" ? 900 : 70,
+      );
+      expect(stdout).toBe("");
+      expect(stderr).toBe(
+        `${_name === "command error" ? "Error: command failed\n" : ""}\x1b[90m${message}\x1b[0m\n`,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+);
diff --git a/tests/lib/version-update.test.ts b/tests/lib/version-update.test.ts
index fe52adc..14811cb 100644
--- a/tests/lib/version-update.test.ts
+++ b/tests/lib/version-update.test.ts
@@ -3,6 +3,7 @@ import {
   compareVersions,
   createVersionObserver,
   installVersion,
+  waitForVersionUpdate,
 } from "../../lib/version-update";
 
 const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
@@ -36,16 +37,15 @@ describe("server version updates", () => {
     expect(await installVersion("2.7.0;echo hacked")).toBe(false);
   });
 
-  test("uses a quiet detached timeout argument vector", async () => {
+  test("uses a quiet Bun install with explicit inherited environment", async () => {
     const calls: string[][] = [];
-    let unrefs = 0;
     const spawn = (
       argv: string[],
       options: {
         stdin: "ignore";
         stdout: "ignore";
         stderr: "ignore";
-        detached: true;
+        env: NodeJS.ProcessEnv;
       },
     ) => {
       calls.push(argv);
@@ -53,30 +53,69 @@ describe("server version updates", () => {
         stdin: "ignore",
         stdout: "ignore",
         stderr: "ignore",
-        detached: true,
+        env: process.env,
       });
+      expect(options.env.PATH).toBe(process.env.PATH);
       return {
         exited: Promise.resolve(0),
-        unref: () => {
-          unrefs++;
+        kill: () => {
+          throw new Error("unexpected kill");
         },
       };
     };
-    expect(await installVersion("2.7.0-rc.1+build.2", spawn, 1)).toBe(true);
+    expect(await installVersion("2.7.0-rc.1+build.2", spawn, 2)).toBe(true);
     expect(calls).toEqual([
       [
-        "timeout",
-        "--signal=TERM",
-        "--kill-after=2s",
-        "1s",
-        "bun",
+        process.execPath,
         "i",
         "-g",
         "--no-cache",
         "@dmgnr/kuber@2.7.0-rc.1+build.2",
       ],
     ]);
-    expect(unrefs).toBe(1);
+  });
+
+  test("kills a stalled installer and treats late success as failure", async () => {
+    let finish!: (code: number) => void;
+    const exited = new Promise<number>((resolve) => {
+      finish = resolve;
+    });
+    const signals: (NodeJS.Signals | undefined)[] = [];
+    const installing = installVersion(
+      "2.7.0",
+      () => ({
+        exited,
+        kill: (signal) => {
+          signals.push(signal);
+          finish(0);
+        },
+      }),
+      1,
+    );
+    expect(await installing).toBe(false);
+    expect(signals).toEqual([undefined]);
+  });
+
+  test("handles spawn errors and bounds an unresponsive child", async () => {
+    expect(
+      await installVersion("2.7.0", () => {
+        throw new Error("spawn failed");
+      }),
+    ).toBe(false);
+    const signals: (NodeJS.Signals | undefined)[] = [];
+    expect(
+      await installVersion(
+        "2.7.0",
+        () => ({
+          exited: new Promise<number>(() => {}),
+          kill: (signal) => {
+            signals.push(signal);
+          },
+        }),
+        1,
+      ),
+    ).toBe(false);
+    expect(signals).toEqual([undefined, "SIGKILL"]);
   });
 
   test("ignores malformed, equal, and older headers without attempting an install", async () => {
@@ -126,7 +165,7 @@ describe("server version updates", () => {
     expect(runs).toEqual(["2.6.1"]);
     expect(lines).toEqual([]);
     finish(true);
-    await tick();
+    await waitForVersionUpdate();
     expect(lines).toEqual(["\x1b[90m+ Updated to 2.6.1\x1b[0m\n"]);
     observe("10.0.0");
     await tick();
@@ -155,28 +194,6 @@ describe("server version updates", () => {
     }
   });
 
-  test("a detached pending install does not delay a short CLI or pollute its streams", async () => {
-    const url = new URL("../../lib/version-update.ts", import.meta.url).href;
-    const script = `
-      const { createVersionObserver } = await import(${JSON.stringify(url)});
-      createVersionObserver({ currentVersion: '2.6.1',
-        runner: () => new Promise(() => {}) })('2.7.0');
-    `;
-    const child = Bun.spawn([process.execPath, "-e", script], {
-      stdin: "ignore",
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const timeout = setTimeout(() => child.kill(), 1_000);
-    try {
-      expect(await child.exited).toBe(0);
-      expect(await new Response(child.stdout).text()).toBe("");
-      expect(await new Response(child.stderr).text()).toBe("");
-    } finally {
-      clearTimeout(timeout);
-    }
-  });
-
   test("a short subprocess emits one outcome to stderr when its runner settles", async () => {
     const url = new URL("../../lib/version-update.ts", import.meta.url).href;
     for (const result of ["true", "false", "reject"]) {
diff --git a/tests/lib/workspace.test.ts b/tests/lib/workspace.test.ts
index f7ba9a7..e801c51 100644
--- a/tests/lib/workspace.test.ts
+++ b/tests/lib/workspace.test.ts
@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, test } from "bun:test";
 import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
 import {
   mkdtemp,
   mkdir,
@@ -7,6 +8,7 @@ import {
   readlink,
   rm,
   stat,
+  symlink,
   writeFile,
 } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -51,6 +53,105 @@ afterEach(async () => {
 });
 
 describe("workspace snapshots", () => {
+  test("auto uses Git ignore rules even for tracked files, not .dockerignore", async () => {
+    const root = await repository();
+    await mkdir(join(root, "nested"));
+    await writeFile(join(root, ".gitignore"), "*.secret\n.env*\nignored/\n");
+    await writeFile(join(root, "nested/.gitignore"), "*.log\n!important.log\n");
+    await writeFile(join(root, ".dockerignore"), "Dockerfile\nvisible.txt\n");
+    await writeFile(join(root, "Dockerfile"), "FROM scratch\n");
+    await writeFile(join(root, "visible.txt"), "visible");
+    await writeFile(join(root, "tracked.secret"), "tracked secret");
+    await writeFile(join(root, ".env.tracked"), "tracked dotenv");
+    await run("git", [
+      "-C",
+      root,
+      "add",
+      "-f",
+      "tracked.secret",
+      ".env.tracked",
+    ]);
+    await writeFile(join(root, "untracked.secret"), "untracked secret");
+    await writeFile(join(root, ".env.local"), "untracked dotenv");
+    await writeFile(join(root, "nested/debug.log"), "ignored");
+    await run("git", ["-C", root, "add", "-f", "nested/debug.log"]);
+    await writeFile(join(root, "nested/important.log"), "included");
+
+    const regular = await enumerateWorkspace(root);
+    const auto = await enumerateWorkspace(root, "auto");
+    expect(regular.manifest.files.map((file) => file.path)).toContain(
+      "tracked.secret",
+    );
+    expect(regular.manifest.files.map((file) => file.path)).toContain(
+      ".env.local",
+    );
+    expect(auto.manifest.files.map((file) => file.path)).toEqual([
+      ".dockerignore",
+      ".gitignore",
+      "Dockerfile",
+      "nested/.gitignore",
+      "nested/important.log",
+      "visible.txt",
+    ]);
+    expect(auto.digest).not.toBe(regular.digest);
+    expect(await enumerateWorkspace(root, "auto")).toEqual(auto);
+  });
+
+  test("auto rejects selected dotenv and conventional credential paths", async () => {
+    for (const [path, tracked] of [
+      [".env", true],
+      [".env.local", false],
+      [".npmrc", false],
+      ["nested/.ssh/id_ed25519", false],
+      ["services/secrets/production.yaml", false],
+    ] as const) {
+      const root = await repository();
+      const file = join(root, path);
+      await mkdir(join(file, ".."), { recursive: true });
+      await writeFile(file, "credential");
+      if (tracked) await run("git", ["-C", root, "add", "-f", path]);
+      await expect(enumerateWorkspace(root, "auto")).rejects.toThrow(
+        `refuses to snapshot potential credentials at ${path}`,
+      );
+    }
+  });
+
+  test("auto does not reject ignored dotenv or safe sample files", async () => {
+    const root = await repository();
+    await writeFile(join(root, ".gitignore"), ".env\nignored/.env.local\n");
+    await writeFile(join(root, ".env"), "ignored secret");
+    await mkdir(join(root, "ignored"));
+    await writeFile(join(root, "ignored/.env.local"), "ignored secret");
+    await writeFile(join(root, ".env.example"), "TOKEN=replace-me");
+    await writeFile(join(root, "secretary-notes.txt"), "ordinary source");
+
+    const snapshot = await enumerateWorkspace(root, "auto");
+    expect(snapshot.manifest.files.map((file) => file.path)).toEqual([
+      ".env.example",
+      ".gitignore",
+      "secretary-notes.txt",
+    ]);
+  });
+
+  test("auto fails closed without a Git repository or executable", async () => {
+    const root = await temporaryDirectory("kuber-auto-no-git-");
+    await writeFile(join(root, "app.txt"), "app");
+    await expect(enumerateWorkspace(root, "auto")).rejects.toThrow(
+      /requires Git and a Git repository/,
+    );
+    await run("git", ["init", "-q", root]);
+    const previousPath = process.env.PATH;
+    try {
+      process.env.PATH = "";
+      await expect(enumerateWorkspace(root, "auto")).rejects.toThrow(
+        /requires Git and a Git repository/,
+      );
+    } finally {
+      if (previousPath === undefined) delete process.env.PATH;
+      else process.env.PATH = previousPath;
+    }
+  });
+
   test("snapshots Gitless directories deterministically without secrets", async () => {
     const root = await temporaryDirectory("kuber-workspace-filesystem-");
     await writeFile(join(root, "Dockerfile"), "FROM scratch\n");
@@ -69,7 +170,10 @@ describe("workspace snapshots", () => {
 
   test("works without Git and conservatively prunes ignored/generated and credential files", async () => {
     const root = await temporaryDirectory("kuber-workspace-no-git-");
-    await writeFile(join(root, ".gitignore"), "local-only/\n*.generated\nsecrets/\n!secrets/keep.txt\n");
+    await writeFile(
+      join(root, ".gitignore"),
+      "local-only/\n*.generated\nsecrets/\n!secrets/keep.txt\n",
+    );
     await writeFile(join(root, "app.ts"), "source");
     await mkdir(join(root, "local-only"));
     await writeFile(join(root, "local-only", "hidden"), "secret");
@@ -117,7 +221,8 @@ describe("workspace snapshots", () => {
       const second = await enumerateWorkspace(root);
       expect(first).toEqual(second);
       expect(first.manifest.files.map((file) => file.path)).toEqual([
-        ".gitignore", "source.ts",
+        ".gitignore",
+        "source.ts",
       ]);
     } finally {
       if (previousPath === undefined) delete process.env.PATH;
@@ -212,6 +317,105 @@ describe("workspace snapshots", () => {
     await expect(enumerateWorkspace(specialRoot)).rejects.toThrow(
       "Special files",
     );
+
+    const autoRoot = await repository();
+    await run("ln", ["-s", "../outside", join(autoRoot, "escape")]);
+    await expect(enumerateWorkspace(autoRoot, "auto")).rejects.toThrow(
+      "Symlink escapes workspace",
+    );
+  });
+
+  test("does not read Git-tracked files through replaced parent symlinks in either mode", async () => {
+    const root = await repository();
+    const outside = await temporaryDirectory("kuber-workspace-outside-");
+    await mkdir(join(root, "sub"));
+    await writeFile(join(root, "sub/visible.txt"), "original");
+    await run("git", ["-C", root, "add", "sub/visible.txt"]);
+    await rm(join(root, "sub"), { recursive: true });
+    await writeFile(join(outside, "visible.txt"), "outside content");
+    await symlink(outside, join(root, "sub"));
+
+    // Git itself may reject a tracked path beneath a symlink before the
+    // parent guard runs; both outcomes must fail closed.
+    for (const mode of ["default", "auto"] as const)
+      await expect(enumerateWorkspace(root, mode)).rejects.toThrow();
+  });
+
+  test("rejects snapshot symlink chains before normalizing target components", async () => {
+    const root = await repository();
+    await symlink(".", join(root, "sub"));
+    await symlink("sub/..", join(root, "chain"));
+
+    for (const mode of ["default", "auto"] as const) {
+      await expect(enumerateWorkspace(root, mode)).rejects.toThrow(
+        "Symlink traverses snapshot symlink: chain -> sub/..",
+      );
+    }
+
+    const blobs = new Map(
+      ["sub/..", "."].map((target) => {
+        const data = Buffer.from(target);
+        const digest =
+          `sha256:${createHash("sha256").update(data).digest("hex")}` as const;
+        return [digest, data] as const;
+      }),
+    );
+    const manifest: WorkspaceManifest = {
+      version: BUILD_PROTOCOL_VERSION,
+      files: [
+        {
+          path: "chain",
+          type: "symlink",
+          digest: [...blobs.keys()][0]!,
+          size: Buffer.byteLength("sub/.."),
+          mode: 0o777,
+        },
+        {
+          path: "sub",
+          type: "symlink",
+          digest: [...blobs.keys()][1]!,
+          size: Buffer.byteLength("."),
+          mode: 0o777,
+        },
+      ],
+    };
+    const destination = join(await temporaryDirectory("kuber-chain-"), "tree");
+    await expect(
+      materializeWorkspace(destination, manifest, async (digest) =>
+        blobs.get(digest)!,
+      ),
+    ).rejects.toThrow("Symlink traverses snapshot symlink: chain -> sub/..");
+    await expect(stat(destination)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  test("retains safe symlinks in both snapshot modes and materialization", async () => {
+    const root = await repository();
+    await writeFile(join(root, "app.txt"), "safe");
+    await symlink(".", join(root, "sub"));
+    await symlink("./app.txt", join(root, "alias"));
+
+    for (const mode of ["default", "auto"] as const) {
+      const snapshot = await enumerateWorkspace(root, mode);
+      expect(snapshot.manifest.files.map((file) => file.path)).toEqual([
+        "alias",
+        "app.txt",
+        "sub",
+      ]);
+      const blobs = new Map(
+        snapshot.blobs.map((blob) => [blob.digest, blob.data]),
+      );
+      const destination = join(
+        await temporaryDirectory("kuber-safe-links-"),
+        "tree",
+      );
+      await materializeWorkspace(
+        destination,
+        snapshot.manifest,
+        async (digest) => blobs.get(digest)!,
+      );
+      expect(await readlink(join(destination, "sub"))).toBe(".");
+      expect(await readFile(join(destination, "alias"), "utf8")).toBe("safe");
+    }
   });
 
   test("allows ignored special files and prunes ignored directories", async () => {
diff --git a/tests/lib/yaml.test.ts b/tests/lib/yaml.test.ts
index eabbe05..a8b8e1c 100644
--- a/tests/lib/yaml.test.ts
+++ b/tests/lib/yaml.test.ts
@@ -47,6 +47,37 @@ describe("Compose file discovery", () => {
 });
 
 describe("Compose parsing", () => {
+  test("accepts the generated marker and preserves x- extensions", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "compose.yml");
+    await writeFile(
+      path,
+      "managedBy: kuber # See https://npmx.dev/@dmgnr/kuber for documentation.\nname: compose-project\nx-note: retained\nservices:\n  app:\n    image: nginx:latest\n",
+    );
+    expect(await readCompose(path)).toMatchObject({
+      managedBy: "kuber",
+      name: "compose-project",
+      "x-note": "retained",
+      services: { app: { image: "nginx:latest" } },
+    });
+  });
+
+  test("rejects incorrect managedBy values", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "compose.yml");
+    for (const marker of ["other", "42"]) {
+      await writeFile(path, `managedBy: ${marker}\nservices: {}\n`);
+      await expect(readCompose(path)).rejects.toThrow();
+    }
+  });
+
+  test("rejects other unknown top-level properties", async () => {
+    const directory = await temporaryDirectory();
+    const path = join(directory, "compose.yml");
+    await writeFile(path, "managedBy: kuber\nunknown: value\nservices: {}\n");
+    await expect(readCompose(path)).rejects.toThrow();
+  });
+
   test("parses and validates a minimal Compose project", async () => {
     const directory = await temporaryDirectory();
     const path = join(directory, "compose.yml");
diff --git a/tests/server/build-controller.test.ts b/tests/server/build-controller.test.ts
index 76afad5..4b0786a 100644
--- a/tests/server/build-controller.test.ts
+++ b/tests/server/build-controller.test.ts
@@ -1,6 +1,6 @@
 import { afterEach, describe, expect, spyOn, test } from "bun:test";
 import { createHash } from "node:crypto";
-import { lstat, mkdtemp, rm } from "node:fs/promises";
+import { lstat, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -9,6 +9,7 @@ import {
   BuildValidationError,
   type BuildJobObservation,
   type BuildKubernetesOperations,
+  type BuildControllerOptions,
 } from "../../server/build-controller";
 import { createApp } from "../../server/app";
 import { hashToken, MemoryAuthStore } from "../../server/auth";
@@ -109,6 +110,7 @@ class TakeoverAtFencedWriteStore extends MemoryBuildStore {
 async function fixture(
   maxLogBytes = 1024,
   store: BuildStore = new MemoryBuildStore(),
+  extra: Partial<BuildControllerOptions> = {},
 ) {
   const root = await mkdtemp(join(tmpdir(), "kuber-controller-"));
   roots.push(root);
@@ -141,6 +143,7 @@ async function fixture(
     maxLogBytes,
     now: () => new Date(Date.UTC(2026, 8, 2, 0, 0, now++)),
     resolveDigest: async () => `sha256:${"f".repeat(64)}`,
+    ...extra,
   });
   const request: BuildRequest = {
     version: BUILD_PROTOCOL_VERSION,
@@ -236,6 +239,93 @@ async function internalFixture(
 }
 
 describe("build controller", () => {
+  test("stages URI outside source, namespaces cache and cleans superseded/terminal packages", async () => {
+    const staged: string[] = [];
+    const fixtureData = await fixture(1024, new MemoryBuildStore(), {
+      stageBuildpack: async (_uri, arch, destination) => {
+        expect(arch).toBe("arm64");
+        staged.push(destination);
+        await mkdir(destination, { recursive: true });
+        await writeFile(join(destination, "order.toml"), "order");
+      },
+    });
+    const { controller, request, root, store, kubernetes } = fixtureData;
+    request.spec.builder = "buildpacks";
+    request.spec.architecture = "arm64";
+    request.spec.buildpackUri =
+      "https://github.com/example/bun/releases/download/v1/buildpack.cnb";
+    await controller.submitBuild(request);
+    const first = (await store.getBuild(request.id))!;
+    expect(staged[0]).toBe(
+      join(root, "workspaces", `${first.spec.workspaceSubPath}-buildpack`),
+    );
+    expect(
+      await Bun.file(
+        join(root, "workspaces", first.spec.workspaceSubPath, "Dockerfile"),
+      ).text(),
+    ).toBe("FROM scratch\n");
+    const firstArgs = (kubernetes.jobs[0]!.spec as any).template.spec
+      .containers[0].args as string[];
+    const cache1 = firstArgs[firstArgs.indexOf("--cache-image") + 1];
+    expect(cache1).toMatch(/:buildpack-[a-f0-9]{24}$/);
+    const newer = structuredClone(request);
+    newer.id = "request-two";
+    newer.spec.buildpackUri = newer.spec.buildpackUri!.replace("/v1/", "/v2/");
+    await controller.submitBuild(newer);
+    expect(await Bun.file(join(staged[0]!, "order.toml")).exists()).toBe(false);
+    const nextArgs = (kubernetes.jobs[1]!.spec as any).template.spec
+      .containers[0].args as string[];
+    expect(nextArgs[nextArgs.indexOf("--cache-image") + 1]).not.toBe(cache1);
+    kubernetes.observation = { phase: "failed", error: "test" };
+    await controller.reconcileBuild(newer.id);
+    await controller.cleanupBuild(newer.id);
+    expect(await Bun.file(join(staged[1]!, "order.toml")).exists()).toBe(false);
+  });
+
+  test("invalid packages fail before Job and clean source and partial staging", async () => {
+    let destination = "";
+    const { controller, request, store, kubernetes, root } = await fixture(
+      1024,
+      new MemoryBuildStore(),
+      {
+        stageBuildpack: async (_uri, _arch, path) => {
+          destination = path;
+          await mkdir(path, { recursive: true });
+          await writeFile(join(path, "partial"), "bytes");
+          throw new Error(
+            "package target linux/arm64 does not match linux/amd64",
+          );
+        },
+      },
+    );
+    request.spec.builder = "buildpacks";
+    request.spec.buildpackUri =
+      "https://github.com/example/bun/releases/download/v1/buildpack.cnb";
+    await expect(controller.submitBuild(request)).rejects.toThrow(/target/);
+    expect(kubernetes.jobs).toHaveLength(0);
+    const record = (await store.getBuild(request.id))!;
+    expect(record.status.state).toBe("failed");
+    expect(await Bun.file(join(destination, "partial")).exists()).toBe(false);
+    expect(
+      await Bun.file(
+        join(root, "workspaces", record.spec.workspaceSubPath, "Dockerfile"),
+      ).exists(),
+    ).toBe(false);
+  });
+
+  test("validates URI/builder pairing before creating a record", async () => {
+    const { controller, request, store, kubernetes } = await fixture();
+    request.spec.buildpackUri =
+      "https://github.com/example/bun/releases/download/v1/buildpack.cnb";
+    await expect(controller.submitBuild(request)).rejects.toThrow(
+      /requires the buildpacks/,
+    );
+    request.spec.builder = "buildpacks";
+    request.spec.buildpackUri = "https://localhost/buildpack.cnb";
+    await expect(controller.submitBuild(request)).rejects.toThrow(/URI/);
+    expect(await store.getBuild(request.id)).toBeUndefined();
+    expect(kubernetes.jobs).toHaveLength(0);
+  });
   test("correlates a UUID build request with the stored build and emits only summary keys", async () => {
     const { controller, request, store } = await fixture();
     request.id = "123e4567-e89b-42d3-a456-426614174000";
@@ -420,6 +510,133 @@ describe("build controller", () => {
     });
   });
 
+  test("submits a Buildpacks Job with mapped destinations and retains result and status semantics", async () => {
+    const resolved: string[] = [];
+    const { controller, request, kubernetes } = await internalFixture(
+      1024,
+      async (image) => {
+        resolved.push(image);
+        return `sha256:${"f".repeat(64)}`;
+      },
+    );
+    request.spec.builder = "buildpacks";
+    request.destinations = [
+      { service: "worker", image: "external.example/other:latest" },
+    ];
+    expect(await controller.submitBuild(request)).toMatchObject({
+      state: "queued",
+    });
+    const pod = (kubernetes.jobs[0]!.spec as any).template.spec;
+    expect(pod.containers[0].command).toEqual(["/cnb/lifecycle/creator"]);
+    expect(pod.containers[0].args).toContain("--tag");
+    expect(pod.containers[0].args).toContain(
+      "cncf-distribution-svc.registry.svc.cluster.local:5000/kuber/demo-worker:latest",
+    );
+    expect(pod.containers[0].args.at(-1)).toBe(
+      "cncf-distribution-svc.registry.svc.cluster.local:5000/kuber/demo-web:latest",
+    );
+    kubernetes.observation = { phase: "succeeded" };
+    expect(await controller.reconcileBuild(request.id)).toMatchObject({
+      state: "succeeded",
+      digest: `sha256:${"f".repeat(64)}`,
+    });
+    expect(resolved).toEqual([
+      "registry.neko-piranha.ts.net/kuber/demo-web:latest",
+      "registry.neko-piranha.ts.net/kuber/demo-worker:latest",
+    ]);
+    expect(await controller.getBuildResult(request.id)).toMatchObject({
+      reference: `registry.neko-piranha.ts.net/kuber/demo-web@sha256:${"f".repeat(64)}`,
+      references: {
+        worker: `registry.neko-piranha.ts.net/kuber/demo-worker@sha256:${"f".repeat(64)}`,
+      },
+    });
+  });
+
+  test("rejects unsupported builders and Buildpacks Dockerfile options before Job creation", async () => {
+    const { controller, request, kubernetes } = await fixture();
+    for (const incompatible of [
+      { dockerfile: "Dockerfile" },
+      { target: "production" },
+      { buildArgs: ["A=B"] },
+    ]) {
+      await expect(
+        controller.submitBuild({
+          ...request,
+          spec: {
+            ...request.spec,
+            builder: "buildpacks",
+            ...incompatible,
+          },
+        }),
+      ).rejects.toBeInstanceOf(BuildValidationError);
+    }
+    await expect(
+      controller.submitBuild({
+        ...request,
+        spec: {
+          ...request.spec,
+          builder: "unknown" as any,
+        },
+      }),
+    ).rejects.toBeInstanceOf(BuildValidationError);
+    expect(kubernetes.jobs).toHaveLength(0);
+  });
+
+  test("rejects an unpinned Buildpacks image before creating a record", async () => {
+    const { controller, request, kubernetes, store } = await fixture();
+    request.spec.builder = "buildpacks";
+    (controller as any).options.buildpacksImage = "heroku/builder:26";
+    await expect(controller.submitBuild(request)).rejects.toThrow(
+      "digest-pinned",
+    );
+    expect(kubernetes.jobs).toHaveLength(0);
+    expect(await store.getBuild(request.id)).toBeUndefined();
+  });
+
+  test("fails a Buildpacks build with destinations in different registries", async () => {
+    const { controller, request, kubernetes } = await fixture();
+    request.spec.builder = "buildpacks";
+    request.destinations = [
+      { service: "worker", image: "another.example.com/worker:latest" },
+    ];
+    await expect(controller.submitBuild(request)).rejects.toThrow(
+      "same registry",
+    );
+    expect(kubernetes.jobs).toHaveLength(0);
+    expect(await controller.getBuildStatus(request.id)).toMatchObject({
+      state: "failed",
+      error: expect.stringContaining("same registry"),
+    });
+  });
+
+  test("Buildpacks alias digest mismatch fails and cancellation deletes its Job", async () => {
+    const { controller, request, kubernetes } = await internalFixture(
+      1024,
+      async (image) =>
+        `sha256:${(image.includes("worker") ? "e" : "f").repeat(64)}`,
+    );
+    request.spec.builder = "buildpacks";
+    request.destinations = [
+      { service: "worker", image: "registry.test/worker:latest" },
+    ];
+    await controller.submitBuild(request);
+    kubernetes.observation = { phase: "succeeded" };
+    expect(await controller.reconcileBuild(request.id)).toMatchObject({
+      state: "failed",
+      error: expect.stringContaining("different digest"),
+    });
+
+    const pending = await fixture();
+    pending.request.spec.builder = "buildpacks";
+    await pending.controller.submitBuild(pending.request);
+    expect(
+      await pending.controller.cancelBuild(pending.request.id),
+    ).toMatchObject({ state: "failed" });
+    expect(pending.kubernetes.deleted).toContain(
+      pending.kubernetes.jobs[0]!.metadata.name,
+    );
+  });
+
   test("fails the shared job if an alias resolves to a different digest", async () => {
     const { controller, request, kubernetes } = await internalFixture(
       1024,
diff --git a/tests/server/build-job.test.ts b/tests/server/build-job.test.ts
index 99431b7..71684cc 100644
--- a/tests/server/build-job.test.ts
+++ b/tests/server/build-job.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, test } from "bun:test";
 import { createBuildJob } from "../../server/build-job";
+import {
+  createBuildpacksJob,
+  DEFAULT_BUILDPACKS_IMAGE,
+} from "../../server/buildpacks-job";
 import type { BuildSpec } from "../../shared/build-protocol";
 
 function spec(architecture: "arm64" | "amd64"): BuildSpec {
@@ -242,3 +246,220 @@ describe("BuildKit Job generation", () => {
     ).toThrow("Workspace subPath");
   });
 });
+
+describe("Buildpacks Job generation", () => {
+  test("mounts custom package separately, preserves builtins and passes explicit creator order", () => {
+    const uri =
+      "https://github.com/example/bun/releases/download/v1/buildpack.cnb";
+    const job = createBuildpacksJob({
+      ...options("arm64"),
+      spec: { ...options("arm64").spec, buildpackUri: uri },
+      buildpackSubPath: "workspaces/job-buildpack",
+    });
+    const pod = (job.spec as any).template.spec;
+    const creator = pod.containers[0];
+    expect(creator.args).toContain("--buildpacks");
+    expect(creator.args).toContain("/custom-buildpacks");
+    expect(creator.args).toContain("--order");
+    expect(creator.args).toContain("/package/order.toml");
+    expect(creator.volumeMounts).toContainEqual({
+      name: "workspace",
+      mountPath: "/package",
+      subPath: "workspaces/job-buildpack",
+      readOnly: true,
+    });
+    expect(creator.volumeMounts).toContainEqual({
+      name: "custom-buildpacks",
+      mountPath: "/custom-buildpacks",
+      readOnly: true,
+    });
+    expect(pod.initContainers[0].args[0]).toContain("/cnb/buildpacks/.");
+    expect(pod.initContainers[1].name).toBe("copy-source");
+    expect(
+      pod.initContainers[1].volumeMounts.some(
+        (mount: any) => mount.mountPath === "/package",
+      ),
+    ).toBe(false);
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        spec: { ...options().spec, buildpackUri: uri },
+      }),
+    ).toThrow(/staged/);
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        spec: { ...options().spec, buildpackUri: uri },
+        buildpackSubPath: "../outside",
+      }),
+    ).toThrow(/safe/);
+  });
+  const options = (architecture: "amd64" | "arm64" = "amd64") => ({
+    name: "build-cnb",
+    namespace: "builds",
+    spec: {
+      ...spec(architecture),
+      builder: "buildpacks" as const,
+      dockerfile: undefined,
+      target: undefined,
+      buildArgs: [],
+    },
+    workspaceClaimName: "workspaces",
+    workspaceSubPath: "snapshot",
+    cacheImage: `registry.example.com/cache/demo-web-cnb-${architecture}`,
+    registrySecretName: "registry-auth",
+    nodeSelector: { pool: "builders", "kubernetes.io/arch": "wrong" },
+  });
+
+  test.each(["amd64", "arm64"] as const)(
+    "uses pinned lifecycle and isolated writable directories on %s",
+    (architecture) => {
+      const job = createBuildpacksJob(options(architecture));
+      const pod = (job.spec as any).template.spec;
+      const init = pod.initContainers[0];
+      const creator = pod.containers[0];
+      expect(creator.name).toBe("buildkit");
+      expect(init.image).toBe(DEFAULT_BUILDPACKS_IMAGE);
+      expect(creator.image).toBe(DEFAULT_BUILDPACKS_IMAGE);
+      expect(init.command).toEqual(["/bin/sh", "-ec"]);
+      expect(init.args).toEqual([
+        'cp -R "$1/." /cnb-app/ && chmod -R u+rwX /cnb-app',
+        "--",
+        "/workspace/apps/web",
+      ]);
+      expect(init.volumeMounts[0]).toEqual({
+        name: "workspace",
+        mountPath: "/workspace",
+        readOnly: true,
+        subPath: "snapshot",
+      });
+      expect(creator.command).toEqual(["/cnb/lifecycle/creator"]);
+      expect(creator.args).toEqual([
+        "--app",
+        "/cnb-app",
+        "--layers",
+        "/layers",
+        "--platform",
+        "/platform",
+        "--cache-image",
+        `registry.example.com/cache/demo-web-cnb-${architecture}`,
+        "--uid",
+        "1000",
+        "--gid",
+        "1000",
+        "registry.example.com/kuber/demo-web:latest",
+      ]);
+      expect(creator.volumeMounts).not.toContainEqual(
+        expect.objectContaining({ name: "workspace" }),
+      );
+      for (const name of ["app", "layers", "cache", "platform", "tmp"])
+        expect(pod.volumes).toContainEqual({ name, emptyDir: {} });
+      expect(pod.securityContext).toMatchObject({
+        runAsUser: 1000,
+        runAsGroup: 1000,
+        fsGroup: 1000,
+        seccompProfile: { type: "RuntimeDefault" },
+      });
+      expect(creator.securityContext.allowPrivilegeEscalation).toBe(false);
+      expect(pod.automountServiceAccountToken).toBe(false);
+      expect(pod.nodeSelector).toEqual({
+        pool: "builders",
+        "kubernetes.io/arch": architecture,
+      });
+      expect(pod.tolerations?.length ?? 0).toBe(
+        architecture === "amd64" ? 1 : 0,
+      );
+      expect(creator.env).toContainEqual({
+        name: "CNB_PLATFORM_API",
+        value: "0.15",
+      });
+      expect(creator.env).toContainEqual({
+        name: "DOCKER_CONFIG",
+        value: "/docker-config",
+      });
+      expect(creator.volumeMounts).toContainEqual({
+        name: "registry-auth",
+        mountPath: "/docker-config",
+        readOnly: true,
+      });
+      expect(pod.volumes).toContainEqual({
+        name: "registry-auth",
+        secret: {
+          secretName: "registry-auth",
+          items: [{ key: ".dockerconfigjson", path: "config.json" }],
+        },
+      });
+      expect(pod.imagePullSecrets).toEqual([{ name: "registry-auth" }]);
+    },
+  );
+
+  test("exports additional tags and scopes insecure registry flags", () => {
+    const job = createBuildpacksJob({
+      ...options(),
+      cacheImage: "cache.local:5000/demo-cnb-amd64",
+      pushImage: "internal.local:5000/web:latest",
+      pushImages: [
+        "internal.local:5000/worker:latest",
+        "internal.local:5000/other:latest",
+      ],
+      pushRegistryInsecure: true,
+      cacheRegistryInsecure: true,
+    });
+    expect((job.spec as any).template.spec.containers[0].args).toEqual([
+      "--app",
+      "/cnb-app",
+      "--layers",
+      "/layers",
+      "--platform",
+      "/platform",
+      "--cache-image",
+      "cache.local:5000/demo-cnb-amd64",
+      "--uid",
+      "1000",
+      "--gid",
+      "1000",
+      "--insecure-registry",
+      "internal.local:5000",
+      "--insecure-registry",
+      "cache.local:5000",
+      "--tag",
+      "internal.local:5000/worker:latest",
+      "--tag",
+      "internal.local:5000/other:latest",
+      "internal.local:5000/web:latest",
+    ]);
+  });
+
+  test("rejects unpinned builders and incompatible options", () => {
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        pushImages: ["another.example.com/worker:latest"],
+      }),
+    ).toThrow("same registry");
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        buildpacksImage: "heroku/builder:26",
+      }),
+    ).toThrow("digest-pinned");
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        buildpacksImage: "heroku/builder@sha256:deadbeef",
+      }),
+    ).toThrow("digest-pinned");
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        spec: { ...options().spec, dockerfile: "Dockerfile" },
+      }),
+    ).toThrow("does not support");
+    expect(() =>
+      createBuildpacksJob({
+        ...options(),
+        spec: { ...options().spec, context: "../escape" },
+      }),
+    ).toThrow("safe workspace-relative");
+  });
+});
diff --git a/tests/server/buildpack-package.test.ts b/tests/server/buildpack-package.test.ts
new file mode 100644
index 0000000..20d886f
--- /dev/null
+++ b/tests/server/buildpack-package.test.ts
@@ -0,0 +1,375 @@
+import { describe, expect, test } from "bun:test";
+import { createHash } from "node:crypto";
+import { mkdtemp, readFile, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { gzipSync } from "node:zlib";
+import {
+  BUILDPACK_LIMITS,
+  fetchBuildpackPackage,
+  parseBuildpackTar,
+  unpackBuildpackPackage,
+  stageBuildpackPackage,
+  type PackageFetcher,
+} from "../../server/buildpack-package";
+import { validateBuildpackUri } from "../../shared/build-protocol";
+
+const uri = "https://github.com/example/bun/releases/download/v1/buildpack.cnb";
+const digest = (bytes: Uint8Array) =>
+  `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+function tar(
+  files: Array<{ path: string; data?: Buffer; type?: string; mode?: number }>,
+): Buffer {
+  const chunks: Buffer[] = [];
+  for (const file of files) {
+    const data = file.data ?? Buffer.alloc(0);
+    const header = Buffer.alloc(512);
+    header.write(file.path, 0, 100);
+    header.write((file.mode ?? 0o644).toString(8).padStart(7, "0") + "\0", 100);
+    header.write(data.length.toString(8).padStart(11, "0") + "\0", 124);
+    header.fill(32, 148, 156);
+    header.write(file.type ?? "0", 156);
+    header.write("ustar\0", 257);
+    const sum = header.reduce((a, b) => a + b, 0);
+    header.write(sum.toString(8).padStart(6, "0") + "\0 ", 148);
+    chunks.push(header, data, Buffer.alloc((512 - (data.length % 512)) % 512));
+  }
+  return Buffer.concat([...chunks, Buffer.alloc(1024)]);
+}
+
+export function syntheticPackage(
+  options: {
+    arch?: string;
+    mismatch?: boolean;
+    composite?: boolean;
+    corrupt?: boolean;
+    badDiff?: boolean;
+    targets?: string;
+    api?: string;
+  } = {},
+): Buffer {
+  const api = options.api ?? "0.10";
+  const root = "/cnb/buildpacks/example_bun/1.0.0";
+  const layer = tar([
+    {
+      path: `${root}/buildpack.toml`,
+      data: Buffer.from(
+        `api = "${api}"\n[buildpack]\nid = "${options.mismatch ? "wrong" : "example/bun"}"\nversion = "1.0.0"\n${options.composite ? '[[order]]\n[[order.group]]\nid = "dependency"\n' : ""}${options.targets ?? ""}`,
+      ),
+    },
+    {
+      path: `${root}/bin/detect`,
+      data: Buffer.from("#!/bin/sh\nexit 0\n"),
+      mode: 0o755,
+    },
+    {
+      path: `${root}/bin/build`,
+      data: Buffer.from("#!/bin/sh\nexit 0\n"),
+      mode: 0o755,
+    },
+  ]);
+  const compressed = gzipSync(layer);
+  const metadata = {
+    id: "example/bun",
+    version: "1.0.0",
+    stacks: [{ id: "*" }],
+  };
+  const config = Buffer.from(
+    JSON.stringify({
+      architecture: options.arch ?? "arm64",
+      os: "linux",
+      rootfs: {
+        type: "layers",
+        diff_ids: [
+          options.badDiff ? `sha256:${"0".repeat(64)}` : digest(layer),
+        ],
+      },
+      config: {
+        Labels: {
+          "io.buildpacks.buildpackage.metadata": JSON.stringify(metadata),
+          "io.buildpacks.buildpack.layers": JSON.stringify({
+            "example/bun": {
+              "1.0.0": {
+                api,
+                layerDiffID: digest(layer),
+                targets: [{ os: "linux", arch: options.arch ?? "arm64" }],
+              },
+            },
+          }),
+        },
+      },
+    }),
+  );
+  const descriptor = (bytes: Buffer, mediaType: string) => ({
+    mediaType,
+    digest: digest(bytes),
+    size: bytes.length,
+  });
+  const manifest = Buffer.from(
+    JSON.stringify({
+      schemaVersion: 2,
+      config: descriptor(config, "application/vnd.oci.image.config.v1+json"),
+      layers: [
+        descriptor(compressed, "application/vnd.oci.image.layer.v1.tar+gzip"),
+      ],
+    }),
+  );
+  return tar([
+    {
+      path: "/oci-layout",
+      data: Buffer.from('{"imageLayoutVersion":"1.0.0"}'),
+    },
+    {
+      path: "/index.json",
+      data: Buffer.from(
+        JSON.stringify({
+          schemaVersion: 2,
+          manifests: [
+            descriptor(manifest, "application/vnd.oci.image.manifest.v1+json"),
+          ],
+        }),
+      ),
+    },
+    ...[config, manifest, compressed].map((data) => ({
+      path: `/blobs/sha256/${digest(data).slice(7)}`,
+      data:
+        options.corrupt && data === config
+          ? Buffer.from("x".repeat(data.length))
+          : data,
+    })),
+  ]);
+}
+
+describe("buildpack packages", () => {
+  test("stages escaped ID with executable files and explicit order outside source", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-package-"));
+    try {
+      const destination = join(root, "package");
+      await stageBuildpackPackage(
+        uri,
+        "arm64",
+        destination,
+        async () => new Response(syntheticPackage()),
+      );
+      expect(await readFile(join(destination, "order.toml"), "utf8")).toBe(
+        '[[order]]\n[[order.group]]\nid = "example/bun"\nversion = "1.0.0"\n',
+      );
+      expect(
+        (
+          await stat(
+            join(destination, "buildpacks/example_bun/1.0.0/bin/build"),
+          )
+        ).mode & 0o777,
+      ).toBe(0o755);
+    } finally {
+      await rm(root, { recursive: true, force: true });
+    }
+  });
+  test("accepts known absolute OCI/CNB prefixes, verified config and gzip layers", () => {
+    const pkg = unpackBuildpackPackage(gzipSync(syntheticPackage()), "arm64");
+    expect(pkg.id).toBe("example/bun");
+    expect(pkg.version).toBe("1.0.0");
+    expect(pkg.entries.map((entry) => entry.path)).toContain(
+      "example_bun/1.0.0/bin/build",
+    );
+  });
+  test.each(["null", "[]", '"layout"', "{"])(
+    "rejects malformed OCI metadata %s",
+    (value) => {
+      expect(() =>
+        unpackBuildpackPackage(
+          tar([{ path: "oci-layout", data: Buffer.from(value) }]),
+          "arm64",
+        ),
+      ).toThrow(/JSON metadata/);
+    },
+  );
+  test("rejects an OCI index with a non-array manifest list", () => {
+    expect(() =>
+      unpackBuildpackPackage(
+        tar([
+          {
+            path: "oci-layout",
+            data: Buffer.from('{"imageLayoutVersion":"1.0.0"}'),
+          },
+          {
+            path: "index.json",
+            data: Buffer.from('{"schemaVersion":2,"manifests":{"length":1}}'),
+          },
+        ]),
+        "arm64",
+      ),
+    ).toThrow(/one OCI image manifest/);
+  });
+  test.each([
+    [{ arch: "arm64" }, "amd64", /target/],
+    [{ mismatch: true }, "arm64", /descriptor/],
+    [{ corrupt: true }, "arm64", /digest/],
+    [{ badDiff: true }, "arm64", /diff digest/],
+    [{ composite: true }, "arm64", /composite/],
+    [{ api: "0.99" }, "arm64", /API/],
+    [
+      { targets: '[[targets]]\nos = "linux"\narch = "amd64"\n' },
+      "arm64",
+      /targets/,
+    ],
+  ] as const)(
+    "rejects incompatible/invalid package %#",
+    (options, arch, error) => {
+      expect(() =>
+        unpackBuildpackPackage(syntheticPackage(options), arch),
+      ).toThrow(error);
+    },
+  );
+  test.each([
+    "../escape",
+    "/etc/passwd",
+    "/blobs/../escape",
+    "a//b",
+    "a/./b",
+    "a\\b",
+    "C:/x",
+  ])("rejects tar traversal %s", (path) => {
+    expect(() => parseBuildpackTar(tar([{ path }]), "oci")).toThrow(/unsafe/);
+  });
+  test.each(["1", "2", "3", "4", "6", "x", "g", "L"])(
+    "rejects links/devices/extensions %s",
+    (type) => {
+      expect(() =>
+        parseBuildpackTar(tar([{ path: "x", type }]), "oci"),
+      ).toThrow(/unsupported/);
+    },
+  );
+  test("rejects checksum, truncation, duplicate paths and file/directory collisions", () => {
+    const bytes = tar([{ path: "x", data: Buffer.from("hello") }]);
+    bytes[0] = 121;
+    expect(() => parseBuildpackTar(bytes, "oci")).toThrow(/checksum/);
+    expect(() =>
+      parseBuildpackTar(
+        tar([{ path: "x", data: Buffer.from("x") }]).subarray(0, 513),
+        "oci",
+      ),
+    ).toThrow(/truncated/);
+    expect(() =>
+      parseBuildpackTar(tar([{ path: "x" }, { path: "x" }]), "oci"),
+    ).toThrow(/duplicate/);
+    expect(() =>
+      parseBuildpackTar(tar([{ path: "x" }, { path: "x/y" }]), "oci"),
+    ).toThrow(/directory/);
+  });
+  test("bounds entries, file sizes and decompression", () => {
+    expect(() =>
+      parseBuildpackTar(
+        tar(
+          Array.from({ length: BUILDPACK_LIMITS.entries + 1 }, (_, index) => ({
+            path: String(index),
+          })),
+        ),
+        "oci",
+      ),
+    ).toThrow(/entry limit/);
+    expect(() =>
+      parseBuildpackTar(
+        tar([{ path: "x", data: Buffer.alloc(BUILDPACK_LIMITS.file + 1) }]),
+        "oci",
+      ),
+    ).toThrow(/file size/);
+    expect(() =>
+      parseBuildpackTar(
+        gzipSync(Buffer.alloc(BUILDPACK_LIMITS.expanded + 1), { level: 1 }),
+        "oci",
+      ),
+    ).toThrow();
+  });
+  test.each([
+    "http://github.com/a/b/releases/download/v1/x.cnb",
+    "https://user@github.com/a/b/releases/download/v1/x.cnb",
+    "https://github.com.evil.test/a/b/releases/download/v1/x.cnb",
+    "https://127.0.0.1/x.cnb",
+    "https://github.com/a/b/blob/x.cnb",
+    uri + "#other",
+    uri + "?token=x",
+    "file:///x.cnb",
+  ])("rejects URI %s", (value) => {
+    expect(() => validateBuildpackUri(value)).toThrow();
+  });
+  test("manually follows the release asset redirect and verifies optional pin", async () => {
+    const bytes = syntheticPackage();
+    const calls: string[] = [];
+    const fetcher = (async (url: any, init: any) => {
+      calls.push(String(url));
+      expect(init.redirect).toBe("manual");
+      return calls.length === 1
+        ? new Response(null, {
+            status: 302,
+            headers: {
+              location:
+                "https://release-assets.githubusercontent.com/asset?signature=x",
+            },
+          })
+        : new Response(bytes);
+    }) as PackageFetcher;
+    expect(
+      await fetchBuildpackPackage(
+        `${uri}#sha256=${digest(bytes).slice(7)}`,
+        fetcher,
+      ),
+    ).toEqual(bytes);
+    expect(calls).toHaveLength(2);
+    await expect(
+      fetchBuildpackPackage(
+        `${uri}#sha256=${"0".repeat(64)}`,
+        async () => new Response(bytes),
+      ),
+    ).rejects.toThrow(/SHA-256/);
+  });
+  test.each([
+    "http://github.com/x",
+    "https://release-assets.githubusercontent.com.evil.test/x",
+    "https://localhost/x",
+    "https://user:pass@github.com/x",
+    "https://github.com:444/x",
+  ])("rejects redirect before fetching %s", async (location) => {
+    let calls = 0;
+    await expect(
+      fetchBuildpackPackage(uri, async () => {
+        calls++;
+        return new Response(null, { status: 302, headers: { location } });
+      }),
+    ).rejects.toThrow(/redirect/);
+    expect(calls).toBe(1);
+  });
+  test("bounds redirect count and advertised/streamed download sizes", async () => {
+    await expect(
+      fetchBuildpackPackage(
+        uri,
+        async () =>
+          new Response(null, { status: 302, headers: { location: uri } }),
+      ),
+    ).rejects.toThrow(/redirect limit/);
+    await expect(
+      fetchBuildpackPackage(
+        uri,
+        async () =>
+          new Response("", {
+            headers: {
+              "content-length": String(BUILDPACK_LIMITS.download + 1),
+            },
+          }),
+      ),
+    ).rejects.toThrow(/size limit/);
+    let cancelled = false;
+    const stream = new ReadableStream({
+      pull(controller) {
+        controller.enqueue(new Uint8Array(1024 * 1024));
+      },
+      cancel() {
+        cancelled = true;
+      },
+    });
+    await expect(
+      fetchBuildpackPackage(uri, async () => new Response(stream)),
+    ).rejects.toThrow(/size limit/);
+    expect(cancelled).toBe(true);
+  });
+});
diff --git a/tests/server/materialize.test.ts b/tests/server/materialize.test.ts
index d5446e4..d4be9cf 100644
--- a/tests/server/materialize.test.ts
+++ b/tests/server/materialize.test.ts
@@ -160,6 +160,158 @@ describe("source materialization", () => {
     expect(await readlink(join(destination, "run"))).toBe("bin/run");
   });
 
+  test("rejects effective symlink escapes in either manifest order before writing or reading file blobs", async () => {
+    for (const entries of [
+      [
+        ["sub", "."],
+        ["chain", "sub/.."],
+      ],
+      [
+        ["chain", "sub/.."],
+        ["sub", "."],
+      ],
+    ]) {
+      const root = await mkdtemp(join(tmpdir(), "kuber-materialize-"));
+      roots.push(root);
+      const destination = join(root, "workspace");
+      const file = Buffer.from("content");
+      const fileDigest = digest(file);
+      const blobs = new Map<Sha256Digest, Uint8Array>();
+      const manifest: WorkspaceManifest = {
+        version: BUILD_PROTOCOL_VERSION,
+        files: [
+          {
+            path: "file",
+            type: "file",
+            digest: fileDigest,
+            size: file.length,
+            mode: 0o644,
+          },
+          ...entries.map(([path, target]) => {
+            const data = Buffer.from(target!);
+            const id = digest(data);
+            blobs.set(id, data);
+            return {
+              path: path!,
+              type: "symlink" as const,
+              digest: id,
+              size: data.length,
+              mode: 0o777 as const,
+            };
+          }),
+        ],
+      };
+      const manifestData = Buffer.from(JSON.stringify(manifest));
+      const manifestDigest = digest(manifestData);
+      const reads: Sha256Digest[] = [];
+      await expect(
+        materializeWorkspace(
+          {
+            get: async (requested) => {
+              reads.push(requested);
+              if (requested === manifestDigest) return manifestData;
+              if (requested === fileDigest)
+                throw new Error("file blob read before validation");
+              return blobs.get(requested)!;
+            },
+          },
+          manifestDigest,
+          destination,
+        ),
+      ).rejects.toThrow("Unsafe symlink target for chain");
+      expect(reads).not.toContain(fileDigest);
+      await expect(lstat(destination)).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    }
+  });
+
+  test("materializes safe chained and parent-relative links", async () => {
+    const root = await mkdtemp(join(tmpdir(), "kuber-materialize-"));
+    roots.push(root);
+    const cas = new FilesystemCas(join(root, "cas"));
+    const files = await Promise.all(
+      [
+        ["nested/parent", "../file"],
+        ["chain", "nested/parent"],
+        ["repeat", "nested/../nested/parent"],
+      ].map(async ([path, target]) => {
+        const data = Buffer.from(target!);
+        return {
+          path: path!,
+          type: "symlink" as const,
+          digest: await cas.put(data),
+          size: data.length,
+          mode: 0o777 as const,
+        };
+      }),
+    );
+    const content = Buffer.from("safe");
+    const manifest: WorkspaceManifest = {
+      version: BUILD_PROTOCOL_VERSION,
+      files: [
+        ...files,
+        {
+          path: "file",
+          type: "file",
+          digest: await cas.put(content),
+          size: content.length,
+          mode: 0o644,
+        },
+      ],
+    };
+    const destination = join(root, "workspace");
+    await materializeWorkspace(
+      cas,
+      await cas.put(Buffer.from(JSON.stringify(manifest))),
+      destination,
+    );
+    expect(await readFile(join(destination, "chain"), "utf8")).toBe("safe");
+    expect(await readFile(join(destination, "repeat"), "utf8")).toBe("safe");
+  });
+
+  test("rejects direct escapes and symlink cycles before destination creation", async () => {
+    for (const links of [
+      [["nested/bad", "../../outside"]],
+      [
+        ["a", "b"],
+        ["b", "a"],
+      ],
+      [["self", "self"]],
+    ]) {
+      const root = await mkdtemp(join(tmpdir(), "kuber-materialize-"));
+      roots.push(root);
+      const cas = new FilesystemCas(join(root, "cas"));
+      const files = await Promise.all(
+        links.map(async ([path, target]) => {
+          const data = Buffer.from(target!);
+          return {
+            path: path!,
+            type: "symlink" as const,
+            digest: await cas.put(data),
+            size: data.length,
+            mode: 0o777 as const,
+          };
+        }),
+      );
+      const manifest: WorkspaceManifest = {
+        version: BUILD_PROTOCOL_VERSION,
+        files,
+      };
+      const destination = join(root, "workspace");
+      await expect(
+        materializeWorkspace(
+          cas,
+          await cas.put(Buffer.from(JSON.stringify(manifest))),
+          destination,
+        ),
+      ).rejects.toThrow(/Unsafe symlink/);
+      await expect(lstat(destination)).rejects.toMatchObject({
+        code: "ENOENT",
+      });
+    }
+  });
+
   test("rejects traversal, path collisions, unsafe links, and size mismatches atomically", async () => {
     expect(() =>
       parseWorkspaceManifest(
diff --git a/tests/server/registry.test.ts b/tests/server/registry.test.ts
index a0ec0da..74990e7 100644
--- a/tests/server/registry.test.ts
+++ b/tests/server/registry.test.ts
@@ -6,6 +6,16 @@ import {
 } from "../../server/registry";
 
 describe("OCI registry digest resolution", () => {
+  const validManifest = JSON.stringify({
+    schemaVersion: 2,
+    mediaType: "application/vnd.oci.image.manifest.v1+json",
+    config: {
+      mediaType: "application/vnd.oci.image.config.v1+json",
+      digest: `sha256:${"a".repeat(64)}`,
+      size: 1,
+    },
+    layers: [],
+  });
   test("parses tags, ports, defaults, and pinned references", () => {
     expect(parseImageReference("localhost:5000/team/image:v1")).toMatchObject({
       registry: "localhost:5000",
@@ -33,7 +43,9 @@ describe("OCI registry digest resolution", () => {
       "_build",
       "a".repeat(128),
     ]) {
-      expect(parseImageReference(`localhost:5000/team/my_image:${tag}`)).toEqual({
+      expect(
+        parseImageReference(`localhost:5000/team/my_image:${tag}`),
+      ).toEqual({
         registry: "localhost:5000",
         repository: "team/my_image",
         reference: tag,
@@ -41,7 +53,9 @@ describe("OCI registry digest resolution", () => {
     }
     const digest = `sha256:${"a".repeat(64)}` as const;
     expect(
-      parseImageReference(`registry.example.com/team/my-image:Release_1@${digest}`),
+      parseImageReference(
+        `registry.example.com/team/my-image:Release_1@${digest}`,
+      ),
     ).toEqual({
       registry: "registry.example.com",
       repository: "team/my-image",
@@ -49,7 +63,8 @@ describe("OCI registry digest resolution", () => {
       digest,
     });
     expect(
-      parseImageReference(`registry.example.com/team/my-image@${digest}`).digest,
+      parseImageReference(`registry.example.com/team/my-image@${digest}`)
+        .digest,
     ).toBe(digest);
   });
 
@@ -79,7 +94,9 @@ describe("OCI registry digest resolution", () => {
   });
 
   test("resolves an anonymous manifest using the advertised digest", async () => {
-    const expected = `sha256:${"b".repeat(64)}` as const;
+    const body = validManifest;
+    const expected =
+      `sha256:${createHash("sha256").update(body).digest("hex")}` as const;
     const calls: Array<{ url: string; authorization: string | null }> = [];
     const fetcher = async (
       input: string | URL | Request,
@@ -90,7 +107,7 @@ describe("OCI registry digest resolution", () => {
         url: String(input),
         authorization: headers.get("authorization"),
       });
-      return new Response("manifest", {
+      return new Response(body, {
         headers: { "docker-content-digest": expected },
       });
     };
@@ -107,13 +124,28 @@ describe("OCI registry digest resolution", () => {
     ]);
   });
 
+  test("rejects a valid but incorrect advertised manifest digest", async () => {
+    const body = validManifest;
+    const incorrect = `sha256:${"b".repeat(64)}`;
+    await expect(
+      resolveRegistryDigest("mismatch.example.com/team/image:v1", {
+        fetch: async () =>
+          new Response(body, {
+            headers: { "docker-content-digest": incorrect },
+          }),
+      }),
+    ).rejects.toThrow("does not match Docker-Content-Digest");
+  });
+
   test("caches successful digest resolutions with deterministic expiry and bounds", async () => {
     let now = 0;
     let calls = 0;
+    const body = validManifest;
+    const advertised = `sha256:${createHash("sha256").update(body).digest("hex")}`;
     const fetcher = async () => {
       calls += 1;
-      return new Response("manifest", {
-        headers: { "docker-content-digest": `sha256:${"d".repeat(64)}` },
+      return new Response(body, {
+        headers: { "docker-content-digest": advertised },
       });
     };
     const options = {
@@ -157,8 +189,10 @@ describe("OCI registry digest resolution", () => {
       init?: RequestInit,
     ) => {
       authorizedCalls.push(new Headers(init?.headers).get("authorization")!);
-      return new Response("manifest", {
-        headers: { "docker-content-digest": `sha256:${"e".repeat(64)}` },
+      return new Response(validManifest, {
+        headers: {
+          "docker-content-digest": `sha256:${createHash("sha256").update(validManifest).digest("hex")}`,
+        },
       });
     };
     for (const username of ["one", "two"]) {
@@ -171,7 +205,8 @@ describe("OCI registry digest resolution", () => {
   });
 
   test("resolves through a trusted internal registry origin", async () => {
-    const expected = `sha256:${"c".repeat(64)}` as const;
+    const expected =
+      `sha256:${createHash("sha256").update(validManifest).digest("hex")}` as const;
     let requested = "";
     await expect(
       resolveRegistryDigest("registry.example.com/team/image:v1", {
@@ -179,8 +214,10 @@ describe("OCI registry digest resolution", () => {
         insecure: true,
         fetch: async (input) => {
           requested = String(input);
-          return new Response("manifest", {
-            headers: { "docker-content-digest": expected },
+          return new Response(validManifest, {
+            headers: {
+              "docker-content-digest": `sha256:${createHash("sha256").update(validManifest).digest("hex")}`,
+            },
           });
         },
       }),
@@ -191,7 +228,8 @@ describe("OCI registry digest resolution", () => {
   });
 
   test("follows a standard bearer challenge and hashes a digest-less response", async () => {
-    const body = '{"schemaVersion":2}';
+    const body =
+      '{"schemaVersion":2,"mediaType":"application/vnd.oci.image.index.v1+json","manifests":[]}';
     const expected =
       `sha256:${createHash("sha256").update(body).digest("hex")}` as const;
     const calls: Array<{ url: string; authorization: string | null }> = [];
@@ -250,7 +288,7 @@ describe("OCI registry digest resolution", () => {
     ).rejects.toThrow("401");
 
     const malformed = async () =>
-      new Response("body", {
+      new Response(validManifest, {
         headers: { "docker-content-digest": "sha256:bad" },
       });
     await expect(
@@ -259,4 +297,65 @@ describe("OCI registry digest resolution", () => {
       }),
     ).rejects.toThrow("Invalid SHA-256");
   });
+
+  test("rejects empty, non-JSON, and malformed manifests with or without digest headers", async () => {
+    const malformedBodies = [
+      "",
+      "sensitive registry response body",
+      '{"schemaVersion":2,"mediaType":"application/vnd.oci.image.manifest.v1+json","layers":[]}',
+    ];
+    for (const [index, body] of malformedBodies.entries()) {
+      for (const includeDigest of [false, true]) {
+        const headers = includeDigest
+          ? {
+              "docker-content-digest": `sha256:${createHash("sha256").update(body).digest("hex")}`,
+            }
+          : undefined;
+        await expect(
+          resolveRegistryDigest(
+            `invalid-${index}-${includeDigest}.example/team/image`,
+            {
+              cacheTtlMs: 0,
+              fetch: async () => new Response(body, { headers }),
+            },
+          ),
+        ).rejects.toThrow("invalid manifest");
+      }
+    }
+  });
+
+  test("accepts supported manifest/index media types with generic content type", async () => {
+    const fixtures = [
+      validManifest,
+      JSON.stringify({
+        schemaVersion: 2,
+        mediaType: "application/vnd.docker.distribution.manifest.v2+json",
+        config: {},
+        layers: [],
+      }),
+      JSON.stringify({
+        schemaVersion: 2,
+        mediaType: "application/vnd.oci.image.index.v1+json",
+        manifests: [],
+      }),
+      JSON.stringify({
+        schemaVersion: 2,
+        mediaType: "application/vnd.docker.distribution.manifest.list.v2+json",
+        manifests: [],
+      }),
+    ];
+    for (const [index, body] of fixtures.entries()) {
+      await expect(
+        resolveRegistryDigest(`valid-${index}.example/team/image`, {
+          cacheTtlMs: 0,
+          fetch: async () =>
+            new Response(body, {
+              headers: { "content-type": "application/octet-stream" },
+            }),
+        }),
+      ).resolves.toBe(
+        `sha256:${createHash("sha256").update(body).digest("hex")}`,
+      );
+    }
+  });
 });
diff --git a/tests/shared/build-protocol.test.ts b/tests/shared/build-protocol.test.ts
index dc7c169..b2670d1 100644
--- a/tests/shared/build-protocol.test.ts
+++ b/tests/shared/build-protocol.test.ts
@@ -29,4 +29,23 @@ describe("build protocol", () => {
     expect(isSha256Digest(`sha256:${"F".repeat(64)}`)).toBe(false);
     expect(() => assertSha256Digest("sha256:short")).toThrow("Invalid SHA-256");
   });
+
+  test("round-trips an explicit buildpacks builder without changing protocol version", () => {
+    const request: BuildRequest = {
+      version: BUILD_PROTOCOL_VERSION,
+      id: "cnb-build",
+      project: "demo",
+      service: "web",
+      spec: {
+        builder: "buildpacks",
+        architecture: "arm64",
+        image: "registry.example/demo/web:latest",
+        context: ".",
+        buildArgs: [],
+        workspace: `sha256:${"a".repeat(64)}`,
+      },
+    };
+    expect(JSON.parse(JSON.stringify(request))).toEqual(request);
+    expect(request.version).toBe(1);
+  });
 });