diff --git a/README.md b/README.md
new file mode 100644
index 00000000..15ccf5c0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,209 @@
+# Bot SIBS — Vitória AI
+
+Assistente virtual interno para consulta de documentação através de uma interface de chat. O projeto utiliza uma arquitetura **RAG** (*Retrieval-Augmented Generation*): pesquisa os excertos mais relevantes dos documentos e envia esse contexto para um modelo de linguagem local, que produz uma resposta curta em português e identifica as fontes consultadas.
+
+## Funcionalidades
+
+- Interface de chat desenvolvida em Angular 18;
+- API REST desenvolvida com FastAPI;
+- pesquisa semântica multilingue com Sentence Transformers;
+- indexação e pesquisa vetorial com FAISS;
+- respostas geradas por um servidor compatível com a API do llama.cpp;
+- apresentação do documento, categoria, `chunk_id` e distância de cada fonte;
+- suporte a documentos digitalizados através do processo auxiliar de OCR.
+
+## Arquitetura
+
+```text
+Utilizador
+ │
+ ▼
+Frontend Angular (:4200)
+ │ POST /perguntar
+ ▼
+API FastAPI (:8000)
+ ├── Sentence Transformer ──► índice FAISS
+ │ │
+ │ ▼
+ │ excertos relevantes
+ │
+ └── contexto + pergunta ──► servidor llama.cpp ──► resposta
+```
+
+## Estrutura do projeto
+
+```text
+Bot SIBS/
+├── app.py # API FastAPI e fluxo RAG
+├── dataset_chunks.json # Conteúdo e metadados dos excertos
+├── embeddings.npy # Embeddings gerados durante a indexação
+├── indice_documentos.faiss # Índice vetorial usado pela API
+├── pdfs/ # Documentos de origem
+├── Scripts/
+│ ├── Classificador.ipynb # Extração, divisão e indexação documental
+│ └── OCR.ipynb # Tratamento OCR de PDFs digitalizados
+└── Frontend/angular-internal-chat/ # Aplicação Angular
+```
+
+## Pré-requisitos
+
+- Python 3.10 ou superior;
+- Node.js 18.19 ou superior e npm;
+- servidor llama.cpp, ou outro servidor com endpoint compatível com OpenAI Chat Completions;
+- ficheiros `dataset_chunks.json` e `indice_documentos.faiss` gerados e compatíveis entre si.
+
+Para voltar a processar documentos digitalizados são também necessários Tesseract OCR, o idioma português do Tesseract e Ghostscript. Estes componentes não são necessários para executar o chat com um índice já criado.
+
+## Instalação
+
+### 1. Backend
+
+Na raiz do projeto, crie e ative um ambiente virtual:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+```
+
+Instale as dependências:
+
+```powershell
+python -m pip install fastapi "uvicorn[standard]" requests pandas numpy faiss-cpu sentence-transformers
+```
+
+> Na primeira execução, o Sentence Transformers poderá descarregar o modelo `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2`.
+
+### 2. Frontend
+
+```powershell
+Set-Location .\Frontend\angular-internal-chat
+npm install
+```
+
+## Configuração
+
+Antes de iniciar a aplicação, reveja as constantes no início de `app.py`:
+
+```python
+INDEX_PATH = r"D:\Trabalhos\Bot SIBS\indice_documentos.faiss"
+CHUNKS_PATH = r"D:\Trabalhos\Bot SIBS\dataset_chunks.json"
+LLAMA_URL = "http://192.168.1.39:8089/v1/chat/completions"
+MODEL_NAME = "Qwen3-1.7B-Q4_K_M.gguf"
+```
+
+- `INDEX_PATH`: caminho para o índice FAISS;
+- `CHUNKS_PATH`: caminho para o dataset de excertos;
+- `LLAMA_URL`: endpoint de Chat Completions do servidor do modelo;
+- `MODEL_NAME`: nome do modelo disponibilizado pelo servidor.
+
+O endereço da API utilizado pelo frontend encontra-se em:
+
+```text
+Frontend/angular-internal-chat/src/environments/environment.ts
+```
+
+Por defeito, o frontend comunica com `http://127.0.0.1:8000/perguntar` e aguarda até 240 segundos por uma resposta.
+
+## Execução
+
+### 1. Iniciar o servidor do modelo
+
+Inicie o llama.cpp com o modelo configurado e confirme que o endpoint definido em `LLAMA_URL` está acessível.
+
+### 2. Iniciar o backend
+
+Execute na raiz do projeto:
+
+```powershell
+python -m uvicorn app:app --reload --host 127.0.0.1 --port 8000
+```
+
+Verifique o estado da API em . A resposta esperada é:
+
+```json
+{"status": "ok"}
+```
+
+A documentação interativa fica disponível em .
+
+### 3. Iniciar o frontend
+
+Noutro terminal:
+
+```powershell
+Set-Location .\Frontend\angular-internal-chat
+npm start
+```
+
+Abra no browser.
+
+## API
+
+### `POST /perguntar`
+
+Pedido:
+
+```json
+{
+ "pergunta": "Como validar a receção dos webservices?"
+}
+```
+
+Resposta:
+
+```json
+{
+ "pergunta": "Como validar a receção dos webservices?",
+ "resposta": "Resposta produzida com base nos documentos...",
+ "fontes": [
+ {
+ "nome_pdf": "Manual_Outs_EDP_VF.pdf",
+ "categoria": "Outros",
+ "chunk_id": 3,
+ "score_distancia": 12.34
+ }
+ ]
+}
+```
+
+Exemplo em PowerShell:
+
+```powershell
+$body = @{ pergunta = "Como validar a receção dos webservices?" } | ConvertTo-Json
+Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:8000/perguntar" -ContentType "application/json" -Body $body
+```
+
+## Atualização da base documental
+
+O notebook `Scripts/Classificador.ipynb` contém o processo de extração de texto, divisão em excertos, criação de embeddings e geração do índice FAISS. O notebook `Scripts/OCR.ipynb` trata previamente PDFs sem texto pesquisável.
+
+Depois de processar novos documentos:
+
+1. copie `dataset_chunks.json` e `indice_documentos.faiss` para os caminhos configurados no backend;
+2. mantenha os dois ficheiros sincronizados, pois a posição de cada vetor corresponde à respetiva linha do dataset;
+3. reinicie a API para carregar o novo índice e os novos excertos.
+
+## Notas de segurança e produção
+
+- O CORS está atualmente aberto a todas as origens (`allow_origins=["*"]`); restrinja-o antes de disponibilizar a aplicação numa rede não controlada.
+- Os caminhos e o endereço do modelo estão fixos em `app.py`; para implantação, recomenda-se movê-los para variáveis de ambiente.
+- A API não possui autenticação nem limitação de pedidos.
+- O histórico enviado pela interface ainda não é utilizado pelo backend na geração da resposta.
+- Os documentos e índices podem conter informação interna; não os publique num repositório público.
+
+## Resolução de problemas
+
+**O frontend indica que não consegue ligar ao backend**
+Confirme que o Uvicorn está ativo na porta `8000` e que `apiUrl` está correto no ficheiro de ambiente do Angular.
+
+**A API devolve `Erro llama.cpp`**
+Confirme o endereço em `LLAMA_URL`, o nome em `MODEL_NAME` e se o servidor do modelo aceita pedidos em `/v1/chat/completions`.
+
+**O backend falha ao arrancar**
+Confirme os caminhos de `INDEX_PATH` e `CHUNKS_PATH`, bem como a instalação de `faiss-cpu` e `sentence-transformers`.
+
+**As respostas não correspondem aos documentos**
+Volte a gerar o dataset e o índice em conjunto e confirme que foi usado o mesmo modelo de embeddings configurado no backend.
+
+
+