@hoilab/ada-cli 0.84.22 → 0.85.1

package/docs/containerization.md

@@ -1,31 +1,31 @@
 # Containerization
 
-Pi runs with all permissions by default, but in some cases, you will want to have more control over what directories Pi can write to and which accesses it has.
+Ada runs with all permissions by default, but in some cases, you will want to have more control over what directories Ada can write to and which accesses it has.
 
 There are two general options. You can either
-1. run the whole `pi` process inside an isolated environment, or
-2. run `pi` on the host and route tool execution into an isolated environment.
+1. run the whole `ada-cli` process inside an isolated environment, or
+2. run `ada-cli` on the host and route tool execution into an isolated environment.
 
 ## Choose a pattern
 
 | Pattern | What is isolated | Best for | Notes |
 | --- | --- | --- | --- |
 | Gondolin extension | Built-in tools and `!` commands | Local micro-VM isolation while keeping auth on host | See [`examples/extensions/gondolin/`](../examples/extensions/gondolin/). |
-| Plain Docker | Whole `pi` process in a local container | Simple local isolation | Provider API keys enter the container. |
-| OpenShell | Whole `pi` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
+| Plain Docker | Whole `ada-cli` process in a local container | Simple local isolation | Provider API keys enter the container. |
+| OpenShell | Whole `ada-cli` process in a policy-controlled sandbox | Local or remote managed sandbox | Requires an OpenShell gateway |
 
