Extension reference

Extensions add focused capability without reintroducing app sprawl.

Extensions are bounded capability slices on the shared base. The detailed reference below covers runtime shape, routing, events, storage, and review boundaries.

Read the public extensions page Read build guide

Agent-first route: Start at /agents, inspect /docs/cli, and drop into this page when you need proof, detail, or rollout guidance.

Agent-first route

Humans should usually delegate first-pass evaluation to an agent. Agents should start at /agents, use /docs/cli as the official product tour, and open /docs/graphql only when needed.

Agent-ready surface

Start with the CLI, not browser guesswork.

Preferred route: /agents, then /docs/cli, then /docs/graphql only when lower-level integration details matter.

$ mbr spec export --json
$ mbr auth whoami --json
$ mbr queues list --workspace ws_preview --json

Open GraphQL reference | Open schema.graphql

Bounded by core

Extensions rely on the shared system model rather than creating a separate one.

Proof

Definition docs/ARCHITECTURE.md Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
Definition 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 Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
Implementation extension-sdk/README.md Shows the canonical public scaffold for bounded custom extension authoring.

Runtime classes are explicit

Bundle and service-backed runtimes carry different storage, routing, and lifecycle implications.

Proof

Definition docs/ARCHITECTURE.md Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
Definition 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 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 Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
Implementation 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 Stores extension package registrations and schema migration history in the shared core runtime store.

Owned schema is available when needed

Service-backed extensions can own an `ext_*` PostgreSQL schema and migration history without leaking into core tables.

Proof

Definition docs/ARCHITECTURE.md Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
Definition 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 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 Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
Implementation 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 Stores extension package registrations and schema migration history in the shared core runtime store.

Pairs with security

Extension evaluation belongs beside the trust and deployment model.

Proof

Definition docs/EXTENSION_SECURITY_MODEL.md Requires extensions to use the same outbox and event-bus pattern as core whenever they publish or consume events.
Implementation internal/infrastructure/stores/shared/interfaces.go Defines the shared outbox and idempotency interfaces used for reliable event publishing and handling.
Implementation internal/infrastructure/stores/sql/analytics_db.go Shows the analytics extension using its own `ext_demandops_web_analytics` schema.
Implementation internal/infrastructure/stores/sql/error_monitoring_store.go Shows the error-tracking extension using its own `ext_demandops_error_tracking` schema.

Table of contents

Section map.

Jump directly to the part you need.

The extension model exists so domain depth can grow on top of a strong shared base. Why extend here Bundle and service-backed runtimes have different responsibilities. Runtime classes and storage Core owns external routing. Extensions declare endpoint classes. Endpoint classes and routing Extensions should use the same typed-event and outbox pattern as core. Events and outbox Public first-party extensions already show how different extension classes fit the model. Concrete extensions

Why extend here

The extension model exists so domain depth can grow on top of a strong shared base.

The key value is not merely that extensions are possible. The key value is that extensions inherit shared identity, routing, queues, cases, knowledge, audit, CLI access, and GraphQL access. That makes extension code smaller and makes evaluation easier for agents.

Proof bundle

Definition docs/ARCHITECTURE.md Defines extensions as bounded runtime classes attached to shared primitives, not disconnected product silos.
Definition 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 Defines trust classes, unsupported extension categories, review gates, and allowed runtime slices.
Implementation extension-sdk/README.md Shows the canonical public scaffold for bounded custom extension authoring.

Why not separate apps

Separate apps rebuild auth, routing, and work records over and over again. Bounded extensions reuse those layers instead.

Why agents care

Agents can inspect the same primitives, CLI verbs, and lifecycle states across core and extensions instead of learning a fresh control plane for each capability slice.

Runtime classes and storage

Bundle and service-backed runtimes have different responsibilities.

A bundle extension stays mostly declarative. A service-backed extension adds handlers, jobs, consumers, and extension-owned state while still living behind core-owned routing and lifecycle controls.

Proof bundle

Definition docs/ARCHITECTURE.md Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
Definition 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 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 Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
Implementation 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 Stores extension package registrations and schema migration history in the shared core runtime store.

Bundle runtime

Best for workflow extensions, admin pages, public pages, bundled skills, seeded knowledge, and declarative product slices that do not need their own backend process.

Service-backed runtime

