Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Move agent instructions to AGENTS.md (#85499)

Chris Truter0ba3bea41a81
diff --git a/.claude/agents/modules-backend-expert.md b/.claude/agents/modules-backend-expert.md
index c2126a01c10..bb2cb9c2ac4 100644
--- a/.claude/agents/modules-backend-expert.md
+++ b/.claude/agents/modules-backend-expert.md
@@ -9,7 +9,7 @@ skills:
You decide how Metabase backend code is organized into modules: names, nesting, public surface, dependency edges, and where a namespace or query lives. You handle one self-contained question or change. Return a summary the caller can act on; don't drive multi-step plans. Module changes cascade (config, init chain, model resolution, routes, requires), so name the cascade instead of silently doing all of it.
-The preloaded `backend-module-conventions` skill covers the standard namespaces, the `<module>.db` rule, and the default checks. Project `CLAUDE.md` covers `fix-modules-config`, nested-module basics, `project-tests`, and ratchet workflow.
+The preloaded `backend-module-conventions` skill covers the standard namespaces, the `<module>.db` rule, and the default checks. Project `AGENTS.md` covers `fix-modules-config`, nested-module basics, `project-tests`, and ratchet workflow.
## Map
diff --git a/.claude/skills/_shared/clojure-commands.md b/.claude/skills/_shared/clojure-commands.md
index 9d9fc0754ea..255767e8ad2 100644
--- a/.claude/skills/_shared/clojure-commands.md
+++ b/.claude/skills/_shared/clojure-commands.md
@@ -12,7 +12,7 @@
## Testing
-Use `./bin/test-agent` to run backend tests. See the top-level CLAUDE.md for usage.
+Use `./bin/test-agent` to run backend tests. See the top-level AGENTS.md for usage.
## Code Readability
diff --git a/.claude/skills/_shared/cypress-conventions.md b/.claude/skills/_shared/cypress-conventions.md
index 4459c08d16d..7ca67539842 100644
--- a/.claude/skills/_shared/cypress-conventions.md
+++ b/.claude/skills/_shared/cypress-conventions.md
@@ -319,7 +319,7 @@ A flow split into 8 tiny `it()` blocks pays that combined overhead 8 times. See
#### Before merging tiny tests, ask whether they belong in E2E at all
-A test whose **only** job is to assert that some elements exist or are visible — no backend interaction worth testing through the wire, no flow that traverses multiple screens, no real-data dependency — is almost always a unit test misfiled into the e2e suite. `frontend/CLAUDE.md` already says "prefer unit tests over E2E tests"; this is the most common failure mode.
+A test whose **only** job is to assert that some elements exist or are visible — no backend interaction worth testing through the wire, no flow that traverses multiple screens, no real-data dependency — is almost always a unit test misfiled into the e2e suite. `frontend/AGENTS.md` already says "prefer unit tests over E2E tests"; this is the most common failure mode.
Strong signals the test should be a Jest + React Testing Library unit test instead:
diff --git a/.claude/skills/backend-module-conventions/SKILL.md b/.claude/skills/backend-module-conventions/SKILL.md
index 35c783ccc8f..77e903dd83d 100644
--- a/.claude/skills/backend-module-conventions/SKILL.md
+++ b/.claude/skills/backend-module-conventions/SKILL.md
@@ -5,7 +5,7 @@ description: Where Metabase backend code goes and how it reaches the app DB. Cov
# Backend module conventions
-This skill decides where a line of backend code lives and how it reaches the app DB. Project `CLAUDE.md`
+This skill decides where a line of backend code lives and how it reaches the app DB. Project `AGENTS.md`
covers the module config keys, nested modules, test commands, and ratchets. When the two disagree, the
source tree wins. Read the linter or test that enforces a rule before you trust any prose about it,
including this file.
diff --git a/.claude/skills/clojure-write/SKILL.md b/.claude/skills/clojure-write/SKILL.md
index 0760a2c7c25..f7d6640d8ef 100644
--- a/.claude/skills/clojure-write/SKILL.md
+++ b/.claude/skills/clojure-write/SKILL.md
@@ -124,4 +124,4 @@ breakage keeps happening, *that* is the signal a comment was warranted.
- After changing module boundaries (adding/removing/renaming a `src` namespace, a cross-module `require`
or `:model/X` reference, or a new module), run `./bin/mage fix-modules-config` to regenerate
`.clj-kondo/config/modules/config.edn` and keep `metabase.core.modules-test` green. No-op when nothing
- drifted; see "Module Boundaries" in the project `CLAUDE.md`.
+ drifted; see "Module Boundaries" in the project `AGENTS.md`.
diff --git a/.claude/skills/typescript-review/SKILL.md b/.claude/skills/typescript-review/SKILL.md
index 395747a30da..6637880ac10 100644
--- a/.claude/skills/typescript-review/SKILL.md
+++ b/.claude/skills/typescript-review/SKILL.md
@@ -19,7 +19,7 @@ metadata:
## Main Focus
-**Primary standard: the [`typescript-write`](../typescript-write/SKILL.md) skill.** Load it first — it defines the authoring rules this review enforces, alongside `frontend/CLAUDE.md` and `docs/developers-guide/frontend.md`.
+**Primary standard: the [`typescript-write`](../typescript-write/SKILL.md) skill.** Load it first — it defines the authoring rules this review enforces, alongside `frontend/AGENTS.md` and `docs/developers-guide/frontend.md`.
Adherence to `typescript-write` is the **highest-priority** review dimension: rank any violation of its provisions above all other findings. Treat its **no-`any` hard rule** (no explicit *or* implicit `any` in new, moved, or otherwise edited code) as **blocking**. Use TypeScript LSP tools to inspect inferred types when available; otherwise rely on type-checking and linting.
@@ -28,7 +28,7 @@ Read the full diff and new files, including tests and helpers. For tests, check
Review in this priority order:
1. **Violations of [`typescript-write`](../typescript-write/SKILL.md) provisions** — no-`any`, type tightening, type modeling, function signatures, null/undefined handling, naming, structure, comments. Highest priority; block on the no-`any` rule. Apply conditional guidance in context: explain the unsupported type guarantee or concrete readability problem, rather than treating every preference as a blanket ban.
-2. Compliance with `frontend/CLAUDE.md`.
+2. Compliance with `frontend/AGENTS.md`.
3. Readability and maintainability.
4. Appropriate test coverage. For internal typed callers, avoid requesting tests solely for inputs the type system excludes. External API data, deserialised values, storage and JavaScript callers can violate annotations: test runtime validation and nontrivial assumptions at those boundaries. Types do not replace behavioural, security or data-integrity tests.
diff --git a/.claude/skills/typescript-write/SKILL.md b/.claude/skills/typescript-write/SKILL.md
index c4ad2663b0e..f3cee41f578 100644
--- a/.claude/skills/typescript-write/SKILL.md
+++ b/.claude/skills/typescript-write/SKILL.md
@@ -5,7 +5,7 @@ description: Write or modify TypeScript and JavaScript code, including tests and
# TypeScript/JavaScript Development Skill
-Before frontend edits, including test-only changes, read `frontend/CLAUDE.md`, `docs/developers-guide/frontend.md`, and the shared references below. For new or edited tests, follow [Test authoring](#test-authoring).
+Before frontend edits, including test-only changes, read `frontend/AGENTS.md`, `docs/developers-guide/frontend.md`, and the shared references below. For new or edited tests, follow [Test authoring](#test-authoring).
@./../_shared/development-workflow.md
@./../_shared/typescript-commands.md
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index d759f44e572..51ed5bca223 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,6 +1,6 @@
# Metabase Developer Assistant Instructions
-For detailed coding standards and conventions, see `CLAUDE.md` and the skills in `.claude/skills/`.
+For detailed coding standards and conventions, see `AGENTS.md` and the skills in `.claude/skills/`.
## Code Review Standards
diff --git a/.github/instructions/typescript.instructions.md b/.github/instructions/typescript.instructions.md
index 1c737ad3697..d2bf32e23dd 100644
--- a/.github/instructions/typescript.instructions.md
+++ b/.github/instructions/typescript.instructions.md
@@ -8,4 +8,4 @@ When reviewing TypeScript or JavaScript code, apply the guidelines in these file
- `.claude/skills/typescript-review/SKILL.md`
- `docs/developers-guide/frontend.md`
-- `frontend/CLAUDE.md`
+- `frontend/AGENTS.md`
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..7c879322cec
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,148 @@
+# Metabase Development Guide
+
+## Do Not Edit `docs/` Alongside Code Changes
+
+**NEVER** change files under `docs/` as part of a code change, even if the change makes the docs out of date.
+A dedicated team of technical writers owns `docs/` and updates it. Edit `docs/` only when the task is
+explicitly a documentation task. If your code change affects documented behavior, say so in your summary
+or PR description so the writers can follow up.
+
+Exception: engineers maintain `docs/developers-guide/`. Update it alongside code changes when needed, for
+example the driver changelog for new driver multimethods or the API changelog for breaking API changes.
+
+# Skills
+
+For detailed guidance on writing and reviewing code and documentation, see the skills in [.claude/skills/](.claude/skills/):
+
+## Clojure
+
+### clojure-mcp tools
+
+- **[clojure-eval](.claude/skills/clojure-eval/SKILL.md)** - Always use this to evaluate Clojure code, **run tests**, and verify edits/compile. Prefer this over shell commands.
+- **[clojure-write](.claude/skills/clojure-write/SKILL.md)** - Clojure/ClojureScript development with REPL-driven workflow and coding conventions
+- **[clojure-review](.claude/skills/clojure-review/SKILL.md)** - Clojure/ClojureScript code review guidelines and style enforcement
+
+### clojure-mcp-lite tools
+
+- **clj-nrepl-eval** - This is another good mechanism for running Clojure code on an nrepl server.
+
+### Application database
+
+- **[app-db-migrations](.claude/skills/app-db-migrations/SKILL.md)** - Add, test, run and roll back application-database (Liquibase) migrations: version-less changesets, lint rules, dev rollback by deployment
+
+## TypeScript
+
+- **[typescript-write](.claude/skills/typescript-write/SKILL.md)** - TypeScript/JavaScript development and best practices
+- **[typescript-review](.claude/skills/typescript-review/SKILL.md)** - TypeScript/JavaScript code review guidelines
+
+## Documentation
+
+- **[docs-write](.claude/skills/docs-write/SKILL.md)** - Documentation writing with Metabase style guide
+- **[docs-review](.claude/skills/docs-review/SKILL.md)** - Documentation review checklist
+
+## Serialization
+
+- **[serdes-workflow](.claude/skills/serdes-workflow/SKILL.md)** - Export, validate, and import Metabase content via serdes
+- **[serdes-yaml-edit](.claude/skills/serdes-yaml-edit/SKILL.md)** - Edit exported YAML files with correct portable references
+
+## Frontend
+
+- **[analytics-events](.claude/skills/analytics-events/SKILL.md)** - Add product analytics events to track user interactions
+
+**Important**: When working with frontend code, read [frontend/AGENTS.md](frontend/AGENTS.md) for project-specific guidelines on component preferences, styling, testing requirements, and available scripts.
+
+## Running Backend Tests
+
+If you do not have `clojure-eval` available to you or `clj-nrepl-eval`, do not fall back to `clj -X:dev:test` directly. Instead, use `./bin/test-agent`. It produces clean, plain-text output with no progress bars or ANSI codes.
+
+```bash
+./bin/test-agent :only '[metabase.foo-test]' # run a namespace
+./bin/test-agent :only '[metabase.foo-test/some-test]' # run a single test
+./bin/test-agent :only '[metabase.foo-test metabase.bar-test]' # multiple namespaces
+```
+
+For module-scoped runs — useful when validating a branch's blast radius — pass `:module` (single) or `:modules` (vector) to scope tests to the module(s) the branch touched. The test runner resolves each module to its test directory through its `:ns-prefix`: `lib.schema` → `test/metabase/lib/schema`, `enterprise/foo` → `enterprise/backend/test/metabase_enterprise/foo` (see `metabase.test-runner/module-folders`).
+
+```bash
+./bin/test-agent :module enterprise/workspaces
+./bin/test-agent :modules '[sql-parsing query-processor]'
+# Driver tests: --drivers=LIST adds the driver aliases and sets DRIVERS=LIST in one step.
+./bin/test-agent --drivers=mysql,h2,postgres :module enterprise/workspaces
+```
+
+Once again, do not use `clj -X:dev:test` directly — its progress-bar output is hard to parse.
+
+## Module Boundaries
+
+The linter config at `.clj-kondo/config/modules/config.edn` records each module's `:api`, `:uses`,
+`:model-exports`, and `:model-imports`. `metabase.core.modules-test` fails when it drifts from the source.
+
+After **any** backend change that could shift module boundaries, regenerate it:
+
+```bash
+./bin/mage fix-modules-config
+```
+
+Changes that shift boundaries include: adding/removing/renaming a `src` namespace, adding or dropping a
+cross-module `require` or `:model/X` reference, or creating a new module. When unsure, just run it — it is
+a no-op (exits `unchanged`) when nothing drifted.
+
+It piggybacks on a running dev nREPL (~5s) and auto-spawns a JVM if none is running (~15s). It only edits
+the four generated keys; structural changes it can't safely make (a new module needs a human `:team`, or
+modules need reordering) are printed as `WARNING:` lines for you to resolve by hand.
+
+Run all repository-level checks, or one named suite:
+
+```bash
+./bin/mage project-tests
+./bin/mage project-tests <backend|migrations|modules|ratchets>
+```
+
+### Nested modules
+
+Module names form a tree: `lib.schema` is a child of `lib`. When OSS module `search` exists,
+`enterprise/search` is its child. Run `./bin/mage modules-tree` to inspect the hierarchy, or add `--html` for an
+interactive explorer with a dependency graph.
+
+- Namespace ownership uses the most specific matching prefix. Declaring `lib.schema` assigns
+ `metabase.lib.schema.*` to it without moving files. Use `:ns-prefix` when namespaces do not match the
+ module name.
+- Every cross-module dependency still requires `:uses`.
+- A child may use an ancestor's internal namespaces. Parents, siblings, and unrelated modules must use the
+ target's `:api`.
+- Each `:module-exports` entry widens a nested module's visibility by one ancestor. Export every link to
+ make it available everywhere. OSS module `X` exports its `enterprise/X` companion automatically.
+
+## Moving or Renaming Quartz Jobs
+
+Keep a job's `:saved-class` the same when you move its namespace or rename its type. Quartz stores that
+class name in the app DB, and `task/defjob` gives the class exactly that name, so a move changes nothing
+that is stored.
+A new job needs one too: compile without it, and the error prints the entry to paste.
+
+Changing a `:saved-class` deletes the jobs stored under the old name, and their triggers, at the next startup.
+The tests in `metabase.app-db.quartz-test` fail with instructions when a job's class name changes, or a job
+is added.
+
+## Ratchets
+
+After changing Clojure suppressions or module-boundary escape hatches, run `./bin/mage kondo-ratchets`.
+Fix the underlying issue when possible; suppressions are a last resort and need a nearby explanation.
+
+Inline-ignore budgets live in `.clj-kondo/ratchets.edn` for production code and `.clj-kondo/ratchets-test.edn`
+for anything under a `test` directory. Module-boundary escape hatches live in
+`.clj-kondo/config/modules/ratchets.edn`.
+
+Explain budget increases in the PR. Do not record reductions in feature PRs: post-merge automation opens
+a `Tighten ratchets` PR for them. Use `./bin/mage kondo-ratchets-shrink --seed :linter` only when adding an
+inline-ignore budget. If any ratchet file conflicts, run `./bin/merge-kondo-ratchets`.
+
+`metabase.core.module-cycles-test` checks that each cyclic cluster of the module require graph has exactly one
+name in `.clj-kondo/config/modules/cycle-clusters.edn`. When it fails, its message says what to change.
+
+`./bin/mage kondo-ratchets` needs the Clojure CLI as well as Babashka. Each ratchet task's `--help` lists its
+options, and `./bin/mage kondo-ratchets-history` reports which commits shrank and grew the budgets.
+
+## Tool Preferences
+
+If `clojure-mcp` tools are available, prefer them over shell-based alternatives for Clojure development.
diff --git a/CLAUDE.md b/CLAUDE.md
index 215a473852a..43c994c2d36 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,148 +1 @@
-# Metabase Development Guide
-
-## Do Not Edit `docs/` Alongside Code Changes
-
-**NEVER** change files under `docs/` as part of a code change, even if the change makes the docs out of date.
-A dedicated team of technical writers owns `docs/` and updates it. Edit `docs/` only when the task is
-explicitly a documentation task. If your code change affects documented behavior, say so in your summary
-or PR description so the writers can follow up.
-
-Exception: engineers maintain `docs/developers-guide/`. Update it alongside code changes when needed, for
-example the driver changelog for new driver multimethods or the API changelog for breaking API changes.
-
-# Skills
-
-For detailed guidance on writing and reviewing code and documentation, see the skills in [.claude/skills/](.claude/skills/):
-
-## Clojure
-
-### clojure-mcp tools
-
-- **[clojure-eval](.claude/skills/clojure-eval/SKILL.md)** - Always use this to evaluate Clojure code, **run tests**, and verify edits/compile. Prefer this over shell commands.
-- **[clojure-write](.claude/skills/clojure-write/SKILL.md)** - Clojure/ClojureScript development with REPL-driven workflow and coding conventions
-- **[clojure-review](.claude/skills/clojure-review/SKILL.md)** - Clojure/ClojureScript code review guidelines and style enforcement
-
-### clojure-mcp-lite tools
-
-- **clj-nrepl-eval** - This is another good mechanism for running Clojure code on an nrepl server.
-
-### Application database
-
-- **[app-db-migrations](.claude/skills/app-db-migrations/SKILL.md)** - Add, test, run and roll back application-database (Liquibase) migrations: version-less changesets, lint rules, dev rollback by deployment
-
-## TypeScript
-
-- **[typescript-write](.claude/skills/typescript-write/SKILL.md)** - TypeScript/JavaScript development and best practices
-- **[typescript-review](.claude/skills/typescript-review/SKILL.md)** - TypeScript/JavaScript code review guidelines
-
-## Documentation
-
-- **[docs-write](.claude/skills/docs-write/SKILL.md)** - Documentation writing with Metabase style guide
-- **[docs-review](.claude/skills/docs-review/SKILL.md)** - Documentation review checklist
-
-## Serialization
-
-- **[serdes-workflow](.claude/skills/serdes-workflow/SKILL.md)** - Export, validate, and import Metabase content via serdes
-- **[serdes-yaml-edit](.claude/skills/serdes-yaml-edit/SKILL.md)** - Edit exported YAML files with correct portable references
-
-## Frontend
-
-- **[analytics-events](.claude/skills/analytics-events/SKILL.md)** - Add product analytics events to track user interactions
-
-**Important**: When working with frontend code, read [frontend/CLAUDE.md](frontend/CLAUDE.md) for project-specific guidelines on component preferences, styling, testing requirements, and available scripts.
-
-## Running Backend Tests
-
-If you do not have `clojure-eval` available to you or `clj-nrepl-eval`, do not fall back to `clj -X:dev:test` directly. Instead, use `./bin/test-agent`. It produces clean, plain-text output with no progress bars or ANSI codes.
-
-```bash
-./bin/test-agent :only '[metabase.foo-test]' # run a namespace
-./bin/test-agent :only '[metabase.foo-test/some-test]' # run a single test
-./bin/test-agent :only '[metabase.foo-test metabase.bar-test]' # multiple namespaces
-```
-
-For module-scoped runs — useful when validating a branch's blast radius — pass `:module` (single) or `:modules` (vector) to scope tests to the module(s) the branch touched. The test runner resolves each module to its test directory through its `:ns-prefix`: `lib.schema` → `test/metabase/lib/schema`, `enterprise/foo` → `enterprise/backend/test/metabase_enterprise/foo` (see `metabase.test-runner/module-folders`).
-
-```bash
-./bin/test-agent :module enterprise/workspaces
-./bin/test-agent :modules '[sql-parsing query-processor]'
-# Driver tests: --drivers=LIST adds the driver aliases and sets DRIVERS=LIST in one step.
-./bin/test-agent --drivers=mysql,h2,postgres :module enterprise/workspaces
-```
-
-Once again, do not use `clj -X:dev:test` directly — its progress-bar output is hard to parse.
-
-## Module Boundaries
-
-The linter config at `.clj-kondo/config/modules/config.edn` records each module's `:api`, `:uses`,
-`:model-exports`, and `:model-imports`. `metabase.core.modules-test` fails when it drifts from the source.
-
-After **any** backend change that could shift module boundaries, regenerate it:
-
-```bash
-./bin/mage fix-modules-config
-```
-
-Changes that shift boundaries include: adding/removing/renaming a `src` namespace, adding or dropping a
-cross-module `require` or `:model/X` reference, or creating a new module. When unsure, just run it — it is
-a no-op (exits `unchanged`) when nothing drifted.
-
-It piggybacks on a running dev nREPL (~5s) and auto-spawns a JVM if none is running (~15s). It only edits
-the four generated keys; structural changes it can't safely make (a new module needs a human `:team`, or
-modules need reordering) are printed as `WARNING:` lines for you to resolve by hand.
-
-Run all repository-level checks, or one named suite:
-
-```bash
-./bin/mage project-tests
-./bin/mage project-tests <backend|migrations|modules|ratchets>
-```
-
-### Nested modules
-
-Module names form a tree: `lib.schema` is a child of `lib`. When OSS module `search` exists,
-`enterprise/search` is its child. Run `./bin/mage modules-tree` to inspect the hierarchy, or add `--html` for an
-interactive explorer with a dependency graph.
-
-- Namespace ownership uses the most specific matching prefix. Declaring `lib.schema` assigns
- `metabase.lib.schema.*` to it without moving files. Use `:ns-prefix` when namespaces do not match the
- module name.
-- Every cross-module dependency still requires `:uses`.
-- A child may use an ancestor's internal namespaces. Parents, siblings, and unrelated modules must use the
- target's `:api`.
-- Each `:module-exports` entry widens a nested module's visibility by one ancestor. Export every link to
- make it available everywhere. OSS module `X` exports its `enterprise/X` companion automatically.
-
-## Moving or Renaming Quartz Jobs
-
-Keep a job's `:saved-class` the same when you move its namespace or rename its type. Quartz stores that
-class name in the app DB, and `task/defjob` gives the class exactly that name, so a move changes nothing
-that is stored.
-A new job needs one too: compile without it, and the error prints the entry to paste.
-
-Changing a `:saved-class` deletes the jobs stored under the old name, and their triggers, at the next startup.
-The tests in `metabase.app-db.quartz-test` fail with instructions when a job's class name changes, or a job
-is added.
-
-## Ratchets
-
-After changing Clojure suppressions or module-boundary escape hatches, run `./bin/mage kondo-ratchets`.
-Fix the underlying issue when possible; suppressions are a last resort and need a nearby explanation.
-
-Inline-ignore budgets live in `.clj-kondo/ratchets.edn` for production code and `.clj-kondo/ratchets-test.edn`
-for anything under a `test` directory. Module-boundary escape hatches live in
-`.clj-kondo/config/modules/ratchets.edn`.
-
-Explain budget increases in the PR. Do not record reductions in feature PRs: post-merge automation opens
-a `Tighten ratchets` PR for them. Use `./bin/mage kondo-ratchets-shrink --seed :linter` only when adding an
-inline-ignore budget. If any ratchet file conflicts, run `./bin/merge-kondo-ratchets`.
-
-`metabase.core.module-cycles-test` checks that each cyclic cluster of the module require graph has exactly one
-name in `.clj-kondo/config/modules/cycle-clusters.edn`. When it fails, its message says what to change.
-
-`./bin/mage kondo-ratchets` needs the Clojure CLI as well as Babashka. Each ratchet task's `--help` lists its
-options, and `./bin/mage kondo-ratchets-history` reports which commits shrank and grew the budgets.
-
-## Tool Preferences
-
-If `clojure-mcp` tools are available, prefer them over shell-based alternatives for Clojure development.
diff --git a/dev/bot/common/environment-discovery.md b/dev/bot/common/environment-discovery.md
index 0cb203cf8c5..94ddb6a539a 100644
--- a/dev/bot/common/environment-discovery.md
+++ b/dev/bot/common/environment-discovery.md
@@ -1,6 +1,6 @@
## Initial Setup
-1. If you have not already, read `CLAUDE.md` in the project root for test commands and conventions.
+1. If you have not already, read `AGENTS.md` in the project root for test commands and conventions.
2. **Create all directories and files that later steps will Read or Write.** Run this single Bash command up front so the rest of the phases don't trip over missing paths:
```bash
mkdir -p .bot/autobot {{OUTPUT_DIR}}/output {{OUTPUT_DIR}}/tmp && touch .bot/autobot/llm-status.txt
diff --git a/frontend/AGENTS.md b/frontend/AGENTS.md
new file mode 100644
index 00000000000..cdba5e2f53b
--- /dev/null
+++ b/frontend/AGENTS.md
@@ -0,0 +1,62 @@
+# Working with frontend code
+
+## Where frontend code lives
+
+This is a high-level guide. Use available search tools to discover the current structure. Update the guide if new high-level modules have been added/discovered.
+
+- Main app UI: `frontend/src/metabase`
+- Query builder, notebook, and visualization flow: `frontend/src/metabase/query_builder`
+- Dashboard runtime and editing: `frontend/src/metabase/dashboard`
+- Admin screens: `frontend/src/metabase/admin`
+- Shared app components: `frontend/src/metabase/common/components`
+- API clients: `frontend/src/metabase/api`
+- Query building and data modeling: `frontend/src/metabase-lib`
+- Shared TypeScript types: `frontend/src/metabase-types`
+- Global and ambient type declarations: `frontend/src/types`
+- Embedding SDK OSS code: `frontend/src/embedding-sdk-bundle` and `frontend/src/embedding-sdk-shared`
+- Enterprise-only features: `enterprise/frontend/src/metabase-enterprise`
+- Enterprise embedding code: `enterprise/frontend/src/embedding`, `enterprise/frontend/src/embedding-sdk-ee`, and `enterprise/frontend/src/embedding-sdk-package`
+- Custom visualization enterprise code: `enterprise/frontend/src/custom-viz`
+- Jest unit tests: colocated next to the files they test
+- Jest test support and mocks: `frontend/test`
+- Cypress E2E scenarios: `e2e/test/scenarios`
+- Cypress component test scenarios: `e2e/test-component/scenarios`
+
+## Technology Stack
+
+- **Framework**: React 18 with TypeScript
+- **State**: Redux Toolkit
+- **Styling**: Mantine style props (preferred) > CSS Modules
+- **UI**: `metabase/ui` components built with Mantine v8
+- **Package manager**: Bun
+- **Build**: Rspack (primary), Webpack (legacy)
+- **Testing**: Jest + React Testing Library, Cypress
+
+## Coding Standards
+
+@../docs/developers-guide/frontend.md
+
+Read `docs/developers-guide/frontend.md` before frontend work — it's the detailed guide imported above.
+
+### Load skills before relevant edits
+
+Skills apply based on the files being changed, including small or incidental edits. Invoke
+each applicable skill by name before the first relevant edit; more than one skill may
+apply. Skills hold the authoritative, detailed rules; when they disagree with the guide
+above or the notes below, follow the skill.
+
+- Editing any `.ts`, `.tsx`, `.js`, or `.jsx` file, including tests and configuration → **typescript-write**
+- Reviewing a TypeScript/React diff → **typescript-review**
+- Writing Cypress E2E specs → **e2e-test-create**, **typescript-write**
+- Running / debugging Cypress E2E → **e2e-test**
+- Replacing Emotion styled-components with Mantine → **emotion-migrate**
+- Adding product analytics events → **analytics-events**
+- Restyling / implementing a `metabase/ui` component from a Figma spec → **metabase-ui-component-from-figma**
+
+### Enterprise Features
+
+Enterprise functionality MUST use the plugin system. It is very important to not expose enterprise code in the OSS version.
+
+### Scripts
+
+@../.claude/skills/_shared/typescript-commands.md
diff --git a/frontend/CLAUDE.md b/frontend/CLAUDE.md
index cdba5e2f53b..43c994c2d36 100644
--- a/frontend/CLAUDE.md
+++ b/frontend/CLAUDE.md
@@ -1,62 +1 @@
-# Working with frontend code
-
-## Where frontend code lives
-
-This is a high-level guide. Use available search tools to discover the current structure. Update the guide if new high-level modules have been added/discovered.
-
-- Main app UI: `frontend/src/metabase`
-- Query builder, notebook, and visualization flow: `frontend/src/metabase/query_builder`
-- Dashboard runtime and editing: `frontend/src/metabase/dashboard`
-- Admin screens: `frontend/src/metabase/admin`
-- Shared app components: `frontend/src/metabase/common/components`
-- API clients: `frontend/src/metabase/api`
-- Query building and data modeling: `frontend/src/metabase-lib`
-- Shared TypeScript types: `frontend/src/metabase-types`
-- Global and ambient type declarations: `frontend/src/types`
-- Embedding SDK OSS code: `frontend/src/embedding-sdk-bundle` and `frontend/src/embedding-sdk-shared`
-- Enterprise-only features: `enterprise/frontend/src/metabase-enterprise`
-- Enterprise embedding code: `enterprise/frontend/src/embedding`, `enterprise/frontend/src/embedding-sdk-ee`, and `enterprise/frontend/src/embedding-sdk-package`
-- Custom visualization enterprise code: `enterprise/frontend/src/custom-viz`
-- Jest unit tests: colocated next to the files they test
-- Jest test support and mocks: `frontend/test`
-- Cypress E2E scenarios: `e2e/test/scenarios`
-- Cypress component test scenarios: `e2e/test-component/scenarios`
-
-## Technology Stack
-
-- **Framework**: React 18 with TypeScript
-- **State**: Redux Toolkit
-- **Styling**: Mantine style props (preferred) > CSS Modules
-- **UI**: `metabase/ui` components built with Mantine v8
-- **Package manager**: Bun
-- **Build**: Rspack (primary), Webpack (legacy)
-- **Testing**: Jest + React Testing Library, Cypress
-
-## Coding Standards
-
-@../docs/developers-guide/frontend.md
-
-Read `docs/developers-guide/frontend.md` before frontend work — it's the detailed guide imported above.
-
-### Load skills before relevant edits
-
-Skills apply based on the files being changed, including small or incidental edits. Invoke
-each applicable skill by name before the first relevant edit; more than one skill may
-apply. Skills hold the authoritative, detailed rules; when they disagree with the guide
-above or the notes below, follow the skill.
-
-- Editing any `.ts`, `.tsx`, `.js`, or `.jsx` file, including tests and configuration → **typescript-write**
-- Reviewing a TypeScript/React diff → **typescript-review**
-- Writing Cypress E2E specs → **e2e-test-create**, **typescript-write**
-- Running / debugging Cypress E2E → **e2e-test**
-- Replacing Emotion styled-components with Mantine → **emotion-migrate**
-- Adding product analytics events → **analytics-events**
-- Restyling / implementing a `metabase/ui` component from a Figma spec → **metabase-ui-component-from-figma**
-
-### Enterprise Features
-
-Enterprise functionality MUST use the plugin system. It is very important to not expose enterprise code in the OSS version.
-
-### Scripts
-
-@../.claude/skills/_shared/typescript-commands.md
diff --git a/frontend/src/metabase/documents/AGENTS.md b/frontend/src/metabase/documents/AGENTS.md
new file mode 100644
index 00000000000..3a7c0078e02
--- /dev/null
+++ b/frontend/src/metabase/documents/AGENTS.md
@@ -0,0 +1,5 @@
+In this directory we have a rich text editor based on tiptap. We implemented custom nodes - like CardEmbedNode, FlexContainer and ResizeNode.
+Also, we added custom drag'n'drop logic to handle these custom nodes. Every CardEmbedNode is wrapped into a ResizeNode to make it resizable vertically.
+
+It is possible to drop a CardEmbedNode onto another CardEmbedNode, this leads into creating a FlexContainer that contains both CardEmbedNodes side-by-side. Result FlexContainer is wrapped into a ResizeNode.
+FlexContainer should not contain more than 3 child nodes like CardEmbedNode.
diff --git a/frontend/src/metabase/documents/CLAUDE.md b/frontend/src/metabase/documents/CLAUDE.md
index 3a7c0078e02..43c994c2d36 100644
--- a/frontend/src/metabase/documents/CLAUDE.md
+++ b/frontend/src/metabase/documents/CLAUDE.md
@@ -1,5 +1 @@
-In this directory we have a rich text editor based on tiptap. We implemented custom nodes - like CardEmbedNode, FlexContainer and ResizeNode.
-Also, we added custom drag'n'drop logic to handle these custom nodes. Every CardEmbedNode is wrapped into a ResizeNode to make it resizable vertically.
-
-It is possible to drop a CardEmbedNode onto another CardEmbedNode, this leads into creating a FlexContainer that contains both CardEmbedNodes side-by-side. Result FlexContainer is wrapped into a ResizeNode.
-FlexContainer should not contain more than 3 child nodes like CardEmbedNode.