agy-insights 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miguel González
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# agy-insights
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Te muestra qué contexto le estás mandando a **Antigravity** de forma repetida o innecesaria, a partir del historial que Antigravity CLI guarda en tu equipo. Tú decides qué hacer con ello.
+
+- Se ejecuta solo en tu máquina y no envía nada a ningún sitio.
+- No cambia nada: te dice qué pegar y dónde, y lo haces tú si quieres.
+- Solo propone mecanismos oficiales de Antigravity.
+- Funciona con cualquier editor, en Windows, macOS y Linux.
+
+## Por qué
+
+Cada fichero que lee el agente y cada salida de comando entra en el contexto y se reenvía en los turnos siguientes de la conversación. La cuota es una bolsa común, así que cada lectura innecesaria la gasta para todos. Esta herramienta te enseña dónde se va ese contexto: relecturas, carpetas de compilación, salidas de tests enormes y sesiones demasiado largas.
+
+## Requisitos
+
+- **Node.js 20 o superior** (`node --version`). No hace falta `npm install`.
+- Haber usado **Antigravity CLI** (`agy`) en este equipo. El historial está en `~/.gemini/antigravity-cli/conversations` (en Windows, `%USERPROFILE%\.gemini\antigravity-cli\conversations`).
+
+## Instalar
+
+No tiene dependencias. Elige una forma:
+
+**Con `npx`, sin instalar nada:**
+
+```sh
+npx agy-insights
+npx agy-insights --text
+```
+
+Para fijar una versión: `npx agy-insights@0.3.0`. En los ejemplos de abajo, cambia `node agy-insights.js` por `npx agy-insights`.
+
+**Instalándolo globalmente:**
+
+```sh
+npm install -g agy-insights
+agy-insights
+```
+
+**Clonando el repositorio:**
+
+```sh
+git clone https://github.com/migohe14/agy-insights.git
+```
+
+Para actualizar: `git pull` dentro de la carpeta. Opcional, para tener el comando `agy-insights` en cualquier carpeta: `npm install -g .` dentro de ella.
+
+## Usar
+
+```sh
+node agy-insights/agy-insights.js
+```
+
+Analiza todo tu historial, guarda un informe HTML en la carpeta temporal y lo abre en el navegador.
+
+| Para… | Ejecuta |
+|---|---|
+| Ver solo un proyecto | `node agy-insights.js --project C:\dev\mi-proyecto` |
+| Ver el proyecto de la carpeta actual | `node <ruta>/agy-insights.js --project .` |
+| Un resumen en la terminal | `node agy-insights.js --text` |
+| El resumen con rutas y exclusiones | `node agy-insights.js --text --paths` |
+| Un mapa del proyecto para pegar en `AGENTS.md` (carpetas, ficheros grandes, carpetas generadas; ~20 líneas aunque el repo sea grande) | `node agy-insights.js --map --project <carpeta>` |
+| Guardar el informe en otro sitio | `node agy-insights.js --out informe.html --no-open` |
+| Ver todas las opciones | `node agy-insights.js --help` |
+
+El informe da dos cifras:
+
+- **Consumo real**: los tokens que Antigravity anota en el registro de cada conversación (`~/.gemini/antigravity-cli/brain/<id>/.system_generated/logs/transcript.jsonl`), subagentes incluidos. Se muestra sin caché y con caché, porque no sabemos si la cuota cuenta igual la caché. Es la cifra que sirve para comparar entre compañeros.
+- **«~tokens»**: estimados a partir del tamaño guardado de cada paso. Sirven para comparar qué ficheros, carpetas o comandos pesan más, pero se quedan cortos frente al consumo real, porque cada llamada al modelo vuelve a enviar el contexto acumulado.
+
+## Leer el informe
+
+Arriba están los totales. Debajo, **Qué está pasando** reúne los hallazgos; al final, el detalle por proyecto, tipo de fichero, carpeta, fichero, herramienta y comando. El proyecto de cada fichero se detecta por su carpeta `.git`.
+
+| Hallazgo | Qué significa | Qué hacer |
+|---|---|---|
+| El agente vuelve a leer lo que ya tenía | Lee otra vez un trozo de fichero que ya estaba en la conversación | Sesiones más cortas, una por tarea, o `/compact`. No excluyas el fichero: lo necesita. |
+| Ficheros generados, compilados o de dependencias | Lecturas de `bin/`, `obj/`, `dist/`, `node_modules`, migraciones, lockfiles o logs | Si no hacían falta, exclúyelos (ver abajo) |
+| Los mismos ficheros entran en muchas sesiones | Un fichero se lee en varias conversaciones distintas | Si es código central es normal; si es grande, dile al agente qué parte mirar |
+| Comandos con salidas muy largas | La salida de tests o builds entra entera | Pide ejecutar solo el test o proyecto afectado |
+| Sesiones muy largas | Todo lo acumulado se reenvía en cada turno | Una conversación nueva por tarea |
+
+## Excluir algo
+
+Despliega **Cómo excluirlo** en una propuesta. Verás el fichero exacto, dónde va el texto y un botón **Copiar**. Hay tres opciones, de más a menos fuerte:
+
+### 1. Denegar la lectura (permiso de Antigravity)
+
+Es lo único que impide de verdad que el agente lea una ruta. Usa los [permisos oficiales](https://antigravity.google/docs/permissions).
+
+1. Abre `~/.gemini/antigravity-cli/settings.json` (en Windows, `%USERPROFILE%\.gemini\antigravity-cli\settings.json`).
+2. Pega la regla dentro de `"permissions"` → `"deny"`. Si no existen, créalas; si existen, añade la regla sin borrar nada:
+
+   ```json
+   {
+     "model": "Gemini 3.8 Flash (Medium)",
+     "permissions": {
+       "deny": [
+         "read_file(C:\\dev\\mi-proyecto\\src\\Infra\\obj)"
+       ]
+     }
+   }
+   ```
+
+3. Guarda y reinicia `agy`.
+
+Denegar la lectura de una ruta también impide escribir en ella, y la regla vale para todos tus proyectos. Úsala para carpetas que el agente no deba tocar nunca, como salidas de compilación.
+
+### 2. `.antigravityignore`
+
+Es el fichero de exclusión de Antigravity, en la raíz del proyecto. Su efecto no está documentado: está confirmado que oculta los ficheros del autocompletado con `@`, pero no que impida al agente leerlos.
+
+### 3. Regla en `AGENTS.md`
+
+Una línea en el `AGENTS.md` del proyecto, pidiendo al modelo que no lea algo o que limite una salida. Es una indicación, no un bloqueo. Las reglas se envían en cada petición y también gastan tokens, así que mantenlas cortas. `AGENTS.md` suele estar en el repositorio del equipo: revisa el cambio antes de subirlo.
+
+## Configurar
+
+Copia `agy-insights.example.json` a `~/.agy-insights.json` (o pásalo con `--config`) y ajústalo. Es tu configuración personal:
+
+| Clave | Para qué sirve | Por defecto |
+|---|---|---|
+| `conversationsDir` | Otra carpeta de historial | la de Antigravity CLI |
+| `customKinds` | Tipos de fichero propios: `{ "regex": "etiqueta" }` | ninguno |
+| `crossSessionMin` | A partir de cuántas conversaciones avisa de un fichero repetido | 3 |
+| `heavyOutputTokens` | A partir de qué tamaño medio avisa de un comando | 2000 |
+| `longSessionTokens` | A partir de qué tamaño avisa de una sesión larga | 100000 |
+
+## Privacidad
+
+- Todo se calcula en tu equipo; no se envía nada.
+- El historial se lee desde una copia temporal y nunca se modifica.
+- No escribe en `~/.gemini`, no instala hooks ni plugins y no toca tu `.gitignore` ni tus proyectos.
+- Lo único que escribe es el informe HTML, en la carpeta temporal o donde digas con `--out`.
+- El informe contiene rutas de tus proyectos. No lo compartas sin revisarlo.
+- **No compartas los ficheros `.db` del historial**: contienen el código que leyó el agente, a menudo de cliente.
+
+## Deshacer
+
+- **Permiso**: borra la línea `read_file(…)` de `"deny"` en `settings.json` y reinicia `agy`.
+- **.antigravityignore y AGENTS.md**: borra las líneas que añadiste.
+
+## Problemas frecuentes
+
+**«No hay conversaciones»**. Si usaste `--project`, puede que trabajaras con Antigravity desde otra carpeta: prueba sin `--project`. Si tampoco aparecen, comprueba que existe la carpeta del historial.
+
+**«No se reconoce el formato del historial»**. Probablemente una versión nueva de Antigravity ha cambiado cómo guarda las conversaciones. Haz `git pull`; si sigue igual, abre una incidencia en el repo.
+
+**Uso la app o el IDE de Antigravity, no el CLI**. Por ahora solo se lee el historial del CLI.
+
+**El navegador no se abre**. La ruta del informe aparece en la terminal; ábrela a mano.
+
+## Estado
+
+Versión piloto. El formato del historial de Antigravity no está documentado, así que algunos datos pueden fallar con versiones nuevas. Si ves algo raro, abre una incidencia. Para contribuir, mira [docs/como-funciona.md](docs/como-funciona.md).

package/agy-insights.example.json

@@ -0,0 +1,10 @@
+{
+  "conversationsDir": "",
+  "customKinds": {
+    "/Legacy/": "código legacy",
+    "\\.resx$": "recursos"
+  },
+  "crossSessionMin": 3,
+  "heavyOutputTokens": 2000,
+  "longSessionTokens": 100000
+}

package/agy-insights.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// agy-insights: shows which context is sent to Antigravity repeatedly or needlessly, from the local
+// Antigravity CLI history. Read-only: the only file it writes is the HTML report, in the temp folder
+// (or wherever --out says).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const { analyze, DEFAULT_DIR } = require('./lib/history');
+const { findings, DEFAULTS } = require('./lib/findings');
+const report = require('./lib/report');
+const { buildMap } = require('./lib/map');
+
+const HELP = `Uso: agy-insights [opciones]   (o npx …, o node agy-insights.js)
+
+Analiza tu historial de Antigravity CLI y abre un informe en el navegador.
+
+Opciones:
+  --project <carpeta>   Solo conversaciones que tocaron ese proyecto ("." = carpeta actual)
+  --text                Resumen en la terminal en vez del informe HTML
+  --paths               Con --text, muestra rutas y las exclusiones propuestas
+  --map                 Imprime un mapa del proyecto (--project, o la carpeta actual) para AGENTS.md
+  --out <fichero>       Dónde guardar el informe HTML (por defecto, en la carpeta temporal)
+  --no-open             No abrir el navegador
+  --dir <carpeta>       Otra carpeta de historial (por defecto ${DEFAULT_DIR})
+  --config <fichero>    Configuración (por defecto ~/.agy-insights.json si existe)
+  --help                Esta ayuda
+`;
+
+function parseArgs(argv) {
+  const opts = { open: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const value = () => {
+      if (i + 1 >= argv.length) fail(`Falta el valor de ${a}`);
+      return argv[++i];
+    };
+    if (a === '--help' || a === '-h') opts.help = true;
+    else if (a === '--project') opts.project = absolute(value());
+    else if (a === '--text') opts.text = true;
+    else if (a === '--paths') opts.paths = true;
+    else if (a === '--map') opts.map = true;
+    else if (a === '--out') opts.out = path.resolve(value());
+    else if (a === '--no-open') opts.open = false;
+    else if (a === '--dir') opts.dir = path.resolve(value());
+    else if (a === '--config') opts.config = path.resolve(value());
+    else fail(`Opción desconocida: ${a}. Usa --help.`);
+  }
+  return opts;
+}
+
+// History paths may come from Windows ("C:\..."): keep those as they are on any OS.
+const absolute = (p) => (/^[A-Za-z]:[\\/]/.test(p) ? p : path.resolve(p));
+
+function fail(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+function loadConfig(file) {
+  const target = file || path.join(os.homedir(), '.agy-insights.json');
+  if (!fs.existsSync(target)) {
+    if (file) fail(`No existe el fichero de configuración ${file}`);
+    return {};
+  }
+  try {
+    return JSON.parse(fs.readFileSync(target, 'utf8'));
+  } catch (e) {
+    return fail(`No se puede leer ${target}: ${e.message}`);
+  }
+}
+
+function openInBrowser(file) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [file]]
+    : process.platform === 'win32' ? ['cmd', ['/c', 'start', '""', file]]
+    : ['xdg-open', [file]];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true, windowsHide: true }).on('error', () => {}).unref();
+  } catch { /* the path is printed anyway */ }
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) return console.log(HELP);
+  const cfg = loadConfig(opts.config);
+
+  if (opts.map) opts.project = opts.project || process.cwd();
+  const r = await analyze({
+    dir: opts.dir || cfg.conversationsDir || DEFAULT_DIR,
+    workspaces: opts.project ? [opts.project] : [],
+    customKinds: cfg.customKinds || {},
+  });
+  if (opts.map) {
+    const m = buildMap(opts.project, { ...cfg.map, history: r.files });
+    console.log(m.block);
+    return console.error(`\n~${m.tokens} tokens en cada petición. Pégalo en ${path.join(opts.project, 'AGENTS.md')} si te convence; agy-insights no lo escribe.`);
+  }
+  const found = findings(r, {
+    crossSessionMin: cfg.crossSessionMin ?? DEFAULTS.crossSessionMin,
+    heavyOutputTokens: cfg.heavyOutputTokens ?? DEFAULTS.heavyOutputTokens,
+    longSessionTokens: cfg.longSessionTokens ?? DEFAULTS.longSessionTokens,
+  });
+
+  if (opts.text) return process.stdout.write(report.text(r, found, { scope: opts.project, paths: opts.paths }));
+
+  const stamp = new Date().toISOString().slice(0, 16).replace(/[-:T]/g, '');
+  const out = opts.out || path.join(os.tmpdir(), 'agy-insights', `informe-${stamp}.html`);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, report.html(r, found, { scope: opts.project }));
+  console.log(`${r.conversations} conversaciones analizadas, ${found.length} hallazgos.\nInforme: ${out}`);
+  if (opts.open) openInBrowser(out);
+}
+
+main().catch((e) => fail(`Error: ${e.message}`));

