ultimate-jekyll-manager 1.7.2 → 1.8.1

package/CHANGELOG.md

@@ -14,6 +14,70 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 - `Fixed` for any bug fixes.
 - `Security` in case of vulnerabilities.
 
+---
+## [1.8.1] - 2026-06-11
+
+### Changed
+
+- **`docs/audit.md` rewritten as the full-audit check catalog (`/omega:ujm audit`).** The two-stage site audit became an ID'd catalog: mirrored universal checks (U-01..U-14 — tests at every layer, XSS, secrets, config canon, doc parity, dead code, dep health, …), UJM-specific checks (UJM-01..UJM-10 — inline-script ban, theme-prefixed classes, content writing rules, SEO meta, purge safelist, reads-vs-writes, page-module pattern, images, a11y), and framework-repo checks (F-01..F-04 — sister parity, defaults sync, docs completeness, green framework suite), with scope auto-detect (consumer vs framework via package.json), a persisted findings report (`.temp/audit/claude-audit.md`), a severity-ordered TodoWrite fix loop, and the `npx mgr audit` automated stage absorbed from the old doc. Wired to the `omega:ujm` router's Audit process; `docs/audit.md` is mirrored across BEM/BXM/EM. CLAUDE.md's docs index updated to match.
+- **package.json `keywords` corrected** — replaced the stale template list (`Autoprefixer`, `imagemin` — not used; `Browsersync` — true but noise) with accurate, discovery-oriented ones (`jekyll`, `static-site`, `static-site-generator`, `website`, `seo`, `gulp`, `sass`, `webpack`, `postcss`). npm-listing metadata only; no behavior change. Mirrored across BEM/BXM/EM.
+
+---
+## [1.8.0] - 2026-06-11
+
+### Added
+
+- **`docs/migration.md` + expanded `docs/audit.md` + dashboard-pages pattern (action-skill consolidation).** The standalone `UJM:migrate`/`UJM:audit`/`UJM:new-page`/`UJM:new-site` skills were deleted and folded into `omega:ujm` as process checklists; their framework facts landed in the repo: new `docs/migration.md` (full old-UJ→UJM migration incl. `_legacy/` flow + config re-mapping, `_config.yml` quick-fix key schema, revert-posts procedure), `docs/audit.md` expanded to the full two-stage workflow (AI content pass → `npx mgr audit` fix loop), and `docs/layouts-and-pages.md` gained the dashboard list/detail/edit page pattern (separate pages, `?id=` redirects, breadcrumbs).
+- **Dev-process guidance relaxed: only `npm start` is off-limits.** The "NEVER run" rule in CLAUDE.md + `src/defaults/CLAUDE.md` now prohibits only the long-running dev server (instruct the user to start it if it isn't running; read `logs/*.log`, never tail the process) — `npx mgr test` and `npm run build` are fine to run.
+- **Skills-as-routers migration — `docs/no-inline-scripts.md` + `docs/purgecss.md` (new), plus `seo.md` / `layouts-and-pages.md` / `javascript-libraries.md` / `assets.md` extensions.** Framework facts migrated from the `omega:ujm` skill into the repo so they version-match the installed package: `no-inline-scripts.md` carries the full hard-rule playbook (where scripts move, Liquid `data-*`/`<template>`/conditional bridges, window-global callbacks, step-by-step migration, verification grep); `purgecss.md` carries the safelist playbook (two locations, RegExp anchoring, `variables: false` gotcha, per-file processing, current UJM safelist, category guide); `seo.md` retitled "SEO & Content" and gains the content writing rules (action-verb H1s, sentence case, headline/accent structure, frontmatter SEO, superheadline rules) + Services and Solutions page strategies + alternatives content guidelines; `layouts-and-pages.md` gains default-page customization rules (.md vs .html, page exclusions), the per-page customization-levels table (homepage/pricing/about/contact/download incl. hero display modes, pricing feature comments, testimonial/FAQ guidelines), and the custom-page creation checklist; `javascript-libraries.md` gains the reads-vs-writes rule (Firestore SDK for dashboard reads, Cloud Functions for writes) + Firestore read examples; `assets.md` gains the account-dropdown item field reference. The `data-wm-bind` deep reference moved to `web-manager/docs/bindings.md` (the module that owns the feature). All indexed in CLAUDE.md; the skill is now a thin router (pointers + hard rules + process checklists).
+
+### Changed
+
+- **Router skill renamed `UJM:patterns` → `omega:ujm`** — all framework skills now live under the `omega:` namespace (`omega:em`/`omega:bxm`/`omega:ujm`/`omega:bem` + the `omega:main` hub). CLAUDE.md's Recommended skills section updated.
+- **newsflash homepage post slots are strictly deduplicated.** Each section consumes its own slice of `site.posts` so no story repeats down the page: hero = post 1, top stories = 2–4, "the latest" feed = 5–9, most-read rail = 10–14, "more to chew on" = 15–17 (only the ticker repeats the latest — it's chrome, not content). Sections disappear gracefully when the site doesn't have enough posts to fill their slice.
+- **Dev builds raise `--limit_posts` from 15 to 18** so a fully-populated newsflash front page (17 distinct posts) is visible during development (`--all-posts` still disables the cap entirely).
+- **Footer appearance picker is now icon-only.** The toggle button in classy's and newsflash's footers shows just the mode icon (`data-appearance-icon` spans) — the `data-appearance-current` text label was removed from the button (the mode words remain in the dropdown items). Pure HTML change; the framework `data-appearance-*` logic is untouched. Docs updated in [docs/themes.md](docs/themes.md#the-appearance-picker-is-required-in-every-footer) + [docs/appearance.md](docs/appearance.md).
+- **newsflash homepage desk cards link to their category pages.** Each desk card is now a story-card link (`href` per item, falling back to the slugified title → `/blog/categories/<slug>`) with a "Read the desk" affordance.
+- **newsflash testimonials moved from the homepage to the about page.** The "From our readers" quote-card section (universal `testimonials` key) now lives on about between the principles and the team CTA; the `.quote-card` styles moved from the homepage page CSS to the about page CSS.
+- **newsflash nav + footer include forks deleted — chrome now inherits from classy.** The nav fork was a verbatim copy of classy's (the fallback regenerates an identical file); the footer's editorial look (oversized serif wordmark, hidden avatar, 24em description measure, panel-color repaints of the `.link-muted`/`.text-body` utilities, weight-800 volt column heads) was ported into the theme's `_general.scss` footer rules, so classy's inherited markup renders the same ink-slab design in both modes.
+- **Classy footer language icon is now theme-adaptive.** The language dropdown button's hardcoded multicolor inline SVG (fixed fills that ignored `currentColor` and clashed on dark surfaces like newsflash's ink-slab footer) is replaced with `{% uj_icon "language" %}`, which inherits the button's color in every theme and mode.
+- **`docs/project-structure.md` renamed `docs/directory-structure.md`** (H1 `# Project Structure` → `# Directory Structure`) for cross-framework doc-file parity — BEM names the same concept `docs/directory-structure.md`, and mirrored docs must match down to the file name. All references updated (`CLAUDE.md`, historical CHANGELOG links). Also normalized `docs/test-boot-layer.md`'s H1 to `# Test Framework — Boot Layer` (matches BXM; EM normalized likewise).
+
+### Added
+
+- **Docs parity — new `docs/build-system.md`, `docs/templating.md`, `docs/logging.md`, `docs/common-mistakes.md`.** `build-system.md` makes CLAUDE.md's existing pipeline-reference link real (was a dead link) — gulp task list, config flow, build modes, pure helpers; `templating.md` graduates from "(planned)" — node-powertools bracket conventions + Liquid coexistence; `logging.md` is now the SSOT for the log-file tee (extracted from local-development.md, which keeps a pointer — mirrors EM/BXM); `common-mistakes.md` extracts the canonical anti-pattern list into the repo (BEM already had one). All indexed in CLAUDE.md → Documentation.
+- **Test coverage convention (docs).** New mirrored "Test coverage" sections in `CLAUDE.md`, `docs/test-framework.md`, `src/defaults/CLAUDE.md`, and `src/defaults/test/README.md` — every feature ships with tests at every layer it has a surface in (logic `build`/`page`, UI `page`, end-to-end `boot`); a layer is skipped only when the feature genuinely has no surface there. Mirrored across EM/BXM/BEM.
+- **New `newsflash` theme — editorial news site.** Paper + ink + vermilion design language with volt highlights: Fraunces serif headlines over Schibsted Grotesk, a live news-ticker marquee above the sticky blurred masthead, framed editorial images, hard-offset "lift" pill buttons, film-grain overlay, and first-class dark mode (deep warm near-black paper, cream ink). Ships custom layouts for base (fonts + ticker), homepage (cover-story hero + top-story tiles + "the latest" editorial post feed with sticky most-read/newsletter rails + numbered rundown playbook + "more to chew on" story tiles + dark big-read CTA band), blog index (lead-story splash + editorial tiles), blog post (reading-progress bar, drop cap, serif crossheads, pullquotes, author card), blog category archives (desk directory with stroked story-count numerals + per-desk fronts), blog tag archives (topics wall + per-topic fronts), pricing (membership tiers with "Editor's pick" + flash-sale promo banner), about (newsroom timeline), contact ("contact the desk" + tips line), team ("the masthead" byline cards + ink-slab charter + newsroom principles), team member (reporter profile with beat facts strip), and a 404 "correction notice". Functional pages (download, feedback, updates, auth, account) intentionally inherit classy markup restyled. Select with `theme.id: "newsflash"`. See [docs/themes.md](docs/themes.md).
+- **Theme-authoring convention: genre-native frontmatter defaults.** A theme's layout frontmatter defaults are part of its identity and must be written for the theme's genre (newsflash ships news copy + news-purposed `rundown`/`desks` homepage sections), never copied from classy's SaaS demo data. Universal section keys (`hero`, `cta`, `stats`, `faqs`, `pricing.plans`, …) stay shared so consumer overrides survive theme swaps. Documented in [docs/themes.md](docs/themes.md#frontmatter-defaults-are-part-of-the-themes-identity) + the Path A authoring checklist.
+- **Appearance picker in every footer.** Classy's footer now ships the appearance (light/dark/system) dropdown next to the language dropdown — a pure drop-in block driven by the framework's `data-appearance-*` attributes. Every theme inherits it via the footer fallback; themes with custom footers (newsflash) include it themselves. Documented as required footer furniture in [docs/themes.md](docs/themes.md) + [docs/appearance.md](docs/appearance.md).
+- **Theme-authoring convention: inherit classy's nav + footer chrome, restyle via CSS.** Themes do NOT fork the chrome includes — `copyFallbackThemeFiles()` supplies classy's nav/footer (with paths rewritten into the theme's namespace) and the chrome's identity comes from theme CSS (newsflash's serif masthead + editorial ink-slab footer are pure `css/layout/` restyles of classy's markup). Fork an include only when the structure genuinely diverges — a re-skin fork is a copy that silently drifts (newsflash's nav fork had diverged from classy by nothing but a comment, and the icon-only picker fix had to be applied twice). Documented in [docs/themes.md](docs/themes.md) + the Path A authoring checklist.
+- **Theme-contract build test.** New `mgr:build/theme-contract` suite turns the docs/themes.md conventions into executable assertions, globbing every shipped theme (`_template` included) so a new theme is covered the moment it lands: entry files + `$avatar-sizes` + shared bootstrap-overrides import, `[ site.theme.id ]` bracket parents (swappability), no theme-prefixed classes in markup, no inline `<script>` bodies, the pricing JS-contract markers, `blog-post-content` in post layouts, and page-asset files matching a layout-declared `asset_path` shape (wrong shape = silent bundle skip). It caught neobrutalism's missing promo banner + `.card-title` on its first run.
+- **Shared plan-pricing include — `core/pricing/resolve-plan.html`.** The plan price-resolution Liquid (product lookup from `site.web_manager.payment.products`, frontmatter-over-config monthly/annual precedence, per-unit math) was copy-pasted across all three themes' pricing layouts; it's now a single shared "logic include" (Jekyll includes share caller scope) that every theme calls per plan and renders the assigned variables from. Also guards the per-unit `divided_by` against nil/zero unit values, which previously crashed the build when the per-unit feature value couldn't resolve.
+- **Theme-authoring convention: develop in ONE appearance mode, ship with BOTH.** Build against a primary mode (the consumer's `theme.appearance` default), then validate light AND dark before declaring the theme done — including a live click-through of the footer appearance picker. Documented in [docs/themes.md](docs/themes.md) authoring conventions + validation checklist.
+- **Theme-authoring gotchas documented:** theme page bundles re-emit Bootstrap after the main bundle (use doubled selectors — `:root:root`, `[data-bs-theme="dark"][data-bs-theme="dark"]`, `.btn.btn`), and `.bg-body-*`/`.text-body-*` utilities paint from the `--bs-*-rgb` companion variables, which must be remapped alongside the hex vars. See [docs/themes.md](docs/themes.md).
+- **`npx mgr blogify --count=<n>`.** The blogify command now accepts a post count (default 12, matching the old hardcoded behavior) — e.g. `--count=18` fills every deduplicated post slot on the newsflash homepage. Documented in README + the CLAUDE.md CLI table.
+- **`npx mgr test` tees output to `logs/test.log`.** All test-runner output is now duplicated (ANSI-stripped) to `<projectRoot>/logs/test.log`, truncated fresh on each run, via the existing `attach-log-file` util (skipped on CI through `isServer()`) — mirrors EM's and BEM's `test.log` pattern. Grep the file after a run instead of scrolling terminal scrollback.
+- **`TEST_EXTENDED_MODE` — extended test mode (`--extended`).** `npx mgr test --extended` (or `TEST_EXTENDED_MODE=true npx mgr test`) opts in tests that hit REAL external services (network fetches, Firebase via web-manager, live APIs); off by default so `npx mgr test` stays fast and offline-safe. The signal is the unprefixed `TEST_EXTENDED_MODE` env var — the SAME name across BEM/BXM/UJM/EM (cross-framework parity) — and once set it propagates to every spawned child (the Jekyll build, the boot HTTP server / Puppeteer browsers) via inherited `process.env`. A warning prints (and is teed to `logs/test.log`) when on. Gate live tests on `process.env.TEST_EXTENDED_MODE`. New `src/test/utils/extended-mode-warning.js` is the SSOT for the warning copy. Documented in [docs/test-framework.md](docs/test-framework.md#extended-mode-test_extended_mode) + the env-vars table.
+
+### Changed
+
+- **Test command standardizes on `TEST_EXTENDED_MODE`, replacing `--integration` / `UJ_TEST_INTEGRATION`** (no backwards compat — the old flag/env are gone). Mirrors the canonical unprefixed `TEST_EXTENDED_MODE` shared across BEM/BXM/EM.
+
+### Fixed
+
+- **`attach-log-file` no longer truncates `logs/test.log` mid-run.** The tee state is now wrapped in a `createTee()` factory (independent, stackable instances) with the process-wide singleton built on top. A later `attach()` captures the CURRENT `process.stdout.write` (which may already be an outer tee) and restores that exact reference on `detach()`, so stacked tees fan out and unwind in LIFO order. The new build-layer `attach-log-file` test uses its OWN `createTee()` instance, so exercising attach/detach no longer detaches the live singleton tee that's capturing the actual run (which previously cut `logs/test.log` to ~9 lines). UJM's name-based signature (`attachLogFile('test')`) and synchronous `detach()` are preserved. Mirrors EM's `createTee()` refactor.
+
+- **neobrutalism pricing page now satisfies the full framework JS contract.** Same two gaps newsflash had: the flash-sale promo banner block (`#pricing-promo-banner` + badge/text/countdown/code ids, shipped `hidden`) was missing entirely, and plan names lacked the `.card-title` class the pricing JS reads for analytics. Both caught by the new theme-contract test on its first run.
+- **Classy admin minimal layouts use bracket parents.** `admin/core/minimal.html` + `minimal-viewport-locked.html` hardcoded `layout: themes/classy/backend/...` instead of the `themes/[ site.theme.id ]/...` convention (the fallback's path rewrite masked it for non-classy themes). Normalized to brackets; now enforced by the theme-contract test.
+- **newsflash nav + dropdown hover text is readable again.** The hover fill (ink pill) left the label ink-on-ink: the shared nav/account includes put Bootstrap's `.text-body` utility (`!important`) on every link and dropdown item, which beat the theme's hover `color`. The hover/active colors now carry `!important`, and dropdown-item child spans with text utilities flip to `inherit` on hover (fixes the blacked-out account-dropdown rows too).
+- **newsflash dropdown item pills no longer press edge-to-edge against the panel.** Bootstrap's re-emitted `.dropdown-menu` rule (`--bs-dropdown-padding-x: 0`) was stripping the theme's panel inset on pages with page CSS — the highlighted pill touched the panel edges. The theme's dropdown rule now uses the doubled selector (`.dropdown-menu.dropdown-menu`), the established page-bundle-gotcha pattern.
+- **newsflash headings no longer go thin on pages with page CSS.** Bootstrap's re-emitted `.display-*` / `.lead` rules (stock weights 300) were clobbering the theme's main-bundle typography on every page that ships a page bundle (post + about read spindly; contact — no page bundle — looked right). Type metrics now ship as Bootstrap variables in the config `@forward with (...)` block (`$display-font-weight: 550`, `$display-line-height: 1.04`, `$lead-font-weight: 400`, `$headings-line-height: 1.1`, `$line-height-base: 1.55`) so every Bootstrap copy compiles them natively. Documented as an extension of the page-bundle gotcha in [docs/themes.md](docs/themes.md).
+- **newsflash post hero image fills its frame.** Two stacked causes: `uj_post` image-tags render as `<picture><img>`, so the img's percentage height resolved against the auto-height picture wrapper (the base `.art-frame` now makes `picture` fill the frame), and the framework's generic `.blog-post-image { max-height: 480px }` capped the image inside the 21/10 frame (the article-hero rule now lifts it with `max-height: none`).
+- **Footer brand description no longer disappears when its data value liquifies to empty.** Both classy's and newsflash's footers resolve the brand blurb via `data.logo.description | default: site.brand.description`, but `default:` only sees the RAW string — a footer.json value like `'{{ site.meta.description }}'` with no `meta.description` set passed the default check and then liquified to nothing, hiding the description even when `brand.description` was set. The footers now re-check after liquification and fall back to `site.brand.description`.
+- **newsflash dark mode no longer stomps consumer brand colors.** The dark-mode `--bs-primary`/`--bs-link-color` remaps were hardcoded to the brightened vermilion, so a consumer's `$primary` override (via `main.scss` `with (...)`) held in light mode but snapped back to vermilion in dark. The remap now derives from the compile-time `$primary` (stock vermilion keeps its hand-tuned brightening; other brand colors get a generic white-mix lift). Documented as a theme-authoring gotcha in [docs/themes.md](docs/themes.md#derive-dark-mode-brand-remaps-from-primary-gotcha).
+- **newsflash pricing page now satisfies the full framework JS contract.** Added the flash-sale promo banner (`#pricing-promo-banner` + badge/text/countdown/code ids, shipped `hidden` — the framework pricing JS reveals it, fills the rotating sale name + countdown, and offsets the masthead) and the `.card-title` class on plan names (read for add-to-cart analytics). The pricing JS contract — billing radios, `.amount`/`.billing-info`/`.price-per-unit` data attributes, `button[data-plan-id]`, plan-name selector, promo banner ids — is now documented as a required cross-theme contract in [docs/themes.md](docs/themes.md#the-pricing-page-has-a-js-contract-too).
+- **`npx mgr test <target>` now correctly scopes by source.** The positional test target was previously ignored — every run executed all suites regardless of the argument. It now selects which test FILES run: `project:` runs project tests only, `mgr:` / `ujm:` / `framework:` run framework tests only (`mgr:` is the universal cross-framework alias, equivalent to the UJM-specific `ujm:` / `framework:`), and a bare path (no prefix) matches both sources. The `--filter=<substring>` flag stays orthogonal — it matches test NAMES within the already-selected files and composes with the target. See [docs/test-framework.md](docs/test-framework.md#filtering-tests).
+
 ---
 ## [1.7.2] - 2026-06-09
 
@@ -21,6 +85,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 - **Push notification subscribe on payment confirmation CTA click** — hooks `subscribe()` onto CTA button clicks on the payment confirmation page. Requires a user gesture for the browser permission prompt, so uses `{ once: true }` click listeners.
 
+### Fixed
+
+- **FormManager spinner layout in icon-only buttons** — `_showSpinner()` no longer adds `me-2` margin when `submittingText` is empty. Previously, the unnecessary right margin squished the spinner off-center in small round buttons (e.g. chat send).
+
 ---
 ## [1.7.1] - 2026-06-09
 
@@ -358,7 +426,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
-- **`docs/<topic>.md` deep references** — 17 new files referenced by the v1.2.0 CLAUDE.md reorg that hadn't been committed yet: `ads.md`, `analytics.md`, `appearance.md`, `assets.md`, `audit.md`, `css.md`, `icons.md`, `images.md`, `javascript-libraries.md`, `jekyll-plugin.md`, `layouts-and-pages.md`, `lazy-loading.md`, `local-development.md`, `page-loading.md`, `project-structure.md`, `seo.md`, `xss-prevention.md`. Restores parity with the cross-links already shipped in [CLAUDE.md](CLAUDE.md).
+- **`docs/<topic>.md` deep references** — 17 new files referenced by the v1.2.0 CLAUDE.md reorg that hadn't been committed yet: `ads.md`, `analytics.md`, `appearance.md`, `assets.md`, `audit.md`, `css.md`, `icons.md`, `images.md`, `javascript-libraries.md`, `jekyll-plugin.md`, `layouts-and-pages.md`, `lazy-loading.md`, `local-development.md`, `page-loading.md`, `directory-structure.md`, `seo.md`, `xss-prevention.md`. Restores parity with the cross-links already shipped in [CLAUDE.md](CLAUDE.md).
 - **`src/defaults/docs/README.md`, `src/defaults/test/README.md`, `src/defaults/CHANGELOG.md`** — consumer-project scaffolding files distributed via the `defaults` gulp task.
 
 ---

package/CLAUDE.md

@@ -8,7 +8,7 @@ Ultimate Jekyll Manager (UJM) is a comprehensive framework for building modern J
 
 - One-line bootstrap per context (build / frontend / service-worker)
 - Multi-stage gulp pipeline (15 tasks: defaults / distribute / webpack / sass / imagemin / jekyll / jsonToHtml / preprocess / audit / translation / minifyHtml / serve / setup / developmentRebuild)
-- Default Jekyll layouts + themes (`classy` + `neobrutalism` shipped; new themes inherit classy's layouts via the build-time fallback — see [docs/themes.md](docs/themes.md))
+- Default Jekyll layouts + themes (`classy` + `neobrutalism` + `newsflash` shipped; new themes inherit classy's layouts AND nav/footer chrome via the build-time fallback — restyle chrome via theme CSS, fork an include only on real structural divergence — ship **genre-native frontmatter defaults**, and must validate **both appearance modes**; conventions are enforced by the build-layer **theme-contract test** — see [docs/themes.md](docs/themes.md))
 - Frontend ES-module Manager with dynamic per-page module loading
 - Service worker with Firebase Messaging + cache management
 - A built-in **three-layer test framework** (build / page / boot)
@@ -22,7 +22,7 @@ The only things that ARE safe to run inside UJM itself:
 
 ## Recommended skills
 
-- **`UJM:patterns`** — SSOT for Ultimate Jekyll Manager architecture, gulp pipeline, frontend Manager, and theme conventions. Auto-loads on UJM-specific keywords (`_config.yml`, `theme.id`, `uj_icon`, `page.resolved`, `npx mgr setup`, etc.) and when touching files in `src/_layouts/`, `src/_includes/`, `src/pages/`, `src/assets/`, `config/ultimate-jekyll-manager.json`.
+- **`omega:ujm`** — router skill. Auto-loads on UJM-specific keywords (`_config.yml`, `theme.id`, `uj_icon`, `page.resolved`, `npx mgr setup`, etc.) and points back to this CLAUDE.md + `docs/` (the SSOT), carrying only Claude-workflow hard rules and process checklists.
 - **`js:patterns`** — JavaScript/Node.js conventions: file structure, JSDoc, defensive coding (`?.` usage), template literals, `package.json` conventions. Auto-loads when creating new `.js` files or touching JS module structure.
 
 ## 🚨 READ WEB-MANAGER TOO
@@ -43,16 +43,19 @@ The only things that ARE safe to run inside UJM itself:
 4. `npm run build` — production build (`UJ_BUILD_MODE=true`)
 5. `npm run deploy` — build + `npu sync --message='Deploy'`
 6. `npm test` (or `npx mgr test`) — runs framework + project test suites
-   - `npx mgr test pages/home` — run a specific test by path (relative to `test/`)
+   - `npx mgr test pages/home` — run a specific test by path (relative to `test/`, matches both sources)
+   - `npx mgr test project:` — run ONLY consumer project tests (`project:custom-test` to match a path)
+   - `npx mgr test mgr:` — run ONLY framework tests (`ujm:` / `framework:` are equivalent UJM aliases)
    - `npx mgr test ujm:pages/home` — run only framework tests matching a path
-   - `npx mgr test project:custom-test` — run only consumer project tests matching a path
-   - Prefix with `TEST_EXTENDED_MODE=true` for tests that hit real external APIs
+   - The `--filter=<substring>` flag matches test NAMES within the selected files (composes with the target); `--layer=build|page|boot` narrows to one layer
+   - Output is teed (ANSI-stripped) to `<projectRoot>/logs/test.log`, truncated fresh each run (skipped on CI) — `cat logs/test.log` instead of scrolling scrollback
+   - `--extended` (or `TEST_EXTENDED_MODE=true`) opts in tests that hit real external services — off by default, unprefixed name shared across BEM/BXM/UJM/EM, propagates to spawned envs (Jekyll/boot server); see [docs/test-framework.md](docs/test-framework.md#extended-mode-test_extended_mode)
 
 ### For Framework Development (This Repository)
 
 1. `npm install` — install UJM's own deps
 2. `npm start` (≡ `npm run prepare:watch`) — copies `src/` → `dist/` on file change
-3. Test in a consumer project: from inside the consumer, run `npx mgr install dev` to swap UJM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/ultimate-jekyll-manager`). Reverse with `npx mgr install live`.
+3. Test in the **designated test consumer** — `../ultimate-jekyll-website` is UJM's consumer for validating framework changes end-to-end (exercise any consumer-level flow there freely: builds, tests, runtime). From inside it, run `npx mgr install dev` to swap UJM to this local repo — required whenever you edit the framework source and want the consumer to pick up the changes (the consumer otherwise keeps its installed `node_modules/ultimate-jekyll-manager`). Reverse with `npx mgr install live`.
 4. `npm test` — runs UJM's own 60 test suites
 
 ## Architecture
@@ -96,7 +99,7 @@ UJM uses node-powertools' `template()` with two bracket conventions:
 - `{ x }` (default) — used wherever `template()` is called without `brackets:` (e.g. defaults.js Gemfile templating)
 - `[ x ]` — used by distribute.js theme fallback and [template-transform.js](src/gulp/tasks/utils/template-transform.js) (for `.html/.md/.liquid/.json`)
 
-Jekyll's Liquid `{{ }}` is processed by Jekyll itself, NOT by node-powertools — those placeholders pass through node-powertools untouched. See [docs/templating.md](docs/templating.md) (planned).
+Jekyll's Liquid `{{ }}` is processed by Jekyll itself, NOT by node-powertools — those placeholders pass through node-powertools untouched. See [docs/templating.md](docs/templating.md).
 
 ### Frontend Manager (`src/index.js`)
 
@@ -135,6 +138,10 @@ Cache name is `${brand.id}-${cache_breaker}` from `UJ_BUILD_JSON.config`. See [d
 
 Same `{ layer, description, run(ctx) }` contract as EM/BXM. JSON-line reporter protocol uses `__UJM_TEST__` marker. See [docs/test-framework.md](docs/test-framework.md) + [docs/test-boot-layer.md](docs/test-boot-layer.md).
 
+### Test coverage
+
+Every feature ships with tests at EVERY layer it has a surface in — logic (`build`, or `page` for frontend module logic), UI (`page` — real events on the real DOM), and end-to-end (`boot`). Skip a layer ONLY when the feature genuinely has no surface there (a pure build utility has no UI; a CSS-only tweak has no logic). "The logic test already covers it" is NOT a reason to skip the UI test — logic tests prove the logic, UI tests prove the wiring, boot tests prove the built site. See [docs/test-framework.md](docs/test-framework.md).
+
 ## CLI
 
 `npx mgr <command>` (aliases `uj`, `ujm`, `ultimate-jekyll`):
@@ -152,15 +159,22 @@ Same `{ layer, description, run(ctx) }` contract as EM/BXM. JSON-line reporter p
 | `minify-html` | minify HTML (preserves JSON-LD + inline scripts + IE conditional comments) |
 | `optimize` | AI-optimize pages via OpenAI |
 | `migrate` | migrate consumer project layout (legacy → current) |
-| `blogify` | generate test blog posts from Unsplash |
+| `blogify` | generate test blog posts from Unsplash (`--count=<n>`, default 12) |
 | `cloudflare-purge` | purge Cloudflare cache |
 | `test` | run framework + project test suites (three layers) |
 
 Note: `-t` short alias belongs to `translation`. The `test` command uses `--test` flag + `test` positional only. See [docs/cli.md](docs/cli.md) (planned).
 
+## Dependency Resolution
+
+- **Consumer code can `import`/`require()` any UJM dependency** — webpack's `resolve.modules` includes the framework's own `node_modules/`. Consumer projects do NOT need to `npm install firebase`, `web-manager`, or any other UJM transitive dep. If a dep doesn't resolve, the fix is in UJM's webpack config — not the consumer's `package.json`.
+- **web-manager owns Firebase.** Consumer code NEVER imports Firebase directly (`import firebase from 'firebase/app'`). Use `import webManager from 'web-manager'` → `webManager.auth()`, `webManager.firestore()`. Same rule in EM and BXM.
+- **`Manager.require(name)`** resolves from UJM's module context at runtime (static + prototype). Use in gulp tasks or unbundled code (e.g. test fixtures). Webpack `resolve.modules` handles the bundled case.
+
 ## Development Workflow
 
-- **🚫 NEVER run `npm start` / `npm run build` / `npm test` in a consumer project** unless the user explicitly asks. The user runs the dev server — running it again kills theirs. Instead, **check `logs/dev.log`** after editing files to confirm the watcher recompiled successfully (`Reloading Browsers...` = success; `errored` = fix the error). If editing multiple files, check the log once after the last edit. A change that breaks the build is not a completed change.
+- **🚫 NEVER run `npm start` in a consumer project** — the user runs the dev server; running it again kills theirs. Assume it's already running; if it isn't, **instruct the user to run it** rather than running it yourself. Instead, **check `logs/dev.log`** after editing files to confirm the watcher recompiled successfully (`Reloading Browsers...` = success; `errored` = fix the error) — never tail/attach to the process. If editing multiple files, check the log once after the last edit. A change that breaks the build is not a completed change. Running `npx mgr test` is fine.
+- **Live-test UI changes via CDP.** After code changes compile, use the `chrome-devtools` MCP tools (screenshots, click, evaluate JS, console logs) to verify the change works in the running browser. This is the primary way to confirm UI changes — type-checking and test suites verify code correctness, not feature correctness. See `~/.claude/mcp-server/servers/chrome-devtools/CLAUDE.md`.
 
 ## File Conventions
 
@@ -195,26 +209,32 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 - [docs/test-boot-layer.md](docs/test-boot-layer.md) — boot layer deep-dive (_site/ discovery, HTTP server, fixture vs consumer)
 - [docs/environment-detection.md](docs/environment-detection.md) — `isTesting`/`isDevelopment`/`isProduction`/`getVersion`
 - [docs/jekyll-plugin.md](docs/jekyll-plugin.md) — UJ Powertools gem: filters, tags, page variables (`page.resolved`, `uj_icon`, `uj_hash`, `iftruthy`, etc.)
-- [docs/audit.md](docs/audit.md) — workflow for fixing issues raised by `gulp/tasks/audit.js`
+- [docs/audit.md](docs/audit.md) — full-audit check catalog (U-xx universal / UJM-xx / F-xx IDs with severity + scope), protocol + fix loop, `npx mgr audit` automated stage
+- [docs/migration.md](docs/migration.md) — full migration (old UJ → latest UJM base), `_config.yml` quick-fix schema, revert-posts procedure
 
 ### Project & dev environment
 
-- [docs/project-structure.md](docs/project-structure.md) — UJM repo layout and consuming-project layout
-- [docs/local-development.md](docs/local-development.md) — browsersync URL, Firebase emulator connect, PurgeCSS safelist, log files (`logs/dev.log`, `logs/build.log`)
+- [docs/directory-structure.md](docs/directory-structure.md) — UJM repo layout and consuming-project layout
+- [docs/build-system.md](docs/build-system.md) — gulp pipeline (15 tasks), config flow, build modes, pure helpers
+- [docs/templating.md](docs/templating.md) — node-powertools bracket conventions, Liquid coexistence
+- [docs/local-development.md](docs/local-development.md) — browsersync URL, Firebase emulator connect, PurgeCSS safelist
+- [docs/logging.md](docs/logging.md) — `dev.log` / `build.log` / `test.log` tee, CI skip
+- [docs/common-mistakes.md](docs/common-mistakes.md) — the canonical "don't do this" list
 - [docs/assets.md](docs/assets.md) — UJM vs consumer file layout, section config (nav/footer/account), frontmatter-driven page customization, webpack aliases, page module pattern
 
 ### Pages, layouts, content
 
 - [docs/animation-studio.md](docs/animation-studio.md) — Animation Studio admin page: clip registration via `window.STUDIO_CLIPS`, helpers (`animate`, `el`, `flowClip`, `cardClip`, `chatClip`), resolution picker, recording, aspect ratio modes
 - [docs/themes.md](docs/themes.md) — theme system: selection + resolution (SCSS loadPaths, `__theme__`, classy layout fallback), shared vs per-theme layers, authoring a theme inside UJM OR in a consumer project, live validation
-- [docs/layouts-and-pages.md](docs/layouts-and-pages.md) — page types, layout chain, `asset_path` frontmatter
+- [docs/layouts-and-pages.md](docs/layouts-and-pages.md) — page types, layout chain, `asset_path` frontmatter, default-page customization rules + per-page levels, dashboard list/detail/edit pattern, custom page creation
 - [docs/images.md](docs/images.md) — `@post/` shortcut for blog post images, BEM admin/post image handling, imagemin pipeline + source-size constraints + `UJ_IMAGEMIN_REWRITE_SOURCES` cleanup flag
 - [docs/icons.md](docs/icons.md) — Font Awesome conventions, `{% uj_icon %}` vs prerendered icons in JS, size reference, country flag SVGs (`assets/icons/flags/modern-square/`)
-- [docs/seo.md](docs/seo.md) — Alternatives collection (competitor comparison pages) + Schema/JSON-LD (`SoftwareApplication`, `FAQPage`)
+- [docs/seo.md](docs/seo.md) — content writing rules (headlines, sentence case, accents), Services/Solutions page strategies, Alternatives collection (competitor comparison pages), Schema/JSON-LD (`SoftwareApplication`, `FAQPage`)
 
 ### Frontend behavior
 
 - [docs/css.md](docs/css.md) — section padding rule, theme-adaptive classes, cards in colored sections, `<html>` data attributes
+- [docs/purgecss.md](docs/purgecss.md) — PurgeCSS safelist playbook: two safelist locations, RegExp anchoring, gotchas (`variables: false`, per-file processing), current UJM safelist
 - [docs/appearance.md](docs/appearance.md) — dark/light/system mode switching: JS API, HTML attributes
 - [docs/page-loading.md](docs/page-loading.md) — page-loading protection, `.btn-action`, layered form-protection strategy
 - [docs/lazy-loading.md](docs/lazy-loading.md) — `data-lazy="@type value"` syntax and supported types
@@ -222,7 +242,8 @@ Deep references live in `docs/`. Treat docs as a first-class deliverable. **When
 
 ### JS libraries & security
 
-- [docs/javascript-libraries.md](docs/javascript-libraries.md) — WebManager singleton + UJM libs at `src/assets/js/libs/` (prerendered icons, authorizedFetch, usage bindings, payment-config, FormManager)
+- [docs/javascript-libraries.md](docs/javascript-libraries.md) — WebManager singleton + UJM libs at `src/assets/js/libs/` (prerendered icons, authorizedFetch, usage bindings, payment-config, FormManager), reads-vs-writes rule (Firestore SDK for reads, Cloud Functions for writes)
+- [docs/no-inline-scripts.md](docs/no-inline-scripts.md) — HARD RULE: no inline `<script>` bodies; full migration playbook incl. Liquid `data-*`/`<template>` bridges
 - [docs/xss-prevention.md](docs/xss-prevention.md) — zero-trust DOM injection rules, `escapeHTML`, postMessage origin checks, redirect validation
 
 ### Analytics

package/README.md

@@ -28,7 +28,7 @@
 * **SEO Optimized**: Ultimate Jekyll is fully SEO optimized.
 * **Blazingly Fast**: Ultimate Jekyll is blazingly fast.
 * **NPM & Gulp**: Ultimate Jekyll is fueled by an intuitive incorporation of npm and gulp.
-* **Themes**: Pick a shipped theme with `theme.id` (`classy` or `neobrutalism`), or author your own. New themes inherit all default page layouts automatically and only restyle/override what differs. See [docs/themes.md](docs/themes.md).
+* **Themes**: Pick a shipped theme with `theme.id` (`classy`, `neobrutalism`, or `newsflash` — an editorial news-site theme), or author your own. New themes inherit all default page layouts automatically and only restyle/override what differs. See [docs/themes.md](docs/themes.md).
 * **Built-in test framework**: three layers (`build` / `page` / `boot`) — plain Node, headless Chromium tab, headless Chromium against real `_site/` with SW registration verification.
 
 ## 🚀 Getting started
@@ -48,6 +48,7 @@ npx mgr test                   # all layers
 npx mgr test --layer build     # plain Node, fast
 npx mgr test --layer page      # headless Chromium tab against harness HTML
 npx mgr test --layer boot      # headless Chromium against built _site/
+npx mgr test --extended        # also run tests that hit real external services (off by default)
 ```
 
 Test files use Jest-compatible matchers:
@@ -183,9 +184,10 @@ npm run prepare:watch
 ```
 
 ### Run the `blogify` task:
-Create 12 test blog posts in the `_posts` directory with the `blogify` task. This is useful for testing and development purposes.
+Create test blog posts in the `_posts` directory with the `blogify` task (default 12; pass `--count=<n>` for more — e.g. 18 fills every post slot on the newsflash homepage). This is useful for testing and development purposes.
 ```bash
 npx mgr blogify
+npx mgr blogify --count=18
 ```
 
 ## Page Frontmatter

package/TODO-AUTH-TESTING.md

@@ -162,4 +162,4 @@ The test harness should stay vanilla Mocha + JSDOM + fixture HTML files.
 - All 6 test files above written and green
 - `npm test` in UJM runs them as part of the standard suite
 - The v1.3.1 bug (consent guard ordering) is caught by `auth-guard-ordering.test.js` — verify by reverting the v1.3.2 fix in a branch and watching the test fail
-- Documented in `docs/testing.md` so contributors know to add auth tests when touching auth code
+- Documented in `docs/test-framework.md` so contributors know to add auth tests when touching auth code

package/dist/assets/themes/newsflash/README.md

@@ -0,0 +1,58 @@
+# Newsflash Theme
+
+An editorial news theme: warm paper surfaces, ink text and hairline frames,
+vermilion accents with volt highlights, optical-sized serif headlines
+(Fraunces) over a clean grotesk (Schibsted Grotesk). Signature elements: the
+live news ticker above the masthead, framed editorial images, kickers,
+section rules, drop caps, and pill controls that lift off small hard shadows.
+
+## Select the theme
+
+```yaml
+# src/_config.yml (consuming project)
+theme:
+  id: "newsflash"
+  target: "frontend"
+  appearance: "light" # or "dark" / "system" — dark mode is first-class
+```
+
+## Customize tokens
+
+Every variable in `_config.scss` is `!default` — override any of them in your
+project BEFORE the theme import:
+
+```scss
+// src/assets/css/main.scss (consuming project)
+@use 'ultimate-jekyll-manager' with (
+  $primary: #0E7C3A,                  // swap vermilion for forest green
+  $nf-volt: #FFD966,                  // warmer highlighter
+  $nf-radius: 12px,                   // tighter frames
+  $nf-font-display: ('Lora', serif),  // different serif voice
+);
+```
+
+Runtime tokens live in `css/base/_root.scss` as `--nf-*` CSS custom
+properties; dark mode is a single `[data-bs-theme="dark"]` remap block.
+
+## What ships custom
+
+- **Layouts** (`_layouts/themes/newsflash/`): base (ticker + fonts), homepage,
+  blog index, blog post, pricing, about, contact, 404. Everything else
+  inherits Classy markup restyled by this theme's CSS.
+- **Chrome** (`_includes/themes/newsflash/frontend/sections/`): the serif
+  masthead nav + the editorial ink-slab footer (volt column heads, language +
+  appearance pickers in the bottom rail). Same `nav.json`/`footer.json` data
+  contract as classy.
+- **Page assets** (`pages/`): homepage rails/big-read band, blog index splash,
+  blog post reading-progress + drop cap, pricing/about/404 accents.
+- **Behaviors** (`js/`): masthead scroll shadow, Bootstrap tooltips. The
+  ticker and marquees are pure CSS.
+
+## Conventions
+
+- Markup uses standard Bootstrap classes + universal semantic names
+  (`.kicker`, `.ticker`, `.section-head`, `.art-frame`) — never `nf-*`
+  prefixes. `nf-*` survives only on SCSS internals (`$nf-*`, `--nf-*`,
+  mixins).
+- Fonts load via the `theme.head.content` block in
+  `_layouts/themes/newsflash/frontend/core/base.html`, never SCSS `@import`.

package/dist/assets/themes/newsflash/_config.scss

@@ -0,0 +1,138 @@
+// Newsflash Theme Configuration
+// ALL customizable variables are defined here with !default.
+// Consuming projects override any of these BEFORE the theme is imported.
+//
+// Design language: warm paper surfaces; ink text + hairline ink frames;
+// vermilion accents with volt highlights; serif display type over a clean
+// grotesk; pill controls sitting on small hard offset shadows that "lift"
+// on hover. An editorial newsroom — modern front page, not a brochure.
+
+// ============================================
+// Bootstrap Color Overrides
+// ============================================
+// Editorial ink-and-accent palette mapped onto Bootstrap's semantic colors.
+$primary:    #F03612 !default;   // vermilion — the signature accent
+$secondary:  #5C544A !default;   // ink-soft — muted secondary actions
+$success:    #2E7D4F !default;   // editorial green
+$info:       #2742F5 !default;   // electric blue
+$warning:    #D9F24E !default;   // volt — highlighter yellow-green
+$danger:     #C81E1E !default;   // deep red (distinct from vermilion)
+$light:      #F7F2E7 !default;   // paper
+$dark:       #171310 !default;   // ink
+
+// ============================================
+// Paper & Ink (the structural neutrals)
+// ============================================
+// "Paper" = the page surface. "Ink" = text, frames, and hard shadows.
+$nf-paper:          #F7F2E7 !default;   // body background (light mode)
+$nf-paper-2:        #EFE8D8 !default;   // wells / alt surfaces (light mode)
+$nf-ink:            #171310 !default;   // text + frames (light mode)
+$nf-ink-soft:       #5C544A !default;   // deks, metas, muted text (light mode)
+
+// Dark mode counterparts — deep warm near-black paper, cream ink.
+$nf-paper-dark:     #181210 !default;
+$nf-paper-2-dark:   #221A14 !default;
+$nf-ink-dark:       #F2E8D9 !default;
+$nf-ink-soft-dark:  #A8998A !default;
+
+// ============================================
+// Accent Palette
+// ============================================
+$nf-vermilion:           #F03612 !default;
+$nf-vermilion-dark-mode: #FF4A26 !default;  // brightened for contrast on dark paper
+$nf-blue:                #2742F5 !default;
+$nf-blue-dark-mode:      #5B72FF !default;
+$nf-volt:                #D9F24E !default;  // stays vibrant in both modes
+$nf-volt-ink:            #171310 !default;  // readable text on volt
+
+// Ink panels (footer, ticker, big-read band) — dark slabs in BOTH modes.
+$nf-panel-bg:         #171310 !default;
+$nf-panel-color:      #F7F2E7 !default;
+$nf-panel-bg-dark:    #0E0B09 !default;     // deeper than dark paper so it still reads as a slab
+$nf-panel-color-dark: #F2E8D9 !default;
+
+// ============================================
+// Borders — hairline ink frames
+// ============================================
+$nf-border-width: 1.5px !default;
+$nf-radius:       18px !default;   // frames, cards, panels
+$nf-radius-sm:    12px !default;   // small frames, inputs
+
+// ============================================
+// Shadows — small hard offsets (controls) + soft pop (frames)
+// ============================================
+// Controls rest on a 3px hard ink shadow and LIFT on hover (shadow grows to
+// 6px while the element translates up-left). Frames use a soft "pop" blur.
+$nf-shadow-offset:       3px !default;
+$nf-shadow-offset-hover: 6px !default;
+$nf-shadow-pop: 0 18px 40px -18px rgba(23, 19, 16, .35) !default;
+
+// ============================================
+// Typography
+// ============================================
+// Fraunces (optical-sized serif) for display; Schibsted Grotesk for body/UI.
+$font-family-sans-serif: 'Schibsted Grotesk', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif !default;
+$nf-font-display: 'Fraunces', Georgia, 'Times New Roman', serif !default;
+
+$headings-font-weight: 600 !default;
+$nf-heading-letter-spacing: -0.02em !default;
+$font-weight-bold: 700 !default;
+
+// ============================================
+// Motion — smooth editorial easing
+// ============================================
+$nf-transition: all 0.2s cubic-bezier(0.22, 1, 0.36, 1) !default;
+
+// ============================================
+// Component Sizing
+// ============================================
+// Avatar sizes map (matches Classy so shared layouts/includes render correctly)
+$avatar-sizes: (
+  null: 3rem,
+  2xs: 0.5rem,
+  xs: 1.5rem,
+  sm: 2rem,
+  md: 2.5rem,
+  lg: 3.5rem,
+  xl: 5rem,
+  2xl: 7.5rem,
+  3xl: 10rem,
+  4xl: 12.5rem,
+  5xl: 15rem
+) !default;
+
+// ============================================
+// Forward Bootstrap with our configuration
+// ============================================
+@forward '../bootstrap/scss/bootstrap.scss' with (
+  $primary: $primary,
+  $secondary: $secondary,
+  $success: $success,
+  $info: $info,
+  $warning: $warning,
+  $danger: $danger,
+  $light: $light,
+  $dark: $dark,
+  $font-family-sans-serif: $font-family-sans-serif,
+  $headings-font-family: $nf-font-display,
+  $headings-font-weight: $headings-font-weight,
+  $font-weight-bold: $font-weight-bold,
+  // Type metrics MUST live in Bootstrap vars (not element rules in the main
+  // bundle): page bundles re-emit Bootstrap AFTER main, so Bootstrap's own
+  // .display-*/.lead/body rules would win there with the stock 300 weights.
+  $headings-line-height: 1.1,
+  $display-font-family: $nf-font-display,
+  $display-font-weight: 550,
+  $display-line-height: 1.04,
+  $lead-font-weight: 400,
+  $line-height-base: 1.55,
+  // Hairline ink borders everywhere; editorial radii (controls go pill in
+  // component SCSS — cards/frames keep these).
+  $border-width: $nf-border-width,
+  $border-radius: $nf-radius-sm,
+  $border-radius-sm: 8px,
+  $border-radius-lg: $nf-radius,
+  $border-radius-xl: 24px,
+  $enable-shadows: false,
+  $enable-negative-margins: true
+);

package/dist/assets/themes/newsflash/_theme.js

@@ -0,0 +1,27 @@
+// Newsflash Theme — JS entry point
+// Loaded at runtime via webpack's __theme__ alias (import('__theme__/_theme.js')).
+// Exposes Bootstrap globally and wires up theme behaviors on DOM ready.
+import bootstrap from '__main_assets__/themes/bootstrap/js/index.umd.js';
+import { ready as domReady } from 'web-manager/modules/dom.js';
+
+// Make Bootstrap available globally (used by UJM utilities + components)
+window.bootstrap = bootstrap;
+
+/* @dev-only:start */
+{
+  console.log('Newsflash theme loaded successfully (assets/themes/newsflash/_theme.js)');
+}
+/* @dev-only:end */
+
+// Theme behaviors
+import setupMastheadScroll from './js/masthead-scroll.js';
+import initializeTooltips from './js/initialize-tooltips.js';
+
+// Initialize when DOM is ready
+domReady().then(() => {
+  // Newsflash behaviors
+  setupMastheadScroll();
+
+  // Generic Bootstrap initializations
+  initializeTooltips();
+});

package/dist/assets/themes/newsflash/_theme.scss

@@ -0,0 +1,37 @@
+// Newsflash Theme — SCSS entry point
+// Forwards config (so consuming projects can override vars), loads Bootstrap
+// via config, then layers the editorial system on top. Import order matters:
+// config → mixins → root vars → base → layout → components → bootstrap overrides.
+
+// Forward theme configuration (allows consuming project to override)
+@forward 'config';
+@use 'config' as *;
+
+// Mixins must be available to every partial below.
+// @import (not @use) so the mixins land in the global scope the @imports share.
+@import 'css/base/mixins';
+
+// CSS custom properties (light/dark bridge)
+@import 'css/base/root';
+
+// Base styles
+@import 'css/base/typography';
+@import 'css/base/utilities';
+
+// Layout styles
+@import 'css/layout/general';
+@import 'css/layout/navigation';
+
+// Component styles
+@import 'css/components/buttons';
+@import 'css/components/cards';
+@import 'css/components/forms';
+@import 'css/components/badges';
+@import 'css/components/ticker';
+@import 'css/components/editorial';
+@import 'css/components/panels';
+@import 'css/components/infinite-scroll';
+
+// Universal Bootstrap overrides (shared across all UJ themes).
+// Must come AFTER Bootstrap is loaded via config to use @extend.
+@import '../bootstrap/overrides';

package/dist/assets/themes/newsflash/css/base/_mixins.scss

@@ -0,0 +1,50 @@
+// Newsflash Theme — Mixins
+// The shared building blocks of the editorial look. Components @include these
+// so the frame/shadow/lift system lives in ONE place (SSOT) rather than being
+// copy-pasted across buttons, cards, inputs, etc.
+
+// Hairline frame in the current ink color.
+@mixin nf-border($width: var(--nf-border-width)) {
+  border: $width solid var(--nf-border-color);
+}
+
+// Small hard offset shadow (no blur) — the resting state of controls.
+@mixin nf-shadow-hard() {
+  box-shadow: var(--nf-shadow-hard);
+}
+
+// Soft "pop" shadow — depth for frames and panels (hero art, signup rail).
+@mixin nf-shadow-pop() {
+  box-shadow: var(--nf-shadow-pop);
+}
+
+// The signature interaction: the element rests on a small hard shadow, then
+// LIFTS up-left on hover (shadow grows beneath it) and presses flush on
+// active. Pure transform + shadow — no color shift.
+@mixin nf-lift() {
+  transition: $nf-transition;
+
+  &:hover {
+    transform: translate(-2px, -2px);
+    box-shadow: var(--nf-shadow-hard-hover);
+  }
+
+  &:active {
+    transform: translate(0, 0);
+    box-shadow: 1px 1px 0 var(--nf-shadow-color);
+  }
+}
+
+// Headline hover underline — an accent rule that grows from the left under
+// the text (the editorial "this is a link" affordance on serif headlines).
+@mixin nf-underline-grow($color: var(--bs-primary), $thickness: 2px) {
+  background-image: linear-gradient($color, $color);
+  background-repeat: no-repeat;
+  background-size: 0% $thickness;
+  background-position: 0 96%;
+  transition: background-size 0.35s cubic-bezier(0.22, 1, 0.36, 1);
+
+  &:hover {
+    background-size: 100% $thickness;
+  }
+}