# BW Dev — Claude Development Guide

**Version:** 1.13.2 (36 modules; 1.12.0 added Image Optimizer with watermark removal and multi-profile UI; 1.12.1 switched its preview to a button-triggered "Update preview" pattern after rian found Imagick on Flywheel too slow for live updates; 1.13.0 merged three standalone plugins as Front-end modules — Inline Search, Animate Row (AOS now vendored, not CDN-loaded), Scroll Down — and added a new Analytics module for GTM + Google Search Console verification; 1.13.1 simplified Analytics (removed the Emit-GTM toggle — emission now keyed off gtm_id alone) and tried to fix an Animate Row blank-hero bug; 1.13.2 fully disabled Animate Row after the 1.13.1 partial fix still left below-the-fold rows hidden — pending a proper rewrite, the module's enqueue is short-circuited site-wide while saved state is preserved) | **Last Updated:** 2026-05-29

## What this plugin is

The single Bowden Works "dev toolkit" plugin used on every Kadence-based site. Combines 5 previously-separate plugins (admin columns, favicon, sticky elements, post-link blocks, YouTube embed) into one BW-compliant plugin with a unified settings page at `Settings → BW Dev` and a white-label layer for client-facing block names.

The original brief from adi is at `docs/notes-from-adi.txt`. Read it once.

## Before making changes

1. Read `docs/HANDOFF-NOTES.md` FIRST — it has the current state and 4 pickup scenarios (fresh Claude, rian releasing, per-site rollout, adding an 8th module). Start there to understand WHAT TO DO NEXT.
2. Read `docs/SESSION-LOG.md` (newest entry at top) for what was just done.
3. Read `docs/ROADMAP.md` for the phase history.
4. Read `docs/KNOWN-ISSUES.md` before recommending anything migration-related.
5. Read `docs/SPEC.md` / `docs/ARCHITECTURE.md` only if HANDOFF doesn't answer your question.

## Hard rules for this plugin

- **Settings page lives at `Settings → BW Dev`** — a submenu under WordPress's built-in Settings menu, NOT a top-level admin menu. (Adi's explicit preference: "not too front facing".)
- **Single root option `bw_dev_settings`** — all persisted state nested under this one option key. No proliferation of `bw_dev_<thing>_settings`.
- **Modules are individually toggleable** — disabled modules register zero hooks, zero assets, zero REST routes.
- **White-label scope = blocks + plugin admin name only.** Tab labels inside `Settings → BW Dev` stay BW-branded; clients don't visit there.
- **DO NOT modify the 5 source plugins** at `/srv/apps/bw-plugins/wp-content/plugins/bw-{admin-column,favicon,pretty-post-link,sticky-settings,youtube-embed}/`. They are the reference implementation until each module is verified ported. Adi will deactivate them manually once each is replaced.
- **Re-prefix everything** when porting: `bw_favicon_*` → `bw_dev_*`, `bw/youtube` → `bw-dev/youtube`, AJAX action names included.
- **Migration is one-way and non-destructive.** Activation reads legacy options into `bw_dev_settings` if it's empty. Never delete legacy options — the old plugin's uninstall hook handles its own cleanup.

## Module slug ↔ source plugin map

| Module slug (PHP) | UI label | Source plugin (DO NOT EDIT) |
|---|---|---|
| `admin_columns` | Admin Columns | `bw-admin-column` |
| `favicon` | Favicon | `bw-favicon` |
| `sticky` | Sticky Elements | `bw-sticky-settings` |
| `post_link` | Post Link Block | `bw-pretty-post-link` |
| `youtube` | YouTube Block | `bw-youtube-embed` |
| `svg_upload` | SVG Upload | *(none — net-new feature)* |
| `admin_note` | Admin Note | `bw-admin-note` (deployed on regent + promobix; the bw-plugins copy is empty) |
| `analytics` | Analytics | *(none — net-new feature; GTM + Search Console verification meta)* |
| `inline_search` | Inline Search | `bw-inline-search` |
| `animate_row` | Animate Row | `bw-animate-row` (AOS vendored in `assets/vendor/aos/`, was unpkg CDN) |
| `scroll_down` | Scroll Down | `bw-scroll-down` |

Block names use hyphens (`bw-dev/post-link-list`), PHP slugs use underscores (`post_link`).

## Process

This plugin follows the standard BW Plugins process defined in the umbrella `/srv/apps/bw-plugins/CLAUDE.md` — versioning protocol (default = patch), release gating (never `release.sh` without explicit "release it" from rian), session protocol, and the Always / Never lists. Plus the full release flow in `/srv/apps/bw-plugins/docs/RELEASE-PROCESS.md`.

The hard rules below are plugin-specific overrides and additions to the umbrella, not duplicates of it.

## Session Protocol (plugin-specific addition)

Standard session protocol plus:

- At session start, also read `docs/ROADMAP.md` (this plugin tracks phases there).
- At session end, also tick any completed checkboxes in `docs/ROADMAP.md`.

## Architecture Quick Reference

- Main file: `bw-dev.php` (thin — header, constants, `plugins_loaded` bootstrap).
- Core classes: `includes/class-bw-dev-{plugin,settings,brand,admin-page}.php`.
- Module interface: `includes/interface-bw-dev-module.php`.
- Modules: `includes/modules/class-bw-dev-module-<slug>.php`.
- Admin views: `admin/views/` and `admin/tab-renderers/`.
- Blocks: `blocks/post-link/` and `blocks/youtube/` (each with `block.json`).
- Shared assets: `assets/{css,js,images}/`.
- Vendored: `vendor/plugin-update-checker/` (never edit).

## Plugin-specific Never (additions to the umbrella)

The umbrella covers vendor edits, secrets, scan bypass, etc. These are bw-dev-only:

- Edit the 5 source plugins under `/srv/apps/bw-plugins/wp-content/plugins/bw-{admin-column,favicon,pretty-post-link,sticky-settings,youtube-embed}/` — they're the reference implementation until each module is verified ported.
- Auto-deactivate or delete the source plugins from bw-dev's activation hook — adi deactivates them manually once each port is verified.
- Add a top-level admin menu — `Settings → BW Dev` only (adi's explicit preference).