package/docs/como-funciona.md

@@ -0,0 +1,88 @@
+# Cómo funciona
+
+Documento para quien mantenga o amplíe agy-insights.
+
+## Principios
+
+Cualquier cambio tiene que respetarlos:
+
+1. **Solo lectura.** No se escribe en `~/.gemini` ni en los proyectos del dev. El historial se copia a una carpeta temporal antes de abrirlo, porque `agy` mantiene esas bases de datos abiertas. Lo único que se escribe es el informe.
+2. **El dev decide.** La herramienta propone texto para pegar; nunca lo aplica.
+3. **Solo mecanismos oficiales de Antigravity** para excluir: permisos (`read_file` en `permissions.deny`), `.antigravityignore` y reglas en `AGENTS.md`. Nada de hooks, plugins, `.gitignore` ni `.ignore`.
+4. **Fallar de forma visible.** Si el formato del historial cambia, el informe debe avisar en vez de mostrar datos falsos.
+5. **Sin dependencias que instalar.** Solo Node 20 o superior; SQLite va en `vendor/`.
+
+## Estructura
+
+```
+agy-insights.js       comando: opciones, configuración, escribe el informe y abre el navegador
+lib/history.js        lee el historial y agrega lecturas, comandos, proyectos y sesiones
+lib/findings.js       convierte el análisis en hallazgos (los 5 detectores)
+lib/fixes.js          construye el texto de cada exclusión; no escribe nada
+lib/report.js         informe HTML (estático, solo botones de copiar) y resumen de texto
+vendor/sql.js/        SQLite en WebAssembly (versión en VERSION, licencia MIT en LICENSE)
+test/fake-history.js  genera historiales falsos con el mismo formato que los reales
+test/*.test.js        tests (node --test)
+```
+
+## El historial de Antigravity CLI
+
+No está documentado; esto es lo que se ha observado en `agy` 1.4.x.
+
+- Una base de datos SQLite por conversación: `~/.gemini/antigravity-cli/conversations/<uuid>.db`, en modo WAL.
+- Tabla `steps`: una fila por paso. `step_payload` es un mensaje protobuf. Las llamadas a herramientas guardan el nombre (`view_file`, `run_command`, `grep_search`…) seguido de sus argumentos en JSON, por ejemplo `{"AbsolutePath":"C:\\dev\\...\\X.cs","StartLine":301,"EndLine":380}`, precedido por un id `call_NNN`.
+- Cada llamada ocupa dos pasos con el mismo id: el de la respuesta del modelo que la pide (`step_type` 15) y el del resultado (`step_type` 132), que repite nombre y argumentos y añade el contenido del fichero o la salida del comando. `lib/history.js` cuenta la llamada una vez por id y suma el tamaño de ambos pasos, que aproxima lo que entró en el contexto.
+- Tabla `gen_metadata`: configuración de cada llamada al modelo, incluido el nombre del modelo.
+- Junto al historial, `../brain/<id>/.system_generated/logs/transcript.jsonl`: una línea JSON por paso. Las de tipo `PLANNER_RESPONSE` son llamadas al modelo y traen `input_tokens`, `cache_read_tokens` y `output_tokens`; los pasos fallidos tienen `status: "ERROR"`. Los subagentes tienen su propia conversación y su propio transcript. `realUsage()` en `lib/history.js` suma esas cifras (solo lee el fichero). El total que imprime `agy -p --output-format json` no incluye los subagentes; este sí.
+
+`lib/history.js` no depende de un esquema protobuf. Recorre el mensaje, recoge todas las cadenas, y considera llamada a herramienta cualquier JSON precedido (a menos de 3 cadenas) por un nombre en `snake_case`. Así aguanta cambios menores de formato. Si hay más de 50 pasos y ninguna llamada reconocida, marca `formatUnrecognized` y el informe lo avisa.
+
+### SQLite
+
+- Con Node 22.13 o superior se usa `node:sqlite`, que lee también el fichero `-wal`.
+- Con versiones anteriores se usa `sql.js` desde `vendor/`. No lee el `-wal`, así que pueden faltar los últimos pasos de una conversación abierta.
+
+Para actualizar `sql.js`: copia `dist/sql-wasm.js`, `dist/sql-wasm.wasm` y `LICENSE` de la nueva versión del paquete npm y actualiza `VERSION`.
+
+### Proyectos
+
+El proyecto de cada fichero se detecta subiendo por su ruta hasta encontrar una carpeta con `.git`, si la ruta existe en la máquina. Con `--project` se usa esa carpeta directamente. Las rutas de Windows (`C:\...`) se normalizan a `/` internamente y se devuelven con `\` en las exclusiones, porque `agy` compara las rutas de los permisos literalmente.
+
+## Añadir un tipo de fichero
+
+En `lib/history.js`, función `kind()`. Si es un tipo que casi nunca hace falta leer, añádelo también a `NON_SOURCE`, y sus patrones de `.antigravityignore` a `KIND_PATTERNS` en `lib/findings.js`. Cada dev puede añadir tipos propios sin tocar el código con `customKinds` en su configuración.
+
+## Añadir un detector
+
+En `lib/findings.js`. Un hallazgo es `{ id, level: 'info' | 'warn', title, why, suggestion, tokens, items }`, y cada `item` es `{ label, tokens, detail, fixes }`. Las `fixes` se crean con `lib/fixes.js`. No propongas excluir código fuente: el agente lo necesita.
+
+Añade un caso en `test/fake-history.js` y un test.
+
+## Tests
+
+```sh
+npm test
+```
+
+Prueban el análisis con un historial falso, los cinco detectores, el formato de las reglas, que nunca se propone excluir código fuente, que el historial no cambia, la detección de proyectos por `.git`, el aviso de formato desconocido, el escapado del HTML y el comando completo. Se ejecutan en CI con Node 20 (sql.js) y Node 22 (node:sqlite).
+
+Para generar un historial de ejemplo y probar el informe a mano:
+
+```sh
+node test/fake-history.js test/tmp/history
+node agy-insights.js --dir test/tmp/history
+```
+
+## Paquete npm
+
+`package.json` define el comando (`bin`) y qué ficheros entran en el paquete (`files`: el comando, `lib/`, `vendor/`, `docs/` y el ejemplo de configuración; los tests no). Se publica en el registro público de npm como `agy-insights`. El paquete solo contiene la herramienta; los historiales que analiza se quedan en la máquina de cada usuario.
+
+- **Probar el paquete en local**: `npm pack` y después `npx --yes --package=./agy-insights-<versión>.tgz agy-insights --help`.
+- **Desde el repositorio**, sin publicar: `npx --yes github:migohe14/agy-insights`. Al no tener dependencias ni paso de build, npm lo instala directamente desde git.
+- **Publicar una versión**: `npm version <patch|minor|major>` (actualiza `package.json` y crea la etiqueta `v…`) y `git push --follow-tags`. El workflow `.github/workflows/publish.yml` pasa los tests y ejecuta `npm publish --provenance`. Necesita el secreto `NPM_TOKEN` en el repositorio de GitHub (un token de npm de tipo *Automation* o *Granular* con permiso de publicación).
+
+## Pendiente
+
+- Confirmar con `agy` que una regla `deny` de `read_file` impide la lectura.
+- Probar con historiales reales de varios devs (Windows y macOS).
+- Leer también el historial de la app y del IDE de Antigravity, si guardan el mismo formato.

package/lib/findings.js

@@ -0,0 +1,147 @@
+// Turns an analysis report into findings: what context is being sent repeatedly or needlessly, why it
+// matters, and which official Antigravity mechanism could address it. Findings only describe and propose
+// (see fixes.js); applying anything is always the developer's decision.
+const fixes = require('./fixes');
+
+const DEFAULTS = { crossSessionMin: 3, heavyOutputTokens: 2000, longSessionTokens: 100000 };
+
+// Suggested .antigravityignore patterns for the built-in non-source types.
+const KIND_PATTERNS = {
+  'node_modules': ['node_modules/'],
+  'build output (dist, bin, obj…)': ['bin/', 'obj/', 'dist/', 'build/', 'out/', 'target/', 'coverage/'],
+  'lockfiles': ['*.lock', 'package-lock.json', 'pnpm-lock.yaml', 'packages.lock.json'],
+  'logs, maps, minificados': ['*.log', '*.map', '*.min.js', '*.min.css'],
+  'código generado / migraciones': ['*.designer.cs', '*.g.cs', 'Migrations/'],
+};
+
+const sum = (xs, f) => xs.reduce((s, x) => s + f(x), 0);
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`;
+const where = (x) => (x.project ? `${x.project} › ${x.rel}` : x.abs);
+
+function findings(r, opts = {}) {
+  const t = { ...DEFAULTS, ...opts };
+  const nonSourceKinds = new Set(r.kinds.filter((k) => k.nonSource).map((k) => k.key));
+  const out = [];
+
+  if (r.formatUnrecognized) {
+    out.push({
+      id: 'format', level: 'warn', title: 'No se reconoce el formato del historial',
+      why: `Hay ${r.steps} pasos pero ninguna llamada a herramienta reconocible. Probablemente agy ha cambiado cómo guarda las conversaciones.`,
+      suggestion: 'Los resultados de abajo no son fiables. Actualiza agy-insights (git pull) o abre una incidencia en el repo.',
+      items: [],
+    });
+  }
+
+  // 1. Same chunk read again within a session: the content is paid twice. The file itself is usually needed.
+  const reread = r.files.filter((f) => f.rereads > 0).sort((a, b) => b.rereadTokens - a.rereadTokens);
+  if (reread.length) {
+    out.push({
+      id: 'rereads', level: 'info', title: 'El agente vuelve a leer lo que ya tenía',
+      tokens: r.rereadTokens,
+      why: `${plural(r.rereads, 'lectura repite', 'lecturas repiten')} un trozo que ya se había leído en la misma sesión. Ese contenido entra dos veces en el contexto.`,
+      suggestion: 'Suele pasar en sesiones largas o después de editar. Sesiones más cortas por tarea, o /compact, lo reducen. No conviene excluir estos ficheros: el agente los necesita.',
+      items: reread.slice(0, 10).map((f) => ({ label: where(f), tokens: f.rereadTokens, detail: plural(f.rereads, 'relectura', 'relecturas'), fixes: [] })),
+    });
+  }
+
+  // 2. Generated, build output, vendor, lockfiles and logs: rarely needed, and candidates for exclusion.
+  const nonSource = r.files.filter((f) => nonSourceKinds.has(f.kind));
+  if (nonSource.length) {
+    const byFolder = new Map();
+    for (const f of nonSource) {
+      const abs = f.abs.slice(0, f.abs.lastIndexOf('/'));
+      const e = byFolder.get(abs) || { abs, rel: f.rel.slice(0, f.rel.lastIndexOf('/')), root: f.root, project: f.project, kind: f.kind, tokens: 0, calls: 0 };
+      e.tokens += f.tokens;
+      e.calls += f.calls;
+      byFolder.set(abs, e);
+    }
+    const items = [...byFolder.values()].sort((a, b) => b.tokens - a.tokens).slice(0, 10).map((e) => ({
+      label: `${where(e)}/`, tokens: e.tokens, detail: `${e.kind} · ${plural(e.calls, 'lectura', 'lecturas')}`,
+      fixes: [
+        fixes.deny(e.abs),
+        e.root && fixes.ignore(e.root, [`${e.rel}/`]),
+        e.root && fixes.rule(e.root, `No leas \`${e.rel}/\`: es ${e.kind}; trabaja con el código fuente.`),
+      ].filter(Boolean),
+    }));
+    // One pattern-based item per project and type, for folders that have not been read yet.
+    const perProject = new Map();
+    for (const f of nonSource) {
+      if (!f.root || !KIND_PATTERNS[f.kind]) continue;
+      const k = `${f.root}|${f.kind}`;
+      const e = perProject.get(k) || { root: f.root, project: f.project, kind: f.kind, tokens: 0 };
+      e.tokens += f.tokens;
+      perProject.set(k, e);
+    }
+    for (const e of perProject.values()) {
+      items.push({
+        label: `${e.project} › todo lo de tipo «${e.kind}»`, tokens: e.tokens, detail: 'patrón para cualquier carpeta del proyecto',
+        fixes: [
+          fixes.ignore(e.root, KIND_PATTERNS[e.kind]),
+          fixes.rule(e.root, `No leas ${e.kind} (${KIND_PATTERNS[e.kind].join(', ')}) salvo que la tarea lo pida.`),
+        ],
+      });
+    }
+    out.push({
+      id: 'non-source', level: 'warn', title: 'Se leen ficheros generados, compilados o de dependencias',
+      tokens: sum(nonSource, (f) => f.tokens),
+      why: 'Salidas de build, código generado, dependencias, lockfiles y logs casi nunca hacen falta para entender o cambiar el código, y suelen ser grandes.',
+      suggestion: 'Revisa si alguna de estas lecturas era necesaria. Si no, puedes impedirlas con un permiso de Antigravity.',
+      items,
+    });
+  }
+
+  // 3. Same file entering many different sessions: repeated context across conversations.
+  const cross = r.files.filter((f) => f.convs >= t.crossSessionMin).sort((a, b) => b.tokens - a.tokens);
+  if (cross.length) {
+    out.push({
+      id: 'cross-session', level: 'info', title: 'Los mismos ficheros entran en muchas sesiones',
+      tokens: sum(cross, (f) => f.tokens),
+      why: `${plural(cross.length, 'fichero se ha leído', 'ficheros se han leído')} en ${t.crossSessionMin} o más conversaciones distintas.`,
+      suggestion: 'Si son el núcleo del proyecto es normal. Si son grandes y el agente solo necesita una parte, decirle qué trozo mirar ahorra lecturas.',
+      // Exclusion is only offered for non-source files: denying core source code would break the agent's work.
+      items: cross.slice(0, 10).map((f) => ({
+        label: where(f), tokens: f.tokens, detail: `${plural(f.convs, 'sesión', 'sesiones')} · ${plural(f.calls, 'lectura', 'lecturas')}`,
+        fixes: nonSourceKinds.has(f.kind) ? [fixes.deny(f.abs), f.root && fixes.ignore(f.root, [f.rel])].filter(Boolean) : [],
+      })),
+    });
+  }
+
+  // 4. Commands whose output is large every time (test suites, builds).
+  const heavy = r.commands.filter((c) => c.tokens / c.calls >= t.heavyOutputTokens).sort((a, b) => b.tokens - a.tokens);
+  if (heavy.length) {
+    out.push({
+      id: 'heavy-commands', level: 'warn', title: 'Comandos con salidas muy largas',
+      tokens: sum(heavy, (c) => c.tokens),
+      why: 'La salida completa de cada comando entra en el contexto y se reenvía en los turnos siguientes.',
+      suggestion: 'Pide ejecutar solo lo necesario (un test concreto, un proyecto concreto) o filtrar la salida. Si pasa siempre, una regla en el AGENTS.md del proyecto lo recuerda en cada sesión.',
+      items: heavy.slice(0, 8).map((c) => ({
+        label: c.key, tokens: c.tokens, detail: `${plural(c.calls, 'vez', 'veces')} · ~${Math.round(c.tokens / c.calls).toLocaleString('es-ES')} tokens cada una`,
+        example: `- Al ejecutar \`${c.key}\`, limita la salida: solo el test o proyecto afectado, o filtra las líneas relevantes.`,
+        fixes: [],
+      })),
+    });
+  }
+
+  // 5. Very long sessions: everything accumulated is resent on every turn.
+  // Real usage when agy's transcript has it (it includes everything resent on each call), else the estimate.
+  const size = (s) => (s.usage ? s.usage.input + s.usage.output : s.tokens);
+  const long = r.sessions.filter((s) => size(s) >= t.longSessionTokens);
+  if (long.length) {
+    out.push({
+      id: 'long-sessions', level: 'info', title: 'Sesiones muy largas',
+      tokens: sum(long, (s) => s.tokens),
+      why: `${plural(long.length, 'conversación supera', 'conversaciones superan')} ${t.longSessionTokens.toLocaleString('es-ES')} tokens. En una sesión larga, todo lo acumulado se vuelve a enviar en cada turno.`,
+      suggestion: 'Una conversación nueva por tarea, o /compact cuando cambias de tema.',
+      items: long.slice(0, 5).map((s) => ({
+        label: `conversación ${s.id.slice(0, 8)}`, tokens: s.tokens, fixes: [],
+        detail: plural(s.steps, 'paso', 'pasos') + (s.usage
+          ? ` · ${s.usage.calls} llamadas al modelo, ${(s.usage.input + s.usage.output).toLocaleString('es-ES')} tokens reales (${(s.usage.input + s.usage.cache + s.usage.output).toLocaleString('es-ES')} con caché)`
+          : ''),
+      })),
+    });
+  }
+
+  return out;
+}
+
+module.exports = { findings, DEFAULTS };

