sauron-cli 1.2.0 → 1.4.0

package/.agents/rules/memory.md

@@ -0,0 +1,156 @@
+---
+trigger: always_on
+---
+
+# 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

package/.agents/skills/wiki/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: wiki
+description: Project Memory and Documentation System - ensures every action, decision, and evolution is recorded, explained, and traceable.
+allowed-tools: Read, Write, Edit, list_dir
+version: 3.0
+priority: MANDATORY
+---
+
+# 🧠 Wiki & Project Memory System
+
+> **MANDATORY SKILL** - Build a living knowledge system. Nothing exists unless it is documented.
+> **WRITE OBLIGATION** - Every functional delivery MUST include wiki updates in the SAME response turn.
+> **SYNC PROTOCOL** - The IA updates local `.sauron/wiki/` files; `sauron pull/push` are manual user commands.
+
+---
+
+## 1. Core Principles
+
+| Principle | Rule |
+|-----------|------|
+| **Source of Truth** | If it's not documented, it doesn't exist. All changes must be recorded before completion. |
+| **Decision > Impl** | Documentation is about **WHY**, not just **WHAT**. Explain context and alternatives. |
+| **Smart Granularity** | Divide documentation into sub-pages based on modules, domains, or critical components. |
+| **Continuous Evolution** | Pages are living organisms. They must contain current state, history, and future direction. |
+| **Write-on-Deliver** | Wiki update is part of the delivery, not a follow-up task. Code without docs = incomplete work. |
+
+---
+
+## 2. Structure & Naming Conventions
+
+| Property | Requirement |
+|----------|-------------|
+| **Base Directory** | `/.sauron/wiki/` |
+| **Root Routing File** | `summary.json` (dentro de `/.sauron/wiki/`) |
+| **Subdirectories** | `knowledge/`, `modules/`, `manuals/`, `standards/`, `history/` (pastas físicas obrigatórias para os domínios no Sauron) |
+| **Naming Pattern** | `{name}.md` (sem prefixos se já estiverem dentro das subpastas físicas de domínio) |
+| **Examples** | `knowledge/architecture.md`, `modules/checkout.md`, `manuals/upholstery.md` |
+
+---
+
+## 3. Reference Templates
+
+### 3.1 Root Routing File (`summary.json`)
+O arquivo `summary.json` é o mapa de metadados que vincula os arquivos locais ao servidor. Ele segue um **padrão rígido** (ver Seção 6 da `memory.md`).
+
+```json
+[
+  {
+    "type": "folder",
+    "name": "Título Original",
+    "slug": "titulo-original",
+    "path": "titulo-original",
+    "id": "UUID-ou-ID"
+  },
+  {
+    "type": "file",
+    "name": "Título Original",
+    "slug": "titulo-original",
+    "path": "slug-do-dominio/titulo-original.md",
+    "id": "UUID-ou-ID",
+    "domainId": "ID-do-pai",
+    "orgId": "ID-da-organizacao",
+    "contentLength": 1234,
+    "contentHash": "sha256-checksum"
+  }
+]
+```
+
+### 3.2 Sub-pages (`{name}.md`)
+```markdown
+# [Module / Page Name]
+
+## 1. Context
+Clear description of what this part of the system is.
+
+## 2. Responsibility
+What this part does and what it DOES NOT do.
+
+## 3. Architectural Decisions
+### Decision 1
+- **Problem**:
+- **Options Considered**:
+  - Option A
+  - Option B
+- **Choice**:
+- **Justification**:
+- **Trade-offs**:
+
+(repeat as necessary)
+
+## 4. Change History
+### [Date] - [Change Title]
+- **What was done**:
+- **Why it was done**:
+- **Impact on the system**:
+- **Files affected**:
+
+## 5. Current State
+Objective technical description of the implementation as it stands today.
+
+## 6. Next Steps (Optional)
+Possible future evolutions.
+```
+
+---
+
+## 4. Update Protocol (MANDATORY)
+
+Whenever a relevant action is performed, the AI **MUST**:
+
+1.  **Identify Scope**: Determine which page in `/.sauron/wiki/` is affected.
+2.  **Register Change**: Add a specific entry to the **Change History** of the corresponding page.
+3.  **Update Current State**: Ensure the technical description reflects reality after the modification.
+4.  **Register Decisions**: Document technical or strategic choices using the **Architectural Decisions** format.
+5.  **Update Routing**: If a new page was created, register it in `summary.json` with its metadata immediately.
+
+---
+
+## 5. Mandatory Write Triggers
+
+> 🔴 These events ALWAYS require a wiki update in the SAME response turn as the code delivery.
+
+| Trigger Event | Wiki Action Required |
+|---------------|---------------------|
+| **External API integrated** | Create `{name}.md` under the corresponding folder (e.g. `integrations/` or `modules/`) with: URL, auth method, request/response shapes, error handling, env vars. |
+| **New route/page created** | Register in `summary.json` System Map + create `{name}.md` under the corresponding folder with layout, components, and behavior. |
+| **Authentication flow changed** | Update auth-related page with full flow: credentials, tokens, cookies, middleware, session lifecycle. |
+| **New UI component delivered** | Register in the parent module page with: props, behavior, dependencies, visual state. |
+| **Architectural decision made** | Document in the relevant page using the Decision template (Problem → Options → Choice → Justification). |
+| **Environment variable added/changed** | Register in relevant infrastructure/config page with: name, purpose, example value. |
+| **Database schema changed** | Update `module-data-schema.md` with the change, including SQL and reasoning. |
+| **Critical bug resolved** | Register root cause and solution in the affected module page. |
+| **Middleware/security layer added** | Document the protection boundary, what it intercepts, and its redirect logic. |
+| **Configuration/settings page created** | Document available options, their purpose, and current state (even if mocked). |
+
+### Self-Check Before Responding
+
+```
+Before writing your response to the user, ask yourself:
+
+1. Did I create or modify any file?           → Wiki needs to know.
+2. Did I connect to an external API?           → Wiki needs full documentation.
+3. Did I change login/session flow?            → Wiki MUST reflect this.
+4. Did I create a new page/route?              → summary.json needs the registration.
+5. Did I make a technical decision?            → Wiki needs the justification.
+6. Did I add/change an env variable?           → Wiki needs the record.
+
+If ANY answer is YES and the wiki was NOT updated → THE TASK IS NOT COMPLETE.
+```
+
+---
+
+## 6. AI Behavior & Constraints
+
+| Rule | Action |
+|------|--------|
+| **Never skip** | Do not modify the system without documenting. |
+| **Never omit** | Always justify decisions; no change can be implicit. |
+| **Never overwrite** | History must never be deleted; append only. |
+| **Never assume** | Do not use context that isn't documented. |
+| **Never defer** | Wiki updates happen NOW, not "later" or "next turn". |
+| **Clarity > Brevity** | Prioritize deep understanding over short summaries. |
+
+---
+
+## 7. Vision/Goal
+
+Transform the project into a system where:
+- Code is **Executable**.
+- Documentation is **Explainable**.
+- Decision History is **Auditable**.
+- No session knowledge is **Lost**.

