# Docs: Build Extensions

The detailed build path stays narrow on purpose: bundle-first, preview-workspace validation, explicit review gates, and service-backed runtime only when clearly justified.

## Summary

- Public start page first: Use `/extension-developers` as the public route that sends humans and agents into the right authoring path before they drop into this detailed guide.
- Prerequisites exist first: The build path assumes there is already a running instance, an authenticated CLI, and a preview workspace.
  Proof:
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Defines the extension authoring contract and the intended bundle-first default.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Single-file agent handoff for creating and validating a bounded extension.
- Implementation: extension-sdk/manifest.json (https://github.com/MoveBigRocks/extension-sdk/blob/main/manifest.json) — Concrete extension manifest scaffold for scope, kind, and runtime behavior.
- Enforcement: extension-sdk/security/threat-model.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/security/threat-model.md) — Threat-model prompt used before activating custom extensions.

- Bounded capability: Define the slice and its relationship to the core primitives.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
- Definition: docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md) — Defines when work belongs in the instance repo versus a separate extension repo.
- Contract: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
- Implementation: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Shows the canonical public scaffold for bounded custom extension authoring.

- Bundle-first default: Start workspace-scoped, standard-risk, and bundle-first unless the requirement clearly needs more.
  Proof:
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Defines the extension authoring contract and the intended bundle-first default.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Single-file agent handoff for creating and validating a bounded extension.
- Implementation: extension-sdk/manifest.json (https://github.com/MoveBigRocks/extension-sdk/blob/main/manifest.json) — Concrete extension manifest scaffold for scope, kind, and runtime behavior.
- Enforcement: extension-sdk/security/threat-model.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/security/threat-model.md) — Threat-model prompt used before activating custom extensions.

- Supported generic slice: The generic self-built path is for workspace-scoped standard-risk product or operational extensions.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
- Definition: docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md) — Defines when work belongs in the instance repo versus a separate extension repo.
- Contract: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
- Implementation: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Shows the canonical public scaffold for bounded custom extension authoring.

- Preview-workspace validation: Validate in a preview workspace before production review.
  Proof:
- Contract: docs/AGENT_CLI.md (https://github.com/MoveBigRocks/platform/blob/main/docs/AGENT_CLI.md) — Defines the supported agent CLI contract, auth modes, and command surface.
- Contract: docs/swagger.yaml (https://github.com/MoveBigRocks/platform/blob/main/docs/swagger.yaml) — Documents the public API surface, auth model, and health endpoints.
- Implementation: cmd/api/routers.go (https://github.com/MoveBigRocks/platform/blob/main/cmd/api/routers.go) — Implements the split between `/graphql`, `/admin/graphql`, public routes, and authenticated agent surfaces.
- Enforcement: .github/workflows/_test.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_test.yml) — Verifies builds, tests, and contract-sensitive paths on the public platform codebase.

- Service-backed needs justification: Only move into handlers, jobs, event consumers, or owned schema when the requirement truly calls for it.
  Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
- Implementation: internal/platform/domain/extension.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension_runtime.go) — Enforces that only service-backed `owned_schema` extensions can register owned schemas.
- Implementation: internal/infrastructure/stores/sql/extension_runtime_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.


## The extension SDK is not the first step in the journey.

Start a custom extension repo only after there is a Move Big Rocks instance you control, `mbr` is authenticated to it, and a preview workspace exists for safe installs. If those do not exist yet, the deployment and instance-repo path comes first.

- Use `/extension-developers` as the public start page when the builder or agent still needs the routing and boundary summary.
- Use `/docs/self-host` first when the runtime does not exist yet.
- Log in with `mbr auth login` before trying extension commands.
- Treat the preview workspace as the default proving ground for installs and upgrades.

## Begin with the simplest safe extension shape.

The canonical authoring flow starts from the extension SDK and keeps the first version narrow. That means `workspace` scope, `standard` risk, and `bundle` runtime unless the product slice truly needs more infrastructure.

Proof:
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Defines the extension authoring contract and the intended bundle-first default.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Single-file agent handoff for creating and validating a bounded extension.
- Implementation: extension-sdk/manifest.json (https://github.com/MoveBigRocks/extension-sdk/blob/main/manifest.json) — Concrete extension manifest scaffold for scope, kind, and runtime behavior.
- Enforcement: extension-sdk/security/threat-model.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/security/threat-model.md) — Threat-model prompt used before activating custom extensions.

- Keep the repo separate from the core repo and from the private instance repo.
- Rename the manifest, routes, and publisher details before deeper work.
- Stay inside the supported generic self-built slice: `workspace`, `standard`, and `product` or `operational`.
- Do not force `instance`, `privileged`, `identity`, or `connector` extensions through the generic SDK path.
- Implement one useful admin or public page before adding more surface area.
- Ship one bundled agent skill so the extension remains legible to agents.

## The CLI gives the shortest supported path from source tree to a live preview-workspace extension.

The public extension build story should be operational, not aspirational. These commands come from the extension SDK handoff and show the default loop for building and operating a custom extension.

Proof:
- Definition: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Defines the extension authoring contract and the intended bundle-first default.
- Definition: extension-sdk/START_HERE.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/START_HERE.md) — Single-file agent handoff for creating and validating a bounded extension.
- Implementation: extension-sdk/manifest.json (https://github.com/MoveBigRocks/extension-sdk/blob/main/manifest.json) — Concrete extension manifest scaffold for scope, kind, and runtime behavior.
- Enforcement: extension-sdk/security/threat-model.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/security/threat-model.md) — Threat-model prompt used before activating custom extensions.

