> ## Documentation Index
> Fetch the complete documentation index at: https://docs.budscollab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Registry

> How BudsCollab app artifacts move from preview to review to install policy.

Registry state is staged. Each stage adds evidence without skipping the review
gates that make a package installable:

| Stage            | Meaning                                      |
| ---------------- | -------------------------------------------- |
| Blueprint        | Draft app source.                            |
| Showcase preview | Discoverable metadata, preview only.         |
| Review report    | Validation evidence and remaining blockers.  |
| Collection entry | User- or space-scoped listing.               |
| Signed package   | Installable only when host policy allows it. |

These stages are represented by `SDK_DISTRIBUTION_LIFECYCLE_CATALOG`.
Collection entries can be projected with `resolveSdkDistributionLifecycleStage()`
so SDK docs, CLI review output, Hub previews, and future Eve sandbox decisions
use the same vocabulary.

For a full registry preflight, run the pack and registry commands after package
validation. The first three commands create the local submission and index; the
remaining commands prepare future hosted API payloads while keeping the package
non-installable.

```bash theme={null}
npx @budscollab/cli app pack budscollab.package.json --owner-id example-dev --owner-name "Example Developer" --visibility unlisted
npx @budscollab/cli app registry budscollab-registry-submission.json --out budscollab-registry-index.json
npx @budscollab/cli app registry-validate budscollab-registry-index.json
npx @budscollab/cli app registry-acceptance budscollab-registry-submission.json --out budscollab-registry-acceptance-request.json
npx @budscollab/cli app registry-acceptance-validate budscollab-registry-acceptance-request.json
npx @budscollab/cli app registry-publisher-verification budscollab-registry-submission.json --out budscollab-registry-publisher-verification.json
npx @budscollab/cli app registry-publisher-verification-validate budscollab-registry-publisher-verification.json
npx @budscollab/cli app registry-review-evidence budscollab-registry-submission.json --out budscollab-registry-review-evidence.json
npx @budscollab/cli app registry-review-evidence-validate budscollab-registry-review-evidence.json
npx @budscollab/cli app registry-signing-request budscollab-registry-acceptance-request.json --out budscollab-registry-signing-request.json
npx @budscollab/cli app registry-signing-request-validate budscollab-registry-signing-request.json
npx @budscollab/cli app registry-install-policy budscollab-registry-signing-request.json --out budscollab-registry-install-policy.json
npx @budscollab/cli app registry-install-policy-validate budscollab-registry-install-policy.json
```

The commands produce a handoff bundle:

| Artifact                                          | What it proves locally                                                                                  |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `budscollab-registry-submission.json`             | Owner, visibility, package artifact, review report, blockers, next gate, and unsigned artifact digests. |
| `budscollab-registry-index.json`                  | Deterministic local index for one or more submissions.                                                  |
| `budscollab-registry-acceptance-request.json`     | Future hosted API request shape with required server gates.                                             |
| `budscollab-registry-publisher-verification.json` | Declared publisher identity, still `unverified`.                                                        |
| `budscollab-registry-review-evidence.json`        | Prepared review evidence, still `unstored`.                                                             |
| `budscollab-registry-signing-request.json`        | Unsigned package digests for a future host-controlled signer.                                           |
| `budscollab-registry-install-policy.json`         | Install-policy preflight, still `not-applied` and non-installable.                                      |

## Hosted API contract

The public SDK slice also includes `hosted-registry-api-contract.json`. It
defines fail-closed `/api/sdk/registry` endpoints for:

| Endpoint                       | Artifact                                          |
| ------------------------------ | ------------------------------------------------- |
| `POST /acceptance-requests`    | `budscollab-registry-acceptance-request.json`     |
| `POST /indexes/validate`       | `budscollab-registry-index.json`                  |
| `POST /publisher-verification` | `budscollab-registry-publisher-verification.json` |
| `POST /review-evidence`        | `budscollab-registry-review-evidence.json`        |
| `POST /signing-requests`       | `budscollab-registry-signing-request.json`        |
| `POST /install-policy`         | `budscollab-registry-install-policy.json`         |

The web app route stubs parse validated SDK artifacts, recompute SHA-256
package artifact hashes, reject digest mismatches, and return `accepted:
false`, `signed: false` where applicable, `installable: false`, and the missing
server gates.

`hosted-registry-readiness-contract.json` is the readiness ledger for those
server gates:

| Gate                   | Local status                                                             |
| ---------------------- | ------------------------------------------------------------------------ |
| Artifact hash          | Evidenced by `artifactDigests` and fail-closed route hash recomputation. |
| Publisher verification | Declared, still unverified.                                              |
| Review storage         | Prepared, still unstored.                                                |
| Artifact signing       | Prepared, still unsigned.                                                |
| Host install policy    | Planned, still not applied.                                              |

The contract mirrors the fail-closed `gateStatuses` returned by the route stubs.
The executable readiness verifier is `scripts/verify-registry-readiness.mjs`.
Run `pnpm verify:registry:local` before deployment to check the contract and
gate posture, then run
`pnpm verify:registry:hosted https://app.budscollab.com --artifact-dir ./generated-app`
after hosted routes exist to POST generated registry artifacts through each
fail-closed endpoint.

Until publisher identity, review storage, artifact hash, artifact signing, and
renderer isolation are complete, external packages should be described as
validated artifacts and showcase previews, not installable marketplace apps.