[tigernaut]

Adds src/lib/AGENTS.md, which svelte-package copies to dist/AGENTS.md in every release package. It is written for teams using io and Holocene: which layer to pick, import paths, real props, semantic color classes and common mistakes. The contributor guidance and behavior are unchanged.

Description & motivation 💭

• It improves the UI that agents build. Fewer invented props, fewer colors that break in dark mode, and fewer Holocene components used where io already has one.
• It moves the io migration forward. It tells every consuming agent to prefer io.
• Adds a point on the agent-readiness score. Consumer guidance shipped in the package moves that check from 1/2 to 2/2, taking the total from 5 to 6.

Screenshots (if applicable) 📸

n/a

Design Considerations 🎨

Drift and discoverability: there’s no one-line fix for this. Two options are to generate the io table when packaging, and to add the Cloud UI pointer we discussed. Neither blocks the PR.

Testing 🧪

How was this tested 👻

• Manual testing
• E2E tests added
• Unit tests added

Steps for others to test: 🚶🏽‍♂️🚶🏽‍♀️

Checklists

Draft Checklist

Merge Checklist

Issue(s) closed

Docs

Any docs updates needed?

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
holocene	Ready	Preview	Oct 23, 2026 8:51pm UTC

[Copilot]

🟢 Approval recommended

The documentation-only change has two minor accuracy corrections with concrete fixes, neither of which blocks approval.

2 open issues

• Document io Button before using a Holocene-only fallback · New
• Acknowledge ChipStatus text overrides for localized labels · New

What changed in this PR

Adds package-consumer guidance for agents using io and Holocene, intended to ship with @temporalio/ui releases without changing runtime behavior.

Changes:

• Documents io-first component selection and package import paths.
• Provides prop examples, semantic color guidance, and common mistakes.
• Points consumers to component contracts for detailed usage rules.

File	Description
src/​lib/​AGENTS.md	Adds consumer guidance for selecting and using io and Holocene components.

_{Review effort: Balanced}

[rossnelson]

Approving. This is the right thing to ship for consumers, and the io-first guidance matches what we tell contributors in the root CLAUDE.md.

One non-blocking note on location rather than content. Tools that walk AGENTS.md files up the tree (Codex, Cursor, and others) will now load src/lib/AGENTS.md for anyone editing under src/lib/, including io/. So contributors' agents will see consumer guidance (@temporalio/ui/io/... imports, dist/**/index.d.ts) alongside the repo rules. The pointer sentence to io/AGENTS.md helps, but it's a workaround for the file living in a path that's magic for those tools.

I've opened a ticket to consolidate them. Part of that work will likely move this file to a non-magic source path and copy it to dist/AGENTS.md at build time, so the contract for consumers stays the dist path and nothing here needs to change now.