docs consolidation

docs/modules/graph/prep/2025-11-20-ops-0001-prep.md

@@ -1,12 +0,0 @@
-# Graph Ops Prep — PREP-GRAPH-OPS-0001
-
-Status: Draft (2025-11-20)
-Owners: Ops Guild
-Scope: Capture dashboard/runbook updates pending next demo outputs.
-
-## Needs
-- Latest demo metrics/dashboards to review.
-- Runbook sections to update once demo outputs land.
-
-## Handoff
-Use as prep artefact; update after next demo provides dashboards/runbooks.

docs/modules/graph/prep/2025-11-22-graph-api-schema-outline.md

@@ -1,66 +0,0 @@
-# Graph API schema outline (prep for GRAPH-API-28-001)
-
-Status: draft outline · Date: 2025-11-22 · Owner: Graph API Guild
-Scope: Establish OpenAPI/JSON schema primitives for search/query/paths/diff/export endpoints, tile streaming, budgets, and RBAC headers. This is a staging note for sprint 0207 Wave 1.
-
-## 1) Shared headers and security
-- `X-Stella-Tenant` (required, string)
-- `Authorization: Bearer <token>`; scopes: `graph:read`, `graph:query`, `graph:export` as applicable per route.
-- `X-Request-Id` optional; echoed in responses.
-- Rate limit headers: `X-RateLimit-Remaining`, `Retry-After` for 429 cases.
-
-## 2) Tile envelope (streaming NDJSON)
-```jsonc
-{
-  "type": "node" | "edge" | "stats" | "cursor" | "diagnostic",
-  "seq": 1,
-  "cost": { "consumed": 12, "remaining": 988, "limit": 1000 },
-  "data": { /* node/edge/payload depending on type */ }
-}
-```
-- Deterministic ordering: breadth-first by hop for paths/query; lexicographic by `id` inside each hop when stable ordering is needed.
-- Cursor tile: `{"type":"cursor","token":"opaque"}` for resume.
-- Stats tile: counts, depth reached, cache hit ratios.
-
-## 3) `/graph/search` (POST)
-Request body (summary):
-- `query` (string; prefix/exact semantics), `kinds` (array of `node` kinds), `limit`, `tenant`, `filters` (labels, ecosystem, scope), `ordering`.
-Response: stream of tiles (`node` + minimal neighbor context), plus final cursor/diagnostic tile.
-Validation rules: enforce `limit <= 500`, reject empty query unless `filters` present.
-
-## 4) `/graph/query` (POST)
-- Body: DSL expression or structured filter object; includes `budget` (nodes/edges cap, time cap), `overlays` requested (`policy`, `vex`, `advisory`), `explain`: `none|minimal|full`.
-- Response: streaming tiles with mixed `node`, `edge`, `stats`, `cursor`; budgets decremented per tile.
-- Errors: `429` budget exhausted with diagnostic tile including partial cursor.
-
-## 5) `/graph/paths` (POST)
-- Body: `source_ids[]`, `target_ids[]`, `max_depth <= 6`, `constraints` (edge kinds, tenant, overlays allowed), `fanout_cap`.
-- Response: tiles grouped by path id; includes `hop` field for ordering; optional `overlay_trace` when policy layer requested.
-
-## 6) `/graph/diff` (POST)
-- Body: `snapshot_a`, `snapshot_b`, optional `filters` (tenant, kinds, advisory keys).
-- Response: tiles of `node_added`, `node_removed`, `edge_added`, `edge_removed`, `overlay_delta` (policy/vex/advisory), plus `manifest` tile with counts and checksums.
-
-## 7) `/graph/export` (POST)
-- Body: `formats[]` (`graphml`, `csv`, `ndjson`, `png`, `svg`), `snapshot_id` or `query_ref`, `include_overlays`.
-- Response: job ticket `{ job_id, status_url, checksum_manifest_url }`; downloads streamed with deterministic manifests.
-
-## 8) Error schema (shared)
-```jsonc
-{
-  "error": "GRAPH_BUDGET_EXCEEDED" | "GRAPH_VALIDATION_FAILED" | "GRAPH_RATE_LIMITED",
-  "message": "human-readable",
-  "details": {},
-  "request_id": "..."
-}
-```
-
-## 9) Open questions to settle before sign-off
-- Final DSL surface vs structured filters for `/graph/query`.
-- Exact cache key and eviction policy for overlays requested via query.
-- PNG/SVG render payload (pre-signed URL vs inline streaming) and size caps.
-
-## 10) Next steps
-- Convert this outline into OpenAPI components + schemas in repo (`docs/api/graph-gateway-spec-draft.yaml`) by 2025-11-24.
-- Add JSON Schema fragments for tiles and error payloads to reuse in SDKs.
-- Review with Policy Engine Guild to lock overlay contract version for GRAPH-API-28-006.

docs/modules/graph/prep/2025-11-24-graph-api-schema-review.md

@@ -1,32 +0,0 @@
-# Graph API schema review notes (planned)
-Date: 2025-11-24 (target)
-Scope: Review OpenAPI/JSON schema for search/query/paths/diff/export, tiles, budgets, and overlays alignment (GRAPH-API-28-001).
-
-## Attendees
-- Graph API Guild: TBD
-- Policy Engine Guild: TBD
-- QA Guild (observer): TBD
-
-## Pre-reads
-- `docs/api/graph-gateway-spec-draft.yaml`
-- `docs/modules/graph/prep/2025-11-22-graph-api-schema-outline.md`
-- Policy overlay contract references: `POLICY-ENGINE-30-001..003`
-
-## Agenda
-- Validate tile envelope shape and budget semantics.
-- Confirm overlay payload fields and versioning handshake with Policy Engine.
-- Decide DSL vs structured filter scope for `/graph/query` v1.
-- Agree on export manifest shape and size caps for PNG/SVG.
-
-## Decisions
-- Tile envelope shape frozen for draft v0.0.3-pre: `node|edge|stats|cursor|diagnostic`, `seq`, optional `cost`, overlays keyed by overlay kind with `{kind, version, data}`.
-- Resume support will rely on cursor tokens; requests accept optional `cursor` field for search/query/diff to resume streams.
-- Path responses carry `pathHop` on node/edge tiles; depth capped at 6 as per sprint scope.
-- Rate-limit/budget headers documented (`X-RateLimit-Remaining`, `Retry-After`), with 429 response carrying error envelope.
-
-## Open items / follow-ups
-- Overlay payload contract (fields for policy/vex/advisory) to be versioned once POLICY-ENGINE-30-001..003 freeze; placeholder schema retained.
-- Export render limits (PNG/SVG size caps) still pending Observability/UX sign-off.
-
-## Outcomes snapshot
-- Draft spec updated at `docs/api/graph-gateway-spec-draft.yaml` (v0.0.3-pre) and referenced in sprint Execution Log.