Version-matched docs for agents

Read the project's installed Systhema version before asking an API question. Pass it unchanged to the docs service. Use project files for token values and documentation for API behavior.

Read the installed versionLink to this section

Run in the app that depends on core:

node -p "require('./node_modules/@systhemaui/core/package.json').version"

If dependencies are not installed, read the @systhemaui/core range in that app's package.json and use the range as a fallback. State that it is a range rather than a confirmed installed version.

Resolve before searchingLink to this section

With systhema-docs, start with:

{ "version": "1.7.5" }

The service maps a patch to its kept minor. A prerelease of a kept minor also uses that minor; a prerelease of a newer, unreleased minor uses next. Ranges resolve from their minimum version. Archived minors and versions outside the served range return fallback docs with warnings; read those warnings before coding. Include version on every normal docs call; omission means latest, which may differ from the project.

{ "query": "custom block client preview", "version": "1.7.5", "limit": 3 }

Read the relevant result rather than treating the snippet as a complete API contract:

{ "path": "payload/custom-blocks", "version": "1.7.5" }

Use the response's section outline for large pages. See MCP reference for argument limits and continuation behavior.

Retrieve markdown without MCPLink to this section

Set the shell variable SYSTHEMA_DOCS_ORIGIN to the documentation site's HTTPS origin, without a trailing slash. This variable is only for the following curl examples; the CLI installer's origin override is SYSTHEMA_DOCS_URL. The examples below use relative routes against that origin; no /docs prefix belongs in the public path.

DOCS_VERSION=$(node -p "require('./node_modules/@systhemaui/core/package.json').version")
curl -fsSL "${SYSTHEMA_DOCS_ORIGIN}/v/${DOCS_VERSION}/llms.txt"
curl -fsSL "${SYSTHEMA_DOCS_ORIGIN}/v/${DOCS_VERSION}/components/button.md"

Full versions resolve through the docs proxy with a 308 redirect. A kept latest minor uses the root; an older kept minor uses /v/<minor>. A prerelease of a kept minor stays on that minor, while an unreleased newer minor uses /next. Follow the resolved links for subsequent reads.

Runtime messages use docsUrl(route, anchor?), which pins the package's own full version in docs.systhema.app/v/<full version>/<route>. The proxy resolves that pin; the helper does not construct a minor URL itself.

The latest version also has /llms.txt; unreleased main has /next/llms.txt. Avoid loading llms-full.txt as a default context source. Search and selected pages consume much less context.

Request a page or sectionLink to this section

The .md suffix and Accept: text/markdown are equivalent ways to request markdown:

curl -fsSL -H 'Accept: text/markdown' \
  "${SYSTHEMA_DOCS_ORIGIN}/v/1.7/components/button"
curl -fsSL "${SYSTHEMA_DOCS_ORIGIN}/v/1.7/components/button.md?section=variants"

Use a heading slug from the actual page outline. Do not invent an anchor from a heading you remember.

Search returns markdown when you request format=md:

curl -fsSL --get "${SYSTHEMA_DOCS_ORIGIN}/api/search" \
  --data-urlencode 'format=md' \
  --data-urlencode 'v=1.7.5' \
  --data-urlencode 'q=custom block preview'

Keep token facts localLink to this section

Read .systhema/references/tokens/_index.toon, collection references, generated types and systhema.config.ts for this project's themes, variants and values. Documentation defaults cannot prove a project has a dark mode or a particular button variant.

When the service is unavailable, use installed package types and local project sources. Report the lookup failure and distinguish locally verified behavior from assumptions. Do not substitute latest docs silently.