agents-city 0.3.0-beta.21 → 0.3.0-beta.22

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "city",
       "source": "./plugin",
-      "version": "0.3.0-beta.21",
+      "version": "0.3.0-beta.22",
       "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

@@ -5,6 +5,14 @@
 **Ejecuta varias ciudades autónomas de agentes en una máquina y conecta sólo
 las que deban hablar.**
 
+```bash
+npm install -g agents-city@beta
+agents-city
+```
+
+Esa es toda la instalación. El segundo comando abre el ayuntamiento en tu
+navegador y te acompaña a crear tu primera ciudad.
+
 Agents City es un orquestador local y multimodelo para trabajo con repositorios.
 Cada ciudad tiene una identidad, un dominio, un asiento principal, un objetivo,
 agentes de apoyo por repo, conocimiento editable, skills reconocidas en vivo y
@@ -87,53 +95,65 @@ Las fronteras importantes son:
 
 ## Inicio rápido
 
-### Ahora mismo: experiencia npm real sin publicar
-
-Empaquetar primero es importante: prueba exactamente la lista de ficheros que
-recibiría una persona desde npm, no el checkout completo.
+### Instalar desde npm
 
 ```bash
-cd /ruta/al/checkout/agents-city
-npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g agents-city@beta
 agents-city --version
-agents-city seat
 ```
 
-No hace falta ejecutar `npm publish`. La instalación anterior es global sólo en
-tu versión activa de Node.
+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.
 
-### Instalación desde el registro cuando esté disponible
+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.
 
-Comprueba primero la disponibilidad y los dist-tags:
+### Probarlo sin instalar nada
 
 ```bash
-npm view agents-city dist-tags --json
+npx agents-city@beta
 ```
 
-Si devuelve `E404`, usa el tarball local de la sección anterior. Cuando el
-registro muestre un dist-tag `beta`, la instalación será:
+`npx` descarga el paquete en su caché, lo ejecuta y deja intacta tu carpeta
+global de npm — la forma más rápida de ver si esto es para ti.
+
+### Después: el Hall, o el terminal
 
 ```bash
-npm install -g agents-city@beta
-agents-city --version
-agents-city seat
+agents-city        # el ayuntamiento en el navegador (igual que: agents-city hall)
+agents-city seat   # el asistente en terminal, si prefieres no salir de la shell
 ```
 
-Usa `@beta` mientras sea prerelease. `npm install -g agents-city` sin tag debe
-reservarse para el futuro release estable marcado como `latest`.
+El Hall se sirve en `127.0.0.1`, elige un puerto libre y abre el navegador. Allí
+puedes crear o seleccionar una ciudad, editar su configuración, ajustar el motor
+de cada agente y ver el mapa en vivo. El Hall y el CLI usan los mismos módulos
+por debajo, así que ninguno de los dos es el camino "menor".
 
-### Abrir el Hall en vez del terminal
+### Actualizar o quitar
 
 ```bash
-agents-city
-# equivalente a:
-agents-city hall
+npm install -g agents-city@beta   # actualizar a la última beta
+npm uninstall -g agents-city      # quitar el programa
 ```
 
-El Hall se sirve en `127.0.0.1`, usa un puerto libre y abre el navegador. Desde
-allí puedes crear o seleccionar una ciudad y editar su configuración usando los
-mismos módulos que usa el CLI.
+Desinstalar deja `~/.agents-city`, tus ciudades y tus repos exactamente donde
+están: el programa no son tus datos.
+
+### Instalar desde el código fuente
+
+Para quien contribuye, y para quien quiera leer el código antes de ejecutarlo.
+Empaquetar primero es la prueba honesta: ejercita exactamente la lista de
+ficheros que recibe una persona desde npm, no tu copia de trabajo entera.
+
+```bash
+git clone https://github.com/jlcases/agents-city.git
+cd agents-city
+npm pack
+npm install -g ./agents-city-*.tgz
+agents-city --version
+```
 
 ## Requisitos e instalación
 
