feat(docs): [experimental] LLM documentation surface — API + stories feeds shipped with the Storybook

[F2X]

Warning

Experimental — under test. The feeds and their format may change or be withdrawn without a deprecation cycle.

Description

Ships an LLM-consumable documentation surface with every Storybook deploy.

Coding agents (Copilot, Claude, CI bots) can read the whole public API of @lucca-front/ng and @lucca/prisme, plus every documented story, from https://lucca-front.lucca.io/<ref>/storybook/llms.txt — unauthenticated, versioned per ref, zero new infrastructure.

• Storybook channel: llms.txt index, llms-full.txt (API + stories), deprecations.json, plus 136 windowed per-entry-point and per-category feeds
• npm channel: llms.txt proxies llms-api.txt beside it, plus llms-stories.txt on ng — read from node_modules at the installed version
• ts-morph extraction: 1083 declarations from 1066 exports, 0 unresolved; 637 story files in 16 categories (28 component-rendered)
• CI gates: coverage ratchet, smoke (API probes, 18 named anchors, feed counts, no internal host), pack verification both ways, story floor + 4 story anchors

Impact

• No runtime or user-visible change — gitignored artifacts via the existing Storybook staticDirs; tarballs grow +161 KB gz (ng), +7 KB (prisme)
• The Storybook at lucca-front.lucca.io is already internet-public (PR previews included): these files add no new exposure class
• Closes docs: ship the llms*.txt surface with the public Storybook R2 deploy #5225 (sub-issue of the doc-for-LLM epic LuccaSA/Guildes#75); supersedes the closed feat(docs): ts-morph LLM API-surface generator for @lucca-front/ng #5175

Evidence — gates output and shipped files

$ npm run docs:api-smoke
[llms-smoke] ok: header
[llms-smoke] ok: component selector
[llms-smoke] ok: component inputs (generated)
[llms-smoke] ok: component outputs (generated)
[llms-smoke] ok: deprecation callout
[llms-smoke] ok: stories section
[llms-smoke] ok: 1083 public API entries (floor 500)
[llms-smoke] ok: 18/18 named feed anchors present
[llms-smoke] ok: 120 entry-point feeds (floor 80)
[llms-smoke] ok: 16 story-category feeds (floor 10)
[llms-smoke] ok: llms.txt links every generated feed
[llms-smoke] ok: no internal host in any of 139 generated files
[llms-smoke] OK: llms-full.txt is 1226 KB, 136 windowed feeds all indexed.

$ npm run docs:api-coverage
[PASS] @lucca-front/ng + @lucca/prisme: 105/1083 public exports documented = 10% (baseline 105 documented)

$ npm run build   # → dist/, publish.yml ships the whole folder
[llms-pack] @lucca-front/ng: 1070 API entries (492 KB) + 147 documented components from 637 story files (745 KB) → dist/ng/{llms.txt,llms-api.txt,llms-stories.txt} (in tarball, 477 files)
[llms-pack] @lucca/prisme: 57 API entries (28 KB) + no stories corpus (opted out) → dist/prisme/{llms.txt,llms-api.txt} (in tarball, 28 files)

$ npm run build-storybook   # → storybook-static/
llms.txt  llms-full.txt (1226 KB)  deprecations.json (36 KB)  llms/ (136 files)

$ npx vitest run --project api-docs
Test Files  3 passed (3)   Tests  142 passed (142)

Evidence — every gate verified by breaking it

# a single lost feed family, with every numeric floor still green
$ rm .storybook/public/llms/ng-icon.md && npm run docs:api-smoke
[llms-smoke] ok: 1083 public API entries (floor 500)
[llms-smoke] MISSING: 17/18 named feed anchors present
[llms-smoke] ok: 119 entry-point feeds (floor 80)
[llms-smoke] FAIL: named feed anchor(s) gone: ng-icon.md.

# a lost story family, same shape one channel down
$ mv stories/documentation/actions/button /tmp && npm run docs:llms-pack
[llms-pack] FAIL: @lucca-front/ng: story anchor(s) gone from the packaged corpus: ## Actions / Button.

# an .npmignore line added upstream: corpus written, not published (28 files -> 27)
$ echo llms-api.txt >> dist/prisme/.npmignore && npm run docs:llms-pack
[llms-pack] FAIL: @lucca/prisme: llms-api.txt written to dist/prisme but ABSENT from
the published tarball (27 files) — check `files`/.npmignore in the dist manifest.

# and the other way: a stale corpus reaching a tarball that opted out
$ cp dist/ng/llms-stories.txt dist/prisme/ && npm run docs:llms-pack   # cleanup neutralised
[llms-pack] FAIL: @lucca/prisme: opted out of the stories corpus, yet llms-stories.txt
reaches the tarball — a stale dist file is being published.

Post-deploy proof: curl -I https://lucca-front.lucca.io/master/storybook/llms-full.txt returns 200 once the next master deploy runs (it 404s today).

---

Technical notes for reviewers

