---
import Base from '../layouts/Base.astro';
import Terminal from '../components/Terminal.astro';
import { Code } from 'astro:components';
import { WARDEN_ACTION } from '../utils/version.js';
---

<Base title="Config" description="Warden configuration reference">
  <h1>Config</h1>

  <p>Warden is configured via <code>warden.toml</code> in your repository root.</p>

  <Terminal showCopy={true}>
    <Code
      code={`version = 1

[[triggers]]
name = "Security Review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "security-review"`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h2>Triggers</h2>

  <p>Triggers map GitHub events to skills.</p>

  <dl>
    <dt>name</dt>
    <dd>Display name</dd>
    <dt>event</dt>
    <dd><code>pull_request</code>, <code>issues</code>, <code>issue_comment</code>, <code>schedule</code></dd>
    <dt>actions</dt>
    <dd>Event actions (required except for <code>schedule</code>)</dd>
    <dt>skill</dt>
    <dd>Skill name or path to run (see <a href="#skill-references">Skill References</a>)</dd>
    <dt>remote</dt>
    <dd>GitHub repository for remote skills: <code>owner/repo</code> or <code>owner/repo@sha</code></dd>
    <dt>model</dt>
    <dd>Model override (optional)</dd>
    <dt>maxTurns</dt>
    <dd>Max agentic turns per hunk (optional)</dd>
  </dl>

  <h3>Pull Request Actions</h3>

  <dl>
    <dt>opened</dt>
    <dd>PR created</dd>
    <dt>synchronize</dt>
    <dd>New commits pushed</dd>
    <dt>reopened</dt>
    <dd>PR reopened</dd>
    <dt>closed</dt>
    <dd>PR closed or merged</dd>
  </dl>

  <h2>Filters</h2>

  <p>Control which files are analyzed using glob patterns.</p>

  <dl>
    <dt>paths</dt>
    <dd>Files to include</dd>
    <dt>ignorePaths</dt>
    <dd>Files to exclude</dd>
  </dl>

  <Terminal showCopy={true}>
    <Code
      code={`[[triggers]]
name = "API Review"
event = "pull_request"
actions = ["opened", "synchronize"]
skill = "api-review"

[triggers.filters]
paths = ["src/api/**/*.ts"]
ignorePaths = ["**/*.test.ts"]`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h2>Output</h2>

  <p>Control how findings are reported.</p>

  <dl>
    <dt>failOn</dt>
    <dd>Minimum severity to fail: <code>critical</code>, <code>high</code>, <code>medium</code>, <code>low</code>, <code>info</code>, <code>off</code></dd>
    <dt>commentOn</dt>
    <dd>Minimum severity to post as comment</dd>
    <dt>maxFindings</dt>
    <dd>Maximum findings to report</dd>
    <dt>commentOnSuccess</dt>
    <dd>Post comment when no findings. Default: <code>false</code></dd>
  </dl>

  <Terminal showCopy={true}>
    <Code
      code={`[triggers.output]
failOn = "high"
commentOn = "medium"
maxFindings = 20`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h2>Defaults</h2>

  <p>Default settings inherited by all triggers. Individual triggers can override any setting.</p>

  <dl>
    <dt>model</dt>
    <dd>Model for all triggers</dd>
    <dt>maxTurns</dt>
    <dd>Max agentic turns per hunk. Default: 50</dd>
    <dt>defaultBranch</dt>
    <dd>Repository default branch (auto-detected)</dd>
    <dt>filters</dt>
    <dd>Default path filters</dd>
    <dt>output</dt>
    <dd>Default output settings</dd>
    <dt>chunking</dt>
    <dd>File processing configuration</dd>
  </dl>

  <Terminal showCopy={true}>
    <Code
      code={`[defaults]
model = "claude-sonnet-4-20250514"
maxTurns = 30

[defaults.filters]
ignorePaths = ["**/vendor/**", "**/node_modules/**"]

[defaults.output]
failOn = "high"
commentOn = "medium"`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h2>Chunking</h2>

  <p>Control how files are split for analysis. By default, Warden analyzes each hunk separately.</p>

  <h3>File Patterns</h3>

  <dl>
    <dt>per-hunk</dt>
    <dd>Analyze each diff hunk separately (default)</dd>
    <dt>whole-file</dt>
    <dd>Analyze entire file as one chunk</dd>
    <dt>skip</dt>
    <dd>Skip the file entirely</dd>
  </dl>

  <h3>Coalescing</h3>

  <p>Merge nearby hunks for better context.</p>

  <dl>
    <dt>enabled</dt>
    <dd>Enable hunk coalescing. Default: <code>true</code></dd>
    <dt>maxGapLines</dt>
    <dd>Max lines between hunks to merge. Default: 30</dd>
    <dt>maxChunkSize</dt>
    <dd>Target max chunk size in characters. Default: 8000</dd>
  </dl>

  <Terminal showCopy={true}>
    <Code
      code={`[defaults.chunking]

[[defaults.chunking.filePatterns]]
pattern = "**/pnpm-lock.yaml"
mode = "skip"

[[defaults.chunking.filePatterns]]
pattern = "**/migrations/*.sql"
mode = "whole-file"

[defaults.chunking.coalesce]
enabled = true
maxGapLines = 50
maxChunkSize = 10000`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h2>Schedule Triggers</h2>

  <p>Run on a cron schedule instead of PR events. Requires <code>filters.paths</code> to specify which files to scan.</p>

  <dl>
    <dt>issueTitle</dt>
    <dd>Title for the tracking issue. Default: "Warden: {'{name}'}"</dd>
    <dt>createFixPR</dt>
    <dd>Create PR with fixes when available. Default: <code>false</code></dd>
    <dt>fixBranchPrefix</dt>
    <dd>Branch prefix for fix PRs. Default: <code>warden-fix</code></dd>
  </dl>

  <Terminal showCopy={true}>
    <Code
      code={`[[triggers]]
name = "Weekly Security Scan"
event = "schedule"
skill = "security-review"

[triggers.filters]
paths = ["src/**/*.ts"]

[triggers.schedule]
createFixPR = true`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h2>Environment Variables</h2>

  <dl>
    <dt>WARDEN_ANTHROPIC_API_KEY</dt>
    <dd>Anthropic API key (required)</dd>
    <dt>WARDEN_MODEL</dt>
    <dd>Model override</dd>
    <dt>WARDEN_SKILL_CACHE_TTL</dt>
    <dd>Cache duration for unpinned remote skills. Default: 24h</dd>
  </dl>

  <h2 id="skill-references">Skill References</h2>

  <p>Skills can be referenced in multiple ways:</p>

  <Terminal showCopy={true}>
    <Code
      code={`# By name (resolved from .warden/skills/, .agents/skills/, .claude/skills/)
[[triggers]]
skill = "security-review"

# By relative path
[[triggers]]
skill = "./custom-skills/my-review"

# Remote skill (unpinned - checks for updates every 24h)
[[triggers]]
skill = "security-review"
remote = "getsentry/warden-skills"

# Remote skill (pinned to commit - cached permanently)
[[triggers]]
skill = "security-review"
remote = "getsentry/warden-skills@abc123def"`}
      lang="toml"
      theme="vitesse-black"
    />
  </Terminal>

  <h3>Resolution Order</h3>

  <ol>
    <li>Remote repository (if <code>remote</code> field is specified)</li>
    <li>Direct path (if skill contains <code>/</code>, <code>\</code>, or starts with <code>.</code>)</li>
    <li>Conventional directories (first match wins)</li>
  </ol>

  <h2>Skills</h2>

  <p>Skills define what Warden analyzes. They follow the <a href="https://agentskills.io">agentskills.io</a> specification.</p>

  <h3>Skill Directories</h3>

  <p>Warden discovers skills from these directories (first match wins):</p>

  <dl>
    <dt>.warden/skills/</dt>
    <dd>Warden-specific skills (highest priority)</dd>
    <dt>.agents/skills/</dt>
    <dd>Shared agent skills</dd>
    <dt>.claude/skills/</dt>
    <dd>Claude Code skills</dd>
  </dl>

  <h3>SKILL.md Format</h3>

  <p>Create a directory with a <code>SKILL.md</code> file:</p>

  <Terminal showCopy={true}>
    <Code
      code={`.agents/skills/
└── security-review/
    └── SKILL.md`}
      lang="text"
      theme="vitesse-black"
    />
  </Terminal>

  <p>The <code>SKILL.md</code> file uses YAML frontmatter for metadata and markdown for the prompt:</p>

  <Terminal showCopy={true}>
    <Code
      code={`---
name: security-review
description: Review code for security vulnerabilities
allowed-tools: Read Grep Glob
---

Review the code for security issues including:
- SQL injection
- XSS vulnerabilities
- Hardcoded secrets
- Insecure dependencies`}
      lang="markdown"
      theme="vitesse-black"
    />
  </Terminal>

  <dl>
    <dt>name</dt>
    <dd>Skill name (referenced by triggers)</dd>
    <dt>description</dt>
    <dd>Brief description</dd>
    <dt>allowed-tools</dt>
    <dd>Space-separated tool names (optional)</dd>
  </dl>

  <h3>Available Tools</h3>

  <p><code>Read</code>, <code>Grep</code>, <code>Glob</code>, <code>Edit</code>, <code>Write</code>, <code>Bash</code>, <code>WebFetch</code>, <code>WebSearch</code></p>

  <h2 id="workflow">Workflow</h2>

  <p>The workflow generated by <code>warden init</code>. Uncomment the GitHub App section for branded comments.</p>

  <Terminal showCopy={true}>
    <Code
      code={`name: Warden

permissions:
  contents: read
  pull-requests: write

on:
  pull_request:
    types: [opened, synchronize, reopened]

env:
  WARDEN_ANTHROPIC_API_KEY: \${{ secrets.WARDEN_ANTHROPIC_API_KEY }}

jobs:
  warden:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Uncomment for GitHub App (branded comments)
      # - uses: actions/create-github-app-token@v1
      #   id: app-token
      #   with:
      #     app-id: \${{ secrets.WARDEN_APP_ID }}
      #     private-key: \${{ secrets.WARDEN_PRIVATE_KEY }}

      - uses: ${WARDEN_ACTION}
        with:
          github-token: \${{ secrets.GITHUB_TOKEN }}
          # github-token: \${{ steps.app-token.outputs.token }}`}
      lang="yaml"
      theme="vitesse-black"
    />
  </Terminal>

  <h3>Action Inputs</h3>

  <dl>
    <dt>github-token</dt>
    <dd>GitHub token for posting comments. Default: <code>GITHUB_TOKEN</code></dd>
    <dt>anthropic-api-key</dt>
    <dd>Anthropic API key (falls back to <code>WARDEN_ANTHROPIC_API_KEY</code>)</dd>
    <dt>config-path</dt>
    <dd>Path to config file. Default: <code>warden.toml</code></dd>
    <dt>fail-on</dt>
    <dd>Minimum severity to fail the check</dd>
    <dt>comment-on</dt>
    <dd>Minimum severity to post comments</dd>
  </dl>
</Base>
