Migrate to mintlify

.github/workflows/update-docs.yml

@@ -0,0 +1,170 @@
+name: Update Docs
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - 'docs/**'
+      - '**/*.test.ts'
+      - '**/*.test.js'
+      - '**/__tests__/**'
+      - '**/test/**'
+      - '**/tests/**'
+      - '**/typescript/site/*'
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        env:
+          MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
+          PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
+        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;
+            }
+
+            // Get SHAs from push payload
+            const beforeSha = context.payload.before;
+            const afterSha = context.payload.after;
+
+            // Skip initial commits (no previous SHA to compare against)
+            if (/^0+$/.test(beforeSha)) {
+              core.notice('Initial commit detected. Skipping documentation update.');
+              return;
+            }
+
+            // Get changed files using GitHub Compare API (reliable for all merge types)
+            let uniqueFiles = [];
+
+            try {
+              const compareResponse = await github.rest.repos.compareCommits({
+                owner,
+                repo,
+                base: beforeSha,
+                head: afterSha
+              });
+
+              // Extract filenames, excluding test files
+              const testFilePattern = /\.(test|spec)\.(ts|js|tsx|jsx)$|__tests__|\/test\/|\/tests\//;
+              uniqueFiles = (compareResponse.data.files || [])
+                .map(f => f.filename)
+                .filter(f => !testFilePattern.test(f));
+
+            } catch (error) {
+              core.setFailed('Failed to compare commits: ' + error.message);
+              return;
+            }
+
+            // Log changed files for debugging
+            console.log('Changed files (' + uniqueFiles.length + '):', uniqueFiles.slice(0, 10));
+            if (uniqueFiles.length > 10) {
+              console.log('... and ' + (uniqueFiles.length - 10) + ' more');
+            }
+
+            // Skip if no non-test files changed
+            if (uniqueFiles.length === 0) {
+              core.notice('No documentation-relevant files changed. Skipping agent trigger.');
+              return;
+            }
+
+            // Get commit message from head commit
+            const headCommit = context.payload.head_commit;
+            const commitMessage = headCommit 
+              ? '- ' + headCommit.message.split('\n')[0]
+              : '- No commit message available';
+
+            // Compare URL for reference
+            const compareUrl = context.payload.compare || '';
+
+            // Build the system prompt
+            const systemPrompt = [
+              'You are a documentation updater that ONLY updates docs directly related to specific code changes.',
+              '',
+              'CRITICAL RULES:',
+              '- ONLY update documentation that is directly affected by the code changes provided',
+              '- DO NOT perform general documentation audits or sync operations',
+              '- DO NOT add documentation for unrelated features, ecosystem partners, or missing content',
+              '- If the code changes do not require documentation updates, report "No documentation updates needed" and exit without creating a PR',
+              '- Focus on the specific files and commits mentioned, not the entire repository state',
+              '- Read the AGENTS.md file in the docs directory for additional guidance'
+            ].join('\n');
+
+            // Build the user prompt
+            const userPrompt = [
+              'Review these SPECIFIC code changes and update documentation ONLY if directly related:',
+              '',
+              '**Repository:** ' + owner + '/' + repo,
+              '**Compare URL:** ' + compareUrl,
+              '',
+              '**Changed Files (' + uniqueFiles.length + '):**',
+              uniqueFiles.join('\n'),
+              '',
+              '**Commit Message:**',
+              commitMessage,
+              '',
+              'IMPORTANT: Only update documentation that is directly impacted by these specific file changes. Do not add documentation for unrelated features or perform general audits. If these changes do not affect documentation, do NOT create a PR.'
+            ].join('\n');
+
+            const url = 'https://api.mintlify.com/v1/agent/' + projectId + '/job';
+            const payload = {
+              branch: 'mintlify/docs-update-' + Date.now(),
+              messages: [
+                {
+                  role: 'system',
+                  content: systemPrompt
+                },
+                {
+                  role: 'user',
+                  content: userPrompt
+                }
+              ],
+              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) {
+                const errorText = await response.text();
+                throw new Error('API request failed with status ' + response.status + ': ' + errorText);
+              }
+
+              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);
+            } catch (error) {
+              core.setFailed('Failed to create documentation update job: ' + error.message);
+            }

docs/AGENTS.md

