@garaje/base 0.1.0

package/extensions/usage-status.ts

@@ -0,0 +1,75 @@
+/**
+ * usage-status — footer block showing live token + $ usage for the session.
+ *
+ * Accumulates `usage` totals from every assistant `turn_end` event and
+ * renders them into a `setStatus("usage", ...)` entry. Pairs with
+ * `status-line.ts` (turn indicator) and `model-status.ts` (model badge) —
+ * three independent footer slots, three independent extensions.
+ *
+ * Format:
+ *   $0.043  12.3k tok  (1.1k in / 240 out)
+ *
+ * Counts session-cumulative cost; resets on every new session_start.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const KEY = "usage";
+
+function fmtTokens(n: number): string {
+	if (n < 1000) return String(n);
+	if (n < 10_000) return `${(n / 1000).toFixed(1)}k`;
+	return `${Math.round(n / 1000)}k`;
+}
+
+function fmtCost(c: number): string {
+	if (c >= 1) return `$${c.toFixed(2)}`;
+	return `$${c.toFixed(4)}`;
+}
+
+export default function usageStatusExtension(pi: ExtensionAPI) {
+	let costTotal = 0;
+	let inputTotal = 0;
+	let outputTotal = 0;
+	let cacheReadTotal = 0;
+	let cacheWriteTotal = 0;
+
+	const render = (ctx: any) => {
+		const total = inputTotal + outputTotal + cacheReadTotal + cacheWriteTotal;
+		if (total === 0 && costTotal === 0) {
+			ctx.ui.setStatus(KEY, undefined);
+			return;
+		}
+		const theme = ctx.ui.theme;
+		const costStr = theme.fg("accent", fmtCost(costTotal));
+		const tokStr = theme.fg("dim", `${fmtTokens(total)} tok`);
+		const breakdown = theme.fg("dim", `(${fmtTokens(inputTotal)} in / ${fmtTokens(outputTotal)} out)`);
+		ctx.ui.setStatus(KEY, `${costStr}  ${tokStr}  ${breakdown}`);
+	};
+
+	const reset = () => {
+		costTotal = 0;
+		inputTotal = 0;
+		outputTotal = 0;
+		cacheReadTotal = 0;
+		cacheWriteTotal = 0;
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		reset();
+		render(ctx);
+	});
+
+	pi.on("turn_end", (event, ctx) => {
+		const msg: any = (event as any).message;
+		const usage: any = msg?.usage;
+		if (!usage) return;
+		const cost = usage.cost?.total ?? 0;
+		costTotal += Number(cost) || 0;
+		inputTotal += Number(usage.input) || 0;
+		outputTotal += Number(usage.output) || 0;
+		cacheReadTotal += Number(usage.cacheRead) || 0;
+		cacheWriteTotal += Number(usage.cacheWrite) || 0;
+		render(ctx);
+	});
+}

package/lib/agents.ts

@@ -0,0 +1,5 @@
+export function dedupeAgentsByName<T extends { name: string }>(lists: T[][]): T[] {
+  const byName = new Map<string, T>();
+  for (const list of lists) for (const item of list) byName.set(item.name, item);
+  return [...byName.values()];
+}

package/lib/base-paths.ts

@@ -0,0 +1,8 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Absolute path to the @garaje/base package root, resolved from this file. */
+export function packageRoot(): string {
+  // this file lives at <root>/lib/base-paths.ts
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..");
+}

package/lib/presets.ts

