Expand scenario READMEs with step-by-step execution guides

scenarios/06-rag-vector-classified-docs/README.md

@@ -4,9 +4,9 @@
 
 Demonstrar que um agente RAG ou copilot interno so recupera documentos e chunks autorizados para o usuario final antes de enviar contexto ao LLM.
 
-## Risco De Negocio
+## O Que Este Lab Mostra
 
-Em RAG, o vazamento muitas vezes acontece antes da resposta do modelo: o mecanismo de busca recupera documentos demais e entrega contexto sensivel ao LLM. Este lab mostra como classificar documentos e aplicar Deep Data Security sobre os chunks recuperaveis.
+Antes do Oracle Deep Data Security, a busca vetorial pode recuperar chunks confidenciais de RH, juridico e executivo. Depois dos data grants, a recuperacao vetorial respeita a classificacao do documento e a persona do usuario.
 
 ## Personas
 
@@ -15,20 +15,97 @@ Em RAG, o vazamento muitas vezes acontece antes da resposta do modelo: o mecanis
 - `sofia`: juridico.
 - `carlos`: executivo.
 
-## Narrativa Da Demo
+## Onde Executar Os Comandos
 
-1. O agente recebe a pergunta: "resuma documentos criticos sobre renovacoes, pessoas e riscos legais".
-2. A busca por similaridade tenta recuperar todos os chunks.
-3. Deep Data Security limita os chunks por classificacao e departamento.
-4. O LLM so recebe contexto autorizado.
+Execute os comandos a partir da raiz do repositorio:
 
-## Observacao Sobre Vetores
+```powershell
+cd C:\Users\rodrigo\Documents\Codex\oracle-deep-data-security-lab
+```
 
-O script usa uma coluna `VECTOR(3, FLOAT32)` para manter o lab simples e demonstravel. Em um ambiente real, substitua por embeddings gerados pelo seu modelo e ajuste a metrica de similaridade.
+Conecte no banco com SQLcl ou SQL*Plus:
 
-## Execucao
+```bash
+sql "<connect_string>"
+```
+
+Este cenario usa tipo `VECTOR`, `TO_VECTOR` e `VECTOR_DISTANCE`. Use uma versao do banco com suporte a Oracle AI Vector Search.
+
+## Passo A Passo - Antes, Ambiente Vulneravel
+
+1. Acesse o banco:
+
+   ```bash
+   sql "<connect_string>"
+   ```
+
+2. Limpe o cenario:
+
+   ```sql
+   @scenarios/06-rag-vector-classified-docs/sql/99_reset.sql
+   ```
+
+3. Crie a tabela de chunks, embeddings simples e personas:
+
+   ```sql
+   @scenarios/06-rag-vector-classified-docs/sql/00_schema.sql
+   @scenarios/06-rag-vector-classified-docs/sql/01_seed_data.sql
+   @scenarios/06-rag-vector-classified-docs/sql/02_identities.sql
+   ```
+
+4. Simule a pergunta RAG:
+
+   ```text
+   Resuma documentos criticos sobre renovacoes, pessoas e riscos legais.
+   ```
+
+5. Execute a busca vetorial:
+
+   ```sql
+   @scenarios/06-rag-vector-classified-docs/sql/04_test_queries.sql
+   ```
+
+Resultado esperado antes: a busca pode recuperar chunks `HR_CONFIDENTIAL`, `LEGAL_CONFIDENTIAL` e `EXECUTIVE_CONFIDENTIAL`.
+
+## Passo A Passo - Depois, Com Deep Data Security
+
+1. Aplique os data grants por classificacao:
+
+   ```sql
+   @scenarios/06-rag-vector-classified-docs/sql/03_data_grants.sql
+   ```
+
+2. Execute novamente a mesma busca vetorial:
+
+   ```sql
+   @scenarios/06-rag-vector-classified-docs/sql/04_test_queries.sql
+   ```
+
+3. Repita a demonstracao simulando `nina`, `heitor`, `sofia` e `carlos`.
+
+Resultado esperado depois:
+
+- `nina` ve apenas chunks `PUBLIC` e `INTERNAL`.
+- `heitor` ve conteudo de RH autorizado.
+- `sofia` ve conteudo juridico autorizado.
+- `carlos` ve todos os documentos por perfil executivo.
+- O LLM recebe somente contexto autorizado.
+
+## Execucao Automatizada Opcional
+
+Windows:
 
 ```powershell
 powershell -ExecutionPolicy Bypass -File .\scripts\run-scenario.ps1 -Scenario 06-rag-vector-classified-docs -ConnectString "<connect_string>"
 ```
 
+Linux/macOS:
+
+```bash
+./scripts/run-scenario.sh 06-rag-vector-classified-docs "<connect_string>"
+```
+
+## Detalhes Da Demo
+
+Veja o passo a passo completo, evidencias e referencias oficiais em [RUNBOOK.md](RUNBOOK.md).
+