# Packages

Compose shared Ferrite source into constrained apps without adding another Cargo dependency or runtime service.

Ferrite packages are reusable source trees for deployable apps. They compile
inside the app’s one authority boundary and use only the handles the host app
declares.

## Add a package

```bash
ferrite add agent-ready
ferrite add ferrite-auth
ferrite add mcp
```

The CLI resolves package dependencies, vendors the source under `src/`, writes
provenance headers, and records the mount in `ferrite-packages.json`. A differing
existing file refuses unless you explicitly force replacement.

## Package catalogue

| Package | Use it for |
| --- | --- |
| `agent-ready` | Markdown twins, robots, llms.txt, OpenAPI, agent card, MCP, readiness reports |
| `ferrite-auth` | Opaque sessions, policy, assurance, action tokens, audit and privacy contracts |
| `mcp` | Constrained MCP wire, stateless client and resource server |
| `acp` | Agent Client Protocol v1 |
| `agent-toolkit` | Durable agent sessions, steering, gates, tool families |
| `ai-budgets` | Model attribution, budgets, and steering |
| `gatekeeper` | Governed connectors, approvals, schedules, token vault |
| `connector-github` / `connector-google` | Provider adapters on gatekeeper |
| `context-library` | Governed organization knowledge |
| `blueprints` | Reusable code and binding requirements without state or credentials |
| `browser-core` | Browser sessions and WebMCP-ready browser primitives |
| `crdt-text` | Convergent collaborative text |
| `wasm-runtime` | Constrained WebAssembly interpretation |
| `serde-codec` / `sha256-hmac` | Compact encoding and constrained cryptographic primitives |

## Update a package checkout

When you contribute to a package, edit `packages/<name>/src` in its source
checkout and run:

```bash
node tools/ferrite-pkg/ferrite-pkg.mjs sync
node tools/ferrite-pkg/ferrite-pkg.mjs check
```

Never hand-edit a file whose header says `@generated by ferrite-pkg`; the next
sync will replace it.

## Security shape

A package has no deployment, credentials, or resources of its own. Host import
requirements name source modules, not capabilities. If a subsystem needs an
independent failure, scale, or authority boundary, make it a private Ferrite
app rather than a package.