Runbook — Screener

agente screener runbook

Manual passo a passo para Pedro Villa e Rafael Rossetto rodarem o Screener no OneDrive da Colliers, do zero, usando Claude Code no terminal. Sem dependência de servidor remoto. Sem dependência de API.

Este documento existe para que qualquer um dos dois consiga:

Preparar o ambiente local
Sincronizar o OneDrive da Colliers
Rodar uma varredura completa
Curar os relatórios e levá-los para o Obsidian
Aprofundar pastas selecionadas para o dicionário de dados

Tudo no terminal. Tudo read-only sobre o OneDrive.

0. Pré-requisitos uma vez por máquina

0.1. Conta e acesso

conta corporativa Anouk com acesso liberado pelo Michael (TI Colliers) ao OneDrive da Colliers
cliente OneDrive instalado: macOS via App Store ou Windows nativo
pasta da Colliers sincronizada no Finder/Explorer (passo 1 abaixo)

0.2. Software local

Ferramenta	Versão mínima	Para que serve
Python 3	3.10	Rodar `inventory.py` e `render_md.py`
`pip`	atualizado	Instalar dependências opcionais
Claude Code	atual	Orquestrar a varredura via agente
Git	atualizado	(já é requisito do projeto)

Verificar:

python3 --version
pip3 --version
claude --version

0.3. Dependências Python (opcionais e de baixo risco)

O Screener funciona com a stdlib pura no modo padrão. Para conforto e para o modo data-dictionary-prep:

pip3 install --user pyyaml openpyxl python-pptx python-docx pypdf

Pacote	Por que
`pyyaml`	Parser do `manifest.yaml`. Sem ele, o Screener cai num parser-lite que cobre o manifest do projeto.
`openpyxl`	Headers-only de XLSX (apenas em `data-dictionary-prep`).
`python-pptx`	Títulos de slides em `data-dictionary-prep`.
`python-docx`	Headings em `data-dictionary-prep`.
`pypdf`	Bookmarks em `data-dictionary-prep`.

No modo padrão (folder-inventory), nenhum desses é necessário.

0.4. xattr no macOS (opcional)

Para detecção fina de placeholders no macOS:

pip3 install --user xattr

Sem xattr, o script ainda detecta placeholders via st_flags (UF_DATALESS). O xattr apenas adiciona um sinal extra.

1. Sincronizar a pasta da Colliers no OneDrive

macOS

Abrir o app OneDrive (logado com a conta Anouk).
Em Settings → Account, verificar que a conta da Colliers está conectada.
Em Sync and Backup → Manage Backup / Choose Folders, marcar a(s) pasta(s) raiz da Colliers que o Michael liberou.
No Finder, navegar até ~/Library/CloudStorage/OneDrive-Colliers/.
Clicar com o botão direito na pasta-raiz da Colliers → Make Available Offline / Always Keep on This Device se quiser baixar tudo. Não é obrigatório. O Screener consegue inventariar arquivos cloud-only sem baixá-los.
Aguardar a indicação de sync inicial. Em pastas grandes, isso pode levar minutos a horas.

Caminho típico macOS:

/Users/<user>/Library/CloudStorage/OneDrive-Colliers/<Compartilhado-da-Colliers>

Windows

Abrir o app OneDrive.
Em Settings → Account, conectar a conta da Anouk com acesso à Colliers.
Em Choose folders, marcar as pastas autorizadas.
No Explorer, navegar até C:\Users\<user>\OneDrive - Colliers\.

Caminho típico Windows:

C:\Users\<user>\OneDrive - Colliers\<Compartilhado-da-Colliers>

Atenção: caminhos com OneDrive - Colliers (com espaço e hífen) são válidos. Sempre passar entre aspas duplas no terminal.

2. Abrir o projeto no Claude Code

cd "/Users/<user>/Library/CloudStorage/GoogleDrive-pedro.villa@anoukpartners.com/Meu Drive/Colliers_Projeto"
claude

Quando o Claude Code abrir, peça ao agente Screener:

