agents-city 0.3.0-beta.21 → 0.3.0

package/city/web/src/bienvenida.ts

@@ -0,0 +1,686 @@
+/**
+ * First run: a city, built by answering five short questions.
+ *
+ * What was here before was a checklist on a page of statistics about a city
+ * that did not exist yet, and the Hall opened on a map with nothing to draw —
+ * "Not drawn yet" as a first impression. A person arriving for the first time
+ * does not need a dashboard. They need to be told, in their own words, what
+ * this thing is and what to do next.
+ *
+ * So: one question per screen, plain language, every jargon word explained the
+ * first time it appears, and nothing mandatory except the two decisions the
+ * product genuinely cannot invent — what kind of work happens here, and who
+ * does it. Everything is skippable and everything is re-editable afterwards
+ * from the same pages that own it, because this flow writes through the very
+ * same endpoints those pages use. It is a guide, not a second implementation.
+ */
+
+import { plural, t as _ } from './idioma';
+import { ESFUERZOS, MODELOS, RUNTIMES, opciones } from './motores';
+
+export interface Dominio {
+  id: string;
+  name: string;
+  summary: string;
+}
+export interface Rol {
+  id: string;
+  name: string;
+  summary: string;
+  trade: string;
+}
+export interface RepoDelDisco {
+  nombre: string;
+  ruta: string;
+  /** repo · worktree · docs — a house can be given any of the three. */
+  clase: string;
+  cuando: string;
+  /** Touched recently, so almost certainly what this person came to pick. */
+  mio: boolean;
+}
+
+/** What the onboarding needs from the Hall. Passed in rather than imported, so
+ * this file cannot quietly grow its own way of talking to the server. */
+export interface Puerta {
+  api: <T>(ruta: string, opts?: RequestInit) => Promise<T>;
+  esc: (s: unknown) => string;
+  aviso: (texto: string, malo?: boolean) => void;
+  refresca: () => Promise<void>;
+  /** Leave the guide and open a normal Hall section. */
+  vete: (seccion: string) => void;
+  ciudad: string;
+  yo: string;
+  datos: string;
+}
+
+interface AgenteNuevo {
+  nombre: string;
+  clase: string;
+  rol: string;
+  montajes: string[];
+  /** Which CLI runs it, and — on Claude — the engine and how hard it thinks.
+   * Empty means the owner's default, which is a real answer and the one most
+   * people should give. Asked here because it is a decision somebody has
+   * already made in their head while naming the house; making them find three
+   * dropdowns afterwards is making them say it twice. */
+  runtime: string;
+  modelo: string;
+  esfuerzo: string;
+}
+
+const CLASES: Array<[string, string, string]> = [
+  [
+    'code',
+    'It writes code',
+    'Its house grows with the pull requests it merges. Mounts repositories and worktrees.',
+  ],
+  [
+    'knowledge',
+    'It keeps knowledge',
+    'Its house grows with the documents it writes. Needs no git at all.',
+  ],
+  ['coordinator', 'It coordinates', 'Its house grows with the decisions it records.'],
+];
+
+/** One glyph per kind of place, so a chip says what it is without a legend. */
+const CLASE_CORTA: Record<string, string> = { repo: 'git', worktree: 'wt', docs: 'doc' };
+
+const PASOS = ['Welcome', 'The work', 'Your chair', 'The houses', 'Ready'];
+
+/** A house, drawn rather than shipped: the same isometric shape the map and the
+ * desktop icon use, so the first thing somebody sees is already the product. */
+function casita(color: string): string {
+  return `<svg viewBox="0 0 120 108" role="img" aria-label="an isometric house" class="bvCasa">
+    <polygon points="60,10 112,40 60,70 8,40" fill="${color}" opacity=".95"/>
+    <polygon points="8,40 60,70 60,100 8,70" fill="${color}" opacity=".62"/>
+    <polygon points="112,40 60,70 60,100 112,70" fill="${color}" opacity=".40"/>
+  </svg>`;
+}
+
+export class Bienvenida {
+  private paso = 0;
+  private dominios: Dominio[] = [];
+  private roles: Rol[] = [];
+  private rolesDeAgente: Rol[] = [];
+  private repos: RepoDelDisco[] = [];
+  private dominio = '';
+  private rol = '';
+  private roster: AgenteNuevo[] = [];
+  private enCurso: AgenteNuevo | null = null;
+  private guardando = false;
+  private buscandoRepos = false;
+  private reposListos = false;
+  /** What is typed in the mount search box, kept across repaints. */
+  private filtro = '';
+  private lienzo: HTMLElement | null = null;
+
+  constructor(private readonly p: Puerta) {}
+
+  /** Draw the current step into `lienzo`. The only entry point. */
+  async pinta(lienzo: HTMLElement): Promise<void> {
+    this.lienzo = lienzo;
+    if (!this.dominios.length) {
+      lienzo.innerHTML = '<p class="cargando">reading the domain packs</p>';
+      const [d, ra] = await Promise.all([
+        this.p.api<{ domains: Dominio[] }>('/api/domains'),
+        this.p.api<{ roles: Rol[] }>('/api/roles?scope=agent'),
+      ]);
+      this.dominios = d.domains;
+      this.rolesDeAgente = ra.roles;
+    }
+    lienzo.innerHTML = `<div class="bv">${this.cabecera()}${await this.cuerpo()}</div>`;
+    this.enlaza(lienzo);
+  }
+
+  private cabecera(): string {
+    const puntos = PASOS.map(
+      (nombre, i) =>
+        `<span class="bvPunto ${i === this.paso ? 'aqui' : i < this.paso ? 'hecho' : ''}"
+          title="${this.p.esc(_(nombre))}"><i></i>${this.p.esc(_(nombre))}</span>`,
+    ).join('');
+    return `<div class="bvPasos">${puntos}</div>`;
+  }
+
+  private async cuerpo(): Promise<string> {
+    switch (this.paso) {
+      case 0:
+        return this.pantallaHola();
+      case 1:
+        return this.pantallaDominio();
+      case 2:
+        return await this.pantallaRol();
+      case 3:
+        return this.pantallaAgentes();
+      default:
+        return this.pantallaFinal();
+    }
+  }
+
+  // ── 0. what this is ────────────────────────────────────────────────────────
+  private pantallaHola(): string {
+    return `
+      <div class="bvHola">
+        <div class="bvArte">${casita('#7048e8')}${casita('#45b9a7')}${casita('#f2674a')}</div>
+        <div>
+          <span class="sub">welcome</span>
+          <h1>${_('A city is you, and the houses around you')}</h1>
+          <p class="prosa">${_(`You take the chair. Around it, one <b>house</b> per worker — an
+          <b>agent</b> — each with its own window, its own role and its own corner of your
+          disk: a repository, three of them, a folder of documents, whatever it actually
+          works on. The map draws them as houses that grow with the work done in them, and
+          many houses are a city. They never talk to each other behind your back: you chair,
+          they answer.`)}</p>
+          <p class="prosa">${_('Everything lives as plain files in {donde}. Nothing leaves this machine, there is no account, and you can edit any of it by hand afterwards.', { donde: `<code class="mono">${this.p.esc(this.p.datos)}</code>` })}</p>
+          <p class="prosa">${_('<b>Four questions and you are working.</b> You can skip any of them and change everything later.')}</p>
+          <div class="bvBotones">
+            <button class="bt ppal" data-bv="siguiente">${_('Let’s build it')}</button>
+            <button class="bt" data-bv="salir">${_('I’ll set it up myself')}</button>
+          </div>
+        </div>
+      </div>`;
+  }
+
+  // ── 1. the domain ─────────────────────────────────────────────────────────
+  private pantallaDominio(): string {
+    const tarjetas = this.dominios
+      .map(
+        (d) => `
+      <button class="bvOpcion ${this.dominio === d.id ? 'elegida' : ''}" data-bv="dominio"
+        data-id="${this.p.esc(d.id)}">
+        <b>${this.p.esc(d.name)}</b><span>${this.p.esc(d.summary)}</span></button>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">${_('question 1 of 4')}</span>
+        <h1>${_('What kind of work happens here?')}</h1>
+        <p class="prosa">${_(`It decides the vocabulary, the roles you will be offered and what
+        counts as evidence in a decision. A clinic does not ship pull requests, and a law
+        firm does not measure story points. Pick the closest one — you can change it later.`)}</p>
+        <div class="bvRejilla">${tarjetas}</div>
+        <div class="bvBotones">
+          <button class="bt" data-bv="atras">${_('Back')}</button>
+          <button class="bt ppal" data-bv="siguiente" ${this.dominio ? '' : 'disabled'}>${_('Next')}</button>
+        </div>
+      </div>`;
+  }
+
+  // ── 2. your chair ─────────────────────────────────────────────────────────
+  private async pantallaRol(): Promise<string> {
+    if (!this.roles.length || this.roles[0]?.id === undefined) {
+      const r = await this.p.api<{ roles: Rol[] }>(
+        '/api/roles?domain=' + encodeURIComponent(this.dominio),
+      );
+      this.roles = r.roles;
+    }
+    const tarjetas = this.roles
+      .map(
+        (r) => `
+      <button class="bvOpcion ${this.rol === r.id ? 'elegida' : ''}" data-bv="rol"
+        data-id="${this.p.esc(r.id)}">
+        <b>${this.p.esc(r.name)}</b><span>${this.p.esc(r.summary || r.trade)}</span></button>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">${_('question 2 of 4')}</span>
+        <h1>${_('And what are you, here?')}</h1>
+        <p class="prosa">${_(`You chair this city whatever you answer — this is your
+        <b>speciality</b>, not your authority. It shapes the perspective you bring to a
+        decision and the knowledge files the city writes for you. <b>Blank</b> is a real
+        answer: it means no preset knowledge.`)}</p>
+        <div class="bvRejilla">${tarjetas}</div>
+        <div class="bvBotones">
+          <button class="bt" data-bv="atras">${_('Back')}</button>
+          <button class="bt ppal" data-bv="siguiente" ${this.rol ? '' : 'disabled'}>Next</button>
+        </div>
+      </div>`;
+  }
+
+  // ── 3. the agents ─────────────────────────────────────────────────────────
+  private pantallaAgentes(): string {
+    // The repository index is a disk scan — a minute on a big home the first
+    // time. Awaiting it here froze the guide on the PREVIOUS screen with no
+    // explanation: the person clicks Next and nothing happens. So the step
+    // draws immediately and the list arrives when it arrives.
+    this.buscaReposUnaVez();
+    if (!this.enCurso) return this.listaDeAgentes();
+    return this.formularioDeAgente(this.enCurso);
+  }
+
+  private buscaReposUnaVez(otraVez = false): void {
+    if (this.buscandoRepos || (this.reposListos && !otraVez)) return;
+    this.buscandoRepos = true;
+    void this.p
+      .api<{ repos: RepoDelDisco[] }>(
+        '/api/misrepos?user=' + encodeURIComponent(this.p.yo) + (otraVez ? '&refresh=1' : ''),
+      )
+      .then((r) => {
+        // The whole index is kept, not a slice of it: the search box below is
+        // what makes a thousand places usable, and a list cut at two hundred
+        // would quietly fail to find the one somebody typed the name of.
+        this.repos = r.repos ?? [];
+      })
+      .catch(() => {
+        this.repos = []; // no index is not a reason to block the flow
+      })
+      .finally(() => {
+        this.buscandoRepos = false;
+        this.reposListos = true;
+        // Only repaint if this step is still on screen.
+        if (this.lienzo && this.paso === 3) void this.pinta(this.lienzo);
+      });
+  }
+
+  private listaDeAgentes(): string {
+    const fichas = this.roster
+      .map(
+        (a) => `
+      <div class="bvFicha">
+        <b>${this.p.esc(a.nombre)}</b>
+        <span>${this.p.esc(a.clase)} · ${this.p.esc(a.rol)}</span>
+        <span class="de">${
+          a.montajes.length
+            ? this.p.esc(a.montajes.map((m) => m.split('/').pop()).join(', '))
+            : _('nothing mounted yet')
+        }</span>
+      </div>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">${_('question 3 of 4')}</span>
+        <h1>${_(this.roster.length ? 'Who else lives here?' : 'Who lives in your city?')}</h1>
+        <p class="prosa">${_(`Every house holds one worker — an <b>agent</b> — with its own window,
+        its own role and its own corner of your disk. A house is <b>not</b> a repository: one
+        can answer for three services and a folder of documents at once, and a house whose
+        work is documents needs no git anywhere.`)}</p>
+        ${this.roster.length ? `<div class="bvFichas">${fichas}</div>` : ''}
+        <div class="bvBotones">
+          <button class="bt ppal" data-bv="nuevo">${_(
+            this.roster.length ? 'Add another house' : 'Build the first house',
+          )}</button>
+          <button class="bt" data-bv="siguiente">${_(
+            this.roster.length ? 'That is everyone' : 'Skip — just me for now',
+          )}</button>
+        </div>
+      </div>`;
+  }
+
+  /**
+   * The places on this disk worth offering for this house, ranked.
+   *
+   * With nothing typed it is what you touched recently, because on a machine
+   * with three hundred clones a list is not an answer. What is typed matches
+   * the name and the path both — people look for `rankia` and for `Documents`
+   * with equal frequency, and only one of those is a repository name. A house
+   * that keeps knowledge sees document folders first, because that is the one
+   * kind of agent the old picker could not help at all.
+   */
+  private buscaEnElDisco(a: AgenteNuevo): RepoDelDisco[] {
+    const q = this.filtro.trim().toLowerCase();
+    const quiereDocs = a.clase === 'knowledge';
+    const puntua = (r: RepoDelDisco): number =>
+      (r.clase === 'docs' ? (quiereDocs ? -2 : 1) : 0) + (r.mio ? -1 : 0);
+    const encaja = q
+      ? this.repos.filter(
+          (r) => r.nombre.toLowerCase().includes(q) || r.ruta.toLowerCase().includes(q),
+        )
+      : this.repos.filter((r) => r.mio);
+    // A mount already chosen stays visible even when the search moves past it,
+    // so unticking never means hunting for it again.
+    const elegidas = this.repos.filter((r) => a.montajes.includes(r.ruta) && !encaja.includes(r));
+    return elegidas
+      .concat(encaja)
+      .sort((x, y) => puntua(x) - puntua(y))
+      .slice(0, 40);
+  }
+
+  private formularioDeAgente(a: AgenteNuevo): string {
+    const clases = CLASES.map(
+      ([id, titulo, porque]) => `
+      <button class="bvOpcion ${a.clase === id ? 'elegida' : ''}" data-bv="clase" data-id="${id}">
+        <b>${_(titulo)}</b><span>${_(porque)}</span></button>`,
+    ).join('');
+    const roles = this.rolesDeAgente
+      .map(
+        (r) =>
+          `<option value="${this.p.esc(r.id)}"${r.id === a.rol ? ' selected' : ''}>${this.p.esc(
+            r.name,
+          )}</option>`,
+      )
+      .join('');
+    const esClaude = (a.runtime || 'claude') === 'claude';
+    const encontrados = this.buscaEnElDisco(a);
+    const sugeridos = encontrados
+      .map(
+        (r) => `<button class="bvChip cl-${this.p.esc(r.clase)} ${
+          a.montajes.includes(r.ruta) ? 'elegida' : ''
+        }"
+          data-bv="monta" data-ruta="${this.p.esc(r.ruta)}"
+          title="${this.p.esc(r.ruta)}${r.cuando ? ` · ${this.p.esc(r.cuando)}` : ''}"
+          ><i class="bvClase">${this.p.esc(CLASE_CORTA[r.clase] ?? r.clase)}</i>${this.p.esc(
+            r.nombre,
+          )}</button>`,
+      )
+      .join('');
+    return `
+      <div class="bvPaso">
+        <span class="sub">${_('a new house')}</span>
+        <h1>${_('Who lives in it?')}</h1>
+        <div class="campo"><label>${_('What do you call it?')}</label>
+          <input type="text" id="bvNombre" value="${this.p.esc(a.nombre)}"
+            placeholder="${_('urgencias, api, the handbook — whatever you would say out loud')}"></div>
+        <label class="bvEtiqueta">${_('What kind of work does it do?')}</label>
+        <div class="bvRejilla bvTres">${clases}</div>
+        <div class="campo"><label>${_('Its role — its speciality, never authority')}</label>
+          <select id="bvRol">${roles}</select></div>
+        <label class="bvEtiqueta">${_('What runs it?')}</label>
+        <p class="pista">${_(
+          'Leave all three on default and it runs the way you do. Model and effort are Claude’s to read; another CLI carries its own flags.',
+        )}</p>
+        <div class="bvMotor">
+          <div class="campo"><label>${_('provider')}</label>
+            <select id="bvRuntime">${opciones(RUNTIMES, a.runtime, this.p.esc, 'claude')}</select></div>
+          <div class="campo"><label>${_('engine')}</label>
+            <select id="bvModelo" ${esClaude ? '' : 'disabled'}>${opciones(
+              [''].concat(MODELOS),
+              a.modelo,
+              this.p.esc,
+              _('default'),
+            )}</select></div>
+          <div class="campo"><label>${_('effort')}</label>
+            <select id="bvEsfuerzo" ${esClaude ? '' : 'disabled'}>${opciones(
+              [''].concat(ESFUERZOS),
+              a.esfuerzo,
+              this.p.esc,
+              _('default'),
+            )}</select></div>
+        </div>
+        <label class="bvEtiqueta">${_('What does it work on?')}</label>
+        <p class="pista">${_(`Everything found on this disk: <b>repositories</b>, the
+        <b>worktrees</b> an isolated agent works in, and <b>folders of documents</b> with no git
+        at all. Pick as many as you like — this is the part that makes it an agent and not a
+        repo.`)}</p>
+        <div class="bvBuscador">
+          <input type="search" id="bvBusca" value="${this.p.esc(this.filtro)}"
+            placeholder="${_('search your disk — a name, or part of a path')}">
+          <button class="bt bvMini" data-bv="rebusca" ${this.buscandoRepos ? 'disabled' : ''}
+            title="${_('Look through the disk again — for something cloned a minute ago')}">${_(
+              this.buscandoRepos ? 'searching…' : 'Search again',
+            )}</button>
+        </div>
+        ${
+          sugeridos
+            ? `<div class="bvChips">${sugeridos}</div>
+               <p class="pista">${
+                 this.filtro
+                   ? _('{shown} of {total} places match', {
+                       shown: String(encontrados.length),
+                       total: String(this.repos.length),
+                     })
+                   : _('{total} places found — type to narrow it down', {
+                       total: String(this.repos.length),
+                     })
+               }</p>`
+            : this.buscandoRepos
+              ? `<p class="cargando">${_('looking through your disk…')}</p>`
+              : this.filtro
+                ? `<p class="pista">${_('Nothing matches that. Add it by path below.')}</p>`
+                : `<p class="pista">${_('Nothing found on this disk — add folders by path below.')}</p>`
+        }
+        <div class="campo"><label>${_('…or a path, and Enter')}</label>
+          <input type="text" id="bvRuta" placeholder="~/documents/handbook"></div>
+        ${
+          a.montajes.length
+            ? `<p class="pista">${_('Working on: {que}', { que: `<b>${this.p.esc(a.montajes.join(', '))}</b>` })}</p>`
+            : ''
+        }
+        <div class="bvBotones">
+          <button class="bt" data-bv="cancela">${_('Cancel')}</button>
+          <button class="bt ppal" data-bv="guarda" ${this.guardando ? 'disabled' : ''}>${_(
+            this.guardando ? 'building…' : 'Build it',
+          )}</button>
+        </div>
+      </div>`;
+  }
+
+  // ── 4. done ───────────────────────────────────────────────────────────────
+  private pantallaFinal(): string {
+    return `
+      <div class="bvPaso">
+        <span class="sub">${_('Ready').toLowerCase()}</span>
+        <h1>${_('{city} is alive', { city: this.p.esc(this.p.ciudad) })}</h1>
+        <p class="prosa">${_(
+          'Your seat is written and {cuantas}. Everything you just answered is a plain file you can read and edit.',
+          {
+            cuantas: this.roster.length
+              ? plural(
+                  this.roster.length,
+                  '<b>{n}</b> house stands around it',
+                  '<b>{n}</b> houses stand around it',
+                )
+              : _('the city is waiting for its first house'),
+          },
+        )}</p>
+        <p class="prosa">${_('What people usually do next:')}</p>
+        <div class="bvSiguientes">
+          <button class="bt ppal" data-bv="sesion">${_('Open my session')}</button>
+          <button class="bt" data-bv="ir-gente">${_('See the houses')}</button>
+          <button class="bt" data-bv="ir-mapa">${_('Draw the map')}</button>
+          <button class="bt" data-bv="ir-puesto">${_('Set a goal')}</button>
+        </div>
+        <p class="pista">${_(`A goal is optional, and the city works without one — but a round with
+        no goal is a status report, because there is nothing to argue against.`)}</p>
+      </div>`;
+  }
+
+  // ── wiring ────────────────────────────────────────────────────────────────
+  private enlaza(lienzo: HTMLElement): void {
+    const repinta = (): void => void this.pinta(lienzo);
+    lienzo.querySelectorAll<HTMLElement>('[data-bv]').forEach((el) => {
+      el.onclick = async (evento) => {
+        evento.preventDefault();
+        const que = el.dataset.bv;
+        if (que === 'salir') return this.p.vete('resumen');
+        if (que === 'atras') {
+          this.paso = Math.max(0, this.paso - 1);
+          return repinta();
+        }
+        if (que === 'dominio') {
+          this.dominio = el.dataset.id ?? '';
+          this.roles = [];
+          this.rol = '';
+          return repinta();
+        }
+        if (que === 'rol') {
+          this.rol = el.dataset.id ?? '';
+          return repinta();
+        }
+        if (que === 'nuevo') {
+          this.enCurso = {
+            nombre: '',
+            clase: 'code',
+            rol: 'blank',
+            montajes: [],
+            runtime: '',
+            modelo: '',
+            esfuerzo: '',
+          };
+          return repinta();
+        }
+        if (que === 'clase' && this.enCurso) {
+          this.enCurso.clase = el.dataset.id ?? 'code';
+          this.recogeFormulario(lienzo);
+          return repinta();
+        }
+        if (que === 'monta' && this.enCurso) {
+          const ruta = el.dataset.ruta ?? '';
+          const ya = this.enCurso.montajes.indexOf(ruta);
+          if (ya >= 0) this.enCurso.montajes.splice(ya, 1);
+          else this.enCurso.montajes.push(ruta);
+          this.recogeFormulario(lienzo);
+          return repinta();
+        }
+        if (que === 'rebusca') {
+          this.recogeFormulario(lienzo);
+          this.buscaReposUnaVez(true);
+          return repinta();
+        }
+        if (que === 'cancela') {
+          this.enCurso = null;
+          return repinta();
+        }
+        if (que === 'guarda') return void (await this.guardaAgente(lienzo));
+        if (que === 'siguiente') return void (await this.avanza(lienzo));
+        if (que === 'sesion') return void (await this.abreSesion());
+        if (que === 'ir-gente') return this.p.vete('gente');
+        if (que === 'ir-mapa') return this.p.vete('mapa');
+        if (que === 'ir-puesto') return this.p.vete('puesto');
+      };
+    });
+    // The search filters what is already in memory, so it repaints as you type
+    // without asking the disk anything. Focus and caret are restored because a
+    // box that loses the cursor on the third letter is not a search box.
+    const busca = lienzo.querySelector<HTMLInputElement>('#bvBusca');
+    if (busca) {
+      busca.oninput = () => {
+        this.filtro = busca.value;
+        const donde = busca.selectionStart ?? busca.value.length;
+        void this.pinta(lienzo).then(() => {
+          const otra = lienzo.querySelector<HTMLInputElement>('#bvBusca');
+          if (!otra) return;
+          otra.focus();
+          otra.setSelectionRange(donde, donde);
+        });
+      };
+    }
+    const ruta = lienzo.querySelector<HTMLInputElement>('#bvRuta');
+    if (ruta)
+      ruta.onkeydown = (e) => {
+        if (e.key !== 'Enter' || !this.enCurso) return;
+        e.preventDefault();
+        const valor = ruta.value.trim();
+        if (valor) this.enCurso.montajes.push(valor);
+        this.recogeFormulario(lienzo);
+        void this.pinta(lienzo);
+      };
+    lienzo.querySelector<HTMLSelectElement>('#bvRuntime')?.addEventListener('change', () => {
+      this.recogeFormulario(lienzo);
+      void this.pinta(lienzo);
+    });
+    if (!busca?.value) lienzo.querySelector<HTMLInputElement>('#bvNombre')?.focus();
+  }
+
+  /** Keep what is typed when a click forces a repaint. */
+  private recogeFormulario(lienzo: HTMLElement): void {
+    if (!this.enCurso) return;
+    const nombre = lienzo.querySelector<HTMLInputElement>('#bvNombre');
+    const rol = lienzo.querySelector<HTMLSelectElement>('#bvRol');
+    if (nombre) this.enCurso.nombre = nombre.value;
+    if (rol) this.enCurso.rol = rol.value;
+    for (const [id, campo] of [
+      ['#bvRuntime', 'runtime'],
+      ['#bvModelo', 'modelo'],
+      ['#bvEsfuerzo', 'esfuerzo'],
+    ] as const) {
+      const sel = lienzo.querySelector<HTMLSelectElement>(id);
+      if (sel) this.enCurso[campo] = sel.value;
+    }
+    const busca = lienzo.querySelector<HTMLInputElement>('#bvBusca');
+    if (busca) this.filtro = busca.value;
+  }
+
+  private async guardaAgente(lienzo: HTMLElement): Promise<void> {
+    this.recogeFormulario(lienzo);
+    const a = this.enCurso;
+    if (!a) return;
+    if (!a.nombre.trim()) {
+      this.p.aviso('Give it a name — it is how you will call it in its window', true);
+      return;
+    }
+    this.guardando = true;
+    await this.pinta(lienzo);
+    try {
+      // The seat has to exist before an agent can join it: agents live on the
+      // owner's card. Writing it here is why this step can come before the goal.
+      await this.aseguraFicha();
+      const r = await this.p.api<{ ok?: boolean; agent?: string; error?: string }>('/api/agentes', {
+        method: 'POST',
+        body: JSON.stringify({ name: a.nombre.trim(), kind: a.clase, role: a.rol }),
+      });
+      if (!r.ok || !r.agent) {
+        this.p.aviso(r.error || 'Could not add that agent', true);
+        return;
+      }
+      for (const ruta of a.montajes) {
+        const m = await this.p.api<{ ok?: boolean; error?: string }>('/api/montaje', {
+          method: 'POST',
+          body: JSON.stringify({ agent: r.agent, add: ruta }),
+        });
+        if (!m.ok) this.p.aviso(`${ruta}: ${m.error ?? 'could not mount'}`, true);
+      }
+      // The engine is a second write by necessity: `/api/agentes` owns who is
+      // on the roster and `/api/agente` owns how one is run, and neither is
+      // allowed to learn the other's job just to save a round trip.
+      const motor: Record<string, string> = {};
+      if (a.runtime) motor.runtime = a.runtime;
+      if (a.modelo) motor.model = a.modelo;
+      if (a.esfuerzo) motor.effort = a.esfuerzo;
+      if (Object.keys(motor).length) {
+        const m = await this.p.api<{ ok?: boolean; error?: string }>('/api/agente', {
+          method: 'POST',
+          body: JSON.stringify({ agent: r.agent, ...motor }),
+        });
+        if (!m.ok) this.p.aviso(m.error ?? 'Could not set its engine', true);
+      }
+      this.roster.push({ ...a, nombre: a.nombre.trim() });
+      this.enCurso = null;
+      this.p.aviso(`${a.nombre.trim()} joined the city`);
+      await this.p.refresca();
+    } catch (e) {
+      this.p.aviso(String(e), true);
+    } finally {
+      this.guardando = false;
+      await this.pinta(lienzo);
+    }
+  }
+
+  private async aseguraFicha(): Promise<void> {
+    await this.p.api<{ ok?: boolean; error?: string }>('/api/ficha', {
+      method: 'POST',
+      body: JSON.stringify({ domain: this.dominio || 'software', role: this.rol || 'blank' }),
+    });
+  }
+
+  private async avanza(lienzo: HTMLElement): Promise<void> {
+    // The step moves FIRST, and only then does anything touch the server.
+    // Refreshing the Hall repaints this view, and a repaint that lands after a
+    // slow write would otherwise redraw the step the person just left — the
+    // guide silently bouncing back one screen.
+    const escribeLaFicha = this.paso === 2;
+    this.paso = Math.min(PASOS.length - 1, this.paso + 1);
+    await this.pinta(lienzo);
+    if (escribeLaFicha) {
+      // The chair is written the moment it is answered, so leaving halfway
+      // still leaves a usable city behind rather than nothing.
+      await this.aseguraFicha();
+      await this.p.refresca();
+    }
+  }
+
+  private async abreSesion(): Promise<void> {
+    try {
+      const r = await this.p.api<{ ok?: boolean; attach?: string; error?: string }>('/api/sesion', {
+        method: 'POST',
+        body: JSON.stringify({ user: this.p.yo }),
+      });
+      this.p.aviso(
+        r.ok && r.attach ? `Session built — attach with: ${r.attach}` : (r.error ?? 'Could not'),
+        !r.ok,
+      );
+    } catch (e) {
+      this.p.aviso(String(e), true);
+    }
+  }
+}