fix(phase6): Update WordPress 6.5+ standards and standardize text domains

## Critical Issues Fixed

### Issue #4: WordPress 6.5+ Block Rendering Standards
- **block-json.instructions.md**: Enhanced dynamic block rendering documentation
  - Added "WordPress 6.5+ File-based Rendering (RECOMMENDED)" section
  - Positioned `"render": "file:./render.php"` as PRIMARY method
  - Documented automatic variables ($attributes, $content, $block)
  - Added proper mustache placeholder example with {{namespace}} and {{slug}}
  - Created "Legacy PHP Callback" section for pre-6.5 compatibility
  - Added Version Compatibility Matrix (6.5+, 6.0-6.4, <6.0)
  - Clarified scaffold standard: Always use file-based rendering

### Issue #5: Text Domain Standardization
- **wpcs-php.instructions.md**: Standardized all text domain examples
  - Changed 'textdomain' to '{{textdomain}}' in all i18n examples (8 instances)
  - Changed 'lsx-theme' to '{{textdomain}}' in translation guidance (line 390)
  - Added explanatory note about placeholder vs production usage
  - Ensures AI agents copy correct mustache placeholders

## Changes Made

### block-json.instructions.md
- Lines 305-367: Complete rewrite of "Render Callback" section
- Added 3 subsections: Recommended, Legacy, Version Compatibility
- Enhanced render.php example with proper @var annotations
- Included WP_Block context usage example
- Clear deprecation warning for render_callback approach

### wpcs-php.instructions.md
- Lines 121-122: Updated wp_die() text domains
- Lines 297-300: Updated core i18n function examples
- Lines 307-308: Updated wp_localize_script() string examples
- Line 390: Updated translation guidance with placeholder explanation
- Line 295: Added note explaining {{textdomain}} placeholder convention

## Impact

### Before:
- Unclear if file-based rendering or PHP callbacks were preferred
- Text domain examples used inconsistent values ('textdomain', 'lsx-theme', 'plugin')
- AI agents might copy wrong text domain into scaffold templates

### After:
- Clear WordPress 6.5+ standard with file-based rendering as PRIMARY method
- All examples consistently use '{{textdomain}}' placeholder
- Explicit note explaining placeholder vs production usage
- Version compatibility matrix guides decision-making

## Validation

✅ File-based rendering positioned as WordPress 6.5+ standard
✅ All text domain examples now use {{textdomain}} placeholder
✅ Backward compatibility documented for legacy WordPress versions
✅ Clear guidance prevents text domain mistakes in scaffold

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: ashleyshaw

.github/instructions/block-json.instructions.md

@@ -304,34 +304,68 @@ The `block.json` file is the canonical way to register blocks in WordPress. This
 
 ## Render Callback (Dynamic Blocks)
 
-### PHP Rendering
+### WordPress 6.5+ File-based Rendering (RECOMMENDED)
+
+**This is the PRIMARY method** for dynamic blocks in WordPress 6.5+. Use `render` property in block.json:
 
 ```json
 {
   "render": "file:./render.php"
 }
 ```
 
+**render.php** receives these variables automatically:
+- `$attributes` - Block attributes array
+- `$content` - Block inner content (for dynamic InnerBlocks)
+- `$block` - WP_Block instance with context and metadata
+
 ```php
 <?php
 /**
- * Render callback for dynamic block
+ * Dynamic block rendering template
  *
- * @param array $attributes Block attributes
- * @param string $content Block content
- * @param WP_Block $block Block instance
+ * @package {{namespace}}
+ * @var array    $attributes Block attributes
+ * @var string   $content    Block inner content
+ * @var WP_Block $block      Block instance
  */
-function render_callback( $attributes, $content, $block ) {
-    $alignment = $attributes['alignment'] ?? 'left';
 
+$alignment = $attributes['alignment'] ?? 'left';
+$post_id = $block->context['postId'] ?? get_the_ID();
+
+?>
+<div class="wp-block-{{namespace}}-{{slug}}-card align<?php echo esc_attr( $alignment ); ?>">
+    <?php echo wp_kses_post( $content ); ?>
+</div>
+```
+
+### Legacy PHP Callback (WordPress < 6.5 - DEPRECATED)
+
+**Only use if you need to support WordPress versions before 6.5.** Register callback in PHP:
+
+```php
+register_block_type( 'namespace/block-name', array(
+    'render_callback' => 'namespace_render_block_callback',
+) );
+
+function namespace_render_block_callback( $attributes, $content, $block ) {
     return sprintf(
-        '<div class="wp-block-namespace-block align%s">%s</div>',
-        esc_attr( $alignment ),
+        '<div class="wp-block-namespace-block">%s</div>',
         wp_kses_post( $content )
     );
 }
 ```
 