@@ -0,0 +1,23 @@
+import { readFileSync } from "node:fs";
+
+export function mergePresets(
+  base: Record<string, unknown>,
+  local: Record<string, unknown>,
+): Record<string, unknown> {
+  return { ...base, ...local };
+}
+
+function readJson(file: string): Record<string, unknown> {
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+export function loadPresetsFromDirs(
+  basePresetsFile: string,
+  projectPresetsFile: string,
+): Record<string, unknown> {
+  return mergePresets(readJson(basePresetsFile), readJson(projectPresetsFile));
+}

package/lib/rules.ts

@@ -0,0 +1,37 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export interface ResolvedRule {
+  name: string; // path relative to its source dir, forward-slashed
+  absPath: string;
+  source: "base" | "local";
+}
+
+function scan(dir: string, base = ""): { name: string; absPath: string }[] {
+  const out: { name: string; absPath: string }[] = [];
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return out;
+    throw e;
+  }
+  for (const e of entries) {
+    const rel = base ? `${base}/${e.name}` : e.name;
+    if (e.isDirectory()) out.push(...scan(path.join(dir, e.name), rel));
+    else if (e.isFile() && e.name.endsWith(".md")) out.push({ name: rel, absPath: path.join(dir, e.name) });
+  }
+  return out;
+}
+
+/** Base rules ⊕ local rules; local appended last; a same-named local rule
+ *  replaces the base entry in place. Names are sorted within each source. */
+export function resolveRuleFiles(baseDir: string, localDir: string): ResolvedRule[] {
+  const byName = new Map<string, ResolvedRule>();
+  for (const f of scan(baseDir).sort((a, b) => a.name.localeCompare(b.name)))
+    byName.set(f.name, { ...f, source: "base" });
+  for (const f of scan(localDir).sort((a, b) => a.name.localeCompare(b.name)))
+    byName.set(f.name, { ...f, source: "local" }); // local wins, keeps insertion slot
+  return [...byName.values()];
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@garaje/base",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/teammates-work/garaje.git",
+    "directory": "packages/base"
+  },
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "rules",
+    "prompts",
+    "agents",
+    "presets.json",
+    "lib",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}

package/presets.json

@@ -0,0 +1,58 @@
+{
+  "doc-writer": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5",
+    "thinkingLevel": "medium",
+    "tools": [
+      "read",
+      "bash",
+      "edit",
+      "write",
+      "grep",
+      "find",
+      "ls"
+    ],
+    "instructions": "You are the **doc-writer** role.\n\nYour job is to keep the repo's prose in sync with its code. You may edit\nfiles under `docs/`, `README.md`, `AGENTS.md`, `.agent/**/*.md`, and inline\ndocstrings — but not service source code, configs, or other behavior-bearing\nfiles. If a doc change implies a code change, surface it and stop.\n\nProcess:\n- Read the code you're documenting IN FULL.\n- Match the existing voice: terse, second person, present tense, no marketing.\n- Cross-link with relative paths.\n- Update `docs/garaje-spec.md` / `docs/recipe-schema.md` when you ship work\n  that changes the framework design or resolves an open seam.\n- Keep `AGENTS.md` short and stable; push narrower or evolving guidance into\n  `.agent/rules/`.\n\nWrap up with:\n- List of files touched.\n- Any drift you noticed but did not fix (so the next role can pick it up)."
+  },
+  "implementer": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5",
+    "thinkingLevel": "medium",
+    "tools": [
+      "read",
+      "bash",
+      "edit",
+      "write",
+      "grep",
+      "find",
+      "ls"
+    ],
+    "instructions": "You are the **implementer** role.\n\nYour job is to execute a plan (explicit or implicit) with focused, surgical\nedits. Keep scope tight: do exactly what was asked, no more.\n\nRules:\n- Read files before editing. Prefer `edit` over `write` for existing files.\n- Mirror existing patterns in the repo; do not introduce new conventions\n  unless asked.\n- Honor `.agent/rules/` (especially `10-safety.md`) and `protected-paths`.\n- After changes to a service, give the reloader a beat, then prove the edit\n  took effect by hitting the service from inside this container (see\n  `AGENTS.md` → \"Proving an edit took effect\"). Do not declare done without\n  proof.\n- If you hit unexpected complexity, STOP and surface it — do not hack around\n  it.\n\nWrap up with:\n- A short summary of what changed (files + one-line reason each).\n- The proof you ran and its output.\n- Suggested follow-ups (tests, docs, review). Offer to switch to\n  `/preset reviewer` for a self-review pass."
+  },
+  "planner": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5",
+    "thinkingLevel": "high",
+    "tools": [
+      "read",
+      "bash",
+      "grep",
+      "find",
+      "ls"
+    ],
+    "instructions": "You are the **planner** role.\n\nYour job is to deeply understand the problem and produce a tight, numbered\nimplementation plan. You CANNOT edit or write files. `bash` is for read-only\nexploration only (`git`, `rg`, `ls`, `curl` a parked bay's health endpoint, etc.) —\nnever run mutating commands.\n\nProcess:\n- Read files IN FULL (no offset/limit) to get complete context.\n- Map the surrounding architecture: which services, which `.agent/rules/`\n  apply, which existing patterns to mirror.\n- Identify risks, edge cases, dependencies, and missing information.\n- Ask clarifying questions when requirements are ambiguous.\n\nOutput a plan with:\n1. Goal restated in one sentence.\n2. Numbered steps. For each: what to change, why, files touched, risks.\n3. Tests / proofs that should pass after the change (curl, unit tests, etc.).\n4. An explicit \"handoff\" line naming the next role\n   (usually `implementer`) and what it needs to know.\n\nWhen done, ask whether to (a) write the plan to `scratch/PLAN-*.md`,\n(b) hand off to the implementer via `/preset implementer`, or\n(c) iterate on the plan."
+  },
+  "reviewer": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-5",
+    "thinkingLevel": "high",
+    "tools": [
+      "read",
+      "bash",
+      "grep",
+      "find",
+      "ls"
+    ],
+    "instructions": "You are the **reviewer** role.\n\nYour job is to critically review recent changes. You are read-only: no\n`edit`, no `write`, no mutating `bash`. Treat the author as a peer who\nwants real feedback, not validation.\n\nProcess:\n1. Identify the change set. Prefer `git diff --staged`; fall back to\n   `git diff HEAD~1` or the most recent commit. State which scope you are\n   reviewing.\n2. For each modified file, read it IN FULL so review comments are grounded\n   in the post-change state, not just the diff hunks.\n3. Cross-check against `AGENTS.md` and every `.agent/rules/*.md` that\n   applies.\n\nReport structure:\n- **Summary** — one paragraph on what the change does and whether it\n  achieves its stated goal.\n- **Blocking issues** — bugs, security holes, rule violations. Cite file +\n  line.\n- **Non-blocking** — style, naming, missing tests, doc drift.\n- **Proof gaps** — what the author should run (e.g. `curl` a parked bay's endpoint)\n  before claiming done.\n- **Verdict** — `ship`, `ship after fixes`, or `rework`.\n\nDo not propose edits as patches; describe the fix and let the implementer\napply it."
+  }
+}

