{"owner":"WordPress","repo":"gutenberg","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# AGENTS.md\n\n## Dev environment tips\n\n```bash\n# Setup\nnvm use                    # Use the required node version\nnpm install && composer install\nnpm run wp-env-test status      # Always check status first.\nnpm run wp-env-test start       # Only start if not already running.\n\n# Development\nnpm start     # Development with watch\nnpm run build # Production build\nnpm run build -- --skip-types # Faster build; skips type generation\n```\n\n### Key Directories\n\n-   `/packages/` - JavaScript packages (each has README.md and CHANGELOG.md)\n-   `/lib/` - PHP code\n-   `/lib/compat/wordpress-X.Y/` - Version-specific features (new PHP features usually go here)\n-   `/phpunit/` - PHP tests\n-   `/schemas/json/` - JSON Schemas for `block.json`, `theme.json`, `font-collection.json`, and `wp-env.json` (published to `schemas.wp.org`; tests in `/test/integration/`)\n-   `/docs/` - Documentation\n    -   `/docs/contributors/` - Contributing guides\n    -   `/docs/explanations/architecture/` - System architecture docs\n    -   `/docs/how-to-guides/` - Implementation tutorials\n    -   `/docs/reference-guides/` - API documentation\n\n## Progressive discovery\n\nRead only what your task needs, when it needs it:\n\n-   **Contributor docs**: before starting a task, check `docs/contributors/code/` for the guide covering that kind of work (coding guidelines, backward compatibility, workspaces, releases) and read the relevant one.\n-   **User-facing copy**: before writing or changing a string a user reads, read `docs/contributors/documentation/copy-guide.md` — it covers terminology, capitalization, and how to word an error message.\n-   **Directory guides**: some directories carry their own `AGENTS.md` and `README.md` with rules for working there (e.g. `packages/components/AGENTS.md`) — read it before changing files in that directory.\n\n## Code quality\n\n```bash\nnpm run format            # Fix JS formatting\nnpm run lint:js          # Check JS linting\nnpm run typecheck        # Type check sources, plus dev files of migrated packages\nvendor/bin/phpcbf        # Fix PHP standards\nvendor/bin/phpcs         # Check PHP standards\n\n# Specific files\nvendor/bin/phpcbf <path_to_php_file.php>\n```\n\n## Architectural decisions\n\n-   **Package layering**: Three editor layers — `block-editor` (generic, WP-agnostic) → `editor` (WordPress post-type-aware) → `edit-post`/`edit-site` (full screens). Lower layers MUST NOT depend on higher ones.\n-   **Block data model**: Blocks are in-memory tree structures during editing, serialized as HTML with comment delimiters (`<!-- wp:name -->`). Work with the block tree via APIs, not the serialized HTML.\n-   **Data layer**: Uses `@wordpress/data` (Redux-like stores). Edit entities through `core-data` actions (`editEntityRecord` / `saveEditedEntityRecord`), not direct state manipulation.\n-   **Styles system**: Three-layer merge — WordPress defaults < `theme.json` < user preferences. Use Block Supports API and CSS custom properties (`--wp--preset--*`), not hardcoded values.\n-   **Modularity**: Packages are available both as npm packages and WordPress scripts (`wp-*` handles). Production packages must work in both contexts.\n\nFor full architecture details, see `docs/explanations/architecture/`.\n\n## Common pitfalls\n\n-   Do not add dependencies to the root `package.json`. Add them to the workspace that uses them, or create a new workspace under `tools/` (or `test/` for test infrastructure). See [Workspace Development](docs/contributors/code/workspace-development.md).\n-   PHP features in `lib/compat/` MUST go in the `wordpress-X.Y/` directory for their intended WordPress release. Inspect the available compatibility directories first; do not assume the newest one is right.\n-   Avoid using private APIs in bundled packages (packages without `wpScript` or `wpModuleExports`). Private APIs are intended for Core usage; bundled packages may also be imported via npm into plugin scripts, causing incompatibilities.\n-   Avoid adding new APIs prefixed with `__experimental` or `__unstable`. This pattern is now not used. Instead use private APIs or in bundled packages regular exports.\n-   `block-editor` is a WordPress-agnostic package. NEVER add `core-data` dependencies or direct REST API calls to it.\n-   `@wordpress/build` (`packages/wp-build`) is a generic build tool used both in Gutenberg and by plugins targeting WordPress Core directly. Avoid Gutenberg-specific changes in it.\n-   Never invoke WordPress's forked or local CLIs through `npx` (e.g. `npx prettier`, `npx wp-scripts`). WordPress ships its own `wp-prettier` fork, and `wp-scripts` is the bin name of `@wordpress/scripts`. A bare `npx wp-scripts` can resolve to an unrelated third-party package on the public registry, not the local tool. Use the npm scripts instead (`npm run format`, `npm run lint:js`, `npm run lint:css` and so on), which run the binaries from local `node_modules`.\n-   PHP function and class names are renamed at build time (`gutenberg_*` prefix, `*_Gutenberg` suffix) to avoid conflicts with WordPress Core — the built names, not the source names, are what runs (and what tests must call). See `docs/contributors/code/build-system-function-prefixing.md`.\n-   Production code changes in a package require an entry in that package's `CHANGELOG.md`. See `docs/contributors/code/managing-packages.md`.\n-   TypeScript configs are being split per package, one package at a time: `tsconfig.build.json` (src only, emits `build-types`) and the default `tsconfig.json` (dev project: tests and stories, `noEmit`, jest types). References to a split package point at `../<pkg>/tsconfig.build.json`, references to a package still on a single config point at `../<pkg>`. `npm run build` does not type check the dev files of split packages; use `npm run typecheck` for those, and keep jest types out of build projects. See the TypeScript section in `packages/README.md`.\n-   A rejected `apiFetch` is not always an `Error`: a REST error arrives as a plain object (`{ code, message, data }`), `parse: false` rejects with the `Response` (which carries `status`, not `message`), an aborted request rethrows an `AbortError`, and a handler set via `setFetchHandler` can reject anything. Do not interpolate the rejection into a string (`` `${ error }` `` gives `[object Object]`) or branch on `instanceof Error`. Normalise it to a message before showing the user anything, and supply your own copy when there is none — `ensureError` in `packages/core-data/src/private-actions.js` is the reference implementation, though it is local to that file rather than exported.\n\n## PR instructions\n\n-   Ensure build passes\n-   Fix all formatting/linting issues; these are enforced through CI in PRs\n",".github/copilot-instructions.md":"## PR review guidelines\n\nWhen reviewing pull requests:\n\n- Only comment on semantically meaningful issues: bugs, incorrect logic, security problems, accessibility regressions, or API contract violations.\n- Skip style, formatting, naming, and whitespace observations — these are enforced by lint and PHPCS.\n- Keep each comment short — one or two sentences maximum.\n- Do not write long descriptions or summaries of what the code does.\n- Do not suggest refactors or improvements unrelated to the PR's stated goal.\n- Keep the top-level review body empty unless a finding genuinely spans multiple files and can't be attached to a specific line. Put findings in inline comments wherever possible, and never use the review body to restate what the PR is doing.\n\n## What not to flag\n\n- **Do not speculate about external code.** Verify WordPress, PHP, and Node APIs, function signatures, and version constraints against the diff or repo files (`composer.json`, `package.json`, etc.) before flagging compatibility or contract issues. Do not invent strings, error messages, or behaviour in linked codebases such as WordPress core. If a claim cannot be verified from the diff or repository, do not include it.\n- **Calibrate edge-case warnings.** Do not flag theoretical edge cases (`Number.MAX_VALUE`, subnormals, inputs that cannot occur given current callers). Flag edge cases only when they correspond to inputs that can plausibly reach the code.\n\n## Gutenberg-specific context\n\n- Do not suggest replacing `@wordpress/data` selectors / actions with local React state — this is the project's intentional state pattern.\n- Do not suggest replacing `__()` / `_x()` / `_n()` calls with template literals — these are WordPress i18n functions.\n- Do not suggest moving code between `block-editor`, `editor`, and `edit-post` packages without considering the layering rule (`block-editor` is WordPress-agnostic; lower layers must not depend on higher ones).\n"},"files":{"AGENTS.md":"# AGENTS.md\n\n## Dev environment tips\n\n```bash\n# Setup\nnvm use                    # Use the required node version\nnpm install && composer install\nnpm run wp-env-test status      # Always check status first.\nnpm run wp-env-test start       # Only start if not already running.\n\n# Development\nnpm start     # Development with watch\nnpm run build # Production build\nnpm run build -- --skip-types # Faster build; skips type generation\n```\n\n### Key Directories\n\n-   `/packages/` - JavaScript packages (each has README.md and CHANGELOG.md)\n-   `/lib/` - PHP code\n-   `/lib/compat/wordpress-X.Y/` - Version-specific features (new PHP features usually go here)\n-   `/phpunit/` - PHP tests\n-   `/schemas/json/` - JSON Schemas for `block.json`, `theme.json`, `font-collection.json`, and `wp-env.json` (published to `schemas.wp.org`; tests in `/test/integration/`)\n-   `/docs/` - Documentation\n    -   `/docs/contributors/` - Contributing guides\n    -   `/docs/explanations/architecture/` - System architecture docs\n    -   `/docs/how-to-guides/` - Implementation tutorials\n    -   `/docs/reference-guides/` - API documentation\n\n## Progressive discovery\n\nRead only what your task needs, when it needs it:\n\n-   **Contributor docs**: before starting a task, check `docs/contributors/code/` for the guide covering that kind of work (coding guidelines, backward compatibility, workspaces, releases) and read the relevant one.\n-   **User-facing copy**: before writing or changing a string a user reads, read `docs/contributors/documentation/copy-guide.md` — it covers terminology, capitalization, and how to word an error message.\n-   **Directory guides**: some directories carry their own `AGENTS.md` and `README.md` with rules for working there (e.g. `packages/components/AGENTS.md`) — read it before changing files in that directory.\n\n## Code quality\n\n```bash\nnpm run format            # Fix JS formatting\nnpm run lint:js          # Check JS linting\nnpm run typecheck        # Type check sources, plus dev files of migrated packages\nvendor/bin/phpcbf        # Fix PHP standards\nvendor/bin/phpcs         # Check PHP standards\n\n# Specific files\nvendor/bin/phpcbf <path_to_php_file.php>\n```\n\n## Architectural decisions\n\n-   **Package layering**: Three editor layers — `block-editor` (generic, WP-agnostic) → `editor` (WordPress post-type-aware) → `edit-post`/`edit-site` (full screens). Lower layers MUST NOT depend on higher ones.\n-   **Block data model**: Blocks are in-memory tree structures during editing, serialized as HTML with comment delimiters (`<!-- wp:name -->`). Work with the block tree via APIs, not the serialized HTML.\n-   **Data layer**: Uses `@wordpress/data` (Redux-like stores). Edit entities through `core-data` actions (`editEntityRecord` / `saveEditedEntityRecord`), not direct state manipulation.\n-   **Styles system**: Three-layer merge — WordPress defaults < `theme.json` < user preferences. Use Block Supports API and CSS custom properties (`--wp--preset--*`), not hardcoded values.\n-   **Modularity**: Packages are available both as npm packages and WordPress scripts (`wp-*` handles). Production packages must work in both contexts.\n\nFor full architecture details, see `docs/explanations/architecture/`.\n\n## Common pitfalls\n\n-   Do not add dependencies to the root `package.json`. Add them to the workspace that uses them, or create a new workspace under `tools/` (or `test/` for test infrastructure). See [Workspace Development](docs/contributors/code/workspace-development.md).\n-   PHP features in `lib/compat/` MUST go in the `wordpress-X.Y/` directory for their intended WordPress release. Inspect the available compatibility directories first; do not assume the newest one is right.\n-   Avoid using private APIs in bundled packages (packages without `wpScript` or `wpModuleExports`). Private APIs are intended for Core usage; bundled packages may also be imported via npm into plugin scripts, causing incompatibilities.\n-   Avoid adding new APIs prefixed with `__experimental` or `__unstable`. This pattern is now not used. Instead use private APIs or in bundled packages regular exports.\n-   `block-editor` is a WordPress-agnostic package. NEVER add `core-data` dependencies or direct REST API calls to it.\n-   `@wordpress/build` (`packages/wp-build`) is a generic build tool used both in Gutenberg and by plugins targeting WordPress Core directly. Avoid Gutenberg-specific changes in it.\n-   Never invoke WordPress's forked or local CLIs through `npx` (e.g. `npx prettier`, `npx wp-scripts`). WordPress ships its own `wp-prettier` fork, and `wp-scripts` is the bin name of `@wordpress/scripts`. A bare `npx wp-scripts` can resolve to an unrelated third-party package on the public registry, not the local tool. Use the npm scripts instead (`npm run format`, `npm run lint:js`, `npm run lint:css` and so on), which run the binaries from local `node_modules`.\n-   PHP function and class names are renamed at build time (`gutenberg_*` prefix, `*_Gutenberg` suffix) to avoid conflicts with WordPress Core — the built names, not the source names, are what runs (and what tests must call). See `docs/contributors/code/build-system-function-prefixing.md`.\n-   Production code changes in a package require an entry in that package's `CHANGELOG.md`. See `docs/contributors/code/managing-packages.md`.\n-   TypeScript configs are being split per package, one package at a time: `tsconfig.build.json` (src only, emits `build-types`) and the default `tsconfig.json` (dev project: tests and stories, `noEmit`, jest types). References to a split package point at `../<pkg>/tsconfig.build.json`, references to a package still on a single config point at `../<pkg>`. `npm run build` does not type check the dev files of split packages; use `npm run typecheck` for those, and keep jest types out of build projects. See the TypeScript section in `packages/README.md`.\n-   A rejected `apiFetch` is not always an `Error`: a REST error arrives as a plain object (`{ code, message, data }`), `parse: false` rejects with the `Response` (which carries `status`, not `message`), an aborted request rethrows an `AbortError`, and a handler set via `setFetchHandler` can reject anything. Do not interpolate the rejection into a string (`` `${ error }` `` gives `[object Object]`) or branch on `instanceof Error`. Normalise it to a message before showing the user anything, and supply your own copy when there is none — `ensureError` in `packages/core-data/src/private-actions.js` is the reference implementation, though it is local to that file rather than exported.\n\n## PR instructions\n\n-   Ensure build passes\n-   Fix all formatting/linting issues; these are enforced through CI in PRs\n",".github/copilot-instructions.md":"## PR review guidelines\n\nWhen reviewing pull requests:\n\n- Only comment on semantically meaningful issues: bugs, incorrect logic, security problems, accessibility regressions, or API contract violations.\n- Skip style, formatting, naming, and whitespace observations — these are enforced by lint and PHPCS.\n- Keep each comment short — one or two sentences maximum.\n- Do not write long descriptions or summaries of what the code does.\n- Do not suggest refactors or improvements unrelated to the PR's stated goal.\n- Keep the top-level review body empty unless a finding genuinely spans multiple files and can't be attached to a specific line. Put findings in inline comments wherever possible, and never use the review body to restate what the PR is doing.\n\n## What not to flag\n\n- **Do not speculate about external code.** Verify WordPress, PHP, and Node APIs, function signatures, and version constraints against the diff or repo files (`composer.json`, `package.json`, etc.) before flagging compatibility or contract issues. Do not invent strings, error messages, or behaviour in linked codebases such as WordPress core. If a claim cannot be verified from the diff or repository, do not include it.\n- **Calibrate edge-case warnings.** Do not flag theoretical edge cases (`Number.MAX_VALUE`, subnormals, inputs that cannot occur given current callers). Flag edge cases only when they correspond to inputs that can plausibly reach the code.\n\n## Gutenberg-specific context\n\n- Do not suggest replacing `@wordpress/data` selectors / actions with local React state — this is the project's intentional state pattern.\n- Do not suggest replacing `__()` / `_x()` / `_n()` calls with template literals — these are WordPress i18n functions.\n- Do not suggest moving code between `block-editor`, `editor`, and `edit-post` packages without considering the layering rule (`block-editor` is WordPress-agnostic; lower layers must not depend on higher ones).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# AGENTS.md\n\n## Dev environment tips\n\n```bash\n# Setup\nnvm use                    # Use the required node version\nnpm install && composer install\nnpm run wp-env-test status      # Always check status first.\nnpm run wp-env-test start       # Only start if not already running.\n\n# Development\nnpm start     # Development with watch\nnpm run build # Production build\nnpm run build -- --skip-types # Faster build; skips type generation\n```\n\n### Key Directories\n\n-   `/packages/` - JavaScript packages (each has README.md and CHANGELOG.md)\n-   `/lib/` - PHP code\n-   `/lib/compat/wordpress-X.Y/` - Version-specific features (new PHP features usually go here)\n-   `/phpunit/` - PHP tests\n-   `/schemas/json/` - JSON Schemas for `block.json`, `theme.json`, `font-collection.json`, and `wp-env.json` (published to `schemas.wp.org`; tests in `/test/integration/`)\n-   `/docs/` - Documentation\n    -   `/docs/contributors/` - Contributing guides\n    -   `/docs/explanations/architecture/` - System architecture docs\n    -   `/docs/how-to-guides/` - Implementation tutorials\n    -   `/docs/reference-guides/` - API documentation\n\n## Progressive discovery\n\nRead only what your task needs, when it needs it:\n\n-   **Contributor docs**: before starting a task, check `docs/contributors/code/` for the guide covering that kind of work (coding guidelines, backward compatibility, workspaces, releases) and read the relevant one.\n-   **User-facing copy**: before writing or changing a string a user reads, read `docs/contributors/documentation/copy-guide.md` — it covers terminology, capitalization, and how to word an error message.\n-   **Directory guides**: some directories carry their own `AGENTS.md` and `README.md` with rules for working there (e.g. `packages/components/AGENTS.md`) — read it before changing files in that directory.\n\n## Code quality\n\n```bash\nnpm run format            # Fix JS formatting\nnpm run lint:js          # Check JS linting\nnpm run typecheck        # Type check sources, plus dev files of migrated packages\nvendor/bin/phpcbf        # Fix PHP standards\nvendor/bin/phpcs         # Check PHP standards\n\n# Specific files\nvendor/bin/phpcbf <path_to_php_file.php>\n```\n\n## Architectural decisions\n\n-   **Package layering**: Three editor layers — `block-editor` (generic, WP-agnostic) → `editor` (WordPress post-type-aware) → `edit-post`/`edit-site` (full screens). Lower layers MUST NOT depend on higher ones.\n-   **Block data model**: Blocks are in-memory tree structures during editing, serialized as HTML with comment delimiters (`<!-- wp:name -->`). Work with the block tree via APIs, not the serialized HTML.\n-   **Data layer**: Uses `@wordpress/data` (Redux-like stores). Edit entities through `core-data` actions (`editEntityRecord` / `saveEditedEntityRecord`), not direct state manipulation.\n-   **Styles system**: Three-layer merge — WordPress defaults < `theme.json` < user preferences. Use Block Supports API and CSS custom properties (`--wp--preset--*`), not hardcoded values.\n-   **Modularity**: Packages are available both as npm packages and WordPress scripts (`wp-*` handles). Production packages must work in both contexts.\n\nFor full architecture details, see `docs/explanations/architecture/`.\n\n## Common pitfalls\n\n-   Do not add dependencies to the root `package.json`. Add them to the workspace that uses them, or create a new workspace under `tools/` (or `test/` for test infrastructure). See [Workspace Development](docs/contributors/code/workspace-development.md).\n-   PHP features in `lib/compat/` MUST go in the `wordpress-X.Y/` directory for their intended WordPress release. Inspect the available compatibility directories first; do not assume the newest one is right.\n-   Avoid using private APIs in bundled packages (packages without `wpScript` or `wpModuleExports`). Private APIs are intended for Core usage; bundled packages may also be imported via npm into plugin scripts, causing incompatibilities.\n-   Avoid adding new APIs prefixed with `__experimental` or `__unstable`. This pattern is now not used. Instead use private APIs or in bundled packages regular exports.\n-   `block-editor` is a WordPress-agnostic package. NEVER add `core-data` dependencies or direct REST API calls to it.\n-   `@wordpress/build` (`packages/wp-build`) is a generic build tool used both in Gutenberg and by plugins targeting WordPress Core directly. Avoid Gutenberg-specific changes in it.\n-   Never invoke WordPress's forked or local CLIs through `npx` (e.g. `npx prettier`, `npx wp-scripts`). WordPress ships its own `wp-prettier` fork, and `wp-scripts` is the bin name of `@wordpress/scripts`. A bare `npx wp-scripts` can resolve to an unrelated third-party package on the public registry, not the local tool. Use the npm scripts instead (`npm run format`, `npm run lint:js`, `npm run lint:css` and so on), which run the binaries from local `node_modules`.\n-   PHP function and class names are renamed at build time (`gutenberg_*` prefix, `*_Gutenberg` suffix) to avoid conflicts with WordPress Core — the built names, not the source names, are what runs (and what tests must call). See `docs/contributors/code/build-system-function-prefixing.md`.\n-   Production code changes in a package require an entry in that package's `CHANGELOG.md`. See `docs/contributors/code/managing-packages.md`.\n-   TypeScript configs are being split per package, one package at a time: `tsconfig.build.json` (src only, emits `build-types`) and the default `tsconfig.json` (dev project: tests and stories, `noEmit`, jest types). References to a split package point at `../<pkg>/tsconfig.build.json`, references to a package still on a single config point at `../<pkg>`. `npm run build` does not type check the dev files of split packages; use `npm run typecheck` for those, and keep jest types out of build projects. See the TypeScript section in `packages/README.md`.\n-   A rejected `apiFetch` is not always an `Error`: a REST error arrives as a plain object (`{ code, message, data }`), `parse: false` rejects with the `Response` (which carries `status`, not `message`), an aborted request rethrows an `AbortError`, and a handler set via `setFetchHandler` can reject anything. Do not interpolate the rejection into a string (`` `${ error }` `` gives `[object Object]`) or branch on `instanceof Error`. Normalise it to a message before showing the user anything, and supply your own copy when there is none — `ensureError` in `packages/core-data/src/private-actions.js` is the reference implementation, though it is local to that file rather than exported.\n\n## PR instructions\n\n-   Ensure build passes\n-   Fix all formatting/linting issues; these are enforced through CI in PRs\n","category":"root","tokens":1670},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"## PR review guidelines\n\nWhen reviewing pull requests:\n\n- Only comment on semantically meaningful issues: bugs, incorrect logic, security problems, accessibility regressions, or API contract violations.\n- Skip style, formatting, naming, and whitespace observations — these are enforced by lint and PHPCS.\n- Keep each comment short — one or two sentences maximum.\n- Do not write long descriptions or summaries of what the code does.\n- Do not suggest refactors or improvements unrelated to the PR's stated goal.\n- Keep the top-level review body empty unless a finding genuinely spans multiple files and can't be attached to a specific line. Put findings in inline comments wherever possible, and never use the review body to restate what the PR is doing.\n\n## What not to flag\n\n- **Do not speculate about external code.** Verify WordPress, PHP, and Node APIs, function signatures, and version constraints against the diff or repo files (`composer.json`, `package.json`, etc.) before flagging compatibility or contract issues. Do not invent strings, error messages, or behaviour in linked codebases such as WordPress core. If a claim cannot be verified from the diff or repository, do not include it.\n- **Calibrate edge-case warnings.** Do not flag theoretical edge cases (`Number.MAX_VALUE`, subnormals, inputs that cannot occur given current callers). Flag edge cases only when they correspond to inputs that can plausibly reach the code.\n\n## Gutenberg-specific context\n\n- Do not suggest replacing `@wordpress/data` selectors / actions with local React state — this is the project's intentional state pattern.\n- Do not suggest replacing `__()` / `_x()` / `_n()` calls with template literals — these are WordPress i18n functions.\n- Do not suggest moving code between `block-editor`, `editor`, and `edit-post` packages without considering the layering rule (`block-editor` is WordPress-agnostic; lower layers must not depend on higher ones).\n","category":".github","tokens":485}]}