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 (provider dedicado nio-local/Qwen vLLM, 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 está dormente — 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.

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:

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 — 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ê.

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):

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):

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ó:

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):

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/ (uma ARQUITETURA-*.md por camada).

Perfis

Fixos no fonte (src/core/types.ts) — novos perfis só entram alterando o código:

fullstack · analyst · scientist · dba · qa · bi

Autenticação

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).

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: 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 um provider dedicado nio-local (OpenAI-compatível, aponta direto pro backend Qwen vLLM interno via NIO_AI_BASE_URL), junto do model: nio-local/<model-id>, do MCP nio, dos MCPs do perfil e de um bloco permission semeado (allowlist só-leitura → allow, resto → ask). O provider opencode (Zen) não é tocado — fica no default big-pickle, fora da competência da CLI. Headroom está dormente: 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 de fato é o provider nio-local; o OpenCode entra só como runtime (serve/SDK), 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-TUI-UX-SPRINTS.md e docs/arch/ARQUITETURA-TUI-INTERACOES-MOTOR.md.

Interface do nio ai (TUI)

Chat no terminal (Ink) sobre o motor nio-local (via runtime OpenCode), 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. 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.

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.

| Comando | Descrição | | --- | --- | | agents | Lista os agentes disponíveis | | ai | Abre a interface NIO da sessão ativa (opencode serve headless + chat Ink) | | ai status | Estado do Headroom (proxy de compressão — dormente, cliente fala direto no LLM) | | command [name] | Cria um comando personalizado pro operador de IA | | completion [shell] | Imprime o script de autocomplete (bash|zsh|fish). | | config | Config compartilhada da equipe (~/.nio/config.env) | | config check | Confere se a config está completa e o Postgres responde | | config path | Imprime o caminho do arquivo de config | | config setup | Wizard: cola os valores do time, testa a conexão e salva | | debug | Diagnostica o ambiente e aponta onde está o problema | | deps | Detecta e (opt-in) instala dependências da sessão ativa | | deps scan | Escaneia os manifests uma vez e registra o que falta | | deps watch | Escaneia a cada 10s até Ctrl+C | | docker | Camada Docker: stack NIO, compose, debug e cluster (Swarm) | | docker cluster <action> [arg] | Docker Swarm — stack nio-cluster (up|down|status|scale) | | docker compose <action> [service] | Wrapper sobre docker compose do projeto (up|down|restart|ps|logs) | | docker create | Cria e sobe um container (wizard ou flags) | | docker debug [container] | Coleta o contexto de um container e entrega o diagnóstico pro operador de IA | | docker headroom | Proxy de compressão de contexto — dormente, opcional pro nio ai | | docker headroom down | Derruba o container do Headroom | | docker headroom status | O Headroom está no ar? | | docker headroom up | Sobe o container do Headroom | | docker orquest [instruction] | Orquestra os serviços do projeto via compose, dirigido pelo operador (linguagem natural) | | docker portainer | Abre o Portainer no navegador | | docker stack | Stack NIO unificado (gateway · kong · headroom · mcp · portainer) — docker/docker-compose.yml | | docker stack down | Derruba o stack inteiro | | docker stack status | ps + health dos 5 serviços | | docker stack up | Sobe o stack inteiro (build do gateway) + registra o MCP | | docker toolkit | Infra NIO: Docker MCP Gateway + Portainer (docker/docker-compose.yml) | | docker toolkit down | Derruba a infra e desabilita o MCP no opencode.json | | docker toolkit status | Estado dos containers + health dos endpoints | | docker toolkit up | Sobe a infra e registra o gateway no opencode.json | | docs | Documentação completa da CLI (terminal ou página com --html) | | exec | Delega a implementação ao Qwen (vLLM local) num worktree e aguarda. | | exec-status <jobId> | Estado de um job de execução (nio exec), em JSON | | init | Cria nio.json no diretório atual e materializa o ambiente da sessão | | lang | Conhecimento/config das linguagens (nio-lang) | | lang sync | Baixa/atualiza o cache de conhecimento das linguagens em ~/.nio/lang | | login | Autentica via nio-gateway (túnel HTTP) e salva a sessão localmente (JWT) | | logout | Encerra a sessão local e revoga a auth_session no banco | | open | Abre a IDE da sessão ativa na pasta do projeto | | plan | Roda o Qwen (vLLM local) sobre o projeto e escreve/refina o plan.md da raiz. | | register | Cria um novo usuário via nio-gateway e já entra (login) | | security | Senha e 2º fator do login (WhatsApp OTP + códigos de backup) | | security change-password | Troca a senha (exige a senha atual) e encerra todas as sessões | | security disable-2fa | Desativa o 2º fator | | security enable-2fa | Ativa o 2º fator via WhatsApp | | security regenerate-backup-codes | Invalida os códigos de backup e gera 10 novos | | security status | Mostra o estado do 2º fator | | sessions | Gerencia as sessões de ambiente (list/activate/pause/delete) | | sessions activate <id> | Ativa uma sessão (arquiva as demais ativas) | | sessions delete <id> | Remove uma sessão (irreversível) | | sessions list | Lista as suas sessões | | sessions pause <id> | Pausa uma sessão | | skills | Skills, commands e agents do nio (lidos do repo aberto via cache) | | skills status | Lista os docs do repo de skills (cache local ~/.nio/skills) | | start | Conduz a esteira: config → gateway → login → sessão → OpenCode | | 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 |

Diagnóstico da própria CLI

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:

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.

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 que espelham o CLI — prefixo nio_

| Operação | O que faz | | --- | --- | | delegate_exec | Delega a IMPLEMENTAÇÃO ao Qwen (vLLM local, via API — sem assinatura nem binário externo) num worktree já criado pelo /implement. | | env_detect_deps | Roda UM ciclo do watcher de dependências sobre a pasta da sessão: escaneia os manifests (package.json, requirements.txt, Cargo.toml), detecta o que está declarado mas não instalado e registra um evento por dependência nova (idempotente). | | env_materialize | Re-materializa o ambiente de uma sessão existente a partir do seu perfil: garante os toolchains de novo, re-resolve os MCPs e reescreve o config em sessions.config. | | exec_status | Estado de uma execução delegada (nio_delegate_exec): running | done | failed, com o resumo do agente, os arquivos alterados e os checks determinísticos (tamanho, lint, build, testes). | | plan | Roda o Qwen (vLLM local, via API) sobre a raiz do projeto e escreve/refina o plan.md de rascunho pré-SDD. | | profile_get | Consulta o catálogo de perfis de ambiente (hardcoded na CLI). | | session_activate | Ativa uma sessão de ambiente do usuário por id (o prefixo do UUID basta). | | 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. |

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- — 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:

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

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.11.2 — desde a 0.5.0 (interface do nio ai fechada: editor multi-linha, fluxo em linha estilo Claude Code, Tab troca de modo, paleta /, fila de permissões, perguntas e menus de opção), entraram: isolamento de MCP por perfil (menos schema por request), map-reduce/token budget pra input grande, roles de banco com privilégio mínimo (db_roles), 2º fator migrado de SMS pra WhatsApp Business API, e hardening contínuo de auth (JWT com rotação de kid, revogação de sessão, breach-check). Histórico completo: git log.

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.