[DISCUSS] What should the repository tell coding agents, and where?

[Astro-Han]

Why now

Three threads each answer part of this and none can move without the others:

• docs: add AGENTS.md #3576 adds a root AGENTS.md (with CLAUDE.md as a symlink). It is accurate, and it is parked because a root instruction file is not documentation people choose to read: buildWorkspaceInstructionsPromptFragment injects it into the system prompt of every agent session whose cwd is this repository, which makes it a change to every contributor's agent, not a docs change.
• Adopt Storybook's official MCP addon to give agents a queryable component interface #3527 proposes @storybook/addon-mcp so an agent can list components and read props before writing UI.
• The design system we build on ships its own agent workflow (Astryx "working with AI"): npx @astryxdesign/cli init --features agents generates agent rules, and https://astryx.atmeta.com/mcp serves its docs. The CLI is already pinned in package.json; none of the workflow is wired.

The cost of leaving this open is visible: three CSS dialects across 67 stylesheets, 13 of 14 settings pages on the stacked-card structure Astryx documents as an anti-pattern, product CSS re-authoring chrome Astryx owns. Each agent reinvents the dialect because the repo never states it in a form agents read.

Proposal

1. Root AGENTS.md (from docs: add AGENTS.md #3576) carries only what every session needs: layout, commands, test and lint gates, PR conventions. Nothing surface-specific. CLAUDE.md stays a symlink so there is one copy.
2. Nested apps/desktop/AGENTS.md and packages/ui/AGENTS.md carry the frontend rules, generated by npx @astryxdesign/cli init --features agents --agent-docs-path <path> and edited to defer to DESIGN.md and docs/frontend-css-governance.md for every Maka-specific rule. Nested files load only when an agent works in that tree, so runtime and CLI sessions never see them.
3. One tracked .mcp.json with two entries: the Storybook addon from Adopt Storybook's official MCP addon to give agents a queryable component interface #3527 and Astryx's xds. Agents that support MCP pick them up; others lose nothing.
4. DESIGN.md remains the single Maka design authority. The generated files may restate Astryx's own rules; they do not restate Maka's.

What changes for contributors

Every agent session in this repo loads the root file; frontend sessions load one nested file and, where the tool supports MCP, gain two docs servers. Lint, CI and review requirements do not change. Contributors who do not use agents are unaffected.

Open questions

• Is a tracked .mcp.json acceptable given it names external and local servers, or should it be documented in CONTRIBUTING.md and left opt-in?
• Should the root file be reviewed like code (any change needs a PR with a stated reason), since it changes agent behaviour repo-wide?
• Size: docs: add AGENTS.md #3576 is 13 KB. Is that the ceiling for the root, with everything else pushed to nested files and links?

If this converges, #3576 proceeds as the root file, #3527 and the Astryx items land as one follow-up PR, and the Desktop tracker #4679 picks up the frontend rules item.

Related: #4156 (local validation hooks by default), #4369 (npm → pnpm).