{
  "schema": "leumas.docs.page/1",
  "id": "skill:leumas-architecture",
  "slug": "skills/leumas-architecture",
  "kind": "tools",
  "bucket": "skill",
  "title": "leumas-architecture",
  "name": "Leumas Architecture",
  "eyebrow": null,
  "chip": null,
  "summary": "Read or change the Leumas architecture graph — add a node, wire two things together, bind a node to real code. Use for architecture map, ecosystem graph, ops/architecture, pnpm arch.",
  "keywords": [
    "leumas-architecture",
    "arch",
    "wire",
    "ecosystem",
    "graph",
    "leumas architecture architecture",
    "touch file",
    "pnpm"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "\n# The architecture graph\n\n`ops/architecture/*.graph.json` is the map of the Leumas ecosystem: Leumas at the root, products\nbranching off it, each product owning its own subtree. Leumas Admin renders and edits it at\n`/architecture`. It is a repo file, so your edit and a canvas edit are the same edit.\n\n**Use the CLI. Do not hand-edit the JSON.** Position, lane, colour, card shape, region and edge ids are\nall derived — say what a thing *is* and what *owns* it, and the tools do the rest.\n\n## Read\n\n```bash\npnpm arch ls                      # every node: id, kind, owner, label\npnpm arch show studio             # one node + every wire touching it\npnpm arch next                    # planned work whose owner is already built — start here\n```\n\nGraphs: `ecosystem` (default — Leumas → products → domains → tabs → sub-tabs, every one the nav\nmanifests declare) · `leumas-api` · `shared-code`.\n\nThe tree under Studio and Admin is **generated**: `node ops/architecture/import-nav.mjs --write` walks\nboth nav manifests. It never overwrites a label, blurb, note, status, proof or position you set by\nhand — so add a domain to a manifest, re-run it, and only the new nodes appear.\n\n## Change\n\n```bash\npnpm arch add <id> --owner <id> --label \"...\" --refs <repo/path> [--uses <id>] [--blurb \"...\"]\npnpm arch wire <from> <to> --uses          # also: --owns --governs --exposes\npnpm arch unwire <from> <to>\npnpm arch mv <id> --owner <newOwner>       # re-parent; lane/region/position recomputed\npnpm arch set <id> --label \"...\" --refs <path>\npnpm arch rm <id> [--force]                # --force also removes what it owns\npnpm arch tidy                             # place anything new; --only all re-ranks the whole graph\npnpm arch status <id> --done               # also --planned --building --verified\npnpm arch status <id> --verified --proof \"pnpm check:nav\"\npnpm check:architecture                    # always finish with this\n```\n\n## Status — this is a worklist, keep it true\n\nEvery node is `planned` → `building` → `done` → `verified`, and the guard checks the claim against the\nfilesystem:\n\n| | |\n|---|---|\n| `planned` | not built. If its code turns up, the guard says \"mark it done\". |\n| `building` | someone is on it. Unchecked — the one honest gap. |\n| `done` | [critical] **hard fail** if any exact ref does not resolve |\n| `verified` | [critical] **hard fail** without `--proof \"<a pnpm script that exists>\"` |\n\n**When you finish a piece of work, mark its node.** That is what makes `pnpm arch next` mean\nsomething, and it is the only reason the graph can tell the next agent what is left.\n\nEvery node has **exactly one owner**, so `--owner` is required on `add`. `--refs` are repo-relative\npaths; prefix one with `?` if it is planned rather than built.\n\n## The four relationships\n\n| flag | means |\n|---|---|\n| `--owns` | the target belongs to the source — this is the tree, one owner per node |\n| `--governs` | the source sets policy for something it does not own |\n| `--uses` | the source imports or calls the target |\n| `--exposes` | the target is a faculty the source offers |\n\n## Two rules\n\n**Never invent a position.** `add` writes no coordinate; `pnpm arch tidy` places whatever is new, and\nthe canvas has the same button. The layout is deterministic and idempotent, so running it twice is a\nno-op — that is what makes a tidied graph committable.\n\n**When a graph gets big, go deeper, not wider.** Move detail into a new `<id>.graph.json` and point the\nparent node at it with `--into <graphId>`. The root graph is meant to stay the same size however large\nLeumas gets.\n\n## If you must touch the file\n\nEvery node and edge is exactly one line, so `grep -n '\"id\":\"studio\"' ops/architecture/ecosystem.graph.json`\ngives you the line to edit. Never read the whole file. Run `pnpm check:architecture --fix` afterwards to\nrestore canonical form — a reflowed file breaks every line anchor and turns a one-node change into a\nwhole-file diff.\n",
  "source": {
    "path": ".claude/skills/leumas-architecture/SKILL.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 4194,
    "hash": "9acee36df3111370aac1e89ce76564f42fd6b3ec"
  },
  "urls": {
    "html": "/p/skills/leumas-architecture",
    "json": "/docs/skills/leumas-architecture.json",
    "md": "/docs/skills/leumas-architecture.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}