Cockpit Vision

Status: draft. Not normative. Use as the working brief for the status/, ops/, and qa/ perspective workers (and their JobCache counterparts) until concrete decisions land in wiki/content/architecture/.

Each perspective is split per kind (ui/, api/, mcp/) following the <product>-<perspective>-<kind> worker-naming convention: every - in the worker name corresponds to a directory boundary. The *-mcp workers are minimal Hono apps whose tools fan out via service binding to the sibling *-api worker (status-mcp → status-api, ops-mcp → ops-api, qa-mcp → qa-api for both CV and JC). Nothing durable lives in the MCP workers; the api workers own D1/R2/operator-actions.

This folder describes the product vision for CareerVector's and JobCache's admin/observability perspectives — the cockpit through which the operator sees the system thinking in real time, and the public face that lets users trust the platform is alive.

The cockpit IS the Runtime Diagnostics surface in ANALYTICS-LAYERS.md. The vision sharpens what that surface should answer and how the data should get there. Read the existing canonical docs first; this study extends them, it does not replace them.

Reading order

File	What it covers
`vision.md`	Product vision: what the cockpit is, who uses it, the questions it must answer, status vs. ops split.
`ops-status-v1.md`	First CareerVector ops/status iteration: five surfaces, API-first contract, FinOps/quotas, user stories, and v1 non-goals.
`finops-runway-contract.md`	FinOps API projection: resource pressure, monthly runway chart data, weakest-link ranking, and vendor-neutral extension rule.
`vendor-inventory-2026-05-19.md`	Ops vendor sweep: clouds/products seen in code and secret inventory, plus the auto-registration model for runtime bindings, usage ledgers, and repo catalog rows.
`ai-gateway-fit.md`	Cloudflare AI Gateway fit: server-first adoption for CareerVector-owned AI traffic, not normal browser BYOK calls.
`telemetry-tiers.md`	Green/yellow/red model: telemetry tier (consent) vs. operational state (rollup). Workspace owner control. Today's vs. end-state.
`architectures.md`	Six concrete delivery architectures for cockpit data, with cost/latency/failure tradeoffs and a labelled recommendation.
`careervector-cockpit.md`	CareerVector-specific cockpit: views, metrics, drill-downs, recovery actions, what status projects publicly.
`jobcache-cockpit.md`	JobCache-specific cockpit: business-facing corpus/ingestion view. Distinct from CV because the audience and concerns differ.
`jobcache-mcp-hosting-investigation.md`	Historical: should `jobcache-mcp` move from CF Workers to Render alongside the API? Decision was option (c) — embed inside `jobcache-interface` (the renamed `jobcache-api`). Render free-plan limits, three options, labelled recommendation, reversal path.

Prior art in this repo

The cockpit must compose with what already exists. Don't reinvent:

@cv/health — Health/Check/Metric shape; rollupHealthState, projectPublic already wired into both status workers.
@cv/perspective-shared — readCareerVectorHealth, readJobcacheHealth, requireAdminForPage.
ANALYTICS-EVENT-CATALOG.md — green/yellow/red telemetry tiers, Axiom EU-Frankfurt ingest, daily-token heartbeats, p2p probes.
ANALYTICS-LAYERS.md — the four-surface vocabulary (Workspace Analytics / Platform Analytics / Runtime Diagnostics / Quality).
REALTIME-ARCHITECTURE-V3.md §SSE Fanout Worker — the text/event-stream tailer on workspace_sub_doc_ops, workspace_process_requests, workspace_agent_presence.
workspace_process_requests — the queue/lease ledger that powers Workspace Intelligence. Cockpit projects it cross-workspace.

Out of scope here

User-facing Workspace Analytics. Lives under careervector.corbet.ch/{workspace}/analytics, distinct surface.
Platform Analytics as a commercial dataset. Different reader, different privacy model. The cockpit may share computation; it does not share UI.
CI/quality runs. Belong on a Quality sub-surface (status.careervector.corbet.ch/quality), tracked separately.