Feat/agnostic architecture - Arquitetura Agnóstica e Adaptação Dinâmica de Ambiente

.gitignore

@@ -11,3 +11,16 @@ build/
 deploy_release/
 
 foton_system/config/settings.json
+
+.obsidian/
+
+# Test Artifacts & Temporary Files
+test_*.txt
+test_*.xlsx
+test.xlsx
+*.bak
+GERADO_*
+tmp/
+.pytest_cache/
+.coverage
+htmlcov/

README.md

@@ -1,33 +1,22 @@
-# FOTON System 💡
+# 💡 FOTON System
 
 > **Transforme o Caos de Arquivos em uma Máquina de Gestão.**
 
 O FOTON System organiza, sincroniza e automatiza seu escritório de arquitetura, eliminando o tempo perdido procurando arquivos e gerando documentos.
 
----
-
-## 📚 Navegação Rápida (Obsidian Vault)
-
-### 🎯 **[👉 COMECE AQUI: DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)** ← Mapa completo de tudo!
-
-### 🎯 Para Começar
-
-- [[UserGuide|📖 Guia do Usuário]] - Manual completo (Modo Visual & Turbo TUI)
-- [[deployment_guide|🚀 Guia de Instalação]] - Instale o Executável (.exe)
-- [[DEPLOYMENT_USER_GUIDE|💾 Implantação e Backup]] - Ferramenta nova! Base de dados inteligente
-- [[mcp_guide|🤖 Integração com IA]] - Controle por voz/texto (Claude/Cursor)
+## 📚 Documentação (Acesso Rápido)
 
-### 🧠 Entendendo o Sistema
+### 🏛️ Para Agentes de IA
+- [[LlmProtocol|📜 Protocolo de Documentação]] - **LEITURA OBRIGATÓRIA PARA AGENTES**
+- [[Index|🗺️ Mapa de Conteúdo (MOC)]] - Navegação por domínios
+- [[LlmContext|🧠 Contexto Geral para LLMs]] - Identidade do sistema
+- [[SystemManifest|📋 Manifesto do Sistema]] - Visão geral técnica
 
-- [[Pipelines|🔄 Como a Mágica Acontece]] - Fluxo de dados simplificado
-- [[concepts|🏗️ Arquitetura do Sistema]] - Conceitos técnicos (Hexagonal)
-- [[DataModel|📊 Modelo de Dados]] - Estrutura de arquivos e DB
-
-### 👨‍💻 Para Desenvolvedores
-
-- [[AI_INTEGRATION_REPORT|🤖 Relatório de IA]] - Como a IA se integra
-- [[AGENTIC_SPRINT_PLAN|📋 Planejamento Agentic]] - Sprints e roadmap
-- [[workplan|📅 Plano de Trabalho]] - Tarefas e milestones
+### 🎯 Para o Arquiteto (Usuário)
+- [[UserGuide|📖 Guia do Usuário]] - Manual completo
+- [[DeploymentUserGuide|💾 Implantação e Backup]] - Guia de segurança de dados
+- [[TuiGuide|📟 Guia do Modo Terminal]] - Produtividade turbo
+- [[QuickReference|📑 Referência Rápida]] - Comandos e atalhos
 
 ---
 
@@ -43,11 +32,11 @@ Um dia, você precisa gerar 5 propostas urgentes. Você abre a pasta do cliente
 
 ### A Solução
 
-Você instala o FOTON. (Veja [[deployment_guide|como instalar]])
+Você instala o FOTON. (Veja [[DeploymentGuide|como instalar]])
 
