{
  "schema": "leumas.docs.page/1",
  "id": "pkg:@leumas/docs",
  "slug": "products/docs",
  "kind": "capabilities",
  "bucket": "product",
  "title": "Leumas Docs — @leumas/docs",
  "name": "Leumas Docs",
  "eyebrow": null,
  "chip": "@leumas/docs",
  "summary": "The public Leumas knowledge bank -- generated reference, downloadable agent skills and a flat-file read API for coding agents, served at docs.leumas.tech.",
  "keywords": [
    "leumas-docs",
    "leumas-run",
    "tech",
    "appliances",
    "architecture",
    "leumas docs api",
    "leumas leumas docs",
    "how to use leumas docs"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# Leumas Docs — `@leumas/docs`\n\n**Documentation as a product — generated, not hand-written.**\nServed three ways: to humans as a site, to agents over MCP, to machines over HTTP.\n\n`docs.leumas.tech`, **hosted through Imperium on the Leumas-run Studio**.\nArchitecture: [APPLIANCES.md](../../APPLIANCES.md) §8 · [PLATFORM.md](../../PLATFORM.md)\n\n---\n\n## Core functionality\n\n1. **Generated reference** — crawls the workspace for every `README.md`, `package.json`, adapter and\n   MCP `server.json`, nav manifest, route manifest, and Imperium mode schema. One source of truth that\n   updates as the ecosystem grows.\n2. **The human site** — searchable docs on `@leumas/ui` + `@leumas/theme`, served as an Imperium\n   config like every other Leumas site.\n3. **The `leumas-docs` MCP server** — so Claude, Cursor and any coding agent can read Leumas docs\n   directly. Uses the **existing** MCP loader; no new mechanism.\n4. **The read API** — `GET /api/docs/*` (search · page · symbol) so other apps and agents can consume\n   it over plain HTTP.\n5. **Leumaepedia** — the wiki, absorbed from Studio's `knowledge` domain.\n6. **Build-knowledge for agents** — the half of the Knowledge Bank that tells AI agents *how to build\n   with Leumas*, not just what Leumas is.\n\n## What it must never do\n\n| Never | Because |\n|---|---|\n| Hand-maintain a page that could be generated | it will go stale. The whole point is derivation |\n| Be its own hosting stack | it's an Imperium config like every other Leumas site |\n| Duplicate the Knowledge Bank | it *renders* `shared/services/knowledge`, it doesn't fork it |\n| Invent an MCP mechanism | `shared/engines/mcp/src/loader.js` already walks a dir and loads `server.json` + `tools/*` |\n\n## Sources it derives from\n\n| Source | Gives |\n|---|---|\n| `products/*/README.md` | the six products — core functionality, file trees, roadmaps |\n| `shared/{packages,engines,services}/*/README.md` + `package.json` | every library, module and backend |\n| `shared/engines/adapters/**` | domain packs and knowledge banks |\n| `shared/engines/mcp/mcp-servers/*/server.json` | every MCP server and tool, with `price` |\n| `shared/packages/config-registry/src/{modes,dataSchemas}.js` | the 30 Imperium modes and their fields |\n| `products/leumas-studio/src/admin/nav.manifest.js` | every Studio surface |\n| `shared/services/knowledge/` | domain knowledge + build-knowledge |\n| `CONTROL-PLANE.md` · `PLATFORM.md` · `APPLIANCES.md` · `CLAUDE.md` | the architecture of record |\n| `/index/*` | the live registry — apps, tools, capabilities, chatbots |\n\n## Composes\n\n```\n@leumas/ui  @leumas/theme        the st- kit + tokens\n@leumas/api-client               reads /index/* and /api/docs/*\n@leumas/config-registry          rendered as an Imperium config\n@leumas/index-service            the createIndexRouter({sources}) pattern the read API copies\n@leumas/mcp                      the loader that picks up the docs server automatically\n```\n\n## File tree\n\n```\nproducts/leumas-docs/\n├── package.json [todo] DOES NOT EXIST YET\n├── vite.config.js [todo]\n├── index.html [todo]\n├── README.md [done] this file — currently the only file\n├── scripts/\n│ └── generate.mjs [todo] crawl the workspace → docs/*.json\n├── docs/ [todo] generated. gitignored\n└── src/\n ├── main.jsx [todo]\n ├── App.jsx [todo] search · sidebar · page · symbol\n └── pages/ [todo] Package · Engine · Service · Product · Mode · MCP · Wiki\n\nshared/engines/mcp/mcp-servers/leumas-docs/ [todo] the MCP server\n├── server.json                                    name · description · tools[] (+ price)\n└── tools/\n    ├── searchDocs.js                              q → ranked pages\n    ├── getPage.js                                 slug → content\n    ├── listPackages.js                            every @leumas/* + what it does\n    ├── getSymbol.js                               an export → where it lives + its signature\n    └── howDoI.js                                  a task → the build-knowledge recipe\n\nshared/services/index/src/docsRouter.js [done] GET /api/docs/{search,packages,symbol,page}\nshared/services/index/src/docsSite.js [done] the docs.leumas.tech Imperium row, ensured at boot\n```\n\n## Roadmap\n\n### [todo] D1 · The generator\n\n- Status: todo — `scripts/generate.mjs` — crawl every source in the table above into `docs/*.json`\n- Status: todo — Run it in CI so it can never drift from the code\n- Status: todo — Guard: a package with no README, or a README missing its core-functionality block, fails the build\n- Status: todo — Provenance: every generated page links back to the file it came from\n\n### [todo] D2 · The MCP server\n\n*Do this second, before the site — it's the highest-leverage output and it reuses everything.*\n\n- Status: todo — `shared/engines/mcp/mcp-servers/leumas-docs/{server.json,tools/*}` — the existing loader picks it\n      up with **zero new mechanism**\n- Status: todo — `searchDocs` · `getPage` · `listPackages` · `getSymbol` · `howDoI`\n- Status: todo — Note: the loader is env-gated — without `MCP_SERVERS_DIR` set, **zero servers load**\n- Status: todo — Verify from Claude Code: \"what does `@leumas/entitlements` do?\" answers from the graph, not guesses\n\n### [done] D3 · The read API\n\n- Status: done — `GET /api/docs/{search,packages,symbol,page}` — `@leumas/index-service/docs-router`, mounted in\n      `leumas-api/src/app.js` with its own `docs:read` limiter (120/min)\n- Status: done — Public read; no auth (documentation is not secret) — the gate is at BUILD time, in\n      `docs.manifest.mjs`, which is the only place it can be verified\n- Status: done — Publicly cacheable: success responses set `public, max-age=300`; a 503 or 404 does not\n\n### [todo] D4 · The site\n\n- Status: todo — Vite app on `@leumas/ui` + `@leumas/theme`\n- Status: done — Publish as an Imperium config on `docs.leumas.tech` — the product-site pattern\n      ([PLATFORM.md](../../PLATFORM.md) §5). Provisioned at boot by `ensureDocsSite`\n      (`@leumas/index-service/docs-site`), `LEUMAS_ROLE=platform` only. Two things about that row are\n      counter-intuitive enough to be worth stating here: it is on the **hosted** lane, not\n      `firstParty`, because a first-party row has `hosting: null` and so structurally cannot carry a\n      target; and its `ownerUserId` is deliberately **empty**, because a non-empty one arms a live\n      entitlement re-check whose only possible effect on a platform site is an outage.\n- Status: todo — SEO: canonical, JSON-LD `TechArticle`, per-page OG images, in the cluster sitemap index\n- Status: todo — Server-rendered above-the-fold content — docs that need JS to show a heading don't rank\n\n### [todo] D5 · Absorb Studio's `knowledge` domain (roadmap B7)\n\n- Status: todo — Leumaepedia (`WikiSurface`) moves here\n- Status: todo — The two `deferred: true` sub-items (Docs Feed, leumas-knowledge MCP) are **built here**, not there\n- Status: todo — Delete the domain from Studio's nav\n\n### [todo] D6 · Build-knowledge for agents\n\n- Status: todo — Render the `shared/services/knowledge` build-knowledge as first-class pages — how to add a\n      package, wire a router, write a plugin manifest, launch a site\n- Status: todo — Every recipe cites the file it's derived from, so a stale recipe is detectable\n\n## Status\n\nBuilt and shipping: the generator (`scripts/generate.mjs`), the corpus under `dist/docs`, the\nReact site with SSR prerender, `llms.txt` / `llms-full.txt`, and the **`leumas-docs` MCP server**\n(`shared/engines/mcp/mcp-servers/leumas-docs/`) with `searchDocs` · `getPage` · `getSymbol` ·\n`listPackages` · `howDoI`.\n\n`GET /api/docs/{search,packages,symbol,page}` is mounted in leumas-api\n(`@leumas/index-service/docs-router`) and is a thin projection of those same tools over the same\nscorer and the same corpus reader — `pnpm smoke:docs-api` asserts the two rank **identically**,\nbecause a docs site and an agent that disagree cannot detect it from either side.\n\n> [warning] **This section said \"one file — this README. Everything above is unbuilt\" long after it stopped\n> being true**, and a reader believed it: a survey of the ecosystem reported the whole product as a\n> stub while the corpus, the site and the MCP server were all shipping. A stale status line is worse\n> than none, because it is the one part of a README people trust without checking. Unticked boxes\n> below are the honest record of what is still open; this paragraph is not a substitute for reading\n> them.\n",
  "source": {
    "path": "products/leumas-docs/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 8705,
    "hash": "affd6c1dd6a97b29c31b2eeb1fef56f34de50766"
  },
  "urls": {
    "html": "/p/products/docs",
    "json": "/docs/products/docs.json",
    "md": "/docs/products/docs.md"
  },
  "links": {
    "composes": [
      "pkg:@leumas/config-registry",
      "pkg:@leumas/index-service",
      "pkg:@leumas/theme",
      "pkg:@leumas/ui"
    ],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  },
  "exports": null
}