sauron-cli 1.1.3 → 1.3.0

package/.genesis/prompts/prompt-sauron-vs-openspec-arquitetura.md

@@ -0,0 +1,106 @@
+# Prompt: Evolução Arquitetural do Sauron CLI inspirada no OpenSpec
+
+```
+Estou desenvolvendo o Sauron CLI, um framework de governança e persistência de memória para assistentes de IA (Cursor, Windsurf, Aider, Antigravity) rodando localmente no repositório. O Sauron ejeta regras (.agents/rules/memory.md) e templates de documentação (.sauron/wiki/) e força a IA a documentar continuamente decisões arquiteturais e mudanças de negócio (Write Obligation).
+
+Quero evoluir a arquitetura do Sauron CLI e torná-lo mais resiliente, sólido e profissional. Para isso, estou analisando a estrutura do OpenSpec (uma ferramenta de especificação iterativa e ágil). O OpenSpec possui um ciclo de vida robusto de workspaces (comandos como setup, link, relink, doctor, update, open) que interagem com diretórios globais de configuração e suportam fluxos interativos e não interativos (--json, --no-interactive).
+
+Stack Técnica:
+- Node.js (ESM)
+- TypeScript 5+
+- Commander.js para rotas CLI
+- Tsup para bundler
+- fs-extra e picocolors
+- @clack/prompts para fluxos interativos
+- diff para motor de merge de conflitos
+
+Atualmente, o Sauron CLI possui apenas o comando 'sauron init' estruturado da seguinte forma:
+
+```typescript
+// src/index.ts
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { runInitCommand } from './features/init/init.command.js';
+
+const program = new Command();
+program
+  .name('sauron')
+  .description('Sauron CLI - Framework para resolução de Amnésia de Contexto em IAs')
+  .version('1.0.0');
+
+program
+  .command('init')
+  .description('Inicializa o Sauron Memory System no projeto atual')
+  .option('-y, --yes', 'Pula os prompts interativos e usa os valores padrão (Não-interativo)')
+  .action((options) => runInitCommand(options));
+
+program.parse();
+```
+
+E no serviço de injeção ('init.service.ts'):
+
+```typescript
+// src/features/init/init.service.ts
+import fs from 'fs-extra';
+import path from 'path';
+import { getManifest, saveManifest, generateHash } from '../../core/manifest.service.js';
+import { checkConflict } from '../../core/merge.service.js';
+import { generateAgentsMarkdown } from './templates.js';
+
+export class InitService {
+  async execute(options: any, onConflict: any) {
+    const { cwd, templatesDir } = options;
+    const manifest = (await getManifest(cwd)) || { version: '1.0.0', files: {} };
+
+    async function processDirectory(source: string, target: string) {
+      if (!(await fs.pathExists(source))) return;
+      const files = await fs.readdir(source);
+      for (const file of files) {
+        const sourcePath = path.join(source, file);
+        const targetPath = path.join(target, file);
+        const stat = await fs.stat(sourcePath);
+
+        if (stat.isDirectory()) {
+          await fs.ensureDir(targetPath);
+          await processDirectory(sourcePath, targetPath);
+        } else {
+          const content = await fs.readFile(sourcePath, 'utf8');
+          const relPath = path.relative(cwd, targetPath).replace(/\\/g, '/');
+          let shouldWrite = true;
+
+          if (await fs.pathExists(targetPath)) {
+            const localContent = await fs.readFile(targetPath, 'utf8');
+            const hasConflict = checkConflict(localContent, content, manifest.files[relPath]);
+            
+            if (hasConflict) {
+              const decision = await onConflict(relPath, localContent, content);
+              if (decision === 'ours') shouldWrite = false;
+            }
+          } else {
+            await fs.ensureDir(path.dirname(targetPath));
+          }
+
+          if (shouldWrite) {
+            await fs.writeFile(targetPath, content, 'utf8');
+          }
+          manifest.files[relPath] = generateHash(content);
+        }
+      }
+    }
+
+    await processDirectory(path.join(templatesDir, '.sauron'), path.join(cwd, '.sauron'));
+    await processDirectory(path.join(templatesDir, '.agents'), path.join(cwd, '.agents'));
+    // ... gera AGENTS.md e salva manifesto
+  }
+}
+```
+
+Comparando nosso design simplista de injeção direta local com a solidez do OpenSpec (que possui gerenciamento de múltiplos workspaces locais e links vinculados, auditoria automática de inconsistências via 'doctor' e atualização seletiva de ferramentas/skills instaladas):
+
+1. Quais são as principais falhas ou limitações estruturais e de design do Sauron CLI em comparação com as práticas adotadas pelo OpenSpec?
+2. Como podemos estender o Sauron CLI com comandos equivalentes a 'doctor' (para auditar a integridade das pastas .sauron/ e .agents/ e o summary.json) e 'uninstall' (para remoção limpa do Sauron preservando a wiki)?
+3. Como reestruturar o core do Sauron CLI para dar suporte a modos programáticos (--json, --no-interactive) em todos os comandos futuros, facilitando o uso por scripts externos?
+4. Que novas funcionalidades de integração com o ecossistema local do desenvolvedor (ex: escolher qual IDE/agente de IA deve consumir as regras) podemos herdar ou nos inspirar do OpenSpec para fortalecer o Sauron?
+
+Forneça uma análise arquitetural profunda, desenhe a nova estrutura de pastas sugerida para o projeto CLI, e proponha os schemas técnicos/exemplos de implementação dos novos comandos.
+```

