docs(agents): make agent-doc links absolute and publish llms.txt - #686
Conversation
- rewrite all relative cross-doc links under .agents/ to absolute https://design.cypress.io/agents/ URLs so an agent fetching one doc over HTTP can follow links to the rest - generate llms.txt at the domain root from copy-agents.mjs, listing every served doc so the whole tree is discoverable without a human pasting URLs - link the agent index and llms.txt from the docs homepage; document the absolute-link convention in AGENTS.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
cypress-design
 |
||||||||||||||||||||||||||||
| Project |
cypress-design
|
| Branch Review |
ryanjwilke/great-kirch-c1d5d3
|
| Run status |
|
| Run duration | 02m 20s |
| Commit |
|
| Committer | Ryan Wilke |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
 |
0
|
 |
0
|
 |
0
|
 |
0
|
 |
2
|
| View all changes introduced in this branch ↗︎ | |
Warning
No Report: Something went wrong and we could not generate a report for the Application Quality products.
There was a problem hiding this comment.
Pull request overview
This PR improves discoverability and navigability of the design-system agent docs when consumed over HTTP by agents that can only follow absolute URLs. It updates the hosted .agents/ markdown corpus to use absolute cross-doc links, and adds a generated llms.txt at the site root so the full served doc tree can be discovered starting from the homepage.
Changes:
- Generate
docs/public/llms.txtduringbuild:docs, listing every served agent doc as an absolute URL. - Add a homepage “For AI agents” section linking to
/agents/index.mdand/llms.txt. - Document the “absolute link” convention in
AGENTS.mdand update.agents/*.mdcross-doc links accordingly.
Reviewed changes
Copilot reviewed 21 out of 22 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/copy-agents.mjs | Generates docs/public/llms.txt from the copied/served docs/public/agents tree. |
| docs/src/pages/index.mdx | Adds homepage entry points to the agent index and llms.txt. |
| AGENTS.md | Documents the absolute cross-doc link convention and llms.txt generation. |
| .gitignore | Ignores generated docs/public/llms.txt. |
| .agents/voice.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/typography.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/spacing.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/review-checklist.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/product-review-checklist.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/visual-hierarchy.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/ux.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/releases.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/product.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/learning-from-feedback.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/feedback.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/principles/ai.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/index.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/illustrations.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/iconography.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/errors.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/colors.md | Converts cross-doc links to absolute hosted URLs. |
| .agents/accessibility.md | Converts cross-doc links to absolute hosted URLs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
cypress-design
|
||||||||||||||||||||||||||||
| Project |
cypress-design
|
| Branch Review |
main
|
| Run status |
|
| Run duration | 02m 29s |
| Commit |
|
| Committer | Ryan Wilke |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
|
|
0
|
|
|
0
|
|
|
0
|
|
|
0
|
|
|
2
|
| View all changes introduced in this branch ↗︎ | |
Warning
No Report: Something went wrong and we could not generate a report for the Application Quality products.
Problem
Agents consuming the design system docs over HTTP (e.g. Claude Design) use fetch tools with a safety guardrail: they can only fetch absolute URLs that already appear in the conversation or in previously fetched pages. Our agent docs defeated that in two ways:
.agents/was relative (./colors.md), so fetchingagents/index.mdunlocked nothing — an agent couldn't follow the router to any pillar or component doc.Goal
An agent that can reach
design.cypress.ioby web search should be able to walk the whole guidance tree with no human in the loop: search → homepage → index → everything.Changes
.agents/rewritten tohttps://design.cypress.io/agents/.... Link text keeps the short path; only hrefs changed. Local repo agents are unaffected (they read viaAGENTS.mdpaths).llms.txtat the domain root — generated byscripts/copy-agents.mjsduringbuild:docsfrom the actual served tree (93 docs incl. component instructions/ReadMes), so it can't drift. Gitignored likedocs/public/agents/.llms.txtso the chain starts from a searchable page (same pattern docs.cypress.io uses).AGENTS.md— documents the absolute-link convention so new links stay absolute.Verification
Ran the dev server and confirmed:
/agents/index.mdserves with absolute links and zero remaining relative links,/llms.txtlists every served doc, and the homepage renders the new section with both links.🤖 Generated with Claude Code
Note
Low Risk
Documentation and static-site build output only; no runtime product, auth, or data paths change.
Overview
Agents that fetch design-system guidance over HTTP often can only follow absolute URLs, so relative cross-links in
.agents/blocked navigation from the router to pillar and component docs. This PR rewrites those cross-doc links tohttps://design.cypress.io/agents/...across the agent markdown corpus and documents the convention inAGENTS.mdso new links stay absolute.scripts/copy-agents.mjsnow emitsdocs/public/llms.txt(gitignored, built withbuild:docs) listing every served.mdwith absolute URLs so the full tree is discoverable from the domain root. The docs homepage gains a For AI agents section pointing at the index andllms.txt, matching the intended path: searchable site → index → rest of the guidance.Reviewed by Cursor Bugbot for commit a1e02a9. Bugbot is set up for automated code reviews on this repo. Configure here.