ultimate-jekyll-manager 1.2.0 → 1.2.2

package/docs/_legacy-claude-md.md

@@ -1,1832 +0,0 @@
-# Ultimate Jekyll Manager
-
-## Project Overview
-
-Ultimate Jekyll Manager is a template framework that consuming projects install as an NPM module to build Jekyll sites quickly and efficiently. It provides best-practice configurations, default components, themes, and build tools.
-
-**Important:** This is NOT a standalone project. You cannot run `npm start` or `npm run build` directly in this repository.
-
-**DO NOT run `npm start`, `npm run build`, or any dev server commands.** The user already has a development server running in a consuming project. Running these commands here would either fail or create duplicate servers unnecessarily.
-
-## Project Structure
-
-### Directory Organization
-- `src/gulp/tasks` - Gulp tasks for building Jekyll sites
-- `src/defaults/src` - Default source files (editable by users, copied to consuming project's `src/`)
-- `src/defaults/dist` - Default distribution files (not editable by users, copied to consuming project's `dist/`)
-- `src/assets/css` - Stylesheets (global, pages, themes)
-- `src/assets/js` - JavaScript modules (core, pages, libraries)
-- `src/assets/themes` - Theme SCSS and JS files
-
-### Consuming Project Structure
-- `src/` - Compiled to `dist/` via npm
-- `dist/` - Compiled to `_site/` via Jekyll
-
-## Local Development
-
-The local development server URL is stored in `.temp/_config_browsersync.yml` in the consuming project's root directory. Read this file to determine the correct URL for browsing and testing. By default, use "https://192.168.86.69:4000".
-
-### Connecting to Local Firebase Emulators
-
-Set the `FIREBASE_EMULATOR_CONNECT` environment variable to `true` to connect the frontend to local Firebase services (Auth, Firestore, Functions, etc.):
-
-```bash
-FIREBASE_EMULATOR_CONNECT=true npm start
-```
-
-This value is written to `.temp/_config_browsersync.yml` under `web_manager.env.FIREBASE_EMULATOR_CONNECT` and made available to the frontend at build time.
-
-### PurgeCSS
-
-PurgeCSS runs automatically in production builds and can be enabled locally with `UJ_PURGECSS=true`. Consuming projects can add custom safelist patterns via `config/ultimate-jekyll-manager.json` under `sass.purgecss.safelist`:
-
-```json5
-{
-  sass: {
-    purgecss: {
-      safelist: {
-        standard: [],   // Matches against the full class name
-        deep: [],       // Matches including child selectors (e.g., pseudo-selectors like :checked)
-        greedy: [],     // Matches anywhere in the selector string
-        keyframes: [],  // Preserves @keyframes animations by name
-      },
-    },
-  },
-}
-```
-
-**All entries are regex strings** — each gets converted to `new RegExp(entry)`. This means:
-
-| Pattern | Matches | Does NOT match |
-|---------|---------|----------------|
-| `"^dot$"` | `dot` | `dotted`, `polkadot` |
-| `"^chat-"` | `chat-bubble`, `chat-input` | `live-chat` |
-| `"fw-semibold"` | `fw-semibold`, `fw-semibold-custom` | (matches loosely) |
-
-**Use `^` and `$` anchors for exact matches.** Without them, the pattern matches any class *containing* the string.
-
-**Example:**
-```json5
-{
-  sass: {
-    purgecss: {
-      safelist: {
-        standard: ["^dot$", "^fw-semibold$", "^chat-"],
-        deep: [":focus-within"],
-        greedy: ["^chat-"],
-        keyframes: ["chat-typing-bounce"],
-      },
-    },
-  },
-}
-```
-
-## Asset Organization
-
-### Ultimate Jekyll Manager Files (THIS project)
-
-**CSS:**
-- `src/assets/css/ultimate-jekyll-manager.scss` - Main UJ stylesheet (provides core styles)
-- `src/assets/css/global/` - Global UJ styles
-- `src/assets/css/pages/` - Page-specific styles provided by UJ
-  - Format: `src/assets/css/pages/[page-name]/index.scss`
-  - Example: `src/assets/css/pages/download/index.scss`
-
-**JavaScript:**
-- `src/assets/js/ultimate-jekyll-manager.js` - Main UJ JavaScript entry point (provides core functionality)
-- `src/assets/js/core/` - Core UJ modules
-- `src/assets/js/pages/` - Page-specific JavaScript provided by UJ
-  - Format: `src/assets/js/pages/[page-name]/index.js`
-  - Example: `src/assets/js/pages/download/index.js`
-- `src/assets/js/libs/` - UJ library modules (prerendered-icons, form-manager, authorized-fetch, etc.)
-
-**Default Pages & Layouts:**
-
-UJ provides default page templates and layouts in `src/defaults/dist/` that are copied to consuming projects. These are NOT meant to be edited by users.
-
-- Format: `src/defaults/dist/_layouts/themes/[theme-id]/frontend/pages/[page-name].html`
-- Examples:
-  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/download.html`
-  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/pricing.html`
-  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/payment/checkout.html`
-  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/payment/confirmation.html`
-  - `src/defaults/dist/_layouts/themes/classy/frontend/pages/contact.html`
-- Core layouts:
-  - `src/defaults/dist/_layouts/core/root.html` - Root HTML wrapper
-  - `src/defaults/dist/_layouts/themes/[theme-id]/frontend/core/base.html` - Theme base layout
-
-**Complete UJ Page Example:**
-- **HTML:** `src/defaults/dist/_layouts/themes/classy/frontend/pages/download.html`
-- **CSS:** `src/assets/css/pages/download/index.scss`
-- **JS:** `src/assets/js/pages/download/index.js`
-
-These files serve as blueprints and reference implementations. When building custom pages in consuming projects, reference these for patterns and best practices.
-
-**IMPORTANT:** Consuming projects CAN create files with the same paths in their own `src/` directory to override UJ defaults, but this should ONLY be done when absolutely necessary. Prefer using `src/pages/` and `src/_layouts/` for custom pages instead of overriding UJ default files.
-
-### Section Configuration Files (JSON)
-
-UJ provides JSON configuration files for common sections like navigation and footer. These JSON files are consumed by corresponding HTML templates during the build process.
-
-**Configuration Files:**
-- `src/defaults/src/_includes/frontend/sections/nav.json` - Navigation configuration
-- `src/defaults/src/_includes/frontend/sections/footer.json` - Footer configuration
-- `src/defaults/src/_includes/global/sections/account.json` - Account dropdown configuration (shared across frontend nav, backend topbar, admin topbar)
-
-**How It Works:**
-1. JSON files contain structured data (links, labels, settings)
-2. HTML templates in `src/defaults/dist/_includes/themes/[theme-id]/` read and render this data
-3. The build process converts `.json` → data loaded by `.html` templates
-
-**Customizing Navigation/Footer:**
-
-Consuming projects should create their own JSON files in `src/_includes/frontend/sections/`:
-- `src/_includes/frontend/sections/nav.json`
-- `src/_includes/frontend/sections/footer.json`
-
-### Account Dropdown (Shared Component)
-
-The account dropdown (avatar + user info + menu items) is a shared component used across the frontend nav, backend topbar, and admin topbar. It is defined once and included everywhere.
-
-**Data Source:** `src/defaults/src/_includes/global/sections/account.json`
-
-This is the single source of truth for account dropdown menu items. Consuming projects can override it by creating `src/_includes/global/sections/account.json`.
-
-**Example: account.json**
-```json5
-{
-  dropdown: [
-    { label: 'Account', href: '/account#profile', icon: 'user-gear' },
-    { label: 'Dashboard', href: '/dashboard', icon: 'gauge-high' },
-    { divider: true, attributes: [['data-wm-bind', '@show auth.account.roles.admin']] },
-    { label: 'Admin Panel', href: '/admin/dashboard', icon: 'shield-halved', attributes: [['data-wm-bind', '@show auth.account.roles.admin']] },
-    { divider: true },
-    { label: 'Sign Out', icon: 'arrow-right-from-bracket', class: 'auth-signout-btn text-danger' }
-  ]
-}
-```
-
-**Include:** `src/defaults/dist/_includes/themes/classy/global/sections/account.html`
-
-This renders the full account dropdown: avatar button with profile photo, user info header (displayName + email), and the menu items from `account.json`.
-
-**Parameters:**
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `size` | `md` | Avatar size class (`sm`, `md`, `lg`) |
-| `attributes` | none | Array of `[name, value]` attribute pairs for the dropdown wrapper |
-
-**Usage in templates:**
-```liquid
-{% include themes/classy/global/sections/account.html size="md" attributes=action.attributes %}
-```
-
-**How it's wired into nav/topbar:**
-
-In `nav.json` or `topbar.json`, set `type: 'account'` on an action — the rendering templates detect this type and include the shared account dropdown automatically. No `dropdown` array is needed on the action:
-
-```json5
-{
-  type: 'account',
-  attributes: [
-    ['data-wm-bind', '@show auth.user'],
-    ['hidden', '']
-  ],
-}
-```
-
-**File Locations:**
-
-| Purpose | Path |
-|---------|------|
-| Account data (SSOT) | `src/defaults/src/_includes/global/sections/account.json` |
-| Account include | `src/defaults/dist/_includes/themes/classy/global/sections/account.html` |
-| Frontend nav (uses include) | `src/defaults/dist/_includes/themes/classy/frontend/sections/nav.html` |
-| Backend topbar (uses include) | `src/defaults/dist/_includes/themes/classy/backend/sections/topbar.html` |
-| Admin topbar (wraps backend) | `src/defaults/dist/_includes/themes/classy/admin/sections/topbar.html` |
-
-**Example: Footer Configuration**
-
-```json
-{
-  logo: {
-    href: '/',
-    class: 'filter-adaptive',
-    text: '{{ site.brand.name }}',
-    description: '{{ site.meta.description }}',
-  },
-  links: [
-    {
-      label: 'Company',
-      href: null,
-      links: [
-        {
-          label: 'About Us',
-          href: '/about',
-        },
-        {
-          label: 'Pricing',
-          href: '/pricing',
-        },
-      ],
-    },
-  ],
-  socials: {
-    enabled: true,
-  },
-  copyright: {
-    enabled: true,
-    text: null,
-  },
-}
-```
-
-**Note:** These are JSON5 files (support comments, trailing commas, unquoted keys). The corresponding HTML templates automatically process these files during the build.
-
-### Customizing Default Pages via Frontmatter
-
-**BEST PRACTICE:** UJ default pages are designed to be customized through frontmatter WITHOUT writing any HTML. Consuming projects can create a simple page that includes ONLY frontmatter to configure the default page's behavior.
-
-**How It Works:**
-1. UJ default pages use `page.resolved` to access merged frontmatter (site → layout → page)
-2. **IMPORTANT:** Before customizing, READ the UJ default page in `src/defaults/dist/_layouts/` to understand available frontmatter options and how they're used
-3. Consuming projects create a page in `src/pages/` with custom frontmatter
-4. The page uses a UJ layout (e.g., `blueprint/pricing`)
-5. Frontmatter overrides default values without any HTML
-
-**Example: Customizing the Pricing Page**
-
-**Step 1:** Read the UJ default pricing page to see available frontmatter options:
-- File: `src/defaults/dist/_layouts/themes/classy/frontend/pages/pricing.html`
-- Look for frontmatter at the top and how `page.resolved.pricing` is used in the HTML
-
-**Step 2:** In consuming project, create `src/pages/pricing.html`:
-
-```yaml
----
-### ALL PAGES ###
-layout: blueprint/pricing
-permalink: /pricing
-
-### PAGE CONFIG ###
-pricing:
-  price_per_unit:
-    enabled: true
-    feature_id: "credits"
-    label: "credit"
-  plans:
-    - id: "basic"
-      name: "Basic"
-      tagline: "best for getting started"
-      url: "/download"
-      pricing:
-        monthly: 0
-        annually: 0
-      features:
-        - id: "credits"
-          name: "Credits"
-          value: 1
-          icon: "sparkles"
-    ...
----
-```
-
-That's it! No HTML needed. The UJ pricing layout reads `page.resolved.pricing` and renders the plans accordingly.
-
-**When to Use Frontmatter Customization:**
-- ✅ Customizing UJ default pages (pricing, contact, download, etc.)
-- ✅ Changing configuration without touching HTML
-- ✅ Maintaining upgradability when UJ updates
-
-**When to Create Custom Pages:**
-- ❌ Building entirely new page types
-- ❌ Needing custom HTML structure
-- ❌ Pages with unique layouts not provided by UJ
-
-### Consuming Project Files
-
-**CSS:**
-- `src/assets/css/main.scss` - Site-wide custom styles (runs on every page, edits by consuming project)
-- `src/assets/css/pages/` - Page-specific custom styles
-  - Format: `src/assets/css/pages/[page-name]/index.scss`
-
-**JavaScript:**
-- `src/assets/js/main.js` - Site-wide custom JavaScript (runs on every page, edits by consuming project)
-- `src/assets/js/pages/` - Page-specific custom JavaScript
-  - Format: `src/assets/js/pages/[page-name]/index.js`
-
-**Pages & Layouts:**
-- `src/pages/` - Individual page HTML/Markdown files
-- `src/_layouts/` - Custom layouts for the consuming project
-
-**Asset Loading:** Page-specific CSS/JS files are automatically included based on the page's canonical path. Override with `asset_path` frontmatter.
-
-### Webpack Import Aliases
-
-UJM defines two webpack aliases (in `src/gulp/tasks/webpack.js`) for importing assets in JavaScript:
-
-| Alias | Resolves To | Purpose |
-|-------|------------|---------|
-| `__main_assets__` | `[UJM package]/dist/assets` | UJM's own built-in assets (core modules, libraries, pages) |
-| `__project_assets__` | `[consuming project]/src/assets` | The consuming project's custom assets |
-
-**`__main_assets__`** — Import UJM libraries and core modules:
-```javascript
-import { FormManager } from '__main_assets__/js/libs/form-manager.js';
-import authorizedFetch from '__main_assets__/js/libs/authorized-fetch.js';
-import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js';
-```
-
-**`__project_assets__`** — Import consuming project's own assets:
-```javascript
-// Used in src/index.js to load project-specific page modules
-import(`__project_assets__/js/pages/${pageModulePath}`)
-```
-
-**How they work together:** `src/index.js` loads page modules from both aliases — first from `__main_assets__` (UJM defaults), then from `__project_assets__` (project overrides/extensions). If a project module doesn't exist, it gracefully skips. This enables a layered system where UJM provides defaults and consuming projects can extend or override page behavior.
-
-**When to use which:**
-- **`__main_assets__`** — When importing UJM-provided libraries, core modules, or referencing UJM's built-in page scripts
-- **`__project_assets__`** — When a consuming project needs to import its own custom assets from within UJM-managed code
-
-### Page Module Structure
-
-All page modules must follow this standardized pattern:
-
-```javascript
-/**
- * [Page Name] Page JavaScript
- */
-
-// Libraries
-import webManager from 'web-manager';
-
-// Module
-export default () => {
-  return new Promise(async function (resolve) {
-    // Initialize when DOM is ready
-    await webManager.dom().ready();
-
-    // Page initialization logic
-    helper1();
-
-    // Resolve after initialization
-    return resolve();
-  });
-};
-
-// Helper functions
-function helper1() {
-  // Helper implementation
-}
-```
-
-**Key Points:**
-- `web-manager` is a singleton — `import webManager from 'web-manager'` returns the same initialized instance everywhere. No need to receive it via params or store in module-level variables.
-- Helpers are defined outside the main export function
-- Always wait for DOM ready before manipulating elements
-- Use `webManager.utilities().escapeHTML()` for XSS prevention — do NOT write your own escape function
-
-## XSS Prevention (ZERO TRUST — MANDATORY)
-
-**TREAT ALL DYNAMIC DATA AS UNTRUSTED.** This is a zero-trust policy: any value that did not come directly from a hardcoded literal in the source file MUST be escaped before being inserted into the DOM via `innerHTML` or attribute interpolation.
-
-This includes — but is not limited to:
-- Firestore document fields (user names, emails, IDs, descriptions, etc.)
-- API response data
-- URL parameters (`location.search`, `URLSearchParams`)
-- User input from form fields
-- OAuth-provided values (displayName, email from Google/GitHub)
-- Any variable whose origin is not a hardcoded source-code constant
-
-### The Rule
-```javascript
-// ✅ ALWAYS escape dynamic data before innerHTML
-$el.innerHTML = `<p>${webManager.utilities().escapeHTML(data.title)}</p>`;
-$el.innerHTML = `<a href="${webManager.utilities().escapeHTML(url)}">${webManager.utilities().escapeHTML(label)}</a>`;
-
-// ✅ textContent is always safe — no escaping needed
-$el.textContent = data.title;
-
-// ❌ NEVER inject dynamic data raw into innerHTML
-$el.innerHTML = `<p>${data.title}</p>`;
-$el.innerHTML = `<a href="${url}">${label}</a>`;
-```
-
-### NEVER Write Your Own Escape Function
-Do NOT create a local `escapeHtml` function or any variant. The ONLY allowed escape method is:
-```javascript
-webManager.utilities().escapeHTML(str)
-```
-
-### When Building DOM Programmatically
-Prefer `document.createElement` + `textContent` for plain text nodes — it is inherently safe:
-```javascript
-const $el = document.createElement('div');
-$el.textContent = data.message; // Safe — no escaping needed
-```
-
-Only use `innerHTML` when you need actual HTML structure (tags, classes, etc.), and escape every dynamic value in it.
-
-### Even "Safe" Values Must Be Escaped
-Even values that *seem* safe (like `Date.toLocaleDateString()` output, numeric calculations, or hardcoded config strings) MUST be escaped when inserted via `innerHTML`. This is defense-in-depth — if the data source ever changes, the escaping is already in place.
-
-```javascript
-// ✅ CORRECT — escape even "safe" values in innerHTML
-$el.innerHTML = `<small>${webManager.utilities().escapeHTML(formatDate(timestamp))}</small>`;
-$el.innerHTML = `<span>${webManager.utilities().escapeHTML(reason)}</span>`;
-
-// ❌ WRONG — assuming the value is safe because it's from a date formatter
-$el.innerHTML = `<small>${formatDate(timestamp)}</small>`;
-```
-
-### Redirects Must Be Validated
-Never redirect to a URL from untrusted sources without validation:
-
-```javascript
-// ✅ CORRECT — validate before redirect
-const url = urlParams.get('returnUrl');
-if (url && webManager.isValidRedirectUrl(url)) {
-  window.location.href = url;
-}
-
-// ✅ CORRECT — validate API response URLs have safe scheme
-if (response.url && /^https?:\/\//i.test(response.url)) {
-  window.location.href = response.url;
-}
-
-// ❌ WRONG — redirect to unvalidated input
-window.location.href = urlParams.get('returnUrl');
-```
-
-### postMessage Handlers Must Check Origin
-Always validate `event.origin` when handling `window.addEventListener('message', ...)`:
-
-```javascript
-// ✅ CORRECT
-window.addEventListener('message', (event) => {
-  if (event.origin !== window.location.origin && event.origin !== 'https://trusted-domain.com') {
-    return;
-  }
-  // handle message
-});
-
-// ❌ WRONG — any origin can send messages
-window.addEventListener('message', (event) => {
-  window.location.href = event.data.url; // attacker-controlled redirect
-});
-```
-
-### Never Use eval() or new Function()
-Do not use `eval()`, `new Function()`, `setTimeout(string)`, or `setInterval(string)`. These execute arbitrary code and violate CSP policies.
-
-### Sanitize Markdown/Rich Text Output
-When rendering user-authored markdown or rich text, use DOMPurify to sanitize the output:
-
-```javascript
-import DOMPurify from 'dompurify';
-const safeHTML = DOMPurify.sanitize(md.render(userContent), {
-  ALLOWED_TAGS: ['h1', 'h2', 'h3', 'p', 'br', 'a', 'b', 'strong', 'i', 'em', 'ul', 'ol', 'li', 'img', 'code', 'pre'],
-  ALLOWED_ATTR: ['href', 'src', 'alt', 'title', 'class', 'target', 'rel'],
-});
-```
-
-### Do NOT Escape Values Passed to textContent-Based APIs
-`showNotification()`, `formManager.showSuccess()`, `formManager.showError()`, and `textContent` assignments use safe text insertion internally. Pre-escaping these causes double-encoding (e.g., `We'll` displays as `We&#039;ll`).
-
-```javascript
-// ✅ CORRECT — these APIs use textContent internally, so they're already safe
-webManager.utilities().showNotification('Thank you! We\'ll be in touch.', 'success');
-formManager.showSuccess('Message sent successfully!');
-
-// ❌ WRONG — double-escapes
-webManager.utilities().showNotification(webManager.utilities().escapeHTML(message), 'success');
-```
-
-## Layouts and Pages
-
-### Page Types
-- **One-off pages** (e.g., `/categories`, `/sitemap`) - Create as pages without custom layouts; use existing layouts
-- **Repeating page types** (e.g., blog posts, category pages) - Create a dedicated layout (e.g., `_layouts/category.html`)
-
-### Layout Requirements
-All layouts and pages must eventually require a theme entry point:
-```yaml
-layout: themes/[ site.theme.id ]/frontend/core/base
-```
-
-**Note:** The `[ site.theme.id ]` syntax is correct and allows dynamic theme selection.
-
-### Asset Path Configuration
-
-For pages sharing the same assets, use the `asset_path` frontmatter variable:
-
-```yaml
----
-# Instead of deriving path from page.canonical.path
-asset_path: categories/category
----
-```
-
-**Example:**
-- One-off page: `pages/categories.html` → `src/assets/css/pages/categories/index.scss`
-- Repeating layout: `_layouts/category.html` → `src/assets/css/pages/categories/category.scss` (set `asset_path: categories/category` in layout frontmatter)
-
-## UJ Powertools (Jekyll Plugin)
-
-Ultimate Jekyll uses the `jekyll-uj-powertools` gem for custom Liquid functionality.
-
-**Documentation:** `/Users/ian/Developer/Repositories/ITW-Creative-works/jekyll-uj-powertools/README.md`
-
-### Available Features
-- **Filters:** `uj_strip_ads`, `uj_json_escape`, `uj_title_case`, `uj_content_format`, `uj_hash`
-- **Tags:** `iftruthy`, `iffalsy`, `uj_icon`, `uj_logo`, `uj_image`, `uj_member`, `uj_post`, `uj_readtime`, `uj_social`, `uj_translation_url`, `uj_fake_comments`, `uj_language`
-- **Global Variables:** `site.uj.cache_breaker`
-- **Page Variables:** `page.random_id`, `page.extension`, `page.layout_data`, `page.resolved`
-
-**Always check the README before assuming functionality.**
-
-### Key Liquid Functions
-
-#### `uj_content_format`
-Formats content by first liquifying it, then markdownifying it (if markdown file).
-
-#### `uj_hash`
-Returns a deterministic number between 0 and max (exclusive) based on the input string's MD5 hash. Same input always produces the same output.
-
-```liquid
-{{ "some-string" | uj_hash: 1000 }}  => 0-999 (stable across builds)
-{{ site.url | uj_hash: 2 }}          => 0 or 1
-```
-
-#### `iftruthy` / `iffalsy`
-Custom tags that check JavaScript truthiness (not null, undefined, or empty string).
-
-```liquid
-{% iftruthy variable %}
-  <!-- Content -->
-{% endiftruthy %}
-```
-
-**Limitations:**
-- Does NOT support logical operators
-- Does NOT support `else` statements
-- CAN contain nested sub-statements
-
-#### `page.resolved`
-A deeply merged object containing all site, layout, and page variables. Precedence: page > layout > site. Enables a system of defaults with progressive overrides.
-
-#### `uj_icon`
-Inserts Font Awesome icons:
-
-```liquid
-{% uj_icon icon-name, "fa-md" %}
-{% uj_icon "rocket", "fa-3xl" %}
-```
-
-**Parameters:**
-1. Icon name (string or variable, without "fa-" prefix)
-2. CSS classes (optional, defaults to "fa-3xl")
-
-**Available Icon Sizes:**
-- `fa-2xs` - Extra extra small
-- `fa-xs` - Extra small
-- `fa-sm` - Small
-- `fa-md` - Medium (default base size)
-- `fa-lg` - Large
-- `fa-xl` - Extra large
-- `fa-2xl` - 2x extra large
-- `fa-3xl` - 3x extra large
-- `fa-4xl` - 4x extra large
-- `fa-5xl` - 5x extra large
-
-**Size Examples:**
-```liquid
-{% uj_icon "check", "fa-sm" %}     <!-- Small inline icon -->
-{% uj_icon "star", "fa-lg" %}      <!-- Slightly larger -->
-{% uj_icon "rocket", "fa-2xl" %}   <!-- Hero/feature icons -->
-{% uj_icon "chart-pie", "fa-4xl" %}<!-- Large placeholder icons -->
-```
-
-#### `asset_path` Override
-Override default page-specific CSS/JS path derivation:
-
-```yaml
----
-asset_path: blog/post
----
-```
-
-Uses `/assets/css/pages/{{ asset_path }}.bundle.css` instead of deriving from `page.canonical.path`. Useful when multiple pages share assets (e.g., all blog posts).
-
-## Blog Post Images
-
-### Inline Images with `@post/` Shortcut
-
-Blog posts use standard markdown syntax for inline images. The `@post/` prefix provides a shortcut to reference images in the post's own image directory:
-
-```markdown
-![Alt text](@post/my-image.jpg)
-```
-
-This resolves at build time to `/assets/images/blog/post-{id}/my-image.jpg`, where `{id}` comes from the post's `post.id` frontmatter value.
-
-**All image types work:**
-
-| Syntax | Result |
-|--------|--------|
-| `![alt](@post/file.jpg)` | Local post image (shortcut) |
-| `![alt](/assets/images/other.jpg)` | Absolute path (any image) |
-| `![alt](https://example.com/img.jpg)` | External URL |
-
-**How it works:** The `markdown-images.rb` hook in `jekyll-uj-powertools` intercepts `![alt](url)` patterns during `pre_render`, resolves `@post/` prefixes, then converts each image to a responsive `<picture>` element with WebP sources and lazy loading via `{% uj_image %}`.
-
-**Image directory structure:** Images for post ID `42` live at `src/assets/images/blog/post-42/`.
-
-**Image class customization:** Set via frontmatter:
-```yaml
----
-theme:
-  post:
-    image:
-      class: "img-fluid rounded-3 shadow my-5"
----
-```
-
-### BEM `admin/post` Image Handling
-
-When posts are created via BEM's `POST /admin/post` endpoint:
-1. External image URLs in the markdown body (e.g., Unsplash) are downloaded
-2. Images are uploaded to `src/assets/images/blog/post-{id}/` on GitHub
-3. The body is rewritten to use `@post/{filename}` format
-4. Failed downloads are skipped (original external URL preserved)
-
-## Icon System
-
-Ultimate Jekyll uses Font Awesome icons but does NOT include the Font Awesome JavaScript or CSS library. All icons must be rendered server-side using Jekyll's `{% uj_icon %}` tag.
-
-### Available Icons
-
-UJM ships with the **full Font Awesome Pro solid icon set** (4,600+ icons) at `assets/icons/font-awesome/solid/`, plus brand icons at `assets/icons/font-awesome/brands/`. Any Pro or Free solid/brand icon name can be used with `{% uj_icon %}` and prerendered icons. The icon style defaults to `solid` and can be configured via `site.config.icons.style`.
-
-Browse available icons at: https://fontawesome.com/icons
-
-### When to Use `{% uj_icon %}` vs Prerendered Icons
-
-**IMPORTANT:** Use the correct method based on WHERE the icon will be used:
-
-#### Use `{% uj_icon %}` in HTML/Liquid Templates
-
-When icons are part of the static HTML template, use `{% uj_icon %}` directly:
-
-```liquid
-<!-- Alerts -->
-<div class="alert alert-success">
-  {% uj_icon "circle-check", "fa-sm" %} Success message
-</div>
-
-<!-- Buttons -->
-<button class="btn btn-primary">
-  {% uj_icon "paper-plane", "fa-md me-2" %}
-  Send
-</button>
-
-<!-- Labels -->
-<label>
-  {% uj_icon "envelope", "fa-sm me-1 text-info" %}
-  Email
-</label>
-```
-
-**Use this when:**
-- The icon is in a Jekyll template (.html file)
-- The icon is static and known at build time
-- The icon is part of the page structure
-
-#### Use Prerendered Icons in JavaScript
-
-When icons need to be dynamically inserted via JavaScript, pre-render them in frontmatter and access them via the library:
-
-**1. Add icons to page frontmatter (names only, no classes):**
-```yaml
----
-prerender_icons:
-  - name: "mobile"
-  - name: "envelope"
-  - name: "bell"
----
-```
-
-**2. Import the library in JavaScript:**
-```javascript
-import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js';
-```
-
-**3. Use in your code (second argument works like uj_icon's second argument):**
-```javascript
-// With size + classes (same as {% uj_icon "mobile", "fa-sm me-1" %})
-$badge.innerHTML = `${getPrerenderedIcon('mobile', 'fa-sm me-1')} Push Notification`;
-
-// Without classes (no size class on the <i> wrapper)
-$el.innerHTML = getPrerenderedIcon('bell');
-```
-
-**Use this when:**
-- Icons are dynamically inserted via JavaScript
-- Icons are part of dynamically generated content
-- Icons are added to elements created with `document.createElement()`
-
-### What NOT to Do
-
-**NEVER use manual icon HTML in JavaScript:**
-```javascript
-// ❌ WRONG - Bootstrap Icons (we don't use Bootstrap Icons)
-$el.innerHTML = '<i class="bi bi-check-circle"></i> Text';
-
-// ❌ WRONG - Manual Font Awesome (we don't have FA JS/CSS)
-$el.innerHTML = '<i class="fa-solid fa-check"></i> Text';
-
-// ✅ CORRECT - Use prerendered icons
-$el.innerHTML = `${getPrerenderedIcon('circle-check', 'fa-sm me-1')} Text`;
-```
-
-### Benefits
-- Icons are rendered server-side with proper Font Awesome classes
-- No client-side icon generation overhead
-- Consistent icon styling across the application
-- No Font Awesome JavaScript/CSS library needed
-
-## CSS Guidelines
-
-### Section Padding in Custom Pages
-
-**DO NOT add padding classes to sections in custom frontend pages.**
-
-UJ handles section padding automatically via the theme's layout system. When creating or editing custom frontend pages:
-
-- ❌ DO NOT use `py-5`, `py-4`, `pt-5`, `pb-5`, `p-5`, etc. on `<section>` elements
-- ❌ DO NOT add vertical padding to sections manually
-- ✅ Let the UJ theme handle section spacing automatically
-
-**The ONLY exception:** Add padding if the user EXPLICITLY requests it for a specific section.
-
-### Theme-Adaptive Classes
-
-**DO NOT USE:** `bg-light`, `bg-dark`, `text-light`, `text-dark`
-
-Ultimate Jekyll supports both light and dark modes. Use adaptive classes instead:
-
-**Backgrounds:**
-- `bg-body` - Primary background
-- `bg-body-secondary` - Secondary background
-- `bg-body-tertiary` - Tertiary background
-
-**Text:**
-- `text-body` - Body text color
-
-**Buttons:**
-- `btn-adaptive` - Adaptive button
-- `btn-outline-adaptive` - Adaptive outline button
-
-These classes automatically adapt to the current theme mode.
-
-### Cards Inside Colored Sections
-
-When placing cards inside sections with `bg-body-secondary` or `bg-body-tertiary`, cards will blend in because they share the same background color by default.
-
-**Solution:** Add `bg-body` to cards to create visual contrast:
-
-```html
-<!-- ❌ WRONG - Card blends with section background -->
-<section class="bg-body-secondary">
-  <div class="card">...</div>
-</section>
-
-<!-- ✅ CORRECT - Card stands out with contrasting background -->
-<section class="bg-body-secondary">
-  <div class="card bg-body">...</div>
-</section>
-```
-
-**Rule:** When a section uses `bg-body-secondary` or `bg-body-tertiary`, always add `bg-body` to child cards to ensure proper visual hierarchy.
-
-## Page Loading Protection System
-
-Ultimate Jekyll prevents race conditions by disabling buttons during JavaScript initialization.
-
-### How It Works
-1. HTML element starts with `data-page-loading="true"` and `aria-busy="true"` (`src/defaults/dist/_layouts/core/root.html`)
-2. Protected elements are automatically disabled during this state
-3. Attributes are removed when JavaScript completes (`src/assets/js/core/complete.js`)
-
-### Protected Elements
-- All form buttons (`<button>`, `<input type="submit">`, `<input type="button">`, `<input type="reset">`)
-- Elements with `.btn` class (Bootstrap buttons)
-- Elements with `.btn-action` class (custom action triggers)
-
-### The `.btn-action` Class
-
-Selectively protect non-standard elements that trigger important actions:
-
-```html
-<!-- Protected during page load -->
-<a href="/api/delete" class="custom-link btn-action">Delete Item</a>
-<div class="card-action btn-action" onclick="processData()">Process</div>
-
-<!-- NOT protected (regular navigation/UI) -->
-<a href="/about" class="btn btn-primary">About Us</a>
-<button data-bs-toggle="modal">Show Info</button>
-```
-
-**Use `.btn-action` for:**
-- API calls
-- Form submissions
-- Data modifications
-- Payment processing
-- Destructive actions
-
-**Don't use for:**
-- Navigation links
-- UI toggles (modals, accordions, tabs)
-- Harmless interactions
-
-### Implementation
-- **CSS:** `src/assets/css/core/utilities.scss` - Disabled styling
-- **Click Prevention:** `src/defaults/dist/_includes/core/body.html` - Inline script
-- **State Removal:** `src/assets/js/core/complete.js` - Removes loading state
-
-### Form Protection Standards
-
-All JS-managed forms use a layered protection strategy to prevent native form submission before JavaScript takes control:
-
-#### Layer 1: `onsubmit="return false"` on ALL JS-managed forms
-
-Every `<form>` that will be managed by FormManager MUST include `onsubmit="return false"`:
-
-```html
-<form id="my-form" onsubmit="return false">
-```
-
-This is a zero-cost safety net that prevents native form submission if a user clicks submit before FormManager attaches its `e.preventDefault()` handler. FormManager's own submit handling overrides this — there is no conflict.
-
-**Exception:** Traditional forms with an `action` attribute that intentionally navigate (e.g., search forms, external form submissions) should NOT include this.
-
-#### Layer 2: Button initial state based on use case
-
-| Use Case | Initial State | Mechanism |
-|----------|---------------|-----------|
-| Buttons dependent on async data (checkout payment methods) | `hidden` | `data-wm-bind="@show ..."` reveals when data loads |
-| Buttons on auth/sensitive forms | `disabled` | FormManager's `ready()` removes `disabled` |
-| Buttons on simple forms (contact, newsletter) | Default (visible) | FormManager's `autoReady: true` enables quickly |
-
-#### Layer 3: FormManager `autoReady` configuration
-
-| Scenario | `autoReady` | `ready()` call |
-|----------|-------------|----------------|
-| No async work before form init | `true` (default) | Automatic on DOM ready |
-| Async work before form init (API calls, redirects) | `false` | Explicit call after async completes |
-
-**Reference implementations:**
-- Simple form: `src/assets/js/pages/contact/index.js`
-- Auth form: `src/assets/js/libs/auth.js`
-- Async data form: `src/assets/js/pages/payment/checkout/index.js`
-
-## Lazy Loading System
-
-Ultimate Jekyll uses a custom lazy loading system powered by web-manager.
-
-### Syntax
-```html
-data-lazy="@type value"
-```
-
-### Supported Types
-
-#### `@src` - Lazy load src attribute
-```html
-<img data-lazy="@src /assets/images/hero.jpg" alt="Hero">
-<iframe data-lazy="@src https://example.com/embed"></iframe>
-```
-
-#### `@srcset` - Lazy load srcset attribute
-```html
-<img data-lazy="@srcset /img/small.jpg 480w, /img/large.jpg 1024w">
-```
-
-#### `@bg` - Lazy load background images
-```html
-<div data-lazy="@bg /assets/images/background.jpg"></div>
-```
-
-#### `@class` - Lazy add CSS classes
-```html
-<div data-lazy="@class animation-fade-in">Content</div>
-```
-
-#### `@html` - Lazy inject HTML content
-```html
-<div data-lazy="@html <p>Lazy loaded content</p>"></div>
-```
-
-#### `@script` - Lazy load external scripts
-```html
-<div data-lazy='@script {"src": "https://example.com/widget.js", "attributes": {"async": true}}'></div>
-```
-
-### Features
-- Automatic cache busting via `buildTime`
-- IntersectionObserver for performance (50px threshold)
-- Loading state CSS classes: `lazy-loading`, `lazy-loaded`, `lazy-error`
-- Intelligent handling of video/audio sources
-- Automatic DOM re-scanning for dynamic elements
-
-**Implementation:** `src/assets/js/core/lazy-loading.js`
-
-## Ad Units (Verts)
-
-Ultimate Jekyll provides ad unit includes that display Google AdSense ads with automatic fallback to in-house ads served from promo-server when AdSense is blocked or unfilled.
-
-### Include Files
-
-| Include | Purpose |
-|---------|---------|
-| `modules/adunits/adsense.html` | AdSense ad with promo-server fallback |
-| `modules/adunits/promo-server.html` | Direct promo-server ad (no AdSense) |
-
-### AdSense Include
-
-```liquid
-{% include /modules/adunits/adsense.html type="in-article" %}
-{% include /modules/adunits/adsense.html type="in-article" vert-size="rectangle" %}
-{% include /modules/adunits/adsense.html type="display" vert-size="banner" %}
-{% include /modules/adunits/adsense.html type="display" vert-size="300" %}
-```
-
-**Parameters:**
-
-| Parameter | Required | Default | Description |
-|-----------|----------|---------|-------------|
-| `type` | No | `display` | Ad type: `display`, `in-article`, `in-feed`, `multiplex` |
-| `slot` | No | From site config | Override the ad slot ID |
-| `vert-size` | No | (unconstrained) | Max height preset or pixel value (cannot use `size` — conflicts with Liquid's built-in `size` filter) |
-| `style` | No | `""` | Custom inline CSS |
-| `layout` | No | `image-above` | Layout for `in-feed` type: `image-above`, `image-side` |
-
-### Promo Server Include
-
-```liquid
-{% include /modules/adunits/promo-server.html vert-id="/verts/units/test/google" %}
-{% include /modules/adunits/promo-server.html vert-id="/verts/units/test/google" vert-size="banner" %}
-```
-
-**Parameters:**
-
-| Parameter | Required | Default | Description |
-|-----------|----------|---------|-------------|
-| `vert-id` | Yes | `""` | Path to the vert on promo-server |
-| `vert-size` | No | (unconstrained) | Max height preset or pixel value |
-| `style` | No | `""` | Custom inline CSS |
-
-### Size Presets
-
-The `vert-size` parameter accepts preset names or raw pixel values. Presets constrain the ad unit's max-height:
-
-| Preset | Max Height | Typical Use |
-|--------|-----------|-------------|
-| `banner` | 150px | Horizontal banner ads |
-| `leaderboard` | 90px | Wide horizontal ads (alias for banner) |
-| `rectangle` | 250px | Medium rectangle, in-content ads |
-| `large-rectangle` | 600px | Large rectangle, sidebar ads |
-| `skyscraper` | 600px | Tall sidebar ads |
-
-Raw pixel values are also accepted: `vert-size="300"` → 300px max-height.
-
-When no `vert-size` is specified, the ad unit renders unconstrained.
-
-### How It Works
-
-1. The include renders a `data-lazy="@script ..."` div that lazy-loads `vert.bundle.js` when scrolled into view
-2. `vert.js` creates a `<vert-unit>` custom element with `max-height` + `overflow: hidden` (if `vert-size` is set)
-3. For AdSense types: loads the AdSense script, pushes the ad, and monitors fill status
-4. If AdSense is blocked or unfilled, falls back to a promo-server iframe
-5. The promo-server iframe content uses CSS container queries to adapt its layout to the available space
-6. Ad units are hidden for non-basic plan users via `data-wm-bind="@hide auth.account.subscription.product.id !== basic"`
-
-### File Locations
-
-| Purpose | Path |
-|---------|------|
-| AdSense include | `src/defaults/dist/_includes/modules/adunits/adsense.html` |
-| Promo Server include | `src/defaults/dist/_includes/modules/adunits/promo-server.html` |
-| Vert JS module | `src/assets/js/modules/vert.js` |
-| Vert CSS | `src/assets/css/core/_verts.scss` |
-
-## Appearance Switching System
-
-Ultimate Jekyll supports dark/light/system theme switching with user preference persistence.
-
-### Supported Modes
-- `dark` - Force dark mode
-- `light` - Force light mode
-- `system` - Auto-detect from OS preference (`prefers-color-scheme`)
-
-### JavaScript API
-
-```javascript
-// Get/set preference
-webManager.uj().appearance.get();        // Returns 'dark', 'light', 'system', or null
-webManager.uj().appearance.set('dark');  // Save and apply preference
-webManager.uj().appearance.getResolved(); // Returns actual theme: 'dark' or 'light'
-
-// Utilities
-webManager.uj().appearance.toggle();     // Toggle between dark/light
-webManager.uj().appearance.cycle();      // Cycle: dark → light → system → dark
-webManager.uj().appearance.clear();      // Clear saved preference
-```
-
-### HTML Data Attributes
-
-```html
-<!-- Buttons to set appearance (auto-gets 'active' class) -->
-<button data-appearance-set="light">Light</button>
-<button data-appearance-set="dark">Dark</button>
-<button data-appearance-set="system">System</button>
-
-<!-- Display current mode as text -->
-<span data-appearance-current></span>
-
-<!-- Show/hide icons based on current mode -->
-<span data-appearance-icon="light" hidden>☀️</span>
-<span data-appearance-icon="dark" hidden>🌙</span>
-<span data-appearance-icon="system" hidden>💻</span>
-```
-
-### Dropdown Example
-
-```html
-<div class="dropdown">
-  <button class="btn dropdown-toggle" data-bs-toggle="dropdown">
-    <span data-appearance-icon="light" hidden>{% uj_icon "sun", "fa-md me-2" %}</span>
-    <span data-appearance-icon="dark" hidden>{% uj_icon "moon-stars", "fa-md me-2" %}</span>
-    <span data-appearance-icon="system" hidden>{% uj_icon "circle-half-stroke", "fa-md me-2" %}</span>
-    <span data-appearance-current></span>
-  </button>
-  <ul class="dropdown-menu">
-    <li><a class="dropdown-item" href="#" data-appearance-set="light">Light</a></li>
-    <li><a class="dropdown-item" href="#" data-appearance-set="dark">Dark</a></li>
-    <li><a class="dropdown-item" href="#" data-appearance-set="system">System</a></li>
-  </ul>
-</div>
-```
-
-### Implementation
-- **Inline script:** `src/defaults/dist/_includes/core/body.html` - Runs immediately to prevent flash
-- **Module:** `src/assets/js/core/appearance.js` - API and UI handling
-- **Storage:** Saved under `_manager.appearance.preference` in localStorage
-- **Test page:** `/test/libraries/appearance`
-
-## JavaScript Libraries
-
-### WebManager
-
-Custom library for site management functionality. **It's a singleton** — import it directly from any file:
-
-```javascript
-import webManager from 'web-manager';
-```
-
-This returns the same initialized instance everywhere. Do NOT pass it via params, store in module-level variables, or create new instances.
-
-**Documentation:** `/Users/ian/Developer/Repositories/ITW-Creative-Works/web-manager/README.md`
-
-**Available Utilities:**
-- `webManager.auth()` - Authentication management
-- `webManager.utilities()` - Utility functions (escapeHTML, clipboardCopy, etc.)
-- `webManager.sentry()` - Error tracking
-- `webManager.dom()` - DOM manipulation
-- `webManager.utilities().escapeHTML(text)` - **XSS prevention** — use this instead of writing your own escape function
-
-**Important:** Always check the source code or README before assuming a function exists. Do not guess at API methods.
-
-#### Subscription Resolution
-
-Use `webManager.auth().resolveSubscription(account)` to derive calculated subscription state. This is the **single source of truth** for determining a user's effective plan — do NOT manually check `subscription.status`, `trial.claimed`, or `cancellation.pending` separately.
-
-```javascript
-const resolved = webManager.auth().resolveSubscription(account);
-// Returns: { plan, active, trialing, cancelling }
-```
-
-| Field | Description |
-|-------|-------------|
-| `plan` | Effective plan ID right now (`'basic'` if cancelled/suspended) |
-| `active` | Has active access (active, trialing, or cancelling) |
-| `trialing` | In active trial |
-| `cancelling` | Cancellation pending |
-
-Raw subscription data (product.id, status, trial, cancellation) is on `account.subscription` directly — `resolveSubscription()` returns only the calculated/derived fields.
-
-The same function exists in BEM as `User.resolveSubscription(account)` with identical return shape.
-
-### Ultimate Jekyll Libraries
-
-Ultimate Jekyll provides helper libraries in `src/assets/js/libs/` that can be imported as needed.
-
-#### Prerendered Icons Library
-
-Provides access to icons defined in page frontmatter and rendered server-side.
-
-**Import:**
-```javascript
-import { getPrerenderedIcon } from '__main_assets__/js/libs/prerendered-icons.js';
-```
-
-**Usage:**
-```javascript
-// With classes (drop-in replacement for uj_icon)
-getPrerenderedIcon('apple', 'fa-md me-2');
-
-// Without classes (no size class)
-getPrerenderedIcon('apple');
-```
-
-**Reference:** `src/assets/js/libs/prerendered-icons.js`
-
-#### Authorized Fetch Library
-
-Simplifies authenticated API requests by automatically adding Firebase authentication tokens via Authorization Bearer header.
-
-**Import:**
-```javascript
-import authorizedFetch from '__main_assets__/js/libs/authorized-fetch.js';
-```
-
-**Usage:**
-```javascript
-const response = await authorizedFetch(url, options);
-```
-
-**Key Benefits:**
-- No need to manually call `webManager.auth().getIdToken()`
-- Automatic token injection as Authorization Bearer header
-- Centralized authentication handling
-- Automatic usage sync: extracts `bm-properties` header from every response and updates `webManager.bindings()` with fresh usage data under the `usage` key
-
-**Options pass-through:** All `wonderful-fetch` options (`response`, `output`, `body`, `timeout`, etc.) are passed through untouched. Internally, `authorizedFetch` uses `output: 'complete'` to read response headers, then returns only the body by default. If the caller passes `output: 'complete'`, they get the full `{ status, headers, body }` response.
-
-**Automatic Usage Binding Sync:**
-
-After every successful response, `authorizedFetch` reads the `bm-properties` header and updates the `usage` bindings key:
-```javascript
-// After an API call, bindings are automatically updated:
-// usage.credits = { monthly: 5, daily: 2, limit: 100 }
-```
-This means any `data-wm-bind` elements bound to `usage.*` paths are automatically kept in sync without any manual work. See "Usage Bindings" below.
-
-**⚠️ IMPORTANT: Auth State Requirement**
-
-`authorizedFetch` requires Firebase Auth to have determined the current user's authentication state before being called. On fresh page loads (e.g., OAuth callback pages, deep links), Firebase Auth needs time to restore the session from IndexedDB/localStorage.
-
-**If called before auth state is determined, it will warn: `"No authenticated user found"`**
-
-**Solution:** Wait for auth state before calling `authorizedFetch`:
-
-```javascript
-// Wait for auth state to be determined (fires once auth is known)
-webManager.auth().listen({ once: true }, async () => {
-  // Now safe to use authorizedFetch
-  const response = await authorizedFetch(url, options);
-});
-```
-
-**When this matters:**
-- Pages that load and immediately need to make authenticated API calls
-- OAuth callback pages (user returns from external auth provider)
-- Deep links that require authenticated requests on load
-
-**When NOT needed:**
-- User-triggered actions (button clicks, form submissions) - by then auth state is always determined
-- Pages that wait for user interaction before making API calls
-
-**Reference:** `src/assets/js/libs/authorized-fetch.js`
-
-#### Usage Bindings
-
-Usage data is available in the `usage` bindings key. It is populated from two sources:
-
-1. **On page load (auth settle):** `web-manager` reads `account.usage` from Firestore and resolves plan limits from `config.payment.plans`, then sets `usage` bindings with the merged data.
-2. **After API calls:** `authorizedFetch` reads the `bm-properties` response header and merges fresh usage counters + limits into the existing `usage` bindings.
-
-**Bindings structure:**
-```javascript
-// usage.credits = { monthly: 5, daily: 2, limit: 100 }
-// usage.requests = { monthly: 20, limit: 500 }
-```
-
-**HTML usage:**
-```html
-<!-- Show usage counter: "5/100" -->
-<span data-wm-bind="@show usage.credits">
-  <span data-wm-bind="usage.credits.monthly">–</span>/<span data-wm-bind="usage.credits.limit">–</span>
-</span>
-```
-
-**Config requirement:** Plan limits must be defined in `_config.yml` under `web_manager.payment.plans`:
-```yaml
-web_manager:
-  payment:
-    plans:
-      - id: basic
-        limits:
-          credits: 100
-      - id: premium
-        limits:
-          credits: 500
-```
-
-#### Payment Config Library
-
-Reads payment configuration (products, processors, prices, limits) from `webManager.config.payment` — populated from `_config.yml` at build time. **Do NOT fetch `/backend-manager/brand` to get payment data.** It's already available instantly via this library.
-
-**Import:**
-```javascript
-import { getPaymentConfig, getProcessors, getProducts, getProductById, getProductLimits, getCurrency } from '__main_assets__/js/libs/payment-config.js';
-```
-
-**Usage:**
-```javascript
-// Get all products
-const products = getProducts();
-
-// Find a specific product
-const product = getProductById('plus');
-
-// Get product limits
-const limits = getProductLimits('plus'); // { credits: 500, agents: 3, ... }
-
-// Get processors (stripe, paypal, etc.)
-const processors = getProcessors();
-```
-
-**Config location in `_config.yml`:**
-```yaml
-web_manager:
-  payment:
-    processors:
-      stripe:
-        publishableKey: pk_live_...
-      paypal:
-        clientId: ...
-    products:
-      - id: basic
-        name: Basic
-        limits:
-          credits: 100
-      - id: plus
-        name: Plus
-        limits:
-          credits: 500
-        prices:
-          monthly: 19
-          annually: 190
-```
-
-**How it works:** The `foot.html` Configuration injection serializes all `web_manager` properties into `window.Configuration`, which `webManager.initialize()` stores in `webManager.config`. The payment config is available immediately — no API call needed.
-
-**When to still use the brand API:**
-- `oauth2` provider configuration (used by the connections section on the account page)
-- Any data that is NOT in `_config.yml` and only exists server-side
-
-**Reference:** `src/assets/js/libs/payment-config.js`
-
-#### Pricing Page: Config-Resolved Values
-
-The pricing layout automatically resolves prices and feature limits from `_config.yml` when not explicitly set in frontmatter. This means consuming projects can define ONLY display metadata (name, tagline, icon, features list) and let prices/limits come from the single source of truth.
-
-**Resolution order (frontmatter wins):**
-1. `plan.pricing.monthly` / `plan.pricing.annually` from page frontmatter
-2. `site.web_manager.payment.products[matching_id].prices.monthly` / `.annually` from config
-3. `0` (default)
-
-**Feature value resolution:**
-1. `feature.value` from page frontmatter
-2. `site.web_manager.payment.products[matching_id].limits[feature.id]` from config (with `-1` → `"Unlimited"`)
-
-**Example: Minimal pricing.md (prices/limits come from config):**
-```yaml
----
-layout: blueprint/pricing
-permalink: /pricing
-
-pricing:
-  plans:
-    - id: "basic"
-      name: "Basic"
-      tagline: "best for getting started"
-      url: "/dashboard"
-      features:
-        - id: "credits"
-          name: "Credits"
-          icon: "sparkles"
-        - id: "agents"
-          name: "Agents"
-          icon: "robot"
-    - id: "plus"
-      name: "Plus"
-      tagline: "best for small websites"
-      features:
-        - id: "credits"
-          name: "Credits"
-          icon: "sparkles"
-        - id: "agents"
-          name: "Agents"
-          icon: "robot"
----
-```
-
-In this example, `credits` value of 100 and price of $19/mo come from `_config.yml`'s `web_manager.payment.products` — no hardcoding needed.
-
-#### FormManager Library
-
-Lightweight form state management library with built-in validation, state machine, and event system.
-
-**Import:**
-```javascript
-import { FormManager } from '__main_assets__/js/libs/form-manager.js';
-```
-
-**Basic Usage:**
-```javascript
-const formManager = new FormManager('#my-form', options);
-
-formManager.on('submit', async ({ data, $submitButton }) => {
-  const response = await fetch('/api', { body: JSON.stringify(data) });
-  if (!response.ok) throw new Error('Failed');
-  formManager.showSuccess('Form submitted!');
-});
-```
-
-**State Machine:**
-```
-initializing → ready ⇄ submitting → ready (or submitted)
-```
-
-**Configuration Options:**
-```javascript
-{
-  autoReady: true,           // Auto-transition to initialState when DOM ready
-  initialState: 'ready',     // State after autoReady fires
-  allowResubmit: true,       // Allow resubmission after success (false = 'submitted' state)
-  resetOnSuccess: false,     // Clear form fields after successful submission
-  warnOnUnsavedChanges: true, // Warn user before leaving page with unsaved changes
-  submittingText: 'Processing...', // Text shown on submit button during submission
-  submittedText: 'Processed!', // Text shown on submit button after success (when allowResubmit: false)
-  inputGroup: null           // Filter getData() by data-input-group attribute (null = all fields)
-}
-```
-
-**Events:**
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `submit` | `{ data, $submitButton }` | Form submission (throw error to show failure) |
-| `validation` | `{ data, setError }` | Custom validation before submit |
-| `change` | `{ field, name, value, data }` | Field value changed |
-| `statechange` | `{ state, previousState }` | State transition |
-| `honeypot` | `{ data }` | Honeypot triggered (for spam tracking) |
-
-**Validation System:**
-
-FormManager runs validation automatically before `submit`:
-1. **HTML5 validation** - Checks `required`, `minlength`, `maxlength`, `min`, `max`, `pattern`, `type="email"`, `type="url"`
-2. **Custom validation** - Use `validation` event for business logic
-
-```javascript
-fm.on('validation', ({ data, setError }) => {
-  if (data.age && parseInt(data.age) < 18) {
-    setError('age', 'You must be 18 or older');
-  }
-});
-```
-
-Errors display with Bootstrap's `is-invalid` class and `.invalid-feedback` elements.
-
-**Autofocus:**
-
-When the form transitions to `ready` state, FormManager automatically focuses the field with the `autofocus` attribute (if present and not disabled).
-
-**Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `on(event, callback)` | Register event listener (chainable) |
-| `ready()` | Transition to ready state |
-| `getData()` | Get form data as nested object (supports dot notation, respects input group filter) |
-| `setData(obj)` | Set form values from nested object |
-| `setInputGroup(group)` | Set input group filter (string, array, or null) |
-| `getInputGroup()` | Get current input group filter |
-| `showSuccess(msg)` | Show success notification |
-| `showError(msg)` | Show error notification |
-| `submit()` | Programmatically trigger form submission (fires native submit event) |
-| `reset()` | Reset form and go to ready state |
-| `isDirty()` | Check if form has unsaved changes |
-| `setDirty(bool)` | Set dirty state |
-| `clearFieldErrors()` | Clear all field validation errors |
-| `throwFieldErrors({ field: msg })` | Set and display field errors, throw error |
-
-**Nested Field Names (Dot Notation):**
-
-Use dot notation in field names for nested data:
-```html
-<input name="user.address.city" value="NYC">
-```
-
-Results in:
-```javascript
-{ user: { address: { city: 'NYC' } } }
-```
-
-**Input Groups:**
-
-Filter `getData()` to only return fields matching a specific group. Fields without `data-input-group` are "global" and always included.
-
-```html
-<!-- Global fields (no data-input-group) - always included -->
-<input name="settings.theme" value="dark">
-
-<!-- Group-specific fields -->
-<input name="options.url" data-input-group="url" value="https://example.com">
-<input name="options.ssid" data-input-group="wifi" value="MyWiFi">
-<input name="options.password" data-input-group="wifi" value="secret123">
-```
-
-```javascript
-// Set group filter (accepts string or array)
-formManager.setInputGroup('url');           // Single group
-formManager.setInputGroup(['url', 'wifi']); // Multiple groups
-formManager.setInputGroup(null);            // Clear filter (all fields)
-
-// Get current filter
-formManager.getInputGroup(); // Returns ['url'] or null
-
-// getData() respects the filter
-formManager.setInputGroup('wifi');
-formManager.getData();
-// Returns: { settings: { theme: 'dark' }, options: { ssid: 'MyWiFi', password: 'secret123' } }
-// Note: 'url' field excluded, global 'settings.theme' included
-```
-
-Can also be set via config:
-```javascript
-const fm = new FormManager('#form', { inputGroup: 'wifi' });
-```
-
-**Honeypot (Bot Detection):**
-
-FormManager automatically rejects submissions if a honeypot field is filled. Honeypot fields are hidden from users but bots fill them automatically.
-
-```html
-<!-- Hidden from users via CSS -->
-<input type="text" name="honey" autocomplete="off" tabindex="-1"
-       style="position: absolute; left: -9999px;" aria-hidden="true">
-```
-
-Fields matching `[data-honey]` or `[name="honey"]` are:
-- Excluded from `getData()` output
-- Checked during validation — if filled, submission is rejected with generic error
-
-**Checkbox Handling:**
-- **Single checkbox:** Returns `true`/`false`
-- **Checkbox group (same name):** Returns object `{ value1: true, value2: false }`
-
-**Multiple Submit Buttons:**
-
-Access the clicked button via `$submitButton`:
-```html
-<button type="submit" data-action="save">Save</button>
-<button type="submit" data-action="draft">Save Draft</button>
-```
-
-```javascript
-fm.on('submit', async ({ data, $submitButton }) => {
-  const action = $submitButton?.dataset?.action; // 'save' or 'draft'
-});
-```
-
-**Reference:** `src/assets/js/libs/form-manager.js`
-**Test Page:** `src/assets/js/pages/test/libraries/form-manager/index.js`
-**Example:** `src/assets/js/pages/contact/index.js`
-
-## Analytics & Tracking
-
-Ultimate Jekyll uses three tracking platforms: Google Analytics (gtag), Facebook Pixel (fbq), and TikTok Pixel (ttq).
-
-### ITM (Internal Tracking Medium)
-
-Internal tracking system modeled after UTM for cross-property user journey tracking.
-
-| Parameter | Purpose | Examples |
-|-----------|---------|----------|
-| `itm_source` | Platform/origin | `website`, `browser-extension`, `app`, `email` |
-| `itm_medium` | Delivery mechanism | `modal`, `prompt`, `banner`, `tooltip` |
-| `itm_campaign` | Specific campaign/feature | `exit-popup`, `premium-unlock`, `newsletter-signup` |
-| `itm_content` | Specific context | Page path, feature ID, variant |
-
-**Examples:**
-```
-# Website exit popup
-?itm_source=website&itm_medium=modal&itm_campaign=exit-popup&itm_content=/pricing
-
-# Extension premium unlock
-?itm_source=browser-extension&itm_medium=prompt&itm_campaign=premium-unlock&itm_content=bulk-export
-```
-
-### Tracking Guidelines
-
-**IMPORTANT Rules:**
-- Track important user events with `gtag()`, `fbq()`, and `ttq()` functions
-- NEVER add conditional checks for tracking functions (e.g., `if (typeof gtag !== 'undefined')`)
-- Always assume tracking functions exist - they're globally available or stubbed
-- Reference standard events documentation before implementing custom tracking
-
-**Standard Events Documentation:**
-- **Google Analytics GA4:** https://developers.google.com/analytics/devguides/collection/ga4/reference/events
-- **Facebook Pixel:** https://www.facebook.com/business/help/402791146561655?id=1205376682832142
-- **TikTok Pixel:** https://ads.tiktok.com/help/article/standard-events-parameters?redirected=2
-
-### Platform-Specific Requirements
-
-#### TikTok Pixel Requirements
-TikTok has strict validation requirements:
-
-**Required Parameters:**
-- `content_id` - MUST be included in all events
-
-**Valid Content Types:**
-- `"product"`
-- `"product_group"`
-- `"destination"`
-- `"hotel"`
-- `"flight"`
-- `"vehicle"`
-
-Any other content type will generate a validation error.
-
-**Example:**
-```javascript
-// ✅ CORRECT
-ttq.track('ViewContent', {
-  content_id: 'product-123',
-  content_type: 'product'
-});
-
-// ❌ WRONG - Missing content_id
-ttq.track('ViewContent', {
-  content_type: 'product'
-});
-
-// ❌ WRONG - Invalid content_type
-ttq.track('ViewContent', {
-  content_id: 'product-123',
-  content_type: 'custom'  // Not in approved list
-});
-```
-
-### Tracking Implementation
-
-**IMPORTANT:** Always track events to ALL THREE platforms in this order:
-1. Google Analytics (gtag)
-2. Facebook Pixel (fbq)
-3. TikTok Pixel (ttq)
-
-Track events directly without existence checks. All three tracking calls should be made together for every event.
-
-**Development Mode:**
-In development mode, all tracking calls are intercepted and logged to the console for debugging. See `src/assets/js/libs/dev.js` for implementation.
-
-## HTML Element Attributes
-
-The `<html>` element has data attributes for JavaScript/CSS targeting:
-
-| Attribute | Values |
-|-----------|--------|
-| `data-theme-id` | Theme ID (e.g., `classy`) |
-| `data-theme-target` | `frontend`, `backend`, `docs` |
-| `data-bs-theme` | `light`, `dark` |
-| `data-page-path` | Page permalink (e.g., `/about`) |
-| `data-asset-path` | Custom asset path or empty |
-| `data-environment` | `development`, `production` |
-| `data-platform` | `windows`, `mac`, `linux`, `ios`, `android`, `chromeos`, `unknown` |
-| `data-browser` | `chrome`, `firefox`, `safari`, `edge`, `opera`, `brave` |
-| `data-device` | `mobile` (<768px), `tablet` (768-1199px), `desktop` (>=1200px) |
-| `data-runtime` | `web`, `browser-extension`, `electron`, `node` |
-| `aria-busy` | `true` (loading), `false` (ready) |
-
-**Detection source:** `web-manager/src/modules/utilities.js`
-
-## Alternatives Collection (SEO Competitor Comparison Pages)
-
-UJ provides an `alternatives` collection for SEO landing pages that target users searching for competitors (e.g., "ExampleApp alternatives"). These pages are entirely frontmatter-driven and designed to convert visitors who are comparing products.
-
-### How It Works
-
-1. The `alternatives` collection is registered in `src/config/_config_default.yml` (UJM-controlled)
-2. Each alternative is a markdown file in the consuming project's `_alternatives/` directory
-3. The layout chain: `blueprint/alternatives/alternative` → `themes/classy/frontend/pages/alternatives/alternative`
-4. An index page at `/alternatives` lists all alternatives automatically
-5. **Shared content lives in the layout** — the theme layout provides default testimonials, stats, FAQs, CTA, and why_switch content so competitor pages only need competitor-specific data
-6. The layout frontmatter uses `{{ page.resolved.alternative.competitor.name }}` to dynamically insert the competitor name into shared content (e.g., FAQ questions, CTA headlines)
-
-### Creating an Alternative Page
-
-In the consuming project, create `src/_alternatives/competitor-name.md`. Only competitor-specific data is needed — shared sections are inherited from the layout:
-
-```yaml
----
-layout: blueprint/alternatives/alternative
-sitemap:
-  include: true
-
-alternative:
-  competitor:
-    name: "Competitor Name"
-    description: "Brief description of the competitor (shown on /alternatives listing)"
-  comparison:
-    features:
-      - name: "Feature Name"
-        icon: "sparkles"
-        ours:
-          value: true  # or string like "Unlimited"
-        theirs:
-          value: false  # or string like "Limited"
----
-```
-
-That's it! The layout automatically generates:
-- Hero with "Brand vs Competitor Name" headline
-- Why Switch section with default differentiator items
-- Testimonials, Stats, FAQs, and CTA with shared content
-- All text dynamically references the competitor name via `{{ page.resolved.alternative.competitor.name }}`
-
-**To override any inherited section**, define it in the competitor's frontmatter — `page.resolved` merge gives page-level values highest priority.
-
-### Available Sections
-
-All sections are **optional** — omit or leave empty to hide. Sections with `(shared)` have default content in the layout:
-
-| Section | Frontmatter Key | Description |
-|---------|----------------|-------------|
-| Hero | `alternative.hero` | Gradient animated hero with "Brand vs Competitor" headline (shared) |
-| Comparison | `alternative.comparison` | Side-by-side feature table — **must be defined per competitor** |
-| Why Switch | `alternative.why_switch` | Alternating image/text showcase blocks (shared) |
-| Video | `alternative.video` | YouTube embed (default: hidden, set `youtube_id` to show) |
-| Testimonials | `alternative.testimonials` | Reuses `testimonial-scroll.html` component (shared) |
-| Stats | `alternative.stats` | Social proof numbers with icons (shared) |
-| FAQs | `alternative.faqs` | Accordion with switching-related questions (shared) |
-| CTA | `alternative.cta` | Final conversion card with buttons (shared) |
-
-### Dynamic Competitor Name in Frontmatter
-
-The layout uses `{{ page.resolved.alternative.competitor.name }}` in its frontmatter defaults to dynamically reference the competitor. This works because the template pipes these values through `| uj_liquify` to resolve Liquid expressions.
-
-**Example:** The layout's default FAQ includes:
-```yaml
-question: "Can I import my data from {{ page.resolved.alternative.competitor.name }}?"
-```
-Which renders as "Can I import my data from ExampleApp?" for an ExampleApp competitor page.
-
-### Reference Implementation
-
-- **Minimal competitor page:** `src/defaults/dist/_alternatives/example-competitor.md` — shows the minimum frontmatter needed (competitor name + comparison features)
-- **Layout with all defaults:** `src/defaults/dist/_layouts/themes/classy/frontend/pages/alternatives/alternative.html` — contains shared content for all sections
-
-### File Locations
-
-| Purpose | Path |
-|---------|------|
-| Theme layout (alternative page) | `src/defaults/dist/_layouts/themes/classy/frontend/pages/alternatives/alternative.html` |
-| Theme layout (index/listing page) | `src/defaults/dist/_layouts/themes/classy/frontend/pages/alternatives/index.html` |
-| Blueprint (alternative) | `src/defaults/dist/_layouts/blueprint/alternatives/alternative.html` |
-| Blueprint (index) | `src/defaults/dist/_layouts/blueprint/alternatives/index.html` |
-| Default page (index) | `src/defaults/dist/pages/alternatives/index.md` |
-| Sample alternative | `src/defaults/dist/_alternatives/example-competitor.md` |
-| CSS | `src/assets/css/pages/alternatives/alternative/index.scss` |
-| JS | `src/assets/js/pages/alternatives/alternative/index.js` |
-
-## Schema / Structured Data (JSON-LD)
-
-UJ automatically generates JSON-LD structured data in `foot.html`. The SoftwareApplication schema with AggregateRating is opt-in via frontmatter.
-
-### SoftwareApplication Schema
-
-Renders a `SoftwareApplication` JSON-LD block with deterministic aggregate ratings. Enabled by blueprint layouts (index, pricing, download, alternatives/alternative) — consuming projects can override or disable per page.
-
-**How it works:**
-
-1. **`_config.yml`** sets fallback defaults (no `enabled` key — just field defaults like `application_category`, `price`, etc.)
-2. **Blueprint layouts** set `schema.software_application.enabled: true` with page-appropriate `features`
-3. **Consuming projects** can override any value in their page frontmatter, or disable with `enabled: false`
-
-This follows the standard `page.resolved` merge: page > layout > site.
-
-**Deterministic ratings:** Uses the `uj_hash` filter (from jekyll-uj-powertools) seeded with `site.url` by default, producing stable values across builds:
-- Rating: always `4.8` or `4.9` (deterministic per seed)
-- Review count: 200,000–999,999 (deterministic per seed)
-- Override seed per page with `hash_seed` to get different values
-
-**Blueprint frontmatter example:**
-```yaml
-### SCHEMA ###
-schema:
-  software_application:
-    enabled: true
-    features:
-      - "Free to use"
-      - "24/7 availability"
-      - "User-friendly interface"
-```
-
-**Consuming project override example:**
-```yaml
-schema:
-  software_application:
-    application_category: "EducationalApplication"
-    features:
-      - "AI-powered solutions"
-      - "24/7 availability"
-```
-
-**Consuming project disable example:**
-```yaml
-schema:
-  software_application:
-    enabled: false
-```
-
-**Available fields:**
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `enabled` | (set by blueprint) | Enable/disable the schema block |
-| `name` | `site.brand.name` | Application name |
-| `description` | `page.resolved.meta.description` | Application description |
-| `application_category` | `WebApplication` | Schema.org application category |
-| `operating_system` | `Web-based` | Target OS |
-| `price` | `0` | Price (string) |
-| `price_currency` | `USD` | Currency code |
-| `features` | `[]` | Feature list for `featureList` field |
-| `hash_seed` | `site.url` | Seed for deterministic rating/count generation |
-
-**File locations:**
-
-| Purpose | Path |
-|---------|------|
-| Schema block (rendering) | `src/defaults/dist/_includes/core/foot.html` |
-| Site-level defaults | `src/defaults/src/_config.yml` (under `schema:`) |
-| Blueprint activation | `src/defaults/dist/_layouts/blueprint/{index,pricing,download}.html`, `blueprint/alternatives/alternative.html` |
-| Hash filter | `jekyll-uj-powertools/lib/filters/main.rb` (`uj_hash`) |
-
-### FAQPage Schema
-
-Renders a `FAQPage` JSON-LD block for pages with FAQ/accordion sections. Enabled by the alternatives blueprint — consuming projects can also enable it on any page with FAQ content.
-
-**How it works:**
-
-1. **`_config.yml`** sets `faq_page.items: []` as fallback
-2. **Blueprint layouts** set `schema.faq_page.enabled: true`
-3. **Items source (fallback chain):** `schema.faq_page.items` → `page.resolved.faqs.items` → `page.resolved.alternative.faqs.items`. Pages with generic `faqs.items` (like pricing) and alternatives pages both get FAQPage schema automatically without duplicating content
-4. Questions/answers are processed through `uj_liquify` (supports Liquid expressions like competitor names) and `uj_json_escape`
-
-**Blueprint activation:** Enabled by default in `blueprint/pricing.html`, `blueprint/contact.html`, `blueprint/download.html`, `blueprint/extension/index.html`, and `blueprint/alternatives/alternative.html`.
-
-**Consuming project usage — provide items directly:**
-```yaml
-schema:
-  faq_page:
-    enabled: true
-    items:
-      - question: "How do I get started?"
-        answer: "Sign up for free and follow the onboarding guide."
-      - question: "Is there a free plan?"
-        answer: "Yes, our basic plan is completely free."
-```
-
-**Available fields:**
-
-| Field | Default | Description |
-|-------|---------|-------------|
-| `enabled` | (set by blueprint) | Enable/disable the schema block |
-| `items` | `[]` | Array of `{question, answer}` objects. Falls back to `alternative.faqs.items` if empty |
-
-## Audit Workflow
-
-When fixing issues identified by the audit task (`src/gulp/tasks/audit.js`):
-
-1. Review the audit file location provided
-2. Create a TODO list for each audit category
-3. Read the ENTIRE audit file and plan fixes for each category
-4. Tackle issues incrementally - DO NOT attempt to fix everything at once
-5. Work through one category at a time
-
-**Remember:** Audit files are large. Systematic, incremental fixes prevent errors and ensure thoroughness.