sauron-cli 1.0.0

package/README.md

@@ -0,0 +1,85 @@
+# Sauron CLI 👁️
+
+> O "Lobo Frontal" dos assistentes de código de IA. Resolva a amnésia de contexto de uma vez por todas.
+
+O **Sauron CLI** é uma infraestrutura passiva de orquestração de contexto para IAs. Ele injeta um "Cérebro" estruturado nos seus repositórios, forçando as Inteligências Artificiais (como Cursor, Windsurf e Aider) a respeitarem um conceito de **"Write Obligation" (Obrigação de Escrita)**. Em vez de apenas ler código, a IA passará a documentar decisões de negócio e arquitetura continuamente, garantindo que o seu projeto não quebre após meses sem ser tocado.
+
+## O Problema
+
+Assistentes de código são incrivelmente poderosos, mas sofrem de amnésia volátil. Entre o fechamento e a abertura de sessões da IDE, as IAs esquecem as regras do seu projeto, alucinam lógicas, e obrigam você a reescrever prompts diários para ditar o contexto. 
+
+## A Solução
+
+O Sauron resolve isso ejetando pastas estruturadas (`.sauron` e `.agents`) no seu repositório local. A partir desse momento, as IAs são condicionadas a documentar regras passivamente de acordo com os templates gerados, preservando o **Single Source of Truth** do seu produto.
+
+## Instalação
+
+```bash
+# Como o pacote ainda não está publicado publicamente no NPM,
+# você pode usá-lo localmente (após rodar npm link neste repositório):
+
+sauron init
+```
+
+*Brevemente disponível via `npx sauron-cli init`.*
+
+## Comandos (MVP)
+
+### `sauron init`
+
+Inicializa o Sauron Memory System no projeto atual.
+Ele copia passivamente toda a estrutura base (templates de instrução e JSON de mapa mental) para o diretório raiz do usuário.
+
+```bash
+sauron init
+```
+*Nota: Este comando é seguro e bloqueará automaticamente caso os diretórios `.sauron` ou `.agents` já existam no repositório, evitando a corrupção do seu histórico atual.*
+
+## Estrutura Injetada
+
+Ao rodar o comando `init`, a CLI injeta a seguinte topologia no projeto:
+
+```text
+/
+├── .agents/
+│   ├── rules/
+│   └── skills/
+└── .sauron/
+    └── wiki/
+        ├── summary.json
+        ├── history/
+        ├── knowledge/
+        ├── manuals/
+        ├── modules/
+        └── standards/
+```
+
+## Stack Tecnológica
+- **Node.js**: Engine nativa.
+- **TypeScript**: Tipagem estática e segurança.
+- **Commander.js**: Para interfaceamento e rotas CLI.
+- **Tsup**: Bundler rápido para Node e ESM.
+- **fs-extra**: Gerenciamento avançado de arquivos.
+
+## Desenvolvimento
+
+Para contribuir com o core do CLI:
+
+```bash
+# 1. Instale as dependências
+npm install
+
+# 2. Rode o build local
+npm run build
+
+# 3. Vincule a CLI globalmente para testes
+npm link
+```
+
+## Próximos Passos no Roadmap
+- `sauron check`: Comando de validação rigorosa para auditar a integridade da documentação deixada pela IA e bater o Markdown com o `summary.json`.
+- `sauron map`: Visão em formato de árvore hierárquica direto no terminal do seu "Cérebro de IA".
+
+---
+
+**Sauron CLI** - Desenvolvido para a comunidade Indie Hacker e Tech Leads do futuro.

package/Taevo-PRD-1780772261443.md

