@nio-cli/cli 0.10.0 → 0.11.0

package/README.md

@@ -1,339 +1,339 @@
-# NIO-CLI
-
-**Orquestrador de ambientes de desenvolvimento.** Você escolhe um perfil,
-responde um wizard, e a CLI — com auxílio de IA via MCP — materializa o ambiente:
-toolchains, linguagens, frameworks, dotfiles, aliases e IDE. A entidade central é
-a **Sessão**: um ambiente isolado, com UUID, persistido no Postgres.
-
-> **Guia rápido de uso:** `nio --help` (primeiros passos + como usar a interface do `nio ai`).
-> **Manual completo:** `nio docs` no terminal · `nio docs --html --open` como página.
-
----
-
-## Como funciona
-
-```
-você → nio (CLI) ──► nio-gateway ──► Postgres        (login: senha + JWT, 2º fator opcional)
-          │
-          ├──► SessionManager / EnvironmentBuilder    (materializa toolchains, MCPs, dotfiles)
-          │
-          └──► opencode.json  ──►  OpenCode (operador de IA)
-                                     └── MCP `nio` (tools nio_*)  ──► SessionManager ──► Postgres
-```
-
-1. **Você se autentica** (`nio register` / `nio login`). O `nio-gateway` — um
-   serviço HTTP loopback — verifica a senha (argon2id), dispara o 2º fator se
-   estiver ativo, e devolve um **JWT** salvo em `~/.nio/session.json`.
-2. **Você monta uma sessão** (`nio init`). O wizard pergunta perfil + recipe, e o
-   `EnvironmentBuilder` garante os toolchains, resolve os MCPs e grava o `config`
-   materializado na linha `sessions` do Postgres. A sessão é isolada, tem UUID e
-   pode ser reativada depois (`nio sessions`).
-3. **`nio ai` abre a interface NIO** — o `opencode serve` headless
-   (`opencode/big-pickle`, MCP `nio` + MCPs do perfil) e o chat do NIO em Ink
-   (fluxo em linha estilo Claude Code, paleta `/`, `Tab` troca de modo). O
-   Headroom foi desativado ([ADR 0010](docs/adr/0010-headroom-desativado.md)) — o
-   client fala direto no LLM, **não precisa de Docker**. Com IDE, roda num
-   terminal integrado dela. A partir daí o agente tem as tools `nio_*` —
-   criar/ativar sessão, re-materializar ambiente, delegar execução. Detalhe de
-   uso: **[Interface do `nio ai`](#interface-do-nio-ai-tui)**.
-
-O **Postgres é a fonte da verdade** do domínio (usuários, sessões, trilha de
-auth). A CLI e o gateway só falam com o banco que **você** configurar — não há
-default, não há banco embutido.
-
----
-
-## Instalação
-
-Precisa de **Node.js 20.12+**. Instala como pacote global:
-
-```bash
-npm i -g @nio-cli/cli
-```
-
-Ficam no PATH: `nio` (CLI), `nio-gateway` (serviço de auth), `nio-cli` e
-`nio-lang` (servidores MCP).
-
-### Pré-requisitos de runtime
-
-| Requisito | Pra quê | Como |
-|---|---|---|
-| **PostgreSQL** alcançável | fonte da verdade (sessões, usuários) | schema em `db/schema.sql` aplicado uma vez |
-| **`JWT_SECRET`** (segredo do time) | assinar/validar as sessões | mesmo valor em toda máquina |
-| **OpenCode** | operador de IA | o `nio init` oferece instalar (`npm i -g opencode-ai`) |
-| **Docker** | **não é necessário** pro `nio ai` (Headroom desativado, ADR 0010 — client fala direto no LLM). Ainda usado por `nio docker` (toolkit/cluster) e pelo gateway conteinerizado | `docker compose version` |
-| *(opcional)* WhatsApp Business API (Meta Graph) | 2º fator | `WHATSAPP_ENDPOINT_URL` + `WHATSAPP_TOKEN` (+ template) |
-
----
-
-## Configuração
-
-**Você não precisa exportar nada no shell.** Rode `nio config setup` — o wizard
-pede o `NIO_DATABASE_URL` (que o time te passa) e o `JWT_SECRET`, **testa a
-conexão** e grava em `~/.nio/config.env` (chmod 600, nunca commitado). O `nio init`,
-`nio register` e `nio login` disparam esse wizard sozinhos se a config faltar; se
-estiver presente mas errada, param com uma mensagem dizendo exatamente o quê.
-
-```bash
-nio config setup     # wizard interativo (cola os valores, testa, salva)
-nio config check     # confere: completa? banco responde?  (--json pra CI)
-nio config path      # ~/.nio/config.env
-```
-
-A CLI carrega as variáveis nesta precedência (shell sempre vence os arquivos):
-
-```
-env do shell  >  $NIO_ENV_FILE  >  ./.env  >  ~/.nio/config.env
-```
-
-Conteúdo de `~/.nio/config.env` (o wizard gera; dá pra editar à mão):
-
-```bash
-NIO_DATABASE_URL=postgres://usuario:senha@HOST:5432/nio_cli
-# NIO_DATABASE_SSL=true          # só se o banco exigir TLS (gerenciado/nuvem)
-JWT_SECRET=<mesmo-valor-do-time>
-
-# 2º fator (WhatsApp OTP via Meta Graph) — opcional, só no lado do gateway
-# WHATSAPP_ENDPOINT_URL=https://graph.facebook.com/v25.0/1076830002188066/messages
-# WHATSAPP_TOKEN=<bearer da Meta Graph>           # app secret; rotaciona ~24h
-# WHATSAPP_TEMPLATE_NAME=autenticao               # template de autenticação aprovado
-# WHATSAPP_TEMPLATE_LANGUAGE=pt_BR                # variação do template
-#
-# DEV: se WHATSAPP_ENDPOINT_URL for loopback (127.0.0.1/localhost — o mock
-# `bun run dev:whatsapp-echo`), o gateway entra em "modo echo": NENHUM WhatsApp real sai.
-# A CLI avisa e mostra o código direto; `nio security status` mostra o backend.
-```
-
-> Alternativa pra time: gere o `~/.nio/config.env` uma vez e distribua o arquivo
-> (é só `KEY=value`) — a CLI valida no primeiro comando.
-
-| Variável | Prefixo | Lida por |
-|---|---|---|
-| `NIO_DATABASE_URL` / `NIO_DATABASE_SSL` | `NIO_` | tudo que toca o banco |
-| `JWT_SECRET` / `JWT_EXPIRES_IN` | **sem** prefixo (segredo do time) | `nio-gateway` + `nio-cli` |
-| `WHATSAPP_ENDPOINT_URL` / `WHATSAPP_TOKEN` (+ `WHATSAPP_TEMPLATE_NAME` / `WHATSAPP_TEMPLATE_LANGUAGE`) | **sem** prefixo | `nio-gateway` |
-| `NIO_GATEWAY_HOST` (default `127.0.0.1`) | `NIO_` | `nio-gateway` — `0.0.0.0` p/ Kong em container |
-| `NIO_GATEWAY_URL` (default `http://127.0.0.1:3000`) | `NIO_` | a CLI acha o nio-gateway (Kong na frente = aponta :8000) |
-
-O schema de conexão é sempre `postgres://…`; um destino inválido falha explícito,
-nunca cai num default silencioso.
-
-### Backend de IA próprio (uso fora da rede NIO)
-
-O motor de IA (`nio ai`/`exec`/`plan`) fala com um backend OpenAI-compatível
-(`/v1`). **O default aponta pra infra interna** (`http://192.168.0.140:8001/v1`,
-modelo `RedHatAI/Qwen3.8-27B-INT4`) — fora dessa rede, suba seu próprio
-vLLM (ou compatível) e aponte a CLI pra ele em `~/.nio/config.env`
-(`nio config path`; `NIO_AI_*` **não** valem no `.env` do projeto):
-
-```bash
-NIO_AI_BASE_URL=https://seu-vllm:8000/v1   # raiz /v1 (o SDK anexa /chat/completions)
-NIO_AI_MODEL=seu-org/seu-modelo            # id EXATO que o backend serve em /v1/models
-NIO_AI_CONTEXT=65536                       # max_model_len do backend; 0 = usa catálogo
-NIO_AI_OUTPUT=2048                         # teto de saída (input + output ≤ contexto!)
-NIO_AI_MAX_INPUT=32000                     # trava de input por prompt (0 = desativa)
-```
-
-Confira com `nio config check` — ele sonda `GET <base>/models` e avisa (sem
-reprovar) se o backend está fora do ar ou não serve o modelo configurado.
-
----
-
-## Primeiros passos
-
-Um comando só:
-
-```bash
-nio            # (ou `nio start`) — a esteira guiada
-```
-
-A esteira detecta em que ponto você está e conduz — **config → gateway → login →
-sessão → handoff pro OpenCode** —, perguntando antes de cada passo. Ela sobe o
-`nio-gateway` sozinha se faltar. Se você sair no meio, ela imprime a linha exata
-pra retomar (`nio start`); nada morre no silêncio.
-
-Por dentro, é isto (cada um roda na mão também):
-
-```bash
-nio config setup     # cola NIO_DATABASE_URL + JWT_SECRET (o time te passa), testa, salva
-nio-gateway          # gateway de auth (a esteira sobe sozinha se faltar)
-nio register         # cria seu usuário na base compartilhada → cai no login
-nio login            # autentica (salva o JWT em ~/.nio/session.json)
-nio security enable-2fa   # (opcional) 2º fator
-nio init             # monta o ambiente da sessão → `nio ai` (opencode serve + chat NIO, num terminal da IDE)
-```
-
-O `nio-gateway` só é necessário pros comandos de auth (`login`/`logout`/
-`verify-2fa`/`security`). Todo o resto — `init`, `sessions`, as tools MCP —
-fala com o Postgres direto usando o JWT local. Rode `nio debug` a qualquer
-momento pra ver o que está ok e o que falta.
-
----
-
-## Arquitetura
-
-Hexagonal. O núcleo não conhece IO; os adapters implementam os contratos.
-
-```
-entrypoints:  src/cli.ts (nio)          src/gateway/index.ts (nio-gateway)
-              src/mcp-server.ts (nio-cli)   src/mcp-server-lang.ts (nio-lang)
-app:          SessionManager · EnvironmentBuilder · DependencyWatcher · DockerManager
-core/:        types.ts (entidades + enums)  +  ports por domínio, sem IO:
-              repositories.ts · environment.ts · docker.ts · messaging.ts · lang.ts
-adapters/:    pg/ (Postgres)  ide/ (vscode)  pkg/ (npm,pip,…)  docker/  sms/  skills/  lang/
-profiles/:    catálogo dos 6 perfis (fixos no fonte)
-```
-
-- **Runtime:** Node 20.12+ é o alvo. Bun roda o projeto em dev, mas **nada**
-  depende de API exclusiva do Bun — só as equivalentes de `node:*`.
-- **Build:** `tsc` puro → `dist/`. Sem bundler.
-- **Banco:** `pg` + um `Pool` único (`src/adapters/pg/client.ts`). Sem Supabase,
-  sem PostgREST, sem `Bun.sql`.
-- **Gateway:** `http.createServer` nativo, loopback, atrás do Kong OSS (opcional,
-  pra rate-limiting). JWT HS256, `jti` = id da `auth_session`. Trilha de auth em
-  stderr estruturado — nunca a senha nem o OTP em texto puro.
-- **Contrato "nunca lança"** nos ports de IO (`ToolchainGateway`, `IdeGateway`,
-  `DockerGateway`, `SmsSender`): falha vira um resultado `{ status, error? }`.
-
-Detalhes: [`docs/arch/`](docs/arch/) (uma `ARQUITETURA-*.md` por camada) e os
-[ADRs](docs/adr/). Histórico cronológico: [`docs/PROGRESSO.md`](docs/PROGRESSO.md).
-
-### Perfis
-
-Fixos no fonte (`src/core/types.ts`) — novos perfis só entram alterando o código:
-
-`fullstack` · `analyst` · `scientist` · `dba` · `qa` · `bi`
-
----
-
-## Autenticação
-
-```bash
-nio register    # cria o usuário (user_cli), senha com hash argon2id
-nio login       # autentica via nio-gateway e salva o JWT em ~/.nio/session.json
-nio whoami      # mostra quem está logado (--json pra saída estável)
-nio logout      # revoga a auth_session no banco e limpa a sessão local
-```
-
-### 2º fator (WhatsApp)
-
-Opt-in por conta. Com `auth_2` ativo, o `nio login` pede um código de 6 dígitos
-enviado por WhatsApp (template de autenticação da Meta Graph); se a mensagem não
-chega, vale um dos 10 **códigos de backup** (mostrados uma vez no `enable-2fa`).
-
-```bash
-nio security enable-2fa               # cadastra o celular, confirma via WhatsApp, mostra os backups
-nio security status                   # ativo? número (mascarado)? quantos backups restam?
-nio security disable-2fa
-nio security regenerate-backup-codes
-```
-
-O gateway gera/valida o OTP em processo (sem Twilio, sem broker), guarda só o
-**HMAC** do código (TTL 5 min, 3 tentativas, uso único) e manda a mensagem pela
-**WhatsApp Business API (Meta Graph)**. Sem `WHATSAPP_ENDPOINT_URL`/`WHATSAPP_TOKEN`
-no ambiente, o login com `auth_2` responde `503 "2FA não configurado"` — o login
-de 1 fator segue normal.
-Detalhes: [spec 0004](docs/specs/auth/0004-login-2fa-sms-otp.md) ·
-[ADR 0006](docs/adr/0006-2fa-sms-otp.md) ·
-[`docs/arch/ARQUITETURA-GATEWAY.md`](docs/arch/ARQUITETURA-GATEWAY.md).
-
-Pra testar sem WhatsApp real, o repo traz um mock: `bun run dev:whatsapp-echo` sobe
-um endpoint local que imprime o código no terminal (aponte `WHATSAPP_ENDPOINT_URL` pra ele).
-
----
-
-## Operador de IA (`nio ai`)
-
-No fim do `nio init` a CLI sobe o **client de IA** da sessão — e o mesmo `nio ai`
-retoma a qualquer momento. Ele:
-
-1. **Prepara o `opencode.json`** — grava o provider `opencode` **direto no OpenCode Zen**
-   (sem `baseURL` de proxy), junto do `model: opencode/big-pickle`, do MCP `nio`, dos MCPs
-   do perfil e de um bloco `permission` semeado (allowlist só-leitura → `allow`, resto →
-   `ask`). O **Headroom foi desativado** ([ADR 0010](docs/adr/0010-headroom-desativado.md)):
-   o client fala direto no LLM, sem compressão — **não precisa de Docker** pro `nio ai`.
-   (O `nio docker headroom` continua existindo, dormente, pra quem quiser subir manualmente.)
-2. **Sobe o `opencode serve` headless e abre a interface NIO** (Ink). O motor é o
-   `opencode/big-pickle`; a casca é nossa. Se a sessão tem IDE (VS Code / Cursor), o
-   `nio init` grava um `.vscode/tasks.json` (task `NIO`, `runOn: folderOpen`) e o
-   `nio ai` sobe num **terminal integrado da IDE** — uma superfície, não duas. Sem
-   IDE, roda no terminal atual. Sem TTY → recusa com mensagem; sem `opencode` no
-   PATH → cai na TUI do OpenCode.
-
-Ver [`docs/arch/ARQUITETURA-CLIENTE-IA.md`](docs/arch/ARQUITETURA-CLIENTE-IA.md),
-[`docs/arch/ARQUITETURA-TUI-UX-SPRINTS.md`](docs/arch/ARQUITETURA-TUI-UX-SPRINTS.md) e
-[`docs/arch/ARQUITETURA-TUI-INTERACOES-MOTOR.md`](docs/arch/ARQUITETURA-TUI-INTERACOES-MOTOR.md).
-
-### Interface do `nio ai` (TUI)
-
-Chat no terminal (Ink) sobre o `opencode/big-pickle`, **em uma superfície só** — no
-estilo do Claude Code. O que o motor faz aparece **em linha**, conforme acontece:
-o raciocínio (`✻`), cada ferramenta (`● nome(args)` + `⎿` a saída), o checklist
-(`☑ ◐ ☐`), os arquivos tocados, o diff da rodada (`✎ N arquivo(s) +x −y`) e os
-tokens/custo no rodapé de cada resposta. Sem sidebar, sem janela extra.
-
-**Digitar & enviar**
-
-| Tecla | Faz |
-|---|---|
-| `Enter` | envia o prompt |
-| `\` + `Enter`  ·  `Ctrl-J` | quebra linha — o prompt é multi-linha e cresce sozinho |
-| `←` `→` `↑` `↓` | move o cursor dentro do texto |
-| `Ctrl-A` / `Ctrl-E` | início / fim da linha |
-| `Ctrl-W` / `Ctrl-U` / `Ctrl-K` | apaga a palavra anterior / até o início / até o fim |
-| colar um bloco | entra literal (várias linhas **não** enviam sozinhas) |
-
-**Modos** — o modo troca o comportamento do agente
-
-| Tecla | Faz |
-|---|---|
-| `Tab` | alterna entre os agentes primários do `opencode.json` (`build` → `plan` → …) |
-| `build` | o agente **executa** (edita, roda comando) |
-| `plan` | o agente **só propõe** — não toca nada |
-
-O modo atual fica no rodapé: `[build]`.
-
-**Paleta de comandos**
-
-| Tecla | Faz |
-|---|---|
-| `/` | abre a lista inline — comandos do `nio` + capacidades do operador |
-| `↑` `↓` + `Enter` | roda o comando / manda a capacidade pro agente / abre o painel |
-| `Esc` | fecha a lista — o texto que você já digitou **continua lá** |
-
-**Quando o agente te interrompe**
-
-- **Permissão** (rodar shell, editar arquivo, chamar MCP…) → modal:
-  `a`/`Enter` permite uma vez · `s` permite **sempre** (salva a regra no `opencode.json`) · `d`/`Esc` nega.
-  Pedidos em paralelo entram numa **fila** (`+N na fila`); um sub-agente travado é
-  reconciliado sozinho em ~4s — não trava mais em "processando".
-- **Pergunta aberta** — o agente termina com "?" → o cue `↳ o nio perguntou` aparece acima do input.
-- **Lista de opções** — o agente listou `1./2./3.` → menu `↑`/`↓`+`Enter` pra escolher; ou ignore e escreva livre.
-
-**Acompanhar & controlar**
-
-| Tecla | Faz |
-|---|---|
-| `Ctrl-R` | expande / colapsa o raciocínio (`✻`) — ver o agente "pensar" ao vivo |
-| `Esc` | durante o processamento: **aborta o turno** |
-
-`NIO_DEBUG=1 nio ai` grava cada evento cru do motor em `~/.nio/tui.log` (nunca no
-terminal — corromperia o render).
-
-> A interface NIO (Ink) está na **fatia 2a** ([ADR 0008](docs/adr/0008-interface-nio-ink.md)).
-> A paridade completa com o OpenCode (diff viewer, file tree, seletor de modelo…) é a 2b.
-> Multi-cliente (OpenCode | Codex) e o ladder de failover entre modelos seguem
-> parkeados em
-> [`docs/arch/ARQUITETURA-CLIENTES-MULTI-FUTURO.md`](docs/arch/ARQUITETURA-CLIENTES-MULTI-FUTURO.md)
-> ([ADR 0004](docs/adr/0004-operador-ia-unico.md)).
-
----
-
-## Comandos do CLI
-
-Operações do CLI, **sem o binário na frente** (declarado no cabeçalho da tabela).
-Gerada da fonte por `npm run gen:docs`. Ajuda de qualquer comando: `nio <cmd> --help`.
-
+# NIO-CLI
+
+**Orquestrador de ambientes de desenvolvimento.** Você escolhe um perfil,
+responde um wizard, e a CLI — com auxílio de IA via MCP — materializa o ambiente:
+toolchains, linguagens, frameworks, dotfiles, aliases e IDE. A entidade central é
+a **Sessão**: um ambiente isolado, com UUID, persistido no Postgres.
+
+> **Guia rápido de uso:** `nio --help` (primeiros passos + como usar a interface do `nio ai`).
+> **Manual completo:** `nio docs` no terminal · `nio docs --html --open` como página.
+
+---
+
+## Como funciona
+
+```
+você → nio (CLI) ──► nio-gateway ──► Postgres        (login: senha + JWT, 2º fator opcional)
+          │
+          ├──► SessionManager / EnvironmentBuilder    (materializa toolchains, MCPs, dotfiles)
+          │
+          └──► opencode.json  ──►  OpenCode (operador de IA)
+                                     └── MCP `nio` (tools nio_*)  ──► SessionManager ──► Postgres
+```
+
+1. **Você se autentica** (`nio register` / `nio login`). O `nio-gateway` — um
+   serviço HTTP loopback — verifica a senha (argon2id), dispara o 2º fator se
+   estiver ativo, e devolve um **JWT** salvo em `~/.nio/session.json`.
+2. **Você monta uma sessão** (`nio init`). O wizard pergunta perfil + recipe, e o
+   `EnvironmentBuilder` garante os toolchains, resolve os MCPs e grava o `config`
+   materializado na linha `sessions` do Postgres. A sessão é isolada, tem UUID e
+   pode ser reativada depois (`nio sessions`).
+3. **`nio ai` abre a interface NIO** — o `opencode serve` headless
+   (`opencode/big-pickle`, MCP `nio` + MCPs do perfil) e o chat do NIO em Ink
+   (fluxo em linha estilo Claude Code, paleta `/`, `Tab` troca de modo). O
+   Headroom foi desativado ([ADR 0010](docs/adr/0010-headroom-desativado.md)) — o
+   client fala direto no LLM, **não precisa de Docker**. Com IDE, roda num
+   terminal integrado dela. A partir daí o agente tem as tools `nio_*` —
+   criar/ativar sessão, re-materializar ambiente, delegar execução. Detalhe de
+   uso: **[Interface do `nio ai`](#interface-do-nio-ai-tui)**.
+
+O **Postgres é a fonte da verdade** do domínio (usuários, sessões, trilha de
+auth). A CLI e o gateway só falam com o banco que **você** configurar — não há
+default, não há banco embutido.
+
+---
+
+## Instalação
+
+Precisa de **Node.js 20.12+**. Instala como pacote global:
+
+```bash
+npm i -g @nio-cli/cli
+```
+
+Ficam no PATH: `nio` (CLI), `nio-gateway` (serviço de auth), `nio-cli` e
+`nio-lang` (servidores MCP).
+
+### Pré-requisitos de runtime
+
+| Requisito | Pra quê | Como |
+|---|---|---|
+| **PostgreSQL** alcançável | fonte da verdade (sessões, usuários) | schema em `db/schema.sql` aplicado uma vez |
+| **`JWT_SECRET`** (segredo do time) | assinar/validar as sessões | mesmo valor em toda máquina |
+| **OpenCode** | operador de IA | o `nio init` oferece instalar (`npm i -g opencode-ai`) |
+| **Docker** | **não é necessário** pro `nio ai` (Headroom desativado, ADR 0010 — client fala direto no LLM). Ainda usado por `nio docker` (toolkit/cluster) e pelo gateway conteinerizado | `docker compose version` |
+| *(opcional)* WhatsApp Business API (Meta Graph) | 2º fator | `WHATSAPP_ENDPOINT_URL` + `WHATSAPP_TOKEN` (+ template) |
+
+---
+
+## Configuração
+
+**Você não precisa exportar nada no shell.** Rode `nio config setup` — o wizard
+pede o `NIO_DATABASE_URL` (que o time te passa) e o `JWT_SECRET`, **testa a
+conexão** e grava em `~/.nio/config.env` (chmod 600, nunca commitado). O `nio init`,
+`nio register` e `nio login` disparam esse wizard sozinhos se a config faltar; se
+estiver presente mas errada, param com uma mensagem dizendo exatamente o quê.
+
+```bash
+nio config setup     # wizard interativo (cola os valores, testa, salva)
+nio config check     # confere: completa? banco responde?  (--json pra CI)
+nio config path      # ~/.nio/config.env
+```
+
+A CLI carrega as variáveis nesta precedência (shell sempre vence os arquivos):
+
+```
+env do shell  >  $NIO_ENV_FILE  >  ./.env  >  ~/.nio/config.env
+```
+
+Conteúdo de `~/.nio/config.env` (o wizard gera; dá pra editar à mão):
+
+```bash
+NIO_DATABASE_URL=postgres://usuario:senha@HOST:5432/nio_cli
+# NIO_DATABASE_SSL=true          # só se o banco exigir TLS (gerenciado/nuvem)
+JWT_SECRET=<mesmo-valor-do-time>
+
+# 2º fator (WhatsApp OTP via Meta Graph) — opcional, só no lado do gateway
+# WHATSAPP_ENDPOINT_URL=https://graph.facebook.com/v25.0/1076830002188066/messages
+# WHATSAPP_TOKEN=<bearer da Meta Graph>           # app secret; rotaciona ~24h
+# WHATSAPP_TEMPLATE_NAME=autenticao               # template de autenticação aprovado
+# WHATSAPP_TEMPLATE_LANGUAGE=pt_BR                # variação do template
+#
+# DEV: se WHATSAPP_ENDPOINT_URL for loopback (127.0.0.1/localhost — o mock
+# `bun run dev:whatsapp-echo`), o gateway entra em "modo echo": NENHUM WhatsApp real sai.
+# A CLI avisa e mostra o código direto; `nio security status` mostra o backend.
+```
+
+> Alternativa pra time: gere o `~/.nio/config.env` uma vez e distribua o arquivo
+> (é só `KEY=value`) — a CLI valida no primeiro comando.
+
+| Variável | Prefixo | Lida por |
+|---|---|---|
+| `NIO_DATABASE_URL` / `NIO_DATABASE_SSL` | `NIO_` | tudo que toca o banco |
+| `JWT_SECRET` / `JWT_EXPIRES_IN` | **sem** prefixo (segredo do time) | `nio-gateway` + `nio-cli` |
+| `WHATSAPP_ENDPOINT_URL` / `WHATSAPP_TOKEN` (+ `WHATSAPP_TEMPLATE_NAME` / `WHATSAPP_TEMPLATE_LANGUAGE`) | **sem** prefixo | `nio-gateway` |
+| `NIO_GATEWAY_HOST` (default `127.0.0.1`) | `NIO_` | `nio-gateway` — `0.0.0.0` p/ Kong em container |
+| `NIO_GATEWAY_URL` (default `http://127.0.0.1:3000`) | `NIO_` | a CLI acha o nio-gateway (Kong na frente = aponta :8000) |
+
+O schema de conexão é sempre `postgres://…`; um destino inválido falha explícito,
+nunca cai num default silencioso.
+
+### Backend de IA próprio (uso fora da rede NIO)
+
+O motor de IA (`nio ai`/`exec`/`plan`) fala com um backend OpenAI-compatível
+(`/v1`). **O default aponta pra infra interna** (`http://192.168.0.140:8001/v1`,
+modelo `RedHatAI/Qwen3.8-27B-INT4`) — fora dessa rede, suba seu próprio
+vLLM (ou compatível) e aponte a CLI pra ele em `~/.nio/config.env`
+(`nio config path`; `NIO_AI_*` **não** valem no `.env` do projeto):
+
+```bash
+NIO_AI_BASE_URL=https://seu-vllm:8000/v1   # raiz /v1 (o SDK anexa /chat/completions)
+NIO_AI_MODEL=seu-org/seu-modelo            # id EXATO que o backend serve em /v1/models
+NIO_AI_CONTEXT=65536                       # max_model_len do backend; 0 = usa catálogo
+NIO_AI_OUTPUT=2048                         # teto de saída (input + output ≤ contexto!)
+NIO_AI_MAX_INPUT=32000                     # trava de input por prompt (0 = desativa)
+```
+
+Confira com `nio config check` — ele sonda `GET <base>/models` e avisa (sem
+reprovar) se o backend está fora do ar ou não serve o modelo configurado.
+
+---
+
+## Primeiros passos
+
+Um comando só:
+
+```bash
+nio            # (ou `nio start`) — a esteira guiada
+```
+
+A esteira detecta em que ponto você está e conduz — **config → gateway → login →
+sessão → handoff pro OpenCode** —, perguntando antes de cada passo. Ela sobe o
+`nio-gateway` sozinha se faltar. Se você sair no meio, ela imprime a linha exata
+pra retomar (`nio start`); nada morre no silêncio.
+
+Por dentro, é isto (cada um roda na mão também):
+
+```bash
+nio config setup     # cola NIO_DATABASE_URL + JWT_SECRET (o time te passa), testa, salva
+nio-gateway          # gateway de auth (a esteira sobe sozinha se faltar)
+nio register         # cria seu usuário na base compartilhada → cai no login
+nio login            # autentica (salva o JWT em ~/.nio/session.json)
+nio security enable-2fa   # (opcional) 2º fator
+nio init             # monta o ambiente da sessão → `nio ai` (opencode serve + chat NIO, num terminal da IDE)
+```
+
+O `nio-gateway` só é necessário pros comandos de auth (`login`/`logout`/
+`verify-2fa`/`security`). Todo o resto — `init`, `sessions`, as tools MCP —
+fala com o Postgres direto usando o JWT local. Rode `nio debug` a qualquer
+momento pra ver o que está ok e o que falta.
+
+---
+
+## Arquitetura
+
+Hexagonal. O núcleo não conhece IO; os adapters implementam os contratos.
+
+```
+entrypoints:  src/cli.ts (nio)          src/gateway/index.ts (nio-gateway)
+              src/mcp-server.ts (nio-cli)   src/mcp-server-lang.ts (nio-lang)
+app:          SessionManager · EnvironmentBuilder · DependencyWatcher · DockerManager
+core/:        types.ts (entidades + enums)  +  ports por domínio, sem IO:
+              repositories.ts · environment.ts · docker.ts · messaging.ts · lang.ts
+adapters/:    pg/ (Postgres)  ide/ (vscode)  pkg/ (npm,pip,…)  docker/  sms/  skills/  lang/
+profiles/:    catálogo dos 6 perfis (fixos no fonte)
+```
+
+- **Runtime:** Node 20.12+ é o alvo. Bun roda o projeto em dev, mas **nada**
+  depende de API exclusiva do Bun — só as equivalentes de `node:*`.
+- **Build:** `tsc` puro → `dist/`. Sem bundler.
+- **Banco:** `pg` + um `Pool` único (`src/adapters/pg/client.ts`). Sem Supabase,
+  sem PostgREST, sem `Bun.sql`.
+- **Gateway:** `http.createServer` nativo, loopback, atrás do Kong OSS (opcional,
+  pra rate-limiting). JWT HS256, `jti` = id da `auth_session`. Trilha de auth em
+  stderr estruturado — nunca a senha nem o OTP em texto puro.
+- **Contrato "nunca lança"** nos ports de IO (`ToolchainGateway`, `IdeGateway`,
+  `DockerGateway`, `SmsSender`): falha vira um resultado `{ status, error? }`.
+
+Detalhes: [`docs/arch/`](docs/arch/) (uma `ARQUITETURA-*.md` por camada) e os
+[ADRs](docs/adr/). Histórico cronológico: [`docs/PROGRESSO.md`](docs/PROGRESSO.md).
+
+### Perfis
+
+Fixos no fonte (`src/core/types.ts`) — novos perfis só entram alterando o código:
+
+`fullstack` · `analyst` · `scientist` · `dba` · `qa` · `bi`
+
+---
+
+## Autenticação
+
+```bash
+nio register    # cria o usuário (user_cli), senha com hash argon2id
+nio login       # autentica via nio-gateway e salva o JWT em ~/.nio/session.json
+nio whoami      # mostra quem está logado (--json pra saída estável)
+nio logout      # revoga a auth_session no banco e limpa a sessão local
+```
+
+### 2º fator (WhatsApp)
+
+Opt-in por conta. Com `auth_2` ativo, o `nio login` pede um código de 6 dígitos
+enviado por WhatsApp (template de autenticação da Meta Graph); se a mensagem não
+chega, vale um dos 10 **códigos de backup** (mostrados uma vez no `enable-2fa`).
+
+```bash
+nio security enable-2fa               # cadastra o celular, confirma via WhatsApp, mostra os backups
+nio security status                   # ativo? número (mascarado)? quantos backups restam?
+nio security disable-2fa
+nio security regenerate-backup-codes
+```
+
+O gateway gera/valida o OTP em processo (sem Twilio, sem broker), guarda só o
+**HMAC** do código (TTL 5 min, 3 tentativas, uso único) e manda a mensagem pela
+**WhatsApp Business API (Meta Graph)**. Sem `WHATSAPP_ENDPOINT_URL`/`WHATSAPP_TOKEN`
+no ambiente, o login com `auth_2` responde `503 "2FA não configurado"` — o login
+de 1 fator segue normal.
+Detalhes: [spec 0004](docs/specs/auth/0004-login-2fa-sms-otp.md) ·
+[ADR 0006](docs/adr/0006-2fa-sms-otp.md) ·
+[`docs/arch/ARQUITETURA-GATEWAY.md`](docs/arch/ARQUITETURA-GATEWAY.md).
+
+Pra testar sem WhatsApp real, o repo traz um mock: `bun run dev:whatsapp-echo` sobe
+um endpoint local que imprime o código no terminal (aponte `WHATSAPP_ENDPOINT_URL` pra ele).
+
+---
+
+## Operador de IA (`nio ai`)
+
+No fim do `nio init` a CLI sobe o **client de IA** da sessão — e o mesmo `nio ai`
+retoma a qualquer momento. Ele:
+
+1. **Prepara o `opencode.json`** — grava o provider `opencode` **direto no OpenCode Zen**
+   (sem `baseURL` de proxy), junto do `model: opencode/big-pickle`, do MCP `nio`, dos MCPs
+   do perfil e de um bloco `permission` semeado (allowlist só-leitura → `allow`, resto →
+   `ask`). O **Headroom foi desativado** ([ADR 0010](docs/adr/0010-headroom-desativado.md)):
+   o client fala direto no LLM, sem compressão — **não precisa de Docker** pro `nio ai`.
+   (O `nio docker headroom` continua existindo, dormente, pra quem quiser subir manualmente.)
+2. **Sobe o `opencode serve` headless e abre a interface NIO** (Ink). O motor é o
+   `opencode/big-pickle`; a casca é nossa. Se a sessão tem IDE (VS Code / Cursor), o
+   `nio init` grava um `.vscode/tasks.json` (task `NIO`, `runOn: folderOpen`) e o
+   `nio ai` sobe num **terminal integrado da IDE** — uma superfície, não duas. Sem
+   IDE, roda no terminal atual. Sem TTY → recusa com mensagem; sem `opencode` no
+   PATH → cai na TUI do OpenCode.
+
+Ver [`docs/arch/ARQUITETURA-CLIENTE-IA.md`](docs/arch/ARQUITETURA-CLIENTE-IA.md),
+[`docs/arch/ARQUITETURA-TUI-UX-SPRINTS.md`](docs/arch/ARQUITETURA-TUI-UX-SPRINTS.md) e
+[`docs/arch/ARQUITETURA-TUI-INTERACOES-MOTOR.md`](docs/arch/ARQUITETURA-TUI-INTERACOES-MOTOR.md).
+
+### Interface do `nio ai` (TUI)
+
+Chat no terminal (Ink) sobre o `opencode/big-pickle`, **em uma superfície só** — no
+estilo do Claude Code. O que o motor faz aparece **em linha**, conforme acontece:
+o raciocínio (`✻`), cada ferramenta (`● nome(args)` + `⎿` a saída), o checklist
+(`☑ ◐ ☐`), os arquivos tocados, o diff da rodada (`✎ N arquivo(s) +x −y`) e os
+tokens/custo no rodapé de cada resposta. Sem sidebar, sem janela extra.
+
+**Digitar & enviar**
+
+| Tecla | Faz |
+|---|---|
+| `Enter` | envia o prompt |
+| `\` + `Enter`  ·  `Ctrl-J` | quebra linha — o prompt é multi-linha e cresce sozinho |
+| `←` `→` `↑` `↓` | move o cursor dentro do texto |
+| `Ctrl-A` / `Ctrl-E` | início / fim da linha |
+| `Ctrl-W` / `Ctrl-U` / `Ctrl-K` | apaga a palavra anterior / até o início / até o fim |
+| colar um bloco | entra literal (várias linhas **não** enviam sozinhas) |
+
+**Modos** — o modo troca o comportamento do agente
+
+| Tecla | Faz |
+|---|---|
+| `Tab` | alterna entre os agentes primários do `opencode.json` (`build` → `plan` → …) |
+| `build` | o agente **executa** (edita, roda comando) |
+| `plan` | o agente **só propõe** — não toca nada |
+
+O modo atual fica no rodapé: `[build]`.
+
+**Paleta de comandos**
+
+| Tecla | Faz |
+|---|---|
+| `/` | abre a lista inline — comandos do `nio` + capacidades do operador |
+| `↑` `↓` + `Enter` | roda o comando / manda a capacidade pro agente / abre o painel |
+| `Esc` | fecha a lista — o texto que você já digitou **continua lá** |
+
+**Quando o agente te interrompe**
+
+- **Permissão** (rodar shell, editar arquivo, chamar MCP…) → modal:
+  `a`/`Enter` permite uma vez · `s` permite **sempre** (salva a regra no `opencode.json`) · `d`/`Esc` nega.
+  Pedidos em paralelo entram numa **fila** (`+N na fila`); um sub-agente travado é
+  reconciliado sozinho em ~4s — não trava mais em "processando".
+- **Pergunta aberta** — o agente termina com "?" → o cue `↳ o nio perguntou` aparece acima do input.
+- **Lista de opções** — o agente listou `1./2./3.` → menu `↑`/`↓`+`Enter` pra escolher; ou ignore e escreva livre.
+
+**Acompanhar & controlar**
+
+| Tecla | Faz |
+|---|---|
+| `Ctrl-R` | expande / colapsa o raciocínio (`✻`) — ver o agente "pensar" ao vivo |
+| `Esc` | durante o processamento: **aborta o turno** |
+
+`NIO_DEBUG=1 nio ai` grava cada evento cru do motor em `~/.nio/tui.log` (nunca no
+terminal — corromperia o render).
+
+> A interface NIO (Ink) está na **fatia 2a** ([ADR 0008](docs/adr/0008-interface-nio-ink.md)).
+> A paridade completa com o OpenCode (diff viewer, file tree, seletor de modelo…) é a 2b.
+> Multi-cliente (OpenCode | Codex) e o ladder de failover entre modelos seguem
+> parkeados em
+> [`docs/arch/ARQUITETURA-CLIENTES-MULTI-FUTURO.md`](docs/arch/ARQUITETURA-CLIENTES-MULTI-FUTURO.md)
+> ([ADR 0004](docs/adr/0004-operador-ia-unico.md)).
+
+---
+
+## Comandos do CLI
+
+Operações do CLI, **sem o binário na frente** (declarado no cabeçalho da tabela).
+Gerada da fonte por `npm run gen:docs`. Ajuda de qualquer comando: `nio <cmd> --help`.
+
 <!-- COMMANDS:START -->
 <!-- gerado por `bun run gen:docs` — não edite à mão. binário `nio`, 60 comandos. -->
 
@@ -399,60 +399,60 @@ Gerada da fonte por `npm run gen:docs`. Ajuda de qualquer comando: `nio <cmd> --
 | `sync` | Instala/atualiza skills, commands e agents nos clientes configurados, a partir do bundle (idempotente); checa atualização do pacote |
 | `validate-plan` | Lê o plan.md da raiz e roda o Qwen (vLLM local) para julgar se o plano precisa de uma spec antes de implementar. |
 | `whoami` | Mostra o usuário autenticado |
-<!-- COMMANDS:END -->
-
-### Diagnóstico da própria CLI
-
-```bash
-nio debug        # bateria de checagens: nio.json, login, Postgres, sessão ativa,
-                 # OpenCode no PATH, cache de skills — ✓ / ⚠ / ✗ com dica em cada
-nio docs         # documentação completa no terminal
-nio docs --html  # a mesma coisa como página (arte); --open abre no navegador
-```
-
-### Autocomplete (tab)
-
-O `nio init` **oferece** ativar; o `nio sync` **valida** e prompta se faltar. À mão:
-
-```bash
-eval "$(nio completion zsh)"     # ~/.zshrc
-eval "$(nio completion bash)"    # ~/.bashrc
-nio completion fish | source     # ~/.config/fish/config.fish
-```
-
----
-
-## Docker (`nio docker`)
-
-Camada de gerência de container — metade wrapper determinístico sobre `docker`,
-metade dirigida pelo operador de IA em linguagem natural (via o **Docker MCP
-Gateway**). Roda em qualquer Docker Engine (não exige Docker Desktop). Ver
-[`docs/arch/ARQUITETURA-DOCKER.md`](docs/arch/ARQUITETURA-DOCKER.md) ·
-[ADR 0005](docs/adr/0005-camada-docker.md).
-
-```bash
-nio docker toolkit up            # sobe o MCP Gateway (127.0.0.1:8811/mcp) + Portainer (9443)
-                                 # e registra o gateway no opencode.json
-nio docker compose up -f app/docker-compose.yml   # wrapper sobre `docker compose` do projeto
-nio docker create --image redis:7 --port 6379:6379
-nio docker debug <container>     # coleta ps/logs/inspect → operador analisa e propõe o fix
-nio docker orquest "sobe api + worker + redis"    # operador gera o compose e sobe (--dry-run mostra)
-nio docker cluster up "api + worker + redis + postgres"   # Docker Swarm (stack `nio-cluster`)
-nio docker cluster status | scale api=3
-nio docker portainer             # abre a UI
-```
-
-`debug`/`orquest`/`cluster` exigem `nio login` + sessão ativa + `opencode` no
-PATH. O estado do cluster fica em `sessions.config` (Postgres), validado contra
-`docker stack services`.
-
----
-
-## Tools MCP
-
-O servidor `nio-cli` expõe as tools de ambiente v2 (todas passam pelo
-`SessionManager` e exigem `nio login`):
-
+<!-- COMMANDS:END -->
+
+### Diagnóstico da própria CLI
+
+```bash
+nio debug        # bateria de checagens: nio.json, login, Postgres, sessão ativa,
+                 # OpenCode no PATH, cache de skills — ✓ / ⚠ / ✗ com dica em cada
+nio docs         # documentação completa no terminal
+nio docs --html  # a mesma coisa como página (arte); --open abre no navegador
+```
+
+### Autocomplete (tab)
+
+O `nio init` **oferece** ativar; o `nio sync` **valida** e prompta se faltar. À mão:
+
+```bash
+eval "$(nio completion zsh)"     # ~/.zshrc
+eval "$(nio completion bash)"    # ~/.bashrc
+nio completion fish | source     # ~/.config/fish/config.fish
+```
+
+---
+
+## Docker (`nio docker`)
+
+Camada de gerência de container — metade wrapper determinístico sobre `docker`,
+metade dirigida pelo operador de IA em linguagem natural (via o **Docker MCP
+Gateway**). Roda em qualquer Docker Engine (não exige Docker Desktop). Ver
+[`docs/arch/ARQUITETURA-DOCKER.md`](docs/arch/ARQUITETURA-DOCKER.md) ·
+[ADR 0005](docs/adr/0005-camada-docker.md).
+
+```bash
+nio docker toolkit up            # sobe o MCP Gateway (127.0.0.1:8811/mcp) + Portainer (9443)
+                                 # e registra o gateway no opencode.json
+nio docker compose up -f app/docker-compose.yml   # wrapper sobre `docker compose` do projeto
+nio docker create --image redis:7 --port 6379:6379
+nio docker debug <container>     # coleta ps/logs/inspect → operador analisa e propõe o fix
+nio docker orquest "sobe api + worker + redis"    # operador gera o compose e sobe (--dry-run mostra)
+nio docker cluster up "api + worker + redis + postgres"   # Docker Swarm (stack `nio-cluster`)
+nio docker cluster status | scale api=3
+nio docker portainer             # abre a UI
+```
+
+`debug`/`orquest`/`cluster` exigem `nio login` + sessão ativa + `opencode` no
+PATH. O estado do cluster fica em `sessions.config` (Postgres), validado contra
+`docker stack services`.
+
+---
+
+## Tools MCP
+
+O servidor `nio-cli` expõe as tools de ambiente v2 (todas passam pelo
+`SessionManager` e exigem `nio login`):
+
 <!-- TOOLS:START -->
 <!-- gerado por `bun run gen:docs` — não edite à mão. 10 tools. -->
 
@@ -470,152 +470,152 @@ O servidor `nio-cli` expõe as tools de ambiente v2 (todas passam pelo
 | `session_create` | Cria uma sessão de ambiente pro usuário autenticado e materializa o perfil escolhido: garante os toolchains, resolve os MCPs e persiste o `config` em `sessions.config`. |
 | `session_list` | Lista as sessões de ambiente do usuário autenticado (mais recentes primeiro), com id, nome, perfil, status e o `config` materializado. |
 | `validate_plan` | Lê o `plan.md` da raiz do projeto e roda o Qwen (vLLM local, via API) para julgar se o plano é complexo o bastante para virar uma spec SDD antes de implementar. |
-<!-- TOOLS:END -->
-
-### Recipes de ambiente (repo NIO-SKILLS)
-
-Além dos 6 perfis fixos, o repo `NIO-SKILLS-` pode carregar **recipes** em
-`recipes/<slug>.md` — presets nomeados (`profile` + linguagens + frameworks +
-MCPs + envVars/aliases) que **estendem** um perfil, editáveis sem release da CLI.
-O `nio init` oferece a recipe depois do perfil; `nio_session_create` aceita
-`{ recipe: "<slug>" }`. Merge determinístico (recipe vence em envVars/aliases;
-união em linguagens/frameworks/MCPs).
-
----
-
-## Skills, commands e dependências
-
-Além das tools, o nio entrega **skills, commands e agents** pros clientes. O conteúdo
-vive num **repo aberto** — [`hugoreiis12-png/NIO-SKILLS-`](https://github.com/hugoreiis12-png/NIO-SKILLS-) —
-e **não** é um pacote npm. O CLI baixa o repo (zipball do GitHub, sem precisar de `git`)
-pra um cache local em **`~/.nio/skills`** e lê de lá. `nio sync` **atualiza o cache**
-(pull da branch) toda vez, então as skills evoluem sem republicar o CLI; e **auto-detecta**
-se o OpenCode tem o conector `nio` configurado, provisionando pra ele conforme a seleção
-de perfil/área do `nio.json`.
-
-Overrides por ambiente:
-
-| Variável              | Efeito                                                              |
-| --------------------- | ------------------------------------------------------------------ |
-| `NIO_SKILLS_DIR`   | Aponta pra um checkout local do repo (dev) — vence tudo            |
-| `NIO_SKILLS_REPO`  | Outro `owner/repo` (default `hugoreiis12-png/NIO-SKILLS-`)           |
-| `NIO_SKILLS_REF`   | Outra branch/tag (default `main`)                                  |
-
-Cada cliente recebe no formato que entende:
-
-| Cliente         | Onde                          | Formato                                                                 |
-| --------------- | ----------------------------- | ----------------------------------------------------------------------- |
-| OpenCode        | `~/.config/opencode/`         | MCP `nio` registrado no `opencode.json`; skills/commands no layout cru do pacote (`skills/<id>/SKILL.md`) |
-| Cowork/Desktop  | —                             | via **MCP prompts** + resources, servidos ao vivo                       |
-
-> **Como aparecem no Cowork/Claude Desktop.** Lá as skills chegam como **prompts MCP**,
-> que o app expõe como **slash-commands** no menu de conectores/"+" (ex.: digite `/` e
-> procure os itens do nio) — são **invocados manualmente**, não carregados sozinhos
-> como Agent Skills que o modelo detecta e usa por conta própria. Se não aparecerem:
-> feche o app de vez (Cmd+Q) e reabra, e confirme que o conector nio está conectado.
-
-### Visibilidade por cliente
-
-Um doc pode ser restrito a clientes específicos via frontmatter:
-
-```yaml
-clients: cowork, opencode   # vazio/ausente = todos os clientes
-```
-
-Valores: `cowork`, `opencode`. O MCP filtra por esse campo, então um skill
-marcado `cowork` só aparece como prompt no Cowork/Desktop, e um `opencode` só
-nos docs provisionados ao operador OpenCode.
-
-### Dependências externas
-
-Commands/skills podem depender de libs externas, declaradas como arquivos em
-`dependencies/` no repo de skills (a presença do arquivo é a declaração). No fim do
-`init`/`sync`, a CLI lista cada uma e:
-
-- **instalador estruturado** (`npm:`, `skills:` = `npx skills add`, `git:`) → oferece
-  rodar com `[y/N]` (comando montado a partir do campo validado, **sem shell**);
-- **`manual:`** (sem instalador automatizável — checagem/UI no cliente) → imprime os
-  passos, com os comandos destacados.
-
-A string `install:` (se houver) é **só exibição** — nunca é executada. A CLI **detecta
-o que já está instalado** e mostra um selo `✓ instalada` (via `npm ls -g`, dir de
-destino, ou o `detect:` do frontmatter).
-
----
-
-## Claude Desktop / Cowork
-
-O Cowork/Claude Desktop é um cliente de **chat** via MCP — as skills chegam como
-**prompts MCP** servidos ao vivo, e o conector vive no `claude_desktop_config.json`
-com caminhos absolutos (`node` + `dist/mcp-server.js`) e `NIO_CLIENT=cowork`. Ele
-**não** é mais um alvo do `nio init` (o checkbox só oferece OpenCode): o setup
-inicial do conector é manual. O `nio sync` **reafirma** esse config quando o conector
-já existe — com o app instalado e você logado (`nio login`), ele reescreve o entry
-com paths atuais (merge não-destrutivo + backup). Reinicie o Claude Desktop pra
-carregar prompts novos depois do sync.
-
----
-
-## Atualizando
-
-```bash
-npm i -g @nio-cli/cli@latest
-```
-
-O `nio sync` **checa a versão publicada** no início e **oferece atualizar** ali mesmo
-(com sua confirmação). `nio sync --yes` aceita sem prompt. A CLI também avisa em
-background em qualquer comando (`update-notifier`).
-
----
-
-## Troubleshooting
-
-| Sintoma | Causa provável / o que fazer |
-|---|---|
-| `nio: command not found` | `npm i -g @nio-cli/cli` e confira `npm bin -g` no PATH |
-| `Configuração necessária` / `NIO_DATABASE_URL não definida` | rode `nio config setup` (ou deixe o `nio init` abrir o wizard) |
-| `Não consegui falar com o nio-gateway` | o `nio-gateway` não está no ar — rode `nio-gateway &` |
-| `Não autenticado` | `nio register` (1ª vez) e depois `nio login` |
-| Erro de conexão com o banco | `ECONNREFUSED` = Postgres fora do ar / host errado; `password authentication failed` = credencial; erro de SSL = `NIO_DATABASE_SSL=true` |
-| `2FA não configurado no servidor` (503) | faltam as `WHATSAPP_*` no ambiente do `nio-gateway` |
-| `nio ai` diz `precisa de um terminal interativo` | você está num pipe/CI — rode num terminal de verdade |
-| `nio ai` travado em "processando" | `Esc` aborta o turno; o motor recupera permissão perdida sozinho em ~4s. Persistiu? `NIO_DEBUG=1 nio ai` e veja `~/.nio/tui.log` |
-| `nio ai` cai na TUI do OpenCode | falta o binário `opencode` no PATH — `npm i -g opencode-ai` |
-| Skills não aparecem no Cowork | chegam como **prompts MCP** (slash-commands), não skills autônomas. Cmd+Q e reabra; confirme o conector |
-| `Conteúdo de skills não encontrado` | cache `~/.nio/skills` vazio — rode `nio sync` com rede, ou `NIO_SKILLS_DIR` pra um checkout local |
-
-Sempre: `nio debug` mostra o estado de tudo com uma dica por item. E
-`NIO_DEBUG=1 nio <cmd>` liga log verboso (`[nio:debug]` em stderr): `.env`
-carregados, config resolvida, requests pro gateway, e stack trace completo nos erros.
-
-O logo Matrix anima (chuva caindo) toda vez que aparece em terminal interativo.
-`NIO_NO_ANIM=1` deixa ele sempre estático; fora de TTY (pipe/CI) já é estático.
-
----
-
-## Convenções
-
-- **Idioma:** UI/CLI em pt-BR. Código (variáveis, funções, tipos) em inglês.
-- **Backups:** toda escrita em config existente gera `.bak.<timestamp>` ao lado.
-- **stdout reservado pro JSON-RPC** no MCP server — logs vão pra stderr.
-- **Regra do hexágono:** `core/ports.ts` / `core/repositories.ts` não importam
-  driver de banco; os adapters (`adapters/*`) implementam os contratos.
-- **Migrations:** fonte da verdade em `db/schema.sql`; deltas incrementais em
-  `db/migrations/NNNN_*.sql`, aplicados à mão (`psql -f`).
-
----
-
-## Versão
-
-**0.5.0** — a interface do `nio ai` (TUI) fechada: editor multi-linha, fluxo em
-linha estilo Claude Code (raciocínio, ferramentas, checklist, diff, tokens),
-`Tab` troca de modo, paleta `/` executável, fila de permissões (com recuperação
-de pedido perdido de sub-agente), perguntas e menus de opção. Mais o fix da cauda
-de 30s no shutdown que tocava o Postgres.
-
-Base (0.2.0–0.4.0): auth (senha + 2º fator SMS OTP), backend de sessões no
-Postgres, wizard de ambiente, tools MCP, camada Docker, gateway com Kong e a
-auditoria de segurança (argon2id + pepper, HIBP k-anonymity, roles de menor
-privilégio). Nasceu de um cliente NOS/Supabase (v1), já removido.
-
-Histórico cronológico: [`docs/PROGRESSO.md`](docs/PROGRESSO.md).
+<!-- TOOLS:END -->
+
+### Recipes de ambiente (repo NIO-SKILLS)
+
+Além dos 6 perfis fixos, o repo `NIO-SKILLS-` pode carregar **recipes** em
+`recipes/<slug>.md` — presets nomeados (`profile` + linguagens + frameworks +
+MCPs + envVars/aliases) que **estendem** um perfil, editáveis sem release da CLI.
+O `nio init` oferece a recipe depois do perfil; `nio_session_create` aceita
+`{ recipe: "<slug>" }`. Merge determinístico (recipe vence em envVars/aliases;
+união em linguagens/frameworks/MCPs).
+
+---
+
+## Skills, commands e dependências
+
+Além das tools, o nio entrega **skills, commands e agents** pros clientes. O conteúdo
+vive num **repo aberto** — [`hugoreiis12-png/NIO-SKILLS-`](https://github.com/hugoreiis12-png/NIO-SKILLS-) —
+e **não** é um pacote npm. O CLI baixa o repo (zipball do GitHub, sem precisar de `git`)
+pra um cache local em **`~/.nio/skills`** e lê de lá. `nio sync` **atualiza o cache**
+(pull da branch) toda vez, então as skills evoluem sem republicar o CLI; e **auto-detecta**
+se o OpenCode tem o conector `nio` configurado, provisionando pra ele conforme a seleção
+de perfil/área do `nio.json`.
+
+Overrides por ambiente:
+
+| Variável              | Efeito                                                              |
+| --------------------- | ------------------------------------------------------------------ |
+| `NIO_SKILLS_DIR`   | Aponta pra um checkout local do repo (dev) — vence tudo            |
+| `NIO_SKILLS_REPO`  | Outro `owner/repo` (default `hugoreiis12-png/NIO-SKILLS-`)           |
+| `NIO_SKILLS_REF`   | Outra branch/tag (default `main`)                                  |
+
+Cada cliente recebe no formato que entende:
+
+| Cliente         | Onde                          | Formato                                                                 |
+| --------------- | ----------------------------- | ----------------------------------------------------------------------- |
+| OpenCode        | `~/.config/opencode/`         | MCP `nio` registrado no `opencode.json`; skills/commands no layout cru do pacote (`skills/<id>/SKILL.md`) |
+| Cowork/Desktop  | —                             | via **MCP prompts** + resources, servidos ao vivo                       |
+
+> **Como aparecem no Cowork/Claude Desktop.** Lá as skills chegam como **prompts MCP**,
+> que o app expõe como **slash-commands** no menu de conectores/"+" (ex.: digite `/` e
+> procure os itens do nio) — são **invocados manualmente**, não carregados sozinhos
+> como Agent Skills que o modelo detecta e usa por conta própria. Se não aparecerem:
+> feche o app de vez (Cmd+Q) e reabra, e confirme que o conector nio está conectado.
+
+### Visibilidade por cliente
+
+Um doc pode ser restrito a clientes específicos via frontmatter:
+
+```yaml
+clients: cowork, opencode   # vazio/ausente = todos os clientes
+```
+
+Valores: `cowork`, `opencode`. O MCP filtra por esse campo, então um skill
+marcado `cowork` só aparece como prompt no Cowork/Desktop, e um `opencode` só
+nos docs provisionados ao operador OpenCode.
+
+### Dependências externas
+
+Commands/skills podem depender de libs externas, declaradas como arquivos em
+`dependencies/` no repo de skills (a presença do arquivo é a declaração). No fim do
+`init`/`sync`, a CLI lista cada uma e:
+
+- **instalador estruturado** (`npm:`, `skills:` = `npx skills add`, `git:`) → oferece
+  rodar com `[y/N]` (comando montado a partir do campo validado, **sem shell**);
+- **`manual:`** (sem instalador automatizável — checagem/UI no cliente) → imprime os
+  passos, com os comandos destacados.
+
+A string `install:` (se houver) é **só exibição** — nunca é executada. A CLI **detecta
+o que já está instalado** e mostra um selo `✓ instalada` (via `npm ls -g`, dir de
+destino, ou o `detect:` do frontmatter).
+
+---
+
+## Claude Desktop / Cowork
+
+O Cowork/Claude Desktop é um cliente de **chat** via MCP — as skills chegam como
+**prompts MCP** servidos ao vivo, e o conector vive no `claude_desktop_config.json`
+com caminhos absolutos (`node` + `dist/mcp-server.js`) e `NIO_CLIENT=cowork`. Ele
+**não** é mais um alvo do `nio init` (o checkbox só oferece OpenCode): o setup
+inicial do conector é manual. O `nio sync` **reafirma** esse config quando o conector
+já existe — com o app instalado e você logado (`nio login`), ele reescreve o entry
+com paths atuais (merge não-destrutivo + backup). Reinicie o Claude Desktop pra
+carregar prompts novos depois do sync.
+
+---
+
+## Atualizando
+
+```bash
+npm i -g @nio-cli/cli@latest
+```
+
+O `nio sync` **checa a versão publicada** no início e **oferece atualizar** ali mesmo
+(com sua confirmação). `nio sync --yes` aceita sem prompt. A CLI também avisa em
+background em qualquer comando (`update-notifier`).
+
+---
+
+## Troubleshooting
+
+| Sintoma | Causa provável / o que fazer |
+|---|---|
+| `nio: command not found` | `npm i -g @nio-cli/cli` e confira `npm bin -g` no PATH |
+| `Configuração necessária` / `NIO_DATABASE_URL não definida` | rode `nio config setup` (ou deixe o `nio init` abrir o wizard) |
+| `Não consegui falar com o nio-gateway` | o `nio-gateway` não está no ar — rode `nio-gateway &` |
+| `Não autenticado` | `nio register` (1ª vez) e depois `nio login` |
+| Erro de conexão com o banco | `ECONNREFUSED` = Postgres fora do ar / host errado; `password authentication failed` = credencial; erro de SSL = `NIO_DATABASE_SSL=true` |
+| `2FA não configurado no servidor` (503) | faltam as `WHATSAPP_*` no ambiente do `nio-gateway` |
+| `nio ai` diz `precisa de um terminal interativo` | você está num pipe/CI — rode num terminal de verdade |
+| `nio ai` travado em "processando" | `Esc` aborta o turno; o motor recupera permissão perdida sozinho em ~4s. Persistiu? `NIO_DEBUG=1 nio ai` e veja `~/.nio/tui.log` |
+| `nio ai` cai na TUI do OpenCode | falta o binário `opencode` no PATH — `npm i -g opencode-ai` |
+| Skills não aparecem no Cowork | chegam como **prompts MCP** (slash-commands), não skills autônomas. Cmd+Q e reabra; confirme o conector |
+| `Conteúdo de skills não encontrado` | cache `~/.nio/skills` vazio — rode `nio sync` com rede, ou `NIO_SKILLS_DIR` pra um checkout local |
+
+Sempre: `nio debug` mostra o estado de tudo com uma dica por item. E
+`NIO_DEBUG=1 nio <cmd>` liga log verboso (`[nio:debug]` em stderr): `.env`
+carregados, config resolvida, requests pro gateway, e stack trace completo nos erros.
+
+O logo Matrix anima (chuva caindo) toda vez que aparece em terminal interativo.
+`NIO_NO_ANIM=1` deixa ele sempre estático; fora de TTY (pipe/CI) já é estático.
+
+---
+
+## Convenções
+
+- **Idioma:** UI/CLI em pt-BR. Código (variáveis, funções, tipos) em inglês.
+- **Backups:** toda escrita em config existente gera `.bak.<timestamp>` ao lado.
+- **stdout reservado pro JSON-RPC** no MCP server — logs vão pra stderr.
+- **Regra do hexágono:** `core/ports.ts` / `core/repositories.ts` não importam
+  driver de banco; os adapters (`adapters/*`) implementam os contratos.
+- **Migrations:** fonte da verdade em `db/schema.sql`; deltas incrementais em
+  `db/migrations/NNNN_*.sql`, aplicados à mão (`psql -f`).
+
+---
+
+## Versão
+
+**0.5.0** — a interface do `nio ai` (TUI) fechada: editor multi-linha, fluxo em
+linha estilo Claude Code (raciocínio, ferramentas, checklist, diff, tokens),
+`Tab` troca de modo, paleta `/` executável, fila de permissões (com recuperação
+de pedido perdido de sub-agente), perguntas e menus de opção. Mais o fix da cauda
+de 30s no shutdown que tocava o Postgres.
+
+Base (0.2.0–0.4.0): auth (senha + 2º fator SMS OTP), backend de sessões no
+Postgres, wizard de ambiente, tools MCP, camada Docker, gateway com Kong e a
+auditoria de segurança (argon2id + pepper, HIBP k-anonymity, roles de menor
+privilégio). Nasceu de um cliente NOS/Supabase (v1), já removido.
+
+Histórico cronológico: [`docs/PROGRESSO.md`](docs/PROGRESSO.md).