opsinjs
Agents and LLMs
The stable machine surfaces, the rules for generating safe health UI, and how to connect an agent
Every page and every component id answers at a stable address, so an agent can look a fact up instead of guessing it.
Machine surfaces
| Path | What it is |
|---|---|
/llms.txt | Index of every page, with absolute URLs and each component's status. Start here |
/llms-full.txt | The whole corpus, size-capped. A ## Truncated block at the end names any page it drops |
/llms-components.txt, /llms-health.txt, /llms-foundations.txt, /llms-reference.txt | Topic shards. Each carries its sections whole |
<page URL>.md | The markdown twin of any page. The documentation index is /docs.md |
/r/index.json | The roster: every component id with status, implemented, category and aliases |
/r/registry.json | The shadcn-spec catalogue, which the shadcn MCP server reads |
/r/<name>.json | One registry item, carrying its source and meta.opsinjs.implemented |
/r/docs.json | The corpus as one versioned, size-capped JSON file for offline use. included and omitted say whether it carries every page |
Page HTML, class names, heading anchors and /view preview routes are not a contract, so link to a page rather than a fragment.
The markdown twin
Append .md to any page URL. Documentation components stay as tags whose attributes are the content, such as <ComponentPreview name="range-bar" />, and the values they draw are published at /r/index.json and in Reference. A component twin carries status and implemented in its frontmatter. Every twin sends the docs version in an x-opsinjs-docs-version header, which a saved file loses, so store it beside any cached copy.
Rules for agents
- Tokens, not values. Never emit a hex,
rgb(), pixel radius or millisecond duration. Use a token or a utility that resolves to one. - Status, not colour. Set a level (
steady,watch,attention,urgent) and let the system choose the colour. Never render a status without its word. - One axis per element. Category and status never colour the same element. See Two colour axes.
- Never invent a component, prop or variant. Read
/r/index.jsonand the installed source. If an id is not in the catalogue, say so and stop. For aplannedid, describe the specification and emit no import. No id is planned today. - Never assume a registry. Check
components.jsonfor@opsinjsbefore emittingadd @opsinjs/<name>, and offer the one-line addition first. - Never invent a number. No threshold, reference range, contrast ratio or bundle size unless a generated source you read supplied it.
- Never decide a threshold. Whether a reading is high belongs to the product's clinical logic, not to opsinjs and not to you. See Reference ranges.
- Never soften a clinical message. "Nothing to worry about" is a different clinical claim, not friendlier copy for
watch. - Never generate an accessibility claim such as "meets WCAG AA" in code, a comment or a commit message.
- Say what
shippedcosts. Every id isshipped. Its API may change in any release, its WCAG 2.2 AA audit was run by its own authors, and it has had no independent accessibility review and no clinical review. Nothing here is for a production health surface. - Install source, never import a package. No opsinjs package is published, so
@opsinjs/reactnever resolves. - Cite the page you used.
// Right: the level is data, the word and the colour are the system's business.
<StatusPill status="watch" describes="HbA1c result" />
// Wrong: a colour decision, an invented prop, and no word.
<StatusPill color="#f59e0b" />Connect an agent
Register the namespace in components.json:
{
"registries": {
"@opsinjs": "https://opsinjs.pensievelabs.org/r/{name}.json"
}
}MCP. opsinjs has no MCP server of its own. The shadcn MCP server reads this registry and supplies inventory, not judgement. Substitute cursor, vscode, codex or opencode for your client.
npx shadcn@latest mcp init --client claudeSkill. The skill at skills/opsinjs/ in the repository holds SKILL.md, four rule files and an eval set. npx skills add prashantonomy/opsinjs installs it, or you can paste the rules above into your system prompt. The skill cannot judge clinical correctness, and its presence is no evidence of a clinical review.
Evals
skills/opsinjs/evals/evals.json holds 22 tasks that score the docs, not a model. Each asks a question an agent would ask and asserts what the answering page must and must not say. pnpm run evals scores them against a pass mark of 0.9. Scores are advisory and are not shown on this site yet.
scripts/run-evals.mts. Run pnpm run generate and reload.Nothing on this site types a measured number by hand, so an ungenerated table shows this rather than an example.