# @garaje/base

The **agent-side substrate** for the [garaje](https://www.npmjs.com/package/garaje)
framework, distributed as a [pi](https://pi.dev) package.

A garaje runs the pi coding agent against your codebases; `@garaje/base` is what
gives that agent its *garaje-specific* behavior. It ships:

- the **Garaje persona**, base **rules**, and canonical **roles**
  (planner / implementer / reviewer / doc-writer),
- the base **extensions** (preset/role commands, guardrails, protected-paths
  and command-intent guards that keep the agent from reconfiguring its own
  container),
- the agent **skills** — including **park** (introspect a codebase and wire it
  into the garaje) and **upgrade-bay** (re-park after upstream change),
- the generated `presets.json` and `agents/*.md` derived from the roles.

## How it's consumed

A garaje pins this package **declaratively** — you don't install or import it by
hand. Its `.pi/settings.json` carries a `packages` entry, and pi installs and
loads the package (read-only) on session start:

```json
{
  "packages": [
    {
      "source": "npm:@garaje/base@0.1.1",
      "extensions": ["extensions/**", "!extensions/session-name.ts"]
    }
  ]
}
```

`garaje init` writes this pin at the CLI's own version, so a fresh garaje is
internally consistent by construction, and `garaje upgrade` bumps it.

## Override-only customization

The base installs **read-only**. A garaje customizes by layering local resources
on top — extra rules in `.agent/rules/`, project presets in `.pi/presets.json`,
local roles in `.pi/agents/` — which pi merges over the base at load time, with
local entries winning on name collisions. Because lower layers are never edited
in place, upgrading the framework is a version-pin bump rather than a merge, and
`garaje upgrade` flags any local override that now shadows or orphans a changed
base resource.

## Harness portability

`@garaje/base` is specifically the **pi adapter** for garaje. The framework's
harness seam is deliberately thin: targeting a different agent harness means
shipping a different base package, not rewriting the framework. Role and rule
*content* is portable Markdown, so it carries across.

A pi package contributes **extensions, prompts, roles, rules, and skills** to a
session (packages contribute resources, not host settings). Released in lockstep
with the `garaje` CLI.

## License

MIT