- Treat `extension.contract.json` as a checked-in proof artifact, not generated noise.
- For workspace-scoped admin UI, make instance-admin entrypoints work even without an active workspace session.
### Lint, verify, and inspect before rollout

Use a preview workspace first, then prove the runtime surface before treating the extension as ready.

```text
$ mbr extensions lint . --json
$ mbr auth login --url https://app.yourdomain.com
$ mbr workspaces list
$ mbr extensions verify . --workspace ws_preview --json
$ mbr extensions nav --instance --json
$ mbr extensions widgets --instance --json
$ mbr extensions skills list --id EXTENSION_ID
```

### Refresh the contract and prove the same surface again

When the extension changes, update the checked-in contract deliberately and rerun the same proof loop before rollout or rollback decisions.

```text
$ mbr extensions lint . --write-contract --json
$ mbr extensions verify . --workspace ws_preview --json
$ mbr extensions nav --instance --json
$ mbr extensions deactivate --id EXTENSION_ID
```


## Do not add backend process complexity unless the requirement truly needs it.

Bundle-first is the default because most workflow extensions do not need their own long-running service. Move into `service_backed` only when the extension needs custom endpoint handlers, event consumers, scheduled jobs, health checks, or an owned `ext_*` schema and migrations. The SDK now documents this as an explicit upgrade path rather than leaving authors to invent it.

Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
- Definition: docs/EXTENSION_ENDPOINT_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_ENDPOINT_MODEL.md) — Defines endpoint classes, core-owned routing, and concrete analytics and error-tracking endpoint patterns.
- Definition: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, review gates, and the requirement that extensions use the same outbox and event-bus pattern as core.
- Implementation: internal/platform/domain/extension.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension.go) — Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
- Implementation: internal/platform/domain/extension_runtime.go (https://github.com/MoveBigRocks/platform/blob/main/internal/platform/domain/extension_runtime.go) — Enforces that only service-backed `owned_schema` extensions can register owned schemas.
- Implementation: internal/infrastructure/stores/sql/extension_runtime_store.go (https://github.com/MoveBigRocks/platform/blob/main/internal/infrastructure/stores/sql/extension_runtime_store.go) — Stores extension package registrations and schema migration history in the shared core runtime store.

- If the requirement is mostly branded pages, workflow seeds, bundled skills, or admin UI, stay bundle-first.
- If the extension must ingest external traffic, process domain events, or own a richer data model, service-backed is justified.
- Service-backed does not remove the need for shared routing, shared auth, shared audit, or shared lifecycle controls.

## Activation should happen only after the threat model and review checklist are complete.

The extension security model is explicit about what must happen before a self-built extension leaves preview-only evaluation. The goal is not merely that the extension runs. The goal is that its trust boundaries and operational impact are reviewable.

Proof:
- Definition: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
- Definition: docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/INSTANCE_AND_EXTENSION_LIFECYCLE.md) — Defines when work belongs in the instance repo versus a separate extension repo.
- Contract: docs/EXTENSION_SECURITY_MODEL.md (https://github.com/MoveBigRocks/platform/blob/main/docs/EXTENSION_SECURITY_MODEL.md) — Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
- Implementation: extension-sdk/README.md (https://github.com/MoveBigRocks/extension-sdk/blob/main/README.md) — Shows the canonical public scaffold for bounded custom extension authoring.

- Threat-model the extension before activation.
- Record the review result in the instance-repo workflow before production rollout.
- Review public routes, external calls, permissions, secret needs, and failure behavior.
- Treat production activation as a human-visible decision even when an agent prepared the extension.