@hybridlabor-api/aos 4.2.0 → 4.4.0

package/mcps/tdmcp/docs/pt/privacy.md

@@ -1,91 +0,0 @@
----
-title: Política de privacidade
-description: "O tdmcp roda inteiramente na sua própria máquina. Não coleta nenhum dado pessoal, não tem telemetria nem análise, e não envia nada para o autor ou para terceiros."
-aside: false
----
-
-# Política de privacidade
-
-_Última atualização: 27 de maio de 2026_
-
-## Resumo
-
-**O tdmcp não coleta, armazena nem transmite nenhum dado pessoal.** Ele roda
-inteiramente na sua própria máquina, não exige conta nem login, e não tem
-telemetria nem análise. Não envia nada para o autor nem para terceiros.
-
-## O que é o tdmcp
-
-O tdmcp é um servidor local de [Model Context Protocol](/pt/reference/architecture)
-mais uma pequena **ponte** em Python que roda dentro do seu próprio processo do
-[TouchDesigner](https://derivative.ca). Não existe serviço hospedado nem componente
-em nuvem: você instala tudo ao lado do TouchDesigner no seu próprio computador, e o
-seu cliente de IA (Claude Desktop, Claude Code, Codex ou Cursor) inicia o servidor
-local.
-
-## Dados que coletamos
-
-**Nenhum.** O tdmcp não tem:
-
-- contas de usuário, login ou autenticação própria;
-- telemetria, análise ou rastreamento de uso;
-- relatórios de erro ou de falha enviados para qualquer lugar.
-
-## Atividade de rede
-
-A única atividade de rede do servidor MCP são requisições HTTP locais para a sua
-**própria** ponte do TouchDesigner em `127.0.0.1:9980` (o host e a porta são
-configuráveis pelo usuário via `TDMCP_TD_HOST` / `TDMCP_TD_PORT`). Ele não faz
-nenhuma outra conexão de rede — nada sai para o autor, para a Anthropic ou para
-terceiros.
-
-Quaisquer arquivos que você pedir para o tdmcp gravar — receitas, presets,
-snapshots ou exportações para o [vault](/reference/tools) — são salvos no seu
-próprio disco local e nunca são enviados para lugar nenhum.
-
-## Seu cliente de IA
-
-Quando você descreve um visual, o seu comando e as respostas da IA são processados
-pelo **cliente de IA que você escolheu** (por exemplo, o Claude Desktop) sob a
-**política de privacidade desse cliente**. O tdmcp não é o controlador desses dados
-e não adiciona nenhuma coleta própria por cima do seu cliente.
-
-## Terceiros
-
-O tdmcp não inclui **nenhum SDK de terceiros, rastreador ou análise**. O npm e o
-GitHub são canais de distribuição do software e operam sob as próprias políticas de
-privacidade; o tdmcp em si não envia os seus dados para eles nem para ninguém
-durante a execução.
-
-## Segurança
-
-A ponte do TouchDesigner executa Python dentro do seu próprio processo do
-TouchDesigner e escuta em `127.0.0.1:9980`. Você continua no controle do acesso:
-
-- mantenha os endpoints de execução de código arbitrário fechados por padrão,
-  exceto quando você configurar `TDMCP_BRIDGE_TOKEN` ou definir explicitamente
-  `TDMCP_BRIDGE_ALLOW_EXEC=1` dentro do TouchDesigner, e
-- exija um token de portador definindo `TDMCP_BRIDGE_TOKEN` no servidor e no
-  TouchDesigner quando a ponte puder ser acessada além de uma máquina local
-  confiável.
-
-Veja a [referência de arquitetura](/pt/reference/architecture) e as
-[variáveis de ambiente](/pt/reference/environment) para o modelo de segurança
-completo.
-
-## Retenção e exclusão de dados
-
-Como o tdmcp não coleta nem retém nenhum dado pessoal, não há nada para
-armazenarmos, retermos ou excluirmos. Remover a extensão remove o software;
-quaisquer arquivos locais que você criou permanecem sob o seu controle, no seu
-próprio disco.
-
-## Contato
-
-Dúvidas sobre esta política? Abra uma issue em
-[github.com/Pantani/tdmcp/issues](https://github.com/Pantani/tdmcp/issues).
-
-## Alterações
-
-Se esta política mudar, a versão atualizada será publicada nesta página com uma
-nova data de "última atualização" acima.

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

@@ -1,178 +0,0 @@
----
-description: "Como funciona o servidor MCP do TouchDesigner — as camadas de tools MCP, a base de conhecimento de operadores embutida e a ponte que roda dentro do TouchDesigner."
----
-
-# Arquitetura
-
-O tdmcp são três programas que conversam entre si na sua máquina:
-
-```
-   Assistente de IA          servidor tdmcp               TouchDesigner
-  (Claude / Cursor)   ──▶   (Node / TypeScript)    ──▶   (a ponte Python dentro do TD)
-   "faça um túnel de         tools MCP + a base de         cria / conecta /
-    feedback a partir        conhecimento de operadores    inspeciona / dá preview dos nós
-    de noise"
-```
-
-1. **O assistente de IA** é qualquer cliente compatível com MCP — Claude Desktop,
-   Claude Code, Codex ou Cursor. É onde você descreve o que quer.
-2. **O servidor tdmcp** é um pequeno programa Node. Ele expõe à IA um conjunto de
-   "tools" do TouchDesigner e uma base de conhecimento de operadores embutida, pelo
-   [Model Context Protocol](https://modelcontextprotocol.io).
-3. **A ponte (bridge)** é um pacote Python que roda *dentro* do TouchDesigner (atrás
-   de um Web Server DAT). É o que de fato dirige o TD. Veja
-   [Bridge & REST API](/reference/bridge-api) (em inglês).
-
-```
-cliente MCP ──stdio──▶ servidor tdmcp (Node/TS) ──HTTP──▶ ponte do TouchDesigner (Python)
-                        ├── Camada 1  tools de artista (create_visual_system, …)
-                        ├── Camada 2  blocos de montagem (create_node_chain, …)
-                        ├── Camada 3  operações atômicas (create_td_node, …)
-                        ├── Base de conhecimento (recursos MCP)
-                        ├── Recipes (templates de rede validados)
-                        └── Motor de feedback (erros / preview / performance)
-```
-
-## As três camadas de tools
-
-As tools são organizadas em camadas para que a IA escolha a altitude certa para
-cada tarefa. Veja a lista completa e sempre atualizada na
-[referência de Tools](/reference/tools) (em inglês).
-
-- **Camada 1 — tools de artista.** Descreva um resultado
-  (`create_feedback_network`, `create_audio_reactive`, `create_generative_art`, …)
-  e receba uma rede inteira, conectada e organizada, muitas vezes já com um painel
-  de controle pronto para performar.
-- **Camada 2 — blocos de montagem.** Peças de nível intermediário
-  (`create_node_chain`, `connect_nodes`, `create_control_panel`,
-  `animate_parameter`, `create_external_io`, …) para montar e controlar redes na
-  mão.
-- **Camada 3 — operações atômicas.** CRUD de um nó só, mais inspeção, análise,
-  renderização e as válvulas de escape em Python (`create_td_node`,
-  `find_td_nodes`, `get_td_node_errors`, `execute_python_script`, …).
-
-Um grupo separado de [tools de vault](/reference/tools#obsidian-vault) (em inglês)
-faz a ponte entre um vault do Obsidian e o TouchDesigner.
-
-## O ciclo criar → verificar → visualizar
-
-Toda construção de alto nível segue o mesmo ciclo, para que a IA veja e corrija o
-próprio trabalho em vez de chutar:
-
-1. **Criar** a rede a partir de uma recipe, de um padrão GLSL ou de Python gerado.
-2. **Verificar** lendo os erros de cook/compilação (`get_td_node_errors`,
-   `summarize_td_errors`).
-3. **Visualizar (preview)** capturando o TOP de saída como uma imagem inline
-   (`get_preview`).
-
-As redes geradas são auto-organizadas num layout legível da esquerda para a direita
-(`arrange_network`) em vez de empilhar os nós uns sobre os outros.
-
-## Base de conhecimento
-
-O servidor já vem com uma referência embutida e offline, para que a IA use
-operadores de verdade em vez de inventá-los: **629 operadores**, **68 classes
-Python**, padrões de fluxo de trabalho, técnicas de GLSL, tutoriais, **7 perfis
-de release do TouchDesigner**, **45 entradas de compatibilidade de operadores**,
-**9 classes de compatibilidade da API Python** e **6 séries de builds
-experimentais**, **7 packs de técnicas** com **39 técnicas** e **6 referências
-de classes do TouchDesigner**. Tudo isso é exposto como recursos MCP que a IA
-pode ler sob demanda:
-
-`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://recipes/{name}` ·
-`tdmcp://tutorials/{name}`
-
-A base de conhecimento é versionada no repositório, então um clone novo precisa só
-de `npm install && npm run build`. O `npm run import:bottobot` a regenera a partir
-do `@bottobot/td-mcp` e só é necessário para atualizá-la.
-
-## Recipes
-
-Recipes são templates de rede validados (JSON) que a IA pode instanciar com
-`apply_recipe`. Elas cobrem pontos de partida comuns — túneis de feedback,
-reaction-diffusion, galáxias de partículas, barras de espectro de áudio, projection
-mapping e mais. Veja a [Galeria de receitas](/pt/guide/recipes) para o que cada uma
-constrói, e o guia `CONTRIBUTING.md` do repositório (em inglês) para adicionar as suas.
-
-## Transportes e eventos
-
-O servidor fala dois transportes MCP:
-
-- **stdio** (padrão) — para clientes locais como Claude Desktop e Claude Code.
-- **Streamable HTTP** (`TDMCP_TRANSPORT=http`) — serve o MCP em
-  `POST/GET/DELETE /mcp` no loopback com sessões com estado, para configurações
-  remotas/headless. Veja [Deployment](/deployment) (em inglês).
-
-Ele também pode assinar um **fluxo de eventos por WebSocket** do TD
-(`node.created` / `node.deleted` / `node.error` / `project.saved` /
-`timeline.frame` / `node.cook`) e encaminhar os eventos como notificações de log do
-MCP. Eventos de alta frequência (`timeline.frame`, `node.cook`) são descartados a
-menos que você opte por recebê-los. Controle com `TDMCP_EVENTS`.
-
-### Chamar o tdmcp de dentro do TouchDesigner (LOPs)
-
-O "MCP Client" do LOPs da dotsimulate pode rodar *dentro* do TouchDesigner e iniciar
-este servidor por stdio, fechando um ciclo: **TD (MCP Client do LOPs) → `node dist/index.js`
-(tdmcp) → HTTP → a ponte do TD em `127.0.0.1:9980` (o mesmo TD) → a rede.** Nenhuma
-mudança de transporte é necessária (stdio é o padrão). Como o cliente vive no TD e não tem
-um campo `env` documentado, aponte seu `command` para o wrapper `scripts/tdmcp-lops.mjs`,
-que injeta o perfil reforçado (`TDMCP_RAW_PYTHON=off`, `TDMCP_TOOL_PROFILE=safe`). Veja o
-[guia de integração com LOPs](/pt/guide/lops-integration).
-
-## Segurança {#security}
-
-A ponte do TouchDesigner roda **Python arbitrário dentro do seu processo do TD** —
-é justamente isso que permite ao assistente construir redes por você. Trate-a como
-uma porta aberta para a máquina onde o TD roda:
-
-- **O Web Server DAT escuta na sua porta (padrão `9980`) em todas as interfaces de
-  rede.** Qualquer um que alcance `http://<seu-ip>:9980` pode rodar código naquela
-  máquina. Só use numa rede confiável e/ou bloqueie a porta no firewall para o
-  localhost.
-- **Ligue a autenticação da ponte em redes não confiáveis:** defina
-  `TDMCP_BRIDGE_TOKEN` com um segredo compartilhado no ambiente do servidor **e** no
-  ambiente do TouchDesigner. A ponte então rejeita qualquer requisição sem um
-  `Authorization: Bearer <token>` correspondente (HTTP `401`). Sem definir (padrão),
-  mantém o fluxo local sem configuração.
-- `TDMCP_RAW_PYTHON=off` esconde apenas as duas **tools de Python cru**
-  (`execute_python_script`, `exec_node_method`), onde o *cliente* escreve o código.
-  **Não** é um botão de desligar a execução de código: muitas tools de mais alto
-  nível ainda enviam o próprio Python templado para a ponte. Os endpoints de
-  código arbitrário do lado da ponte (`/api/exec`, `method` de nó) ficam fechados
-  por padrão, exceto quando `TDMCP_BRIDGE_TOKEN` estiver configurado ou
-  `TDMCP_BRIDGE_ALLOW_EXEC=1` for definido explicitamente no ambiente do
-  TouchDesigner; os endpoints estruturados continuam funcionando.
-- O servidor MCP escuta só no loopback (`127.0.0.1`) nos dois transportes e ativa a
-  proteção contra DNS-rebinding no HTTP.
-- **A ponte recusa requisições cross-origin de navegador.** Qualquer requisição que
-  traga um header `Origin` que não seja loopback é rejeitada (HTTP `401`), então uma
-  página web maliciosa não consegue fazer um POST silencioso para a ponte
-  (CSRF / DNS-rebinding → execução de código drive-by). O servidor MCP não envia
-  `Origin`, então o uso normal não é afetado.
-- **A UI de chat do copiloto local (`tdmcp chat`) aplica a mesma proteção.** Ela
-  escuta só no loopback e rejeita (HTTP `403`) qualquer requisição cujo `Host` ou
-  `Origin` não seja um nome de loopback, então uma página que o artista visita não
-  consegue dirigir o CRUD de nós contra o projeto ao vivo via
-  `http://127.0.0.1:<porta-do-chat>/chat`.
-
-Tudo isso é configurado pelas [variáveis de ambiente](/pt/reference/environment).
-
-## Limitações conhecidas
-
-- **Eventos de WebSocket** são encaminhados como notificações de log do MCP nos dois
-  transportes; eventos de alta frequência são descartados a menos que você opte por
-  recebê-los.
-- **Os construtores de áudio / partículas / 3D e as recipes exóticas** (kinect, LED,
-  projeção) produzem redes válidas e conectadas, mas usam nomes de parâmetro do TD
-  em "melhor esforço" — pode ser preciso ajustar finamente, e elas emitem avisos
-  nesse sentido.
-- **O preview** retorna o TOP na sua resolução nativa (o tamanho pedido é apenas
-  uma sugestão).
-- A ponte é entregue como módulos Python mais um template de callbacks (um `.tox`
-  binário não pode ser gerado a partir do código-fonte); o instalador de uma linha
-  monta tudo para você.

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

@@ -1,70 +0,0 @@
----
-description: "Variáveis de ambiente do tdmcp, o servidor MCP do TouchDesigner — configure o host e a porta da ponte, o token de autenticação, o caminho do vault e a segurança da execução."
----
-
-# Variáveis de ambiente
-
-A configuração pode vir de variáveis de ambiente ou de um arquivo JSON opcional.
-As variáveis de ambiente vencem os valores do arquivo, então CI, Docker e a config
-do cliente MCP continuam simples. Toda variável é opcional e tem um padrão sensato.
-
-## Servidor
-
-| Variável | Padrão | Descrição |
-| --- | --- | --- |
-| `TDMCP_TD_HOST` | `127.0.0.1` | Host da ponte do TouchDesigner. |
-| `TDMCP_TD_PORT` | `9980` | Porta do Web Server DAT. |
-| `TDMCP_TRANSPORT` | `stdio` | Transporte MCP: `stdio` (padrão) ou `http` (Streamable HTTP). |
-| `TDMCP_HTTP_PORT` | `3939` | Porta do transporte HTTP (quando `TDMCP_TRANSPORT=http`). |
-| `TDMCP_EVENTS` | `on` | Assina os eventos por WebSocket do TD e os encaminha como notificações de log do MCP (`on`/`off`). |
-| `TDMCP_RAW_PYTHON` | `on` | Se expõe as duas tools de escape em Python cru (`execute_python_script`, `exec_node_method`) no servidor MCP. Defina como `off` para trancá-las em configurações restritas. Isso remove só essas duas tools de código escrito pelo cliente — muitas tools de mais alto nível ainda enviam o próprio Python *templado* à ponte, então `off` **não** significa "nenhum código roda no TD". A própria ponte agora mantém endpoints de código arbitrário desligados, exceto quando `TDMCP_BRIDGE_TOKEN` ou o opt-in explícito `TDMCP_BRIDGE_ALLOW_EXEC=1` estiver definido no ambiente do TouchDesigner. |
-| `TDMCP_TOOL_PROFILE` | `full` | Perfil de exposição de tools. `full` registra todas as tools; `safe` esconde tools destrutivas/de código cru, incluindo Python cru, deleção de nós, reescrita de DATs, writes de checkpoint/componente/pacote e writes de previews — um superconjunto estrito de `TDMCP_RAW_PYTHON=off`. Use `safe` para um agente autônomo dentro do TD (ex.: o "MCP Client" do LOPs da dotsimulate). O padrão `full` mantém os clientes existentes inalterados. |
-| `TDMCP_BRIDGE_TOKEN` | _(não definido)_ | Token bearer compartilhado opcional. Quando definido, o servidor o envia e a ponte o exige — defina o **mesmo** valor no ambiente do TouchDesigner para ligar a autenticação. |
-| `TDMCP_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent` (registrado no stderr). |
-| `TDMCP_REQUEST_TIMEOUT_MS` | `10000` | Timeout por requisição à ponte, em milissegundos. |
-| `TDMCP_CONFIG_FILE` | _(não definido)_ | Arquivo JSON de configuração opcional. As chaves usam os nomes internos (`tdHost`, `tdPort`, `requestTimeoutMs`, etc.). |
-| `TDMCP_PROFILE` | _(não definido)_ | Nome de perfil opcional dentro do arquivo de configuração selecionado (`profiles.<nome>`), seja ele definido por `TDMCP_CONFIG_FILE` ou encontrado pelos caminhos de busca padrão. O arquivo base carrega primeiro, o perfil sobrescreve, e as variáveis de ambiente vencem ambos. |
-| `TDMCP_VAULT_PATH` | _(não definido)_ | Caminho absoluto para um vault do Obsidian (uma pasta de notas Markdown). Habilita as [tools de vault](/reference/tools#obsidian-vault) (em inglês); um `~/` inicial é expandido. Deixe sem definir para desabilitá-las. |
-
-## Copiloto local (`tdmcp chat`)
-
-Estas configuram o [copiloto LLM local](/reference/cli#local-copilot-tdmcp-chat)
-(em inglês).
-
-| Variável | Padrão | Descrição |
-| --- | --- | --- |
-| `TDMCP_LLM_BASE_URL` | `http://127.0.0.1:11434/v1` | Endpoint de chat compatível com OpenAI. Por padrão aponta para um Ollama local; aponte para LM Studio, uma GPU na nuvem ou uma API paga. |
-| `TDMCP_LLM_MODEL` | `qwen2.5:3b` | Id do modelo que o copiloto pede (precisa estar baixado no backend, ex.: `ollama pull qwen2.5:3b`). Suba para `qwen2.5:7b` para mais folga. |
-| `TDMCP_LLM_API_KEY` | _(não definido)_ | Token bearer opcional para o endpoint do LLM (ignorado pelo Ollama local; necessário para APIs pagas/na nuvem). |
-| `TDMCP_LLM_TIER` | `standard` | Tier padrão de tools do chat: `standard`, `safe` (somente leitura) ou `creative` (adiciona geradores curados). Os toggles do navegador ainda podem sobrescrever por turno. |
-| `TDMCP_LLM_MAX_STEPS` | `8` | Máximo de iterações modelo/tool em um turno do copiloto local. Valores são limitados a `1..32`. |
-| `TDMCP_LLM_TEMPERATURE` | `0.4` | Temperatura de amostragem enviada ao endpoint de chat compatível com OpenAI. Valores são limitados a `0..2`. |
-| `TDMCP_CHAT_PORT` | `4141` | Porta de loopback em que a UI web do `tdmcp chat` escuta. |
-
-## Lado do TouchDesigner
-
-Defina estas no ambiente do **TouchDesigner** (não no do servidor) para defesa em
-profundidade — elas são impostas do lado da ponte, mesmo para chamadores diretos na
-rede. Veja [Segurança](/pt/reference/architecture#security).
-
-| Variável | Padrão | Descrição |
-| --- | --- | --- |
-| `TDMCP_BRIDGE_ALLOW_EXEC` | _(não definido)_ | Opt-in opcional do lado da ponte. Defina como `1`/`true`/`on` no ambiente do TouchDesigner para permitir os endpoints de código arbitrário (`/api/exec`, `method` de nó) quando não houver token da ponte configurado. Deixe sem definir para o padrão mais seguro; os endpoints estruturados continuam funcionando. |
-| `TDMCP_BRIDGE_TOKEN` | _(não definido)_ | Token bearer compartilhado; precisa bater com o valor do servidor para autorizar as requisições. |
-
-## Exemplo: config do cliente MCP
-
-```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/public/favicon.svg

@@ -1,12 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-label="tdmcp">
-  <defs>
-    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
-      <stop offset="0" stop-color="#ff2da6"/>
-      <stop offset="1" stop-color="#36e3ff"/>
-    </linearGradient>
-  </defs>
-  <rect width="64" height="64" rx="14" fill="#0b0b0e"/>
-  <rect x="2.5" y="2.5" width="59" height="59" rx="11.5" fill="none" stroke="url(#g)" stroke-width="2" opacity="0.6"/>
-  <text x="32" y="43" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="30" font-weight="700" text-anchor="middle" fill="#f4f4f6">td</text>
-  <circle cx="50" cy="16" r="4" fill="url(#g)"/>
-</svg>

package/mcps/tdmcp/docs/public/robots.txt

@@ -1,4 +0,0 @@
-User-agent: *
-Allow: /
-
-Sitemap: https://pantani.github.io/tdmcp/sitemap.xml

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

@@ -1,116 +0,0 @@
----
-title: API stability & deprecation policy
-description: The v1.0 API-stability pin for tdmcp — what counts as the public tool contract, the no-breaking-change guarantee across a minor cycle, and the one-minor-warn / next-minor-remove deprecation policy.
----
-
-# API stability & deprecation policy
-
-This page is the formal **stability pin** for the tdmcp tool API on the road to
-1.0 (roadmap gate **G1**). It states *what is held stable*, *for how long*, and
-*how a change is allowed to break it*.
-
-It is a companion to the [Tool API contract](./tool-contract), which documents
-the behavioural invariants every tool follows (naming, input schema, error
-handling, offline behaviour, result shape, deprecation mechanics). This page does
-**not** restate those rules — it pins them: it defines the surface they apply to,
-the guarantee window, and the deprecation timeline. At 1.0 these two pages fold
-into a single frozen contract.
-
-## What the public API surface is
-
-The "tdmcp tool" contract has exactly two parts, both read from source:
-
-1. **The `ToolContext` shape** — the dependency-injection object passed to every
-   tool handler (`src/tools/types.ts`).
-2. **Each tool's Zod `inputSchema`** — the per-tool argument schema exposed via
-   `inputSchema: schema.shape`, registered through `server.registerTool(...)`.
-
-Anything not in these two — internal helpers, the bridge REST wire format, the
-Python bridge modules in `td/`, the knowledge-base layout, CLI internals — is
-**not** part of the pinned public surface and may change in a minor release.
-
-### `ToolContext` fields (as of the v0.9 line)
-
-`ToolContext` (`src/tools/types.ts`) is the injected dependency bundle. Required
-fields are always present; optional fields may be `undefined` when the
-corresponding feature is off, and a handler **must** degrade gracefully when an
-optional dependency is absent.
-
-| Field | Required | Purpose |
-| --- | --- | --- |
-| `client` | yes | `TouchDesignerClient` — the HTTP client to the TD bridge. |
-| `knowledge` | yes | `KnowledgeBase` — embedded operator / Python / pattern reference. |
-| `recipes` | yes | `RecipeLibrary` — validated network templates. |
-| `logger` | yes | `Logger` — structured logging. |
-| `vault?` | no | `Vault` — Obsidian vault, set via `TDMCP_VAULT_PATH`; `undefined` when unconfigured. |
-| `allowRawPython?` | no | Whether raw-Python escape-hatch tools may register. `undefined` means allowed (default); only an explicit `false` locks them out. |
-| `toolProfile?` | no | Tool-exposure profile; `"safe"` hides destructive/raw-code tools, `undefined` means `"full"` (default). |
-| `llm?` | no | Best-effort LLM backend (vision/captioning/text). Tools must degrade when it is `undefined` or unreachable. |
-| `server?` | no | The live `McpServer`, assigned before registration so a few tools can introspect the registry. |
-| `creativeRag?` | no | Optional local Creative RAG service (`TDMCP_RAG_ENABLED=1`); backs read-only `tdmcp://creative/*` resources only. |
-| `projectRag?` | no | Optional local Project RAG service (`TDMCP_RAG_ENABLED=1 && TDMCP_PROJECT_RAG_ENABLED=1`); backs read-only `tdmcp://project/*` resources only. |
-
-This table is descriptive, not the source of truth — `src/tools/types.ts` is.
-The stability **rule** below is what is pinned, not this exact field list (the
-list grows by additive optional fields over time).
-
-## The stability guarantee
-
-Across **one full minor release cycle** (one tagged minor with no breaking
-change), tdmcp guarantees:
-
-- **No breaking change to `ToolContext`.** Adding a new **optional** field is
-  allowed and non-breaking. **Renaming** a field, **removing** a field, changing
-  a field's type, or **adding a required** field is breaking and not allowed
-  within the cycle.
-- **No breaking change to any existing tool's `inputSchema`.** Adding a new
-  **optional** field (typically via `.default(...)` or `.optional()`) is allowed.
-  **Renaming** a field, **removing** a field, **tightening** a type, or making a
-  previously **optional field required** is breaking and not allowed.
-
-A field declared with `.default(...)` is optional from the client's point of
-view — the server fills the default before the handler runs — so adding one never
-breaks an existing caller.
-
-| Change | Verdict |
-| --- | --- |
-| Add a new optional `ToolContext` field | ✅ non-breaking |
-| Add a new tool | ✅ non-breaking |
-| Add an optional / defaulted field to a tool schema | ✅ non-breaking |
-| Make a required tool-schema field optional | ✅ non-breaking |
-| Rename or remove a `ToolContext` field | ❌ breaking |
-| Add a required `ToolContext` field | ❌ breaking |
-| Rename or remove a tool-schema field | ❌ breaking |
-| Make an optional tool-schema field required, or tighten its type | ❌ breaking |
-| Remove a registered tool with no warn cycle | ❌ breaking |
-
-Any change marked breaking requires a **major** version bump.
-
-## Deprecation policy
-
-Removals are never silent. The policy is **one-minor warn, next-minor remove**:
-
-1. **Warn (minor _N_).** The item is marked deprecated:
-   - a `CHANGELOG.md` entry under that minor records the deprecation and names
-     the replacement (if any);
-   - the tool's **description** is annotated as deprecated so MCP clients see it
-     at the call site;
-   - the tool stays **registered and callable** — for a renamed tool, the old
-     name is kept as an alias.
-2. **Remove (minor _N+1_).** No earlier than the next minor, the deprecated item
-   (or alias) is removed, and the removal is recorded in `CHANGELOG.md`.
-
-So any deprecated tool or alias stays callable for **at least one full minor
-release** after the deprecation is announced, giving clients a window to migrate
-without guessing. Where there is a replacement, the deprecation note points to
-it.
-
-## Relationship to G1 and 1.0
-
-Roadmap gate **G1 — Tool API stability** has two parts: completing one tagged
-minor cycle with no breaking change to the surface above, and this
-`API_STABILITY.md` pin. This file satisfies the second part. When 1.0 ships, the
-guarantee window widens from "one minor cycle" to "the 1.x line": breaking the
-pinned surface then requires a **2.0** major bump, and this page plus the
-[Tool API contract](./tool-contract) become the single frozen contract clients
-can build against.