# The docs checked against the code by Claude Code sessions, one per page,
# following the docs skill's audit job (harness/docs-audit.md). What `docs`
# checks is links and diagrams; this is whether the pages still say what
# the code does. Each run costs model usage, so it never runs on a push or
# a pull, only when the owner asks for it by name:
#
#   knotless rerun knotless://chadtmiller.com/knotless --ref refs/heads/main \
#     --workflow docs-audit [-e PAGES="design/storage.md reference/cli.md"] \
#     [-e AUDIT_MODEL=...]
#
# PAGES names pages under docs/, every design and reference page by
# default. The report is the end of the log, a section per page: what
# it says wrongly, what it leaves out, and code that looks like a bug.
# The check passes whatever the pages say, and fails only when a page
# could not be audited. The sessions read; they change nothing.
#
# Credentials as scenarios.yml's: ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN,
# or OPENROUTER_API_KEY, used first when granted.
image: node:24.22.1
on:
  asked: {refs: [refs/heads/main]}
secrets: [ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, OPENROUTER_API_KEY]
cache: [/opt/claude]
env:
  PAGES: >-
    design/README.md design/storage.md design/gateway.md design/access.md
    design/identity.md design/collaboration.md design/merge-queue.md
    design/runner.md design/serve.md design/security.md
    reference/cli.md reference/api.md reference/mcp.md
    reference/workflows.md reference/runner-internals.md
steps:
  - name: claude
    run: |
      [ -x /opt/claude/bin/claude ] || npm install -g --prefix /opt/claude --no-audit --no-fund @anthropic-ai/claude-code
      /opt/claude/bin/claude --version
  - name: audit
    # Three pages at a time (harness/docs-audit.sh), each a session of up
    # to 20 minutes.
    timeout: 120
    run: |
      export PATH=/opt/claude/bin:$PATH
      # OpenRouter speaks Claude Code's own protocol; the Anthropic key
      # must be empty, not unset, or it is tried first.
      if [ -n "${OPENROUTER_API_KEY:-}" ]; then
        export ANTHROPIC_BASE_URL=https://openrouter.ai/api ANTHROPIC_AUTH_TOKEN=$OPENROUTER_API_KEY ANTHROPIC_API_KEY=
      fi
      bash harness/docs-audit.sh $PAGES