engine-kit 0.0.0-stage → 0.2.0

package/CONTRATO-MOTOR.md

@@ -0,0 +1,194 @@
+# Contrato de um motor no `engine-registry`
+
+O que o repositório de **cada motor** precisa fazer para entrar aqui — e ser instalado com
+integridade e autenticidade pelo `engine-kit`. Este documento é o insumo das sessões de
+alinhamento: uma sessão por motor, seguindo este checklist.
+
+> **Regra da casa:** o `engine-registry` (público) é o **canônico de consumo** — é o único que o
+> `manifest.json` aponta e o único cuja falha de publicação aborta o release. O repositório
+> privado do motor guarda **fonte, CI e histórico**, e pode receber um espelho da release. Dois
+> canônicos seriam duas verdades, e a divergência apareceria para o usuário como *"atualizei e
+> voltou a versão velha"*.
+
+---
+
+## 1. Uma vez por motor: a chave
+
+```sh
+node kit/gen-key.mjs <motor>
+```
+
+- grava a privada em `~/.engine-signing/<motor>_ed25519_private.key` (**nunca** versionar, **nunca**
+  subir para CI);
+- imprime a **pública** para colar no `manifest.json`, em `install.publicKey`;
+- recusa sobrescrever uma chave existente: trocá-la invalidaria todas as releases já assinadas
+  daquele motor nos consumidores que já a pinaram.
+
+**Uma chave por motor.** Um vazamento obriga a republicar aquele motor, não a casa inteira.
+
+## 2. O artefato
+
+O motor builda o próprio artefato — o `publish-base.ps1` **não** builda nada. Um wheel Python, um
+bundle esbuild e um `.tgz` multi-plataforma não têm nada em comum: "parametrizar" o build seria
+reescrever cada build dentro do script.
+
+Requisitos do artefato:
+
+- **self-contained**: sobe numa máquina limpa, sem depender do consumidor (traz o próprio
+  `node_modules` trimado, ou o runtime que precisar);
+- o conteúdo vai na **raiz** do `.tgz` (o kit renomeia o staging inteiro para `<home>/<extractTo>`);
+- traz um `package.json` com o **mesmo `version`** que vai para o `manifest.json`.
+
+> **Armadilha real:** o `provision` compara a versão do `package.json` **de dentro** do artefato
+> com o pin do registry. Se o manifest disser `0.1.1` e o artefato disser `0.1.0`, o pin nunca é
+> satisfeito e a máquina **reinstala o motor em toda chamada**. Bump de versão exige rebuild.
+
+> **Armadilha do tar no Windows:** num terminal Git Bash, o GNU tar do Git vem antes no `PATH` e
+> lê `C:\...` como host remoto (`Cannot connect to C: resolve failed`). Empacote com o tar nativo
+> (`C:\Windows\System32\tar.exe`, bsdtar), chamando-o pelo caminho absoluto ou pondo `System32`
+> antes no `PATH`. Na extração o kit já faz isso sozinho (`kit/provision.mjs`).
+
+## 3. Publicar
+
+```sh
+pwsh kit/publish-base.ps1 -Engine <motor> -Version <x.y.z> -Asset <artefato.tgz> -DryRun
+pwsh kit/publish-base.ps1 -Engine <motor> -Version <x.y.z> -Asset <artefato.tgz> `
+     -SourceRepo AllanSantos-DV/<repo-privado>
+```
+
+O script faz, em ordem e com *fail-loud* em cada passo:
+
+1. **zera `GH_TOKEN`/`GITHUB_TOKEN`/`GIT_CONFIG_PARAMETERS`** e confere `gh api user` contra o dono
+   do registry — o app Copilot injeta o token de uma conta de trabalho em todo processo filho, e
+   sem isso o `gh` publica pela conta errada;
+2. assina cada artefato e **prova a assinatura na hora** (valida o legítimo, recusa o adulterado);
+3. cria a release no registry (recusa se a tag já existir — artefato assinado não se sobrescreve);
+4. espelha no repo privado, se `-SourceRepo` (falha aqui **avisa**, não aborta: não é o canônico);
+5. atualiza o `manifest.json` **parseado** (nunca regex em JSON);
+6. **prova o caminho real**: baixa a release publicada e valida `sha256` + assinatura como um
+   consumidor faria. *"Publiquei"* não é prova — asset faltando, `.sig` esquecido e tag errada só
+   aparecem quando alguém tenta instalar, em produção.
+
+Depois: commitar e enviar o `manifest.json`. **Consumidores só enxergam a mudança após o push** —
+até lá o registry publicado continua descrevendo a versão anterior.
+
+## 4. Onde o motor instala — e como o consumidor ACHA
+
+Esta seção existe porque a ausência dela custou caro: um consumidor escreveu o caminho do
+executável **de cabeça**, errou por um segmento, e o mesmo palpite foi copiado para três
+conectores em duas linguagens. O motor ficava "não instalado" com o binário no disco, e o
+consumidor entrava em laço de reinstalação que nunca resolvia.
+
+**Layout de instalação (Windows, por-usuário):**
+
+```
+%LOCALAPPDATA%\<motor>\           ← raiz  (a ÚNICA parte que o consumidor pode assumir)
+    venv\Scripts\<motor>.exe      ← o CLI              ⚠ tem 'venv'
+    venv\Scripts\python.exe       ← o interpretador do motor
+    logs\daemon.log
+    run\daemon-<hash>.pid
+    cli.json                      ← o PONTEIRO publicado pelo motor
+```
+
+**Como o consumidor acha o CLI — nesta ordem:**
+
+1. variável de ambiente de override (`<MOTOR>_CLI`), se existir e apontar para arquivo real;
+2. **`<raiz>/cli.json`** — o motor grava ali o caminho do próprio executável, derivado do
+   `sys.executable` do venv dele. Não é palpite: é o motor declarando onde está;
+3. só então o layout acima, como plano B para o **primeiro contato** (antes de o motor ter
+   rodado alguma vez, o ponteiro ainda não existe);
+4. `PATH` por último — e sabendo que normalmente **não resolve**: ninguém ativa o venv do motor.
+   Procurar no `PATH` primeiro ainda arrisca pegar um binário homônimo de outro projeto.
+
+**Regras para quem escreve um consumidor:**
+
+- **Não escreva o caminho de memória.** A resposta está no código do motor
+  (`bootstrap.daemon_paths()`, `sdk/python/vox_lifecycle.py`) e no `cli.json`. Se você está
+  digitando `Scripts` sem olhar, você está adivinhando.
+- **Não duplique a descoberta em N conectores.** Cada cópia é um lugar a mais para o palpite
+  errado sobrar quando o layout mudar. Um erro copiado três vezes leva três releases para sair.
+- **Ausência do motor é ESTADO, não exceção**: devolva "não instalado" e deixe o bootstrap
+  decidir. Levantar aqui transforma primeiro-uso em erro.
+
+**Regra para quem publica o motor:** o motor **declara** onde se instalou (escreve o
+`cli.json` no arranque do daemon e em qualquer invocação do CLI, com escrita atômica). Publicar
+um ponteiro para arquivo inexistente é pior que não publicar — o consumidor confiaria nele.
+
+## 5. Disciplina de release
+
+Release não é ferramenta de depuração. Publicar para "ver se agora vai" gasta número de versão,
+polui o histórico e obriga todo consumidor a decidir se atualiza — para descobrir o bug seguinte.
+
+- **Reproduza o defeito localmente antes de versionar.** Se você não sabe qual linha falha, não
+  há o que publicar.
+- **Valide pelo caminho REAL do consumidor**, não pela peça isolada. Testar `find_vox()` sozinho
+  não prova que o worker sobe; foi assim que três releases seguidas saíram sem resolver.
+- **Uma release deve carregar a correção E o teste que a trava.** Sem o teste, o mesmo erro
+  volta em silêncio na próxima refatoração.
+- Sinal de alerta: duas releases do mesmo motor no mesmo dia com poucos minutos de intervalo.
+  Isso não é entrega incremental, é depuração em produção.
+
+## 6. Checklist por motor
+
+```
+[ ] chave gerada em ~/.engine-signing/<motor>_ed25519_private.key
+[ ] entrada do motor existe no manifest.json (kind, home, install.entry, platforms)
+[ ] build produz artefato self-contained, com package.json na versão certa
+[ ] publish-base.ps1 rodado em -DryRun sem erro
+[ ] release publicada no engine-registry com .tgz + .sig + .sha256
+[ ] manifest.json com publicKey, signatureAlgorithm, signatureRequired:true, repo=engine-registry
+[ ] node kit/verify-release.mjs <motor>  → verde
+[ ] node tests/e2e-install.mjs --local          → instala e sobe num HOME isolado
+[ ] o motor PUBLICA o ponteiro do CLI (<raiz>/cli.json) no arranque — nada de o consumidor adivinhar
+[ ] nenhum consumidor tem caminho de instalação escrito à mão (grep por "Scripts" nos conectores)
+[ ] o defeito foi reproduzido pelo caminho REAL do consumidor, não só na peça isolada
+[ ] a correção vai junto com o teste que a trava
+[ ] consumidores apontados para o engine-registry (o repo antigo deixou de ser consultado)
+[ ] grep nos repos dos consumidores pela URL antiga retorna ZERO   ← critério de remoção da ponte
+[ ] só então: release antiga marcada como deprecated / removida
+```
+
+## 7. Estado da migração
+
+| Motor | `kind` | Fonte (privado) | Release canônica | Assinado | Ponte no canal antigo |
+|---|---|---|---|---|---|
+| `mcp-gateway` | daemon | `mcp-bridge` (branch `feat/mcp-gateway`) | `engine-registry` ✅ | ✅ | — (nunca esteve lá) |
+| `embed-house` | daemon | `embed-house` | `engine-registry` ✅ | ✅ | `copilot-marketplace` |
+| `neural-link` | **cli** | `neural-link` | `engine-registry` ✅ | ✅ | `neural-link-runtime` (redirecionado) |
+| `vox-engine` | daemon (`pipe`), **self-managed** | `vox-engine` | `engine-registry` ✅ | ✅ | `copilot-marketplace` |
+
+Cada repo de motor tem o próprio `publish.ps1`, que **builda** o que é específico dele e **delega**
+ao `kit/publish-base.ps1` a parte comum (identidade do `gh`, assinatura, release, manifest, prova).
+
+### Consumidores repontados
+
+| Consumidor | Motor | O que mudou |
+|---|---|---|
+| `modo-auto` + espelho no marketplace | embed-house | `provision.mjs` → registry |
+| `copilot-voice` | vox-engine | `tools/sdk-drift.ps1` baixa o canônico do registry — **gate verde, provado nesta máquina** |
+| `Action`, `cerne` | vox-engine | `vox_sdk.py` vendorizado → registry |
+
+### O que ficou de propósito
+
+- **`copilot-voice` / `voice-chat`: o SDK vendorizado NÃO foi tocado.** Essas cópias são
+  **byte-idênticas** ao canônico publicado (é o que o gate anti-drift verifica). Editá-las agora
+  criaria drift contra o canônico atual e **quebraria o publish desses consumidores** — por 404 do
+  gate, não por bug. Elas migram sozinhas na próxima release do vox, quando os flats publicados já
+  carregarem a URL nova. Enquanto isso, continuam achando a release pela ponte.
+- **Cópias em worktrees de feature** (`hermes-agent-*`, `cerne-feat-*`): são branches de trabalho,
+  não distribuição. Migram no merge.
+- **Escopo por projeto no dispatcher**: o campo `project` já é aceito, validado e propagado; o
+  **filtro** por escopo é o próximo passo. A ordem é essa de propósito — ligar o filtro antes de
+  alguém mandar o campo silenciaria todos os handlers de uma vez.
+- **Skill Manager provisionando pelo kit**: hoje ele embute e faz o deploy do runtime. É extensão
+  em produção; a troca entra junto com o ciclo do escopo.
+
+### Sobre remover as releases do `copilot-marketplace`
+
+**Não apague antes do critério bater.** O critério é binário:
+
+> um `grep` nos repositórios dos consumidores pela URL antiga daquele motor retorna **zero**.
+
+Hoje ainda retorna para `copilot-voice`/`voice-chat` (SDK vendorizado byte-idêntico ao canônico
+publicado). Enquanto não zerar, a ponte fica — com aviso de depreciação no corpo da release.
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Allan Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,306 @@
-# Temporary Holding Version
+# engine-registry
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vitrine de **MOTORES** compartilhados e, em uma seção separada, de aplicativos
+distribuídos. O `engine-kit` continua lendo somente `manifest.engines`.
+
+Um motor **não é um plugin**: não se instala pela vitrine de extensões, não tem `hooks` nem
+`extensions`. Ele é **infraestrutura**: instala **uma vez por máquina** em `~/.<motor>` e serve
+**N consumidores** (Copilot, Claude Code, Cursor, VS Code, scripts…), sem depender do host.
+
+```
+extensões/plugins  ──declaram──►  engine-kit  ──resolve──►  engine-registry
+   (voice-chat,                  (esta lib)     provision      (manifest.json)
+    modo-auto,                                  lifecycle           │
+    mcp-bridge…)                                    │               ▼
+                                                    └──────►  ~/.<motor>  (1 por máquina)
+```
+
+## Por que existe
+
+Antes, cada plugin carregava seu próprio `boot.mjs` com a lógica de "achar ou baixar o motor" —
+o mesmo código copiado em cada consumidor. Um motor novo obrigava a repetir tudo. Aqui a lógica
+vive num lugar só e o consumidor apenas **declara a dependência**.
+
+## Motores registrados
+
+| Motor | Versão | Tipo | O que faz |
+|---|---|---|---|
+| `embed-house` | 1.0.5 | `daemon` (http) | Casa de embeddings (MiniLM-L6-v2, 384-dim): carrega o modelo uma vez e serve vetores a N consumidores. |
+| `vox-engine` | 0.28.7 | `daemon` (pipe), **self-managed** | Motor de voz (STT/TTS) compartilhado, com auto-unload quando ocioso. Traz o próprio instalador e updater. |
+| `mcp-gateway` | 0.15.0 | `daemon` (http) | Agregador MCP: conecta uma vez em cada servidor MCP e reexpõe tudo num endpoint único. |
+| `neural-link` | 0.7.15 | `cli` | Dispatcher adaptativo de hooks: recebe o evento por stdin, pontua os handlers e devolve uma decisão composta. |
+| `vxk` | 0.18.0 | `cli` | Explicações visuais animadas e narradas como servidor MCP (stdio): devolve UM HTML autocontido e offline. A narração vem do `vox-engine`. |
+| `cerne` | 0.4.10 | `daemon`, **self-managed** | Leitura ativa de vídeo (captura, quadros, transcrição, tradução) exposta via MCP. Instalador Inno por usuário, Windows. |
+
+**Todos** são publicados aqui, assinados com Ed25519 e verificados antes de instalar.
+
+Um motor pode ser de dois tipos (`kind`):
+
+- **`daemon`** — processo longo que anuncia `runtime.json` e responde a um `healthCheck`. O kit
+  sobe e espera o auto-anúncio.
+- **`cli`** — executável invocado **por evento** (ex.: um dispatcher de hooks). Não há processo
+  para manter vivo: provisionar já é entregar. O `lifecycle` devolve o caminho do binário sem
+  spawn, sem health e sem runtime — forçar um daemon aqui seria inventar um ciclo de vida que o
+  motor não tem.
+
+E pode declarar `status: "self-managed"`: o motor traz o **próprio instalador/updater** (o caso do
+`vox-engine`, um app Python). A entrada aqui é o **descritor de registro** — onde está a release,
+qual a chave, qual a versão — e o `provision` recusa com razão explícita em vez de tentar extrair
+um instalador como se fosse um tarball.
+
+## Instalar um motor com um comando
+
+Sem clonar o repositório, com Node 18 ou mais:
+
+```sh
+npx engine-kit ensure vxk                     # instala ou atualiza; reusa se já estiver em dia
+npx engine-kit ensure vxk --version 0.18.0    # pin de versão
+```
+
+O `npx` baixa o kit do npm e o kit baixa o motor da release, confere o **sha256**, a **assinatura Ed25519**
+e a **versão** do artefato; qualquer divergência aborta sem instalar nada. A chave pública do primeiro contato
+vem do `manifest.json` que viaja **dentro do pacote** (publicado no npm por publicação confiável, com
+proveniência): se o registry servir outra chave, é ABORT já na primeira instalação. Motor que o pacote não
+conhece é recusado (`npx engine-kit@latest ensure <motor>` traz o kit novo). Motores `self-managed`
+(`vox-engine`, `cerne`) seguem pelo próprio instalador.
+
+Atualização automática, ligada por padrão: o kit consulta a última versão no npm e, se houver uma nova, roda o
+mesmo comando nela (o `npx` sem versão reusaria a da cache); o motor instalado é atualizado para a versão do
+registry, com o aviso `motor atualizado: <motor> vA → vB`. `ENGINE_KIT_NO_AUTO_UPDATE=1` desliga as duas trocas e
+deixa só o aviso de versão nova disponível. `--version` explícito sempre vale.
+
+Publicar o kit: tag `engine-kit-v<versão do package.json>` criada na `main`; o workflow `.github/workflows/publish.yml`
+roda a suíte e publica por OIDC (sem token guardado). Conferir a proveniência: `npm audit signatures` num projeto
+que dependa do `engine-kit`, ou o selo "Provenance" na página do pacote.
+
+## Conciliar a máquina
+
+```sh
+node kit/doctor.mjs          # diagnostica: o que reusar, atualizar ou baixar
+node kit/doctor.mjs --fix    # aplica
+```
+
+Desatualizado → atualiza. Ausente → baixa. **Atualizado → reusa** — e o diagnóstico não baixa nada,
+porque reusar é o caminho comum e precisa ser barato. Antes de trocar um daemon vivo, o doctor pede
+o `shutdownPath` que o registry declara: no Windows, arquivo em uso não pode ser sobrescrito.
+
+## Como consumir
+
+```js
+import { ensureEngine } from "engine-kit";
+
+const r = await ensureEngine("embed-house", {
+  // O kit NUNCA adivinha a saúde do motor: quem conhece o protocolo é o consumidor.
+  healthCheck: async (rt) => {
+    const res = await fetch(`http://127.0.0.1:${rt.port}/health`, { signal: AbortSignal.timeout(2000) });
+    if (!res.ok) return null;
+    const h = await res.json();
+    return h.dim === 384 ? h : null;   // handshake: dimensão/modelo compatíveis
+  },
+});
+
+if (!r.available) {
+  // Degrade SINALIZADO — nunca silencioso.
+  log(`embed-house indisponível: ${r.reason}`);
+} else {
+  usar(r.runtime.port);
+}
+```
+
+Declare a dependência no manifesto do seu plugin:
+
+```jsonc
+{
+  "name": "meu-plugin",
+  "engines": { "embed-house": ">=1.0.0" }
+}
+```
+
+### Adaptadores prontos
+
+Cada motor tem um adaptador em `consumers/` que já sabe o handshake dele — o consumidor não
+precisa escrever `healthCheck` nem descobrir onde mora o token:
+
+```js
+import { ensureGateway } from "engine-registry/consumers/mcp-gateway.mjs";
+
+const gw = await ensureGateway({ log });
+if (!gw.available) { log(`gateway indisponível: ${gw.reason}`); return; }  // degrade SINALIZADO
+
+// gw.url    -> http://127.0.0.1:7337/mcp
+// gw.token  -> bearer (lido do cofre com ACL do dono)
+// gw.backends -> ["files", "memory", ...]
+```
+
+## Garantias do kit
+
+- **Integridade fail-closed** — o sidecar `.sha256` é obrigatório; ausente, malformado ou
+  divergente = **aborta sem instalar**.
+- **Autenticidade fail-closed** — quando o registry declara `install.publicKey`, o artefato só é
+  extraído se a **assinatura Ed25519** conferir. Isso cobre o que o SHA256 **não** cobre: quem
+  troca o artefato no release **regenera o `.sha256` junto** e passaria pela integridade. A
+  assinatura amarra o artefato a quem detém a chave privada — que nunca sai da máquina do dono.
+- **Um provisionamento por vez** — lock atômico (`wx`): consumidores concorrentes não brigam;
+  os demais esperam o vencedor.
+- **Reúso por semver same-major `>=`** — dois consumidores com pins diferentes convergem no maior,
+  sem loop de download. Major diferente = incompatível (o protocolo é atado ao major).
+- **Troca atômica** — download em `.part` → rename; extração em staging → swap. No Windows, o
+  gancho `onBeforeReplace` derruba o daemon antes (arquivo em uso não pode ser sobrescrito).
+- **Nunca lança** — toda falha vira `{ ok:false, reason }` / `{ available:false, reason }`. Quem
+  decide como degradar é o consumidor.
+- **Singleton do motor** — a corrida é resolvida **dentro** do motor (port-lock/bind); o kit só
+  sobe e espera o auto-anúncio.
+
+## Assinatura dos motores
+
+Contrato **`ed25519-sha256-raw`** (o mesmo que o `vox-engine` já pratica em produção — a migração
+dele não exige reassinar nada):
+
+- assina-se o **SHA-256** do artefato (*hash-then-sign*), não o artefato direto;
+- o `.sig` é a assinatura Ed25519 **crua: 64 bytes binários**, nunca base64;
+- a chave **pública** (32 bytes hex) é **pinada** no `manifest.json`, em `install.publicKey`;
+- a chave **privada** fica em `~/.engine-signing/<motor>_ed25519_private.key` e **nunca entra em
+  CI** — é isso que impede um CI comprometido de forjar um release.
+
+**Uma chave por motor**, não uma chave do publisher: um vazamento obriga a republicar aquele
+motor, não a casa inteira.
+
+Política do `provision`, sem meio-termo silencioso:
+
+| Situação no registry | O que acontece |
+|---|---|
+| `publicKey` declarada | assinatura **obrigatória**; inválida/ausente = ABORT |
+| `signatureRequired: true` sem `publicKey` | manifesto **inconsistente** = ABORT |
+| `signatureAlgorithm` desconhecido | ABORT (nunca aceite silencioso) |
+| nem chave nem exigência (motor ainda não migrado) | instala, mas o log **sinaliza** que a autenticidade não foi verificada |
+
+### Raiz de confiança — por que a chave no manifest não bastava
+
+A `publicKey` vinha do **mesmo `manifest.json`** que o kit baixa. Quem controla o repositório troca
+o artefato, o `.sig` **e** a chave — e o fail-closed aprova os três, porque todos vêm da mesma
+origem. É uma tranca com a chave pendurada na porta. Uma review corroborada apontou; está fechado
+assim:
+
+| Camada | Como funciona | Fecha o quê |
+|---|---|---|
+| **TOFU** (padrão, automático) | a chave do 1º contato é gravada em `~/.engine-kit/trust.json`; qualquer troca depois = **ABORT** | repo comprometido **depois** da adoção — o caso realista |
+| **Pin do consumidor** | `ensureEngine(nome, { trustedKeys: { "<motor>": "<hex>" } })`; divergência = **ABORT** já no 1º contato | não depende do registry em momento nenhum (padrão do `vox-engine`) |
+| **Chave no pacote** (`npx engine-kit ensure`) | o comando fixa a chave do `manifest.json` embarcado no pacote do npm | registry comprometido **antes** do 1º contato: trocar a chave exige publicar um engine-kit novo, e a publicação deixa proveniência pública |
+
+Rotação legítima é **ato explícito**: apagar a entrada em `~/.engine-kit/trust.json`.
+
+**O que isto NÃO cobre, dito na cara:** comprometimento **anterior** ao primeiro contato (o TOFU
+grava a chave do atacante), downgrade/replay e expiração. Fechar isso exige transparência pública
+(**Sigstore/cosign**, **TUF**, *npm provenance*) — decisão de produto do dono, registrada e não
+esquecida. Para 4 motores de um autor só, TOFU + pin cobre o vetor realista a custo operacional
+zero; log de transparência cobre o resto a um custo bem maior.
+
+## Estrutura
+
+```
+manifest.json    # o registry: descritor de cada motor (release, asset, entry, runtime, chave)
+schema.json      # contrato do manifest (JSON Schema)
+kit/
+  index.mjs        # ensureEngine = resolve → provision → lifecycle
+  resolve.mjs      # descobre o motor no registry (cache 6h, degrada p/ cache obsoleto)
+  provision.mjs    # baixa/atualiza: SHA256 + assinatura fail-closed, lock e swap atômico
+  lifecycle.mjs    # garante o processo vivo (daemon) ou entrega o binário (cli)
+  cli.mjs          # comando `engine-kit` (bin do pacote): `npx engine-kit ensure <motor>`
+  ensure.mjs       # ensure: resolve → provision com a chave do manifest embarcado no pacote
+  update.mjs       # o kit se atualiza (relança na última versão do npm); ENGINE_KIT_NO_AUTO_UPDATE=1 desliga
+  signature.mjs    # contrato ed25519-sha256-raw — assinar e verificar na MESMA fonte
+  keystore.mjs     # onde moram as chaves privadas (~/.engine-signing)
+  gen-key.mjs      # gera o par de UM motor (com auto-prova)
+  sign.mjs         # assina um artefato e prova a assinatura na hora
+  update-manifest.mjs # patch do manifest parseado (nunca regex em JSON); --app para apps
+  verify-release.mjs  # baixa a release publicada e prova o caminho do consumidor; --app para apps
+  app-release.mjs     # URLs e verificação de TODOS os assets de um app (manifest.apps)
+  publish-base.ps1    # publicação de motor: identidade do gh → assina → release → manifest → prova
+consumers/
+  mcp-gateway.mjs  # adaptador pronto: handshake + token + shutdown do agregador MCP
+site/               # vitrine de produto dos motores (estática); processo em docs/PAGES.md
+tools/              # pages-branch.mjs: publica site/ na gh-pages
+tests/
+  smoke.mjs          # contratos do kit: node tests/smoke.mjs
+  test-*.mjs         # contratos hermeticos (assinatura, trust, tar, apps, cache, doctor, gateway)
+  e2e-*.mjs          # instalacao real de um motor do zero: node tests/e2e-install.mjs
+```
+
+## Verificar
+
+```sh
+node tests/smoke.mjs                     # contratos, offline
+node tests/smoke.mjs --network           # resolvendo do registry remoto
+node tests/test-signature.mjs            # contrato de assinatura (hermético)
+node tests/test-signature.mjs --network  # + interop com uma release REAL do vox-engine
+node tests/test-apps.mjs                 # catálogo de apps (hermético)
+node tests/e2e-install.mjs               # baixa e sobe o mcp-gateway num HOME isolado (prova real)
+node tests/e2e-install.mjs --local       # idem, mas usando o manifest.json que você vai publicar
+```
+
+## Publicar um motor
+
+Veja o passo a passo completo em [`CONTRATO-MOTOR.md`](./CONTRATO-MOTOR.md). Em resumo:
+
+```sh
+node kit/gen-key.mjs <motor>          # uma vez por motor: gera a chave e imprime a pública
+# ... o motor builda o próprio artefato ...
+pwsh kit/publish-base.ps1 -Engine <motor> -Version <x.y.z> -Asset <artefato.tgz> -DryRun
+pwsh kit/publish-base.ps1 -Engine <motor> -Version <x.y.z> -Asset <artefato.tgz>
+```
+
+O `publish-base.ps1` confere a identidade do `gh` (o app Copilot injeta o token de uma conta de
+trabalho nos processos filhos e o `gh` publica pela conta errada), assina, publica no registry,
+atualiza o `manifest.json` **parseado** e então **prova**: baixa a release publicada e valida
+`sha256` + assinatura pelo caminho de um consumidor.
+
+O artefato deve ser **self-contained** (traz o próprio `node_modules` trimado): o motor precisa
+subir numa máquina limpa, sem depender do consumidor.
+
+## Aplicativos
+
+`manifest.apps` é o catálogo de **aplicativos distribuídos**: produtos que o usuário baixa e
+instala, com instalador, interface e atualização próprios. O `engine-kit` **não** os provisiona —
+`resolve`/`provision` leem só `manifest.engines`. A entrada declara versão, tag e os assets por
+plataforma, e a release mora aqui, no registry público, com download **sem login**.
+
+| App | Versão | Plataformas | O que faz |
+|---|---|---|---|
+| — | — | — | Nenhum app registrado ainda. |
+
+Um app só entra nesta tabela e em `manifest.apps` **depois** de a release pública existir e passar
+em `node kit/verify-release.mjs --app <nome>` (download anônimo de todos os assets, `.sha256` e
+`.sig`). Aplicativo integrador (como o WhatsApp Bridge, tag `whatsapp-bridge-vX.Y.Z`) vai em
+`apps`; motor compartilhado com GUI e instalador próprios (como o Cerne) vai em `engines` com
+`status: "self-managed"`.
+
+### Contrato da entrada
+
+- `release.assets[].name` aceita `{version}`; `checksum` e `signature` aceitam `{asset}` e
+  `{version}`. Nome literal, sem placeholder, também vale. Prefira templates
+  (`whatsapp-bridge-setup-{version}-win32-x64.exe`, `{asset}.sha256`): uma versão nova muda só
+  `version`, sem reescrever os assets.
+- `signature` ausente = `{asset}.sig`. Com `release.publicKey` declarada, **todo** asset precisa
+  de `.sig` válido; `signatureRequired: true` sem `publicKey` é recusado.
+- O schema é estrito: campo desconhecido na entrada, na release ou num asset é recusado.
+- Uma chave por produto, como nos motores: `node kit/gen-key.mjs <app>` (a privada fica em
+  `~/.engine-signing/<app>_ed25519_private.key` e nunca entra em CI).
+
+### Publicar um app
+
+O `publish-base.ps1` é dos motores (um `.tgz`, notas que falam do `engine-kit`). Um app publica
+com **o próprio script**, que builda, assina cada asset com `node kit/sign.mjs <asset> --engine
+<app>` e cria a release `<app>-vX.Y.Z` neste repositório. Do kit, o app usa só a parte do
+manifest e a prova:
+
+```sh
+# 1ª vez: registre a entrada à mão em manifest.apps (o script ATUALIZA, não inventa descritor)
+node kit/update-manifest.mjs --app <app> --version <x.y.z> --public-key <hex> \
+     [--asset "<template>=<plataforma>" ...]
+node kit/verify-release.mjs --app <app>   # baixa todos os assets sem login e confere
+```
+
+
+## Licença
+
+MIT