name: Documentation Review

on:
  pull_request:
    types: [opened, ready_for_review]
    branches: [develop, main]
  workflow_dispatch:
    inputs:
      branch:
        description: "Branch to review docs against"
        required: true
        default: "develop"

permissions:
  contents: write
  pull-requests: write
  issues: write
  id-token: write

jobs:
  # Runs automatically on PRs — compares PR diff against docs
  docs-check-pr:
    if: github.event_name == 'pull_request' && github.event.pull_request.draft == false && !startsWith(github.head_ref, 'docs/auto-sync')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.pull_request.head.ref }}

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          use_commit_signing: true
          prompt: |
            You are a documentation maintainer for the Lodge project (Urbit-Ethereum stack).

            Review PR #${{ github.event.pull_request.number }} and check whether any of the
            project's markdown documentation files have become stale or inconsistent with the
            code changes in this PR.

            Documentation files to check against:
            - docs/architecture.md — system design, contract state, layer descriptions
            - docs/inviters.md — inviter address mechanism, onboarding flow
            - docs/secrets.md — master tickets, passkeys, HD wallets, login flow
            - docs/url-resolution.md — lodge URL hostname and path encoding
            - docs/azimuth-workaround.md — block confirmation workaround
            - docs/state-principles.md — state management, transaction log design
            - docs/contracts.md — contract documentation
            - docs/servers.md — server documentation
            - docs/login.md — complete auth flow, login hooks, error handling
            - CLAUDE.md — project overview, commands, patterns, monorepo structure
            - client/CLAUDE.md — client-specific architecture and patterns
            - server/CLAUDE.md — server-specific architecture and patterns
            - README.md, client/README.md, server/README.md, contracts/README.md

            For each file, check whether any of the following changed in the PR diff:
            1. Function signatures, contract interfaces, or API endpoints that are documented
            2. State structures (Solidity structs, Zustand stores, type definitions)
            3. Environment variables or configuration referenced in docs
            4. CLI commands, dev scripts, or build steps
            5. Authentication or onboarding flows
            6. Routing, file paths, or monorepo structure

            RULES:
            - ONLY edit markdown files listed above. NEVER edit source code, tests, or configs.
            - ONLY fix concrete inconsistencies between the PR's code changes and existing docs.
            - Do NOT rewrite, restructure, or "improve" docs beyond what is needed for accuracy.
            - Do NOT add new sections or documentation. Only update existing content.
            - Keep edits minimal — change the fewest words necessary to make docs accurate.
            - Do NOT touch docs that are already consistent with the code changes.

            ACTIONS:
            If docs are already consistent:
            Post a short PR comment confirming docs are up to date. Keep it to 1-2 sentences.

            If docs need updating:
            1. Edit the stale markdown files directly to fix the inconsistencies.
            2. Commit the changes with a clear message like "docs: update X to reflect Y".
            3. Post a PR comment summarizing what you changed and why.
          claude_args: |
            --max-turns 60
            --model claude-sonnet-4-5-20250929
            --allowedTools "Read,Edit,Glob,Grep,Bash"

  # Manual trigger — reviews current branch state against docs
  docs-check-manual:
    if: github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
          ref: ${{ github.event.inputs.branch }}

      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          github_token: ${{ secrets.GITHUB_TOKEN }}
          use_commit_signing: true
          prompt: |
            You are a documentation maintainer for the Lodge project (Urbit-Ethereum stack).
            Review the "${{ github.event.inputs.branch }}" branch and fix any docs that are
            inconsistent with the code. Be efficient — don't read every file exhaustively.
            Focus on likely drift areas.

            WORKFLOW — follow these steps in order:
            1. Run "git log --oneline -20" to see recent changes.
            2. Read the key source files that changed recently (contracts, package.json, routes).
            3. Read each doc file and check for inconsistencies with the code.
            4. If any docs need fixing, make all edits FIRST, then do the git operations LAST.
            5. Create branch, commit, push, and open PR in a SINGLE chained command.

            Documentation files: docs/architecture.md, docs/inviters.md, docs/secrets.md,
            docs/url-resolution.md, docs/azimuth-workaround.md, docs/state-principles.md,
            docs/contracts.md, docs/servers.md, docs/login.md, CLAUDE.md,
            client/CLAUDE.md, server/CLAUDE.md, README.md, contracts/README.md

            Check for: changed function signatures, structs, env vars, CLI commands, auth flows,
            file paths, monorepo structure.

            RULES:
            - ONLY edit markdown files. NEVER edit source code, tests, or configs.
            - ONLY fix concrete inconsistencies. No rewrites or improvements.
            - Keep edits minimal.

            GIT OPERATIONS (do this last, in one step):
            If no changes needed: do nothing.
            If changes were made:
            git checkout -b docs/auto-sync-$(date +%Y-%m-%d) &&
            git add -A &&
            git commit -m "docs: sync documentation with current codebase" &&
            git push -u origin docs/auto-sync-$(date +%Y-%m-%d) &&
            gh pr create --base "${{ github.event.inputs.branch }}" --title "docs: sync documentation" --body "Automated docs sync — fixes inconsistencies found between code and documentation."
          claude_args: |
            --max-turns 100
            --model claude-sonnet-4-5-20250929
            --allowedTools "Read,Edit,Glob,Grep,Bash"
