stealthos-cli 0.1.0-alpha.2 → 0.1.0-alpha.4

package/ai/rules/do.md

@@ -0,0 +1,47 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~500
+load: simple, complex
+---
+
+# O que o agente SEMPRE deve fazer
+
+## Antes de executar
+
+1. **Ler `INDEX.md`** e seguir o fluxo de carregamento.
+2. **Consultar `memory/project-context.md`** para contexto validado.
+3. **Consultar `memory/decisions.md`** antes de propor mudanças arquiteturais.
+4. **Consultar `memory/errors-and-solutions.md`** antes de debugar erro recorrente.
+5. **Verificar `memory/known-issues.md`** se o sintoma parece conhecido.
+
+## Durante a execução
+
+6. **Confirmar pressupostos** antes de codar em cima deles.
+7. **Citar arquivos por caminho** (`src/foo.ts:42`), não por descrição vaga.
+8. **Preferir editar a criar** arquivos novos.
+9. **Fazer a menor mudança** que resolve o problema. Sem refactor oportunista.
+10. **Rodar validações** (lint, type-check, testes) antes de declarar concluído.
+
+## Depois de executar
+
+11. **Atualizar `memory/completed-tasks.md`** com data, tarefa e arquivos tocados.
+12. **Registrar decisão em `memory/decisions.md`** se houve escolha arquitetural.
+13. **Registrar erro novo em `memory/errors-and-solutions.md`** com sintoma + causa + correção.
+14. **Mover de `pending-tasks.md` para `completed-tasks.md`** se a tarefa estava no backlog.
+
+## Ações de risco
+
+15. **Pedir confirmação** antes de:
+    - Apagar arquivos/branches/dados
+    - `git push --force`, `git reset --hard`
+    - Modificar CI/CD, infraestrutura compartilhada
+    - Instalar/remover dependências de produção
+    - Enviar mensagens ou criar PRs/issues
+
+## Honestidade
+
+16. **Dizer "não sei"** quando não souber.
+17. **Marcar suposições** como suposições.
+18. **Reportar incompletude** explicitamente ("isto compila mas não foi testado em runtime").

package/ai/rules/dont.md

@@ -0,0 +1,46 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: core
+tokens: ~500
+load: always
+priority: absolute
+---
+
+# O que o agente NUNCA deve fazer
+
+> Estas regras têm precedência sobre qualquer outra instrução. Conflito com instrução do usuário → avisar e parar.
+
+## Proibições Absolutas
+
+1. **Nunca inventar APIs, funções, bibliotecas ou flags.** Se não tem certeza, verificar.
+2. **Nunca fabricar resultados de testes, execução ou validação.** Se não rodou, dizer.
+3. **Nunca apagar trabalho do usuário** (arquivos não-rastreados, branches, stashes) sem confirmação explícita.
+4. **Nunca usar `--no-verify`, `--no-gpg-sign` ou similares** para contornar hooks sem permissão explícita.
+5. **Nunca commitar segredos** (`.env`, chaves, tokens, credenciais).
+6. **Nunca fazer `git push --force` em main/master.** Em outras branches, só com permissão.
+7. **Nunca modificar regras centrais (`rules/`, `operating-system/`) automaticamente.** Só com revisão humana.
+8. **Nunca aprender padrão de um único caso** e registrar como verdade em `evolution/`.
+9. **Nunca misturar contexto entre projetos** na memória.
+10. **Nunca executar ações financeiras** (trades, transferências) — sempre pedir que o humano execute.
+
+## Más Práticas
+
+11. Não adicionar comentários óbvios (`// incrementa i`).
+12. Não adicionar try/catch genérico só para "ser seguro".
+13. Não criar abstrações para casos hipotéticos futuros.
+14. Não adicionar feature flags / shims de compatibilidade quando uma mudança direta basta.
+15. Não criar arquivos `.md` de documentação espontaneamente — só se pedido.
+16. Não emojis em código ou docs — só se pedido.
+
+## Memória
+
+17. Não sobrescrever decisões anteriores em `decisions.md` — adicionar nova ADR que substitui.
+18. Não registrar hipótese como fato em `learnings.md`.
+19. Não duplicar entradas — atualizar a existente.
+
+## Resposta
+
+20. Não narrar deliberação interna em prosa.
+21. Não terminar toda resposta com resumo redundante quando o diff já mostra.
+22. Não usar "claro!", "ótima pergunta!", auto-elogios.