-Extensions run wherever the `pi` process runs. If you run host `pi` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
+Extensions run wherever the `ada-cli` process runs. If you run host `ada-cli` with a tool-routing extension, other custom extension tools still run on the host unless they also delegate their operations.
 
 ## Gondolin
 
 [Gondolin](https://github.com/earendil-works/gondolin) is a local Linux micro-VM.
-Use the [example extension](../examples/extensions/gondolin) when you want `pi` on the host but all built-in tools routed into the VM.
+Use the [example extension](../examples/extensions/gondolin) when you want `ada-cli` on the host but all built-in tools routed into the VM.
 
 Setup:
 
 ```bash
-cp -R packages/coding-agent/examples/extensions/gondolin ~/.pi/agent/extensions/gondolin
-cd ~/.pi/agent/extensions/gondolin
+cp -R packages/coding-agent/examples/extensions/gondolin ~/.ada/agent/extensions/gondolin
+cd ~/.ada/agent/extensions/gondolin
 npm install --ignore-scripts
 ```
 
@@ -33,7 +33,7 @@ Run from the project you want mounted:
 
 ```bash
 cd /path/to/project
-pi -e ~/.pi/agent/extensions/gondolin
+ada-cli -e ~/.ada/agent/extensions/gondolin
 ```
 
 The extension mounts the host cwd at `/workspace` in the VM and overrides `read`, `write`, `edit`, `bash`, `grep`, `find`, and `ls`.
@@ -44,9 +44,9 @@ Requirements: Node.js >= 23.6.0 for `@earendil-works/gondolin`, plus QEMU (requi
 
 ## Plain Docker
 
-Run the whole `pi` process in Docker when you want the simplest local container boundary.
+Run the whole `ada-cli` process in Docker when you want the simplest local container boundary.
 
-`Dockerfile.pi`:
+`Dockerfile.ada`:
 
 ```dockerfile
 FROM node:24-bookworm-slim
@@ -54,27 +54,27 @@ FROM node:24-bookworm-slim
 RUN apt-get update \
   && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
   && rm -rf /var/lib/apt/lists/*
-RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent
+RUN npm install -g --ignore-scripts @hoilab/ada-cli
 
 WORKDIR /workspace
-ENTRYPOINT ["pi"]
+ENTRYPOINT ["ada-cli"]
 ```
 
 Build and run:
 
 ```bash
-docker build -t pi-sandbox -f Dockerfile.pi .
+docker build -t ada-sandbox -f Dockerfile.ada .
 
 docker run --rm -it \
   -e ANTHROPIC_API_KEY \
   -v "$PWD:/workspace" \
-  -v pi-agent-home:/root/.pi/agent \
-  pi-sandbox
+  -v ada-agent-home:/root/.ada/agent \
+  ada-sandbox
 ```
 
 The `-v "$PWD:/workspace"` mounts your current directory into the container at /workspace such that reads and writes in `/workspace` inside Docker directly affect your host files, like in the Gondolin example.
 
-Use a named volume for `/root/.pi/agent` if you want container-local settings and sessions. Mounting your host `~/.pi/agent` exposes host auth and session files to the container.
+Use a named volume for `/root/.ada/agent` if you want container-local settings and sessions. Mounting your host `~/.ada/agent` exposes host auth and session files to the container.
 
 ## OpenShell
 
@@ -89,23 +89,23 @@ openshell gateway add <gateway-url> --name <name>
 openshell gateway select <name>
 ```
 
-Launch `pi` inside an OpenShell sandbox:
+Launch `ada-cli` inside an OpenShell sandbox:
 
 ```bash
-openshell sandbox create --name pi-sandbox --from pi -- pi
+openshell sandbox create --name ada-sandbox --from ada -- ada-cli
 ```
 
-In this pattern, the whole `pi` process runs inside the sandbox.
+In this pattern, the whole `ada-cli` process runs inside the sandbox.
 Built-in tools, `!` commands, and extension tools execute inside the OpenShell boundary.
 
 If the gateway is remote, project files are not bind-mounted from the host, meaning writes in the sandbox are not reflected on your machine.
 Clone the repository inside the sandbox or use OpenShell file transfer commands:
 
 ```bash
-openshell sandbox upload pi-sandbox ./repo /workspace
-openshell sandbox download pi-sandbox /workspace/repo ./repo-out
+openshell sandbox upload ada-sandbox ./repo /workspace
+openshell sandbox download ada-sandbox /workspace/repo ./repo-out
 ```
 
 OpenShell providers can keep raw model API keys outside the sandbox.
 When inference routing is configured, code inside the sandbox can call `https://inference.local`, and the gateway injects the configured provider credentials upstream.
-Configure Pi to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.
+Configure Ada to use the corresponding OpenAI-compatible or Anthropic-compatible endpoint if you want model traffic to use this route.

package/docs/custom-provider.md

@@ -30,7 +30,7 @@ See these complete provider examples:
 
 ## Quick Reference
 
-Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Pi composes `models.json` overrides above registered native providers.
+Extensions can register either a complete pi-ai `Provider` or use the legacy provider-config form. Prefer a complete provider when custom authentication, filtering, refresh, or streaming behavior is required. Ada composes `models.json` overrides above registered native providers.
 
 ```typescript
 import { createProvider, openAICompletionsApi } from "@earendil-works/pi-ai";
@@ -88,7 +88,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. pi waits for the factory before startup continues, so the provider is available during interactive startup and to `pi --list-models`.
+The extension factory can also be `async`. For dynamic model discovery, fetch and register models in the factory instead of `session_start`. Ada waits for the factory before startup continues, so the provider is available during interactive startup and to `ada-cli --list-models`.
 
 ## Override Existing Provider
 
@@ -239,7 +239,7 @@ models: [{
   id: "custom-model",
   // ...
   reasoning: true,
-  thinkingLevelMap: {              // map pi levels to provider values; null hides unsupported levels
+  thinkingLevelMap: {              // map Ada levels to provider values; null hides unsupported levels
     minimal: null,
     low: null,
     medium: null,
@@ -382,7 +382,7 @@ interface OAuthLoginCallbacks {
 
 ### OAuthCredentials
 
-Credentials are persisted in `~/.pi/agent/auth.json`:
+Credentials are persisted in `~/.ada/agent/auth.json`:
 
 ```typescript
 interface OAuthCredentials {
@@ -566,14 +566,14 @@ calculateCost(model, output.usage);
 
 ### Context Overflow Errors
 
-When a request exceeds the model's context window, pi can recover automatically by compacting the conversation and retrying. This recovery only kicks in if pi recognizes the failure as an overflow.
+When a request exceeds the model's context window, Ada can recover automatically by compacting the conversation and retrying. This recovery only kicks in if Ada recognizes the failure as an overflow.
 
 Detection runs on the finalized assistant message:
 
 - `stopReason === "error"`
-- `errorMessage` matches one of pi's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
+- `errorMessage` matches one of Ada's known overflow patterns (see [`packages/ai/src/utils/overflow.ts`](https://github.com/earendil-works/pi-mono/blob/main/packages/ai/src/utils/overflow.ts))
 
-If your provider returns overflow errors with a message pi does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase pi recognizes. The generic fallback `context_length_exceeded` is the safest choice.
+If your provider returns overflow errors with a message Ada does not recognize, normalize the error from the same extension that registers the provider. Use a `message_end` handler to rewrite the assistant message so its `errorMessage` starts with a phrase Ada recognizes. The generic fallback `context_length_exceeded` is the safest choice.
 
 ```typescript
 const MY_PROVIDER_OVERFLOW_PATTERN = /your provider's overflow phrase/i;
@@ -605,7 +605,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-`message_end` runs before pi tracks the assistant message for auto-compaction, so the rewritten `errorMessage` is what pi checks. With this in place, pi will:
+`message_end` runs before Ada tracks the assistant message for auto-compaction, so the rewritten `errorMessage` is what Ada checks. With this in place, Ada will:
 
 1. Detect the overflow from `errorMessage`.
 2. Drop the failed assistant message from live context.
@@ -615,7 +615,7 @@ export default function (pi: ExtensionAPI) {
 Guard the rewrite carefully:
 
 - Scope it to your provider (`message.provider` and `ctx.model?.provider`) so unrelated errors from other providers are untouched.
-- Match a provider-specific pattern, not pi's generic overflow patterns. Rewriting rate-limit or throttling errors (`rate limit`, `too many requests`) would falsely trigger compaction instead of pi's normal retry-with-backoff path.
+- Match a provider-specific pattern, not Ada's generic overflow patterns. Rewriting rate-limit or throttling errors (`rate limit`, `too many requests`) would falsely trigger compaction instead of Ada's normal retry-with-backoff path.
 - Skip when `errorMessage` already includes `context_length_exceeded` so the handler is idempotent.
 
 ### Registration
@@ -713,7 +713,7 @@ interface ProviderModelConfig {
   /** Whether the model supports extended thinking. */
   reasoning: boolean;
 
-  /** Maps pi thinking levels to provider/model-specific values; null marks a level unsupported. */
+  /** Maps Ada thinking levels to provider/model-specific values; null marks a level unsupported. */
   thinkingLevelMap?: Partial<Record<"off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max", string | null>>;
 
   /** Supported input types. */

package/docs/development-fork.md

@@ -0,0 +1,170 @@
+# Desarrollo del fork: cómo trabajar con este proyecto
+
+Este repositorio es un **fork de pi.dev** (earendil-works/pi) rebrandeado como **ada-cli**. Su regla de diseño principal es mantenerse en lockstep con upstream mediante un sync diario determinista, y esa regla condiciona todo lo demás: dónde vive el código nuevo, cuánto puedes tocar los ficheros de upstream y qué comprueba la build antes de dejarte commitear. Esta página explica cómo trabajar con el proyecto sin leerse el código.
+
+## Requisitos e instalación local
+
+Requiere **Node ≥ 22.19** (y **bun** solo para construir el binario standalone).
+
+```bash
+git clone https://github.com/HOILAB/ada-cli
+cd ada-cli
+npm install        # dependencias del monorepo
+npm run build      # construye todos los paquetes (JS)
+```
+
+Tres formas de ejecutarlo:
+
+- **Binario global desde el monorepo:**
+  ```bash
+  cd packages/coding-agent
+  npm install -g .   # instala el binario ada-cli globalmente
+  ada-cli --version  # → 0.84.2
+  ```
+- **Binario standalone** (no necesita Node en runtime):
+  ```bash
+  cd packages/coding-agent
+  npm run build:binary       # produce dist/ada
+  sudo cp dist/ada /usr/local/bin/ada
+  ```
+- **Desde fuente**, sin instalar nada:
+  ```bash
+  /ruta/al/repo/pi-test.sh   # se puede llamar desde cualquier directorio; respeta tu cwd
+  ```
+
+La app de escritorio (`desktop/`, Tauri 2 + Next.js) usa **el mismo SDK publicado en npm** (`@hoilab/ada-cli@<versión>`), no un tarball ni `file:` — las rutas `file:` rompen la externalización de webpack del build de Next:
+
+```bash
+cd desktop
+npm install
+npm run desktop:dev     # ventana Tauri en desarrollo
+npm run desktop:build   # .app/.dmg/.exe de producción
+```
+
+## Los gates: qué valida `npm run check`
+
+`npm run check` es la puerta de entrada de todo commit. Encadena estas comprobaciones (cada una existe por un fallo concreto que ya ocurrió):
+
+| Gate | Qué valida |
+|---|---|
+| `biome check --write --error-on-warnings .` | Formato y lint; reescribe lo formateable y falla con cualquier warning |
+| `check:pinned-deps` | Todas las dependencias (`dependencies`, `devDependencies`, `optionalDependencies`) usan versión exacta `x.y.z` — sin rangos `^` ni `~` |
+| `check:ts-imports` | Los imports relativos terminan en **`.ts`**, nunca `.js` (el código corre con Node strip-only mode, sin emit) |
+| `tsgo --noEmit` | Tipado de todo el monorepo |
+| `check:browser-smoke` | Humo de navegador sobre paquetes de UI |
+| `check:dist-assets` | Los assets que el paquete publicado promete están en `dist/` |
+| `check:desktop` | Typecheck de la app de escritorio |
+| `check:cargas` | Banco de cargas (`test/banco-cargas.test.ts`): herramientas de edición aplicando cargas reales sin corrupción |
+| `check:bytes-fuente` | No hay bytes de control (p. ej. `\0`) en el `.ts`: un byte NUL convierte el fichero en «binario» para git diff y grep, y el código desaparece de toda búsqueda |
+| `check:arranque` | El CLI arranca perezoso: mide tiempo y número de módulos cargados para responder, y falla si alguien reintroduce un import estático en la cadena `cli.ts -> atajos.ts` |
+| `check:fork-budget` | El presupuesto de hunks upstream no ha crecido (`./scripts/sync-ada.sh --check`; hoy **163/163**) |
+| `check:licencias` | Inventario de licencias + SBOM CycloneDX; una dependencia sin licencia declarada **falla** (fail-closed), no sale en verde |
+| `check:docs` | Documentación e índice inseparables: (1) todo `path` de `docs.json` existe, (2) todo fichero de `docs/` está indexado salvo excepciones declaradas con motivo, (3) los enlaces relativos entre páginas (incluidas anclas) apuntan a algo |
+| `check:imports-runtime` | Todo lo que el código importa en producción está en `dependencies`, no solo en `devDependencies` — en el árbol de trabajo funciona, en una instalación limpia da `ERR_MODULE_NOT_FOUND` |
+| `check:shrinkwrap` / `check:install-lock:coding-agent` | El shrinkwrap e install-lock generados están sincronizados con el lock raíz |
+
+Además, el hook **husky pre-commit** ejecuta antes de cada commit:
+
+1. `check-lockfile-commit.mjs` — bloquea commits que toquen el lockfile salvo `PI_ALLOW_LOCKFILE_CHANGE=1`.
+2. `npm run check` completo.
+3. `check:browser-smoke` extra si tocas `packages/ai/*`, `packages/web-ui/*`, `package.json` o `package-lock.json`.
+4. Re-stagea los ficheros que el formateador haya modificado.
+
+Para correr los gates: `npm run check` desde la raíz (salida completa, sin colas). No commitees con `--no-verify`. Cada gate también tiene su script individual (`npm run check:docs`, etc.) para iterar rápido.
+
+## El presupuesto de hunks upstream (163/163)
+
+El fork se reconstruye en cada sync como `main = upstream/main + delta_hoilab`. Por eso, **cada hunk que llevamos en un fichero que upstream también edita es coste de conflicto que pagamos en cada sync futuro, para siempre**. Esa es la restricción de diseño número uno del fork.
+
+Cómo se mide:
+
+```bash
+./scripts/sync-ada.sh --check    # mide y sale, sin tocar nada (no hace fetch)
+ADA_SYNC_HUNK_BUDGET=170 ./scripts/sync-ada.sh   # subir el techo puntualmente en un sync
+```
+
+Qué cuenta y qué no:
+
+- Se mide **en vivo** contra el merge-base con `upstream/main` (`git diff`), no contra `scripts/ada-rebrand.patch`, que es una referencia regenerada que va por detrás del delta real.
+- Solo cuentan ficheros que **existen en upstream**: los nuestros (`workflows/`, `memory-engine/`, `core/proveedores-registry/`, …) aplican limpios siempre y no pueden conflictuar.
+- Solo cuentan **fuentes** (`packages/*/src/`): docs y tests de upstream que rebrandeamos son conflictos triviales que el propio script reaplica; mezclarlos escondería el número que importa detrás de ruido.
+- El umbral es un **trinquete fijado en la medida real** (163/163), no un número redondo: el siguiente hunk añadido a un fichero de upstream rompe el sync y obliga a una decisión explícita, en vez de colarse.
+
+Cuándo es legítimo subir el presupuesto: cuando el cambio **no puede vivir en un fichero nuestro** (un punto de registro, un gate de sesión, el único punto donde ocurre una escritura) y aporta más de lo que cuesta mantenerlo contra los refactors futuros de upstream. Cuándo no: por comodidad o para desbloquear un sprint. Antes de subirlo, comprobar siempre si el cambio puede reescribirse como fichero adicional — casi siempre puede (un barril de exports, una extensión cargada con `-e`, un early return agrupado). Ejemplos reales de ambas decisiones están documentados en ADA-CLI.md (el cliente LSP se enganchó gratis vía `-e`; el cifrado en reposo de `auth.json` compró su hunk porque llegar tarde al camino de lectura habría dejado al CLI sin autenticación).
+
+Si sube, hay que **documentarlo en el mismo commit**, en dos sitios:
+
+1. El historial de subidas en los comentarios de `scripts/sync-ada.sh` (función `check_sync_budget`): de → a, y por qué este cambio no podía ser aditivo.
+2. La tabla equivalente en `ADA-CLI.md` (raíz).
+
+Un presupuesto sin dueño acaba siempre subido en vez de cuestionado.
+
+Nota importante: parte del crecimiento histórico fue **deriva de upstream**, no decisiones nuestras — upstream refactoriza un fichero que no tocábamos y nuestro delta aflora ahí. El guard mide las dos cosas igual; distingüelas al documentar.
+
+## Reglas del fork
+
+1. **0 hunks por defecto.** Todo cambio nuevo vive primero en ficheros nuestros bajo `packages/coding-agent/src/core/`. Un hunk en un fichero de upstream se compra solo con justificación escrita (ver sección anterior).
+2. **Ownership por directorio para trabajo paralelo.** Cuando varios agentes/persona trabajan a la vez, cada uno es dueño de su directorio bajo `src/core/` y nadie edita el ajeno. Las fronteras cruzadas (wiring en ficheros de upstream, índices compartidos como `docs/docs.json`) se serializan en un único punto.
+3. **Commit seriado único.** El trabajo aterriza en commits convencionales seriados; el sync diario captura el delta commiteado y lo reaplica — lo que no está commiteado no viaja (y el sync con árbol sucio se niega a correr para no destruirlo).
+4. **`erasableSyntaxOnly`** (raíz: `tsconfig.base.json`): el código de `packages/*/src`, `packages/*/test` y ejemplos corre con Node strip-only mode. Prohibido: parameter properties (`constructor(private x)`), `enum`, `namespace`/`module`, `import =`/`export =`, cualquier construcción que necesite emit de JS. Usa campos explícitos con asignación en el constructor.
+5. **Imports relativos con extensión `.ts`** (gate `check:ts-imports`).
+6. **`Record` sobre `Map`/`Set` estáticos**: para tablas declarativas conocidas en tiempo de escritura (catálogos, registros), usa objetos `Record` tipados — dan completitud compile-time y son triviales de inspeccionar; `Map`/`Set` quedan para estado mutable en runtime.
+7. Sin emojis en commits, issues, PRs ni código.
+
+## Convenciones de test
+
+Los tests en `packages/coding-agent/test/` siguen tres reglas duras, nacidas de fallos repetidos:
+
+- **Ambos halves.** Una prueba que solo comprueba una AUSENCIA, o que compara dos estados vacíos, da verde también con el código roto. Toda prueba debe tener su caso positivo y su caso negativo juntos: exige que la marca exista *antes* de comprobar que no se reescribe; comprueba el caso revocado junto al válido.
+- **Tres estados.** Donde el dominio lo pide (aprobaciones, dispositions de seguridad), el test cubre los tres estados del contrato — aprobado, denegado, y pendiente/desconocido — no solo el binario feliz.
+- **Prueba de mutación.** Tras escribir las pruebas, rompe temporalmente el mecanismo (quita el arreglo, invierte la condición), confirma que SUS tests caen, y restaura. Un test que sigue verde con el control roto no mide nada. Es también el procedimiento del checklist de auditoría (docs/COMPLIANCE-AUDIT.md §16) para cualquier control que parezca débil.
+
+Ejecutar tests:
+
+```bash
+cd packages/coding-agent
+./test.sh                          # tests sin LLM (no necesitan API keys)
+npm test                           # todos
+tsx --test test/<fichero>.test.ts  # uno concreto
+```
+
+## Cómo añadir un módulo nuevo
+
+1. **Crea el módulo como fichero(s) propios** bajo `packages/coding-agent/src/core/<tu-modulo>/`. Coste de presupuesto: cero.
+2. **Cabecera docstring obligatoria** explicando POR QUÉ existe, qué problema resuelve, qué NO hace y sus límites declarados. Es la fuente de verdad de la documentación de usuario: quien no lee el código tiene que poder confiar solo en la cabecera. Mira cualquier módulo existente (p. ej. `core/proveedores-registry/index.ts`) como plantilla.
+3. **Test** en `packages/coding-agent/test/` siguiendo las convenciones de arriba (ambos halves + prueba de mutación si guarda un control de seguridad).
+4. **Wiring sin tocar upstream siempre que exista la vía:**
+   - Tools nuevas: expórtalas desde tu módulo y cárgalas como **extensión** con `-e`:
+     ```bash
+     ada-cli -e packages/coding-agent/src/core/lsp/extension.ts ...
+     ```
+     Así funciona hoy el cliente LSP: cuatro tools (`lsp_rename`, `lsp_symbols`, `lsp_definition`, `lsp_references`) dadas de alta con `pi.registerTool` sin gastar un solo hunk. El día que haya margen, migrar a builtin es una línea en `builtInExtensions` y tu fichero no cambia.
+   - Exports públicos nuevos: agrúpalos en un barril propio (patrón `src/ada-publico.ts`) en lugar de dispersar exports por ficheros de upstream.
+5. Si NINGUNA vía gratuita sirve (el enganche debe ocurrir en un punto del ciclo de vida de upstream, antes de que algo ya haya leído estado), entonces — y solo entonces — compra el hunk con su documentación (sección del presupuesto).
+6. **Documenta**: página en `packages/coding-agent/docs/` + entrada en `docs.json`. El gate `check:docs` no te deja commitear una sin la otra.
+
+## Cómo añadir un proveedor
+
+El registro de proveedores es declarativo: `packages/coding-agent/src/core/proveedores-registry/`. Añadir un proveedor es **una entrada en `PROVIDERS`** (en `definiciones.ts`), con completitud comprobada en compile-time:
+
+- familia de API, baseUrl por defecto,
+- modelos con contexto y costes,
+- auth como **referencia a la variable de entorno — nunca el valor**,
+- features soportadas.
+
+De ahí salen gratis el resolver por modelo, el listado y el puente con discovery de runtimes (`resolverPorBaseUrl` resuelve endpoints descubiertos contra la tabla). No toques `resolver.ts` ni `tipos.ts` salvo que el tipo del proveedor no quepa en el esquema existente.
+
+## Commits
+
+Formato convencional, mensaje en español, informativo y conciso:
+
+```
+{feat,fix,docs}[(ai,tui,agent,coding-agent)]: <mensaje>
+```
+
+Reglas:
+
+- Commitea **solo los ficheros que cambiaste tú en esta sesión**: revisa `git status` antes de `git add`. Nunca `git add -A` ni `git add .`, nunca `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash` ni `--no-verify`.
+- El mensaje dice qué incluye el cambio y, si toca un hunk de upstream o sube el presupuesto, por qué no pudo ser aditivo — y actualiza la cifra en `sync-ada.sh` + `ADA-CLI.md` en el mismo commit.
+- Si tu commit toca ficheros citados en `docs/COMPLIANCE-AUDIT.md`, actualiza el mapa en el mismo commit.
+- Sin emojis.

package/docs/development.md

@@ -1,12 +1,12 @@
 # Development
 
-See [AGENTS.md](https://github.com/earendil-works/pi-mono/blob/main/AGENTS.md) for additional guidelines.
+See [AGENTS.md](../../../AGENTS.md) for additional guidelines.
 
 ## Setup
 
 ```bash
-git clone https://github.com/earendil-works/pi-mono
-cd pi-mono
+git clone https://github.com/HOILAB/ada-cli
+cd ada-cli
 npm install
 npm run build
 ```
@@ -14,25 +14,25 @@ npm run build
 Run from source:
 
 ```bash
-/path/to/pi-mono/pi-test.sh
+/path/to/ada-cli/pi-test.sh
 ```
 
-The script can be run from any directory. Pi keeps the caller's current working directory.
+The script can be run from any directory. Ada keeps the caller's current working directory.
 
 ## Forking / Rebranding
 
-Configure via `package.json`:
+Configure via `package.json`. Ada CLI itself is a rebrand of upstream pi driven entirely by these fields:
 
 ```json
 {
   "piConfig": {
-    "name": "pi",
-    "configDir": ".pi"
+    "name": "ada-cli",
+    "configDir": ".ada"
   }
 }
 ```
 
-Change `name`, `configDir`, and `bin` field for your fork. Affects CLI banner, config paths, and environment variable names.
+Change `name`, `configDir`, and the `bin` field for your fork. Affects CLI banner, config paths, and environment variable names (`name` uppercased with dashes as underscores produces `ADA_CLI_CODING_AGENT_DIR`).
 
 ## Path Resolution
 
@@ -48,7 +48,7 @@ Never use `__dirname` directly for package assets.
 
 ## Debug Command
 
-`/debug` (hidden) writes to `~/.pi/agent/pi-debug.log`:
+`/debug` (hidden) writes to `~/.ada/agent/ada-cli-debug.log`:
 - Rendered TUI lines with ANSI codes
 - Last messages sent to the LLM
 
@@ -60,6 +60,43 @@ npm test                          # Run all tests
 npm test -- test/specific.test.ts # Run specific test
 ```
 
+## Releasing
+
+`npm run publish:dry` runs every gate and reports exactly what would be
+published. It is safe and worth running first — it is how the two problems below
+were found before they cost anything.
+
+Only `@hoilab/ada-cli` is published. The other eight public workspace packages
+carry upstream's scope (`@earendil-works/*`) and this account has no publish
+rights over them, so `getPublicWorkspacePackages` filters them out. Bumping them
+is also wrong: their versions track upstream, and raising them breaks the desktop
+app, which resolves its own copy from the registry and then sees two different
+`Agent` types. Bump only ours.
+
+### Two things that will stop you
+
+**1. Provenance needs CI.** `scripts/publish.mjs` passes `--provenance`, which
+signs a verifiable link between the tarball and the commit that produced it. npm
+can only generate it from a CI runner with OIDC; run locally it fails with:
+
+```
+npm error Automatic provenance generation not supported for provider: null
+```
+
+Publishing without it is not equivalent — the package ships with no attestation
+of what code it came from, which for a product sold on its chain of custody is a
+real downgrade rather than a formality. The intended path is to push the tag and
+let `build-binaries.yml` publish: it already has `id-token: write`.
+
+**2. The release workflow still contains upstream's announcement job.**
+`announce-pi-dev-release` uploads artifacts to upstream's `pi-artifacts` R2
+bucket using `PI_ARTIFACTS_R2_*` secrets that do not exist in this repository, so
+it fails — and `publish-github-release` depends on it, so the GitHub release
+never gets published even though npm publishing already succeeded. It is the same
+call-home-to-a-third-party that was removed from the product, still present in
+the pipeline. Removing that job and its `needs:` entry is a prerequisite for a
+clean tagged release.
+
 ## Project Structure
 
 ```

package/docs/docs.json

@@ -12,7 +12,7 @@
           "path": "quickstart.md"
         },
         {
-          "title": "Using Pi",
+          "title": "Using Ada",
           "path": "usage.md"
         },
         {
@@ -23,6 +23,10 @@
           "title": "Security",
           "path": "security.md"
         },
+        {
+          "title": "Compliance",
+          "path": "compliance.md"
+        },
         {
           "title": "Containerization",
           "path": "containerization.md"
@@ -42,6 +46,14 @@
         {
           "title": "Compaction",
           "path": "compaction.md"
+        },
+        {
+          "title": "Environment variables",
+          "path": "environment-variables.md"
+        },
+        {
+          "title": "llama.cpp",
+          "path": "llama-cpp.md"
         }
       ]
     },
@@ -65,7 +77,7 @@
           "path": "themes.md"
         },
         {
-          "title": "Pi Packages",
+          "title": "Ada Packages",
           "path": "packages.md"
         },
         {
@@ -133,9 +145,34 @@
         }
       ]
     },
+    {
+      "title": "Módulos del fork",
+      "items": [
+        {
+          "title": "Motor: contexto, colaboración y medición",
+          "path": "modules-motor.md"
+        },
+        {
+          "title": "Seguridad: secretos, cifrado, parches y privacidad",
+          "path": "modules-seguridad.md"
+        },
+        {
+          "title": "Infraestructura: brokers, terminal, GC, perfiles",
+          "path": "modules-infraestructura.md"
+        },
+        {
+          "title": "Producto: marketplace, registry, commits, cleanse",
+          "path": "modules-producto.md"
+        }
+      ]
+    },
     {
       "title": "Development",
       "items": [
+        {
+          "title": "Desarrollo del fork",
+          "path": "development-fork.md"
+        },
         {
           "title": "Development",
           "path": "development.md"

package/docs/environment-variables.md

@@ -1,25 +1,27 @@
 # Environment Variables
 
-Pi uses environment variables in three ways:
+Ada uses environment variables in three ways:
 
-- Variables such as `PI_OFFLINE` configure the Pi process.
-- Pi sets process markers so child processes can identify Pi as the launching agent.
+- Variables such as `PI_OFFLINE` configure the Ada process.
+- Ada sets process markers so child processes can identify Ada as the launching agent.
 - Commands run by the LLM-callable bash tool receive `PI_*` variables describing the current session.
 
+Most variable names keep the `PI_` prefix for compatibility with the upstream pi ecosystem — extensions, packages, and tooling written against pi read these exact names. Only the config and session directory overrides are Ada-specific.
+
 Provider API-key variables are documented separately in [Providers](providers.md#environment-variables-or-auth-file).
 
 ## Process Marker
 
 The CLI and RPC entry points set two process markers:
 
-- `AI_AGENT=pi` is a generic marker that lets tooling identify Pi as the agent that launched the process.
-- `PI_CODING_AGENT=true` is Pi-specific and lets child processes detect that they run inside Pi.
+- `AI_AGENT=pi` is a generic marker that lets tooling identify the agent that launched the process.
+- `PI_CODING_AGENT=true` lets child processes detect that they run inside Ada.
 
-Child processes inherit both markers. They are not session-specific and are not set automatically when Pi is embedded through the SDK.
+Child processes inherit both markers. They are not session-specific and are not set automatically when Ada is embedded through the SDK.
 
 ## Bash Tool Session Environment
 
-Commands run by the bash tool receive the current Pi session state:
+Commands run by the bash tool receive the current Ada session state:
 
 | Variable | Description |
 |----------|-------------|
@@ -29,7 +31,7 @@ Commands run by the bash tool receive the current Pi session state:
 | `PI_MODEL` | Currently selected model ID |
 | `PI_REASONING_LEVEL` | Current effective reasoning level: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max` |
 
-The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting Pi. `PI_PROVIDER` and `PI_MODEL` identify the selected Pi model, not a different upstream model that a router may choose internally.
+The values are resolved when each command starts. Switching models or changing the reasoning level therefore affects the next bash command without restarting Ada. `PI_PROVIDER` and `PI_MODEL` identify the model selected in Ada, not a different upstream model that a router may choose internally.
 
 When asked which model or provider is running, inspect these variables instead of inferring the answer from the system prompt:
 
@@ -50,7 +52,7 @@ These variables are injected into the LLM-callable bash tool. They are not injec
 
 ### Custom Bash Tools
 
-Bash tools created with `createBashTool()` expose the session environment by default when registered with Pi. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
+Bash tools created with `createBashTool()` expose the session environment by default when registered with Ada. Injection happens before `spawnHook`, so a hook receives the variables in `ctx.env`:
 
 ```typescript
 const bashTool = createBashTool(cwd, {
@@ -70,22 +72,23 @@ const bashTool = createBashTool(cwd, {
 });
 ```
 
-When disabled, Pi removes inherited values for these variables so nested Pi processes do not expose stale parent-session metadata.
+When disabled, Ada removes inherited values for these variables so nested Ada processes do not expose stale parent-session metadata.
 
-## Pi Process Configuration
+## Ada Process Configuration
 
-These variables are read by Pi itself:
+These variables are read by Ada itself:
 
 | Variable | Description |
 |----------|-------------|
-| `PI_CODING_AGENT_DIR` | Override the config directory; default is `~/.pi/agent` |
-| `PI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
+| `ADA_CLI_CODING_AGENT_DIR` | Override the config directory; default is `~/.ada/agent` |
+| `ADA_CLI_CODING_AGENT_SESSION_DIR` | Override session storage; overridden by `--session-dir` |
 | `PI_PACKAGE_DIR` | Override the package directory, useful for Nix/Guix store paths |
-| `PI_OFFLINE` | Disable startup network operations, including update checks, package updates, and install/update telemetry |
+| `PI_OFFLINE` | Disable startup network operations, including update checks and package updates. (Ada sends no install telemetry — see [settings](settings.md#telemetry-and-update-checks).) |
 | `PI_SKIP_VERSION_CHECK` | Disable the `pi.dev` latest-version request |
-| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no` |
+| `ADA_MUESTREO_RESTRINGIDO` | Decodificación restringida: `1` la enciende sin activar el resto de lo experimental, `0` la apaga aunque `PI_EXPERIMENTAL=1`. Apagada por defecto — ver [Compliance](compliance.md#constrained-decoding) |
+| `PI_TELEMETRY` | **Inert.** Used to override the install ping and the default attribution headers; both were removed, so this variable no longer changes anything |
 | `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
-| `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `ADA_SHARE_VIEWER_URL` | Override the base URL used by `/share`; `PI_SHARE_VIEWER_URL` is still accepted as a fallback |
 | `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
 | `PI_TUI_ESC_TIMEOUT` | How long to wait after a lone ESC before treating it as Escape, in milliseconds; defaults to `100` over SSH and `10` otherwise. Increase if Alt-key input is misread as Escape |
 | `VISUAL`, `EDITOR` | External editor fallback when `externalEditor` is unset |