[JReinhold]

Closes #

What I did

Agents that debug a sandbox's Chromatic build must first find the sandbox's Chromatic project. The repository holds only the internal UI's project ID (code/chromatic.config.json). Each sandbox finds its project through a secret CircleCI token, and a token is not a project ID. So agents list all 88 projects in the storybookjs account each time. Most of these projects are no longer used, and two project names do not match their template keys.

This PR adds .agents/guidelines/chromatic-projects.md. It lists the project ID for the internal UI and for each sandbox template that runs the chromatic task on next. AGENTS.md points to it.

I took the IDs from the Chromatic API. Each project in the list had a build on next within the last day.

Does it work?

I gave 10 Haiku subagents (low effort) a question about one sandbox's Chromatic project each. The prompts did not mention the list. Some prompts named the template key. Others were vague, such as "the svelte-kit sandbox" or "the react-native-web expo sandbox". Two asked about templates whose project name differs from the template key (nextjs/prerelease, internal/react18-webpack-babel).

• All 10 used the correct project ID, and all 10 took it from the list.
• None searched the Chromatic account for projects.
• Eight followed the AGENTS.md pointer directly. Two first found the file through git show of the newest commit, because the doc was the latest change in their checkout.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

• stories
• unit tests
• integration tests
• end-to-end tests

Manual testing

Caution

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

This PR changes only agent documentation. To check it:

1. Open .agents/guidelines/chromatic-projects.md.
2. Pick a template, for example nextjs/prerelease, and open https://www.chromatic.com/builds?appId=<id> with the ID from the table, without the Project: prefix.
3. Make sure the project has recent builds on next.

Documentation

• Add or update documentation reflecting your changes
• If you are deprecating/removing a feature, make sure to update
  MIGRATION.MD

Checklist for Maintainers

• When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts

• Declare whether manual QA will be needed for this PR during the next release, through qa:needed or qa:skip

• Make sure this PR contains one of the labels below:

  Available labels

  • bug: Internal changes that fixes incorrect behavior.
  • maintenance: User-facing maintenance tasks.
  • dependencies: Upgrading (sometimes downgrading) dependencies.
  • build: Internal-facing build tooling & test updates. Will not show up in release changelog.
  • cleanup: Minor cleanup style change. Will not show up in release changelog.
  • documentation: Documentation only changes. Will not show up in release changelog.
  • feature request: Introducing a new feature.
  • BREAKING CHANGE: Changes that break compatibility in some way with current major version.
  • other: Changes that don't fit in the above categories.

🦋 Canary Release - 🚫 Not run

This PR does not have a canary release associated.

In-repo PRs: add the ci:canary label. Later pushes republish while the label remains.

Fork PRs: the label does nothing (a later push must not auto-publish). A maintainer publishes from this repository with Run workflow and the pr input. branch and sha are optional; if more than one is set, they must be the same commit. The fork author does not need to do anything.

🤖 Generated with Claude Code

[greptile-apps]

Confidence Score: 4/5

[Low impact] The change reaches coding agents working with Chromatic.

The PR appears safe to merge, with a non-blocking correction to the CI job lookup directions.

Findings

1.  CI names do not match ▶

Fix with agent prompt

### Issue 1
.agents/guidelines/chromatic-projects.md:3
The template key is not the name shown in the CI job. `scripts/ci/sandboxes.ts` uses each template’s `name`, so `nextjs/default-ts` appears as `Next.js Latest (Webpack | TypeScript) (chromatic)`. An agent starting from a failed job cannot directly match that name to this table as promised. Point readers to `code/lib/cli-storybook/src/sandbox-templates.ts` to map job names to template keys.

```suggestion
Pass the project ID as `projectId` to the Chromatic tools. Sandbox projects are listed by template key. CI jobs use the template's display name followed by ` (chromatic)`; use `code/lib/cli-storybook/src/sandbox-templates.ts` to map that name to a template key.
```

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds a Chromatic project lookup guide for agents.

• Agents can look up Chromatic project IDs by sandbox template.

_{Reviews (1) · Last reviewed commit: "docs(agents): list Chromatic project IDs..." · Reviewed by Greptile}