wordpress-agent-kit 0.5.1 → 0.6.0

package/.github/skills/wp-abilities-verify/references/schema-lints.md

@@ -1,118 +0,0 @@
-# Schema Lints
-
-Static lints against an ability's `input_schema`. Schema hygiene is
-about *agent legibility*: orchestrating agents read the schema to
-figure out how to call the ability. A schema that's hard to parse,
-ambiguous, or misleading wastes turns even when the ability itself
-works.
-
-These lints are six small principles. Apply them by reading the
-schema, not by mechanically grepping — most plugins use enough
-formatting variety that grep recipes drift.
-
-## Lint 1 — `additionalProperties: false` for object schemas
-
-For top-level `'type' => 'object'` schemas, declare
-`'additionalProperties' => false` unless you deliberately accept
-extras. Without this, an agent passing a typo (`par_page` instead of
-`per_page`) gets accepted silently and falls through to the backing,
-which ignores the unknown key.
-
-- `additionalProperties: false` declared → OK.
-- `additionalProperties: true` declared → WARN, unless the schema is
-  for genuinely free-form metadata (payment custom fields, form
-  free-text); document the reason inline.
-- Not declared on an object schema → WARN.
-- Non-object root (string with enum, integer, etc.) → N/A. The lint
-  applies only to objects.
-
-## Lint 2 — every required field has a non-empty description
-
-For each entry in `required`, the matching `properties` entry must
-declare a non-empty `description`. Required fields are where agents
-most need guidance; an opaque required key forces the agent to guess
-from the field name alone. Empty / missing → FAIL.
-
-Optional-field descriptions are nice-to-have — absence is WARN.
-
-## Lint 3 — enums are non-empty
-
-`'enum' => []` accepts no values, rejecting every input. Almost always
-a bug. → FAIL.
-
-A single-value enum (`'enum' => [ 'pending' ]`) is legal but unusual;
-WARN and prompt for review — often a copy-paste that lost the other
-values.
-
-## Lint 4 — no `$ref`
-
-Agents read the schema via REST introspection. A `$ref` forces the
-agent to follow a reference to see the field shape — wastes a turn and
-often breaks because the referenced schema isn't in the same document.
-Inline the shape instead.
-
-Any `'$ref'` in the schema → FAIL.
-
-## Lint 5 — defaults are statically constant
-
-Each `'default'` value must evaluate to the same shape on every call:
-
-- Scalar literals — `true`, `false`, integer, float, quoted string,
-  `null` → OK.
-- Empty or all-literal arrays — `[]`, `array()`, `[ 'a', 'b' ]` → OK.
-- Literal cast to an empty object — `(object) array()`, `(object) []`
-  → OK. This is the recommended top-level default for zero-arg-allowed
-  abilities; see
-  `../../wp-abilities-api/references/input-schema-gotchas.md` §4.
-- `new stdClass()` with no arguments → OK.
-- A function call (`gmdate('c')`, `wp_generate_uuid4()`, `time()`),
-  variable reference, or other computed expression → FAIL.
-
-The principle: defaults that vary per call are both non-deterministic
-and surprising to agents that expect defaults to be static.
-
-## Lint 6 — `reference_ability: true` implies no required inputs
-
-If an audit doc is provided and an ability has
-`reference_ability: true`, its `input_schema.required` array must be
-empty or absent. The reference ability is the smallest, safest
-bootstrap call an implementer lands first; it must work with
-`execute([])`. Required inputs on the reference ability → FAIL.
-
-(No audit provided → this lint is skipped — no reference ability is
-declared.)
-
-## Cross-reference: gotchas 1-3 (callback hardening) and gotcha 4 (structural default)
-
-Static lints catch shape; the four runtime gotchas in
-`../../wp-abilities-api/references/input-schema-gotchas.md` split into
-two kinds.
-
-Gotchas 1-3 need defensive code in the execute callback —
-`array_key_exists` instead of `isset`-only for property defaults,
-pagination key translation, ID validation that accepts `"0"`. These
-are runtime behaviors the callback itself must handle; static schema
-lints can't enforce them.
-
-Gotcha 4 — the direct vs indirect invocation strictness — is what
-motivates the `(object) array()` top-level default that Lint 5
-explicitly accepts. This one IS structural and Lint 5 carries the
-enforcement.
-
-## Output format
-
-```markdown
-## Schema lints
-
-| Ability | Lint | Result | Detail |
-|---|---|---|---|
-| <ability> | additionalProperties (object schemas) | WARN | not declared on object schema |
-| <ability> | required-field descriptions | OK | 3/3 required fields documented |
-| <ability> | enum non-empty | OK | no enums |
-| <ability> | no $ref | OK | inline |
-| <ability> | static defaults | FAIL | `created_at` uses `gmdate('c')` |
-| <ability> | reference_ability implies no required | N/A | not reference ability |
-```
-
-A FAIL on any lint flips that ability to FAIL in the run summary.
-WARNs surface but don't block.

