### Setup Playwright Environment

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Testing-Guide.md

Install dependencies, start the WordPress environment, and prepare Playwright browsers.

```bash
# Install dependencies
npm install

# Start the WordPress environment
npm run play:up

# Build the plugin
npm run build

# Install Playwright browsers
npx playwright install
```

--------------------------------

### Run Development Server

Source: https://github.com/brainstormforce/sureforms-public/blob/master/modules/gutenberg/readme.md

Commands to install dependencies and start the development process after switching to the required Node version.

```bash
npm i
```

```bash
npm run start
```

--------------------------------

### PHP Initialization Entry Points

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Illustrates the PHP initialization flow, starting from the main plugin file and progressing through the plugin loader for autoloader registration and hook setup.

```php
sureforms.php (defines constants)
  → plugin-loader.php (Plugin_Loader class)
    → Autoloader registration
    → WordPress hooks: plugins_loaded, init, admin_init
```

--------------------------------

### Local Development Environment Setup

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

Example configuration for a local development environment, including the URL, username, and password for accessing the WordPress admin area.

```bash
# If using Local by Flywheel or similar
http://localhost:10003/wp-admin/
Username: admin
Password: admin
```

--------------------------------

### Usage Examples

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/WordPress-Hooks-Reference.md

Practical examples demonstrating how to use SureForms hooks.

```APIDOC
## Usage Examples

Here are practical examples of how to utilize SureForms hooks in your WordPress development.

### Adding a Custom REST Endpoint

Use the `srfm_rest_api_endpoints` filter to register a new REST API endpoint.

```php
add_filter( 'srfm_rest_api_endpoints', function( $endpoints ) {
    $endpoints['my-custom/data'] = [
        'methods'             => 'GET',
        'callback'            => 'my_custom_callback',
        'permission_callback' => [ \SRFM\Inc\Helper::class, 'get_items_permissions_check' ],
    ];
    return $endpoints;
} );
```

### Modifying Form Data Before Processing

Leverage the `srfm_form_submit_data` filter to alter form submission data prior to processing.

```php
add_filter( 'srfm_form_submit_data', function( $data, $form_id ) {
    // Add custom processing here
    $data['custom_field'] = 'custom_value';
    return $data;
}, 10, 2 );
```

### Running Code After Submission

Utilize the `srfm_form_submit` action hook to execute custom code after a form has been successfully submitted.

```php
add_action( 'srfm_form_submit', function( $entry_id, $form_id, $form_data ) {
    // Example: Send data to an external service or trigger automation
    // error_log( "Form submitted: Entry ID " . $entry_id . " for Form ID " . $form_id );
}, 10, 3 );
```
```

--------------------------------

### Install SureForms Locally

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/README.md

Clone the repositories for SureForms Free and Pro, install dependencies, and build the project locally.

```bash
cd /path/to/wordpress/wp-content/plugins
git clone https://github.com/brainstormforce/sureforms.git
git clone https://github.com/brainstormforce/sureforms-pro.git
cd sureforms && npm install && npm run build
cd ../sureforms-pro && npm install && npm run build
```

--------------------------------

### Install Dependencies

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Contributing-Guide.md

Install required PHP and Node.js dependencies.

```bash
composer install
npm install
```

--------------------------------

### Start Local WordPress Environment with wp-env

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Launch a Docker-based local WordPress environment using the `npm run play:up` command. This provides a convenient setup for testing and development.

```bash
npm run play:up
```

--------------------------------

### Verify Pro Plugin Installation

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Ensure both the free and pro versions of the plugin are installed.

```bash
wp plugin list | grep sureforms
# Ensure both sureforms AND sureforms-pro are installed
```

--------------------------------

### Query Monitor Installation

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

Install the Query Monitor plugin via WP-CLI.

```bash
wp plugin install query-monitor --activate
```

--------------------------------

### Start Development Server

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Starts the Webpack development server in watch mode for automatic rebuilding and hot reloading.

```bash
npm start
```

--------------------------------

### Install and Run Markdownlint CLI

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Install the markdownlint-cli globally and then run it on all markdown files in the internal-docs directory to check for syntax errors.

