Trace del request

La forma más clara de ver cómo interactúan los ocho archivos es tracear una sola pregunta por ambos puntos de entrada.

Trace de pregunta por la 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)

Dos cosas para notar:

• El trace se abre hacia afuera desde locallens.ts hacia los gateways y vuelve. Cada llamada interna a interna pasa por la clase del workflow.
• domain.ts no aparece en el trace. Eso es por diseño. Los tipos no participan en el runtime — solo lo restringen.

Trace de pregunta por el 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)

El trace del navegador es el trace de la CLI más un salto HTTP en cada extremo. Una vez que el request llega a locallens.ts, el camino es idéntico al de la CLI.

Por qué esta forma importa

Tres propiedades caen de tener una clase de workflow con puntos de entrada delgados:

1. Un solo lugar para agregar una feature. LocalLensApp.askBrain es el único método de responder-la-pregunta. La CLI y el navegador se benefician en el momento en que le agregas algo.
2. Superficie de errores estable. Los errores fluyen hacia arriba a través de LocalLensApp, llegan a cli.ts o server.ts como AppError o Error genérico, y los formatea un solo helper en el borde.
3. Fácil de testear. LocalLensApp se puede testear unitario sin levantar un servidor o un shell. El store se cambia por una variante de directorio temporal; el gateway de QVAC se puede stubbear.

Dónde se rompería

Si una feature necesitara un workflow distinto en el camino del navegador que en el camino de la CLI, la simetría se quebraría. La movida correcta en ese caso es agregar un método nuevo a LocalLensApp (o un helper nuevo que lo consuma), no empujar lógica a server.ts. Mantén los puntos de entrada delgados.