@hybridlabor-api/aos 4.2.0 → 4.4.0

package/mcps/tdmcp/docs/superpowers/specs/2026-06-04-ai-party-ui24r-scene-arming-design.md

@@ -1,296 +0,0 @@
-# AI Party Ui24R Scene-Arming Design
-
-Date: 2026-06-04
-Status: design complete for dry-run MVP; live Ui24R execution blocked pending
-bench and venue validation
-Harness: `tdmcp-ai-party-mixer-design`
-
-## Summary
-
-Expand AI-Controlled Party with Soundcraft Ui24R mixer awareness through
-operator-approved scene arming. The AI may prepare a specific Ui24R show,
-snapshot, or cue change, but a human operator must approve one exact action
-before any adapter can dispatch it.
-
-The first implementation should ship contract + dry-run adapter only. Bitfocus
-Companion is the recommended first live backend after isolated bench validation.
-A direct Node bridge is a later backend after protocol validation on the target
-Ui24R firmware.
-
-## Source Baseline
-
-- Soundcraft's official Ui24R product page documents browser-based control,
-  firmware support for cue recall, and downloadable owner manuals:
-  <https://www.soundcraft.com/en-US/products/ui24R>
-- The Ui24R owner manual documents show/snapshot recall and the relationship
-  between shows and snapshots:
-  <https://www.soundcraft.com/en/product_documents/ui24r_manual_v1-0_web-pdf>
-- Bitfocus lists a Soundcraft Ui connection for Ui12, Ui16, and Ui24R with
-  show, snapshot, and cue loading actions, making Companion the lowest-risk
-  first live backend to bench:
-  <https://bitfocus.io/connections/soundcraft-ui>
-- Companion v4.3 documents HTTP button triggering and connection status
-  endpoints, which fits a preconfigured one-button scene dispatch instead of
-  exposing raw mixer commands:
-  <https://companion.free/user-guide/v4.3/remote-control/http-remote-control/>
-
-## MVP Flow
-
-```text
-voice / ChatGPT / setlist / TD audio analysis
-  -> AI Show Director
-  -> arm_mixer_scene
-  -> MixerScenePolicy + venue scene catalog
-  -> approval queue
-  -> authenticated operator approval
-  -> dry-run adapter first
-  -> Companion live backend after bench validation
-  -> audit log + dashboard
-```
-
-## Non-Goals
-
-- No autonomous mixer execution.
-- No mixer gain, PA mute, routing, patching, mute groups, phantom power, or
-  channel-strip control.
-- No raw Ui24R, Companion, WebSocket, HTTP, or arbitrary adapter command path.
-- No claim that approval means hardware changed.
-- No inferred rollback of mixer state.
-
-## Contract
-
-Add a new `ShowIntent` variant, separate from `arm_effect`:
-
-```ts
-type MixerSceneIntent = {
-  type: "arm_mixer_scene";
-  adapter_target: {
-    kind: "soundcraft_ui24r";
-    mixer_id: string;
-  };
-  target:
-    | { kind: "show"; show_name?: string; scene_id?: string; setlist_ref?: string }
-    | {
-        kind: "snapshot";
-        show_name?: string;
-        snapshot_name?: string;
-        scene_id?: string;
-        setlist_ref?: string;
-      }
-    | { kind: "cue"; show_name?: string; cue_name?: string; scene_id?: string; setlist_ref?: string };
-  request?: {
-    source?: "voice" | "chatgpt" | "setlist" | "td_audio_analysis" | "operator" | "scheduler";
-    raw_text?: string;
-    reason?: string;
-    requested_for?: string;
-  };
-};
-```
-
-Policy result:
-
-- valid catalog-backed mixer scene requests return `require_approval`;
-- the MVP never returns `allow` for mixer scenes;
-- missing config, unknown target, unresolved `setlist_ref`, unsupported target,
-  changed catalog hash, or unsafe scene diff returns `block`;
-- `mixer_gain`, `pa_mute`, and `audio_routing` remain blocked `arm_effect`
-  operations.
-
-Approval model:
-
-- add a generic `ShowApprovalTarget`;
-- preserve old effect approvals for backwards compatibility;
-- support `target.kind = "mixer_scene"` with exact adapter and scene target;
-- keep CLI verbs as `tdmcp-agent show-director approve <id>` and
-  `tdmcp-agent show-director cancel <id>`.
-
-Approved dry-run plan:
-
-```json
-{
-  "kind": "mixer_scene",
-  "action": "arm",
-  "adapter_target": { "kind": "soundcraft_ui24r", "mixer_id": "foh-ui24r" },
-  "mixer_scene": {
-    "kind": "snapshot",
-    "show_name": "AI Party Demo",
-    "snapshot_name": "Band A Intro"
-  },
-  "approval_id": "approval_0001",
-  "operator": "front-of-house",
-  "dry_run_only": true
-}
-```
-
-## Scene Catalog And Safety Manifest
-
-Every AI-armable mixer scene must be in a trusted venue catalog. The LLM may not
-invent or live-match scene names.
-
-Minimum catalog fields:
-
-- stable scene ID;
-- operator display label;
-- adapter target and operation: `recall_show`, `recall_snapshot`, or
-  `recall_cue`;
-- Ui24R show/snapshot/cue reference;
-- policy hash or catalog version;
-- exported checksum/hash or equivalent evidence;
-- allowed setlist sections;
-- last rehearsal/bench validation time;
-- rollback/manual recovery target;
-- safety notes;
-- forbidden-delta result.
-
-Hard gate: if the system cannot prove that a scene excludes gain, PA mute,
-routing, patch, channel-strip, mute-group, phantom-power, or other forbidden
-changes, that scene is not AI-armable in the MVP. It may still be manually
-recalled by the audio operator outside the AI path.
-
-## Adapter Strategy
-
-### Dry-Run
-
-The dry-run adapter is the first shipped backend. It consumes only approved
-mixer-scene plans, validates the catalog, and returns
-`hardware_changed: false`.
-
-It should simulate missing targets, stale approvals, policy hash mismatch,
-backend health failures, timeouts, readback mismatch, and duplicate idempotency
-keys.
-
-### Companion
-
-Companion is the first live backend after bench validation. tdmcp maps an
-approved scene ID to a preconfigured Companion button; Companion owns the
-Soundcraft Ui connection.
-
-Live states must stay precise:
-
-- HTTP button press accepted -> `sent` or `acknowledged`;
-- Soundcraft readback or operator confirmation -> `confirmed`;
-- timeout after send -> `unknown`;
-- no readback -> never claim confirmed.
-
-### Direct Node
-
-Direct Node bridge is later. It should use a typed allowlist around the
-Soundcraft Ui protocol and must not expose raw commands. It requires bench proof
-against the target Ui24R firmware before any live backend is enabled.
-
-## Policy Invariants
-
-- Caller-provided policy can make rules stricter, never softer.
-- Hard denies override all user/LLM policy input.
-- `preapproved`, `operator`, `approval_id`, `state`, and target metadata from
-  LLM/voice/ChatGPT are untrusted for live authority.
-- Approval must be explicit, fresh, one-shot, operator-authenticated, and tied
-  to the exact scene hash/version shown to the operator.
-- Approval re-runs policy immediately before adapter dispatch.
-- One idempotency key may produce at most one live send.
-- Unknown adapter state stops further AI mixer actions until operator review.
-- Panic/fallback bypasses the LLM and approval queue.
-
-## Dashboard And Runbook
-
-The operator surface must show current/next cue context, mixer adapter backend
-and health, pending approvals, exact scene label, adapter target, policy reason,
-safety summary, approval state, audit log, and panic/fallback state.
-
-Runbook language should use "arms", "prepares", "queues", and "requires
-approval" for AI behavior. Use "executes" only for operator-approved adapter
-actions. Use "confirmed" only with readback or explicit operator confirmation.
-
-## Implementation Slices
-
-### Slice 1: Contract + Dry-Run
-
-- Add `arm_mixer_scene` schema.
-- Add `MixerScenePolicy`/catalog validation.
-- Add generic approval target while preserving effect approvals.
-- Add `mixer_scene` dry-run action plan.
-- Add dry-run adapter interface/stub.
-- Add CLI schema/help examples.
-- Add unit tests and CLI tests.
-
-### Slice 2: Docs + Runbook
-
-- Update EN/PT AI-Controlled Party docs.
-- Add dry-run CLI example once implemented.
-- Add rehearsal/show-day checklist.
-- Keep live Soundcraft execution marked not live-validated.
-
-### Slice 3: Companion Bench Spike
-
-- Add Companion backend behind live-enable flag.
-- Map one bench-validated scene to one button.
-- Health-check Companion and Soundcraft connection.
-- Record `sent`, `acknowledged`, `confirmed`, `failed`, `unknown`.
-- Do not proceed without isolated Ui24R bench validation.
-
-### Slice 4: Direct Node Research
-
-- Prove exact Ui24R show/snapshot/cue APIs against target firmware.
-- Build fixture tests before live code.
-- Keep raw commands and non-MVP mixer operations unavailable.
-
-## Verification Gates
-
-Run for Slice 1:
-
-```bash
-npm run typecheck
-npm run build
-npm run lint
-npm test -- tests/unit/showDirector.test.ts tests/unit/cliAgent.test.ts
-```
-
-Add tests for valid show/snapshot/cue mixer targets, blocked unknown
-adapter/mixer IDs, unresolved `setlist_ref`, approval revalidation, dry-run-only
-plans, hard-deny custom-policy bypass attempts, and the CLI guarantee that no
-TD/Soundcraft/Companion/Node client is built during dry-run.
-
-Live gates:
-
-1. Contract gate.
-2. Dry-run CI gate.
-3. Companion bench gate.
-4. Direct Node bench gate.
-5. Venue rehearsal gate.
-6. Show-day gate.
-7. Post-show audit gate.
-
-## Handoff Prompt
-
-```text
-Use the tdmcp-pipeline harness to implement Slice 1 of
-docs/superpowers/specs/2026-06-04-ai-party-ui24r-scene-arming-design.md.
-
-Scope:
-- Add an operator-approved Soundcraft Ui24R mixer scene-arming contract to the
-  existing dry-run AI Show Director.
-- Add `arm_mixer_scene` as a new ShowIntent variant.
-- Add a MixerScenePolicy/catalog validator for predeclared Soundcraft Ui24R
-  show/snapshot/cue targets.
-- Add generic approval targets while preserving existing effect approvals.
-- Emit a dry-run-only `mixer_scene` action plan after authenticated approval.
-- Add a dry-run adapter interface/stub that never contacts hardware.
-- Keep `mixer_gain`, `pa_mute`, `audio_routing`, routing, patching,
-  channel-strip edits, phantom power and raw adapter commands blocked.
-- Include unit and CLI tests proving custom policy cannot soften hard denies and
-  no TD/Soundcraft/Companion/Node client is built during dry-run.
-
-Do not implement live Companion or direct Ui24R execution in this slice. Add only
-typed stubs or not-configured results for future live backends.
-```
-
-## Open Decisions
-
-- Panic handling for pending mixer approvals: recommended default is mark them
-  stale/cancelled after panic, requiring a new arm cycle.
-- Public term: use "show/snapshot/cue" in technical docs and "mixer scene
-  arming" as the umbrella term.
-- Live backend priority: dry-run first, Companion bench second, direct Node
-  later.
-- Confirmation wording: use `confirmed` only with readback or explicit operator
-  confirmation.

