Consolidate documentation, bump to v1.2.1

Condense CLAUDE.md from ~1960 to ~160 lines keeping only essential
architecture and lessons learned. Merge INSTALL.md into README.md
and IMPLEMENTATION.md into CLAUDE.md, then delete the source files.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.gitignore

@@ -1,14 +1,8 @@
-# Linked sources
-wp-core
-wp-plugins
-tpp
-
 # Editor swap files
 *.*swp
 
 # Composer
 vendor/
-composer.lock
 
 # Cache
 cache/
@@ -16,9 +10,14 @@ cache/
 # Development files
 .vscode/
 .idea/
+logs/
 *.log
 
 # OS files
 .DS_Store
 Thumbs.db
+.directory
+
+# Binary files
+languages/*.mo
 

CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2026-03-01
+
+### Changed
+
+- Consolidated documentation: merged INSTALL.md into README.md, merged IMPLEMENTATION.md into CLAUDE.md
+- Condensed CLAUDE.md from ~1960 lines to ~160 lines, keeping only essential architecture and lessons learned
+- README.md now includes full installation guide, usage tutorial, and troubleshooting section
+- Cleaned up .gitignore
+
+### Removed
+
+- INSTALL.md (content merged into README.md)
+- IMPLEMENTATION.md (content merged into CLAUDE.md)
+
 ## [1.2.0] - 2026-03-01
 
 ### Fixed

IMPLEMENTATION.md

@@ -1,434 +0,0 @@
-# WooCommerce Composable Products - Implementation Summary
-
-## Overview
-
-This document provides a technical overview of the WooCommerce Composable Products plugin implementation.
-
-**Version:** 1.0.0
-**Created:** 2024-12-31
-**AI-Generated:** 100% created with Claude.AI assistance
-
-## Architecture
-
-### Plugin Structure
-
-```txt
-wc-composable-product/
-├── assets/                  # Frontend assets
-│   ├── css/
-│   │   ├── admin.css       # Admin styles
-│   │   └── frontend.css    # Frontend styles
-│   └── js/
-│       ├── admin.js        # Admin JavaScript
-│       └── frontend.js     # Frontend JavaScript
-├── cache/                  # Twig template cache
-├── includes/               # PHP classes
-│   ├── Admin/
-│   │   ├── Product_Data.php    # Product data tab
-│   │   └── Settings.php        # Settings page
-│   ├── Cart_Handler.php        # Cart integration
-│   ├── Plugin.php              # Main plugin class
-│   ├── Product_Selector.php    # Frontend selector
-│   └── Product_Type.php        # Custom product type
-├── languages/              # Translation files
-│   └── wc-composable-product.pot
-├── templates/              # Twig templates
-│   └── product-selector.twig
-└── wc-composable-product.php   # Main plugin file
-```
-
-## Core Components
-
-### 1. Main Plugin Class (`Plugin.php`)
-
-**Responsibilities:**
-
-- Singleton pattern implementation
-- Twig template engine initialization
-- Hook registration
-- Component initialization
-- Asset enqueuing
-
-**Key Methods:**
-
-- `instance()`: Get singleton instance
-- `init_twig()`: Initialize Twig with WordPress functions
-- `render_template()`: Render Twig templates
-- `add_product_type()`: Register composable product type
-
-### 2. Product Type (`Product_Type.php`)
-
-**Extends:** `WC_Product`
-
-**Key Features:**
-
-- Custom product type: `composable`
-- Selection limit management (per-product or global)
-- Pricing mode (fixed or sum)
-- Product selection criteria (category/tag/SKU)
-- Dynamic product availability
-- Price calculation
-
-**Key Methods:**
-
-- `get_selection_limit()`: Get max selectable items
-- `get_pricing_mode()`: Get pricing calculation mode
-- `get_available_products()`: Query available products
-- `calculate_composed_price()`: Calculate final price
-
-### 3. Admin Settings (`Admin/Settings.php`)
-
-**Extends:** `WC_Settings_Page`
-
-**Global Settings:**
-
-- Default selection limit
-- Default pricing mode
-- Display options (images, prices, total)
-
-**Integration:** Adds tab to WooCommerce Settings
-
-### 4. Product Data Tab (`Admin/Product_Data.php`)
-
-**Responsibilities:**
-
-- Add "Composable Options" tab to product edit page
-- Render selection criteria fields
-- Save product meta data
-- Dynamic field visibility based on criteria type
-
-**Saved Meta:**
-
-- `_composable_selection_limit`: Item limit
-- `_composable_pricing_mode`: Pricing calculation
-- `_composable_criteria_type`: Selection method
-- `_composable_categories`: Selected categories
-- `_composable_tags`: Selected tags
-- `_composable_skus`: SKU list
-
-### 5. Product Selector (`Product_Selector.php`)
-
-**Responsibilities:**
-
-- Render frontend product selection interface
-- Prepare data for Twig template
-- Apply display settings
-
-**Template Variables:**
-
-- `products`: Available products array
-- `selection_limit`: Max selections
-- `pricing_mode`: Pricing calculation
-- `show_images/prices/total`: Display flags
-
-### 6. Cart Handler (`Cart_Handler.php`)
-
-**Responsibilities:**
-
-- Validate product selection
-- Add selected products to cart data
-- Calculate dynamic pricing
-- Display selected products in cart
-
-**Hooks:**
-
-- `woocommerce_add_to_cart_validation`: Validate selections
-- `woocommerce_add_cart_item_data`: Store selections
-- `woocommerce_before_calculate_totals`: Update prices
-- `woocommerce_get_item_data`: Display in cart
-
-## Frontend Implementation
-
-### Product Selector Template (`product-selector.twig`)
-
-**Features:**
-
-- Responsive grid layout
-- Checkbox-based selection
-- Product images and prices
-- Real-time total calculation
-- AJAX add-to-cart
-
-**Data Attributes:**
-
-- `data-product-id`: Composable product ID
-- `data-selection-limit`: Max selections
-- `data-pricing-mode`: Pricing mode
-- `data-price`: Individual product prices
-
-### JavaScript (`frontend.js`)
-
-**Functionality:**
-
-- Selection limit enforcement
-- Visual feedback on selection
-- Real-time price updates (sum mode)
-- AJAX cart operations
-- Error/success messages
-
-**Key Functions:**
-
-- `handleCheckboxChange()`: Selection logic
-- `updateTotalPrice()`: Calculate total
-- `addToCart()`: AJAX add-to-cart
-- `showMessage()`: User feedback
-
-### CSS Styling
-
-**Approach:**
-
-- Grid-based layout (responsive)
-- Card-style product items
-- Visual selection states
-- Mobile-first design
-- Breakpoints: 768px, 480px
-
-## Data Flow
-
-### Creating a Composable Product
-
-1. Admin selects "Composable product" type
-2. Configure selection limit and pricing mode
-3. Choose selection criteria (category/tag/SKU)
-4. Save product metadata
-5. WooCommerce registers product with custom type
-
-### Frontend Display
-
-1. Customer visits product page
-2. `Cart_Handler` renders `Product_Selector`
-3. `Product_Type::get_available_products()` queries products
-4. Twig template renders grid with products
-5. JavaScript handles interactions
-
-### Adding to Cart
-
-1. Customer selects products (JavaScript validation)
-2. Click "Add to Cart" button
-3. AJAX request with selected product IDs
-4. `Cart_Handler::validate_add_to_cart()` validates
-5. `Cart_Handler::add_cart_item_data()` stores selections
-6. `Cart_Handler::calculate_cart_item_price()` updates price
-7. Product added to cart with custom data
-
-### Cart Display
-
-1. WooCommerce loads cart
-2. `Cart_Handler::get_cart_item_from_session()` restores data
-3. `Cart_Handler::display_cart_item_data()` shows selections
-4. Price calculated dynamically on each cart load
-
-## Security Implementation
-
-### Input Sanitization
-
-- **Integers:** `absint()` for IDs and limits
-- **Text:** `sanitize_text_field()` for modes and types
-- **Textarea:** `sanitize_textarea_field()` for SKUs
-- **Arrays:** `array_map()` with sanitization functions
-
-### Output Escaping
-
-- **HTML:** `esc_html()`, `esc_html_e()`
-- **Attributes:** `esc_attr()`
-- **URLs:** `esc_url()`
-- **JavaScript:** Localized scripts with escaped data
-
-### Validation
-
-- Selection limit enforcement
-- Product availability verification
-- Cart data validation
-- Nonce verification (via WooCommerce)
-
-## Internationalization
-
-### Text Domain
-
-`wc-composable-product`
-
-### Translation Functions
-
-- `__()`: Return translated string
-- `_e()`: Echo translated string
-- `sprintf()` with `__()`: Variable substitution
-
-### POT File
-
-Generated template: `languages/wc-composable-product.pot`
-
-**Supported Locales (per CLAUDE.md):**
-
-- en_US (English)
-- de_DE, de_DE_informal (German - Germany)
-- de_CH, de_CH_informal (German - Switzerland)
-- fr_CH (French - Switzerland)
-- it_CH (Italian - Switzerland)
-
-## Performance Considerations
-
-### Caching
-
-- Twig templates cached in `cache/` directory
-- Auto-reload enabled in debug mode
-- Optimized Composer autoloader
-
-### Database Queries
-
-- Efficient `WP_Query` for product selection
-- Meta queries for SKU filtering
-- Taxonomy queries for category/tag filtering
-
-### Asset Loading
-
-- Scripts only on relevant pages
-- Minification ready (use build tools)
-- Conditional enqueuing
-
-## Extensibility
-
-### Hooks & Filters
-
-**Available Filters:**
-
-- `wc_composable_settings`: Modify settings array
-- `woocommerce_product_class`: Custom product class
-- `product_type_selector`: Product type registration
-
-**Customization Points:**
-
-- Twig templates (override in theme)
-- CSS styling (enqueue custom styles)
-- JavaScript behavior (extend object)
-
-### Developer API
-
-```php
-// Get composable product
-$product = wc_get_product($product_id);
-
-// Check if composable
-if ($product->get_type() === 'composable') {
-    // Get available products
-    $products = $product->get_available_products();
-
-    // Get selection limit
-    $limit = $product->get_selection_limit();
-
-    // Calculate price
-    $price = $product->calculate_composed_price($selected_ids);
-}
-```
-
-## Testing Checklist
-
-### Admin Testing
-
-- [ ] Product type appears in dropdown
-- [ ] Composable Options tab displays
-- [ ] Selection criteria toggle works
-- [ ] Meta data saves correctly
-- [ ] Settings page accessible
-- [ ] Global defaults apply
-
-### Frontend Testing
-
-- [ ] Product selector renders
-- [ ] Selection limit enforced
-- [ ] Price calculation accurate (both modes)
-- [ ] AJAX add-to-cart works
-- [ ] Cart displays selections
-- [ ] Checkout processes correctly
-
-### Edge Cases
-
-- [ ] Empty criteria (no products)
-- [ ] Out of stock products excluded
-- [ ] Invalid product selections rejected
-- [ ] Multiple cart items unique
-- [ ] Session persistence
-
-## Known Limitations
-
-1. **Variable Products:** Currently supports simple products in selection
-2. **Grouped Products:** Cannot be used as selectable items
-3. **Stock Management:** No automatic stock reduction for selected items
-4. **Caching:** Template cache needs manual clearing after updates
-
-## Future Enhancements
-
-Potential features for future versions:
-
-- Variable product support in selection
-- Quantity selection per item (not just presence)
-- Visual bundle previews
-- Advanced pricing rules
-- Stock management integration
-- Product recommendations
-- Selection templates/presets
-- Multi-currency support enhancements
-
-## Dependencies
-
-### Runtime
-
-- PHP 8.3+
-- WordPress 6.0+
-- WooCommerce 8.0+
-- Twig 3.0 (via Composer)
-
-### Development
-
-- Composer for dependency management
-- WP-CLI for i18n operations (optional)
-
-## Deployment
-
-### Production Checklist
-
-1. Run `composer install --no-dev --optimize-autoloader`
-2. Ensure `vendor/` directory is included
-3. Ensure `cache/` directory is writable
-4. Test on staging environment
-5. Clear all caches after activation
-6. Verify WooCommerce compatibility
-
-### Release Package
-
-Must include:
-
-- All PHP files
-- `vendor/` directory
-- Assets (CSS, JS)
-- Templates
-- Language files
-- Documentation
-
-Must exclude:
-
-- `.git/` directory
-- `composer.lock`
-- Development files
-- `wp-core/`, `wp-plugins/` symlinks
-
-## Support & Maintenance
-
-### Code Standards
-
-- WordPress Coding Standards
-- WooCommerce best practices
-- PSR-4 autoloading
-- Inline documentation
-
-### Version Control
-
-- Semantic versioning (MAJOR.MINOR.PATCH)
-- Changelog maintained
-- Annotated git tags
-- Development on `dev` branch
-
----
-
-**Last Updated:** 2024-12-31
-**Maintainer:** Marco Graetsch
-**AI Assistant:** Claude.AI (Anthropic)

INSTALL.md

@@ -1,150 +0,0 @@
-# Installation Guide
-
-## Requirements
-
-Before installing the WooCommerce Composable Products plugin, ensure your system meets these requirements:
-
-- **PHP**: 8.3 or higher
-- **WordPress**: 6.0 or higher
-- **WooCommerce**: 8.0 or higher
-- **Composer**: For dependency management
-
-## Installation Steps
-
-### 1. Upload Plugin Files
-
-Upload the plugin directory to your WordPress installation:
-
-```bash
-/wp-content/plugins/wc-composable-product/
-```
-
-### 2. Install Dependencies
-
-Navigate to the plugin directory and install dependencies:
-
-```bash
-cd /wp-content/plugins/wc-composable-product/
-composer install --no-dev --optimize-autoloader
-```
-
-### 3. Activate Plugin
-
-1. Log in to your WordPress admin panel
-2. Navigate to **Plugins > Installed Plugins**
-3. Find "WooCommerce Composable Products"
-4. Click **Activate**
-
-### 4. Configure Settings
-
-After activation, configure the plugin:
-
-1. Navigate to **WooCommerce > Settings**
-2. Click on the **Composable Products** tab
-3. Configure default settings:
-   - **Default Selection Limit**: Number of items customers can select (default: 5)
-   - **Default Pricing Mode**: Choose between "Sum of selected products" or "Fixed price"
-   - **Display Options**: Toggle product images, prices, and totals
-
-## Creating Your First Composable Product
-
-### Step 1: Create a New Product
-
-1. Go to **Products > Add New**
-2. Enter a product name (e.g., "Custom Sticker Pack")
-
-### Step 2: Set Product Type
-
-1. In the **Product Data** panel, select **Composable product** from the dropdown
-
-### Step 3: Configure General Settings
-
-In the **General** tab:
-- Set a **Regular price** (used if pricing mode is "Fixed")
-- Configure **Selection Limit** (leave empty to use global default)
-- Choose **Pricing Mode** (leave empty to use global default)
-
-### Step 4: Configure Composable Options
-
-Click on the **Composable Options** tab:
-
-1. **Selection Criteria**: Choose how to select available products
-   - **By Category**: Select product categories
-   - **By Tag**: Select product tags
-   - **By SKU**: Enter comma-separated SKUs
-
-2. Based on your selection:
-   - **Categories**: Select one or more categories from the dropdown
-   - **Tags**: Select one or more tags from the dropdown
-   - **SKUs**: Enter SKUs like: `STICKER-01, STICKER-02, STICKER-03`
-
-### Step 5: Publish
-
-Click **Publish** to make your composable product live.
-
-## Frontend Usage
-
-When customers visit your composable product:
-
-1. They see a grid of available products based on your criteria
-2. They can select up to the configured limit
-3. The total price updates in real-time (if using sum pricing mode)
-4. Click "Add to Cart" to add the composition to their cart
-5. Selected products are displayed in the cart
-
-## Troubleshooting
-
-### Plugin Won't Activate
-
-- Ensure WooCommerce is installed and activated first
-- Check PHP version (must be 8.3+)
-- Verify Composer dependencies are installed
-
-### Products Not Showing in Selector
-
-- Check that products are published and in stock
-- Verify the selection criteria (category/tag/SKU) is correct
-- Ensure products match the criteria you configured
-
-### Twig Template Errors
-
-- Ensure the `vendor/` directory exists and contains Twig
-- Run `composer install` again
-- Check that the `cache/` directory is writable
-
-### JavaScript Not Working
-
-- Clear browser cache
-- Check browser console for errors
-- Ensure jQuery is loaded (WooCommerce includes it)
-
-## Updating
-
-When updating the plugin:
-
-1. Deactivate the plugin
-2. Replace plugin files
-3. Run `composer install --no-dev --optimize-autoloader`
-4. Reactivate the plugin
-5. Clear all caches (WordPress, browser, CDN)
-
-## Uninstallation
-
-To completely remove the plugin:
-
-1. Deactivate the plugin
-2. Delete the plugin from the Plugins page
-3. Optionally clean up database entries (WooCommerce will handle this automatically)
-
-## Support
-
-For issues and feature requests:
-- GitHub: https://github.com/magdev/wc-composable-product/issues
-- Documentation: See README.md
-
-## Next Steps
-
-- Customize the template by editing `templates/product-selector.twig`
-- Modify styles in `assets/css/frontend.css`
-- Translate the plugin using the provided `.pot` file
-- Create categories/tags for easier product organization

README.md

@@ -1,12 +1,8 @@
 # WooCommerce Composable Products
 
-Create composable products where customers can select a limited number of items from a configurable set of products.
+Create composable products where customers can select a limited number of items from a configurable set of products. Think of it as a "build your own gift box" or "create your sticker pack" feature.
 
-## Description
+## Key Features
-
-This plugin adds a new product type to WooCommerce that allows customers to build their own product bundles by selecting from a predefined set of simple or variable products. Think of it as a "build your own gift box" or "create your sticker pack" feature.
-
-### Key Features
 
 - **Custom Product Type**: New "Composable Product" type in WooCommerce
 - **Flexible Selection**: Define available products by category, tag, or SKU
@@ -23,33 +19,94 @@ This plugin adds a new product type to WooCommerce that allows customers to buil
 - PHP 8.3 or higher
 - WordPress 6.0 or higher
 - WooCommerce 8.0 or higher
+- Composer (for dependency management)
 
 ## Installation
 
-1. Upload the plugin files to `/wp-content/plugins/wc-composable-product/`
+### From Release Package
-2. Run `composer install --no-dev` in the plugin directory
+
-3. Activate the plugin through the 'Plugins' menu in WordPress
+1. Download the latest release ZIP from the releases page
-4. Configure global settings under WooCommerce > Settings > Composable Products
+2. In WordPress admin, go to **Plugins > Add New > Upload Plugin**
+3. Upload the ZIP file and click **Install Now**
+4. Activate the plugin through the **Plugins** menu
+5. Configure global settings under **WooCommerce > Settings > Composable Products**
+
+### From Source
+
+1. Upload the plugin directory to `/wp-content/plugins/wc-composable-product/`
+2. Install dependencies:
+
+   ```bash
+   cd /wp-content/plugins/wc-composable-product/
+   composer install --no-dev --optimize-autoloader
+   ```
+
+3. Activate the plugin through the **Plugins** menu in WordPress
+4. Configure global settings under **WooCommerce > Settings > Composable Products**
 
 ## Usage
 
-### Creating a Composable Product
-
-1. Go to Products > Add New
-2. Select "Composable Product" as the product type
-3. Configure product details:
-   - Set the selection limit (or use global default)
-   - Choose pricing mode (fixed or sum)
-   - Define available products by category, tag, or SKU
-4. Publish the product
-
 ### Global Settings
 
-Navigate to WooCommerce > Settings > Composable Products to configure:
+Navigate to **WooCommerce > Settings > Composable Products** to configure:
 
-- Default selection limit
+- **Default Selection Limit**: Number of items customers can select (default: 5)
-- Default pricing mode
+- **Default Pricing Mode**: Choose between "Sum of selected products" or "Fixed price"
-- Display options
+- **Display Options**: Toggle product images, prices, and totals
+
+### Creating a Composable Product
+
+1. Go to **Products > Add New**
+2. Select **Composable product** from the Product Data dropdown
+3. In the **General** tab:
+   - Set a **Regular price** (used when pricing mode is "Fixed")
+   - Configure **Selection Limit** (leave empty to use global default)
+   - Choose **Pricing Mode** (leave empty to use global default)
+4. Click the **Composable Options** tab:
+   - **Selection Criteria**: Choose how to define available products
+     - **By Category**: Select one or more product categories
+     - **By Tag**: Select one or more product tags
+     - **By SKU**: Enter comma-separated SKUs (e.g., `STICKER-01, STICKER-02`)
+5. Click **Publish**
+
+### Frontend Behavior
+
+When customers visit a composable product page:
+
+1. A grid of available products is displayed based on configured criteria
+2. Customers select up to the configured limit via checkboxes
+3. Total price updates in real-time (in sum pricing mode)
+4. Stock indicators show availability (green/orange/red badges)
+5. Click "Add to Cart" to add the composition to cart
+6. Selected products are listed in the cart and checkout
+
+## Troubleshooting
+
+### Plugin Won't Activate
+
+- Ensure WooCommerce is installed and activated first
+- Check PHP version (must be 8.3+)
+- Verify Composer dependencies are installed (`vendor/` directory exists)
+
+### Products Not Showing in Selector
+
+- Check that products are published
+- Verify the selection criteria (category/tag/SKU) matches existing products
+- Ensure the criteria type and values are saved in the Composable Options tab
+
+### Twig Template Errors
+
+- Ensure the `vendor/` directory exists and contains Twig
+- Run `composer install` again
+- Check that the `cache/` directory is writable
+
+### Updating
+
+1. Deactivate the plugin
+2. Replace plugin files (or upload new release ZIP)
+3. If installed from source: run `composer install --no-dev --optimize-autoloader`
+4. Reactivate the plugin
+5. Clear all caches (WordPress, browser, CDN)
 
 ## Development
 
@@ -96,4 +153,4 @@ Marco Graetsch
 
 ## Support
 
-For issues and feature requests, please use the GitHub issue tracker.
+For issues and feature requests, please use the issue tracker.

wc-composable-product.php

@@ -4,7 +4,7 @@
  * Plugin Name: WooCommerce Composable Products
  * Plugin URI: https://src.bundespruefstelle.ch/magdev/wc-composable-product
  * Description: Create composable products where customers select a limited number of items from a configurable set
- * Version: 1.2.0
+ * Version: 1.2.1
  * Author: Marco Graetsch
  * Author URI: https://src.bundespruefstelle.ch/magdev
  * License: GPL v3 or later
@@ -20,7 +20,7 @@
 defined('ABSPATH') || exit;
 
 // Define plugin constants
-define('WC_COMPOSABLE_PRODUCT_VERSION', '1.2.0');
+define('WC_COMPOSABLE_PRODUCT_VERSION', '1.2.1');
 define('WC_COMPOSABLE_PRODUCT_FILE', __FILE__);
 define('WC_COMPOSABLE_PRODUCT_PATH', plugin_dir_path(__FILE__));
 define('WC_COMPOSABLE_PRODUCT_URL', plugin_dir_url(__FILE__));