update-docs.yml

name: Auto-update Documentation

on:
  pull_request:
    types: [closed]

jobs:
  update-docs:
    # Only run when a non-bot PR is actually merged. Skipping mintlify[bot]'s own
    # merged docs PRs prevents a generate -> auto-merge -> generate loop.
    if: github.event.pull_request.merged == true && github.event.pull_request.user.login != 'mintlify[bot]'
    runs-on: ubuntu-latest

    steps:
      - name: Get PR details
        id: pr_details
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          PR_DIFF=$(gh api \
            -H "Accept: application/vnd.github.v3.diff" \
            /repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }})

          FILES_CHANGED=$(gh api \
            /repos/${{ github.repository }}/pulls/${{ github.event.pull_request.number }}/files \
            --jq '[.[] | .filename] | join(", ")')

          echo "pr_diff<<EOF" >> $GITHUB_OUTPUT
          echo "$PR_DIFF" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

          echo "files_changed=$FILES_CHANGED" >> $GITHUB_OUTPUT

      - name: Call Mintlify Agent API
        uses: actions/github-script@v8
        env:
          MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
          PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_TITLE: ${{ github.event.pull_request.title }}
          PR_URL: ${{ github.event.pull_request.html_url }}
          PR_BODY: ${{ github.event.pull_request.body }}
          PR_DIFF: ${{ steps.pr_details.outputs.pr_diff }}
          FILES_CHANGED: ${{ steps.pr_details.outputs.files_changed }}
        with:
          script: |
            const { owner, repo } = context.repo;
            const projectId = process.env.PROJECT_ID;
            const apiKey = process.env.MINTLIFY_API_KEY;

            if (!projectId || !apiKey) {
              core.setFailed('Missing MINTLIFY_PROJECT_ID or MINTLIFY_API_KEY secrets');
              return;
            }

            const prBody = process.env.PR_BODY || 'No description provided';
            const userMessage = [
              `You are a documentation maintainer for ${owner}/${repo}. This is a monorepo: application code and documentation live in the same repository. All documentation files are under the \`docs/\` directory (Mintlify config at \`docs/docs.json\`). Scope every edit to \`docs/\` only — do not modify application code. Open the documentation PR against this same repository (${owner}/${repo}).`,
              ``,
              `## Merged PR Details`,
              `- **PR**: #${process.env.PR_NUMBER} — ${process.env.PR_TITLE}`,
              `- **URL**: ${process.env.PR_URL}`,
              `- **Files Changed**: ${process.env.FILES_CHANGED}`,
              ``,
              `## PR Description`,
              prBody,
              ``,
              `## Code Changes (Diff)`,
              '```diff',
              process.env.PR_DIFF,
              '```',
              ``,
              `## Instructions`,
              `First, review the merged diff and the repository's \`docs/\` directory to decide whether USER-FACING documentation actually needs to change. If not, make no changes and do not open a PR.`,
              ``,
              `Hard rules:`,
              `- Only edit user-facing feature docs. NEVER create or modify anything under \`docs/contributing/**\` — that directory is internal and off-limits to this agent.`,
              `- NEVER document backend or internal implementation details: Convex, internal HTTP endpoints or routes, environment variables, secrets or keys, server-side persistence/runtime mechanics, or internal source-file paths.`,
              `- Ground every statement in the provided diff and the current code/docs. Do NOT invent features, flags, tools, defaults, or numbers; if you cannot confirm a detail from the diff or the repository, omit it.`,
              `- Target the CURRENT docs structure. If the relevant page appears to have been renamed or removed, update the current equivalent page instead of recreating the old one; check \`docs/docs.json\` for the live page list.`,
              ``,
              `Keep edits minimal, precise, and user-focused. When adding or moving pages, update \`docs/docs.json\` so navigation stays accurate. Use concise commit messages and open a single focused PR only when user-facing changes are required. Use .mmd files for diagrams and other visual content if needed.`,
            ].join('\n');

            const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
            const payload = {
              branch: `mintlify/docs-update-pr-${process.env.PR_NUMBER}-${Date.now()}`,
              messages: [
                {
                  role: 'system',
                  content: 'You are an action runner that updates documentation based on code changes. You should never ask questions. If you are not able to access the repository, report the error and exit.'
                },
                {
                  role: 'user',
                  content: userMessage
                }
              ],
              asDraft: false
            };

            try {
              const response = await fetch(url, {
                method: 'POST',
                headers: {
                  'Authorization': `Bearer ${apiKey}`,
                  'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
              });

              if (!response.ok) {
                throw new Error(`API request failed with status ${response.status}: ${await response.text()}`);
              }

              const reader = response.body.getReader();
              const decoder = new TextDecoder();
              let buffer = '';

              while (true) {
                const { done, value } = await reader.read();
                if (done) break;
                buffer += decoder.decode(value, { stream: true });
                const lines = buffer.split('\n');
                buffer = lines.pop() || '';
                for (const line of lines) {
                  if (line.trim()) {
                    console.log(line);
                  }
                }
              }
              if (buffer.trim()) {
                console.log(buffer);
              }

              core.notice(`Documentation update job triggered for ${owner}/${repo} PR #${process.env.PR_NUMBER}`);
            } catch (error) {
              core.setFailed(`Failed to create documentation update job: ${error.message}`);
            }