# BW AI Schema Pro — Claude Development Guide

**Version:** 2.2.2 | **Last Updated:** 2026-06-01

## What this plugin does

Advanced Schema Markup plugin optimized for the AI era — enhances content visibility and understanding by AI systems with comprehensive schema markup. Includes admin UI, blocks, author/team detection, and template-based schema rendering.

## ⚠️ Pre-existing-plugin exception — read this before touching code

This plugin was imported into the bw-plugins framework on 2026-05-06 from `/srv/apps/bwgeo/`. It pre-dates the BW slug-derived prefix standard. **Do not "fix" the prefix without reading `docs/ROADMAP.md` first** — it's deliberately deferred and a rename touches customer data on real production sites. The slug rename and the prefix conformance are bundled into a single 3.0.0 release so customer data only gets migrated once.

| BW standard (for slug `bw-ai-schema-pro`) | What this plugin actually uses |
|---|---|
| Function/hook/option prefix `bw_ai_schema_pro_*` | `bw_schema_*` |
| VERSION constant `BW_AI_SCHEMA_PRO_VERSION` | `BW_SCHEMA_VERSION` (plus a literal compat alias of the same name — see below) |
| Other constants `BW_AI_SCHEMA_PRO_*` | `BW_SCHEMA_*` |
| Class prefix `BW_AI_Schema_Pro_*` | `BW_Schema_*` (one class is `BW_AI_Schema_Pro` — the main bootstrap) |
| Class file names `class-bw-ai-schema-pro-*.php` | `class-bw-schema-*.php` |

**New code added to this plugin should use the established `bw_schema_*` / `BW_SCHEMA_*` prefix** for internal consistency until the planned rename happens. Inconsistent prefixes within one plugin would be worse than the slug mismatch.

**BW tooling — resolved via in-plugin shim (2.1.4):** `bw-ai-schema-pro.php` defines `BW_AI_SCHEMA_PRO_VERSION` as a literal next to the grandfathered `BW_SCHEMA_VERSION`. `tools/bump-version.sh` updates the literal alongside the plugin header, so the BW toolchain sees what it expects and no hand-edit is required. The shim sunsets at the 3.0.0 rename.

## Before making changes

1. Read `docs/SESSION-LOG.md` for recent context.
2. Read `docs/HANDOFF-NOTES.md` for any pending async messages.
3. Read `docs/SPEC.md` for current requirements (sparse — pre-existing plugin).
4. Read `docs/KNOWN-ISSUES.md` — especially the import-related ones.

## 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 exception callout at the top of this file and the items below are plugin-specific overrides; everything else follows the umbrella. **The planned rename + prefix conformance is a 3.0.0 candidate — see `docs/ROADMAP.md`.**

## Releasing — plugin-specific reminder

The umbrella's "never release without an explicit go" rule applies extra strictly here: this plugin is on ~8 production customer sites, and a bad release ships to all of them on next update check. Mosiah/demoing.info copies are non-critical staging (resynced when next worked on).

Distribution path is just plugins.bowden.works now (URL flip shipped in 2.1.4 — see CHANGELOG). The bw-update-server has the plugin registered. `tools/release.sh bw-ai-schema-pro <version>` works the same as for any other bw-* plugin.

## Architecture Quick Reference

- Main file: `bw-ai-schema-pro.php` (~1k lines, includes bootstrap + activation/deactivation hooks)
- Core classes: `includes/class-bw-schema-*.php` (renderer, cache, security, blocks, hooks, helpers, templates, team-detector, team-member, author-box, author-override, admin)
- Schema definitions: `includes/schemas/`
- Admin UI: `admin/`
- Frontend assets: `assets/`
- Blocks: `blocks/`
- Vendored libs: `vendor/plugin-update-checker`
- Docs: `docs/`

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

The umbrella covers vendor edits, secrets, scan bypass, and the release-gating rule. These are schema-pro-only:

- **Do not do an in-place prefix rename without the database-migration plan** in `docs/ROADMAP.md`. A casual rename orphans `bw_schema_*`-keyed options, post-meta, transients, and cached schemas on every customer site. The 3.0.0 rename bundles slug + prefix migration into one release so customer data only moves once — splitting it would force two migrations.
- **Do not remove the `BW_AI_SCHEMA_PRO_VERSION` compat constant** in `bw-ai-schema-pro.php`. BW tooling depends on it; the grandfathered `BW_SCHEMA_VERSION` is for internal use and is derived from the plugin header at runtime.