package/lib/fixes.js

@@ -0,0 +1,64 @@
+// Ready-to-paste exclusions using only official Antigravity mechanisms. This module never writes
+// anything: it builds the exact text and says which file it goes in. Applying it is the developer's call.
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const AGY_SETTINGS = path.join(os.homedir(), '.gemini', 'antigravity-cli', 'settings.json');
+
+// Paths as the developer's OS writes them (agy matches permission paths literally).
+const native = (p) => (/^[A-Za-z]:\//.test(p) ? p.replace(/\//g, '\\') : p);
+
+let denied = null;
+function deniedRules() {
+  if (!denied) {
+    try { denied = JSON.parse(fs.readFileSync(AGY_SETTINGS, 'utf8')).permissions?.deny || []; } catch { denied = []; }
+  }
+  return denied;
+}
+
+// Permission rule (https://antigravity.google/docs/permissions): deny > ask > allow, a denied read_file
+// path covers everything below it, and denying a read also denies writes there.
+function deny(absPath) {
+  const rule = `read_file(${native(absPath)})`;
+  return {
+    how: 'deny', title: 'Denegar la lectura (permiso de Antigravity)',
+    file: AGY_SETTINGS, where: 'dentro de "permissions" → "deny"',
+    text: JSON.stringify(rule),
+    note: 'Es lo único que impide la lectura. Afecta a todos tus proyectos, también impide escribir en esa ruta, y hay que reiniciar agy.',
+    applied: deniedRules().includes(rule),
+  };
+}
+
+// .antigravityignore: Antigravity's own exclusion file. Its scope is undocumented; it is confirmed to hide
+// files from @ completion, not to stop the agent from reading them.
+function ignore(root, patterns) {
+  const file = path.join(native(root), '.antigravityignore');
+  let current = [];
+  try { current = fs.readFileSync(file, 'utf8').split(/\r?\n/).map((l) => l.trim()); } catch { /* not there yet */ }
+  const missing = patterns.filter((p) => !current.includes(p));
+  return {
+    how: 'ignore', title: 'Añadir a .antigravityignore',
+    file, where: 'al final del fichero (créalo si no existe)',
+    text: missing.join('\n'),
+    note: 'Lo oculta del autocompletado con @; no está documentado que impida leerlo.',
+    applied: missing.length === 0,
+  };
+}
+
+// AGENTS.md rule: a request to the model, sent with every request (it costs tokens too).
+function rule(root, text) {
+  const file = path.join(native(root), 'AGENTS.md');
+  const line = `- ${text}`;
+  let present = false;
+  try { present = fs.readFileSync(file, 'utf8').split(/\r?\n/).some((l) => l.trim() === line); } catch { /* none */ }
+  return {
+    how: 'rule', title: 'Añadir una regla a AGENTS.md',
+    file, where: 'al final del fichero',
+    text: line,
+    note: 'Es una indicación al modelo, no un bloqueo. Se envía en cada petición: mantenla corta. AGENTS.md suele estar en el repo del equipo.',
+    applied: present,
+  };
+}
+
+module.exports = { AGY_SETTINGS, native, deny, ignore, rule };