Improve MCP with docs-backed onboarding and edge access checks

[Jotatavo]

Summary

• Extends the DoubleZero MCP with guided onboarding: get_onboarding_runbook loads walkthroughs from public docs (catalog from GitHub raw docs/runbooks.md).
• Replaces the mock edge-access check with a real check_edge_access that execs doublezero access-pass get --user-payer <pubkey> --client-ip <ip> --json on the API host, so onchain state is the source of truth. Only a connected pass reports active; requested/disconnected/expired report pending with per-status guidance.
• Moves docs fetching into utils/pkg/docsfetch (shared by read_docs and the runbook loader), bounded at 10k per page.
• Removes the embedded runbook fallback (api/handlers/runbooks/). Catalog and bodies come only from docs — no in-repo mockups.
• Based on @armcconnell's MCP onboarding mockup work (lake-private / mcp-onboarding).

Docs dependency (cross-repo — cannot merge here)

The runbook index (docs/runbooks.md) and the runbook pages land via malbeclabs/docs#197 in a separate repo. There is no embed fallback: until that PR merges, get_onboarding_runbook cannot list or load runbooks. Merge docs#197 first (or together), then this.

Deployment note

check_edge_access requires the doublezero CLI on the API host. Hosts without it get a clear tool error ("access pass lookup failed"); no other tool is affected.

Testing Verification

• Verified the docs#197 runbooks.md index format parses with the catalog parser (fenced example block is stripped; all three runbook entries parse).
• Verified doublezero access-pass get behavior against a live testnet host: connected pass with 0.0.0.0 wildcard resolves for an arbitrary receiving IP, lowercase status in JSON, exit 1 + Error: Access Pass not found on a miss.
• Red-checked the status gating tests: against the previous code a requested pass reported active; the new tests fail on that code and pass on the fix.
• get_onboarding_runbook exercised with local docs fixtures; missing index / missing page return clear errors (no embed path).

[armcconnell]

Good direction, and the move from the mockup's in-memory fake to a real dz_access_passes_current lookup is the right call. Two things block merge.

1. check_edge_access reports active for unapproved passes. Only expired maps to pending, but the status enum is requested | connected | disconnected | expired. A requested pass — the case the tool exists to catch — comes back active.

2. get_onboarding_runbook is dead on arrival. docs/runbooks.md 404s on malbeclabs/docs@main right now, so every call errors, and the tool is already advertised in the server card and on the web MCP page. The embed fallback doesn't help — it covers the body, not the index.

The rest are smaller: docsfetch duplicates the existing read_docs fetch rather than replacing it, the access-pass query uses the privileged pool where execute_sql uses the read-only one, and there's an exported mutable global for test injection.

On rollout: this depends on a change in another repo and lights up a tool for every MCP client on merge. Since it's your first change in this repo, please pair with a maintainer on the sequencing — docs page merged first, then this, and confirm behavior against a preview env before it hits prod.

Also worth noting the mockup's dz-edge-subscriber.md came over verbatim, including hardcoded Hyperliquid ports and multicast group. That was fine for a demo; if it's shipping, it should live in docs like every other runbook rather than as an embed.

[Jared-dz]

Both blockers are addressed, replies with SHAs on each thread. Summary of the round (f3fe506..ef656fc):

1. Status gating — check_edge_access gates on connected (5fda19d); every other status reports pending with per-status guidance.
2. Runbook index 404 — the catalog falls back to the embedded runbooks when the index is unavailable (ef656fc), so the tool works on merge in either sequencing. The live index ships via malbeclabs/docs#197 — separate repo, so it merges independently; the dependency is called out in the code and PR body. I verified that page's format parses with the catalog parser.
3. Smaller items: read_docs moved onto the shared docsfetch package (05a8bad) with a 10k read bound (3fdda4b); docs-source injection moved onto the API struct, no exported mutable global (39ba529); t.Parallel() restored (acf0acd). The agent/ copy of the docs fetch stays put for a follow-up PR since touching agent code obliges an eval run.

One direction change to flag: Jared redirected the access check off ClickHouse — it now execs doublezero access-pass get --user-payer <pubkey> --client-ip <ip> --json, so onchain state is the source of truth and the semantics match the CLI exactly (including 0.0.0.0 wildcard resolution, verified against a live testnet host). Deployment consequence: the API host needs the doublezero CLI; noted in the PR body.

On dz-edge-subscriber.md: agreed it should live in docs. docs#197 does not include it, which means once the live index is published the embed drops out of the catalog (the fallback only serves while the index is missing). Follow-up needed either way: add it to docs (minus the hardcoded Hyperliquid specifics) or delete the embed. Leaving that call to you and Jared.

addressed, and approved by our lord and savior Karl