# BW Plugins — Claude Meta-Process

This is the Bowden Works WordPress plugin development area. All plugins live under `wp-content/plugins/bw-*/`.

## Before doing anything

1. **Read the specific plugin's `CLAUDE.md`** (`wp-content/plugins/bw-<slug>/CLAUDE.md`).
2. **Read `docs/SESSION-LOG.md`** inside the plugin directory for recent context.
3. **Read `docs/HANDOFF-NOTES.md`** inside the plugin directory for async messages.
4. If the user says "work on the plugin" and there is more than one, **ask which**.

## What lives where

| Path | Purpose |
|---|---|
| `wp-content/plugins/bw-*/` | Plugins under active development |
| `wp-content/themes/kadence-child/` | Dev site child theme (team CPT for test fixtures) |
| `tools/` | Shared scripts: release, security-scan, cleanup-scan, test-plugin, bump-version, new-plugin |
| `tools/vendor-sources/plugin-update-checker/` | Shared vendor source, copied into each plugin during scaffold |
| `docs/` | Cross-plugin docs: CONTRIBUTING, RELEASE-PROCESS, SECURITY, NEW-PLUGIN-GUIDE, CLAUDE-STANDARDS |
| `docs/templates/` | Scaffolding templates used by `tools/new-plugin.sh` |
| `.releases/` | Per-release snapshots (zip + meta + source tarball) |

## The dist host

Updates are served from a separate WordPress site at `plugins.bowden.works`, located at `/srv/apps/bw-plugins-dist/`. A custom WP plugin there (`bw-update-server`) handles the REST endpoint `/wp-json/bw/v1/update-check`. `tools/release.sh` publishes zips to `/srv/apps/bw-plugins-dist/wp-content/uploads/plugin-updates/`.

**NEVER** edit files in the dist host's `plugin-updates/` directory manually. Use `tools/release.sh`.

## Common commands

```bash
# Create a new plugin
tools/new-plugin.sh bw-<slug> "BW <Name>" "Short description"

# Bump version (updates header, constant, CHANGELOG, CLAUDE.md together)
tools/bump-version.sh bw-<slug> 0.2.0

# Run scans during development
tools/cleanup-scan.sh bw-<slug>
tools/security-scan.sh bw-<slug>
tools/test-plugin.sh bw-<slug>

# Release
tools/release.sh bw-<slug> 0.2.0
```

## Container management

```bash
srv-gw status --project bw-plugins     # Check status
srv-gw logs --project bw-plugins       # View logs
srv-gw restart --project bw-plugins    # Restart
```

## Versioning protocol (applies to every plugin)

- **Patch (X.Y.Z):** Bug fix or small iteration.
- **Minor (X.Y.0):** New feature or task completion.
- **Major (X.0.0):** Breaking change.
- `0.x.y` during pre-1.0 development (anything can break).
- Version in plugin header, `BW_<SLUG>_VERSION` constant, and `CHANGELOG.md` entry must all match. Release script enforces this.

## Always

- Read the plugin's own `CLAUDE.md` before editing it.
- Update `CHANGELOG.md` when making user-visible changes.
- Update `docs/SESSION-LOG.md` at the end of each session.
- Use `tools/release.sh` for releases — never touch dist files directly.
- Prefix all plugin globals/hooks/options/functions with `bw_<slug>_`.
- Declare `defined( 'ABSPATH' ) || exit;` at the top of every PHP file.
- Use `esc_html()` / `esc_attr()` / `esc_url()` before outputting user data.
- Use `$wpdb->prepare()` for all SQL with variables.
- Use `wp_verify_nonce()` on every state-changing admin action.

## Never

- Never edit `vendor/` (third-party code).
- Never edit `wp-content/uploads/` on the dist host directly.
- Never bypass `cleanup-scan`, `security-scan`, or `test-plugin` (no `|| true`, no `--force`).
- Never commit secrets to any file — `.env`, API keys, passwords.
- Never touch `/srv/apps/bwgeo/`, `/srv/apps/communityfinancials/`, or `bw-ai-schema-pro` in any location. Those are the legacy setup, left alone until rian explicitly migrates them into this framework.
- Never run destructive operations (rm -rf, DROP TABLE, docker rm) without explicit user confirmation.

## No git in Phase 1

This repo is NOT under git yet. File deletions are real and irreversible outside of:
- Filesystem rsync backups to NAS (scheduled daily)
- Per-release source snapshots at `.releases/<slug>/<version>/source-snapshot.tar.gz`
- Append-only `docs/SESSION-LOG.md` inside each plugin

**Be extra careful with deletions.** Ask before removing anything non-trivial.

## Database

- **DB:** `wp_bw_plugins`, user `wp_bw_plugins`, credentials in `.env`
- **Host:** port 3078 (internal, proxied through Caddy)

## Plugins currently in this repo

See `README.md` for the current list.