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

package/ai/bootstrap/existing-project.md

@@ -0,0 +1,191 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: on_demand
+tokens: ~900
+load: bootstrap_existing
+---
+
+# Bootstrap — Projeto Existente
+
+> Diálogo + análise para incorporar o AI OS a um projeto já em andamento.
+> Objetivo: descobrir o estado real do projeto SEM assumir — popular `memory/project-context.md` com fatos validados.
+
+---
+
+## TL;DR
+
+1. Pedir caminho do projeto.
+2. **Inspecionar antes de perguntar** (não pedir o que dá para descobrir lendo).
+3. Validar inferências com o usuário.
+4. Cobrir lacunas com perguntas direcionadas.
+5. **Rodar `bootstrap/tech-mapping.md`** para produzir `operating-system/architecture.md` organizado por especificação técnica (Frontend, Backend, BD, Infra, Integrações, Tools, APIs, MCPs, Dados, etc.). **Obrigatório** — sem isto o context fica raso.
+6. Popular `project-context.md` + criar ADR-0001 ("Adoção do AI OS").
+
+---
+
+## Passo 1 — Localizar e Inspecionar
+
+Pedir caminho:
+> "Onde está o projeto? Pode ser caminho local, URL de repositório, ou descrição da pasta."
+
+Após receber, executar **inspeção automática** (sem perguntar ao usuário ainda):
+
+### Detecção de stack
+
+| Arquivo presente | Conclusão |
+|---|---|
+| `package.json` | Node.js / JS / TS |
+| `tsconfig.json` | TypeScript |
+| `pyproject.toml` / `requirements.txt` / `setup.py` | Python |
+| `Cargo.toml` | Rust |
+| `go.mod` | Go |
+| `pom.xml` / `build.gradle` | Java / Kotlin |
+| `composer.json` | PHP |
+| `Gemfile` | Ruby |
+| `mix.exs` | Elixir |
+| `pubspec.yaml` | Dart / Flutter |
+| `*.csproj` / `*.sln` | .NET |
+
+### Detecção de framework (a partir de deps)
+
+- `react`, `next`, `vue`, `nuxt`, `svelte`, `solid` → frontend framework
+- `express`, `fastify`, `nest`, `koa` → Node backend
+- `django`, `fastapi`, `flask` → Python backend
+- `rails`, `sinatra` → Ruby backend
+- `spring`, `quarkus`, `micronaut` → Java backend
+
+### Detecção de infra
+
+- `Dockerfile` / `docker-compose.yml` → containerizado
+- `.github/workflows/` → GitHub Actions
+- `.gitlab-ci.yml` → GitLab CI
+- `terraform/` / `*.tf` → IaC
+- `kubernetes/` / `k8s/` / `*.yaml` com `kind:` → K8s
+- `serverless.yml` / `sam-template.yaml` → serverless
+
+### Detecção de testes
+
+- `**/*.test.*`, `**/*.spec.*`, `__tests__/`, `tests/` → existe suite
+- `jest.config.*`, `vitest.config.*`, `pytest.ini`, `cypress.config.*`, `playwright.config.*` → framework de teste
+
+### Detecção de DB
+
+- Buscar strings: `postgresql://`, `mysql://`, `mongodb://`, `redis://` em arquivos de config
+- ORMs nas deps: `prisma`, `typeorm`, `sequelize`, `sqlalchemy`, `mongoose`, `gorm`, `diesel`
+
+### Detecção de convenções
+
+- Há `.editorconfig` / `.prettierrc` / `eslint.config.*` / `ruff.toml` / `pyproject.toml [tool.*]`?
+- Há `CONTRIBUTING.md` / `STYLE.md`?
+- Estrutura de pastas: por feature ou por tipo?
+
+---
+
+## Passo 2 — Reportar Inferências
+
+O agente PROPÕE o que entendeu:
+
+```
+Inspeção do projeto em <caminho>:
+
+Stack detectada:
+- Linguagem: <X>
+- Framework: <Y>
+- DB: <Z> (via <ORM>)
+- Infra: <containerizada/serverless/bare>
+- CI/CD: <pipeline detectado ou "não encontrado">
+- Testes: <framework> com <N> arquivos de teste
+
+Convenções aparentes:
+- Lint: <ferramenta ou "não configurado">
+- Format: <ferramenta ou "não configurado">
+- Estrutura: <por feature / por tipo / híbrida>
+
+Lacunas que preciso confirmar:
+1. <pergunta específica>
+2. <pergunta específica>
+
+Pode confirmar/corrigir o que descobri e responder as lacunas?
+```
+
+---
+
+## Passo 3 — Perguntas Direcionadas (só o que NÃO dá para inferir)
+
+Q1 — **Objetivo de negócio**: para que serve, quem usa.
+Q2 — **Ambientes**: dev / staging / prod — URLs, branches por ambiente.
+Q3 — **Time**: quantas pessoas tocam, papéis.
+Q4 — **Compliance**: LGPD, GDPR, PCI, HIPAA?
+Q5 — **Restrições não-óbvias**: janelas de deploy, dependências de outros sistemas, dívidas conhecidas.
+Q6 — **Dor atual**: o que motivou trazer o OS? (bug recorrente, escala, novo dev entrando, qualidade...)
+
+---
+
+## Passo 4 — Detectar Dores Visíveis
+
+Durante inspeção, **registrar sinais de problema** para sugerir melhorias:
+
+| Sinal | Sugestão |
+|---|---|
+| Sem testes | Configurar suite mínima |
+| Sem CI | Pipeline básico |
+| `package-lock.json` desatualizado | Auditoria de deps |
+| `.env` commitado | Mover para cofre + rotacionar |
+| `node_modules` versionado | `.gitignore` |
+| Sem `README.md` ou stub | Setup local docs |
+| Imports relativos `../../../` profundos | Path aliases / restructure |
+| Funções >200 linhas | Sinalizar para refactor |
+| TODO/FIXME >50 ocorrências | Migrar para `pending-tasks.md` |
+| Arquivos `>1000` linhas | Sinalizar |
+
+Apresentar como **sugestões**, não imposição. Usuário escolhe.
+
+---
+
+## Passo 5 — Popular Memória
+
+Após validar com usuário, escrever em:
+
+### `memory/project-context.md`
+- Identificação, stack, ambientes, time, compliance, restrições.
+
+### `memory/decisions.md`
+- **ADR-0001**: "Adoção do AI Operating System em projeto existente" — data, motivação (vinda da Q6), escopo (quais partes do OS aplicam).
+
+### `memory/pending-tasks.md`
+- Cada sugestão aceita → uma task com prioridade.
+
+### `memory/known-issues.md`
+- Cada dor relatada que ainda não tem fix → uma entrada.
+
+### `operating-system/architecture.md`
+- **Aplicar `bootstrap/tech-mapping.md`** para gerar este arquivo. Estrutura mínima obrigatória: Frontend, Backend, BD, Infra/Deploy, Integrações Externas, Tools/Scripts, APIs (contratos), MCPs, Dados/Samples, Pendências de mapeamento. Omitir seções que não se aplicam.
+- Documentar arquitetura **real** observada (não a aspiracional). Trade-offs aceitos do legado vão para `decisions.md` ou ADRs específicas.
+
+### `operating-system/folder-structure.md`
+- Documentar estrutura existente. Se for ruim, marcar como "alvo de migração futura" em vez de mudar agora.
+
+### `operating-system/coding-standards.md`
+- Sincronizar com lint/format detectados. Não impor padrão novo sem ADR.
+
+---
+
+## Passo 6 — Critério de "Bootstrap Concluído"
+
+- [ ] `project-context.md` validado pelo usuário
+- [ ] ADR-0001 criado
+- [ ] Arquitetura real documentada
+- [ ] Pendências e issues catalogados
+- [ ] Sugestões aceitas viraram tasks ou ADRs
+- [ ] Usuário confirmou: "ok, agora vamos trabalhar"
+
+---
+
+## Anti-padrões em projeto existente
+
+- **Reescrever convenções** existentes sem ADR + acordo do time.
+- **Marcar tudo como dívida técnica** — escolher 1-3 alvos de cada vez.
+- **Aplicar regras genéricas** contra a realidade do projeto. Adaptar.
+- **Ignorar histórico**: ler `git log` recente para entender direção atual.
+- **Substituir documentação existente** silenciosamente — adicionar referência cruzada.

