Merge branch 'main' into fix/break-circular-references

Signed-off-by: Ash Shaw <[email protected]>

Author: ashleyshaw

README.md

@@ -30,19 +30,86 @@ A multi-block WordPress plugin scaffold with support for:
 - Node.js 18+
 - [Secure Custom Fields](https://wordpress.org/plugins/secure-custom-fields/) plugin
 
-## Installation
+## Using This Scaffold
 
-1. Clone this repository to your WordPress plugins directory:
+This scaffold can be used in two ways:
+
+### Option 1: Template Mode (Modify Scaffold Directly)
+
+Use the scaffold as a template repository and process it in-place:
+
+1. **Create from template** on GitHub or clone the repository
+2. **Process the scaffold** with your plugin details:
+
+   ```bash
+   node scripts/generate-plugin.js --in-place
+   ```
+
+   This will:
+   - Prompt for confirmation (to prevent accidental overwrites)
+   - Replace all `{{mustache}}` variables in files
+   - Update file and directory names with your slug
+   - Process the scaffold directory directly (no separate output)
+
+3. **Install dependencies and build**:
+
+   ```bash
+   npm install
+   composer install
+   npm run build
+   ```
+
+4. **Commit your customized plugin** to your repository
+
+**⚠️ Important**: Template mode modifies files in-place. Always use on a fresh clone or when you're certain you want to replace the scaffold content.
+
+### Option 2: Generator Mode (Create New Plugin)
+
+Generate a new plugin in a separate output directory:
+
+1. **Clone or download** this scaffold repository
+2. **Run the generator** to create a new plugin:
+
+   ```bash
+   node scripts/generate-plugin.js
+   ```
+
+   Or with a configuration file:
+
+   ```bash
+   node scripts/generate-plugin.js --config my-plugin-config.json
+   ```
+
+3. **Find your generated plugin** in:
+   - `generated-plugins/<your-slug>/` - Complete plugin ready to use
+
+4. **Move to WordPress plugins directory**:
+
+   ```bash
+   mv generated-plugins/my-plugin/ /path/to/wordpress/wp-content/plugins/
+   cd /path/to/wordpress/wp-content/plugins/my-plugin/
+   npm install
+   composer install
+   npm run build
+   ```
+
+**Benefits**: Keeps the scaffold repository clean and can generate multiple plugins.
+
+See [docs/GENERATE-PLUGIN.md](docs/GENERATE-PLUGIN.md) for detailed usage instructions, configuration options, and examples.
+
+## Installation (For Already-Generated Plugins)
+
+If you've already processed the scaffold or received a generated plugin:
+
+1. Ensure you're in your WordPress plugins directory:
 
    ```bash
-   cd wp-content/plugins/
-   git clone https://github.com/{{author}}/{{slug}}.git
+   cd wp-content/plugins/your-plugin-name
    ```
 
 2. Install dependencies:
 
    ```bash
-   cd {{slug}}
    npm install
    composer install
    ```

docs/GENERATE-PLUGIN.md

@@ -253,9 +253,147 @@ JSON configuration files (`package.json`, `composer.json`, `block.json`) use pla
 }
 ```
 
+## Operational Modes
+
+### Template Mode vs Generator Mode
+
+The scaffold supports two operational modes:
+
+#### Template Mode (`--in-place`)
+
+**Use when**: You want to use the scaffold as a starting point for your plugin.
+
+- Processes files directly in the scaffold directory
+- Replaces all mustache variables in-place
+- Renames files and directories to match your slug
+- **⚠️ Destructive**: Modifies the scaffold permanently
+- Includes confirmation prompt to prevent accidents
+- Best for GitHub template repositories
+
+**Command:**
+
+```bash
+node scripts/generate-plugin.js --in-place
+```
+
+**Workflow:**
+
+1. Clone/fork the scaffold repository
+2. Run generator with `--in-place` flag
+3. Confirm the operation (y/N prompt)
+4. Scaffold is processed in-place
+5. Install dependencies and build
+6. Commit your customized plugin
+
+#### Generator Mode (Default)
+
+**Use when**: You want to create multiple plugins or keep the scaffold clean.
+
+- Creates new plugin in `generated-plugins/<slug>/`
+- Leaves scaffold directory unchanged
+- Can generate multiple plugins
+- Safe for repeated use
+- Best for maintaining the scaffold as a tool
+
+**Command:**
+
+```bash
+node scripts/generate-plugin.js
+```
+
+**Workflow:**
+
+1. Clone the scaffold repository once
+2. Run generator (no `--in-place` flag)
+3. Generated plugin appears in `generated-plugins/<slug>/`
+4. Move to WordPress plugins directory
+5. Install dependencies and build
+6. Generate another plugin anytime
+
 ## Generation Methods
 
-### Method 1: AI-Assisted Generation (Recommended)
+### Method 1: Template Mode (In-Place Processing)
+
+Use the scaffold as a GitHub template and process it directly:
+
+```bash
+# Interactive mode with confirmation
+node scripts/generate-plugin.js --in-place
+
+# With configuration file
+node scripts/generate-plugin.js --in-place --config plugin-config.json
+
+# Skip confirmation (automation only - use with caution)
+node scripts/generate-plugin.js --in-place --yes
+```
+
+**Process:**
+
+1. Prompts for plugin configuration (or reads from config file)
+2. **Displays confirmation warning** about in-place modification
+3. Waits for user confirmation (y/N)
+4. Processes all files in the scaffold directory
+5. Replaces mustache variables throughout
+6. Renames files/directories to match your slug
+7. Reports completion with next steps
+
+**⚠️ Important Notes:**
+
+- Always use on a fresh clone or template repository
+- Cannot be undone without version control
+- Confirmation prompt defaults to "No" for safety
+- Use `--yes` flag only in automated workflows you trust
+
+### Method 2: Generator Mode (Default)
+
+Create a new plugin in a separate output directory:
+
+```bash
+# Interactive mode - prompts for all configuration
+node scripts/generate-plugin.js
+
+# With configuration file
+node scripts/generate-plugin.js --config plugin-config.json
+
+# With inline arguments
+node scripts/generate-plugin.js \
+  --slug tour-operator \
+  --name "Tour Operator" \
+  --description "Tour booking and display plugin" \
+  --author "LightSpeed" \
+  --author-uri "https://developer.lsdev.biz"
+```
+
+**Process:**
+
+1. Reads configuration from prompts, file, or arguments
+2. Validates configuration against schema
+3. Creates `generated-plugins/<slug>/` directory
+4. Copies and processes all scaffold files
+5. Replaces mustache variables
+6. Renames files/directories
+7. Leaves scaffold directory unchanged
+
+**Output Location:**
+
+```bash
+generated-plugins/
+└── tour-operator/        # Your generated plugin
+    ├── tour-operator.php
+    ├── package.json
+    ├── composer.json
+    └── ... (complete plugin structure)
+```
+
+**Best for:**
+
+- Creating multiple plugins from the same scaffold
+- Keeping scaffold repository clean
+- Testing different configurations
+- CI/CD pipelines
+- Advanced users comfortable with CLI tools
+
+### Method 3: AI-Assisted Generation (Recommended)
 
 Use the workspace prompt for an interactive, guided experience:
 
@@ -270,7 +408,7 @@ Use the workspace prompt for an interactive, guided experience:
 3. Collects all required information interactively
 4. Validates input at each stage
 5. Confirms configuration before generation
-6. Generates the complete plugin structure
+6. Generates the complete plugin structure (uses generator mode by default)
 7. Provides post-generation setup instructions
 
 **Benefits:**
@@ -280,6 +418,7 @@ Use the workspace prompt for an interactive, guided experience:
 - Validation at each step
 - Smart defaults for common configurations
 - Best for first-time users
+- Can use either template or generator mode
 
 **Stages:**
 
@@ -291,7 +430,7 @@ Use the workspace prompt for an interactive, guided experience:
 6. **Templates & Patterns** - Template and pattern selection
 7. **Version & Compatibility** - WordPress/PHP requirements
 
-### Method 2: Agent-Based Generation
+### Method 4: Agent-Based Generation
 
 Request the scaffold generator agent directly:
 
@@ -327,8 +466,9 @@ node scripts/generate-plugin.js
 # Prompts for all required information
 node scripts/generate-plugin.js
 ```
