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).
    # There are two colour schemes, `default` and `slate`, and the
    # choice between them is driven by the OS preference below. The
    # theme picker in extra.js §1 lets a reader override it.
    - 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:
    # Top-level chapters 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.
    #
    # Chapters are collapsed by default, so the sidebar is a drop-down
    # tree: clicking a chapter title expands its sub-pages. The title
    # is the toggle, and two things in extra.css make that work —
    # `pointer-events: auto` on the section link, which Material
    # otherwise sets to `none`, and a `::after` chevron whose rotation
    # keys off `.md-nav__item--section > .md-nav__toggle:checked ~`,
    # the checkbox Material expands the chapter from.
    #
    # navigation.indexes is off: it promotes a section's first page to
    # the section heading, which both drops that page from the chapter
    # list (losing "1.1" and "5.1" from the sidebar) and turns that
    # chapter's title into a link instead of a toggle. Every chapter
    # has to behave the same way, so no section gets an index page.
    #
    # 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
    - search.suggest
    - search.highlight
    - content.code.copy
    - content.code.annotate
    - content.tabs.link
    - content.tooltips
    - content.action.edit
    - toc.follow
  # Open Graph / Twitter card preview when a doc URL is pasted into
  # Slack / Twitter / Discord.
  #
  # NOTE: `social_cards` is an **Insiders-only** theme option. On the
  # open-source build it is accepted without error and emits nothing —
  # it is not what puts the card on a link preview. The tags are
  # written by hand in `overrides/main.html` (`og:title`,
  # `og:description`, `og:type`, `og:url`, `og:image`, `twitter:*`),
  # which also honours per-page `image:` front matter. This block is
  # kept only so an Insiders build picks the same default image.
  social_cards:
    enabled: true
    image: assets/images/og-image.png

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. Decision model:
      # What the gate is and what it enforces. This is the mental
      # model a reader needs before anything else — the breaker, the
      # policy types, the rules inside them, and the credential that
      # talks to the gateway.
      - 2.1. Circuit breaker: concepts/circuit-breaker.md
      - 2.2. Policies: concepts/policies.md
      - 2.3. Tool policies: concepts/tool-policies.md
      - 2.4. Sensitive tools: concepts/sensitive-tools.md
      - 2.5. API keys: concepts/api-keys.md
  - 3. Cost & safety:
      # The two dimensions the gate actually bounds — how much an
      # agent may spend, and what happens when it hits that limit or
      # breaks a rule. Both are cost/enforcement concepts and are
      # read together.
      - 3.1. Budgets: concepts/budgets.md
      - 3.2. Human approval: concepts/human-approval.md
  - 4. Runtime:
      # What a protected run looks like at runtime: the unit cost binds
      # to, the shapes of an execution, what happens when it fails,
      # and how an operator steers a live agent.
      - 4.1. Workflow context: concepts/workflow.md
      - 4.2. Tracing: concepts/tracing.md
      - 4.3. Error handling: concepts/error-handling.md
      - 4.4. Control plane (WebSocket): concepts/control-plane.md
      - 4.5. MCP servers (Action sources): concepts/mcp-servers.md
  - 5. Organization:
      # The surfaces a team works in once the agent is wired up:
      # approvals, notifications, alerts, membership, billing, and the
      # per-user settings. None of these change the enforcement
      # contract, so they sit apart from chapters 2–4.
      - 5.1. Approvals (UI surface): concepts/approvals.md
      - 5.2. Notifications: concepts/notifications.md
      - 5.3. Alerts: concepts/alerts.md
      - 5.4. Team: concepts/team.md
      - 5.5. Billing & Plan: concepts/billing.md
      - 5.6. Organization: concepts/organization.md
      - 5.7. Profile settings: concepts/profile.md
  - 6. How-to:
      - 6.1. Protect a LangGraph agent: how-to/langgraph.md
      - 6.2. Use with OpenAI Agents: how-to/openai-agents.md
      - 6.3. Use CrewAI: how-to/crewai.md
      - 6.4. Use with FastAPI: how-to/fastapi.md
      - 6.5. LLM frameworks: how-to/llm-frameworks.md
      - 6.6. Set a hard cost cap: how-to/cost-cap.md
      - 6.7. Run multiple agents: how-to/multi-agent.md
      - 6.8. Multi-agent orchestration: how-to/multi-agent-orchestration.md
      - 6.9. Stream responses: how-to/streaming.md
      - 6.10. Manual cost / event tracking: how-to/custom-tracking.md
      - 6.11. CI / CD integration: how-to/ci-cd.md
  - 7. Reference:
      - 7.1. SDK API: reference/sdk-api.md
      - 7.2. Decorators & extractors: reference/decorators.md
      - 7.3. HTTP API: reference/http-api.md
      - 7.4. Error codes: reference/errors.md
      - 7.5. Tool catalog: reference/llm-tool-catalog.md
      - 7.6. Glossary: glossary.md
  - 8. Compliance:
      - 8.1. Overview: compliance/index.md
      - 8.2. Data handling & vendor review: compliance/data-handling.md
  - 9. Operations:
      - 9.1. Troubleshooting: troubleshooting.md
      - 9.2. Performance & limits: operations/performance.md
      - 9.3. Framework & ecosystem positioning: operations/framework-positioning.md
      # Changelog sits at the end of the reading order, not inside a
      # chapter: it is the one page a reader arrives at by intent rather
      # than by following the narrative, and it is the only page allowed
      # to describe how the API changed over time. Everything else in the
      # nav describes the current state.
      - 9.4. Changelog: changelog.md

