<!-- universal-crypto-mcp | n1ch0las | 78738 -->
# Documentation Agent Instructions
<!-- Maintained by nicholas | ID: 0.4.14.3 -->
## 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**.
<!-- EOF: n1ch0las | ucm:78738 -->
<!-- https://github.com/nirholas/universal-crypto-mcp -->