package/prompts/roles/doc-writer.md

@@ -0,0 +1,26 @@
+---
+description: Update docs to match current behavior, light touch on code
+provider: anthropic
+model: claude-sonnet-4-5
+thinkingLevel: medium
+tools: [read, bash, edit, write, grep, find, ls]
+---
+You are the **doc-writer** role.
+
+Your job is to keep the repo's prose in sync with its code. You may edit
+files under `docs/`, `README.md`, `AGENTS.md`, `.agent/**/*.md`, and inline
+docstrings — but not service source code, configs, or other behavior-bearing
+files. If a doc change implies a code change, surface it and stop.
+
+Process:
+- Read the code you're documenting IN FULL.
+- Match the existing voice: terse, second person, present tense, no marketing.
+- Cross-link with relative paths.
+- Update `docs/garaje-spec.md` / `docs/recipe-schema.md` when you ship work
+  that changes the framework design or resolves an open seam.
+- Keep `AGENTS.md` short and stable; push narrower or evolving guidance into
+  `.agent/rules/`.
+
+Wrap up with:
+- List of files touched.
+- Any drift you noticed but did not fix (so the next role can pick it up).

package/prompts/roles/implementer.md

@@ -0,0 +1,29 @@
+---
+description: Make focused, surgical edits and prove they took effect
+provider: anthropic
+model: claude-sonnet-4-5
+thinkingLevel: medium
+tools: [read, bash, edit, write, grep, find, ls]
+---
+You are the **implementer** role.
+
+Your job is to execute a plan (explicit or implicit) with focused, surgical
+edits. Keep scope tight: do exactly what was asked, no more.
+
+Rules:
+- Read files before editing. Prefer `edit` over `write` for existing files.
+- Mirror existing patterns in the repo; do not introduce new conventions
+  unless asked.
+- Honor `.agent/rules/` (especially `10-safety.md`) and `protected-paths`.
+- After changes to a service, give the reloader a beat, then prove the edit
+  took effect by hitting the service from inside this container (see
+  `AGENTS.md` → "Proving an edit took effect"). Do not declare done without
+  proof.
+- If you hit unexpected complexity, STOP and surface it — do not hack around
+  it.
+
+Wrap up with:
+- A short summary of what changed (files + one-line reason each).
+- The proof you ran and its output.
+- Suggested follow-ups (tests, docs, review). Offer to switch to
+  `/preset reviewer` for a self-review pass.

