diff --git a/README.md b/README.md
index 3c8871b..bf56589 100644
--- a/README.md
+++ b/README.md
@@ -1,21 +1,42 @@
-
-## cssHolmes module for [XOOPS CMS 2.5.10+](https://xoops.org)
-[](https://xoops.org)
-[](http://www.gnu.org/licenses/gpl-2.0.html)
+# cssHolmes for XOOPS
-[](https://scrutinizer-ci.com/g/XoopsModules25x/cssholmes/?branch=master)
-[](https://www.codacy.com/app/XoopsModules25x/cssholmes)
-[](https://codeclimate.com/github/XoopsModules25x/cssholmes)
-[](https://github.com/XoopsModules25x/cssholmes/tags/)
-[](https://github.com/XoopsModules25x/cssholmes/releases/)
+cssHolmes combines HTML/CSS diagnostics, a visual theme designer, and a library
+of portable theme configuration sets. Preview changes, inspect tokens and
+contrast, and publish validated overrides without rewriting theme source files.
-**cssHolmes** module for [XOOPS CMS](https://xoops.org) is a "CSS Markup Detective", with diagnostic CSS stylesheet that can highlight potentially invalid, inaccessible or erroneous HTML(5) markup by adding one class.
+Requires **PHP 8.4+** and an installed XOOPS site. XOOPS 2.7 and 2.8 are the
+current integration targets; see the [compatibility and verification record](docs/compatibility.md)
+for what has actually been tested. XMF/XTF contract checks do not establish a
+native XOOPS 4 port.
-[](https://xoops.gitbook.io/cssholmes-tutorial/) Tutorial: see [GitBook](https://xoops.gitbook.io/cssholmes-tutorial/).
-To contribute to the Tutorial, [fork it on GitHub](https://github.com/XoopsDocs/cssholmes-tutorial)
+- [Visual designer](docs/visual-designer.md): selection, preview and saving.
+- [Theme sets](docs/theme-sets.md): library, palettes, import/export and reset.
+- [Tutorial](docs/TUTORIAL-cssholmes-XTF-XMF-v2.md).
+- [XMF/XTF migration boundaries](docs/xoops4-migration.md).
+- [Development and testing](CONTRIBUTING.md).
-[](https://www.transifex.com/xoops)
+Install the module as `htdocs/modules/cssholmes` and use the XOOPS module
+administration screen to install or update it. Keep the site's shared dependencies
+in `xoops_lib`; this module has no separate Composer installation or vendor tree.
+Back up the site's files and database before an installed-module upgrade.
-Please visit us on https://xoops.org
+## Development checks
-Current and upcoming "next generation" versions of XOOPS CMS are crafted on GitHub at: https://github.com/XOOPS
+Use a complete source checkout, including the testing/tooling files supplied by
+[the final QA change](https://github.com/XoopsModules25x/cssholmes/pull/9).
+Documentation-only review branches are incomplete; release ZIPs intentionally
+exclude `tests/`, PHPUnit configuration and other development files. If
+`tests/run.php` is absent, obtain the complete source before running these commands.
+
+From that source directory, `php tests/run.php` runs the isolated PHP
+regressions plus the analyzer, CLI and diagnostic PHPUnit tests using shared
+`xoops_lib/vendor/bin/phpunit`. For a separate checkout, set `XOOPS_VENDOR_PATH`
+to that shared vendor directory. `php tests/run.php --browser` also runs the
+browser regressions with an existing Playwright/Chromium installation.
+
+Source and issues: [XoopsModules25x/cssholmes](https://github.com/XoopsModules25x/cssholmes).
+The repository's CI checks PHP 8.4/8.5; release tags run CI before creating a
+clean module ZIP. Qodana is optional and explicitly skips its scan when
+`QODANA_TOKEN` is unavailable. A skipped scan is not a quality result.
+
+Licensed under the [GNU GPL, version 2 or later](docs/license.txt).
diff --git a/docs/RELEASE-3.3.0-alpha.1.md b/docs/RELEASE-3.3.0-alpha.1.md
new file mode 100644
index 0000000..1ae8067
--- /dev/null
+++ b/docs/RELEASE-3.3.0-alpha.1.md
@@ -0,0 +1,28 @@
+# cssHolmes 3.3.0 Alpha 1
+
+An alpha prerelease for testing theme inspection, visual editing and reusable style sets on XOOPS. Requires **PHP 8.4 or newer**. Try it on a development or staging site first.
+
+## Highlights
+
+- Inspect styles, resolved tokens and estimated text contrast; edit colors, typography, spacing and supported layout properties with live preview.
+- Use undo/redo, scoped rules and explicit **Save to theme** publication. Overrides are stored separately from theme source files.
+- Keep alternatives in a named-set library, with validated import/export and protection against concurrent updates.
+- With the corresponding xStyles integration update, inspect or edit individual examples, compare **Published vs draft**, and preview draft CSS at 360, 768 and 1280 pixels.
+- Run theme and template diagnostics, including the standalone CLI scanner.
+
+## Install or upgrade
+
+1. Back up the site, database and existing private cssHolmes settings.
+2. Extract the release ZIP so its `cssholmes` directory is under `htdocs/modules/`.
+3. Install or update cssHolmes through XOOPS module administration. Existing permissions are preserved on update; review legacy Registered Users overlay/diagnostics grants.
+ Workbench history migrates from `data/workbench/*.json` to `XOOPS_VAR_PATH/configs/cssholmes/workbench/`. Keep these private files in backups. If both locations contain different histories, the update stops for manual reconciliation rather than overwriting either copy. Legacy text patches without a saved revision must be restored manually.
+4. For the new gallery controls, also deploy the xStyles `feat/cssholmes-integration` update and update that module. cssHolmes works independently without xStyles.
+5. Read `docs/TUTORIAL-xStyles.md` in the package for the illustrated workflow.
+
+No module-local Composer or vendor installation is needed. Saving a named set does not publish changes; **Save to theme** does and may affect visitors.
+
+## Compatibility and limitations
+
+PHP 8.4/8.5 are the QA targets. Clean installation and upgrade from 3.0.0 passed on a disposable XOOPS 2.7.4-RC2 site with PHP 8.4.27, including authenticated save/reload, anonymous published styles, permission checks and restoration. See `docs/compatibility.md` for precise test evidence. The retained XOOPS 2.5.12 installer minimum is not a claim that all older core/PHP combinations were tested.
+
+This alpha does not publish admin-theme changes or provide a native XOOPS 4 port. Contrast readings are conservative estimates, not an accessibility certificate. Legacy Common PHPUnit tests still need modernization; they are outside the documented standalone suite. Qodana is optional and requires a repository token.
diff --git a/docs/TUTORIAL-cssholmes-XTF-XMF-v2.md b/docs/TUTORIAL-cssholmes-XTF-XMF-v2.md
new file mode 100644
index 0000000..511d418
--- /dev/null
+++ b/docs/TUTORIAL-cssholmes-XTF-XMF-v2.md
@@ -0,0 +1,720 @@
+# cssHolmes Tutorial — XTF Themes and XMF Widgets
+
+**Audience:** XOOPS designers, theme builders, theme editors, widget developers
+**Requires:** PHP 8.4+, cssHolmes installed and activated. See [tested compatibility boundaries](compatibility.md); the installer minimum is not a claim that every older XOOPS/PHP combination has been tested.
+**Version covered:** cssHolmes 3.3.0 Alpha 1
+
+---
+
+## What You Can Do With cssHolmes
+
+cssHolmes is a diagnostic and editing workbench built into XOOPS. It helps
+with three jobs:
+
+1. **Creating** a new XTF theme
+2. **Editing** or repairing an existing theme
+3. **Building** and validating new XMF Widgets
+
+It works on both the public site and the admin side, which matters because
+XTF widgets and layout patterns live in both places.
+
+
+
+*The hub page gives you three paths: the legacy HTML5 test suite for generic
+markup checks, the modern XTF/XMF test suite for theme and widget work, and
+the admin workbench for server-side scans and exports.*
+
+### What about sites without XTF?
+
+If no `theme.json` manifest is detected, cssHolmes switches to generic mode.
+HTML5, accessibility, layout, inspection, measurement, copy, and export still
+work. Generic theme scanning remains available for themes containing `theme.tpl`
+or `theme.html`; only manifest-dependent checks and XTF-specific tools such as
+token matching are unavailable. Slot selection still works wherever the page
+provides a `[data-slot]` ancestor; it does not require a manifest.
+
+
+
+*On a plain XOOPS install, the toolbar shows the available tools and explains
+why XTF features are limited. You can still use it for HTML quality and
+accessibility work.*
+
+---
+
+## XTF in 60 Seconds
+
+If you are new to XTF, here is the minimum you need to understand before
+using cssHolmes.
+
+**Theme = a directory with a `theme.json` file.** That file declares the
+theme's name, version, assets, and structure. It replaces the old approach
+of loose PHP files and CSS with no machine-readable manifest.
+
+**Slots = named regions in a theme layout.** A theme declares slots like
+`header`, `sidebar`, `content`, `footer`. Each slot is a place where widgets
+can be placed. Think of slots as containers with names.
+
+**Widgets = reusable components.** A widget produces HTML that gets rendered
+inside a slot. Widgets have names (like `xmf:hero`, `xmf:testimonial`),
+properties, and variants. They follow the `.xmf-` CSS class convention.
+
+**Tokens = design variables.** A theme declares tokens in `theme.json` for
+colors, spacing, fonts, and radii. They become CSS custom properties like
+`--xtf-color-primary`. Using tokens instead of hardcoded values means
+changing a token can update declarations that reference it. Matching rendered
+colors alone does not establish that reference.
+
+**The relationship:**
+
+```
+theme.json
+ declares slots ─── each slot holds widgets
+ declares tokens ── used in CSS as var(--xtf-*)
+ declares assets ── CSS and JS files
+```
+
+When cssHolmes inspects an element, it finds the nearest recognized widget
+wrapper by class or data attribute and the nearest `[data-slot]` ancestor.
+These are clues from the rendered markup; the inspector does not consult a
+widget registry or verify which widget rendered the element. It also lists
+manifest token values matching the computed color. A value match does not prove
+that the stylesheet references that token. Check the CSS declaration before
+changing a global token.
+
+---
+
+## Before and After
+
+All URLs in this tutorial use the default query key, `holmes`. If you changed
+**Preferences: holmes_query_key**, replace `holmes` in each example with your
+configured key (for example, `?themecheck=layout`). Profile values stay the same.
+
+The fastest way to understand what cssHolmes does is to see the same page
+with and without it.
+
+**Without cssHolmes** — a normal XOOPS page:
+
+
+
+*Nothing visible. The page renders normally. You cannot tell which elements
+are widgets, where slot boundaries are, or whether colors use tokens.*
+
+**With cssHolmes activated** — same page, `?holmes=xtf-theme,xtf-widget,layout`:
+
+
+
+*Now you can see the toolbar at the bottom, the active profiles highlighted
+in the profile row, and the diagnostic status. The page is annotated without
+being broken.*
+
+**With the layout profile active** — outlines show structure:
+
+
+
+*The layout profile adds dashed outlines to containers so you can see nesting
+depth, empty blocks, and spacing at a glance. Useful for catching alignment
+drift in slot shells and widget wrappers.*
+
+---
+
+## Core Concepts
+
+### 1. Overlay Profiles
+
+Profiles are layers of diagnostic CSS. Each one highlights a different
+category of issues. You combine them for the job at hand.
+
+| Profile | What it highlights |
+|---------|-------------------|
+| `html5` | Missing attributes, deprecated elements, empty blocks |
+| `xtf-theme` | Hardcoded colors, empty slots, dark mode breakage |
+| `xtf-widget` | Widget root classes, SVG dimensions, inline handlers |
+| `a11y` | Landmarks, labels, empty links/buttons, tabindex |
+| `layout` | Nesting depth, empty containers, layout shift risks |
+
+Activate with a query parameter:
+
+```
+/?holmes=xtf-theme,xtf-widget
+/?holmes=all
+/modules/cssholmes/admin/index.php?holmes=xtf-theme,a11y
+```
+
+Use them as layers, not all-or-nothing. For theme work, start with
+`xtf-theme,a11y,layout`. For widget work, use `xtf-widget,layout,html5`.
+
+### 2. Reading the Diagnostic Counts
+
+The toolbar shows error and warning counts:
+
+
+
+| Indicator | Color | Meaning |
+|-----------|-------|---------|
+| **E:** (red) | Red outline on page | Error — broken, invalid, or missing required attribute |
+| **W:** (orange/yellow) | Orange/yellow outline | Warning — likely problem or bad practice |
+
+The counts sum all visible diagnostic outlines on the current page across all
+active profiles. Click `clear` to dismiss them.
+
+### 3. The Toolbar
+
+The toolbar is your working surface. It groups into three tiers:
+
+**Navigate and understand:**
+- `inspect` — hover to see element details, click to lock selection
+- `measure` — show pixel distances between elements
+- `widget` — jump from any child to the nearest widget wrapper
+- `slot` — select the nearest ancestor carrying `[data-slot]`
+
+**Edit and experiment:**
+- `token` — preview color changes with token matching
+- `typo` — adjust font size, weight, line-height, alignment
+- `text` — make text content editable for quick experiments
+
+**Capture and share:**
+- `copy text` — copy a readable inspection summary (selector, metrics and context)
+- `copy json` — copy the inspection snapshot as JSON
+- `export sel` — export the full inspection with context
+- `undo` — revert the last local edit
+
+**Diagnose (third row):**
+- `overflow` — highlight every element with overflowing content
+- `z-index` — label rendered elements with nonzero computed z-index values
+- `grid` — show CSS Grid and Flexbox containers with column/row lines
+- `proto` / `deuter` / `trita` / `achro` — simulate color blindness types
+
+Keyboard shortcuts: `I` inspect, `M` measure, `T` token, `P` typography,
+`U` undo. They only work while the toolbar is open (not minimised), never
+together with Ctrl, Cmd or Alt (so Ctrl+P and Ctrl+U keep working), and
+never while you type in a form field. `Esc` leaves inspect and measure mode
+and clears the selection; minimising the toolbar does the same.
+
+### 4. The Admin Workbench
+
+The admin side is where inspection results become actual work.
+
+
+
+The workbench workflow:
+
+1. **Theme scan** — select a theme, run analyzers, review findings by category
+2. **Export/Import** — paste the review payload from `export sel` or the Local Changes `export` button into the workbench
+3. **Review** — accept or reject individual changes
+4. **Patch draft** — generate suggested edits with likely file targets
+5. **History** — compare scans over time to track regressions
+
+
+
+*Paste the `export sel` review payload or Local Changes export here. These contain
+a `changes` array that the workbench can review. The `copy json` snapshot is for
+inspection/debugging and is not accepted as a workbench import.*
+
+---
+
+## Quick Start for Designers
+
+This is the simplest useful workflow for designing or refining a theme.
+
+### Step 1. Open any page with cssHolmes
+
+Add the query parameter to the URL:
+
+```
+/?holmes=xtf-theme,a11y,layout
+```
+
+For widget-heavy pages:
+
+```
+/?holmes=xtf-theme,xtf-widget,layout
+```
+
+
+
+*Start with a realistic page — one with widgets, sidebar, and content — because
+it exercises the theme shell, widget output, and slot structure at the same time.*
+
+### Step 2. Inspect an element
+
+Click `inspect` in the toolbar (or press `I`), then hover any element. The
+toolbar shows live metrics: selector, size, position, margins, padding, font,
+color, theme, and — when applicable — the nearest widget and slot.
+
+
+
+*Click to lock the selection. The inspector panel shows everything you need
+to know: the full selector path, actual computed values, which theme is active,
+and the XTF mode.*
+
+Click a deeper element to see its specific properties:
+
+
+
+*Here the inspector shows the `div.xmf-testimonial` widget boundary, its slot
+context, and all computed styles. The Widget line tells you this is inside a
+recognized XMF widget.*
+
+### Step 3. Jump to the widget or slot boundary
+
+If you clicked a nested child — a paragraph, an icon, a span — the `widget`
+button selects the nearest recognized widget wrapper, such as `.xtf-slot-widget`,
+`[data-widget]`, or an `xmf-` root class. The `slot` button selects the nearest
+`[data-slot]` ancestor; a wrapper class alone does not identify a slot.
+
+This is the most useful XTF-specific improvement over browser devtools. It
+answers: "Am I editing the theme shell, the slot wrapper, or the widget itself?"
+
+### Step 4. Try a local edit
+
+Use:
+- `token` for color/token previews
+- `typo` for font size, line-height, weight, alignment, spacing
+- `text` for quick content experiments on leaf text nodes
+
+
+
+*The typography editor lets you tune font size, line-height, weight, spacing,
+and alignment before touching any CSS file. Especially useful for density
+tuning in admin tables and widget cards.*
+
+These overlay edits change the current page in your browser and can be undone.
+They do not write theme files or publish changes. The token editor changes the
+selected element's matching foreground/background properties and its local token
+record; it does not change the global CSS variable. Inspect the source declaration
+before applying an exported token patch in the workbench.
+
+### Step 5. Measure spacing
+
+Click `measure` (or press `M`), then select an element and hover another.
+cssHolmes draws measurement lines between them showing pixel distances.
+
+
+
+*Measure mode answers layout questions that are hard to judge by eye: spacing
+between cards, gaps inside slot shells, padding symmetry in admin panels.*
+
+### Step 6. Export the result
+
+When you find a useful change:
+
+- `copy json` copies the current inspection snapshot for inspection/debugging;
+ it has no `changes` array and cannot be imported into the workbench.
+- `export sel` copies a review payload containing the selected element's
+ inspection context and an `inspect` item in its `changes` array.
+- The Local Changes `export` button copies recorded edits as review items.
+
+
+
+*The `export sel` review payload keeps selector path, computed values, theme,
+widget, slot and matched tokens together. Use this payload for workbench review;
+use Local Changes export when you want to review the edits you recorded.*
+
+### Step 7. Review in the workbench
+
+Paste the review payload from `export sel` or Local Changes export into the admin
+workbench. Do not paste a `copy json` inspection snapshot. Review payloads provide:
+
+1. structured review items with likely target files
+2. patch drafts for supported recorded edits; inspection-only items supply context
+3. a shared record that designers and developers can both read
+
+
+
+*The server-side scan complements the live overlay. Manifest errors, missing
+tokens, template problems, and accessibility findings become structured
+review rows.*
+
+---
+
+## Quick Start for Developers
+
+### Theme build workflow
+
+1. Build or scaffold the XTF theme.
+2. Open the site with `?holmes=xtf-theme,layout,a11y`.
+3. Use `inspect`, `measure`, `widget`, and `slot` to verify rendered structure.
+4. Go to the admin workbench and run a theme scan.
+5. Review findings by analyzer: manifest, tokens, templates, accessibility.
+6. Use toolbar exports and workbench drafts to convert experiments into code.
+
+### Widget build workflow
+
+1. Render the widget in a realistic page or slot.
+2. Use `?holmes=xtf-widget,layout` overlay profiles.
+3. Inspect the root wrapper — confirm it has an `xmf-` prefixed class.
+4. Use `widget` to jump to the wrapper that should remain stable.
+5. Export inspection or local edits for follow-up.
+6. In the workbench, paste raw widget HTML into the widget scan card.
+7. Review widget-output findings before shipping.
+
+
+
+*The marketplace catalog is a useful real-world test target: cssHolmes can
+inspect actual widget cards rendered inside slot wrappers.*
+
+
+
+*Slot-aware views matter because many XTF problems are not inside the widget
+template itself, but in how the widget is placed, ordered, or reused across
+slots.*
+
+### Admin theme workflow
+
+cssHolmes runs on admin pages too. Use it for:
+
+- admin list views and table density
+- dashboard widget spacing
+- toolbar and header alignment
+- card layouts and icon presentation
+- accessibility checks in admin interactions
+
+Admin themes are where spacing drift, hardcoded colors, and typography
+inconsistencies accumulate fastest.
+
+---
+
+## Walkthrough: "What Is This Color?"
+
+This is the #1 use case when inheriting an existing theme. You see a color
+on the page and need to know: is it backed by a token? Which one? Should I
+change `theme.json` or component CSS?
+
+1. Activate `?holmes=xtf-theme` on the page.
+
+2. Click `inspect`, then click the colored element.
+
+3. Look at the **Color** line in the inspector. If a token matches, you will
+ see it listed in the token field.
+
+4. A listed token has a normalized value matching the element's computed
+ foreground or background color. For example, `--xtf-color-primary` may
+ match `rgb(37, 99, 235)` even when the declaration uses a literal color.
+ Inspect the winning CSS declaration in browser developer tools before
+ changing a global token; the match does not prove that declaration uses it.
+
+5. No match means no loaded manifest token matched those computed colors.
+ The declaration might use another CSS variable, inheritance or a literal.
+ Inspect its source; absence of a match does not itself trigger an overlay warning.
+
+6. Use the `token` editor to preview a replacement on the selected element's
+ matching color properties. It records a local token edit for review; it does
+ not suggest a CSS variable reference or update every use of that token.
+
+
+
+*The token editor shows the matched token key, editable value and color picker.
+Its value starts from the loaded manifest and changes with local edits; it is
+not a live view of the saved `theme.json` after a preview.*
+
+---
+
+## Walkthrough: Inspecting an Element Step by Step
+
+
+
+*Starting point. The toolbar is visible, inspect mode is ready, no element
+is selected yet.*
+
+
+
+*Hover any element. The inspector shows live metrics in the toolbar panel:
+selector path, dimensions, computed styles. Nothing is locked yet — move the
+mouse to explore different elements.*
+
+
+
+*Click to lock. The element is now selected. You can read its full details,
+use widget/slot jumps, or open editors. The selection stays locked until you
+click elsewhere or press Esc.*
+
+
+
+*With the element locked, `copy text` copies a readable inspection summary;
+`copy json` copies the inspection snapshot as JSON. Neither button copies only
+the element's text content.*
+
+
+
+*The `text` tool opens a prompt to edit the element's text content directly.
+This is for quick content experiments — the change is local and undoable.*
+
+---
+
+## When cssHolmes Becomes Indispensable
+
+### You inherit a theme with inconsistent colors
+
+1. `inspect` shows each element's color
+2. Token matching lists equal resolved values; inspect CSS declarations to confirm their source
+3. `token` editor lets you preview a change safely
+4. Export + workbench creates a patch draft for `theme.json`
+
+Without this, the work is guesswork across CSS files and templates.
+
+### A widget looks correct in one slot but broken in another
+
+
+
+*The same pricing widget placed in two slots. In the narrow sidebar (left),
+the cards stack vertically. In the wide content slot (right), they display
+side-by-side as designed. cssHolmes helps you see why: `widget` shows the
+wrapper, `slot` shows the container width, `measure` confirms the 280px
+constraint.*
+
+1. `widget` jumps to the widget wrapper in each context
+2. `slot` shows the containing slot's constraints
+3. `measure` reveals actual spacing differences between contexts
+4. The widget scan validates the HTML output independently
+
+This is exactly the kind of issue where generic devtools are not enough.
+
+### You are building a new admin theme
+
+1. cssHolmes runs on the admin side
+2. `typo` helps tune density quickly across dense tables
+3. `measure` catches awkward spacing between cards and panels
+4. `a11y` profile highlights focus and structural issues
+5. Export/import gives you a repeatable review loop
+
+### A designer and developer need a shared language
+
+The designer exports the inspected element with selector, slot, widget, token,
+and metrics. The developer sees exactly what to change and where. The workbench
+generates patch suggestions. No more screenshots with arrows and vague comments.
+
+---
+
+## Suggested Profile Combinations
+
+| Job | Profiles |
+|-----|----------|
+| New XTF theme | `xtf-theme,a11y,layout` |
+| Widget development | `xtf-widget,layout,html5` |
+| Final QA pass | `xtf-theme,xtf-widget,a11y,layout` |
+| Admin theme refinement | `xtf-theme,a11y,layout` |
+| Generic markup check | `html5` |
+
+---
+
+## Diagnostic Tools
+
+The third toolbar row contains tools that go beyond element inspection.
+These help with layout debugging, stacking conflicts, and accessibility
+validation across the entire page.
+
+### Overflow Detection
+
+Click `overflow` to scan every element on the page for content that
+overflows its container. Elements where `scrollWidth > clientWidth` or
+`scrollHeight > clientHeight` get a red outline and a label showing the
+overflow direction.
+
+The button shows the count: `overflow (3)` means three elements have
+overflow problems on this page.
+
+**When to use it:**
+
+- After placing a widget in a narrow slot (sidebar, footer) to check
+ whether its content fits.
+- On admin pages with dense tables that may exceed their container.
+- After changing a theme's `layout.sidebar-width` token to verify nothing
+ broke.
+
+**Example — pricing widget in a sidebar:**
+
+You placed `xmf:pricing` in the sidebar slot. The content area looks fine,
+but did the sidebar version overflow? Click `overflow`. If the pricing card
+container is wider than 280px, it gets a red `overflow x` label instantly.
+
+This is the automated version of the manual "scroll right and squint" test.
+
+### Z-Index Overlay
+
+Click `z-index` to label rendered elements whose computed z-index is neither
+`auto` nor `0`. Elements with both zero width and height, plus the cssHolmes
+toolbar and inspector, are skipped.
+Colors help scanning but can repeat for different values; read the numeric labels.
+
+The button shows the number of labels: `z-index (12)` means twelve elements
+were labeled. This is not a complete stacking-context analysis: zero-valued
+contexts are omitted, and values in different contexts are not directly comparable.
+
+**When to use it:**
+
+- When a dropdown menu disappears behind a widget or slot container.
+- When the admin sidebar overlaps modal content.
+- When a sticky header covers a fixed toolbar.
+- Before shipping a theme to verify that z-index values are intentional
+ and not escalating (100 → 999 → 9999 → 99999).
+
+**Example — admin dashboard:**
+
+Open the admin dashboard with `?holmes=all` and click `z-index`. You will
+see labels like `z:10` on the sidebar, `z:100` on the header, `z:1000` on
+dropdown menus. If a widget badge shows `z:99999`, that is a red flag — it
+may conflict with modals or overlays in the same stacking context. Check the
+ancestor contexts in browser developer tools before changing it.
+
+### CSS Grid and Flexbox Overlay
+
+Click `grid` to find every CSS Grid and Flexbox container on the page. Each
+one gets a dashed outline and a label showing its type:
+
+- **Grid containers** show as purple outlines with labels like `grid 3-col`
+ (showing the column count). Vertical and horizontal grid lines are drawn
+ inside the container to visualize the track layout.
+- **Flex containers** show as teal outlines with labels like `flex row` or
+ `flex column` showing the flex direction.
+
+The button shows the count: `grid (8)` means eight Grid or Flex containers
+were found on the page.
+
+**When to use it:**
+
+- To see the layout structure of a theme at a glance — which parts use Grid,
+ which use Flexbox, and how many columns each Grid has.
+- When debugging why a widget renders differently in two slots — the parent
+ slot may use Grid in one place and Flexbox in another.
+- To verify that admin dashboard layouts use consistent column patterns.
+- When a theme switches from a 3-column content grid to a 2-column sidebar
+ layout, the overlay shows exactly where the change happens.
+
+**Example — front1 theme layout:**
+
+Open the front1 showcase page and click `grid`. You will see the main
+content area as a Grid container (perhaps `grid 2-col` for sidebar + content),
+the widget card section as a Flex container (`flex row wrap`), and the footer
+links as another Flex row. This immediately shows the layout architecture
+without reading any CSS.
+
+**Example — widget marketplace catalog:**
+
+The widget card grid in the marketplace uses CSS Grid. Click `grid` and you
+see the exact column tracks — if the cards are in a `grid 3-col` layout, the
+purple lines show the column boundaries. If a card spans two columns
+unexpectedly, the mismatch between the grid lines and the card borders makes
+it obvious.
+
+### Color Blindness Simulation
+
+The four simulation buttons apply SVG color matrix filters to the entire
+page:
+
+| Button | Simulates | What it affects |
+|--------|-----------|-----------------|
+| `proto` | Protanopia | Red-blind — reds appear dark/brownish |
+| `deuter` | Deuteranopia | Green-blind — greens shift toward brown/yellow |
+| `trita` | Tritanopia | Blue-blind — blues shift toward cyan/green |
+| `achro` | Achromatopsia | Total color blindness — everything is grayscale |
+
+Click one to activate, click again to deactivate. Only one simulation can
+be active at a time.
+
+**When to use it:**
+
+- To verify that color-coded status indicators (draft/published/archived,
+ success/warning/error badges) are distinguishable without relying on
+ color alone.
+- To check that links are recognizable without depending only on their
+ blue color.
+- To validate that charts, graphs, or colored category badges in widgets
+ use patterns or labels in addition to color.
+
+**Example — status badges in a module list:**
+
+An admin page shows module status as colored dots: green for active, red
+for disabled, yellow for needs update. Click `proto` (protanopia). If the
+red and green dots now look nearly identical, the design fails for
+red-blind users — about 8% of males. The fix: add a checkmark icon to
+active and an X icon to disabled, not just color.
+
+**Example — theme color palette:**
+
+Open the front1 theme page and click `achro` (achromatopsia). The entire
+page renders in grayscale. If two adjacent sections — say the hero and the
+content area — become indistinguishable, the theme needs better contrast
+or structural borders between regions.
+
+### Combining diagnostic tools with profiles
+
+These tools work alongside overlay profiles. A typical QA pass:
+
+1. Activate `?holmes=xtf-theme,xtf-widget,layout`
+2. Click `overflow` to find layout problems
+3. Click `z-index` to check stacking
+4. Click `proto` and `deuter` to test color accessibility
+5. Use `inspect` and `measure` on any flagged elements to get details
+6. Export findings to the admin workbench
+
+---
+
+## Recommended Workflow Loop
+
+For the best results, treat cssHolmes as a loop:
+
+1. **Scan** — run the server-side analyzers on the theme
+2. **Inspect** — use the live overlay to explore flagged areas
+3. **Preview** — try local changes with the token, typo, and text editors
+4. **Export** — capture inspection snapshots and local edits as JSON
+5. **Review** — import into the workbench, accept or reject changes
+6. **Patch** — generate draft patches with file targets
+7. **Rescan** — verify the fixes reduced the finding count
+
+This loop works for XTF because the real problem is rarely just CSS. It is
+usually the combination of theme manifest, token choice, template structure,
+slot placement, and widget output. cssHolmes can see across all of those.
+
+---
+
+## Current Limitations
+
+1. Toolbar edits are preview edits, not direct file writes.
+2. Patch drafts are guidance, not automatic safe commits.
+3. Overlay token matching requires loaded `theme.json` token values that match
+ the element's normalized computed `color` or `backgroundColor`. A literal CSS
+ color can match too; the declaration does not need to reference a custom
+ property. A value match does not identify the declaration's source.
+4. Widget scan works best with representative pasted HTML, not full
+ registry-driven widget introspection.
+5. Browser-level manual verification is still important before shipping.
+
+These are acceptable constraints because they keep the tool safe while still
+making it immediately useful.
+
+---
+
+## Reference: Test Suites
+
+cssHolmes includes two test suite pages:
+
+**Legacy HTML5 Suite** — the original holmes.css diagnostic fixtures:
+
+
+
+*Links, images, form attributes, deprecated elements, empty blocks — all
+rendered with intentional problems so you can see what each diagnostic looks
+like.*
+
+**Modern XTF/XMF Suite** — practical samples for token-aware work:
+
+
+
+*Feature cards, widget previews, admin-like panels, warning cards, forms,
+accessibility samples, and edge cases. Use this page to learn what each
+profile highlights before running it on a real site.*
+
+---
+
+## What Comes Next
+
+The next expansions that would strengthen this workflow:
+
+1. Direct token patch application to `theme.json`
+2. Richer widget analyzer coverage
+3. Typography export mapped to likely CSS targets automatically
+4. Image swap tooling for widget and card design
+5. Scan history comparison across theme revisions
+
+Even before those arrive, cssHolmes is already useful enough to become part
+of the normal XOOPS XTF workflow.
diff --git a/docs/TUTORIAL-xStyles.md b/docs/TUTORIAL-xStyles.md
new file mode 100644
index 0000000..5310127
--- /dev/null
+++ b/docs/TUTORIAL-xStyles.md
@@ -0,0 +1,99 @@
+# Improve your XOOPS theme with cssHolmes and xStyles
+
+**Inspect an example, adjust its styles, compare the result, then publish when ready.**
+
+xStyles puts common headings, tables, forms and other page elements in one
+gallery. cssHolmes adds inspection and visual editing. Together, they give you
+a repeatable place to improve a theme without hunting through different pages
+or rewriting its original stylesheets.
+
+## Before you start
+
+Install or update both modules, then open **xStyles → Go to module** to reach
+the frontend gallery. Log in as a cssHolmes module administrator, or use an
+account with **Overlay** and **Edit** permissions. Publishing also requires
+**Workbench** permission; downloading CSS or portable style sets requires
+**Export** permission. These instructions cover frontend themes.
+
+The screenshots below show the actual designer and preview controls with an
+isolated demonstration example. Your theme supplies the appearance of the
+examples; its fonts and colors will differ.
+
+## 1. Inspect an example
+
+Choose **Typography** in xStyles and select a heading example. Click
+**Inspect example** to open cssHolmes with its first relevant element selected
+and **Tokens and contrast** expanded. Use **Pick element** to choose another
+element within the example.
+
+Check the **Selector** and matching-element count: a rule may affect several
+elements on real pages. Prefer a reusable theme selector over a gallery-only ID.
+For a low measured contrast ratio, **Adjust text color** or **Adjust background
+color** takes you to the corresponding editing control.
+
+
+
+*Inspect the selected element before deciding what to change. Contrast readings
+are estimates; they do not certify the whole theme's accessibility.*
+
+## 2. Edit and compare before publishing
+
+Click **Edit styles**, or continue in the open designer. Try changing the
+heading's **Font size**, for example from `22px` to `30px`, and **Text color**
+from pale gray to `#2255aa`.
+
+Expand **Preview your changes** and select **Published vs draft**. Both panes
+show the same example and theme at the same viewport width. The published pane
+keeps the saved appearance; the draft pane follows your edits. **Undo**, **Redo**
+and **Discard draft** let you try alternatives before deciding.
+
+
+
+*Compare a proposed change with the published result without switching tabs or publishing each experiment.*
+
+## 3. Check three screen sizes together
+
+Choose **Draft at three screen sizes** to preview **360, 768 and 1280 CSS pixels**.
+Use each pane's scrollbars to explore wider content. In the designer, choose a
+screen-size scope when a change should apply only to mobile, tablet or desktop.
+
+
+
+*Here the mobile draft uses 40px while the wider drafts retain 30px. The different
+sizes illustrate scoped editing; choose values that suit your own design.*
+
+These private draft panes belong to **Preview your changes**. The ordinary
+xStyles **Compare themes** and **Responsive preview** panels show published
+styles only.
+
+## 4. Publish deliberately—and reuse good work
+
+When satisfied, click **Save to theme**. This publishes the overrides for the
+selected theme and can change what visitors see. The private panes refresh after
+saving. Check a representative real page as well as the gallery.
+
+To keep an alternative for later, save a **named set** in the designer's library.
+Saving a set does **not** publish it. See [Theme sets](theme-sets.md) for reuse,
+import and export.
+
+Drafts stay in the current page until saved. Closing the designer retains the
+draft there; navigating away loses unsaved changes. Saved overrides live outside
+the theme's source files and require cssHolmes to remain active, unless you
+export and integrate the CSS yourself.
+
+## Why this makes theme work more productive
+
+| Task | What the combined workflow saves |
+|---|---|
+| Find a useful test page | xStyles gathers common elements in one searchable gallery. |
+| Locate and adjust a style | Inspect/Edit connects the example directly to the designer. |
+| Judge an experiment | Published and draft panes show the difference together. |
+| Check responsive behavior | Three widths update from the same draft. |
+| Reuse a successful design | Named sets preserve alternatives without publishing them. |
+
+For example, you can inspect a heading, adjust its size and color, compare the
+saved appearance, check three widths, and publish once—all from the same page.
+The benefit is fewer repeated navigation, resize and save cycles, rather than
+an unmeasured promise of a particular speed increase.
+
+For more controls and recovery options, read the [visual designer guide](visual-designer.md).
diff --git a/docs/changelog.txt b/docs/changelog.txt
index de772a6..0d0015d 100644
--- a/docs/changelog.txt
+++ b/docs/changelog.txt
@@ -1,20 +1,92 @@
-
1.3 Beta 1 [WORK IN PROGRESS - NOT RELEASED]
Dev: XOOPS 2.5.11, PHP 7.4.8
+
3.3.0 Alpha 1 [2026-10-26]
+Requires PHP 8.4+. Alpha prerelease for testing; see docs/compatibility.md for tested environments and limitations.
+
+- Added a visual theme designer with scoped selectors, colors, typography, spacing, live preview, undo/redo and explicit Save to theme publication.
+- Added private per-theme override storage, export, previous-save restoration and optimistic conflict checks without rewriting theme source files.
+- Added a named style-set library with preview, categories, likes and validated portable import/export; saving a set does not publish it.
+- Added xStyles example inspection/editing, private published-versus-draft comparison and three-width draft previews.
+- Added contrast-to-color controls and temporary selected-element highlighting.
+- Preserved the editing revision across library refreshes so concurrent set updates are rejected safely.
+- Kept selected palette names and swatches visible after library refreshes across Chromium versions.
+- Added shared QA runner, PHP 8.4/8.5 CI, optional Qodana and release packaging without module-local development dependencies.
+- Moved workbench histories to private storage with migration, locked updates and atomic writes; removed bundled development history.
+- Prevented unsafe imported patches and rollback over later template edits; fixed literal CSS replacements and scan diagnostics.
+- Enforced designer export permission, protected manifest edits from external symlinks, and bounded import history without deleting rollback records.
+- Corrected named-color and image-dimension checks, form-label associations, missing-landmark counters, dark-mode detection and widget-root highlighting.
+- Escaped inspected page text and exported changes in overlay HTML, derived diagnostic stylesheet URLs from the module script, and simplified font-family validation.
+- Avoided repeated core initialization during install, made uninstall backup names unique, and removed duplicate GD status output.
+- Supported trusted deployment symlinks while retaining storage-file checks; corrected legacy copy and database helper failures.
+- Excluded local workbench JSON records from release archives so upgrades do not overwrite a site's saved workbench data.
+- Read-only resolved token inspection and conservative rendered text contrast estimates.
+- XTF data-theme mode support in draft and public CSS; content-based stylesheet ETags.
+- Kept ordinary xStyles comparison frames published-only with editor assets suppressed; private draft panes accept only the matching theme.
+- Added XMF 2 / XTF package contract, diagnostics and frame integration checks.
+- Added an illustrated cssHolmes + xStyles tutorial, shared-tool contributor instructions and explicit compatibility documentation.
+- Verified clean ZIP installation and upgrade from 3.0.0 on a disposable XOOPS 2.7.4-RC2 site: configuration, existing permissions and saved designer overrides are preserved.
+
+Earlier unreleased development included in this release:
+- added permission checks to all admin workbench pages and actions (mamba)
+- added a new "cssHolmes Admin" permission for granular control over who can access the admin workbench (mamba)
+- added **Diagnose (third row):**
+ - `overflow` — highlight every element with overflowing content
+ - `z-index` — show z-index values as colored labels on all positioned elements
+ - `grid` — show CSS Grid and Flexbox containers with column/row lines
+ - `proto` / `deuter` / `trita` / `achro` — simulate color blindness types
+- added CSS Grid and Flexbox diagnostics to the front-end inspection overlay (mamba)
+- changed install defaults: Use Overlay and Use Diagnostics now go to the Webmasters group only; earlier versions also granted them to Registered Users (mamba)
+- updates do not change existing permissions: when Registered Users still hold the old overlay/diagnostics grants, the update log and the admin Index and Permissions pages show a notice so the administrator can remove them (mamba)
+- fixed the "Overlay query key" setting description, which claimed the overlay was for administrators only (english, french) (mamba)
+- fixed keyboard shortcuts I, M, T, P, U: they now ignore Ctrl/Cmd/Alt (Ctrl+P and Ctrl+U work again), never fire while typing, only work while the toolbar is open, and only block the key they handle (mamba)
+- changed Esc to leave inspect and measure mode and close the editors; minimising the toolbar does the same, so a minimised toolbar no longer captures clicks (mamba)
+- fixed the E/W counters ignoring html5 findings: every profile rule now sets a --holmes-{profile} severity marker that the counters read, instead of matching outline colours (mamba)
+- fixed the html5 body attribute rules (background, *margin, bgproperties), which never matched because the overlay puts holmes-debug on (mamba)
+- changed the html5 profile to treat table summary as obsolete (grey) instead of requiring it (red) (mamba)
+- added Smarty-aware template reading to the analyzers: Smarty comments and tags are neutralised before HTML checks, so is no longer cut at the first }> (mamba)
+- added include resolution to the analyzers: <{include file="$theme_name/tpl/x.tpl"}>, `$xoTheme->folderName`, |cat: chains and plain relative names are followed, so skip link, main, lang and module header checks see the included partials; missing theme includes are reported with file and line (mamba)
+- changed accessibility element checks (img alt, empty links and buttons, form labels, tabindex) to report every occurrence with file and line, to ignore without href (fragment targets) and inputs wrapped in
+
+*Inspect the selected element before deciding what to change. Contrast readings
+are estimates; they do not certify the whole theme's accessibility.*
+
+## 2. Edit and compare before publishing
+
+Click **Edit styles**, or continue in the open designer. Try changing the
+heading's **Font size**, for example from `22px` to `30px`, and **Text color**
+from pale gray to `#2255aa`.
+
+Expand **Preview your changes** and select **Published vs draft**. Both panes
+show the same example and theme at the same viewport width. The published pane
+keeps the saved appearance; the draft pane follows your edits. **Undo**, **Redo**
+and **Discard draft** let you try alternatives before deciding.
+
+
+
+*Compare a proposed change with the published result without switching tabs or publishing each experiment.*
+
+## 3. Check three screen sizes together
+
+Choose **Draft at three screen sizes** to preview **360, 768 and 1280 CSS pixels**.
+Use each pane's scrollbars to explore wider content. In the designer, choose a
+screen-size scope when a change should apply only to mobile, tablet or desktop.
+
+
+
+*Here the mobile draft uses 40px while the wider drafts retain 30px. The different
+sizes illustrate scoped editing; choose values that suit your own design.*
+
+These private draft panes belong to **Preview your changes**. The ordinary
+xStyles **Compare themes** and **Responsive preview** panels show published
+styles only.
+
+## 4. Publish deliberately—and reuse good work
+
+When satisfied, click **Save to theme**. This publishes the overrides for the
+selected theme and can change what visitors see. The private panes refresh after
+saving. Check a representative real page as well as the gallery.
+
+To keep an alternative for later, save a **named set** in the designer's library.
+Saving a set does **not** publish it. See [Theme sets](theme-sets.md) for reuse,
+import and export.
+
+Drafts stay in the current page until saved. Closing the designer retains the
+draft there; navigating away loses unsaved changes. Saved overrides live outside
+the theme's source files and require cssHolmes to remain active, unless you
+export and integrate the CSS yourself.
+
+## Why this makes theme work more productive
+
+| Task | What the combined workflow saves |
+|---|---|
+| Find a useful test page | xStyles gathers common elements in one searchable gallery. |
+| Locate and adjust a style | Inspect/Edit connects the example directly to the designer. |
+| Judge an experiment | Published and draft panes show the difference together. |
+| Check responsive behavior | Three widths update from the same draft. |
+| Reuse a successful design | Named sets preserve alternatives without publishing them. |
+
+For example, you can inspect a heading, adjust its size and color, compare the
+saved appearance, check three widths, and publish once—all from the same page.
+The benefit is fewer repeated navigation, resize and save cycles, rather than
+an unmeasured promise of a particular speed increase.
+
+For more controls and recovery options, read the [visual designer guide](visual-designer.md).
diff --git a/docs/changelog.txt b/docs/changelog.txt
index de772a6..0d0015d 100644
--- a/docs/changelog.txt
+++ b/docs/changelog.txt
@@ -1,20 +1,92 @@
-