mkdocs.yml

site_name: Dev Health documentation
site_description: Task-oriented Dev Health documentation with the Full Chaos visual identity.
site_url: https://docs.fullchaos.dev
# repo_name: Full Chaos / Dev Health
# repo_url: https://github.com/full-chaos/dev-health-ops
# edit_uri: edit/main/docs/

docs_dir: docs
site_dir: .build/docs

theme:
  name: material
  logo: assets/fcd-simplified.png
  favicon: assets/fcd-simplified.png
  font: false
  features:
    - navigation.indexes
    - navigation.sections
    - navigation.path
    - navigation.top
    - navigation.tracking
    - toc.follow
    - search.suggest
    - search.highlight
    - content.action.edit
    - content.action.view
  palette:
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/weather-night
        name: Use dark theme
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/weather-sunny
        name: Use light theme

nav:
  - Documentation home: index.md
  - Context Fabric: context-fabric/index.md
  - Get started:
      - get-started/index.md
      - Choose a task: get-started/choose-a-task.md
      - Prerequisites: get-started/prerequisites.md
  - Use Dev Health:
      - use/index.md
      - Context and filters:
          - use/navigate/index.md
          - Scope and time: use/navigate/scope-and-time.md
          - Filters and comparisons: use/navigate/filters-and-comparisons.md
          - Data states: use/navigate/data-states.md
      - Investment:
          - use/investment/index.md
          - Investigate effort: use/investment/investigate-effort.md
          - Investment Mix: use/investment/investment-mix.md
          - Investment Flows: use/investment/investment-flows.md
          - Investment Expense: use/investment/investment-expense.md
          - Evidence: use/investment/follow-evidence.md
      - Delivery flow:
          - use/delivery-flow/index.md
          - PR Flow: use/delivery-flow/pr-flow.md
          - Quadrants: use/delivery-flow/quadrants.md
          - Review pressure: use/delivery-flow/review-pressure.md
      - Code and relationships:
          - use/code-and-relationships/index.md
          - Code Hotspots: use/code-and-relationships/code-hotspots.md
          - Work Graph: use/code-and-relationships/work-graph.md
      - Planning:
          - use/plan-and-improve/index.md
          - Completion Forecast: use/plan-and-improve/capacity-planning.md
          - Compare trends: use/plan-and-improve/compare-trends.md
          - Team conversations: use/plan-and-improve/team-conversations.md
      - AI workflows:
          - use/ai-workflows/index.md
          - AI Impact: use/ai-workflows/impact.md
          - AI Review Load: use/ai-workflows/review-load.md
          - AI Governance Risk: use/ai-workflows/risk.md
          - Ask what Ask Dev supports: use/ai-workflows/ask-dev-questions.md
          - Read an Ask Dev answer: use/ai-workflows/ask-dev-answers.md
      - Reports:
          - use/reports/index.md
          - Create or clone: use/reports/create-or-clone.md
          - Run and schedule: use/reports/run-and-schedule.md
          - Output and provenance: use/reports/read-output-and-provenance.md
      - Troubleshooting:
          - use/troubleshooting/index.md
          - No or incomplete data: use/troubleshooting/no-or-incomplete-data.md
          - Scope and filters: use/troubleshooting/scope-and-filters.md
          - Permissions and availability: use/troubleshooting/permissions-and-availability.md
          - Stale or delayed results: use/troubleshooting/stale-or-delayed-results.md
          - Report problems: use/troubleshooting/reports.md
  - Administer Dev Health:
      - admin/index.md
      - Workspace:
          - admin/workspace/index.md
          - Settings: admin/workspace/settings.md
      - Teams and access:
          - admin/teams-and-identities/index.md
          - Teams and repositories: admin/teams-and-identities/teams-and-repositories.md
          - Roles and access: admin/teams-and-identities/roles-and-access.md
      - Data sources:
          - admin/data-sources/index.md
          - GitHub: admin/data-sources/github.md
          - GitLab: admin/data-sources/gitlab.md
          - Jira Service Management: admin/data-sources/jira-atlassian.md
          - Incident response / PagerDuty: admin/data-sources/incident-response.md
          - Credential lifecycle: admin/data-sources/credential-lifecycle.md
      - Sync and coverage:
          - admin/sync-and-coverage/index.md
          - Status and freshness: admin/sync-and-coverage/status-and-freshness.md
          - Coverage: admin/sync-and-coverage/coverage.md
      - Security:
          - admin/security-and-audit/index.md
          - Credentials: admin/security-and-audit/credentials.md
          - Privacy and telemetry: admin/security-and-audit/privacy.md
      - Troubleshooting:
          - admin/troubleshooting/index.md
          - Authentication and roles: admin/troubleshooting/authentication-and-roles.md
          - Provider connections: admin/troubleshooting/provider-connections.md
          - Sync and coverage: admin/troubleshooting/sync-and-coverage.md
  - Install and operate:
      - operate/index.md
      - Plan:
          - operate/plan/index.md
          - Prerequisites: operate/plan/prerequisites.md
          - Capacity and sizing: operate/plan/capacity-and-sizing.md
      - Install:
          - operate/install/index.md
          - Local evaluation: operate/install/local-evaluation.md
          - Production: operate/install/production.md
          - Verify health: operate/install/verify-health.md
      - Configure:
          - operate/configure/index.md
          - Environment and secrets: operate/configure/environment-and-secrets.md
          - Databases and storage: operate/configure/databases-and-storage.md
          - Network and TLS: operate/configure/network-and-tls.md
          - Workers and schedules: operate/configure/workers-and-schedules.md
          - External services: operate/configure/external-services.md
      - Maintain:
          - operate/maintain/index.md
          - Upgrade: operate/maintain/upgrade.md
          - Backup and restore: operate/maintain/backup-and-restore.md
          - Decommission: operate/maintain/decommission.md
      - Run:
          - operate/run/index.md
          - Workers and jobs: operate/run/workers-and-jobs.md
          - Ingestion and backfills: operate/run/ingestion-and-backfills.md
          - Operational controls: operate/run/operational-controls.md
          - Ask Dev rollout: operate/run/ask-dev-rollout.md
      - Observe:
          - operate/observe/index.md
          - Health checks: operate/observe/health-checks.md
          - Logs: operate/observe/logs.md
          - Metrics and traces: operate/observe/metrics-and-traces.md
          - Dashboards and alerts: operate/observe/dashboards-and-alerts.md
      - Security:
          - operate/security/index.md
          - Production hardening: operate/security/hardening.md
      - Runbooks:
          - operate/runbooks/index.md
          - Ingestion failure: operate/runbooks/ingestion-failure.md
          - Worker or queue failure: operate/runbooks/worker-or-queue-failure.md
          - Database or migration failure: operate/runbooks/database-or-migration-failure.md
          - Provider authentication failure: operate/runbooks/provider-authentication-failure.md
          - Ask Dev web proxy or browser failure: operate/runbooks/ask-dev-web-proxy-or-browser-failure.md
          - Performance or rate limit: operate/runbooks/performance-or-rate-limit.md
          - Backup or restore failure: operate/runbooks/backup-or-restore-failure.md
          - Disaster recovery: operate/runbooks/disaster-recovery.md
  - Integrate and extend:
      - integrate/index.md
      - Customer Push:
          - integrate/customer-push/index.md
          - Supported boundary: integrate/customer-push/overview.md
          - Register a source: integrate/customer-push/register-source.md
          - Discover the schema: integrate/customer-push/schema-discovery.md
          - Submit records: integrate/customer-push/submit-records.md
          - Idempotency and retries: integrate/customer-push/idempotency-and-retries.md
          - Validation errors: integrate/customer-push/errors.md
          - Delivery observability: integrate/customer-push/observability.md
      - APIs:
          - integrate/api/index.md
          - GraphQL: integrate/api/graphql.md
          - Authentication: integrate/api/authentication.md
          - Automation: integrate/api/automation.md
      - Webhooks:
          - integrate/webhooks/index.md
          - Configure: integrate/webhooks/configure.md
          - Verify signatures: integrate/webhooks/verify-signatures.md
          - Retries and replay: integrate/webhooks/retries-and-replay.md
      - Build an integration:
          - integrate/build-an-integration/index.md
          - Provider integration: integrate/build-an-integration/provider.md
          - Data contracts: integrate/build-an-integration/data-contracts.md
          - Testing: integrate/build-an-integration/testing.md
      - Troubleshooting:
          - integrate/troubleshooting/index.md
          - Authentication: integrate/troubleshooting/authentication.md
          - Schema and validation: integrate/troubleshooting/schema-and-validation.md
          - Delivery and rate limits: integrate/troubleshooting/delivery-and-rate-limits.md
  - Reference:
      - reference/index.md
      - API:
          - reference/api/index.md
          - Authentication and authorization: reference/api/authentication.md
          - Errors, pagination, and limits: reference/api/errors-pagination-rate-limits.md
      - GraphQL:
          - reference/graphql/index.md
          - Schema and fields: reference/graphql/schema.md
          - Filters and scope: reference/graphql/filters.md
          - Nullability and errors: reference/graphql/nullability-and-errors.md
      - CLI: reference/cli/index.md
      - Configuration:
          - reference/configuration/index.md
          - Environment variables: reference/configuration/environment.md
          - Feature flags: reference/configuration/feature-flags.md
      - Schemas:
          - reference/schemas/index.md
          - Record kinds and enums: reference/schemas/record-kinds-and-enums.md
      - Data models:
          - reference/data-models/index.md
          - Work Graph: reference/data-models/work-graph.md
          - Investment: reference/data-models/investment.md
      - Metrics:
          - reference/metrics/index.md
          - Definitions: reference/metrics/definitions.md
          - Weighting and aggregation: reference/metrics/weighting-and-aggregation.md
      - Taxonomies:
          - reference/taxonomies/index.md
          - Investment: reference/taxonomies/investment.md
      - Limits and compatibility:
          - reference/limits-and-compatibility/index.md
          - Provider limits: reference/limits-and-compatibility/provider-limits.md
          - Version compatibility: reference/limits-and-compatibility/compatibility.md
      - Deprecations: reference/deprecations/index.md
  - Contribute:
      - contribute/index.md
      - Get started:
          - contribute/start/index.md
          - Repository map: contribute/start/repository-map.md
          - Development environment: contribute/start/development-environment.md
      - Architecture:
          - contribute/architecture/index.md
          - Platform: contribute/architecture/platform.md
          - Data and storage: contribute/architecture/data-and-storage.md
          - Stable contracts: contribute/architecture/contracts.md
          - Ask Dev v2 contracts: contribute/architecture/ask-dev-contracts-v2.md
          - Ask Dev subject preflight: contribute/architecture/ask-dev-subject-preflight.md
          - Ask Dev role readiness: contribute/architecture/ask-dev-role-readiness.md
      - Develop and test:
          - contribute/development/index.md
          - Commands: contribute/development/commands.md
          - Testing: contribute/development/testing.md
          - Fixtures and live validation: contribute/development/fixtures-and-live-validation.md
          - Migrations: contribute/development/migrations.md
          - Debugging: contribute/development/debugging.md
      - Review and release:
          - contribute/review-and-release/index.md
          - Pull requests: contribute/review-and-release/pull-requests.md
          - Releases and rollback: contribute/review-and-release/releases.md
      - Documentation:
          - contribute/documentation/index.md
          - Classify and place: contribute/documentation/classify-and-place.md
          - Write and review: contribute/documentation/write-and-review.md
          - Preview and validate: contribute/documentation/preview-and-validate.md
          - Content model: contribute/documentation/content-model.md
          - Authoring templates: contribute/documentation/templates.md
          - Editorial and accessibility style: contribute/documentation/style-guide.md
          - Representative reader tasks: contribute/documentation/reader-tasks.md
          - IA diagrams: contribute/documentation/ia-diagrams.md

plugins:
  - search

extra_css:
  - stylesheets/extra.css
  - stylesheets/home.css
  - stylesheets/home-sections.css
  - stylesheets/context-fabric.css
  - stylesheets/review-fixes.css

extra:
  generator: false
  social:
    - icon: fontawesome/solid/globe
      link: https://fullchaos.dev
      name: FullChaos Studios
    - icon: fontawesome/brands/github
      link: https://github.com/full-chaos/dev-health-ops
      name: Dev Health source

markdown_extensions:
  - admonition
  - attr_list
  - footnotes
  - md_in_html
  - toc:
      permalink: true
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.tabbed:
      alternate_style: true

copyright: >-
  © 2026 <a href="https://fullchaos.dev">FullChaos Studios</a> ·
  <a href="https://github.com/full-chaos/dev-health-ops">Dev Health</a> ·
  <a href="https://github.com/full-chaos/dev-health-ops/tree/main/docs">Documentation source</a>