Migrate to mintlify

[manifoldfrs]

Description

Migrates x402 documentation from GitBook to Mintlify, with automated documentation updates when SDK code changes.

Automated Documentation Updates:

• New GitHub Actions workflow triggers Mintlify's AI agent on pushes to main
• The mintlify agent will analyze code changes and create documentation PRs when needed
• Intelligent filtering skips trivial changes like comments, formatting, tests which are defined in the github workflow and in the AGENTS.md file

Files

File	Purpose
.github/workflows/update-docs.yml	Automation workflow
docs/AGENTS.md	Agent behavior rules and code-to-doc mapping
docs/docs.json	Mintlify navigation configuration

Automation Workflow

When code is pushed to main, the GitHub Actions workflow evaluates whether to trigger the Mintlify agent. The workflow first applies a paths-ignore filter that skips entirely if only documentation files or test files changed. If non-excluded files are present, the workflow uses GitHub's Compare API to get a reliable list of changed files between the before/after commit SHAs. This approach was specifically chosen because the standard payload.commits[].added/modified method fails for squash merges, but the Compare API works correctly for all merge types (merge commits, squash, and rebase).

The workflow constructs a detailed prompt containing the list of changed files, the commit message, and a set of critical rules that constrain the agent's behavior. These rules explicitly instruct the agent to only update documentation directly related to the specific code changes, and to skip creating a PR if the changes are trivial (comment removal, formatting, optional parameters, etc.). The agent also reads docs/AGENTS.md which contains a code-to-doc mapping table. For example, changes to typescript/packages/core/src/ should update Core Concepts docs, while changes to python/x402/src/ should update Python SDK references.

The Mintlify agent analyzes the code changes against the existing documentation. If it determines updates are needed, it creates a new branch and opens a pull request with the documentation changes. If the changes are trivial or don't affect user-facing documentation, the agent reports "No documentation updates needed" and exits without creating a PR. All PRs are created as non-draft and ready for human review, the agent never commits directly to main.

The two-layer filtering (paths-ignore at trigger level, regex filtering in script, plus agent-level rules in AGENTS.md) creates a system that's sensitive enough to catch impactful changes but not so noisy that it creates PRs for every commit. Testing confirmed this balance: the agent correctly skipped trivial changes like comment removal and optional parameter additions, while correctly creating a PR when a default timeout behavior was added to HTTPFacilitatorClient (see manifoldfrs#15).

Tests

Tested with 5 scenarios on fork (manifoldfrs/x402-fh):

Test	Description	Result
Test case 1	Comment removal in SDK file	Workflow triggered → Agent skipped (trivial) ✓
Test case 2	Optional debug params added	Workflow triggered → Agent skipped (optional) ✓
Test case 3	Test files only	Workflow NOT triggered (paths-ignore) ✓
Test case 4	Docs files only	Workflow NOT triggered (paths-ignore) ✓
Test case 5	Timeout feature added	Workflow triggered → PR #15 created ✓

Configurations Required

Secret	Description	Where to Get
MINTLIFY_API_KEY	Admin API key	Mintlify Dashboard
MINTLIFY_PROJECT_ID	Project identifier	Same page as API key

Prerequisites

• Mintlify Pro or Custom plan (for Agent API access)
• Mintlify GitHub App installed on coinbase/x402
• Secrets added to repository

Documentation

• Mintlify Agent API: https://mintlify.com/docs/api/agent/create-agent-job
• Mintlify Automation Guide: https://mintlify.com/docs/guides/automate-agent

Checklist

• Documentation renders correctly on Mintlify
• Navigation structure preserved in docs.json
• All internal links updated (removed .md extensions)
• MDX components work (Tabs, Cards, Callouts)
• Automation workflow tested (5 test cases)
• AGENTS.md rules defined for code-to-doc mapping
• Secrets configured in coinbase/x402 (required before merge)
• Mintlify GitHub App installed on coinbase/x402

Breaking Changes

None. This is a documentation infrastructure change only.

Related

• Test PR created by agent: Document HTTPFacilitatorClient timeout configuration manifoldfrs/x402-fh#15

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 0 Sum 1

[vercel]

@manifoldfrs is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

[phdargen]

Ideally we could exclude legacy packages here:

• typescript/packages/legacy/*
• go/legacy
• python/legacy

[manifoldfrs]

Agreed, but I did happen to update the typescript legacy package to fix a bug in this PR https://github.com/coinbase/x402/pull/967/changes#diff-3997cdf0b0daf1a99c50cd1b237f6c702dcbbc7416645928f76068d6a795fac1, perhaps we leave it for now and we exclude later?

[phdargen]

yes but gitdocs only document v2, not legacy as far as I know

[manifoldfrs]

ah yes you're right we decided to leave legacy docs out, good catch I'll update

[phdargen]

once v2 is live, this should be python/x402/ only

[phdargen]

see above

[phdargen]

Looks great to me @manifoldfrs! Just a few minor suggestions/comments above

[manifoldfrs]

Will incorporate python v2 changes once this PR merges: #841