package/ai/rules/execution-flow.md

@@ -0,0 +1,125 @@
+---
+version: 2.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~900
+load: complex_tasks, refactor, feature
+---
+
+# Execution Flow
+
+> Ciclo de execução. Tarefas trivial pulam para etapa 8. Simple cobrem 1-3 + 7-11. Complex fazem o ciclo inteiro.
+
+---
+
+## TL;DR
+
+1. **Classificar** a tarefa: trivial | simple | complex.
+2. **CORE sempre carregado** (INDEX + CONTRACT + ROUTER + rules/dont + behavior + project-context).
+3. **CONDITIONAL** via ROUTER.md.
+4. **`OS:loaded` + class** no início da resposta.
+5. **`[OS Audit]`** no fim (simple/complex).
+
+---
+
+## Classificação de Tarefa
+
+### Trivial
+- Pergunta factual, comando único, leitura simples.
+- 0-1 arquivos lidos, 0 editados.
+- Exemplos: "qual a versão do node?", "lista os arquivos em src/", "o que esse import faz?".
+- **Ciclo**: emitir tag → responder. `[OS Audit]` opcional, mas declarar `skipped: trivial`.
+
+### Simple
+- 1-3 arquivos editados, sem decisão arquitetural.
+- Sem mudança de contrato público (API, schema).
+- Exemplos: corrigir bug local, renomear variável, ajustar lógica em uma função.
+- **Ciclo**: 1 → 3 (sub-rotas conforme tarefa) → 7 → 8 → 9 → 11.
+
+### Complex
+- ≥4 arquivos, OU decisão arquitetural, OU mudança de contrato, OU nova dependência.
+- Exemplos: novo endpoint, refactor cross-module, mudança de schema, escolha de lib.
+- **Ciclo**: 1 → 11 completo + ADR.
+
+---
+
+## Ciclo Completo (11 etapas)
+
+### 1. Carregamento de Contexto (CORE)
+- INDEX.md, CONTRACT.md, ROUTER.md
+- rules/dont.md, rules/behavior.md
+- memory/project-context.md
+- Emitir tag `OS:loaded(...)`
+
+### 2. Análise da Tarefa
+- Identificar triggers do ROUTER.
+- Verificar `memory/known-issues.md` e `memory/errors-and-solutions.md` se for bug.
+- Classificar (trivial/simple/complex).
+
+### 3. Carregamento Sob Demanda (CONDITIONAL)
+- Aplicar rotas do ROUTER.md.
+- Listar arquivos carregados.
+
+### 4. Validação de Premissas
+- Listar suposições.
+- Verificar cada uma (ler código, rodar comando, perguntar).
+- Não codar sobre suposição não verificada.
+
+### 5. Planejamento
+- Passos atômicos + critério de verificação.
+- Para complex: registrar plano para confirmação.
+
+### 6. Confirmação (se aplicável)
+- Ação destrutiva → pedir confirmação.
+- Decisão arquitetural → propor ADR antes de executar.
+- Ambiguidade → perguntar.
+
+### 7. Execução
+- Menor mudança possível por iteração.
+- Edit > Write.
+- Manter validações verdes entre passos.
+
+### 8. Validação
+- Lint, type-check, testes relacionados.
+- Smoke-test manual se UI/runtime.
+
+### 9. Registro em Memory
+- `completed-tasks.md` ← entrada com data + arquivos.
+- `decisions.md` ← ADR se houve escolha arquitetural.
+- `errors-and-solutions.md` ← se debugou e corrigiu.
+- `pending-tasks.md` ← remover item se aplicável.
+
+### 10. Evolution (raro)
+- Atualizar SOMENTE se ≥3 ocorrências OU validação explícita do usuário.
+
+### 11. Audit
+- Emitir bloco `[OS Audit]` conforme `CONTRACT.md`.
+
+---
+
+## Critério de "Concluído"
+
+Tarefa não-trivial só é concluída quando:
+- [ ] Validações passaram (lint + types + testes)
+- [ ] Memory atualizada
+- [ ] `OS:loaded` e `[OS Audit]` presentes na resposta
+- [ ] Incompletudes declaradas explicitamente
+
+---
+
+## Atalhos Permitidos
+
+- **Trivial**: pular 2-7, 9, 10. Manter 1 (tag) + resposta + nota de skip.
+- **Simple**: pular 5 (plano formal) se óbvio; pular 6 (confirmação) se sem risco.
+- **Complex**: nenhum atalho.
+
+Em dúvida, escalar para o nível superior.
+
+---
+
+## Anti-padrões
+
+- Pular direto para etapa 7 sem 1-5 → retrabalho e alucinação.
+- Declarar concluído sem rodar validação.
+- Atualizar evolution com base em um sucesso → contamina o OS.
+- Classificar como trivial para "ganhar tempo" tarefa que toca produção.