```bash
# Install markdownlint
npm install -g markdownlint-cli

# Lint all docs
cd internal-docs/
markdownlint *.md
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Getting-Started.md

Install required PHP and Node.js dependencies using Composer and npm.

```bash
composer install    # PHP dependencies
npm install         # Node dependencies
```

--------------------------------

### Start Development Server

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Contributing-Guide.md

Launch the wp-scripts development server with hot reloading.

```bash
npm start        # Start wp-scripts dev server (hot reload)
```

--------------------------------

### Install WordPress and SureForms Dependencies

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

Clone the SureForms repositories and install both npm and Composer dependencies for both the free and pro versions. Ensure you are in the correct directory before running commands.

```bash
# Clone repositories (if not already)
cd /path/to/wp-content/plugins/
git clone https://github.com/brainstormforce/sureforms.git
git clone https://github.com/brainstormforce/sureforms-pro.git

# Install dependencies - SureForms Free
cd sureforms/
npm install
composer install

# Build assets
npm run build

# Install dependencies - SureForms Pro
cd ../sureforms-pro/
npm install
composer install
npm run build
```

--------------------------------

### New Feature Documentation Template - PHP Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

A template for documenting new features, including sections for overview, use cases, how to use, configuration, API reference, examples, troubleshooting, and related information. Includes a placeholder for PHP code examples.

```php
// Code example
```

```php
// Code here
```

--------------------------------

### Install Query Monitor

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Command to install and activate the Query Monitor plugin for debugging slow queries.

```bash
wp plugin install query-monitor --activate
# View entries page, check QM for slow queries
```

--------------------------------

### Example User Agent String

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/glossary.md

Sample string identifying a browser and operating system.

```text
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36
```

--------------------------------

### Bad PHP Code Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Avoid vague and generic code examples. Such examples lack specificity and do not effectively illustrate functionality.

```php
$data = SomeClass::get_stuff($args);
```

--------------------------------

### Form Structure Examples

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/ui-and-copy.md

Examples of logical field ordering for contact and order forms.

```text
1. Name
2. Email
3. Subject
4. Message
5. [Submit]
```

```text
1. Name
2. Email
3. Product selection
4. Quantity
5. Payment details
6. [Complete Purchase]
```

--------------------------------

### Initialize Local WordPress Development Environment

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/faq.md

Standard WP-CLI commands to download, configure, and install a local WordPress site for SureForms development.

```bash
# Use Local by Flywheel or similar
# Or manual setup:
cd ~/Sites/my-wordpress-site
wp core download
wp core config --dbname=sureforms_dev --dbuser=root
wp core install --url=http://localhost:8080 --title="Dev Site"
wp plugin install sureforms --activate
```

--------------------------------

### Good PHP Code Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Use specific and realistic examples for code snippets. Ensure clarity and provide context for the data being retrieved.

```php
$entries = Entries::get_all([
  'where' => [
    ['key' => 'form_id', 'value' => 123, 'compare' => '=']
  ],
  'limit' => 20
]);
```

--------------------------------

### Install PHP Dependencies

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Testing-Guide.md

Install required PHP packages via Composer.

```bash
composer install
```

--------------------------------

### PHP Code Example with Comment

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Include comments in PHP code examples to explain the functionality. This improves readability and understanding.

```php
// Good: Explain what code does
$entries = Entries::get_all([
  'where' => [
    ['key' => 'status', 'value' => 'published', 'compare' => '=']
  ]
]);
```

--------------------------------

### Install WP-CLI Globally

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Installs the WP-CLI tool globally on your system. This is optional but recommended for managing WordPress from the command line.

```bash
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
sudo mv wp-cli.phar /usr/local/bin/wp
```

--------------------------------

### Install and Run Markdown Link Check

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Install the markdown-link-check package globally and use it to verify that all links within the markdown files in the internal-docs directory are valid.

```bash
# Install markdown-link-check
npm install -g markdown-link-check

