# Swift Commerce Codex Instructions

## Project Identity

Swift Commerce is a WooCommerce extension suite that replaces many single-purpose WooCommerce plugins with one centralized product.

- `swift-commerce`: Free plugin distributed on WordPress.org.
- `swift-commerce-pro`: Pro plugin sold through SwiftCommerce.io/Freemius.
- Free owns the React dashboard, shared settings, base feature classes, REST routes, assets, and WordPress.org-compatible functionality.
- Pro extends Free with premium-only PHP classes, assets, templates, email types, and gated UI behavior.

## Non-Negotiables

- Preserve Free/Pro separation. Do not put Pro-only behavior into the WordPress.org Free plugin unless it is only a locked/gated UI preview.
- Follow WordPress.org compliance for Free code: sanitize input, escape output, verify nonces, check capabilities, use prepared SQL, load assets conditionally, and avoid external calls without clear user control/documentation.
- Use the project prefixes:
  - PHP constants/classes: `SWIFT_COMMERCE_`
  - Functions/options/transients/tables/nonces/hooks: `swift_commerce_`
  - Script/style handles: `swift-commerce-`
  - Never use standalone `sc_` or `SC_`.
- Respect the existing feature enabled/disabled state. Feature UI and WooCommerce product/order integrations should not appear when the feature is disabled unless the existing design intentionally shows a disabled upsell/state.
- Keep changes scoped. Do not refactor unrelated modules while fixing a bug.
- Never move changelog entries for unreleased work into older releases. Current unreleased work belongs in the active release section only, which is currently Pro `1.5.0`.

## Tech Stack

- Backend: PHP 7.4+, WordPress, WooCommerce.
- Frontend: React 18, TypeScript, Tailwind CSS, ShadCN UI, Lucide icons.
- Build: Vite/PostCSS.
- Licensing/distribution: Freemius for Pro, WordPress.org for Free.

## Working Patterns

- Read `.github/copilot-instructions.md` for the broad project overview when deeper context is needed.
- Use relevant Codex-installed Swift Commerce skills when a task matches them, especially:
  - `react-dashboard` for dashboard UI/settings work.
  - `wp-org-compliance` for Free plugin PHP and WordPress.org review safety.
  - `free-pro-gating` for Free/Pro boundaries.
  - `woocommerce-compat` for WooCommerce hooks, products, orders, carts, checkout, and My Account behavior.
  - `php-rest-api` for REST routes.
  - `changelog-writing` and `version-sync` for release notes and version metadata.
  - `testing-checklist` before final verification.
- Prefer existing local patterns over introducing new architecture.
- Use `rg`/`rg --files` for discovery.
- Use `apply_patch` for manual edits.
- Build after React/TypeScript changes with `npm run build`.
- Run PHP lint when PHP is available; if `php` is missing, say so in the final response.

## Changelog Discipline

- Update `swift-commerce-pro/CHANGELOG.md` only under the active release unless the user explicitly asks for a new release.
- Do not create a new version just because work was done.
- Keep release notes factual and grouped under `Added`, `Improved`, or `Fixed`.
- If Free and Pro both change, update the appropriate changelog/readme metadata for each plugin while preserving version alignment.

## UI Guidance

- Follow existing ShadCN/Tailwind patterns in `src/components/ui` and current feature folders.
- Use Lucide icons where suitable.
- Do not add decorative UI that makes operational dashboard screens feel like marketing pages.
- Keep dashboard layouts compact, scannable, and consistent with nearby feature screens.
- Avoid visible explanatory text that merely describes how to use obvious controls.

## Verification

Before finishing:

- Inspect the diff for unrelated churn.
- Run the narrowest meaningful validation available.
- For dashboard changes, run `npm run build`.
- For PHP changes, run syntax checks when available.
- Mention any validation that could not be run.