0f70fb6c90
- Playbook + RAG doc; Cursor rule; sync script + manifest snapshot - mcp-wormhole-docs: resources + wormhole_doc_search (read-only) - verify-wormhole-ai-docs-setup.sh health check Wire pnpm-workspace + lockfile + AGENTS/MCP_SETUP/MASTER_INDEX in a follow-up if not already committed. Made-with: Cursor
64 lines
3.8 KiB
Markdown
64 lines
3.8 KiB
Markdown
# Wormhole AI resources — LLM and agent playbook
|
||
|
||
**Purpose:** How agents and humans should use Wormhole’s published documentation bundles for **Wormhole protocol** work, without mixing them up with **DBIS Chain 138** canonical facts in this repo.
|
||
|
||
**Upstream hub:** [Wormhole AI Resources](https://wormhole.com/docs/ai-resources/ai-resources/)
|
||
**Source repo (docs):** [wormhole-foundation/wormhole-docs](https://github.com/wormhole-foundation/wormhole-docs)
|
||
|
||
---
|
||
|
||
## Canonical fetch URLs (verified)
|
||
|
||
Use these URLs in automation and MCP. The path `https://wormhole.com/docs/docs/...` (double `docs`) returns **404**; prefer the paths below.
|
||
|
||
| Tier | Artifact | URL |
|
||
|------|-----------|-----|
|
||
| 1 | `llms.txt` | `https://wormhole.com/docs/llms.txt` |
|
||
| 2 | `site-index.json` | `https://wormhole.com/docs/ai/site-index.json` |
|
||
| 3 | Category bundles | `https://wormhole.com/docs/ai/categories/<name>.md` |
|
||
| 4 | Full corpus | `https://wormhole.com/docs/ai/llms-full.jsonl` |
|
||
|
||
**Category file names:** `basics`, `ntt`, `connect`, `wtt`, `settlement`, `executor`, `multigov`, `queries`, `transfer`, `typescript-sdk`, `solidity-sdk`, `cctp`, `reference` (each as `<name>.md`).
|
||
|
||
**Per-page markdown (optional):** entries in `site-index.json` include `resolved_md_url` / `raw_md_url` under `https://wormhole.com/docs/ai/pages/...` for single-page depth.
|
||
|
||
---
|
||
|
||
## Consumption ladder (smallest context first)
|
||
|
||
1. **`llms.txt`** — Map of the doc site and links; use first to decide where to go next.
|
||
2. **`site-index.json`** — Lightweight index (title, preview, categories, URLs); use for retrieval and “which page answers X”.
|
||
3. **Category `.md`** — Focused implementation tasks (NTT, TypeScript SDK, reference, etc.).
|
||
4. **`llms-full.jsonl`** — Full text + metadata; use only for large-context models or **indexed RAG** (see [WORMHOLE_AI_RESOURCES_RAG.md](WORMHOLE_AI_RESOURCES_RAG.md)). Do not paste whole file into a small context window.
|
||
|
||
Wormhole notes these files are **informational only** (no embedded persona); safe to combine with project [AGENTS.md](../../AGENTS.md) and Cursor rules.
|
||
|
||
---
|
||
|
||
## Boundary: Wormhole vs this repo
|
||
|
||
| Topic | Source |
|
||
|--------|--------|
|
||
| Wormhole NTT, Connect, VAAs, Guardians, Executor, Wormhole CCTP integration, chain IDs **on Wormhole-supported networks** | Wormhole AI bundles + official Wormhole reference |
|
||
| Chain **138** token addresses, PMM pools, DODOPMMIntegration, **CCIP** routes, deployer wallet, Blockscout labels | Repo canonical docs: [EXPLORER_TOKEN_LIST_CROSSCHECK.md](../11-references/EXPLORER_TOKEN_LIST_CROSSCHECK.md), [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md), [07-ccip/](../07-ccip/) runbooks |
|
||
|
||
Do **not** treat Wormhole docs as authority for Chain 138 deployment facts. Do **not** treat this repo’s CCIP docs as authority for Wormhole core contracts on other chains.
|
||
|
||
---
|
||
|
||
## Local mirror and MCP
|
||
|
||
- **Sync script:** `bash scripts/doc/sync-wormhole-ai-resources.sh` — downloads tier 1–3 (and optionally tier 4) into `third-party/wormhole-ai-docs/` and writes `manifest.json` (SHA-256, timestamps).
|
||
- **MCP server:** `mcp-wormhole-docs/` — read-only resources and `wormhole_doc_search`; see [MCP_SETUP.md](MCP_SETUP.md).
|
||
- **Health check:** `bash scripts/verify/verify-wormhole-ai-docs-setup.sh` — mirror presence + `node --check` on the MCP entrypoint.
|
||
|
||
---
|
||
|
||
## Security and ops
|
||
|
||
- Fetch only from `https://wormhole.com/docs/` (allowlisted in the MCP server when using live fetch).
|
||
- `llms-full.jsonl` is large; mirror with `INCLUDE_FULL_JSONL=1` only when needed for RAG or offline use.
|
||
- Re-sync when Wormhole ships breaking doc changes; keep `manifest.json` for audit (“which snapshot was used?”).
|
||
|
||
**Licensing:** Wormhole Foundation material — use mirrors and RAG **consistent with their terms**; link to original URLs in answers when possible.
|