@hoilab/ada-cli 0.84.22 → 0.85.1

package/docs/modules-seguridad.md

@@ -0,0 +1,158 @@
+# Seguridad — secretos, cifrado, parches, revisión y privacidad
+
+Los ocho módulos de este grupo defienden tres cosas: que los secretos no lleguen al proveedor, que lo que se escribe a disco no filtre datos protegidos, y que las operaciones destructivas (editar, aplicar parches, publicar revisiones) fallen de forma comprobable en vez de corromper en silencio.
+
+## Secretos keyed reversibles (C01) — evita que tus API keys y tokens salgan hacia el modelo/proveedor, sin romper los edits exactos del agente.
+
+**Activa**: lanzando con la extensión `ada-cli -e packages/coding-agent/src/core/secretos/extension.ts` (dos ganchos ya emitidos por el runner, coste cero contra el presupuesto de sincronización con upstream). Migrar a builtin está previsto pero hoy requiere el flag `-e`.
+
+**Garantiza**:
+- Los mensajes salientes se ofuscan con placeholders `$$NOMBRE_AMIGABLE_HASH$$` keyed (SHA-256 HMAC con clave por instalación): los bytes del secreto nunca llegan al proveedor.
+- Es un punto fijo: re-ofuscar cada turno no altera el output ni rompe los prefijos de prompt-cache.
+- Antes de ejecutar una herramienta, `deobfuscateToolArguments` restaura los placeholders sobre el input, así los edits exact-match siguen casando con los bytes reales del disco (issue #6968).
+- Tokens con forma de credencial (GitHub/GitLab/OpenAI/Anthropic: `ghp_`, `glpat-`, `sk-proj-`, `sk-ant-`, …) se detectan sin entropy-gate: un falso positivo solo sobre-ofusca y el round-trip es lossless.
+- La clave vive en `$XDG_STATE_HOME/ada/secret-placeholder.key` (fallback `~/.ada/agent/`), creada con flag `wx` mode 0600 anti-carrera; nunca pasa por argv ni se registra, y el propio obfuscador la auto-redacta del output visible.
+- Para display local, los placeholders que el modelo eco-ea se restauran (`deobfuscateSessionContext`).
+- Los placeholders llevan ~62 bits de entropía para que secretos distintos no colisionen aunque cambie el conjunto configurado entre sesiones.
+
+**No garantiza**:
+- No es builtin: sin el flag `-e` no hay ofuscación.
+- Coincidencias más cortas de 8 caracteres (`MIN_OBFUSCATE_SECRET_LEN`) no van detrás de placeholder reversible, para no tapar palabras pequeñas.
+- No es gestión de credenciales ni cifrado en reposo: solo evita la salida hacia el proveedor.
+
+**Código**: `src/core/secretos/` (`extension.ts` cableado, `index.ts`, `obfuscator.ts`, `message-transform.ts`, `placeholder.ts`, `placeholder-scan.ts`, `replacement.ts`, `regex.ts`)
+
+**Test**: `test/secretos-keyed.test.ts`
+
+## Share cifrado E2E — exporta/comparte una sesión sin que el paquete (ni quien lo intercepte) pueda leerla; primero se tapa, después se cifra.
+
+**Activa**: automático donde se usa: el exportador es un módulo puro que solo escribe si le das fichero destino, y su primitiva de sellado AES-256-GCM se reutiliza en las salas de colaboración (`colaboracion/rele`).
+
+**Garantiza**:
+- El orden ES la feature (hallazgo D10 de la auditoría omp): la redacción previa reutiliza el punto único `taparAntesDeEscribir` (identificadores + art. 9 del RGPD), no un detector propio.
+- Cifrado AES-256-GCM con clave derivada por scrypt (resistente a tablas precalculadas si la clave humana es débil). Formato `[MAGIC "ADASHR1"][sal 16B][iv 12B][ct+tag]`; la sal va en el paquete porque no es secreta.
+- La clave (256 bits aleatorios, base64url) nunca se serializa dentro del paquete ni en disco junto a él: va al receptor por canal aparte.
+- Tres estados honestos: `exportado` (hay contenido superviviente sellado), `vacio` (la sesión no tenía texto) y `todo-tapado` (había texto y la redacción lo eliminó todo) — no exporta un bloque opaco inútil.
+- Techo del paquete: 1 MiB. Errores distinguibles: `PaqueteNoReconocido` (formato) vs `ClaveIncorrecta` (GCM falla: clave equivocada o paquete alterado).
+- Sin red: no hace fetch, no abre sockets, no sube nada a ninguna parte.
+
+**No garantiza**:
+- Quien tenga la clave lee todo lo que sobrevivió a la redacción: la confidencialidad frente al receptor depende del canal aparte por el que viajes la clave.
+- No transporta el paquete: moverlo es cosa de la persona.
+
+**Código**: `src/core/share/cifrado.ts`, `src/core/share/exportar.ts`
+
+**Test**: `test/share-cifrado.test.ts`
+
+## apply_patch nativo — aplica los patches wire (`*** Begin Patch … *** End Patch`) que emiten los proveedores entrenados, rechazando con `conflict://` si el fichero divergió.
+
+**Activa**: automático: `core/registro.ts` (importado por `core/ada.ts`, sin tocar upstream) registra la tool nativa `apply_patch` y envuelve la tool `edit` para delegar directamente al parser/aplicador nativo cuando los argumentos traen `patch`.
+
+**Garantiza**:
+- Anclaje por contexto: cada hunk valida su contenido esperado contra el fichero; si divergió, falla con `conflict://<ruta>#<hashEsperado>-><hashActual>` SIN tocar disco.
+- Escritura atómica con verificación byte a byte post-escritura.
+- Soporta Add / Update / Delete / Move-to y hunks `@@ -a,b +c,d @@`; los hunks se aplican de abajo hacia arriba para no desplazar índices.
+- Los ficheros con cabecera binaria se rechazan (sniffer).
+- Normalización LF para comparar, preservando la terminación original fuera del patch.
+
+**No garantiza**:
+- NO es un wrapper fuzzy: no adivina posiciones; si el contexto no casa exacto, conflicto.
+
+**Código**: `src/core/parche/parser.ts`, `src/core/parche/aplicar.ts`, `src/core/parche/registro.ts`; tool expuesta en `src/core/tools/apply_patch.ts`
+
+**Test**: `test/apply-patch.test.ts`
+
+## Auto-reparación de hunks — recupera una edición fallida cuyo bloque de contexto existe pero desplazado, en vez de perder un turno.
+
+**Activa**: automática: cuando una edición falla porque el hunk no aplica donde se esperaba, se intenta la reparación antes de devolver el error.
+
+**Garantiza**:
+- Solo repara con un «par simétrico» válido: las mismas líneas de `oldText` aparecen contiguas y ÚNICAS en el contenido actual (0 apariciones = contenido distinto; >1 = ambiguo; en ambos casos no se repara).
+- Validación sintáctica posterior con la regla de `edicion/parseo.ts`: solo se acusa a la edición si la preimagen parseaba; un fichero ya roto antes no bloquea.
+- Tree-sitter es opcional y nunca lanza: si el parser o la gramática del lenguaje no están instalados, devuelve «no sé, no bloqueo». Es dependencia realmente opcional.
+
+**No garantiza**:
+- No repara contenido divergiendo (el bloque ya no es ese) ni posiciones ambiguas: elegir por el modelo es peor que rechazar.
+- Sin gramáticas tree-sitter instaladas, esa capa estructural no añade ninguna prueba.
+
+**Código**: `src/core/reparacion/index.ts`, `src/core/reparacion/reparar-hunk.ts`
+
+**Test**: `test/reparacion-hunk.test.ts`
+
+## Revisión de código (dispositions + procedencia + SARIF firmado) — convierte «pídele al modelo que revise» en un proceso de seguridad: hallazgos anclados, decisiones humanas trazables e informes que GitHub ingiere.
+
+**Activa**: comando `ada-cli review` sobre tu diff; añade `--sarif` para publicar en el pipeline de Code Scanning.
+
+**Garantiza**:
+- **Anclaje**: un hallazgo cuya evidencia no aparece literalmente (texto normalizado) en las líneas AÑADIDAS del diff se descarta, por convincente que sea. Sobre un diff limpio, un revisor honesto devuelve cero.
+- Hallazgos con evidencia OBLIGATORIA y huella estable (regla + ruta + evidencia, deliberadamente sin número de línea): mover el fichero no lo convierte en hallazgo nuevo.
+- **Dispositions**: `aceptado-riesgo` y `falso-positivo` suprimen solo con quién, cuándo y justificación; `corregido` NO suprime — si el hallazgo reaparece, cuenta como regresión nueva; `pendiente` no decide nada.
+- **Procedencia encadenada**: cada scan registra herramienta, versión, commit analizado, timestamp y pin del ruleset, con hash SHA-256 encadenado al registro anterior (como el libro de auditoría); `verificarProcedencia` recomputa toda la cadena y detecta cualquier manipulación o edición manual a medias.
+- **SARIF 2.1.0** válido para GitHub Code Scanning / Azure DevOps: toda regla citada en `results` está declarada en `driver.rules` y `originalUriBaseIds` fija la raíz del repositorio. Vale para cualquier revisión, no solo el escáner.
+- **Publicación firmada**: HMAC-SHA256 sobre los bytes EXACTOS del documento, firma en `.sig` aparte (el SARIF sigue siendo ingerible tal cual), verificación con `timingSafeEqual` y validación de forma previa (Buffer.from hex trunca en silencio).
+
+**No garantiza**:
+- La calidad de los hallazgos sigue siendo la del modelo: el anclaje garantiza que lo publicado existe, no que sea cierto.
+- La firma es simétrica: verificar exige la misma clave que firmó.
+- Una disposition sin persona/fecha/motivo no es auditoría — el formato te la exige, pero no puede impedir que alguien justifique mal.
+
+**Código**: `src/core/revision/` (`hallazgo.ts`, `revisor.ts`, `dispositions.ts`, `procedencia.ts`, `sarif.ts`, `publicar.ts`); CLI en `src/cli/review-command.ts`
+
+**Test**: `test/sarif.test.ts`, `test/revision-dispositions.test.ts` (incluye procedencia encadenada y publicación firmada)
+
+## Hooks TypeScript in-process (B05) — reflejos programáticos sobre cada llamada a herramienta, con objetos tipados y capacidad de reescritura bajo re-aprobación obligatoria.
+
+**Activa**: registrando hooks como ficheros `.ts` que exportan `{matcher?, onToolCall}`; se compilan al vuelo con jiti (sin caché de módulos: editar el `.ts` surte efecto sin reiniciar). Complementa, no sustituye, los hooks de shell de `core/hooks/`.
+
+**Garantiza**:
+- Tres veredictos: `permitir`, `rechazar`, `reescribir`. El `matcher` es una regex contra `toolName`; ausente casa con todo; inválida NO casa y no revienta (misma semántica que `planificarHooks`).
+- Fail-closed por defecto: un hook colgado o que revienta queda aislado por timeout (10 s por defecto) y cierra el paso según `failClosed` (por defecto, cerrar).
+- Orden determinista (hooks ordenados por origen); el primer veredicto que bloquea gana. El runner nunca lanza: un módulo dinámico no puede tumbar el turno.
+- Invariante «approve one thing, run another»: una reescritura NUNCA sale lista para aplicar. Si `effectiveParams` difiere del input recibido, el resultado lleva `requiereAprobacion: true` y el consumidor está obligado a re-aprobar SOBRE LOS PARÁMETROS EFECTIVOS antes de ejecutar nada. No existe camino que devuelva `effectiveParams` sin esa marca.
+
+**No garantiza**:
+- No reemplaza los hooks de shell: es la variante in-process con tipado y reescritura.
+- El runner no re-aprueba él mismo: delega la re-aprobación en el consumidor (es un contrato documentado, no automático).
+
+**Código**: `src/core/hooks-ts/tipos.ts` (contrato puro), `cargador.ts` (jiti), `runner.ts` (agregación), `index.ts`
+
+**Test**: `test/hooks-ts.test.ts`
+
+## Privacidad art. 9/10 RGPD — impide que categorías especiales de datos (salud, sindicación, origen étnico, religión, política, vida sexual, biometría, genética; condenas del art. 10) se escriban EN CLARO en auditoría, diario o export.
+
+**Activa**: automático: todo lo que toca disco pasa por el punto único `taparAntesDeEscribir` — el libro de auditoría (`audit/libro.ts`), el diario de ediciones y la exportación cifrada (`share/`). No hay que acordarse de llamar a las dos pasadas: el módulo las compone.
+
+**Garantiza**:
+- Dos pasadas compuestas: identificadores (`redactSensitive`) + barrido específico de categorías especiales art. 9/10, que NO depende del nivel elegido (el art. 9 es una prohibición legal, no una preferencia).
+- Los IDENTIFICADORES se validan, no se reconocen por forma: DNI/NIE por letra de control (módulo 23), IBAN y número de la Seguridad Social por módulo 97 — esto elimina el falso positivo medido del escáner anterior (un UUID con fragmento con forma de NSS).
+- El VOCABULARIO ambiguo exige CO-OCURRENCIA con un marcador de persona dentro de una ventana de 60 caracteres («su diagnóstico» dispara; «diagnóstico» en un log de compilador, no).
+- Si el texto no se puede analizar (`TextoNoAnalizable`: no es cadena o es absurdamente largo), se tapa el TEXTO ENTERO con marca y motivo visible — nunca se escribe en claro algo que nadie ha mirado, y quien audite distingue un campo tapado por precaución de uno tapado por hallazgo.
+
+**No garantiza**:
+- No entiende negación ni hipótesis («no está de baja por depresión» dispara igual): deliberado — en detección de fugas el falso negativo se paga más caro.
+- No cubre `fingerprint`/«huella digital» como biometría (en este repo son huellas de certificado/fichero); sí cubre «huella dactilar».
+- La matrícula española no tiene dígito de control: única forma sin validar de las cinco (compensada exigiendo el alfabeto real de placas).
+
+**Código**: `src/core/privacidad/categorias-especiales.ts` (detección), `src/core/privacidad/tapar.ts` (composición)
+
+**Test**: `test/pii-categorias-especiales.test.ts`, `test/tapar-articulo-9.test.ts`
+
+## Edición robusta — recupera ediciones que hoy se pierden por una errata del modelo, una ruta a medias o un notebook, sin convertir la recuperación en corrupción.
+
+**Activa**: automático dentro de la tool de edición (`tools/edit-diff.ts`) y del observador de ediciones; la edición de notebooks está expuesta por la API de `core/ada.ts`.
+
+**Garantiza**:
+- **Bloques con errata (`parecido.ts`)**: el modelo cita contexto y lo retipea mal; se casa por parecido (Levenshtein) con tres puertas — umbral alto 0,92 de similitud media por línea, dominancia clara del mejor candidato sobre el segundo, y las líneas CITADAS se escriben del FICHERO, no del modelo (solo las líneas donde `oldText` y `newText` difieren son propuesta del modelo). A diferencia de omp, no persiste las erratas del contexto citado.
+- **Rutas difusas (`rutas-difusas.ts`)**: el modelo dijo `edit.ts` y quiso decir `src/core/tools/edit.ts`; resuelve por sufijo ÚNICO de ruta en el workspace. La ruta exacta gana siempre; 0 o 2+ coincidencias es error con candidatos (`ErrorRutaAmbigua`, hasta 10 listados). Excluye `node_modules`, `.git`, `dist`, etc.
+- **Notebooks (`ipynb.ts`)**: edición por celdas sobre el JSON parseado; re-serialización estable (orden de claves original, indentación 1 como Jupyter — el diff solo muestra la celda tocada) y validación por re-parseo ANTES de escribir: nunca escribe JSON roto. Sin dependencias nuevas.
+- **Diario de ediciones (`diario.ts`)**: JSONL diario con `{ruta, antes, despues, resultado}` de cada edición, materia prima para medir si el auto-arreglo mejora de verdad. Ambos lados pasan por `taparAntesDeEscribir` (no por `redactSensitive`, que no cubre el art. 9). Nunca lanza: un fallo del diario no tumba la edición que registra.
+
+**No garantiza**:
+- Erratas por debajo del umbral de similitud o sin candidato dominante se rechazan: no adivina.
+- La búsqueda difusa es por sufijo EXACTO, no por parecido de nombre: `edit.tss` no resuelve a `edit.ts` (eso es terreno de la recuperación de erratas de `reparacion.ts`, en otro plano).
+- El wiring de `.ipynb` en `tools/edit.ts` queda pendiente (hunks upstream vivos): la API ya está expuesta, el despacho es una línea cuando toque.
+- El diario no es el libro de sesión: nadie audita su cadena, por eso mismo todo lo que escribe va tapado.
+
+**Código**: `src/core/edicion/parecido.ts`, `rutas-difusas.ts`, `ipynb.ts`, `diario.ts`, `observador.ts`, `reparacion.ts`
+
+**Test**: `test/edicion-robustez.test.ts`, `test/diario-de-ediciones.test.ts`, `test/reparacion-de-ediciones.test.ts`, `test/cleanse-reparacion.test.ts`

package/docs/packages.md

@@ -1,14 +1,14 @@
-> pi can help you create pi packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
+> Ada can help you create packages. Ask it to bundle your extensions, skills, prompt templates, or themes.
 
-# Pi Packages
+# Ada Packages
 
-Pi packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories.
+Ada packages bundle extensions, skills, prompt templates, and themes so you can share them through npm or git. A package can declare resources in `package.json` under the `pi` key, or use conventional directories. The manifest key stays `pi` so packages work unchanged across Ada and upstream pi.
 
 ## Table of Contents
 
 - [Install and Manage](#install-and-manage)
 - [Package Sources](#package-sources)
-- [Creating a Pi Package](#creating-a-pi-package)
+- [Creating a Package](#creating-a-package)
 - [Package Structure](#package-structure)
 - [Dependencies](#dependencies)
 - [Package Filtering](#package-filtering)
@@ -17,41 +17,41 @@ Pi packages bundle extensions, skills, prompt templates, and themes so you can s
 
 ## Install and Manage
 
-> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+> **Security:** Ada packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
 
 ```bash
-pi install npm:@foo/bar@1.0.0
-pi install git:github.com/user/repo@v1
-pi install https://github.com/user/repo  # raw URLs work too
-pi install /absolute/path/to/package
-pi install ./relative/path/to/package
-
-pi remove npm:@foo/bar
-pi list                     # show installed packages from settings
-pi update                   # update pi only
-pi update --all             # update pi, update packages, and reconcile pinned git refs
-pi update --extensions      # update packages and reconcile pinned git refs only
-pi update --models          # refresh model catalogs only
-pi update --self            # update pi only
-pi update --self --force    # reinstall pi even if current
-pi update npm:@foo/bar      # update one package
-pi update --extension npm:@foo/bar
+ada-cli install npm:@foo/bar@1.0.0
+ada-cli install git:github.com/user/repo@v1
+ada-cli install https://github.com/user/repo  # raw URLs work too
+ada-cli install /absolute/path/to/package
+ada-cli install ./relative/path/to/package
+
+ada-cli remove npm:@foo/bar
+ada-cli list                     # show installed packages from settings
+ada-cli update                   # update Ada only
+ada-cli update --all             # update Ada, update packages, and reconcile pinned git refs
+ada-cli update --extensions      # update packages and reconcile pinned git refs only
+ada-cli update --models          # refresh model catalogs only
+ada-cli update --self            # update Ada only
+ada-cli update --self --force    # reinstall Ada even if current
+ada-cli update npm:@foo/bar      # update one package
+ada-cli update --extension npm:@foo/bar
 ```
 
-These commands manage pi packages and `pi update` can update the pi CLI installation. To uninstall pi itself, see [Quickstart](quickstart.md#uninstall).
+These commands manage Ada packages and `ada-cli update` can update the Ada CLI installation. To uninstall Ada itself, see [Quickstart](quickstart.md#uninstall).
 
-By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup after the project is trusted.
+By default, `install` and `remove` write to user settings (`~/.ada/agent/settings.json`). Use `-l` to write to project settings (`.ada/settings.json`) instead. Project settings can be shared with your team, and Ada installs any missing packages automatically on startup after the project is trusted.
 
 To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
 
 ```bash
-pi -e npm:@foo/bar
-pi -e git:github.com/user/repo
+ada-cli -e npm:@foo/bar
+ada-cli -e git:github.com/user/repo
 ```
 
 ## Package Sources
 
-Pi accepts three source types in settings and `pi install`.
+Ada accepts three source types in settings and `ada-cli install`.
 
 ### npm
 
@@ -60,9 +60,9 @@ npm:@scope/pkg@1.2.3
 npm:pkg
 ```
 
-- Versioned specs are pinned and skipped by package updates (`pi update --extensions`, `pi update --all`).
-- User installs go under `~/.pi/agent/npm/`.
-- Project installs go under `.pi/npm/`.
+- Versioned specs are pinned and skipped by package updates (`ada-cli update --extensions`, `ada-cli update --all`).
+- User installs go under `~/.ada/agent/npm/`.
+- Project installs go under `.ada/npm/`.
 - Set `npmCommand` in `settings.json` to pin npm package lookup and install operations to a specific wrapper command such as `mise` or `asdf`.
 
 Example:
@@ -87,21 +87,21 @@ ssh://git@github.com/user/repo@v1
 - HTTPS and SSH URLs are both supported.
 - SSH URLs use your configured SSH keys automatically (respects `~/.ssh/config`).
 - For non-interactive runs (for example CI), you can set `GIT_TERMINAL_PROMPT=0` to disable credential prompts and set `GIT_SSH_COMMAND` (for example `ssh -o BatchMode=yes -o ConnectTimeout=5`) to fail fast.
-- Refs are pinned tags or commits. `pi update --extensions` and `pi update --all` do not move them to newer refs, but they do reconcile an existing clone to the configured ref.
-- Use `pi install git:host/user/repo@new-ref` to update settings and move an existing package to a new pinned ref.
-- Cloned to `~/.pi/agent/git/<host>/<path>` (global) or `.pi/git/<host>/<path>` (project).
-- When reconciliation changes the checkout, pi resets and cleans the clone, then runs `npm install` if `package.json` exists.
+- Refs are pinned tags or commits. `ada-cli update --extensions` and `ada-cli update --all` do not move them to newer refs, but they do reconcile an existing clone to the configured ref.
+- Use `ada-cli install git:host/user/repo@new-ref` to update settings and move an existing package to a new pinned ref.
+- Cloned to `~/.ada/agent/git/<host>/<path>` (global) or `.ada/git/<host>/<path>` (project).
+- When reconciliation changes the checkout, Ada resets and cleans the clone, then runs `npm install` if `package.json` exists.
 
 **SSH examples:**
 ```bash
 # git@host:path shorthand (requires git: prefix)
-pi install git:git@github.com:user/repo
+ada-cli install git:git@github.com:user/repo
 
 # ssh:// protocol format
-pi install ssh://git@github.com/user/repo
+ada-cli install ssh://git@github.com/user/repo
 
 # With version ref
-pi install git:git@github.com:user/repo@v1.0.0
+ada-cli install git:git@github.com:user/repo@v1.0.0
 ```
 
 ### Local Paths
@@ -111,11 +111,11 @@ pi install git:git@github.com:user/repo@v1.0.0
 ./relative/path/to/package
 ```
 
-Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, pi loads resources using package rules.
+Local paths point to files or directories on disk and are added to settings without copying. Relative paths are resolved against the settings file they appear in. If the path is a file, it loads as a single extension. If it is a directory, Ada loads resources using package rules.
 
-## Creating a Pi Package
+## Creating a Package
 
-Add a `pi` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability.
+Add a `pi` manifest to `package.json` or use conventional directories. Include the `pi-package` keyword for discoverability. Both the manifest key and the keyword stay `pi`/`pi-package`: this is the shared ecosystem format, and packages published for either Ada or upstream pi work in both.
 
 ```json
 {
@@ -134,7 +134,7 @@ Paths are relative to the package root. Arrays support glob patterns and `!exclu
 
 ### Gallery Metadata
 
-The [package gallery](https://pi.dev/packages) displays packages tagged with `pi-package`. Add `video` or `image` fields to show a preview:
+The upstream [package gallery](https://pi.dev/packages) displays packages tagged with `pi-package`. Add `video` or `image` fields to show a preview:
 
 ```json
 {
@@ -157,7 +157,7 @@ If both are set, video takes precedence.
 
 ### Convention Directories
 
-If no `pi` manifest is present, pi auto-discovers resources from these directories:
+If no `pi` manifest is present, Ada auto-discovers resources from these directories:
 
 - `extensions/` loads `.ts` and `.js` files
 - `skills/` recursively finds `SKILL.md` folders and loads top-level `.md` files as skills
@@ -166,11 +166,11 @@ If no `pi` manifest is present, pi auto-discovers resources from these directori
 
 ## Dependencies
 
-Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When pi installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
+Third party runtime dependencies belong in `dependencies` in `package.json`. Dependencies that do not register extensions, skills, prompt templates, or themes also belong in `dependencies`. When Ada installs a package from npm or git, it runs `npm install`, so those dependencies are installed automatically.
 
-Pi bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`.
+Ada bundles core packages for extensions and skills. If you import any of these, list them in `peerDependencies` with a `"*"` range and do not bundle them: `@earendil-works/pi-ai`, `@earendil-works/pi-agent-core`, `@earendil-works/pi-coding-agent`, `@earendil-works/pi-tui`, `typebox`. Ada resolves these specifiers to its own bundled copies, so extensions written for pi keep working without changes — do not rewrite them to `@hoilab/ada-cli`.
 
-Other pi packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Pi loads packages with separate module roots, so separate installs do not collide or share modules.
+Other packages must be bundled in your tarball. Add them to `dependencies` and `bundledDependencies`, then reference their resources through `node_modules/` paths. Ada loads packages with separate module roots, so separate installs do not collide or share modules.
 
 Example:
 
@@ -217,7 +217,7 @@ Filter what a package loads using the object form in settings:
 
 ## Enable and Disable Resources
 
-Use `pi config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. `pi config` starts in global settings (`~/.pi/agent/settings.json`); press Tab to switch between global and project-local modes. Use `pi config -l` to start in project overrides (`.pi/settings.json`) with inherited global resources dimmed.
+Use `ada-cli config` to enable or disable extensions, skills, prompt templates, and themes from installed packages and local directories. `ada-cli config` starts in global settings (`~/.ada/agent/settings.json`); press Tab to switch between global and project-local modes. Use `ada-cli config -l` to start in project overrides (`.ada/settings.json`) with inherited global resources dimmed.
 
 ## Scope and Deduplication
 

package/docs/prompt-templates.md

@@ -1,4 +1,4 @@
-> pi can create prompt templates. Ask it to build one for your workflow.
+> Ada can create prompt templates. Ask it to build one for your workflow.
 
 # Prompt Templates
 
@@ -6,11 +6,11 @@ Prompt templates are Markdown snippets that expand into full prompts. Type `/nam
 
 ## Locations
 
-Pi loads prompt templates from:
+Ada loads prompt templates from:
 
-- Global: `~/.pi/agent/prompts/*.md`
-- Project: `.pi/prompts/*.md` (only after the project is trusted)
-- Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
+- Global: `~/.ada/agent/prompts/*.md`
+- Project: `.ada/prompts/*.md` (only after the project is trusted)
+- Packages: `prompts/` directories or `pi.prompts` entries in `package.json` (the manifest key stays `pi` for compatibility with existing packages)
 - Settings: `prompts` array with files or directories
 - CLI: `--prompt-template <path>` (repeatable)
 

package/docs/providers.md

@@ -1,6 +1,6 @@
 # Providers
 
-Pi supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with pi; configured providers may refresh newer catalogs and cache them in `~/.pi/agent/models-store.json` for offline use.
+Ada supports subscription-based providers via OAuth and API key providers via environment variables or auth file. Built-in catalogs ship with Ada; configured providers may refresh newer catalogs and cache them in `~/.ada/agent/models-store.json` for offline use.
 
 ## Table of Contents
 
@@ -23,7 +23,7 @@ Use `/login` in interactive mode, then select a provider:
 - OpenRouter (OAuth-minted API key billed from OpenRouter credits)
 - Radius
 
-Use `/logout` to clear credentials. Tokens are stored in `~/.pi/agent/auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically.
+Use `/logout` to clear credentials. Tokens are stored in `~/.ada/agent/auth.json` and auto-refresh when expired. OpenRouter instead mints a user-controlled API key that does not expire automatically.
 
 ### OpenAI Codex
 
@@ -63,7 +63,7 @@ Use `/login` in interactive mode and select a provider to store an API key in `a
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
-pi
+ada-cli
 ```
 
 | Provider | Environment Variable | `auth.json` key |
@@ -108,7 +108,7 @@ Reference for environment variables and `auth.json` keys: [`const envMap`](https
 
 #### Auth File
 
-Store credentials in `~/.pi/agent/auth.json`:
+Store credentials in `~/.ada/agent/auth.json`:
 
 ```json
 {
@@ -154,7 +154,7 @@ API key credentials can also include provider-scoped environment values. These v
 }
 ```
 
-Use this when pi should use different provider settings than the project shell environment.
+Use this when Ada should use different provider settings than the project shell environment.
 
 ### Key Resolution
 
@@ -224,14 +224,14 @@ export AWS_REGION=us-west-2
 Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
 
 ```bash
-pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
+ada-cli --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0
 ```
 
 Prompt caching is enabled automatically for Claude models whose ID contains a recognizable model name (base models and system-defined inference profiles). For application inference profiles (whose ARNs don't contain the model name), set `AWS_BEDROCK_FORCE_CACHE=1` to enable cache points:
 
 ```bash
 export AWS_BEDROCK_FORCE_CACHE=1
-pi --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
+ada-cli --provider amazon-bedrock --model arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
 ```
 
 If you are connecting to a Bedrock API proxy, the following environment variables can be used:
@@ -255,7 +255,7 @@ export AWS_BEDROCK_FORCE_HTTP1=1
 export CLOUDFLARE_API_KEY=...           # or use /login
 export CLOUDFLARE_ACCOUNT_ID=...
 export CLOUDFLARE_GATEWAY_ID=...        # create at dash.cloudflare.com → AI → AI Gateway
-pi --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"
+ada-cli --provider cloudflare-ai-gateway --model "claude-sonnet-4-5"
 ```
 
 Routes to OpenAI, Anthropic, and Workers AI through Cloudflare AI Gateway. Workers AI uses the Unified API (`/compat`) and prefixed model IDs (`workers-ai/@cf/...`). OpenAI uses the OpenAI passthrough route (`/openai`) with native OpenAI model IDs such as `gpt-5.1`. Anthropic uses the Anthropic passthrough route (`/anthropic`) with native Anthropic model IDs such as `claude-sonnet-4-5`.
@@ -269,7 +269,7 @@ AI Gateway authentication uses `CLOUDFLARE_API_KEY` as `cf-aig-authorization`. U
 | Stored BYOK | Cloudflare token only | Cloudflare injects provider keys stored in the AI Gateway dashboard |
 | Inline BYOK | Cloudflare token plus upstream `Authorization` header | The request supplies the upstream provider key |
 
-For normal pi usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream `Authorization` header for the Cloudflare AI Gateway provider, for example via a `models.json` provider/model override.
+For normal Ada usage, prefer unified billing or stored BYOK. Inline BYOK requires configuring an additional upstream `Authorization` header for the Cloudflare AI Gateway provider, for example via a `models.json` provider/model override.
 
 ### Cloudflare Workers AI
 
@@ -278,10 +278,10 @@ For normal pi usage, prefer unified billing or stored BYOK. Inline BYOK requires
 ```bash
 export CLOUDFLARE_API_KEY=...           # or use /login
 export CLOUDFLARE_ACCOUNT_ID=...
-pi --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"
+ada-cli --provider cloudflare-workers-ai --model "@cf/moonshotai/kimi-k2.6"
 ```
 
-Pi automatically sets `x-session-affinity` for [prefix caching](https://developers.cloudflare.com/workers-ai/features/prompt-caching/) discounts.
+Ada automatically sets `x-session-affinity` for [prefix caching](https://developers.cloudflare.com/workers-ai/features/prompt-caching/) discounts.
 
 ### Google Vertex AI
 
@@ -297,7 +297,7 @@ Or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key file.
 
 ## llama.cpp
 
-Pi supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage loaded models with `/llama`, and select a loaded model with `/model`.
+Ada supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage loaded models with `/llama`, and select a loaded model with `/model`.
 
 See [llama.cpp](llama-cpp.md) for server setup, model directory layout, environment variables, and command usage.