# Check links
markdown-link-check internal-docs/*.md
```

--------------------------------

### Install Volta Node.js Manager

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Getting-Started.md

Use this command to install Volta, which manages Node.js versions automatically based on the project configuration.

```bash
curl https://get.volta.sh | bash
```

--------------------------------

### Bash Command with Output Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

When demonstrating shell commands, include the expected output if it is helpful for understanding the command's effect.

```bash
wp plugin list --status=active
# Output:
# sureforms        active
# sureforms-pro    active
```

--------------------------------

### Paginate Database Queries

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

PHP example for implementing pagination in entry retrieval.

```php
$entries = Entries::get_all([
  'limit' => 20,
  'offset' => ($page - 1) * 20
]);
```

--------------------------------

### Database Version Storage Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/04-backend/DATABASE-SCHEMA.md

Illustrates how table versions are stored in the WordPress options table.

```text
Option Name: srfm_entries_version
Option Value: 1 (integer)

Option Name: srfm_payments_version
Option Value: 1 (integer)
```

--------------------------------

### Install and Run Aspell for Spell Checking

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Install aspell using a package manager (brew for macOS, apt for Linux) and then use it to check the spelling of a specific markdown file.

```bash
# Install aspell
brew install aspell  # macOS
apt install aspell   # Linux

# Check spelling
aspell check internal-docs/README.md
```

--------------------------------

### PHP Unit Test Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Testing-Guide.md

Example of a PHP unit test class extending WP_UnitTestCase.

```php
class Test_My_Feature extends WP_UnitTestCase {
    public function test_feature_works() {
        // Arrange
        $form_id = $this->factory->post->create([
            'post_type' => 'sureforms_form',
        ]);

        // Act
        $result = some_function($form_id);

        // Assert
        $this->assertEquals('expected', $result);
    }
}
```

--------------------------------

### Install PHP and JavaScript Dependencies

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Install project dependencies using Composer for PHP and npm for JavaScript. This step ensures all necessary libraries and packages are available for development.

```bash
# PHP dependencies
composer install

# JavaScript dependencies
npm install
```

--------------------------------

### GET /initiate-auth

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/AI-Form-Builder.md

Initiates the authentication process by generating a URL for the billing portal.

```APIDOC
## GET /initiate-auth

### Description
Generates an authentication URL to redirect the user to the billing portal for SureForms AI access.

### Method
GET

### Endpoint
/initiate-auth

### Response
#### Success Response (200)
- **auth_url** (string) - The URL to the billing portal for authentication.
```

--------------------------------

### Manage Docker-based WordPress Environment

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Getting-Started.md

Commands to start, stop, and clean the local Docker environment.

```bash
npm run play:up     # Start WordPress + MySQL containers
```

```bash
npm run play:stop   # Stop containers
```

```bash
npm run env:clean   # Reset all data
```

--------------------------------

### Activate SureForms Plugins via WP-CLI

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

Activate the SureForms free and pro plugins using the WP-CLI command. This is a quick way to verify installation after cloning and installing dependencies.

```bash
# In WordPress admin
wp plugin activate sureforms sureforms-pro
wp plugin list | grep sureforms
```

--------------------------------

### Implement Upgrade Logic for New Version

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/04-backend/DATABASE-SCHEMA.md

Example of implementing custom migration logic within the upgrade method for a specific version.

```php
public function upgrade($old_version) {
    global $wpdb;

    if ($old_version < 2) {
        // Additional migration logic beyond column addition
        $wpdb->query("UPDATE {$this->table_name} SET new_column = 'default_value'");
    }
}
```

--------------------------------

### Install and Enable Redis Object Cache

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Install the Redis Cache plugin and enable it using the WordPress CLI. Object caching can significantly improve site performance by reducing database load.

```bash
wp plugin install redis-cache --activate
wp redis enable
```

--------------------------------

### Conventional Commits Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Illustrates the standard format for commit messages, including type, scope, and description.

```text
feat: add date picker field block
fix: resolve form submission nonce error
docs: update API endpoint documentation
style: format code with PHPCS
refactor: simplify validation logic
test: add unit tests for Helper class
chore: update dependencies
```

--------------------------------

### Implement Rate Limiting Pattern

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/apis.md

Example pattern for implementing rate limiting using WordPress transients.

```php
// Example pattern (not in core)
$key = 'form_submit_' . $user_ip;
$attempts = get_transient($key) ?: 0;

if ($attempts >= 5) {
    wp_send_json_error('Too many submissions', 429);
}

set_transient($key, $attempts + 1, 15 * MINUTE_IN_SECONDS);
```

--------------------------------

### Enqueue Frontend Styles

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Frontend-Assets.md

Example of enqueuing frontend CSS using the project's version constant for cache busting.

```php
wp_enqueue_style(
    'srfm-frontend',
    SRFM_URL . 'assets/css/minified/frontend.min.css',
    [],
    SRFM_VER
);
```

--------------------------------

### Manage Hook Priority

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/04-backend/HOOKS-REFERENCE.md

Examples of setting execution order for SureForms hooks using priority integers.

```php
// Execute before SureForms processes submission
add_action('srfm_before_submission', 'my_function', 5);

// Execute at default time
add_action('srfm_before_submission', 'my_function', 10);

// Execute after SureForms processes submission
add_action('srfm_before_submission', 'my_function', 15);
```

--------------------------------

### Clone SureForms Repository

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/01-getting-started/GETTING-STARTED.md

Use this command to clone the SureForms repository to your local machine. Navigate into the cloned directory to proceed with setup.

```bash
git clone https://github.com/brainstormforce/sureforms.git
cd sureforms
```

--------------------------------

### Updating Migration Guide for Deprecation

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

In the README.md, detail breaking changes due to deprecation. Specify what changed, the required action, and provide code examples for the old and new methods.

```markdown
## Upgrading from 2.4.x to 2.5.0

### Breaking Changes

**Old Feature Deprecated:**
- **What changed:** `old_function()` is now deprecated
- **Action required:** Replace with `new_function()`
- **Code example:**
  ```php
  // Old (deprecated)
  old_function($data);

  // New (recommended)
  new_function($data);
  ```
```

--------------------------------

### Initialize SureForms Development Environment

Source: https://github.com/brainstormforce/sureforms-public/blob/master/modules/gutenberg/readme.md

Commands to resolve dependency issues and prepare the build environment.

```bash
npm install --legacy-peer-deps
```

```bash
npm install --force
```

```bash
npm install
```

```bash
npm run build
```

```bash
npm start
```

--------------------------------

### Commit Message Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

A concrete example of a feature commit message.

```text
feat(blocks): add star rating field

- Add new star-rating block
- Implement frontend JavaScript
- Add sanitization and validation
- Update docs with new field type

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

--------------------------------

### GET sureforms/get-shortcode

Source: https://github.com/brainstormforce/sureforms-public/blob/master/inc/abilities/ABILITIES.md

Get the shortcode and block markup for embedding a form.

```APIDOC
## GET sureforms/get-shortcode

### Description
Get the shortcode and block markup for embedding a form.

### Parameters
#### Query Parameters
- **form_id** (integer) - Required - Form ID

### Response
#### Success Response (200)
- **form_id** (integer) - Form ID
- **shortcode** (string) - Form shortcode
- **block_markup** (string) - Block markup for embedding

#### Response Example
{
  "form_id": 123,
  "shortcode": "[sureforms id=\"123\"]",
  "block_markup": "<!-- wp:srfm/form {\"id\":123} /-->"
}
```

--------------------------------

### GET sureforms/get-form-stats

Source: https://github.com/brainstormforce/sureforms-public/blob/master/inc/abilities/ABILITIES.md

Get submission statistics for a specific form or all forms.

```APIDOC
## GET sureforms/get-form-stats

### Description
Get submission statistics for a specific form or all forms.

### Parameters
#### Query Parameters
- **form_id** (integer) - Optional - Form ID (0 for all forms)

### Response
#### Success Response (200)
- **form_id** (integer) - Form ID
- **form_title** (string) - Form title
- **form_status** (string) - Form status
- **total_entries** (integer) - Total submissions
- **unread_count** (integer) - Unread submissions
- **read_count** (integer) - Read submissions
- **trash_count** (integer) - Trash submissions

#### Response Example
{
  "form_id": 123,
  "form_title": "Contact Form",
  "form_status": "publish",
  "total_entries": 42,
  "unread_count": 5,
  "read_count": 35,
  "trash_count": 2
}
```

--------------------------------

### Build the Plugin

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Getting-Started.md

Compile assets and minify files for production use.

```bash
npm run build       # Full production build (JS + SASS + minify)
```

--------------------------------

### Playwright E2E Test Example

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Testing-Guide.md

Example of a Playwright test script for form submission.

```javascript
const { test, expect } = require('@playwright/test');

test('form submission works', async ({ page }) => {
    await page.goto('/form-page/');
    await page.fill('[name="email"]', 'test@example.com');
    await page.click('button[type="submit"]');
    await expect(page.locator('.success-message')).toBeVisible();
});
```

--------------------------------

### Import Force UI Components (JavaScript)

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Admin-Dashboard.md

Demonstrates how to import components like Button, Modal, and Input directly from the `@bsf/force-ui` library.

```javascript
import { Button, Modal, Input } from '@bsf/force-ui';
```

--------------------------------

### Verify Build

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Getting-Started.md

Run the build process to ensure no errors exist in the current configuration.

```bash
npm run build        # Should complete without errors
```

--------------------------------

### Create and Check PHP Test File

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/maintenance.md

Use this bash script to create a temporary PHP file, paste your example code into it, and then check its syntax using the PHP linter.

```bash
# Create test file
cat > /tmp/test-example.php << 'EOF'
<?php
// Paste example code here
EOF

# Check syntax
php -l /tmp/test-example.php
```

--------------------------------

### Build and Test Commands

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

Commands for building assets and verifying database entries after implementation.

```bash
# Build assets
npm run build

# Test in browser
# 1. Create new form
# 2. Add "Star Rating" block
# 3. Configure settings (label, required, max stars)
# 4. Publish form
# 5. Submit test entry
# 6. Verify data saved correctly

# Check database
wp db query "SELECT * FROM wp_sureforms_entries ORDER BY id DESC LIMIT 1;"
```

--------------------------------

### Setup React Query Client

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/05-frontend/FRONTEND-GUIDE.md

Configure the QueryClient with default options for stale time and retries. This client is then provided to the application using QueryClientProvider.

```javascript
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const queryClient = new QueryClient({
    defaultOptions: {
        queries: {
            staleTime: 5 * 60 * 1000, // 5 minutes
            retry: 1,
        },
    },
});

function App() {
    return (
        <QueryClientProvider client={queryClient}>
            <Dashboard />
        </QueryClientProvider>
    );
}
```

--------------------------------

### Build Project

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Contributing-Guide.md

Commands for generating production builds for the project.

```bash
npm run build          # Full production build (JS + SASS + minify)
npm run build:script   # Build JS only
npm run build:sass     # Build SASS only
```

--------------------------------

### Install SMTP Plugin via WP-CLI

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/faq.md

Command to install and activate the WP Mail SMTP plugin to resolve email delivery issues.

```bash
wp plugin install wp-mail-smtp --activate
```

--------------------------------

### Run Quick Diagnostics

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Use these WP-CLI commands to check environment versions, plugin status, and database integrity.

```bash
# 1. WordPress & PHP versions
wp core version
php -v

# 2. Plugin status
wp plugin list | grep sureforms

# 3. Theme compatibility
wp theme list --status=active

# 4. Recent errors
tail -50 wp-content/debug.log | grep -i "sureforms\|fatal\|error"

# 5. Database tables exist
wp db query "SHOW TABLES LIKE '%sureforms%';"
```

--------------------------------

### Check Version Compatibility

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Confirm that the free and pro plugin versions match.

```bash
# Free and Pro versions should match
# Both should be 2.5.0 (or same major.minor)
```

--------------------------------

### Initialize Star Rating Block Directories

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/onboarding.md

Use these shell commands to scaffold the directory structure for a new custom block.

```bash
# Create directories
mkdir -p src/blocks/star-rating
mkdir -p inc/blocks/star-rating

# Copy from existing field (Phone is a good template)
cp -r src/blocks/phone/* src/blocks/star-rating/
cp inc/blocks/phone/block.php inc/blocks/star-rating/
```

--------------------------------

### PHP Security Best Practices

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/coding-standards.md

Demonstrates input sanitization, database preparation, and output escaping.

```php
// Input
$email = sanitize_email( wp_unslash( $_POST['email'] ?? '' ) );

// Database
$results = $wpdb->get_results(
    $wpdb->prepare(
        "SELECT * FROM {$wpdb->prefix}sureforms_entries WHERE form_id = %d",
        $form_id
    )
);

// Output
echo '<div>' . esc_html( $user_name ) . '</div>';
```

--------------------------------

### Install and Activate WP Super Cache Plugin

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Install and activate the WP Super Cache plugin using the WordPress CLI. Caching pages can significantly speed up frontend loading times for users.

```bash
wp plugin install wp-super-cache --activate
```

--------------------------------

### Clone Repository

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Contributing-Guide.md

Initial steps to fork and clone the SureForms repository to a local environment.

```bash
git clone https://github.com/YOUR_USERNAME/sureforms.git
cd sureforms
```

--------------------------------

### GET /entries/list

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/REST-API-Reference.md

Retrieves a paginated list of form entries.

```APIDOC
## GET /entries/list

### Description
Paginated entries listing.

### Method
GET

### Endpoint
/wp-json/sureforms/v1/entries/list

### Parameters
#### Query Parameters
- **form_id** (int) - Optional - Filter by form ID
- **status** (string) - Optional - Filter by entry status
- **search** (string) - Optional - Search term
- **date_from** (string) - Optional - Start date
- **date_to** (string) - Optional - End date
- **orderby** (string) - Optional - Sort column
- **order** (string) - Optional - Sort direction (ASC/DESC)
- **per_page** (int) - Optional - Items per page
- **page** (int) - Optional - Current page number
```

--------------------------------

### PHP Namespace Declaration

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/glossary.md

Example of organizing SureForms classes using namespaces.

```php
namespace SRFM\Inc\Database\Tables;

class Entries {
  // ...
}
```

--------------------------------

### GET /wp-json/sureforms/v1/entries/list

Source: https://context7.com/brainstormforce/sureforms-public/llms.txt

Retrieve form entries with filtering, pagination, and sorting options.

```APIDOC
## GET /wp-json/sureforms/v1/entries/list

### Description
Retrieve form entries with filtering, pagination, and sorting options.

### Method
GET

### Endpoint
/wp-json/sureforms/v1/entries/list

### Parameters
#### Query Parameters
- **form_id** (integer) - Required - Filter entries by form ID.
- **status** (string) - Optional - Filter by entry status (e.g., unread).
- **per_page** (integer) - Optional - Number of entries per page.
- **page** (integer) - Optional - Page number.
- **orderby** (string) - Optional - Field to sort by.
- **order** (string) - Optional - Sort direction (ASC/DESC).

### Response
#### Success Response (200)
- **entries** (array) - List of entry objects.
- **total** (integer) - Total number of entries.
- **total_pages** (integer) - Total number of pages.

#### Response Example
{
  "entries": [
    {
      "id": 45,
      "form_id": 123,
      "form_name": "Contact Form",
      "status": "unread",
      "created_at": "2024-01-15 10:30:00",
      "form_permalink": "https://example.com/contact/"
    }
  ],
  "total": 150,
  "total_pages": 8,
  "current_page": 1
}
```

--------------------------------

### SureForms System Overview

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/architecture.md

Illustrates the modular structure of SureForms, differentiating between the core Free plugin and the optional Pro extension with its advanced features and integrations.

```text
WordPress Site
├── SureForms Free (Required)
│   ├── Core form functionality
│   ├── Stripe payments
│   ├── AI form builder
│   └── Entry management
└── SureForms Pro (Optional Extension)
    ├── Advanced features (conditional logic, multi-step)
    ├── PayPal payments
    ├── User registration/login
    └── 24+ native integrations
```

--------------------------------

### Build Commands

Source: https://github.com/brainstormforce/sureforms-public/blob/master/CLAUDE.md

Commands for managing the development server and production builds.

```bash
npm run start              # Dev server with watch
npm run build              # Full production build
npm run build:script       # Webpack only
npm run build:sass         # SASS only
```

--------------------------------

### Instant Form URL Structure

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/glossary.md

Example of a direct access URL for a published SureForms form.

```text
https://yoursite.com/?srfm_form=abc123
```

--------------------------------

### SureForms Pro Build Commands

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/README.md

Commands for building SureForms Pro, including full build and packaging for distribution.

```bash
npm run build          # Full build
npm run package        # Create distributable zip
```

--------------------------------

### Add New Column to Schema

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/04-backend/DATABASE-SCHEMA.md

Example of adding a new column definition to the table schema.

```php
public function get_schema() {
    return [
        // ... existing columns
        'new_column' => [
            'type'    => 'string',
            'default' => '',
        ],
    ];
}
```

--------------------------------

### Release SureForms Pro

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/README.md

Steps to prepare and package SureForms Pro for distribution, including version updates and build commands.

```bash
Update version in `sureforms-pro.php`
Run `npm run build && npm run package`
Generates `sureforms-pro.zip`
Deploy to licensing server
```

--------------------------------

### Run WordPress Coding Standards Checker

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/troubleshooting.md

Commands to install and run PHPCS for WordPress standards.

```bash
composer require --dev wp-coding-standards/wpcs
vendor/bin/phpcs --standard=WordPress inc/
```

--------------------------------

### Run Full Production Build

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Deployment-Guide.md

Execute the complete production build process, which includes JavaScript and SASS compilation, and minification.

```bash
# Full production build (JS + SASS + minify)
npm run build
```

--------------------------------

### Reinstall Dependencies

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/wiki/Troubleshooting-FAQ.md

Clear existing node_modules and perform a fresh installation to resolve build issues.

```bash
rm -rf node_modules
npm install
```

--------------------------------

### View Build Output Files

Source: https://github.com/brainstormforce/sureforms-public/blob/master/docs/05-frontend/FRONTEND-GUIDE.md

Lists the generated JavaScript bundles and dependency manifests in the assets/build directory.

```text
assets/build/
├── formEditor.js       # Form editor bundle (~1.9MB)
├── blocks.js           # Gutenberg blocks (~1.3MB)
├── dashboard.js        # Dashboard page (~1.3MB)
├── entries.js          # Entries page (~728KB)
├── forms.js            # Forms listing (~727KB)
├── settings.js         # Settings page (~1.1MB)
├── formSubmit.js       # Frontend submission (~60KB)
└── *.asset.php         # Webpack dependency manifests
```

--------------------------------

### SureForms Free Build Commands

Source: https://github.com/brainstormforce/sureforms-public/blob/master/internal-docs/README.md

Commands for building SureForms Free, including full build, development mode, linting, and translation file generation.

```bash
npm run build          # Full build (webpack + sass + grunt)
npm run start          # Dev mode (watch)
npm run lint-js:fix    # Fix JS linting
npm run makepot        # Generate translation files
```

--------------------------------

### GET sureforms/get-form

Source: https://github.com/brainstormforce/sureforms-public/blob/master/inc/abilities/ABILITIES.md

Retrieve detailed information about a specific form including fields, settings, and shortcode.

```APIDOC
## GET sureforms/get-form

### Description
Retrieve detailed information about a specific form including fields, settings, and shortcode.

### Parameters
#### Query Parameters
- **form_id** (integer) - Required - Form ID

### Response
#### Success Response (200)
- **form_id** (integer) - Form ID
- **title** (string) - Form title
- **status** (string) - Form status
- **fields** (array) - List of form fields
- **settings** (object) - Form settings
- **shortcode** (string) - Form shortcode

#### Response Example
{
  "form_id": 123,
  "title": "Contact Form",
  "status": "publish",
  "fields": [
    {
      "type": "input",
      "label": "Full Name",
      "slug": "full-name",
      "required": true
    }
  ],
  "settings": {
    "submit_button_text": "Submit",
    "use_label_as_placeholder": false,
    "form_container_width": "",
    "instant_form": "",
    "submit_alignment": "left",
    "form_recaptcha": ""
  },
  "shortcode": "[sureforms id=\"123\"]"
}
```

--------------------------------

### GET sureforms/list-forms

Source: https://github.com/brainstormforce/sureforms-public/blob/master/inc/abilities/ABILITIES.md

Retrieve a list of forms with optional filtering by status, search query, and pagination.

```APIDOC
## GET sureforms/list-forms

### Description
Retrieve a list of forms with optional filtering by status, search query, and pagination.

### Parameters
#### Query Parameters
- **status** (string) - Optional - Enum: publish, draft, trash, any. Default: any
- **search** (string) - Optional - Search forms by title
- **per_page** (integer) - Optional - Results per page (1-100). Default: 10
- **page** (integer) - Optional - Page number. Default: 1

### Response
#### Success Response (200)
- **forms** (array) - List of form objects
- **total** (integer) - Total number of forms
- **pages** (integer) - Total number of pages

#### Response Example
{
  "forms": [
    {
      "id": 123,
      "title": "Contact Form",
      "status": "publish",
      "date": "2025-01-15 10:30:00",
      "entry_count": 42
    }
  ],
  "total": 5,
  "pages": 1
}
```