# 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 `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.
- Pi extensions are **codified in the repo**, not installed ad hoc. Run
  `pi install -l npm:<pkg>@<version>` — the `-l` writes the committed
  `.pi/settings.json`, and teammates get the package automatically on their next
  `garaje up`. Without `-l` the install lands in user scope on the pi-config
  volume, where nobody else can see it. Always pin the version, then commit
  `.pi/settings.json`. (`.pi/npm/` holds the artifacts and is gitignored.)
- Inference credentials live in `.env`, which compose forwards into this
  container; that is the only surface. A key stored by `/login` is written to
  `/root/.pi/agent/auth.json` on the pi-config volume and OVERRIDES `.env`.
- `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; `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.