package/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 20
+        cache: 'npm'
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Run Build
+      run: npm run build

package/.sauron/.manifest.json

@@ -1,6 +1,7 @@
 {
   "version": "1.0.0",
   "files": {
-    "AGENTS.md": "16636ca1f503c84b91daa406a3cfc581563580f48443e6c082e32c7ea0037920"
+    ".agents/skills/wiki/SKILL.md": "8ce35d3ee8294f0883bb54e81d12948f6a4adc9fbde87c92cec91e58e9dd9a73",
+    "AGENTS.md": "c9a63ca8bdd74bf396ad713d79fc21ab075d0c7051ec51ffdcc0cfd9a85777ee"
   }
 }

package/.sauron/wiki/history/implementacao-scanner-inteligente.md

@@ -0,0 +1,29 @@
+# Implementação do Scanner Inteligente de Projetos e Receitas de Wiki
+
+## O que foi feito
+- **Scanner Heurístico Superficial (`ProjectScanner`)**: Varredura assíncrona não bloqueante de nível superior na raiz do repositório (O(1)) filtrando cirurgicamente pastas gigantes (`node_modules`, `.git`) para extrair a stack de desenvolvimento, bancos de dados, IAs configuradas (Cursor, Windsurf, Aider, Antigravity) e gerenciadores de pacotes.
+- **Dicionário de Assinaturas Tecnológicas (`signatures.ts`)**: Mapeamento estruturado de tecnologias como TypeScript, Next.js, React, NestJS, Express, Prisma, PostgreSQL e Redis com base em dependências declaradas e arquivos marcadores físicos (ex. `compose.yml`).
+- **Geração Condicional de Documentação (`WikiBootstrapper`)**: Injeção automática e não destrutiva de guias e regras de estilo baseadas em prompts de IA para cada tecnologia identificada, armazenados na pasta de templates `templates/wiki-recipes/`.
+- **Governança Dinâmica da Wiki (`summary.json`)**: Registro automático das receitas injetadas com geração idempotente de UUIDs de KB, slugs, cálculo de tamanho em bytes (`contentLength`) e hash SHA-256 (`contentHash`).
+- **Polimento UX e Labor Illusion**: Delay artificial de 800ms em execução interativa que informa visualmente a varredura e pré-popula de forma inteligente os inputs de onboarding do `@clack/prompts`.
+- **Proteção a Arquivos Mutáveis**: Correção na governança do `.manifest.json` da CLI para excluir arquivos de evolução contínua (`.sauron/wiki/summary.json` e `.agents/rules/memory.md`), garantindo que o comando `sauron doctor` não reporte falsos alertas de modificação manual.
+
+## Por que foi feito
+O onboarding inicial dependia de digitação manual cega por parte do desenvolvedor, gerando fricção. Além disso, a estrutura de wiki anterior injetava apenas estruturas vazias sem o know-how de desenvolvimento das ferramentas específicas do repositório, deixando o "Cérebro da IA" sem contexto especializado de melhores práticas sobre as tecnologias de eleição.
+
+## Como funciona
+1. **Varredura**: O `ProjectScanner` usa `fs.readdir` com `withFileTypes: true` para identificar arquivos marcadores (como `tsconfig.json`) e lê o `package.json` para testar assinaturas. Também analisa docker compose em busca de imagens de banco de dados.
+2. **Onboarding**: No modo interativo, o spinner exibe a análise por 800ms, em seguida alimenta os inputs interativos usando as propriedades `initialValue`/`initialValues`.
+3. **Injeção de Receitas**: O `WikiBootstrapper` copia as receitas de `templates/wiki-recipes/` aplicáveis para `.sauron/wiki/standards/` se o arquivo destino não existir, registrando a entrada correspondente no `summary.json`.
+4. **Higiene do Doctor**: A CLI não inclui mais arquivos sob `.sauron/wiki/` ou `.agents/rules/memory.md` no `.manifest.json` para que edições orgânicas da equipe de desenvolvimento transcorram sem acionar alarmes de violação de integridade.
+
+## Arquivos afetados
+- [src/core/scanner/signatures.ts](file:///F:/Projetos/sauron-cli/src/core/scanner/signatures.ts)
+- [src/core/scanner/project-scanner.ts](file:///F:/Projetos/sauron-cli/src/core/scanner/project-scanner.ts)
+- [src/core/wiki/wiki-bootstrapper.ts](file:///F:/Projetos/sauron-cli/src/core/wiki/wiki-bootstrapper.ts)
+- [src/features/init/init.command.ts](file:///F:/Projetos/sauron-cli/src/features/init/init.command.ts)
+- [src/features/init/init.service.ts](file:///F:/Projetos/sauron-cli/src/features/init/init.service.ts)
+- [templates/wiki-recipes/](file:///F:/Projetos/sauron-cli/templates/wiki-recipes/) (diretório de regras Markdown)
+
+## Data
+2026-06-06T20:56:00-03:00

package/.sauron/wiki/history/reestruturacao-arquitetural-core.md

@@ -0,0 +1,29 @@
+# Reestruturação Arquitetural do Core: De Monolito a Framework Desacoplado
+
+## O que foi feito
+- Implementação de um fluxo de controle de E/S e visualização desacoplado utilizando o padrão de projeto Strategy.
+- Criação dos novos comandos de ciclo de vida do Sauron CLI:
+  - `sauron doctor`: Inspeciona a integridade criptográfica SHA-256 e de conformidade do projeto.
+  - `sauron uninstall`: Desvincula as configurações do Sauron, com remoção cirúrgica de regras injetadas e degradação graciosa da wiki (preservada por padrão).
+- Implementação de um Registro Global Central (`~/.sauron/registry.json`) para rastreabilidade de múltiplos projetos sob a jurisdição do Sauron.
+- Desenvolvimento de adaptadores específicos de IAs (`CursorAdapter`, `WindsurfAdapter`, `AiderAdapter`, `AntigravityAdapter`) para injeção e higiene nativas dos arquivos das IDEs (.mdc, .windsurfrules, etc.).
+- Suporte nativo a modos programáticos (`--json`, `--no-interactive`) em todos os comandos, evitando travamentos em pipelines.
+
+## Por que foi feito
+A versão anterior possuía um acoplamento rígido de entrada e saída com a lógica central de injeção, impedindo a sua automação por agentes autônomos ou processos de CI/CD (pois os prompts interativos causavam travamentos perpétuos se conflitos surgissem). Além disso, a injeção estática e agnóstica não atendia aos formatos de configuração específicos de cada IDE/IA moderna.
+
+## Como funciona
+1. **Contexto de Sessão e PresentationDriver**: O roteador decide qual driver (Terminal ou JSON) instanciar baseado nas flags globais da CLI. Se o modo for não-interativo e surgir um conflito de arquivos, o driver resolve o conflito com a estratégia fornecida via `--conflict <ours|theirs>` ou gera um erro imediato.
+2. **Padrão Adaptador**: Cada IA alvo possui um adaptador concreto. Para o Cursor, injeta regras em `.cursor/rules/sauron-memory.mdc` com frontmatter YAML. Para o Windsurf, manipula cirurgicamente o arquivo compartilhado `.windsurfrules` isolando o bloco do Sauron com marcadores de âncora `# SAURON START` e `# SAURON END`, removidos no `uninstall`.
+3. **Registry Central**: Armazena metadados essenciais de todos os projetos na máquina local.
+
+## Arquivos afetados
+- Praticamente todo o código da CLI foi modularizado sob os novos diretórios:
+  - [src/domain/](file:///F:/Projetos/sauron-cli/src/domain/) (entidades de sessão e interfaces de adaptador)
+  - [src/presentation/](file:///F:/Projetos/sauron-cli/src/presentation/) (drivers concretos e roteamento)
+  - [src/core/](file:///F:/Projetos/sauron-cli/src/core/) (registry global e adaptadores de agentes)
+  - [src/features/](file:///F:/Projetos/sauron-cli/src/features/) (handlers dos comandos init, doctor e uninstall)
+- [src/index.ts](file:///F:/Projetos/sauron-cli/src/index.ts) (registro dos comandos commander)
+
+## Data
+2026-06-06T20:20:00-03:00

package/.sauron/wiki/history/resiliencia-caminho-templates.md

@@ -0,0 +1,29 @@
+# Resiliência no Caminho de Templates (Correção de Bug e Onboarding)
+
+## O que foi feito
+- Análise de viabilidade e onboarding detalhado da arquitetura da Sauron CLI.
+- Correção de um bug na resolução do diretório de templates (`templatesDir`) em `src/features/init/init.command.ts`.
+- Inicialização do Sauron Memory System no próprio projeto `sauron-cli`.
+
+## Por que foi feito
+Anteriormente, o comando `sauron init` assumia que o arquivo compilado estaria no mesmo nível relativo de diretórios do ambiente de desenvolvimento (dentro de `dist/features/init/init.command.js`). No entanto, o empacotamento com o `tsup` condensa toda a saída em um único bundle em `dist/index.js`, fazendo com que `__dirname` em tempo de execução aponte diretamente para `dist/`. Isso causava um retorno silencioso no processo de cópia de templates, deixando a pasta `.agents` e a wiki em `.sauron` inexistentes no diretório de destino do usuário.
+
+## Como funciona
+A localização do diretório `templates` foi reformulada para ser resiliente e buscar em múltiplos níveis de diretório relativos a `__dirname`:
+1. Verifica se `templates` existe um nível acima de `__dirname` (padrão de build em `dist/index.js`).
+2. Se não existir, retrocede três níveis (padrão em ambiente de desenvolvimento rodando a partir de `src/features/init/init.command.ts`).
+
+```typescript
+// src/features/init/init.command.ts
+let templatesDir = path.join(__dirname, '..', 'templates');
+if (!fs.existsSync(templatesDir)) {
+  templatesDir = path.join(__dirname, '..', '..', '..', 'templates');
+}
+```
+
+## Arquivos afetados
+- [init.command.ts](file:///F:/Projetos/sauron-cli/src/features/init/init.command.ts)
+- [dist/index.js](file:///F:/Projetos/sauron-cli/dist/index.js) (Regerado pós-build)
+
+## Data
+2026-06-06T19:40:00-03:00

package/.sauron/wiki/standards/typescript.rules.md

@@ -0,0 +1,21 @@
+# TypeScript - Diretrizes de Qualidade e Tipagem Estrita
+
+Este documento normatiza os padrões de tipagem e compilação para o uso do TypeScript no projeto.
+
+## 🎯 Regras Obrigatórias para a IA
+
+1. **Tipagem Estrita (Strict Mode)**:
+   - Nunca utilizar `any` de forma deliberada. Se a tipagem for dinâmica ou desconhecida, prefira `unknown` e realize Type Guarding (assercões de tipo seguras).
+   - Ative e respeite `noImplicitAny`, `strictNullChecks` e `noUnusedLocals`.
+
+2. **Tipos vs Interfaces**:
+   - Utilize `interface` para declarar contratos de objetos públicos, classes, e componentes expostos.
+   - Utilize `type` para uniões (`|`), interseções (`&`), tuplas, tipos utilitários ou definições primitivas de alias.
+
+3. **Importações Explicitas**:
+   - Utilize imports com a extensão `.js` ao compilar para ECMAScript Modules (ESM) nativo no Node.js.
+   - Prefira importações nomeadas em vez de imports coringa (`* as module`).
+
+## 🚫 Práticas Banidas
+- Desativar checagens com comentários `// @ts-ignore` (use `// @ts-expect-error` apenas com justificativa explícita e em testes).
+- Asserções de tipo coercitivas (`as any` ou `as unknown as Type`).

package/.sauron/wiki/summary.json

@@ -0,0 +1,81 @@
+[
+  {
+    "type": "folder",
+    "name": "History",
+    "slug": "history",
+    "path": "history",
+    "id": "domain-history"
+  },
+  {
+    "type": "file",
+    "name": "Resiliência no Caminho de Templates",
+    "slug": "resiliencia-no-caminho-de-templates",
+    "path": "history/resiliencia-caminho-templates.md",
+    "id": "kb-history-resilience-templates",
+    "domainId": "domain-history",
+    "orgId": "org-sauron-cli",
+    "contentLength": 1815,
+    "contentHash": "e5f4da0442923d13b2de447dcaff137de34f8b6f533dd3b95d5423b316a79313"
+  },
+  {
+    "type": "file",
+    "name": "Reestruturação Arquitetural do Core",
+    "slug": "reestruturacao-arquitetural-do-core",
+    "path": "history/reestruturacao-arquitetural-core.md",
+    "id": "kb-history-rearchitecture-core",
+    "domainId": "domain-history",
+    "orgId": "org-sauron-cli",
+    "contentLength": 2908,
+    "contentHash": "6f2373af88c7347d556cbf747ca814397105336c3c434b7037d7aaa28163bb16"
+  },
+  {
+    "type": "file",
+    "name": "Scanner Inteligente e Receitas de Wiki",
+    "slug": "implementacao-scanner-inteligente",
+    "path": "history/implementacao-scanner-inteligente.md",
+    "id": "kb-history-scanner-intel",
+    "domainId": "domain-history",
+    "orgId": "org-sauron-cli",
+    "contentLength": 3712,
+    "contentHash": "a73ef1a09456ad5a03fd3a41438ea8fc4850b8b6703e8b579c899777a073d692"
+  },
+  {
+    "type": "folder",
+    "name": "Knowledge",
+    "slug": "knowledge",
+    "path": "knowledge",
+    "id": "domain-knowledge"
+  },
+  {
+    "type": "folder",
+    "name": "Manuals",
+    "slug": "manuals",
+    "path": "manuals",
+    "id": "domain-manuals"
+  },
+  {
+    "type": "folder",
+    "name": "Modules",
+    "slug": "modules",
+    "path": "modules",
+    "id": "domain-modules"
+  },
+  {
+    "type": "folder",
+    "name": "Standards",
+    "slug": "standards",
+    "path": "standards",
+    "id": "domain-standards"
+  },
+  {
+    "type": "file",
+    "name": "TypeScript Guidelines",
+    "slug": "typescript-rules",
+    "path": "standards/typescript.rules.md",
+    "id": "kb-standards-typescript",
+    "domainId": "domain-standards",
+    "orgId": "org-sauron-cli",
+    "contentLength": 1182,
+    "contentHash": "a52a45607902b2173261fcbeb18277d91211f8e4a9867762ac9a2477edec1021"
+  }
+]

package/.windsurfrules

@@ -0,0 +1,160 @@
+# SAURON END
+
+
+
+# SAURON END
+
+# SAURON END
+
+# SAURON START
+---
+trigger: always_on
+---
+
+# SAURON START
+---
+trigger: always_on
+---
+
+# SAURON START
+---
+trigger: always_on
+---
+
+# SAURON START
+---
+trigger: always_on
+---
+
+# Regra de Memória do Projeto (OBRIGATÓRIA)
+
+> Esta regra garante que o Wiki (`.sauron/wiki/`) é a fonte da verdade absoluta do projeto.
+> Violá-la significa perder informação crítica entre sessões.
+
+---
+
+## 1. LEITURA — Antes de Agir
+
+Sempre que algo for perguntado ou uma tarefa for iniciada:
+
+1. Leia `.sauron/wiki/summary.json` (o arquivo de roteamento base) primeiro. Este arquivo segue um **padrão rígido** e é a única fonte confiável de metadados.
+2. Navegue pelas sub-páginas relevantes usando as informações de nome original e tipo (file/folder) contidas no JSON.
+3. Só recorra à exploração do sistema de arquivos se a informação **não existir** no sumário (e atualize o sumário se necessário seguindo o schema da Seção 6).
+
+---
+
+## 2. PROTOCOLO DE SINCRONIZAÇÃO (NUVEM)
+
+O fluxo de documentação segue um ciclo de três etapas para garantir a persistência:
+
+1. **PULL (Manual)**: Antes de iniciar a tarefa, o usuário executa `sauron pull` para atualizar os documentos locais com a versão mais recente da nuvem.
+2. **EXECUÇÃO (IA)**: Durante o desenvolvimento, o Agente atualiza/cria os documentos em `.sauron/wiki/` em tempo real.
+3. **PUSH (Manual)**: Ao finalizar a tarefa, o usuário executa `sauron push` para enviar as atualizações locais para a nuvem.
+
+> [!IMPORTANT]
+> O Agente deve assumir que o diretório `.sauron/wiki/` é o destino final e atualizá-lo diligentemente, permitindo que o usuário sincronize as mudanças posteriormente.
+
+---
+
+## 3. ESCRITA — Depois de Entregar (CRÍTICO)
+
+**Após QUALQUER entrega funcional, a wiki DEVE ser atualizada NO MESEMO TURNO de resposta.**
+
+### Gatilhos Obrigatórios de Escrita
+
+| Evento | Ação no Wiki |
+|--------|-------------|
+| **Integração de API externa** | Criar/atualizar página documentando URL, autenticação, payload, resposta e tratamento de erros. |
+| **Nova página/rota criada** | Registrar em `summary.json` (seguindo o **padrão rígido** da Seção 6) + criar arquivo `.md`. |
+| **Fluxo de autenticação alterado** | Atualizar a página de auth com o fluxo completo, incluindo cookies, tokens e middleware. |
+| **Novo componente de UI funcional** | Registrar na página do módulo correspondente com props, comportamento e dependências. |
+| **Decisão arquitetural tomada** | Documentar usando o formato "Decisão Arquitetural" (Problema → Opções → Escolha → Justificativa). |
+| **Variável de ambiente adicionada/alterada** | Registrar na página de infraestrutura com nome, propósito e exemplo. |
+| **Schema de banco alterado** | Atualizar `module-data-schema.md` com a mudança. |
+| **Bug crítico resolvido** | Registrar causa raiz e solução na página do módulo afetado. |
+
+### Regra de Ouro
+
+```
+❌ ERRADO: Entregar código → Responder ao usuário → Esquecer o wiki
+✅ CORRETO: Entregar código → Atualizar wiki → Responder ao usuário
+```
+
+A atualização do wiki é **parte da entrega**, não um passo opcional posterior.
+
+---
+
+## 4. FORMATO — O que Escrever
+
+Cada registro deve conter no mínimo:
+- **O que foi feito** (descrição objetiva)
+- **Por que foi feito** (contexto e motivação)
+- **Como funciona** (detalhes técnicos: endpoints, payloads, fluxos)
+- **Arquivos afetados** (lista de caminhos)
+- **Data** (timestamp da alteração)
+
+---
+
+## 6. ESTRUTURA RÍGIDA DO SUMMARY.JSON
+
+O arquivo `.sauron/wiki/summary.json` é o mapa de metadados que vincula os arquivos locais ao servidor. O CLI exige um padrão estrito para o comando `sauron push` funcionar corretamente.
+
+### Regras de Ouro do Summary
+- **NUNCA altere IDs**: Os campos `id`, `domainId` e `orgId` são cruciais. Removê-los ou alterá-los causará a criação de documentos duplicados no servidor em vez de atualizar os existentes.
+- **Mantenha o Mapeamento**: O campo `name` deve ser o título original (com espaços e acentos). O `slug` e o `path` devem ser gerados seguindo a lógica de normalização (lowercase, sem acentos, espaços viram hífens).
+- **Otimização**: Os campos `contentLength` e `contentHash` (SHA256) permitem que o CLI pule arquivos não alterados. Se você editar um arquivo manualmente, o `push` detectará a mudança mesmo se você não atualizar o hash (ele recalcula o hash local), mas o `summary.json` deve ser mantido atualizado para consistência.
+- **Acoplamento Físico**: O Sauron CLI mapeia domínios do banco de dados na nuvem com base na subpasta física no disco local (usando o diretório pai do arquivo). Arquivos na raiz do wiki sempre pertencerão ao domínio genérico `.`. É obrigatória a organização física em pastas para manter a separação lógica na nuvem.
+- **Ignorar summary.md**: O arquivo `summary.md` é uma página especial/reservada. Nunca adicione o `summary.md` como uma entrada do tipo `"file"` dentro do `summary.json`, caso contrário o CLI tentará excluí-lo e falhará com erro 422.
+
+### Schema Obrigatório
+
+O JSON deve ser um **array de objetos** seguindo rigorosamente estes formatos:
+
+#### Entrada de Pasta (Domínio)
+```json
+{
+  "type": "folder",
+  "name": "Título Original",
+  "slug": "titulo-original",
+  "path": "titulo-original",
+  "id": "id-do-dominio"
+}
+```
+
+#### Entrada de Arquivo (Documento)
+```json
+{
+  "type": "file",
+  "name": "Título Original do Documento",
+  "slug": "titulo-original-do-documento",
+  "path": "slug-do-dominio/titulo-original-do-documento.md",
+  "id": "id-do-kb",
+  "domainId": "id-do-dominio-pai",
+  "orgId": "id-da-organizacao",
+  "contentLength": 1234,
+  "contentHash": "sha256-checksum"
+}
+```
+
+---
+
+## 7. VALIDAÇÃO — Checklist Mental
+
+Antes de finalizar qualquer resposta que envolva código, pergunte-se:
+
+- [ ] Criei ou modifiquei um arquivo? → Wiki precisa saber.
+- [ ] Conectei a uma API externa? → Wiki precisa documentar.
+- [ ] Alterei fluxo de login/sessão? → Wiki MUST refletir.
+- [ ] Criei uma nova página/rota? → `summary.json` precisa do registro de roteamento seguindo o **padrão rígido**.
+- [ ] Tomei uma decisão técnica (lib X vs Y, abordagem A vs B)? → Wiki precisa da justificativa.
+- [ ] Adicionei/alterei uma variável de ambiente? → Wiki precisa do registro.
+
+Se qualquer checkbox for `true` e o wiki não foi atualizado, **a tarefa NÃO está completa**.
+
+# SAURON END
+
+# SAURON END
+
+# SAURON END
+
+# SAURON END