+### Method 4: Agent-Based Generation
 
-**Direct Mode:**
+Request the scaffold generator agent directly:
 
 ```bash
 # Provide all values via arguments
@@ -354,13 +494,24 @@ node scripts/validate-plugin-config.js my-plugin.json
 
 # Generate plugin
 node scripts/generate-plugin.js --config my-plugin.json
+```text
+Generate a new multi-block plugin from scaffold
 ```
 
-**Best for:**
+Or be more specific:
 
-- Automation and CI/CD pipelines
-- Batch plugin generation
-- Advanced users comfortable with CLI tools
+```text
+Create a tour operator plugin with tours CPT, destination taxonomy, and booking fields
+```
+
+**Features:**
+
+- Conversational interface
+- Can infer requirements from description
+- Validates configuration automatically
+- Follows agent specification in `.github/agents/generate-plugin.agent.md`
+- Best for experienced users who know their requirements
+- Can use either template or generator mode
 
 ## Post-Generation Workflow
 
@@ -373,7 +524,7 @@ tree -L 2
 
 Expected structure:
 
-```
+```text
 tour-operator/
 ├── tour-operator.php         # Main plugin file (slug-based name)
 ├── package.json              # Node dependencies
@@ -386,7 +537,7 @@ tour-operator/
 │   └── scss/                 # Stylesheets
 ├── templates/                # Block templates
 ├── patterns/                 # Block patterns
-├── parts/                    # Template parts
+├── template-parts/           # Template parts
 └── scf-json/                 # SCF field groups
 ```
 
