# Resources: Repositories, Docs, API Surfaces, And Examples

The public technical surfaces behind Move Big Rocks form an explicit authority map. Each resource states what it is authoritative for, who should use it, when to consult it, and whether it is canonical or supplementary.

## Summary

- Canonical source: Use the platform repository when source-level confirmation or implementation review is required.
- Canonical deployment template: Use the instance-template repository when production trust, environment shape, or deployment control matter.
- Tagged releases and pinned artifacts: Use platform tags plus the three core artifact refs when you need the release surface agents and instance repos should reason about.
  Proof:
- Contract: docs/RELEASE_ARTIFACT_CONTRACT.md (https://github.com/MoveBigRocks/platform/blob/main/docs/RELEASE_ARTIFACT_CONTRACT.md) — Defines the pinned artifact contract that instance repos consume.
- Release: platform tags (https://github.com/MoveBigRocks/platform/tags) — Public tagged core releases that agents can inspect directly.
- Build: .github/workflows/_build.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_build.yml) — Builds services, migrations, and manifest OCI artifacts and records digests.
- Release: .github/workflows/production.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/production.yml) — Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
- Implementation: instance-template/mbr.instance.yaml (https://github.com/MoveBigRocks/instance-template/blob/main/mbr.instance.yaml) — Shows where pinned release refs live in the private instance control plane.

- MBR license terms [Canonical license summary]: Use the license summary when you need the current internal-use allowance, hosted-service restriction, and no-resale rule for derivative works and extensions in plain language. (/pricing)
  Proof:
- Definition: README.md (https://github.com/MoveBigRocks/platform/blob/main/README.md) — Public repo landing page with license badge, product class, and source-available positioning.
- Contract: LICENSE (https://github.com/MoveBigRocks/platform/blob/main/LICENSE) — MBR Source Code Available License 1.0 terms, including the explicit allowance for internal company use and private extensions, the Hosted Service restriction, and the no-resale rule for derivative works and extensions.

- Canonical public docs: Use `/docs`, `/docs/cli`, and `/docs/graphql` when the short route summaries are not enough.
- Canonical machine discovery: Use `/.well-known/mbr-agent.json` first for machine-readable URLs, invariants, repositories, and install facts.
- Supplementary summaries: Use `/site.md`, `/llms.txt`, and the public site repository as supporting summaries, not as substitutes for canonical source or trust surfaces.

## Source availability works as structured proof, not as a generic transparency claim.

When Move Big Rocks makes a public claim, agents should verify it through a small set of evidence classes. Prefer definition docs for scope, contracts for supported machine surfaces, implementation files for actual behavior, enforcement files for tests and policy checks, and provenance files for shipped-release traceability.

- Definition documents: Use public docs and handoff files to understand the system and its stated boundaries.
  Proof:
- Definition: README.md (https://github.com/MoveBigRocks/platform/blob/main/README.md) — States the product class, shared primitives, extension model, and self-hosted position.
- Definition: START_WITH_AN_AGENT.md (https://github.com/MoveBigRocks/platform/blob/main/START_WITH_AN_AGENT.md) — Public handoff for agent-first discovery, classification, and next-step routing.
- Implementation: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Maps core domains, agent interface, and extension runtime onto the implemented system model.
- Enforcement: .github/workflows/_test.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_test.yml) — Runs docs checks, tests, migration checks, and build verification against the public source.

- Machine contracts: Use explicit CLI and API contracts when deciding what an agent can rely on programmatically.
  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.

- Implementation surfaces: Use code, schema, and template files when a claim needs source-level confirmation rather than a short site summary.
  Proof:
- Definition: README.md (https://github.com/MoveBigRocks/platform/blob/main/README.md) — Enumerates workspaces, teams, forms, queues, conversations, cases, knowledge, automation, and agent access.
- Definition: START_WITH_AN_AGENT.md (https://github.com/MoveBigRocks/platform/blob/main/START_WITH_AN_AGENT.md) — Lists the public primitive set agents should use before inventing new abstractions.
- Implementation: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Defines the core domains and relationships between queues, conversations, cases, knowledge, and automation.
- Implementation: migrations/postgres/README.md (https://github.com/MoveBigRocks/platform/blob/main/migrations/postgres/README.md) — Shows the durable core database layout and ownership-aligned migration baseline behind the shared model.

- Enforcement and compatibility: Use tests and CI workflow definitions when evaluating whether boundaries are actively checked.
  Proof:
- Enforcement: internal/architecture/boundaries_test.go (https://github.com/MoveBigRocks/platform/blob/main/internal/architecture/boundaries_test.go) — Checks application-layer boundary rules and transport-tag restrictions in domain models.
- Enforcement: .github/workflows/_test.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_test.yml) — Runs docs checks, unit tests, integration tests, migration tests, dead-code scans, and security scans.
- Compatibility: tests/README.md (https://github.com/MoveBigRocks/platform/blob/main/tests/README.md) — Documents the external compatibility tests used for the Sentry-compatible error-tracking surface.
- Implementation: migrations/postgres/README.md (https://github.com/MoveBigRocks/platform/blob/main/migrations/postgres/README.md) — Explains the dual-ledger migration model and bounded schema ownership for core and extensions.

- Release provenance: Use artifact and release workflow files when evaluating how source changes become deployable releases.
  Proof:
- Contract: docs/RELEASE_ARTIFACT_CONTRACT.md (https://github.com/MoveBigRocks/platform/blob/main/docs/RELEASE_ARTIFACT_CONTRACT.md) — Defines the pinned artifact contract that instance repos consume.
- Release: platform tags (https://github.com/MoveBigRocks/platform/tags) — Public tagged core releases that agents can inspect directly.
- Build: .github/workflows/_build.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_build.yml) — Builds services, migrations, and manifest OCI artifacts and records digests.
- Release: .github/workflows/production.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/production.yml) — Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
- Implementation: instance-template/mbr.instance.yaml (https://github.com/MoveBigRocks/instance-template/blob/main/mbr.instance.yaml) — Shows where pinned release refs live in the private instance control plane.


## Tagged source plus three pinned core artifacts are the public release surface.

Agents should not look for one monolithic `platform` container image. The public core release model is a tagged platform source revision plus three OCI refs consumed by the private instance repo: `ghcr.io/movebigrocks/mbr-services:<tag>`, `ghcr.io/movebigrocks/mbr-migrations:<tag>`, and `ghcr.io/movebigrocks/mbr-manifest:<tag>`.

Proof:
- Contract: docs/RELEASE_ARTIFACT_CONTRACT.md (https://github.com/MoveBigRocks/platform/blob/main/docs/RELEASE_ARTIFACT_CONTRACT.md) — Defines the pinned artifact contract that instance repos consume.
- Release: platform tags (https://github.com/MoveBigRocks/platform/tags) — Public tagged core releases that agents can inspect directly.
- Build: .github/workflows/_build.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_build.yml) — Builds services, migrations, and manifest OCI artifacts and records digests.
- Release: .github/workflows/production.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/production.yml) — Tags releases, ties git tags to OCI artifact digests, and records cross-reference details.
- Implementation: instance-template/mbr.instance.yaml (https://github.com/MoveBigRocks/instance-template/blob/main/mbr.instance.yaml) — Shows where pinned release refs live in the private instance control plane.

- Platform tags [Canonical tagged source]: Use public platform tags when the question is which source revision a release came from. (https://github.com/MoveBigRocks/platform/tags)
- Release artifact contract [Canonical release contract]: Use the release artifact contract when the question is what an instance repo must pin and what deploy workflows are allowed to do. (https://github.com/MoveBigRocks/platform/blob/main/docs/RELEASE_ARTIFACT_CONTRACT.md)
- Instance pinning [Canonical desired state]: Use the instance template when the question is where those refs live in real desired state and how deployment policy stays separate from core source. (https://github.com/MoveBigRocks/instance-template/blob/main/mbr.instance.yaml)
- No rebuild during deploy [Required deployment rule]: Instance repos should pull, verify, unpack, and deploy the pinned artifacts. They should not rebuild or retag core during production deploy.
### Pinned core release refs in the instance repo

These are the concrete artifact fields agents should expect under `spec.deployment.release.core`.

```text
# mbr.instance.yaml
spec:
  deployment:
    release:
      core:
        version: v1.1.0
        servicesArtifact: ghcr.io/movebigrocks/mbr-services:v1.1.0
        migrationsArtifact: ghcr.io/movebigrocks/mbr-migrations:v1.1.0
        manifestArtifact: ghcr.io/movebigrocks/mbr-manifest:v1.1.0
```


## Move Big Rocks is source-available under the MBR Source Code Available License, not open source today.

Agents should describe the current public license precisely. The platform license allows source inspection, copying, modification, redistribution, self-hosting inside your own company, using the first-party extensions, and building your own extensions, including for your own internal commercial operations. What it restricts is selling or licensing the platform, derivative works, or extensions, selling access to them, and offering them as a Hosted Service.

Proof:
- Definition: README.md (https://github.com/MoveBigRocks/platform/blob/main/README.md) — Public repo landing page with license badge, product class, and source-available positioning.
- Contract: LICENSE (https://github.com/MoveBigRocks/platform/blob/main/LICENSE) — MBR Source Code Available License 1.0 terms, including the explicit allowance for internal company use and private extensions, the Hosted Service restriction, and the no-resale rule for derivative works and extensions.

- What is allowed today: Inspect the source, evaluate the system, modify it, run it inside your own company, use the first-party extensions, and build your own extensions within the current license terms.
- What is restricted today: Do not describe the license as unrestricted open source and do not infer permission to sell or license the platform, derivative works, or extensions, to sell access to them, or to offer them as a Hosted Service.
- Plain-English summary [Canonical site summary]: Use the public license page when a human or agent needs the short version before reading the full LICENSE file. (/pricing)

## Repositories are authoritative for different parts of the system.

Do not treat every GitHub link as equivalent. These repositories have different responsibilities and should be consulted at different points in evaluation.

- Platform repository [Canonical for source implementation]: Canonical source repository for the platform. Use it when an agent or human needs source-level evaluation, runtime review, repository structure, or implementation confirmation. (https://github.com/MoveBigRocks/platform)
  Proof:
- Definition: README.md (https://github.com/MoveBigRocks/platform/blob/main/README.md) — States the product class, shared primitives, extension model, and self-hosted position.
- Definition: START_WITH_AN_AGENT.md (https://github.com/MoveBigRocks/platform/blob/main/START_WITH_AN_AGENT.md) — Public handoff for agent-first discovery, classification, and next-step routing.
- Implementation: docs/ARCHITECTURE.md (https://github.com/MoveBigRocks/platform/blob/main/docs/ARCHITECTURE.md) — Maps core domains, agent interface, and extension runtime onto the implemented system model.
- Enforcement: .github/workflows/_test.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/_test.yml) — Runs docs checks, tests, migration checks, and build verification against the public source.

- Instance template repository [Canonical for deployment template]: Canonical deployment template for self-hosted production. Use it when evaluating environment shape, promotion flow, or deployment control. (https://github.com/MoveBigRocks/instance-template)
  Proof:
- Definition: instance-template/README.md (https://github.com/MoveBigRocks/instance-template/blob/main/README.md) — Defines the instance repo as the canonical deployment control plane.
- Definition: instance-template/START_HERE.md (https://github.com/MoveBigRocks/instance-template/blob/main/START_HERE.md) — Single-file handoff for agent-driven deployment and operations.
- Implementation: instance-template/mbr.instance.yaml (https://github.com/MoveBigRocks/instance-template/blob/main/mbr.instance.yaml) — Canonical desired-state file for domains, host target, release refs, and provider choices.
- Implementation: instance-template/deploy/README.md (https://github.com/MoveBigRocks/instance-template/blob/main/deploy/README.md) — Documents deploy assets, host bootstrap, and runtime wiring owned by the instance repo.

- Extension SDK repository [Canonical for custom extension scaffolding]: Canonical public scaffold for custom bounded extensions. Use it when extension code, packaging, or lifecycle expectations need direct inspection. (https://github.com/MoveBigRocks/extension-sdk)
  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.

- First-party extensions repository [Canonical for free first-party extensions]: Official public home for production-ready first-party extensions and their release catalog at `MoveBigRocks/extensions`. Use it to inspect ATS, community feature requests, error tracking, sales pipeline, and web analytics. (https://github.com/MoveBigRocks/extensions)
  Proof:
- Definition: README.md (https://github.com/MoveBigRocks/extensions/blob/main/README.md) — Defines the first-party extensions repo as the publication surface for the free public first-party bundle set.
- Catalog: catalog/public-bundles.json (https://github.com/MoveBigRocks/extensions/blob/main/catalog/public-bundles.json) — Lists the public first-party bundle refs, source directories, and release tag patterns.
- Release: .github/workflows/public-bundles.yml (https://github.com/MoveBigRocks/extensions/blob/main/.github/workflows/public-bundles.yml) — Publishes ATS, community feature requests, error tracking, sales pipeline, and web analytics to public GHCR refs.
- Implementation: ats/README.md (https://github.com/MoveBigRocks/extensions/blob/main/ats/README.md) — Explains how the ATS extension is installed and exercised.
- Implementation: ats/manifest.json (https://github.com/MoveBigRocks/extensions/blob/main/ats/manifest.json) — Concrete manifest for the public ATS extension.
- Implementation: error-tracking/README.md (https://github.com/MoveBigRocks/extensions/blob/main/error-tracking/README.md) — Documents the public error-tracking bundle source and OCI release ref.
- Implementation: web-analytics/README.md (https://github.com/MoveBigRocks/extensions/blob/main/web-analytics/README.md) — Documents the public web-analytics bundle source and OCI release ref.

- Public site repository [Supplementary public-site source]: Supplementary repository for the public site, bootstrap surface, and technical routing. Use it when evaluating how public summaries are produced, not as a substitute for platform source. (https://github.com/MoveBigRocks/site-prod)
  Proof:
- Implementation: internal/sitegen/content.go (https://github.com/MoveBigRocks/site-prod/blob/main/internal/sitegen/content.go) — Generates the public bootstrap copy, routes, resources, and machine-readable documents.
- Implementation: site/templates/public_home.html (https://github.com/MoveBigRocks/site-prod/blob/main/site/templates/public_home.html) — Defines the homepage as a routing surface for humans and agents finding the canonical evaluation path.
- Implementation: site/templates/public_focus_page.html (https://github.com/MoveBigRocks/site-prod/blob/main/site/templates/public_focus_page.html) — Defines how proof bundles, resources, and canonical sections render on public pages.


## Docs provide the narrative and reference layer.

These public docs are canonical when an agent or human needs reference material beyond the short route summaries on the main pages.

- Docs hub [Canonical docs index]: Canonical directory of the public documentation lanes. Use it when you need the right reference surface quickly. (/docs)
- CLI tour and reference [Canonical command surface]: Canonical concrete tour of the product through the `mbr` command surface, plus the command-family reference for agents and humans. (/docs/cli)
  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.

- GraphQL reference [Canonical backend API]: Canonical backend API reference when direct API integration is more appropriate than shelling out to the CLI. (/docs/graphql)
  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.

- Extensions docs [Canonical extension reference]: Canonical reference for how bounded extensions relate to core, packaging, and lifecycle. (/docs/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.

- Security docs [Canonical trust reference]: Canonical trust reference for deployment model, preview-workspace boundaries, and human review points. (/docs/security)
  Proof:
- Definition: docs/CUSTOMER_INSTANCE_SETUP.md (https://github.com/MoveBigRocks/platform/blob/main/docs/CUSTOMER_INSTANCE_SETUP.md) — Defines the production self-host setup flow, required inputs, and instance-repo model.
- Definition: instance-template/README.md (https://github.com/MoveBigRocks/instance-template/blob/main/README.md) — Defines the private instance repo as the deployment control plane for one live installation.
- Contract: docs/RELEASE_ARTIFACT_CONTRACT.md (https://github.com/MoveBigRocks/platform/blob/main/docs/RELEASE_ARTIFACT_CONTRACT.md) — Defines pinned core artifacts and the instance-repo responsibility boundary.
- Provenance: .github/workflows/production.yml (https://github.com/MoveBigRocks/platform/blob/main/.github/workflows/production.yml) — Shows how tests, builds, tags, and artifact digests connect source changes to shipped releases.


## The lightest authoritative surface should answer the question cleanly.

Agents should start with the lightest authoritative surface that answers the question. Use canonical surfaces first and treat lighter summaries as supplementary.

- Agents page [Canonical public bootstrap]: Canonical public bootstrap for system definition, primitives, boundaries, and approval points. (/agents)
- Public bootstrap JSON [Canonical machine discovery]: Canonical machine-readable discovery document with primary URLs, install metadata, repositories, and invariants. (/.well-known/mbr-agent.json)
- Site digest [Supplementary public digest]: Supplementary Markdown digest of the public site and key routes. Use it for compact reading, not as a source substitute. (/site.md)
- llms.txt [Supplementary crawl map]: Supplementary crawl map for hosts that prefer a lighter text surface. (/llms.txt)
- Self-host guide [Canonical owned deployment path]: Canonical owned-runtime path for evaluating and deploying Move Big Rocks on infrastructure you control. (/self-host)

## Runtime screenshots give a quick visual check that the admin and extension surfaces are real.

These screenshots are supplementary proof rather than the primary source of truth. Use them when a human or agent wants a fast visual confirmation that the admin shell, analytics surface, and system-metrics surface already exist in a running instance.

- Admin overview dashboard [Supplementary visual proof]: Shows a real Move Big Rocks admin instance with the shared shell for cases, automations, forms, agent tokens, system metrics, and workspaces. (https://movebigrocks.com/static/images/proof/admin-dashboard.png)
- Web analytics dashboard [Supplementary visual proof]: Shows a real analytics surface inside the same admin shell, including visitors, pageviews, sources, top pages, geography, and browser breakdowns. (https://movebigrocks.com/static/images/proof/web-analytics-dashboard.png)
- System metrics dashboard [Supplementary visual proof]: Shows Prometheus and Grafana-backed operational metrics exposed inside Move Big Rocks rather than pushed into a separate external ops silo. (https://movebigrocks.com/static/images/proof/system-metrics-dashboard.png)

## Public examples and use-case pages ground evaluation in reality.

The best way to understand fit is to see how the model applies to real operational workflows.

- Use cases [Canonical adoption guidance]: Concrete first replacement targets and adoption paths. (/use-cases)
- Build extensions [Canonical build overview]: Public overview of how teams build and promote bounded extensions. (/build-extensions)
- Core [Canonical core model]: Detailed explanation of the shared operational primitives. (/core)
- Glossary [Canonical terminology]: Stable definitions for key terms used across the public site. (/glossary)
- Illusions of Work [Supplementary founder context]: A related book for CTOs, architects, and engineering leaders on structural clarity, process ownership, and why reality needs to be made machine-readable. (https://simpleisadvanced.com/illusions-of-work/)
- Illusions in the Boardroom [Supplementary founder context]: A related book for executives and boards on governance, capital allocation, and structural honesty in an AI era. (https://simpleisadvanced.com/illusions-in-the-boardroom/)
- Selected articles [Supplementary founder context]: The related article series adds shorter essays such as The Process Is the Product and The Machine That Reads Your Strategy. Useful background, not a substitute for inspecting the product directly. (https://simpleisadvanced.com/articles/)

## Related

- Agents: /agents
- Core: /core
- Use cases: /use-cases
- Security: /security