mkdocs.yml

site_name: OpenAdapt Docs
site_description: >-
  OpenAdapt is a demonstration compiler. Record a GUI workflow once and compile
  it into deterministic replay, re-resolve or propose governed repairs under
  drift, verify real effects, and halt rather than guess.
site_url: https://docs.openadapt.ai
# The header star/fork counter reads from repo_url. Point it at the flagship
# repo so it reflects the project's real GitHub traction, not this docs repo.
repo_url: https://github.com/OpenAdaptAI/OpenAdapt
repo_name: OpenAdaptAI/OpenAdapt
# Docs live in this (openadapt-maintenance) repo, not the code repo above, so
# the per-page "edit" link would 404. Disable it rather than point it wrong.
edit_uri: ''
copyright: >-
  © 2023–2026 OpenAdapt.AI and MLDSAI Inc. ·
  <a href="https://openadapt.ai">OpenAdapt.ai</a> &middot;
  <a href="https://blog.openadapt.ai">Blog</a> &middot;
  <a href="https://openadapt.ai/security">Security</a>

theme:
  name: material
  # Register the local overrides directory so overrides/main.html can inject the
  # PostHog snippet and shared analytics event layer via the extrahead block.
  custom_dir: overrides
  logo: assets/logo.svg
  favicon: assets/favicon.ico
  # Match the public site's local system stacks and avoid a third-party font
  # request on documentation pages. brand.css defines both Material font vars.
  font: false
  icon:
    repo: fontawesome/brands/github
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-sunny
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/weather-night
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.top
    - navigation.instant
    - navigation.tracking
    - navigation.indexes
    - toc.integrate
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - search.suggest
    - search.highlight

extra_css:
  - stylesheets/brand.css

plugins:
  - search

markdown_extensions:
  - toc:
      permalink: true
  - admonition
  - attr_list
  - md_in_html
  - def_list
  - tables
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.keys
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

extra:
  generator: false
  # Analytics. See ANALYTICS.md (repo root) for the full data-handling notes.
  # Google Analytics is env-driven; the fallback keeps the existing measurement
  # ID working when GOOGLE_ANALYTICS_KEY is unset. GA measurement IDs are public
  # (non-secret), so committing the fallback is fine.
  analytics:
    provider: google
    property: !ENV [GOOGLE_ANALYTICS_KEY, "G-CJ01Y19XJN"]
  # PostHog is read at BUILD time. When NEXT_PUBLIC_POSTHOG_KEY is unset (local
  # builds and CI), posthog_key is "" and overrides/main.html emits no PostHog
  # script at all. Reuses the same env var names and host as the marketing site
  # so every property reports into one PostHog project.
  posthog_key: !ENV [NEXT_PUBLIC_POSTHOG_KEY, ""]
  posthog_host: !ENV [NEXT_PUBLIC_POSTHOG_HOST, "https://us.i.posthog.com"]
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/OpenAdaptAI
    - icon: fontawesome/brands/discord
      link: https://discord.gg/yF527cQbDG
    - icon: fontawesome/solid/globe
      link: https://openadapt.ai
    - icon: fontawesome/solid/rss
      link: https://blog.openadapt.ai

# Top-level information architecture follows the five-section review:
# Start, Build, Operate, Security, Internals. Pages keep their existing
# on-disk paths (get-started/, concepts/, guides/, reference/, desktop/,
# ecosystem/); only their grouping and cross-links change.
nav:
  - Home: index.md
  - Start:
    - get-started/index.md
    - Your first workflow: get-started/first-workflow.md
    - What you get: get-started/what-you-get.md
    - Desktop application: desktop/install.md
  - Build:
    - concepts/index.md
    - All how-to guides: guides/index.md
    - The demonstration compiler: concepts/demonstration-compiler.md
    - The workflow-program IR: concepts/workflow-ir.md
    - Record your own app: guides/record-your-app.md
    - Induce a program from multiple traces: guides/induce-a-program.md
    - Multi-trace induction: concepts/multi-trace-induction.md
    - Run a workflow for each record: guides/data-driven-loops.md
    - Visualize a compiled program: concepts/program-visualizer.md
    - Parameters and secrets: guides/parameters-and-secrets.md
    - The capability ladder: concepts/capability-ladder.md
    - Write and enforce a policy: guides/policy-and-certification.md
    - Qualify a workflow: guides/qualify-a-workflow.md
    - Policy and certify: concepts/policy-and-certify.md
    - Effect verification: concepts/effect-verification.md
    - The identity gate: concepts/identity-gate.md
    - Qualification-owned entity language: concepts/qualification-owned-entity-language.md
  - Operate:
    - Run a deployment: guides/run-a-deployment.md
    - Read and audit run reports: guides/run-reports.md
    - Run outcomes and halt reasons: reference/run-outcomes.md
    - Human judgment in a workflow: concepts/human-judgment.md
    - Workflow catalog and halt map: guides/workflow-catalog.md
    - Attend a paused run and teach a correction: concepts/halt-learn-loop.md
    - Governed self-healing: concepts/self-healing.md
    - Durable runtime: concepts/durable-runtime.md
    - Deploy on-prem: guides/deploy-on-prem.md
    - The on-prem VLM appliance: concepts/vlm-appliance.md
    - The hosted option: guides/hosted.md
    - Connect to a cloud workspace: desktop/connect-to-cloud.md
    - Troubleshooting: guides/troubleshooting.md
  - Security:
    - Security and deployment review: guides/security-review.md
    - Account security and privileged access: guides/account-security.md
    - Qualification evidence: get-started/what-works-today.md
    - Fail-closed regulated execution: concepts/regulated-execution.md
    - Settings and policy governance: concepts/settings-governance.md
    - Security and data handling: guides/security-and-data-handling.md
    - PHI handling in one page: commercial/phi-handling.md
    - Vulnerability disclosure: commercial/vulnerability-disclosure.md
  - Commercial:
    - commercial/index.md
    - Qualification Sprint: commercial/qualification-sprint.md
    - Scope and prerequisite checklist: commercial/scope-checklist.md
    - Qualification report outline: commercial/qualification-report-outline.md
    - Acceptance matrix template: commercial/acceptance-matrix.md
    - Security packet: commercial/security-packet.md
    - Subprocessors and data retention: commercial/subprocessors.md
    - Deployment boundaries: commercial/deployment-boundaries.md
    - External Citrix zero-install brief: commercial/citrix-external-brief.md
    - OpenAdapt Execute private-pilot guide: commercial/oem-brief.md
    - Integrate OpenAdapt Execute: commercial/execute-api.md
    - Procurement FAQ: commercial/procurement-faq.md
  - Internals:
    - The substrate model: concepts/substrate-model.md
    - The deployment matrix: concepts/deployment-matrix.md
    - Backends, where it runs: concepts/backends.md
    - reference/index.md
    - openadapt flow CLI: reference/cli.md
    - Versions and compatibility: reference/compatibility.md
    - Deployment configuration: reference/deployment-config.md
    - The bundle format: reference/bundle-format.md
    - Configuration and env vars: reference/configuration.md
    - Glossary: reference/glossary.md
    - Package and repository lifecycle: ecosystem/index.md
    - Documentation source of truth: reference/documentation-governance.md
    - What's New: whats-new.md
    - Changelog: changelog.md
  - Blog ↗: https://blog.openadapt.ai
  - OpenAdapt.ai ↗: https://openadapt.ai