Machine discovery
Designing AI-readable component docs
How catalogue JSON, llms.txt, registry payloads, canonical pages, and explicit status language help agents discover Gummy UI without exposing private source.
By Gummy UI · Published
Offer stable public contracts
An agent needs more than a marketing homepage to use a component system responsibly. Gummy UI exposes a catalogue API with groups, descriptions, source identities, semantics, keyboard notes, dependencies, and registry URLs. Individual registry payloads contain the editable public files, while canonical component pages provide human-readable context.
These surfaces derive from the same catalogue so names and URLs can be compared. A health endpoint reports only public service identity and catalogue size. It intentionally avoids private diagnostics, credentials, customer records, or claims about systems that are not active.
Use llms.txt as a map
The llms.txt route lists canonical documentation, catalogue, registry, MCP guidance, licence, and component links in plain text. It is a discovery aid, not a new source of product truth. Descriptions and registry URLs still point back to the public manifest and payloads.
This blog is included in the same map so design and implementation reasoning can be found without scraping navigation. RSS provides another standards-based list of article updates. Neither route includes paid source paths, release locations, entitlement details, or invented support channels.
State unavailable capabilities clearly
The public HTTP catalogue and registry contracts are implemented locally. A hosted MCP transport is not advertised as active because authentication, rate limits, monitoring, and deployment remain release decisions. The Pro catalogue now describes implemented blocks, templates, and design-kit definitions without misrepresenting local implementation evidence as verified, protected, downloadable product.
Explicit status language helps both people and agents avoid unsafe inference. “Specified,” “implemented,” “tested,” “deployed,” and “production-verified” are different states. Machine-readable metadata should preserve those distinctions instead of flattening every listed item into availability.
Protect the repository boundary
Public discovery may include safe names, descriptions, counts, and preview references. It must not include editable paid blocks, templates, design source, protected release URLs, or entitlement logic. The public registry is generated only from the MIT component source intended for distribution.
Discovery tests should therefore check presence and absence together: every canonical public article or component should be listed, while account internals, checkout routes, private previews, and paid source remain excluded from indexes. Useful machine access depends on a narrow, reviewable boundary.