|
| 1 | +# Dashboard Module |
| 2 | + |
| 3 | +## Positioning |
| 4 | + |
| 5 | +This module is the repository's **web operator surface**. |
| 6 | + |
| 7 | +Read it as: |
| 8 | + |
| 9 | +- the browser-based control surface for runs, sessions, reviews, and command |
| 10 | + visibility |
| 11 | +- a way to inspect and operate CortexPilot Command Tower orchestration truth from the web |
| 12 | +- a repo-owned UI for evaluating control-plane behavior |
| 13 | + |
| 14 | +Do **not** read it as: |
| 15 | + |
| 16 | +- a polished customer-facing SaaS product |
| 17 | +- a standalone web application with its own independent product roadmap |
| 18 | +- evidence that every workflow here is already broad-market ready |
| 19 | + |
| 20 | +## Module Responsibility |
| 21 | + |
| 22 | +- Provide run, workflow, session, and review visualization for CortexPilot Command Tower |
| 23 | + orchestration output. |
| 24 | +- Surface operator-facing status, artifacts, and control points for the web. |
| 25 | +- Surface intake preview, approval summaries, and run diagnostics as |
| 26 | + operator-readable decision objects rather than raw payloads alone. |
| 27 | + |
| 28 | +## Why This Module Exists |
| 29 | + |
| 30 | +If `apps/orchestrator/` is the machine room, `apps/dashboard/` is the glass |
| 31 | +window operators use to see what the machine room is doing. Its job is |
| 32 | +visibility and control, not pretending the whole repository is already a |
| 33 | +finished consumer product. |
| 34 | + |
| 35 | +## Input / Output |
| 36 | + |
| 37 | +- Input: API responses from the orchestrator backend. |
| 38 | +- Output: operational UI views for runs, events, contracts, reports, and |
| 39 | + command surfaces. |
| 40 | + |
| 41 | +## High-value operator surfaces |
| 42 | + |
| 43 | +- PM workspace: registry-driven task-pack selection plus `execution_plan_report` |
| 44 | + preview before execution starts. |
| 45 | +- Agents: the first-screen role catalog now also hosts a repo-owned role |
| 46 | + configuration desk for previewing and saving future compiled defaults |
| 47 | + (`system_prompt_ref`, bundle refs, and role-level runtime binding) while |
| 48 | + `task_contract` remains the only execution authority. |
| 49 | +- Workflow views: workflow-case summaries derived from run manifests and PM |
| 50 | + session bindings, now with queue/SLA read surfaces and a read-only |
| 51 | + `Workflow read model` card sourced from `workflow_case_read_model`. |
| 52 | +- Dashboard `Run Detail` and `Workflow Case detail` now resolve page-level |
| 53 | + title/subtitle/degraded-state copy from the shared locale substrate via the |
| 54 | + UI locale cookie, so the high-value detail routes stay aligned with the |
| 55 | + English-first / `zh-CN` operator contract instead of drifting through |
| 56 | + page-local literals. |
| 57 | +- Run Detail: incident packs, approval summaries, replay compare reports, and a |
| 58 | + read-only role-binding summary in the existing `Status & Contract` card, so |
| 59 | + bundle/runtime posture is visible on the main run surface without creating a |
| 60 | + second execution-authority switch. |
| 61 | +- Contracts and Run Detail now also surface the derived runtime capability |
| 62 | + posture (`lane`, `compat_api_mode`, `provider_status`, `tool_execution`) so |
| 63 | + operators can read chat-style compatibility vs fail-closed tool execution |
| 64 | + without overstating the current runtime boundary. |
| 65 | +- The staged UI-audit/dashboard-build path now depends on |
| 66 | + `apps/dashboard/lib/types.ts` explicitly re-exporting task-pack/runtime |
| 67 | + helper values and on `scripts/install_dashboard_deps.sh` recreating its |
| 68 | + runtime log directory before each install attempt, so smoke failures track |
| 69 | + product regressions instead of staging drift. |
| 70 | +- Builder/public discovery: the home builder section now surfaces direct |
| 71 | + `Read-only MCP quickstart` and `API and contract quickstart` entry cards so |
| 72 | + operators can jump from the web control surface into the truthful public |
| 73 | + onboarding ladder before diving into package-level docs. |
| 74 | +- Home discovery now compresses the old ecosystem / integrations / AI surfaces / |
| 75 | + builder sprawl into one adoption-path section so the dashboard front door |
| 76 | + behaves more like a router than a wall of repeated summaries. |
| 77 | +- That same adoption layer now treats `/compatibility/` as the primary routing |
| 78 | + decision card, swaps the redundant compatibility action button for a lighter |
| 79 | + `/use-cases/` proof-first CTA, and keeps `/integrations/`, `/skills/`, |
| 80 | + `/mcp/`, `/api/`, and `/builders/` as the deeper branches once the job is |
| 81 | + clear. |
| 82 | +- The dashboard public-docs resolver still treats `/integrations/`, |
| 83 | + `/skills/`, and `/compatibility/` as first-class public docs routes so |
| 84 | + public-docs base overrides do not strand those CTA links on app-local paths. |
| 85 | +- The same public-home polish keeps the explicit `Open use-case guide` side |
| 86 | + door routed through the public-docs resolver, so the proof-first walkthrough |
| 87 | + stays visible without turning the dashboard back into a second full routing |
| 88 | + matrix. |
| 89 | +- The contract-facing builder card now points to the repo-owned |
| 90 | + `packages/frontend-api-contract/docs/README.md` guide instead of only the raw |
| 91 | + generated `.d.ts` surface, so builders get a human-readable package entrypoint |
| 92 | + before opening the generated types. |
| 93 | +- The home surface and PM workspace now also carry small `zh-CN` screen-reader |
| 94 | + onboarding lists plus the clearer `Back to bottom` chat action wording, so |
| 95 | + the first-step contract stays discoverable in localized assistive flows |
| 96 | + without changing the visible English-first operator copy. |
| 97 | +- PM intake/chat regressions should keep the `Back to bottom` wording and the |
| 98 | + localized onboarding note aligned with this README in the same patch, so the |
| 99 | + dashboard doc-drift gate tracks the same visible operator-language contract |
| 100 | + that the PM intake tests now assert. |
| 101 | + |
| 102 | +## Strongest Signals |
| 103 | + |
| 104 | +- operator-first web workflows |
| 105 | +- command visibility over product marketing polish |
| 106 | +- alignment with the repository's three truth layers |
| 107 | + |
| 108 | +## Key Config |
| 109 | + |
| 110 | +- API base and frontend fetch layer are defined in `apps/dashboard/lib/api.ts`. |
| 111 | +- Runtime defaults and startup commands are coordinated from the repo root |
| 112 | + quickstart in `README.md`. |
| 113 | +- Dashboard dependency hotfixes should keep the root `package.json` overrides, |
| 114 | + root `pnpm-lock.yaml`, and `apps/dashboard/pnpm-lock.yaml` aligned so |
| 115 | + dashboard-only transitive patches do not drift from the workspace baseline. |
| 116 | +- `apps/dashboard/pnpm-lock.yaml` is a maintained dashboard-specific lockfile; |
| 117 | + keep transitive security patch updates in the same change set when dashboard |
| 118 | + dependency metadata changes. |
| 119 | +- The optional `depcheck` package is intentionally absent from the default |
| 120 | + dashboard dependency set; the dead-code gate already skips when the probe is |
| 121 | + unavailable, so leaving it out avoids carrying an otherwise unnecessary |
| 122 | + `brace-expansion` advisory path in the maintained lock surface. |
| 123 | +- Dashboard dependency lock refreshes are repo-owned: when transitive package |
| 124 | + fixes land here, keep `apps/dashboard/pnpm-lock.yaml` aligned with the root |
| 125 | + `package.json` / `pnpm-lock.yaml` change set. |
| 126 | +- Current transitive hardening includes the `yaml` override used through |
| 127 | + `cosmiconfig@7.1.0`; keep the dashboard lockfile and the root override in |
| 128 | + sync so the dashboard does not drift onto an older parser patch level. |
| 129 | +- Current lock maintenance also pins patched `picomatch` / `brace-expansion` |
| 130 | + transitive paths through the repo-owned override set so GitHub security |
| 131 | + receipts and the dashboard lockfile stay aligned. |
| 132 | +- Current security-only lock maintenance also pins `lodash-es@4.18.1` through |
| 133 | + both the root workspace and `apps/dashboard` override surfaces so the |
| 134 | + tracked `lighthouse@13.0.3` transitive chain does not fall back to the |
| 135 | + vulnerable `lodash-es@4.17.23` path on either maintained lockfile. |
| 136 | +- When a dashboard security-only lock refresh lands, keep this module README in |
| 137 | + the same change set so doc-drift gates can trace the maintenance decision to |
| 138 | + the dashboard surface that actually owns the lockfile. |
| 139 | + |
| 140 | +## Common Troubleshooting |
| 141 | + |
| 142 | +- Dependencies missing: `pnpm --dir apps/dashboard install` |
| 143 | +- Test failure: `pnpm --dir apps/dashboard test` |
| 144 | +- Typecheck: `pnpm --dir apps/dashboard exec tsc -p tsconfig.typecheck.json --noEmit` |
| 145 | + |
| 146 | +## Quality Gate |
| 147 | + |
| 148 | +- Coverage gate (stage-1): >= 85% |
| 149 | +- Command Tower regression tests now treat the English-first labels, drawer |
| 150 | + names, and quick-action copy as the canonical operator contract; update the |
| 151 | + dashboard tests in the same patch whenever those public-facing labels move. |
| 152 | +- Search page regression tests should wait for the terminal promote-status copy |
| 153 | + instead of the first rendered status node because the UI intentionally passes |
| 154 | + through `Promoting evidence...` before it settles on success or failure. |
| 155 | +- The current CI unblock patch also keeps the PM and RunDetail regression suite |
| 156 | + aligned with the English-first operator surface, including Command Tower |
| 157 | + session copy, PM composer controls, and RunDetail tab/status wording. |
| 158 | +- Workflow Case detail now also renders the latest linked run's |
| 159 | + `workflow_case_read_model` for operator inspection, but that card remains a |
| 160 | + read-only mirror below `task_contract` execution authority. |
| 161 | +- Run Detail now mirrors `role_binding_read_model` inside the existing |
| 162 | + `Status & Contract` card, and that note keeps `task_contract` explicit as the |
| 163 | + only execution authority. |
| 164 | +- Agents now also uses a registry-backed read-only role catalog on the first |
| 165 | + screen, so operators can inspect skills/MCP/runtime posture before drilling |
| 166 | + into individual agent seats or scheduler backlog. |
| 167 | +- Contracts now acts as a bundle/runtime inspector: each card keeps the task |
| 168 | + contract envelope visible while projecting the derived bundle/runtime summary |
| 169 | + as read-only operator context rather than a control surface; role-default |
| 170 | + edits belong on `Agents`, not on the contract inspector. |
0 commit comments