garaje 0.1.0

package/dist/sessions/collect.js

@@ -0,0 +1,86 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+const PREVIEW_LEN = 60;
+function clean(text) {
+    return text.replace(/[\r\n]+/g, " ").trim().split(/\s+/).join(" ");
+}
+/** Parse one .jsonl session file into a row, or null if it isn't a session. */
+function parseSession(path) {
+    let lines;
+    try {
+        lines = readFileSync(path, "utf8").split(/\r?\n/);
+    }
+    catch {
+        return null;
+    }
+    let header;
+    try {
+        header = JSON.parse(lines[0] ?? "");
+    }
+    catch {
+        return null;
+    }
+    if (!header || header.type !== "session")
+        return null;
+    let messages = 0;
+    let cost = 0;
+    let preview = "";
+    for (const line of lines.slice(1)) {
+        if (!line)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (obj?.type !== "message")
+            continue;
+        messages += 1;
+        const msg = obj.message ?? {};
+        if (msg.role === "user" && !preview) {
+            const content = msg.content;
+            if (typeof content === "string")
+                preview = content;
+            else if (Array.isArray(content)) {
+                const block = content.find((b) => b && b.type === "text");
+                if (block)
+                    preview = block.text ?? "";
+            }
+        }
+        if (msg.role === "assistant") {
+            cost += Number(msg.usage?.cost?.total ?? 0) || 0;
+        }
+    }
+    const mtime = statSync(path).mtimeMs;
+    return {
+        id: header.id ?? "",
+        last: new Date(mtime).toISOString().replace(/\.\d{3}Z$/, "Z"),
+        messages,
+        cost,
+        preview: clean(preview).slice(0, PREVIEW_LEN),
+        mtime,
+    };
+}
+// All parseable sessions under <root>/sessions/*/*.jsonl, newest-first.
+export function collectSessions(root) {
+    const dir = join(root, "sessions");
+    if (!existsSync(dir))
+        return [];
+    const rows = [];
+    for (const sub of readdirSync(dir, { withFileTypes: true })) {
+        if (!sub.isDirectory())
+            continue;
+        const subPath = join(dir, sub.name);
+        for (const f of readdirSync(subPath)) {
+            if (!f.endsWith(".jsonl"))
+                continue;
+            const parsed = parseSession(join(subPath, f));
+            if (parsed)
+                rows.push(parsed);
+        }
+    }
+    rows.sort((a, b) => b.mtime - a.mtime);
+    return rows.map(({ mtime, ...row }) => row);
+}

package/dist/sessions/render.js

