---
name: doc-agent-mount-rollout
description: Roll out a scoped per-document agent panel (voice + live-action + side-chat) to N content views by extending the existing doc-agent system additively.
---
# Doc Agent Mount Rollout

## When to use
- User asks to add the `<doc-agent-panel>` (or equivalent scoped agent) to multiple views beyond the initial mounts (e.g. notes, databases, workflows).
- User asks for a per-document agent with capability-gated voice / live-action / chat, scoped to one document at a time.
- Task involves expanding `DocAgentType` / capability matrix / tool-policy to cover new content surfaces.
- Voice or live-action streams need to be branched between grid-scoped and doc-scoped sessions.

## How to apply
1. **Phase 0 — Inventory & plan.** Read the existing mounts (`notes.ts`, `databases.ts`, `workflows.ts`) and the current `doc-agent-panel`, `doc-agent-prompts.ts`, `tool-policy.ts`, `live-action-context.ts`. Write a plan doc (e.g. `docs/doc-agent-universal-plan.md`) containing: view-by-view inventory, the new `DocAgentType` entries, a capability matrix (voice / liveActionObserve / liveActionAct / chat / tools), and a risk list. Don't skip the doc — later phases reference it.
2. **Phase 1 — Type + policy + gateway (additive only).** Extend the `DocAgentType` union, add per-type prompt builders, add a `DOC_AGENT_CAPABILITIES` matrix, add a `clampModalities` helper that intersects requested modalities with the matrix, and extend the tool-policy allow list ADDITIVELY (never remove existing entries). Add gateway RPCs `attach_live_action` / `detach_live_action` / `set_modalities` / `get_modalities`. Add a `DocScope` + `filterEvent` so doc sessions only see their own document's events. Build a `buildDocLiveActionPreamble` mirroring the grid one.
3. **Phase 2 — Route voice/live-action by sessionKey shape.** In the voice-stream server, detect doc-scoped sessions via a sessionKey regex (e.g. `doc:<type>:<id>`). Route their preamble through `buildDocLiveActionPreamble`, return HTTP 403 when the voice modality is gated off in the matrix, and isolate grid-context so it does NOT leak into doc sessions. Keep the grid path untouched.
4. **Phase 3 — Mount the panel per-view.** For each target view, mount `<doc-agent-panel>` with view-local document state (id + type). Wire capabilities-aware voice & live-action toggle buttons that read from the matrix, plus a bounded observed-events strip (last 5). Implement attach/detach lifecycle on view enter/leave. **Do not touch the 3 existing mounts.** If a view is read-only / has no controller wired, leave `liveActionAct: false` in the matrix as a deferred item rather than faking it.
5. **Phase 4 — Tests.** Add unit tests for prompt builders, the capability/clamp matrix, the gateway RPCs, and `filterEvent` scoping. Aim for one test file per concern.
6. **Phase 5 — Summary.** Append a summary table and file:line integration-point refs to the plan doc so future agents can find the seams.
7. **Verify** server-side `tsc`, UI `tsc` (no NEW errors in touched files — pre-existing errors are fine), and all new tests pass before declaring done.
8. **Defer explicitly.** Call out anything you skipped (e.g. docTypes that conflict with existing agents, views with no client wired, missing event producers) in the final summary rather than half-implementing.

## Rules
- Never remove or rewrite entries in the existing tool-policy allow list — extension is additive only.
- Never touch the 3 pre-existing mounts (`notes`, `databases`, `workflows`) while rolling out new ones.
- Never let grid-context bleed into doc-scoped sessions; branch on sessionKey shape, not on a global flag.
- Never claim a docType supports `liveActionAct` unless a controller is actually wired on that view — gate it off in the matrix and list it as deferred.
- Always write the Phase-0 plan doc before editing code; later phases cite it.
- Always clamp requested modalities through the capability matrix server-side, and return HTTP 403 (not a silent downgrade) when voice is gated off.
- Always scope events with `DocScope` + `filterEvent` so doc A's agent never sees doc B's events.
- Always verify both `tsc` passes (server + UI) and the new tests before committing each phase.
- Always commit per-phase with a `feat(doc-agent): phase N — …` message so the rollout is bisectable.