@@ -856,6 +1007,12 @@ For complete schema details, see:
 - **[../.github/instructions/generate-plugin.instructions.md](../.github/instructions/generate-plugin.instructions.md)** - Mustache template rules
 - **[../.github/instructions/schema-files.instructions.md](../.github/instructions/schema-files.instructions.md)** - Schema file standards
 - **[../.github/instructions/scf-fields.instructions.md](../.github/instructions/scf-fields.instructions.md)** - SCF field types
+- [Generator Instructions](.github/instructions/generate-plugin.instructions.md) - Rules for using mustache values
+- [Plugin Generator Agent](.github/agents/generate-plugin.agent.md) - Agent specification
+- [Generation Prompt](.github/prompts/generate-plugin.prompt.md) - Interactive prompt template
+- [SCF Fields Reference](.github/instructions/scf-fields.instructions.md) - Field types and usage
+- [Build Process](BUILD-PROCESS.md) - Detailed build documentation
+- [API Reference](API-REFERENCE.md) - PHP and JavaScript APIs
 
 ## Support
 

inc/class-block-bindings.php

@@ -1,4 +1,6 @@
 <?php
+namespace {{namespace|lowerCase}}\classes;
+
 /**
  * Block Bindings Registration.
  *
@@ -17,6 +19,13 @@
  */
 class Block_Bindings {
 
+	/**
+	 * Binding source name.
+	 *
+	 * @var string
+	 */
+	const SOURCE = '{{namespace}}/fields';
+
 	/**
 	 * Constructor.
 	 */

inc/class-block-templates.php

@@ -1,4 +1,6 @@
 <?php
+namespace {{namespace|lowerCase}}\classes;
+
 /**
  * Block Templates Registration.
  *