Best when the extension truly needs custom handlers, event consumers, scheduled jobs, health checks, or its own bounded runtime process.

Owned `ext_*` schema

A service-backed `owned_schema` extension can register an extension-owned PostgreSQL schema and advance its migrations independently from core.

Shared runtime registry

Install state, schema version, and migration status remain visible in the shared runtime store rather than hiding in ad hoc deployment scripts.

Endpoint classes and routing

Core owns external routing. Extensions declare endpoint classes.

The extension endpoint model is deliberate. Extensions do not open arbitrary internet-facing ports on their own. They declare endpoint classes and core mounts them into approved path families with core-owned auth, rate limits, tracing, and audit boundaries.

Proof bundle

Definition docs/ARCHITECTURE.md Defines runtime classes, shared routing, event-driven integration, and extension-owned `ext_*` PostgreSQL schemas.
Definition 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 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 Defines runtime class, storage class, endpoint class, and manifest fields for extensions.
Implementation 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 Stores extension package registrations and schema migration history in the shared core runtime store.

Public and admin pages

Asset-backed public pages and admin pages mount through core under explicit path families.

Public ingest and webhooks

Service-backed analytics or compatibility-sensitive extensions can register public ingest or webhook endpoints through the same reviewed endpoint catalog.

Extension APIs and health

Service-backed extensions can expose extension APIs and internal health endpoints without becoming a separate router or trust domain.

Events and outbox

Extensions should use the same typed-event and outbox pattern as core.

When an extension publishes or consumes domain events, it should use the same outbox and event-bus model as core. That keeps retries, idempotency, auditability, and operational visibility consistent across first-party and self-built extensions.

Proof bundle

Definition docs/EXTENSION_SECURITY_MODEL.md Requires extensions to use the same outbox and event-bus pattern as core whenever they publish or consume events.
Implementation internal/infrastructure/stores/shared/interfaces.go Defines the shared outbox and idempotency interfaces used for reliable event publishing and handling.
Implementation internal/infrastructure/stores/sql/analytics_db.go Shows the analytics extension using its own `ext_demandops_web_analytics` schema.
Implementation internal/infrastructure/stores/sql/error_monitoring_store.go Shows the error-tracking extension using its own `ext_demandops_error_tracking` schema.

Typed event flows

Event publishers and consumers should be explicit and inspectable rather than hidden in private scripts or side channels.

Reliable delivery model

The shared outbox and idempotency interfaces provide the same reliability pattern core uses for durable follow-through.

Extension-owned data stays bounded

Analytics and error-tracking demonstrate that richer product slices can keep their own bounded data model without bypassing the shared base.

Concrete extensions

Public first-party extensions already show how different extension classes fit the model.

The site should not ask agents to imagine what an extension looks like. Use the public first-party extensions and the platform docs as concrete evidence for the model.

Proof bundle

Definition README.md Documents the first-party extensions repo, install refs, and release tag model.
Catalog catalog/public-bundles.json Machine-readable catalog for the free public first-party bundle set.
Release .github/workflows/public-bundles.yml Publishes the free public first-party bundle set to GHCR from the first-party extensions repo.
Definition extension-sdk/README.md Explains the bundle-first default and when to move into service-backed endpoints, jobs, consumers, and owned-schema migrations.
Definition extension-sdk/START_HERE.md Gives the local lint, verify, and sandbox lifecycle for a custom extension.
Definition docs/EXTENSION_ENDPOINT_MODEL.md Uses ATS, community feature requests, sales pipeline, web analytics, and error tracking as concrete endpoint and runtime examples.

ATS

ATS is a bundle-first, workspace-scoped product extension with careers assets, workflow seeds, and bundled agent skills.

Web analytics

Web analytics is the canonical example of a service-backed product extension with public ingest routes, admin pages, and an extension-owned analytics schema.

Error tracking

Error tracking is the canonical example of a service-backed extension with compatibility-sensitive ingest aliases, issue processing, and extension-owned bounded state.

Private workflow extensions

Customer-built private extensions can still stay on the same base when they follow the same runtime, review, and routing rules.

Move Big Rocks

Let agents inspect the CLI-first surface. Let humans decide trust, rollout, and boundaries.

Start from /agents, use /docs/cli as the official product tour, inspect /resources for source and proof, and review /security before making deployment or data-handling decisions.

Open /agents Open resources