package/ai/bootstrap/new-project.md

@@ -0,0 +1,127 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: on_demand
+tokens: ~800
+load: bootstrap_new
+---
+
+# Bootstrap — Projeto Novo
+
+> Diálogo estruturado para começar um projeto do zero.
+> O agente conduz, o usuário responde, o resultado popula `memory/project-context.md` + cria estrutura inicial.
+
+---
+
+## TL;DR
+
+1. Descobrir **o que** o usuário quer construir (1 frase clara).
+2. Descobrir **para quem** e **escala esperada**.
+3. Recomendar stack + arquitetura inicial (com alternativas).
+4. Confirmar.
+5. Criar estrutura mínima + ADR-0001 (escolha de stack).
+
+---
+
+## Fluxo de Perguntas (em ordem, uma por vez)
+
+### Q1 — Visão em uma frase
+> "Em uma frase, o que esse projeto deve fazer e para quem?"
+
+Esperar resposta antes de prosseguir. Se vago ("um app de gestão"), pedir refinamento.
+
+### Q2 — Funcionalidades essenciais
+> "Liste 3-5 funcionalidades essenciais para a primeira versão. (Sem features 'opcionais' por enquanto.)"
+
+### Q3 — Usuários e escala
+> "Quem usa e quantos? (10 internos, 10k público, 1M+ ?)"
+
+Resposta influencia stack, infra, complexidade arquitetural.
+
+### Q4 — Restrições conhecidas
+> "Existe alguma restrição já dada? (linguagem obrigatória, cloud específica, prazo, compliance: LGPD/GDPR/PCI...)"
+
+### Q5 — Preferência ou liberdade
+> "Você tem preferência de stack ou prefere que eu recomende com base no que descrevemos?"
+
+---
+
+## Recomendação (após Q1-Q5)
+
+O agente PROPÕE com formato:
+
+```
+Com base no que você descreveu, recomendo:
+
+Stack:
+- Backend: <linguagem> + <framework>
+- Frontend: <framework>
+- DB: <db>
+- Infra inicial: <cloud/local>
+
+Por quê:
+- <razão 1, ligada à escala/feature>
+- <razão 2>
+
+Alternativas consideradas:
+- <alternativa A> — descartada porque <razão>
+- <alternativa B> — descartada porque <razão>
+
+Arquitetura inicial: monolito modular em camadas (Clean/Hexagonal).
+Justificativa: time pequeno + escala atual não justifica microserviços.
+
+Pode confirmar ou me dizer o que mudar?
+```
+
+---
+
+## Após Confirmação
+
+1. Registrar **ADR-0001** em `memory/decisions.md` com a stack escolhida.
+2. Preencher `memory/project-context.md` com:
+   - Visão
+   - Stack
+   - Escala alvo
+   - Restrições / compliance
+3. **Aplicar `bootstrap/tech-mapping.md`** para produzir `operating-system/architecture.md` organizado por especificação técnica (Frontend, Backend, BD, Infra, Integrações, Tools, APIs, MCPs, Dados, Pendências). No projeto novo o mapa começa com 1-2 itens por seção e cresce ao longo do desenvolvimento.
+4. Atualizar `operating-system/folder-structure.md` com a estrutura escolhida (ver convenção em `folder-structure.md` global).
+5. Criar **estrutura mínima de pastas e arquivos** (não código de funcionalidade ainda — só esqueleto). A estrutura deve respeitar as especificações técnicas mapeadas: cada especificação ganha sua pasta (ex.: `frontend/`, `backend/`, `infra/`).
+6. Criar **PEND-001** em `memory/pending-tasks.md`: "Implementar primeira feature (Q2 #1)".
+
+---
+
+## Sugestões Proativas
+
+O agente DEVE sugerir (mas não impor):
+- **Testes**: configuração mínima desde o dia 1.
+- **CI**: pipeline básico (lint + types + tests).
+- **`.env.example`** versionado.
+- **Pré-commit hooks** (lint, format).
+- **README.md** com setup local.
+- **`.gitignore`** apropriado à stack.
+- **Healthcheck endpoint** se backend.
+
+Listar as sugestões e perguntar quais aplicar antes de criar.
+
+---
+
+## Quando parar o bootstrap
+
+O bootstrap está "completo" quando:
+- [ ] `memory/project-context.md` preenchido.
+- [ ] ADR-0001 registrado.
+- [ ] `operating-system/architecture.md` populado via `bootstrap/tech-mapping.md` (mesmo que mínimo).
+- [ ] Estrutura de pastas criada, alinhada com as especificações técnicas mapeadas.
+- [ ] Primeira tarefa real está em `memory/pending-tasks.md`.
+
+A partir daí, o agente segue o fluxo normal de execução (`rules/execution-flow.md`).
+
+---
+
+## Anti-padrões em projeto novo
+
+- Escolher stack pelo "mais novo/hype" sem ligar à necessidade.
+- Microserviços para projeto solo / dia 1.
+- Cobertura 100% antes de escrever feature.
+- Configurar 10 ferramentas antes de uma linha de feature funcionar.
+- Pular ADR "porque é projeto pequeno" — projeto pequeno hoje pode crescer.