Carregue o agente Screener (agentes-core/screener/system-prompt.md + skill folder-inventory). Vou rodar uma varredura no OneDrive da Colliers.

O Claude Code lê o system-prompt, a skill, os guardrails. A partir desse ponto, ele atua como o Screener — segue o checklist pré-scan, pergunta o caminho-raiz, etc.

3. Preparar a sessão de varredura

3.1. Criar diretório de execução

DATA=$(date +%Y-%m-%d)
ROOT_SLUG="onedrive-colliers"
OUT_DIR="agentes-core/screener/outputs/${DATA}_${ROOT_SLUG}"
mkdir -p "$OUT_DIR"

3.2. Copiar e ajustar o manifest

cp agentes-core/screener/scripts/manifest.example.yaml "$OUT_DIR/manifest.yaml"

Editar "$OUT_DIR/manifest.yaml":

operator: colocar pedro ou rafael
root: colocar o caminho absoluto da pasta-raiz no OneDrive sincronizado; em frontmatter Markdown, usar aspas simples para caminhos Windows (root: 'C:\Users\...')
max_depth: deixar null (default), ou 4 se quiser uma 1ª passada mais leve
exclude: adicionar padrões locais se houver pastas técnicas a ignorar
allow_sensitive: deixar [] na primeira execução

4. Primeira passada: árvore só (rápida, segura)

Esta passada serve para descobrir quantas pastas existem, quão profunda é a árvore, e quais pastas têm nome com sinal de sensibilidade — antes de varrer arquivos.

python3 agentes-core/screener/scripts/inventory.py \
  --tree-only \
  --root "/Users/<user>/Library/CloudStorage/OneDrive-Colliers/<raiz-colliers>" \
  --manifest "$OUT_DIR/manifest.yaml" \
  --max-depth 4 \
  --out "$OUT_DIR/tree.json"

O script imprime no stderr:

[screener] dirs=NN files=0 bytes=0 cloud_only=0 errors=N duration=N.Ns

Pedir ao Claude Code (Screener):

Abra tree.json e me mostre as pastas com sensitive_flag = true. Quero decidir caso a caso o que varrer.

Para cada pasta sensível, decidir:

pular: deixa fora do manifest.yaml. Default.
varrer-com-restricao: adicionar à lista allow_sensitive no manifest e registrar a justificativa em 05_anomalias.md depois.

5. Varredura completa

python3 agentes-core/screener/scripts/inventory.py \
  --root "/Users/<user>/Library/CloudStorage/OneDrive-Colliers/<raiz-colliers>" \
  --manifest "$OUT_DIR/manifest.yaml" \
  --out "$OUT_DIR/inventory.json"

Para liberar pastas sensíveis específicas, adicionar --allow-sensitive repetidamente:

python3 ... \
  --allow-sensitive "Diretoria/Projetos publicos" \
  --allow-sensitive "Juridico/Modelos contratos"

O script:

imprime progresso a cada 5000 arquivos
escreve inventory.json (cru) e inventory.csv (analisável)
nunca abre conteúdo de arquivo
nunca escreve no OneDrive

Tempo esperado para 100k arquivos: ~3 a 8 minutos em SSD local. Mais lento se o OneDrive ainda estiver baixando metadata.

6. Renderizar os relatórios .md

python3 agentes-core/screener/scripts/render_md.py \
  --inventory "$OUT_DIR/inventory.json" \
  --out-dir "$OUT_DIR"

Resultado:

$OUT_DIR/
├── 00_sumario.md
├── 01_estrutura.md
├── 02_formatos.md
├── 03_areas/
│   ├── <area-1>.md
│   ├── <area-2>.md
│   └── ...
├── 04_candidatos-dicionario.md
├── 05_anomalias.md
├── 06_glossario-observado.md
├── inventory.json
├── inventory.csv
└── manifest.yaml

7. Curadoria com o Claude Code

Voltar ao Claude Code (Screener carregado) e pedir:

Leia 00_sumario.md, 02_formatos.md e os arquivos em 03_areas/. Preencha a seção “Leitura do Screener” do sumário com:

3 a 7 hipóteses sobre como o OneDrive está organizado, com 3+ exemplos cada como evidência

5 a 10 perguntas para a Colliers

top 5 candidatos a fonte do dicionário de dados, justificando cada um em 1 linha

O Screener relê os relatórios e edita 00_sumario.md direto. Cada inferência fica marcada como hipótese.

Em seguida:

Para cada área em 03_areas/, escreva 1 a 3 hipóteses de uso na seção “Hipóteses de uso”, com arquivos como evidência. Marque tudo como hipótese.

8. Pós-scan: levar para o Obsidian e registrar

8.1. Copiar a versão curada para o vault

DEST="04-referencia/colliers/onedrive-inventario/${DATA}"
mkdir -p "$DEST"
cp "$OUT_DIR/00_sumario.md" "$DEST/"
cp "$OUT_DIR/01_estrutura.md" "$DEST/"
cp "$OUT_DIR/02_formatos.md" "$DEST/"
cp -R "$OUT_DIR/03_areas" "$DEST/"
cp "$OUT_DIR/04_candidatos-dicionario.md" "$DEST/"
cp "$OUT_DIR/06_glossario-observado.md" "$DEST/"

O inventory.csv, inventory.json e 05_anomalias.md ficam apenas em agentes-core/screener/outputs/. Não publicam no Quartz.

8.2. Atualizar a memória do Screener

Pedir ao Claude Code:

Atualize agentes-core/screener/memory/context/conhecimento-onedrive-colliers.md com aprendizados estruturais desta varredura: padrões de pasta, convenções de nomenclatura, áreas com mais volume. Sem conteúdo de arquivos. Sem dados sensíveis.

8.3. Registrar a sessão

SESSION="agentes-core/screener/memory/sessions/${DATA}.md"
cat > "$SESSION" <<EOF
---
title: Sessão Screener — ${DATA}
operator: pedro
root: '<colocar caminho>'
duration: <ler de inventory.json summary>
---
 
# Sessão ${DATA}
 
## Decisões
- 
 
## Sensíveis liberadas
- 
 
## Próximos passos
- 
EOF

9. Modo data-dictionary-prep (opcional, segunda fase)

Só rodar depois que a varredura básica estiver curada e o time tiver decidido quais pastas merecem virar fonte de dicionário.

9.1. Autorizar a pasta

Editar manifest.yaml:

dictionary_prep_allowed:
  - "CTS/Avaliacoes/CIVAS/Bases consolidadas"
  - "CIB/Industrial/Dashboards"

9.2. Pedir ao Screener

Carregue a skill data-dictionary-prep. Quero abrir cabeçalhos das XLSX em “CTS/Avaliacoes/CIVAS/Bases consolidadas”. Estimativa de tempo e contagem de arquivos antes de prosseguir.

O Screener responde com:

número de arquivos a abrir
estimativa de tempo
pedido de confirmação literal: digite "abrir headers de CTS/Avaliacoes/CIVAS/Bases consolidadas" para confirmar

Você confirma a frase exata.

O Screener gera 04_candidatos-dicionario/<arquivo>.md, faz os greps anti-leak, e atualiza 04_candidatos-dicionario.md com ranking.

10. Re-execução periódica (diff)

Para ver o que mudou desde a última varredura:

PREV="agentes-core/screener/outputs/<data-anterior>_onedrive-colliers/inventory.json"
CURR="$OUT_DIR/inventory.json"
 
python3 agentes-core/screener/scripts/inventory.py \
  --diff "$PREV" "$CURR" \
  --out "$OUT_DIR/diff.md"

Saída: lista de arquivos adicionados, removidos e alterados (size ou mtime).

11. Checklist condensado

Cola e cola no terminal. Substituir <user> e <raiz>.

