agents-city 0.1.0

package/plugin/scripts/crecimiento.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""What makes a house grow depends on who lives in it.
+
+The map grew every building from merged pull requests. That is right for a code
+agent and meaningless for everyone else — a knowledge agent whose work is a
+folder of documents, or a coordinator whose work is decisions, would forever
+show an empty lot no matter how much they did. So growth is polymorphic: each
+agent kind declares how its floors are counted, over its own workspace, with no
+assumption of git.
+
+- **code**: floors = merged PRs (the existing signal), bricks = commits with no
+  PR. Counted from the mounted repos, exactly as before.
+- **knowledge**: floors = documents in the workspace, bricks = recent edits.
+  A person with no git at all now has a house that grows as their knowledge does.
+- **coordinator**: floors = recorded decisions (deliberations), bricks = notices.
+
+Every counter takes the same `(agente, data)` and returns the same
+`{floors, bricks, activity30, signal}` shape, so the map renders one model and
+the reporter pushes one row regardless of kind. Pure counting over the
+filesystem; the git-backed `code` counter is injected so this module needs no
+network and stays trivially testable.
+"""
+
+import os
+import time
+
+import deliberations
+import workspace
+
+#: Extensions that count as a knowledge document.
+DOC_EXT = ('.md', '.txt', '.rst', '.org', '.pdf', '.doc', '.docx', '.adoc')
+DIAS_RECIENTE = 30
+_SEG_RECIENTE = DIAS_RECIENTE * 24 * 3600
+
+
+def _ahora():
+    # Injected via env for deterministic tests; falls back to wall clock.
+    forzado = os.environ.get('CITY_GROWTH_NOW')
+    return float(forzado) if forzado else time.time()
+
+
+def _cuenta_docs(raiz):
+    """(total docs, docs edited within DIAS_RECIENTE) under a folder tree."""
+    total = recientes = 0
+    ahora = _ahora()
+    for base, dirs, files in os.walk(raiz):
+        dirs[:] = [d for d in dirs if d not in ('.git', 'node_modules', '.cache')]
+        for f in files:
+            if f.lower().endswith(DOC_EXT):
+                total += 1
+                try:
+                    if ahora - os.path.getmtime(os.path.join(base, f)) < _SEG_RECIENTE:
+                        recientes += 1
+                except OSError:
+                    pass
+    return total, recientes
+
+
+def _resultado(floors, bricks, actividad, signal):
+    return {'floors': floors, 'bricks': bricks, 'activity30': actividad, 'signal': signal}
+
+
+def _knowledge(agente, data, contador_git=None):
+    total = recientes = 0
+    vistos = set()
+    # The workspace always counts and mounts add to it — `or`-falling-back made
+    # the agent's own documents vanish the moment it mounted anything.
+    for destino in [agente.workspace] + list(workspace.mount_targets(agente, data) or []):
+        real = os.path.realpath(destino) if destino else ''
+        if not real or real in vistos or not os.path.isdir(real):
+            continue
+        vistos.add(real)
+        t, r = _cuenta_docs(real)
+        total += t
+        recientes += r
+    return _resultado(total, recientes, recientes, 'documents')
+
+
+def _coordinator(agente, data, contador_git=None):
+    # Count decisions through the canonical deliberation reader, not a re-glob:
+    # the store is a tree of `deliberations/<id>/` dirs, so listing `*.json`
+    # would always find nothing.
+    registros = deliberations.lista(data)
+    ahora = _ahora()
+    recientes = 0
+    for d in registros:
+        cuando = d.get('updated_at') or d.get('created_at')
+        try:
+            if cuando and ahora - _epoch(cuando) < _SEG_RECIENTE:
+                recientes += 1
+        except (ValueError, TypeError):
+            pass
+    return _resultado(len(registros), 0, recientes, 'decisions')
+
+
+def _code(agente, data, contador_git=None):
+    """Floors from merged PRs via an injected git counter; 0 without one.
+
+    Kept injectable so this module needs no git and no network: the map/reporter
+    passes the existing PR counter, the tests pass a stub.
+    """
+    if contador_git is None:
+        return _resultado(0, 0, 0, 'pull-requests')
+    prs, commits, act = contador_git(agente, data)
+    return _resultado(prs, commits, act, 'pull-requests')
+
+
+#: One counter per kind. Every counter has the same (agente, data, contador_git)
+#: signature — the non-code ones ignore contador_git — so dispatch is uniform,
+#: no special case. Keyed off workspace.CLASES so the kind vocabulary lives once;
+#: `crece` degrades an unknown kind to _knowledge rather than crashing, so a new
+#: kind added to workspace.CLASES stays safe here until a counter is written.
+_CONTADORES = {
+    'code': _code,
+    'knowledge': _knowledge,
+    'coordinator': _coordinator,
+}
+
+
+def _epoch(valor):
+    """An ISO-8601 or epoch-ish timestamp -> epoch seconds. Raises on garbage.
+
+    A timezone-naive timestamp is read as UTC (not local time), so a coordinator's
+    recency window does not drift by the machine's UTC offset.
+    """
+    import datetime
+    texto = str(valor)
+    try:
+        return float(texto)
+    except ValueError:
+        dt = datetime.datetime.fromisoformat(texto.replace('Z', '+00:00'))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=datetime.timezone.utc)
+        return dt.timestamp()
+
+
+def crece(agente, data, contador_git=None):
+    """The growth of one agent's house, dispatched uniformly on its kind."""
+    contador = _CONTADORES.get(agente.clase, _knowledge)
+    return contador(agente, data, contador_git)

