ultimate-jekyll-manager 1.7.2 → 1.8.1

package/dist/test/suites/build/theme-contract.test.js

@@ -0,0 +1,173 @@
+// Theme contract — structural invariants every shipped theme must satisfy
+// (docs/themes.md conventions turned into executable assertions). Globs the
+// theme directories, so a new theme is covered the moment it lands:
+//   1. Entry files exist ($avatar-sizes map, shared bootstrap overrides import)
+//   2. Layouts are swappable (parent refs use [ site.theme.id ] brackets,
+//      no theme-prefixed classes in markup, no inline <script> bodies)
+//   3. Cross-theme JS contracts hold (pricing data attributes, blog-post-content)
+//   4. Page asset files use a shape the layouts' asset_path frontmatter declares
+//      (wrong shape = silent bundle skip)
+
+const path = require('path');
+const jetpack = require('fs-jetpack');
+const glob = require('glob').globSync;
+
+const ROOT = path.join(__dirname, '../../../..');
+const ASSETS = path.join(ROOT, 'src/assets/themes');
+const LAYOUTS = path.join(ROOT, 'src/defaults/dist/_layouts/themes');
+const INCLUDES = path.join(ROOT, 'src/defaults/dist/_includes/themes');
+
+// _template is held to the asset contract too — it's what theme authors copy.
+// bootstrap is the shared Bootstrap source, not a theme.
+const themes = jetpack.list(ASSETS).filter((t) => t !== 'bootstrap');
+
+// Class tokens that would couple markup to one theme (markup must stay
+// swappable; theme prefixes live only in SCSS internals)
+const THEME_PREFIXES = ['nf-', 'nb-', 'classy-', 'newsflash-', 'neobrutalism-', 'broadsheet-', 'template-'];
+
+// Markers the framework pricing JS reads — identical across themes by contract
+// (see docs/themes.md "Pricing page JS contract")
+const PRICING_MARKERS = ['data-plan-id', 'billing-info', 'price-per-unit', 'pricing-promo-banner', 'card-title', 'data-monthly'];
+
+// All markup files (layouts + includes) for a theme
+function markupFiles(theme) {
+  return [
+    ...glob(`${LAYOUTS}/${theme}/**/*.html`),
+    ...glob(`${INCLUDES}/${theme}/**/*.html`),
+  ];
+}
+
+// Inline <script> bodies are banned in theme markup (ld+json and src loaders OK)
+function findInlineScript(html) {
+  const scripts = html.matchAll(/<script\b([^>]*)>([\s\S]*?)<\/script>/g);
+
+  for (const [, attrs, body] of scripts) {
+    if (attrs.includes('src=')) {
+      continue;
+    }
+    if (attrs.includes('application/ld+json')) {
+      continue;
+    }
+    if (body.trim() === '') {
+      continue;
+    }
+
+    return body.trim().slice(0, 80);
+  }
+
+  return null;
+}
+
+// Flat page-asset names declared by ANY theme layout's asset_path frontmatter
+// (the fallback means classy's declarations apply to every theme)
+function declaredAssetPaths() {
+  const paths = new Set();
+
+  for (const file of glob(`${LAYOUTS}/*/**/*.html`)) {
+    const match = jetpack.read(file).match(/^asset_path:\s*(\S+)/m);
+    if (match) {
+      paths.add(match[1].replace(/['"]/g, ''));
+    }
+  }
+
+  return paths;
+}
+
+module.exports = {
+  layer: 'build',
+  description: 'theme contract (structure, swappability, cross-theme JS contracts)',
+  type: 'group',
+  tests: [
+    ...themes.map((theme) => ({
+      name: `${theme}: entry files + config contract`,
+      run: (ctx) => {
+        const config = jetpack.read(`${ASSETS}/${theme}/_config.scss`);
+        const entry = jetpack.read(`${ASSETS}/${theme}/_theme.scss`);
+
+        ctx.expect(config).toBeTruthy();
+        ctx.expect(entry).toBeTruthy();
+        ctx.expect(jetpack.exists(`${ASSETS}/${theme}/_theme.js`)).toBeTruthy();
+
+        // Shared nav/account includes depend on the avatar size map
+        ctx.expect(config).toContain('$avatar-sizes');
+
+        // Universal Bootstrap overrides must close the cascade
+        ctx.expect(entry).toContain("@import '../bootstrap/overrides'");
+      },
+    })),
+
+    ...themes.map((theme) => ({
+      name: `${theme}: layouts swappable, markup clean`,
+      run: (ctx) => {
+        for (const file of markupFiles(theme)) {
+          const html = jetpack.read(file);
+          const rel = path.relative(ROOT, file);
+
+          // Parent layout refs resolve via bracket templating, never a
+          // hardcoded theme id (swappability: change theme.id, done)
+          const parent = html.match(/^layout:\s*themes\/(.+)$/m);
+          if (parent) {
+            ctx.expect(`${rel}: ${parent[1]}`).toMatch(/\[\s*site\.theme\.id\s*\]/);
+          }
+
+          // No theme-prefixed classes in markup
+          for (const [, classes] of html.matchAll(/class="([^"]*)"/g)) {
+            for (const token of classes.split(/\s+/)) {
+              const prefixed = THEME_PREFIXES.some((p) => token.startsWith(p));
+              ctx.expect(prefixed ? `${rel}: class "${token}"` : '').toBeFalsy();
+            }
+          }
+
+          // No inline script bodies
+          const inline = findInlineScript(html);
+          ctx.expect(inline ? `${rel}: inline <script> "${inline}"` : null).toBeFalsy();
+        }
+      },
+    })),
+
+    ...themes.map((theme) => ({
+      name: `${theme}: cross-theme JS contracts`,
+      run: (ctx) => {
+        // A theme that ships its own pricing/post layouts must keep the
+        // markers the framework JS targets; absent layouts inherit classy's,
+        // so the contract holds by definition.
+        const pricing = jetpack.read(`${LAYOUTS}/${theme}/frontend/pages/pricing.html`);
+        if (pricing) {
+          for (const marker of PRICING_MARKERS) {
+            ctx.expect(pricing).toContain(marker);
+          }
+        }
+
+        const post = jetpack.read(`${LAYOUTS}/${theme}/frontend/pages/blog/post.html`);
+        if (post) {
+          // Load-bearing for ad injection
+          ctx.expect(post).toContain('blog-post-content');
+        }
+      },
+    })),
+
+    {
+      name: 'page asset files match a declared asset_path shape',
+      run: (ctx) => {
+        const declared = declaredAssetPaths();
+
+        // Sanity: the derivation itself found the known flat shapes
+        ctx.expect(declared.has('blog/post')).toBeTruthy();
+
+        for (const theme of themes) {
+          for (const file of glob(`${ASSETS}/${theme}/pages/**/*.{scss,js}`)) {
+            const rel = path.relative(`${ASSETS}/${theme}/pages`, file);
+            const base = rel.replace(/\.(scss|js)$/, '');
+
+            // index.* shapes resolve by page path; flat shapes must be
+            // declared by some layout's asset_path or the bundle never loads
+            if (path.basename(base) === 'index') {
+              continue;
+            }
+            ctx.expect(declared.has(base) ? '' : `${theme}/pages/${rel}: no layout declares asset_path "${base}"`).toBeFalsy();
+          }
+        }
+      },
+    },
+  ],
+};

package/dist/test/utils/extended-mode-warning.js

@@ -0,0 +1,13 @@
+// TEST_EXTENDED_MODE warning — SSOT for consistent messaging.
+//
+// Mirrors BEM/BXM/EM: `TEST_EXTENDED_MODE` is the shared, unprefixed env var that opts a
+// test run into hitting REAL external services instead of skipping/stubbing them. Off by
+// default so `npx mgr test` stays fast and offline-safe. Used by the test command (printed to
+// console + teed to logs/test.log).
+const EXTENDED_MODE_WARNING = [
+  '⚠️⚠️⚠️  WARNING: TEST_EXTENDED_MODE IS TRUE  ⚠️⚠️⚠️',
+  'Tests that hit real external services (network fetches, Firebase via web-manager, live APIs) are ENABLED!',
+  'This will make real network calls against live backends.',
+];
+
+module.exports = { EXTENDED_MODE_WARNING };

package/dist/utils/attach-log-file.js

@@ -12,75 +12,102 @@
 // Truncates fresh on each call (O_TRUNC), so a new `npm start` doesn't accumulate stale
 // lines from the previous run.
 //
-// Idempotent: calling twice with the same path just returns the existing fd.
+// Idempotent: calling twice with the same name on one tee just returns the existing fd.
 //
 // Uses synchronous fs.writeSync(fd, ...) rather than createWriteStream(). Reason: gulp tasks
 // crash via thrown errors that propagate to process.exit, and createWriteStream's internal
 // buffer was being dropped before the kernel could flush it — so the very lines describing
 // the crash (the most important ones) never made it to disk. Synchronous writes incur a
-// per-line syscall but guarantee the tail of the log survives an immediate exit.
+// per-line syscall but guarantee the tail of the log survives an immediate exit. (This is the
+// key behavioral difference from EM, whose tee is async/stream-based with an awaited detach.)
+//
+// The default export is a process-wide SINGLETON (the common case: a CLI command tees its
+// whole run to one file). `attachLogFile.createTee()` returns an INDEPENDENT tee with its own
+// state. Tees STACK: a later attach() captures the CURRENT `process.stdout.write` (which may
+// already be an outer tee) as its "original", so writes fan out through every layer and
+// detach() restores the exact prior writer in LIFO order. That stacking is what lets the
+// attach-log-file unit test exercise attach/detach on a throwaway instance WITHOUT killing
+// the live singleton tee that's capturing the actual test run — the bug that previously
+// truncated `logs/test.log` to ~9 lines (the test detached the live tee mid-run).
 
 const fs = require('fs');
 const path = require('path');
 
 const ANSI_PATTERN = /\x1B\[[0-9;]*[a-zA-Z]/g;
 
-let activeFd       = null;
-let activePath     = null;
-let originalStdoutWrite = null;
-let originalStderrWrite = null;
+function stripAnsi(s) {
+  return String(s).replace(ANSI_PATTERN, '');
+}
 
-function attachLogFile(name) {
-  // Skip on CI/cloud — controlled by UJ_IS_SERVER env var (set by workflows).
-  const Manager = require('../build.js');
-  if (Manager.isServer()) return null;
+// Factory — each call returns an independent tee with its own closure state.
+function createTee() {
+  let activeFd            = null;
+  let activePath          = null;
+  let originalStdoutWrite = null;
+  let originalStderrWrite = null;
 
-  if (!name) return null;
+  function attach(name) {
+    // Skip on CI/cloud — controlled by UJ_IS_SERVER env var (set by workflows).
+    const Manager = require('../build.js');
+    if (Manager.isServer()) return null;
 
-  const abs = path.resolve(process.cwd(), 'logs', `${name}.log`);
+    if (!name) return null;
 
-  if (activeFd !== null && activePath === abs) return activeFd;
-  if (activeFd !== null) detach();
+    const abs = path.resolve(process.cwd(), 'logs', `${name}.log`);
 
-  fs.mkdirSync(path.dirname(abs), { recursive: true });
-  const fd = fs.openSync(abs, 'w');
+    if (activeFd !== null && activePath === abs) return activeFd;
+    if (activeFd !== null) detach();
 
-  fs.writeSync(fd, `# ujm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    const fd = fs.openSync(abs, 'w');
 
-  originalStdoutWrite = process.stdout.write.bind(process.stdout);
-  originalStderrWrite = process.stderr.write.bind(process.stderr);
+    fs.writeSync(fd, `# ujm log — ${new Date().toISOString()} — pid=${process.pid}\n`);
 
-  process.stdout.write = function (chunk, ...rest) {
-    try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
-    return originalStdoutWrite(chunk, ...rest);
-  };
-  process.stderr.write = function (chunk, ...rest) {
-    try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
-    return originalStderrWrite(chunk, ...rest);
-  };
+    // Capture whatever the CURRENT writer is — could be the raw stream OR an outer tee.
+    // Restoring this exact reference on detach() is what makes stacked tees safe.
+    originalStdoutWrite = process.stdout.write.bind(process.stdout);
+    originalStderrWrite = process.stderr.write.bind(process.stderr);
 
-  activeFd   = fd;
-  activePath = abs;
+    process.stdout.write = function (chunk, ...rest) {
+      try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+      return originalStdoutWrite(chunk, ...rest);
+    };
+    process.stderr.write = function (chunk, ...rest) {
+      try { fs.writeSync(fd, stripAnsi(String(chunk))); } catch (e) { /* ignore */ }
+      return originalStderrWrite(chunk, ...rest);
+    };
 
-  return fd;
-}
+    activeFd   = fd;
+    activePath = abs;
 
-function detach() {
-  if (originalStdoutWrite) process.stdout.write = originalStdoutWrite;
-  if (originalStderrWrite) process.stderr.write = originalStderrWrite;
-  if (activeFd !== null) {
-    try { fs.closeSync(activeFd); } catch (e) { /* ignore */ }
+    return fd;
   }
-  activeFd   = null;
-  activePath = null;
-  originalStdoutWrite = null;
-  originalStderrWrite = null;
+
+  // Restores stdout/stderr and closes the fd. Synchronous — UJM writes synchronously, so the
+  // tail is already on disk by the time detach() runs; this just cleans up the handle.
+  function detach() {
+    if (originalStdoutWrite) process.stdout.write = originalStdoutWrite;
+    if (originalStderrWrite) process.stderr.write = originalStderrWrite;
+    if (activeFd !== null) {
+      try { fs.closeSync(activeFd); } catch (e) { /* ignore */ }
+    }
+    activeFd   = null;
+    activePath = null;
+    originalStdoutWrite = null;
+    originalStderrWrite = null;
+  }
+
+  return { attach, detach };
 }
 
-function stripAnsi(s) {
-  return String(s).replace(ANSI_PATTERN, '');
+// Process-wide singleton — the production entry point.
+const singleton = createTee();
+
+function attachLogFile(name) {
+  return singleton.attach(name);
 }
 
 module.exports = attachLogFile;
-module.exports.detach    = detach;
+module.exports.detach    = singleton.detach;
 module.exports.stripAnsi = stripAnsi;
+module.exports.createTee = createTee;

package/docs/appearance.md

@@ -63,3 +63,4 @@ webManager.uj().appearance.clear();      // Clear saved preference
 - **Module:** `src/assets/js/core/appearance.js` — API and UI handling
 - **Storage:** Saved under `_manager.appearance.preference` in localStorage
 - **Test page:** `/test/libraries/appearance`
+- **Footer picker:** every theme footer ships the appearance dropdown next to the language dropdown (classy's footer provides it to fallback themes automatically; themes with custom footers include it themselves — see [docs/themes.md](themes.md#the-appearance-picker-is-required-in-every-footer)). The footer toggle button is **icon-only** — `data-appearance-icon` spans, no `data-appearance-current` text label (the mode words live in the menu items)

package/docs/assets.md

@@ -151,6 +151,15 @@ This is the single source of truth for account dropdown menu items. Consuming pr
 
 This renders the full account dropdown: avatar button with profile photo, user info header (displayName + email), and the menu items from `account.json`.
 
+Each dropdown item supports:
+
+- `label` — Display text
+- `href` — Link URL (omit for button behavior, e.g. Sign Out)
+- `icon` — Font Awesome icon name
+- `class` — Additional CSS classes
+- `divider: true` — Renders a divider line
+- `attributes` — Array of `[name, value]` pairs (e.g. `data-wm-bind` for visibility)
+
 **Parameters:**
 
 | Parameter | Default | Description |

package/docs/audit.md

@@ -1,11 +1,82 @@
 # Audit Workflow
 
-When fixing issues identified by the audit task (`src/gulp/tasks/audit.js`):
+Full-project audit for UJM — runs against a CONSUMER site or the FRAMEWORK repo itself (scope auto-detected). Invoked via the `omega:ujm` skill (`/omega:ujm audit`) or any "audit this site/project" request.
 
-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
+Every check has a stable ID, a severity, and a scope. Findings are reported as `ID @ file:line`, fixed one at a time, then re-verified. The tables below do NOT restate the rules — each check links to the doc that owns the rule and the fix.
 
-**Remember:** Audit files are large. Systematic, incremental fixes prevent errors and ensure thoroughness.
+## Protocol
+
+1. **Detect scope** — read `package.json`: `name` is `ultimate-jekyll-manager` → **framework audit** (U + UJM + F checks); `ultimate-jekyll-manager` in (dev)dependencies → **consumer audit** (U + UJM checks).
+2. **Run the catalog** — every check matching the scope. Search with Grep/Glob/Read over `src/` (+ `test/`, config files); ALWAYS exclude `dist/`, `node_modules/`, `_site/`, `_legacy/`, `_backup/`, `.temp/`, `.cache/`. Record each finding as `ID @ file:line` + a one-line description.
+3. **Persist the report** — write the findings list to `.temp/audit/claude-audit.md` (the same scratch dir `npx mgr audit` uses) so a long fix loop survives session breaks. Summarize counts by severity in chat.
+4. **Fix loop** — TodoWrite per finding, highest severity first, ONE at a time: mark in-progress → root cause → fix → verify → complete. Ask before structural or destructive fixes (file deletions, layout swaps, data changes).
+5. **Re-verify** — re-run every check that produced findings until clean; finish with `npx mgr test` (must be green).
+6. **Doc parity** — if fixes changed behavior, update README / CLAUDE.md / `docs/<topic>.md` / CHANGELOG in the same change set.
+
+Severity: **CRIT** security or broken functionality · **HIGH** hard-rule violation · **MED** convention drift · **LOW** optional improvement.
+Scope: **C** consumer · **F** framework repo · **B** both.
+
+## Universal checks (U-xx)
+
+Mirrored across all four OMEGA frameworks (UJM / BEM / BXM / EM) — same ID means the same check everywhere.
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| U-01 | HIGH | B | Every feature has tests at EVERY layer it surfaces (build / page / boot) — never mocked ([test-framework.md](test-framework.md)) |
+| U-02 | HIGH | B | Test hygiene — real-external-API tests gated behind `TEST_EXTENDED_MODE` in-source (not mocked); no tests that assert nothing ([test-framework.md](test-framework.md)) |
+| U-03 | CRIT | B | XSS — inline `webManager.utilities().escapeHTML(value)` at EVERY DOM sink, `sanitizeURL(url)` at executable URL sinks, zero local escape helpers ([xss-prevention.md](xss-prevention.md)) |
+| U-04 | HIGH | B | web-manager owns Firebase — no direct `firebase` imports anywhere; `webManager.auth()` / `.firestore()` ([javascript-libraries.md](javascript-libraries.md)) |
+| U-05 | HIGH | C | No UJM transitive deps installed in the consumer `package.json` (`firebase`, `web-manager`, …) — webpack `resolve.modules` resolves them ([common-mistakes.md](common-mistakes.md)) |
+| U-06 | HIGH | B | Env behavior gated on the INTENTIONAL check — `isProduction()` or `isDevelopment() \|\| isTesting()`, never `!isDevelopment()`; no ad-hoc `process.env.UJ_*` reads where a helper exists ([environment-detection.md](environment-detection.md)) |
+| U-07 | HIGH | B | Config canon — `src/_config.yml` + `config/ultimate-jekyll-manager.json` match the documented shapes; canonical cross-framework blocks (`brand`, flat 8-key `firebaseConfig`, …) not reinvented ([CLAUDE.md](../CLAUDE.md) §Config flow) |
+| U-08 | CRIT | B | No private credentials committed — `.env`, tokens, secret keys; `.gitignore` covers them. (The Firebase WEB `apiKey` is public by design — do NOT flag it.) |
+| U-09 | HIGH | B | Source discipline — nothing edited in `dist/` / `_site/`; no live code referencing `_legacy/` / `_backup/` ([common-mistakes.md](common-mistakes.md)) |
+| U-10 | MED | B | Doc parity — README / CLAUDE.md / `docs/` / CHANGELOG match shipped behavior; CLAUDE.md < 250 lines; the docs index lists every `docs/*.md`; no stale names for renamed commands/patterns |
+| U-11 | MED | B | SSOT/DRY — no duplicated constants/config/logic; one authoritative home per value, imported everywhere else |
+| U-12 | MED | B | JS conventions — file structure, JSDoc, short-circuit returns, leading logical operators, `fs-jetpack`, one `module.exports` per file (global `js:patterns` skill + [CLAUDE.md](../CLAUDE.md) §File Conventions) |
+| U-13 | MED | B | Dead code & stale patterns — no orphaned `src/` files nothing imports; no leftovers of migrated-away formats ([migration.md](migration.md)); inventory TODO/FIXME (report only) |
+| U-14 | LOW | B | Dependency health — review `npm outdated` / `npm audit`; apply fixes via the `general:update-packages` workflow (includes supply-chain checks) |
+
+## UJM-specific checks
+
+| ID | Sev | Scope | Check |
+|----|-----|-------|-------|
+| UJM-01 | CRIT | B | ZERO inline `<script>` bodies in HTML under `src/` — JS belongs in page modules / `main.js`; migrate per the playbook ([no-inline-scripts.md](no-inline-scripts.md)) |
+| UJM-02 | HIGH | B | Bootstrap-first markup; NO theme-prefixed (`<themeid>-*`) classes in pages/includes — theme SCSS restyles universal classes ([themes.md](themes.md), [css.md](css.md)) |
+| UJM-03 | MED | C | Content writing rules — action-verb headings, sentence case, headline/accent structure; skip front matter, test pages, and blog posts ([seo.md](seo.md#content-writing-rules-applies-to-all-pages)) |
+| UJM-04 | MED | C | Spelling and grammar in body text — skip code blocks, attributes, URLs |
+| UJM-05 | HIGH | C | SEO meta — custom pages carry `meta.title` / `meta.description`; default pages customize via frontmatter per the per-page levels table ([layouts-and-pages.md](layouts-and-pages.md), [seo.md](seo.md)) |
+| UJM-06 | HIGH | B | PurgeCSS — every dynamically-added JS class is safelisted ([purgecss.md](purgecss.md)) |
+| UJM-07 | HIGH | C | Reads-vs-writes — Firestore SDK for dashboard READS only; all WRITES go through Cloud Functions ([javascript-libraries.md](javascript-libraries.md)) |
+| UJM-08 | HIGH | B | Page JS pattern — modules at `src/assets/js/pages/<path>/index.js` with element-existence guards; forms via FormManager; no Liquid in JS (use `data-*` / `<template>` bridges) ([assets.md](assets.md), [page-loading.md](page-loading.md), [no-inline-scripts.md](no-inline-scripts.md)) |
+| UJM-09 | MED | C | Images — imagemin source-size constraints respected, `data-lazy` lazy loading used, `@post/` shortcut in blog posts ([images.md](images.md), [lazy-loading.md](lazy-loading.md)) |
+| UJM-10 | MED | B | Accessibility basics — meaningful `alt` text, labeled form fields, real `<button>`/`<a>` elements (no clickable `div`s) |
+
+## Automated stage: `npx mgr audit`
+
+After (or alongside) the catalog, run UJM's built-in audit tool — HTML validation + spellcheck + optional Lighthouse:
+
+1. **Ask the user** whether to run it or whether they've already run it; run `npx mgr audit` if needed.
+2. **Read EVERY file in `.temp/audit/` COMPLETELY** — audit outputs are large; don't plan from a skim.
+3. **Fold the findings into the same TodoWrite fix loop** — one category at a time; do NOT attempt everything at once.
+4. **Re-run `npx mgr audit` after each batch** — confirm fixed issues resolved and no new ones appeared.
+
+Implementation: [`src/gulp/tasks/audit.js`](../src/gulp/tasks/audit.js); results land in `<projectRoot>/.temp/audit/`.
+
+## Framework-repo checks (F-xx)
+
+Only when auditing the UJM repo itself. Mirrored across the four frameworks.
+
+| ID | Sev | Check |
+|----|-----|-------|
+| F-01 | MED | Sister parity — mirrored sections (config shapes, test contract, CLAUDE.md skeleton, shared env/test conventions) in sync with BEM / BXM / EM; deviations are deliberate and documented |
+| F-02 | HIGH | Consumer-shipped defaults in sync — what `npx mgr setup` scaffolds matches current conventions and docs |
+| F-03 | MED | Docs completeness — every `docs/*.md` indexed in CLAUDE.md; every subsystem has a doc; no "(planned)" links for things that have shipped |
+| F-04 | HIGH | `npx mgr test mgr:` green before treating the audit as complete |
+
+## See also
+
+- [seo.md](seo.md) — the content conventions UJM-03 enforces
+- [xss-prevention.md](xss-prevention.md) — the escaping rules behind U-03
+- [no-inline-scripts.md](no-inline-scripts.md) — the UJM-01 migration playbook
+- [test-framework.md](test-framework.md) — the layers behind U-01 / U-02

package/docs/build-system.md

@@ -0,0 +1,57 @@
+# Build System
+
+UJM's build is a multi-stage gulp pipeline orchestrated by `src/gulp/main.js`, run from the consumer project (`npm start` for dev, `npm run build` for production).
+
+## Pipeline overview
+
+Build sequence:
+
+```
+defaults → distribute → parallel(webpack, sass, imagemin) → jsonToHtml → jekyll → audit → translation → minifyHtml
+```
+
+Dev sequence:
+
+```
+serve → build → developmentRebuild
+```
+
+## Gulp tasks
+
+15 tasks live in `src/gulp/tasks/`: `defaults` / `distribute` / `webpack` / `sass` / `imagemin` / `jekyll` / `jsonToHtml` / `preprocess` / `audit` / `translation` / `minifyHtml` / `serve` / `setup` / `developmentRebuild`.
+
+Pure helpers are exposed under [src/gulp/tasks/utils/](../src/gulp/tasks/utils/) (`merge-jekyll-configs`, `_validate-yaml`, `template-transform`, `collectTextNodes`, `dictionary`, `github-cache`, `formatDocument`) — these are the highest-value test targets (zero I/O, callable directly in `build`-layer tests).
+
+## Config flow
+
+Three config files in the consumer project feed the build:
+
+1. **`src/_config.yml`** — Jekyll config (brand, theme, meta, web_manager). Read by `Manager.getConfig('project')`.
+2. **`config/ultimate-jekyll-manager.json`** — UJM-specific config (purgecss safelist, webpack target, imagemin opts, distribute glob patterns). JSON5.
+3. **`package.json`** — read by `Manager.getPackage('project')`.
+
+UJM ships defaults via `_config_default.yml` + `_config_development.yml` at `src/config/` — merged at Jekyll build time via the `--config` chain by [merge-jekyll-configs.js](../src/gulp/tasks/utils/merge-jekyll-configs.js).
+
+## Build modes
+
+| Mode | Trigger | Effect |
+|---|---|---|
+| Development | `npm start` (default) | Serve + watch + incremental rebuild via `developmentRebuild` |
+| Production | `npm run build` (`UJ_BUILD_MODE=true`) | Full pipeline incl. minifyHtml; PurgeCSS runs automatically |
+
+PurgeCSS can be enabled locally with `UJ_PURGECSS=true`; consumer safelist patterns live in `config/ultimate-jekyll-manager.json` under `sass.purgecss.safelist`. See [local-development.md](local-development.md).
+
+## Serve / live reload
+
+The dev server URL is stored in `.temp/_config_browsersync.yml` in the consuming project root — read it to determine the correct URL for browsing/testing. See [local-development.md](local-development.md) for emulator connection (`FIREBASE_EMULATOR_CONNECT=true`).
+
+## Log files
+
+The gulp pipeline tees all output to `logs/dev.log` (`npm start`) / `logs/build.log` (`npm run build`). Full reference: [logging.md](logging.md).
+
+## See also
+
+- [templating.md](templating.md) — node-powertools bracket conventions in the pipeline
+- [css.md](css.md) — SCSS structure + PurgeCSS
+- [local-development.md](local-development.md) — dev server, emulators, PurgeCSS toggles
+- [test-framework.md](test-framework.md) — testing the pipeline's pure helpers

package/docs/common-mistakes.md

@@ -0,0 +1,15 @@
+# Common Mistakes to Avoid
+
+1. **🚫 Inline `<script>` tags in HTML files** — the #1 worst mistake. Move ALL JS to page modules (`src/assets/js/pages/<path>/index.js`) or `main.js`. Component/layout scripts go in `main.js` with element-existence guards. Liquid-templated scripts bridge via `data-*` attributes or `<template>` elements. **Only exceptions:** `type="application/ld+json"`, external `<script src="...">` loaders, and ≤10-line first-paint display helpers with an explaining comment.
+2. **🚫 Reinventing Bootstrap — the #1 CSS mistake** — NEVER create custom classes for things Bootstrap already provides. No `.lm-btn` when `.btn .btn-primary` exists; no `.lm-wrap` when `.container` exists; no custom flex/gap/padding/margin/text-align classes when Bootstrap utilities do the same thing. Theme SCSS overrides how `.btn`/`.card`/`.navbar` LOOK — it doesn't create parallel replacements. Custom CSS is ONLY for genuinely novel components with no Bootstrap equivalent. Before writing ANY custom class, ask: "Does Bootstrap have this?" If yes, USE IT. See [themes.md](themes.md) and [css.md](css.md).
+3. **Creating duplicate CSS** — check Bootstrap and the active theme first.
+4. **Wrong imports** — FormManager needs curly braces: `import { FormManager } from ...`.
+5. **Assuming `Manager`, `firebase`, `webManager` are on `window`** — they are NOT. Use `import webManager from 'web-manager'` in a module. `firebase.firestore()` → `webManager.firestore()`. **Consumer code NEVER imports Firebase directly** — Firebase is web-manager's internal dependency. Same rule in EM and BXM.
+6. **Installing UJM's dependencies as direct consumer deps** — Consumer projects must NOT `npm install firebase`, `web-manager`, or any other UJM/web-manager transitive dep. UJM's webpack config includes `resolve.modules` pointing at the framework's own `node_modules/`. If a dependency isn't resolving, the fix is in UJM's webpack config — not the consumer's `package.json`. Mirrors EM and BXM.
+7. **Not using FormManager** — use it for ALL forms.
+8. **Calling `$form.requestSubmit()` directly** — use `formManager.submit()`.
+9. **Wrong dark mode classes** — use `bg-body` variants, not `bg-light`/`bg-dark`.
+10. **Not waiting for DOM** — always `await webManager.dom().ready()`.
+11. **Using native fetch** — always use `wonderful-fetch` or `authorized-fetch`.
+12. **XSS — unescaped dynamic data in innerHTML** — Use `webManager.utilities().escapeHTML()`. Dynamic URLs in `href`/`src`/`action`/`window.location`/`window.open` ALSO need `webManager.utilities().sanitizeURL()` — `escapeHTML` alone lets `javascript:` execute. See [xss-prevention.md](xss-prevention.md).
+13. **Leaving Liquid `{{ }}` or `{% %}` inside moved JS modules** — Jekyll does NOT process `src/assets/js/**/*.js`. Use `data-*` attribute bridges or `<template>` cloning.

package/docs/{project-structure.md → directory-structure.md}

@@ -1,4 +1,4 @@
-# Project Structure
+# Directory Structure
 
 UJM 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.
 

package/docs/environment-detection.md

@@ -82,4 +82,4 @@ Write the function in [src/utils/mode-helpers.js](../src/utils/mode-helpers.js)
 
 ## See also
 
-- [test-framework.md](test-framework.md) — `UJ_TEST_MODE` is set automatically by the test runners; `--integration` gates real external APIs.
+- [test-framework.md](test-framework.md) — `UJ_TEST_MODE` is set automatically by the test runners; `--extended` / `TEST_EXTENDED_MODE=true` gates real external APIs.

package/docs/javascript-libraries.md

@@ -46,6 +46,43 @@ Raw subscription data (product.id, status, trial, cancellation) is on `account.s
 
 The same function exists in BEM as `User.resolveSubscription(account)` with identical return shape.
 
+### Reads vs Writes: When to Use What
+
+| Operation | Method | Why |
+|-----------|--------|-----|
+| **Read** (list, fetch single) | `webManager.firestore()` | Faster, cheaper, no Cloud Function cold starts, no HTTP overhead |
+| **Write** (create, update, delete) | `authorizedFetch` (Cloud Function) | Server-side validation, usage tracking, analytics |
+| **Config/limits lookup** | `webManager.config.payment.products` | Already available client-side from `_config.yml`, no fetch needed |
+
+**Dashboard and frontend reads MUST use the Firestore SDK directly** — never call a Cloud Function GET endpoint from the dashboard. Firestore reads are faster, cheaper, and don't incur cold starts. The backend GET routes (`routes/{resource}/get.js`) exist for **external API consumers only**, not for our own frontend. (Requires Firestore security rules that allow the read, e.g. `allow read: if isAuthenticated() && resource.data.owner == authUid()`.)
+
+```javascript
+// Collection query (list user's items) — wait for auth first
+webManager.auth().listen({ once: true }, async ({ user }) => {
+  if (!user) return;
+
+  const result = await webManager.firestore()
+    .collection('codes')
+    .where('owner', '==', user.uid)
+    .orderBy('meta.created.timestampUNIX', 'desc')
+    .get();
+
+  if (result.empty) return; // show empty state
+
+  result.docs.forEach((doc) => {
+    const data = doc.data();
+    // Render item...
+  });
+});
+
+// Single document read
+const doc = await webManager.firestore().doc(`codes/${id}`).get();
+if (!doc.exists()) return; // not found
+const data = doc.data();
+```
+
+Full Firestore query API (chainable `.where()`/`.orderBy()`/`.limit()`/`.startAt()`, response shapes): see `web-manager`'s [docs/modules.md](../../web-manager/docs/modules.md) — in consumer projects, `node_modules/web-manager/docs/modules.md`.
+
 ## Ultimate Jekyll Libraries
 
 Ultimate Jekyll provides helper libraries in `src/assets/js/libs/` that can be imported as needed.
@@ -314,7 +351,7 @@ initializing → ready ⇄ submitting → ready (or submitted)
   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
+  submittingText: 'Processing...', // Text shown on submit button during submission (use '' for icon-only buttons)
   submittedText: 'Processed!', // Text shown on submit button after success (when allowResubmit: false)
   inputGroup: null           // Filter getData() by data-input-group attribute (null = all fields)
 }