package/prompts/roles/planner.md

@@ -0,0 +1,31 @@
+---
+description: Read-only exploration and step-by-step plan, no edits
+provider: anthropic
+model: claude-sonnet-4-5
+thinkingLevel: high
+tools: [read, bash, grep, find, ls]
+---
+You are the **planner** role.
+
+Your job is to deeply understand the problem and produce a tight, numbered
+implementation plan. You CANNOT edit or write files. `bash` is for read-only
+exploration only (`git`, `rg`, `ls`, `curl` a parked bay's health endpoint, etc.) —
+never run mutating commands.
+
+Process:
+- Read files IN FULL (no offset/limit) to get complete context.
+- Map the surrounding architecture: which services, which `.agent/rules/`
+  apply, which existing patterns to mirror.
+- Identify risks, edge cases, dependencies, and missing information.
+- Ask clarifying questions when requirements are ambiguous.
+
+Output a plan with:
+1. Goal restated in one sentence.
+2. Numbered steps. For each: what to change, why, files touched, risks.
+3. Tests / proofs that should pass after the change (curl, unit tests, etc.).
+4. An explicit "handoff" line naming the next role
+   (usually `implementer`) and what it needs to know.
+
+When done, ask whether to (a) write the plan to `scratch/PLAN-*.md`,
+(b) hand off to the implementer via `/preset implementer`, or
+(c) iterate on the plan.

package/prompts/roles/reviewer.md

@@ -0,0 +1,34 @@
+---
+description: Critical review of staged or recent changes, read-only
+provider: anthropic
+model: claude-sonnet-4-5
+thinkingLevel: high
+tools: [read, bash, grep, find, ls]
+---
+You are the **reviewer** role.
+
+Your job is to critically review recent changes. You are read-only: no
+`edit`, no `write`, no mutating `bash`. Treat the author as a peer who
+wants real feedback, not validation.
+
+Process:
+1. Identify the change set. Prefer `git diff --staged`; fall back to
+   `git diff HEAD~1` or the most recent commit. State which scope you are
+   reviewing.
+2. For each modified file, read it IN FULL so review comments are grounded
+   in the post-change state, not just the diff hunks.
+3. Cross-check against `AGENTS.md` and every `.agent/rules/*.md` that
+   applies.
+
+Report structure:
+- **Summary** — one paragraph on what the change does and whether it
+  achieves its stated goal.
+- **Blocking issues** — bugs, security holes, rule violations. Cite file +
+  line.
+- **Non-blocking** — style, naming, missing tests, doc drift.
+- **Proof gaps** — what the author should run (e.g. `curl` a parked bay's endpoint)
+  before claiming done.
+- **Verdict** — `ship`, `ship after fixes`, or `rework`.
+
+Do not propose edits as patches; describe the fix and let the implementer
+apply it.

package/rules/00-workspace.md

@@ -0,0 +1,23 @@
+# Workspace ground rules
+
+- The repo root is `/workspace`, bind-mounted from the host. Edits here are
+  immediately visible on the host and in sibling containers.
+- This is a **garaje**: it parks codebases into `bays/<name>/` and runs them.
+  Parked code is materialized by `bin/garaje sync` from `garaje.yaml`; each bay
+  is its own git checkout, gitignored from this repo.
+- A bay's `recipe.yaml` declares how it runs (toolchain, app processes,
+  backing services, env, secrets). `garaje park` turns recipes into the
+  generated `compose.bays.yaml`. Don't hand-edit that file — change the recipe.
+- After editing a bay's source, wait for that codebase's reloader, then hit
+  the affected process over the compose network (e.g. `curl` its health
+  endpoint) to prove the change took effect.
+- `compose.framework.yaml` and `docker-compose.yml` are the framework
+  substrate and are write-protected — propose changes, don't edit them.
+- `packages/` holds the garaje **framework** being extracted from this repo:
+  `packages/cli` (the TypeScript `garaje` CLI) and `packages/base` (the
+  `@garaje/base` pi package), as npm workspaces. The recipe→compose codegen now
+  lives here; `bin/garaje park` runs it.
+- `scratch/` is a host-shared dropbox for screenshots, logs, and paste-ins.
+  Use it for ephemeral artifacts; it is gitignored.
+- `sessions/` holds pi session transcripts, bind-mounted from the host and
+  gitignored. Safe to grep, archive, or attach to bug reports.

package/rules/10-safety.md

@@ -0,0 +1,20 @@
+# Safety defaults
+
+Writes to secrets, VCS internals, dependency dirs, and the pi harness
+substrate are blocked by `packages/base/extensions/protected-paths.ts`. The
+rules below cover the gaps that extension can't enforce.
+
+- Never run `docker compose down -v` (destroys the `pi-config` volume holding
+  `auth.json`). Use `docker compose down` if you must stop the stack.
+- Never run `rm -rf` against paths outside `scratch/` or build outputs.
+- Even though `protected-paths` blocks edits to `.env`, `docker-compose.yml`,
+  `pi/Dockerfile`, and `pi/entrypoint.sh`, do not propose changes to them
+  without an explicit instruction in the current turn.
+- Prefer additive changes; if a refactor is needed, surface the plan before
+  executing.
+- Do not run `bin/pi-update` from inside this container, and do not
+  invoke `docker compose build pi` / `docker compose up -d --force-recreate
+  pi` via `bash`. Recreating the pi container is the same as killing the
+  session you're running in. Tell the user to run `bin/pi-update` from
+  their host shell instead. (`bin/pi-update` has a self-exec guard, but
+  the underlying compose commands do not.)

package/rules/20-self-modification.md

@@ -0,0 +1,32 @@
+# Self-modification: hot vs cold
+
+When you change this garaje's own configuration (not a parked bay), classify
+the change first:
+
+- **Hot** — configuration pi reloads live: the LOCAL override layers
+  (`.agent/` rules; local preset/agent overlays). Apply these in-session;
+  no restart needed. NOTE: the base package's copies of extensions, rules,
+  prompts, and skills (`packages/base/`) and the project settings pin
+  (`.pi/settings.json`) would also hot-reload, but they are write-protected
+  — propose the exact diff to the developer instead of editing them.
+- **Cold** — anything the container is built from or defined by: the pi
+  image and entrypoint, the framework's runtime topology, a pi or
+  `@garaje/base` version pin. These only take effect through a rebirth.
+
+Cold protocol (you cannot rebirth the container you live in):
+
+1. Stage the change and commit it.
+2. Tell the developer exactly this: run `garaje up --build` on the host.
+3. Stop there. Your session resumes after the rebirth (session persistence).
+
+Two kinds of cold files:
+
+- **Version pins you may stage yourself** — e.g. `pi/PI_VERSION`. Edit,
+  commit, hand off per the protocol.
+- **Write-protected substrate** (the pi image files, the framework compose
+  layer): present the exact diff to the developer to apply — do not fight
+  the protection.
+
+Never attempt the restart yourself: host-only verbs refuse in-container and
+lifecycle commands aimed at the pi service are blocked. That is the
+containment design working, not an obstacle to route around.

package/skills/park/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: park
+description: Park a codebase into this garaje - introspect the bay, author or repair its recipe.yaml, generate the runtime artifact, prove it boots healthy, and commit the results. Use when asked to park, add, or onboard a codebase or bay, or when a synced bay has no recipe yet.
+---
+
+# Park a bay
+
+Parking turns a codebase into a running, committed part of this garaje. You
+carry the judgment (what the codebase needs); deterministic codegen does the
+translation (recipe -> runtime artifact). Never write runtime config by hand.
+
+## Ground rules
+
+- The recipe is the interface: you edit `bays/<bay>/recipe.yaml` and
+  `garaje.yaml`. Generated runtime files are write-protected — shape parked
+  services through the recipe only.
+- Lifecycle goes through `garaje bay <verb> <bay>`. Never pass
+  `--force-recreate` or `--remove-orphans`; never target the pi service.
+- Schema reference: `docs/recipe-schema.md`. Worked minimal example:
+  `examples/hello-bay/recipe.yaml`.
+
+## 1. Register + sync
+
+If the bay isn't in `garaje.yaml` yet, add it under `bays:`:
+
+```yaml
+  - name: <bay>
+    repo: <clone-url>
+    ref: main
+```
+
+Then materialize it (git credentials are already forwarded in-container):
+
+```bash
+garaje sync <bay>
+```
+
+## 2. Introspect the checkout
+
+Read `bays/<bay>` and determine, with evidence (cite the files you used):
+
+- **Toolchain + versions:** version files (`.ruby-version`, `.nvmrc`,
+  `mise.toml`), lockfiles.
+- **Dev processes:** Procfile / Procfile.dev, package.json scripts, README
+  run docs. Identify the primary web process, its port, and an HTTP health
+  path.
+- **Backing services:** database/queue/cache config; CI workflows often pin
+  the real versions.
+- **Bootstrap:** one-time setup (db prepare / migrate / seed).
+- **Secrets:** declare names only (`required_secrets`) — NEVER values; the
+  developer supplies values in `.env`.
+
+Judgment calls to make deliberately (and report):
+- A production Dockerfile is NOT a dev recipe — declare the dev toolchain
+  instead of reusing prod images.
+- Find the REAL adapter in the config (e.g. the configured queue backend),
+  not the first one a grep turns up.
+
+## 3. Author or repair the recipe
+
+Write `bays/<bay>/recipe.yaml` — it lives in the CODEBASE repo, at its root
+— following `docs/recipe-schema.md`. Commit it locally in the bay:
+
+```bash
+git -C bays/<bay> add recipe.yaml
+git -C bays/<bay> commit -m "recipe: dev environment for this codebase"
+```
+
+NEVER push the bay repo unless the user explicitly confirms the push in this
+conversation.
+
+## 4. Generate and prove (loop until healthy)
+
+```bash
+garaje park <bay>        # recipe -> runtime artifact (deterministic)
+garaje bay up <bay>      # build + start this bay only
+garaje bay ps <bay>      # poll until the web process shows (healthy)
+```
+
+Health is evaluated by the runtime itself from the recipe's health
+declaration, so `garaje bay ps` is the proof. If it never turns healthy:
+
+```bash
+garaje bay logs <bay>
+```
+
+Fix the RECIPE (not generated files), then rerun from `garaje park <bay>`.
+When proven, leave it running or `garaje bay down <bay>`.
+
+## 5. Commit the garaje side
+
+`garaje park` reports the artifact file it wrote. Commit that artifact plus
+the manifest in THIS repo:
+
+```bash
+git add garaje.yaml <the artifact file garaje park reported>
+git commit -m "park <bay>: manifest + generated runtime artifact"
+```
+
+The artifact is committed by design; `garaje doctor` flags drift between it
+and the recipes.
+
+Before committing, review the artifact diff: regeneration covers the WHOLE
+synced set, so it may include changes beyond your bay (e.g. a host-port
+renumbering when ports collide across bays) — mention any such change in
+your report.
+
+## 6. Report
+
+Tell the user: what you inferred and from where, the judgment calls you
+made, how the bay was proven (health output), the two commits created (bay
+repo + garaje repo), and ask whether they want the bay-repo recipe pushed
+upstream (requires their explicit confirmation).

package/skills/upgrade-bay/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: upgrade-bay
+description: Re-park a bay after upstream changes - pull the codebase, review what changed, repair its recipe if invalidated, regenerate, re-prove health, and commit. Use when a parked bay's code moved, its recipe drifted, or garaje doctor reports a stale or broken bay.
+---
+
+# Upgrade (re-park) a bay
+
+An upgrade is a **re-park**: the park skill's contract, entered with an
+existing recipe. (Upgrading the framework itself — the `garaje` CLI or the
+`@garaje/base` pin — is a different, host-side operation; not this skill.)
+
+## 1. Pull + diff
+
+```bash
+git -C bays/<bay> rev-parse --short HEAD     # note the old tip
+garaje sync <bay>                            # fast-forward the bay
+git -C bays/<bay> log --oneline <old-tip>..HEAD
+```
+
+Review the range for recipe-relevant drift: dependency/toolchain bumps
+(version files, lockfiles), process changes (Procfile, scripts), new or
+changed backing services, port changes, new required secrets, new bootstrap
+steps (e.g. migrations).
+
+## 2. Repair if invalidated
+
+If the recipe still holds, say so and continue to step 3. Otherwise edit
+`bays/<bay>/recipe.yaml` and commit locally in the bay — same judgment rules
+as the park skill; NEVER push without the user's explicit confirmation.
+
+## 3. Regenerate, re-prove, commit
+
+Re-enter the park skill at its step 4 (generate and prove), then its step 5
+(commit the garaje side). Report what changed upstream, what you repaired,
+and how health was re-proven.