up

docs/modules/graph/README.md

@@ -35,11 +35,26 @@ Graph Indexer + Graph API build the tenant-scoped knowledge graph that powers bl
 - Logs/traces: structured ETL logs, query planner traces, WebGL interaction telemetry (once UI lands).
 - Offline bundles: deterministic `nodes.jsonl`, `edges.jsonl`, overlay manifests + DSSE signatures, consumable by Export Center and CLI mirroring.
 
+## Operations & runbook (Sprint 030)
+- Dashboards: import `Observability/graph-api-grafana.json` (panels for latency, budget denials, overlay cache ratio, export latency). Apply tenant filter in every panel.
+- Health checks: `/healthz` should be 200; search/query/paths/diff/export endpoints require `X-Stella-Tenant`, `Authorization`, and scopes (`graph:read/query/export`).
+- Key metrics (new):
+  - `graph_tile_latency_seconds` histogram (label `route`); alert when p95 > 1.5s for 5m.
+  - `graph_query_budget_denied_total` counter (label `reason`); investigate spikes (>50 in 5m).
+  - `graph_overlay_cache_hits_total` / `graph_overlay_cache_misses_total`; watch miss ratio > 0.4 for 10m.
+  - `graph_export_latency_seconds` histogram (label `format`); alert when p95 > 2s for ndjson/graphml.
+- Triage playbook:
+  - Budget denials: lower default edges/nodes budget or guide callers to request smaller scopes; verify overlay includes are truly required.
+  - Overlay cache misses: ensure cache TTL is ≥5m; check overlay service connectivity to Policy Engine; warm cache by replaying recent hot nodes.
+  - Export slowness: reduce export `Limit`, offload PNG/SVG to worker, and confirm disk I/O headroom.
+  - If alerts fire, capture tenant, route, cursor/budget values, and recent deploy SHA in incident note.
+
 ## Key docs & updates
 - [`architecture.md`](architecture.md) — inputs, pipelines, APIs, storage choices, observability, offline handling.
 - [`implementation_plan.md`](implementation_plan.md) — phased delivery roadmap, work breakdown, risks, test strategy.
 - [`schema.md`](schema.md) — canonical node/edge schema and attribute dictionary (keep in sync with indexer code).
 - Updates: `docs/updates/2025-10-26-scheduler-graph-jobs.md`, `docs/updates/2025-10-26-authority-graph-scopes.md`, `docs/updates/2025-10-30-devops-governance.md` for the latest decisions/dependencies.
+- Index: see `architecture-index.md` for data model, ingestion pipeline, overlays/caches, events, and API/observability pointers.
 
 ## Epic alignment
 - **Epic 5 – SBOM Graph Explorer:** Graph Indexer, Graph API, saved queries, overlays, Console/CLI experiences, Offline Kit parity.