# 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**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://x402.gitbook.io/x402/agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.