chore(mosaic): point agents at the layer guides before they edit

.changeset/mosaic-path-scoped-guides.md

@@ -0,0 +1,2 @@
+---
+---

AGENTS.md

@@ -11,6 +11,7 @@ Clerk's JavaScript SDK and library monorepo.
 - Every PR needs a changeset. Agents write `.changeset/<name>.md` directly, because `pnpm changeset` prompts interactively. Empty changesets, for tooling/repo-only changes, are two `---` delimiters with no body. A changeset is a changelog entry for users upgrading the package, not a summary of the work done in the PR. Describe the user-facing change (what changed for someone consuming the library and how it affects them) rather than the implementation details of the diff. If a change has no user-facing impact, use an empty changeset.
 - Reuse existing patterns before writing new ones. Before adding a helper, hook, or a local way of handling errors, pending state, focus or similar cross-cutting concerns, search the package for one that already solves it. If none fits, stop and ask the user before introducing a new pattern: say what the problem is, what you checked, and what you propose.
 - PR descriptions follow `.github/PULL_REQUEST_TEMPLATE.md` and add no sections of their own. Never add a "Testing" (or "Test plan" / "How to test") section summarizing the tests written or the checks run; the Checklist covers that and reviewers read the diff. Describe the change, not the work done on it.
+- Before editing any file under `packages/mosaic`, read `packages/mosaic/AGENTS.md`. It names the guide to read for each kind of file.
 
 ## Verifying changes
 

packages/mosaic/.claude/rules/controllers.md

@@ -0,0 +1,7 @@
+---
+paths:
+  - 'src/**/*.controller.ts'
+  - 'src/**/*.controller.tsx'
+---
+
+Read `packages/mosaic/docs/controllers.md` before changing this file.

packages/mosaic/.claude/rules/models.md

@@ -0,0 +1,7 @@
+---
+paths:
+  - 'src/**/*.model.ts'
+  - 'src/**/*.model.tsx'
+---
+
+Read `packages/mosaic/docs/models.md` before changing this file.

packages/mosaic/.claude/rules/stylex.md

@@ -0,0 +1,7 @@
+---
+paths:
+  - 'src/**/*.styles.ts'
+  - 'src/**/*.stylex.ts'
+---
+
+Read `packages/mosaic/docs/stylex.md` before changing this file.

packages/mosaic/.claude/rules/testing.md

@@ -0,0 +1,9 @@
+---
+paths:
+  - 'src/**/__tests__/**'
+  - 'src/**/*.test.ts'
+  - 'src/**/*.test.tsx'
+  - 'src/**/*.test-d.ts'
+---
+
+Read `packages/mosaic/docs/testing.md` before changing this file.

packages/mosaic/.claude/rules/views.md

@@ -0,0 +1,6 @@
+---
+paths:
+  - 'src/**/*.view.tsx'
+---
+
+Read `packages/mosaic/docs/views.md` before changing this file.

packages/mosaic/AGENTS.md

@@ -25,6 +25,18 @@ Read the guide for the task you are doing. Paths below are relative to this pack
 | Add a public prop that shows or hides UI  | [Public visibility props](docs/public-props.md)                                   |
 | Prove a change in a browser               | [verify-mosaic](.claude/skills/verify-mosaic/SKILL.md)                            |
 
+## Before editing a file
+
+Before you change a file that matches a pattern below, read its guide, even for a one-line change.
+
+| File                                                               | Read                               |
+| ------------------------------------------------------------------ | ---------------------------------- |
+| `src/**/*.styles.ts`, `src/**/*.stylex.ts`                         | [StyleX](docs/stylex.md)           |
+| `src/**/*.model.ts(x)`                                             | [Models](docs/models.md)           |
+| `src/**/*.controller.ts(x)`                                        | [Controllers](docs/controllers.md) |
+| `src/**/*.view.tsx`                                                | [Views](docs/views.md)             |
+| `src/**/__tests__/**`, `src/**/*.test.ts(x)`, `src/**/*.test-d.ts` | [Testing](docs/testing.md)         |
+
 ## Layers in one paragraph
 
 A flow lives in `src/features/<feature>/`. The **model** (`*.model.ts(x)`) is the only file that reads Clerk hooks or calls Clerk resources, and answers with plain data, plain callbacks and a `status`. The **controller** (`*.controller.ts(x)`) holds local state and wraps the model's callbacks for pending, errors and closing. The **view** (`*.view.tsx`) renders plain props. No Clerk resource reaches the controller and no machine snapshot reaches the view.