@hybridlabor-api/aos 4.2.0 → 4.4.0

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

@@ -1,420 +0,0 @@
-# Project RAG
-
-> Status: **experimental — F0-F4 publicados atrás de flags opt-in**.
-> A validação live da quarentena TouchDesigner ainda exige uma bridge separada
-> na porta `9981` e só é verificada quando essa bridge está realmente rodando.
-
-Project RAG é o irmão **técnico/de projeto** do
-[Creative RAG](./CREATIVE_RAG.md). Indexa **projetos, componentes, snippets
-e tutoriais** do TouchDesigner com `provenance` + `license` obrigatórios em
-todo card, para que o agente responda "me mostre um `.tox` real que faz hand
-tracking com MediaPipe" — e sempre exiba a origem e os termos de uso.
-
-É **opt-in**, **offline-first**, e o caminho de busca **nunca** toca a bridge
-TouchDesigner, DMX ou Python exec. O analyzer opt-in de quarentena (F3) usa uma
-instância TD *separada* em porta dedicada (`9981`), nunca a 9980 ativa do usuário.
-
-## Quando usar
-
-| Pergunta | Use |
-|---|---|
-| "Me inspire com artista que usa estética generativa de crescimento" | **Creative RAG** |
-| "Mostre `.tox` reais que fazem FFT + Feedback para eu reconstruir" | **Project RAG** |
-| "Qual wrapper MediaPipe-TD eu deveria olhar?" | **Project RAG** |
-| "Qual museu tem obras generativas em open access?" | **Creative RAG** |
-
-Os dois compartilham embedder + camada de storage + gating, mas mantêm os
-cards em **diretórios separados** — um nunca vaza no outro.
-
-## Gating
-
-Off por default. Ativação exige **as duas flags**:
-
-```bash
-export TDMCP_RAG_ENABLED=1            # chave-mãe RAG (off por default)
-export TDMCP_PROJECT_RAG_ENABLED=1    # chave do project-rag (default ON se RAG on)
-```
-
-Quando qualquer uma estiver off, `tdmcp project-rag …` imprime uma linha de
-desativado e sai 0; os MCP resources não são registrados.
-
-## Fontes do seed (F2)
-
-F2 entrega **dois repos P0** por default + um scanner de topic:
-
-- [`torinmb/mediapipe-touchdesigner`](https://github.com/torinmb/mediapipe-touchdesigner) — **MIT** (permissiva)
-- [`DBraun/TouchDesigner_Shared`](https://github.com/DBraun/TouchDesigner_Shared) — **GPL-3.0** (copyleft; sinalizada no output da busca)
-
-Ambos via REST API do GitHub (sem `git clone` local — robusto para CI), com
-`provenance` e licença SPDX-detected por card.
-
-Você pode trocar o seed (ou adicionar mais repos) via CSV:
-
-```bash
-export TDMCP_PROJECT_RAG_GITHUB_REPOS="torinmb/mediapipe-touchdesigner,DBraun/TouchDesigner_Shared,foo/bar@v1"
-```
-
-Sintaxe `owner/repo[@ref]` fixa branch/tag/SHA.
-
-### Adicionando fontes GPL (handling de copyleft)
-
-Project RAG aceita licenças copyleft (`GPL-2.0`, `GPL-3.0`, `LGPL-*`,
-`AGPL-3.0`) mas trata como *bandeira amarela*, nunca bloqueio:
-
-- Cards são indexados e binários baixados normalmente.
-- O output da busca renderiza a licença como `GPL-3.0 · copyleft` para deixar
-  a obrigação visível à vista.
-- O composite aplica uma **penalidade leve de desempate** (`−0.05`) para que
-  um card permissivo (MIT/Apache/BSD/ISC/MPL) igualmente relevante fique
-  acima do copyleft. É nudge, nunca bloqueio — um match semântico forte
-  passa por cima da penalidade.
-- A matriz é enforçada por `licensePolicy` em
-  [`src/projectRag/licensePolicy.ts`](https://github.com/Pantani/tdmcp/blob/main/src/projectRag/licensePolicy.ts);
-  cards `Derivative-EULA`, `Proprietary-*`, `Unknown` e `Restricted` jamais
-  têm binário persistido, independente da allowlist.
-
-Para **excluir** resultados GPL completamente de uma busca, passe
-`--license MIT,Apache-2.0,BSD-2-Clause,BSD-3-Clause,ISC,MPL-2.0,CC0,PublicDomain`.
-
-### Scanner de topics do GitHub
-
-A fonte `github-topic` varre a Search API do GitHub por repos com topics
-relevantes a TouchDesigner e surface os com sinal mais alto:
-
-```bash
-# Topics default (em ordem de prioridade):
-#   touchdesigner-components, touchdesigner-tool,
-#   touchdesigner-tools, touchdesigner
-$ tdmcp project-rag sync --source github-topic
-
-# Override por run (CSV) e cap do número de resultados:
-$ tdmcp project-rag sync --topic touchdesigner-components --cap 10
-
-# Desligar o scanner totalmente para este run:
-$ tdmcp project-rag sync --topic off
-
-# Ou via env (persistente):
-$ export TDMCP_PROJECT_RAG_GITHUB_TOPICS=touchdesigner-components,touchdesigner
-$ export TDMCP_PROJECT_RAG_TOPIC_CAP=15
-```
-
-Filtros duros aplicados **antes** de qualquer extração:
-
-| Filtro | Default | Configurável via |
-|---|---|---|
-| Allowlist SPDX | MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Unlicense, CC0-1.0 (clean); GPL/LGPL/AGPL aceitos como copyleft; resto rejeitado | hardcoded para segurança |
-| Mínimo de stars | 5 | (opção do construtor) |
-| Recência mínima de `pushed_at` | `>=2024-01-01` | (opção do construtor) |
-| Cap por sync | 25 repos total entre topics | `--cap N` / `TDMCP_PROJECT_RAG_TOPIC_CAP` |
-| Forks | rejeitados | hardcoded |
-| Token GitHub | opcional mas recomendado | `TDMCP_PROJECT_RAG_GH_TOKEN` |
-
-Um HTTP 403 com corpo "rate limit" vira `SourceSkippedError` tipado — cards
-prévios nunca são tombstoneados por um retorno zero silencioso.
-
-### Rate-limit do GitHub e token
-
-Sem autenticação, **60 requests/hora** por IP. Com Personal Access Token
-(sem scopes para repos públicos), **5.000 requests/hora**:
-
-```bash
-export TDMCP_PROJECT_RAG_GH_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxxxxxxx"
-```
-
-Quando o limite anônimo é estourado, o adapter lança `SourceSkippedError`
-tipado — **nunca** retorna zero items silencioso (o que tombstonearia
-erroneamente todos os cards prévios da fonte).
-
-### Exemplo de sessão
-
-```bash
-# 1. Puxa cards dos repos configurados + scanner de topic
-$ tdmcp project-rag sync
-synced: 14 added, 0 updated, 0 tombstoned, 12 binaries stored, 2 skipped (license)
-
-# 2. Lista as fontes e status
-$ tdmcp project-rag sources
-ready    github-repo   (GitHub repo allowlist (TDMCP_PROJECT_RAG_GITHUB_REPOS)) — authenticated
-ready    github-topic  (GitHub topic scanner (touchdesigner-components et al.)) — authenticated
-planned  derivative-local      (TouchDesigner OP Snippets + Palette (local install)) — F2
-planned  awesome-touchdesigner (monkeymonk/awesome-touchdesigner (discovery)) — F2
-
-# 3. Embedda cards novos/alterados (cache hits pulam re-embed)
-$ tdmcp project-rag index
-indexed: 14 embedded, 0 cached/skipped, 14 total cards
-
-# 4. Busca semântica — badge copyleft aparece em resultados GPL/LGPL/AGPL
-$ tdmcp project-rag search "mediapipe hand tracking"
-0.812  torinmb/mediapipe-touchdesigner [component] — MIT
-        https://github.com/torinmb/mediapipe-touchdesigner
-0.341  DBraun/TouchDesigner_Shared [component] — GPL-3.0 · copyleft
-        https://github.com/DBraun/TouchDesigner_Shared
-        rights: Copyleft (GPL-3.0): derived work must preserve license.
-
-# 5. Re-rank sem re-embed (ex.: após tunar pesos)
-$ tdmcp project-rag reindex --rescore
-rescored: 14 of 14 cards (no re-embed)
-
-# 6. Lê um card completo (provenance + license + score)
-$ tdmcp project-rag info <id> --json | jq .
-```
-
-### O que cada card carrega
-
-Todo card persistido inclui os campos obrigatórios do schema v2:
-
-- `provenance.sourceName` — ex.: `github:torinmb/mediapipe-touchdesigner`
-- `provenance.sourceUrl` — URL canônica
-- `provenance.canonical` — base do hash do id
-- `provenance.commitOrVersion` — branch/tag/SHA no momento do sync
-- `provenance.fetchedAt` — timestamp ISO
-- `license` + `licenseConfidence` (`spdx-detected` via GitHub License API)
-- `binaryHash` (sha256) + `binaryPath` (relativo ao data dir) quando a
-  licença permite persistir o `.tox`/`.toe`
-- `score.composite` — `technical · 0.45 + license · 0.25 + freshness · 0.15 + reliability · 0.15`
-  (pesos configuráveis via `TDMCP_PROJECT_RAG_SCORE_WEIGHTS`)
-
-Cards `Derivative-EULA`, `Proprietary-*`, `Unknown` e `Restricted` **nunca**
-têm o binário persistido localmente, mesmo se a allowlist permitir — a matriz
-de licenças é enforçada antes do download.
-
-## CLI
-
-```bash
-tdmcp project-rag sources                           # lista fontes + status
-tdmcp project-rag sync                              # puxa cards de todas as fontes
-tdmcp project-rag sync --source github-repo --limit 5
-tdmcp project-rag sync --topic touchdesigner-components --cap 10
-tdmcp project-rag sync --topic off                  # desliga topic scanner neste run
-tdmcp project-rag index                             # embedda novos/alterados (Ollama)
-tdmcp project-rag reindex --rescore                 # recompila score SEM re-embed
-tdmcp project-rag search <query>                    # busca cosine no índice local
-tdmcp project-rag search <query> --license MIT,Apache-2.0 --type component --tags tox
-tdmcp project-rag info <id>                         # mostra um card
-```
-
-Todos suportam `--json`.
-
-## Scoring (ajuste F2)
-
-`finalRank = cosineSim * score.composite`. O composite é soma ponderada de
-quatro eixos 0..1 mais um desempate copyleft:
-
-| Campo | O que captura | Peso default |
-|---|---|---|
-| `technical` | `log10(operatorMixTotal+1)/3 · 0.5` mais bônus para arquivos top-level, params expostos, scripts, preview, e tamanho do body | `0.45` |
-| `license` | `licenseScore(license)` — CC0/PublicDomain = 1.0, MIT/Apache/BSD/ISC/MPL = 0.95, CC-BY* = 0.8, Derivative-EULA = 0.85, GPL/LGPL/AGPL = 0.7, Proprietary-Free = 0.4, Unknown = 0.2 | `0.25` |
-| `freshness` | `exp(-age_em_dias / 365)` a partir de `provenance.fetchedAt` | `0.15` |
-| `reliability` | `spdx-detected/declared` → 0.85, `heuristic` → 0.6, `unknown` → 0.4; **fontes curadas** (seed default do tdmcp) ganham `+0.10` | `0.15` |
-| `copyleftPenalty` | `−0.05` aplicado após a soma quando a licença é GPL/LGPL/AGPL — desempate, nunca bloqueio | `−` |
-
-Override de pesos via `TDMCP_PROJECT_RAG_SCORE_WEIGHTS=technical:license:freshness:reliability`
-(ex.: `0.55:0.20:0.15:0.10` para enviesar puramente para fit técnico). Depois
-rode `tdmcp project-rag reindex --rescore` para aplicar sem gastar ciclos do
-embedder.
-
-Os pesos default foram tunados contra
-`_workspace/campaign_project_rag/scoring_ground_truth.json` (10 queries →
-top-1 esperados) e batem **9/10 de hit-rate** em
-`tests/unit/projectRag/scoringGroundTruth.test.ts`.
-
-## MCP resources
-
-Registrados SOMENTE quando as duas flags estão on:
-
-- `tdmcp://project/cards/{id}` — um card (id = sha256 de `provenance.canonical`).
-- `tdmcp://project/search{?q,k,license,type,tags,operator}` — busca cosine;
-  todo resultado carrega provenance + license + rightsNotes.
-- `tdmcp://project/sources` *(F4)* — fontes configuradas + status
-  (`ready` / `skipped` / `planned` / `failed`), pra o agente saber quais
-  fontes estão indexadas antes de buscar.
-
-## F4 — superfície AI (prompts, tool de copiloto, cross-link no CLI)
-
-F4 é a **camada AI** em cima de F0–F3. Tudo offline, opt-in, gated por
-`TDMCP_RAG_ENABLED=1 && TDMCP_PROJECT_RAG_ENABLED=1`.
-
-### Prompt MCP — `project_rag_context`
-
-Roda `service.search(query, k, { license })` no índice Project RAG
-configurado e devolve uma mensagem de prompt listando os top-k cards como
-*referência autoritativa* — título, licença, notas de direitos (se houver)
-e `tdmcp://project/cards/{id}`. Args: `query` (texto livre), `k` (1–10,
-default 5), `license` (CSV tipo `CC0,MIT,Apache-2.0`).
-
-Se a Project RAG não estiver habilitada ou o service der throw, o prompt
-**degrada silenciosamente** para um prompt padrão que menciona o problema e
-segue com o conhecimento próprio do modelo — ele nunca bloqueia o turn. O
-mesmo fallback vale para um resultado vazio (com a dica
-`tdmcp project-rag sync`).
-
-### Resource MCP — `tdmcp://project/sources`
-
-Lista JSON read-only de `{ name, displayName, status, reason? }` para que
-um agente saiba, antes de buscar, quais fontes estão indexadas localmente
-vs. configuradas mas skipped/planned/failed.
-
-### Tool de copiloto — `project_rag_search`
-
-Tool LLM read-only (`mutates: false`) exposta para `tdmcp ask`,
-`tdmcp chat`, o chat server loopback e o copiloto Telegram. Args espelham
-o CLI: `query`, `k` (default 5, máx 20), e arrays opcionais de filtro
-`license`, `type`, `operator`, `tags`. A tool é incluída no catálogo por
-`resolveTools(tier, { projectRag: ctx.projectRag !== undefined })` — então
-quando a Project RAG está desabilitada, **a tool fica AUSENTE do catálogo,
-não recusada na call**. Um modelo pequeno nunca vê uma tool que não pode
-usar.
-
-### Dica de cross-link no CLI (Creative RAG → Project RAG)
-
-Quando `tdmcp creative-rag search` retorna poucos resultados (default
-threshold ≤ 2) **e** a Project RAG está enabled **e** o usuário está em
-modo texto (não `--json`), o CLI imprime uma única linha no stderr:
-
-```text
-tip: also try `tdmcp project-rag search "<query>"` — more sources may match in the local project repertoire.
-```
-
-A sugestão é puramente informativa — não altera o comportamento da busca,
-saída para máquina (`--json`) nem exit code. Existe pra que um artista que
-tentou a RAG errada primeiro consiga pivotar sem reler os docs.
-
-### Ranking cross-RAG — fundir os dois corpora (opt-in)
-
-Quando os dois corpora RAG estão habilitados, `tdmcp ask` pode fundir Creative RAG
-e Project RAG em **um** bloco de referências ranqueado usando
-[Reciprocal Rank Fusion (RRF)](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf):
-`rrf(d) = Σ 1/(k + rank)`. RRF é **baseado em ranking**, então evita comparar
-escalas incompatíveis diretamente (Creative usa cosine `0..1`; Project usa
-`cosineSim * composite`). Habilite com:
-
-```text
-export TDMCP_RAG_ENABLED=1          # chave-mae do RAG
-export TDMCP_PROJECT_RAG_ENABLED=1  # chave do project-rag (default ON quando a chave-mae esta on)
-export TDMCP_RAG_FUSION=1           # fusao cross-RAG (default OFF)
-export TDMCP_RAG_FUSION_K=60        # constante k do RRF (inteiro positivo 1..1000, default 60)
-```
-
-A fusão ativa **somente** quando `TDMCP_RAG_ENABLED &&
-TDMCP_PROJECT_RAG_ENABLED && TDMCP_RAG_FUSION` e **ambos** os corpora retornam
-pelo menos um resultado. Se qualquer corpus estiver vazio, ausente ou com erro,
-`tdmcp ask` volta para o bloco de contexto criativo existente — comportamento
-idêntico a deixar a flag off. `k` menor concentra mais peso nos primeiros ranks;
-`k` maior achata a diferença.
-
-## F3 — análise via bridge-quarentena (opt-in)
-
-F3 entrega **dois analisadores de artefato** para `.toe`/`.tox` baixados.
-Ambos rodam completamente fora do TouchDesigner principal do usuário —
-nenhum deles consegue atrapalhar um show ao vivo.
-
-### Analisador estático (`toeExpand`)
-
-Wrapper para um CLI externo tipo `toeexpand` (o binário que você colocar
-no `PATH`), executado em subprocesso de quarentena:
-
-- Apenas `spawn()` — sem interpolação de shell.
-- Ambiente reduzido: somente `PATH`, `HOME`, `LANG=C.UTF-8`. Nenhum `TDMCP_*` vaza.
-- Timeout duro de 30s (configurável via `TDMCP_PROJECT_RAG_ANALYZE_TIMEOUT_MS`).
-- Group-kill no timeout (`detached:true` + `kill(-pgid)`).
-- `cwd` UUID por chamada em `os.tmpdir()/tdmcp-prag-toe/` — limpeza
-  `try/finally` em todo caminho de saída.
-- O `.toe`/`.tox` é copiado para dentro do cwd quarentena; o Node nunca o abre.
-- Quando o binário não está no `PATH`, retorna `skipped` (NÃO `failed`), para
-  que um sync normal sem `toeexpand` instalado apenas registre que a análise
-  estática foi pulada e prossiga.
-
-Defina o caminho explicitamente quando necessário:
-
-```bash
-export TDMCP_PROJECT_RAG_TOEEXPAND_BIN=/usr/local/bin/toeexpand
-```
-
-### Analisador dinâmico (bridge de quarentena)
-
-Quando você quer realmente *cozinhar* o artefato, F3 dirige uma **instância
-dedicada do TouchDesigner**, em uma **porta separada** (default `9981`, nunca
-`9980`). O TD principal do usuário não é tocado.
-
-A instalação é orientada por docs e idempotente — `tdmcp project-rag bridge
-install` imprime o walkthrough e prova se a bridge está acessível:
-
-```text
-$ tdmcp project-rag bridge install
-tdmcp project-rag bridge install — quarantine bridge setup
-…
-  1. Abra uma instância nova de TouchDesigner (NÃO reuse a que tdmcp dirige
-     para trabalho ao vivo).
-  2. Dentro dela, instale a bridge tdmcp: tdmcp install-bridge
-  3. Edite o parâmetro "port" do Web Server DAT de 9980 → 9981.
-  4. Salve como tdmcp_bridge_qa.toe.
-  5. Habilite F3:
-       export TDMCP_PROJECT_RAG_BRIDGE_ANALYSIS=1
-       export TDMCP_PROJECT_RAG_ENABLED=1
-       export TDMCP_RAG_ENABLED=1
-       # Opcional, mas recomendado quando a bridge de quarentena exige auth:
-       export TDMCP_BRIDGE_TOKEN=<mesmo-token-usado-por-essa-bridge>
-…
-Probe: http://127.0.0.1:9981 — OFFLINE
-```
-
-O analisador:
-
-- Instancia um **novo** `TouchDesignerClient` na
-  `TDMCP_PROJECT_RAG_BRIDGE_PORT` (default `9981`). **Recusa** usar a porta
-  `9980` — chamar `analyze` com a porta apontando para `9980` devolve
-  `failed: "refusing to use main TD port 9980"`.
-- Reusa `TDMCP_BRIDGE_TOKEN` como bearer token da bridge de quarentena quando
-  ele está setado, então uma bridge QA protegida pode continuar autenticada.
-- Sonda a bridge com `GET /api/info`. Se a sonda lança erro de conexão →
-  devolve `skipped` (NÃO `failed`), pois o caminho offline é o padrão seguro.
-- Em uma bridge acessível: coleta erros de rede via `getNetworkErrors("/")`
-  e tenta capturar um preview de `/project1/out1`. Tolerante a sucessos
-  parciais: preview ausente ainda produz `ok` com `errorCount`.
-
-### Comandos
-
-```bash
-# Analisa um arquivo diretamente pela bridge de quarentena.
-# Exit 0 para ok/skipped; exit 1 só em falha real.
-tdmcp project-rag analyze /caminho/absoluto/para/component.tox
-tdmcp project-rag analyze ./algum.toe --json
-
-# Faz sync e roda o analisador de bridge em todo card com binário baixável.
-# Persiste analysisStatus em cada card; reruns pulam cards já ok.
-tdmcp project-rag sync --bridge
-tdmcp project-rag sync --bridge --json
-```
-
-`analysisStatus` é gravado no frontmatter YAML do card:
-
-```yaml
-analysisStatus: ok           # cozinhou limpo na quarentena
-analysisReason: "bridge offline at http://127.0.0.1:9981"  # set em skipped/failed
-```
-
-Esse campo é **excluído do contentHash** do card (tratado como metadado de
-persistência, como `binaryPath`) — re-sincronizar conteúdo inalterado
-continua sendo cache-hit mesmo após o analisador rodar.
-
-### Threat model — recap
-
-| Risco | Mitigação |
-|---|---|
-| Usuário roda `sync --bridge` e um `.tox` malicioso corrompe o show file | A bridge de quarentena roda em uma **instância de TD separada** em **porta separada** — o TD principal em 9980 nunca é alcançado |
-| Cook longo trava o agente | Timeout duro de 30s (configurável); para o analisador estático, group-kill no subprocesso; para a bridge, `Promise.race` com cap |
-| Subprocesso enxerga `TDMCP_BRIDGE_TOKEN` e vaza | Ambiente reduzido (`PATH`, `HOME`, `LANG` apenas) — nenhum `TDMCP_*` é encaminhado |
-| Bridge offline gera relatório "failed" ruidoso | Offline sempre degrada para `skipped`; `exit 0` em skip; o relatório registra quais cards não foram analisados |
-| Path traversal via nome de artefato manipulado | O analisador estático copia o arquivo com basename fixo (`input<ext>`) dentro de um cwd UUID — o path original nunca chega ao argv do subprocesso |
-
-## Regras de segurança
-
-- O caminho de busca nunca spawna Python nem fala com a bridge TD ativa.
-- O analyzer F3 usa um *novo* `TouchDesignerClient` na
-  `TDMCP_PROJECT_RAG_BRIDGE_PORT` (default 9981) e recusa fallback para o
-  client padrão 9980. tdmcp nunca spawna TD sozinho.
-- `.toe`/`.tox` baixados **NUNCA** são abertos no projeto ativo do usuário.
-- Matriz de licenças é enforçada antes de qualquer persistência de binário.
-
-Para o design completo veja `_workspace/01_design_project_rag.md`; para o
-roadmap faseado, `_workspace/01_plan_project_rag_implementation.md`.

package/mcps/tdmcp/docs/pt/guide/ai-controlled-party.md

@@ -1,218 +0,0 @@
----
-title: Festa Controlada por IA
-description: "Opere um ensaio seguro de festa assistida por IA com tdmcp e TouchDesigner: dashboard local, policy ShowIntent, aprovações, efeitos simulados, Telegram, Ollama e limites de TD."
----
-
-# Festa Controlada por IA
-
-AI-Controlled Party é um padrão de show mode para usar tdmcp e TouchDesigner
-como co-piloto de visuais ao vivo. A IA pode sugerir e selecionar cues
-aprovados, mudar clima visual, rascunhar anúncios e reagir a texto do operador
-ou do Telegram. O TouchDesigner continua sendo o runtime determinístico de
-palco, e o operador humano mantém autoridade final sobre efeitos perigosos.
-
-A implementação atual é uma **POC local de rehearsal**, não controle autônomo de
-show. Ela prova o loop de decisão, dashboard, trilha de auditoria, caminho
-opcional com LLM local, caminho opcional por Telegram e superfície visual
-opcional no TouchDesigner. Ela não prova hardware de venue.
-
-```text
-dashboard / Telegram / texto do operador
-  -> parser opcional com Ollama ou fallback determinístico
-  -> envelope ShowIntent
-  -> decisão de policy
-  -> permitir, enfileirar aprovação ou bloquear
-  -> simulação ou update no painel de controle do TouchDesigner
-  -> hardware real só depois de adaptador de venue e gates de aprovação separados
-```
-
-## O que existe agora
-
-| Superfície | Status | O que prova |
-| --- | --- | --- |
-| `tdmcp-agent show-director` | CLI de policy já entregue | Valida um `ShowIntent`, retorna `allow`, `require_approval` ou `block`, e atualiza JSON de aprovação/auditoria sem conectar ao TD ou a hardware. |
-| `tdmcp-agent ai-party-poc` | Runner offline para produtor | Roda o rehearsal de sete momentos com fan-in, decisões de policy, estado de aprovação, resumo de audit e efeitos apenas simulados. |
-| `npm run ai-party:dev` | POC local de rehearsal live | Sobe o backend Live Nervous System e o dashboard, normalmente em `http://127.0.0.1:8787/`. |
-| `npm run ai-party:dry` | Prova rápida | Roda a sequência determinística doors -> mood -> brand -> aprovação de fog -> aprovação -> áudio-reativo -> prova de segurança, sem serviço externo. |
-| `npm run ai-party:td-build` | Superfície visual opcional no TD | Cria `/project1/ai_party_poc` com painel de controle, cadeia visual TOP, tabela DMX simulada, placeholder DMX desabilitado e `preview_out`. |
-| `npm run ai-party:telegram` | Caminho local opcional por Telegram | Usa long polling da Bot API com chats em allowlist; responde no Telegram, mas todo pedido passa pela mesma policy. |
-| `tdmcp-agent ai-party` | Gateway Hermes/Telegram anterior | Faz dry-run de uma mensagem no formato Telegram/Hermes pela policy do Show Director. Continua policy-only e não cria contexto de TD. |
-
-O dashboard inclui entrada de comando, chips de exemplo, cue deck, fila de
-aprovação, estado live, status de preview do TouchDesigner, filtros do log de
-eventos e painel de segurança. O serviço local escreve eventos JSONL em
-`POC_EVENT_LOG_PATH` (`./data/ai-party-poc-events.jsonl` por padrão).
-
-## Rehearsal local recomendado
-
-Comece pela prova offline:
-
-```bash
-npm run ai-party:dry
-npm run ai-party:test
-```
-
-Depois rode o dashboard:
-
-```bash
-npm run ai-party:dev
-```
-
-Abra a URL impressa. Prompts úteis de teste:
-
-- `deixa a sala mais premium tropical`
-- `prepara fumaça curta no próximo drop`
-- `blackout total e strobo máximo e raw dmx`
-
-Comportamento esperado:
-
-- O primeiro prompt seleciona um cue ou mood visual seguro.
-- O pedido de fog cria um item de aprovação; aprová-lo ainda simula o efeito
-  físico, exceto se gates live e um adaptador real forem adicionados
-  deliberadamente.
-- O pedido de blackout / strobe máximo / raw DMX é bloqueado e registrado.
-
-## Ollama opcional
-
-Configure um modelo local só se quiser colocar o parser LLM no loop:
-
-```bash
-OLLAMA_BASE_URL=http://127.0.0.1:11434
-OLLAMA_MODEL=qwen2.5:3b
-npm run ai-party:dev
-```
-
-Nenhum modelo específico é obrigatório para a POC. Se o Ollama estiver
-indisponível ou `OLLAMA_MODEL` não estiver configurado, o dashboard mostra esse
-estado e usa parser determinístico de fallback para os comandos de demo.
-
-## Preview opcional no TouchDesigner
-
-Inicie o bridge do tdmcp e então construa a rede demo:
-
-```bash
-npm run ai-party:td-build
-```
-
-O builder cria ou substitui `/project1/ai_party_poc`. Todo operador criado
-recebe coordenadas explícitas `nodeX` / `nodeY`, então a rede fica legível em
-vez de empilhada. O endpoint de preview do dashboard mira:
-
-```text
-/project1/ai_party_poc/preview_out
-```
-
-Ações de cue e mood podem atualizar o painel de controle do TD quando o bridge
-estiver acessível. Efeitos físicos continuam representados por uma tabela DMX
-simulada e um placeholder de output desabilitado.
-
-## Bancada opcional com Telegram
-
-Use long polling do Telegram para rehearsal local:
-
-```bash
-TELEGRAM_BOT_TOKEN=... \
-TELEGRAM_ALLOWED_CHAT_IDS=123456789 \
-TELEGRAM_POLLING_ENABLED=true \
-npm run ai-party:telegram
-```
-
-Comandos suportados incluem `/status`, `/cues`, `/cue <cue_name>`,
-`/mood <text>`, `/fog <seconds> <intensity>`, `/approve <approval_id>`,
-`/reject <approval_id>`, `/panic` e `/demo`.
-
-Mantenha o Telegram em allowlist. Webhook é trabalho de deploy, não o caminho da
-POC local.
-
-## Modelo de segurança
-
-A LLM só interpreta texto em JSON `ShowIntent` estruturado. Ela nunca despacha
-DMX cru, Python cru, endpoints arbitrários, canais de fixture, comandos de
-mixer, ações de PA ou controle de laser / moving head.
-
-Intenções de baixo risco permitidas:
-
-- `announce`
-- `change_mood`
-- `request_cue` para cues visuais pré-aprovados
-- `log_note`
-- `panic_status`
-
-Exigem aprovação por padrão:
-
-- `fog`
-- `hazer`
-- `strobe` limitado
-
-Bloqueados ou operator-only por padrão:
-
-- `blackout`
-- `freeze`
-- `moving_head`
-- `laser`
-- `mixer_gain`
-- `pa_mute`
-- `audio_routing`
-- ganho de entrada, mute groups, patching, edições de channel strip e comandos
-  crus de adaptador
-
-A aprovação é checada duas vezes: quando o pedido entra na fila e de novo quando
-o operador aprova. O estado de cooldown em runtime faz parte da segunda checagem,
-então dois pedidos de fog enfileirados não conseguem disparar juntos se a
-primeira aprovação colocar o efeito dentro da janela de cooldown.
-
-`HARDWARE_ENABLED` e `DMX_LIVE_ENABLED` são gates de integração para adaptadores
-futuros. Não trate isso como driver DMX pronto para venue. A POC atual no TD usa
-`sim_dmx_table` e `dmx_out_disabled`, e fixtures reais ainda exigem adaptador
-separado, mapa de patch, caminho de emergency stop, validação de bancada e
-rehearsal no venue.
-
-## Estudo de armamento de cena do mixer
-
-A extensão desenhada para Soundcraft Ui24R continua **planejada**, não execução
-live:
-
-- A intenção proposta é `arm_mixer_scene`, separada dos efeitos perigosos
-  `mixer_gain`, `pa_mute` e `audio_routing`.
-- A IA pode preparar um alvo específico de show, snapshot ou cue da Ui24R.
-- A policy do MVP sempre deve exigir aprovação humana antes de qualquer
-  adaptador disparar a ação.
-- A primeira fatia de implementação deve ser apenas contrato + adaptador
-  dry-run.
-- Bitfocus Companion continua sendo o primeiro backend live recomendado depois
-  de validação isolada em bancada; um bridge Node direto fica adiado até o
-  protocolo da Ui24R ser provado no firmware alvo.
-
-A spec durável está em
-[AI Party Ui24R Scene-Arming Design](../../superpowers/specs/2026-06-04-ai-party-ui24r-scene-arming-design.md).
-
-O achado de segurança mais importante: um show/snapshot/cue da Ui24R pode
-esconder mudanças amplas de estado do mixer. Uma cena do mixer só pode ser
-armada pela IA se um catálogo/manifesto confiável do venue provar que ela exclui
-mudanças de ganho, PA mute, roteamento, patching, channel strip, mute group e
-phantom power. Caso contrário, ela continua operator-only/manual.
-
-## Plano de validação
-
-Use a POC como harness. Cada passagem deve provar uma fronteira antes de confiar
-na próxima:
-
-| Etapa | O que provar | Sinal de aprovação |
-| --- | --- | --- |
-| Policy offline | Texto e eventos roteirizados viram `ShowIntent`s válidos. | `npm run ai-party:dry` e `npm run ai-party:test` passam; caminhos permitido, enfileirado e bloqueado aparecem. |
-| Rehearsal no dashboard | O operador consegue ver cue atual, aprovações pendentes, motivos de policy, estado de panic e audit events. | `npm run ai-party:dev` serve o dashboard, aprovações podem ser aprovadas/rejeitadas, e pedidos bloqueados continuam bloqueados. |
-| Preview no TouchDesigner | TD consegue hospedar a POC visual sem depender de hardware de dispositivo. | `npm run ai-party:td-build` cria `/project1/ai_party_poc`; `/api/td/preview` consegue ler `preview_out` quando o bridge está disponível. |
-| Bancada com Telegram | Um bot consegue receber mensagens de operador permitidas e enviar respostas de status. | Long polling processa apenas chats em allowlist e mapeia `/cue`, `/mood`, `/fog`, `/approve`, `/reject` e `/panic` pela policy. |
-| Hardware de venue | Cada fixture, output e efeito tem estado seguro antes de controle ao vivo. | Ainda pendente: fixture patching, adaptadores reais de DMX/fog/strobe/hazer/PA, emergency stop, cooldowns e rehearsal de operador precisam ser específicos por venue. |
-
-Repita as etapas de policy offline e dashboard sempre que a policy mudar. Repita
-as etapas de hardware para cada venue.
-
-## Ainda não validado ao vivo
-
-STT real, integração OpenClaw, webhooks de Telegram em deploy, fixture patching,
-saída DMX, hardware de fog/hazer, strobe, moving heads, lasers, PA, recall de
-cena da Soundcraft Ui24R, emergency stop de venue e rehearsal de operador sob
-pressão de show exigem validação específica por venue. Não trate a POC local, o
-planner dry-run ou o contrato planejado de cena do mixer como controlador de
-hardware.