alegra-data-agent 0.7.0 → 0.7.1

package/README.md

@@ -1,21 +1,445 @@
-# alegra-data-agent
+# Data Agent Self Service
 
-Agente de Data interno de Alegra. Instala skills + MCPs en tu cliente de IA con un comando.
+> **Cómo se llama cada cosa.** El producto es **Data Agent Self Service** — así aparece en el
+> gateway y en el login. El repositorio es `Alegra-Team/data-agent-selfservice` y el paquete npm
+> es `alegra-data-agent`: son tres registros independientes y no tienen por qué coincidir.
+>
+> El paquete **no se renombra**: su nombre está incrustado en el hook de arranque de cada máquina
+> ya instalada, así que cambiarlo obligaría a migrar a todo el mundo a mano. Lo mismo vale para
+> el `ISSUER`/`AUDIENCE` de los JWT (`gateway/lib/jwt.ts`) — tocarlos invalidaría los tokens ya
+> emitidos.
+
+Agente de Data interno de Alegra. Una línea instala las skills + MCPs del equipo BI Data en tu herramienta de IA (Claude Code, Cursor, OpenCode, Antigravity, Codex, Hermes), gated por OAuth `@alegra.com`.
+
+> Uso interno de Alegra. No publicar, no promocionar, no contribuciones externas.
+
+## Estado
+
+- **CLI**: [`alegra-data-agent`](https://www.npmjs.com/package/alegra-data-agent) en npmjs.com.
+- **Gateway en producción**: [https://alegra-data-agent.vercel.app](https://alegra-data-agent.vercel.app).
+- **Healthcheck**: `https://alegra-data-agent.vercel.app/api/health`.
+- **Guía de uso y documentación**: [wiki del agente](https://wiki.alegra.com/doc/alegra-data-agent-DKiPc9cvFS) — empezar, cómo preguntar, qué responde, problemas comunes, [arquitectura y seguridad](https://wiki.alegra.com/doc/arquitectura-y-seguridad-vWfNc90Myy) e [historial de cambios](https://wiki.alegra.com/doc/historial-de-cambios-J8uMHq1sfd). La página de entrada del gateway enlaza a todas.
+
+## Compatibilidad
+
+| Sistema operativo | ✓ |
+|---|---|
+| macOS (Intel + Apple Silicon) | ✅ |
+| Ubuntu / Debian / Linux | ✅ |
+| WSL (Windows Subsystem for Linux) | ✅ |
+| Windows 10/11 nativo | ✅ |
+
+| Cliente AI | ✓ |
+|---|---|
+| [Claude Code](https://claude.com/claude-code) | ✅ |
+| [Cursor](https://cursor.com) | ✅ |
+| [OpenCode](https://opencode.ai) | ✅ |
+| [Antigravity](https://antigravity.dev) | ✅ |
+| [Codex](https://developers.openai.com/codex) | ✅ |
+| [Hermes Agent](https://hermes-agent.nousresearch.com) | ✅ |
+
+Si no tenés ningún cliente instalado, el bootstrap te instala Claude Code automáticamente.
+
+### Si no usás terminal
+
+El comando de arriba es para clientes CLI/IDE. En **claude.ai, Claude Desktop, Cowork y móvil**
+el agente llega sin instalar nada:
+
+| | Cómo |
+|---|---|
+| MCPs | Configuración → **Conectores**. En Team/Enterprise el owner los agrega en *Organization settings* y le quedan disponibles a toda Alegra. |
+| Skills | Configuración → **Habilidades** → subir el `.zip`. El owner puede provisionarlas para toda la organización y **aparecen solas**, sin que nadie suba nada. |
+
+Los ZIP se generan con `pnpm run pack:web` (uno por skill, en `dist/skills-web/`).
+
+Dos cosas que conviene saber:
+
+- Un conector de la cuenta se sirve a **todas** las superficies, **Claude Code incluido** — ahí
+  aparecen en `/mcp` bajo `claude.ai`. Si ya tenés el MCP como server local, el conector queda
+  oculto por URL duplicada; el propio `/mcp` te dice cómo cambiar de uno al otro.
+- Los ZIP subidos **no se auto-actualizan**, y no hay API para subirlos. El CLI sí (manifest
+  firmado). Después de un release, `pnpm run pack:web` dice cuáles cambiaron: solo esos se
+  vuelven a subir (paso 5 del «Flujo de release»).
+
+Detalle y el porqué en [ADR-0010](./docs/adr/0010-superficies-no-code.md).
 
 ## Instalación
 
+**El comando único es:**
+
 ```sh
 pnpm dlx alegra-data-agent
 ```
 
-Solo accesible para cuentas `@alegra.com` (OAuth Google). El CLI te abre el navegador para iniciar sesión.
+Funciona en cualquier terminal (macOS Terminal, GNOME Terminal, WSL, PowerShell) y desde la terminal embebida de cualquier cliente AI (Claude Code, Cursor, OpenCode, Antigravity, Codex, Hermes).
+
+### Si no tenés Node o pnpm
+
+Si al correr `pnpm dlx alegra-data-agent` te dice `pnpm: command not found`, primero corré el bootstrap que te instala Node 22+ y pnpm 11+ automáticamente:
+
+**macOS / Linux / WSL** — en cualquier terminal:
+
+```sh
+curl -fsSL https://alegra-data-agent.vercel.app/install.sh | bash
+```
+
+**Windows nativo** — en PowerShell (sin admin):
+
+```powershell
+irm https://alegra-data-agent.vercel.app/install.ps1 | iex
+```
+
+El bootstrap deja Node + pnpm + git + Claude Code listos, y al final corre `pnpm dlx alegra-data-agent` por vos. Después de eso, el comando único es siempre `pnpm dlx alegra-data-agent`.
+
+### Después del install
+
+1. **Reiniciá tu cliente AI** (Claude Code / Cursor / OpenCode / Antigravity / Codex / Hermes).
+2. **Hacé tu primera pregunta** en español. Ejemplo: *"cuántos nuevos clientes en mayo en Colombia"*.
+3. **La primera vez** que el agente use un servicio (Metabase, Amplitude, Wiki) te va a pedir 1 click con tu cuenta `@alegra.com`. Después no te pide nada más.
+
+> El agente nunca te va a pedir API keys, tokens, ni variables de entorno. Todo es OAuth `@alegra.com` automático.
+
+> **HubSpot es la excepción: no lo instala el CLI, se habilita como conector de la cuenta.** El
+> servidor de HubSpot no soporta el registro automático que usan los clientes AI, así que una entry
+> local nunca autentica. El conector oficial sí funciona: Configuración → Conectores → HubSpot →
+> Conectar, y queda disponible en Claude Code, Claude Desktop y claude.ai. En Cursor, OpenCode y
+> Codex hoy no hay ruta. Detalle en [`agent/mcps/hubspot/README.md`](./agent/mcps/hubspot/README.md).
 
 ## Requisitos
 
-- Node ≥ 22.6.0
-- pnpm ≥ 11.1.2
-- Uno de: Claude Code, Cursor, OpenCode, Antigravity, Codex, Hermes Agent
+- Cuenta Google `@alegra.com` verificada (lo único que sí tenés que tener antes).
+- Node ≥ 22.6.0 — instala el bootstrap si te falta.
+- pnpm ≥ 11.1.2 — instala el bootstrap si te falta.
+- Un cliente AI compatible — el bootstrap instala Claude Code si no detecta ninguno.
+
+## Qué se instala
+
+| Herramienta | Skills | Configuración MCP |
+|---|---|---|
+| Claude Code | `~/.claude/skills/<n>/` (carpeta) | `~/.claude.json` → `mcpServers` |
+| Cursor | `~/.cursor/skills/<n>/` (carpeta) | `~/.cursor/mcp.json` → `mcpServers` |
+| OpenCode | `~/.config/opencode/skills/<n>/` (carpeta) | `~/.config/opencode/opencode.json` → `mcp` |
+| Antigravity | `~/.gemini/skills/<n>/` (carpeta) | `~/.gemini/config/mcp_config.json` → `mcpServers` |
+| Codex | `~/.agents/skills/<n>/` (carpeta) | `~/.codex/config.toml` → `[mcp_servers.<n>]` |
+
+### Acotar los MCPs a una carpeta (opcional)
+
+Por defecto los MCPs se instalan a nivel usuario: quedan disponibles en toda sesión, de
+cualquier carpeta. Si en la misma máquina separás contextos —trabajo de Alegra, proyectos
+propios, trabajo de un cliente— podés acotarlos a una sola carpeta:
+
+```bash
+mkdir -p ~/.alegra
+echo 'MCP_DIR=~/trabajo/alegra' >> ~/.alegra/agent.conf
+pnpm dlx alegra-data-agent install --yes
+```
+
+Los MCPs pasan a `~/trabajo/alegra/.mcp.json`, que Claude Code resuelve subiendo desde el
+directorio actual: **cascadea a todo lo que esté dentro de esa carpeta y es invisible fuera
+de ella**. Se pre-aprueban solos, así que no hay que aceptarlos repo por repo.
+
+También funciona como env var (`ALEGRA_DATA_AGENT_MCP_DIR`, le gana al archivo), pero el
+archivo es lo recomendado: el hook de auto-update corre en un shell no interactivo y no ve
+lo que exportes en tu `.bashrc`, así que reinstalaría a nivel usuario.
+
+**Qué clientes lo respetan.** Claude Code y Cursor pueden acotar un MCP a una carpeta, así
+que con `MCP_DIR` los MCPs van solo a esos dos. OpenCode, Hermes, Codex y Antigravity no
+pueden: OpenCode busca su config de proyecto solo hasta la raíz del repo git, y Hermes guarda
+los MCPs por perfil. Ahí los MCPs quedarían globales, así que no se instalan y se retiran los
+que ya tuvieran. Las skills sí se instalan en todos. Para consultar datos de Alegra, usá
+Claude Code o Cursor dentro de la carpeta.
+
+**Se corrige solo.** Cada arranque compara dónde debería estar cada MCP con dónde está y
+retira lo que sobra, siempre que sea nuestro: una copia en `~/.claude.json` de antes de
+configurar `MCP_DIR`, la de una carpeta vieja si lo cambiaste o lo sacaste, o la de un cliente
+que no corresponde. Un server tuyo con el mismo nombre y otra configuración no se toca.
+`alegra-data-agent status` te dice en qué archivo quedaron y avisa si ve algo fuera de lugar.
+
+Detalle completo en [ADR-0012](docs/adr/0012-mcp-scope-por-workspace.md).
+
+### Dónde quedan los archivos que genera el agente
+
+Cuando pedís un CSV, un Excel o un gráfico, el agente lo guarda en `alegra-data/` dentro de
+la carpeta donde abriste la sesión, y te dice la ruta al terminar (en WSL, también la de
+Windows). Nunca en los temporales del cliente. Para que vaya siempre a la misma carpeta:
+
+```bash
+mkdir -p ~/.alegra
+echo "OUTPUT_DIR=$HOME/Documentos/alegra-data" >> ~/.alegra/agent.conf
+```
+
+Lo lee el agente, no el CLI, así que aplica desde la siguiente pregunta, sin reinstalar. En
+claude.ai, Desktop y Cowork el archivo aparece para descargar en el chat.
+
+El CLI:
+
+1. Verifica auth contra el gateway (OAuth Google `hd=alegra.com`).
+2. Descarga el manifest firmado Ed25519 y verifica firma antes de tocar disco.
+3. Verifica SHA-256 por archivo antes de escribirlo.
+4. Escribe atómicamente (tmp + rename) los configs JSON y respalda lo que ya existía (`*.bak-<ts>`).
+5. Registra en `~/.config/alegra-data-agent/lock.json` qué quedó instalado por target.
+6. Configura **auto-update en cada cliente instalado** (los 5, no solo Claude Code): Claude Code y Codex vía hook `SessionStart`, Cursor vía `workspaceOpen`, Antigravity vía `SessionStart` (Gemini), OpenCode vía plugin. Al abrir el cliente, el contenido se actualiza solo.
+
+## Comandos
+
+```sh
+pnpm dlx alegra-data-agent                       # instala / actualiza todo (default)
+pnpm dlx alegra-data-agent --target=claude-code,cursor
+pnpm dlx alegra-data-agent --only=alegra-sales,alegra-growth
+pnpm dlx alegra-data-agent --dry-run
+
+pnpm dlx alegra-data-agent update                # re-descarga lo que cambió
+pnpm dlx alegra-data-agent status                # estado actual + drift
+pnpm dlx alegra-data-agent list                  # catálogo del gateway
+pnpm dlx alegra-data-agent uninstall
+
+pnpm dlx alegra-data-agent login
+pnpm dlx alegra-data-agent logout
+pnpm dlx alegra-data-agent whoami
+```
+
+Ayuda completa: `pnpm dlx alegra-data-agent help`.
+
+> El CLI siempre termina ejecutando la última versión publicada: si pnpm sirve una anterior (cooldown de 24h de pnpm 11), el comando detecta la nueva en el registry y se re-ejecuta solo con ella (self-bounce).
+
+## Skills
+
+16 skills. Cada equipo dueño mantiene la suya; BI Data mantiene la infraestructura y las skills horizontales.
+
+| Skill | Dueño | Tipo |
+|---|---|---|
+| `alegra-bi` (router) | BI Data | Router |
+| `alegra-strategic` | Strategic | Dominio |
+| `alegra-product` | Producto | Dominio |
+| `alegra-sales` | Sales | Dominio |
+| `alegra-accountant` | Programa Contadores | Dominio |
+| `alegra-cx` | Customer Experience | Dominio |
+| `alegra-growth` | Growth | Dominio |
+| `alegra-alanube` | Alanube | Dominio |
+| `alegra-collection` | Collection | Dominio |
+| `alegra-sr` | Strategic Relationships | Dominio |
+| `alegra-board` | BI Data | Dominio |
+| `dashboard-auditor` | BI Data | Horizontal (review) |
+| `dataviz-reviewer` | BI Data | Horizontal (review) |
+| `presentation-coach` | BI Data | Horizontal (coach) |
+| `launch-measurement` | BI Data | Horizontal (proceso) |
+| `agent-onboarding` | BI Data | Soporte |
+
+Arquitectura: [`docs/skills-architecture.md`](./docs/skills-architecture.md). Contrato de ejecución (MBQL por defecto, SQL nativo de fallback, acceso MCP-first sin tokens): [`agent/skills/SKILL_STANDARD.md`](./agent/skills/SKILL_STANDARD.md) §3.1.
+
+### Cómo responde el agente
+
+Tres reglas transversales que heredan todas las skills de dominio (detalle en [`agent/skills/SKILL_STANDARD.md`](./agent/skills/SKILL_STANDARD.md)):
+
+- **Pregunta la población, asume los defaults.** Si falta el período, el país o el segmento, elige el más útil y lo avisa en una línea. Si no está claro **qué se cuenta** — "nuevos usuarios" puede ser signups (se registraron) o new logos (empezaron a pagar), que difieren en un orden de magnitud — pregunta antes de consultar. El vocabulario de poblaciones vive en el router (`alegra-bi`, sección «Vocabulario»).
+- **La respuesta dice de dónde sale el número.** `New logos (empezaron a pagar · fact_customers_mrr) | 71`, no `Nuevos | 71`. Una cifra sin procedencia no se puede auditar, y las mismas palabras nombran poblaciones distintas según la tabla.
+- **Una pregunta = una consulta.** Dos si hace falta una semilla o un delta. MBQL por defecto; cuando MBQL no lo expresa (CTEs, subqueries, window functions) va SQL nativo por `execute_sql` en una llamada, en vez de partirlo en varias.
+
+**Fuentes de verdad, cuando dos tablas dan números distintos:** `dm_strategic.fact_customers_mrr` manda para todo lo que sea quién paga, quién empezó y quién dejó de pagar. `dm_sales.fact_closed_deals` es su vista comercial (quién cerró, contra qué meta), conectada por `id_company`. Para eventos de uso de producto, `amplitude_events_enriched` en Metabase — no el MCP de Amplitude, no las columnas `*_m` de retención.
+
+## MCPs
+
+Los remotos van vía OAuth — el cliente abre el flow en el primer uso, **cero tokens manuales, cero env vars con secretos**. `salesforce` es la excepción: MCP stdio local del vendor, auth por la Salesforce CLI (`sf org login web --set-default`, requiere Node ≥ 22), solo lectura, para casos puntuales fuera del mirror de Metabase. No se autentica desde `/mcp` — soporte en el Caso 11 de `agent-onboarding`.
+
+| MCP | Backend | Transporte | Auth |
+|---|---|---|---|
+| `amplitude` | Amplitude SaaS | remoto (http) | OAuth |
+| `hubspot` | HubSpot SaaS | conector de cuenta | OAuth — **no se instala**: se habilita en Configuración → Conectores ([por qué](./agent/mcps/hubspot/README.md)) |
+| `metabase` | Metabase self-hosted | remoto (http) | OAuth corporativo |
+| `salesforce` | Salesforce DX (solo lectura) | stdio local | Salesforce CLI (`sf org login web`) — no por `/mcp` |
+| `wiki-alegra` | Wiki self-hosted | remoto (http) | OAuth corporativo |
+
+Llave universal para joins: `id_company`. Detalles en [`docs/joining-data-sources.md`](./docs/joining-data-sources.md).
+
+## Para mantenedores
+
+Skills viven en `agent/skills/<name>/SKILL.md` (+ anexos). MCPs en `agent/mcps/<name>/config.example.json`. El manifest firmado se regenera cuando esos paths cambian — **hoy en local**, porque Actions está apagado (ver «Release sin Actions» más abajo).
+
+### Flujo de release
+
+> Los pasos 1 y 2 describen el flujo **con CI**. Mientras Actions siga apagado, la validación y la firma van en local: ver «Release sin Actions» justo abajo.
+
+1. PR `<rama>-changes` o `feature/* → testing` modificando `agent/skills/**` o `agent/mcps/**` (CI valida standards, scan y frescura del manifest).
+2. PR `testing → main`: el workflow `sign-manifest.yml` se dispara en el PR (toca esos paths), regenera el manifest, lo escanea, lo firma con `ALEGRA_SIGNING_KEY` y commitea el manifest firmado de vuelta al branch del PR vía la REST API de GitHub (queda Verified, server-side). Al mergear, `main` ya tiene el manifest correcto.
+3. Gateway en Vercel se redespliega manualmente con `pnpm run deploy` desde `gateway/` (corre `prepare:skills`, que verifica firma y sha256, y después `vercel --prod`; nunca `vercel --prod` a secas). La integración Vercel ↔ GitHub no está habilitada: el proyecto de Vercel vive en su propio team y no depende de la organización de GitHub.
+4. Próximo `update` de cualquier alegrito trae los cambios — sin republicar el CLI a npm.
+5. **Superficies no-code (claude.ai, Desktop, Cowork).** Los pasos anteriores no llegan ahí: esos
+   ZIP se suben a mano y no hay API para automatizarlo (ADR-0010). `pnpm run pack:web` lista
+   exactamente cuáles cambiaron respecto de lo que ya está en la organización. Se suben esos, y
+   después `pnpm run pack:web -- --mark-published <skills>` registra lo subido en
+   `agent/web-published.json`, que se commitea. Sin este paso, quien usa Desktop sigue con las
+   definiciones viejas sin saberlo.
+
+### Release sin Actions
+
+Con los workflows apagados, los dos pasos que hacía el CI se hacen en local. Requieren la clave
+privada de firma (gestor del equipo) y el token de npm.
+
+```sh
+# 1. Validar, escanear, regenerar y FIRMAR el manifest
+ALEGRA_SIGNING_KEY="$(cat /ruta/a/la/clave)" pnpm run manifest
+
+# 2. Verificar que el manifest quedó firmado y válido antes de commitear
+node --experimental-strip-types -e "import('./src/signature.ts').then(async m => {
+  const man = JSON.parse((await import('node:fs')).readFileSync('agent/skills/index.json','utf-8'));
+  const r = m.verifyManifestSignature(man);
+  console.log(r.ok ? 'firma válida — ' + man.signature.keyId : 'INVÁLIDA: ' + r.reason);
+})"
+
+# 3. Publicar a npm: DESPUÉS del merge a main, del deploy del gateway verificado en producción
+#    con una sesión real (manifest nuevo, firma válida, update instala) y del tag. Lección de la 0.5.0.
+pnpm run prepublishOnly && cp .github/README-npm.md README.md && pnpm publish --access public --no-git-checks
+git checkout README.md   # devolver el README completo al repo
+```
+
+> `--no-git-checks` es obligatorio acá, no opcional: el swap del paso anterior deja el working tree
+> "sucio" a propósito (es exactamente lo que hace `publish.yml` en `Swap to minimal README for npm
+> tarball` + `--no-git-checks` en su paso `Publish`). Sin el flag, `pnpm publish` rechaza con
+> `ERR_PNPM_GIT_UNCLEAN` — no es una falla real, es el propio swap documentado arriba.
+
+El manifest firmado se commitea en el PR, en vez de que el bot lo commitee al branch. Todo lo
+demás del flujo no cambia.
+
+**Después de publicar, la wiki.** Copiar la entrada nueva del `CHANGELOG.md` **arriba** de la
+página hija [Historial de cambios](https://wiki.alegra.com/doc/historial-de-cambios-J8uMHq1sfd) y
+actualizar la línea **Estado** del home de la wiki (versión, skills, fecha). El home no lleva
+historial: solo el enlace a esa página, para que no crezca con cada release. El CHANGELOG del repo
+es la fuente; la wiki lo copia, nunca al revés.
+
+### Publicación de nueva versión del CLI
+
+1. Bump `version` en `package.json` y `gateway/package.json` + entrada en `CHANGELOG.md` + regenerar el manifest con **`pnpm run manifest`** (el pipeline completo: `validate` → `scan` → `generate` → `sign`; el `productVersion` sale de package.json). Todo dentro del mismo PR del release.
+2. Tras el merge a main, tag sobre el merge commit: `git tag -s vX.Y.Z && git push origin vX.Y.Z`.
+3. **Con Actions apagado este paso no ocurre:** el tag no publica nada y el publish se hace a mano (ver «Release sin Actions»). Cuando Actions vuelva, el workflow `publish.yml` valida que `package.json` coincida con el tag, corre los gates (validate → scan → tests) y publica: build → swap a `.github/README-npm.md` (README mínimo del tarball) → `pnpm publish --access public`. Requiere el secret `NPM_TOKEN` configurado.
+
+> ⚠️ **Nunca corras `manifest:generate` solo.** Borra el bloque `signature` de
+> `agent/skills/index.json`, y `verifyManifestSignature` es hard-fail: un manifest sin firma hace
+> que el CLI rechace **toda** instalación y update, no solo la skill que tocaste. Siempre
+> `pnpm run manifest`, que firma al final. `tests/security/manifest-committed.test.mjs` lo caza en
+> local si se te pasa.
+
+**Si el release sale mal:** mover el dist-tag `latest` hacia atrás **no revierte a nadie** — el
+hook resuelve por rango semver y los tags no participan. El procedimiento real está en
+[`docs/rollback.md`](./docs/rollback.md).
+
+### Local
+
+```sh
+pnpm run manifest:scan         # buscar prompt-injection / credenciales
+pnpm run manifest:generate     # regenera agent/skills/index.json
+pnpm run manifest:sign         # firma (requiere ALEGRA_SIGNING_KEY)
+pnpm run manifest               # los cuatro en orden (validate → scan → generate → sign)
+
+pnpm install
+pnpm typecheck
+pnpm build                     # → dist/
+
+pnpm test                      # Fase 1: SOLO valida el schema de los evals — no
+                               # ejecuta ningún agente
+pnpm test:security             # la suite real: firma, paths, clientes, drift de MCPs
+pnpm test:all                  # ambos
+
+pnpm run eval:run -- --local   # Fase 2: ejecuta los evals de verdad contra las skills
+                               # del repo. Cuesta tokens y tarda horas (116 casos); para
+                               # un caso puntual: --only <nombre-del-caso>
+
+pnpm run verify:clients        # E2E: instala en un HOME temporal con 5 de los 6 clientes
+                               # simulados (Hermes aún no está cubierto) y verifica rutas, shapes de MCP, hooks
+                               # e idempotencia (requiere sesión y red)
+```
+
+> **`test:all` en verde no dice que las skills respondan bien.** La Fase 1 solo lee los YAML;
+> si tardó un segundo, no ejecutó nada. Medir routing, tablas y números es `eval:run`: corre cada
+> caso aislado (sin el repo ni la memoria del dev a la vista) y consulta Metabase de verdad.
+> Detalle en [`docs/evals.md`](./docs/evals.md).
+
+El grueso de la verificación corre en local, no en CI: la organización está en plan Free y el
+pool de minutos de Actions es compartido. `pre-commit install && pre-commit install --hook-type
+pre-push` deja los mismos gates enganchados a los commits.
+
+### Keypair de firma
+
+```sh
+pnpm run signing-key:generate      # escribe la privada a un archivo 600; NO la imprime
+```
+
+La pública va en `TRUSTED_KEYS` (`src/signature.ts`); la privada, **en dos lugares**: el gestor
+de contraseñas del equipo y el secret `ALEGRA_SIGNING_KEY` del repo. Un secret de GitHub no se
+puede leer: si es la única copia, se pierde en cuanto haga falta usarla en otro lado — pasó con
+la clave v1 y obligó a rotar.
+
+El CLI acepta **varias claves a la vez**, que es lo que permite rotar sin ventana de rotura: con
+una sola, el CLI nuevo rechaza el manifest viejo *y* el viejo rechaza el nuevo. Procedimiento
+completo en [SECURITY.md](SECURITY.md#custodia-y-rotación-de-la-clave-de-firma).
+
+## Estructura del repo
+
+```
+data-agent-selfservice/
+├── src/                # CLI TypeScript (publicado a npm como dist/)
+├── scripts/            # generate-manifest, sign-manifest, scan-skills, generate-signing-key, verify-clients
+├── agent/
+│   ├── skills/         # SKILL.md + anexos, agrupados por dueño
+│   └── mcps/           # config.example.json por MCP
+├── gateway/            # Next.js en Vercel — OAuth + manifest firmado + skills
+├── docs/               # ADRs + guías
+├── tests/              # evals + security tests
+├── install.sh          # bootstrap para macOS/Linux/WSL (servido por gateway)
+└── install.ps1         # bootstrap para Windows (servido por gateway)
+```
+
+## Troubleshooting
+
+| Síntoma | Probable causa | Fix |
+|---|---|---|
+| `pnpm: command not found` | pnpm no instalado | `corepack enable && corepack prepare pnpm@11.1.2 --activate` |
+| `Node.js >= 22.6.0` requerido | Node viejo | `nvm install 22` o reinstala desde nodejs.org |
+| `Solo cuentas @alegra.com` | OAuth con cuenta personal | Login con tu cuenta corporativa |
+| El cliente no ve los MCPs | Cambio de config no recargado | Reinicia el cliente |
+| `keyId no reconocido` | El CLI no conoce la clave con la que se firmó el manifest (rotación en curso y CLI viejo) | `pnpm dlx alegra-data-agent@latest`. Durante una rotación el CLI acepta la clave nueva y la anterior, así que esto solo aparece en versiones muy atrasadas |
+| Una versión recién publicada no se instala / no actualiza | Cooldown de pnpm 11 (`minimumReleaseAge`, ~24h) sobre versiones de <24h | Desde 0.2.2 el CLI hace self-bounce: aunque pnpm sirva una versión anterior, el comando detecta la última en el registry y se re-ejecuta con ella solo. El self-update (hook) y el bootstrap además corren con `--config.minimumReleaseAge=0`. Para forzarlo a mano: `pnpm dlx alegra-data-agent@<versión>` (pin exacto) |
+
+Si nada funciona: la skill `agent-onboarding` (instalada por defecto) tiene una guía paso a paso de troubleshooting que el modelo puede correr contigo.
+
+## Branching
+
+`<nombre>-changes → testing → main`. Cada quien trabaja en su rama personal (`jhon-changes`,
+`luis-changes`…) y llega por PR: primero a `testing`, después a `main`. Nada entra directo a
+`main`, y **el PR a `main` lo aprueba y mergea otra persona** — nadie mergea el suyo. Detalle en
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+Cambios a `agent/skills/**` o `agent/mcps/**` disparan el workflow de firma en el PR hacia `main`
+(el manifest firmado se commitea al branch del PR antes del merge). Cambios a `scripts/**.mjs`
+requieren review humano: no autoejecutan la firma, para que un PR a los scripts no pueda
+exfiltrar la clave.
+
+> En plan Free los repos privados no tienen rulesets, así que esto es **un acuerdo del equipo,
+> no un candado técnico**. Lo mismo vale para los commits firmados. Ver
+> [Cómo trabajamos en GitHub (Alegra-Team)](https://wiki.alegra.com/doc/como-trabajamos-en-github-alegra-team-2WuRXpYEmg).
+
+## CI / Workflows
+
+> ⚠️ **Hoy Actions está deshabilitado en este repo.** La organización agotó su presupuesto
+> (`the job was not started because recent account payments have failed or your spending limit
+> needs to be increased`), así que ningún workflow puede correr y dejarlos activos solo llenaría
+> los PRs de checks rojos que no dicen nada del código. **Mientras dure, todo es local**: la
+> validación con pre-commit/pre-push, y la firma del manifest y la publicación a npm a mano —
+> ver «Release sin Actions» abajo. Para reactivarlos cuando haya presupuesto:
+> `gh api -X PUT /repos/Alegra-Team/data-agent-selfservice/actions/permissions -F enabled=true`.
+
+Cuatro workflows, y solo uno corre por PR. El pool de minutos de Actions es compartido entre
+todos los repos de la organización (plan Free), así que en GitHub queda únicamente lo que no se
+puede garantizar en la máquina del autor; el resto vive en `.pre-commit-config.yaml`.
+
+| Workflow | Cuándo dispara | Qué hace |
+|---|---|---|
+| `pr.yml` | PRs a `testing` y a `main` (`paths-ignore` docs-only) | **Un solo job**: gates pnpm-only, standards de skills/MCPs (strict), scan de secretos y prompt injection, frescura del manifest, typecheck y tests. El typecheck del gateway solo si el PR toca `gateway/` |
+| `sign-manifest.yml` | PRs a `main` que tocan `agent/skills/**` o `agent/mcps/**` | Regenera + escanea + firma el manifest y lo commitea al branch del PR vía REST API de GitHub, no con `git push`: así queda firmado server-side y Verified. Necesita el secret `ALEGRA_SIGNING_KEY` |
+| `security.yml` | Schedule semanal + `workflow_dispatch` | Gitleaks + OSV + Trivy + pnpm audit. CodeQL solo bajo dispatch explícito (es el job más caro). No corre por push ni por PR |
+| `publish.yml` | Tag `v*.*.*` | Valida versión == tag + gates + publica el CLI a npmjs.com. Necesita el secret `NPM_TOKEN` |
 
-## Soporte
+Por qué un solo job y no varios: GitHub factura por job con un mínimo de un minuto, así que
+partir la validación en cuatro costaba cuatro minutos aunque dos de ellos fueran un `grep` de
+tres segundos.
 
-Guía de uso, documentación y soporte para el equipo de Alegra: entra a https://alegra-data-agent.vercel.app con tu cuenta `@alegra.com`.
+Dependabot apunta a `testing` como cualquier otro cambio, no directo a main).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alegra-data-agent",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "private": false,
   "description": "Agente de Data interno de Alegra. Instala skills + MCPs en tu cliente de IA con un comando.",
   "license": "UNLICENSED",