docs: add BGP status reporting guidance for telemetry agent

CLAUDE.md

@@ -0,0 +1,46 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Repo Is
+
+This is the documentation site for **DoubleZero**, a decentralized high-performance networking protocol built by Malbec Labs. The site is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) and deployed to GitHub Pages at `https://docs.malbeclabs.com/`.
+
+## Commands
+
+Install dependencies:
+```bash
+pip install mkdocs-material
+```
+
+Preview locally with live reload:
+```bash
+mkdocs serve
+```
+
+Build static site to `./site/`:
+```bash
+mkdocs build
+```
+
+## Deployment
+
+Merging to `main` triggers the GitHub Actions workflow (`.github/workflows/`) which builds and deploys the site to GitHub Pages automatically. There is no manual deploy step.
+
+## Site Structure
+
+Navigation is defined in `mkdocs.yml`. The docs directory is flat — all content pages live directly under `docs/`. The two primary audiences are:
+
+- **Users** — validators, RPC nodes, and MEV infrastructure that connect to DoubleZero to use the network. Docs cover setup, connection modes (IBRL and multicast), paying fees, and troubleshooting.
+- **Contributors** — entities with underutilized fiber optic links and hardware who extend the network. Docs cover hardware requirements, device provisioning, and operations.
+
+## Key Concepts
+
+- **DoubleZero Device (DZD)**: Physical switching hardware running the DoubleZero Agent software at each end of a contributor's fiber link.
+- **DoubleZero Exchange (DZX)**: Interconnect points (like internet exchanges) where contributor links peer together in major metros.
+- **Multicast groups**: Logical groups with publisher/subscriber allowlists for efficient multi-recipient data distribution. Only the DoubleZero Foundation can create groups; owners manage the allowlists.
+- **Connection modes**: IBRL (individual routing) and multicast — both require users to first run `doublezero keygen` and complete setup as described in `docs/setup.md`.
+
+## MkDocs Extensions in Use
+
+The site uses several pymdownx extensions — notably `pymdownx.superfences` with Mermaid diagram support, `admonition` for warning/note callouts, and `pymdownx.arithmatex` for MathJax. When adding content, use the existing patterns for these (e.g., `??? warning` for collapsible warnings, ` ```mermaid ` fences for diagrams).

docs/contribute-operations.md

@@ -291,6 +291,31 @@ doublezero_device_telemetry_agent_peer_discovery_not_found_tunnels{local_device_
 - `up` - This is the timeseries metric automatically generated by prometheus if the scrape instance is healthy and reachable. If it is not, either the agent is not reachable or the agent is not running.
 - `doublezero_device_telemetry_agent_errors_total` with an `error_type` of `submitter_failed_to_write_samples` - This is a signal the telemetry agent can't write samples onchain, which could be do to management connectivity issues on the device.
 
+### BGP Status Reporting
+
+The telemetry agent can periodically submit each user's BGP session status (Up/Down) onchain. This enables idle user detection and connection diagnostics without relying solely on onchain activation state.
+
+To enable, add `--bgp-status-enable` to the `doublezero-telemetry` daemon configuration:
+
+```
+daemon doublezero-telemetry
+   exec /usr/local/bin/doublezero-telemetry --local-device-pubkey $PUBKEY --env $ENV --keypair $KEY_PAIR --bgp-status-enable
+   no shutdown
+```
+
+Optional tuning flags:
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--bgp-status-interval` | `60s` | Collection and submission frequency |
+| `--bgp-status-refresh-interval` | `6h` | Periodic re-submission interval even if status unchanged |
+| `--bgp-status-down-grace-period` | `30s` | Minimum duration before reporting a session as Down |
+
+When metrics are also enabled, the following additional metrics are exposed:
+
+- `doublezero_bgpstatus_submissions_total` — total onchain submissions by status (Up/Down/Unknown)
+- `doublezero_bgpstatus_submission_duration_seconds` — submission latency histogram
+
 ---
 
 ## Link Management

docs/contribute-provisioning.md

@@ -928,6 +928,15 @@ daemon doublezero-telemetry
         no shut
     ```
 
+!!! note "BGP Status Reporting (Optional)"
+    To enable onchain BGP session status reporting, add `--bgp-status-enable` to the exec command:
+    ```
+    daemon doublezero-telemetry
+        exec /usr/local/bin/doublezero-telemetry --local-device-pubkey <DEVICE_ACCOUNT> --env mainnet --keypair /mnt/flash/metrics-publisher-keypair.json --bgp-status-enable
+        no shut
+    ```
+    The submission interval (default `60s`), refresh interval (default `6h`), and Down grace period (default `30s`) can be tuned with `--bgp-status-interval`, `--bgp-status-refresh-interval`, and `--bgp-status-down-grace-period` respectively.
+
 #### Verify it's running
 
 ```bash