Operations docs (docs/operations/) — Agent Instructions

Last Updated: 2026-06-10

Runbooks for production deployment, marketing landing + macOS installer releases, Garage v1 PDS/entitlements/support rollout, PDS account migration (MOOver), self-hosted installer troubleshooting (alpha), catalog vs blockstore capacity, and OAuth / PDS origin behavior. Not ADRs — keep high-level architecture in docs/architecture/.

Rules

• Mermaid: Use fenced ```mermaid blocks for topology and sequence diagrams. Registered in docs/.vitepress/plugins/ (VitePress 2 has no markdown.mermaid option).
• Linting: Run pnpm run lint:md before commit.
• Cross-links: Link to Getting started for local dev; link to ADRs for design rationale, not duplicate them.
• Sidebar: Add new pages to docs/.vitepress/config.mts under Operations and list them in 00-index.md.

When to update

• Gateway env vars, OAuth metadata shape, or edge routing change.
• Production static UI serving path changes.
• Loopback PDS / PUBLIC_BASE_URL pairing rules change in crates/auth.
• Catalog schema, outbox retention, chunking limits, or install layout paths change (catalog-vs-blockstore-storage.md).
• Landing deploy path, installer download hosting (droplet vs Spaces), or macOS release/signing flow changes (marketing-landing-and-macos-releases.md); keep root .env.example APPLE_* / SPACES_* keys in sync.
• Garage v1 phase gates, PDS/proxy launch order, or operator support flow change (garage-v1-rollout.md); keep ADR 37 / ADR 38 in sync when normative rules change.
• PDS droplet, authz proxy, or infra/pds stack change (pds-deployment.md, infra/pds/AGENTS.md).
• Customer app.* edge or infra/app stack change (app-deployment.md, infra/app/AGENTS.md).
• Managed Postgres or infra/data stack change (data-deployment.md, infra/data/AGENTS.md).
• Operator admin.* edge or infra/admin stack change (admin-deployment.md, infra/admin/AGENTS.md).