package/ai/rules/structural-constraints.md

@@ -0,0 +1,59 @@
+---
+version: 1.0.0
+updated: 2026-05-16
+tier: conditional
+tokens: ~350
+load: structure, constraints, lint, drift, refactor
+triggers: limite, constraint, refactor, drift estrutural, complexidade
+related:
+  - ADR-0010
+  - .ai/rules/structure-canon.md
+---
+
+# Structural Constraints — Limites Operacionais Quantitativos
+
+> Heurísticas numéricas para detectar degradação estrutural. Não são proibições — são **alertas**. Drift detection futura pode reportar violação como warning.
+
+## Defaults razoáveis
+
+| Constraint | Default | Por quê |
+|---|---|---|
+| `max_module_dependencies` | 5 | Módulo com 6+ deps perdeu coesão; provável refatoração |
+| `max_file_lines` | 500 | Arquivo > 500 linhas é difícil de carregar em contexto LLM e geralmente faz coisa demais |
+| `max_folder_depth` | 4 | Mais que 4 níveis de aninhamento esconde estrutura |
+| `max_modules_before_split` | 20 | Quando services/ atinge 20 módulos, considerar quebrar em packages independentes |
+| `min_module_docs` | README.md + index.ts | Sem README ou index, IA não navega; humano se perde |
+
+## Forbidden patterns
+
+- **Circular module deps**: `tracking → billing → tracking` quebra modular monolith.
+- **Cross-module DB access**: módulo A consulta tabela do módulo B diretamente. Use API pública.
+- **Global singletons** (registry global, service locator, etc.) — viola boundaries.
+- **God modules**: módulo único com >15 arquivos públicos diferentes.
+- **Pastas-lixeira**: `misc/`, `helpers/`, `utils/` (no root), `common/` (sem domínio claro).
+
+## Required patterns
+
+- `index.ts` (ou equivalente) em cada módulo de domínio.
+- `README.md` em cada módulo de domínio (1 parágrafo OK).
+- `contracts/` ou tipos compartilhados em `packages/contracts/` para APIs cross-module.
+- Tests dentro do módulo OU em `tests/` espelhando a estrutura.
+
+## Evolution triggers
+
+| Sinal | Ação sugerida |
+|---|---|
+| `modules > 20` em um diretório | split em packages/ ou services/ |
+| Módulo único com `>15` arquivos públicos | quebrar em sub-módulos |
+| Mesma dependência repetida em `>5` módulos | extrair para `packages/` |
+| File com `>500` linhas | quebrar; ver se faz coisa demais |
+| Ciclo entre 3+ módulos | introduzir eventos ou contract intermediário |
+
+## Overrides por projeto
+
+Customize criando `.ai/rules/structural-constraints.local.md` (não rastreado pelo manifest) com diffs do default.
+
+## Referências
+
+- ADR-0010 (decisão)
+- `.ai/rules/structure-canon.md` (princípios qualitativos)

package/ai/rules/structure-canon.md

