[Epic]: AGT Studio umbrella tracker

## Summary

**AGT Studio** is the single unified UI for the Agent Governance Toolkit. It collapses the seven scattered UI surfaces that exist today (six Streamlit/HTTP dashboards plus the `console.html` pitch asset) into one canonical, deployable product surface. Launched standalone with `agt ui`, or hosted as a VS Code / Cursor webview against the same SPA bundle.

This issue is the **umbrella tracker** for the entire build. Every child issue links back here. Maintainers picking up individual child issues should treat this issue as the master reference for scope, constraints, decisions, and sequencing.

Build is **sequential, one issue at a time, top-to-bottom**. Cross-cutting and deprecation issues can be opportunistically batched once their replacement panel ships.

## Status

**3 of 32 issues closed.** Current: #3893 (Epic 0, issue 4).

## Issues

Execution order, top-to-bottom. The order respects the dependencies defined in ADR 0028 and the locked-in decisions below.

| # | Epic | Issue | Status | Issue # | PR # |
| --- | --- | --- | --- | --- | --- |
| 1 | 0 | Engine API: contract spec + OpenAPI document | Closed | #3011 | #3013 |
| 2 | 0 | Engine API: capability metadata implementation | Closed | #3026 | #3027 |
| 3 | 0 | Engine API: FastAPI reference adapter + `/policies` gap-fix | Closed | #3066 | #3085 |
| 4 | 0 | Engine API: conformance test suite | Filed | #3893 | — |
| 5 | 1a | AGT Studio: package + CI scaffold + CODEOWNERS | Filed | #3898 | — |
| 6 | 1b | AGT Studio: sidecar threat model + security posture doc | Not filed | — | — |
| 7 | 1b | AGT Studio: `agt serve` implementation | Not filed | — | — |
| 8 | 1c | AGT Studio: SPA shell + transport abstraction + `postMessage` contract test | Not filed | — | — |
| 9 | 1d | AGT Studio: `agt ui` launcher + first end-to-end slice | Not filed | — | — |
| 10 | 2 | AGT Studio: policy browse (inventory + list + detail view) | Not filed | — | — |
| 11 | 3a | AGT Studio: Monaco editor + schema + inline lint | Not filed | — | — |
| 12 | 3b | AGT Studio: workspace picker + atomic save + Studio-local audit log | Not filed | — | — |
| 13 | 4a | AGT Studio: policy test runner (wraps `policy_test.replay`) | Not filed | — | — |
| 14 | 4b | AGT Studio: what-if simulator + regression diff | Not filed | — | — |
| 15 | 5 | AGT Studio: engine + policy version explorer | Not filed | — | — |
| 16 | 7a | Engine API: WebSocket transport + CloudEvents decision-event schema | Not filed | — | — |
| 17 | 7b | AGT Studio: live-decisions panel | Not filed | — | — |
| 18 | 8a | AGT Studio: shadow-agent panel | Not filed | — | — |
| 19 | 8b | AGT Studio: trust network panel | Not filed | — | — |
| 20 | 9a | AGT Studio: audit log viewer + Merkle chain integrity badge | Not filed | — | — |
| 21 | 9b | AGT Studio: signed evidence export (CloudEvents bundle per ADR 0021) | Not filed | — | — |
| 22 | 6 | AGT Studio: VS Code / Cursor webview shell (reuses Epic 1c transport) | Not filed | — | — |
| 23 | 10 | Deprecate `examples/demos/governance-dashboard/` | Not filed | — | — |
| 24 | 10 | Deprecate `agent-mesh/examples/trust-dashboard/` | Not filed | — | — |
| 25 | 10 | Deprecate `agent-hypervisor/examples/docker-compose/app/dashboard.py` | Not filed | — | — |
| 26 | 10 | Deprecate `agent-os/modules/scak/dashboard.py` | Not filed | — | — |
| 27 | 10 | Archive `examples/demos/presentation/console.html` to `examples/legacy/`| Not filed | — | — |
| 28 | 11 | AGT Studio: sidecar security review | Not filed | — | — |
| 29 | 11 | AGT Studio: accessibility audit (WCAG 2.1 AA) | Not filed | — | — |
| 30 | 11 | AGT Studio: dependency supply-chain audit + lockfile policy | Not filed | — | — |
| 31 | 11 | AGT Studio: browser matrix decision + CI coverage | Not filed | — | — |
| 32 | 11 | AGT Studio: docs site section under `docs/studio/` | Not filed | — | — |

Status values: `Not filed` → `Filed` → `In progress` → `Closed`.