package/.aider.instructions.md

@@ -0,0 +1,152 @@
+# 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

package/.cursor/rules/sauron-memory.mdc

@@ -0,0 +1,157 @@
+---
+description: Diretrizes de Memória e Write Obligation para evitar Amnésia de Contexto
+globs: *
+---
+
+# 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

package/.genesis/prompts/prompt-onboarding-inteligente.md

@@ -0,0 +1,45 @@
+# Prompt: Evolução do Onboarding e Scanner de Projeto no Sauron CLI
+
+```
+Estou desenvolvendo o Sauron CLI, um framework de persistência de contexto e governança de memória de IA no repositório. O fluxo atual de inicialização ('sauron init') depende de um onboarding interativo que faz quatro perguntas manuais de texto ao desenvolvedor: qual(is) IA(s) usará, severidade das regras, contexto do projeto e stack tecnológica.
+
+Quero evoluir esse onboarding para um modelo de "Smart Onboarding e Project Scanner". Em vez de forçar o usuário a digitar tudo manualmente, a CLI deve escanear a estrutura física do repositório antes de exibir os prompts interativos, sugerindo automaticamente as tecnologias detectadas e gerando as primeiras documentações contextuais da wiki baseadas nessa detecção.
+
+Stack Técnica:
+- Node.js (ESM)
+- TypeScript 5
+- @clack/prompts para UI interativa
+- fs-extra para leitura e varredura do disco
+
+Atualmente, o onboarding coleta dados de forma totalmente manual no arquivo de entrypoint:
+
+```typescript
+// src/features/init/init.command.ts
+let aiTargets = ['Cursor', 'Windsurf', 'Aider', 'Antigravity'];
+let severity = 'Observacional';
+let projectContext = 'Projeto Genérico';
+let projectStack = 'Node.js, TypeScript';
+
+if (session.interactive) {
+  const config = await p.group({
+    targets: () => p.multiselect({ message: 'Qual(is) IA(s)...', options: [...] }),
+    severity: () => p.select({ message: 'Qual o nível...', options: [...] }),
+    context: () => p.text({ message: 'Descreva brevemente o contexto...', defaultValue: 'Projeto Genérico' }),
+    stack: () => p.text({ message: 'Qual a stack tecnológica...', defaultValue: 'Node.js, TypeScript' }),
+  });
+  aiTargets = config.targets;
+  severity = config.severity;
+  projectContext = config.context;
+  projectStack = config.stack;
+}
+```
+
+Quero ideias, arquitetura e soluções técnicas para os seguintes desafios:
+
+1. **Varredura e Mapeamento de Dependências (Scanner)**: Como estruturar de forma performática a leitura e análise de arquivos comuns de configuração (como package.json, tsconfig.json, next.config.js, compose.yml, requirements.txt, gemini.config, etc.) para inferir a linguagem principal, frameworks frontend/backend, bancos de dados, estilizações e provedores de nuvem?
+2. **Design de UI Sem Fricção**: Como pré-modular e apresentar as informações encontradas pelo scanner nos prompts do @clack/prompts, de forma que o usuário apenas confirme ou ajuste as tecnologias inferidas em vez de digitá-las do zero?
+3. **Bootstrapping Inteligente de Wiki**: Como a CLI pode utilizar as informações detectadas da stack para gerar dinamicamente arquivos iniciais de diretrizes na wiki (.sauron/wiki/standards/ e .sauron/wiki/modules/) adaptados àquela stack específica (ex: injetar um modelo de manual técnico do Firebase se detectar o Firebase, ou guias de estilo de Tailwind se encontrar o Tailwind)?
+4. **Resiliência e Execução Rápida**: Qual a melhor estratégia arquitetural para o scanner operar sem degradar o tempo de inicialização da CLI, lidando graciosamente com repositórios gigantescos ou com dependências desatualizadas?
+
+Desenhe a arquitetura técnica dessa camada de escaneamento, especifique os algoritmos de detecção baseados no sistema de arquivos e forneça exemplos de código do serviço do Scanner adaptados para TypeScript.
+```