package/ai/bootstrap/tech-mapping.md

@@ -0,0 +1,164 @@
+---
+version: 1.0.0
+updated: 2026-05-14
+tier: conditional
+tokens: ~1200
+load: bootstrap_new, bootstrap_existing, architecture_review
+triggers: mapa tecnico, tech-mapping, especifica, arquitetura inicial, organizar projeto
+---
+
+# Tech-Mapping Protocol
+
+> **Etapa obrigatória do bootstrap** (tanto para projeto NOVO quanto EXISTENTE).
+> Objetivo: organizar tudo que o projeto contém em **especificações técnicas** + **subespecificações**, e materializar isso em `operating-system/architecture.md` do projeto.
+>
+> Sem este mapa, manutenção e onboarding ficam caros porque o agente (e humanos novos) precisam descobrir do zero onde mora cada coisa.
+
+---
+
+## TL;DR
+
+1. Identificar quais **especificações de alto nível** o projeto possui.
+2. Para cada uma, descobrir **subespecificações** (módulos, integrações, scripts).
+3. Materializar em [`operating-system/architecture.md`](../operating-system/architecture.md) com tabelas (arquivo · responsabilidade · dependências).
+4. Listar lacunas em uma seção `## 10. PENDÊNCIAS DE MAPEAMENTO` (até 10 itens).
+
+---
+
+## Catálogo de Especificações de Alto Nível
+
+Cada projeto contém um subconjunto destas:
+
+| # | Especificação | Quando se aplica | Subespecificações típicas |
+|---|---|---|---|
+| 1 | **Frontend** | Há UI (web, mobile, desktop) | Entry/build, Views/Pages, Components, Services (client-side), State management, Styling, i18n, Assets, Testes UI |
+| 2 | **Backend** | Há servidor/API | Entry, Middleware, Rotas, Modules/Domains, Workers/Jobs, Core/utils, Auth, Cache |
+| 3 | **Banco de Dados** | Há persistência | Engine, Schema/migrations, ORM/queries, Indexação, Extensões (PostGIS, pgcrypto...), Estratégia de backup |
+| 4 | **Infra / Deploy** | Há infra como código ou pipelines | Containers (Docker), Orquestração (K8s, Compose), CI/CD, IaC (Terraform), Envs e variáveis, Healthchecks |
+| 5 | **Integrações Externas** | Há sistemas de terceiros | Cada terceiro vira subespecificação: auth, client, contratos, fallbacks, credenciais |
+| 6 | **Tools / Scripts** | Há utilitários internos | npm scripts, scripts ad-hoc (operação/debug), workers/CLIs internos |
+| 7 | **APIs (contratos)** | Há contrato HTTP/gRPC/GraphQL públicos | Por endpoint: verbo, path, payload, response, owner |
+| 8 | **MCPs / Automação** | Há MCPs configurados | Cada MCP: nome, tools, escopo (workspace/global), settings.json refs |
+| 9 | **Dados / Samples** | Há datasets, fixtures, amostras grandes | Caminho, tamanho, propósito, status no gitignore |
+| 10 | **Mobile / Desktop / Game** | Aplicação nativa | Build per platform, deploy stores, etc. (especialização opcional) |
+| 11 | **ML / Pipelines de dados** | Há treino/inferência ou ETL | Modelos, datasets, pipelines, feature store |
+
+> **Não inventar** especificação que não existe no projeto. Se algo não se aplica, omitir. Se algo emergente não cabe em nenhuma das categorias acima, criar uma nova (com nome curto) e documentar.
+
+---
+
+## Subespecificações: como descobrir
+
+### Para cada especificação, o agente DEVE:
+
+1. **Listar arquivos/pastas** que pertencem a ela (via `ls`/`Glob`, não inventar).
+2. **Cruzar com imports/refs** — se um módulo importa algo, anotar dependência.
+3. **Detectar contratos** — tipos exportados, rotas, schemas SQL, enums.
+4. **Documentar pontos de extensão** — onde adicionar mais coisa do mesmo tipo (ex: "para adicionar um novo domínio backend, criar pasta `modules/<nome>/` com `routes.ts + service.ts`").
+
+### Tabela obrigatória por especificação
+
+```markdown
+| Item | Caminho | Responsabilidade | Dependências |
+|---|---|---|---|
+```
+
+---
+
+## Formato do `operating-system/architecture.md`
+
+```markdown
+# Arquitetura <NOME-DO-PROJETO> — Mapa Técnico por Especificação
+
+> Organização por especificação técnica. Cada bloco lista (a) onde no FS, (b) responsabilidade, (c) dependências externas, (d) pontos de extensão.
+
+## Visão de alto nível
+[diagrama ASCII simples mostrando o fluxo client → server → DB → integrações]
+
+## 1. FRONTEND
+### 1.1 Entry point e build
+### 1.2 Views / Pages
+### 1.3 Services
+### 1.4 Estado / Storage
+### 1.5 Estilos
+### 1.6 Testes UI
+
+## 2. BACKEND
+### 2.1 Entry point
+### 2.2 Middleware HTTP
+### 2.3 Rotas
+### 2.4 Modules / Domains
+### 2.5 Workers / Jobs
+### 2.6 Core e utilitários
+
+## 3. BANCO DE DADOS
+### 3.1 Infra
+### 3.2 Tabelas (ou collections, etc.)
+### 3.3 Extensões
+### 3.4 Conexão
+### 3.5 Recovery / Resiliência
+
+## 4. INFRA / DEPLOY
+### 4.1 Containers locais
+### 4.2 Variáveis de ambiente
+### 4.3 CI/CD
+### 4.4 Deploy real (URLs, hosts)
+
+## 5. INTEGRAÇÕES EXTERNAS
+### 5.1 <Integração 1>
+### 5.2 <Integração 2>
+...
+
+## 6. TOOLS / SCRIPTS
+
+## 7. APIs (contratos)
+
+## 8. MCPs / Automação
+
+## 9. DADOS / SAMPLES
+
+## 10. PENDÊNCIAS DE MAPEAMENTO
+- [ ] item curto
+- ...
+```
+
+> Omitir seções que não se aplicam ao projeto. Manter a numeração quando possível para consistência cross-project.
+
+---
+
+## Quando rodar
+
+| Momento | Ação |
+|---|---|
+| Bootstrap projeto novo | Após decidir stack (mas antes de codar), criar esqueleto com 1-2 itens por seção. Atualizar à medida que cresce. |
+| Bootstrap projeto existente | **Obrigatório** — popular com a realidade observada. Sem isso, `project-context.md` fica raso e o agente perde direção. |
+| Após adicionar módulo/integração | Atualizar a seção correspondente. |
+| Antes de refator grande | Reler — o mapa freia mudanças mal-fundamentadas. |
+| Auditoria trimestral | Validar que o mapa ainda reflete o código. Promover pendências da seção 10. |
+
+---
+
+## Anti-padrões
+
+- **Mapa aspiracional**: descrever o que "deveria ser" em vez do que **é**. O mapa é descritivo, não normativo. Diferença vai para `pending-tasks.md` ou ADR.
+- **Inventar especificações** que não existem para "ficar completo" — gera ruído.
+- **Listar arquivos sem responsabilidade** — uma tabela sem coluna "Responsabilidade" não vale o token gasto.
+- **Diagramas elaborados** demais — ASCII simples é suficiente; um diagrama complicado fica desatualizado e ninguém edita.
+- **Não atualizar nunca** — vira fóssil. Toda PR que toca arquitetura deveria ter linha "Atualiza architecture.md ✓".
+
+---
+
+## Checklist do agente ao gerar
+
+- [ ] Cada seção foi inferida do FS real (não inventada).
+- [ ] Cada arquivo citado existe (checar com `Read` ou `Glob`).
+- [ ] Cada integração externa tem variável de ambiente correspondente em `.env.example`.
+- [ ] Pendências de mapeamento (seção 10) listadas com ações concretas.
+- [ ] Referência cruzada para `memory/project-context.md` (e vice-versa) presente.
+- [ ] Trade-offs e decisões aparecem como **referência a ADRs**, não inline.
+
+---
+
+## Promoção / Evolução
+
+Se padrões emergem repetidamente em vários projetos (3+) — exemplo: "todo backend Strak-like tem `core/infra/modules/workers`" — promover via `/promote-learning` para `operating-system/folder-structure.md` global.

