garaje 0.1.4 → 0.2.0

package/dist/upgrade/index.js

@@ -1,9 +1,16 @@
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { classify } from "./classify.js";
 import { currentBaseVersion, rewriteBasePin, rewriteDockerfileCliPin } from "./pins.js";
+import { DEFAULT_PACKAGES, isScaffoldedGaraje, mergeSettingsPackages, missingDefaultPackages, rematerialize, scaffoldPiLensConfig, } from "./managed.js";
+import { discoverBays, readRecipes, readToolchainArtifact, writeToolchainArtifact, } from "../park/index.js";
+import { generateToolchain, isEmptyToolchain, parseToolchainBays, } from "../park/toolchain.js";
+import { readManifest } from "../manifest.js";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(HERE, "../../templates"); // packages/cli/templates
 /** Resolve @garaje/base@<version> into a directory tree via `npm pack`, or
  *  undefined if it can't be fetched (e.g. pre-publish / offline). */
 function fetchBaseTree(version) {
@@ -29,6 +36,200 @@ function parseTo(args) {
         return args[i + 1];
     return undefined;
 }
+/** Re-read recipes one bay at a time to name whichever one is corrupt, for a
+ *  better error message. Reuses readRecipes itself rather than re-implementing
+ *  any parsing — this only narrows down which single bay a whole-list throw
+ *  came from. */
+function describeRecipeFailure(root, bays, err) {
+    for (const bay of bays) {
+        try {
+            readRecipes(root, [bay]);
+        }
+        catch (e) {
+            return `bay '${bay}' has a corrupt recipe.yaml (${e.message}) — fix it, then re-run upgrade`;
+        }
+    }
+    return `a bay recipe.yaml failed to parse (${err.message}) — fix it, then re-run upgrade`;
+}
+/** Bays the manifest names but discoverBays() didn't find parked (no
+ *  recipe.yaml) — split into "not even cloned" (garaje sync will help) vs
+ *  "cloned but missing recipe.yaml" (sync is a no-op there; `garaje park`
+ *  only fails outright when NOTHING anywhere is parked, so it silently
+ *  excludes this bay rather than fixing it — the real remedy is authoring
+ *  bays/<name>/recipe.yaml). doctor.ts draws this same "parked is stricter
+ *  than synced/cloned" line; this mirrors it with a concrete per-bay remedy
+ *  instead of one blanket "sync then park" that is actively wrong for a
+ *  bay that is already cloned. */
+function describeUnparkedBays(root, names) {
+    const notCloned = names.filter((n) => !existsSync(join(root, "bays", n, ".git")));
+    const clonedNoRecipe = names.filter((n) => !notCloned.includes(n));
+    const parts = [];
+    if (notCloned.length) {
+        parts.push(`not synced: ${notCloned.join(", ")} (run \`garaje sync\`, then \`garaje park\`)`);
+    }
+    if (clonedNoRecipe.length) {
+        const authorHint = clonedNoRecipe.length === 1
+            ? `bays/${clonedNoRecipe[0]}/recipe.yaml`
+            : clonedNoRecipe.map((n) => `bays/${n}/recipe.yaml`).join(", ");
+        parts.push(`cloned but missing recipe.yaml: ${clonedNoRecipe.join(", ")} (author ${authorHint}, ` +
+            "then `garaje park` — `garaje sync` is a no-op here)");
+    }
+    return parts.join("; ");
+}
+/**
+ * Decide the pi/toolchain/ outcome for `garaje upgrade`, using BOTH the
+ * committed manifest (garaje.yaml, read STRICTLY via readManifest — see
+ * below) and what is actually on disk (discoverBays) — never discoverBays
+ * alone, and never manifestBays().
+ *
+ * bays/* is gitignored in every garaje: a fresh clone has the manifest but
+ * none of the bay working trees. discoverBays() then returns [], and
+ * regenerating from that would silently gut a correct, committed toolchain
+ * artifact down to empty (Finding A) — worse than the bug this replaced,
+ * because `garaje up --build` then succeeds with a Ruby-less pi container.
+ *
+ * Decision table:
+ * - garaje.yaml unreadable (missing, corrupt, OR — strict mode — a `bays:`
+ *   entry with no usable `name:`) and pi/toolchain/ IS committed -> leave it
+ *   (it is still the last-known truth) and say why.
+ * - garaje.yaml unreadable and pi/toolchain/ is NOT committed -> fail before
+ *   any write: there is nothing to derive the toolchain from and nothing to
+ *   fall back on (Finding C — manifestBays() used to collapse this into the
+ *   same `[]` as "the manifest genuinely declares no bays", and `write` then
+ *   gutted or fabricated an empty artifact instead of failing loud).
+ * - every manifest bay parked (including the vacuous case: manifest declares
+ *   none) -> regenerate from the parked recipes; readRecipes can still throw
+ *   on a corrupt recipe, which this catches and reports as "fail" rather than
+ *   letting it escape as an uncaught exception (Finding B) — UNLESS doing so
+ *   would NARROW a committed artifact (see the structural invariant below),
+ *   in which case that fires instead of "write".
+ * - some of the manifest's bays are not parked -> the committed artifact, if
+ *   present, was generated from these recipes when they WERE parked, so it
+ *   is still ground truth: leave it untouched and say why (which bay(s), and
+ *   the CORRECT remedy per bay — see describeUnparkedBays).
+ * - same, but pi/toolchain/ doesn't exist at all -> nothing to fall back on;
+ *   fail the upgrade outright rather than materialize a Dockerfile whose
+ *   `COPY toolchain/` has nothing to copy.
+ *
+ * STRUCTURAL INVARIANT: never replace a committed toolchain artifact with one
+ * derived from a SMALLER bay set than the artifact itself records. Four
+ * separate bugs have now reached "artifact silently narrowed, image builds,
+ * pi is missing a runtime" by four different routes — a gitignored bays/ on a
+ * fresh clone, a corrupt garaje.yaml, a `bays:` entry silently dropped for
+ * lacking `name:` (syntactically valid YAML — parseManifest's lenient mode
+ * does not throw on it), and a bay parked locally but never added to
+ * garaje.yaml at all. Patching each route individually kept finding a new
+ * one; the actual invariant is about the ARTIFACT, not any one cause:
+ * `generateToolchain` now records the bay set it was derived from in a
+ * `# bays: ...` comment (parseToolchainBays reads it back). If the committed
+ * artifact's recorded set is not a subset of the set we are about to
+ * regenerate from — i.e. regenerating would drop a bay the committed
+ * artifact reflects — refuse, whatever the cause, and name the dropped
+ * bay(s). Regenerating from the SAME set, or a LARGER one, is unaffected.
+ * `isEmptyToolchain` remains as a backstop for an artifact committed before
+ * this provenance line existed (no `# bays:` to compare against).
+ */
+export function planToolchain(root) {
+    const committed = readToolchainArtifact(root); // undefined = nothing committed at all
+    // Read the manifest STRICTLY — this is a WRITER, not a check. manifestBays()
+    // is lenient (missing/corrupt -> []) because every OTHER caller is a check
+    // that reports a bad manifest and moves on; see its docstring in
+    // ../park/index.ts for why a writer must not reuse that leniency. Strict
+    // mode additionally throws on a `bays:` entry with no usable name — see
+    // ParseManifestOptions in ../manifest.ts — so THAT silent-drop route is
+    // caught here directly, same as a missing/corrupt garaje.yaml, rather than
+    // relying solely on the narrowing check below to notice its effect.
+    let manifest;
+    try {
+        manifest = readManifest(root, { strict: true });
+    }
+    catch (e) {
+        const reason = e.message;
+        if (committed) {
+            return {
+                action: "leave",
+                message: `garaje.yaml is unreadable (${reason}) — pi/toolchain/ left as committed (fix garaje.yaml, then re-run upgrade)`,
+            };
+        }
+        return {
+            action: "fail",
+            message: `garaje.yaml is unreadable (${reason}) and pi/toolchain/ does not exist — the toolchain can't ` +
+                `be derived and the image won't build. Fix garaje.yaml, then re-run upgrade.`,
+        };
+    }
+    const manifestNames = manifest.map((b) => b.name);
+    const parked = discoverBays(root);
+    const unparked = manifestNames.filter((b) => !parked.includes(b));
+    if (unparked.length === 0) {
+        let recipes;
+        try {
+            recipes = readRecipes(root, parked);
+        }
+        catch (e) {
+            return { action: "fail", message: describeRecipeFailure(root, parked, e) };
+        }
+        // generateToolchain can ALSO throw (an unsafe bay name, or — the
+        // structural backstop — a provenance round-trip failure), and used to do
+        // so OUTSIDE any try/catch here, routing around the `action: "fail"` path
+        // this whole ToolchainPlan design exists to provide: the exception
+        // propagated straight out of planToolchain, then out of runUpgrade (which
+        // has no top-level catch either), and `garaje upgrade` printed a raw
+        // Node stack trace instead of a clean, actionable failure.
+        let toolchain;
+        try {
+            toolchain = generateToolchain(recipes);
+        }
+        catch (e) {
+            return {
+                action: "fail",
+                message: `pi/toolchain/ can't be generated (${e.message}) — fix the recipe, then re-run upgrade`,
+            };
+        }
+        if (committed) {
+            const committedBays = parseToolchainBays(committed.miseToml);
+            if (committedBays !== undefined) {
+                // The provenance line is present — do the precise per-bay diff.
+                const newBays = new Set(recipes.map((r) => r.name));
+                const dropped = committedBays.filter((b) => !newBays.has(b));
+                if (dropped.length > 0) {
+                    return {
+                        action: "fail",
+                        message: `regenerating pi/toolchain/ from garaje.yaml would drop bay(s) the committed artifact ` +
+                            `was derived from: ${dropped.join(", ")} — refusing to narrow it. This can happen even ` +
+                            "with syntactically valid YAML (e.g. a `bays:` entry missing `name:`), or when a bay is " +
+                            "parked locally but not (yet) declared in garaje.yaml. Sync the missing bay(s) " +
+                            "(`garaje sync`) and re-run upgrade, or fix garaje.yaml; if you really mean to drop " +
+                            "them, run `garaje park` yourself, then re-run upgrade.",
+                    };
+                }
+            }
+            else if (isEmptyToolchain(toolchain) && !isEmptyToolchain(committed)) {
+                // Backstop: the committed artifact predates the `# bays:` provenance
+                // line, so there is nothing to diff against — fall back to the
+                // coarser "would this regeneration go empty" check.
+                return {
+                    action: "fail",
+                    message: `regenerating pi/toolchain/ from garaje.yaml would produce an EMPTY artifact, but the ` +
+                        `committed one is not — refusing to overwrite it. This can happen even with syntactically ` +
+                        "valid YAML (e.g. a `bays:` entry missing `name:`). Check garaje.yaml; if you really want to " +
+                        "shrink to zero bays, run `garaje park` yourself, then re-run upgrade.",
+                };
+            }
+        }
+        return { action: "write", recipes };
+    }
+    if (!committed) {
+        return {
+            action: "fail",
+            message: `pi/toolchain/ is missing and cannot be derived — ${describeUnparkedBays(root, unparked)}. ` +
+                `Re-run upgrade once fixed.`,
+        };
+    }
+    return {
+        action: "leave",
+        message: `${describeUnparkedBays(root, unparked)} — pi/toolchain/ left as committed`,
+    };
+}
 /** `garaje upgrade [--to <version>]` — bump the base + CLI pins and classify. */
 export function runUpgrade(root, args) {
     const settingsPath = join(root, ".pi/settings.json");
@@ -67,23 +268,76 @@ export function runUpgrade(root, args) {
         if (t)
             rmSync(t.replace(/\/package$/, ""), { recursive: true, force: true });
     }
-    // Rewrite the three committed pins.
-    writeFileSync(settingsPath, rewriteBasePin(settingsText, to));
+    // Rewrite the committed pins, then re-materialize the framework-managed files
+    // and merge the framework-default packages. Without the latter two, a
+    // framework change reaches NEW garajes only. Both the rematerialize and the
+    // settings merge are declined in the framework monorepo (base pinned by
+    // relative path, not npm:) — one guard, one meaning: "this is not a
+    // scaffolded garaje, so upgrade does nothing structural to it." The
+    // version-pin rewrites above/below still run in both cases.
+    const scaffolded = isScaffoldedGaraje(root);
+    // Decide the pi/toolchain/ outcome BEFORE any write below runs. A
+    // re-materialized pi/Dockerfile's `COPY toolchain/` step must never be
+    // written on a promise the toolchain regen can't keep — a corrupt recipe or
+    // an undeliverable artifact has to fail upgrade OUTRIGHT, before pins,
+    // pi/Dockerfile, or anything else is touched, so a failed upgrade leaves the
+    // garaje exactly as it was (see planToolchain). Declined for the monorepo,
+    // same guard as rematerialize: pi/Dockerfile there is hand-maintained, not
+    // re-materialized, so upgrade has no reason to touch its sibling artifact.
+    const toolchainPlan = scaffolded ? planToolchain(root) : { action: "skip" };
+    if (toolchainPlan.action === "fail") {
+        process.stderr.write(`garaje upgrade: ${toolchainPlan.message}\n`);
+        return 1;
+    }
+    const rewritten = rewriteBasePin(settingsText, to);
+    const merged = scaffolded ? mergeSettingsPackages(rewritten, DEFAULT_PACKAGES) : rewritten;
+    writeFileSync(settingsPath, merged);
     if (existsSync(dockerfilePath)) {
         writeFileSync(dockerfilePath, rewriteDockerfileCliPin(readFileSync(dockerfilePath, "utf8"), to));
     }
     writeFileSync(versionPath, `${to}\n`);
+    const managed = rematerialize(root, TEMPLATES, to);
+    // Apply the toolchain decision made above. "write" (co-covers both "every
+    // manifest bay synced" and "manifest declares none" — an empty recipe list
+    // yields the valid empty artifact) and "leave" (bay(s) unsynced but the
+    // committed artifact still stands, untouched) are the only two live cases
+    // here; "fail" already returned above, and "skip" is the monorepo no-op.
+    if (toolchainPlan.action === "write") {
+        writeToolchainArtifact(root, toolchainPlan.recipes);
+    }
+    // Scaffold .pi-lens.json if this garaje predates it (create-only — never
+    // clobber a customized one).
+    const piLensCreated = scaffoldPiLensConfig(root, TEMPLATES);
     // Report.
     process.stdout.write(`garaje upgrade: pins bumped ${from ?? "(local)"} -> ${to}\n`);
     for (const f of findings) {
         process.stdout.write(`  ${f.kind.toUpperCase()} [${f.resource}] ${f.name}: ${f.detail}\n`);
     }
+    for (const m of managed) {
+        process.stdout.write(`  managed ${m.file.padEnd(24)}${m.changed ? "rewritten" : "unchanged"}\n`);
+    }
+    if (toolchainPlan.action === "write") {
+        process.stdout.write(`  managed pi/toolchain/           regenerated from ${toolchainPlan.recipes.length} bay recipe(s)\n`);
+    }
+    else if (toolchainPlan.action === "leave") {
+        process.stdout.write(`  managed pi/toolchain/           left as-is (${toolchainPlan.message})\n`);
+    }
+    if (piLensCreated) {
+        process.stdout.write(`  scaffold .pi-lens.json          created (was missing; template defaults)\n`);
+    }
+    const addedPkgs = scaffolded ? missingDefaultPackages(settingsText, DEFAULT_PACKAGES) : [];
+    for (const p of addedPkgs) {
+        process.stdout.write(`  merged  .pi/settings.json      + ${p}\n`);
+    }
     const nextHeader = classified
         ? `  # review the ${findings.length} override(s) above, then:\n`
         : `  # classification was skipped (base trees unavailable) — re-run this after the ` +
             `packages are published to check for shadow/orphan overrides, then:\n`;
-    process.stdout.write(`\nNext:\n${nextHeader}` +
-        `  npm i -g garaje@${to}\n  garaje up --build\n  git add -A && git commit -m 'upgrade garaje to ${to}'\n`);
+    process.stdout.write(`\nNote: this upgrade ran using the CLI you already have installed — install ` +
+        `garaje@${to} globally BEFORE running \`garaje upgrade\`, not after (the ` +
+        `version that performs the upgrade is whatever is already on PATH).\n` +
+        `\nNext:\n${nextHeader}` +
+        `  garaje up --build\n  garaje sync\n  git add -A && git commit -m 'upgrade garaje to ${to}'\n`);
     return findings.length > 0 ? 1 : 0;
 }
 /** Latest published `garaje` version, or undefined (pre-publish / offline). */

package/dist/upgrade/managed.js

@@ -0,0 +1,117 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { basePinSource } from "./pins.js";
+import { driverContext, getDriver } from "../driver/index.js";
+/**
+ * Files the FRAMEWORK owns end-to-end. They are already write-protected from the
+ * agent, and — since the toolchain moved into the generated pi/toolchain/ —
+ * they carry no per-garaje content at all. That is what makes overwriting them
+ * safe, and what lets a framework change reach a garaje that already exists.
+ *
+ * .pi/settings.json is deliberately NOT here: it is garaje-owned (model,
+ * provider, their own packages) and is MERGED instead. See mergeSettingsPackages.
+ *
+ * The compose file(s) are NOT hardcoded here: compose filenames are
+ * driver-internal knowledge (north-star §4.1 — the runtime-driver seam is the
+ * only dialect layers above codegen may speak). We ask the driver for its own
+ * frameworkOwnedFiles() instead — NOT requiredFiles(), which only promises a
+ * file must exist (doctor), not that it is safe to overwrite — so a future
+ * k8s driver (Phase 8) gets its own framework-owned manifests re-materialized
+ * for free, without also clobbering a manifest a dev is meant to customize,
+ * and no compose literal leaks above the seam.
+ */
+export function managedFiles(root) {
+    const driver = getDriver(driverContext(root));
+    return ["pi/Dockerfile", "pi/entrypoint.sh", ...driver.frameworkOwnedFiles()];
+}
+/** pi packages every garaje should have. Merged into .pi/settings.json, never
+ *  imposed over the garaje's own choices. */
+export const DEFAULT_PACKAGES = ["npm:pi-lens"];
+/** A package spec without its version: npm:pi-lens@1.2.3 -> npm:pi-lens. The
+ *  leading @ of a scoped name (npm:@garaje/base) is not a version separator —
+ *  only an @ after the last / (i.e. after the scope) can introduce a version. */
+export function packageName(spec) {
+    const at = spec.lastIndexOf("@");
+    const boundary = Math.max(spec.indexOf(":"), spec.lastIndexOf("/"));
+    return at > boundary ? spec.slice(0, at) : spec;
+}
+/** Names already present in settingsText's package list (by packageName, not
+ *  exact spec — a default already pinned to a version still counts). */
+function presentPackageNames(settingsText) {
+    const data = JSON.parse(settingsText);
+    const packages = Array.isArray(data.packages) ? data.packages : [];
+    return new Set(packages
+        .map((p) => (typeof p === "string" ? p : p?.source))
+        .filter((s) => typeof s === "string")
+        .map(packageName));
+}
+/** Which of `defaults` are absent from settingsText, matched by package name
+ *  the same way mergeSettingsPackages decides what to add — so a stdout
+ *  report of "what got added" can never disagree with what actually did. */
+export function missingDefaultPackages(settingsText, defaults) {
+    const present = presentPackageNames(settingsText);
+    return defaults.filter((def) => !present.has(packageName(def)));
+}
+/** Add any missing framework-default packages. The garaje's model, provider,
+ *  theme and own packages are untouched, and a default it already pinned to a
+ *  version is left at that version. */
+export function mergeSettingsPackages(settingsText, defaults) {
+    const data = JSON.parse(settingsText);
+    const packages = Array.isArray(data.packages) ? [...data.packages] : [];
+    for (const def of missingDefaultPackages(settingsText, defaults)) {
+        packages.push(def);
+    }
+    data.packages = packages;
+    return `${JSON.stringify(data, null, 2)}\n`;
+}
+/** True for a scaffolded garaje (base pinned from npm), false for the framework
+ *  monorepo (base pinned by relative path), whose root pi/Dockerfile legitimately
+ *  differs from the template and must never be clobbered. Also gates the
+ *  .pi/settings.json package merge: the monorepo's own settings.json must not
+ *  be touched either. */
+export function isScaffoldedGaraje(root) {
+    const settings = join(root, ".pi", "settings.json");
+    if (!existsSync(settings))
+        return false;
+    const source = basePinSource(readFileSync(settings, "utf8"));
+    return Boolean(source?.startsWith("npm:"));
+}
+/** Scaffold `.pi-lens.json` from the template if it is missing. It is
+ *  garaje-owned once it exists (a garaje may have customized its ignore
+ *  list), so this only ever CREATES — never overwrites. Declined for the
+ *  monorepo, same guard as rematerialize/mergeSettingsPackages: this repo is
+ *  not a scaffolded garaje. Returns true iff the file was created. */
+export function scaffoldPiLensConfig(root, templatesDir) {
+    if (!isScaffoldedGaraje(root))
+        return false;
+    const dest = join(root, ".pi-lens.json");
+    if (existsSync(dest))
+        return false;
+    const template = join(templatesDir, ".pi-lens.json");
+    if (!existsSync(template))
+        return false;
+    writeFileSync(dest, readFileSync(template, "utf8"));
+    return true;
+}
+/** Rewrite every framework-managed file from the CLI's bundled templates.
+ *  Returns one outcome per file; an empty array means we declined (monorepo). */
+export function rematerialize(root, templatesDir, version) {
+    if (!isScaffoldedGaraje(root))
+        return [];
+    const out = [];
+    for (const rel of managedFiles(root)) {
+        const templatePath = join(templatesDir, rel);
+        if (!existsSync(templatePath))
+            continue;
+        const want = readFileSync(templatePath, "utf8").split("__GARAJE_VERSION__").join(version);
+        const dest = join(root, rel);
+        const have = existsSync(dest) ? readFileSync(dest, "utf8") : undefined;
+        if (have === want) {
+            out.push({ file: rel, changed: false });
+            continue;
+        }
+        writeFileSync(dest, want);
+        out.push({ file: rel, changed: true });
+    }
+    return out;
+}

package/dist/upgrade/pins.js

@@ -12,7 +12,9 @@ export function currentBaseVersion(settingsText) {
     return m ? m[1] : undefined;
 }
 /** The @garaje/base package source pinned in .pi/settings.json: an `npm:` spec
- *  in a scaffolded garaje, a relative path in the framework monorepo. */
+ *  in a scaffolded garaje, a relative path in the framework monorepo. Returns
+ *  undefined if no package matches — the caller must treat that as "not
+ *  pinned", not fall back to an unrelated package. */
 export function basePinSource(settingsText) {
     let sources;
     try {
@@ -24,5 +26,5 @@ export function basePinSource(settingsText) {
     catch {
         return undefined;
     }
-    return sources.find((s) => /@garaje\/base|packages\/base/.test(s)) ?? sources[0];
+    return sources.find((s) => /@garaje\/base|packages\/base/.test(s));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "garaje",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/templates/.env.example

@@ -1,3 +1,15 @@
-# Copy to .env and fill in to use API-key auth for the pi container.
-# Alternatively leave blank and run `/login` inside pi (persisted via the pi-config volume).
+# Copy to .env, then fill in one provider key.
+#
+# This file is the garaje's ONLY credential surface: compose forwards .env into
+# the pi container (env_file). A variable exported in your shell does NOT reach
+# the agent.
+
+# The scaffolded provider. Create a key at https://console.mixlayer.com/app/api-keys
+MIXLAYER_API_KEY=
+
+# Only needed if you switch .pi/settings.json back to defaultProvider "anthropic".
 ANTHROPIC_API_KEY=
+
+# NOTE: a key stored by `/login` inside pi is written to ~/.pi/agent/auth.json on
+# the pi-config volume, survives rebuilds, and TAKES PRECEDENCE over this file.
+# `garaje doctor` warns when that file exists.

package/templates/.pi/settings.json

@@ -1,13 +1,15 @@
 {
   "$schema": "https://pi.dev/schemas/settings.json",
-  "defaultProvider": "anthropic",
-  "defaultModel": "claude-opus-4-8",
+  "defaultProvider": "mixlayer",
+  "defaultModel": "qwen/qwen3.5-397b-a17b",
   "defaultThinkingLevel": "medium",
   "theme": "dark",
   "packages": [
     {
       "source": "__BASE_PIN__",
       "extensions": ["extensions/**", "!extensions/session-name.ts"]
-    }
+    },
+    "npm:pi-mixlayer@0.4.0",
+    "npm:pi-lens"
   ]
 }

package/templates/.pi-lens.json

@@ -0,0 +1,11 @@
+{
+  "ignore": [
+    "sessions/**",
+    "scratch/**",
+    ".pi/**",
+    "bays/*/node_modules/**",
+    "bays/*/tmp/**",
+    "bays/*/log/**",
+    "bays/*/vendor/**"
+  ]
+}

package/templates/compose.framework.yaml

@@ -14,8 +14,23 @@ services:
       - ./:/workspace
       - pi-config:/root/.pi/agent
       - garaje-auth:/root/.garaje-auth
+      # pi-side project dependencies (gems, node_modules) for the parked bays,
+      # installed by `garaje sync`. Names NO bay on purpose: the framework layer
+      # stays codebase-agnostic, so the framework/bays compose split that carries
+      # containment (bays scope excludes this file entirely) is untouched.
+      - pi-deps:/garaje/deps
+    # Provider credentials come from .env — a garaje's single credential surface.
+    # Any pi provider extension (pi-mixlayer, pi-openai, …) resolves its key from
+    # the container environment, so adding a provider needs no framework release.
+    # A shell-exported variable does NOT reach the agent; put it in .env.
+    # required:false keeps `garaje up` working before .env exists.
+    env_file:
+      - path: .env
+        required: false
     environment:
-      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      # Framework-owned. `environment:` overrides `env_file`, so a stray .env
+      # entry cannot hijack any of these.
+      #
       # The agent's ONLY docker endpoint: the whitelisting proxy below.
       # The raw socket is never mounted here (north-star §5.1 layer 1).
       - DOCKER_HOST=tcp://docker-proxy:2375
@@ -26,6 +41,10 @@ services:
       # bind mounts use ${GARAJE_HOST_ROOT:-.} because bind sources resolve
       # on the daemon (host) side even when compose runs in-container.
       - GARAJE_HOST_ROOT=${PWD:-}
+      # pi/Dockerfile sets this via ENV, which env_file (unlike environment:)
+      # does NOT outrank — restated here so a stray .env line cannot redirect
+      # the agent's gh config directory (and its git/gh credential wiring).
+      - GH_CONFIG_DIR=/root/.garaje-auth/gh
     depends_on:
       - docker-proxy
 
@@ -58,3 +77,4 @@ services:
 volumes:
   pi-config:
   garaje-auth:
+  pi-deps:

package/templates/gitignore

@@ -24,3 +24,7 @@ bays/*
 
 # Dev-local garaje overrides (per-bay bind-mount paths, personal settings).
 garaje.local.yaml
+
+# Pi packages installed into project scope by `pi install -l`. The package
+# manifest lives in the committed .pi/settings.json; these are its artifacts.
+/.pi/npm/

package/templates/pi/Dockerfile

@@ -21,6 +21,54 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     && apt-get update && apt-get install -y --no-install-recommends gh docker-ce-cli docker-buildx-plugin docker-compose-plugin \
     && rm -rf /var/lib/apt/lists/*
 
+# --- Per-bay toolchains -------------------------------------------------------
+# GENERATED by `garaje park` from every parked bay's recipe.yaml — the same
+# declaration the bay images build from. The agent's container therefore carries
+# exactly the runtimes of the code it edits, which is what lets pi-lens spawn a
+# language server and a linter per bay.
+#
+# These layers sit BEFORE the pi/npm layers on purpose. Docker invalidates every
+# layer after a changed one; Ruby compiles from source under mise (~5-10 min).
+# A PI_VERSION bump is frequent and must NOT recompile Ruby. Parking a new bay
+# is rare, and may legitimately pay that recompile cost.
+COPY toolchain/ /tmp/toolchain/
+
+# The apt list is a bare, newline-separated file (no comments — xargs would read
+# a '#' line as a package name). Empty for a garaje with no bays, hence the -s test.
+RUN if [ -s /tmp/toolchain/apt-packages.txt ]; then \
+        apt-get update \
+        && xargs -a /tmp/toolchain/apt-packages.txt \
+             apt-get install -y --no-install-recommends \
+        && rm -rf /var/lib/apt/lists/*; \
+    fi
+
+# mise in SHIMS mode. A shim resolves its tool's version from the CALLING
+# directory — and pi-lens spawns language servers with cwd = the bay root. So
+# each bay's own .ruby-version selects its runtime with zero integration code,
+# and two bays on different Ruby versions each get the right one.
+ENV MISE_DATA_DIR=/root/.local/share/mise
+ENV PATH=/root/.local/share/mise/shims:/root/.local/bin:$PATH
+
+# Pinned for build reproducibility: an unpinned installer means two teammates
+# who build a month apart get different mise versions — not theoretical, this
+# exact version's install already warns "precompiled ruby will be the default
+# in 2026.8.0". Bump deliberately, matching PI_VERSION's own pinning discipline.
+ARG MISE_VERSION=2026.7.5
+RUN export MISE_VERSION="${MISE_VERSION}" \
+    && curl -fsSL https://mise.run | sh \
+    && mkdir -p /root/.config/mise \
+    && cp /tmp/toolchain/mise.toml /root/.config/mise/config.toml \
+    && mise install --yes \
+    && mise reshim \
+    && rm -rf /tmp/toolchain
+
+# pi-side project dependencies live on the pi-deps volume (compose.framework.yaml).
+# ONE shared BUNDLE_PATH serves EVERY bay: bundler namespaces gems by Ruby ABI
+# directory and activates strictly from the calling project's Gemfile.lock. So
+# `bundle exec rubocop` in bays/rtfm gets rtfm's pinned cops and cannot see
+# stacey's gems. Verified against ruby:3.4-slim — see the design spec §2.
+ENV BUNDLE_PATH=/garaje/deps/bundle
+
 # Pi version is pinned in pi/PI_VERSION so a pi bump is a one-file diff
 # teammates pick up on `git pull && garaje up --build`. Bring the file in first
 # as its own layer so editing it busts the cache for the npm install layer

package/templates/pi/toolchain/mise.toml

@@ -0,0 +1,14 @@
+# GENERATED by `garaje park` from bays/*/recipe.yaml. Do not edit by hand.
+#
+# The union of every parked bay's declared runtimes. mise installs all of
+# them; each bay's own .ruby-version / .node-version then selects which one
+# applies inside that bay. pi-lens spawns language servers with cwd = the bay
+# root, so the mise shim on PATH resolves the right version with no glue.
+#
+# bays: (none)
+
+[tools]
+
+[settings]
+# Honor each bay's .ruby-version / .node-version (they already ship them).
+idiomatic_version_file_enable_tools = ["node", "ruby"]