(CODUX-146) Document the 3D Chat runtime contract

[numnx]

🧩 Task: Document the 3D Chat runtime contract

Automated task PR opened by Code UX for T07.

📋 Summary

Sprint: Sprint 214 · 3d Chat Agent · Task: T07

Make the 3D Chat agent truthful, expressive, stable, and richly interactive by separating project-manager activity from background work, adding validated response emotions and animations, improving idle/resume life, refining animated tools, and documenting the complete runtime contract.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.6-sol

⏱️ Timing

Started	2026-07-11 10:47:15 UTC
Finished	2026-07-11 10:51:39 UTC
Duration	4m 24s

📊 Token Usage

Metric	Value
Input tokens	128,780
Cached input tokens	1,572,608
Output tokens	10,498
Total tokens	1,711,886
Invocations	1
Tool calls	20
Active time	3m 55s

Included usage estimate (subscription/local login): $1.75

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Update the repository documentation so maintainers and users can understand how 3D Chat derives runtime state, consumes agent effects, presents background activity, and handles idle interactions and reduced motion.

## Scope
- `docs/dashboard/design-system-chat.md`: cinematic stage behavior, PM-versus-background activity, `agentEffect` and `codeux:agent` contracts, thought cues, idle greetings, work tools, accessibility, and reduced motion.
- `docs/dashboard/design-system-agents.md`: avatar expression/animation vocabulary, Three.js lifecycle, tool catalog, disposal, and fallback rules.
- `docs/architecture/chat-thread-runtime.md`: dashboard-reply effect parsing, metadata persistence, native markdown fence behavior, and external-channel stripping.
- `docs-web/user/dashboard/chat.md`.
- `docs-web/user/dashboard/agents.md`.
- `docs-web/architecture/virtual-workers.md` and/or the matching public architecture section for the chat runtime.

## Implementation Requirements
1. Document exact field names, supported values, bounds, precedence rules, and malformed-payload fallback behavior for `agentEffect` and `codeux:agent`.
2. Document that only the selected Project Manager’s active reply state drives working expression/tools, while unrelated agent activity appears as a truthful thought/status cue.
3. Document idle and welcome-back choreography, work-tool behavior, reduced-motion and WebGL fallback semantics, accessibility expectations, and the commands needed to validate the surface; then run the repository’s documentation publication check.

## Constraints
- Update canonical `docs/` content first and keep corresponding `docs-web/` pages consistent.
- Do not create `docs-release/` or a new page when the existing chat, agents, and architecture pages are sufficient.
- Describe implemented behavior only; do not claim unverified browser or CI results.

## Verification
- Run `pnpm run check:docs-web`.
- Verify the documented paths and anchors with `rg "agentEffect|codeux:agent|Project Manager|reduced motion|welcome-back|work tool" docs/dashboard docs/architecture docs-web/user/dashboard docs-web/architecture`.
- Run `pnpm run typecheck:dashboard` if documentation examples or linked contract snippets affect dashboard-facing types.

🌿 Branch Info

Base: feature/CODUX-214-3d-chat-agent
Head: task/feature-codux-21-t07-codex-2f952499-mrg8pw3w

---

🤖 Generated by Code UX