{
  "schema": "leumas.docs.page/1",
  "id": "skill:leumas-body",
  "slug": "skills/leumas-body",
  "kind": "tools",
  "bucket": "skill",
  "title": "leumas-body",
  "name": "Leumas Body",
  "eyebrow": null,
  "chip": null,
  "summary": "The BODY primitive — a species-agnostic anatomical graph and the Human Atlas over it. Read before touching @leumas/body, the atlas, or any anatomical claim.",
  "keywords": [
    "leumas-body",
    "anatomical",
    "atlas",
    "answering anatomy question",
    "primitive",
    "adding species",
    "human",
    "claim"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "\n# Body — the organism primitive\n\nLeumas understands files, devices, networks, APIs, workflows and 3D scenes. **BODY** is the primitive\nthat makes it understand organisms: systems, structures, the typed relationships between them, and\nthe processes they take part in. The Human Atlas is the first interface on top of it, not the thing\nitself.\n\n## The one claim everything here is built around\n\n> **The 3D model is not the body.** The body is a structured biological graph; a mesh is one\n> representation hung off a node of it.\n\nEvery question the atlas answers is answerable with **no geometry loaded**. Almost every structure has\nno mesh at all and is fully searchable, traversable and citable. That is what makes the atlas\nscriptable from an MCP client with no viewer, usable without a GPU, and correct about the part of the\nbody nobody has modelled.\n\nAn agent that reads \"not drawn\" as \"not present\" will report most of the body missing.\n\n> **Most positions in this atlas were DERIVED, not authored.** The human body plan places every bone,\n> every named joint, every muscle group, the whole viscera and the major vessels and nerves by hand;\n> everything else is put inside whatever the ontology says contains it. The dog is still at its\n> original ~110. `check:body` prints the live split — never quote a count from here.\n> Every one carries its tier and a sentence explaining it — `body.describe(id).placement`, or the\n> `getPlacement` tool. **Quote the explanation, never the coordinates alone.** `docs/placement.md`.\n\n## Where things are\n\n| Thing | Where |\n|---|---|\n| The engine — graph, search, registry, validation, adapters | `shared/packages/body/` (`@leumas/body`) |\n| The 3D viewer, layer system, command executor | `shared/packages/body-viewer/` (`@leumas/body-viewer`) |\n| The app — listing, 22 agent tools, MCP, REST, domain claim | `shared/apps/body-atlas/` |\n| The Studio domain — Explore, Tree, Graph, Lessons, Sources | `products/leumas-studio/src/admin/body/` |\n| The API | `/api/body`, mounted in `products/leumas-api/src/app.js` |\n| The importer | `ops/tools/anatomy-ingest/` — `pnpm anatomy:update uberon` |\n| The guard | `pnpm check:body` (self-tests) · `pnpm test:body` |\n| Developer docs | `shared/packages/body/docs/` — one file per \"how do I add a …\" |\n\n## The vocabulary, in six lines\n\n- **Species** — `human`, `test-organism`. Data, listed in `data/species/index.js`.\n- **Variant** — `adult-male`, `adult-female`. **Sex is a variant, never a global switch.**\n- **Structure** — `anatomy:<species>:<slug>`. The only key anything is synchronised by.\n- **System** / **Region** — `system:human:skeletal`, `region:human:hand`. Groupings, not graph nodes.\n- **Relationship** — one of **64 closed types** (`GET /api/body/relations`). An invented one\n  traverses to nothing while every guard passes.\n- **Process** — `process:human:respiration`. Physiology, in the same graph, its own id class.\n\n## Answering an anatomy question\n\n**Always through the graph. Never from memory.**\n\n```\nPOST /api/body/human/adult-female/ask   { \"question\": \"What supplies the heart with blood?\" }\n  → { plan, facts, structures[], visualActions[], sources[], note }\n```\n\n`facts` is the answer, `sources` is where it came from, `visualActions` drives the viewer. Put the\nfacts into English afterwards — do **not** substitute your own recall when `answerable: true`.\n\nWhen `answerable: false`, `note` says why, and the honest thing is to repeat it.\n\n## The four sentences to get right\n\n1. **An empty relationship list is a statement about the DATA, never about the body.** Every organ\n   has a blood supply; this dataset asserts one for a minority. Say \"no arterial supply is recorded\n   in this dataset\" — the API already returns exactly that sentence in `note`.\n2. **A fuzzy search hit is a suggestion, not a resolution.** \"femer\"→\"femur\" scores identically to\n   \"ileum\"→\"ilium\", so no threshold separates a helpful correction from a dangerous one. `resolve()`\n   refuses to promote one; so must you.\n3. **The geometry is SCHEMATIC.** Primitives at roughly the right position, not organ shape —\n   `manifest.schematic === true`, the viewer badges it, and any answer showing it must say so.\n4. **A variant does not hide anatomy, it does not have it.** The prostate is absent from the female\n   body everywhere — graph, search, relationships, manifest. Asking for it 404s, correctly.\n\n## Medical safety — the boundary that is not negotiable\n\nThis is an **educational and informational** anatomy platform. Not a diagnostic system, not a medical\ndevice, not a treatment or prescribing engine, not a substitute for a clinician. There is no verb\nthat takes a symptom and returns a condition, and adding one is a different product.\n\nThree kinds of statement, never blurred:\n\n| Kind | May you produce it? |\n|---|---|\n| **Anatomical fact** — sourced from the graph | Yes, with its citation |\n| **Educational medical information** — general, sourced | Yes, marked as general |\n| **Personal medical advice** — about this person's body | **No** |\n\n## The agent tools\n\n22 of them, from one `defineLeumasApp` declaration, so they are adapter functions, MCP tools,\nLeviathan functioncalls, REST routes and a typed SDK simultaneously. Read-only, `permissions: []`,\nno `req.user` anywhere in the engine.\n\n`listSpecies` · `listVariants` · `listSystems` · `listRegions` · `vocabulary` · `search` ·\n`getStructure` · `getRelationships` · `getChildren` · `getParents` · `contains` · `getBloodSupply` ·\n`getInnervation` · `getPath` · `getSubgraph` · `compareStructures` · `compareVariants` · `ask` ·\n`getSources` · `listLessons` · `getLesson` · `getModelManifest` · `getPlacement` · `viewerCommand` ·\n`stats`\n\n`viewerCommand` cannot reach a browser — nothing on the server can. It **validates** a visual\ninstruction and returns it; the surface in front of the user executes it. The action list is closed\nand every id is checked to exist first, so the worst a hostile command does is change what is on\nscreen.\n\n## Adding a species\n\nA folder and a line. No engine code.\n\n```sh\n# 1. write data/species/<id>/ingest.profile.json   (from an ontology)\n#    or the five dataset files by hand             (curated)\n# 2. add the id to SHIPPED_SPECIES in shared/packages/body/data/species/index.js\nnode ops/tools/anatomy-ingest/index.mjs update uberon --species <id>\nnode ops/tools/anatomy-ingest/index.mjs validate --species <id>\nnode ops/tools/anatomy-ingest/index.mjs schematic --species <id>    # placeholder geometry\n```\n\n`schematic` also prints and commits the **placement ratchet** — what fraction of that body can be\ndrawn at all. `check:body` fails when it falls; only re-running this raises it, which means a person\nsaw the number.\n\nThat claim is enforced rather than hoped for: `test/cross-species.test.js` loads the synthetic\n`test-organism` — three systems that are not human systems — through the same registry, loader,\nvalidator, search index, graph and viewer, and asserts every surface works on it. **Do not delete\nthat species to make a refactor pass.** It is the only thing that notices when the engine quietly\nlearns what a heart is.\n\n## Before you touch anything\n\n| You are about to | Read first |\n|---|---|\n| add a relationship type | `src/relations.js` — the vocabulary is CLOSED for a reason |\n| change how a structure is selected into the human slice | `data/species/human/ingest.profile.json` — the `_readme` records an ingest that lost the pancreas |\n| write an anatomical fact by hand | `data/species/human/relationships.curated.json` — every edge cites a chapter |\n| add geometry | `docs/adding-a-mesh.md` — the manifest slot takes `bundle`+`mesh` instead of `procedural`, and nothing else changes |\n| take a new dataset | `data/licenses/manifest.json` — and check `shareAlike` before anything else |\n| add a viewer action | `body-viewer/src/commands.js` — the list is closed because a model writes into it |\n| say where something is, in ANY surface or answer | `docs/placement.md` — four tiers, and only one of them means somebody looked |\n| author or change a SHAPE in a body plan | `docs/primitives.md` — the nine primitives, which fields scale, and the four ways a shape draws wrong with no error |\n| touch the instanced renderer | `body-viewer/src/InstancedBody.jsx` — six traps, every one of which renders perfectly while being wrong |\n| change a body plan's positions | `data/species/<id>/schematic.layout.json`, then re-run `anatomy-ingest schematic` — it writes the coverage ratchet `check:body` holds you to |\n\n## Prove it\n\n```sh\npnpm check:body        # the dataset, the licences, the lessons, the manifests — and its own self-test\npnpm test:body         # the engine suite + the viewer suite\npnpm anatomy:validate  # every shipped species, as a report\n```\n\n## Related\n\n`leumas-capabilities` (where new code goes) · `leumas-domains` (the Studio domain contract) ·\n`leumas-guards` (which guard proves what) · `threejs-leumas` (the 3D placement rules the viewer obeys).\n",
  "source": {
    "path": ".claude/skills/leumas-body/SKILL.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 9285,
    "hash": "bca9c682bf97b7a6d6fec15b832cbeba3417aa9b"
  },
  "urls": {
    "html": "/p/skills/leumas-body",
    "json": "/docs/skills/leumas-body.json",
    "md": "/docs/skills/leumas-body.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}