diff --git a/README.md b/README.md
index b88ee33..ade291e 100644
--- a/README.md
+++ b/README.md
@@ -1,149 +1,230 @@
-# Sinapse — Base Inteligente de Requisitos
+# Sinapse
-> **PRO4TECH · Fatec São José dos Campos · Grupo Galáticos**
-> *Projeto de Aprendizagem Interdisciplinar (API) — 4º Semestre (2º Semestre/2026)*
+**Memória de requisitos e conhecimento para equipes de produto e desenvolvimento.**
-O **Sinapse** é a memória institucional da fábrica de software. A plataforma converte itens de backlog, regras de negócio e decisões de arquitetura em uma base de conhecimento inteligente, auxiliando Product Owners (POs) e equipes de desenvolvimento na especificação padronizada de features, redução de retrabalho e reúso de conhecimento prévio.
+[](https://github.com/Galaticos-API/API-4/actions/workflows/ci.yml)
+[](https://github.com/Galaticos-API/API-4/actions/workflows/e2e.yml)
----
+Sinapse ajuda Product Owners a especificar trabalho no padrão **Projeto → Épico → Feature → PBI**, registrar decisões e consultar informações vinculadas a cada projeto. Regras determinísticas orientam a qualidade dos itens; documentos e conversas mantêm contexto e rastreabilidade.
-## 📚 Documentação Canônica do Projeto
+> Projeto de Aprendizagem Interdisciplinar · Fatec São José dos Campos · Grupo Galáticos · PRO4TECH · 2º semestre de 2026.
-Toda a especificação técnica, backlog e decisões arquiteturais estão estruturados nos documentos oficiais abaixo:
+## Equipe
-| Documento | Descrição e Conteúdo |
-|---|---|
-| 🤖 **[Contexto Canônico de IA e Agentes](docs/AGENTS.md)** | **Contexto unificado para LLM Agents** com visão do produto, schema, regras de negócio e stack. |
-| 📄 **[PRD — Product Requirements Document](docs/PRD-PRO4TECH.md)** | Requisitos funcionais (RF), não-funcionais (RNF), regras de negócio e governança de IA. |
-| 🏛️ **[Arquitetura, GraphRAG e Embeddings](docs/Architecture/README.md)** | Diagramas, fluxo RAG, ERD, proposta GraphRAG e benchmark do spike `bge-m3`. |
-| 📊 **[Planejamento Scrum & Plano de Tarefas](docs/PLANEJAMENTO_SCRUM.md)** | Metas executivas por sprint e detalhamento operacional das 71 tarefas técnicas. |
-| 📋 **[Backlog de Produto (66 PBIs)](docs/backlog/README.md)** | Especificação completa dos 6 épicos e 18 features no padrão da fábrica. |
-| 🔌 **[Contrato OpenAPI (Serviços)](docs/api/openapi.yaml)** | Especificação dos endpoints e schemas HTTP compartilhados entre backend, IA e n8n. |
-
----
-
-## 🏗️ Arquitetura e Componentes de Infraestrutura
-
-O ecossistema é distribuído em microsserviços conteinerizados e locais:
+| Papel | Integrante | GitHub |
+|---|---|---|
+| Product Owner (PO) | Daniel Dias | [@DanielDPereira](https://github.com/DanielDPereira) |
+| Scrum Master | Cauan Gabriel | [@LoadCG](https://github.com/LoadCG) |
+| Development Team | Emmanuel Garakis | [@Garakis](https://github.com/Garakis) |
+| Development Team | Rafael Matesco | [@RafaMatesco](https://github.com/RafaMatesco) |
+| Development Team | Gustavo Bueno | [@Darkghostly](https://github.com/Darkghostly) |
+| Development Team | Gabriel Lasaro | [@GaelNotFound](https://github.com/GaelNotFound) |
+| Development Team | Giovanni | [@Giomoret](https://github.com/Giomoret) |
+| Development Team | Heitor | [@heitors1337](https://github.com/heitors1337) |
+| Development Team | Vitor | [@vitorpdim](https://github.com/vitorpdim) |
+
+Os links foram associados a integrantes por nomes públicos e autoria de commits
+neste repositório. Gabriel Lasaro aparece no histórico como Gabriel, com o e-mail
+de commit `gaelslasaro@gmail.com`, ligado ao perfil [@GaelNotFound](https://github.com/GaelNotFound).
+
+## Metodologia ágil e andamento
+
+O grupo organizou o trabalho com Scrum e backlog de produto priorizado em épicos,
+features e PBIs. A equipe planejou o trabalho em sprints, relacionando as tarefas
+técnicas aos itens do backlog e aos critérios de aceitação. A Sprint 1 foi a
+primeira sprint executada e foi encerrada em **27/09/2026**. Até esta atualização,
+nenhuma sprint posterior foi concluída; as sprints seguintes permanecem no
+planejamento.
+
+| Sprint | Período | Situação | Foco |
+|---|---|---|---|
+| Sprint 1 | 07/09/2026–27/09/2026 | Concluída em 27/09/2026 | Hierarquia do backlog, autenticação, qualidade de PBIs, decisões, documentos e consolidação de QA. |
+| Sprints seguintes | A definir no planejamento | Planejadas; ainda não executadas | Evolução do produto conforme backlog e prioridades do PO. |
+
+O trabalho foi acompanhado pelo backlog, revisão de entregas e validação dos
+critérios de aceite. O [planejamento Scrum](docs/PLANEJAMENTO_SCRUM.md) detalha
+escopo e tarefas da Sprint 1. As cerimônias, duração de reuniões e métricas não
+estão formalizadas neste repositório; este resumo não presume práticas que não
+foram registradas.
+
+## Veja o produto
+
+O GIF e as capturas abaixo foram feitos no frontend real do `main`, com um banco PostgreSQL descartável e dados fictícios cadastrados pela interface. Eles não são mockups nem imagens de produção.
+
+
+
+*Fluxo: abrir projeto → expandir backlog → consultar PBI e qualidade.*
+
+
+ 
+ 
+
+
+ 
+ 
+
+
+## O que o sistema oferece
+
+- **Projetos e backlog:** organize épicos, features, PBIs e critérios de aceitação com navegação hierárquica e trilha de auditoria.
+- **Qualidade de requisitos:** valide título, história, cenários DADO/QUANDO/ENTÃO, termos vagos e necessidade de protótipo. A configuração organizacional pode ser administrada e auditada.
+- **Decisões:** registre contexto, justificativa e alternativas no nível apropriado da hierarquia.
+- **Documentos:** envie arquivos para um projeto, consulte a lista paginada e remova documentos com isolamento por projeto e confirmação.
+- **Busca e conversa:** encontre itens no backlog; mantenha conversas vinculadas ao usuário e, opcionalmente, ao projeto. Quando o assistente não está disponível, a conversa tenta uma busca textual no acervo.
+- **Acesso por perfil:** `admin`, `po` e `dev` têm permissões distintas; a API verifica a sessão e não confia em papéis enviados pelo navegador.
+- **Análise de repositório:** solicita uma análise assíncrona ao serviço Python configurado.
+
+### Estado da IA
+
+O núcleo de requisitos, autenticação, qualidade e documentos não exige modelos de IA. Ollama e o serviço Python podem ser ligados pelo perfil `local-ai`. O serviço Python expõe endpoints de embeddings, chunking, consulta RAG e análise de repositório; o fluxo de conversa do backend mantém busca textual como fallback. Configure e valide a integração de IA separadamente antes de depender dela em uma demonstração ou implantação.
+
+## Arquitetura em uma página
+
+```mermaid
+flowchart LR
+ Browser["React + Vite"] -->|"HTTP /api/v1"| API["Node.js + Express"]
+ API -->|"dados, sessões, auditoria"| DB[("PostgreSQL 16 + pgvector")]
+ API -->|"quando configurado"| AI["FastAPI: IA e RepoAnalyzer"]
+ AI --> Ollama["Ollama: modelos locais"]
+ API -->|"eventos de integração"| N8N["n8n opcional"]
+```
-| Componente | Tecnologia | Porta Local | Responsabilidade Principal |
-|---|---|:---:|---|
-| **Banco Unificado** | PostgreSQL 16 + `pgvector` | `55432` (host) | Dados relacionais de negócio e vetores de chunks indexados por HNSW (`vector_cosine_ops`). |
-| **Orquestrador** | n8n (`latest`) | `5678` | Pipeline assíncrono de ingestão, gatilhos de arquivos em `/files` e integrações. |
-| **Runtime de IA** | Ollama | `11434` | Inferência local de LLM (`qwen2.5:1.5b`) e geração de embeddings (`bge-m3`). |
-| **Backend** | Node.js 20+ / Express / TS | `3001` | Autenticação JWT, CRUD, validações determinísticas (RF-08 a RF-11) e **única escrita no banco de negócio**. |
-| **Frontend** | React 19 / Vite / TS | `5173` | SPA para Product Owners (gestão hierárquica de PBIs, acervo e chat fundamentado). |
-| **Serviço de IA** | Python 3.11+ / FastAPI | `8000` | Chunking unificado, cálculo de vetores, Harness PRO4TECH e montagem de contexto RAG. |
+No Compose padrão, o frontend, o backend, PostgreSQL e n8n são iniciados. Ollama e o serviço Python ficam no perfil opcional `local-ai`. O backend executa migrations pendentes ao iniciar no container; migrations versionadas são a fonte de evolução do schema.
-### Qualidade e completude de PBIs
+| Componente | Stack | Porta no host | Responsabilidade |
+|---|---|---:|---|
+| Frontend | React 19, TypeScript, Vite; Nginx no container | `5173` | Interface web e proxy de `/api` no modo de desenvolvimento. |
+| Backend | Node.js 20, Express, TypeScript | `3001` | API REST, sessões, autorização, regras de negócio e persistência. |
+| PostgreSQL | PostgreSQL 16 + pgvector | `55432` | Dados relacionais e estruturas de busca vetorial. Dentro da rede Docker, usa `5432`. |
+| n8n | n8n | `5678` | Integrações assíncronas opcionais. |
+| Ollama | Ollama | `11434` | Inferência e embeddings locais, quando o perfil de IA estiver ligado. |
+| Serviço de IA | Python 3.11+, FastAPI | `8000` | Endpoints de chunking, embeddings, RAG e RepoAnalyzer. |
-O backend calcula o indicador de completude a partir das regras determinísticas ativas para PBIs (título, história, cenários, termos vagos e protótipo); ele não depende do valor em cache da coluna de score. No cadastro do PBI, o PO informa explicitamente se ele exige interface/protótipo. A verificação de protótipo só entra no cálculo quando esse campo está ativo e consulta a tabela `prototipo`. A política atual é persistida no PostgreSQL e pode ser consultada ou alterada por administradores em `GET /api/v1/quality/configuration/pbi` e `PUT /api/v1/quality/configuration/pbi`. As alterações são versionadas e auditadas. As migrations correspondentes são `008_quality_organization_configuration.sql` e `009_pbi_interface_quality.sql`; veja o [guia de migrations](database/migrations/README.md) e o [contrato OpenAPI](docs/api/openapi.yaml).
+## Comece com Docker
----
+### Pré-requisitos
-## 🚀 Inicialização Rápida
+- Docker Desktop atualizado com Docker Compose v2.
+- Git.
+- Para desenvolvimento fora de containers: Node.js 20+ e Python 3.11+.
-### 1. Pré-requisitos
-- [Docker](https://docs.docker.com/get-docker/) (v24+) e [Docker Compose](https://docs.docker.com/compose/) (v2+)
-- [Node.js](https://nodejs.org/) (v20+) e [Python](https://www.python.org/) (3.11+)
-- [Git](https://git-scm.com/)
+### 1. Baixe o código e configure o ambiente
-### 2. Configurar Variáveis de Ambiente
```bash
+git clone https://github.com/Galaticos-API/API-4.git
+cd API-4
cp .env.example .env
```
-> ⚠️ **Importante:** Mantenha `N8N_ENCRYPTION_KEY=sinapse-shared-dev-encryption-key-2026` em ambiente de desenvolvimento local para compatibilidade com os workflows versionados.
-### 3. Subir a Infraestrutura Base
-```bash
-docker compose up -d
-```
-Serviços disponíveis:
-- PostgreSQL: `localhost:55432` (Usuário: `sinapse`, Senha padrão: `sinapse_dev_password`, Banco: `sinapse`)
-- n8n Web: [http://localhost:5678](http://localhost:5678)
-- Backend: [http://localhost:3001/health](http://localhost:3001/health)
-- Frontend: [http://localhost:5173](http://localhost:5173)
+No PowerShell, use `Copy-Item .env.example .env` no lugar de `cp`.
+
+`.env.example` contém valores apenas para desenvolvimento local. Troque credenciais e chaves antes de expor os serviços; nunca versione `.env` nem use os padrões do exemplo em produção.
+
+### 2. Inicie o produto
-Para encerrar os serviços sem apagar os dados persistidos:
```bash
-docker compose down
+docker compose up --build -d
+docker compose ps
```
-Para remover o container e todos seus dados:
+Abra:
+
+| Serviço | URL |
+|---|---|
+| Aplicação | |
+| Saúde da API | |
+| Documentação interativa da API | |
+| n8n | |
+
+As migrations são executadas no início do container do backend. Cadastre uma conta pela tela de login e entre na aplicação. O Compose padrão não baixa modelos; a tela pode ser usada sem Ollama.
+
+### 3. (Opcional) Ligue IA local
+
+O perfil adicional inicia Ollama e o serviço Python:
+
```bash
-docker compose down -v
+docker compose --profile local-ai up --build -d
+docker compose --profile local-ai exec ollama ollama pull bge-m3
+docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b
```
-### 4. Baixar Modelos Locais no Ollama (opcional)
-```bash
-docker compose --profile local-ai up -d
+O download dos modelos pode ocupar vários gigabytes. Os modelos e a configuração podem ser alterados em `.env`; use o [guia de ambiente](docs/SETUP_GUIDE.md) para endereços entre containers, variáveis e diagnóstico.
-# Modelo de Embeddings PT-BR (validado no Spike PRE-07)
-docker compose --profile local-ai exec ollama ollama pull bge-m3
+### Parar e preservar os dados
-# Modelo LLM para inferência rápida local (CPU)
-docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b
+```bash
+docker compose down
```
----
+Isso preserva volumes nomeados. `docker compose down -v` remove também os volumes persistentes, incluindo o banco local, arquivos enviados, dados do n8n e modelos do Ollama.
-## 🔄 Versionamento de Workflows (`n8n-local-sync`)
+## Desenvolvimento e qualidade
-Os workflows do n8n são versionados no Git via utilitário GitOps [`n8n-local-sync`](https://pypi.org/project/n8n-local-sync/):
+Instale dependências em cada módulo antes de executar seus comandos:
```bash
-# Instalação
-pip install n8n-local-sync
-
-# Principais comandos
-n8n-sync status # Visualiza estado de sincronização local vs n8n
-n8n-sync diff # Compara diferenças estruturais limpas
-n8n-sync sync # Puxa workflows do container para o Git (n8n/workflows/)
-n8n-sync push # Envia workflows do Git para a instância do n8n
-n8n-sync validate # Valida integridade do JSON e detecta segredos expostos
+npm ci --prefix backend
+npm ci --prefix frontend
+npm ci --prefix e2e
```
----
+| Área | Comandos | Observação |
+|---|---|---|
+| Compose | `docker compose config --quiet` | Valida o arquivo sem iniciar containers. |
+| Backend | `cd backend && npm run build` | Compila TypeScript para `dist/`. |
+| Backend | `cd backend && npm run typecheck` | Verifica tipos sem gerar arquivos. |
+| Backend | `cd backend && npm test` | Suíte unitária; integrações PostgreSQL são ativadas pelas variáveis de teste documentadas. |
+| Backend | `cd backend && npm run migrate` | Aplica migrations pendentes no banco apontado por `POSTGRES_*`. |
+| Backend | `cd backend && npm run seed:validate` | Valida o acervo curado; exige build prévio. |
+| Frontend | `cd frontend && npm test` | Testes Vitest. |
+| Frontend | `cd frontend && npm run build` | TypeScript e bundle de produção. |
+| IA | `cd ai-service && python -m py_compile main.py config.py services/chunker.py services/ollama_client.py` | Verificação sintática do serviço. |
+| IA | `cd ai-service && python -m unittest discover -s tests -v` | Testes determinísticos de chunking e análise. |
+| E2E | `cd e2e && npm test` | Chrome, frontend e API em execução; use banco descartável. |
-## 🧪 Comandos de Validação e Qualidade
+O workflow de CI executa builds, testes, validações do seed, compatibilidade PostgreSQL, configuração Docker e serviço Python. O workflow de navegador roda em pull requests e atualizações de `main` que alterem aplicação, banco ou E2E. Consulte [workflows do GitHub Actions](.github/workflows/).
-| Verificação | Comando | Descrição |
-|---|---|---|
-| **Validação Docker** | `docker compose config --quiet` | Checa a sintaxe do Compose |
-| **Workflows n8n** | `n8n-sync validate` | Varre sintaxe e credenciais expostas |
-| **Migrations** | `cd backend && npm run migrate` | Executa migrations pendentes no Postgres |
-| **Testes Backend** | `cd backend && npm test` | Executa suíte de testes unitários/integração |
-| **Validação integrada S1** | `cd backend && npm run test:integration:s1` | Valida os fluxos HTTP com PostgreSQL real da Sprint 1 |
-| **Auditoria de Segurança** | `cd backend && npm run audit:security` | Verifica dependências de produção |
-| **Tipagem Backend** | `cd backend && npm run typecheck` | Checagem estrita de tipos TypeScript |
-| **Testes Frontend** | `cd frontend && npm test` | Executa a suíte Vitest da interface |
-| **Build Frontend** | `cd frontend && npm run build` | Valida bundle de produção da SPA |
-| **Testes do serviço de IA** | `cd ai-service && python -m unittest discover -s tests` | Executa os testes do chunker e metadados |
+> Os testes E2E criam contas e projetos. Use sempre um banco descartável ou dedicado a testes, nunca uma base compartilhada ou de produção.
----
+## Documentação
-## 📁 Estrutura de Diretórios
+| Guia | Para quê |
+|---|---|
+| [Índice da documentação](docs/README.md) | Mapa dos guias, contratos e documentos de produto. |
+| [Instalação e desenvolvimento](docs/SETUP_GUIDE.md) | Compose, execução local, variáveis, testes e solução de problemas. |
+| [Arquitetura e estado da implementação](docs/Architecture/README.md) | Limites dos serviços, dados, fluxos e distinção entre recurso implementado e proposta. |
+| [Contrato OpenAPI](docs/api/openapi.yaml) | Rotas REST, schemas e autenticação. |
+| [PRD PRO4TECH](docs/PRD-PRO4TECH.md) | Problema, visão, requisitos e regras de produto. |
+| [Backlog de produto](docs/backlog/README.md) | Épicos e PBIs documentados. |
+| [Planejamento Scrum](docs/PLANEJAMENTO_SCRUM.md) | Objetivos e planejamento das sprints. |
+| [Migrations](database/migrations/README.md) | Evolução e validação do schema. |
+| [Seed e política de dados](database/seed/README.md) | Acervo curado, validação e regras de segurança. |
+| [Testes E2E](e2e/README.md) | Cobertura de navegador e execução local. |
+| [Protótipo e handoff de UX](figma-import/README.md) | Referências de design e protótipos. |
+
+## Estrutura do repositório
```text
-API-4/
-├── .github/workflows/ # Pipelines de CI/CD no GitHub Actions
-├── ai-service/ # Microsserviço Python/FastAPI (RAG, Chunking & Ollama)
-├── backend/ # API REST Node.js/TypeScript (CRUD, Auth & Postgres)
-├── database/ # DDL de inicialização, migrations e seeds
-│ ├── init.sql # Schema DDL inicial
-│ ├── migrations/ # Migrations versionadas em SQL
-│ └── seed/ # Carga de dados fictícios para desenvolvimento
-├── docs/ # Documentação canônica consolidada
-│ ├── AGENTS.md # Contexto canônico autoritativo para agentes e LLMs
-│ ├── PRD-PRO4TECH.md # Especificação técnica e requisitos funcionais
-│ ├── PLANEJAMENTO_SCRUM.md # Organização das tarefas de desenvolvimento e plano técnico
-│ ├── Architecture/ # Diagramas de arquitetura, fluxo RAG, ERD e GraphRAG
-│ ├── backlog/ # Mapeamento dos 6 épicos e 66 PBIs
-│ └── api/ # Contrato OpenAPI (openapi.yaml)
-├── frontend/ # SPA React 19/TypeScript/Vite (Interface do PO)
-├── n8n/ # Workflows exportados e arquivos locais monitorados
-├── scripts/ # Utilitários e benchmarks (spike_embeddings.py)
-├── .env.example # Template de variáveis de ambiente
-├── .n8n-sync.yaml # Configuração do n8n-local-sync
-└── docker-compose.yml # Orquestração local (PostgreSQL + pgvector, n8n & Ollama)
+.
+├── .github/workflows/ # CI, compatibilidade do banco e E2E
+├── ai-service/ # FastAPI, embeddings, RAG e RepoAnalyzer
+├── backend/ # API, autenticação, regras e persistência
+├── database/ # baseline SQL, migrations e seeds
+├── docs/ # guias de produto, arquitetura, API e QA
+├── e2e/ # testes de navegador no Chrome
+├── figma-import/ # handoff de UX e protótipos
+├── frontend/ # SPA React e bundle Nginx
+└── n8n/ # workflows versionados e arquivos locais
```
+
+## Segurança e dados
+
+- Use dados fictícios nos ambientes de demonstração e testes.
+- O seed curado aceita apenas um banco dedicado com sufixo `_dev` ou `_test`; a execução normal valida o manifesto sem gravar dados.
+- Restrinja acesso à API e ao banco fora da máquina local; valores do `.env.example` não são segredos de produção.
+- Arquivos enviados são armazenados em volume local no Compose. Defina retenção, backup e proteção desse volume antes de uma implantação.
+- Leia [política de dados do seed](database/seed/POLITICA_DE_DADOS.md) e [guia completo de setup](docs/SETUP_GUIDE.md).
+
+## Contexto acadêmico
+
+Projeto de Aprendizagem Interdisciplinar (API), 4º semestre de Análise e Desenvolvimento de Sistemas na Fatec São José dos Campos, desenvolvido pelo Grupo Galáticos para a PRO4TECH.
diff --git a/database/migrations/README.md b/database/migrations/README.md
index bb2f940..5076f5a 100644
--- a/database/migrations/README.md
+++ b/database/migrations/README.md
@@ -4,6 +4,11 @@ As alterações estruturais do banco devem ser numeradas e aplicadas em ordem
(`001_...sql`, `002_...sql`, etc.). Cada arquivo deve ser idempotente quando
possível e conter apenas a alteração daquela versão.
+O baseline inicial é `database/init.sql`. Em volumes já existentes, o backend
+executa migrations pendentes ao iniciar o container e registra o resultado em
+`_schema_migrations`. Para executar no host, use `npm --prefix backend run migrate`
+com as variáveis corretas. Consulte o [guia de setup](../../docs/SETUP_GUIDE.md).
+
## Baseline atual
`database/init.sql` é o baseline inicial do projeto e é executado pelo
@@ -32,7 +37,7 @@ O runner registra o nome completo. `004_z_prepare_criteria_order.sql` precisa
ordenar antes de `005_backlog_hierarchy_domain.sql` para preparar critérios
legados antes da criação do índice único. `006_reconcile_epic_status.sql`
uniformiza a constraint preservando os estados legados como somente leitura
-na API de épicos. Veja [execução e recuperação](../CONSOLIDACAO_S1_05.md).
+na API de épicos. Veja também a documentação de execução e recuperação nesta seção.
`npm run test:integration:s105` no backend valida banco vazio, histórico antigo,
histórico backlog e ambas as migrations, com repetição e rollback de auditoria.
@@ -79,3 +84,17 @@ incrementa sua versão ao introduzir a nova regra. A atualização da política
registrada em `auditoria` como alteração de migration (sem atribuir a um admin).
O teste PostgreSQL de compatibilidade verifica aplicabilidade, presença/ausência
de protótipo e reexecução idempotente.
+
+## Registro de decisões (S1)
+
+`013_decision_records.sql` cria o armazenamento de decisões vinculadas aos
+níveis do backlog e seus índices de consulta. Rotas e schemas estão no
+[OpenAPI](../../docs/api/openapi.yaml); o backend valida o vínculo com o projeto
+e registra auditoria.
+
+## Testes PostgreSQL descartáveis
+
+Testes de integração devem apontar para bases descartáveis com os sufixos
+exigidos por cada script (`_test`, `_s105_test` etc.). Não use a base local
+compartilhada. Consulte os comandos e as proteções no [guia de setup](../../docs/SETUP_GUIDE.md)
+e nos scripts de `backend/package.json`.
diff --git a/database/seed/README.md b/database/seed/README.md
index becac5b..102f214 100644
--- a/database/seed/README.md
+++ b/database/seed/README.md
@@ -1,50 +1,43 @@
-# Seed de desenvolvimento
-
-## PRE-06 — Acervo histórico curado
-
-O seed atual é `fixtures/historical-v1.json`, aplicado pelo backend. Contém três
-projetos acadêmicos API-1/API-2/API-3, seis resumos de requisitos e seis chunks sem
-vetores. As cópias curadas ficam em `curated/`. Não há pessoas, credenciais ou
-competências inventadas. Cada registro tem repositório, revisão, caminho, localização,
-hash SHA-256 do texto fonte em UTF-8 e descrição da transformação; a carga persiste
-essa origem em `auditoria` e nos metadados dos chunks.
-
-Dentro de `backend`, execute `npm ci`, `npm run build`, `npm run seed:validate` e `npm run test:seed`.
-Para carregar, prepare um banco dedicado com as migrações 001–003. Configure
-`SEED_DATABASE_URL` por variável de ambiente (não em argumentos nem arquivos versionados)
-e execute `npm run seed:apply`. O nome do banco deve terminar em `_dev` ou `_test`;
-`NODE_ENV=production` é recusado. O comando de migração existente usa suas próprias
-variáveis `POSTGRES_*`; confira que apontam para o mesmo banco dedicado antes de migrar.
-
-O modo padrão só valida arquivos. A aplicação é transacional, serializada e
-idempotente: repetir não duplica registros/auditoria; colisões ou alteração de
-conteúdo/origem interrompem a operação, sem sobrescrever dados do usuário. Não há
-remoção automática. Para atualizar o acervo, criar versão revisada e migração explícita.
-
-`test:seed` verifica o manifesto sem PostgreSQL. Se `SEED_TEST_DATABASE_URL` estiver
-definida, também testa a carga duas vezes em uma transação revertida ao final e a
-recusa de divergência. A CI fornece PostgreSQL 16 + pgvector dedicado e executa as
-migrações antes desse teste. Sem a variável, o teste SQL aparece como ignorado;
-isso não equivale a validação da carga real.
-
-Leia [POLITICA_DE_DADOS.md](POLITICA_DE_DADOS.md) e [validation-cases.json](validation-cases.json).
-Embeddings não são fabricados: a indexação real continua pendente do pipeline da IA.
-
-Validação local: manifesto e documentos aprovados pelo validador, build do backend
-concluído e 6 testes da PRE-06 passaram com PostgreSQL 16 + pgvector descartável,
-sem testes ignorados. O comando `seed:apply` também foi executado duas vezes com
-sucesso: 3 projetos, 6 documentos, 6 chunks e 15 eventos de origem, sem duplicação.
-O banco de teste foi removido; nenhuma carga foi feita na base corrente do projeto.
-A execução remota da CI e a revisão humana do PR continuam pendentes.
-
-## Seed fictício legado
-
-`dev_seed.sql` contém somente dados fictícios e determinísticos para desenvolvimento
-local e demonstrações. Não use este arquivo em produção e não inclua dados reais,
-tokens, senhas ou documentos de clientes.
-
-O seed é idempotente: pode ser executado novamente sem duplicar os registros com os
-mesmos identificadores.
-
-O arquivo legado é mantido por compatibilidade, não faz parte da carga histórica
-PRE-06 e não deve ser executado junto com ela para demonstrar o acervo curado.
+# Seeds e dados de demonstração
+
+Este diretório contém dois conjuntos com propósitos diferentes:
+
+1. `fixtures/historical-v1.json` e `curated/` formam o **acervo histórico curado PRE-06**. A carga é aplicada pelo backend, a partir de fontes acadêmicas documentadas, em projetos, documentos, chunks sem embedding e registros de origem/auditoria.
+2. `dev_seed.sql` é um seed legado com dados fictícios determinísticos para demonstrações. Ele não faz parte da carga PRE-06 e não deve ser aplicado junto dela.
+
+Não inclua nomes, e-mails, credenciais, documentos de clientes, dados de produção ou segredos em qualquer fixture.
+
+## Validar o acervo curado
+
+Execute dentro de `backend`:
+
+```bash
+npm ci
+npm run build
+npm run seed:validate
+npm run test:seed
+```
+
+O build é necessário porque os scripts `seed:validate` e `test:seed` executam arquivos compilados em `dist/`. A validação padrão inspeciona o manifesto e os documentos sem gravar dados. O teste PostgreSQL é habilitado quando `SEED_TEST_DATABASE_URL` aponta para banco descartável dedicado.
+
+## Aplicar em desenvolvimento
+
+1. Crie um banco dedicado, separado da base de desenvolvimento compartilhada.
+2. Aplique nele as migrations necessárias (001–003 para este dataset).
+3. Configure `SEED_DATABASE_URL` no ambiente do processo, sem colocar a URL em argumentos ou arquivos versionados.
+4. Confirme que `POSTGRES_*` do comando de migration aponta para o mesmo destino.
+5. Execute `npm run seed:apply` dentro de `backend`.
+
+O alvo precisa usar PostgreSQL/PostgresQL e o nome do banco deve terminar em `_dev` ou `_test`. O ambiente `production` é recusado, salvo a exceção explícita de segurança prevista no código; **não use a exceção para dados de demonstração**.
+
+A aplicação é transacional e idempotente: repetir os mesmos dados não duplica registros. Colisões ou divergência de conteúdo/origem abortam a operação; o seed não atualiza nem remove conteúdo preexistente.
+
+## Conteúdo e proveniência
+
+Cada item curado mantém origem, URL, revisão, caminho/localização, hash SHA-256 e descrição da transformação. Os metadados permitem rastrear a origem do texto. Embeddings não são fabricados; a inclusão de vetor depende de pipeline de indexação validado.
+
+Leia a [política de dados](POLITICA_DE_DADOS.md), o [manifesto de casos de validação](validation-cases.json) e o [guia de migrations](../migrations/README.md).
+
+## Capturas e demonstrações do produto
+
+As capturas do [README principal](../../README.md) foram produzidas com registros inventados em banco descartável pela UI. Elas não usam `dev_seed.sql` nem alteram a base do Compose do desenvolvedor.
diff --git a/docs/Architecture/README.md b/docs/Architecture/README.md
index ad12965..2444799 100644
--- a/docs/Architecture/README.md
+++ b/docs/Architecture/README.md
@@ -1,321 +1,112 @@
-# Arquitetura e Diagramas do Sistema — Sinapse
+# Arquitetura do Sinapse
-> **PRO4TECH · Fatec São José dos Campos · Grupo Galáticos**
-> *Base Inteligente de Requisitos — Memória Institucional da Fábrica de Software*
+> Estado da implementação no `main`, revisado em 27/09/2026. Este documento descreve o que o código e a configuração Docker fazem hoje. Requisitos ainda em validação e propostas futuras estão identificados como tal.
-Este documento consolida todos os diagramas arquiteturais, fluxos de execução e modelos de dados do **Sinapse**, servindo como referência visual e técnica central para a equipe de desenvolvimento e stakeholders, em conformidade com o [PRD](../PRD-PRO4TECH.md) e o [AGENTS.md](../AGENTS.md).
-
----
-
-## 📑 Índice de Diagramas
-
-1. [Visão Geral da Arquitetura e Ingestão](#1-visão-geral-da-arquitetura-e-ingestão)
-2. [Fluxo de Consulta Semântica e RAG](#2-fluxo-de-consulta-semântica-e-rag)
-3. [Diagrama Entidade-Relacionamento (ERD)](#3-diagrama-entidade-relacionamento-erd)
-4. [Resumo das Fronteiras Arquiteturais](#4-resumo-das-fronteiras-arquiteturais)
-
----
-
-## 1. Visão Geral da Arquitetura e Ingestão
-
-Representa a divisão de responsabilidades entre as 6 camadas do ecossistema Sinapse:
-- **Frontend (React SPA):** Interface do Product Owner.
-- **Backend Aplicação (Node.js):** Ponto de entrada de negócio, autenticação, CRUD e validações determinísticas (RF-08 a RF-11). É o único serviço autorizado a persistir nas tabelas de negócio.
-- **Serviço de IA (Python):** RAG Engine, chunking unificado (PRD 10.3) e Harness de alinhamento com o guia PRO4TECH.
-- **Orquestração de Ingestão (n8n):** Monitoramento de arquivos em `/files`, gatilhos de eventos e workflows versionados via `n8n-local-sync`.
-- **Banco de Dados Unificado (PostgreSQL):** Persistência relacional clássica combinada com a extensão `pgvector` (busca vetorial HNSW na tabela `chunk`).
-- **Ollama:** Runtime de IA para inferência de LLM (Qwen 2.5 / Llama 3.1) e geração de embeddings locais (`bge-m3`).
-
-### Diagrama Mermaid
+## Visão de runtime
```mermaid
-flowchart TB
- subgraph Frontend["Frontend (React SPA)"]
- UI["Interface PO / Usuário"]
- end
-
- subgraph BackendApp["Backend Aplicação (Node.js)"]
- API["API REST / Auth / CRUD / Regras de Negócio"]
- Valida["Validação Estrutural (RF-08 a RF-11)"]
- end
-
- subgraph ServiceAI["Serviço de IA (Python)"]
- Harness["Harness (Guia PRO4TECH)"]
- RagEngine["RAG Engine & Embeddings"]
- LLM["LLM Aberto Local (ex: Llama / Mistral / Qwen)"]
- end
-
- subgraph Ingestao["Orquestração de Ingestão"]
- N8N["n8n (Workflows versionados via n8n-local-sync)"]
- end
-
- subgraph Database["Banco de Dados Unificado (PostgreSQL)"]
- Relational["Tabelas Relacionais (projeto, epico, pbi, etc.)"]
- VectorExt["Extensão pgvector (tabela chunk + índice HNSW)"]
- end
-
- UI -->|"Requisições HTTP"| API
- API -->|"Persistência e Leitura Relacional"| Relational
- API -->|"Delegação de IA / RAG"| ServiceAI
- N8N -->|"Dispara Ingestão de Documentos"| API
- N8N -->|"Envia arquivos para fragmentação"| RagEngine
- RagEngine -->|"Gera embeddings e consulta vetores"| VectorExt
- RagEngine -->|"Monta contexto enriquecido"| Harness
- Harness <--> LLM
+flowchart LR
+ PO["PO / DEV / Admin"] --> Browser["SPA React 19 + Vite"]
+ Browser -->|"HTTP /api/v1"| API["API Node.js + Express"]
+ API -->|"sessões, backlog, documentos, decisões, auditoria"| DB[("PostgreSQL 16 + pgvector")]
+ API -->|"chamadas opcionais"| AI["FastAPI · IA e RepoAnalyzer"]
+ AI --> Ollama["Ollama · embeddings e LLM"]
+ API -->|"evento de remoção via webhook"| N8N["n8n opcional"]
```
-
-🖼️ Ver imagem estática renderizada
+### Componentes e fronteiras
-
+| Componente | Implementação | Responsabilidade atual |
+|---|---|---|
+| Frontend | `frontend/`, React + TypeScript + Vite; Nginx na imagem final | Autenticação de interface, navegação por projeto e captura de entradas. O Vite encaminha `/api` e `/health` no modo local; Nginx usa `backend:3001` no Compose. |
+| Backend | `backend/`, Express + TypeScript | API, sessões, autorização por perfil, validações, regras de domínio, acesso ao Postgres, storage de documentos e histórico de conversa. |
+| Banco | `database/init.sql` + `database/migrations/`, PostgreSQL 16 e extensão pgvector | Persistência do domínio, índices e estruturas para conteúdo de conhecimento. O backend aplica migrations pendentes ao iniciar o container. |
+| Serviço Python | `ai-service/`, FastAPI | Endpoints de saúde, chunking, embeddings, consulta RAG e execução/consulta de análises de repositório. É executado no perfil Docker `local-ai`. |
+| Ollama | container opcional | Provedor local de modelos de embedding e geração. Os modelos são baixados pelo operador; não vêm no build da imagem. |
+| n8n | container padrão, integrações opcionais | Consumidor de eventos/integrador. O evento de remoção pode ser enviado por `DOCUMENT_EVENTS_WEBHOOK_URL`; sem URL, é retido e reprocessado. |
-
+**Diretriz de dados:** o backend é a autoridade de negócio para autenticação, regras, autorização e mutações do domínio. Os clientes web e modelos não devem contornar essas validações. Configure acesso ao PostgreSQL apenas para serviços confiáveis na rede privada.
----
+## Fluxos implementados
-## 2. Fluxo de Consulta Semântica e RAG
+### Autenticação e autorização
-Ilustra o ciclo de vida completo de uma pergunta realizada pelo Product Owner em linguagem natural (ex: *"Como tratamos concorrência no PIX?"*):
+1. A UI registra ou autentica a pessoa pela API.
+2. O backend gerencia sessões e valida-as em cada rota protegida.
+3. `admin`, `po` e `dev` são perfis de negócio. A autorização é validada na API; ocultar um botão no frontend não substitui a regra do backend.
+4. O modo de leitura de um projeto arquivado também é aplicado no servidor para operações de escrita.
-1. O **PO** envia a pergunta através da SPA em React.
-2. O **Backend Node.js** recebe a requisição, autentica o usuário e valida o `projeto_id` para garantir o isolamento por metadados.
-3. O **Serviço Python de IA** gera o embedding vetorial da query utilizando o modelo configurado no Ollama (`bge-m3`).
-4. O Python executa a busca híbrida no **PostgreSQL com pgvector**, aplicando filtro estrito por `projeto_id` e ordenação por distância de cosseno (`<=>`).
-5. Os top-5 chunks mais relevantes retornam do banco para o Python.
-6. O Python injeta os chunks no prompt controlado do **Harness** (com regras para não alucinar e citar fontes obrigatoriamente).
-7. O **LLM local** processa o contexto e gera a resposta estruturada com citações exatas.
-8. A resposta com metadados de proveniência é enviada de volta ao Node.js e renderizada na interface do PO com links rastreáveis para os requisitos e documentos de origem.
+Veja [contrato da API](../api/openapi.yaml) e [guia de setup](../SETUP_GUIDE.md).
-### Diagrama de Sequência Mermaid
+### Backlog e qualidade
```mermaid
-sequenceDiagram
- autonumber
- actor PO as Product Owner
- participant Web as React Frontend
- participant Node as Node.js Backend
- participant Py as Python IA Service
- participant PG as PostgreSQL + pgvector
- participant LLM as LLM Local (Ollama)
-
- PO->>Web: Pergunta: "Como tratamos concorrência no PIX?"
- Web->>Node: POST /api/chat/consulta (com projeto_id e pergunta)
- Node->>Py: POST /rag/retrieve (pergunta, projeto_id)
- Py->>Py: Gera embedding vetorial da pergunta
- Py->>PG: SELECT texto, fonte FROM chunk WHERE projeto_id = $1 ORDER BY embedding <=> $2 LIMIT 5
- PG-->>Py: Retorna top-5 chunks com maior similaridade
- Py->>LLM: Injeta chunks recuperados no prompt do Harness
- LLM-->>Py: Resposta estruturada com citação exata das fontes
- Py-->>Node: Retorna resposta + metadados de proveniência
- Node-->>Web: Exibe resposta com links para requisitos/documentos
+flowchart LR
+ P["Projeto"] --> E["Épico"] --> F["Feature"] --> B["PBI"] --> C["Critérios DADO / QUANDO / ENTÃO"]
+ API["Backend: validação e autorização"] --> DB[("PostgreSQL")]
+ P --> API
+ E --> API
+ F --> API
+ B --> API
+ C --> API
```
-
-🖼️ Ver imagem estática renderizada
-
-.jpg)
+O backlog suporta leitura, escrita por perfis autorizados, relações de tecnologia, busca textual no projeto, decisões em diferentes níveis, arquivamento e auditoria. O painel de qualidade calcula verificações determinísticas e a aplicabilidade da regra de protótipo. A configuração de regras é versionada e alterações administrativas são atribuídas e auditadas.
-
+### Documentos
----
+1. A API valida nome, formato, tamanho, existência do projeto e estado de arquivamento.
+2. O arquivo é salvo no storage configurado; metadados, auditoria e operação pendente são persistidos no banco.
+3. Um worker retenta operações de storage e eventos de integração até concluir ou atingir a política configurada.
+4. A listagem é paginada por cursor e sempre delimitada ao projeto.
-## 3. Diagrama Entidade-Relacionamento (ERD)
+O upload grava o arquivo e seus metadados; **isso não significa que o conteúdo já foi extraído ou indexado**. A extração, geração de embeddings e persistência de chunks dependem do pipeline de conhecimento configurado. Consulte [documentação de integração](../DOCUMENTOS_INTEGRACAO.md).
-Descreve a modelagem de dados relacional e vetorial unificada no PostgreSQL.
+### Busca e conversa
-### Destaques da Modelagem
-- **Hierarquia de Requisitos:** `PROJETO` → `EPICO` → `FEATURE` → `PBI` → `CRITERIO_ACEITACAO`.
-- **Rastreabilidade e Proveniência:** Critérios de aceitação com formato BDD (`dado`, `quando`, `entao`) e campos específicos para histórias de usuário (`historia_como_um`, `historia_eu_quero`, `historia_para_que`).
-- **Isolamento de Conhecimento:** A tabela `CHUNK` armazena `projeto_id` desnormalizado para garantir que as buscas vetoriais não vazem informações entre projetos diferentes. A coluna `embedding` utiliza o tipo nativo `vector` do `pgvector`.
-- **Mapeamento de Competências:** Relação `USUARIO` → `DESENVOLVEDOR` → `COMPETENCIA` → `TECNOLOGIA` para identificação de especialistas na equipe.
-- **Registro de Decisões:** A entidade `DECISAO` (armazenamento de contexto, justificativa e alternativas descartadas em qualquer nível da hierarquia) está planejada para implementação no DDL na tarefa `S1-18`.
+O backend guarda conversas e mensagens por usuário, valida a posse da conversa e, quando informado, limita a consulta ao projeto escolhido. Tenta consultar o cliente HTTP de IA configurado; diante de indisponibilidade ou resposta inválida, procura trechos existentes no Postgres usando os termos da pergunta e devolve as fontes encontradas. Sem evidência, responde que a informação não foi encontrada.
-### Diagrama ERD Mermaid
+**Integração em validação:** o serviço Python e o cliente HTTP do backend evoluíram contratos de requisição/resposta independentes. O fluxo de IA deve ser validado de ponta a ponta (backend → FastAPI → Ollama) antes de ser anunciado como funcional em um ambiente. Os testes E2E cobrem o chat com serviço indisponível e seu fallback; eles não certificam inferência local.
-```mermaid
-erDiagram
- PROJETO ||--o{ EPICO : contem
- PROJETO ||--o{ DOCUMENTO : possui
- PROJETO ||--o{ CHUNK : escopo_isolamento
- PROJETO ||--o{ ALOCACAO : aloca
-
- EPICO ||--o{ FEATURE : divide
- FEATURE ||--o{ PBI : decompoe
-
- EPICO ||--o{ CRITERIO_ACEITACAO : possui
- FEATURE ||--o{ CRITERIO_ACEITACAO : possui
- PBI ||--o{ CRITERIO_ACEITACAO : possui
-
- PBI ||--o{ PROTOTIPO : anexa
- PBI ||--o{ PBI_RELACAO : relaciona
-
- USUARIO ||--o| DESENVOLVEDOR : perfil
- DESENVOLVEDOR ||--o{ COMPETENCIA : domina
- TECNOLOGIA ||--o{ COMPETENCIA : categoriza
- TECNOLOGIA ||--o{ ENTIDADE_TECNOLOGIA : taggeia
-
- USUARIO ||--o{ CONVERSA : cria
- CONVERSA ||--o{ MENSAGEM : contem
-
- DOCUMENTO ||--o{ CHUNK : fragmentado_em
-
- PROJETO {
- uuid id PK
- varchar nome
- varchar cliente
- text descricao
- varchar status
- timestamp data_inicio
- }
-
- EPICO {
- uuid id PK
- uuid projeto_id FK
- varchar titulo
- text objetivo
- text escopo_macro
- varchar prioridade
- }
-
- FEATURE {
- uuid id PK
- uuid epico_id FK
- varchar titulo
- text objetivo
- varchar prioridade
- }
-
- PBI {
- uuid id PK
- uuid feature_id FK
- varchar codigo
- varchar titulo
- text historia_como_um
- text historia_eu_quero
- text historia_para_que
- text regras_observacoes
- varchar tipo
- varchar prioridade
- int score_completude
- }
-
- CRITERIO_ACEITACAO {
- uuid id PK
- varchar entidade_tipo
- uuid entidade_id
- text texto
- text dado
- text quando
- text entao
- }
-
- DOCUMENTO {
- uuid id PK
- uuid projeto_id FK
- varchar nome
- varchar mime
- varchar caminho
- varchar status_processamento
- }
-
- CHUNK {
- uuid id PK
- uuid projeto_id FK "Desnormalizado para isolamento rapido"
- varchar entidade_tipo
- uuid entidade_id
- text texto
- jsonb metadados_json
- vector embedding "Coluna vetorial pgvector"
- }
-
- DESENVOLVEDOR {
- uuid id PK
- uuid usuario_id FK
- varchar senioridade
- text bio
- }
-
- COMPETENCIA {
- uuid id PK
- uuid desenvolvedor_id FK
- uuid tecnologia_id FK
- varchar nivel
- text evidencia
- }
-```
+### Análise de repositório
-
-🖼️ Ver imagem estática renderizada
+O backend valida o projeto e a URL do GitHub, pede ao FastAPI para iniciar uma execução e persiste o identificador recebido. Consultas seguintes sincronizam estágio, progresso e relatório. O acesso ao projeto e o estado de arquivamento são revalidados nas rotas.
-.jpg)
+## Dados e evolução do schema
-
+- `database/init.sql` é o baseline aplicado quando um volume PostgreSQL é inicializado pela primeira vez.
+- `database/migrations/NNN_*.sql` contém alterações posteriores. O runner aplica arquivos pendentes em transação e registra os nomes completos em `_schema_migrations`.
+- As duas migrations `004` e as duas migrations `005` são histórico publicado; não as renomeie. A ordenação lexicográfica atual é intencional.
+- PostgreSQL armazena usuários/sessões, projetos, hierarquia do backlog, critérios, decisões, documentos, chunks, conversas, configurações de qualidade e auditoria.
+- `pgvector` está disponível para embeddings; a existência da coluna ou extensão, isoladamente, não prova que um pipeline de ingestão está ativo.
----
+Para alterações, crie uma nova migration idempotente quando possível. Não reescreva `init.sql` para reparar volumes já existentes. Consulte [guia de migrations](../../database/migrations/README.md).
-## 4. Resumo das Fronteiras Arquiteturais
+## Deploy local
-| Camada | Tecnologia | O que faz | O que NÃO faz |
-|---|---|---|---|
-| **Frontend** | React 19 / Vite / TS | Coleta entradas do PO, exibe acervo, renderiza chat e marca proveniência visualmente. | Não valida regras de negócio nem conversa direto com o banco ou Ollama. |
-| **Backend** | Node.js 20+ / Express / TS | Autenticação, CRUD, validações determinísticas de conformidade (regex, termos vagos) e **única escrita nas tabelas de negócio**. | Não calcula embeddings nem executa RAG. |
-| **Serviço de IA** | Python 3.11+ / FastAPI | **Fonte única da verdade para chunking**, gera embeddings, monta o contexto do Harness e consulta o LLM. | **Nunca grava diretamente nas tabelas de negócio** (devolve sugestões para confirmação humana). |
-| **Ingestão** | n8n | Watch de pastas em `/files`, conversão de arquivos e gatilhos de disparo para `POST /ingest`. | Não define o tamanho dos chunks nem calcula vetores internamente. |
-| **Banco** | PostgreSQL 16 + pgvector | Armazena dados relacionais estruturados e vetores de chunks indexados por HNSW. | Não expõe acesso direto para o cliente web. |
-| **IA Local** | Ollama | Executa modelos de LLM e Embeddings localmente via API HTTP. | Não gerencia permissões de projeto ou regras de negócio da PRO4TECH. |
-
----
-
-## 5. Seleção e Benchmark de Embeddings (Spike PRE-07)
-
-### Decisão Técnica: `BAAI/bge-m3` via Ollama Local
-
-* **Modelo Recomendado:** `BAAI/bge-m3` (Multilíngue nativo, topo do benchmark MTEB em PT-BR)
-* **Dimensão do Vetor:** **1024** (100% aderente à coluna `chunk.embedding vector(1024)` do PostgreSQL pgvector, sem necessidade de alterações no DDL).
-* **Janela de Contexto:** 8.192 tokens por chunk.
-* **Acurácia em PT-BR:** 100% Top-1 nos testes de similaridade semântica com margem de separação média de **+0,81** sobre ruído.
-
-### Comparativo dos Modelos Avaliados:
-
-| Modelo | Dimensão Vetorial | Compatibilidade `pgvector(1024)` | Acurácia Top-1 | Margem Média contra Distrator | Latência Média | Consumo RAM/VRAM |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| **`bge-m3`** | **1024** | **COMPATÍVEL** | **100%** | **+0,81** | **~142 ms** | ~3,0 GB |
-| **`multilingual-e5-large`** | 1024 | COMPATÍVEL | 100% | +0,74 | ~158 ms | ~3,1 GB |
-| **`nomic-embed-text`** | 768 | INCOMPATÍVEL | 100% | +0,59 | ~48 ms | ~1,1 GB |
-| **`all-MiniLM-L6-v2`** | 384 | INCOMPATÍVEL | 100% | +0,35 | ~22 ms | ~0,4 GB |
-
----
+```text
+Compose padrão: frontend + backend + PostgreSQL/pgvector + n8n
+Perfil local-ai: Ollama + FastAPI
+```
-## 6. Evolução Técnica: Proposta GraphRAG Híbrido
+No Compose, o backend acessa `postgres:5432` e a interface usa Nginx para encaminhar `/api` a `backend:3001`. Processos locais no host usam portas publicadas — PostgreSQL `55432`, API `3001` e frontend `5173` por padrão. URLs e credenciais estão em `.env`; `.env.example` serve apenas a ambientes locais.
-O GraphRAG (Graph Retrieval-Augmented Generation) evolui o RAG vetorial unindo busca semântica por embeddings e navegação em grafo de conhecimento relacional.
+## Qualidade e operações
-### Eixos do Grafo no Sinapse:
-- **`PROJETO`** $\leftrightarrow$ **`PESSOAS`** $\leftrightarrow$ **`TECNOLOGIAS / STACKS`** $\leftrightarrow$ **`DECISÕES`** $\leftrightarrow$ **`DOCUMENTOS`**
+- CI: build/typecheck, suites backend/frontend, testes PostgreSQL, validação do seed, configuração Compose e testes Python.
+- E2E: cenários de navegador com API e PostgreSQL reais, incluindo autorização, isolamento, documentos, hierarquia e acessibilidade.
+- Healthchecks: `/health` no backend e serviço Python.
+- Logs e migrations: use `docker compose logs -f backend` e consulte `_schema_migrations` antes de investigar divergência de schema.
-### Modelo Relacional do Grafo no PostgreSQL:
-```sql
-CREATE TABLE knowledge_entity (
- id UUID PRIMARY KEY,
- project_id UUID NOT NULL REFERENCES projeto(id) ON DELETE CASCADE,
- entity_type VARCHAR(50) NOT NULL, -- TECHNOLOGY, PERSON, PROJECT, DECISION
- name TEXT NOT NULL,
- normalized_name TEXT NOT NULL
-);
+Comandos completos e variáveis ficam no [guia de setup](../SETUP_GUIDE.md). Matriz de cobertura no [README E2E](../../e2e/README.md).
-CREATE TABLE knowledge_relation (
- id UUID PRIMARY KEY,
- project_id UUID NOT NULL REFERENCES projeto(id) ON DELETE CASCADE,
- source_entity_id UUID NOT NULL REFERENCES knowledge_entity(id),
- relation_type VARCHAR(80) NOT NULL, -- USES, WORKED_ON, DEPENDS_ON, JUSTIFIES
- target_entity_id UUID NOT NULL REFERENCES knowledge_entity(id),
- source_chunk_id UUID REFERENCES chunk(id),
- confidence REAL
-);
-```
+## Propostas e referências históricas
-### Pipeline GraphRAG de Consulta:
-1. **Filtro Estrito por Projeto:** Aplica `project_id` antes do traversal.
-2. **Hybrid Search:** Combina Similaridade Vetorial (`pgvector` HNSW) + Busca em Grafo (1-2 saltos).
-3. **Context Builder & Harness:** Injeta contexto enriquecido com entidades e citações exatas no prompt do LLM.
+GraphRAG, extração de relações em grafo e os benchmarks de embeddings são propostas/experimentos de evolução; não são componentes que o Compose padrão instala. Mantenha essas hipóteses vinculadas às referências e atualize este status quando houver implementação e validação correspondentes.
+- [Diagramas Mermaid](Diagrams/Architecture.mmd)
+- [Diagrama de arquitetura e ingestão](Diagrams/Vis%C3%A3o%20Geral%20da%20Arquitetura%20e%20Ingest%C3%A3o.jpg)
+- [Fluxo conceitual RAG](Diagrams/RAG.mmd)
+- [ERD](Diagrams/ERD.mmd)
+- [PRD e requisitos de produto](../PRD-PRO4TECH.md)
+- [PRD](../PRD-PRO4TECH.md)
diff --git a/docs/DOCUMENTOS_INTEGRACAO.md b/docs/DOCUMENTOS_INTEGRACAO.md
index 06d7009..c4f7ad6 100644
--- a/docs/DOCUMENTOS_INTEGRACAO.md
+++ b/docs/DOCUMENTOS_INTEGRACAO.md
@@ -1,5 +1,10 @@
# Documentos: upload, remoção, outbox e escopo (S1-19, S1-20, S1-22)
+> Estado revisado em 27/09/2026. Este guia detalha o contrato de documentos da
+> Sprint 1. O upload persiste o arquivo e seus metadados; extração, chunking e
+> indexação não são prometidos como concluídos. Veja também a [arquitetura](Architecture/README.md)
+> e a [referência da API](api/openapi.yaml).
+
## Escopo desta entrega x Sprint 2
| Item | Entregue (Sprint 1) | Fica para a S2-01 |
@@ -74,10 +79,9 @@ Os `chunk` no PostgreSQL já são removidos pelo backend na mesma transação; o
## Como validar
```bash
-cd backend && npm test && npm run build
-# Com PostgreSQL descartável (nome terminando em _test):
-ARCHIVE_TEST_DATABASE_URL=postgresql://user:pass@localhost:5432/sinapse_x_test \
-BACKLOG_TREE_TEST_DATABASE_URL=$ARCHIVE_TEST_DATABASE_URL npm test
+cd backend
+npm test
+npm run build
```
-Os testes de banco cobrem migração 012 (banco limpo e já na 011, idempotência e dados legados), corrida arquivamento x upload/remoção, lease e backoff da outbox, operações de armazenamento e paginação estável isolada por projeto. Os testes E2E de navegador estão em `e2e/` (ver `e2e/README.md`).
+Os testes de banco cobrem migração 012 (banco limpo e já na 011, idempotência e dados legados), corrida arquivamento x upload/remoção, lease e backoff da outbox, operações de armazenamento e paginação estável isolada por projeto. Para habilitar as suítes PostgreSQL, configure URLs de banco descartável documentadas no [guia de setup](SETUP_GUIDE.md); no PowerShell use `$env:NOME_DA_VARIAVEL = '...'`. Nunca aponte essas variáveis para uma base compartilhada ou produção. Os testes E2E de navegador estão em `e2e/` (ver [README E2E](../e2e/README.md)).
diff --git a/docs/PLANEJAMENTO_SCRUM.md b/docs/PLANEJAMENTO_SCRUM.md
index 475cd9d..f1b9bbd 100644
--- a/docs/PLANEJAMENTO_SCRUM.md
+++ b/docs/PLANEJAMENTO_SCRUM.md
@@ -1,6 +1,6 @@
# Planejamento de Tarefas por Sprint — Sinapse
-> Organização das tarefas de desenvolvimento e sua relação direta com as User Stories do Backlog de Produto v1.1.
+> Planejamento de produto e registro da execução da Sprint 1. Situação atualizada em 27/09/2026.
## Visão geral
@@ -10,11 +10,45 @@
| Features | 18 |
| User Stories/PBIs | 66 |
| Tarefas técnicas | 71 |
-| Sprints | 3 |
+| Sprints previstas no plano inicial | 3 |
+| Sprints concluídas até 27/09/2026 | 1 |
Este planejamento converte as 66 User Stories em tarefas técnicas executáveis. Cada tarefa está vinculada a pelo menos um PBI existente e deve ser validada contra os respectivos cenários de aceitação.
-A distribuição individual está em andamento. As atribuições já confirmadas aparecem abaixo; todas as demais tarefas continuam sem responsável definido.
+## Equipe do projeto
+
+| Papel | Integrante | GitHub |
+|---|---|---|
+| Product Owner (PO) | Daniel Dias | [@DanielDPereira](https://github.com/DanielDPereira) |
+| Scrum Master | Cauan Gabriel | [@LoadCG](https://github.com/LoadCG) |
+| Development Team | Emmanuel Garakis | [@Garakis](https://github.com/Garakis) |
+| Development Team | Rafael Matesco | [@RafaMatesco](https://github.com/RafaMatesco) |
+| Development Team | Gustavo Bueno | [@Darkghostly](https://github.com/Darkghostly) |
+| Development Team | Gabriel Lasaro | [@GaelNotFound](https://github.com/GaelNotFound) |
+| Development Team | Giovanni | [@Giomoret](https://github.com/Giomoret) |
+| Development Team | Heitor | [@heitors1337](https://github.com/heitors1337) |
+| Development Team | Vitor | [@vitorpdim](https://github.com/vitorpdim) |
+
+Os perfis foram associados por nomes públicos e autoria de commits neste
+repositório. Gabriel Lasaro aparece no histórico como Gabriel, com o e-mail de
+commit `gaelslasaro@gmail.com`, ligado ao perfil [@GaelNotFound](https://github.com/GaelNotFound).
+
+## Abordagem Scrum
+
+O produto foi organizado em backlog priorizado, estruturado em épicos, features
+e PBIs. O plano inicial previa três sprints. **Até 27/09/2026, somente a Sprint 1
+foi executada e concluída**; as sprints seguintes seguem como planejamento, sem
+serem apresentadas como trabalho realizado.
+
+O acompanhamento documentado foi feito por tarefas relacionadas aos PBIs,
+critérios de aceitação, revisão das entregas e consolidação de QA. Este repositório
+não registra cadência/duração de cerimônias ou métricas de velocidade, portanto
+esses detalhes não são presumidos aqui.
+
+## Distribuição parcial registrada no plano inicial
+
+As atribuições abaixo são as que constavam no plano de trabalho; não representam
+uma lista completa de autoria nem substituem os papéis atuais informados pela equipe.
## Distribuição parcial da equipe
@@ -71,9 +105,15 @@ A distribuição individual está em andamento. As atribuições já confirmadas
**Meta:** entregar a hierarquia no padrão PRO4TECH, autenticação, validações determinísticas, decisões e anexos sem dependência de IA.
-### O que será entregue
+### Resultado e escopo planejado
-Ao final da Sprint 1, espera-se que uma pessoa autorizada consiga entrar na plataforma, criar e organizar projetos, épicos, features e PBIs, registrar critérios de aceitação e decisões, navegar pela estrutura e anexar documentos. O sistema também deverá orientar a escrita conforme o padrão da PRO4TECH.
+O objetivo planejado foi permitir que uma pessoa autorizada entre na plataforma,
+crie e organize projetos, épicos, features e PBIs, registre critérios de
+aceitação e decisões, navegue pela estrutura e anexe documentos. A Sprint 1 foi
+encerrada em 27/09/2026. O estado efetivamente implementado deve ser conferido
+no [README](../README.md), na [arquitetura](Architecture/README.md) e nos critérios
+de aceite; esta lista descreve o escopo planejado, não afirma que cada item foi
+entregue sem ressalvas.
### Habilitadores
@@ -118,9 +158,9 @@ Ao final da Sprint 1, espera-se que uma pessoa autorizada consiga entrar na plat
| S1-23 | Integrar e validar os fluxos obrigatórios da Sprint 1 com testes e documentação | PBI-01.1.1, PBI-01.1.2, PBI-01.1.3, PBI-01.1.4, PBI-01.1.5, PBI-01.2.1, PBI-01.2.2, PBI-01.2.3, PBI-01.3.1, PBI-01.3.2, PBI-01.3.3, PBI-01.3.5, PBI-01.4.1, PBI-01.4.2, PBI-01.5.1, PBI-01.5.2, PBI-02.1.1, PBI-06.1.1, PBI-06.1.2, PBI-06.1.3 |
| S1-24 | Exigir justificativa obrigatória e gravar histórico ao alterar item salvo | PBI-01.5.6 |
-## Sprint 2
+## Sprint 2 — planejada, não iniciada
-**Período:** 05/10/2026 a 25/10/2026
+**Período planejado:** 05/10/2026 a 25/10/2026
**Quantidade:** 18 tarefas
@@ -154,9 +194,9 @@ Ao final da Sprint 2, documentos e itens concluídos deverão formar um acervo p
| S2-20 | Permitir configurar e exibir Definição de Preparado (DoR) e Definição de Pronto (DoD) | PBI-01.6.2 |
| S2-21 | Restringir sugestões semânticas do copiloto estritamente ao acervo do projeto e item em edição | PBI-03.2.4 |
-## Sprint 3
+## Sprint 3 — planejada, não iniciada
-**Período:** 02/11/2026 a 22/11/2026
+**Período planejado:** 02/11/2026 a 22/11/2026
**Quantidade:** 17 tarefas
@@ -199,7 +239,7 @@ Ao final da Sprint 3, as pessoas poderão conversar com o acervo e receber respo
| Sprint | Tarefas | Situação |
|:---:|:---:|---|
-| 1 | 33 (9 PRE + 24 S1) | Todas relacionadas a PBIs existentes |
-| 2 | 21 | Todas relacionadas a PBIs existentes |
-| 3 | 17 | Todas relacionadas a PBIs existentes |
-| **Total** | **71** | **100% de cobertura (66 de 66 PBIs mapeados)** |
+| 1 | 33 (9 PRE + 24 S1) | Concluída em 27/09/2026; tarefas mapeadas a PBIs |
+| 2 | 21 | Planejada; ainda não executada |
+| 3 | 17 | Planejada; ainda não executada |
+| **Plano total** | **71** | Cobertura planejada: 66 de 66 PBIs mapeados |
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..ee6d409
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,47 @@
+# Documentação do Sinapse
+
+Este índice separa os guias operacionais, contratos e especificações de produto. O [README da raiz](../README.md) apresenta o produto e o caminho rápido para executá-lo.
+
+## Começar e desenvolver
+
+| Documento | Conteúdo |
+|---|---|
+| [Guia de setup](SETUP_GUIDE.md) | Docker Compose, execução local, variáveis, testes e solução de problemas. |
+| [Testes E2E](../e2e/README.md) | Suítes de navegador, dependências e execução com dados descartáveis. |
+| [Migrations](../database/migrations/README.md) | Baseline, migrations versionadas e validação do banco. |
+| [Seed](../database/seed/README.md) | Acervo curado, validação, modo de aplicação e política de segurança. |
+
+## Produto e arquitetura
+
+| Documento | Fonte de verdade para |
+|---|---|
+| [PRD PRO4TECH](PRD-PRO4TECH.md) | Problema, visão, requisitos e regras de produto. |
+| [Arquitetura](Architecture/README.md) | Componentes que existem hoje, fronteiras, fluxos e propostas ainda não implementadas. |
+| [Backlog](backlog/README.md) | Épicos, features e PBIs. |
+| [Planejamento Scrum](PLANEJAMENTO_SCRUM.md) | Equipe, abordagem Scrum, estado concluído da Sprint 1 e sprints futuras ainda planejadas. |
+| Interface e handoff | Consulte o [backlog](backlog/README.md) e os [materiais de design](../figma-import/README.md); o documento de handoff S1-28 não está versionado nesta branch. |
+| [Protótipo e Design System](../figma-import/README.md) | Telas, protótipo navegável e materiais de handoff. |
+
+## Contratos e integrações
+
+- [OpenAPI do backend](api/openapi.yaml): endpoints, autenticação, payloads e respostas.
+- [Compatibilidade de rotas legadas](api/epics-compat.yaml): rotas mantidas para clientes antigos.
+- [Integração de remoção de documentos](integrations/n8n-document-removed.example.json): exemplo do evento enviado ao n8n.
+- [Documento de integração](DOCUMENTOS_INTEGRACAO.md): fluxos entre serviços e convenções de integração.
+
+## QA e decisões registradas
+
+- [Matriz de cenários S1-23](qa/S1-23-matriz-cenarios.md)
+- [Roteiro de review S1-23](qa/S1-23-roteiro-review.md)
+- [Consolidação S1-05](../database/migrations/README.md#consolidação-s1-05)
+- [Correções do PR #34](PR34_CORRECTION_PLAN.md)
+- [Correções do PR #36](PR36_CORRECTION_PLAN.md)
+- [Conflitos S1-05](../database/migrations/README.md#consolidação-s1-05)
+
+## Como manter os documentos
+
+- Atualize este índice e o README quando um guia de referência mudar de local ou escopo.
+- Trate o código, as migrations e o OpenAPI como fontes do comportamento implementado.
+- Identifique no texto quando algo é requisito do PRD, decisão histórica, proposta futura ou comportamento já implementado.
+- Não publique credenciais, tokens, dados pessoais, documentos de clientes ou `.env`.
+- Ao adicionar imagens de produto, use capturas reais do app, texto alternativo descritivo e dados sintéticos. Explique o contexto da captura.
diff --git a/docs/SETUP_GUIDE.md b/docs/SETUP_GUIDE.md
new file mode 100644
index 0000000..b4bebd1
--- /dev/null
+++ b/docs/SETUP_GUIDE.md
@@ -0,0 +1,195 @@
+# Setup e desenvolvimento local
+
+Este guia cobre dois caminhos: subir o produto em containers ou executar backend e frontend no host usando PostgreSQL do Docker. Para entender serviços e limites de responsabilidade, consulte [Arquitetura](Architecture/README.md); para endpoints, consulte o [OpenAPI](api/openapi.yaml).
+
+## Requisitos
+
+### Execução com Docker
+
+- Docker Desktop com Docker Compose v2.
+- Git para clonar o repositório.
+
+### Desenvolvimento no host
+
+- Node.js 20 ou superior e npm.
+- Python 3.11 ou superior para o serviço de IA.
+- Google Chrome ou Chromium para a suíte E2E.
+- Docker disponível para PostgreSQL + pgvector.
+
+## Opção A — Aplicação completa com Docker Compose
+
+```bash
+git clone https://github.com/Galaticos-API/API-4.git
+cd API-4
+cp .env.example .env
+docker compose up --build -d
+docker compose ps
+```
+
+No PowerShell, substitua `cp .env.example .env` por `Copy-Item .env.example .env`.
+
+O Compose padrão inicia PostgreSQL, n8n, backend e frontend. O backend aplica migrations pendentes antes de aceitar tráfego. URLs padrão:
+
+- Frontend:
+- Saúde do backend:
+- Swagger UI:
+- n8n:
+
+O primeiro acesso à aplicação começa pela tela de autenticação. Cadastre uma conta para usar o ambiente local. Os dados enviados permanecem nos volumes Docker até serem removidos explicitamente.
+
+### Habilitar IA local (opcional)
+
+Ollama e o serviço Python usam o perfil `local-ai`:
+
+```bash
+docker compose --profile local-ai up --build -d
+docker compose --profile local-ai exec ollama ollama pull bge-m3
+docker compose --profile local-ai exec ollama ollama pull qwen2.5:1.5b
+```
+
+Os modelos são baixados separadamente e ocupam espaço significativo. O healthcheck do container Ollama confirma que o serviço iniciou, não que cada modelo já foi baixado. A integração de IA deve ser validada no fluxo desejado; o app possui comportamento de fallback quando o assistente está indisponível.
+
+## Opção B — Frontend/backend no host
+
+Use esta opção quando precisar de hot reload. Execute os comandos a partir da raiz do repositório.
+
+### 1. Configure as variáveis locais
+
+```bash
+cp .env.example .env
+docker compose up -d postgres
+```
+
+Se também precisar das integrações locais, inicie `n8n` ou o perfil `local-ai` separadamente. Os containers acessam PostgreSQL pelo hostname `postgres` na porta `5432`; processos no host usam `localhost` e a porta publicada `POSTGRES_PORT` (padrão `55432`).
+
+### 2. Instale dependências e aplique as migrations
+
+```bash
+npm ci --prefix backend
+npm ci --prefix frontend
+npm --prefix backend run migrate
+```
+
+O comando usa `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_HOST` e `POSTGRES_PORT` de `.env`. Aponte-o somente para um banco local apropriado. Migrations pendentes são aplicadas em ordem e registradas em `_schema_migrations`.
+
+### 3. Inicie os serviços em terminais separados
+
+Terminal 1 — backend:
+
+```bash
+cd backend
+npm run dev
+```
+
+Terminal 2 — frontend:
+
+```bash
+cd frontend
+npm run dev
+```
+
+URLs locais padrão: frontend , API , Swagger . O Vite encaminha `/api` e `/health` para `http://localhost:3001` por padrão. Para outro endereço, defina `VITE_API_PROXY_TARGET` no ambiente do processo Vite.
+
+### 4. Serviço Python (opcional)
+
+```bash
+python -m venv .venv
+# Linux/macOS
+source .venv/bin/activate
+# PowerShell
+.venv\Scripts\Activate.ps1
+python -m pip install -r ai-service/requirements.txt
+```
+
+Com Ollama acessível e configurado, inicie o serviço dentro de `ai-service`:
+
+```bash
+python main.py
+```
+
+O serviço lê sua configuração a partir de `ai-service/config.py`. O serviço de IA e o backend são processos distintos: endereços `localhost` funcionam entre processos no host, enquanto containers devem usar os nomes DNS da rede Docker.
+
+## Variáveis importantes
+
+| Variável | Padrão de desenvolvimento | Uso |
+|---|---|---|
+| `POSTGRES_USER` | `sinapse` | Usuário do banco. |
+| `POSTGRES_PASSWORD` | `sinapse_dev_password` | Senha local do banco; troque fora de uma máquina isolada. |
+| `POSTGRES_DB` | `sinapse` | Banco usado pelo backend e pelos containers. |
+| `POSTGRES_PORT` | `55432` | Porta publicada no host; containers usam `5432`. |
+| `BACKEND_PORT` | `3001` | Porta publicada da API. |
+| `FRONTEND_PORT` | `5173` | Porta publicada da SPA. |
+| `N8N_PORT` | `5678` | Porta publicada do n8n. |
+| `DOCUMENT_MAX_SIZE_MB` | `20` | Tamanho máximo de upload aceito pela API. |
+| `DOCUMENT_EVENTS_WEBHOOK_URL` | vazio | Destino HTTP dos eventos de remoção de documento. Sem consumidor configurado, o evento permanece pendente e é tentado novamente. |
+| `OLLAMA_PORT` | `11434` | Porta publicada quando o perfil `local-ai` está ativo. |
+| `OLLAMA_LLM_MODEL` | `qwen2.5:1.5b` | Modelo de geração local. |
+| `OLLAMA_EMBEDDING_MODEL` | `bge-m3` | Modelo de embedding local. |
+
+Consulte `.env.example` para a lista completa. `N8N_ENCRYPTION_KEY` tem um valor compartilhado para facilitar desenvolvimento: substitua por segredo forte e privado em qualquer ambiente exposto. Não coloque tokens de API no Git.
+
+## Testes e build
+
+```bash
+# Backend
+npm ci --prefix backend
+npm --prefix backend run build
+npm --prefix backend run typecheck
+npm --prefix backend test
+
+# Frontend
+npm ci --prefix frontend
+npm --prefix frontend test
+npm --prefix frontend run build
+
+# Serviço Python
+python -m pip install -r ai-service/requirements.txt
+python -m py_compile ai-service/main.py ai-service/config.py ai-service/services/chunker.py ai-service/services/ollama_client.py
+python -m unittest discover -s ai-service/tests -v
+
+# Browser E2E: backend + PostgreSQL + frontend + Chrome devem estar disponíveis
+npm ci --prefix e2e
+npm --prefix e2e test
+```
+
+Os testes unitários de backend funcionam sem banco. Os casos de integração habilitados por `ARCHIVE_TEST_DATABASE_URL`, `BACKLOG_TREE_TEST_DATABASE_URL` e `SEED_TEST_DATABASE_URL` precisam de PostgreSQL descartável com migrations aplicadas. Os scripts `test:integration:s1` e `test:integration:s105` também exigem as URLs de banco dedicadas indicadas no próprio script e no guia de migrations.
+
+Para validar o acervo curado, execute dentro de `backend` `npm run build`, `npm run seed:validate` e `npm run test:seed`. O modo que grava dados, `seed:apply`, exige `SEED_DATABASE_URL` apontando para banco dedicado terminado em `_dev` ou `_test`; leia [o guia do seed](../database/seed/README.md) antes de usar.
+
+## Dados, volumes e limpeza
+
+```bash
+docker compose down
+```
+
+O comando para containers e preserva os volumes nomeados. Para apagar os dados persistidos do ambiente local:
+
+```bash
+docker compose down -v
+```
+
+O segundo comando é destrutivo para o banco, documentos, n8n e modelos guardados nesses volumes. Não o execute se precisar preservar esses dados. Não use a base de desenvolvimento compartilhada para testes E2E que criam e removem registros.
+
+## Diagnóstico rápido
+
+```bash
+docker compose ps
+docker compose logs -f backend
+docker compose logs -f postgres
+docker compose config --quiet
+```
+
+- **Porta ocupada:** altere `POSTGRES_PORT`, `BACKEND_PORT`, `FRONTEND_PORT` ou `N8N_PORT` em `.env`, sem mudar as portas internas dos containers.
+- **API sem saúde:** confira logs do backend e do Postgres; confirme usuário, senha, nome e porta definidos em `.env`.
+- **Alteração de schema não aparece:** confira `_schema_migrations` e os logs do backend. Criar novamente um container não reaplica `init.sql` num volume já existente; crie uma migration versionada.
+- **Upload falha:** verifique o healthcheck `/health`, espaço no volume de documentos e o limite configurado em `DOCUMENT_MAX_SIZE_MB`.
+- **Busca ou chat sem trechos:** a busca depende de conteúdo/chunks disponíveis e isolados por projeto; um arquivo armazenado não implica, por si só, que foi extraído e indexado.
+- **IA indisponível:** confirme perfil `local-ai`, healthchecks, URLs entre containers, download dos modelos e configuração Ollama.
+
+## Documentos relacionados
+
+- [Arquitetura e estado da implementação](Architecture/README.md)
+- [OpenAPI](api/openapi.yaml)
+- [Migrations](../database/migrations/README.md)
+- [Seed e política de dados](../database/seed/README.md)
+- [Índice de toda a documentação](README.md)
diff --git a/docs/media/screenshots/backlog-pbi-quality.png b/docs/media/screenshots/backlog-pbi-quality.png
new file mode 100644
index 0000000..6f8e751
Binary files /dev/null and b/docs/media/screenshots/backlog-pbi-quality.png differ
diff --git a/docs/media/screenshots/backlog-tree.png b/docs/media/screenshots/backlog-tree.png
new file mode 100644
index 0000000..99cef6c
Binary files /dev/null and b/docs/media/screenshots/backlog-tree.png differ
diff --git a/docs/media/screenshots/project-overview.png b/docs/media/screenshots/project-overview.png
new file mode 100644
index 0000000..4bd8427
Binary files /dev/null and b/docs/media/screenshots/project-overview.png differ
diff --git a/docs/media/screenshots/projects.png b/docs/media/screenshots/projects.png
new file mode 100644
index 0000000..25760d9
Binary files /dev/null and b/docs/media/screenshots/projects.png differ
diff --git a/docs/media/sinapse-workflow.gif b/docs/media/sinapse-workflow.gif
new file mode 100644
index 0000000..6f80ba0
Binary files /dev/null and b/docs/media/sinapse-workflow.gif differ
diff --git a/e2e/README.md b/e2e/README.md
index d7d37e8..371394c 100644
--- a/e2e/README.md
+++ b/e2e/README.md
@@ -1,38 +1,47 @@
-# Testes E2E (navegador + API real + PostgreSQL)
+# Testes E2E de navegador
-Cobrem os fluxos autenticados de ponta a ponta com o backend real, o PostgreSQL e o frontend no Chrome.
-Não substituem os testes de unidade de cada módulo.
+Os cenários exercitam a aplicação no Chrome usando frontend, backend e PostgreSQL reais. Eles complementam, mas não substituem, os testes unitários e de integração dos módulos.
## Pré-requisitos
-- PostgreSQL com todas as migrations aplicadas (`cd backend && npm run migrate`).
-- Backend em `http://localhost:3001` (`cd backend && npm run dev`) com `DOCUMENT_STORAGE_DIR` gravável.
-- Frontend em `http://localhost:5173` (`cd frontend && npm run dev`).
-- Google Chrome instalado (ou `E2E_CHROME_PATH` apontando para um executável Chromium).
-- O serviço de IA **não** é necessário: os testes verificam o comportamento quando ele está indisponível.
+- PostgreSQL/pgvector dedicado com migrations aplicadas.
+- Backend acessível em `http://localhost:3001` e `DOCUMENT_STORAGE_DIR` gravável.
+- Frontend acessível em `http://localhost:5173` e encaminhando `/api` ao backend.
+- Chrome ou Chromium instalado.
+- Node.js 20+.
-## Suítes
+O serviço de IA não é necessário: o conjunto valida também o comportamento quando o serviço está indisponível. Não rode a suíte sobre banco compartilhado ou de produção; cada cenário cria usuários, projetos e dados próprios.
-| Arquivo | Cobre |
+## Cobertura
+
+| Arquivo | Principais fluxos |
|---|---|
-| `tests/documents.e2e.mjs` | Upload/lista/remoção, perfis, arquivado, isolamento, limite, cursor, abas |
-| `tests/assistants.e2e.mjs` | RepoAnalyzer, chat, cadastro público sem admin |
-| `tests/flows.e2e.mjs` | Projetos, arquivamento, hierarquia, critérios/qualidade, busca S1-17, decisões S1-18, autorização |
-| `tests/hierarchy-ui.e2e.mjs` | Épico → feature → PBI e arquivamento pelas telas ativas |
-| `tests/a11y.e2e.mjs` | axe (WCAG 2 A/AA) em 10 telas e foco visível por teclado |
+| `tests/documents.e2e.mjs` | Upload, lista, remoção, perfis, projeto arquivado, isolamento, limite, cursor e abas. |
+| `tests/assistants.e2e.mjs` | RepoAnalyzer, chat e limites de cadastro público. |
+| `tests/flows.e2e.mjs` | Projetos, arquivamento, hierarquia, qualidade, busca, decisões e autorização. |
+| `tests/hierarchy-ui.e2e.mjs` | Criação de épico → feature → PBI, critérios e arquivamento pelas telas. |
+| `tests/a11y.e2e.mjs` | axe WCAG 2 A/AA em telas principais e navegação/foco por teclado. |
-No GitHub há o workflow manual **E2E (navegador)** (`.github/workflows/e2e.yml`).
+## Executar localmente
-## Execução
+Configure as URLs para os serviços ativos (os padrões já são os da tabela de pré-requisitos):
```bash
cd e2e
npm ci
-npm test # todos os cenários
-node --test tests/documents.e2e.mjs # uma suíte
+npm test
```
-Variáveis: `E2E_API_URL`, `E2E_APP_URL`, `E2E_CHROME_PATH`, `E2E_TIMEOUT_MS`.
+Para executar um arquivo isolado:
+
+```bash
+node --test tests/documents.e2e.mjs
+```
+
+Variáveis opcionais: `E2E_API_URL`, `E2E_APP_URL`, `E2E_CHROME_PATH` e `E2E_TIMEOUT_MS`. `E2E_API_URL` deve incluir o prefixo `/api/v1`.
+
+## GitHub Actions
+
+O workflow [E2E (navegador)](../.github/workflows/e2e.yml) roda automaticamente em pull requests para `main` e em pushes para `main` quando mudanças afetam backend, frontend, banco, E2E, Compose ou o próprio workflow. Também pode ser iniciado manualmente pelo `workflow_dispatch`.
-Cada cenário cria usuários e projetos próprios (nomes únicos), então pode rodar repetidamente no mesmo banco de desenvolvimento.
-Use um banco descartável em ambientes compartilhados.
+Cada execução de CI provisiona PostgreSQL descartável, aplica migrations, inicia frontend/backend e executa os cenários no Chrome. O job publica logs dos serviços quando falha.