@@ -0,0 +1,24 @@
+const MAX_ROWS = 100;
+/** Render sessions/INDEX.md. Pure: caller supplies rows + the generated-at stamp. */
+export function renderIndex(rows, generatedAt) {
+    const lines = [
+        "# Sessions index",
+        "",
+        `_Auto-generated by \`garaje sessions-index\` at ${generatedAt}._ Regenerated on every \`garaje up\`.`,
+        "",
+        `${rows.length} session(s) total. Showing newest ${Math.min(rows.length, MAX_ROWS)}.`,
+        "",
+        "Resume by short id with `garaje pi --session <id>`, or pick interactively with `garaje pi -r`.",
+        "",
+        "| last activity | id | msgs | cost | preview |",
+        "|---|---|---:|---:|---|",
+    ];
+    for (const s of rows.slice(0, MAX_ROWS)) {
+        const shortId = s.id ? s.id.slice(0, 8) : "?";
+        const preview = (s.preview || "_(no user messages yet)_").replace(/\|/g, "\\|");
+        const cost = s.cost ? `$${s.cost.toFixed(4)}` : "—";
+        lines.push(`| ${s.last} | \`${shortId}\` | ${s.messages} | ${cost} | ${preview} |`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}

package/dist/sessions/run.js

@@ -0,0 +1,14 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { collectSessions } from "./collect.js";
+import { renderIndex } from "./render.js";
+/** Regenerate <root>/sessions/INDEX.md. Safe to re-run; idempotent. */
+export function runSessionsIndex(root) {
+    const dir = join(root, "sessions");
+    mkdirSync(dir, { recursive: true });
+    const rows = collectSessions(root);
+    const generatedAt = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    writeFileSync(join(dir, "INDEX.md"), renderIndex(rows, generatedAt));
+    process.stderr.write(`sessions-index: wrote sessions/INDEX.md (${rows.length} sessions)\n`);
+    return { code: 0 };
+}

package/dist/upgrade/classify.js

@@ -0,0 +1,137 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/** name (relative, forward-slashed) -> file content, for *.md under dir. */
+function scanMd(dir) {
+    const out = new Map();
+    const walk = (d, base = "") => {
+        let entries;
+        try {
+            entries = readdirSync(d, { withFileTypes: true });
+        }
+        catch {
+            return; // missing dir -> no resources
+        }
+        for (const e of entries) {
+            const rel = base ? `${base}/${e.name}` : e.name;
+            if (e.isDirectory())
+                walk(join(d, e.name), rel);
+            else if (e.isFile() && e.name.endsWith(".md"))
+                out.set(rel, readFileSync(join(d, e.name), "utf8"));
+        }
+    };
+    walk(dir);
+    return out;
+}
+function readJsonObj(file) {
+    try {
+        const v = JSON.parse(readFileSync(file, "utf8"));
+        return v && typeof v === "object" ? v : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** Named-file resources (rules, agents): shadow = local hides a changed/added
+ *  base file; orphan = local file whose base counterpart was removed. */
+function classifyNamedFiles(oldDir, newDir, localDir, resource) {
+    const oldF = scanMd(oldDir);
+    const newF = scanMd(newDir);
+    const local = new Set(scanMd(localDir).keys());
+    const out = [];
+    for (const [name, newText] of newF) {
+        const changed = !oldF.has(name) || oldF.get(name) !== newText;
+        if (changed && local.has(name)) {
+            const verb = oldF.has(name) ? "changed" : "added";
+            out.push({
+                kind: "shadow",
+                resource,
+                name,
+                detail: `base ${verb} ${resource} '${name}', but a local override shadows it — the update is hidden until you reconcile`,
+            });
+        }
+    }
+    for (const name of local) {
+        if (oldF.has(name) && !newF.has(name)) {
+            out.push({
+                kind: "orphan",
+                resource,
+                name,
+                detail: `local ${resource} '${name}' overrode a base file removed in the new version — the override is now dead`,
+            });
+        }
+    }
+    return out;
+}
+/** presets.json: keys, not files. Shadow = local key hides a changed/added base
+ *  key; orphan = local key whose base key was removed. */
+function classifyPresets(oldFile, newFile, localFile) {
+    const oldK = readJsonObj(oldFile);
+    const newK = readJsonObj(newFile);
+    const local = readJsonObj(localFile);
+    const out = [];
+    for (const [k, v] of Object.entries(newK)) {
+        const changed = !(k in oldK) || JSON.stringify(oldK[k]) !== JSON.stringify(v);
+        if (changed && k in local) {
+            const verb = k in oldK ? "changed" : "added";
+            out.push({
+                kind: "shadow",
+                resource: "preset",
+                name: k,
+                detail: `base ${verb} preset '${k}', but a local preset shadows it`,
+            });
+        }
+    }
+    for (const k of Object.keys(local)) {
+        if (k in oldK && !(k in newK)) {
+            out.push({
+                kind: "orphan",
+                resource: "preset",
+                name: k,
+                detail: `local preset '${k}' overrode a base preset removed in the new version — dead override`,
+            });
+        }
+    }
+    return out;
+}
+/** Pull the extension basenames a garaje excludes via `!extensions/<x>` in its
+ *  base-pin `extensions` filter array. */
+export function extractExtensionFilters(settingsFile) {
+    const s = readJsonObj(settingsFile);
+    const pkgs = Array.isArray(s.packages) ? s.packages : [];
+    const out = [];
+    for (const p of pkgs) {
+        if (p && typeof p === "object" && Array.isArray(p.extensions)) {
+            for (const g of p.extensions) {
+                if (typeof g === "string" && g.startsWith("!extensions/")) {
+                    out.push(g.slice("!extensions/".length));
+                }
+            }
+        }
+    }
+    return out;
+}
+/** A `!`-filter orphans when its target extension is gone in the new base — the
+ *  intended exclusion silently stops applying, so a base extension may now load. */
+function classifyFilters(newExtDir, filters) {
+    const out = [];
+    for (const f of filters) {
+        if (!existsSync(join(newExtDir, f))) {
+            out.push({
+                kind: "orphan",
+                resource: "filter",
+                name: f,
+                detail: `.pi/settings.json filters out base extension '${f}', which the new version renamed or removed — the exclusion no longer applies`,
+            });
+        }
+    }
+    return out;
+}
+/** Diff old-base vs new-base against the garaje's small local override layer. */
+export function classify(oldBaseDir, newBaseDir, cwd) {
+    return [
+        ...classifyNamedFiles(join(oldBaseDir, "rules"), join(newBaseDir, "rules"), join(cwd, ".agent/rules"), "rule"),
+        ...classifyNamedFiles(join(oldBaseDir, "agents"), join(newBaseDir, "agents"), join(cwd, ".pi/agents"), "agent"),
+        ...classifyPresets(join(oldBaseDir, "presets.json"), join(newBaseDir, "presets.json"), join(cwd, ".pi/presets.json")),
+        ...classifyFilters(join(newBaseDir, "extensions"), extractExtensionFilters(join(cwd, ".pi/settings.json"))),
+    ];
+}

package/dist/upgrade/index.js

@@ -0,0 +1,94 @@
+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 { classify } from "./classify.js";
+import { currentBaseVersion, rewriteBasePin, rewriteDockerfileCliPin } from "./pins.js";
+/** 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) {
+    const dir = mkdtempSync(join(tmpdir(), `garaje-base-${version}-`));
+    const packed = spawnSync("npm", ["pack", `@garaje/base@${version}`, "--pack-destination", dir], {
+        stdio: "ignore",
+    });
+    if (packed.status !== 0) {
+        rmSync(dir, { recursive: true, force: true });
+        return undefined;
+    }
+    const tgz = spawnSync("sh", ["-c", `ls "${dir}"/*.tgz`], { encoding: "utf8" }).stdout.trim();
+    const untar = spawnSync("tar", ["-xzf", tgz, "-C", dir], { stdio: "ignore" });
+    if (untar.status !== 0) {
+        rmSync(dir, { recursive: true, force: true });
+        return undefined;
+    }
+    return join(dir, "package"); // npm tarballs root everything under package/
+}
+function parseTo(args) {
+    const i = args.indexOf("--to");
+    if (i >= 0)
+        return args[i + 1];
+    return undefined;
+}
+/** `garaje upgrade [--to <version>]` — bump the base + CLI pins and classify. */
+export function runUpgrade(root, args) {
+    const settingsPath = join(root, ".pi/settings.json");
+    const dockerfilePath = join(root, "pi/Dockerfile");
+    const versionPath = join(root, ".garaje-version");
+    if (!existsSync(settingsPath)) {
+        process.stderr.write("garaje upgrade: no .pi/settings.json — run inside a garaje\n");
+        return 1;
+    }
+    const to = parseTo(args) ?? resolveLatest();
+    if (!to) {
+        process.stderr.write("garaje upgrade: could not resolve a target version (pass --to <version>)\n");
+        return 1;
+    }
+    if (!/^[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.]+)?$/.test(to)) {
+        process.stderr.write(`garaje upgrade: invalid --to target '${to}' — expected a semver version\n`);
+        return 1;
+    }
+    const settingsText = readFileSync(settingsPath, "utf8");
+    const from = currentBaseVersion(settingsText);
+    // Classify old vs new base against the local override layer, if both trees resolve.
+    let findings = [];
+    let classified = false;
+    const newTree = fetchBaseTree(to);
+    const oldTree = from ? fetchBaseTree(from) : undefined;
+    if (newTree && oldTree) {
+        findings = classify(oldTree, newTree, root);
+        classified = true;
+    }
+    else {
+        process.stderr.write(`garaje upgrade: could not fetch @garaje/base@${from ?? "?"}/${to} to classify — ` +
+            `skipping the shadow/orphan check (run it after the packages are published)\n`);
+    }
+    // Always clean up any temp tree we fetched (the tree path ends in /package).
+    for (const t of [oldTree, newTree]) {
+        if (t)
+            rmSync(t.replace(/\/package$/, ""), { recursive: true, force: true });
+    }
+    // Rewrite the three committed pins.
+    writeFileSync(settingsPath, rewriteBasePin(settingsText, to));
+    if (existsSync(dockerfilePath)) {
+        writeFileSync(dockerfilePath, rewriteDockerfileCliPin(readFileSync(dockerfilePath, "utf8"), to));
+    }
+    writeFileSync(versionPath, `${to}\n`);
+    // 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`);
+    }
+    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`);
+    return findings.length > 0 ? 1 : 0;
+}
+/** Latest published `garaje` version, or undefined (pre-publish / offline). */
+function resolveLatest() {
+    const r = spawnSync("npm", ["view", "garaje", "version"], { encoding: "utf8" });
+    const v = (r.stdout || "").trim();
+    return r.status === 0 && v ? v : undefined;
+}

package/dist/upgrade/pins.js

@@ -0,0 +1,13 @@
+/** Replace the pinned @garaje/base npm version; leave a local-path source alone. */
+export function rewriteBasePin(settingsText, newVersion) {
+    return settingsText.replace(/(npm:@garaje\/base@)[0-9A-Za-z.\-]+/g, `$1${newVersion}`);
+}
+/** Replace the `garaje@<v>` CLI install literal in a scaffolded pi/Dockerfile. */
+export function rewriteDockerfileCliPin(dockerfileText, newVersion) {
+    return dockerfileText.replace(/(garaje@)[0-9A-Za-z.\-]+/g, `$1${newVersion}`);
+}
+/** The version currently pinned for @garaje/base, or undefined for a local path. */
+export function currentBaseVersion(settingsText) {
+    const m = settingsText.match(/npm:@garaje\/base@([0-9A-Za-z.\-]+)/);
+    return m ? m[1] : undefined;
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "garaje",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/teammates-work/garaje.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "garaje": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "yaml": "^2.4.0"
+  }
+}

package/templates/.agent/README.md

@@ -0,0 +1,17 @@
+# `.agent/` — local override layer
+
+This directory is the LOCAL override layer over the `@garaje/base` framework
+substrate. The substrate itself — the extension bundle, base rules, canonical
+role prompts, and generated presets/agents — ships in the `@garaje/base` pi
+package. Consumption is declarative: `.pi/settings.json` pins `@garaje/base` as
+a `packages` source, and pi merges its content with what's here at load time.
+
+`.agent/rules/*.md` are local overrides layered over `@garaje/base`'s `rules/`:
+a file here whose name matches a base rule file shadows it entirely (local
+wins), and a file here with a new name is layered in additively. `commands/`
+and `skills/` are for local, repo-specific slash commands and pi skills that
+supplement the base bundle; both start empty.
+
+`AGENTS.md` at the repo root is always loaded first; base rules and local rules
+in `.agent/rules/` layer on top, merged in filename order with local overrides
+winning on name collisions.

package/templates/.env.example

@@ -0,0 +1,3 @@
+# 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).
+ANTHROPIC_API_KEY=

package/templates/.garaje-version

@@ -0,0 +1 @@
+__GARAJE_VERSION__

package/templates/.pi/README.md

@@ -0,0 +1,17 @@
+# `.pi/` — project settings + optional local overrides
+
+`settings.json` is this garaje's pi configuration, including the `packages`
+pin that consumes `@garaje/base` — the extension bundle, rules, prompts/roles,
+and generated presets/agents all live in that package. Hand-edit
+`settings.json` directly; it's committed as-is.
+
+This directory can optionally hold project-local overrides that merge over the
+base package's at load time:
+
+- `presets.json` — project-only presets, merged with the base package's
+  (consumed by the `preset` extension, `/preset <name>`).
+- `agents/<role>.md` — project-only subagent definitions, merged with the base
+  package's `agents/` (consumed by the `subagent` extension).
+
+Neither is generated — they're empty unless this garaje needs a preset or role
+that doesn't belong in the shared `@garaje/base` package.

package/templates/.pi/settings.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://pi.dev/schemas/settings.json",
+  "defaultProvider": "anthropic",
+  "defaultModel": "claude-opus-4-8",
+  "defaultThinkingLevel": "medium",
+  "theme": "dark",
+  "packages": [
+    {
+      "source": "__BASE_PIN__",
+      "extensions": ["extensions/**", "!extensions/session-name.ts"]
+    }
+  ]
+}

package/templates/AGENTS.md

@@ -0,0 +1,38 @@
+# Garaje workspace
+
+You are running inside the `pi` container of a docker-compose project — a
+**garaje**. Your working directory `/workspace` is the repo root, bind-mounted
+read-write from the host. Editing a file here changes it on the host and inside
+the running containers simultaneously.
+
+A garaje parks one or more **codebases** into `bays/` and runs them for
+agentic dev. Each parked codebase declares how it runs in its own `recipe.yaml`.
+
+## Agent contract
+
+This file is the canonical entry point. Layered guidance lives in
+[`.agent/rules/`](.agent/rules/) and in the pinned `@garaje/base` package's
+rules; they merge alphabetically with local rules winning on name collisions.
+See [`.agent/README.md`](.agent/README.md) for the directory contract.
+
+## Layout
+
+- `bays/<name>/` — parked codebases, materialized by `garaje sync` from
+  `garaje.yaml`. Gitignored; each is its own git checkout. This is where the
+  application code you work on lives.
+- `compose.framework.yaml` — the pi service itself. **You cannot edit this**
+  (protected). `docker-compose.yml` is likewise protected.
+- `compose.bays.yaml` — generated from each bay's `recipe.yaml` by
+  `garaje park`; generated + committed. Don't hand-edit it — change the recipe.
+- `.agent/` — the local override layer (rules, commands, skills) over the
+  `@garaje/base` package.
+- `scratch/` — host-shared dropbox for screenshots, logs, paste-ins (gitignored).
+- `sessions/` — pi session transcripts, host-visible (gitignored).
+
+## Working on a parked codebase
+
+Each bay carries a `recipe.yaml` describing how it runs (toolchain, app
+processes, backing services, env, secrets). After editing a bay's source, the
+services live-reload per that codebase's own dev setup; prove a change by
+hitting the affected process (e.g. `curl` the app's health endpoint) from
+inside this container over the compose network.

package/templates/compose.framework.yaml

@@ -0,0 +1,60 @@
+# Framework-owned. Defines the pi agent container itself + its docker proxy.
+#
+# WRITE-PROTECTED: the agent cannot edit this file (enforced by
+# packages/base/extensions/protected-paths.ts). Parked-codebase services are generated
+# into compose.bays.yaml by `garaje park` and layered in by the bin tooling.
+#
+# This file names no codebase on purpose — the pi service is codebase-agnostic.
+
+services:
+  pi:
+    build: ./pi
+    working_dir: /workspace
+    volumes:
+      - ./:/workspace
+      - pi-config:/root/.pi/agent
+      - garaje-auth:/root/.garaje-auth
+    environment:
+      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
+      # 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
+      # Marker for `garaje` in-container behavior: host-only verbs refuse,
+      # bay verbs run in the bays-only driver scope.
+      - GARAJE_IN_CONTAINER=1
+      # Host path of this garaje root, baked at `garaje up` time. Generated
+      # 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:-}
+    depends_on:
+      - docker-proxy
+
+  # Whitelisting socket proxy (tecnativa/docker-socket-proxy): default-deny;
+  # the env flags below open exactly what parking a bay needs — build, image,
+  # container lifecycle, exec, networks, volumes. Swarm/secrets/system stay
+  # denied. NOTE: the proxy filters by ENDPOINT, not by target container —
+  # per-container protection of the pi service is layers 2+3 (compose split,
+  # command-intent guard). No published ports: only compose-network peers
+  # (the pi service) can reach it.
+  docker-proxy:
+    image: tecnativa/docker-socket-proxy:0.3.0
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    environment:
+      BUILD: 1
+      CONTAINERS: 1
+      EXEC: 1
+      GRPC: 1
+      IMAGES: 1
+      INFO: 1
+      NETWORKS: 1
+      POST: 1
+      SESSION: 1
+      VOLUMES: 1
+      ALLOW_START: 1
+      ALLOW_STOP: 1
+      ALLOW_RESTARTS: 1
+
+volumes:
+  pi-config:
+  garaje-auth:

package/templates/docker-compose.yml

@@ -0,0 +1,13 @@
+# Framework-owned, WRITE-PROTECTED (see packages/base/extensions/protected-paths.ts).
+#
+# Thin composition root. It wires in the framework layer (the pi service).
+# Parked-codebase services live in compose.bays.yaml, which is GENERATED from
+# each bay's recipe.yaml by `garaje park` and layered in by the bin tooling
+# (see bin/_lib.sh). Both files sit at the repo root so build contexts and
+# bind mounts resolve unambiguously.
+#
+# The compose project name is NOT hardcoded here — it comes from the committed
+# `name:` in garaje.yaml, passed as `docker compose -p <name>` by bin/_lib.sh,
+# so each garaje owns its own identity (and stable volume prefix).
+include:
+  - compose.framework.yaml

package/templates/garaje.yaml

@@ -0,0 +1,14 @@
+# garaje.yaml — the parking manifest. COMMITTED.
+#
+# Lists which codebases this garaje parks. `garaje sync` clones each entry
+# into bays/<name> (gitignored), the bind-mounted folder the agent works in.
+# The garaje commits this manifest, not the code (no submodules).
+#
+# A dev who already has a checkout can override per-bay to bind-mount their
+# local path instead — see garaje.local.yaml (gitignored). [override: TODO]
+
+# This garaje's name (set at `garaje init`). Drives the docker compose project
+# name, and thus the volume prefix where auth.json lives (<name>_pi-config).
+name: __GARAJE_NAME__
+
+bays: []

package/templates/gitignore

@@ -0,0 +1,26 @@
+# Local secrets
+.env
+
+# Node (only appears if a service is run outside its container)
+node_modules/
+
+# Python
+__pycache__/
+*.pyc
+
+# JetBrains IDE
+.idea/
+
+# Agent runtime artifacts — host-visible but not committed.
+/sessions/*
+!/sessions/.gitkeep
+scratch/*
+!scratch/.gitkeep
+
+# Parked codebases — materialized by `garaje sync` from garaje.yaml.
+# The garaje commits the manifest (garaje.yaml), not the code.
+bays/*
+!bays/.gitkeep
+
+# Dev-local garaje overrides (per-bay bind-mount paths, personal settings).
+garaje.local.yaml