@@ -0,0 +1,429 @@
+### METADADOS
+
+| Atributo | Detalhe |
+| :--- | :--- |
+| **Nome do Produto** | Sauron (Sauron CLI & Sauron Cloud) |
+| **Versão** | 1.0 (Draft) |
+| **Data Atual** | 24 de Maio de 2024 |
+| **Status** | Draft |
+| **Responsável** | [PENDENTE: Inserir nome do Solo Founder/Product Owner] |
+| **Stack Tecnológica Recomendada** | Node.js, TypeScript, NPM, Commander, Tsup (CLI). React/Next.js (Web), React Native/Expo (Mobile), Stripe (Assinaturas). |
+
+---
+
+### 1. VISÃO GERAL E PROPOSTA DE VALOR
+
+**Elevator Pitch:**
+O Sauron é uma infraestrutura de orquestração de contexto para IAs que atua como o "lobo frontal" de assistentes de código, garantindo que regras de negócio não se percam através de um ecossistema agnóstico de ferramentas de linha de comando, interface web e aprovações mobile.
+
+**Problema Central:**
+Na era do "vibe coding", desenvolvedores dependem crescentemente de agentes de Inteligência Artificial (como Cursor, Windsurf e Aider) para gerar e refatorar bases de código complexas. Contudo, esses agentes sofrem de "Amnésia de Contexto". Eles conseguem ler a sintaxe do código atual, mas desconhecem o histórico e o *porquê* das decisões arquiteturais (regras de negócio). Isso resulta em refatorações destrutivas, perda de tempo com a reescrita de prompts gigantescos diários e um consumo ineficiente da "Context Window" dos modelos (gastando tokens excessivamente e aumentando o tempo de resposta). 
+
+Além disso, a documentação tradicional falha porque é mantida por humanos após o código ser escrito, tornando-se rapidamente obsoleta. Sem um "Single Source of Truth" determinístico, a escalabilidade de projetos guiados por IA torna-se insustentável a médio prazo.
+
+**Diferencial Competitivo:**
+O diferencial intransponível do Sauron em 6 meses reside no conceito nativo de **"Write Obligation" (Obrigação de Escrita)** aliado à agnosia de plataforma. Diferente de concorrentes que apenas leem o repositório, o Sauron obriga a IA a documentar proativamente suas ações e decisões de negócio em um formato Markdown estruturado antes de concluir a tarefa. O Sauron não compete com os agentes (não escreve código); ele os padroniza e governa. Essa infraestrutura passiva é validada localmente via CLI e estendida colaborativamente via interfaces Web e Mobile.
+
+**Posicionamento de Mercado:**
+O Sauron posiciona-se como a "camada de governança e memória" padrão (o equivalente a um "Git para contexto de IA") no desenvolvimento de software. Ele atende desde o Indie Hacker que precisa de controle absoluto do seu projeto solo, até Tech Leads corporativos que demandam monitoramento, sincronização na nuvem e auditoria de agentes de IA através de uma suíte multiplataforma paga (Web/Mobile).
+
+---
+
+### 2. PROBLEMA E OPORTUNIDADE
+
+**Descrição Aprofundada da Dor:**
+O desenvolvedor contemporâneo passa de "escritor de código" para "revisor de código gerado". A dor crítica ocorre na transição entre sessões de trabalho. Quando a IDE é fechada, a IA esquece os limites estritos do domínio da aplicação. Consequentemente, o usuário precisa gastar de 15 a 30 minutos por dia apenas contextualizando o agente, subindo arquivos `.txt` desorganizados ou copiando regras do Notion para o chat da IA. As alucinações da IA quebram lógicas de pagamento, rotas de autenticação e padrões de arquitetura porque a memória do agente é volátil.
+
+**Jornada Atual do Usuário (AS-IS):**
+1. O desenvolvedor abre sua IDE (ex: Cursor) em um projeto complexo.
+2. Ele percebe que a IA não entende as regras de faturamento do sistema.
+3. Ele sai da IDE, abre o Notion/Confluence (ou um bloco de notas local) e copia as regras.
+4. Ele cola as regras no prompt principal da IA.
+5. A IA codifica, mas esquece o contexto 10 interações depois devido ao limite da janela de contexto.
+6. A documentação original fica defasada, pois o código mudou e o humano não atualizou o Notion.
+
+**Oportunidade Quantificada:**
+Estima-se que mais de 5 milhões de desenvolvedores já utilizem assistentes de IA avançados. Se cada desenvolvedor perde em média 20 minutos diários gerenciando contexto e corrigindo alucinações decorrentes de amnésia da IA, há uma oportunidade de recuperação de 33 milhões de horas mensais no mercado global de desenvolvimento corporativo e indie. [ESTIMATIVA — validar com o time de pesquisa].
+
+**Concorrentes Diretos e Indiretos:**
+- *Repomix / gpt-repo-to-text (Indiretos):* Agregadores "Read-Only". Copiam todo o repositório, mas não ensinam a IA a manter histórico.
+- *Aider / GPT-Pilot (Indiretos):* Agentes de execução direta. Focam no "O quê" e prendem o usuário ao terminal deles.
+- *Notion / Confluence (Indiretos):* Plataformas de documentação tradicional. Exigem trabalho manual humano e são isoladas da IDE.
+
+---
+
+### 3. PÚBLICO-ALVO E PERSONAS
+
+| Atributo | Persona 1: Alex, o Indie Hacker (Early Adopter) | Persona 2: Sarah, Tech Lead Corporativa (Fase Escala) |
+| :--- | :--- | :--- |
+| **Nome e Perfil** | Alex (28), Desenvolvedor Full-stack Solo, construtor de micro-SaaS. | Sarah (35), Arquiteta de Software gerenciando 3 squads. |
+| **Contexto de Uso** | Usa Cursor para escrever 100% do código (Vibe Coding). Trabalha localmente. | Supervisiona código gerado por IAs operadas por desenvolvedores juniores. |
+| **Dor Principal** | A IA quebra lógicas de projetos paralisados há semanas por falta de memória de contexto. | Agentes de IA do time estão alucinando e ignorando padrões arquiteturais e de compliance corporativo. |
+| **Job-to-be-done** | Quando volto a um projeto antigo, quero que a IA saiba imediatamente as regras, para continuar desenvolvendo sem atrito. | Quando a IA de um dev altera uma regra core, quero ser notificada no Mobile para aprovar e garantir a governança. |
+| **Maior Medo/Risco** | O projeto ficar tão complexo que a IA não consiga mais escalá-lo, travando o produto. | Vazamento de propriedade intelectual ou código deficiente indo para produção por erro não auditado da IA. |
+| **Critério de Sucesso** | Rodar `sauron init` e ver a IA documentar e respeitar o histórico automaticamente na próxima hora. | Ter visibilidade completa das regras no Dashboard Web e aprovar integrações via Mobile App. |
+| **Maturidade Digital** | 5 (Explorador de bleeding-edge AI) | 4 (Altamente técnica, focada em processos robustos) |
+
+---
+
+### 4. OBJETIVOS E MÉTRICAS DE SUCESSO
+
+**North Star Metric:**
+*Successful Context Writes (SCW):* Número de arquivos de regras de negócio (Skills/Memories) gerados, atualizados e auditados com sucesso pelas IAs nas bases de código dos usuários.
+
+**Tabela de KPIs:**
+
+| Métrica | Baseline Atual | Meta 3 Meses | Meta 6 Meses | Como Medir |
+| :--- | :--- | :--- | :--- | :--- |
+| Instalações CLI (`npx`) | 0 | 5.000 | 15.000 | NPM Registry Stats |
+| Sucesso do `sauron check` | 0% | > 85% | > 95% | Telemetria anônima (CLI) |
+| Assinantes Cloud (SaaS) | 0 | 100 | 500 | Stripe Billing (Dashboard) |
+| MAU (Web Dashboard) | 0 | 500 | 2.500 | Google Analytics / PostHog |
+
+**Métricas de Produto:**
+- *Engajamento:* Média de comandos `sauron map` executados por usuário/semana.
+- *Retenção:* % de repositórios que continuam passando no `sauron check` após 30 dias do `init`.
+- *Adoção Multiplataforma:* % de usuários CLI que fazem login no Web Dashboard e baixam o Mobile App.
+
+**Métricas de Negócio:**
+- *Receita Recorrente Mensal (MRR):* Gerada pelas assinaturas premium de sincronização e aprovação Mobile.
+- *Churn de Assinatura:* Meta < 5% ao mês.
+- *LTV / CAC:* [PENDENTE: Estimar após validação de custos de ads do SaaS na Fase 2].
+
+---
+
+### 5. ESCOPO — IN & OUT
+
+**Lista In-Scope:**
+- Desenvolvimento da CLI com os comandos `init`, `check` e `map` (Prioridade Máxima: O núcleo que valida a tese de governança local).
+- Geração da estrutura de pastas `.sauron/` e `.agents/` e do `summary.json`.
+- Web Dashboard para gestão do contexto de times e gerenciamento de assinaturas SaaS (Prioridade Alta: Atende restrição multiplataforma).
+- Aplicativo Mobile para aprovações rápidas de mudanças de regras e monitoramento de alertas (Prioridade Média: Atende restrição de governança de squads).
+- Módulo de Assinaturas (Stripe) para liberação de acesso aos Adapters Cloud (Prioridade Alta: Sustentação de receita estipulada).
+
+**Lista Out-of-Scope:**
+- Execução direta de código-fonte pelo Sauron (Justificativa: O CLI é passivo; quem altera código é o Cursor/Windsurf).
+- Treinamento local de modelos LLM (Justificativa: Fora da proposta de infraestrutura de governança; muito custoso).
+- Versionamento de código integrado (O Sauron gerencia memória em Markdown, o Git continuará sendo a ferramenta para código-fonte).
+
+**Hipóteses Assumidas:**
+- Desenvolvedores aceitarão adicionar uma pasta oculta `.sauron` aos seus repositórios.
+- Assistentes de IA (LLMs atuais) têm capacidade analítica suficiente para respeitar instruções severas escritas em arquivos Markdown.
+- Tech Leads pagarão por um modelo SaaS/Assinatura para ter visibilidade Web e aprovações Mobile.
+
+**Restrições:**
+- *Técnicas:* O desenvolvimento do CLI inicial será feito por 1 Solo Founder usando Vibe Coding em 2 a 3 dias.
+- *Multiplataforma:* Web e Mobile exigem construção de API e banco de dados centralizado em nuvem paralela à CLI open-source.
+
+---
+
+### 6. REQUISITOS FUNCIONAIS
+
+*(Instrução Crítica seguida: Gherkin completo, mínimo 2 regras de negócio por feature, prioridades MoSCoW).*
+
+#### ÉPICO 1: Core CLI Tools (Governança Local)
+
+**Feature 1.1: Ejeção da Estrutura Inicial (`sauron init`)**
+- **User Story:** Como Indie Hacker, quero inicializar o Sauron na raiz do meu projeto, para que a IA receba imediatamente a arquitetura de memória e regras de negócio base.
+- **Regras de Negócio:**
+  1. O comando deve ser bloqueado se executado fora de um diretório válido ou se a pasta `.sauron` já existir.
+  2. O comando deve ejetar estritamente o manifesto `summary.json`, a pasta `.agents` e a pasta `.sauron/wiki/`.
+- **Critérios de Aceitação (Gherkin):**
+  - Dado que o usuário está na raiz de um projeto Node sem o Sauron instalado, quando ele executar `npx sauron-cli init`, então o sistema deve criar a estrutura de pastas `.sauron`, e exibir uma mensagem de sucesso no terminal com a cor verde.
+  - Dado que a pasta `.sauron` já existe no diretório atual, quando o usuário executar `npx sauron-cli init`, então o sistema deve abortar a operação, e exibir o erro "Sauron já inicializado neste diretório".
+- **Prioridade:** Must Have
+- **Complexidade:** P
+
+**Feature 1.2: Validação de Integridade (`sauron check`)**
+- **User Story:** Como desenvolvedor, quero rodar uma auditoria local nos arquivos Markdown, para que eu tenha certeza que a IA não corrompeu as métricas ou a estrutura exigida pelo framework.
+- **Regras de Negócio:**
+  1. Todos os arquivos `.md` na pasta `wiki` devem possuir um mapeamento exato no `summary.json` (match de ID, Slug e Type).
+  2. Arquivos órfãos (existem fisicamente, mas não no JSON) devem resultar em falha no check (exit code 1).
+- **Critérios de Aceitação (Gherkin):**
+  - Dado que a IA criou um novo arquivo Markdown sem atualizá-lo no `summary.json`, quando o usuário executar `sauron check`, então o CLI deve apontar falha de validação, e listar o nome do arquivo órfão no console.
+  - Dado que a estrutura Markdown e o `summary.json` estão perfeitamente sincronizados, quando o usuário executar `sauron check`, então o CLI deve retornar exit code 0, e exibir uma mensagem "Auditoria concluída com sucesso".
+- **Prioridade:** Must Have
+- **Complexidade:** M
+
+**Feature 1.3: Visualização do Cérebro (`sauron map`)**
+- **User Story:** Como desenvolvedor, quero visualizar a árvore de contexto atual, para que eu entenda rapidamente o que a IA já documentou sem precisar abrir os arquivos JSON ou Markdown um a um.
+- **Regras de Negócio:**
+  1. A exibição deve ser formatada em hierarquia de árvore via terminal utilizando biblioteca visual (ex: `chalk`).
+  2. O comando deve agrupar os itens por domínios (`knowledge`, `modules`, `standards`).
+- **Critérios de Aceitação (Gherkin):**
+  - Dado que o manifesto possui 3 domínios registrados, quando o usuário executar `sauron map`, então o sistema deve imprimir uma árvore colorida no terminal ilustrando a relação hierárquica, e agrupar os arquivos em seus respectivos domínios.
+  - Dado que o `summary.json` está vazio de regras, quando o usuário executar `sauron map`, então o sistema deve exibir um "Empty State" amigável, e sugerir que o usuário interaja com a IA para criar as primeiras regras.
+- **Prioridade:** Should Have
+- **Complexidade:** M
+
+#### ÉPICO 2: Ecossistema Multiplataforma & SaaS (Governança Escalonada)
+
+**Feature 2.1: Criação Completa de Projetos via Web Dashboard**
+- **User Story:** Como Tech Lead, quero acessar um dashboard web para visualizar e editar o repositório de memória das IAs dos meus squads de forma centralizada, para que padrões organizacionais sejam cumpridos.
+- **Regras de Negócio:**
+  1. O usuário Web deve ter nível de permissão "Admin" ou "Editor" vinculado ao plano da assinatura.
+  2. Qualquer alteração feita via Web atualizará o banco de dados nuvem e notificará os clientes locais via webhook ou adapter para sincronização posterior.
+- **Critérios de Aceitação (Gherkin):**
+  - Dado que o Tech Lead está autenticado no Web Dashboard com plano ativo, quando ele cria uma nova "Regra de Negócio Padrão" pela interface web, então o sistema deve salvar a regra no banco de dados centralizado, e propagar o status de sincronização pendente para o repositório vinculado.
+  - Dado que a assinatura do usuário está expirada, quando ele tenta salvar uma regra via Web, então o sistema deve bloquear a ação, e redirecioná-lo para a tela de pagamento.
+- **Prioridade:** Should Have (Fase 2)
+- **Complexidade:** G
+
+**Feature 2.2: Mobile App para Aprovações Rápidas (Governança)**
+- **User Story:** Como Tech Lead, quero receber notificações push no meu celular quando a IA de um júnior alterar uma regra core do Sauron, para que eu possa revisar e aprovar o contexto rapidamente de qualquer lugar.
+- **Regras de Negócio:**
+  1. Alterações em arquivos classificados como `type: "core_standard"` acionam uma trava (lock) e exigem aprovação via Mobile ou Web.
+  2. O app Mobile operará em modo "Read & Approve", não permitindo edição de blocos extensos de código.
+- **Critérios de Aceitação (Gherkin):**
+  - Dado que uma regra core foi modificada por um agente no CLI e submetida via Nuvem, quando o Tech Lead abrir o app Mobile, então ele deve ver um diff das mudanças, e visualizar os botões de "Aprovar" ou "Rejeitar".
+  - Dado que o Tech Lead clica em "Aprovar" no Mobile, quando a requisição é concluída, então a trava do arquivo é removida no banco de dados, e o desenvolvedor local recebe permissão para continuar a task.
+- **Prioridade:** Could Have (Fase 2)
+- **Complexidade:** GG
+
+**Feature 2.3: Motor de Assinaturas (Monetização Cloud)**
+- **User Story:** Como usuário corporativo, quero gerenciar meu plano de assinatura, para que meu time tenha acesso aos recursos de sincronização Cloud, Web e Mobile.
+- **Regras de Negócio:**
+  1. A cobrança ocorrerá via Stripe (cartão de crédito) em um modelo de assentos (per-seat pricing).
+  2. Cancelamento do plano reverte o repositório ao estado Open Source (apenas operação local via CLI, perdendo acesso Web/Mobile).
+- **Critérios de Aceitação (Gherkin):**
+  - Dado que um usuário acessa a aba "Billing" no Web Dashboard, quando ele preenche os dados do cartão via checkout do Stripe e confirma, então a conta é provisionada com status "Premium", e os recursos Mobile e Web são desbloqueados em tempo real.
+  - Dado que o pagamento mensal falha, quando passam-se 3 dias de retentativa, então a API deve revogar as chaves de sincronização em nuvem, e enviar um e-mail de aviso de downgrade.
+- **Prioridade:** Must Have (Fase SaaS)
+- **Complexidade:** G
+
+---
+
+### 7. REQUISITOS NÃO-FUNCIONAIS
+
+- **Performance:** 
+  - O comando `sauron check` deve varrer até 100 arquivos Markdown e validar o JSON associado em `< 50ms` localmente.
+  - O tempo de carregamento da "Tree View" no Dashboard Web deve ser `< 1.5s` (LCP).
+- **Segurança:** 
+  - Na versão Web/Mobile, todas as chaves de sincronização devem ser protegidas usando criptografia AES-256 no banco de dados.
+  - A autenticação Cloud deve exigir OAuth 2.0 (GitHub Login obrigatório). JWT tokens de sessão expiram em 24h.
+- **Conformidade Legal:** 
+  - Total conformidade com GDPR e LGPD: O sistema (na sua via SaaS) deve permitir a exclusão completa e permanente dos dados da conta do usuário em até 72 horas após o pedido (`Right to be Forgotten`).
+- **Escalabilidade:** 
+  - O banco de dados Web/Mobile (PostgreSQL) deve suportar no mínimo 1.000 requisições simultâneas de Webhooks de sincronização de CLI na Fase 2 (SaaS MVP) sem degradação de performance.
+- **Disponibilidade:** 
+  - A API do SaaS (Web/Mobile) deve garantir um SLA de 99.9% de uptime. Plano de contingência via fallback para AWS Multi-AZ no banco de dados. (O CLI Open Source possui 100% de disponibilidade por ser offline).
+- **Acessibilidade:** 
+  - O Dashboard Web deve atingir nota "AA" nos padrões WCAG 2.1 (contraste de cor, navegação completa por teclado e suporte a leitores de tela como NVDA/VoiceOver).
+- **Compatibilidade:** 
+  - CLI: Suporte nativo a Node.js v18+. Sistemas operacionais: Windows (PowerShell/WSL), macOS (Zsh), Linux (Bash).
+  - Web: Suporte aos navegadores Chrome v100+, Firefox v100+, Safari v15+.
+  - Mobile: Suporte a iOS 15+ e Android 11+.
+
+---
+
+### 8. FLUXOS DO USUÁRIO E JORNADA
+
+**Happy Path (Inicialização e Uso do CLI):**
+1. O usuário abre o terminal em um projeto existente.
+2. Executa o comando `npx sauron-cli init`.
+3. O CLI injeta a pasta `.sauron` e exibe mensagem de sucesso.
+4. O usuário abre sua IDE (Cursor) e inicia o chat com a IA.
+5. O usuário instrui a IA: "Implemente um sistema de login e siga as regras do Sauron".
+6. A IA lê a arquitetura, escreve o código do login e, seguindo o "Write Obligation", cria o arquivo `.sauron/wiki/auth-rules.md`.
+7. A IA atualiza automaticamente o `summary.json` mapeando a nova regra.
+8. O usuário roda `sauron check` e recebe aprovação verde ("Tudo sincronizado").
+9. O usuário roda `sauron map` e visualiza a nova estrutura mapeada no terminal.
+
+**Fluxo Alternativo (Correção de Erro de IA):**
+No passo 7, a IA esquece de atualizar o `summary.json`. No passo 8, o `sauron check` falha e exibe erro vermelho: "Arquivo órfão: auth-rules.md". O desenvolvedor pede para a IA: "Você esqueceu de mapear no JSON, conserte". A IA atualiza o JSON. O usuário roda `check` novamente, agora com sucesso.
+
+**Tabela de Edge Cases (Casos de Fronteira):**
+
+| Situação | Comportamento Esperado | Mensagem ao Usuário | Ação do Sistema |
+| :--- | :--- | :--- | :--- |
+| Rodar `init` em pasta sem permissão de escrita | CLI captura erro do File System. | "Erro: Permissão negada para gravar no diretório." | Aborta processo, Exit Code 1. |
+| Rodar `check` e o `summary.json` tem sintaxe inválida (malformado pela IA) | Parser falha de forma controlada, identificando a linha do erro. | "Falha crítica: summary.json possui sintaxe inválida na linha X." | Aborta o check imediatamente. |
+| Arquivo `.md` listado no JSON foi deletado fisicamente | Inconsistência apontada no check. | "Erro: Arquivo [nome] listado no JSON não existe." | Marca o check como falho. |
+| Tech Lead tenta aprovar regra no Mobile sem internet | App detecta estado offline da rede local. | "Sem conexão. Tente novamente mais tarde." | Salva aprovação pendente no cache local (Queue). |
+| Usuário com assinatura bloqueada tenta sincronizar CLI (`sauron push`) | Rejeição no servidor e no CLI local. | "Sincronização falhou. Assinatura Cloud inativa." | Bloqueia webhook HTTP 403 Forbidden. |
+| Usuário roda `map` num projeto gigante (+500 regras) | O comando paginará a exibição para não inundar o terminal. | "Mostrando regras 1-50 de 500. Pressione Espaço." | Ativa modo interativo de rolagem no terminal. |
+
+---
+
+### 9. REGRAS DE NEGÓCIO E LÓGICA
+
+- **Estados e Transições de Arquivos de Regra (Cloud/Mobile):**
+  - *Draft Local:* Gerado pela IA, validado pelo CLI, mas não sincronizado.
+  - *Em Revisão:* Sincronizado para a nuvem, aguardando aprovação do Tech Lead via Mobile.
+  - *Aprovado (Ativo):* Aprovado via Web/Mobile, serve de "Single Source of Truth" incontestável.
+  - *Obsoleto:* Substituído por nova versão arquitetural.
+- **Validações Críticas (Sauron Check):**
+  - O campo `id` no JSON deve ser único. Duplicações acionam erro fatal.
+  - O campo `type` deve pertencer ao enum: `["knowledge", "modules", "standards", "core_standard"]`.
+- **Regras de Acesso por Assinatura (Módulo SaaS):**
+  - *Plano OSS (Free):* Apenas comandos locais. Arquivos guardados na máquina/Git do usuário.
+  - *Plano Pro (SaaS):* Desbloqueia autenticação via Web, visualização de painéis e uso do Mobile App. Limite de 5 membros.
+- **Lógica de Permissões Multiplataforma:**
+  - `Admin`: Edita assinaturas, aprova regras no app Mobile.
+  - `Developer`: Roda CLI, sincroniza para revisão, visualiza painéis no Web, mas não aprova Core Standards.
+
+---
+
+### 10. INTEGRAÇÕES E DEPENDÊNCIAS
+
+| Serviço | Finalidade | Obrigatório para MVP? | Risco de Dependência | Fallback se indisponível | Versão / Endpoint |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Node FS API** | Manipulação de arquivos, escrita local do JSON e Markdown | Sim | Baixo (nativo) | N/A (crítico) | Nativo Node 18+ |
+| **Agentes de IA (Cursor/Windsurf)** | Execução real do projeto e documentação | Sim (passivo) | Médio (mudanças no prompt engine deles) | Uso de outro LLM via terminal | N/A |
+| **Stripe API** | Processamento de pagamento e assinaturas (SaaS) | Não (Apenas V2/SaaS) | Médio | Cobrança manual via invoice | `v1/checkout/sessions` |
+| **Expo / React Native** | Build do Mobile App de notificações/aprovações | Não (Apenas V2/SaaS) | Baixo | Acessar Dashboard Responsivo Web | SDK 50+ |
+| **GitHub OAuth** | Autenticação para Web Dashboard Cloud | Não (Apenas V2/SaaS) | Baixo | Autenticação por Magic Link (Email) | OAuth 2.0 / Autorize |
+
+---
+
+### 11. ARQUITETURA DE DADOS (HIGH-LEVEL)
+
+**Entidades Principais:**
+- **Summary (JSON):**
+  - `version` (String)
+  - `last_updated` (Timestamp)
+  - `domains` (Array of Object References)
+- **Domain (JSON/Lógico):**
+  - `id` (UUID)
+  - `name` (String)
+  - `files` (Array of Markdown Files)
+- **File / Rule (Markdown Físico):**
+  - `slug` (String, ex: "auth-rules")
+  - `content` (Text, armazenado localmente e mapeado via nuvem na V2)
+- **UserAccount (DB Nuvem):**
+  - `uuid` (UUID)
+  - `email` (String, Sensível)
+  - `plan` (Enum: Free, Pro)
+  - `role` (Enum: Admin, Developer)
+
+**Estratégia de Banco de Dados:**
+- *CLI (V1):* Totalmente local (Relacional em JSON File System). Nenhuma dependência externa.
+- *Web/Mobile (SaaS V2):* PostgreSQL relacional (hospedado na AWS/Supabase) para armazenar usuários, permissões, logs de sincronização e assinaturas. Cache via Redis para listagem rápida de árvores (`sauron map` via Web).
+
+**Dados Sensíveis e Proteção:**
+Os arquivos de código e memória das empresas não devem vazar. No plano Cloud (SaaS), o conteúdo em Markdown enviado pelas APIs de sincronização será encriptado at-rest utilizando chaves KMS geradas por usuário (E2E Encryption Strategy), garantindo soberania dos dados do cliente.
+
+---
+
+### 12. DIRETRIZES DE UX/UI
+
+**Princípios de Design:**
+1. *Terminal-First Elegance:* A interface de CLI deve ser limpa, com uso sutil de cores para guiar o usuário sem poluir o log.
+2. *Clareza Determinística:* Se houver erro, a ferramenta deve apontar exatamente a linha e o arquivo (Fail loudly and clearly).
+3. *Single Pane of Glass:* O Dashboard Web deve permitir visualização da topologia do cérebro da aplicação em uma única tela.
+4. *Fricção Intencional:* No Mobile App, aprovações críticas (mudança de regras core) exigem duplo clique ou "swipe-to-approve" para evitar aprovações acidentais.
+
+**Estados Críticos da UI:**
+- *Empty State (CLI):* Ao rodar `map` vazio, terminal retorna em amarelo: `[Sauron] O cérebro está vazio. Peça para a IA criar as primeiras memórias.`
+- *Loading (Web):* Skeleton screens reproduzindo a árvore de arquivos enquanto a API Cloud busca o `summary.json` em nuvem.
+- *Erro (Mobile):* Modal vermelho se falha a sincronização, com botão de "Retry Network".
+- *Sucesso (CLI):* Texto em negrito e verde vivo utilizando `chalk.green.bold()`.
+
+**Tom de Voz e Microcopy:**
+- *Perfil:* Assertivo, cirúrgico, assistente confiável ("Lobo frontal").
+- *Exemplo de Erro:* "Erro fatal: Encontramos um arquivo fantasma. `database-rules.md` existe, mas não está no `summary.json`."
+
+**Distinção de Experiência entre Plataformas:**
+- *CLI:* Foco total no desenvolvedor, ações de terminal, respostas textuais.
+- *Web:* Foco na topologia e overview gerencial, gráficos de saúde da documentação.
+- *Mobile:* Interface simplificada estilo "Tinder de Code Review" — aprova ou rejeita regras alteradas pelas IAs em tempo real.
+
+---
+
+### 13. RISCOS, PREMISSAS E MITIGAÇÕES
+
+| Risco | Categoria | Probabilidade | Impacto | Mitigação | Responsável |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| **Alucinação da IA corrompendo o JSON** | Técnico | Alta | Alto | O comando `sauron check` fará validação rígida, impedindo sincronizações defeituosas. | [PENDENTE: Eng. Principal] |
+| **Adoção pelo Usuário (Baixa adesão à disciplina de Write)** | Negócio | Média | Alto | Criar templates perfeitos (`memory.md`, `skill.md`) injetados via `init` que "forçam" a IA a respeitar a estrutura. | [PENDENTE: PM / UX] |
+| **Mudança na Política/API de Terceiros (IDE Agents)** | Técnico | Baixa | Médio | Como a infraestrutura é passiva e baseada em Markdown, o risco é baixo. Arquivos `.md` são padrões universais. | [PENDENTE: Arquiteto] |
+| **Resistência ao modelo SaaS Web/Mobile por Tech Leads** | Negócio | Alta | Médio | Focar na fase MVP Open Source para Indie Hackers. Quando a tração orgânica vier, o up-sell para o time corporativo será natural. | [PENDENTE: Growth/Vendas] |
+| **Risco Regulatório e Privacidade de Dados (SaaS Cloud)** | Operacional | Baixa | Alto | Adotar estratégia "Bring Your Own Database (Adapters)" ou garantir criptografia E2E na sincronização da Nuvem Oficial. | [PENDENTE: Legal/Security] |
+| **Dificuldade na Aprovação App Mobile nas Lojas (Apple/Google)** | Operacional | Baixa | Baixo | Preparar os termos de serviço focados em B2B e prever Web App (PWA) como fallback provisório. | [PENDENTE: Mobile Dev] |
+
+---
+
+### 14. ROADMAP E FASES DE ENTREGA
+
+| Feature / Módulo | Tamanho | Prioridade (MoSCoW) | Dependências |
+| :--- | :--- | :--- | :--- |
+| **Fase 1: MVP CLI (Open Source V1)** |
+| Ejeção de Estrutura (`sauron init`) | S | Must Have | Setup inicial do Tsup/Commander |
+| Auditoria de Integridade (`sauron check`) | M | Must Have | `init` funcional |
+| Visão Hierárquica (`sauron map`) | M | Should Have | `check` e `init` |
+| **Fase 2: Expansão Cloud & SaaS (V2)** |
+| Web Dashboard (Criação/Monitoramento) | XL | Must Have | Backend / API REST em nuvem |
+| Motor de Assinaturas (Stripe) | L | Must Have | Dashboard Web criado |
+| API de Adapters / Sincronização Local-Nuvem| L | Should Have | Web Dashboard operante |
+| **Fase 3: Mobile & Governança de Squads (V3)**|
+| App Mobile Native (Aprovações push) | XL | Could Have | API Cloud / Adapters |
+| Lock System de Arquivos (Governança) | L | Must Have | App Mobile operante |
+
+---
+
+### 15. CRITÉRIOS DE ACEITAÇÃO E DOD
+
+**Definition of Done (DoD) Geral do Projeto:**
+- [ ] O código passou em lint, formatação e verificação de tipagem estática (TypeScript strict mode).
+- [ ] Testes unitários (Jest/Vitest) cobrem ao menos 80% dos parsers e validadores do CLI.
+- [ ] As 3 features críticas possuem testes de cenário feliz, alternativo e falha documentados.
+- [ ] O comando `npx sauron-cli` pode ser executado globalmente sem erros de permissionamento no SO.
+- [ ] A interface CLI retorna mensagens claras de sucesso e erro ao usuário.
+- [ ] As variáveis de ambiente SaaS (Web/Mobile) estão devidamente encriptadas.
+- [ ] Documentação do README do Open Source está revisada, instruindo como instalar.
+- [ ] O Release está publicado via pipeline automatizada (GitHub Actions para NPM, Vercel para Web).
+
+**Cenários de Teste para Feature Crítica (`sauron check`):**
+- *Cenário Feliz:* Rode o `check` num projeto perfeito. A validação deve retornar verde e demorar < 50ms.
+- *Cenário Alternativo:* Adicione manualmente um novo domínio no JSON com lista vazia de arquivos. O `check` deve alertar "Domínio vazio detectado", mas não deve quebrar/falhar com exit code 1 (warning, not error).
+- *Cenário de Erro:* Remova uma aspa dupla do arquivo `summary.json`. O parser JSON nativo lançará erro. O Sauron deve capturá-lo e imprimir de forma elegante no console em vez de vomitar um stack trace ilegível do Node.js.
+
+---
+
+### 16. PLANO DE LANÇAMENTO
+
+**Fases de Lançamento:**
+1. **Alpha Fechado (Solo Founder & IAs):** O fundador utilizará a CLI nos seus próprios projetos de laboratório durante 1 semana.
+   - *Go/No-go:* Se a IA alucinar as regras ou quebrar o JSON mais de 3 vezes por semana, retorna para revisão de prompt.
+2. **Beta Aberto (Comunidade Indie Hacker):** Divulgação no X (Twitter) e Product Hunt do pacote via NPM (`npx sauron-cli`).
+   - *Critério:* Chegar a 1.000 instalações. Feedback intensivo de dev solos focados no modelo Open Source.
+3. **Lançamento SaaS Phase (Fase 2 - Web Dashboard):** Abertura do modelo de monetização com Early-bird pricing.
+   - *Onboarding:* E-mails educacionais para a base do pacote NPM mostrando os benefícios do sincronismo em nuvem.
+4. **General Availability (GA Mobile - Fase 3):** App chega às lojas oficiais (App Store / Play Store) direcionando marketing para Tech Leads e empresas B2B.
+
+**Métricas de Adoção Inicial:**
+Monitorar retenção do pacote NPM no primeiro mês de uso (se os usuários continuam rodando `sauron check` semanas após a instalação, provando o valor a longo prazo).
+
+---
+
+### GLOSSÁRIO
+
+1. **Amnésia de Contexto:** Limitação dos agentes de IA em recordar decisões de negócio passadas durante sessões prolongadas de desenvolvimento.
+2. **Context Window:** O limite numérico de tokens (palavras/caracteres) que uma Inteligência Artificial consegue processar em um único prompt.
+3. **Vibe Coding:** Paradigma moderno de desenvolvimento onde o humano apenas escreve prompts e orquestra, enquanto a IA escreve e compila todo o código.
+4. **Write Obligation:** Conceito central do Sauron onde a IA é arquiteturalmente forçada a documentar ativamente regras no projeto (escrever memórias), e não apenas ler repositórios.
+5. **LLM (Large Language Model):** Modelo de linguagem de grande escala (ex: GPT-4, Claude 3) que alimenta os agentes de código.
+6. **Agente Executável:** Ferramentas de IA (como Aider e Devin) que tomam ações ativas no terminal e alteram o código diretamente.
+7. **Lobo Frontal:** Metáfora anatômica utilizada para descrever o Sauron CLI; a área cerebral responsável pela tomada de decisão, comportamento padrão e memória de longo prazo das IAs.
+8. **Single Source of Truth (SSOT):** Prática de estruturar dados/regras de forma que exista um único ponto de referência confiável.
+9. **Sauron Adapters:** Scripts ou conectores open-source que permitirão ligar os dados locais do CLI a bancos de dados externos (SaaS/Cloud).
+10. **MoSCoW:** Técnica de priorização de requisitos (Must, Should, Could, Won't have).
+
+---
+
+### APÊNDICE
+
+**Perguntas Abertas para o Time:**
+1. O parser do comando `check` deve usar validações restritas via Zod no TypeScript, ou deixaremos a lógica customizada para garantir performance máxima sem dependências extras?
+2. Para o fluxo do "Sauron Cloud / Web Dashboard", como garantiremos a criptografia ponta a ponta sem onerar a experiência de busca no banco PostgreSQL?
+3. O modelo de assinatura (Stripe) deve cobrar um valor base pelo "Team Workspace" + taxa por usuário adicional, ou ser flat-rate na V1 do SaaS?
+4. A injeção das pastas e templates via `sauron init` sobrescreverá arquivos com nomes similares (risco destrutivo), ou irá dar append seguro? Precisamos decidir o comportamento do Merge.
+5. Como os Agentes vão lidar com limites rigorosos de rate-limiting (tokens) ao ler uma estrutura de "Memórias" que começar a ultrapassar 50+ arquivos Markdown? Teremos um sistema de auto-compressão no roadmap futuro?
+
+**Referências:**
+- Documentação do Commander.js: `https://github.com/tj/commander.js/`
+- Arquiteturas de Vibe Coding & Context Management (Pesquisas em IA e Repomix).
+- Padrões WCAG 2.1 para o Dashboard Web.
+
+**Histórico de Versões:**
+- *v1.0:* Criação do PRD cobrindo Core CLI, Injeção multiplataforma (Web/Mobile) e Módulo de Monetização. Elaborado pelo Product Manager Senior (IA).

package/dist/index.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/commands/init.ts
+import fs from "fs-extra";
+import path from "path";
+import pc from "picocolors";
+import { fileURLToPath } from "url";
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+async function runInit() {
+  const cwd = process.cwd();
+  const packageRoot = path.join(__dirname, "..");
+  const templatesDir = path.join(packageRoot, "templates");
+  const targetSauronDir = path.join(cwd, ".sauron");
+  const targetAgentsDir = path.join(cwd, ".agents");
+  console.log(pc.blue("Inicializando Sauron Memory System..."));
+  if (await fs.pathExists(targetSauronDir) || await fs.pathExists(targetAgentsDir)) {
+    console.error(pc.red("Erro: Sauron j\xE1 inicializado neste diret\xF3rio (pasta .sauron ou .agents existente)."));
+    process.exit(1);
+  }
+  try {
+    const sourceSauronDir = path.join(templatesDir, ".sauron");
+    const sourceAgentsDir = path.join(templatesDir, ".agents");
+    if (await fs.pathExists(sourceAgentsDir)) {
+      await fs.copy(sourceAgentsDir, targetAgentsDir);
+    } else {
+      console.warn(pc.yellow(`Aviso: Pasta .agents n\xE3o encontrada nos templates originais (${sourceAgentsDir}).`));
+    }
+    if (await fs.pathExists(sourceSauronDir)) {
+      await fs.copy(sourceSauronDir, targetSauronDir);
+    } else {
+      console.warn(pc.yellow(`Aviso: Pasta .sauron n\xE3o encontrada nos templates originais (${sourceSauronDir}).`));
+    }
+    console.log(pc.green(pc.bold("\nSauron Memory System instalado com sucesso! \u{1F441}\uFE0F\n")));
+    console.log(pc.white("O C\xE9rebro da IA foi ejetado neste diret\xF3rio. A partir de agora, suas IAs documentar\xE3o regras passivamente.\n"));
+  } catch (error) {
+    console.error(pc.red("Erro fatal ao ejetar os arquivos do Sauron:"), error);
+    process.exit(1);
+  }
+}
+
+// src/index.ts
+var program = new Command();
+program.name("sauron").description("Sauron CLI - Framework para resolu\xE7\xE3o de Amn\xE9sia de Contexto em IAs").version("1.0.0");
+program.command("init").description("Inicializa o Sauron Memory System no projeto atual").action(runInit);
+program.parse();

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "sauron-cli",
+  "version": "1.0.0",
+  "description": "",
+  "main": "dist/index.js",
+  "bin": {
+    "sauron": "./dist/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^15.0.0",
+    "fs-extra": "^11.3.5",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}

package/sauron_cli_implementation_plan.md

@@ -0,0 +1,62 @@
+# Plano de Implementação: Sauron CLI
+
+Este é o plano detalhado de construção técnica do framework Sauron CLI. Ao iniciar um novo projeto, entregue este plano para o seu agente de IA para que ele possa executar a construção em 5 fases.
+
+## Fase 1: Setup do Repositório
+**Objetivo:** Inicializar o projeto Node.js e instalar o maquinário do CLI.
+
+1. Inicialize um pacote Node.js (`npm init -y`).
+2. Defina o campo `"bin": { "sauron": "./dist/index.js" }` e `"type": "module"` no `package.json`.
+3. Instale as dependências essenciais: 
+   - `npm install commander fs-extra picocolors`
+   - `npm install -D typescript @types/node @types/fs-extra tsup`
+4. Crie o arquivo `tsconfig.json` básico.
+5. Crie um script no `package.json`: `"build": "tsup src/index.ts --format esm --clean"`.
+
+## Fase 2: Construção dos Templates (O Coração)
+**Objetivo:** Criar a pasta que armazena as réplicas exatas do sistema Sauron que serão ejetadas nas máquinas dos usuários.
+
+Crie fisicamente a seguinte estrutura no diretório `templates/`:
+```plaintext
+templates/
+├── .agents/
+│   ├── rules/
+│   │   └── memory.md       (Conteúdo que orienta a IA a ler o Sauron)
+│   └── skills/
+│       └── wiki/
+│           └── SKILL.md    (Conteúdo da Write Obligation / Regra do Sauron)
+└── .sauron/
+    └── wiki/
+        ├── summary.json    (Arquivo inicial de mapa vazio)
+        ├── history/
+        ├── knowledge/
+        ├── manuals/
+        ├── modules/
+        └── standards/
+```
+
+## Fase 3: Desenvolvimento do Core CLI (`src/index.ts`)
+**Objetivo:** Criar a porta de entrada que escuta o comando do usuário.
+
+1. Crie a pasta `src/` e o arquivo `index.ts`.
+2. Adicione a shebang line no topo de `index.ts`: `#!/usr/bin/env node`.
+3. Configure o `commander` para iniciar o programa, declarando nome, versão e descrição.
+4. Registre o comando primário: `program.command('init').description('Inicializa o Sauron Memory System no projeto atual').action(runInit)`.
+
+## Fase 4: Lógica do Comando Init (`src/commands/init.ts`)
+**Objetivo:** O motor que vai copiar os templates.
+
+1. Identifique o diretório de execução do usuário usando `process.cwd()`.
+2. Identifique onde os templates do CLI estão localizados localmente usando `__dirname` e caminhos relativos (cuidado com as diferenças de pathing no momento em que o código vira bundle pelo `tsup`).
+3. Verifique com `fs-extra.pathExists` se `.sauron` ou `.agents` já existem no destino. Se sim, logue um aviso colorido com `picocolors` sugerindo cuidado ou pulando etapas não-destrutivas.
+4. Execute `fs-extra.copy()` para ejetar `templates/.agents/` e `templates/.sauron/` para o `process.cwd()`.
+5. Exiba mensagens visuais de sucesso indicando que a memória da IA está instalada.
+
+## Fase 5: Build, Teste e Deploy
+**Objetivo:** Empacotar e preparar para NPM.
+
+1. Rode `npm run build`. O `tsup` deverá gerar a pasta `dist/` com o binário minificado.
+2. Na raiz do projeto CLI, rode `npm link` para testar o binário globalmente no sistema local.
+3. Crie uma pasta vazia aleatória e rode `sauron init` para atestar que os templates são injetados.
+4. Adicione um arquivo `.npmignore` garantindo que os `templates/` e `dist/` não fiquem de fora da publicação (cuidado, `dist` costuma ficar no `.gitignore`).
+5. (Final) Para a distribuição global, rode `npm login` seguido de `npm publish --access public`.

package/templates/.agents/rules/memory.md

@@ -0,0 +1,128 @@
+---
+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**.

package/templates/.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/templates/.sauron/wiki/summary.json

@@ -0,0 +1,37 @@
+[
+  {
+    "type": "folder",
+    "name": "History",
+    "slug": "history",
+    "path": "history",
+    "id": "domain-history"
+  },
+  {
+    "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"
+  }
+]