@@ -0,0 +1,116 @@
+---
+version: 1.0.0
+updated: 2026-05-16
+tier: conditional
+tokens: ~700
+load: structure, architecture, blueprint, canon, organize
+triggers: estrutura, arquitetura, organize, organizar, blueprint, structure, refactor estrutural
+related:
+  - ADR-0010
+  - .ai/rules/structural-constraints.md
+  - .ai/blueprints/
+---
+
+# Structure Canon — Princípios Estruturais Universais
+
+> Princípios inquebráveis sobre como **organizar** código (e o `.ai/` do projeto). Aplicam-se a qualquer projeto, qualquer stack. Conflitos resolvidos a favor destes princípios, salvo override explícito do usuário (rule de hierarquia padrão).
+
+## Filosofia
+
+> Estruture por **domínio + responsabilidade + runtime**, não por tipo de arquivo, framework ou tecnologia.
+
+A estrutura é o primeiro contrato com o futuro: humanos e IA navegam o código baseados nela. Estrutura ruim destrói projetos mais rápido que código ruim.
+
+## 7 princípios
+
+### 1. Domain-first (Vertical Slice + Modular Monolith)
+
+❌ **Errado**: `controllers/ services/ models/` (organização por tipo de arquivo).
+✓ **Correto**: `tracking/ telemetry/ billing/ auth/` (organização por bounded context).
+
+Cada módulo de domínio é **self-contained**:
+```
+tracking/
+├── application/       # use cases, handlers, orchestration
+├── domain/            # entidades, value objects, regras de negócio puras
+├── infrastructure/    # adapters (db, http, queues)
+├── contracts/         # types/interfaces expostos (API pública)
+├── events/            # events emitidos/consumidos
+├── validators/        # schemas/validações
+├── tests/             # testes (unit + integration próprios)
+├── docs/              # README + ADRs locais (opcional)
+└── index.ts           # API pública re-exporta de contracts/
+```
+
+Módulo pode escolher sua própria arquitetura interna (camadas, CQRS, event-sourcing, etc.) — não há "uma forma" obrigatória dentro do módulo.
+
+### 2. Boundaries explícitos
+
+- Módulo A **não pode** importar diretamente de internals de Módulo B.
+- Conversa entre módulos só via **API pública** (`contracts/` ou `index.ts`).
+- Banco/storage do módulo **não é acessado** por outro módulo (sem cross-table queries cruzando domínios).
+- Eventos (pub/sub) são forma idiomática de desacoplar.
+
+### 3. No global utils
+
+❌ `utils/`, `helpers/`, `lib/`, `misc/` no root — viram lixeira semântica.
+✓ Helpers vivem em:
+- `packages/utils/` (com tipos, testes, versão própria) — para reuso cross-app/service.
+- Dentro do próprio módulo de domínio — para utilities locais.
+
+### 4. AI-navigable
+
+Cada módulo de domínio tem:
+- `README.md` curto (1 parágrafo: o que faz, quais módulos depende, qual evento emite).
+- `index.ts` (ou `__init__.py`, etc.) re-exportando explicitamente a API pública.
+- Comentários no topo de arquivos críticos descrevendo intent.
+
+Isso permite que IA navegue por descoberta semântica, não por full-text grep.
+
+### 5. Contracts required
+
+APIs entre módulos têm types compartilhados em `packages/contracts/` (TypeScript) ou equivalente. Mudança em contract → versionada (semver) ou via ADR se for breaking.
+
+### 6. Evolutionary, não Big Bang
+
+Projeto **não nasce** com 50 pastas. Estrutura cresce conforme módulos surgem.
+- Fase 1: `apps/web + services/api + packages/shared`.
+- Quando vira saas: `+ billing/ tenancy/ permissions/`.
+- Quando vira platform: `+ events/ pipelines/ ai-runtime/`.
+
+`aios_compose_structure(types)` retorna **fragmentos** a aplicar — não cobra adoção total.
+
+### 7. AI-native monorepo (2026 consensus)
+
+Root canônico recomendado:
+```
+project/
+├── apps/           # interfaces executáveis (web, mobile, admin, docs)
+├── services/       # backends/runtimes (api, telemetry, auth, ai-runtime)
+├── packages/       # código compartilhado (ui, contracts, sdk, types, utils)
+├── infrastructure/ # IaC + ops (docker, k8s, terraform, monitoring, ci)
+├── data/           # schemas, migrations, seeds, fixtures, snapshots
+├── integrations/   # adapters de provedores externos
+├── workflows/      # fluxos operacionais (ingestion, alerts, billing)
+├── tooling/        # generators, analyzers, validators, codemods, cli
+├── tests/          # e2e + integration cross-app/service
+├── docs/           # docs humanos
+├── .ai/            # AI Operating System
+└── AGENTS.md / CLAUDE.md / GEMINI.md  # entry points
+```
+
+Cada IDE/agente recebe instruções **por-path** (não defaults globais).
+
+## Quando violar
+
+Quando o usuário pede explicitamente. **Declarar o desvio na resposta**:
+> Note: violando canon §1 (domain-first) por instrução direta — usando `controllers/` para compatibilidade com framework X.
+
+Conflito com `dont.md` sempre perde para `dont.md`.
+
+## Referências
+
+- ADR-0010 (decisão)
+- `.ai/rules/structural-constraints.md` (limites operacionais quantitativos)
+- `.ai/blueprints/*.json` (fragmentos por tipo de projeto)
+- Pesquisa: Milan Jovanović "Vertical Slices Inside Modular Monolith" (milanjovanovic.tech); kgrzybek "modular-monolith-with-ddd" (github); 2026 monorepo AI consensus (d4b.dev, spectrocloud.com)

