agents-city 0.3.0-beta.21

package/plugin/scripts/reset.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""Reset one managed city to first-run state, recoverably.
+
+The target is always explicit.  Repos are references and are never touched.  The
+city folder and its local map state move to a timestamped backup, incident local
+roads are removed at both ends, and an empty city with the same stable identity
+is created in its place.  The next ``agents-city seat --city <name>`` runs the
+five onboarding questions again.
+"""
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+import time
+
+import cities
+import domains
+import roads
+import runtime_processes
+
+
+def _backup_path(usuario, datos):
+    sello = time.strftime("%Y%m%d-%H%M%S")
+    base = os.path.join(cities.carpeta_usuario(usuario), ".backups")
+    nombre = f"{cities.slug_ciudad(datos)}-{sello}"
+    ruta = os.path.join(base, nombre)
+    n = 2
+    while os.path.exists(ruta):
+        ruta = os.path.join(base, f"{nombre}-{n}")
+        n += 1
+    return ruta
+
+
+def _deten(datos, dry_run=False):
+    guion = os.path.join(os.path.dirname(__file__), "apaga.py")
+    args = [sys.executable, guion, datos]
+    if dry_run:
+        args.append("--dry-run")
+    return subprocess.run(args, capture_output=True, text=True)
+
+
+def _valida(datos, usuario):
+    usuario = usuario or cities.usuario_actual()
+    datos = os.path.realpath(datos)
+    if not cities.gestionada(datos, usuario):
+        raise ValueError(
+            "reset only accepts a managed city under "
+            f"{cities.carpeta_usuario(usuario)}; external/shared "
+            "folders are never erased"
+        )
+    if not cities.es_ciudad(datos):
+        raise ValueError(f"{datos} is not a city")
+    owner_en_disco = cities.lee_clave(datos, "owner")
+    if owner_en_disco and owner_en_disco != usuario:
+        raise ValueError(f"this city belongs to {owner_en_disco!r}, not {usuario!r}")
+    return datos, usuario
+
+
+def _contexto(datos, usuario):
+    return {
+        "datos": datos,
+        "usuario": usuario,
+        "ident": cities.identidad(datos),
+        "nombre": cities.nombre(datos),
+        "slug": cities.slug_ciudad(datos),
+        "owner": cities.lee_clave(datos, "owner") or usuario,
+        "domain": domains.de_ciudad(datos),
+        "grow": cities.lee_clave(
+            datos, "grow_command", "git log --since=30.days --oneline | wc -l"
+        ),
+        "backup": _backup_path(usuario, datos),
+        "estado": os.path.join(cities.raiz(), "state", cities.slug(datos)),
+        "runtime": runtime_processes.ruta(datos),
+        "roads": roads.lee(datos),
+    }
+
+
+def _preview(ctx):
+    print(f"  Would reset city `{ctx['slug']}` at {ctx['datos']}")
+    print(f"  Would preserve it at {ctx['backup']}")
+    print("  Would leave every referenced repo untouched")
+    if ctx["roads"]:
+        print(f"  Would close {len(ctx['roads'])} road(s) at both ends")
+    parada = _deten(ctx["datos"], dry_run=True)
+    if parada.stdout.strip():
+        print(parada.stdout.rstrip())
+
+
+def _para(datos):
+    parada = _deten(datos)
+    if parada.returncode != 0:
+        detalle = (parada.stderr or parada.stdout or "unknown stop error").strip()
+        raise ValueError(f"could not stop the city before reset: {detalle}")
+
+
+def _cierra_carreteras(ctx):
+    """Back up and remove the other half of every incident local road."""
+    backlinks = os.path.join(ctx["backup"], "road-backlinks")
+    for camino in ctx["roads"]:
+        otro = roads.destino_local(camino, ctx["usuario"])
+        if not otro:
+            continue
+        os.makedirs(backlinks, exist_ok=True)
+        if os.path.isfile(roads.ruta(otro)):
+            destino = os.path.join(backlinks, f"{cities.slug_ciudad(otro)}.roads.json")
+            shutil.copy2(roads.ruta(otro), destino)
+        roads.desconecta(otro, ctx["ident"])
+
+
+def _mueve_si_existe(origen, destino):
+    if os.path.exists(origen):
+        shutil.move(origen, destino)
+
+
+def _respalda(ctx):
+    os.makedirs(ctx["backup"], exist_ok=False)
+    _cierra_carreteras(ctx)
+    shutil.move(ctx["datos"], os.path.join(ctx["backup"], "city"))
+    _mueve_si_existe(ctx["estado"], os.path.join(ctx["backup"], "state"))
+    _mueve_si_existe(ctx["runtime"], os.path.join(ctx["backup"], "runtime"))
+
+
+def _crea_vacia(ctx):
+    datos = ctx["datos"]
+    os.makedirs(datos, exist_ok=True)
+    cities.asegura_metadata(datos, ctx["owner"], ctx["nombre"], ctx["ident"])
+    # Keep stable identity and growth measure, but no seat, agents, repos or roads.
+    city_yml = os.path.join(datos, "city.yml")
+    texto = open(city_yml, encoding="utf-8").read()
+    if "\ndomain:" not in "\n" + texto:
+        texto += f"domain: {ctx['domain']}\n"
+    if "\ngrow_command:" not in "\n" + texto:
+        texto += f"grow_command: {ctx['grow']}\n"
+    cities.escribe_atomico(city_yml, texto)
+    roads.escribe(datos, [])
+    cities.selecciona(ctx["usuario"], datos)
+
+
+def reinicia(datos, usuario="", dry_run=False):
+    datos, usuario = _valida(datos, usuario)
+    ctx = _contexto(datos, usuario)
+    if dry_run:
+        _preview(ctx)
+        return ctx["backup"]
+
+    _para(datos)
+    _respalda(ctx)
+    _crea_vacia(ctx)
+    return ctx["backup"]
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Reset one city to onboarding; repos stay untouched and data is backed up"
+    )
+    ap.add_argument("city", help="city name or path (required)")
+    ap.add_argument("--dry-run", action="store_true", help="show every effect, change nothing")
+    a = ap.parse_args()
+    usuario = cities.usuario_actual()
+    datos = cities.resuelve(a.city, usuario)
+    if not datos:
+        conocidas = ", ".join(c["slug"] for c in cities.lista(usuario)) or "none"
+        print(f"  No city called {a.city!r}. Known here: {conocidas}.", file=sys.stderr)
+        return 1
+    try:
+        backup = reinicia(datos, usuario, a.dry_run)
+    except ValueError as e:
+        print(f"  {e}", file=sys.stderr)
+        return 1
+    if not a.dry_run:
+        corto = backup.replace(os.path.expanduser("~"), "~")
+        print(f"  City `{cities.slug_ciudad(datos)}` reset. Recovery copy: {corto}")
+        print(f"  Run `agents-city seat --city {cities.slug_ciudad(datos)}` for onboarding.")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugin/scripts/roads.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Explicit roads between autonomous cities.
+
+Roads connect city seats, never users and never repo windows.  A local road is
+written at both ends.  A remote road is added from a small public invitation;
+the other end accepts this city's invitation independently.  No token or skill
+content is ever stored here.
+"""
+
+import json
+import os
+import re
+import sys
+
+import card
+import cities
+import domains
+
+
+ADDRESS_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}/[a-z0-9][a-z0-9_-]{0,63}$")
+ID_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,128}$")
+INVITATION_KEYS = {"version", "id", "name", "owner", "address", "domain", "role"}
+
+
+def _limpia(camino):
+    """Validate untrusted road metadata and return its storage shape."""
+    if not isinstance(camino, dict):
+        return None
+    ident = str(camino.get("id", "")).strip()
+    address = str(camino.get("address", "")).strip().lower()
+    if not ID_RE.fullmatch(ident) or not ADDRESS_RE.fullmatch(address):
+        return None
+    dueno, slug = address.split("/", 1)
+    owner = str(camino.get("owner") or dueno).strip().lower()
+    if owner != dueno:
+        return None
+    name = " ".join(str(camino.get("name") or slug).split())[:80] or slug
+    limpio = {"id": ident, "name": name, "owner": owner, "address": address}
+    dominio = domains.canonico(camino.get("domain"))
+    rol = str(camino.get("role") or "").strip().lower()
+    if dominio and re.fullmatch(r"[a-z0-9-]{1,80}", dominio):
+        limpio["domain"] = dominio
+    if rol and re.fullmatch(r"[a-z0-9-]{1,80}", rol):
+        limpio["role"] = rol
+    if camino.get("local"):
+        limpio["local"] = True
+    return limpio
+
+
+def ruta(datos):
+    return os.path.join(os.path.realpath(datos), "roads.json")
+
+
+def _atomico(ruta_, objeto):
+    os.makedirs(os.path.dirname(ruta_), exist_ok=True)
+    temporal = ruta_ + f".tmp-{os.getpid()}"
+    with open(temporal, "w", encoding="utf-8") as f:
+        json.dump(objeto, f, indent=2, ensure_ascii=False, sort_keys=True)
+        f.write("\n")
+    os.replace(temporal, ruta_)
+
+
+def lee(datos):
+    try:
+        objeto = json.load(open(ruta(datos), encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, TypeError):
+        return []
+    caminos = objeto.get("roads", []) if isinstance(objeto, dict) else []
+    return [limpio for r in caminos if (limpio := _limpia(r)) is not None]
+
+
+def escribe(datos, caminos):
+    limpios, ids, direcciones = [], set(), set()
+    for camino in caminos:
+        limpio = _limpia(camino)
+        if not limpio or limpio["id"] in ids or limpio["address"] in direcciones:
+            continue
+        ids.add(limpio["id"])
+        direcciones.add(limpio["address"])
+        limpios.append(limpio)
+    limpios.sort(key=lambda r: (r["owner"], r["name"].lower(), r["id"]))
+    _atomico(ruta(datos), {"version": 1, "roads": limpios})
+
+
+def invitacion(datos, usuario=""):
+    usuario = usuario or cities.usuario_actual()
+    owner = cities.lee_clave(datos, "owner") or usuario
+    ficha = card.lee(os.path.join(datos, f"{owner}.md"))
+    invitacion_ = {
+        "version": 1,
+        "id": cities.identidad(datos),
+        "name": cities.nombre(datos),
+        "owner": owner,
+        "address": cities.direccion(usuario, datos),
+        "domain": domains.de_ciudad(datos),
+    }
+    if ficha.get("role"):
+        invitacion_["role"] = ficha["role"]
+    return invitacion_
+
+
+def _pon(datos, destino, local=False):
+    caminos = [r for r in lee(datos) if r["id"] != destino["id"]]
+    nuevo = dict(destino)
+    if local:
+        nuevo["local"] = True
+    caminos.append(nuevo)
+    escribe(datos, caminos)
+
+
+def conecta(origen, destino, usuario=""):
+    """Connect two cities on this machine, symmetrically."""
+    usuario = usuario or cities.usuario_actual()
+    if cities.identidad(origen) == cities.identidad(destino):
+        raise ValueError("a city cannot build a road to itself")
+    _pon(origen, invitacion(destino, usuario), local=True)
+    _pon(destino, invitacion(origen, usuario), local=True)
+
+
+def conecta_invitacion(origen, destino):
+    """Add the local half of a road to a remote city invitation."""
+    necesarios = {"id", "name", "owner", "address"}
+    if not isinstance(destino, dict) or not necesarios <= set(destino):
+        raise ValueError("the invitation is missing id, name, owner or address")
+    if not set(destino) <= INVITATION_KEYS:
+        raise ValueError("the invitation contains fields other than public city identity")
+    limpia = _limpia(destino)
+    if not limpia:
+        raise ValueError("the invitation has invalid or inconsistent identity")
+    origen_publico = invitacion(origen)
+    if limpia["id"] == origen_publico["id"] or limpia["address"] == origen_publico["address"]:
+        raise ValueError("a city cannot build a road to itself")
+    _pon(origen, limpia, local=False)
+
+
+def desconecta(origen, destino_id):
+    antes = lee(origen)
+    despues = [r for r in antes if r["id"] != destino_id]
+    escribe(origen, despues)
+    return len(antes) != len(despues)
+
+
+def desconecta_local(origen, destino):
+    a = desconecta(origen, cities.identidad(destino))
+    b = desconecta(destino, cities.identidad(origen))
+    return a or b
+
+
+def quita_incidentes(datos, usuario=""):
+    """Remove every local edge touching a city; used by a scoped reset."""
+    usuario = usuario or cities.usuario_actual()
+    ident = cities.identidad(datos)
+    for otra in cities.lista(usuario):
+        if os.path.realpath(otra["ruta"]) != os.path.realpath(datos):
+            desconecta(otra["ruta"], ident)
+    escribe(datos, [])
+
+
+def destino_local(camino, usuario=""):
+    """Resolve a road record to a city currently present on this machine."""
+    if not camino.get("local"):
+        return ""
+    usuario = usuario or cities.usuario_actual()
+    return next((c["ruta"] for c in cities.lista(usuario) if c["id"] == camino.get("id")), "")
+
+
+def _resuelve(nombre, usuario):
+    datos = cities.resuelve(nombre, usuario)
+    if not datos:
+        conocidas = ", ".join(c["slug"] for c in cities.lista(usuario)) or "none"
+        raise ValueError(f"no city called {nombre!r}; known here: {conocidas}")
+    return datos
+
+
+def _ayuda():
+    return """usage:
+  agents-city road list <city>
+  agents-city road connect <city> <local-city|invitation.json>
+  agents-city road disconnect <city> <local-city|city-id>
+  agents-city road invite <city>
+
+Roads are explicit. Connecting two local cities writes both ends. For a remote
+city, exchange the public JSON printed by `road invite`; it contains no token."""
+
+
+def main():
+    args = sys.argv[1:]
+    if not args or args[0] in ("-h", "--help", "help"):
+        print(_ayuda())
+        return 0
+    usuario = cities.usuario_actual()
+    try:
+        if args[0] == "list" and len(args) == 2:
+            origen = _resuelve(args[1], usuario)
+            caminos = lee(origen)
+            if not caminos:
+                print(f"  {cities.nombre(origen)} has no roads.")
+            for r in caminos:
+                local = "local" if destino_local(r, usuario) else "remote"
+                print(f"  {r['name']}  {r['address']}  [{local}]")
+            return 0
+        if args[0] == "invite" and len(args) == 2:
+            print(json.dumps(invitacion(_resuelve(args[1], usuario)), indent=2))
+            return 0
+        if args[0] == "connect" and len(args) == 3:
+            origen = _resuelve(args[1], usuario)
+            destino = cities.resuelve(args[2], usuario)
+            if destino:
+                conecta(origen, destino, usuario)
+                print(f"  Road open: {cities.nombre(origen)} <-> {cities.nombre(destino)}")
+            else:
+                with open(os.path.expanduser(args[2]), encoding="utf-8") as f:
+                    conecta_invitacion(origen, json.load(f))
+                print(f"  Remote road added to {cities.nombre(origen)}.")
+            return 0
+        if args[0] == "disconnect" and len(args) == 3:
+            origen = _resuelve(args[1], usuario)
+            destino = cities.resuelve(args[2], usuario)
+            cambiado = desconecta_local(origen, destino) if destino else desconecta(origen, args[2])
+            print("  Road closed." if cambiado else "  No such road.")
+            return 0
+    except (OSError, ValueError, json.JSONDecodeError) as e:
+        print(f"  {e}", file=sys.stderr)
+        return 1
+    print(_ayuda(), file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/plugin/scripts/roles.py

@@ -0,0 +1,274 @@
+#!/usr/bin/env python3
+"""The roles offered to an owner seat, across the built-in work domains.
+
+The v2 road address is stable ``owner/city`` and never depends on role. The short
+role suffixes remain only to read and import v1 cards such as ``alice/lead``.
+
+The catalogue is shared by the Hall and seat so they cannot label the same role
+differently. Which subset is relevant is owned by ``domains.py``: a city first
+chooses its work domain, then one role inside it. Role descriptions may still be
+overridden by a city's own role files.
+
+Only picker labels and one-line summaries live here. The operating knowledge and
+trade come from each role's Markdown file, looked up in your city first and the
+plugin's examples second — duplicating those in code is how a managing partner
+once got labelled a master builder.
+"""
+
+import os
+import re
+
+AQUI = os.path.dirname(os.path.abspath(__file__))
+
+# (id, what the city calls it, its one line, whether it owns a property of every
+# folder rather than folders of its own).
+CATALOGO = [
+    # Deliberately no role pack. ``blank`` is an explicit choice to start with
+    # no predefined responsibility or operating knowledge; it is offered in
+    # every domain and can also be assigned to an individual repo agent.
+    ("blank", "Blank role", "no predefined responsibility or role knowledge", True),
+    # Software development
+    ("cpto", "Product & technology lead", "direction, priorities and product outcomes", True),
+    ("dev", "Software engineer", "owns repositories and answers for their code", False),
+    (
+        "data-engineer",
+        "Data engineer",
+        "pipelines, transformations, storage contracts and data reliability",
+        False,
+    ),
+    ("devops", "Platform / DevOps lead", "security, reliability, performance, cost and CI", True),
+    ("data", "Data & analytics lead", "events, schemas and comparable measurement", True),
+    ("product-design", "Product designer", "design system, accessibility and user flows", True),
+    ("po", "Product manager", "scope, priority and delivery coherence", True),
+    ("llm-engineer", "AI / LLM engineer", "model calls, prompts, evaluations and token cost", True),
+    ("ai-manager", "AI portfolio lead", "initiative overlap, adoption and portfolio value", True),
+    # Marketing, legal and finance
+    ("brand-lead", "Brand lead", "positioning, priorities and brand coherence", True),
+    ("content", "Content lead", "owns pieces, channels and editorial intent", False),
+    ("performance", "Performance marketing lead", "paid acquisition, spend and conversion", True),
+    ("seo", "SEO lead", "organic structure, indexing, links and durable URLs", True),
+    (
+        "lifecycle",
+        "Lifecycle / CRM lead",
+        "segments, triggers, sequences and contact pressure",
+        True,
+    ),
+    ("managing-partner", "Managing partner", "practice direction, matters and staffing", True),
+    ("associate", "Lawyer / associate", "owns matters and their legal context", False),
+    ("compliance", "Compliance lead", "obligations, deadlines, conflicts and records", True),
+    ("knowledge", "Knowledge lead", "precedents, reusable work and institutional memory", True),
+    ("cfo", "CFO / finance lead", "financial direction, priorities and resource choices", True),
+    ("controller", "Controller", "close, reconciliations, controls and audit trail", True),
+    (
+        "fin-analytics",
+        "Financial analyst",
+        "definitions, comparability, forecasts and scenarios",
+        True,
+    ),
+    ("ops", "Operations specialist", "owns operational processes and their exceptions", False),
+    # Healthcare
+    (
+        "clinical-director",
+        "Clinical director",
+        "clinical direction, accountability and care priorities",
+        True,
+    ),
+    ("clinician", "Clinician", "owns patient or pathway context and clinical judgement", False),
+    (
+        "patient-safety",
+        "Patient safety & quality lead",
+        "harm prevention, incidents and safeguards",
+        True,
+    ),
+    (
+        "clinical-ops",
+        "Clinical operations lead",
+        "capacity, pathways, handoffs and service delivery",
+        True,
+    ),
+    ("health-data", "Clinical data lead", "health measures, provenance and data quality", True),
+    (
+        "health-compliance",
+        "Health privacy & compliance lead",
+        "privacy, consent, access and regulation",
+        True,
+    ),
+    # Revenue
+    ("revenue-lead", "Revenue leader", "commercial direction, forecast and commitments", True),
+    ("account-executive", "Account executive", "owns opportunities and buyer context", False),
+    (
+        "revops",
+        "Revenue operations lead",
+        "pipeline definitions, routing, systems and forecast hygiene",
+        True,
+    ),
+    (
+        "customer-success",
+        "Customer success lead",
+        "adoption, outcomes, renewal and churn risk",
+        True,
+    ),
+    (
+        "enablement",
+        "Sales enablement lead",
+        "playbooks, evidence and reusable field knowledge",
+        True,
+    ),
+    # Research and general operations
+    (
+        "research-director",
+        "Research director",
+        "questions, portfolio direction and research decisions",
+        True,
+    ),
+    ("researcher", "Researcher", "owns studies, sources and interpretation", False),
+    (
+        "methods",
+        "Methods / statistics lead",
+        "study design, validity, uncertainty and analysis",
+        True,
+    ),
+    (
+        "research-ops",
+        "Research operations lead",
+        "participants, tooling, data and study delivery",
+        True,
+    ),
+    ("ethics", "Ethics lead", "consent, proportionality, vulnerable groups and review", True),
+    ("operations-lead", "Operations lead", "operating direction, outcomes and trade-offs", True),
+    ("program-manager", "Programme manager", "dependencies, scope, milestones and delivery", True),
+    ("process-owner", "Process owner", "owns a process, its exceptions and its outcomes", False),
+    (
+        "quality",
+        "Quality & risk lead",
+        "acceptance, failure modes, controls and verification",
+        True,
+    ),
+    ("city-lead", "City lead", "sets direction and chairs decisions in a custom domain", True),
+    ("specialist", "Domain specialist", "owns a body of work and answers from its evidence", False),
+]
+
+# Short, lowercase and stable. A role nobody anticipated still gets a sensible name
+# from `sufijo()` rather than nothing.
+SUFIJOS = {
+    "blank": "blank",
+    "cpto": "lead",
+    "devops": "ops",
+    "data": "data",
+    "product-design": "design",
+    "po": "po",
+    "llm-engineer": "llm",
+    "ai-manager": "ai",
+    "dev": "dev",
+    "data-engineer": "dataeng",
+    "brand-lead": "brand",
+    "content": "content",
+    "performance": "ads",
+    "seo": "seo",
+    "lifecycle": "crm",
+    "managing-partner": "partner",
+    "associate": "assoc",
+    "compliance": "comp",
+    "knowledge": "know",
+    "cfo": "cfo",
+    "controller": "ctrl",
+    "fin-analytics": "fin",
+    "ops": "ops",
+    "clinical-director": "clinical",
+    "clinician": "clinician",
+    "patient-safety": "safety",
+    "clinical-ops": "careops",
+    "health-data": "healthdata",
+    "health-compliance": "privacy",
+    "revenue-lead": "revenue",
+    "account-executive": "account",
+    "revops": "revops",
+    "customer-success": "success",
+    "enablement": "enable",
+    "research-director": "research",
+    "researcher": "researcher",
+    "methods": "methods",
+    "research-ops": "resops",
+    "ethics": "ethics",
+    "operations-lead": "operations",
+    "program-manager": "program",
+    "process-owner": "process",
+    "quality": "quality",
+    "city-lead": "lead",
+    "specialist": "specialist",
+}
+
+# Whoever sets the goals. Not a style rule: goals are the one thing this system keeps
+# whatever kind of city you build, and they are agreed between the architect and each
+# city seat. Without that seat there is nobody to agree them with, and every round
+# degrades into a status report.
+ARQUITECTOS = {
+    "cpto",
+    "brand-lead",
+    "managing-partner",
+    "cfo",
+    "clinical-director",
+    "revenue-lead",
+    "research-director",
+    "operations-lead",
+    "city-lead",
+}
+
+
+def sufijo(rol):
+    """The agent-name suffix for a role."""
+    return SUFIJOS.get(rol, rol.split("-")[0][:8])
+
+
+def agente(usuario, rol, ciudad=""):
+    """A stable owner/city address, or the legacy user/role address.
+
+    Repo agents stay private behind the seat.  Once a city is known, the public
+    endpoint is ``user/city`` so changing its role cannot break every road.
+    """
+    if ciudad:
+        segura = re.sub(r"[^a-z0-9-]+", "-", ciudad.lower()).strip("-") or "city"
+        return f"{usuario}/{segura}"
+    return f"{usuario}/{sufijo(rol)}"
+
+
+def nombre(rol):
+    """What the city calls this role, or a readable version of its id."""
+    for r, n, _, _ in CATALOGO:
+        if r == rol:
+            return n
+    return rol.replace("-", " ").title()
+
+
+def oficio(rol, datos=""):
+    """The trade, read from the role's own file — never from a table in code.
+
+    A hardcoded map labels every unknown role as the same thing, which is exactly
+    what once turned a managing partner into a master builder. Looked up in the data
+    repo first (roles are data, and a team renames them), then in the examples this
+    plugin ships. `../roles/examples` and not a path through the clone, because the
+    installed plugin has no clone — this is the one lookup that works at both doors.
+
+    There were two copies of this: the wizard's skipped the data repo, so a re-run
+    against renamed roles showed the stale trade. One copy, the complete one.
+    """
+    if rol == "blank":
+        return "No preset"
+    bases = [os.path.join(datos, "roles")] if datos else []
+    bases.append(os.path.join(AQUI, "..", "roles", "examples"))
+    for base in bases:
+        f = os.path.join(base, f"{rol}.md")
+        if os.path.exists(f):
+            m = re.search(r"^trade:\s*(.+)$", open(f).read(), re.M)
+            if m:
+                return m.group(1).strip()
+    # No role file: say what the role is called rather than inventing a trade.
+    return rol.replace("-", " ").title()
+
+
+def transversal(rol):
+    """Whether this role owns a property of every folder rather than folders."""
+    for r, _, _, t in CATALOGO:
+        if r == rol:
+            return t
+    return True