Trace de request

O jeito mais claro de ver como os oito arquivos interagem é traçar uma única pergunta pelos dois pontos de entrada.

Trace de pergunta na CLI

CLI question
  → cli.ts            (parse argv, instantiate LocalLensApp)
  → locallens.ts      (createBrainFromFolder)
  →   files.ts        (discoverTextDocuments)
  →   rag.ts          (chunkDocuments → ragChunk)
  →   qvac.ts         (ingestChunks → ragIngest)
  →   store.ts        (saveBrain, saveChunks)
  → locallens.ts      (askBrain)
  →   qvac.ts         (search → ragSearch)
  →   rag.ts          (buildGroundedHistory)
  →   qvac.ts         (answer → completion stream)
  → locallens.ts      (assemble ChatAnswer)
  → cli.ts            (print answer + sources, deleteBrain, close)

Duas coisas para notar:

• O trace abre em leque para fora de locallens.ts para os gateways e volta. Toda chamada interno-para-interno roteia pela classe de workflow.
• domain.ts não aparece no trace. Isso é por design. Tipos não participam do runtime — só restringem ele.

Trace de pergunta no navegador

Browser question
  → ui/app.js         (event handler, fetch POST /api/brains/:id/chat)
  → server.ts         (route match, JSON parse)
  → locallens.ts      (askBrain)
  →   qvac.ts         (search)
  →   rag.ts          (buildGroundedHistory)
  →   qvac.ts         (answer)
  → locallens.ts      (assemble ChatAnswer)
  → server.ts         (JSON serialize, write response)
  → ui/app.js         (render markdown, append to chat thread)

O trace do navegador é o trace da CLI mais um hop HTTP em cada ponta. Quando o request chega em locallens.ts, o caminho é idêntico ao caminho da CLI.

Por que esse formato importa

Três propriedades caem de uma classe de workflow com pontos de entrada finos:

1. Um lugar para adicionar uma feature. LocalLensApp.askBrain é o único método de responder-a-pergunta. A CLI e o navegador beneficiam ambos no momento em que você adiciona algo.
2. Superfície de erro estável. Erros fluem para cima por LocalLensApp, chegam em cli.ts ou server.ts como AppError ou Error genérico, e são formatados por um helper na borda.
3. Fácil de testar. LocalLensApp pode ser unit-testado sem subir um servidor ou shell. O store troca por uma variante de diretório temp; o gateway QVAC pode ser stubbed.

Onde quebraria

Se uma feature precisasse de um workflow diferente no caminho do navegador do que no caminho da CLI, a simetria racharia. O movimento certo então é adicionar um método novo no LocalLensApp (ou um helper novo que consome ele), não empurrar lógica para server.ts. Mantém os pontos de entrada finos.