# 0) variáveis
DATA=$(date +%Y-%m-%d)
PROJ="/Users/<user>/Library/CloudStorage/GoogleDrive-pedro.villa@anoukpartners.com/Meu Drive/Colliers_Projeto"
ROOT="/Users/<user>/Library/CloudStorage/OneDrive-Colliers/<raiz-colliers>"
OUT_DIR="$PROJ/agentes-core/screener/outputs/${DATA}_onedrive-colliers"
 
# 1) preparar
cd "$PROJ"
mkdir -p "$OUT_DIR"
cp agentes-core/screener/scripts/manifest.example.yaml "$OUT_DIR/manifest.yaml"
$EDITOR "$OUT_DIR/manifest.yaml"   # ajustar root, operator
 
# 2) tree only
python3 agentes-core/screener/scripts/inventory.py \
  --tree-only --root "$ROOT" --manifest "$OUT_DIR/manifest.yaml" \
  --max-depth 4 --out "$OUT_DIR/tree.json"
 
# 3) revisar pastas sensíveis no Claude Code (Screener)
 
# 4) varredura completa
python3 agentes-core/screener/scripts/inventory.py \
  --root "$ROOT" --manifest "$OUT_DIR/manifest.yaml" \
  --out "$OUT_DIR/inventory.json"
 
# 5) renderizar md
python3 agentes-core/screener/scripts/render_md.py \
  --inventory "$OUT_DIR/inventory.json" --out-dir "$OUT_DIR"
 
# 6) curadoria com o Screener no Claude Code
 
# 7) publicar no vault
DEST="$PROJ/04-referencia/colliers/onedrive-inventario/${DATA}"
mkdir -p "$DEST"
cp "$OUT_DIR"/00_sumario.md "$OUT_DIR"/01_estrutura.md "$OUT_DIR"/02_formatos.md "$OUT_DIR"/04_candidatos-dicionario.md "$OUT_DIR"/06_glossario-observado.md "$DEST/"
cp -R "$OUT_DIR/03_areas" "$DEST/"

12. Falhas comuns e como resolver

Sintoma	Causa provável	Como resolver
`inventory.json` com 0 arquivos	OneDrive não terminou sync inicial	Aguardar o cliente OneDrive indicar “All files up to date”
Muitos `cloud_only: true`	Pasta nunca foi baixada	OK para o inventário; se quiser análise mais funda, “Always keep on this device” no Finder
`OSError: name too long`	Caminho com >255 caracteres	Pular a pasta no manifest; relatar à TI Colliers
`inventory.json` >100MB	Pasta-raiz gigante	Rodar com `--max-depth 5` primeiro, depois aprofundar pasta a pasta
Caracteres acentuados aparecendo errados	Terminal sem UTF-8	`export LANG=pt_BR.UTF-8` ou `en_US.UTF-8`
`Permission denied` no Windows	OneDrive segurando lock	Fechar Excel/Word/PowerPoint abertos. Se persistir, reiniciar o cliente OneDrive
Script abortou no meio	Erro inesperado	Última saída do stderr está em `OUT_DIR/manifest.lock.yaml`. Erros já gravados em `inventory.json["summary"]["errors"]`. Re-rodar é seguro (idempotente)

13. O que NUNCA fazer

Não rodar o Screener fora da pasta-raiz autorizada
Não passar --allow-sensitive sem registrar a justificativa em 05_anomalias.md
Não abrir arquivos da Colliers manualmente para “ajudar” o Screener — modo dictionary-prep faz isso de forma controlada
Não copiar inventory.csv para fora do projeto Anouk sem decisão de Pedro
Não publicar inventory.csv no Quartz
Não rodar a skill data-dictionary-prep em pasta sensível, mesmo que tenha sido liberada para inventário

14. Quando pedir ajuda

Situação	Para quem
Acesso ao OneDrive não funciona	Michael (TI Colliers)
Sync OneDrive trava	Suporte interno Anouk
Dúvida sobre o que liberar/não liberar	Pedro
Script falha de forma reprodutível	Pedro (criar issue em `agentes-core/screener/memory/context/lessons.md`)
Risco de privacidade detectado	Pedro imediatamente

Colliers × Costal — Interno

Explorador

runbook