---
title: "Pilot Platform and DevOps"
canonical: "https://pilot.docs.mindburn.org/platform"
source: "pilot/docs/platform.md"
edit: "https://github.com/Mindburn-Labs/pilot/edit/main/docs/platform.md"
section: "platform"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-18"
checksum_sha256: "sha256:3032342368a2458c247a2dba5bac0edcaf4c1686bfbfdde1bbd77306b13f5b7e"
build_timestamp: "2026-05-24T13:42:52.320Z"
---
# Pilot Platform and DevOps

This page is the public platform map for Pilot. It is intentionally narrow:
deployment, operations, infrastructure prerequisites, and recovery paths. Product
workflow behavior belongs in `docs/architecture.md`, API details belong in
`docs/api.md`, and environment variables belong in `docs/env-reference.md`.

## Source truth

- Local and production deployment: `docs/self-hosting.md`, `infra/README.md`,
  `infra/digitalocean/README.md`, and `infra/docker/README.md`.
- Runtime operation and incident response: `docs/runbook.md`,
  `docs/degradation-matrix.md`, and `infra/monitoring/README.md`.
- Configuration: `docs/env-reference.md` and `.env.example`.
- Migration safety: `packages/db/migrations/README.md` and
  `scripts/check-migration-journal.ts`.

## Platform boundary

Pilot runs as a self-hosted stack: web UI, gateway, orchestrator, PostgreSQL,
pgvector, background jobs, optional Telegram surfaces, and optional HELM
governance. The platform docs should explain how to run, observe, back up, and
upgrade that stack. They should not claim managed hosting, production
availability, or customer deployment status unless a release artifact and smoke
evidence prove it.

## Public operator path

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        SelfHosting["Self-hosting guide"]
        Env["Environment reference"]
        Deploy["Infra and Docker docs"]
        Degrade["Degradation matrix"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        Runbook["Runbook"]
        Recovery["Recovery or rollback action"]
    end

    %% Operational Flow Edges
    SelfHosting --> Env
    Env --> Deploy
    Deploy --> Runbook
    Runbook --> Degrade
    Degrade --> Recovery

    %% Premium Styling Rules
    style Runbook fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
    style Recovery fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff
```


## Validation

Run `npm run docs:coverage && npm run docs:truth` before publishing platform
claims. Run `npm run compose:config` when changing Docker or DigitalOcean
deployment instructions.