---
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
```

A fresh manifest reads `bays: []`. That is an empty *flow* sequence — list
items cannot be appended beneath it. Replace it with a bare `bays:` first, or
`garaje sync` will reject the file as malformed YAML.

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).