@@ -174,15 +194,19 @@ Agents City usa el CLI independiente `gh`:
 
 `gh` no va dentro del paquete npm de Agents City.
 
-### Actualizar una instalación local
+### Actualizar una instalación
 
 ```bash
-cd /ruta/al/checkout/agents-city
-npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g agents-city@beta   # desde el registro
 agents-city --version
 ```
 
+Desde un checkout del código, empaqueta e instala el tarball:
+
+```bash
+cd /ruta/al/checkout/agents-city && npm pack && npm install -g ./agents-city-*.tgz
+```
+
 Las sesiones ya abiertas conservan el código cargado en memoria. Para aplicar la
 nueva versión a una ciudad:
 
@@ -1205,7 +1229,7 @@ asiento; nunca adquiere autoridad para ordenar directamente a un repo local.
 ```bash
 cd /ruta/al/checkout/agents-city
 npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g ./agents-city-*.tgz
 agents-city seat
 ```
 
@@ -1479,7 +1503,7 @@ de razonamiento»; una autenticación fallida tampoco se cuenta como muestra rá
 ```bash
 cd /ruta/al/checkout/agents-city
 npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g ./agents-city-*.tgz
 agents-city --version
 agents-city exit producto --dry-run
 agents-city exit producto
@@ -1986,7 +2010,7 @@ npm pack --dry-run
 npm pack
 
 CITY_TEST_PREFIX="$(mktemp -d)"
-npm install -g --prefix "$CITY_TEST_PREFIX" ./agents-city-0.3.0-beta.21.tgz
+npm install -g --prefix "$CITY_TEST_PREFIX" ./agents-city-*.tgz
 "$CITY_TEST_PREFIX/bin/agents-city" --version
 "$CITY_TEST_PREFIX/bin/agents-city" --help
 ```

package/README.md

@@ -5,6 +5,14 @@
 **Run several autonomous agent cities on one machine, and connect only the
 cities that should talk.**
 
+```bash
+npm install -g agents-city@beta
+agents-city
+```
+
+That is the whole installation. The second command opens the town hall in your
+browser and walks you through creating your first city.
+
 Agents City is a local-first, multi-model orchestrator for repository work. Each
 city has its own identity, domain, chair seat, goal, repo support agents,
 editable knowledge, live-recognised skills, and explicit roads to other cities.
@@ -85,53 +93,65 @@ The important boundaries are:
 
 ## Quick start
 
-### Right now: the real npm experience without publishing
-
-Packing first matters: this tests the exact file list a person would receive
-from npm, not the whole checkout.
+### Install from npm
 
 ```bash
-cd /path/to/agents-city
-npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g agents-city@beta
 agents-city --version
-agents-city seat
 ```
 