package/mcps/tdmcp/docs/superpowers/specs/2026-06-08-ai-controlled-party-producer-poc.md

@@ -1,232 +0,0 @@
-# AI-Controlled Party - Producer POC
-
-Date: 2026-06-08
-Status: Offline POC runner implemented; live TouchDesigner rehearsal still pending
-Scope: closed producer rehearsal, not a public in-venue show
-Anchor: `docs/superpowers/specs/2026-06-01-ai-controlled-party-plan.md`
-
-## Summary
-
-Build the recommended AI-Controlled Party proof of concept for a major event
-producer: real TouchDesigner visuals, two synchronized outputs, local
-audio-reactive behavior, text-or-transcript show requests, an operator-visible
-approval flow, and simulated physical effects.
-
-The claim for the POC is:
-
-> An AI show director can co-pilot a party by proposing and selecting approved
-> show intents while TouchDesigner keeps visual timing deterministic and a human
-> operator keeps final authority over unsafe effects.
-
-This POC must not present an LLM as an unrestricted stage controller. Fog,
-hazer, strobe, moving heads, lasers, mixer gain, PA mute, audio routing,
-blackout and freeze remain blocked, operator-only, or simulated unless a later
-venue-specific validation pass approves them.
-
-## Existing Surfaces
-
-| Surface | Status | Repo anchor |
-|---|---|---|
-| Show intent schema | Exists | `src/automation/showDirectorSchema.ts` |
-| Effect policy defaults | Exists | `src/automation/showDirectorSchema.ts` |
-| Dry-run runtime, approvals and audit log | Exists | `src/automation/showDirectorRuntime.ts` |
-| CLI dry-run policy proof | Exists | `tdmcp-agent show-director` |
-| Cues and morphs | Exists | `src/tools/layer2/manageCue.ts` |
-| Beat/cue autopilot | Exists | `src/tools/layer1/createAutopilot.ts` |
-| Stage dashboard | Exists, needs POC configuration | `src/tools/layer2/createStageDashboard.ts` |
-| Panic/freeze/blackout primitive | Exists | `src/tools/layer2/createPanic.ts` |
-| Two-output projection rehearsal | Exists as tool/example pattern | `src/tools/layer1/createMultiOutput.ts` |
-| Voice/STT/OpenClaw | Not live-validated | current docs mark as future validation |
-| Approval dashboard integrated with show-director | Gap | build after POC spec |
-| Physical fixtures/DMX/fog/strobe/PA | Out of scope for first POC | venue pass only |
-
-## Implemented POC Surface
-
-This spec now has a runnable offline rehearsal surface:
-
-- `src/automation/aiPartyFanIn.ts` normalizes operator text, voice transcripts,
-  dashboard actions, audio-section markers and scripted intents into
-  `ShowIntent`.
-- `src/automation/effectSimulator.ts` converts approved dry-run effect plans into
-  simulated-only visual/log events.
-- `src/automation/aiPartyPoc.ts` runs the producer rehearsal sequence, keeps
-  approval/audit state, and reports a dashboard-ready dry-run JSON envelope.
-- `tdmcp-agent ai-party-poc` exposes the runner without constructing a
-  TouchDesigner context.
-- `tests/unit/aiPartyFanIn.test.ts`, `tests/unit/aiPartyPoc.test.ts`,
-  `tests/unit/showDirectorFixtures.test.ts`, and focused CLI tests pin the
-  offline behavior.
-
-## Demo Shape
-
-Run this as a 15-20 minute closed rehearsal. The producer should see a show, not
-a slide deck:
-
-1. **Doors / preflight** - `doors_idle`
-   - Two outputs are visible: main wall and lyric/status wall.
-   - Dashboard shows bridge health, VU/BPM, cue queue and panic state.
-2. **AI welcome** - `ai_intro_text`
-   - A host-style announcement explains that physical effects are simulated.
-3. **Band intro + approval** - `band_intro`, `fog_sim_short`
-   - A pre-approved cue is allowed.
-   - A short fog request enters approval and produces no hardware plan.
-4. **Audio-reactive core** - `music_reactive_main`
-   - TouchDesigner reacts locally to beat, energy, transients or chroma.
-   - The AI only changes phrase, cue or mood, never beat-by-beat timing.
-5. **Voice/text mood shift** - `mood_shift_safe_red_chaos`
-   - A request such as "make it red and chaotic" becomes `change_mood`.
-   - Intensity and palette remain bounded by policy/runtime controls.
-6. **Safety proof** - `policy_block_demo`, `panic_recovery_test`
-   - Excess fog, strobe, mixer, PA, blackout, freeze and laser requests are
-     blocked or operator-only.
-   - Panic/freeze/recovery is demonstrated locally, independent from the LLM.
-7. **Closing / audit** - `credits_log`
-   - The AI/operator shows the audit trail: allowed, queued, approved, blocked
-     and cancelled decisions.
-
-## Architecture
-
-```text
-operator text / voice transcript / scripted demo request
-  -> fan-in normalizer
-  -> ShowIntentSchema
-  -> showDirectorRuntime policy + state
-  -> approval queue + audit log
-  -> safe action mapper
-  -> TouchDesigner cues, dashboard, panic and multi-output visuals
-```
-
-For the first POC, the fan-in can be manual or scripted: a typed request, a
-transcript pasted from another system, or a JSON intent fixture. Voice is allowed
-as theatre only if it still lands as text before `ShowIntentSchema`.
-
-## Technical Runbook
-
-### Before rehearsal
-
-1. Save or load a TouchDesigner project with these cues available:
-   `doors_idle`, `ai_intro_text`, `band_intro`, `fog_sim_short`,
-   `music_reactive_main`, `mood_shift_safe_red_chaos`, `policy_block_demo`,
-   `panic_recovery_test`, `credits_log`.
-2. Check bridge health:
-
-   ```bash
-   curl http://127.0.0.1:9980/api/info
-   ```
-
-3. Use a safe profile for any AI-facing session:
-   `TDMCP_TOOL_PROFILE=safe`, `TDMCP_RAW_PYTHON=off` when possible, and
-   `TDMCP_BRIDGE_TOKEN` on shared networks.
-4. Configure two outputs with a known test pattern and fallback black/freeze
-   path. Confirm there is no accidental overlap, clipping or unreadable text.
-5. Validate audio first with synthetic/file input. Switch to mixer/device only
-   after the synthetic path drives a stable feature CHOP.
-6. Build or open the stage dashboard with cue buttons, VU/BPM, FPS/cook readout
-   and a visible panic surface.
-7. Confirm `create_panic` or `tdmcp-agent panic` works without using the LLM.
-8. Disconnect or simulate all physical hazards: fog, hazer, strobe, moving
-   heads, lasers, DMX, PA mute/gain and routing.
-
-### During rehearsal
-
-1. Open with `doors_idle` and show the dashboard plus both outputs.
-2. Submit a pre-approved cue request:
-
-   ```bash
-   tdmcp-agent show-director --params '{"intent":{"type":"request_cue","cue":"band_intro","scene_id":"band_a_intro","preapproved":true}}'
-   ```
-
-3. Queue a short fog request and show that it requires approval:
-
-   ```bash
-   tdmcp-agent show-director --params '{"intent":{"type":"arm_effect","effect":"fog","duration_seconds":3,"intensity":0.35}}'
-   ```
-
-4. Run the audio-reactive scene from TouchDesigner. Do not ask the LLM to hit
-   beats or drops directly.
-5. Submit a bounded mood change:
-
-   ```bash
-   tdmcp-agent show-director --params '{"intent":{"type":"change_mood","mood":"red_chaotic_bounded","palette":["red","deep_blue","white"],"intensity":0.65}}'
-   ```
-
-6. Demonstrate blocked requests:
-
-   ```bash
-   tdmcp-agent show-director --params '{"intent":{"type":"arm_effect","effect":"fog","duration_seconds":30,"intensity":0.8}}'
-   tdmcp-agent show-director --params '{"intent":{"type":"arm_effect","effect":"mixer_gain","intensity":0.7}}'
-   ```
-
-7. Trigger panic/freeze/recovery locally, then show the audit trail.
-
-## Fixtures
-
-The rehearsal fixtures live under `tests/fixtures/show-director/`:
-
-- `producer-demo-setlist.json` - seven-moment scene list.
-- `producer-demo-policy.json` - POC safety policy.
-- `producer-demo-intents.jsonl` - allowed, approval-gated and blocked requests.
-
-These are intentionally lightweight so the next implementation wave can use
-them as test fixtures, CLI examples and operator rehearsal material.
-
-## Acceptance Criteria
-
-The POC passes when:
-
-- the demo runs end-to-end without restarting TouchDesigner;
-- two outputs remain framed and legible without accidental overlap;
-- audio moves visuals locally in real time;
-- `show-director` demonstrates `allow`, `require_approval` and `block`;
-- no hazardous hardware receives an executable plan;
-- panic/freeze/clear works without the LLM;
-- the audit log reconstructs what happened.
-
-The POC fails when:
-
-- the bridge is offline or stale during rehearsal;
-- projection output clips, covers or visually competes with dashboard/status UI;
-- audio features do not update;
-- dashboard/panic is inaccessible;
-- a hazardous request produces a live hardware plan;
-- any physical fog, strobe, DMX, laser, mixer or PA action is triggered without
-  venue-specific validation.
-
-## Parallel Implementation Lanes
-
-Use a fan-out/fan-in workflow. Builders can work in parallel on isolated files;
-one lead integrates shared registries/docs after review.
-
-| Lane | Owner type | Write scope | Goal |
-|---|---|---|---|
-| Fan-in runtime | builder | new `src/automation/aiPartyFanIn.ts` + test | Normalize operator text/transcripts/scripted events into `ShowIntent`. |
-| Approval dashboard | builder | new dashboard module or isolated extension spec | Display last AI decision, approval queue, audit log and approve/cancel controls. |
-| Effect simulator | builder | new simulator module + test | Convert approved dry-run effects into visible/logged simulation states, never DMX. |
-| Rehearsal recipe/runbook | docs/runtime builder | fixtures + docs | Turn this POC into repeatable CLI/TD steps. |
-| Integration | single writer | shared registries/CLI/docs only after builders finish | Wire any shipped runtime surfaces without conflicts. |
-| QA | independent verifier | no production edits | Run offline gates, bridge checks, layout checks and live TD validation when reachable. |
-
-## Next Agent Prompt
-
-```text
-Use parallel agents to prepare the AI-Controlled Party producer POC from
-docs/superpowers/specs/2026-06-08-ai-controlled-party-producer-poc.md.
-
-Do not connect physical DMX/fog/strobe/mixer/PA hardware. Keep all hazardous
-effects dry-run or simulated.
-
-Fan out:
-- Agent A: design/implement an isolated fan-in runtime that maps operator text
-  or transcript events to ShowIntent, with unit tests.
-- Agent B: design an approval/audit dashboard surface without editing shared
-  stage-dashboard files unless the lead approves the integration path.
-- Agent C: design/implement an effect simulator that represents fog/hazer/strobe
-  as safe visual/log states only.
-- Agent D: turn the fixtures and runbook into rehearsal commands and docs.
-
-Fan in:
-- A single integrator reviews the outputs, edits shared files if needed, and
-  runs focused tests plus docs build.
-- QA verifies allow/approval/block decisions, panic independence, bridge health,
-  and visual layout integrity for desktop/mobile dashboard states.
-```

