# Installing Bucker with a coding agent

A coding agent can install the SDK for you, and you can read exactly what it intends to do
before it does anything. This page is the contract: what the agent runs, what it is told,
what it is never shown, and how the install proves itself.

## 1. Check the skill before you trust it

The agent's instructions are the `bucker-install` skill, served by the MCP tool
`get_bucker_skills` and written to `docs/skills/` by `create-bucker --skills`. An agent edits
your repository on its say-so, so the pack must be the one Bucker released.

```bash
bucker-verify skill ./skills --key ./bucker-skills.pub
```

The pack is a `manifest.json` listing each skill with its SHA-256, a `packDigest` over those
lines, and an ed25519 signature over `packDigest`. The check is offline and refuses (exit 2) a pack
whose manifest or any skill's digest was altered. The key is the one you obtained out of band
from the release: a key found inside the pack is only the pack's claim about itself and is
never trusted. A signed pack checked with no `--key`, and an unsigned pack without
`--allow-unsigned`, exit 7 ("nothing was checked") rather than pass.

## 2. Ask for the plan

```bash
npx create-bucker --json --dry-run
```

Standard output carries exactly one JSON document, schema `create-bucker-plan/1`, and nothing
else (progress and the package manager's output go to standard error). It lists the detected
framework, the steps, the files to be created or edited with a bounded diff each, the guards
that applied (for example a Sentry SDK already present, or the source-map check), and a
`plan.digest`: a SHA-256 over what will happen. The plan is deterministic. The real run that
follows prints the same `plan`, so a person who confirmed the dry run has confirmed the run.

The DSN is a credential, so it is reported as `{ "variable": "BUCKER_DSN", "fingerprint": "<8 hex>" }`
and never as a value. The installer writes the value into the env file itself, under the same
never-overwrite rule as before: an existing key with a different value is left alone and
reported. `--json` never prompts; an edit to your own code that was not confirmed with `--yes`
is declined and says so.

## 3. Run it

```bash
npx create-bucker --json --yes --org <org> --project <project>
```

The run then proves the install, in order:

1. **Test envelope.** A synthetic envelope (`BuckerTestEvent`) goes to the ingest door the DSN
   names. A 2xx says the DSN authenticates and the door accepts. It proves nothing about your
   SDK, and the server never counts it as the app's first event.
2. **Source maps.** When the bundler plugin is installed, a minified frame is resolved and the
   result is reported as a guard (`resolved`, `unresolved`, or `not_applicable`).
3. **First real event.** The installer waits for a non-synthetic event (`--verify-timeout`,
   `--no-verify` skips it). You trigger it from the app.
4. **Receipt.** The installer reports the plan digest, the SDK versions it read from disk, the
   framework and the DSN fingerprint to
   `POST /orgs/:org/projects/:project/install/verify`.

## 4. The receipt

The server checks that the fingerprint belongs to an active key of that project and that a real
event has arrived (`409 no_real_event` otherwise), then signs an `install_verified` claim into the
organization's receipt log. It records the plan digest, framework, SDK versions, the fingerprint,
whether source maps were checked and when the first real event arrived. It records no path, no
repository name and no person.

- The project comes from the URL and the caller's permission on it, never from the body, and the
  body schema refuses an unknown field. Another organization's project is "not found".
- The same plan digest reported twice returns the claim already filed. A second install of the
  same project is a different plan and files a new claim (`reissued: true`); the old one is never
  rewritten.
- `bucker-verify` checks the claim offline. It is an extension-kind claim, so a verifier that
  does not know the kind reports it `UNVERIFIED_BY_THIS_VERSION` and no tier accepts it.
- `sdk_inventory_get` with `include: ["setup"]` shows the project's newest receipt.

There is no MCP tool that files a receipt: it is filed by the installer a person ran with their
own token.

## What an agent must never do

- Print, log, paste or commit the DSN or any `bkr_` / `bpat_` token. The installer redacts both
  from every output path; do not work around it.
- Merge, approve or deploy on the strength of an install. A receipt says the pipeline works.
