diff --git a/.oxlintrc.json b/.oxlintrc.json
index 7bc2fbad1..18ac71c5a 100644
--- a/.oxlintrc.json
+++ b/.oxlintrc.json
@@ -100,6 +100,7 @@
"sentry-cli/no-examples-in-full-description": "error",
"sentry-cli/no-regex-markdown-parsing": "error",
"sentry-cli/json-transform-uses-fields": "error",
+ "sentry-cli/no-runtime-output-schema-imports": "error",
"no-restricted-imports": [
"error",
{
diff --git a/packages/cli/AGENTS.md b/packages/cli/AGENTS.md
index c9520682e..925f67aaf 100644
--- a/packages/cli/AGENTS.md
+++ b/packages/cli/AGENTS.md
@@ -239,29 +239,46 @@ Lint enforcement: `stderr.write()` is banned in command files (GritQL rule). Use
`output.schema` drives `--fields` completion, the JSON field table in `--help`, and the skill references. Nothing validates output against it, so declare each field once and derive the TypeScript type from the schema; the compiler then keeps the two in sync ([#1824](https://github.com/getsentry/toolkit/issues/1824)).
+The schemas live in `src/output-schemas/.ts` (one module per top-level command), which only the build loads ([#1914](https://github.com/getsentry/toolkit/issues/1914)). `script/generate-output-schemas.ts` (part of `generate:docs`) reads each exported `…Schema` and writes its field list and `--fields` paths to the gitignored `src/generated/output-schemas/.ts`, under the same export name. A command imports that data as its `output.schema`, so a run loads only its own route's field lists, and none of the schemas:
+
+- Import the schema data from `src/generated/output-schemas/`, and everything else from `src/output-schemas/` with `import type` only. Lint (`sentry-cli/no-runtime-output-schema-imports`) rejects a value import, or `import { type X }`, which `verbatimModuleSyntax` keeps as a runtime import.
+- Export the type the command needs next to its schema (`export type ReleaseDeleteOutput = InferOutput`), or `import type` the schema and write `typeof`.
+- A schema that also validates an API response at runtime (`SentryLogSchema`, `TransactionListItemSchema`, `ConversationListItemSchema`, `DashboardRevisionSchema`) stays where it is and is re-exported from its area's module.
+- `src/output-schemas/` must not import `src/generated/output-schemas/`: the generator loads the former to write the latter.
+
- **API fields** keep their `@sentry/api` type and come from the generated `@sentry/api/valibot` schema (`vXxxResponse.entries`, wrapped in `pipe(field, description(…))` when it needs a description).
-- **Fields the CLI adds** (target context such as `org`/`orgSlug`, flags such as `dryRun`/`deleted`, computed values such as `url`, `trace`, `period`) are written once as a valibot `object` of output fields. Spread its `entries` into the schema, and get the type with `InferOutput`, or `WithOutputFields` (`src/types/output.ts`) when the fields sit on (or override) an API object.
+- **Fields the CLI adds** (target context such as `org`/`orgSlug`, flags such as `dryRun`/`deleted`, computed values such as `url`, `trace`, `period`) are written once as a valibot `object` of output fields. Spread its `entries` into the schema, and get the type with `InferOutput`, or `WithOutputFields` (`src/output-schemas/output.ts`) when the fields sit on (or override) an API object.
- Type the `human` formatter's parameter (and `jsonTransform`'s, when set) with the derived type. `buildCommand`, `buildListCommand`, and `buildDeleteCommand` infer the output type from `output` and check every `CommandOutput` that `func` yields against it. Annotate a yield (`new CommandOutput