# Factorize Essentials — 5-Minute Quickstart

Trust notes, honest badges, and checkout guards for a liquidation / open-box WooCommerce store. No build step, no API keys, no settings screen — activate it and the storefront changes are live.

## Prerequisites

- WordPress 6.2+ and PHP 7.4+
- **WooCommerce installed and active** — without it the plugin activates cleanly but does nothing
- A few products to see it work: ideally at least one on sale and one out of stock

## Install

1. Copy the `factorize-essentials` folder into `wp-content/plugins/` (or upload the zip via Plugins → Add New → Upload Plugin).
2. Activate **Factorize Essentials**.
3. A **Factorize** menu appears in wp-admin — the shared hub every Factorize plugin stands up. Essentials shows as a status card under the Storefront tab; there is nothing to configure there.

## First value in 4 steps

1. **Open an on-sale product** on the front end. You should see the real percentage-off flash (e.g. "-29%"), a "SAVE $x" line under the price, the condition note, and the free-pickup line under the buy box.
2. **Open the shop page.** Out-of-stock items now carry an OUT OF STOCK badge and a "View Details" button instead of "Add to cart".
3. **Search for gibberish** (`?s=zzzzzz&post_type=product`). Instead of a dead-end notice you get the query echoed back, a spelling nudge, and "Shop All Deals" / "Home" buttons.
4. **Make the wording yours.** Via WP-CLI:

   ```sh
   wp option update factorize-essentials_options \
     '{"pickup_title":"Pickup at Our Warehouse — Free","condition_note":"New overstock — box may show shelf wear."}' \
     --format=json
   ```

   Or in PHP: `update_option( 'factorize-essentials_options', array( 'pickup_title' => '...' ) );`

## Configuration

| Key | Default | Effect |
| --- | --- | --- |
| `condition_note` | `New and unused — packaging may have slight dents, creases, or an open box.` | Condition disclaimer under the product summary on single product pages. |
| `pickup_title` | `Pickup In Store — Free` | Bold first line of the pickup note under the buy box. |
| `pickup_sub` | `Free local pickup — or flat-rate shipping at checkout.` | Small-print second line of the pickup note. |

Values are read through `empire_essentials_config( $key )`. Override any subset via the `factorize-essentials_options` option (as above) or filter the merged array at runtime with `add_filter( 'factorize-essentials_config', ... )`. The per-string filters `empire_tools_condition_note`, `empire_tools_pickup_title`, and `empire_tools_pickup_sub` apply on top, so theme-level overrides keep working. A legacy `empire-store-essentials_options` option is read as a fallback when the new one is empty.

## Troubleshooting

- **Badges and notes render as plain unstyled text.** The plugin outputs classed markup and leaves all CSS to the theme. Add styles for `et-save-badge`, `et-oos-badge`, `et-condition-note`, `et-pickup-note`, `et-brand-chips`, `et-no-results`, `et-checkout-fineprint`, and `et-cart-count` (the live cart badge also needs a `span.et-cart-count` element in your header for the AJAX fragment to refresh).
- **The checkout fine print shows someone else's pickup address.** In 1.0.0 the checkout note's copy is fixed in code and was written for the original store. Edit or remove the `render_block` filter in `factorize-essentials.php` for now — an admin-editable version is on the roadmap.
- **No brand chip row above the shop grid.** The row only renders on the main shop and search pages, and only for product categories that have an `order` meta value to sort by (set by category-ordering tools). No ordered, non-empty categories means no row — that's the designed empty state, not a bug.