package/.github/skills/wp-abilities-verify/references/static-enumeration.md

@@ -1,126 +0,0 @@
-# Static Enumeration
-
-Enumerate a plugin's abilities from source, with no running
-environment. Static enumeration is necessarily best-effort — PHP's
-dynamism (variable indirection, runtime-conditional registration)
-means a complete inventory only comes from a live `wp_get_abilities()`
-call. When static and runtime inventories diverge, trust runtime;
-static drives the diff so the reviewer knows where to look.
-
-## Typical registration shape
-
-```php
-wp_register_ability(
-    '<plugin-slug>/<ability-name>',
-    array(
-        'label'               => __( '...', '<text-domain>' ),
-        'description'         => __( '...', '<text-domain>' ),
-        'category'            => '<category-slug>',
-        'input_schema'        => array( /* ... */ ),
-        'execute_callback'    => array( self::class, 'execute_my_ability' ),
-        'permission_callback' => array( self::class, 'check_permission' ),
-        'meta'                => array(
-            'annotations' => array(
-                'readonly'    => true,
-                'destructive' => false,
-                'idempotent'  => true,
-            ),
-            'show_in_rest' => true,
-        ),
-    )
-);
-```
-
-## Step 1 — find every registration call
-
-```bash
-grep -rn --include='*.php' 'wp_register_ability\s*(' <plugin-root>/
-```
-
-Zero hits → return a clear "no abilities registered" report per
-SKILL.md "Failure modes." Don't fabricate an empty inventory.
-
-## Step 2 — extract each ability name
-
-The first argument is the ability name — usually a literal string.
-Real-world formatting splits the call across lines (the example
-above is itself multi-line), so single-line regexes miss common
-cases. Use a multi-line tool:
-
-```bash
-# ripgrep with --multiline + PCRE2 captures the name regardless of line break:
-rg --multiline --pcre2 --type=php -n \
-   "wp_register_ability\s*\(\s*['\"]([^'\"]+)['\"]" <plugin-root>/
-
-# Fallbacks: pcregrep -M, perl -0777.
-```
-
-If the first argument is a variable or constant
-(`wp_register_ability( $name, ... )`,
-`wp_register_ability( MyPlugin\NAME, ... )`), trace it: a recent
-assignment in the same function or a class constant usually resolves;
-a name computed in a loop won't, in which case flag the limitation and
-recommend runtime mode for authoritative enumeration.
-
-## Step 3 — extract the annotation block
-
-Annotations live at `meta.annotations.{readonly,destructive,idempotent}`.
-For each registration, read the array literal forward until the
-matching close. Common shapes:
-
-- Multi-line literal (most common).
-- Short-form one-liner.
-- Helper method (`'annotations' => self::annotations_for_read()`) —
-  resolve the helper if it returns a literal; otherwise mark
-  `<unresolved>` and run the adversarial check against the callback
-  alone.
-- Class constant (`'annotations' => self::READONLY_ANNOTATIONS`) —
-  resolve the constant.
-
-Record `ability_name → declared_annotations`.
-
-## Step 4 — follow `execute_callback` to its body
-
-`execute_callback` is one of:
-
-```php
-'execute_callback' => array( self::class, 'execute_get_things' ),
-'execute_callback' => array( My_Class::class, 'execute_get_things' ),
-'execute_callback' => array( $this, 'execute_get_things' ),
-'execute_callback' => 'my_plugin_execute_get_things',  // top-level function
-'execute_callback' => function ( $input ) { /* ... */ },  // closure
-```
-
-Resolve the reference to its source location: file + start line + end
-line. The annotation-correctness, schema-lint, and permission checks
-all operate on that byte range.
-
-## Limits of static enumeration
-
-Cases where the inventory is incomplete or ambiguous:
-
-- Variable-indirected names (`foreach` over a slug list).
-- Variable-indirected annotations (built from config).
-- Conditional registration (`if ( feature_enabled() )`).
-- Variable-indirected callbacks (`array( $this, $callback_name )`).
-
-Record each in the report's "Static enumeration limitations" section
-and recommend a runtime-mode rerun for the authoritative inventory.
-
-## Output format
-
-```markdown
-## Static inventory
-
-Found <N> ability registrations across <M> files:
-
-| Ability | Source file | Registration line | Callback file | Callback lines |
-|---|---|---|---|---|
-| myplugin/get-foo | src/Abilities.php | 42 | src/Abilities.php | 102-134 |
-| myplugin/submit-bar | src/Abilities.php | 68 | src/Services/Bar.php | 58-91 |
-
-### Limitations
-
-- <ability>: annotations built dynamically in `annotations_for_read()`;
-  recommend runtime mode for annotation cross-check.
-```

