mkdocs.yml

site_name: NullRun Docs
site_description: Runtime decision layer for tool-using AI agents — user-facing documentation
site_url: https://docs.nullrun.io
repo_url: https://github.com/nullrunio/nullrun-docs
repo_name: nullrunio/nullrun-docs

# Brand assets live in docs/assets/images/. Mkdocs copies the entire
# docs/assets/ tree to site/assets/ at build time, so image links
# (`![alt](assets/images/foo.png)`) work without explicit registration.
extra_css:
  - stylesheets/extra.css
extra_javascript:
  - javascripts/extra.js

# Tier 3: Material template overrides (home.html + main.html).
# `home.html` replaces the default index layout with a custom hero +
# Mermaid architecture diagram + screenshot + CTA row.
# `main.html` extends base.html to inject OG / Twitter social-card
# metadata + the announcement banner slot.
theme:
  name: material
  custom_dir: overrides
  language: en
  logo: assets/images/logo.svg
  favicon: assets/images/favicon.png
  palette:
    # Brand is monochrome (cream + near-black); `primary: black`
    # keeps Material links/accents in family with the frontend's
    # --fg-default (#1A1A18). The cream/dark page surface itself
    # is painted by extra.css (Material exposes the CSS vars via
    # --md-primary-fg-color / --md-default-bg-color).
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: black
      accent: grey
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: white
      accent: grey
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - navigation.indexes
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - toc.follow
    # Tier 2 banner — set via `extra.announcement` block below.
    - announce.dismiss
  # Open Graph / Twitter card preview when a doc URL is pasted into
  # Slack / Twitter / Discord. `image` is the global fallback; per-page
  # overrides via `image:` front-matter on any Markdown file.
  social_cards:
    enabled: true
    image: assets/images/og-image.svg

nav:
  - Home: index.md
  - Getting started:
      - First agent in 15 minutes: getting-started/onboarding.md
      - Installation: getting-started/install.md
      - Quickstart: getting-started/quickstart.md
      - Configuration: getting-started/configuration.md
  - Concepts:
      - Circuit breaker: concepts/circuit-breaker.md
      - Budgets: concepts/budgets.md
      - Sensitive tools: concepts/sensitive-tools.md
      - Workflow context: concepts/workflow.md
      - Tracing: concepts/tracing.md
      - Control plane (WebSocket): concepts/control-plane.md
      - API keys: concepts/api-keys.md
      - Policies: concepts/policies.md
      - Tool policies: concepts/tool-policies.md
      - Human approval: concepts/human-approval.md
      - Error handling: concepts/error-handling.md
  - How-to:
      - Protect a LangGraph agent: how-to/langgraph.md
      - Use with OpenAI Agents: how-to/openai-agents.md
      - Use with FastAPI: how-to/fastapi.md
      - LLM frameworks:
          - Auto-instrumentation overview: how-to/auto-instrumented-frameworks.md
          - Anthropic: how-to/anthropic.md
          - Mistral: how-to/mistral.md
          - Gemini (Google GenAI): how-to/gemini.md
          - Cohere: how-to/cohere.md
          - AWS Bedrock: how-to/bedrock.md
          - LangChain: how-to/langchain.md
          - LlamaIndex: how-to/llama-index.md
          - CrewAI: how-to/crewai.md
          - AutoGen: how-to/autogen.md
          - Raw openai SDK: how-to/raw-openai.md
      - Set a hard cost cap: how-to/cost-cap.md
      - Run multiple agents: how-to/multi-agent.md
      - Multi-agent orchestration: how-to/multi-agent-orchestration.md
      - Stream responses: how-to/streaming.md
      - Manual cost / event tracking: how-to/custom-tracking.md
      - CI / CD integration: how-to/ci-cd.md
  - Reference:
      - SDK API: reference/sdk-api.md
      - HTTP API: reference/http-api.md
      - Error codes: reference/errors.md
      - Tool catalog: reference/llm-tool-catalog.md
  - Compliance:
      - Overview: compliance/index.md
      - Geographic restrictions: compliance/geo-restrictions.md
      - Sanctions screening: compliance/sanctions-screening.md
  - Troubleshooting: troubleshooting.md

# Tier 2 announcement — rendered as a dismissible top-of-page bar by
# the `announce.dismiss` Material feature. Empty / unset hides it.
extra:
  announcement: |
    <strong>Plan rebalance 2026-06-24</strong> — Lite/Starter/Growth/Scale caps
    were rebalanced and overage billing was disabled on every tier.
    See the <a href="/#plans">Plans table</a> for the new numbers.

  social:
    - icon: fontawesome/brands/github
      link: https://github.com/nullrunio/nullrun-docs
      name: GitHub
    - icon: fontawesome/solid/book
      link: https://docs.nullrun.io
      name: Documentation

# Markdown extensions — every one of these is load-bearing for the
# docs surface below. Don't remove without checking the pages.
markdown_extensions:
  - admonition
  - attr_list                  # {.class} / {key="value"} on images/links
  - md_in_html                 # parse Markdown inside <div> blocks
  - meta                       # front-matter (used by home.html + social cards)
  - tables
  - toc:
      # permalink: false — hides the `¶` after every heading in the
      # rendered UI. Headings still get stable anchors via
      # pymdownx.superfences / markdown.extensions; deep links from
      # other pages work because mkdocs still emits id="..." on the
      # heading tags. Only the visible `¶` glyph is suppressed.
      permalink: false
  - pymdownx.details
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      # Tier 1: inline architecture diagrams render in-browser via
      # the bundled Mermaid runtime (no server roundtrip). Used by
      # index.md and concepts/control-plane.md.
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
      slugify: !!python/object/apply:pymdownx.slugs.slugify
        kwds:
          case: lower
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets:
      check_paths: true

plugins:
  # Built-in search is sufficient for the doc size. If we later need
  # API reference indexing or cross-repo search, swap in mkdocs-material[full]
  # and add `plugins: [search, gen-files]` here.
  - search