@hybridlabor-api/aos 4.2.0 → 4.4.0

package/mcps/tdmcp/docs/reference/coverage-harness.md

@@ -1,61 +0,0 @@
-# Coverage harness & gate
-
-tdmcp tracks executable-TypeScript test coverage with a small harness on top of
-Vitest's v8 coverage provider, and enforces a **no-regression floor** in CI.
-
-## Scope
-
-Coverage is measured over `src/**/*.ts` only. Generated knowledge data
-(`src/knowledge/data/**`) is excluded — it is imported reference JSON, not
-executable code, so it must never drive the numbers up or down. See
-`vitest.config.ts` (`coverage.include` / `coverage.exclude`).
-
-## Commands
-
-| Command | What it does |
-|---|---|
-| `npm run test:coverage` | Raw Vitest coverage run; **fails if any threshold in `vitest.config.ts` is not met**. This is the gate. |
-| `npm run coverage:harness` | Runs the coverage gate, then writes a ranked gap report to `_workspace/coverage/latest.md` and a machine-readable `coverage/coverage-summary.json`. |
-| `npm run coverage:harness -- --summary-only` | Re-render the report from the existing `coverage/coverage-summary.json` without re-running the suite. |
-| `npm run coverage:harness -- --limit=40 --min-lines=91` | Print more ranked gaps and **fail if line coverage drops below the requested floor** (use the +5pp target while a coverage wave is in flight). |
-
-The report ranks files by a gap score
-(`missing_lines*3 + missing_functions*2 + missing_branches`) and buckets the
-top files into suggested test waves by surface (entrypoints/CLI/LLM,
-resources/knowledge, prompts, tools, server/transport).
-
-## The gate (G2)
-
-The thresholds in `vitest.config.ts` are a **no-regression floor**: they are
-locked at the measured baseline, floored to the integer at or below current
-coverage. They must always PASS at current coverage and must never be lowered.
-
-### Baseline (2026-06-21)
-
-| Metric | Measured | Locked threshold |
-|---|---:|---:|
-| Statements | 84.71% | 84 |
-| Branches | 70.73% | 70 |
-| Functions | 83.02% | 83 |
-| Lines | 86.6% | 86 |
-
-CI runs `npm run test:coverage`, so any regression below these floors red-lights
-the build. When a coverage wave raises the real numbers, **raise the thresholds
-to the new floor** in the same change — that is how the gate ratchets up.
-
-### Tracked +5pp target
-
-The roadmap goal (`docs/ROADMAP.md` → "G2 — Test coverage") is **lines and
-branches ≥ baseline + 5 pp**:
-
-| Metric | Baseline | +5pp target |
-|---|---:|---:|
-| Lines | 86.6% | **≥ 91** |
-| Branches | 70.73% | **≥ 75** |
-
-This is the next coverage wave's objective. Drive a wave toward it with
-`npm run coverage:harness -- --min-lines=91` (and the ranked gap list), then
-ratchet the `vitest.config.ts` floors up as the numbers land. Branches is the
-widest gap (70.73% → 75 is ~4.3 pp, roughly 800 uncovered branches), so it needs
-the most new tests; lines (86.6% → 91 is ~4.4 pp, ~1,200 uncovered lines) follows
-the same wave.

package/mcps/tdmcp/docs/reference/environment.md