package/.github/skills/wp-block-development/SKILL.md

@@ -1,175 +0,0 @@
----
-name: wp-block-development
-description: "Use when developing WordPress (Gutenberg) blocks: block.json metadata, register_block_type(_from_metadata), attributes/serialization, supports, dynamic rendering (render.php/render_callback), deprecations/migrations, viewScript vs viewScriptModule, and @wordpress/scripts/@wordpress/create-block build and test workflows."
-license: GPL-2.0-or-later
-compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Filesystem-based agent with bash + node. Some workflows require WP-CLI."
----
-
-# WP Block Development
-
-## When to use
-
-Use this skill for block work such as:
-
-- creating a new block, or updating an existing one
-- changing `block.json` (scripts/styles/supports/attributes/render/viewScriptModule)
-- fixing “block invalid / not saving / attributes not persisting”
-- adding dynamic rendering (`render.php` / `render_callback`)
-- block deprecations and migrations (`deprecated` versions)
-- build tooling for blocks (`@wordpress/scripts`, `@wordpress/create-block`, `wp-env`)
-
-## Inputs required
-
-- Repo root and target (plugin vs theme vs full site).
-- The block name/namespace and where it lives (path to `block.json` if known).
-- Target WordPress version range (especially if using modules / `viewScriptModule`).
-
-## Procedure
-
-### 0) Triage and locate blocks
-
-1. Run triage:
-   - `node skills/wp-project-triage/scripts/detect_wp_project.mjs`
-2. List blocks (deterministic scan):
-   - `node skills/wp-block-development/scripts/list_blocks.mjs`
-3. Identify the block root (directory containing `block.json`) you’re changing.
-
-If this repo is a full site (`wp-content/` present), be explicit about *which* plugin/theme contains the block.
-
-### 1) Create a new block (if needed)
-
-If you are creating a new block, prefer scaffolding rather than hand-rolling structure:
-
-- Use `@wordpress/create-block` to scaffold a modern block/plugin setup.
-- If you need Interactivity API from day 1, use the interactive template.
-
-Read:
-- `references/creating-new-blocks.md`
-
-After scaffolding:
-
-1. Re-run the block list script and confirm the new block root.
-2. Continue with the remaining steps (model choice, metadata, registration, serialization).
-
-### 2) Ensure apiVersion 3 (WordPress 6.9+)
-
-WordPress 6.9 enforces `apiVersion: 3` in the block.json schema. Blocks with apiVersion 2 or lower trigger console warnings when `SCRIPT_DEBUG` is enabled.
-
-**Why this matters:**
-- WordPress 7.0 will run the post editor in an iframe regardless of block apiVersion.
-- apiVersion 3 ensures your block works correctly inside the iframed editor (style isolation, viewport units, media queries).
-
-**Migration:** Changing from version 2 to 3 is usually as simple as updating the `apiVersion` field in `block.json`. However:
-- Test in a local environment with the iframe editor enabled.
-- Ensure any style handles are included in `block.json` (styles missing from the iframe won't apply).
-- Third-party scripts attached to a specific `window` may have scoping issues.
-
-Read:
-- `references/block-json.md` (apiVersion and schema details)
-
-### 3) Pick the right block model
-
-- **Static block** (markup saved into post content): implement `save()`; keep attributes serialization stable.
-- **Dynamic block** (server-rendered): use `render` in `block.json` (or `render_callback` in PHP) and keep `save()` minimal or `null`.
-- **Interactive frontend behavior**:
-  - Prefer `viewScriptModule` for modern module-based view scripts where supported.
-  - If you're working primarily on `data-wp-*` directives or stores, also use `wp-interactivity-api`.
-
-### 4) Update `block.json` safely
-
-Make changes in the block’s `block.json`, then confirm registration matches metadata.
-
-For field-by-field guidance, read:
-- `references/block-json.md`
-
-Common pitfalls:
-
-- changing `name` breaks compatibility (treat it as stable API)
-- changing saved markup without adding `deprecated` causes “Invalid block”
-- adding attributes without defining source/serialization correctly causes “attribute not saving”
-
-### 5) Register the block (server-side preferred)
-
-Prefer PHP registration using metadata, especially when:
-
-- you need dynamic rendering
-- you need translations (`wp_set_script_translations`)
-- you need conditional asset loading
-
-Read and apply:
-- `references/registration.md`
-
-### 6) Implement edit/save/render patterns
-
-Follow wrapper attribute best practices:
-
-- Editor: `useBlockProps()`
-- Static save: `useBlockProps.save()`
-- Dynamic render (PHP): `get_block_wrapper_attributes()`
-
-Read:
-- `references/supports-and-wrappers.md`
-- `references/dynamic-rendering.md` (if dynamic)
-
-### 7) Inner blocks (block composition)
-
-If your block is a “container” that nests other blocks, treat Inner Blocks as a first-class feature:
-
-- Use `useInnerBlocksProps()` to integrate inner blocks with wrapper props.
-- Keep migrations in mind if you change inner markup.
-
-Read:
-- `references/inner-blocks.md`
-
-### 8) Attributes and serialization
-
-Before changing attributes:
-
-- confirm where the attribute value lives (comment delimiter vs HTML vs context)
-- avoid the deprecated `meta` attribute source
-
-Read:
-- `references/attributes-and-serialization.md`
-
-### 9) Migrations and deprecations (avoid "Invalid block")
-
-If you change saved markup or attributes:
-
-1. Add a `deprecated` entry (newest → oldest).
-2. Provide `save` for old versions and an optional `migrate` to normalize attributes.
-
-Read:
-- `references/deprecations.md`
-
-### 10) Tooling and verification commands
-
-Prefer whatever the repo already uses:
-
-- `@wordpress/scripts` (common) → run existing npm scripts
-- `wp-env` (common) → use for local WP + E2E
-
-Read:
-- `references/tooling-and-testing.md`
-
-## Verification
-
-- Block appears in inserter and inserts successfully.
-- Saving + reloading does not create “Invalid block”.
-- Frontend output matches expectations (static: saved markup; dynamic: server output).
-- Assets load where expected (editor vs frontend).
-- Run the repo’s lint/build/tests that triage recommends.
-
-## Failure modes / debugging
-
-If something fails, start here:
-
-- `references/debugging.md` (common failures + fastest checks)
-- `references/attributes-and-serialization.md` (attributes not saving)
-- `references/deprecations.md` (invalid block after change)
-
-## Escalation
-
-If you’re uncertain about upstream behavior/version support, consult canonical docs first:
-
-- WordPress Developer Resources (Block Editor Handbook, Theme Handbook, Plugin Handbook)
-- Gutenberg repo docs for bleeding-edge behaviors

package/.github/skills/wp-block-development/references/attributes-and-serialization.md

@@ -1,22 +0,0 @@
-# Attributes and serialization
-
-Use this file when attributes aren’t saving, content becomes “Invalid block”, or you’re changing markup.
-
-## How attributes persist
-
-Attributes can come from:
-
-- the comment delimiter JSON (common and stable)
-- the block’s saved HTML (from tags/attributes)
-- context
-
-Read the canonical guide for supported `source`/`selector`/`attribute` patterns:
-
-- https://developer.wordpress.org/block-editor/reference-guides/block-api/block-attributes/
-
-## Common pitfalls
-
-- Changing saved HTML without a `deprecated` version breaks existing posts.
-- Using the `meta` attribute source (deprecated) causes long-term pain; avoid it.
-- Choosing brittle selectors leads to attributes “not found” when markup changes slightly.
-

package/.github/skills/wp-block-development/references/block-json.md

@@ -1,49 +0,0 @@
-# `block.json` (metadata) guidance
-
-Use this file when you’re editing `block.json` fields or choosing between script/styles fields.
-
-## Practical rules
-
-- Treat `name` as stable API (renaming breaks existing content).
-- Prefer adding new functionality without changing saved markup; if markup must change, add a `deprecated` version.
-- Keep assets scoped: editor assets should not ship to frontend unless needed.
-
-## API version + schema
-
-**WordPress 6.9+ requires apiVersion 3.** The block.json schema now only validates blocks with `apiVersion: 3`. Older versions (1 or 2) trigger console warnings when `SCRIPT_DEBUG` is enabled.
-
-**Why apiVersion 3 matters:**
-- The post editor will be iframed if all registered blocks have apiVersion 3+.
-- WordPress 7.0 will always use the iframe editor regardless of apiVersion.
-- Benefits: style isolation (admin CSS won't affect editor content), correct viewport units (vw, vh), native media queries.
-
-**Migration checklist:**
-1. Update `apiVersion` to `3` in block.json.
-2. Ensure all style handles are declared in block.json (styles not included won't load in the iframe).
-3. Test blocks that rely on third-party scripts (window scoping may differ).
-4. Add a `$schema` to improve editor tooling and validation.
-
-References:
-
-- Block metadata: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
-- Block API versions: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/
-- Iframe migration guide: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-api-versions/block-migration-for-iframe-editor-compatibility/
-- Block schema index: https://schemas.wp.org/
-
-## Modern asset fields to know
-
-This is not a full schema; it’s a “what matters in practice” list:
-
-- `editorScript` / `editorStyle`: editor-only assets.
-- `script` / `style`: shared assets.
-- `viewScript` / `viewStyle`: frontend view assets.
-- `viewScriptModule`: module-based frontend scripts (newer WP).
-- `render`: points to a PHP render file for dynamic blocks (newer WP).
-
-## Helpful upstream references
-
-- Block metadata reference (block.json):
-  - https://developer.wordpress.org/block-editor/reference-guides/block-api/block-metadata/
-- Block.json schema (editor tooling):
-  - https://schemas.wp.org/trunk/block.json
-

package/.github/skills/wp-block-development/references/creating-new-blocks.md

@@ -1,46 +0,0 @@
-# Creating new blocks (scaffolding)
-
-Use this file when you are creating a new block (or a new block plugin) from scratch.
-
-## Preferred path: `@wordpress/create-block`
-
-`@wordpress/create-block` scaffolds a modern block setup that tends to track current best practices.
-
-Typical options to decide up front:
-
-- TypeScript vs JavaScript
-- Static vs dynamic (`render.php` / server rendering)
-- Whether the block should be interactive on the frontend
-
-Canonical docs:
-
-- https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/
-
-## “Most up-to-date” interactive blocks
-
-For a modern interactive block, prefer the official Interactivity API template:
-
-- Template: `@wordpress/create-block-interactive-template`
-
-This template is designed to integrate:
-
-- Interactivity API directives (`data-wp-*`)
-- module-based view scripts (`viewScriptModule`)
-- server rendering (`render.php`)
-
-References:
-
-- https://developer.wordpress.org/block-editor/reference-guides/packages/packages-create-block/
-- https://make.wordpress.org/core/2024/03/04/a-first-look-at-the-interactivity-api-in-wordpress-6-5/
-
-## Manual fallback (when scaffolding is not available)
-
-If you cannot run `create-block` (no Node tooling or restricted network):
-
-1. Create a plugin or theme location that will register the block.
-2. Create a block folder with a valid `block.json`.
-3. Register via `register_block_type_from_metadata()` in PHP.
-4. Add editor JS and (optionally) frontend view assets.
-
-Then follow the rest of `wp-block-development` for metadata, registration, and serialization.
-

package/.github/skills/wp-block-development/references/debugging.md

@@ -1,36 +0,0 @@
-# Debugging quick routes
-
-## Block doesn’t appear in inserter
-
-- Confirm `block.json` `name` is valid and the block is registered.
-- Confirm build output exists and scripts are enqueued.
-- If using PHP registration, confirm `register_block_type_from_metadata()` runs (wrong hook/file not loaded is common).
-
-## “This block contains unexpected or invalid content”
-
-- You changed saved markup or attribute parsing.
-- Add `deprecated` versions and a migration path.
-- Reproduce with an old post containing the previous markup.
-
-## Attributes not saving
-
-- Confirm attribute definition matches actual markup.
-- If the value is in delimiter JSON, avoid brittle selectors.
-- Avoid `meta` attribute source (deprecated).
-
-## Console warnings about apiVersion (WordPress 6.9+)
-
-If you see "The block 'namespace/block' is registered with API version 2 or lower":
-
-- Update `apiVersion` to `3` in block.json.
-- This warning only appears when `SCRIPT_DEBUG` is true.
-- WordPress 7.0 will require apiVersion 3 for proper iframe editor support.
-
-## Styles not applying in editor (apiVersion 3 / iframe)
-
-If styles work on frontend but not in the editor:
-
-- Ensure style handles are declared in block.json (`editorStyle`, `style`).
-- Styles not included in block.json won't load inside the iframed editor.
-- Check for Dashicons or other dependencies that need explicit inclusion.
-

package/.github/skills/wp-block-development/references/deprecations.md

@@ -1,24 +0,0 @@
-# Deprecations and migrations
-
-Use this file when you must change saved markup or attribute shapes without breaking existing content.
-
-## `deprecated` basics
-
-Block deprecations are handled in JS block registration.
-
-- Add older implementations to `deprecated` (newest → oldest).
-- Each deprecated entry can include:
-  - `attributes`
-  - `supports`
-  - `save`
-  - `migrate`
-
-Upstream reference:
-
-- https://developer.wordpress.org/block-editor/reference-guides/block-api/block-deprecation/
-
-## Practical guardrails
-
-- Keep fixtures: store example content for each deprecated version.
-- When in doubt, add a migration path rather than silently changing selectors.
-

package/.github/skills/wp-block-development/references/dynamic-rendering.md

@@ -1,23 +0,0 @@
-# Dynamic blocks (server rendering)
-
-Use this file when converting a block to dynamic, or debugging frontend output mismatch.
-
-## Choose the mechanism
-
-- Prefer `render` in `block.json` (dynamic render file).
-- Alternative: pass `render_callback` when registering the block in PHP.
-
-## Wrapper attributes
-
-In PHP render output, always use:
-
-- `get_block_wrapper_attributes()`
-
-This preserves support-generated classes/styles.
-
-## Practical checklist
-
-- Ensure PHP file exists and is reachable from the block root.
-- Ensure registration runs on every request (not only in admin).
-- Keep `save()` empty or `null` for fully dynamic output, unless you intentionally save fallback markup.
-

package/.github/skills/wp-block-development/references/inner-blocks.md

@@ -1,25 +0,0 @@
-# Inner Blocks (nested blocks)
-
-Use this file when your block contains other blocks (container blocks).
-
-## Canonical references
-
-- Nested blocks guide: https://developer.wordpress.org/block-editor/how-to-guides/block-tutorial/nested-blocks-inner-blocks/
-- `@wordpress/block-editor` package: https://developer.wordpress.org/block-editor/reference-guides/packages/packages-block-editor/
-- Block supports: https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
-
-## Practical patterns
-
-- Editor:
-  - Use `useInnerBlocksProps( useBlockProps(), { ... } )` to combine wrapper props with inner blocks.
-  - Use templates/allowed blocks only when you have a clear UX reason (too strict is frustrating).
-- Save:
-  - Use `useInnerBlocksProps.save( useBlockProps.save(), { ... } )` if you need wrapper props.
-  - Output nested content via `<InnerBlocks.Content />` when appropriate.
-
-## Common pitfalls
-
-- Only one `InnerBlocks` should exist per block.
-- Changing the wrapper structure that contains inner blocks can invalidate existing content; consider deprecations/migrations.
-- If you need to constrain allowed blocks, prefer doing it intentionally and documenting why.
-

package/.github/skills/wp-block-development/references/registration.md

@@ -1,30 +0,0 @@
-# Registration patterns (PHP-first)
-
-Use this file when you need to register blocks robustly across repo types (plugin/theme/site).
-
-## Prefer metadata registration
-
-Prefer:
-
-- `register_block_type_from_metadata( $path_to_block_dir, $args = [] )`
-
-Why:
-
-- keeps metadata authoritative (`block.json`)
-- supports dynamic render (`render`) and other metadata-driven fields
-- enables cleaner asset handling
-
-Upstream reference:
-
-- https://developer.wordpress.org/reference/functions/register_block_type_from_metadata/
-
-## Where to register
-
-- Plugins: register on `init` in the main plugin bootstrap or a dedicated loader.
-- Themes: register on `init` (or `after_setup_theme` if you need theme supports first), but keep it predictable.
-
-## Dynamic render mapping
-
-If `block.json` includes `render`, ensure the file exists relative to the block root.
-Inside the render file, use `get_block_wrapper_attributes()` for wrapper attributes.
-