+### Version Compatibility Matrix
+
+| WordPress Version | Render Method | Support Status |
+|-------------------|---------------|----------------|
+| **6.5+** | `"render": "file:./render.php"` | ✅ Recommended |
+| **6.0 - 6.4** | `render_callback` in PHP | ⚠️ Legacy support |
+| **< 6.0** | `render_callback` in PHP | ❌ Not scaffold target |
+
+**Scaffold Standard:** Always use `"render": "file:./render.php"` in block.json. This is cleaner, more maintainable, and aligns with WordPress core direction.
+
 ### Dynamic Block Best Practices
 
 - Validate and sanitize attributes

.github/instructions/wpcs-php.instructions.md

@@ -118,8 +118,8 @@ if ( WP_DEBUG ) {
 
 // User-friendly error messages
 wp_die(
-    __( 'Something went wrong. Please try again later.', 'textdomain' ),
-    __( 'Error', 'textdomain' ),
+    __( 'Something went wrong. Please try again later.', '{{textdomain}}' ),
+    __( 'Error', '{{textdomain}}' ),
     array( 'response' => 500 )
 );
 ```
@@ -292,20 +292,22 @@ function my_plugin_render_custom_block( $attributes, $content, $block ) {
 
 ### Internationalization (i18n) Examples
 
+> **Note:** In examples, `'{{textdomain}}'` represents your plugin's actual text domain placeholder. When writing code for the scaffold, always use `'{{textdomain}}'` so the generator can replace it. In production plugin code, use your actual text domain (e.g., `'my-plugin'`).
+
 ```php
 // Use proper text domain consistently
-__( 'Text to translate', 'textdomain' );
-_e( 'Text to echo', 'textdomain' );
-_x( 'Text', 'Context for translators', 'textdomain' );
-_n( 'Singular', 'Plural', $count, 'textdomain' );
+__( 'Text to translate', '{{textdomain}}' );
+_e( 'Text to echo', '{{textdomain}}' );
+_x( 'Text', 'Context for translators', '{{textdomain}}' );
+_n( 'Singular', 'Plural', $count, '{{textdomain}}' );
 
 // For JavaScript strings
 wp_localize_script( 'my-script', 'myL10n', array(
     'ajaxurl' => admin_url( 'admin-ajax.php' ),
     'nonce' => wp_create_nonce( 'my_ajax_nonce' ),
     'strings' => array(
-        'loading' => __( 'Loading...', 'textdomain' ),
-        'error' => __( 'An error occurred', 'textdomain' ),
+        'loading' => __( 'Loading...', '{{textdomain}}' ),
+        'error' => __( 'An error occurred', '{{textdomain}}' ),
     )
 ) );
 ```
@@ -387,7 +389,7 @@ function my_plugin_rest_permission_check() {
 
 ## Translation & Internationalization
 
-- Use correct text domain for all translations: `__('text', 'lsx-theme')`.
+- Use correct text domain for all translations: `__( 'text', '{{textdomain}}' )` (use your plugin's actual text domain, represented here as `{{textdomain}}` placeholder).
 - Ensure all user-visible strings are translatable.
 - Use proper escaping functions with translations: `esc_html__()`, `esc_attr__()`.
 - For HTML with translations, use `esc_html_e()` or appropriate alternatives.