• ts-morph, not Compodoc: the pinned Compodoc 1.1.16 under-resolves signal input()/output() (feat(docs): single LLM documentation surface via Compodoc #5167 was closed for that); ts-morph reads them straight from source. Output is deterministic — identical source yields byte-identical files.
• @lucca/prisme shares the ng topology in-repo (secondary entry points with public-api.ts barrels); documenting it also resolves the @lucca-front/ng button/icon re-exports cleanly.
• Stories extraction is purely syntactic (no Storybook runtime, no browser): Meta title, template: literals (following one level of in-file indirection — the Template/getTemplate and cleanupTemplate(...) idioms), story export names, argTypes.*.description; createTestStory wrappers skipped. 28/636 files carry no static template (component-rendered) — they still contribute titles and prop descriptions.
• deprecations.json resolves by declaration, not by name. 3 of its 126 entries reach several entry points (both tooltip barrels, both button barrels); where two classes share a name, only the barrel declaring the deprecated one is listed, so a lint rule keyed on the import path flags the right barrel.
• The feed anchors are named, never derived. The index and the llms/ folder are produced by the same extraction, so a lost entry point vanishes from both and a count floor of 80 against ~120 feeds lets it through. The 18 anchors cover one feed per package, per nesting depth and per story-category arm. The packaged stories corpus carries the same discipline: 4 named component anchors, because a floor of 400 against 636 story files also lets a whole family through. Add an anchor when a family becomes load-bearing; never trim the list to make the gate pass.
• The npm channel packs rather than trusting the write, and asserts file by file. A files allowlist or .npmignore introduced upstream drops a feed at publish time with the build still green — only npm pack sees the published file list (~0.9 s per package). An allowlist naming llms-api.txt alone would drop the proxy and the stories, so all three names are checked.
• llms.txt proxies, it never copies. In the tarball it lists the entry points and relatively links ./llms-api.txt and ./llms-stories.txt; the 136 split feeds stay on the deploy, since shipping them would duplicate ~300 KB of the same bytes. The split is what makes the corpora usable: an agent after a signature reads 288 KB (23 KB on prisme), never the 722 KB of templates. And the link must stay relative — an absolute docs URL answers for master while the package is pinned, the version leak this channel exists to close.
• @lucca-front/ng carries the stories; @lucca/prisme opts out. 388 of the 636 story files import neither package (they document the CSS design system), so splitting the corpus per package by import would drop 61% of the examples from both, so ng carries it whole (+134 KB gz, +11%). That corpus meant +94% on a 90 KB package, so prisme ships its API alone (+7 KB gz) and its proxy links the stories on the deploy — which tracks master while the package is pinned, so the version guarantee holds for prisme's API, not its examples. Flip stories in PACK_TARGETS to undo.
• No dependency on @lucca/docs-kit. The kit's bundler covers the tag-sourced Starlight pipeline (Pagga.Front, lu-swag): its files-allowlist guard is a no-op here and its archived-snapshot guard has no subject (the Storybook is versioned per deployment, not by tag). lucca-front carries no external @lucca/* dependency — both of its own are in-repo.
• lucca docs is a parallel channel, not a substitute. It serves authenticated devs fleet-wide from an Astro site published by a build.cake PublishAstroDocs task; lucca-front has none, is absent from its registry, and per LuccaSA/Guildes#75 the DD arm is 401-gated.
• The deployed index links relatively, not to master, and lists the zeroheight Prisme reference as prose documentation; machine extraction of zeroheight is a separate decision (feat(docs): aggregate Prisme (zeroheight) guidance into the llms*.txt feeds #5222).
• Drive-by, separate commit: removed the orphan build-compodoc npm script and its tsconfig.compodoc-html.json (referenced by no workflow or script; the Storybook builder's own compodoc integration in angular.json is untouched).

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01TN1HaKioHi3vwVHDyeUafV

[github-actions]

🚀 Storybook preview deployed: https://pub-dc6d99acd6874e2aaff6219dd8a13ae2.r2.dev/PR-5224/index.html

[Copilot]

Pull request overview

Adds a generated, Storybook-hosted LLM documentation surface for public APIs and stories.

Changes:

• Extracts API and Storybook metadata with ts-morph.
• Generates full, indexed, windowed, and deprecation feeds.
• Adds Vitest coverage and CI validation gates.

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
.github/workflows/build.yml	Runs documentation validation in CI.
.gitignore	Ignores generated feeds.
package.json	Adds scripts and ts-morph.
package-lock.json	Locks the new dependency.
vitest.config.ts	Adds the API-docs test project.
tsconfig.compodoc-html.json	Removes obsolete Compodoc configuration.
scripts/api-docs/extract-api.mjs	Extracts public TypeScript APIs.
scripts/api-docs/extract-api.spec.mjs	Tests API extraction.
scripts/api-docs/extract-stories.mjs	Extracts documented stories.
scripts/api-docs/extract-stories.spec.mjs	Tests story extraction.
scripts/api-docs/generate-llms.mjs	Generates documentation feeds.
scripts/api-docs/generate-llms.spec.mjs	Tests feed rendering.
scripts/api-docs/check-llms-surface.mjs	Smoke-tests generated artifacts.
scripts/api-docs/check-api-coverage.mjs	Enforces JSDoc coverage.

Suppressed comments (3)

scripts/api-docs/extract-api.mjs:179

• The generated input name must use Angular's public alias, not the backing property name. The current output documents luTooltipInput although consumers bind [luTooltip] (packages/ng/tooltip/trigger/tooltip-trigger.directive.ts:68), and the repository contains several other aliased signal inputs. Read the alias option for input, input.required, and model.

				name: prop.getName(),

scripts/api-docs/extract-api.mjs:175

• Angular model() declares both an input and an implicit <name>Change output, but this branch records only the input. Consequently APIs such as IndexTableRowComponent.selectedChange (packages/ng/index-table/index-table-row/index-table-row.component.ts:52) disappear from the promised output surface. Add the corresponding output, including alias handling, whenever the callee is model or model.required.

		if (INPUT_CALLEES.has(callee)) {

scripts/api-docs/extract-api.mjs:169

• getProperties() only yields declarations on this class, so inherited Angular inputs/outputs are omitted. For example, DurationPickerComponent extends BasePickerComponent, whose public step, size, and disabled model (packages/ng/time/core/base-picker.component.ts:15-19) are part of the derived component API but will not be rendered. Traverse base classes and merge inherited members while allowing derived overrides.

	for (const prop of classNode.getProperties()) {

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 15 changed files in this pull request and generated no new comments.

Suppressed comments (7)

scripts/api-docs/extract-api.mjs:241

• Signal input aliases are not applied here, so the generated binding names are wrong. For example, LinkComponent.luHref = input('', { alias: 'href' }) is emitted as luHref, and the same happens for luLink, luTooltip, and other aliased signals. Parse the signal options for input, input.required, and model and emit the configured alias as the public name.

				name: prop.getName(),

scripts/api-docs/extract-stories.mjs:237

• The renderer never emits story.name, and stories without described arg types are skipped entirely by this loop. Files such as simple-select.stories.ts contain many distinct variants (Basic, Minimal, WithDisplayer, etc.); their templates are currently dumped together under one file heading with no indication of which story they belong to. Preserve template/description data per story and render a heading for every extracted story so the promised story corpus remains identifiable.

			for (const story of file.stories) {

scripts/api-docs/extract-api.mjs:237

• model() and model.required() enter this input-only branch, but an Angular model also exposes an output named <modelName>Change. Consequently components such as Calendar2Component lose dateChange, modeChange, and the other model outputs from the advertised full API. Add the corresponding output entry (using the model alias when present).

This issue also appears on line 241 of the same file.

		if (INPUT_CALLEES.has(callee)) {

scripts/api-docs/extract-api.mjs:373

• The entity is built only from members declared directly on the concrete class. Angular components inherit inputs and outputs: for example, LuSimpleSelectInputComponent extends ALuSelectInputComponent, whose placeholder, clearable, panelClosed, and many other bindings are part of the usable component API, but this feed emits only the subclass's three own inputs. Traverse base classes and merge inherited Angular members and public methods, with derived declarations taking precedence.

			return { ...base, selector: selectorOf(node), ...membersOf(node), methodsClass: methodsOf(node) };

scripts/api-docs/generate-llms.mjs:329

• The method signature is placed in a Markdown table without escaping pipes in argument types. Public methods such as callCanDeactivateFn(canDeactivateFn: CanDeactivateFn<C> | DeprecatedGuard) therefore add an unintended table column and corrupt the generated feed. Escape | in the complete signature before writing the cell.

			const args = (m.args || []).map((a) => `${a.name}: ${a.type || 'unknown'}`).join(', ');
			lines.push(`| \`${m.name}(${args})\` | ${typeCell(m.returnType)} | ${cleanCell(m.rawdescription || m.description)} |`);

scripts/api-docs/extract-stories.mjs:183

• For helper-built stories, storyObject is the generateStory({...}) configuration, while the actual Storybook argTypes are under storyPartial.argTypes. Calling argTypesOf only at the top level drops those descriptions; for example, simple-select.stories.ts documents AddOption's addOptionLabel and addOptionStrategy there, but neither reaches the feed. Resolve the helper's storyPartial object and merge its arg types with the Meta defaults.

This issue also appears on line 237 of the same file.

		const own = argTypesOf(storyObject);
		stories.push({ name: varDecl.getName(), argTypes: own.length ? own : metaArgTypes });

scripts/api-docs/generate-llms.mjs:52

• Hard-coding master means every versioned deployment's index crosses versions: following a link from v21.3/storybook/llms.txt loads the master API/story feed rather than v21.3. This contradicts the PR's per-ref documentation contract and can give agents APIs unavailable in the selected release. Use URLs relative to the current Storybook directory, or inject the deployed ref when generating the index.

export const CANONICAL_BASE_URL = 'https://lucca-front.lucca.io/master/storybook';