Skip to content

Decision record · ADR

ADR-0054: Give agents plain-text documentation: bundle the support matrix with the skill and publish Markdown alternates

Status: accepted | Date: 2026-10-01

References: RFC-0011, RFC-0008, ADR-0045

Agents read InferLab documentation as plain text. The agent skill linked the backend support matrix at docs/backend-support.md through a relative path that leaves the plugin directory. The release archive carries that file at its root, but Claude Code and Codex copy only plugins/inferlab into their plugin caches, so the link the installed skill follows does not resolve; a test pinned that link without exercising an installed cache. Linking the public website instead returns rendered HTML with navigation and styling, which is costly and noisy for an agent, and it shows only the current main snapshot rather than the version an installed agent runs. ADR-0045 names the matrix version-correspondence table as an authority surface agents must consult, so the matrix has to be reachable from where agents actually read.

The backend support matrix lives at plugins/inferlab/skills/inferlab/references/backend-support.md and remains the single authority for publicly qualified backend capabilities and the version-correspondence table. Skill references link it relatively, so every installed plugin cache carries it at the plugin version. README and the website projection reference the new location; the release archive no longer carries a separate root copy. The public website additionally publishes, for every projected documentation page, a plain-text Markdown alternate at the page route with a .md suffix, plus llms.txt, an index that links those alternates, and llms-full.txt, their concatenation. Both are generated from the projected sources at build time and are never edited independently.

Agents reach the matrix offline and in plain text from the installed skill, and online agents can read any website page as Markdown without parsing HTML. The website still represents only the current main snapshot; an agent needing an older release reads the matrix bundled with that release. Moving the file updates several mechanical references in one change, and the public-register guard must keep exempting the matrix from the versioned-fact rule at its new path. The website build gains generated text outputs whose drift is prevented by construction rather than review.

Keep the matrix as the single authority but move its file into the skill reference set, and have the website also serve Markdown alternates of every page plus llms.txt and llms-full.txt (accepted)

Section titled “Keep the matrix as the single authority but move its file into the skill reference set, and have the website also serve Markdown alternates of every page plus llms.txt and llms-full.txt (accepted)”
  • Pros: Installed agents read the matrix offline, as plain text, at the version of the plugin they installed, One editable file; the website and README reference it instead of a second copy, Website readers and online agents also get plain-text pages without HTML
  • Cons: Every reference to the old path, the packaging checks, the public-register guard, and the website projection move together
Section titled “Link the public website page from the skill (rejected)”
  • Pros: No file move
  • Cons: Rendered HTML, network required, and only the current main snapshot
Section titled “Link the raw Markdown on GitHub, either main or the release tag derived from inferlab --version (rejected)”
  • Pros: Plain Markdown with no infrastructure change; a tag link follows the binary version
  • Cons: Needs network, and a development build has no tag to resolve

Add a CLI command that prints the matrix embedded in the binary (rejected)

Section titled “Add a CLI command that prints the matrix embedded in the binary (rejected)”
  • Pros: Offline, plain text, and exactly the running binary’s version
  • Cons: Adds a product command for what a bundled file already provides

Copy the matrix into the skill directory at packaging time (rejected)

Section titled “Copy the matrix into the skill directory at packaging time (rejected)”
  • Pros: Matches the installed plugin version
  • Cons: The repository either links a file that exists only in the package or keeps a committed copy that needs its own drift check