@@ -0,0 +1,106 @@
+# Documentation Agent Instructions
+
+## Package Identity
+- Mintlify documentation source for docs.x402.org
+- MDX/Markdown files with `docs.json` as navigation configuration
+
+## Directory Structure
+- `core-concepts/` — Protocol explanations (HTTP 402, client-server, facilitator, wallet)
+- `getting-started/` — Quickstart guides for buyers and sellers (MDX files with tabs)
+- `guides/` — How-to guides (MCP server, v1→v2 migration)
+- `README.md` — Welcome/landing page
+- `docs.json` — Mintlify navigation and configuration
+
+## Code-to-Doc Mapping
+- Changes to `typescript/packages/core/src/` affect Core Concepts docs
+- Changes to `typescript/packages/*/src/` affect SDK references and quickstart guides
+- Changes to `python/x402/src/` affect Python SDK references
+- Changes to `go/` affect Go SDK references
+- Changes to facilitator endpoints affect quickstart guides
+- Changes to `specs/` may require updates to core-concepts docs
+
+## Style Guidelines
+- Use TypeScript for primary code examples (it's the reference SDK)
+- Include error handling in all API examples
+- Write for developers with 2-5 years experience
+- Use MDX components (`<Tabs>`, `<Tab>`, `<Callout>`, `<Card>`) for interactive content
+- Show both success and error response examples for API endpoints
+- Use real-world parameter values in examples (not foo/bar placeholders)
+
+## Conventions
+- DO: Add new pages to `docs.json` navigation
+- DO: Include code examples from real SDK files (not made-up snippets)
+- DO: Link to relevant specs in `specs/` for protocol details
+- DO: Use `<Tabs>` for multi-language code examples
+- DO: Add frontmatter (title, description) to all pages
+- DON'T: Duplicate protocol details from `specs/` — link instead
+- DON'T: Add pages without updating `docs.json`
+- **Git: Create PRs for review; NEVER commit directly to main**
+
+## Touch Points / Key Files
+- `README.md` — Landing page
+- `docs.json` — Navigation and configuration (MUST update when adding pages)
+- `core-concepts/*.md` — Conceptual documentation
+- `getting-started/*.mdx` — Quickstart guides (MDX for tab components)
+- `guides/*.md` — How-to guides
+
+## File Extensions
+- Use `.md` for standard markdown pages
+- Use `.mdx` for pages with React components (Tabs, Cards, etc.)
+
+## Common Gotchas
+- `docs.json` controls Mintlify navigation; pages not listed won't appear
+- Images/diagrams go in project root `static/` directory
+- Code examples should reference actual SDK file paths
+- Links between pages should omit file extensions (e.g., `../core-concepts/http-402` not `../core-concepts/http-402.md`)
+
+## Pre-PR Checks
+- All links work (no broken references)
+- New pages added to `docs.json` navigation
+- Code examples are from actual SDK files and compile
+- Frontmatter present on all pages (title, description)
+- MDX syntax is valid (run `mint dev` to verify)
+
+## Agent Behavior Rules (Automated Workflows)
+
+When triggered by GitHub Actions or other automated workflows:
+
+### DO
+- ONLY update documentation directly related to the specific code changes
+- Focus on the files and commits mentioned in the trigger
+- Update SDK references if API signatures change
+- Update quickstart guides if SDK usage patterns change
+- Update core-concepts if protocol behavior changes
+
+### DO NOT
+- Perform general documentation audits or sync operations
+- Add documentation for ecosystem partners not mentioned in the code change
+- Add documentation for features unrelated to the trigger
+- Create PRs for trivial changes (comment removal, formatting, etc.)
+- Sync ecosystem partner data from `typescript/site/app/ecosystem/` unless explicitly changed
+
+### Code-to-Doc Mapping (for automated updates)
+
+| Code Change | Doc Update Required |
+|-------------|---------------------|
+| `typescript/packages/*/src/*.ts` API changes | SDK reference, quickstart guides |
+| `python/x402/src/*.py` API changes | Python SDK reference |
+| `go/*.go` API changes | Go SDK reference |
+| `java/src/**/*.java` API changes | Java SDK reference |
+| `specs/*.md` protocol changes | core-concepts docs |
+| Comment removal, formatting | NO update needed |
+| Test file changes | NO update needed |
+| Build/CI config changes | NO update needed |
+| Ecosystem partner metadata only | NO update needed (site handles this) |
+
+### When to Skip (No PR)
+
+If the code changes are limited to:
+- Removing or adding code comments
+- Formatting/style changes (prettier, linting)
+- Test files only (`*.test.ts`, `__tests__/`, etc.)
+- CI/build configuration only (`.github/`, `turbo.json`, etc.)
+- Dependency updates without API changes (`package.json`, `go.mod`, etc.)
+- Ecosystem partner metadata (`typescript/site/app/ecosystem/partners-data/`)
+
+Then report "No documentation updates needed" and **do not create a PR**.