agents-city 0.3.0-beta.22 → 0.3.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "city",
       "source": "./plugin",
-      "version": "0.3.0-beta.22",
+      "version": "0.3.0",
       "description": "Operate one autonomous city seat, its domain, role, repo support agents, goal, recognised skills and explicit roads to other cities."
     }
   ]

package/README.es.md

@@ -6,7 +6,7 @@
 las que deban hablar.**
 
 ```bash
-npm install -g agents-city@beta
+npm install -g agents-city
 agents-city
 ```
 
@@ -98,22 +98,23 @@ Las fronteras importantes son:
 ### Instalar desde npm
 
 ```bash
-npm install -g agents-city@beta
+npm install -g agents-city
 agents-city --version
 ```
 
+Esto es `0.x` a propósito: los comandos ya se usan hoy, pero los formatos de
+fichero y las APIs todavía pueden cambiar entre versiones menores. Aquí nada
+pretende estar congelado.
+
 Necesitas Node.js 22 o superior, Python 3 y tmux; los detalles están en la
 [tabla de requisitos](#requisitos-base), y `agents-city seat` se ofrece a
 instalar tmux si falta. No se instala nada en el sistema más allá de la carpeta
 global de npm de tu Node activo.
 
-El `@beta` es deliberado: esto es una prerelease, y fijarla significa que una
-futura versión estable no puede cambiarte la máquina sin que tú lo pidas.
-
 ### Probarlo sin instalar nada
 
 ```bash
-npx agents-city@beta
+npx agents-city
 ```
 
 `npx` descarga el paquete en su caché, lo ejecuta y deja intacta tu carpeta
@@ -134,7 +135,7 @@ por debajo, así que ninguno de los dos es el camino "menor".
 ### Actualizar o quitar
 
 ```bash
-npm install -g agents-city@beta   # actualizar a la última beta
+npm install -g agents-city        # actualizar a la última versión
 npm uninstall -g agents-city      # quitar el programa
 ```
 
@@ -197,7 +198,7 @@ Agents City usa el CLI independiente `gh`:
 ### Actualizar una instalación
 
 ```bash
-npm install -g agents-city@beta   # desde el registro
+npm install -g agents-city        # desde el registro
 agents-city --version
 ```
 
@@ -231,7 +232,7 @@ una ciudad concreta.
 
 ## Primer arranque, paso a paso
 
-`agents-city seat` crea `home` si todavía no existe y hace cinco decisiones.
+`agents-city seat` crea `home` si todavía no existe y hace siete preguntas.
 
 ### 1. Dominio de trabajo
 
@@ -255,22 +256,39 @@ opciones incorporadas son:
 Es la responsabilidad del jefe de esa ciudad, no el nombre de la ciudad ni el
 motor. El asiento sigue siendo presidente aunque elijas `blank`.
 
-### 3. Repos y rol de cada agente
-
-Puedes leer repos del disco, de tu cuenta GitHub o de una organización. Cada repo
-seleccionado recibe:
-
-- una ventana tmux;
-- un actor privado del bus;
-- un directorio de trabajo dentro del repo;
-- un rol operativo explícito;
-- las skills que su runtime ya sea capaz de descubrir allí.
-
-El rol del repo puede pertenecer a otro dominio. Ejemplo: una ciudad de software
-puede asignar `po` a un repo de producto, `seo` al portfolio y `data-engineer` a
-un pipeline. Ninguno se convierte en presidente.
-
-Elegir cero repos también es válido: abre una ciudad con sólo su asiento.
+### 3. Los agentes, de uno en uno
+
+Esta es la ciudad en sí, y es un bucle, no una lista de carpetas que marcar. Cada
+agente se pregunta entero, y después se te ofrece otro, hasta que digas que la
+ciudad está completa:
+
+1. **Su nombre** — cómo lo llamas en su ventana, en el mapa y en el bus.
+2. **Qué tipo de trabajo hace** — `code`, `knowledge` o `coordinator`. No es un
+   permiso: decide cómo crece su casa en el mapa, para que a quien trabaja con
+   documentos no se le mida en pull requests.
+3. **Su rol** — su especialidad, del dominio de esta ciudad o de otro. Una ciudad
+   de software puede dar `po` a un agente de producto, `seo` al del portfolio y
+   `data-engineer` al del pipeline. Ninguno se convierte en presidente.
+4. **Todo aquello sobre lo que trabaja** — cuantos repos quiera (leídos del
+   disco, de tu cuenta GitHub o de una organización) **más** cuantas carpetas de
+   documentos quiera. Un agente puede responder por tres servicios y un manual a
+   la vez, y un agente sin git en ninguna parte es un agente de primera. Todo se
+   monta dentro de su workspace, no se convierte en agentes distintos.
+5. **Qué lo ejecuta** — Claude con su propio modelo y esfuerzo, o Codex,
+   OpenCode, Kimi, o un fallback explícito de terminal.
+6. **Las skills con las que empieza** — una carpeta de skill o un `.zip`
+   instalado en la casa de ese agente. Sólo se ofrece para motores que leen
+   skills: a un agente en Codex se le dice que su motor las ignora, en vez de
+   venderle algo que no hace nada.
+
+Cada agente recibe entonces una ventana tmux, un actor privado del bus, su
+workspace como directorio de trabajo y las skills que su runtime ya sea capaz de
+descubrir en lo que monta.
+
+Decir que la ciudad no tiene agentes también es válido: abre con sólo su asiento,
+y las carreteras la conectan con otras ciudades.
+
+Cambia el reparto cuando quieras con `agents-city seat --agents`.
 
 ### 4. Objetivo
 
@@ -286,19 +304,52 @@ Un objetivo puede ser cuantitativo o cualitativo. Guarda:
 
 Puedes omitirlo y configurarlo después con `agents-city seat --goal`.
 
-### 5. Motor de cada ventana
-
-Enter conserva Claude en todas. También puedes elegir por ventana:
+### 5. Motor de tu propia silla
 
-- Claude y, opcionalmente, modelo/esfuerzo;
-- Codex;
-- OpenCode;
-- Kimi;
-- un comando desconocido mediante el fallback explícito de terminal.
+El motor de cada agente ya se decidió sobre el agente, en la pregunta 3. Queda tu
+ventana: la que sostiene el rol de presidente, los comandos `/city:` y el plugin.
+Enter la deja en tu Claude; también puedes elegir Claude con modelo y esfuerzo,
+Codex, OpenCode, Kimi, o un comando desconocido mediante el fallback explícito de
+terminal.
 
 La configuración persistente queda en la ficha del propietario. Los flags
 `--model` y `--effort` de `seat` son overrides sólo para ese arranque.
 
+### 6. Si tu silla pide permiso
+
+Por ciudad, en `city.yml` como `seat_yolo`. En local el asiento son tus propias
+manos en tu propia máquina, así que pedirte permiso en tu propia silla es una
+elección, no una ley. Las ventanas de los agentes conservan su jaula igualmente,
+y arrancar con `--no-yolo` sigue frenando toda la sesión, asiento incluido.
+
+### 7. La ciudad en tu escritorio
+
+Se ofrece una vez, cuando la ciudad es nueva: un acceso directo de verdad con el
+nombre de la ciudad y un icono coloreado a partir de su propia identidad — un
+`.app` en macOS o una entrada `.desktop` en Linux. Doble clic y la ciudad se
+abre.
+
+Ejecuta la misma línea que escribirías tú, así que es un botón etiquetado sobre
+la puerta que ya existe, no una segunda forma de entrar. Añádelo o quítalo cuando
+quieras:
+
+```bash
+agents-city shortcut              # esta ciudad, en tu escritorio
+agents-city shortcut home --hall  # una puerta que abre el mapa en su lugar
+agents-city shortcut --remove     # quitarlo otra vez
+agents-city shortcut --to ~/bin   # en otro sitio que no sea el escritorio
+```
+
+**En Windows** la ciudad vive dentro de WSL, y un `~/Desktop` de WSL es el
+escritorio del home de Linux: uno que nadie mira nunca. Por eso el acceso directo
+se escribe en el escritorio **de Windows**, preguntándoselo a Windows en vez de
+adivinarlo a partir del nombre de usuario (un escritorio redirigido a OneDrive o
+a un perfil de dominio no está bajo `C:\Users\<nombre>\Desktop`). Es un `.lnk` de
+verdad, construido con la propia PowerShell de Windows para que pueda llevar un
+`.ico`, y arranca `wsl.exe` ejecutando el mismo comando en una shell de login. Si
+no hay interoperabilidad, se escribe un `.cmd` que también se abre con doble
+clic: la misma puerta, con icono genérico.
+
 ### Qué se crea
 
 ```text
@@ -442,8 +493,10 @@ agents-city cities
 agents-city road
 agents-city bus
 agents-city committee
+agents-city agents
 agents-city skills
 agents-city city
+agents-city shortcut
 agents-city demo
 agents-city report
 agents-city tokens
@@ -451,6 +504,8 @@ agents-city logs
 agents-city benchmark
 agents-city reset
 agents-city exit
+agents-city doctor
+agents-city update
 agents-city test
 ```
 
@@ -501,6 +556,12 @@ se escriben en el registro de actividad. El token de observador rota con el hub,
 sólo acepta un origen de este ordenador y es de sólo lectura: el navegador no
 puede dirigir el comité. `Ctrl-c` detiene el Hall.
 
+Bajo la marca hay dos botones: **día/noche** e **ES/EN**. El Hall habla español e
+inglés, arranca en el idioma del navegador y recuerda la elección explícita. Las
+traducciones se indexan por la frase en inglés, así que lo que aún no esté
+traducido cae en un inglés legible y no en un identificador — un texto nuevo
+nunca se queda bloqueado esperando a la traducción.
+
 ### `agents-city setup`
 
 Crea o selecciona una ciudad y abre el Hall; con `--tui` entrega el flujo a
@@ -742,6 +803,31 @@ La capacidad real de invocar una skill depende del runtime. Agents City la
 anuncia como capacidad del miembro y deja al proveedor aplicar sus propias reglas
 de descubrimiento y uso.
 
+### `agents-city agents`
+
+Lista los agentes de esta ciudad y gestiona sobre qué trabaja cada uno. Los
+montajes de un agente son symlinks dentro de su workspace, así que esto es el
+equivalente en terminal de la fila **works on** del Hall y de la pregunta 3 del
+asistente.
+
+```bash
+agents-city agents list --card ~/.agents-city/alice/home/alice.md --data ~/.agents-city/alice/home
+agents-city agents mounts --agent urgencias --data ~/.agents-city/alice/home
+agents-city agents mount --agent urgencias --src ~/documentos/manual --data …
+agents-city agents unmount --agent urgencias --name manual --data …
+```
+
+| Comando | Efecto |
+|---|---|
+| `list` | cada agente: nombre, slug, rol, runtime, tipo, directorio de trabajo |
+| `mounts` | los montajes de un agente, como etiqueta y destino real |
+| `mount --src RUTA` | monta un repo, un worktree o una carpeta de documentos |
+| `unmount --name ETIQUETA` | quita ese montaje; la carpeta en sí no se toca |
+| `sync` / `sync-all` | reconstruye los workspaces desde la ficha, como hace el lanzador |
+
+Desmontar quita un symlink y una clave de la ficha. Nunca borra aquello a lo que
+apuntaba el enlace.
+
 ### `agents-city city`
 
 Abre el mapa local de una ciudad, sin arrancar una sesión de agentes.
@@ -769,6 +855,46 @@ clicables, `P` (o el control ⛶) alterna pantalla completa, y el rail en vivo
 del Hall se redimensiona arrastrando su borde. El contrato completo está en
 [docs/map-live-layers.md](docs/map-live-layers.md).
 
+### `agents-city shortcut`
+
+Pone una ciudad en tu escritorio: su nombre, un icono coloreado a partir de su
+propia identidad, y un doble clic que la abre.
+
+```bash
+agents-city shortcut               # la ciudad seleccionada
+agents-city shortcut product       # una concreta
+agents-city shortcut --hall        # una puerta que abre el mapa en vez del asiento
+agents-city shortcut --remove      # quitarlo del escritorio
+agents-city shortcut --to ~/bin    # escribirlo en otro sitio
+```
+
+| Opción | Efecto |
+|---|---|
+| `--hall` | el acceso directo abre el mapa en el navegador en vez de la ciudad tmux |
+| `--remove` | quita el acceso directo de esta ciudad |
+| `--to DIR` | lo escribe en otra carpeta que no sea el escritorio |
+
+Lo que se escribe depende del escritorio, y en cada uno es de verdad, no un
+script disfrazado:
+
+| Plataforma | Acceso directo | Icono |
+|---|---|---|
+| macOS | bundle `.app` que abre la ciudad en Terminal | `.icns`, construido con el `iconutil` del sistema |
+| Linux | entrada `.desktop`, marcada como confiable donde hay `gio` | `.png` bajo `XDG_DATA_HOME` |
+| Windows (WSL) | `.lnk` en el escritorio **de Windows**, que lanza `wsl.exe` | `.ico`, cuando hay interoperabilidad con PowerShell |
+
+Todos ejecutan la misma línea que escribirías tú, así que el acceso directo es un
+botón etiquetado sobre la puerta que ya existe, no una segunda forma de entrar. El
+icono se genera sin ninguna librería de imagen: un PNG escrito a mano, envuelto
+como `.ico` para Windows y convertido con `iconutil` en macOS.
+
+En Windows la ciudad vive dentro de WSL, y un `~/Desktop` de ahí es el escritorio
+del home de Linux que nadie mira: por eso el escritorio de Windows se le pregunta
+a Windows, nunca se arma a partir del nombre de usuario, porque un escritorio
+redirigido a OneDrive o a un perfil de dominio no está bajo
+`C:\Users\<nombre>\Desktop`. Sin interoperabilidad se escribe un `.cmd` que
+también se abre con doble clic: la misma puerta, con icono genérico.
+
 ### `agents-city demo`
 
 Abre una ciudad ficticia y desechable en el Hall completo. El centro contiene
@@ -938,13 +1064,22 @@ demuestra por sí solo mayor calidad de respuesta ni una afirmación SOTA.
 
 ### `agents-city reset`
 
-Reinicia **una** ciudad gestionada conservando su identidad estable y sus repos.
+Reinicia ciudades gestionadas conservando su identidad estable y sus repos.
 
 ```bash
-agents-city reset producto --dry-run
-agents-city reset producto
+agents-city reset product --dry-run   # muestra cada efecto, no cambia nada
+agents-city reset product
+agents-city reset product cliente-a   # varias, separadas por espacios
+agents-city reset all                 # todas las de este propietario
 ```
 
+Un nombre desconocido aborta la ejecución **entera** antes de tocar nada:
+reiniciar tres ciudades y pararse en una errata es el peor final posible para un
+comando destructivo. El Hall tiene lo mismo como botón, en **Cities** — primero
+enseña qué desaparece, qué sobrevive y dónde queda la copia, y te pide escribir
+el nombre de la ciudad.
+
+
 El plan de reset:
 
 1. valida que el destino sea una ciudad gestionada, no una ruta arbitraria;
@@ -975,6 +1110,44 @@ seguir activo. Sin ciudad, muestra o cierra todo lo gestionado por Agents City.
 Una sesión tmux puede contener trabajo sin guardar, por lo que el dry-run es la
 forma segura de comprobar el alcance.
 
+### `agents-city doctor`
+
+Revisa esta máquina y dice qué parte falta, en una pantalla.
+
+```bash
+agents-city doctor
+```
+
+Informa de las herramientas que necesita (python3, tmux, bash, git, node, y `gh`
+como opcional), qué runtimes de agente hay instalados, **qué jaula te da este
+kernel** —seatbelt, bubblewrap, o ninguna y por qué—, la ciudad seleccionada y su
+ficha, si el bundle del Hall está construido, y si hay una versión más nueva
+publicada. Sale con código distinto de cero cuando algo está roto, así que
+también sirve dentro de un script.
+
+Si le pasas un fichero de configuración, conserva su trabajo anterior: detectar
+una forma antigua, explicarla y migrarla con `--fix` (dejando copia de
+seguridad).
+
+### `agents-city update`
+
+```bash
+agents-city update            # instala la versión publicada más nueva
+agents-city update --check    # sólo pregunta: instalada frente a publicada
+agents-city update --tag beta # sigue una dist-tag
+```
+
+La comprobación es **un GET al registro público de npm**, cacheado un día bajo
+`~/.agents-city/.runtime/`. No se envía nada de tu máquina —ni identificador, ni
+contador, ni telemetría— y `CITY_UPDATE_CHECK=0` lo desactiva por completo. Sólo
+ocurre donde has abierto algo deliberadamente: `doctor`, `update` y el Hall (que
+muestra una línea cuando hay versión nueva). Un `agents-city cities` normal no
+toca la red.
+
+Si lo instalaste desde un checkout de git, `update` se niega y te dice el comando
+que encaja con tu instalación, en vez de ejecutar `npm install -g` sobre tu copia
+de trabajo.
+
 ### `agents-city test`
 
 Ejecuta la suite del checkout. Sin argumentos ejecuta todas las suites; con
@@ -1624,7 +1797,7 @@ de vida por mensaje. `bus inbox` consume `road-inbox`, no el historial append-on
 | `AGENTS_CITY_USER` | identidad local resuelta | fuerza el propietario para pruebas/migraciones |
 | `AGENTS_CITY_DATA` | ciudad seleccionada | fuerza una carpeta de ciudad en una terminal externa |
 | `CITY_CODE_DIR` | `~/codigo` | destino de clones aceptados desde GitHub |
-| `CITY_SEARCH_IN` | raíces habituales del home | lista separada por `:` donde buscar repos locales |
+| `CITY_SEARCH_IN` | raíces habituales del home | lista separada por `:` donde buscar (también `;`, para Windows) |
 | `CITY_SEARCH_DEPTH` | `4` | profundidad máxima de esa búsqueda |
 | `AGENTS_CITY_ORG` | vacía | filtra repos por organización; vacía significa todos |
 | `CITY_SETTLE` | `8` | espera inicial, en segundos, para arrancar Claude |
@@ -1634,6 +1807,12 @@ de vida por mensaje. `bus inbox` consume `road-inbox`, no el historial append-on
 | `AGENTS_CITY_URL` | `CITY_BUS_URL` | endpoint de reporting/mapa si está separado |
 | `CITY_DIR` | `~/.claude/channels/city-bus` | carpeta de compatibilidad para `.env` y hooks |
 | `CITY_HOOKS` | `city` | `everywhere` ejecuta los hooks de conciencia en todas las sesiones de Claude, no solo en runtimes de ciudad |
+| `CITY_DESKTOP` | `~/Desktop`, o el escritorio de Windows bajo WSL | dónde escribe `agents-city shortcut` |
+| `CITY_CAGE` | `1` | `0` arranca todas las ventanas sin jaula |
+| `CITY_CAGE_DENY` | vacío | rutas extra que sellar, separadas por `:` |
+| `CITY_CAGE_ALLOW_WRITE` | vacío | rutas extra que mantener escribibles, separadas por `:` |
+| `CITY_UPDATE_CHECK` | `1` | `0` no pregunta nunca a npm si hay versión más nueva |
+| `CITY_CAGE_BWRAP` | se sondea | `1`/`0` responde «¿puede este Linux crear un espacio de nombres?» sin sondear; el lanzador lo fija una vez por ciudad |
 
 Ejemplos:
 
@@ -1649,10 +1828,30 @@ agents-city cities create laboratorio
 CITY_SETTLE=0 CITY_STAGGER=0 agents-city seat --city producto
 ```
 
-El índice de repos locales se cachea un día en
-`$XDG_CACHE_HOME/agents-city/repos.tsv` o `~/.cache/agents-city/repos.tsv`. El Hall
-ofrece refrescarlo. Desde terminal, si cambias `CITY_SEARCH_IN` y la caché aún es
-válida, elimina **sólo ese fichero de índice** y repite `seat --repos`.
+### Qué se le puede dar a una casa para trabajar
+
+`plugin/scripts/busca.py` recorre tu disco una vez e indexa tres clases de sitio:
+
+* **repositorios** — con el nombre de su remoto `origin`, no el de la carpeta en
+  la que están, para que un clon se encuentre por el nombre que dirías en voz
+  alta;
+* **worktrees** — un worktree enlazado es la carpeta en la que de verdad trabaja
+  un agente aislado, y aparece como `repo@rama`, una cosa distinta que elegir;
+* **carpetas de documentos** — un directorio con escritura dentro y sin git por
+  ninguna parte, que es lo que monta un agente `knowledge`.
+
+Lee `.git/config` y `HEAD` directamente en vez de lanzar `git` una vez por
+repositorio, así que un escaneo completo termina mientras alguien mira la
+pantalla, y funciona allí donde funcione Python: macOS, Linux y Windows por
+igual. La guía y el Hall buscan sobre este índice; `plugin/scripts/find-repos.sh`
+es un envoltorio fino para quien lo llama desde shell, y sólo imprime la mitad
+git.
+
+El índice se cachea un día en `$XDG_CACHE_HOME/agents-city/lugares.tsv` o
+`~/.cache/agents-city/lugares.tsv`. Tanto el formulario de casas del Hall como el
+asiento ofrecen refrescarlo; desde terminal, `busca.py --refresh` lo reconstruye,
+que es justo lo que quieres tras cambiar `CITY_SEARCH_IN` con la caché aún
+válida.
 
 Para ajustes de transporte, el orden es:
 
@@ -1696,7 +1895,8 @@ y sólo el primero es yolo. En macOS las ventanas de repo de Claude, OpenCode y
 Kimi arrancan dentro de un perfil seatbelt generado: las escrituras caen sólo en su propio repo y su
 estado de runtime, y los ficheros que convierten una inyección de prompt en un
 robo de credenciales (`~/.ssh`, `~/.git-credentials`, `~/.aws`, configs de gh
-y de nube, tokens de carretera remota) quedan sellados en el kernel — lecturas
+y de nube, tokens de carretera remota, y el propio
+`~/.claude/.credentials.json` de Claude Code) quedan sellados en el kernel — lecturas
 y escrituras, hijos y nietos incluidos. Al agente no se le pregunta nada: las
 rutas prohibidas sencillamente no existen para él. Codex usa en cambio su
 sandbox nativa `workspace-write` y no se envuelve en seatbelt: workers MCP como
@@ -1704,6 +1904,22 @@ sandbox nativa `workspace-write` y no se envuelve en seatbelt: workers MCP como
 proceso ya enjaulado. `CITY_CAGE=0` desactiva de forma deliberada la capa de
 confinamiento aplicable.
 
+**En Linux la jaula es bubblewrap.** El sello se construye como se construye en
+Linux: un espacio de nombres de montaje donde las rutas selladas sencillamente
+no están montadas, así que dentro de la jaula `~/.ssh` es un directorio vacío y
+`~/.git-credentials` se lee como nada. La misma promesa que el seatbelt, con
+otro mecanismo, y `bin/test-cage.py` lo demuestra contra un espacio de nombres
+real en cada ejecución de CI en Linux: la clave plantada no se puede leer, el
+repo sigue siendo escribible, una escritura en un directorio sellado nunca llega
+al disco y un proceso nieto no se escapa.
+
+Necesita `bubblewrap` instalado (`apt install bubblewrap`) y espacios de nombres
+de usuario sin privilegios habilitados — Agents City comprueba que bwrap puede
+crear uno de verdad en vez de fiarse de que exista el binario, y una máquina
+donde no pueda lo dice y arranca sin jaula, exactamente como antes. En otras
+plataformas no hay confinamiento: sin jaula, pon agentes sobre trabajo sobre el
+que te sentirías cómodo ejecutando un script.
+
 Como una ventana enjaulada no puede leer el token de `gh`, los PRs y pushes
 pasan por un broker de credenciales opcional (`CITY_BROKER=1`): un proceso
 pequeño del lado del dueño que guarda las credenciales, acepta tokens por
@@ -1883,8 +2099,8 @@ agents-city seat --repos
 ```
 
 La detección exige `.git` (directorio o fichero de worktree) y un remote `origin`.
-Si acabas de cambiar las raíces, refresca desde el Hall o elimina exclusivamente
-`~/.cache/agents-city/repos.tsv`. `AGENTS_CITY_ORG` puede estar filtrando el repo;
+Si acabas de cambiar las raíces, usa **Buscar otra vez** en el formulario de
+casas, o ejecuta `plugin/scripts/busca.py --refresh`. `AGENTS_CITY_ORG` puede estar filtrando el repo;
 déjala vacía para indexar todos los remotes.
 
 ### GitHub no muestra repos privados u organizaciones