## Source of truth

- **ADR 0028** (`docs/adr/0028-agt-studio-unified-ui.md`) — binding scope, merged via PR #2639.
- **RFC discussion**: #2638.
- **Inspiration**: Azure Policy lifecycle UI (browse → inspect → author → simulate → version). Studio is opinionated for AGT, not a portal clone.

Do not re-litigate scope in child issues. If a proposed change conflicts with ADR 0028, raise a new ADR instead.

Non-negotiables (set by ADR 0028; violation = review reject)

1. **Read-only for runtime state.** No approvals, no quarantine, no production hot-reload, no credential rotation, no incident workflow changes, no operator/SOC console capabilities. That direction was explicitly rejected; the write-path risk plus auth surface plus 24/7 support load are out of scale for AGT, and Sentinel, Defender, and Foundry already own that space.
2. **The only write surface is policy YAML on local disk** (Epic 3 only), constrained by a workspace picker that the user explicitly chooses. No writes under loaded runtime policy directories unless the user adds them to the workspace allowlist.
3. **One canonical UI.** New UI features land here, not in a new dashboard.
4. **Policy-first.** Visibility features (audit, trust, decisions) exist to support policy authoring, testing, and debugging, not as a separate operator plane.
5. **No SSO, SAML, OIDC, RBAC, or multi-tenancy.** Studio is an authoring and visibility tool. Production deployments wrap the engine API behind their own auth.

Locked-in decisions (do not re-litigate per issue)

| # | Decision | Detail |
| --- | --- | --- |
| 1 | SPA stack | React 18 + TypeScript + Vite + TanStack Query + Tailwind. No separate ADR; tactical pick. |
| 2 | Package layout | New top-level `agent-governance-studio/`. PyPI `agent-governance-studio`, Python import `agent_governance_studio`, npm `@microsoft/agent-governance-studio`. |
| 3 | Release cadence | Lockstep monthly tag with the rest of AGT. CODEOWNERS names are filled in by the Epic 1a scaffold PR. |
| 4 | Sidecar auth | Loopback default, no token. Non-loopback bind requires a token from `~/.config/agt/studio-token` or env var. |
| 5 | Issue strategy | Per-Epic tracker issue + child issues, all under the "AGT Studio" milestone. No Project board. |
| 6 | CLI extension policy configs | Copilot, Claude, and Antigravity CLI policy configs are first-class in the Epic 2 policy corpus alongside the 73 examples and 14 templates, not in a separate tab. |
| 7 | Licensing | MIT, same as AGT-wide. No separate license policy, no new CI gate. Follow the existing AGT TypeScript-package conventions for npm transitive deps. |
| 8 | Maintainer escalation | ADR 0028 is sufficient cover. No per-issue signoff. File issues, open PRs, standard review process picks them up. |
| 9 | Studio-local audit log | `~/.config/agt/studio-audit.log`, separate from the engine audit chain. Records every policy-file write from Epic 3. |
| 10 | Telemetry | Off by default. If a user opts in, the only sink is a local debug log under `~/.config/agt/`. No remote telemetry sink, ever. |

Codebase grounding (what already exists, do not re-implement)

- **CLI host**: `agent_compliance.cli.agt.AgtGroup` (Click) at `agent-governance-python/agent-compliance/src/agent_compliance/cli/agt.py`. Plugin discovery via the `agt.commands` entry-point group. `agt ui` and `agt serve` plug in from the new Studio package without touching `agent-compliance`.
- **Policy replay engine**: `agent_compliance.policy_test.replay(...)` returns a `ReplayReport` with `to_dict()`. Epic 4 wraps this; do not rewrite it. Today it is synchronous and uses top-level fixture globbing only; Epic 4 wraps cancellation, progress streaming, and explicit fixture-discovery semantics around it.
- **Dashboard backend (library only, no HTTP today)**: `agentmesh.dashboard.api.DashboardAPI` with `get_live_traffic`, `get_leaderboard`, `get_trust_trends`, `get_audit_log`, `get_compliance_report`, `get_overview`. Subscribes to `EventBus`. The Engine API (Epic 0) wraps these read methods for HTTP/WebSocket exposure.
- **FastAPI sidecars already in tree** that the reference adapter (Epic 0) consolidates: `agentmesh/server/sidecar.py`, `policy_server.py`, `audit_collector.py`, `trust_engine.py`, `api_gateway.py`. The surface today is fragmented and inconsistent. Two known gaps Studio cannot work around:
- `GET /api/v1/policies` returns counts only, not a usable inventory.
- `POST /api/v1/policy/reload` is runtime-mutating and must NOT be in the Studio client (enforced via capability metadata, see Epic 0).
- **Policy corpus** (Epic 2 inventory source): 73 example policies under `examples/policies/...` and 14 production templates under `agent-governance-python/agent-os/templates/policies/`. Plus the CLI extension policy configs from decision 6.
- **No SPA in the repo** outside the Chrome extension. The Studio frontend is greenfield.
- **No WebSocket / SSE** in any existing server. All live UIs poll today. Epic 7a lands the WebSocket transport on the Engine API.