package/mcps/tdmcp/docs/superpowers/specs/2026-06-08-deep-doppelganger-design.md

@@ -1,136 +0,0 @@
-# Deep Doppelganger TouchDesigner Design
-
-## Goal
-
-Build a surprising live TouchDesigner project called `deep_doppelganger` that uses
-the webcam as the visual input, depends on body/hand tracking for performance
-control, and produces one clean video TOP output named `out_video`.
-
-## Current Runtime
-
-- TouchDesigner is running locally with the tdmcp bridge at
-  `http://127.0.0.1:9980`.
-- The verified bridge target is `NewProject.1.toe`.
-- The bridge reports TD `099`, build `2025.32820`, Python `3.11.10`, and bridge
-  `0.6.1`.
-- A create/delete canary already proved that tdmcp can mutate the project.
-
-## Concept
-
-The performer is turned into a delayed, unstable double. The camera remains
-recognizable enough for the audience to read the human body, but the tracked
-body and hands drive a second presence: a ghost image, a spectral depth cloud,
-an opening feedback tunnel, and a glitch layer that becomes more aggressive
-when motion rises or tracking confidence falls.
-
-## Approved Direction
-
-Use the "Doppelganger Profundo" direction:
-
-- Live camera as the source material.
-- Pose and hands as the primary control signal.
-- Optical flow as a secondary motion/failure signal.
-- A single final video output ready for projector, perform window, recording, or
-  downstream video output.
-
-## Architecture
-
-Create a top-level base COMP:
-
-```text
-/project1/deep_doppelganger
-```
-
-Inside it, use organized zones with no accidental overlap:
-
-- `input_camera`: webcam capture, mirror/fit, and a stable `live_camera` TOP.
-- `tracking`: body and hand channels, normalized into a `tracking_bus` CHOP.
-- `motion_flow`: optical-flow or frame-difference analysis from the camera.
-- `ghost_delay`: delayed and displaced copy of the live camera.
-- `depth_cloud`: point-cloud or depth-relief interpretation of the camera.
-- `feedback_tunnel`: feedback loop whose opening/decay responds to the hands.
-- `flow_glitch`: displacement/glitch layer driven by flow and tracking loss.
-- `layer_mixer`: final composite.
-- `output`: final `out_video` TOP. Target `1920x1080` on licensed systems;
-  this verified Non-Commercial TD session renders at `1280x720` because of the
-  TouchDesigner output cap.
-- `control_panel`: artist-facing custom parameters.
-
-## Data Flow
-
-```text
-camera TOP
-  -> live_camera
-  -> tracking source and motion-flow source
-
-pose/hands CHOPs
-  -> tracking_bus
-  -> control expressions for ghost, cloud, tunnel, glitch
-
-optical-flow/frame-diff CHOP
-  -> motion_energy
-  -> flow_glitch and fallback instability
-
-visual entities
-  -> layer_mixer
-  -> out_video
-```
-
-## Performance Controls
-
-Expose these controls on `/project1/deep_doppelganger/control_panel` or the root
-`deep_doppelganger` COMP:
-
-- `Shock`: overall intensity.
-- `GhostDelay`: delay amount and opacity of the double.
-- `DepthScale`: point-cloud or relief depth.
-- `TunnelOpen`: how much the feedback tunnel opens.
-- `GlitchBite`: displacement/glitch strength.
-- `TrackingPanic`: automatic instability amount when tracking confidence falls.
-- `CameraOpacity`: original camera visibility in the final composite.
-- `Blackout`: emergency output black.
-
-## Tracking Contract
-
-The piece should depend on tracking:
-
-- Hand span and wrist height should visibly affect the tunnel and ghost.
-- Body center should pull the ghost/point cloud.
-- Tracking confidence should affect the stability of the image.
-
-The system should still remain operable if tracking temporarily drops:
-
-- Hold last good tracking values briefly.
-- Raise `TrackingPanic`.
-- Increase glitch/ghost instability instead of cutting to black.
-
-## Failure Behavior
-
-- If the tdmcp bridge is offline, stop and report the bridge status before
-  editing.
-- If MediaPipe is unavailable, build the camera and visual network with a
-  synthetic/fallback tracking bus so the patch opens, but mark live tracking as
-  unverified.
-- If camera permission blocks the Video Device In TOP, keep the network intact
-  and leave visible notes/warnings in the report.
-- Never treat a successful app launch alone as proof; validate `/api/info` and a
-  preview or node-health check.
-
-## Validation
-
-The project is ready only when:
-
-- `/api/info` responds.
-- Tracking nodes or fallback channels exist.
-- `out_video` exists and is previewable.
-- The network has no reported errors on the main container.
-- Nodes are arranged in stable zones with no accidental overlap.
-- A desktop visual check confirms the project structure is readable.
-
-## Scope Boundaries
-
-This design builds a live TouchDesigner project in the running TD session. It
-does not add a new tdmcp MCP tool or release a new package version.
-
-The implementation may create a small reusable script or command plan if that is
-the clearest way to keep the live build repeatable.