-1. **Sincronização Mágica**: Com um clique, o FOTON lê suas pastas e arruma seu Excel. "J. Silva" e "João Silva" viram a mesma pessoa. ([[Pipelines#Sincronização|Como funciona]])
+1. **Sincronização Mágica**: Com um clique, o FOTON lê suas pastas e arruma seu Excel. "J. Silva" e "João Silva" viram a mesma pessoa. ([[Pipelines|Como funciona]])
 2. **Centros de Verdade**: O FOTON cria um arquivo `INFO-CLIENTE.md` dentro da pasta do João. Agora, os dados moram onde o projeto mora. ([[DataModel|Entenda a estrutura]])
-3. **Automação**: Para gerar as 5 propostas, você só digita o valor. O FOTON puxa o nome, endereço e CPF do João automaticamente e gera o PDF. Sem erro de digitação. ([[UserGuide#Geração de Documentos|Veja como]])
+3. **Automação**: Para gerar as 5 propostas, você só digita o valor. O FOTON puxa o nome, endereço e CPF do João automaticamente e gera o PDF. Sem erro de digitação. ([[UserGuide|Veja como]])
 
 ### O Retorno a Produtividade
 
@@ -61,29 +50,29 @@ Você gastou 10 minutos no que levaria 2 horas. Seus arquivos estão organizados
 
 > "O Fim do 'Onde Salvei?'"
 
-- **Sincronização Bidirecional**: O que está na pasta vai para o Excel, e vice-versa. ([[Pipelines#Sincronização|Veja o fluxo]])
-- **Banco de Dados Distribuído**: Seus dados vivem nas pastas, em arquivos de texto simples (`INFO-*.md`). Leves, seguros e fáceis de editar. ([[DataModel#Centros de Verdade|Saiba mais]])
+- **Sincronização Bidirecional**: O que está na pasta vai para o Excel, e vice-versa. ([[Pipelines|Veja o fluxo]])
+- **Banco de Dados Distribuído**: Seus dados vivem nas pastas, em arquivos de texto simples (`INFO-*.md`). Leves, seguros e fáceis de editar. ([[DataModel|Saiba mais]])
 
 ### 2. Geração de Documentos
 
 > "Adeus, Ctrl+C Ctrl+V"
 
-- **Context-Aware**: O sistema sabe quem é o cliente pela pasta onde você está. ([[concepts#Context-Aware Engine|Entenda a lógica]])
-- **Templates Inteligentes**: Use seus modelos de Word e PowerPoint. O sistema preenche as lacunas (`@nome`, `@valor`) para você. ([[UserGuide#Geração de Documentos|Tutorial completo]])
+- **Context-Aware**: O sistema sabe quem é o cliente pela pasta onde você está. ([[Concepts|Entenda a lógica]])       
+- **Templates Inteligentes**: Use seus modelos de Word e PowerPoint. O sistema preenche as lacunas (`@nome`, `@valor`) para você. ([[UserGuide|Tutorial completo]])
 
 ### 3. Integração com IA
 
 > "Seu assistente que nunca esquece nada"
 
-- **Controle por Voz/Texto**: Use Claude ou Cursor para gerenciar o escritório em linguagem natural. ([[mcp_guide|Configure em 2 minutos]])
-- **Memória Vetorial (RAG)**: Pergunte "O que sabemos sobre projetos residenciais?" e a IA busca em todos os seus documentos. ([[AI_INTEGRATION_REPORT|Como funciona]])
+- **Controle por Voz/Texto**: Use Claude ou Cursor para gerenciar o escritório em linguagem natural. ([[McpGuide|Configure em 2 minutos]])
+- **Memória Vetorial (RAG)**: Pergunte "O que sabemos sobre projetos residenciais?" e a IA busca em todos os seus documentos. ([[AiIntegrationReport|Como funciona]])
 
 ### 4. Modo Avançado (Ferramentas Administrativas)
 
 > "Para quando você precisa de super poderes"
 
-- **Refatoração de Dados**: Mudou o nome de uma variável? O sistema atualiza todos os seus arquivos de uma vez. ([[UserGuide#Schema Manager|Veja como]])
-- **Diagnóstico**: Um "Check-up" completo para garantir que nenhuma pasta está perdida ou sem dono. ([[UserGuide#Diagnóstico|Entenda]])
+- **Refatoração de Dados**: Mudou o nome de uma variável? O sistema atualiza todos os seus arquivos de uma vez. ([[UserGuide|Veja como]])
+- **Diagnóstico**: Um "Check-up" completo para garantir que nenhuma pasta está perdida ou sem dono. ([[UserGuide|Entenda]])    
 
 ---
 
@@ -97,8 +86,8 @@ Baixe o instalador na aba **Releases** do GitHub e rode. Pronto!
 
 ```bash
 pip install -r requirements.txt
-python foton_system/interfaces/cli/main.py --tui  # Modo Turbo (Terminal)
-python foton_system/interfaces/cli/main.py --gui  # Modo Visual (Janelas)
+python -m foton_system.main --tui  # Modo Turbo (Terminal)
+python -m foton_system.main --gui  # Modo Visual (Janelas)
 ```
 
 Use `foton --info` para ver onde seus dados estão salvos.
@@ -112,25 +101,25 @@ graph TD
     README[📄 README] --> UserGuide[📖 User Guide]
     README --> Pipelines[🔄 Pipelines]
     README --> deployment[🚀 Deploy Guide]
-    
+
     UserGuide --> TUI[📟 TUI Guide]
     UserGuide --> mcp[🤖 MCP Guide]
-    
+
     Pipelines --> concepts[🏗️ Concepts]
     concepts --> MCPServices[⚡ MCP Services Layer]
-    
+
     deployment --> workplan[📅 Work Plan]
 ```
 
 ---
 
 ## 📖 Leia Também
 
-- [[concepts|Conceitos de Arquitetura]] - Entenda a Arquitetura Hexagonal
+- [[Concepts|Conceitos de Arquitetura]] - Entenda a Arquitetura Hexagonal
 - [[Pipelines|Pipelines do Sistema]] - Visualize o fluxo de dados
 - [[DataModel|Modelo de Dados]] - Como os dados estão organizados
-- [[AI_INTEGRATION_REPORT|IA no FOTON]] - Como a inteligência artificial ajuda
-- [[workplan|Plano de Trabalho]] - Roadmap e funcionalidades planejadas
+- [[AiIntegrationReport|IA no FOTON]] - Como a inteligência artificial ajuda
+- [[WorkPlan|Plano de Trabalho]] - Roadmap e funcionalidades planejadas
 
 ---
 

docs/00_META/ADR/ADR001_ParaZettelkastenDoc.md

@@ -0,0 +1,27 @@
+---
+type: adr
+domain: core
+status: accepted
+date: 2026-05-11
+---
+# ADR001: Adoção do Modelo PARA + Zettelkasten para Documentação
+
+## Status
+Aceito
+
+## Contexto
+A documentação anterior do FOTON System estava dispersa, com links quebrados e sem uma estrutura clara de evolução. Isso dificultava tanto o uso por humanos quanto a navegação por agentes de IA, aumentando a entropia do repositório.
+
+## Decisão
+Adotar uma estrutura híbrida baseada em:
+1.  **PARA (Projects, Areas, Resources, Archives):** Para categorizar o ciclo de vida da informação.
+2.  **Zettelkasten:** Para criar um grafo de conhecimento interligado por links bi-direcionais (`[[link]]`) e metadados (Frontmatter YAML).
+
+## Consequências
+- **Positivas:** Maior rastreabilidade, facilidade de onboarding para IAs, histórico de sprints preservado.
+- **Negativas:** Requer rigor na manutenção dos metadados e na localização dos arquivos.
+
+---
+## 🔗 Links Relacionados
+- Índice de ADRs: [[Index]]
+- Protocolo: [[LlmProtocol]]

docs/00_META/ADR/ADR002_PascalCaseNaming.md

@@ -0,0 +1,26 @@
+---
+type: adr
+domain: core
+status: accepted
+date: 2026-05-11
+---
+# ADR002: Padronização de Nomenclatura PascalCase para Documentos
+
+## Status
+Aceito
+
+## Contexto
+Arquivos Markdown na pasta `docs/` seguiam múltiplos padrões (snake_case, UPPER_CASE, camelCase), o que gerava inconsistências nos links bi-direcionais e dificultava a predição de caminhos por scripts e IAs.
+
+## Decisão
+Padronizar todos os nomes de arquivos de documentação para **PascalCase** (ex: `UserGuide.md`).
+Pastas meta e de projeto mantêm o prefixo numérico ou descritivo em snake_case para ordenação no sistema de arquivos.
+
+## Consequências
+- **Positivas:** Coesão visual, links previsíveis, conformidade com padrões de "Wikis" modernas.
+- **Negativas:** Necessidade de renomear arquivos existentes e atualizar todas as referências internas.
+
+---
+## 🔗 Links Relacionados
+- Protocolo: [[LlmProtocol]]
+- Índice: [[Index]]

docs/00_META/ADR/ADR003_SandboxTestIsolation.md

@@ -0,0 +1,20 @@
+# ADR 003: Isolamento de Testes via Modo Sandbox
+
+## Status
+Proposto
+
+## Contexto
+O Foton System manipula dados críticos de escritórios de arquitetura (Excel, arquivos Markdown de clientes e documentos legais). A execução de testes (Unitários, Integração ou E2E) no ambiente de desenvolvimento corre o risco de corromper ou misturar dados de teste com dados reais, especialmente em máquinas onde o sistema está instalado para uso produtivo.
+
+## Decisão
+Fica estabelecido que **todos os testes automatizados** devem obrigatoriamente operar em **Modo Sandbox**.
+
+1. **Ativação Obrigatória:** Todo `setUpClass` de suítes de teste de integração ou E2E deve chamar `PathManager.set_sandbox_mode(True)`.
+2. **Isolamento de Diretório:** Os testes devem utilizar um subdiretório exclusivo dentro da pasta temporária do sistema (ex: `%TEMP%/foton_tests_XXXX`) para garantir que execuções paralelas não interfiram entre si.
+3. **Limpeza Automática:** O `tearDownClass` deve ser responsável por limpar o diretório temporário e desativar o modo sandbox (`set_sandbox_mode(False)`).
+4. **Configuração Volátil:** Os testes não devem ler o `settings.json` real do usuário. O `Config()` deve ser reinicializado ou sobreposto com caminhos apontando para o sandbox.
+
+## Consequências
+- **Segurança:** Risco zero de deleção ou modificação acidental de dados reais do usuário durante o desenvolvimento.
+* **Reprodutibilidade:** Testes rodam em um ambiente "limpo" e controlado, independente da máquina onde estão sendo executados.
+* **Complexidade:** Requer um boilerplate consistente em todos os arquivos de teste para garantir que o `PathManager` e o `Config` estejam devidamente isolados.

CONTRIBUTING.md → docs/00_META/Contributing.md

@@ -1,4 +1,10 @@
-# Contribuindo para o FOTON System
+---
+type: guide
+domain: core
+status: active
+tags: [contributing, development, collaboration]
+---
+# Contribuindo para o FOTON System (Contributing)
 
 Obrigado pelo interesse em contribuir para o FOTON System! 🎉
 Este documento define as diretrizes para garantir que a colaboração seja produtiva e organizada.
@@ -85,3 +91,9 @@ Ao abrir uma Issue, por favor inclua:
 * Screenshots ou logs de erro.
 
 Obrigado por ajudar a construir o FOTON System! 🚀
+
+---
+## 🔗 Links Relacionados
+- Índice: [[Index]]
+- Manifesto: [[SystemManifest]]
+- Protocolo: [[LlmProtocol]]

docs/00_META/Dictionary.md

@@ -0,0 +1,35 @@
+---
+type: concept
+domain: core
+status: active
+tags: [meta, dictionary, ddd, terms]
+---
+# 📖 Dicionário de Domínios e Termos (Dictionary)
+
+Este documento serve como a **Ubiquitous Language** (DDD) do FOTON System. Aqui definimos o que cada termo significa para garantir que Humanos e IAs falem a mesma língua.
+
+## 🏛️ Termos de Arquitetura
+
+- **Centro de Verdade (Center of Truth):** Arquivo `.md` (INFO-CLIENTE, INFO-SERVICO) que detém a autoridade sobre os dados de um projeto.
+- **RalphLoop:** Ciclo agêntico de "Pesquisa -> Plano -> Ação -> Validação".
+- **Hexagonal Architecture:** Padrão que isola a lógica de negócio (Core) de implementações externas (Adapters).
+- **Zettelkasten + PARA:** Sistema de organização de notas interligadas por grafos e esferas de responsabilidade.
+
+## 👥 Termos de Negócio (Escritório)
+
+- **Cliente:** Pessoa ou entidade que contrata os serviços de arquitetura.
+- **Serviço (Service):** Um sub-projeto ou demanda específica vinculada a um cliente (ex: Projeto Executivo, Consultoria).
+- **Template:** Modelo de documento (Word/PowerPoint) com variáveis `@tags`.
+- **CUB (Custo Unitário Básico):** Índice usado para estimativas de custos de construção.
+
+## 🤖 Termos Técnicos
+
+- **MCP (Model Context Protocol):** Protocolo de comunicação entre o Foton e Assistentes de IA.
+- **TUI (Terminal User Interface):** Interface de navegação via teclado no terminal.
+- **Frontmatter:** Bloco de metadados YAML no início dos arquivos Markdown.
+
+---
+## 🔗 Links Relacionados
+- Índice: [[Index]]
+- Protocolo: [[LlmProtocol]]
+- Contexto LLM: [[LlmContext]]

docs/00_META/Index.md

@@ -0,0 +1,60 @@
+---
+type: index
+domain: core
+status: active
+tags: [map, index, toc]
+---
+# 🗺️ Mapa de Conteúdo (Index)
+
+Bem-vindo ao centro nervoso da documentação do **FOTON System**. Este índice organiza o conhecimento do sistema seguindo a metodologia PARA + Zettelkasten.
+
+## 🏛️ Esferas de Conhecimento
+
+### 00_META - Metadados e Protocolos
+- [[LlmProtocol]] - Regras para IAs e Agentes.
+- [[LlmContext]] - Contexto geral para LLMs e identidade do sistema.
+- [[SystemManifest]] - Visão técnica e manifesto do sistema.
+- [[Contributing]] - Guia de contribuição para o projeto.
+- [[Dictionary]] - Glossário de termos técnicos e de negócio.
+
+#### ADRs (Architectural Decision Records)
+- [[ADR001_ParaZettelkastenDoc]] - Adoção do PARA + Zettelkasten.
+- [[ADR002_PascalCaseNaming]] - Padronização PascalCase.
+
+### 01_PROJECTS - Sprints e Esforços Ativos
+- [[PlanDocRefactor]] - **Sprint Atual:** Refatoração da Documentação.
+- [[SprintSandbox]] - Testes e experimentações em ambiente controlado.
+- [[AgenticSprintPlan]] - Planejamento original da evolução agêntica.
+- [[WorkPlan]] - Plano de masterização de frameworks.
+
+### 02_AREAS - Domínios e Regras Perenes (DDD)
+- [[Concepts]] - Arquitetura Hexagonal e padrões.
+- [[Pipelines]] - Fluxos de dados do sistema.
+- [[DataModel]] - Modelo de dados e Centros de Verdade.
+- [[BackupStrategySummary]] - Estratégia de backup e resiliência de dados.
+- [[DatabaseFlowDiagram]] - Diagramas de inicialização de base.
+- [[DatabaseInitializationSolution]] - Soluções para base ausente.
+
+### 03_RESOURCES - Manuais e Recursos
+- [[UserGuide]] - Guia do Usuário (Arquiteto).
+- [[QuickReference]] - Atalhos e comandos rápidos.
+- [[TuiGuide]] - Guia do Modo Terminal.
+- [[McpGuide]] - Guia de Integração com IA via MCP.
+- [[DocsMcp]] - Documentação técnica específica para MCP.
+- [[DeploymentGuide]] - Guia de Deploy (Devs).
+- [[DeploymentUserGuide]] - Guia de Implantação para o Usuário.
+- [[TestQualityReport]] - Relatório de qualidade de testes.
+
+### 04_ARCHIVES - Histórico e Releases
+- [[Release_v1.1.0]] - Notas da versão 1.1.0.
+- [[AiIntegrationReport]] - Relatório inicial de integração IA.
+- [[DocumentationAudit]] - Auditoria inicial da estrutura de documentação.
+
+---
+## 🏷️ Navegação Rápida por Tags
+- #architecture | #feature | #mcp | #guide | #backup
+
+---
+**Links Relacionados:**
+- [[README]]
+- [[LlmProtocol]]