docs: add Solana onboarding runbooks for the MCP

.github/workflows/translate.yml

@@ -39,9 +39,11 @@ jobs:
         run: |
           BASE="${{ github.event.pull_request.base.sha }}"
           # Only source .md files — exclude already-translated ones (e.g. index.es.md)
+          # and MCP runbooks (git/raw only, not on the public site).
           CHANGED=$(git diff --name-only "$BASE" HEAD -- docs/ \
             | grep '\.md$' \
             | grep -vE '\.[a-z]{2,3}\.md$' \
+            | grep -vE '(^|/)runbooks\.md$|(^|/).*-runbook\.md$' \
             || true)
           echo "Source files changed:"
           echo "$CHANGED"

docs/runbooks.md

@@ -0,0 +1,24 @@
+---
+description: Machine-readable index of onboarding runbooks for the DoubleZero MCP. Not linked in the docs nav.
+search:
+  exclude: true
+---
+
+# Runbooks
+
+The DoubleZero MCP loads this file from GitHub raw
+(`https://raw.githubusercontent.com/malbeclabs/docs/main/docs/runbooks.md`)
+to discover walkthroughs. Humans use [Connect your AI](mcp.md); do not add this
+page to the site nav.
+
+To register a runbook, add a list item under **Index** in this shape:
+
+```markdown
+- `service-id` — [Human title](page-slug.md)
+```
+
+## Index
+
+- `solana-ibrl` — [Connect validator (IBRL Mainnet)](solana-ibrl-runbook.md)
+- `solana-shreds-publisher` — [Publish shreds (Edge)](solana-shreds-publisher-runbook.md)
+- `solana-shreds` — [Subscribe to shreds (Edge)](solana-shreds-runbook.md)

docs/solana-ibrl-runbook.md

