# Ctrl AI

> Ctrl AI vendors verified backend parts (auth, billing, email, webhooks, jobs,
> storage, …) into your repo and locks each to a content hash, so the
> infrastructure an AI agent depends on can't be changed without it showing up — a
> red diff locally and a failed check in CI. Your agent wires the seams and builds
> the product; it doesn't re-derive or silently rewrite the parts.

This file is a cold-load manifest for AI agents. The authoritative, deeper sources
are linked below; the registry catalog is `registry/index.json`.

## Rules for an agent in a Ctrl-locked repo

- **Never edit files under `parts/**`.** Interiors are content-hashed; an edit
  changes the hash and `ctrlai guard` (pre-commit) and `ctrlai audit` (CI) fail.
- **Import only the seam:** `parts/<name>/src/index`, aliased `@parts/<name>`.
  Deep imports are illegal (and `@parts/<name>/<interior>` won't even resolve).
- **Change a part only through a sanctioned verb, never your editor:**
  `ctrlai add <part|pack>`, `ctrlai upgrade <part> [--adapter=X]`,
  `ctrlai eject <part>`, `ctrlai remove <part>`. Each moves the lock and the
  spec (`ctrl.spec.json`) together.
- **Learn a part from `parts/<name>/contract.json` (manifest) + `seams.md`
  (what to wire) + `SPEC.md` — never from `src/`.**
- **Keep `ctrlai conform` green** (CI runs `audit` + `conform`). Don't hand-roll a
  capability a part covers — even via raw `fetch` (a known detection blind spot).
- **Your product's own schema** goes in `migrations/NNN-*.sql` at the repo root,
  not under `parts/**`.
- `git commit --no-verify` only skips the local hook; CI still runs and the change
  still can't land. Use the verbs.

## Honest scope (today)

The lock delivers **legibility** — every infra change is a reviewable diff and
drift fails CI. It is **not** cryptographic tamper-proofing yet: attestations are
`dev:unsigned` and a determined writer who also rewrites `parts.lock` +
`ATTESTATION.json` can re-bless an edit. Enforced integrity (a change can't land at
all) is the cross-repo / team tier. See trust-and-security.md.

## Capabilities (16 verified parts)

`auth.session`, `auth.apikey`, `auth.tenancy`, `billing.subscription`,
`billing.usage`, `email.transactional`, `sms.transactional`, `webhooks.ingest`,
`webhooks.dispatch`, `jobs.queue`, `storage.upload`, `ratelimit.api`, `audit.log`,
`flags.feature`, `search.fulltext`, `admin.crud`.

## Packs (one-command kits)

`ctrlai add <pack>` — `saas`, `ai-api`, `marketplace`, `backoffice`, `starter`.

## MCP server (`@ctrlai/mcp`, if connected)

`resolve_plan(capabilities[])`, `search_parts(query)`, `get_contract(part)`,
`get_seams(part)`, `get_upgrade_plan(part, from, to)`, `inspect_repo()`,
`doctor_repo()`, `conform_repo()`, `provision_repo()`.

## Docs

- How it works (mental model): docs/how-ctrl-ai-works.md
- Agent contract (the full version of the rules above): docs/agent-guide.md
- CLI reference: docs/cli-reference.md
- Trust & security (the honest threat model): docs/trust-and-security.md
- Troubleshooting (CI went red → fix): docs/troubleshooting.md
- Quickstart (first run): docs/quickstart.md