-You do not need to run `npm publish`. The installation is global only for your
-currently active Node installation.
+You need Node.js 22+, Python 3 and tmux; the
+[requirements table](#base-requirements) has the details, and `agents-city seat`
+offers to install tmux when it is missing. Nothing is installed system-wide
+beyond the npm global folder of your active Node installation.
 
-### Registry installation once available
+`@beta` is deliberate: this is a prerelease, and pinning it means a future
+stable release cannot change your machine without you asking for it.
 
-Check availability and dist-tags first:
+### Try it without installing anything
 
 ```bash
-npm view agents-city dist-tags --json
+npx agents-city@beta
 ```
 
-If it returns `E404`, use the local tarball in the previous section. Once the
-registry shows a `beta` dist-tag, install it with:
+`npx` downloads the package into its cache, runs it, and leaves your global npm
+folder untouched — the fastest way to see whether this is for you.
+
+### Then: the Hall, or the terminal
 
 ```bash
-npm install -g agents-city@beta
-agents-city --version
-agents-city seat
+agents-city        # the town hall in your browser (same as: agents-city hall)
+agents-city seat   # the terminal wizard, if you prefer not to leave the shell
 ```
 
-Use `@beta` while this is a prerelease. Bare `npm install -g agents-city` should
-be reserved for the future stable release carrying the `latest` tag.
+The Hall listens on `127.0.0.1`, chooses a free port, and opens the browser. You
+can create or select a city, edit its configuration, tune each agent's engine
+and watch the live map there. The Hall and the CLI use the same underlying
+modules, so neither is the "lesser" path.
 
-### Open the Hall instead of the terminal wizard
+### Update, or remove
 
 ```bash
-agents-city
-# equivalent to:
-agents-city hall
+npm install -g agents-city@beta   # update to the newest beta
+npm uninstall -g agents-city      # remove the program
 ```
 
-The Hall listens on `127.0.0.1`, chooses a free port, and opens the browser. You
-can create or select a city and edit its configuration there. The Hall and CLI
-use the same underlying modules.
+Uninstalling leaves `~/.agents-city`, your cities and your repositories exactly
+where they are: the program is not your data.
+
+### Install from a source checkout instead
+
+For contributors, and for anyone who wants to read the code before running it.
+Packing first is the honest test: it exercises the exact file list a person
+receives from npm, not your whole working copy.
+
+```bash
+git clone https://github.com/jlcases/agents-city.git
+cd agents-city
+npm pack
+npm install -g ./agents-city-*.tgz
+agents-city --version
+```
 
 ## Requirements and installation
 
@@ -172,15 +192,19 @@ onboarding, Agents City uses the separate `gh` CLI:
 
 `gh` is not bundled inside the Agents City npm package.
 
-### Update a local installation
+### Update an installation
 
 ```bash
-cd /path/to/agents-city
-npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g agents-city@beta   # from the registry
 agents-city --version
 ```
 
+From a source checkout, pack and install the tarball instead:
+
+```bash
+cd /path/to/agents-city && npm pack && npm install -g ./agents-city-*.tgz
+```
+
 Already-running sessions retain the code loaded in memory. To apply the new
 version to one city:
 
@@ -1194,7 +1218,7 @@ it never gains authority to command a local repo directly.
 ```bash
 cd /path/to/agents-city
 npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g ./agents-city-*.tgz
 agents-city seat
 ```
 
@@ -1466,7 +1490,7 @@ authentication failure is not counted as a fast sample.
 ```bash
 cd /path/to/agents-city
 npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g ./agents-city-*.tgz
 agents-city --version
 agents-city exit product --dry-run
 agents-city exit product
@@ -1964,7 +1988,7 @@ npm pack --dry-run
 npm pack
 
 CITY_TEST_PREFIX="$(mktemp -d)"
-npm install -g --prefix "$CITY_TEST_PREFIX" ./agents-city-0.3.0-beta.21.tgz
+npm install -g --prefix "$CITY_TEST_PREFIX" ./agents-city-*.tgz
 "$CITY_TEST_PREFIX/bin/agents-city" --version
 "$CITY_TEST_PREFIX/bin/agents-city" --help
 ```

package/bin/test-contracts.py

@@ -435,7 +435,6 @@ def documentacion_publica():
     runtime, or release without documenting it in both supported languages.
     """
     print('  bilingual public documentation')
-    package = json.load(open(os.path.join(RAIZ, 'package.json'), encoding='utf-8'))
     public_commands = [
         'hall', 'seat', 'cities', 'road', 'bus', 'committee', 'benchmark',
         'reset', 'skills', 'city', 'demo', 'setup', 'report', 'tokens', 'exit',
@@ -499,9 +498,17 @@ def documentacion_publica():
         afirma(f'· {filename} carries eighteen reproducible use cases',
                content.count(cookbook_prefix) == 18,
                f'found {content.count(cookbook_prefix)}')
-        afirma(f'· {filename} tracks the package release used by its tarball examples',
-               package['version'] in content,
-               f"README has no {package['version']}")
+        # The install instructions must not name a versioned tarball. They used
+        # to, and every release left a README telling newcomers to install a
+        # file that no longer existed — so the contract was "repeat the current
+        # version everywhere". A glob cannot go stale, which is the better
+        # answer: what is pinned here is that nobody re-introduces the trap.
+        tarballs_fijos = re.findall(r'agents-city-\d[\w.\-]*\.tgz', content)
+        afirma(f'· {filename} installs by glob, never a tarball name that goes stale',
+               not tarballs_fijos, 'pinned: ' + ', '.join(sorted(set(tarballs_fijos))))
+        afirma(f'· {filename} opens with the one command that installs from npm',
+               'npm install -g agents-city@beta' in content.split('## ')[0],
+               'the first screen does not show the npm install line')
         afirma(f'· {filename} links to the other language',
                '[Español](README.es.md)' in content and '[English](README.md)' in content)
         afirma(f'· {filename} shows the real city identity key',

package/bin/test-seat.py

@@ -509,7 +509,7 @@ def maquinas_hostiles():
         "· an old cached Claude plugin is updated through Claude's own CLI",
         llamadas
         and llamadas[0][:4] == ["claude", "plugin", "update", "city@agents-city"]
-        and "0.3.0-beta.21" in salida.getvalue(),
+        and "0.3.0-beta.22" in salida.getvalue(),
         f"calls={llamadas!r} output={salida.getvalue()!r}",
     )
 

package/docs/testing.md

@@ -149,7 +149,7 @@ temporary prefix before touching a global installation:
 ```bash
 npm pack
 PREFIX=$(mktemp -d)
-npm install -g --prefix "$PREFIX" ./agents-city-0.3.0-beta.21.tgz
+npm install -g --prefix "$PREFIX" ./agents-city-*.tgz
 "$PREFIX/bin/agents-city" --version
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-city",
-  "version": "0.3.0-beta.21",
+  "version": "0.3.0-beta.22",
   "description": "Run autonomous agent cities: one chair seat, role-aware repo agents, repo-owned skills, and explicit roads.",
   "bin": {
     "agents-city": "bin/agents-city.js"

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "city",
   "displayName": "Agents City",
-  "version": "0.3.0-beta.21",
+  "version": "0.3.0-beta.22",
   "description": "One autonomous city seat with a work domain, role, goal, repo support agents, recognised skills and explicit roads to other cities.",
   "author": {
     "name": "jlcases",

package/plugin/channel/bus.js

@@ -20100,7 +20100,7 @@ try {
 }
 var chair = Boolean(context && context.actors[actor]?.role === "chair" && actor === "seat");
 var server = new Server(
-  { name: "agents-city-bus", version: "0.3.0-beta.21" },
+  { name: "agents-city-bus", version: "0.3.0-beta.22" },
   {
     capabilities: {
       ...channelEnabled ? { experimental: { "claude/channel": {} } } : {},

package/plugin/channel/bus.ts

@@ -24,7 +24,7 @@ try {
 
 const chair = Boolean(context && context.actors[actor]?.role === 'chair' && actor === 'seat');
 const server = new Server(
-  { name: 'agents-city-bus', version: '0.3.0-beta.21' },
+  { name: 'agents-city-bus', version: '0.3.0-beta.22' },
   {
     capabilities: {
       ...(channelEnabled ? { experimental: { 'claude/channel': {} } } : {}),

package/plugin/channel/runtime/codex.ts

@@ -67,7 +67,7 @@ export class CodexConnector implements RuntimeConnector {
       async (method, params) => this.providerRequest(method, params),
     );
     await this.rpc.request('initialize', {
-      clientInfo: { name: 'agents-city', title: 'Agents City', version: '0.3.0-beta.21' },
+      clientInfo: { name: 'agents-city', title: 'Agents City', version: '0.3.0-beta.22' },
       capabilities: { experimentalApi: true },
     });
     await this.rpc.notify('initialized');

package/plugin/channel/runtime-gateway.js

@@ -4894,7 +4894,7 @@ var CodexConnector = class {
       async (method, params) => this.providerRequest(method, params)
     );
     await this.rpc.request("initialize", {
-      clientInfo: { name: "agents-city", title: "Agents City", version: "0.3.0-beta.21" },
+      clientInfo: { name: "agents-city", title: "Agents City", version: "0.3.0-beta.22" },
       capabilities: { experimentalApi: true }
     });
     await this.rpc.notify("initialized");