package/plugin/scripts/deliberations.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Read-only summaries of durable committee acts for the local Hall."""
+import json
+import os
+import re
+
+ID_RE = re.compile(r'^delib_[a-z0-9][a-z0-9_-]{5,79}$')
+
+
+def lista(datos):
+    root = os.path.join(os.path.realpath(datos), 'deliberations')
+    try:
+        nombres = sorted(os.listdir(root), reverse=True)
+    except OSError:
+        return []
+    fuera = []
+    for ident in nombres:
+        if not ID_RE.match(ident):
+            continue
+        try:
+            state = json.load(open(os.path.join(root, ident, 'state.json'),
+                                   encoding='utf-8'))
+            if state.get('schema') != 'agents-city/deliberation@1':
+                continue
+            brief = state['brief']
+            decisions = state.get('decisions') or []
+            decision = decisions[-1] if decisions else {}
+            verification = decision.get('verification') or {}
+            fuera.append({
+                'id': ident,
+                'status': state.get('status', 'unknown'),
+                'question': brief.get('question', ''),
+                'desired_outcome': brief.get('desiredOutcome', ''),
+                'participants': brief.get('participants', []),
+                'participant_roles': state.get('participantRoles', {}),
+                'received': len(state.get('positions') or {}),
+                'total': len(brief.get('participants') or []),
+                'revision': (state.get('progress') or {}).get('revision', 1),
+                'decision': decision.get('outcome', ''),
+                'contributors': decision.get('decisiveContributors', []),
+                'verifier': decision.get('verifier', ''),
+                'verification': verification.get('result', ''),
+                'updated_at': state.get('updatedAt', ''),
+                'act': os.path.join(root, ident, 'ACT.md'),
+            })
+        except (OSError, ValueError, KeyError, TypeError, json.JSONDecodeError):
+            continue
+    return fuera

package/plugin/scripts/doctor.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+"""doctor: detect an old config shape, explain it, back it up, rewrite it.
+
+The runtime reads one config schema — the current one. It keeps no long-lived
+aliases that silently accept renamed or malformed keys, because a silent alias
+is how two subtly different shapes drift apart. Instead, every change that can
+invalidate an existing config ships a migration here: `doctor` finds the old
+shape, says in one line what it is doing, writes a timestamped backup, and
+rewrites the file to canonical form.
+
+Each migration is a small object with three parts — does it apply, what does it
+change, and the rewrite — so adding one is additive and never touches the
+others (open for extension). `--dry-run` reports without writing; the default
+writes a `.bak-<stamp>` next to the file first. Pure enough to test against a
+temp file with no real config in sight.
+"""
+
+import argparse
+import json
+import os
+import sys
+
+GUIONES = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, GUIONES)
+from dataclasses import dataclass
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class Migracion:
+    id: str
+    explica: str
+    aplica: Callable[[dict], bool]
+    reescribe: Callable[[dict], dict]
+
+
+def _renombra_bus_url(cfg):
+    cfg = dict(cfg)
+    cfg['roadsUrl'] = cfg.pop('busUrl')
+    return cfg
+
+
+def _sella_bind(cfg):
+    cfg = dict(cfg)
+    gw = dict(cfg.get('gateway', {}))
+    gw.setdefault('bind', 'loopback')
+    cfg['gateway'] = gw
+    return cfg
+
+
+def _cage_por_defecto(cfg):
+    cfg = dict(cfg)
+    seg = dict(cfg.get('security', {}))
+    if 'cage' not in seg:
+        seg['cage'] = True
+    cfg['security'] = seg
+    return cfg
+
+
+#: Ordered so a file needing several migrations converges in one pass. Each is
+#: idempotent: re-running doctor on a canonical file changes nothing.
+MIGRACIONES = [
+    Migracion(
+        'bus-url-renamed-to-roads-url',
+        'the transport key `busUrl` is now `roadsUrl`',
+        lambda c: 'busUrl' in c,
+        _renombra_bus_url,
+    ),
+    Migracion(
+        'gateway-bind-defaults-to-loopback',
+        'a gateway block without an explicit `bind` now pins `loopback`',
+        lambda c: isinstance(c.get('gateway'), dict) and 'bind' not in c['gateway'],
+        _sella_bind,
+    ),
+    Migracion(
+        'cage-on-by-default',
+        'the per-window cage is recorded as on unless the owner set it',
+        # Guard the type like migration 2: a `security` that is present but not
+        # a dict (null/str/list) must not crash the tool that exists to fix it.
+        # Absent security counts as an empty dict, so the default is still added.
+        lambda c: isinstance(c.get('security', {}), dict) and 'cage' not in c.get('security', {}),
+        _cage_por_defecto,
+    ),
+]
+
+
+def _aplica(cfg):
+    """The single migration walk: return (nuevo, [Migracion aplicadas]).
+
+    Everything else is a view of this — `diagnostica` wants the objects,
+    `cura` wants their ids, `cura_fichero` wants both — so the apply/rewrite
+    logic lives here once and never runs twice per file.
+    """
+    aplicadas = []
+    trabajo = dict(cfg)
+    for m in MIGRACIONES:
+        if m.aplica(trabajo):
+            trabajo = m.reescribe(trabajo)
+            aplicadas.append(m)
+    return trabajo, aplicadas
+
+
+def diagnostica(cfg):
+    """Return the ordered migrations that still apply to `cfg`."""
+    return _aplica(cfg)[1]
+
+
+def cura(cfg):
+    """Apply every applicable migration in order; return (nuevo, ids_aplicadas)."""
+    nuevo, aplicadas = _aplica(cfg)
+    return nuevo, [m.id for m in aplicadas]
+
+
+def _stamp_backup(ruta, marca):
+    """Copy the file to a timestamped sibling before rewriting. Marca is passed
+    in (never read from the clock here) so a caller controls naming and tests
+    stay deterministic."""
+    destino = f'{ruta}.bak-{marca}'
+    with open(ruta, encoding='utf-8') as f:
+        contenido = f.read()
+    with open(destino, 'w', encoding='utf-8') as f:
+        f.write(contenido)
+    os.chmod(destino, 0o600)
+    return destino
+
+
+def cura_fichero(ruta, marca, dry_run=False):
+    """Diagnose and (unless dry-run) rewrite a config file. Returns a report."""
+    with open(ruta, encoding='utf-8') as f:
+        cfg = json.load(f)
+    nuevo, pendientes = _aplica(cfg)  # one walk: report and rewrite come from it
+    reporte = {'file': ruta, 'migrations': [m.id for m in pendientes],
+               'explains': [m.explica for m in pendientes], 'wrote': False, 'backup': None}
+    if not pendientes or dry_run:
+        return reporte
+    reporte['backup'] = _stamp_backup(ruta, marca)
+    tmp = f'{ruta}.tmp'
+    with open(tmp, 'w', encoding='utf-8') as f:
+        json.dump(nuevo, f, indent=2, sort_keys=True)
+    # Preserve the original file's mode rather than inheriting the umask default
+    # (0644): a config that was 0600 must not be silently widened by a migration.
+    try:
+        os.chmod(tmp, os.stat(ruta).st_mode & 0o777)
+    except OSError:
+        os.chmod(tmp, 0o600)
+    os.replace(tmp, ruta)
+    reporte['wrote'] = True
+    return reporte
+
+
+# ── the machine, not just the config ─────────────────────────────────────────
+#
+# `doctor` used to answer one narrow question — is this config file an old
+# shape? — behind no command at all. What a person means by "doctor" is: tell
+# me whether this thing can work here, and if not, which part. So it answers
+# that too, and every line is derived: what is installed, what the kernel will
+# grant, which city is selected. Nothing here writes.
+
+
+def _version_de(programa, bandera='--version'):
+    import shutil as _sh
+    import subprocess as _sp
+
+    ruta = _sh.which(programa)
+    if not ruta:
+        return ''
+    try:
+        r = _sp.run([ruta, bandera], capture_output=True, text=True, timeout=10)
+    except (OSError, _sp.SubprocessError):
+        return 'installed'
+    primera = (r.stdout or r.stderr).strip().splitlines()
+    return primera[0].strip() if primera else 'installed'
+
+
+def revisa_entorno():
+    """Every check as `(area, ok, detail)`. `ok` is None for "not applicable".
+
+    A list rather than printed lines, so the Hall could show the same answers
+    the terminal does without either of them re-deciding what healthy means.
+    """
+    import shutil as _sh
+    import sys as _sys
+
+    import cage as _cage
+    import cities as _cities
+
+    fuera = []
+    fuera.append(('python', True, _sys.version.split()[0]))
+    # Every one of these spells its version flag differently, and tmux answers
+    # `--version` with an error that reads like a working version string.
+    for programa, bandera, obligatorio in (('tmux', '-V', True), ('bash', '--version', True),
+                                           ('git', '--version', True),
+                                           ('node', '--version', True),
+                                           ('gh', '--version', False)):
+        v = _version_de(programa, bandera)
+        fuera.append((programa, bool(v) if obligatorio else (True if v else None),
+                      v or ('missing' if obligatorio else 'not installed (optional)')))
+
+    motores = [m for m in ('claude', 'codex', 'opencode', 'kimi') if _sh.which(m)]
+    fuera.append(('runtimes', bool(motores),
+                  ', '.join(motores) if motores else 'none — a city needs at least one CLI'))
+
+    if _sys.platform == 'darwin':
+        detalle = ('seatbelt' if _sh.which('sandbox-exec') else 'sandbox-exec missing')
+    elif _sys.platform.startswith('linux'):
+        if not _sh.which('bwrap'):
+            detalle = 'bubblewrap not installed — agents run uncaged (apt install bubblewrap)'
+        elif not _cage.bwrap_sirve():
+            detalle = ('bubblewrap present but the kernel refuses unprivileged '
+                       'namespaces — agents run uncaged')
+        else:
+            detalle = 'bubblewrap'
+    else:
+        detalle = f'no cage on {_sys.platform}'
+    fuera.append(('cage', _cage.disponible(), detalle))
+
+    try:
+        usuario = _cities.usuario_actual()
+        datos = _cities.actual(usuario, crear=False)
+        if datos:
+            fuera.append(('city', True, _cities.direccion(usuario, datos)))
+            ficha = os.path.join(datos, f'{usuario}.md')
+            fuera.append(('card', os.path.isfile(ficha),
+                          ficha if os.path.isfile(ficha) else f'no card at {ficha}'))
+        else:
+            fuera.append(('city', None, 'none selected yet — agents-city seat creates one'))
+    except (OSError, ValueError) as e:
+        fuera.append(('city', False, str(e)))
+
+    hall = os.path.join(os.path.dirname(os.path.dirname(GUIONES)),
+                        'city', 'web', 'dist-hall', 'hall.js')
+    fuera.append(('hall bundle', os.path.isfile(hall),
+                  'built' if os.path.isfile(hall) else 'not built — ./bin/hall builds it'))
+    return fuera
+
+
+def informe_entorno():
+    """Print the environment report. Returns 0 when nothing is broken."""
+    import actualiza
+
+    print('\n  Agents City doctor\n')
+    roto = 0
+    for area, bien, detalle in revisa_entorno():
+        marca = '·' if bien is None else ('ok' if bien else 'XX')
+        if bien is False:
+            roto += 1
+        print(f'  {marca:>2}  {area:<12} {detalle}')
+    instalada, ultima, hay = actualiza.comprueba()
+    if ultima:
+        print(f'  {"!!" if hay else "ok":>2}  {"version":<12} {instalada}'
+              + (f' — {ultima} is out: agents-city update' if hay else ' (current)'))
+    else:
+        print(f'  {"·":>2}  {"version":<12} {instalada} (registry not checked)')
+    print()
+    if roto:
+        print(f'  {roto} thing(s) need attention.\n')
+    return 1 if roto else 0
+
+
+def main():
+    # `doctor` with no file is the environment report — what a person means by
+    # the word. The config migration keeps its own path, unchanged.
+    if len(sys.argv) == 1 or sys.argv[1] in ('-h', '--help', 'help'):
+        if len(sys.argv) > 1:
+            print('  usage: agents-city doctor [config.json [--fix]]\n\n'
+                  '  With no arguments: check this machine — tools, runtimes, the\n'
+                  '  cage, the selected city, and whether a newer version is out.\n'
+                  '  With a config file: detect, explain and migrate an old shape.')
+            return 0
+        return informe_entorno()
+    p = argparse.ArgumentParser(description='Detect, explain and migrate an old config shape.')
+    p.add_argument('fichero', help='the config JSON file to check')
+    p.add_argument('--fix', action='store_true', help='rewrite (default is dry-run report)')
+    p.add_argument('--stamp', default='manual', help='backup suffix (tests pass a fixed value)')
+    args = p.parse_args()
+    try:
+        reporte = cura_fichero(args.fichero, args.stamp, dry_run=not args.fix)
+    except (OSError, json.JSONDecodeError) as e:
+        print(f'{e}', file=sys.stderr)
+        return 1
+    if not reporte['migrations']:
+        print('config is already canonical')
+        return 0
+    for ident, porque in zip(reporte['migrations'], reporte['explains'], strict=True):
+        print(f'  {ident}: {porque}')
+    if reporte['wrote']:
+        print(f'rewritten; backup at {reporte["backup"]}')
+    else:
+        print('dry-run: pass --fix to apply')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())

package/plugin/scripts/domains.py

@@ -0,0 +1,201 @@
+#!/usr/bin/env python3
+"""Built-in work domains and the knowledge packs installed into one city.
+
+A domain is the context of the city (software, healthcare, legal, finance...).
+A role is the responsibility of its one owner seat inside that domain.  Keeping
+those two choices separate is important: ``data`` means something different in a
+software product from a clinical-data responsibility, while neither is the city
+itself.
+
+The catalogue is plain Markdown under ``plugin/domains``. On selection, the
+chosen domain pack and every non-blank seat/repo role pack are copied into the
+city's own ``domains/`` and ``roles/`` folders. They are ordinary, editable files
+after that. This is city knowledge, not a repo skill: Agents City never installs
+or changes skills in a referenced repo.
+"""
+
+import glob
+import os
+import re
+import shutil
+
+import cities
+
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+PACKS = os.path.realpath(os.path.join(AQUI, "..", "domains"))
+ROLE_PACKS = os.path.realpath(os.path.join(AQUI, "..", "roles", "examples"))
+
+# Old cities called the domain ``kind`` and used these ids.  Read them forever,
+# but every new write uses the explicit ``domain`` field and canonical id.
+ALIASES = {"product": "software", "blank": "custom"}
+
+
+def canonico(valor):
+    return ALIASES.get(str(valor or "").strip().lower(), str(valor or "").strip().lower())
+
+
+def _frontmatter(texto):
+    if not texto.startswith("---\n"):
+        return ""
+    partes = texto.split("---", 2)
+    return partes[1] if len(partes) == 3 else ""
+
+
+def _escalar(fm, clave, defecto=""):
+    m = re.search(rf"^{re.escape(clave)}:[ \t]*(.*)$", fm, re.M)
+    return (m.group(1).strip() if m else "") or defecto
+
+
+def _lista(fm, clave):
+    """Indented ``- value`` rows below one frontmatter key."""
+    m = re.search(rf"^{re.escape(clave)}:[ \t]*\n((?:[ \t]+-[^\n]*\n?)*)", fm, re.M)
+    if not m:
+        return []
+    fuera = []
+    for linea in m.group(1).splitlines():
+        valor = re.sub(r"^[ \t]+-[ \t]*", "", linea).strip()
+        if not valor:
+            continue
+        base, _, nota = valor.partition("#")
+        fuera.append((base.strip().rstrip(), "on by default" in nota.lower()))
+    return fuera
+
+
+def _unidades(fm):
+    fuera = []
+    for valor, _ in _lista(fm, "units"):
+        nombre, sep, color = valor.rpartition(";")
+        if sep and re.fullmatch(r"[0-9a-fA-F]{6}", color.strip()):
+            fuera.append((nombre.strip(), color.strip().lower()))
+    return fuera
+
+
+def lee(ruta):
+    try:
+        texto = open(ruta, encoding="utf-8").read()
+    except OSError:
+        return {}
+    fm = _frontmatter(texto)
+    ident = canonico(_escalar(fm, "id", os.path.basename(ruta)[:-3]))
+    roles = _lista(fm, "roles")
+    return {
+        "id": ident,
+        "order": int(_escalar(fm, "order", "999")),
+        "name": _escalar(fm, "name", ident.replace("-", " ").title()),
+        "summary": _escalar(fm, "summary"),
+        "parcel": _escalar(fm, "parcel", "a working repository"),
+        "source": _escalar(fm, "source", "github|disk"),
+        "grows": _escalar(fm, "grows_with"),
+        "grow_cmd": _escalar(fm, "grow_command"),
+        "roles": roles,
+        "units": _unidades(fm),
+        "path": ruta,
+        "text": texto,
+    }
+
+
+def catalogo():
+    fuera = [lee(ruta) for ruta in glob.glob(os.path.join(PACKS, "*.md"))]
+    return sorted((p for p in fuera if p.get("id")), key=lambda p: (p["order"], p["name"].lower()))
+
+
+def obtiene(ident):
+    buscado = canonico(ident)
+    return next((p for p in catalogo() if p["id"] == buscado), None)
+
+
+def roles_de(ident):
+    pack = obtiene(ident)
+    return list(pack["roles"]) if pack else []
+
+
+def dominio_de_rol(rol, defecto="software"):
+    for pack in catalogo():
+        if any(r == rol for r, _ in pack["roles"]):
+            return pack["id"]
+    return defecto
+
+
+def de_ciudad(datos, defecto="software"):
+    explicito = cities.lee_clave(datos, "domain")
+    legado = cities.lee_clave(datos, "kind")
+    elegido = canonico(explicito or legado or defecto)
+    return elegido if obtiene(elegido) else canonico(defecto)
+
+
+def selecciona(datos, ident):
+    """Persist the canonical domain without rewriting city identity metadata."""
+    ident = canonico(ident)
+    if not obtiene(ident):
+        raise ValueError(f"unknown city domain: {ident}")
+    ruta = os.path.join(datos, "city.yml")
+    try:
+        texto = open(ruta, encoding="utf-8").read()
+    except OSError:
+        texto = ""
+    if re.search(r"^domain:", texto, re.M):
+        texto = re.sub(r"^domain:.*$", f"domain: {ident}", texto, count=1, flags=re.M)
+    else:
+        if texto and not texto.endswith("\n"):
+            texto += "\n"
+        texto += f"domain: {ident}\n"
+    cities.escribe_atomico(ruta, texto)
+    return ident
+
+
+INSTRUCCIONES = """# Agents City seat
+
+This folder is one autonomous city, not a source-code repository and not a team
+of people. Its only public actor is the owner seat; referenced repos are private
+support agents behind that chair.
+
+Before acting for this city:
+
+1. Read `city.yml` for the selected `domain` and owner.
+2. Read the owner card `<owner>.md` for the role, goal and support repos.
+3. Read `domains/<domain>.md` and `roles/<role>.md` when that role file exists.
+   `blank` deliberately has no role file. These are transparent, editable
+   operating knowledge for this city, not hidden prompts.
+4. Read each support agent's `role.<repo>` assignment from the owner card before
+   asking it for evidence. Use a chaired committee when several matter.
+   Repo agents do not talk directly to each other.
+
+Skills remain installed in the referenced repos. Agents City only recognises
+them; it never copies, installs or enables a repo skill from this folder.
+"""
+
+
+def materializa(datos, ident, rol):
+    """Copy selected built-in knowledge into a city, never over user edits.
+
+    A later role/domain switch gets its own file, so changing back restores the
+    city's edited copy.  Existing files are deliberately not refreshed in place.
+    """
+    pack = obtiene(ident)
+    if not pack:
+        return []
+    hechos = []
+    carpeta_dominios = os.path.join(datos, "domains")
+    carpeta_roles = os.path.join(datos, "roles")
+    os.makedirs(carpeta_dominios, exist_ok=True)
+    os.makedirs(carpeta_roles, exist_ok=True)
+
+    destino_dominio = os.path.join(carpeta_dominios, f"{pack['id']}.md")
+    if not os.path.exists(destino_dominio):
+        shutil.copy2(pack["path"], destino_dominio)
+        hechos.append(f"domains/{pack['id']}.md")
+
+    rol_seguro = str(rol or "")
+    if re.fullmatch(r"[a-z0-9-]+", rol_seguro):
+        fuente_rol = os.path.join(ROLE_PACKS, f"{rol_seguro}.md")
+        destino_rol = os.path.join(carpeta_roles, f"{rol_seguro}.md")
+        if os.path.isfile(fuente_rol) and not os.path.exists(destino_rol):
+            shutil.copy2(fuente_rol, destino_rol)
+            hechos.append(f"roles/{rol_seguro}.md")
+
+    instrucciones = os.path.join(datos, "AGENTS.md")
+    if not os.path.exists(instrucciones):
+        cities.escribe_atomico(instrucciones, INSTRUCCIONES)
+        hechos.append("AGENTS.md")
+    return hechos