Leumas Docs — @leumas/docs

Documentation as a product — generated, not hand-written. Served three ways: to humans as a site, to agents over MCP, to machines over HTTP.

docs.leumas.tech, hosted through Imperium on the Leumas-run Studio. Architecture: APPLIANCES.md §8 · PLATFORM.md

---

Core functionality

1. Generated reference — crawls the workspace for every README.md, package.json, adapter and

MCP server.json, nav manifest, route manifest, and Imperium mode schema. One source of truth that updates as the ecosystem grows.

1. The human site — searchable docs on @leumas/ui + @leumas/theme, served as an Imperium

config like every other Leumas site.

1. The leumas-docs MCP server — so Claude, Cursor and any coding agent can read Leumas docs

directly. Uses the existing MCP loader; no new mechanism.

1. The read API — GET /api/docs/* (search · page · symbol) so other apps and agents can consume

it over plain HTTP.

1. Leumaepedia — the wiki, absorbed from Studio's knowledge domain.
2. Build-knowledge for agents — the half of the Knowledge Bank that tells AI agents *how to build

with Leumas*, not just what Leumas is.

What it must never do

Sources it derives from

Composes

@leumas/ui  @leumas/theme        the st- kit + tokens
@leumas/api-client               reads /index/* and /api/docs/*
@leumas/config-registry          rendered as an Imperium config
@leumas/index-service            the createIndexRouter({sources}) pattern the read API copies
@leumas/mcp                      the loader that picks up the docs server automatically

File tree

products/leumas-docs/
├── package.json [todo] DOES NOT EXIST YET
├── vite.config.js [todo]
├── index.html [todo]
├── README.md [done] this file — currently the only file
├── scripts/
│ └── generate.mjs [todo] crawl the workspace → docs/*.json
├── docs/ [todo] generated. gitignored
└── src/
 ├── main.jsx [todo]
 ├── App.jsx [todo] search · sidebar · page · symbol
 └── pages/ [todo] Package · Engine · Service · Product · Mode · MCP · Wiki

shared/engines/mcp/mcp-servers/leumas-docs/ [todo] the MCP server
├── server.json                                    name · description · tools[] (+ price)
└── tools/
    ├── searchDocs.js                              q → ranked pages
    ├── getPage.js                                 slug → content
    ├── listPackages.js                            every @leumas/* + what it does
    ├── getSymbol.js                               an export → where it lives + its signature
    └── howDoI.js                                  a task → the build-knowledge recipe

shared/services/index/src/docsRouter.js [done] GET /api/docs/{search,packages,symbol,page}
shared/services/index/src/docsSite.js [done] the docs.leumas.tech Imperium row, ensured at boot

Roadmap

[todo] D1 · The generator

• Status: todo — scripts/generate.mjs — crawl every source in the table above into docs/*.json
• Status: todo — Run it in CI so it can never drift from the code
• Status: todo — Guard: a package with no README, or a README missing its core-functionality block, fails the build
• Status: todo — Provenance: every generated page links back to the file it came from

[todo] D2 · The MCP server

Do this second, before the site — it's the highest-leverage output and it reuses everything.

• Status: todo — shared/engines/mcp/mcp-servers/leumas-docs/{server.json,tools/*} — the existing loader picks it

up with zero new mechanism

• Status: todo — searchDocs · getPage · listPackages · getSymbol · howDoI
• Status: todo — Note: the loader is env-gated — without MCP_SERVERS_DIR set, zero servers load
• Status: todo — Verify from Claude Code: "what does @leumas/entitlements do?" answers from the graph, not guesses

[done] D3 · The read API

• Status: done — GET /api/docs/{search,packages,symbol,page} — @leumas/index-service/docs-router, mounted in

leumas-api/src/app.js with its own docs:read limiter (120/min)

• Status: done — Public read; no auth (documentation is not secret) — the gate is at BUILD time, in

docs.manifest.mjs, which is the only place it can be verified

• Status: done — Publicly cacheable: success responses set public, max-age=300; a 503 or 404 does not

[todo] D4 · The site

• Status: todo — Vite app on @leumas/ui + @leumas/theme
• Status: done — Publish as an Imperium config on docs.leumas.tech — the product-site pattern

(PLATFORM.md §5). Provisioned at boot by ensureDocsSite (@leumas/index-service/docs-site), LEUMAS_ROLE=platform only. Two things about that row are counter-intuitive enough to be worth stating here: it is on the hosted lane, not firstParty, because a first-party row has hosting: null and so structurally cannot carry a target; and its ownerUserId is deliberately empty, because a non-empty one arms a live entitlement re-check whose only possible effect on a platform site is an outage.

• Status: todo — SEO: canonical, JSON-LD TechArticle, per-page OG images, in the cluster sitemap index
• Status: todo — Server-rendered above-the-fold content — docs that need JS to show a heading don't rank

[todo] D5 · Absorb Studio's knowledge domain (roadmap B7)

• Status: todo — Leumaepedia (WikiSurface) moves here
• Status: todo — The two deferred: true sub-items (Docs Feed, leumas-knowledge MCP) are built here, not there
• Status: todo — Delete the domain from Studio's nav

[todo] D6 · Build-knowledge for agents

• Status: todo — Render the shared/services/knowledge build-knowledge as first-class pages — how to add a

package, wire a router, write a plugin manifest, launch a site

• Status: todo — Every recipe cites the file it's derived from, so a stale recipe is detectable

Status

Built and shipping: the generator (scripts/generate.mjs), the corpus under dist/docs, the React site with SSR prerender, llms.txt / llms-full.txt, and the leumas-docs MCP server (shared/engines/mcp/mcp-servers/leumas-docs/) with searchDocs · getPage · getSymbol · listPackages · howDoI.

GET /api/docs/{search,packages,symbol,page} is mounted in leumas-api (@leumas/index-service/docs-router) and is a thin projection of those same tools over the same scorer and the same corpus reader — pnpm smoke:docs-api asserts the two rank identically, because a docs site and an agent that disagree cannot detect it from either side.

[warning] This section said "one file — this README. Everything above is unbuilt" long after it stopped being true, and a reader believed it: a survey of the ecosystem reported the whole product as a stub while the corpus, the site and the MCP server were all shipping. A stale status line is worse than none, because it is the one part of a README people trust without checking. Unticked boxes below are the honest record of what is still open; this paragraph is not a substitute for reading them.