# The announcement-banner slot in overrides/main.html is intentionally
# left empty — the design has no banner surface.
#
# `extra.social` is deliberately unset, so the social plugin renders no
# badge links in the footer. That footer is an empty override anyway.
#
# Unsetting it was originally credited with silencing a 404 on
# `api.github.com/repos/<repo>/releases/latest` on every page load —
# it does not, and the request kept firing. The real source is the
# theme core: `partials/nav.html` renders a repository link carrying
# `data-md-component="source"`, and the bundle keys a
# repository-facts fetch (releases/latest + repo stars/forks) off
# that attribute whenever `config.repo_url` is set. `overrides/
# partials/source.html` drops the attribute, which is what actually
# stopped the 404. See the comment in that file.
#
# `config.repo_url` itself stays set — it also drives the GitHub
# button in the menu-bar and the page-level "Edit this page" action.
extra: {}

# 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: true — every heading carries a real `<a class="headerlink">`
      # pointing at its own `id`, so a reader can right-click → "copy link
      # to section" on any heading, and the browser's URL bar fills in
      # when they click one. With `false` the `id` is still emitted (deep
      # links from other pages keep working) but there is no link to copy.
      #
      # The glyph itself stays hidden until the heading is hovered or the
      # link is keyboard-focused — see `.headerlink` in extra.css §7. That
      # keeps the resting page free of `¶` marks while making the anchor
      # discoverable on interaction, which is the trade the previous
      # `permalink: false` gave up entirely.
      permalink: true
  - pymdownx.details
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences:
      # Inline architecture diagrams render in-browser via the Mermaid
      # runtime vendored at docs/javascripts/mermaid.min.js and driven
      # by the loader in docs/javascripts/extra.js (§6).
      #
      # The fence class is `nr-mermaid`, NOT Material's stock
      # `mermaid`. Material's bundle carries its own Mermaid
      # integration that claims every `.mermaid` node, strips the
      # class, and lazily fetches the runtime from unpkg.com — which
      # the site CSP (overrides/main.html, `script-src 'self'`) blocks.
      # That left every diagram on the site rendering as a raw code
      # block. Owning the class keeps a single renderer: ours.
      custom_fences:
        - name: mermaid
          class: nr-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` and `line_spans` are OFF deliberately.
      #
      # Both options exist to serve `content.code.annotate`: the fenced
      # `(!)` annotation syntax pairs a numbered callout with a line in
      # the block, and these two options are what give each line the id
      # and the jump target the callout links to. There is not a single
      # annotation in the docs — 40 code blocks, zero callouts — so what
      # the options actually bought was an empty `<a
      # class="__codelineno">` anchor plus a `<span id="__span-N-M">`
      # wrapper around every line of every block, with no CSS in
      # extra.css targeting either class. That is ~1,100 empty anchors
      # and ~1,100 extra spans in the DOM for a feature nothing uses.
      #
      # If annotations are added later, turn both back on and keep
      # `content.code.annotate` in `features` (it is already there) —
      # the two halves have to land together or the callouts link to
      # nothing.
      #
      # `pygments_lang_class: true` stays: that one is what lets
      # extra.css style a block by language (`.language-python`, and
      # the diff/error callouts below).
      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.
  #
  # The print edition is kept out of the index by `search: {exclude:
  # true}` in its own front matter, not by a plugin option — this
  # Material version's search plugin has no `exclude:` config key, and
  # adding one only warns under --strict. The front-matter flag is
  # emitted by infra/scripts/build-print.py, so it survives every
  # regeneration of print.md.
  - 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` and `docs/print.md` are GENERATED
# artefacts, not hand-edited files. Both are rebuilt from the Markdown
# sources by a script in `infra/scripts/`, after any content change in
# `docs/**`:
#
#   python infra/scripts/build-llms-full.py   # -> docs/llms-full.txt
#   python infra/scripts/build-print.py       # -> docs/print.md
#   python infra/scripts/build-print.py --check   # CI staleness check
#
# Both read the page list from the `nav:` tree above, so a page added
# or moved here reaches both artefacts without editing a second list.
#
# The corpus build enforces a no-internals rule — internal storage
# table names, internal service names, internal class names, ADR
# references, and SQL fragments must not appear — by *failing* rather
# than by substituting the tokens away. Rewriting them would let the
# corpus drift from the Markdown it claims to mirror and would leave
# half-sentences behind; a named failure points at the source page that
# needs the edit. The storage-table half of the rule is waived for
# `compliance/data-handling.md`, the vendor security-review page, which
# names the fields it stores on purpose.
validation:
  nav:
    omitted_files: ignore