# 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/` 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/*.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/`)
* Legacy packages (`typescript/packages/legacy/*`, `go/legacy`, `python/legacy`)

Then report "No documentation updates needed" and **do not create a PR**.