Update AGENTS.md: add standard header, plugin URLs, Themes list, Docs section

Author: ajaydsouza

AGENTS.md

@@ -1,11 +1,17 @@
 # AGENTS.md
 
-**WebberZone Code Block Highlighting** v1.1.0. WordPress plugin extending the native Gutenberg `core/code` block with syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid. Namespace: `WebberZone\Code_Block_Highlighting`. Requires WordPress 6.6+, PHP 7.4+. No Freemius.
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
 
-Two highlighting modes:
+## Plugin Overview
+
+**WebberZone Code Block Highlighting** v1.1.0 (plugin slug: `webberzone-code-block-highlighting`) extends the native Gutenberg `core/code` block with syntax highlighting via JS block filters and a `render_block_core/code` PHP filter. Does not replace the block — existing posts stay valid. Namespace: `WebberZone\Code_Block_Highlighting`. Requires WordPress 6.6+, PHP 7.4+. No Freemius.
 
+Two highlighting modes:
 - **Client-side** (default): Prism.js runs in the browser. Loads the Prism JS bundle + theme CSS.
-- **Server-side**: highlight.php pre-renders token spans on the server. Loads only `hljs-clipboard.js` for the copy-to-clipboard and expand/collapse toolbar buttons (no Prism JS). Uses the same Prism theme CSS — token class remapping (`remap_token_classes()` in `class-blocks.php`) converts hljs-* span classes to Prism `token *` classes via `strtr`, giving exact visual parity across all 21 themes.
+- **Server-side**: highlight.php pre-renders token spans on the server. No Prism.js loaded. Loads Prism theme CSS + `hljs-server-mode.css` + `hljs-clipboard.js` (copy-to-clipboard + expand/collapse). Token class remapping (`remap_token_classes()` in `class-blocks.php`) converts hljs-* span classes to Prism `token *` classes via `strtr`, giving exact visual parity across all 21 themes.
+
+WordPress.org: https://wordpress.org/plugins/webberzone-code-block-highlighting/
+webberzone.com: https://webberzone.com/plugins/webberzone-code-block-highlighting/
 
 ## Commands
 
@@ -32,7 +38,6 @@ npm run zip            # Plugin zip
 Bootstrap: `wzcbh()` singleton on `plugins_loaded` → instantiates `Frontend\Blocks`, `Frontend\Styles_Handler` → `Admin\Admin` on `init` (admin only).
 
 Key files:
-
 - `includes/class-main.php` — bootstrap and object wiring
 - `includes/frontend/class-blocks.php` — editor assets, REST route, `render_block_core/code` filter; `render_code_block_server()` for server mode; `remap_token_classes()` for hljs→Prism class mapping
 - `includes/frontend/class-styles-handler.php` — conditional asset loading for both modes: client (Prism JS + theme CSS) and server (theme CSS + `hljs-server-mode.css` + `hljs-clipboard.js`)
@@ -50,24 +55,28 @@ Always `require` the generated `.asset.php` manifest before enqueueing block scr
 
 **`wzcbh_languages` filter** — controls the editor UI dropdown only. Does not affect which Prism grammars are bundled. Adding a slug without a matching grammar import in `frontend.js` results in plain-text output.
 
-**Editor canvas styling** — `enqueue_editor_canvas_styles()` extracts only `background` and `color` from the active Prism theme CSS and re-injects them with `.block-editor-block-list__layout` prepended to win the specificity race against the editor's own `pre` styles.
+**Editor canvas styling** — `enqueue_editor_canvas_styles()` extracts only `background` and `color` from the active Prism theme CSS and re-injects them with `.block-editor-block-list__layout` prepended to win the specificity race against the editor's own `pre` styles. Layout properties are intentionally excluded.
+
+**Themes (21):** A11y Dark, Coldark Cold, Coldark Dark, Dracula, Duotone Dark, Duotone Light, GitHub Light, Gruvbox Dark, Gruvbox Light, Lucario, Material Dark, Material Light, Night Owl, Nord, One Dark, One Light, Shades of Purple, Solarized Dark, Synthwave '84, VS Code Dark+, Xonokai (Monokai).
+
+**Default color scheme:** `prism-onedark`
+
+**If you change block attributes in JS**, update `render_code_block()` in `class-blocks.php` and the defaults flow as well.
 
-**Server-mode token remapping** — `remap_token_classes()` in `class-blocks.php` uses `strtr()` to convert every `class="hljs-*"` span emitted by highlight.php into the equivalent Prism `class="token *"` span. Keys are ordered longest-first to prevent prefix collisions.
+**Server-mode token remapping** — `remap_token_classes()` in `class-blocks.php` uses `strtr()` to convert every `class="hljs-*"` span emitted by highlight.php into the equivalent Prism `class="token *"` span. `strtr()` is safe here because highlight.php emits single-class spans only (no compound classes). Keys are ordered longest-first to prevent prefix collisions (e.g. `hljs-selector-tag` before a hypothetical `hljs-selector`).
 
 **highlight.php autoloader** — `\Highlight\Autoloader::register()` does not exist. Use `spl_autoload_register(static function(string $class_name): void { \Highlight\Autoloader::load($class_name); })`.
 
 **`hljs-server-mode.css`** — only handles `.wzcbh-highlighted-line` line highlighting. Font-size, line-numbers gutter, and word-wrap are all in `frontend.css` (webpack build), which loads in both modes.
 
-**Both modes use the same Prism theme CSS** — `Settings::get_color_scheme_css()` always returns the Prism CSS URL. There is no per-mode branch.
-
-**Default color scheme:** `prism-onedark`
+**Both modes use the same Prism theme CSS** — `Settings::get_color_scheme_css()` always returns the Prism CSS URL. There is no per-mode branch or hljs-specific theme mapping table.
 
 ## Asset loading
 
 Assets load only on pages containing at least one `core/code` block (`Styles_Handler::enqueue_assets()`). Use `wzcbh_force_load_assets` to override.
 
-- **Client mode**: `frontend.css` + Prism theme CSS + `wzcbh-prism-js` script bundle
-- **Server mode**: `frontend.css` + Prism theme CSS + `hljs-server-mode.css` + `hljs-clipboard.js` (syntax pre-rendered in HTML; `hljs-clipboard.js` provides copy-to-clipboard and expand/collapse only, no Prism)
+- **Client mode**: `frontend.css` + Prism theme CSS + `wzcbh-prism-js` script bundle (includes all grammars and plugins)
+- **Server mode**: `frontend.css` + Prism theme CSS + `hljs-server-mode.css` + `hljs-clipboard.js` (copy-to-clipboard + expand/collapse)
 
 ## Filters and routes
 
@@ -94,6 +103,14 @@ Assets load only on pages containing at least one `core/code` block (`Styles_Han
 
 Toolbar language labels are `aria-hidden`. Expand/collapse button uses `aria-expanded`. When extending toolbar behaviour, preserve keyboard access and screen reader support.
 
+## Docs
+
+KB articles live in `docs/` using the standard WebberZone structure. Frontmatter values:
+- `products: [code-block-highlighting]`
+- Section prefixes: `01-wzcbh-getting-started`, `02-wzcbh-advanced`, `03-wzcbh-developer-docs`
+
+Run `/docs-style --audit webberzone-code-block-highlighting` to check style compliance before committing docs.
+
 ## Before adding new per-block controls
 
 Verify: JS attribute schema → save output → `render_code_block()` in PHP → frontend Prism plugin support.