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>

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
-
-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
+## 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/`
-2. Run `composer install --no-dev` in the plugin directory
-3. Activate the plugin through the 'Plugins' menu in WordPress
-4. Configure global settings under WooCommerce > Settings > Composable Products
+### From Release Package
+
+1. Download the latest release ZIP from the releases page
+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 pricing mode
-- Display options
+- **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 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.