@@ -1,116 +0,0 @@
----
-description: "Environment variables for tdmcp, the TouchDesigner MCP server — configure the bridge host and port, auth token, vault path and exec safety."
----
-
-# Environment variables
-
-Configuration can come from environment variables or from an optional JSON config
-file. Environment variables win over file values, so CI, Docker and MCP-client
-config stay simple. Every variable is optional and has a sensible default.
-
-## Server
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `TDMCP_TD_HOST` | `127.0.0.1` | TouchDesigner bridge host. |
-| `TDMCP_TD_PORT` | `9980` | Web Server DAT port. |
-| `TDMCP_TRANSPORT` | `stdio` | MCP transport: `stdio` (default) or `http` (Streamable HTTP). |
-| `TDMCP_HTTP_PORT` | `3939` | Port for the HTTP transport (when `TDMCP_TRANSPORT=http`). |
-| `TDMCP_EVENTS` | `on` | Subscribe to TD WebSocket events and forward them as MCP logging notifications (`on`/`off`). |
-| `TDMCP_RAW_PYTHON` | `on` | Whether to expose the two raw-Python escape-hatch tools (`execute_python_script`, `exec_node_method`) in the MCP server. Set to `off` to lock them out for restricted setups. This removes only those two client-authored-code tools — many higher-level tools still send their own *templated* Python to the bridge, so `off` is **not** "no code runs in TD". The bridge itself now keeps arbitrary-code endpoints disabled unless `TDMCP_BRIDGE_TOKEN` or explicit `TDMCP_BRIDGE_ALLOW_EXEC=1` is set in TouchDesigner's environment. |
-| `TDMCP_TOOL_PROFILE` | `full` | Tool exposure profile. `full` registers every tool; `safe` hides destructive/raw-code tools, including raw Python, node deletion, DAT rewrites, checkpoint/component/package writes and preview-asset writes — a strict superset of `TDMCP_RAW_PYTHON=off`. Use `safe` for an autonomous in-TD agent (e.g. dotsimulate's LOPs MCP Client). Default `full` keeps existing clients unchanged. |
-| `TDMCP_BRIDGE_TOKEN` | _(unset)_ | Optional shared bearer token. When set, the server sends it and the bridge requires it — set the **same** value in TouchDesigner's environment to turn auth on. |
-| `TDMCP_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent` (logged to stderr). |
-| `TDMCP_REQUEST_TIMEOUT_MS` | `10000` | Per-request timeout to the bridge, in milliseconds. |
-| `TDMCP_CONFIG_FILE` | _(unset)_ | Optional JSON config file. Keys match the internal config names (`tdHost`, `tdPort`, `requestTimeoutMs`, etc.). |
-| `TDMCP_PROFILE` | _(unset)_ | Optional profile name inside the selected config file (`profiles.<name>`), whether that file is set with `TDMCP_CONFIG_FILE` or found through the default search paths. File base values load first, profile values override them, env vars override both. |
-| `TDMCP_VAULT_PATH` | _(unset)_ | Absolute path to an Obsidian vault (a folder of Markdown notes). Enables the [vault tools](/reference/tools#obsidian-vault); a leading `~/` is expanded. Leave unset to disable them. |
-
-## Local copilot (`tdmcp chat`)
-
-These configure the [local LLM copilot](/reference/cli#local-copilot-tdmcp-chat).
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `TDMCP_LLM_BASE_URL` | `http://127.0.0.1:11434/v1` | OpenAI-compatible chat endpoint. Defaults to local Ollama; point it at LM Studio, a cloud GPU or a paid API. |
-| `TDMCP_LLM_MODEL` | `qwen2.5:3b` | Model id the copilot requests (must be pulled in the backend, e.g. `ollama pull qwen2.5:3b`). Bump to `qwen2.5:7b` for more headroom. |
-| `TDMCP_LLM_API_KEY` | _(unset)_ | Optional bearer token for the LLM endpoint (ignored by local Ollama; needed for paid/cloud APIs). |
-| `TDMCP_LLM_TIER` | `standard` | Default chat tool tier: `standard`, `safe` (read-only), or `creative` (adds curated generators). The browser toggles can still override it per turn. |
-| `TDMCP_LLM_MAX_STEPS` | `8` | Maximum model/tool loop iterations for one local copilot turn. Values are clamped to `1..32`. |
-| `TDMCP_LLM_TEMPERATURE` | `0.4` | Sampling temperature sent to the OpenAI-compatible chat endpoint. Values are clamped to `0..2`. |
-| `TDMCP_CHAT_PORT` | `4141` | Loopback port the `tdmcp chat` web UI binds to. |
-
-## Telegram copilot (`tdmcp telegram`)
-
-These configure the [Telegram copilot](/reference/cli#telegram-copilot). It uses
-Telegram Bot API long polling, so no public webhook or inbound port is required.
-Messages are accepted only from configured allowlists.
-
-For local setup, prefer `tdmcp telegram setup`: it validates the BotFather token
-and writes the matching config keys to `~/.config/tdmcp/config.json` or the file
-selected with `--config`. The environment variables below remain useful for
-temporary shells, process managers and CI-style runs.
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `TDMCP_TELEGRAM_BOT_TOKEN` | _(unset)_ | Telegram bot token from BotFather. Required for `tdmcp telegram`; redacted in config output. |
-| `TDMCP_TELEGRAM_ALLOWED_CHATS` | _(empty)_ | Comma-separated Telegram chat ids allowed to reach the local copilot. At least this or `TDMCP_TELEGRAM_ALLOWED_USERS` must be set. |
-| `TDMCP_TELEGRAM_ALLOWED_USERS` | _(empty)_ | Optional comma-separated Telegram user ids. When set, the user id must match in addition to any configured chat allowlist. |
-| `TDMCP_TELEGRAM_DEFAULT_TIER` | `safe` | Default Telegram tool tier: `safe`, `standard`, or `creative`. Non-safe prompts still require `/approve`. |
-| `TDMCP_TELEGRAM_POLL_TIMEOUT_SEC` | `30` | Telegram `getUpdates` long-poll timeout, validated to `1..60` seconds by the config schema. |
-| `TDMCP_TELEGRAM_CONFIRM_TIMEOUT_MS` | `60000` | Expiry for a staged non-safe prompt awaiting `/approve`. |
-
-## AI Party ShowIntent eval and rehearsal POC
-
-These variables configure the local-model evaluation and optional improvement
-pipeline under `training/showintent/`, plus the local Live Nervous System
-rehearsal POC used by `npm run ai-party:*`.
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `LLM_MODE` | `ollama` | Runtime mode label for the AI Party POC. The current eval harness targets Ollama. |
-| `OLLAMA_BASE_URL` | `http://127.0.0.1:11434` | Ollama base URL used by `npm run ai-party:llm-eval`, `npm run ai-party:llm-baseline` and the optional Live Nervous System parser. |
-| `OLLAMA_MODEL` | `qwen2.5:3b` for eval, unset for the live POC | Ollama model id. The live dashboard uses deterministic fallback parsing when this is unset or unavailable. Use an improved model only after it beats the baseline without weakening safety metrics. |
-| `TDMCP_AI_PARTY_LLM_MODEL` | `showintent-party:local` | Model id used by `tdmcp-agent ai-party --llm` when `--llm-model` / `OLLAMA_MODEL` are not set. This keeps the ShowIntent-only model separate from the general `tdmcp chat` model. |
-| `LLM_EVAL_STRICT` | `false` | Set to `true` to make eval fail when demo-ready hard targets are not met. |
-| `LLM_SCHEMA_VERSION` | `showintent.v1` | Schema/version label to record alongside reports and POC configuration. |
-| `TD_BRIDGE_URL` | `http://127.0.0.1:9980` | TouchDesigner bridge URL used by `npm run ai-party:td-build` and dashboard TD preview checks. |
-| `TD_BRIDGE_TOKEN` | _(unset)_ | Optional bridge bearer token for the Live Nervous System TD client. |
-| `POC_DASHBOARD_HOST` | `127.0.0.1` | Host for the local AI Party dashboard/backend. |
-| `POC_DASHBOARD_PORT` | `8787` | Port for the local AI Party dashboard/backend. |
-| `POC_EVENT_LOG_PATH` | `./data/ai-party-poc-events.jsonl` | JSONL event log for operator commands, policy decisions, approvals, dispatch results and health changes. |
-| `TELEGRAM_BOT_TOKEN` | _(unset)_ | Telegram bot token for `npm run ai-party:telegram`. This is separate from the general `tdmcp telegram` copilot variables. |
-| `TELEGRAM_ALLOWED_CHAT_IDS` | _(empty)_ | Comma-separated chat allowlist required before the AI Party Telegram polling loop processes messages. |
-| `TELEGRAM_POLLING_ENABLED` | `false` | Enables AI Party Telegram long polling; `npm run ai-party:telegram` turns polling on for that process. |
-| `TELEGRAM_WEBHOOK_URL` | _(unset)_ | Reserved for deployed webhook work; local rehearsal uses long polling. |
-| `HARDWARE_ENABLED` | `false` | Future-adapter gate for physical-effect dispatch. Leave false for local rehearsal. |
-| `DMX_LIVE_ENABLED` | `false` | Future-adapter gate for DMX/live physical dispatch. Leave false unless a venue-safe adapter and kill path have been validated. |
-
-## TouchDesigner side
-
-Set these in **TouchDesigner's** environment (not the server's) for defense in
-depth — they are enforced bridge-side, even for direct network callers. See
-[Security](/reference/architecture#security).
-
-| Variable | Default | Description |
-| --- | --- | --- |
-| `TDMCP_BRIDGE_ALLOW_LAN` | _(unset)_ | Bridge address scope. The bridge is loopback-only by default and refuses off-host (non-loopback) peers immediately (HTTP `403`), before routing/auth. Set to `1`/`true`/`yes`/`on` in TouchDesigner's environment to allow LAN peers; pair it with `TDMCP_BRIDGE_TOKEN`. |
-| `TDMCP_BRIDGE_ALLOW_EXEC` | _(unset)_ | Optional bridge-side opt-in. Set to `1`/`true`/`on` in TouchDesigner's environment to allow arbitrary-code endpoints (`/api/exec`, node `method`) when no bridge token is configured. Leave unset for the safer default; structured endpoints keep working. |
-| `TDMCP_BRIDGE_TOKEN` | _(unset)_ | Shared bearer token; must match the server's value to authorize requests. |
-
-## Example: MCP client config
-
-```json
-{
-  "mcpServers": {
-    "tdmcp": {
-      "command": "node",
-      "args": ["/abs/path/to/tdmcp/dist/index.js"],
-      "env": {
-        "TDMCP_TD_PORT": "9980",
-        "TDMCP_VAULT_PATH": "~/Documents/MyVault"
-      }
-    }
-  }
-}
-```

package/mcps/tdmcp/docs/reference/packages.md

@@ -1,98 +0,0 @@
----
-description: "Install and stage TouchDesigner community libraries with tdmcp's manifest-driven package manager."
----
-
-# Package Manager
-
-`tdmcp install <lib>` stages trusted, manifest-listed TouchDesigner community packages under `~/.tdmcp/packages`. It works when TouchDesigner is closed. If the TD bridge is reachable and a package exposes a safe `.tox` import path, tdmcp can also import it under `/project1/tdmcp_packages/<package_id>`.
-
-## Everyday Commands
-
-```bash
-tdmcp search shader
-tdmcp list --available
-tdmcp info shader-park-td --json
-tdmcp install mediapipe-touchdesigner --dry-run --json
-tdmcp install raytk
-tdmcp doctor comfyui-td
-tdmcp packages --help
-tdmcp packages path
-```
-
-`install-bridge` is separate and unchanged:
-
-```bash
-tdmcp install-bridge
-```
-
-## Support Levels
-
-`full` packages have manifests, aliases, dry-run plans, cache/stage support, artifact detection, installed-state tracking, and mocked install coverage. They may still stage instead of live-import when the package is a collection or template.
-
-`stage-only` packages are safe to download and place on disk, but should be opened or imported manually.
-
-`doctor-only` packages need external runtimes such as models, CUDA/TensorRT, ComfyUI, Ableton, or Bitwig. tdmcp gives preflight guidance and does not pretend those dependencies are installed.
-
-`deferred` items are not install targets in this pass.
-
-## Included Packages
-
-Fully supported:
-
-- `mediapipe-touchdesigner`
-- `raytk`
-- `functionstore-tools`
-- `touchdesigner-shared`
-- `shader-park-td`
-- `sop-to-svg`
-- `augmenta-touchdesigner`
-- `simplemixer`
-
-Doctor/stage guidance:
-
-- `td-yolo`
-- `td-depth-anything`
-- `comfyui-td`
-- `touchdiffusion`
-- `geopix`
-- `td-ableton`
-- `td-bitwig`
-
-## Safe Dry Runs
-
-Use `--dry-run --json` before staging anything:
-
-```bash
-tdmcp install mediapipe-touchdesigner --dry-run --json
-```
-
-Dry-runs do not download archives, extract files, write installed state, or contact TouchDesigner.
-
-## Importing Into TouchDesigner
-
-When TouchDesigner is closed or the bridge is unreachable, install reports say `staged` and include the staged path plus next steps. When the bridge is live and a package has a safe `.tox`, tdmcp imports into:
-
-```text
-/project1/tdmcp_packages/<package_id>
-```
-
-It will not overwrite an existing package node unless you pass `--yes`.
-
-## Security Model
-
-tdmcp downloads archives, validates archive paths, extracts into its package cache, scans for artifacts, and writes an installed registry. It does not execute third-party Python, shell scripts, npm postinstall hooks, pip installs, model downloads, CUDA/TensorRT setup, Ableton setup, Bitwig setup, ComfyUI setup, or arbitrary downloaded code by default.
-
-`--allow-python-deps` and `--allow-external` are acknowledgements for doctor/report guidance. They do not run dependency installers in this implementation.
-
-## Developer Notes
-
-Package manifests live in `src/packages/registry.ts`. Add a manifest with:
-
-- `id`, `aliases`, `displayName`, `description`
-- `homepage`, `source`, `license`, `tags`
-- `packageType`, `supportLevel`, `platforms`, `tdVersionRange`
-- `requiresTouchDesignerBridge`, `externalDependencies`
-- `installStrategy`, `healthChecks`, `importHints`
-- `uninstallStrategy`, `securityNotes`
-
-Add tests under `tests/unit/packageManager.test.ts` for aliases, dry-run behavior, doctor behavior, mocked install/stage behavior, and any package-specific safety rule. Mark heavy model/runtime integrations as `doctor-only` unless the TD-side adapter can be staged safely without hidden external work.

package/mcps/tdmcp/docs/reference/tool-contract.md

@@ -1,74 +0,0 @@
----
-title: Tool API contract
-description: The stable contract every tdmcp MCP tool follows — invariants every client can rely on as the project consolidates toward 1.0.
----
-
-# Tool API contract
-
-This page documents the invariants every tdmcp MCP tool follows from v0.9.0
-onward and that will be **frozen at 1.0**. The full per-tool reference is the
-generated [Tools reference](./tools); this page covers the rules behind it so
-clients (Claude / Cursor / Codex / custom MCP clients) can rely on a stable
-shape.
-
-Changes that break any invariant below require a major version bump.
-
-## 1. Naming
-
-- Tool names are `snake_case`, registered via `server.registerTool(name, …)`
-  inside the file's `registerX` function.
-- A name shipped under a tagged release stays the same identity from 1.0
-  forward. A renamed tool keeps an alias under the old name for at least one
-  minor release before the alias is dropped.
-
-## 2. Input schema
-
-- Every tool defines a Zod schema and exposes it as
-  `inputSchema: schema.shape`.
-- Any field declared with `.default(...)` is **optional from the client's
-  point of view** — the server fills the default before calling the
-  implementation.
-- Required fields stay required; making a required field optional is
-  non-breaking, but the reverse (tightening) requires a major bump.
-
-## 3. Error handling
-
-- A handler **never throws**. Validation failures and TouchDesigner errors are
-  serialized into `isError: true` results via the `errorResult` helper.
-- TouchDesigner-side failures are normalized by `friendlyTdError` so the
-  client sees a single readable shape regardless of which `TdError` subtype
-  was raised by the bridge client.
-
-## 4. Offline behavior
-
-- When the TouchDesigner bridge is unreachable, a tool returns
-  `isError: true` with a friendly message ("TouchDesigner bridge not running
-  at…") instead of timing out silently or crashing the server.
-- The MCP server itself stays up — every other tool, resource, and prompt
-  remains callable while the bridge is offline.
-
-## 5. Result shape
-
-- `content[0].text` is a short human-readable description of what happened —
-  safe to surface to an end user.
-- `structuredContent` is the machine-readable payload. New keys are
-  **additive**; existing keys keep their type and meaning across minor
-  versions.
-- A tool that returns no useful structured payload may omit
-  `structuredContent`, but if it ever ships one it does not later remove it.
-
-## 6. Deprecation policy
-
-- A tool flagged for removal is first marked deprecated in the registry, kept
-  registered as an alias, and stays callable for at least one minor release.
-- The deprecation note documents the replacement tool (if any) so MCP clients
-  can migrate without guessing.
-
-## What this is **not**
-
-- Not a per-tool spec — that's [Tools reference](./tools), regenerated from
-  the live registry on every docs build.
-- Not a promise that every internal helper is stable — only the registered
-  tool surface is.
-- Not a freeze on adding new tools. The contract governs **how** tools behave,
-  not how many ship.

package/mcps/tdmcp/docs/superpowers/plans/2026-05-29-shader-park-animus-integrations.md

@@ -1,76 +0,0 @@
-# Shader Park Animus Integrations Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add package-managed Shader Park support, a TD-first `.tox` fetch path, and Animus-inspired native examples/tutorials.
-
-**Architecture:** Keep runtime-safe code in a small Shader Park integration module that dynamically imports `shader-park-core` while suppressing its import-time stdout. Add one Layer 1 tool that compiles Shader Park sculpture code into a GLSL MAT render network. Keep the official `.tox` as an external downloadable asset and represent Animus as a native recipe/tutorial, since it is not an npm package.
-
-**Tech Stack:** TypeScript, Zod, TouchDesigner bridge client, Shader Park Core, Vitest/MSW, VitePress docs, npm scripts.
-
----
-
-### Task 1: Shader Park compiler adapter
-
-**Files:**
-- Create: `src/integrations/shaderPark.ts`
-- Test: `tests/unit/shaderParkIntegration.test.ts`
-
-- [ ] Write a failing test that compiles `sphere(0.5);` and proves the adapter suppresses `shader-park-core` import-time `console.log`.
-- [ ] Implement `compileShaderParkToTouchDesigner(code)` with dynamic import, output validation, and normalized uniforms.
-- [ ] Run `npx vitest run tests/unit/shaderParkIntegration.test.ts`.
-
-### Task 2: Layer 1 Shader Park tool
-
-**Files:**
-- Create: `src/tools/layer1/createShaderPark.ts`
-- Test: `tests/unit/createShaderPark.test.ts`
-- Modify later in integration: `src/tools/layer1/index.ts`, `src/cli/agent.ts`
-
-- [ ] Write failing MSW tests for schema defaults, created TD operators, compiled pixel DAT, original-code DAT, uniform sequence binding, controls, and result metadata.
-- [ ] Implement `createShaderParkImpl` using `compileShaderParkToTouchDesigner`, `createSystemContainer`, `glslMAT`, `geometryCOMP`, `boxSOP`, camera/light/render/null, and `finalize`.
-- [ ] Run `npx vitest run tests/unit/createShaderPark.test.ts`.
-
-### Task 3: Official `.tox` fetch path
-
-**Files:**
-- Create: `scripts/fetch-shader-park-td.mjs`
-- Modify: `package.json`
-
-- [ ] Add `shader-park:tox` script that downloads the latest `Shader_Park_TD.tox` release asset to `vendor/shader-park/Shader_Park_TD.tox` or `--out <path>`.
-- [ ] Keep the `.tox` out of git and npm package output by default.
-- [ ] Smoke-test `node scripts/fetch-shader-park-td.mjs --help`.
-
-### Task 4: Animus native example
-
-**Files:**
-- Create: `recipes/animus_rings_visualizer.json`
-
-- [ ] Add a recipe that uses native TD operators to build an audio-driven rings visualizer inspired by Animus.
-- [ ] Use a synthetic audio source so it validates without device permissions.
-- [ ] Run `npm run validate:recipes`.
-
-### Task 5: Registry, CLI, docs, tutorials
-
-**Files:**
-- Modify: `src/tools/layer1/index.ts`
-- Modify: `src/cli/agent.ts`
-- Create: `docs/guide/shader-park.md`
-- Create: `docs/pt/guide/shader-park.md`
-- Modify: `docs/.vitepress/config.ts`
-- Modify: `README.md`
-
-- [ ] Register `create_shader_park` in Layer 1.
-- [ ] Add `tdmcp-agent shaderpark` command.
-- [ ] Add bilingual docs covering the npm compiler tool, the official `.tox` fetch path, and Animus as native recipe.
-- [ ] Add the guide link to VitePress navigation and README docs table.
-
-### Task 6: Harness verification
-
-**Files:**
-- Create: `_workspace/03_integrate.md`
-- Create: `_workspace/04_qa_shader_park_animus.md`
-
-- [ ] Run focused Vitest files.
-- [ ] Run `npm run typecheck`, `npm run build`, `npm test`, `npm run validate:recipes`, `npm run test:bridge`, `./node_modules/.bin/biome check .`, and `npm run docs:build`.
-- [ ] Record results and any live TouchDesigner validation gap in `_workspace/04_qa_shader_park_animus.md`.

package/mcps/tdmcp/docs/superpowers/plans/2026-06-02-doctor-fix-textport-auto-install.md

@@ -1,131 +0,0 @@
-# Doctor Fix Textport Auto Install Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Make `tdmcp-agent doctor --fix` attempt a bounded macOS TouchDesigner Textport install before falling back to the manual Textport command.
-
-**Architecture:** Keep `install-bridge` as the source of truth for copying bridge modules and generating the install command. Return a structured result from `runInstallBridge`, then let `doctor --fix` run a test-injectable auto runner that can paste/execute that command in TouchDesigner and verify `/api/info`.
-
-**Tech Stack:** TypeScript, Node child_process, Vitest/MSW, existing `runDoctor` and `runInstallBridge` CLI helpers.
-
----
-
-### Task 1: Structured Install Bridge Result
-
-**Files:**
-- Modify: `src/cli/installBridge.ts`
-- Test: `tests/unit/installBridge.test.ts`
-
-- [x] **Step 1: Write failing tests**
-
-```ts
-it("returns the no-preferences Textport command for callers", async () => {
-  const fetchImpl = vi.fn();
-  vi.stubGlobal("fetch", fetchImpl);
-
-  const result = await runInstallBridge(["--dir", "/tmp/tdmcp-bridge"]);
-
-  expect(result?.ok).toBe(true);
-  expect(result?.modulesDir).toBe("/tmp/tdmcp-bridge/modules");
-  expect(result?.textportCommand).toBe(
-    "from mcp import install; install.run()",
-  );
-  expect(result?.noPrefsTextportCommand).toBe(
-    'import sys; sys.path.insert(0, "/tmp/tdmcp-bridge/modules")\nfrom mcp import install; install.run(modules_dir="/tmp/tdmcp-bridge/modules")',
-  );
-});
-```
-
-- [x] **Step 2: Verify red**
-
-Run: `npm test -- tests/unit/installBridge.test.ts`
-
-Expected: FAIL because `runInstallBridge` currently returns `void`.
-
-- [x] **Step 3: Implement minimal result**
-
-Add an exported `InstallBridgeResult` and return it from success/failure branches. Preserve console output and `process.exitCode`.
-
-- [x] **Step 4: Verify green**
-
-Run: `npm test -- tests/unit/installBridge.test.ts`
-
-Expected: PASS.
-
-### Task 2: Doctor Auto Textport Runner
-
-**Files:**
-- Modify: `src/cli/doctor.ts`
-- Test: `tests/unit/doctor-fix.test.ts`
-
-- [x] **Step 1: Write failing tests**
-
-```ts
-it("--fix attempts Textport auto-install when install-bridge cannot verify immediately", async () => {
-  server.use(offlineInfoHandler, llmModels("qwen2.5:3b"));
-  const attempted: string[] = [];
-  const r = await runDoctor({
-    config: makeConfig(),
-    makeCtx,
-    fix: true,
-    runInstallBridge: async () => ({
-      ok: false,
-      detail: "manual Textport step required",
-      noPrefsTextportCommand:
-        'import sys; sys.path.insert(0, "/tmp/tdmcp-bridge/modules")\nfrom mcp import install; install.run(modules_dir="/tmp/tdmcp-bridge/modules")',
-    }),
-    runTextportInstall: async (command) => {
-      attempted.push(command);
-      return { ok: true, detail: "Textport command sent" };
-    },
-  });
-
-  expect(attempted).toHaveLength(1);
-  expect(r.report.repairs).toContainEqual(
-    expect.objectContaining({ id: "bridge", status: "applied" }),
-  );
-});
-```
-
-- [x] **Step 2: Verify red**
-
-Run: `npm test -- tests/unit/doctor-fix.test.ts`
-
-Expected: FAIL because `runTextportInstall` does not exist yet.
-
-- [x] **Step 3: Implement minimal doctor auto runner**
-
-Add `runTextportInstall?: (command: string) => Promise<{ ok: boolean; detail: string }>` to `RunDoctorOptions`. In `repairBridge`, when `install-bridge --verify` returns `ok:false` with `noPrefsTextportCommand` or `textportCommand`, call the runner once. Treat runner success as an applied bridge repair and runner failure as a failed repair that includes the manual fallback command.
-
-- [x] **Step 4: Implement default macOS runner**
-
-Use `osascript` only on `darwin`; otherwise return a clear unsupported result. The script should activate TouchDesigner, open Textport with `Option-T`, paste the exact command, press Return, and remain bounded by `TDMCP_TEXTPORT_INSTALL_TIMEOUT_MS`.
-
-- [x] **Step 5: Verify green**
-
-Run: `npm test -- tests/unit/doctor-fix.test.ts`
-
-Expected: PASS.
-
-### Task 3: Docs and Full Verification
-
-**Files:**
-- Modify: `docs/ROADMAP.md`
-- Modify: `docs/guide/prompt-cookbook.md`
-- Modify: `docs/pt/guide/prompt-cookbook.md`
-
-- [x] **Step 1: Update docs**
-
-Mention that `doctor --fix` now attempts a macOS Textport auto-install when the bridge is offline and keeps the manual command as fallback.
-
-- [x] **Step 2: Run focused checks**
-
-Run: `npm test -- tests/unit/installBridge.test.ts tests/unit/doctor-fix.test.ts`
-
-Expected: PASS.
-
-- [x] **Step 3: Run wider checks**
-
-Run: `npm run typecheck`
-
-Expected: PASS.