Existing UI surfaces being collapsed (7 dashboards → 1 Studio + 1 Grafana template pack)

Per ADR 0028 dispositions. Epic 10 owns the deprecation cycle.

| # | Path | Current purpose | Disposition |
| --- | --- | --- | --- |
| 1 | `examples/demos/governance-dashboard/` (Streamlit, simulated) | Fleet, shadow agents, lifecycle funnel, allow/deny feed, trust heatmap | Deprecate. Port shadow-agent + risk-distribution patterns into Studio (Epic 8). |
| 2 | `agent-governance-python/agent-mesh/examples/trust-dashboard/` (stdlib HTTP, real) | Trust graph, scores, credentials, protocol traffic, compliance | Deprecate. Port trust UI into Studio Trust panel (Epic 8). Protocol traffic moves to a Grafana template. |
| 3 | `agent-governance-python/agent-hypervisor/examples/docker-compose/app/dashboard.py` (stdlib HTTP, real) | Sessions, rings, sagas, liability, events | Replace with Studio agent-fleet view (Epic 8). |
| 4 | `agent-governance-python/agent-sre/src/agent_sre/slo/dashboard.py` (`SLODashboard` library only) | SLOs, cost, chaos, incidents, progressive delivery | Keep as a data model. Replace UI surface with Grafana templates. |
| 5 | `agent-governance-python/agent-os/modules/scak/dashboard.py` (Streamlit, simulated) | SCAK memory and telemetry | Deprecate. No port; all simulated data. |
| 6 | `agent-governance-python/agent-os/modules/observability/src/agent_os_observability/dashboards.py` (Grafana JSON templates) | Pre-built Grafana dashboards | Keep and expand. Studio surfaces deep-links into these. |
| 7 | `examples/demos/presentation/console.html` (static pitch asset) | Pitch deck only | Archive to `examples/legacy/console.html` with a README. |

Working agreements for child issues

- **Link back**: every child issue starts with `Tracker: #2729`.
- **Milestone**: "AGT Studio".
- **Labels**: `enhancement` plus the relevant package label (`agent-mesh`, `agent-governance`, `ide-extension`, etc.) plus `architecture` if it touches Engine API surface, plus `security` if it touches the sidecar or any write path. `Priority: HIGH` for all Epic 0 work (it is the gate).
- **Issue bodies via `--body-file`** (preserves backticks and code blocks; never inline PowerShell strings).
- **Verify the rendered description on GitHub** after creation. If formatting is broken, fix with `gh issue edit --body-file`.
- **PRs**: conventional commit titles, DCO signoff, Copilot co-author trailer. One issue may produce one or more PRs; the issue closes when all its acceptance criteria are green.
- **PR descriptions**: must follow the project's PR description standard (Summary, Problem, Changes table, Testing). See repo `AGENTS.md`.
- **Scope discipline**: keep PRs scoped to a single Epic's child issue. No bundling unrelated changes.
- **Umbrella status updates**: each time an issue is filed or closed, update its row in the Issues table above and the status counter at the top.

## Acceptance for this umbrella

This tracker stays open until all of the following are true:

- All 32 child issues are closed or explicitly out of scope.
- `agt ui` is documented in onboarding as the default Studio launcher.
- All six existing Streamlit/HTTP dashboards have at least one release of overlap with their Studio replacement, then are deprecated or archived per Epic 10.
- The read-only invariant has a CI test that fails the build if any `runtime_mutating: true` route appears in the generated Studio client (Epic 1d).
- No new runtime write-path control was introduced as part of Studio.
- Engine API contract spec (issue #3011) is merged before Studio MVP code merges. (Originally planned as ADR 0029; maintainer decision to ship as a spec doc — see #3011 for rationale.)

## References

- ADR 0028: `docs/adr/0028-agt-studio-unified-ui.md`
- ADR 0017: Audit chain integrity (Merkle)
- ADR 0021: CloudEvents schema
- Repo `AGENTS.md`: PR description standard, security rules, supply-chain rules, post-merge review checklist