package/ai/clients/README.md

@@ -0,0 +1,114 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: on-demand
+purpose: Catalog of AI OS adapters for each IDE/CLI
+---
+
+# AI OS Clients — Catálogo
+
+Este diretório documenta como ativar o AI Operating System em cada IDE/CLI suportada. Cada doc inclui: capability matrix, ativação em 3 passos, snippet completo, validação, troubleshooting.
+
+A estratégia uniforme é: **stub na raiz** (formato que a IDE auto-carrega) + **config MCP** (quando suportado) apontando para `.ai/server/aios-server.mjs`.
+
+## Capability Matrix
+
+| IDE / CLI | Entry-point | MCP | Hooks | Doc |
+|---|---|---|---|---|
+| Claude Code | `CLAUDE.md` | sim (`.claude/settings.json`) | sim (3 hooks) | [claude-code.md](./claude-code.md) |
+| Cursor | `.cursorrules` + `.cursor/rules/ai-os.mdc` | sim (`.cursor/mcp.json`) | — | [cursor.md](./cursor.md) |
+| Windsurf (Cascade) | `.windsurfrules` | sim (global) | — | [windsurf.md](./windsurf.md) |
+| Cline (VSCode) | `.clinerules` | sim (global VSCode) | — | [cline.md](./cline.md) |
+| Continue (VSCode/JetBrains) | `.continue/rules/ai-os.md` | sim (`config.yaml`) | — | [continue.md](./continue.md) |
+| GitHub Copilot (VSCode) | `.github/copilot-instructions.md` | **não** | — | [copilot.md](./copilot.md) |
+| TRAE (ByteDance) | `.trae/rules/project_rules.md` | sim (v1.3+) | — | [trae.md](./trae.md) |
+| Antigravity (Google) | `GEMINI.md` + `.gemini/settings.json` | sim | — | [antigravity.md](./antigravity.md) |
+| Gemini CLI | `GEMINI.md` + `.gemini/settings.json` | sim | — | [antigravity.md](./antigravity.md) |
+| Codex / Aider / Amp / Jules | `AGENTS.md` | varia | — | [codex-aider-cli.md](./codex-aider-cli.md) |
+
+## ❓ Runtime Orchestrator completo (ADR-0004 → ADR-0009): 3 commands + 34 tools
+
+Desde 2026-05-16 (RFC-0001 + RFC-0002), o AI OS é um **Runtime Operacional**: 3 commands consolidados (`/init`, `/sync`, `/work`) executam workflows determinísticos sobre 34 tools MCP, com state persistente, lifecycle, execution contracts, pause/resume, drift detection, runtime-context compilado e confidence system.
+
+**3 commands consolidados:**
+
+| Command | Workflow | Versão | Quando usar |
+|---|---|---|---|
+| `/init` | `.ai/workflows/init.json` | v3 (ramificado: discovery vs reverse-engineering) | Projeto novo, primeira sessão, reset deliberado |
+| `/sync` | `.ai/workflows/sync.json` | v3 (com compile + drift) | Após bloco de desenvolvimento, periodicamente, antes de pausar |
+| `/work` | `.ai/workflows/work.json` | v3 (com 2 pause-for-input: clarification + approval) | Qualquer tarefa nova |
+
+**8 commands antigos foram aposentados** (`/analyze`, `/audit`, `/compact-memory`, `/context`, `/load-os`, `/os-status`, `/promote-learning`, `/snapshot`) — viraram steps internos dos 3 workflows.
+
+### 34 tools MCP por camada
+
+| Camada | Tools |
+|---|---|
+| **Orchestrator** | `aios_run_workflow`, `aios_list_workflows`, `aios_resume_workflow`, `aios_list_paused_executions`, `aios_cancel_paused_execution` |
+| **Runtime State** | `aios_state_get`, `aios_state_set`, `aios_state_advance`, `aios_state_reset` |
+| **State Compiler / Context / Drift / Artifacts** | `aios_compile_runtime_context`, `aios_detect_drift`, `aios_get_context`, `aios_artifact_list` |
+| **Confidence** | `aios_confidence_get`, `aios_confidence_set`, `aios_confidence_assess` |
+| **Primitivas base (12)** | `aios_get_core_bundle`, `aios_route_query`, `aios_classify_task`, `aios_read`, `aios_list`, `aios_search_memory`, `aios_get_summary`, `aios_get_manifest`, `aios_lint`, `aios_detect_stack`, `aios_validate_audit`, `aios_health` |
+| **Runtime v0.1 (5)** | `aios_analyze_project`, `aios_build_context_package`, `aios_snapshot`, `aios_snapshot_list`, `aios_snapshot_diff` |
+
+### Slash commands não portam — use MCP tools ou linguagem natural
+
+Os slash commands `/init`, `/sync`, `/work` são **exclusivos do Claude Code**. Em outras IDEs, peça em linguagem natural (a tool MCP correspondente é chamada):
+
+| Em vez de digitar | Peça em linguagem natural | Tool MCP chamada |
+|---|---|---|
+| `/init` | "inicialize o conhecimento do projeto" | `aios_run_workflow({ name: "init" })` |
+| `/sync` | "sincroniza o estado do projeto" | `aios_run_workflow({ name: "sync" })` |
+| `/work <intent>` | "trabalhe nesta tarefa: <intent>" | `aios_run_workflow({ name: "work", input: { intent } })` |
+| (retomar pause) | "retome a execução X com resposta Y" | `aios_resume_workflow({ execution_id, user_input })` |
+| ad-hoc: state | "qual a phase atual?" / "ajuste mode para validation" | `aios_state_get/set/advance` |
+| ad-hoc: confidence | "avalie confidence do projeto" | `aios_confidence_assess` |
+| ad-hoc: drift | "houve drift desde último snapshot?" | `aios_detect_drift` |
+| ad-hoc: contexto | "me dá o context layer working" | `aios_get_context({ layer: "working" })` |
+| ad-hoc: health | "qual o status do AI OS?" | `aios_health` |
+
+### Pause/resume mechanism (workflows multi-turno)
+
+Workflows como `/work` v3 e `/init` v3 podem **pausar** para coletar input do usuário. Retornam `status: "paused"` + `execution_id` + `pause_info`. O cliente externo (Claude AskUserQuestion, Gemini chat) mostra o `prompt`, coleta resposta, e chama `aios_resume_workflow`. TTL default: 30 min.
+
+```
+1. aios_run_workflow({name:"work",input:{intent:"X"}})
+   → status: paused, execution_id: exec-abc, pause: clarification_questions
+2. (cliente mostra prompt, usuário responde "ok")
+3. aios_resume_workflow({execution_id:"exec-abc", user_input:"ok"})
+   → status: paused, pause: plan_approval
+4. (resume novamente com "ok")
+5. aios_resume_workflow({execution_id:"exec-xyz", user_input:"ok"})
+   → status: ok, guarantees_met: [...], steps: [...]
+```
+
+Se o agente não chamar a tool, é sinal de que o MCP não está conectado — ver troubleshooting de cada IDE.
+
+## Snippets reutilizáveis
+
+`snippets/` contém os blocos JSON canônicos:
+
+- [`mcp-stdio.json`](./snippets/mcp-stdio.json) — caminho relativo (preferido)
+- [`mcp-http.json`](./snippets/mcp-http.json) — variante HTTP (CLIs ou clientes sem stdio)
+- [`mcp-absolute-paths.json`](./snippets/mcp-absolute-paths.json) — caminho absoluto para configs globais (Cline, Windsurf, TRAE)
+
+## Validação cross-cutting
+
+Antes de debugar qualquer IDE específica, confirme que o daemon sobe:
+
+```powershell
+cd "C:\Users\PC\Desktop\Estrutura para IA\Harness"
+node .ai/server/aios-server.mjs --http
+# em outro terminal:
+curl http://127.0.0.1:47781/health
+```
+
+Se a chamada `/health` falhar, o problema está no daemon (Node, build, paths), não nas IDEs.
+
+## Adicionar uma nova IDE
+
+1. Criar o stub na raiz no formato que a IDE auto-carrega (consultar docs da ferramenta).
+2. Reusar o template de stub-pattern (ver os existentes — todos com mesma estrutura de 12-18 linhas).
+3. Criar config MCP se a IDE suporta (escopo projeto preferido; global como fallback).
+4. Criar doc `.ai/clients/<ide>.md` seguindo a estrutura: cabeçalho + capability + ativação 3 passos + snippet inline + validação + troubleshooting + limitações.
+5. Adicionar linha à tabela acima.