@hybridlabor-api/aos 4.3.0 → 4.4.0

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

@@ -1,191 +0,0 @@
----
-description: "How the TouchDesigner MCP server works — the MCP tool layers, the embedded operator knowledge base, and the bridge that runs inside TouchDesigner."
----
-
-# Architecture
-
-tdmcp is three programs that talk to each other on your machine:
-
-```
-   AI assistant            tdmcp server                TouchDesigner
-  (Claude / Cursor)  ──▶  (Node / TypeScript)   ──▶   (the Python bridge inside TD)
-   "make a feedback        MCP tools + the              creates / connects /
-    tunnel from noise"     operator knowledge base       inspects / previews nodes
-```
-
-1. **The AI assistant** is any MCP-capable client — Claude Desktop, Claude Code,
-   Codex, or Cursor. It's where you describe what you want.
-2. **The tdmcp server** is a small Node program. It exposes a set of TouchDesigner
-   "tools" and an embedded operator knowledge base to the AI over the
-   [Model Context Protocol](https://modelcontextprotocol.io).
-3. **The bridge** is a Python package that runs *inside* TouchDesigner (behind a
-   Web Server DAT). It's what actually drives TD. See
-   [Bridge & REST API](/reference/bridge-api).
-
-```
-MCP client ──stdio──▶ tdmcp server (Node/TS) ──HTTP──▶ TouchDesigner bridge (Python)
-                       ├── Layer 1  artist tools (create_visual_system, …)
-                       ├── Layer 2  building blocks (create_node_chain, …)
-                       ├── Layer 3  atomic ops (create_td_node, …)
-                       ├── Knowledge base (MCP resources)
-                       ├── Recipes (validated network templates)
-                       └── Feedback engine (errors / preview / performance)
-```
-
-## The three tool layers
-
-Tools are organized into layers so the AI can pick the right altitude for a task.
-See the full, always-current list in the [Tools reference](/reference/tools).
-
-- **Layer 1 — artist tools.** Describe a result (`create_feedback_network`,
-  `create_audio_reactive`, `create_generative_art`, …) and get a whole network,
-  wired and arranged, often with a control panel ready to perform.
-- **Layer 2 — building blocks.** Mid-level pieces (`create_node_chain`,
-  `connect_nodes`, `create_control_panel`, `animate_parameter`,
-  `create_external_io`, …) for assembling and controlling networks by hand.
-- **Layer 3 — atomic operations.** Single-node CRUD plus inspection, analysis,
-  rendering and the Python escape hatches (`create_td_node`, `find_td_nodes`,
-  `get_td_node_errors`, `execute_python_script`, …).
-
-A separate group of [vault tools](/reference/tools#obsidian-vault) bridges an
-Obsidian vault and TouchDesigner.
-
-## The create → verify → preview loop
-
-Every high-level build follows the same loop so the AI can see and fix its own
-work instead of guessing:
-
-1. **Create** the network from a recipe, GLSL pattern, or generated Python.
-2. **Verify** by reading cook/compile errors (`get_td_node_errors`,
-   `summarize_td_errors`).
-3. **Preview** by capturing the output TOP as an inline image (`get_preview`).
-
-Generated networks are auto-arranged into a readable left→right layout
-(`arrange_network`) instead of piling nodes on top of each other.
-
-## Knowledge base
-
-The server ships with an embedded, offline reference so the AI uses real
-operators rather than inventing them: **629 operators**, **68 Python classes**,
-workflow patterns, GLSL techniques, tutorials, **7 TouchDesigner release
-profiles**, **45 operator compatibility entries**, **9 Python API compatibility
-classes**, **6 experimental build series**, **7 technique packs** with **39
-techniques**, and **6 TouchDesigner class references**. These are exposed as MCP
-resources the AI can read on demand:
-
-`tdmcp://operators/{category|name}` · `tdmcp://python-api/{class}` ·
-`tdmcp://operator-connections/{operator}` · `tdmcp://operator-examples/{operator}` ·
-`tdmcp://td-versions/{version}` · `tdmcp://td-experimental/{series_or_category}` ·
-`tdmcp://compat/operators/{operator}` · `tdmcp://compat/python/{class_or_member}` ·
-`tdmcp://techniques/{category}` · `tdmcp://td-classes/{family}` ·
-`tdmcp://patterns/{name}` · `tdmcp://glsl/{name}` ·
-`tdmcp://glsl-snippets` · `tdmcp://recipes/{name}` ·
-`tdmcp://recipes/search/{query}` · `tdmcp://tutorials/{name}` ·
-`tdmcp://commands` · `tdmcp://prompts` · `tdmcp://cheatsheets` ·
-`tdmcp://learning/touchdesigner`
-
-The knowledge base is committed to the repo, so a fresh clone needs only
-`npm install && npm run build`. `npm run import:bottobot` regenerates it from
-`@bottobot/td-mcp` and is only needed to refresh it.
-
-## Creative RAG (optional, opt-in)
-
-[Creative RAG](/CREATIVE_RAG) is a separate, opt-in subsystem that lives
-**outside** the TouchDesigner bridge. It is **not** a tool layer, it does **not**
-touch TD, DMX, fixtures or any Python exec path. It is a CLI subcommand
-(`tdmcp creative-rag {sync|index|search}`) plus two **read-only** MCP resources
-(`tdmcp://creative/cards/{id}` and `tdmcp://creative/search`), both registered
-only when `TDMCP_RAG_ENABLED=1`. Its only outbound calls are HTTPS to four
-open-data museum APIs (during explicit `sync`) and `POST /api/embed` to a
-**local Ollama process** (during `index` and `search`). Repertoire, not policy
-— search results never trigger an in-TD action.
-
-## Recipes
-
-Recipes are validated network templates (JSON) the AI can instantiate with
-`apply_recipe`. They cover common starting points — feedback tunnels,
-reaction-diffusion, particle galaxies, audio spectrum bars, projection mapping
-and more. See the [Recipe gallery](/guide/recipes) for what each one builds, and
-the repository's `CONTRIBUTING.md` guide to add your own.
-
-## Transports & events
-
-The server speaks two MCP transports:
-
-- **stdio** (default) — for local clients like Claude Desktop and Claude Code.
-- **Streamable HTTP** (`TDMCP_TRANSPORT=http`) — serves MCP at
-  `POST/GET/DELETE /mcp` on loopback with stateful sessions, for remote/headless
-  setups. See [Deployment](/deployment).
-
-It can also subscribe to a **WebSocket event stream** from TD
-(`node.created` / `node.deleted` / `node.error` / `project.saved` /
-`timeline.frame` / `node.cook`) and forward events as MCP logging notifications.
-High-frequency events (`timeline.frame`, `node.cook`) are dropped unless
-explicitly opted in. Toggle with `TDMCP_EVENTS`.
-
-### Calling tdmcp from inside TouchDesigner (LOPs)
-
-dotsimulate's LOPs "MCP Client" can run *inside* TouchDesigner and spawn this
-server over stdio, closing a loop: **TD (LOPs MCP Client) → `node dist/index.js`
-(tdmcp) → HTTP → the TD bridge on `127.0.0.1:9980` (the same TD) → the network.**
-No transport change is needed (stdio is the default). Because the client lives in
-TD with no documented `env` field, point its `command` at the
-`scripts/tdmcp-lops.mjs` wrapper, which injects the hardened profile
-(`TDMCP_RAW_PYTHON=off`, `TDMCP_TOOL_PROFILE=safe`). See the
-[LOPs integration guide](/guide/lops-integration).
-
-## Security
-
-The TouchDesigner bridge runs **arbitrary Python inside your TD process** — that
-is what lets the assistant build networks for you. Treat it like an open door to
-the machine TD runs on:
-
-- **The Web Server DAT binds its port (default `9980`) on all interfaces, but the
-  bridge is loopback-only by default.** A request from a non-loopback peer address
-  is rejected immediately (HTTP `403`), **before** routing, authentication, or any
-  tool runs, so reaching the port from another machine is not enough to drive it.
-  To expose the bridge to a LAN, set `TDMCP_BRIDGE_ALLOW_LAN=1` in TouchDesigner's
-  environment (also accepts `true`/`yes`/`on`) — and pair it with
-  `TDMCP_BRIDGE_TOKEN`. Even then, only run it on a trusted network and/or firewall
-  the port. (Some TouchDesigner builds don't surface the peer address to the
-  callback; where that's the case the `Origin`/`Host` guards below are the
-  defense.)
-- **Turn on bridge auth for untrusted networks:** set `TDMCP_BRIDGE_TOKEN` to a
-  shared secret in **both** the server's environment and TouchDesigner's
-  environment. The bridge then rejects any request without a matching
-  `Authorization: Bearer <token>` (HTTP `401`). Unset (default) keeps the
-  zero-config local flow.
-- `TDMCP_RAW_PYTHON=off` hides only the two **raw-Python MCP tools**
-  (`execute_python_script`, `exec_node_method`) where the *client* authors the
-  code. It is **not** a code-execution kill-switch: many higher-level tools still
-  send their own templated Python to the bridge. The bridge-side arbitrary-code
-  endpoints (`/api/exec`, node-`method`) are default-closed unless
-  `TDMCP_BRIDGE_TOKEN` is configured or `TDMCP_BRIDGE_ALLOW_EXEC=1` is explicitly
-  set in TouchDesigner's environment; structured endpoints keep working.
-- The MCP server binds to loopback (`127.0.0.1`) for both transports and enables
-  DNS-rebinding protection on HTTP.
-- **The bridge refuses browser cross-origin requests.** Any request carrying an
-  `Origin` header that isn't loopback is rejected (HTTP `403`), and a
-  `POST`/`PATCH`/`PUT` whose `Content-Type` is present but not `application/json`
-  is rejected too — that blocks the simple cross-site form/`fetch` POSTs a
-  malicious web page could aim at the bridge (CSRF / DNS-rebinding → drive-by code
-  execution). The MCP server sends no `Origin` and always uses
-  `application/json`, so normal use is unaffected.
-- **The local copilot chat UI (`tdmcp chat`) applies the same guard.** It binds to
-  loopback and rejects (HTTP `403`) any request whose `Host` or `Origin` isn't a
-  loopback name, so a page the artist visits can't drive node CRUD against the live
-  project via `http://127.0.0.1:<chat-port>/chat`.
-
-All of these are configured through [environment variables](/reference/environment).
-
-## Known limitations
-
-- **WebSocket events** are forwarded as MCP logging notifications on both
-  transports; high-frequency events are dropped unless opted in.
-- **Audio / particle / 3D builders and the exotic recipes** (kinect, LED,
-  projection) produce valid, connected networks but use best-effort TD parameter
-  names — fine-tuning may be needed, and they emit warnings to that effect.
-- **Preview** returns the TOP at its native resolution (the requested size is
-  advisory).
-- The bridge ships as Python modules plus a callbacks template (a binary `.tox`
-  can't be generated from source); the one-line installer assembles it for you.

package/mcps/tdmcp/docs/reference/bridge-api.md

@@ -1,155 +0,0 @@
----
-description: "The tdmcp bridge and REST API — the component inside TouchDesigner that the MCP server drives to create, inspect, connect and preview nodes."
----
-
-# Bridge & REST API
-
-The bridge is the TouchDesigner side of tdmcp: a small Python package that exposes
-a REST API behind a **Web Server DAT**, which the server calls over HTTP. It runs
-*inside* the TD process — that's what gives it the power to create, connect,
-inspect and preview real nodes.
-
-> A binary `.tox` can't be generated from source by an AI agent, so the bridge
-> ships as Python modules plus a callbacks template. The one-line installer
-> assembles it for you; you can then export your own reusable `.tox`.
-
-## Install it once
-
-All three options create one tidy `tdmcp_bridge` COMP (Web Server DAT +
-callbacks), are idempotent, and can be undone with
-`from mcp import install; install.uninstall()`.
-
-There are two reusable TouchDesigner objects in this flow:
-
-| Object | Path / artifact | Purpose |
-| --- | --- | --- |
-| Runtime bridge | `/project1/tdmcp_bridge` | The actual Web Server DAT bridge that exposes `/api/info` and the REST API. |
-| Palette package | `tdmcp/tdmcp_bridge_package.tox` | A draggable Palette component with **Install**, **Reinstall**, **Uninstall**, and **Status** controls for the runtime bridge. |
-
-For repeat use across projects, stage the modules and export the Palette package:
-
-```bash
-npx --yes --package=@dpantani/tdmcp tdmcp install-bridge --palette
-# or, from a clone after build:
-node dist/index.js install-bridge --palette
-```
-
-The CLI prints the exact Textport command with your staged module path. Paste the
-Palette package command in TouchDesigner, then drag **tdmcp →
-tdmcp_bridge_package** from the Palette into a project and click **Install**.
-`/api/info` responds only after that package button has created the runtime
-bridge. Advanced exports can use `--palette-dir <path>` and
-`--package-name <name>`.
-
-**A. One paste — no clone, no Preferences.** In the Textport
-(`Dialogs → Textport and DATs`):
-
-```python
-import urllib.request; exec(urllib.request.urlopen("https://github.com/Pantani/tdmcp/raw/v0.12.0/td/bootstrap.py").read().decode())
-```
-
-Downloads the bridge to `~/tdmcp-bridge/modules` and starts it on port 9980.
-(Needs the repo reachable; if it's private, use B or C.)
-
-**B. After adding the module path.** Add the absolute path of `td/modules` to
-**Preferences → "Python 64-bit Module Path"**, then in the Textport:
-
-```python
-from mcp import install; install.run()
-```
-
-**C. From the terminal.** `npx --yes --package=@dpantani/tdmcp tdmcp install-bridge` (or
-`node dist/index.js install-bridge` from a clone) copies the bridge to
-`~/tdmcp-bridge` and prints exactly what to paste.
-
-You should see `[tdmcp] bridge running on port 9980 (/project1/tdmcp_bridge)`.
-Verify from a terminal:
-
-```bash
-curl http://127.0.0.1:9980/api/info
-# {"ok":true,"data":{"python_version":"3.11.x","td_version":"...","bridge_version":"..."}}
-```
-
-### Make a reusable `.tox`
-
-```python
-from mcp import install
-install.export("/path/to/mcp_webserver_base.tox", modules_dir="/abs/path/to/td/modules")
-```
-
-Pass `modules_dir` so the import path travels inside the `.tox`; from then on the
-install is just dragging the component in.
-
-### Keep it on across restarts
-
-Save your project as your **Default Project**, or use the self-installing
-`td/startup.py` in an Execute DAT (toggle **Start** and **Create** on). `install()`
-is idempotent, so it's safe to leave in place permanently. Full manual
-(Web-Server-DAT-by-hand) steps are in the
-[TouchDesigner bridge folder](https://github.com/Pantani/tdmcp/tree/main/td).
-
-## Endpoints
-
-All responses use the envelope `{ "ok": true, "data": … }` or
-`{ "ok": false, "error": { "message": … } }`.
-
-| Method | Path | Purpose |
-| --- | --- | --- |
-| GET | `/api/info` | TD/Python/bridge versions |
-| POST | `/api/nodes` | create node `{parent_path,type,name?,parameters?}` |
-| GET | `/api/nodes?parent=…` | list children |
-| GET | `/api/nodes/{path}` | node detail (path is percent-encoded) |
-| PATCH | `/api/nodes/{path}` | update `{parameters}` |
-| DELETE | `/api/nodes/{path}` | delete node |
-| POST | `/api/exec` | run Python `{script,return_output?}` |
-| POST | `/api/nodes/{path}/method` | call `{method,args?,kwargs?}` |
-| GET | `/api/nodes/{path}/errors` | node errors |
-| GET | `/api/preview/{path}` | TOP as base64 PNG |
-| POST | `/api/batch` | `{operations:[…]}` (create/update/delete/connect) |
-| GET | `/api/network/{path}/errors` | recursive errors |
-| GET | `/api/network/{path}/topology` | nodes + connections |
-| GET | `/api/network/{path}/performance` | cook times |
-| POST | `/api/connect` | connect `{source_path,target_path,source_output?,target_input?}` (index-aware) |
-| POST | `/api/disconnect` | disconnect `{to_path,from_path?,to_input?}` (by target, optionally by source/input) |
-| GET | `/api/nodes/{path}/params?modes=true` | parameter values **+ modes** (`keys?`, `non_default_only?`) |
-| PATCH | `/api/nodes/{path}/params/{param}/mode` | set a parameter's mode `{mode,expr?,value?}` (constant/expression/bind) |
-| GET | `/api/nodes/{path}/text` | read a DAT's text |
-| PUT | `/api/nodes/{path}/text` | replace a DAT's text `{text}` |
-| GET | `/api/logs` | recent bridge/cook errors from the in-bridge Error DAT (`severity?`, `max_lines?`, `scope?`) |
-
-The `/api/exec` and node-`method` endpoints are disabled bridge-side by default
-unless `TDMCP_BRIDGE_TOKEN` is configured or `TDMCP_BRIDGE_ALLOW_EXEC=1` is set
-inside TouchDesigner — see [Security](/reference/architecture#security). The
-structured endpoints added in 0.6.0 — `/api/connect`, `/api/disconnect`,
-`/api/logs`, the `?modes=true` parameter reads, `…/params/{param}/mode` and the
-DAT `…/text` reads/writes — are **not** behind the exec gate, so they keep
-working while arbitrary exec is closed.
-
-## Developing the bridge
-
-TouchDesigner imports the bridge modules once at project open, so editing files
-under `td/` does **not** update a running bridge. Reload without reopening:
-
-```python
-from mcp import dev
-dev.reload_bridge()   # reimports every mcp.* / utils.* module; returns the names reloaded
-```
-
-For the local dev loop, `tdmcp-agent watch-build` watches `src/` and `td/`.
-When a saved change touches `td/`, it waits for typecheck/build to pass, runs
-`python -m py_compile` over the changed Python files, then calls the
-`reload_bridge` tool automatically. Use `--no-reload-bridge` for a build-only
-watcher, or `--no-py-compile` when you need to skip the Python syntax gate.
-
-Bump `BRIDGE_VERSION` in `td/modules/utils/version.py` on every bridge change.
-`get_td_info` reports the *running* bridge's version, so when it lags the repo you
-know the running bridge is stale and should be reloaded.
-
-### Notes / known limitations
-
-- Operator types are resolved with a regex-guarded `eval` of the type name; only
-  `[A-Za-z][A-Za-z0-9_]*` is accepted.
-- `preview` returns the TOP at its native resolution; the requested width/height
-  are advisory.
-- WebSocket event streaming is stubbed in the callbacks and forwarded as MCP
-  logging notifications by the server.

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

@@ -1,288 +0,0 @@
----
-description: "The tdmcp command line — agent runner and a local-LLM copilot for the TouchDesigner MCP server, for tasks that do not need a paid API."
----
-
-# CLI
-
-The package installs two binaries: `tdmcp` (the MCP server + utilities) and
-`tdmcp-agent` (a shell-friendly client). After `npm run build`, run them with
-`node dist/index.js …` / `node dist/cli/agent.js …`, or globally if you
-`npm link` / install the package.
-
-## `tdmcp` — server & utilities
-
-| Command | What it does |
-| --- | --- |
-| `tdmcp` | Start the MCP server (default `stdio` transport). Configured via [environment variables](/reference/environment). |
-| `tdmcp serve --http --port 3939` | Start the MCP server over loopback Streamable HTTP for clients that do not use stdio. Bare `tdmcp` still defaults to stdio. |
-| `tdmcp --help` | Print top-level usage without starting the MCP server. |
-| `tdmcp init` | One-shot onboarding: stage the bridge, write a client config (Claude / Cursor / Codex), seed a profile and optional bridge token. See [Onboarding](#onboarding) below. |
-| `tdmcp ask "your prompt"` | Non-interactive copilot turn — one prompt in, one answer out (machine-readable with `--json`). See [Onboarding](#onboarding) below. |
-| `tdmcp chat` _(alias `tdmcp llm-run`)_ | Start the local LLM copilot UI (see below). |
-| `tdmcp telegram` | Start an allowlisted Telegram Bot API long-poll bridge into the local Ollama copilot. See [Telegram copilot](#telegram-copilot) below. |
-| `tdmcp creative-rag sync\|index\|search` | Manage the opt-in Creative RAG reference store. See [Creative RAG](/creative-rag). |
-| `tdmcp project-rag sources\|sync\|index\|search\|info\|analyze\|bridge` | Manage the opt-in TouchDesigner project RAG store and quarantine analyzer. See [Project RAG](/project-rag). |
-| `tdmcp install-bridge` | Stage the TouchDesigner bridge to `~/tdmcp-bridge` and print the runtime Textport command for `/project1/tdmcp_bridge`. Add `--palette` to also print a Palette package export command for draggable `tdmcp_bridge_package.tox`; `--palette-dir <path>` and `--package-name <name>` imply `--palette`. Add `--verify` to check `/api/info` once, `--wait` to poll until it is up, and `--port <port>` for non-default bridges. For the Palette package, `/api/info` can only pass after the package's **Install** button creates the runtime bridge. See [Bridge & REST API](/reference/bridge-api). |
-| `tdmcp install-client <claude\|codex\|cursor>` | Print a client-specific MCP config snippet for the current package. Add `--write --path <file>` to deep-merge and verify an explicit client config file (JSON for Claude/Cursor, TOML for Codex). |
-| `tdmcp completion bash` | Print a shell completion snippet for the primary binary. Supports `bash`, `zsh`, and `fish`, including package-manager shortcuts and common flags. |
-| `tdmcp --version` | Print the package version. |
-| `tdmcp search/list/info/install/uninstall/doctor/packages path` | Manage TouchDesigner community packages. See [Package manager](/reference/packages). |
-
-Common package-manager examples:
-
-```bash
-tdmcp search shader
-tdmcp list --available
-tdmcp info shader-park-td --json
-tdmcp install mediapipe-touchdesigner --dry-run --json
-tdmcp doctor comfyui-td --json
-tdmcp packages --help
-tdmcp packages path
-tdmcp completion bash
-```
-
-## Onboarding & one-shot ask {#onboarding}
-
-### `tdmcp init`
-
-One-shot onboarding for first-time users. Stages the TouchDesigner bridge,
-writes (or merges) a per-client MCP config for Claude / Cursor / Codex, creates
-a default profile in `tdmcp.json`, and optionally seeds a `TDMCP_BRIDGE_TOKEN`.
-Safe to re-run — every step is idempotent and reports `ok` / `would` / `skip` /
-`fail`.
-
-```bash
-tdmcp init --yes
-```
-
-| Flag | Purpose |
-| --- | --- |
-| `-y, --yes` | Accept defaults, non-interactive. |
-| `--dry-run` | Plan only; do not touch files or launch TouchDesigner. |
-| `--json` | Emit a single JSON envelope (suppresses banners; pair with `--show-token` if you need the token unredacted). |
-| `--clients <list>` | `auto` (default), `none`, or csv of `claude,cursor,codex`. |
-| `--skip <steps>` | csv of `bridge,clients,config,token,open,doctor` to skip individual steps. |
-| `--token <v>` | Use this `TDMCP_BRIDGE_TOKEN` (use `--no-token` to opt out of token generation). |
-| `--profile <name>` | Profile name in `tdmcp.json` (default `local`). |
-
-### `tdmcp ask`
-
-Non-interactive copilot turn — pass a single prompt, get one answer back. Uses
-the same curated local-LLM tier as `tdmcp chat`, but skips the browser UI so it
-plugs into scripts and CI.
-
-```bash
-tdmcp ask "what TOPs are cooking the slowest right now?" --json
-```
-
-| Flag | Purpose |
-| --- | --- |
-| `--json` | Emit a single JSON line: `{answer, error?, durationMs, model, tier, toolCalls}`. |
-| `--tools=off` | Bypass tool calls and return a pure model answer. |
-| `--model <name>` | Override `llmModel` for this turn. |
-| `--profile <name>` | Use a named profile from `tdmcp.json` / `.tdmcprc`. |
-| `--config <path>` | Use a specific config file instead of the search order. |
-| `--read-only` | Force the safe (inspection-only) tier. |
-| `--creative` | Use the creative tier and a warmer sampling preset. |
-| `--with-creative` | Inject Creative RAG cards into the prompt context when Creative RAG is enabled. |
-| `--no-ollama` | Don't auto-start local Ollama (remote endpoint or self-managed daemon). |
-| `--timeout <ms>` | Wall-clock cap on the turn (default 120000). Exits 124 on hit. |
-
-## `tdmcp-agent` — command-line agent
-
-`tdmcp-agent` drives the same tools from a shell with machine-readable output —
-useful for scripts and CI.
-
-```bash
-tdmcp-agent --help                 # list commands
-tdmcp-agent info                   # health check + TD/bridge info
-tdmcp-agent nodes find --params '{"parent_path":"/project1","type":"TOP"}'
-tdmcp-agent nodes create --dry-run --params '{"parent_path":"/project1","type":"noiseTOP"}'
-tdmcp-agent commands --json       # discover commands + mutating/unsafe flags
-tdmcp-agent help nodes find       # focused help + input schema
-tdmcp-agent schema "nodes create" # print a command's JSON Schema
-tdmcp-agent nodes list --output table
-tdmcp-agent nodes list --output csv
-tdmcp-agent hardware-diagnose --params '{"expected_min_monitors":2,"status_paths":["/project1/kinect_wall_harp/bridge_status"]}'
-tdmcp-agent run ./show-plan.json  # run a JSON file of command steps
-cat show-plan.json | tdmcp-agent run - --continue-on-error
-tdmcp-agent config profiles       # list saved config profiles
-tdmcp-agent config profile club   # show one profile, secrets redacted
-tdmcp-agent completion bash       # shell completion snippet
-tdmcp-agent repl                  # interactive mode with persistent history + Tab completion
-tdmcp-agent doctor --fix          # apply safe repairs, then report remaining guidance
-tdmcp-agent watch-build           # watch src/ + td/, rebuild, py_compile + reload td/*.py edits
-tdmcp-agent watch-build --no-reload-bridge  # build-only watcher
-tdmcp-agent watch --pretty --heartbeat-ms 5000
-tdmcp-agent watch --on beat --exec './cue-next.sh' --debounce-ms 250
-tdmcp-agent show-director --params '{"intent":{"type":"request_cue","cue":"band_intro","preapproved":true}}'
-tdmcp-agent ai-party-poc
-tdmcp-agent ai-party-poc --params '{"auto_approve_effects":true,"operator":"front-of-house"}'
-tdmcp-agent ai-party --params '{"message":{"text":"/fog 3s light","chat_role":"operator","user_role":"foh"}}'
-```
-
-Output format is `--output json` (default) / `ndjson` / `text` / `table` /
-`csv`. Mutating commands are tagged `mutates`; the Python escape hatches require
-`--allow-unsafe` and honour `TDMCP_RAW_PYTHON=off`. `tdmcp-agent doctor --fix`
-currently applies safe local repairs, such as creating a missing configured
-`TDMCP_VAULT_PATH` folder, and prints suggestions for the remaining manual
-items. Argument JSON can come from
-`--params '<json>'`, `--params-file file.json`, `--params -` (stdin), or
-`--json '<json>'`. Connection overrides are available per call with `--td-host`,
-`--td-port`, and `--timeout`; script-friendly flags include `--version`,
-`--quiet`, and `--no-color`.
-Run files also accept stdin via `run -`; add `--continue-on-error` to execute the
-whole file and return the first non-zero step code after recording every result.
-Global `--no-color` is forwarded into run-file steps, and an individual step can
-set `"no_color": true` when a generated plan needs script-compatible output.
-For agent clients, `tdmcp://commands` exposes the same command catalog as an MCP
-resource.
-
-`tdmcp-agent show-director` is a dry-run only AI Show Director policy surface. It
-validates a `ShowIntent`, returns `allow`, `require_approval` or `block`, and
-emits updated approval/audit state as JSON. It never connects to TouchDesigner or
-hardware; use it to gate future voice/OpenClaw/dashboard integrations before any
-cue or effect is mapped to real execution.
-
-`tdmcp-agent ai-party-poc` runs the producer rehearsal package for the
-[AI-Controlled Party](/guide/ai-controlled-party) concept. With no params it uses
-the built-in seven-moment demo; with custom `events` it accepts operator text,
-voice transcripts, audio-section markers, dashboard approval actions or scripted
-`ShowIntent`s. The output is a dry-run JSON envelope with policy decisions,
-approval queue state, an audit log summary and simulated effect events. It does
-not build a TouchDesigner context and never emits a live hardware plan.
-
-`tdmcp-agent ai-party` is the Hermes/Telegram POC wrapper around that policy
-surface. It accepts a Telegram-style message, validates an optional raw Hermes
-candidate or uses a deterministic fallback parser, then returns the dry-run
-decision, plan, approval state and Telegram reply text. `tdmcp-agent ai-party
-telegram-once` runs one Telegram Bot API long-poll batch and sends replies with
-`sendMessage`; it is still policy-only and does not create a TouchDesigner
-context.
-
-The ShowIntent local-model improvement harness lives under
-`training/showintent/`. It evaluates an Ollama model against locked
-operator/Telegram cases before any optional fine-tuning:
-
-```bash
-tdmcp-agent ai-party llm-setup
-tdmcp-agent ai-party --llm --params '{"message":{"text":"deixa mais premium","chat_role":"operator","user_role":"foh"}}'
-OLLAMA_MODEL=qwen2.5:3b npm run ai-party:llm-baseline
-npm run ai-party:llm-generate-data
-npm run ai-party:llm-import-curated
-```
-
-The harness trains the model only to emit valid `ShowIntent` JSON. It does not
-replace `ShowIntentSchema`, `EffectPolicySchema` or `showDirectorRuntime`, and it
-does not teach raw DMX, raw Python or direct hardware control.
-
-`tdmcp-agent ai-party --llm` calls local Ollama through `/api/chat`, validates
-the returned ShowIntent JSON, then sends it through the same dry-run policy
-gateway. If the model returns malformed output, the request is blocked. The
-general `tdmcp chat` copilot still uses the normal chat model; the AI Party model
-is ShowIntent-only and should not become the default copilot model.
-
-## Local copilot (`tdmcp chat`)
-
-> For an artist-friendly walkthrough, see [Local copilot (no API)](/guide/local-copilot).
-> This section is the reference detail.
-
-For **simple tasks** you can talk to a **local LLM** instead of a paid API.
-`tdmcp chat` boots a small chat UI in your browser, wired to the same
-TouchDesigner bridge — and **starts Ollama for you** if it isn't already running:
-
-```bash
-# one-time: install Ollama from https://ollama.com
-ollama pull qwen2.5:3b   # optional — the UI also has a one-click pull
-tdmcp chat               # starts Ollama if needed, opens http://127.0.0.1:4141
-```
-
-If the endpoint is local Ollama and the daemon isn't up, `tdmcp chat` launches
-`ollama serve` for you — detached and left running, so quitting the chat never
-takes the model offline. Flags: **`--read-only`** (force the safe tool tier),
-**`--creative`** (use the creative tier and a warmer sampling preset),
-**`--prompt <text>`** (headless one-shot answer, no browser/server),
-**`--no-ollama`** (don't auto-start — for a remote endpoint or a self-managed
-daemon), **`--no-open`** (don't open the browser), **`--profile <name>`** /
-**`--config <path>`** (select saved config), and **`--help`**.
-
-It is meant for the easy stuff — inspecting the project, reading errors, and
-creating/wiring/parameterizing individual operators — and is given a **curated,
-safe subset** of the tools (no Layer-1 system generators, no raw Python). For full
-systems, click **Escalate ⇪** to copy a ready-to-paste prompt and hand off to
-Claude/Codex (they drive the same project, so nothing needs to move). The UI also
-has a **read-only** toggle, live **model switching** + endpoint settings, a
-one-click **model pull**, and persistent history. The copilot sees the registered
-MCP prompt catalog from `tdmcp://prompts`, so it can point users at the right
-Claude/Codex prompt when a request is better handled by a full MCP client.
-
-::: tip Which local model?
-Benchmarked on the simple-task workload, **`qwen2.5:3b`** hit 100% tool-calling —
-as reliable as 7B/14B but faster and lighter (the default). Sub-3B models (e.g.
-`qwen2.5:1.5b`) are flaky; `llama3.1:8b` was notably weaker at tool use. Bump to
-`qwen2.5:7b`/`14b` only for more answer-quality headroom. Any OpenAI-compatible
-endpoint works via `TDMCP_LLM_BASE_URL` — local Ollama/LM Studio, or a cloud API.
-Tune the default tool tier, loop budget and sampling with `TDMCP_LLM_TIER`,
-`TDMCP_LLM_MAX_STEPS` and `TDMCP_LLM_TEMPERATURE`.
-:::
-
-## Telegram copilot (`tdmcp telegram`) {#telegram-copilot}
-
-`tdmcp telegram` runs a local long-polling Telegram Bot API loop and forwards
-allowlisted text messages to the same local Ollama copilot used by `tdmcp chat`.
-It is a transport adapter: Telegram never talks directly to the TouchDesigner
-bridge.
-
-Required setup:
-
-```bash
-printf '%s\n' '123456:ABC...' | tdmcp telegram setup --token-stdin --chat-id 123456
-ollama pull qwen2.5:3b
-tdmcp telegram
-```
-
-`tdmcp telegram setup` validates the BotFather token with Telegram `getMe`, then
-writes `telegramBotToken`, `telegramAllowedChats` and `telegramDefaultTier` to
-the selected config file. By default it uses `TDMCP_CONFIG_FILE`, an existing
-`tdmcp.json` / `.tdmcprc` in the current directory, or
-`~/.config/tdmcp/config.json`. Use `--config <path>` or `--profile <name>` to
-choose the destination explicitly. If you omit `--chat-id`, setup can wait for
-the next message sent to the bot and save that chat after confirmation.
-
-The Telegram surface defaults to `safe` mode, so read-only inspection prompts run
-immediately. `/standard` and `/creative` stage the next prompt and require
-`/approve` before any non-safe tool tier runs. `/cancel` clears pending/running
-work, `/status` shows tier/pending state, and `/panic` intentionally does not
-execute remotely in this MVP; use a trusted local shell for `tdmcp-agent panic`.
-
-Runtime flags: `--once` (poll once and exit), `--read-only`, `--creative`,
-`--tier <safe|standard|creative>`, `--poll-timeout <sec>`,
-`--drop-pending-updates`, `--profile <name>`, `--config <path>`, and `--help`.
-
-Setup flags: `--token-stdin`, `--chat-id <id>`, `--user-id <id>`,
-`--setup-timeout <sec>`, `--yes`, `--profile <name>`, `--config <path>`, and
-`--help`.
-
-## npm scripts
-
-| Script | Purpose |
-| --- | --- |
-| `npm run setup` | Guided install + build, then prints how to connect your client. |
-| `npm run dev` | Run the server from source (stdio). |
-| `npm run build` | Typecheck + bundle + copy assets to `dist/`. |
-| `npm test` | Unit + integration tests (Vitest + MSW). |
-| `npm run typecheck` / `npm run lint` | TypeScript / Biome. |
-| `npm run smoke:live` | End-to-end test against a running TD. |
-| `npm run validate:recipes` | Validate every recipe JSON. |
-| `npm run ai-party:dev` | Start the Live Nervous System AI Party dashboard/backend, normally on `http://127.0.0.1:8787/`. |
-| `npm run ai-party:dry` | Run the deterministic AI Party rehearsal smoke without external services. |
-| `npm run ai-party:td-build` | Build the optional `/project1/ai_party_poc` TouchDesigner preview network through the bridge. |
-| `npm run ai-party:test` | Run the focused AI Party live POC, Show Director, gateway and producer-runner tests. |
-| `npm run ai-party:telegram` | Start the local AI Party dashboard/backend with Telegram long polling enabled. |
-| `npm run ai-party:llm-eval` | Run the ShowIntent eval cases against `OLLAMA_BASE_URL` / `OLLAMA_MODEL`. |
-| `npm run ai-party:llm-baseline` | Save a timestamped ShowIntent local-LLM baseline report and failure JSONL. |
-| `npm run ai-party:llm-generate-data` | Generate deterministic ShowIntent training JSONL and train/validation splits. |
-| `npm run ai-party:llm-import-curated` | Convert approved curation CSV rows into validated training JSONL. |
-| `npm run import:bottobot` | (Re)build the embedded knowledge base — only needed to refresh it. |
-| `npm run build:mcpb` | Package a Claude Desktop `.mcpb` extension (formerly `.dxt`; see [Deployment](/deployment)). |
-| `npm run docs:dev` / `docs:build` | Run / build this documentation site (regenerates the [Tools reference](/reference/tools) first). |