@@ -0,0 +1,160 @@
+---
+description: LLM-oriented runbook — connect a Solana Mainnet-Beta validator to DoubleZero in IBRL mode. Served to the MCP via GitHub raw; not published on the docs site.
+---
+
+# Connect validator (IBRL Mainnet) — runbook
+
+This page is for the DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. It is
+not published on the docs site.
+
+1. Connect the [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`).
+2. Tell it this is a **Solana Mainnet-Beta validator**, the Linux host (or SSH), and where the validator identity keypair lives.
+3. Walk the steps below in order. Prefer to do it by hand? Use the [human guide](DZ Mainnet-beta Connection.md).
+
+**What success looks like:** `doublezero status` shows tunnel **up**, User Type **IBRL**, Network **mainnet-beta**. `Tunnel src` and `Doublezero IP` match the host public IPv4.
+
+IBRL does not require restarting validator clients; it uses the existing public IP.
+
+---
+
+## Prerequisites
+
+| Need | Notes |
+|------|--------|
+| Linux/amd64 host | Install DoubleZero **on the validator host**, not in a container. |
+| Public IPv4, no NAT | Gossip IP must match this host. |
+| Solana CLI on `$PATH` | For `solana sign-offchain-message`. |
+| Validator identity keypair | Readable by the user running the commands (often under the `sol` user). |
+| ≥1 SOL on the identity | Passport / onchain request. |
+| GRE (IP proto 47) + BGP | BGP on `169.254.0.0/16` tcp/179. |
+| `doublezero-solana` | `sudo apt update && sudo apt install doublezero-solana` (or distro equivalent). |
+
+The Validator ID is checked against Solana gossip to determine the target IP. A junk ID on the same IP is ignored; only the primary ID in gossip is used.
+
+---
+
+## Steps
+
+### 1. Install the client
+
+Follow [setup](setup.md) if `doublezero` is not installed. Mainnet packages:
+
+```bash
+curl -1sLf https://dl.cloudsmith.io/public/malbeclabs/doublezero/setup.deb.sh | sudo -E bash
+sudo apt-get install doublezero
+```
+
+Rocky / RHEL: use `setup.rpm.sh` and `sudo yum install doublezero`.
+
+**Verify:** `sudo systemctl status doublezerod` is active. Back up `~/.config/doublezero/id.json`.
+
+### 2. Point the daemon at mainnet-beta
+
+```bash
+DESIRED_DOUBLEZERO_ENV=mainnet-beta \
+	&& sudo mkdir -p /etc/systemd/system/doublezerod.service.d \
+	&& echo -e "[Service]\nExecStart=\nExecStart=/usr/bin/doublezerod -sock-file /run/doublezerod/doublezerod.sock -env $DESIRED_DOUBLEZERO_ENV" | sudo tee /etc/systemd/system/doublezerod.service.d/override.conf > /dev/null \
+	&& sudo systemctl daemon-reload \
+	&& sudo systemctl restart doublezerod \
+	&& doublezero config set --env $DESIRED_DOUBLEZERO_ENV  > /dev/null \
+	&& echo "✅ doublezerod configured for environment $DESIRED_DOUBLEZERO_ENV"
+```
+
+Wait ~30s, then `doublezero latency` should list mainnet devices.
+
+### 3. Open UDP 44880 on `doublezero0`
+
+```bash
+sudo iptables -A INPUT -i doublezero0 -p udp --dport 44880 -j ACCEPT
+sudo iptables -A OUTPUT -o doublezero0 -p udp --dport 44880 -j ACCEPT
+```
+
+UFW: `sudo ufw allow in on doublezero0 to any port 44880 proto udp` and the matching `out` rule. Also allow GRE and BGP as in [setup](setup.md).
+
+### 4. Confirm DoubleZero ID and primary validator
+
+The DoubleZero ID from setup on the **primary** must be on every backup (`~/.config/doublezero/id.json`).
+
+```bash
+doublezero address
+doublezero-solana passport find-validator -u mainnet-beta
+```
+
+Expect the primary: in gossip, in the leader schedule, “can connect as a primary”. On backups, run the same `find-validator`; they should **not** be leader-scheduled.
+
+One machine only: omit `--backup-validator-ids` / `backup_ids=` from later commands.
+
+### 5. Prepare the access message (primary)
+
+On the primary (active stake, identity in gossip):
+
+```bash
+doublezero-solana passport prepare-validator-access -u mainnet-beta \
+  --doublezero-address <DOUBLEZERO_ADDRESS> \
+  --primary-validator-id <NODE_ID> \
+  --backup-validator-ids <ID2>,<ID3>,<ID4>
+```
+
+Drop `--backup-validator-ids` if there are no backups (max 3). Copy the `solana sign-offchain-message …` line from the output.
+
+### 6. Sign with the validator identity key
+
+On the primary, run the printed command (identity keypair, **not** only the DoubleZero key):
+
+```bash
+solana sign-offchain-message \
+   service_key=<DOUBLEZERO_ADDRESS>,backup_ids=<ID2>,<ID3>,<ID4> \
+   -k <identity-keypair-file.json>
+```
+
+**Produces:** a signature string. Carry it into the next step.
+
+### 7. Request validator access
+
+```bash
+doublezero-solana passport request-validator-access -k <path-to-keypair> -u mainnet-beta \
+  --primary-validator-id <NODE_ID> \
+  --backup-validator-ids <ID2>,<ID3>,<ID4> \
+  --signature <SIGNATURE> \
+  --doublezero-address <DOUBLEZERO_ADDRESS>
+```
+
+Wait for Sentinel to validate and create the access pass. Optional: the agent can call **`check_edge_access`** with `pubkey` (`doublezero address`) and the host public IP until the pass is present.
+
+### 8. Connect IBRL
+
+```bash
+doublezero connect ibrl
+```
+
+Wait ~1 minute for GRE. Until then, status may be `down` / `Unknown`.
+
+```bash
+doublezero status
+```
+
+**Pass:** `up`, User Type `IBRL`, Network `mainnet-beta`, tunnel typically `doublezero0`.
+
+```bash
+ip route
+```
+
+Expect BGP-learned routes via `doublezero0`.
+
+---
+
+## Gotchas
+
+1. **Wrong env.** Testnet packages / `DESIRED_DOUBLEZERO_ENV=testnet` will not land on mainnet-beta.
+2. **Identity not in gossip.** Junk IDs on the same IP cannot register the machine.
+3. **Backups must share the primary DoubleZero ID.** Copy `id.json`; do not keygen a second identity.
+4. **Sign with the validator identity**, not the DoubleZero key.
+5. **Status down for ~1 minute** after `connect ibrl` is normal while GRE comes up.
+
+---
+
+## See also
+
+- [Validator Mainnet-Beta Connection](DZ Mainnet-beta Connection.md)
+- [Setup](setup.md)
+- Next: [Publish shreds (Edge)](solana-shreds-publisher-runbook.md)

docs/solana-shreds-publisher-runbook.md

@@ -0,0 +1,88 @@
+---
+description: LLM-oriented runbook — configure a connected Solana validator to publish leader shreds to DoubleZero Edge. Served to the MCP via GitHub raw; not published on the docs site.
+---
+
+# Publish shreds (Edge) — runbook
+
+This page is for the DoubleZero MCP (`get_onboarding_runbook`) via GitHub raw. It is
+not published on the docs site.
+
+1. Connect the [DoubleZero MCP](mcp.md) (`https://data.doublezero.xyz/api/mcp`).
+2. Confirm the validator is **already on DoubleZero IBRL** (mainnet-beta). If not, finish [Connect validator (IBRL Mainnet)](solana-ibrl-runbook.md) first.
+3. Walk the steps below. Human guide: [Validator Multicast Connection](Validator Multicast Connection.md).
+
+**What success looks like:** validator sends leader shreds to `233.84.178.1:7733`, multicast publish on `edge-solana-shreds` is up, and [publisher-check](https://data.doublezero.xyz/dz/publisher-check) shows publishing after at least one leader slot.
+
+This path is for **validators**. Trading firms that want to *subscribe* use [Subscribe to shreds](solana-shreds-runbook.md).
+
+---
+
+## Prerequisites
+
+| Need | Notes |
+|------|--------|
+| IBRL tunnel already up | [IBRL Mainnet runbook](solana-ibrl-runbook.md) / [human guide](DZ Mainnet-beta Connection.md). |
+| Supported client | Jito-Agave **3.1.9+**, JitoBam 3.1.9+, Frankendancer, or Harmonic **3.1.11+**. Other versions will not publish. |
+| Restart window | Adding the shred destination requires a validator restart. |
+
+---
+
+## Steps
+
+### 1. Point the client at the Edge shred group
+
+**Jito-Agave (v3.1.9+) and Harmonic (3.1.11+)** — in the validator start script add:
+
+```text
+--shred-receiver-address 233.84.178.1:7733
+```
+
+You can send to Jito and `edge-solana-shreds` at the same time. Restart the validator.
+
+**Frankendancer** — in `config.toml`:
+
+```toml
+[tiles.shred]
+additional_shred_destinations_leader = [ "233.84.178.1:7733", ]
+```
+
+Restart the validator.
+
+### 2. Publish on the multicast group
+
+```bash
+doublezero connect ibrl && doublezero connect multicast --publish edge-solana-shreds
+```
+
+**Verify:** `doublezero status` still IBRL/up, and the user is a publisher on `edge-solana-shreds`.
+
+Live group IPs: `doublezero multicast group list`. All shred feeds use UDP **`7733`**; the IP selects the feed.
+
+| Feed | Address |
+|------|---------|
+| `edge-solana-shreds` (leader) | `233.84.178.1:7733` |
+| `edge-solana-retrans-eu` | `233.84.178.12:7733` |
+| `edge-solana-retrans-apac` | `233.84.178.13:7733` |
+| `edge-solana-retrans-amer` | `233.84.178.14:7733` |
+
+### 3. Confirm publishing
+
+Open [publisher-check](https://data.doublezero.xyz/dz/publisher-check). You will not see confirmation until the validator has published leader shreds for **at least one slot**.
+
+Healthy: outbound spikes aligned with leader slots (sawtooth). Steady outbound with no slot pattern is **retransmit** (bad).
+
+---
+
+## Gotchas
+
+1. **Wrong client version.** Not 3.1.9+ / 3.1.11+ → nothing useful on the wire.
+2. **Retransmit flag left on.** Remove `--shred-retransmit-receiver-address` from Jito-Agave. Check the **No Retransmit Shreds** column on publisher-check (2-epoch vs recent-slot views).
+3. **Not yet a leader.** Dashboard stays empty until a leader slot.
+4. **IBRL not up.** Do not start here; finish IBRL first.
+
+---
+
+## See also
+
+- [Validator Multicast Connection](Validator Multicast Connection.md)
+- [Validator Rewards](Validator Rewards.md)