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:
    # Neo-brutalist palette mirroring the product (https://nullrun.io):
    #   Light = cream paper (#F1EDDA) + machined ink (#1A1A1A) — mirrors
    #           globals.css :root --bg-base / --ink.
    #   Dark  = machined black (#1A1A1A) + neutral paper (#EBEBEB) —
    #           mirrors globals.css .dark.
    # The actual chrome / sidebar surface is painted by extra.css
    # (--bg, --sidebar-bg, --fg, --accent-flag, --accent-block,
    # --accent-allow, neo-brutalist variables).
    # The earlier 3-theme (default + slate + navy JS hack) layout was
    # retired on 2026-08-30 — navy was a helix-parity hack, not part of
    # the product design system.
    - 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 removed: top-level sections render in the left
    # sidebar (`navigation.sections`), not as header tabs. The 2-column
    # layout is sidebar (left, fixed) + content (center, max 750px).
    # The "On this page" TOC is collapsed by default — sections in
    # the left sidebar are numbered (1. / 2. / 2.1. …) and act as the
    # primary navigation; the right-side TOC appears only on long pages.
    #
    # navigation.expand removed 2026-08-30: top-level chapters (1, 2,
    # 3, 4, 5, 6) are now COLLAPSED by default — the sidebar acts as
    # a drop-down tree. Clicking a chapter title expands its sub-pages.
    # Material's stock `navigation.sections` toggle behaviour wires the
    # click; the CSS at `.md-nav__item--expanded > .md-nav__link::after`
    # rotates the chevron 90° on expand.
    #
    # navigation.tracking enabled: Material's bundle intercepts clicks
    # on internal links, fetches the next page in the background,
    # swaps the content + sidebar + footer in place, and pushes the
    # URL via history.pushState. The browser doesn't actually reload
    # anything — no flash of unstyled content, no header/menu-bar
    # re-paint, no scroll-position reset until the swap completes.
    # Sidebar links feel like SPA navigation.
    #
    # navigation.instant: scroll position resets to top immediately
    # when the new page swaps in (otherwise the user stays at the
    # old scroll position which is disorienting on a long page).
    #
    # navigation.instant.progress: show a thin progress strip under
    # the menu-bar while the next page is loading.
    #
    # navigation.footer removed — the footer is gone (override partial
    # renders empty), so prev/next pager isn't used. Navigation
    # between chapters happens through the left sidebar only.
    - navigation.sections
    - navigation.tracking
    - navigation.instant
    - navigation.instant.progress
    - navigation.top
    - navigation.indexes
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - toc.follow
  # 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
  - 1. Getting started:
      - 1.1. First agent in 15 minutes: getting-started/onboarding.md
      - 1.2. 5-minute tour: getting-started/tour.md
      - 1.3. Installation: getting-started/install.md
      - 1.4. Quickstart: getting-started/quickstart.md
      - 1.5. Configuration: getting-started/configuration.md
  - 2. Concepts:
      # Concepts are ordered by complexity: foundational abstractions
      # first (what NullRun is + how to talk to it), then the core
      # dimensions it operates on (cost, safety), then operational
      # concerns (workflows, observation, settings), then behavioural
      # concerns (failures, escalation, UI surfaces), then real-time /
      # advanced integration (push, tool sources, channels, rules), then
      # organisational and billing concepts at the bottom.
      - 2.1. Circuit breaker: concepts/circuit-breaker.md
      - 2.2. API keys: concepts/api-keys.md
      - 2.3. Budgets: concepts/budgets.md
      - 2.4. Sensitive tools: concepts/sensitive-tools.md
      - 2.5. Workflow context: concepts/workflow.md
      - 2.6. Tracing: concepts/tracing.md
      - 2.7. Policies: concepts/policies.md
      - 2.8. Tool policies: concepts/tool-policies.md
      - 2.9. Error handling: concepts/error-handling.md
      - 2.10. Human approval: concepts/human-approval.md
      - 2.11. Approvals (UI surface): concepts/approvals.md
      - 2.12. Control plane (WebSocket): concepts/control-plane.md
      - 2.13. MCP servers (Action sources): concepts/mcp-servers.md
      - 2.14. Notifications: concepts/notifications.md
      - 2.15. Alerts: concepts/alerts.md
      - 2.16. Team: concepts/team.md
      - 2.17. Billing & Plan: concepts/billing.md
      - 2.18. Organization: concepts/organization.md
      - 2.19. Profile settings: concepts/profile.md
  - 3. How-to:
      - 3.1. Protect a LangGraph agent: how-to/langgraph.md
      - 3.2. Use with OpenAI Agents: how-to/openai-agents.md
      - 3.3. Use CrewAI: how-to/crewai.md
      - 3.4. Use with FastAPI: how-to/fastapi.md
      - 3.5. LLM frameworks: how-to/llm-frameworks.md
      - 3.6. Set a hard cost cap: how-to/cost-cap.md
      - 3.7. Run multiple agents: how-to/multi-agent.md
      - 3.8. Multi-agent orchestration: how-to/multi-agent-orchestration.md
      - 3.9. Stream responses: how-to/streaming.md
      - 3.10. Manual cost / event tracking: how-to/custom-tracking.md
      - 3.11. CI / CD integration: how-to/ci-cd.md
  - 4. Reference:
      - 4.1. SDK API: reference/sdk-api.md
      - 4.2. HTTP API: reference/http-api.md
      - 4.3. Error codes: reference/errors.md
      - 4.4. Tool catalog: reference/llm-tool-catalog.md
  - 5. Compliance:
      - 5.1. Overview: compliance/index.md
      - 5.2. Geographic restrictions: compliance/geo-restrictions.md
      - 5.3. Sanctions screening: compliance/sanctions-screening.md
  - 6. Troubleshooting: troubleshooting.md

# No announcement banner — banner removed on 2026-08-30 per design
# decision. (Old: Plan-rebalance 2026-06-24 dismissible banner. Removed.)
extra:
  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

# Allow `docs/llms.txt` and `docs/llms-full.txt` to live in `docs/`
# (so mkdocs copies them verbatim into `site/`) without triggering the
# "exists in docs but not in nav" warning under --strict. They are
# agent-discovery artefacts, not nav pages.
#
# Note on /.well-known/llms.txt: the llmstxt.org spec specifies the
# discovery file at the SITE ROOT (`/llms.txt`), not at the
# `.well-known/` URI. MkDocs 1.6 has no built-in mechanism to copy
# dotfile directories into the build, and adding a plugin just for
# one alias file is overkill. The canonical /llms.txt is the spec-
# compliant location; /llms-full.txt is the full corpus.
#
# IMPORTANT — `docs/llms-full.txt` is a GENERATED corpus, not a hand-
# edited file. It is rebuilt from the Markdown source files by
# `infra/scripts/build-llms-full.ps1` after any content change in
# `docs/**`. The script must apply a redaction pass before emitting:
# it must strip any internal storage table names (audit_events,
# approval_rules, approvals, overdraft_used), internal class names
# (ApproximateBudget), internal service names (breaker-core,
# gate-core, prod-guard), and any SQL fragments. The source MD
# files are the contract — if the corpus diverges, regenerate it.
validation:
  nav:
    omitted_files: ignore