From 9b16917c77e0fe4205f8411ec5278d5b918cb4b4 Mon Sep 17 00:00:00 2001 From: Gabriel Date: Fri, 28 Aug 2026 13:25:09 -0400 Subject: [PATCH 1/3] chore: docs-sync setup (code map cleanup + docs CI) --- .github/workflows/docs-ci.yaml | 23 +++++++++++++++++++++++ DOCS_CODE_MAP.md | 16 ++++++++-------- 2 files changed, 31 insertions(+), 8 deletions(-) create mode 100644 .github/workflows/docs-ci.yaml diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml new file mode 100644 index 0000000..481dca8 --- /dev/null +++ b/.github/workflows/docs-ci.yaml @@ -0,0 +1,23 @@ +name: docs-ci + +on: + pull_request: + push: + branches: [master, main] + +concurrency: + group: docs-ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + build-and-check-links: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + - run: npm ci + - run: npm run build + - run: npx mintlify broken-links diff --git a/DOCS_CODE_MAP.md b/DOCS_CODE_MAP.md index 19d4765..9786e57 100644 --- a/DOCS_CODE_MAP.md +++ b/DOCS_CODE_MAP.md @@ -1,15 +1,15 @@ # Docs ↔ Codebase map -Use this map to verify that **mintlify-docs** stays in sync with the **routemesh** monorepo. Each doc area lists the code paths that define or implement the behavior the docs describe. +Use this map to verify that **mintlify-docs** stays in sync with the **routemesh** codebase. Each doc area lists the code paths (by repo and file) that define or implement the behavior the docs describe. -**Monorepo layout (relative to repo root):** -- `atlas/` — Router (RPC handling, cooldowns, routing, batch ID, error codes) -- `sentinel/` — Data quality (replay checks, lag checks, staging, disqualification) -- `front-end/` — Dashboard, provider portal, consumer app, URLs, nav -- `mintlify-docs/` — This documentation site +**Repos (each is its own GitHub repository under `routemesh/`):** +- `routemesh/atlas` — Router (RPC handling, cooldowns, routing, batch ID, error codes) +- `routemesh/sentinel` — Data quality (replay checks, lag checks, staging, disqualification) +- `routemesh/front-end` — Dashboard, provider portal, consumer app, URLs, nav +- `routemesh/mintlify-docs` — This documentation site - `api-reference/openapi.json` — API spec (should match atlas + any gateway that sets headers) -- `routemesh-mcp/` — `@routemesh/mcp` MCP server (Node/TS) -- `api/` — API server (`api.routeme.sh`: mgmt tokens, usage, API keys, chains) + +The `atlas/…`, `front-end/…`, and `sentinel/…` path prefixes below refer to those respective repos' roots. --- From 40ca78c91a8aa0f041b0ef22bb7ce26bab242312 Mon Sep 17 00:00:00 2001 From: Gabriel Date: Fri, 28 Aug 2026 13:28:16 -0400 Subject: [PATCH 2/3] chore: remove internal docs map + sync prompt (leak internal repos to public) --- DOCS_CODE_MAP.md | 75 --------------------------------------------- PROMPT_DOCS_SYNC.md | 63 ------------------------------------- 2 files changed, 138 deletions(-) delete mode 100644 DOCS_CODE_MAP.md delete mode 100644 PROMPT_DOCS_SYNC.md diff --git a/DOCS_CODE_MAP.md b/DOCS_CODE_MAP.md deleted file mode 100644 index 9786e57..0000000 --- a/DOCS_CODE_MAP.md +++ /dev/null @@ -1,75 +0,0 @@ -# Docs ↔ Codebase map - -Use this map to verify that **mintlify-docs** stays in sync with the **routemesh** codebase. Each doc area lists the code paths (by repo and file) that define or implement the behavior the docs describe. - -**Repos (each is its own GitHub repository under `routemesh/`):** -- `routemesh/atlas` — Router (RPC handling, cooldowns, routing, batch ID, error codes) -- `routemesh/sentinel` — Data quality (replay checks, lag checks, staging, disqualification) -- `routemesh/front-end` — Dashboard, provider portal, consumer app, URLs, nav -- `routemesh/mintlify-docs` — This documentation site -- `api-reference/openapi.json` — API spec (should match atlas + any gateway that sets headers) - -The `atlas/…`, `front-end/…`, and `sentinel/…` path prefixes below refer to those respective repos' roots. - ---- - -## Consumer docs (intro/) - -| Doc | What to verify | Code paths | -|-----|----------------|------------| -| **getting-started** | Billing URL, dashboard URL, login URL, RPC base URL, chains URL | `front-end/src/lib/constants/external-links.ts`, `front-end/vercel.json` or env for app URL; atlas route path `/rpc/:chainId/:apiKey` | -| **how-it-works** | Terminology (provider, node, route, pathway); routing steps; data quality mention | `atlas/` routing flow; `intro/data-quality.mdx` link | -| **request-behavior** | Cooldowns, 429 on all cooldown, **-32003** code; **eth_getLogs** limits (-32602 block span, -32005 query density); hint suffix in `error.message` | `atlas/api/rpc/eth-getlogs-range-validator.go`, `atlas/common/node-processor/handlers/eth-get-logs-oversized-error-normalizer.go`, `atlas/common/node-processor/node-processor.go` (`normalizeEthGetLogsOversizedHandlerEvaluation`), `atlas/common/node-processor/http-status-aggregator.go` | -| **rpc-error-codes** | All codes: -32700, -32600, -32602, -32603, -32000, -32001, -32002, -32003, -32005; eth_getLogs normalized messages | `atlas/api/rpc/jsonrpc-errors.go`, `atlas/common/custom-errors/custom-errors.go` (`ErrBlockRangeTooLarge`, `ErrEthGetLogsResultCountExceeded`, `EthGetLogsHintError`), `atlas/common/node-processor/handlers/eth-get-logs-oversized-error-normalizer.go` | -| **debugging** | `X-Batch-Id` header name; RPC URL pattern `lb.routeme.sh/rpc/{chain_id}/{api_key}`; Logs page URL | Atlas or gateway: where response headers are set (BatchID exists in `atlas/api/rpc/handle-rpc-requests.go`, `atlas/common/models/request-context.go`). Front-end logs: `front-end/src/app/(protected)/app/consumer/logs/` | -| **data-quality** | Sentinel concepts (replay, lag, staging); no need to sync exact thresholds/strike counts (keep docs high-level) | `sentinel/` (replay in `common/replay/`, lag in `common/lag/`, config in `config.yaml`). Consumer doc can stay conceptual. | -| **redundancy** | lb.routeme.sh, lb2.routeme.sh; Cloudflare vs AWS; 15s failover | Infrastructure/config (may live outside repo or in terraform). | -| **network-support** | support@routeme.sh; Lite vs Full support (if referenced) | Front-end or backend chain-support logic. | -| **mcp-server** | Tool list + parameters (all `rpc_*` + `get_usage`, `list_api_keys`, `create_api_key`, `update_api_key`); env vars and defaults (`ROUTEMESH_API_KEY`, `ROUTEMESH_MGMT_TOKEN`, `ROUTEMESH_API_SERVER_URL`, `ROUTEMESH_BASE_URL`, `ROUTEMESH_BACKUP_BASE_URL`, `ROUTEMESH_TIMEOUT_MS`, `ROUTEMESH_RETRY_ATTEMPTS`); failover/retry behavior; mgmt token flow (dashboard **Mgmt Tokens** page, one-time secret, customer-tier scope) | `routemesh-mcp/src/tools/read-tools.ts` (RPC tool schemas), `routemesh-mcp/src/tools/customer-tools.ts` + `src/tools/api-keys-tools.ts` (customer tool schemas), `routemesh-mcp/src/config/env.ts` (env vars + defaults), `routemesh-mcp/src/routemesh/client.ts` (retry/failover, `/rpc/{chainId}/{apiKey}`), `routemesh-mcp/src/api-server/client.ts` (mgmt token in `x-api-key`), `api/api/middleware/mgmtauth/mgmtauth.go` + `api/apikeys/apikeys.go` + `api/usage/usage.go` (customer-tier route scope), `front-end/src/app/(protected)/app/consumer/mgmt-tokens/` (token create UI) | -| **routing-strategies** | Economy vs performance; strategy names | `atlas/` routing + `front-end` (e.g. strategy filters). | -| **pricing-model** | Credits, pricing page URL | `front-end` billing/pricing; external-links. | -| **updates** | Changelog or update content | Editorial; optional link to updates source. | - ---- - -## Provider docs (provider/) - -| Doc | What to verify | Code paths | -|-----|----------------|------------| -| **overview** | Contact (k@routeme.sh); routeme.sh app URL; no software required (URL + pricing) | `front-end/src/lib/constants/external-links.ts` (MAIN_WEBSITE); provider portal routes | -| **dashboard** | Dashboard metrics (requests, market share, active routes, revenue); app URL | `front-end/src/app/(protected)/app/provider/page.tsx`; provider dashboard API | -| **plans** | Portal plans URL: `/app/provider/portal/plans` | `front-end/src/config/navigation.ts` (Plans href), `front-end/src/app/(protected)/app/provider/portal/plans/` | -| **methods** | Portal methods URL: `/app/provider/portal/methods` | `front-end/src/config/navigation.ts` (Methods href), `front-end/src/app/(protected)/app/provider/portal/methods/` | -| **nodes** | Portal nodes URL: `/app/provider/portal/nodes` | `front-end/src/config/navigation.ts` (Nodes href), `front-end/src/app/(protected)/app/provider/portal/nodes/` | -| **inspect** | Inspect URL; replay/lag metrics in UI | `front-end/src/config/navigation.ts` (Inspect href), `front-end/src/app/(protected)/app/provider/inspect/`; `front-end/src/app/api/(protected)/provider/lag-checks/` | -| **market-share** | Market share URL; “paid for all requests” vs “market share = who won” | `front-end/src/app/(protected)/app/provider/market-share/`; billing/analytics logic | -| **data-quality, replay-checks, lag-checks, quality-checks-recovery** | Concepts only; no exact thresholds. Replay = read-only/deterministic methods; lag = freshness | `sentinel/config.yaml` (excluded_methods, etc.) — do **not** copy config into docs; keep provider docs high-level. | - ---- - -## API reference - -| Asset | What to verify | Code paths | -|-------|----------------|------------| -| **api-reference/openapi.json** | Server URLs (routeme.sh, lb, lb2); error codes in descriptions; `X-Batch-Id` in responses; path `/rpc/{chain_id}/{api_key}`; eth_getLogs -32602/-32005 | `atlas/api/rpc/rpc.go` (route registration); `atlas/api/rpc/jsonrpc-errors.go` (codes); `atlas/common/node-processor/handlers/eth-get-logs-oversized-error-normalizer.go` | - ---- - -## Cross-cutting - -| Item | Where it lives | Verify | -|------|----------------|--------| -| **routeme.sh, lb.routeme.sh, lb2.routeme.sh** | Docs + openapi.json + intro (redundancy, getting-started, debugging) | Same hostnames in `front-end/src/lib/constants/external-links.ts` and any env/deploy config. | -| **support@routeme.sh, k@routeme.sh** | docs.json (navbar), provider overview, network-support | docs.json `navbar.links`; provider/overview.mdx; intro/network-support.mdx. | -| **Twitter, LinkedIn, GitHub** | docs.json footer; provider overview | `docs.json` `footer.socials`; `front-end/src/lib/constants/external-links.ts` SOCIAL. | -| **Provider portal nav** | Provider doc links to /app/provider/... | Match `front-end/src/config/navigation.ts` (provider section). | - ---- - -## Quick checks for a cron job - -1. **Error codes** — Grep `atlas/common/json-rpc/json-rpc.go` and `atlas/common/custom-errors/custom-errors.go` for -32xxx; ensure `intro/rpc-error-codes.mdx` and `intro/request-behavior.mdx` list the same codes and messages. -2. **Provider app paths** — Grep `front-end/src/config/navigation.ts` for provider hrefs; ensure `provider/*.mdx` and `docs.json` use the same paths (e.g. `/app/provider/inspect`, `/app/provider/portal/plans`). -3. **External URLs** — Grep `routeme.sh` in mintlify-docs and compare to `front-end/src/lib/constants/external-links.ts`. -4. **OpenAPI** — If openapi.json is hand-maintained, diff error code list and server URLs against atlas and gateway behavior. -5. **Broken links** — Run `mint broken-links` in mintlify-docs (see AGENTS.md). diff --git a/PROMPT_DOCS_SYNC.md b/PROMPT_DOCS_SYNC.md deleted file mode 100644 index 57dfa00..0000000 --- a/PROMPT_DOCS_SYNC.md +++ /dev/null @@ -1,63 +0,0 @@ -# Prompt: Verify docs are correct and synced to the codebase - -**Use this prompt in a cron job or one-off run so an AI can quickly verify that mintlify-docs matches the routemesh codebase.** - ---- - -## Instructions for the AI - -You are verifying that the **mintlify-docs** documentation is correct and in sync with the **routemesh** monorepo (atlas, sentinel, front-end). - -1. **Read the doc–code map** - Open and use **`mintlify-docs/DOCS_CODE_MAP.md`**. It lists each doc area and the code paths that implement or define the behavior the docs describe. - -2. **Run these checks (in order)** - - **Error codes** - - In `atlas/common/json-rpc/json-rpc.go` and `atlas/common/custom-errors/custom-errors.go`, list every JSON-RPC error code (-32xxx) and its message or error name. - - Compare with `mintlify-docs/intro/rpc-error-codes.mdx` and `mintlify-docs/intro/request-behavior.mdx`. - - Report any mismatch (missing code, wrong message, or extra doc-only code). - - **Provider portal paths** - - In `front-end/src/config/navigation.ts`, read the provider section (Dashboard, Inspect, Market Share, Plans, Methods, Nodes). Note the href paths (e.g. `getRoute('/inspect')` → `/app/provider/inspect`). - - Compare with links in `mintlify-docs/provider/*.mdx` (e.g. `https://routeme.sh/app/provider/inspect`, `https://routeme.sh/app/provider/portal/plans`). - - Report any wrong or broken provider app URLs. - - **External URLs and contacts** - - In `front-end/src/lib/constants/external-links.ts`, note MAIN_WEBSITE, DOCUMENTATION, and SOCIAL (Twitter, LinkedIn). - - In `mintlify-docs/docs.json`, note navbar primary href, footer socials, and support link. - - In `mintlify-docs/provider/overview.mdx` and `mintlify-docs/intro/network-support.mdx`, note k@routeme.sh and support@routeme.sh. - - Report any mismatch (e.g. different domain or contact). - - **OpenAPI vs router** - - In `mintlify-docs/api-reference/openapi.json`, note server URLs and any documented error codes in response/description. - - Compare server URLs with what’s in the map and with atlas route registration (`atlas/api/rpc/rpc.go`: path `/rpc/:chainId/:apiKey`). - - Report if openapi.json is missing a code that atlas returns or documents a code atlas doesn’t use. - - **Broken internal links** - - From repo root, run: `cd mintlify-docs && npx mintlify broken-links` (or `mint broken-links` if mintlify CLI is installed). - - Report any broken links and fix or note them. - -3. **Output** - - Summarize: “Docs sync check: PASS” or “Docs sync check: FAIL”. - - List each discrepancy (doc path or file, code path, and what’s wrong). - - If you have write access, fix minor doc typos or outdated URLs and report what you changed; do not change code. - -4. **Do not** - - Change Sentinel config or implementation details in the docs (provider and consumer data-quality docs stay high-level). - - Add new error codes to the docs unless they exist in atlas. - - Assume gateway or infra that isn’t in the repo; only note “documented but not found in repo” for things like X-Batch-Id if the map says to verify and you can’t find where it’s set. - ---- - -## One-line prompt (for cron / automation) - -Copy-paste this as the user message if the runner only supports a single prompt: - -``` -Using mintlify-docs/DOCS_CODE_MAP.md, verify that mintlify-docs is in sync with the routemesh codebase (atlas, sentinel, front-end). Run: (1) Error codes in atlas vs intro/rpc-error-codes.mdx and request-behavior.mdx, (2) Provider portal paths in front-end/src/config/navigation.ts vs provider/*.mdx links, (3) External URLs and contacts in front-end/src/lib/constants/external-links.ts and docs.json, (4) OpenAPI server URLs and error codes vs atlas, (5) mint broken-links in mintlify-docs. Report PASS/FAIL and list discrepancies; fix only docs if you have write access. -``` - ---- - -## Where the map lives - -- **Doc–code map:** `mintlify-docs/DOCS_CODE_MAP.md` -- **This prompt:** `mintlify-docs/PROMPT_DOCS_SYNC.md` -- **Mintlify config:** `mintlify-docs/docs.json` -- **Link check:** from `mintlify-docs/`, run `npx mintlify broken-links` or `mint broken-links`. From 5905bc0f92072c74605b382bd40e23336928ddb3 Mon Sep 17 00:00:00 2001 From: Gabriel Date: Fri, 28 Aug 2026 13:31:32 -0400 Subject: [PATCH 3/3] ci: use 'mintlify validate' (build is not a valid CLI command) --- .github/workflows/docs-ci.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs-ci.yaml b/.github/workflows/docs-ci.yaml index 481dca8..926d564 100644 --- a/.github/workflows/docs-ci.yaml +++ b/.github/workflows/docs-ci.yaml @@ -19,5 +19,5 @@ jobs: node-version: 20 cache: npm - run: npm ci - - run: npm run build + - run: npx mintlify validate - run: npx mintlify broken-links