mkdocs.yml

site_name: BaseHarbor
site_description: Secure, modular, self-hosted backend infrastructure for independent applications.
site_url: https://mcpdev80.github.io/baseharbor/
repo_url: https://github.com/mcpdev80/baseharbor
repo_name: mcpdev80/baseharbor
docs_dir: docs
site_dir: site
exclude_docs: |
  de/**
  internal/**

theme:
  name: material
  font: false
  language: en
  logo: brand/baseharbor-master-lockup.png
  favicon: brand/baseharbor.ico
  features:
    - navigation.instant
    - navigation.sections
    - navigation.path
    - navigation.top
    - toc.follow
    - search.suggest
    - search.highlight
    - content.code.copy
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

plugins:
  - search

markdown_extensions:
  - admonition
  - attr_list
  - md_in_html
  - pymdownx.details
  - pymdownx.superfences

extra_css:
  - brand/brand-tokens.css
  - stylesheets/baseharbor-docs.css

extra:
  alternate:
    - name: English
      link: /baseharbor/
      lang: en
    - name: Deutsch
      link: /baseharbor/de/
      lang: de

nav:
  - Home: index.md

  - Getting Started:
      - First application: tutorials/getting-started.md
      - Homelab: tutorials/homelab.md
      - Core resources: explanation/core-resources.md
      - CLI orientation: cli/index.md
      - Human CLI workflows: cli/human-workflows.md

  - Applications:
      - Application contract: explanation/application-contract.md
      - Application commands: cli/applications.md
      - Create and edit needs: how-to/application-needs.md
      - Core workflow: cli/core.md
      - Environments: how-to/environments.md
      - Backup & restore: how-to/backup-restore.md
      - Dynamic application secrets: how-to/dynamic-application-secrets.md

  - Targets:
      - Target concepts: explanation/targets.md
      - Target commands: cli/targets.md
      - Developer access: how-to/developer-access.md

  - Providers:
      - Provider model: explanation/providers.md
      - Provider commands: cli/providers.md
      - External / BYO providers: how-to/external-providers.md
      - PostgreSQL: how-to/postgres.md
      - Cache: how-to/cache.md
      - Durable key-value: how-to/durable-key-value.md
      - Document database: how-to/document-database.md
      - Messaging: how-to/messaging.md
      - Object storage: how-to/object-storage.md
      - Secrets: how-to/secrets.md
      - Observability: how-to/observability.md

  - Workspaces:
      - Workspace & development commands: cli/development.md

  - Development Stacks:
      - Backstage integration: how-to/backstage.md

  - Organization / Platform Configuration:
      - Concepts & distribution: explanation/organization-configuration.md
      - Resolution & independent policy: spec/organization-resolution-v1.md
      - Organization & policy commands: cli/organization-policy.md

  - Security / Trust:
      - Security model: explanation/security.md
      - Authentication: explanation/authentication.md
      - Security & trust commands: cli/security-trust.md
      - Extension artifact trust: spec/extension-artifact-trust-v1.md

  - Operations:
      - Troubleshooting: troubleshooting/index.md
      - Errors: reference/errors.md

  - Automation / Agents:
      - Automation commands: cli/automation-agents.md
      - MCP / agent interface: reference/mcp.md
      - CLI / machine coverage: reference/cli-machine-coverage.md
      - Machine operation recipes: how-to/machine-operations.md
      - Machine Interface v1: spec/machine-interface-v1.md
      - Protected Machine HTTP v1: spec/machine-http-v1.md
      - Runtime Explorer v1: spec/runtime-explorer-v1.md

  - Reference:
      - Public contracts: reference/public-contracts.md
      - Platform support: reference/platform-support.md
      - Complete command index: cli/command-index.md
      - CLI reference: reference/cli.md
      - Global options: cli/global-options.md
      - Shell & UX: cli/shell-ux.md
      - Manifest: reference/manifest.md
      - Application secret API: reference/application-secret-api.md
      - Authentication & API errors: reference/authentication-and-api-errors.md
      - Backup & restore: reference/backup-and-restore.md
      - PostgreSQL & migrations: reference/postgresql-and-migrations.md
      - Compose runtime: reference/runtime-compose.md
      - Runtime Resource API: reference/runtime-resource-api.md
      - Runtime secret broker: reference/runtime-secret-broker.md
      - Secrets & OpenBao: reference/secrets-and-openbao.md
      - Runtime Provider Contract v1: spec/runtime-provider-contract-v1.md
      - Runtime Provider Conformance v1: spec/runtime-provider-conformance-v1.md
      - Public provider conformance v1: spec/provider-conformance-v1.md
      - Delivery Provider Contract v1: spec/delivery-provider-contract-v1.md

  - Architecture:
      - System architecture: explanation/architecture.md
      - Workload sources: explanation/workload-sources.md

  - Developer:
      - Contributing: https://github.com/mcpdev80/baseharbor/blob/develop/CONTRIBUTING.md
      - Development guidelines: DEVELOPMENT_GUIDELINES.md
      - Documentation style: STYLE_GUIDE.md
      - Release requirements: development/v0.4.23-release-requirements.md
      - Pre-release readiness: development/pre-release-readiness.md
      - Architecture decisions: decisions/index.md
      - Specifications:
          - Overview: spec/README.md
          - Application Contract v1: spec/application-contract-v1.md
          - Provider Contract v1: spec/provider-contract-v1.md
          - Development Extension v1: spec/development-extension-v1.md
          - Reconciliation v1: spec/reconciliation-v1.md
          - Machine Interface v1: spec/machine-interface-v1.md
          - Protected Machine HTTP v1: spec/machine-http-v1.md
          - Runtime Explorer v1: spec/runtime-explorer-v1.md
          - Audit & Evidence v1: spec/audit-evidence-v1.md
          - Security invariants: spec/security-invariants.md
          - Input resolution: spec/input-resolution.md
          - Control-plane runtime: spec/control-plane-runtime.md
          - Application Runtime Broker: spec/application-runtime-broker.md
          - Application runtime identity: spec/application-runtime-identity.md
          - Runtime broker security: spec/runtime-secret-broker-security.md
          - Standards-first contracts: spec/standards-first.md
          - Standards matrix: spec/standards-matrix.md

  - Project:
      - Roadmap: roadmap.md
      - Release notes: releases/index.md
      - Release reference: reference/releases.md