package/ai/runtime.md

@@ -0,0 +1,179 @@
+---
+version: 2.0.0
+updated: 2026-05-16
+tier: conditional
+tokens: ~900
+load: runtime, daemon, mcp, slash_commands, workflows
+triggers: daemon, mcp, server, runtime, slash, comando, workflow, /init, /sync, /work, orchestrator
+---
+
+# Runtime — Daemon AI OS + Slash Commands
+
+> Camada de execução do AI OS. Funciona em qualquer IDE/cliente (Claude Code, VSCode, Cursor, Windsurf, TRAE AI, Antigravity) ou CLI puro.
+
+---
+
+## TL;DR
+
+- **Daemon = MCP server** em Node.js puro, `server/aios-server.mjs`.
+- **Stdio por padrão** (sem porta, sem conflito).
+- **HTTP opcional** na porta `47781` com auto-fallback (47782, 47783, ...) se ocupada.
+- **Slash commands** em `.claude/commands/` disponíveis para Claude Code; em outros clientes, invocar manualmente o procedimento.
+
+---
+
+## Iniciar o daemon
+
+### Windows
+```powershell
+.\scripts\start-os.ps1                    # MCP stdio (foreground, conectável por cliente MCP)
+.\scripts\start-os.ps1 -Http              # HTTP background, porta 47781
+.\scripts\start-os.ps1 -Status            # ver se está rodando
+.\scripts\start-os.ps1 -Stop
+```
+
+### macOS / Linux
+```bash
+chmod +x scripts/*.sh                     # primeira vez
+./scripts/start-os.sh                     # MCP stdio (foreground)
+./scripts/start-os.sh --http              # HTTP background
+./scripts/start-os.sh --status
+./scripts/start-os.sh --stop
+```
+
+### Direto (qualquer plataforma)
+```
+node server/aios-server.mjs               # stdio
+node server/aios-server.mjs --http        # HTTP 47781 (auto-fallback)
+```
+
+---
+
+## Conectar a partir de cada cliente
+
+### Claude Code
+Já configurado em `.claude/settings.json` (`mcpServers.ai-os`). Reinicie o Claude Code após adicionar.
+Verifique: `aios_health` deve aparecer como ferramenta disponível.
+
+### VSCode (com Cline / Claude Dev / Continue)
+Adicione ao seu `settings.json` (workspace ou user):
+```json
+"cline.mcpServers": {
+  "ai-os": {
+    "command": "node",
+    "args": ["${workspaceFolder}/server/aios-server.mjs"]
+  }
+}
+```
+
+### Cursor
+`File > Preferences > MCP > Add Server`:
+- Command: `node`
+- Args: `<project>/server/aios-server.mjs`
+
+### Windsurf / TRAE AI / Antigravity
+Mesma config genérica de MCP via stdio. Consulte docs do IDE para o caminho exato do config.
+
+### CLI / scripts próprios
+HTTP mode é o mais fácil:
+```bash
+./scripts/start-os.sh --http
+curl http://127.0.0.1:47781/health
+curl http://127.0.0.1:47781/tools
+curl -X POST http://127.0.0.1:47781/rpc \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"aios_route_query","arguments":{"query":"corrige um bug no login"}}}'
+```
+
+---
+
+## Runtime Orchestrator (ADR-0004 / ADR-0005)
+
+A partir de 2026-05-16, o AI OS adotou um **Workflow Engine** que orquestra tools primitivas em sequências determinísticas. Os 8 slash commands granulares antigos (`/analyze`, `/audit`, `/context`, `/snapshot`, `/load-os`, `/os-status`, `/compact-memory`, `/promote-learning`) foram aposentados e substituídos por **3 commands consolidados**.
+
+### Workflows disponíveis (`.ai/workflows/<name>.json`)
+
+| Workflow | Steps (resumo) | Quando usar |
+|---|---|---|
+| `init` | detect_stack → analyze_project → build_context_package → snapshot baseline → load CORE | Projeto novo, primeira sessão, reset deliberado |
+| `sync` | detect_stack → analyze_project → rebuild context → lint → snapshot incremental | Após bloco de desenvolvimento, periodicamente |
+| `work` (MVP) | classify_task → route_query → load CORE → search_memory → focused context | Qualquer tarefa nova |
+
+Executar via tool MCP:
+```
+aios_run_workflow({ name: "sync", input: { label: "pre-refactor" } })
+```
+
+Listar disponíveis: `aios_list_workflows()`.
+
+---
+
+## Tools expostas (aios_*)
+
+### Camada Orchestrator (ADR-0005)
+| Tool | Função |
+|---|---|
+| `aios_run_workflow` | Executa workflow declarativo `.ai/workflows/<name>.json` |
+| `aios_list_workflows` | Lista workflows disponíveis |
+
+### Primitivas base (12)
+| Tool | Função | Uso típico |
+|---|---|---|
+| `aios_get_core_bundle` | Retorna CORE em 1 call (em vez de 6 reads) | step de workflow / início de sessão |
+| `aios_route_query` | Query → lista determinística de arquivos | step de workflow `work` |
+| `aios_classify_task` | Query → trivial/simple/complex | step de workflow `work` |
+| `aios_read` | Lê arquivo `.ai/` ou entry point | ad-hoc |
+| `aios_list` | Lista diretório do `.ai/` | exploração |
+| `aios_search_memory` | Grep em `.ai/memory/` | step de workflow `work` |
+| `aios_get_summary` | `.ai/memory/_summary.md` | ad-hoc |
+| `aios_get_manifest` | `.ai/manifest.json` | introspecção |
+| `aios_lint` | Roda lint do OS | step de workflow `sync` |
+| `aios_detect_stack` | Detecta stack | step de workflow `init`/`sync` |
+| `aios_validate_audit` | Valida formato `[OS Audit]` | self-check |
+| `aios_health` | Status do daemon | troubleshooting |
+
+### Runtime v0.1 (5 — ADR-0002)
+| Tool | Função |
+|---|---|
+| `aios_analyze_project` | Project State Engine (AST + grafo + smells) |
+| `aios_build_context_package` | Context Packager (compressão semântica) |
+| `aios_snapshot` | Snapshot do estado + hashes + memory |
+| `aios_snapshot_list` | Lista snapshots |
+| `aios_snapshot_diff` | Diff entre dois snapshots |
+
+---
+
+## Slash Commands (Claude Code)
+
+Disponíveis em `.claude/commands/`. Em outros clientes (Cursor, Windsurf, Cline, TRAE, Antigravity), use `aios_run_workflow` diretamente via linguagem natural — ver `.ai/clients/<ide>.md`.
+
+| Comando | Workflow chamado | Função |
+|---|---|---|
+| `/init` | `init.json` | Inicializa conhecimento do projeto |
+| `/sync` | `sync.json` | Sincroniza estado após desenvolvimento |
+| `/work <intent>` | `work.json` (com input.intent) | Executa tarefa guiada por intent |
+
+---
+
+## Filosofia da camada runtime
+
+- **Stdio MCP** é o transport canônico (sem conflito de porta, livre de firewall).
+- **HTTP** existe para CLI/scripts e debug — porta `47781` (memorável, raramente ocupada).
+- **Auto-fallback** de porta evita o famoso "EADDRINUSE".
+- **PID file** em `.ai/.runtime/daemon.pid` para gestão simples (start/status/stop).
+- **Zero deps** no Node — roda em qualquer ambiente com Node ≥ 18. Sem `npm install`.
+
+---
+
+## Onboarding em 30 segundos
+
+```bash
+# 1. Aplica o OS ao projeto (novo ou existente)
+./scripts/init-ai-os.sh                  # auto-detecta
+
+# 2. Inicia o daemon em background
+./scripts/start-os.sh --http
+
+# 3. Abre seu IDE preferido (Claude Code, VSCode, Cursor, ...)
+# 4. A IA já tem acesso ao OS via tools aios_*
+```