@omega.js/web 0.1.0

package/docs/shared/translation.md

@@ -0,0 +1,291 @@
+# Translation
+
+AI translation for OMEGA consumers — one engine, config-driven, with a
+**committed** per-string cache. Shipped cp96 (Ian directive 2026-07-11),
+replacing both legacy systems: UJM's OpenAI-only gulp task with the
+`cache-uj-translation` GitHub-branch cache, and BXM's Claude-only task with a
+gitignored `.cache/` (which re-translated everything on any change and on
+every fresh clone).
+
+## Config (shared `translation` section of omega.json5)
+
+```json5
+translation: {
+  enabled: true,          // optional master switch (default true)
+  default: 'en',          // source language (default 'en')
+  languages: ['es', 'fr'],// target codes — EMPTY/ABSENT = translation off
+  providers: { claude: {} },// the engine is a KEY (#425): claude | chatgpt. Absent block = claude
+  model: null,            // optional override for the chosen engine (claude → 'sonnet' alias, chatgpt → 'gpt-5.4-nano')
+  exclude: [],            // web only: BRAND page routes/folders to skip (the framework's own default pages are already excluded — #605)
+}
+```
+
+Shared section (typically brand-level; `SHARED_SECTIONS` includes it, so
+every target inherits it through the merge chain). Language codes
+validate against the SSOT in `@omega.js/devkit/translate` (`LANGUAGE_NAMES`,
+~32 codes) — an unknown code is a hard config error naming the supported set.
+The same SSOT carries `LANGUAGE_LOCALES` + `ogLocale(code)`, the one code →
+Open Graph `language_TERRITORY` map (`es` → `es_ES`).
+
+## Providers
+
+| Provider | Rides | Credentials |
+|----------|-------|-------------|
+| `claude` (default) | the locally-installed Claude Code via `@anthropic-ai/claude-agent-sdk` | **none** — local auth |
+| `chatgpt` | OpenAI Responses API (native fetch) | `OPENAI_API_KEY` via the .env cascade |
+
+The claude provider runs **hermetic** sessions: `settingSources: []` (no user
+CLAUDE.md/hooks — they pollute mechanical output; a stop-hook reply actually
+leaked into a canary before this was locked down), a custom translator system
+prompt instead of the CLI persona, and NO `maxTurns` cap (a plain reply
+already counts as the final turn — `maxTurns: 1` reports `error_max_turns`
+even though the text arrived).
+
+**Enabling translation on web means installing the SDK (#37).** `@omega.js/web`
+does NOT ship `@anthropic-ai/claude-agent-sdk`: translation is opt-in and the
+SDK is heavy, so a web brand that turns it on installs it in the target itself
+(`npm install @anthropic-ai/claude-agent-sdk`); `@omega.js/extension` still
+declares it. The SDK is lazy-required at the first claude call, so a brand
+without translation never pays for it, and a brand that enabled translation
+without the SDK gets a hard error naming the package and that install command,
+never a silent skip. The `chatgpt` provider needs no SDK at all (native fetch
+plus `OPENAI_API_KEY`).
+
+**The manage cycle provisions it (#168).** Nobody types that install in a
+managed brand: the manager's workspace service reconciles it like every other
+brand file. A web app whose RESOLVED config translates with the `claude`
+provider gets `@anthropic-ai/claude-agent-sdk` written into its package.json
+`dependencies` (at the range `@omega.js/web` declares as its optional peer,
+read from the installed web package), followed by one `npm install` at the
+brand root. Converge-to-config, so: already declared (in `dependencies` or
+`devDependencies`) = zero-mutation no-op that never overwrites a
+consumer-chosen spec, `--dry-run` plans without writing, translation off or
+provider `chatgpt` leaves the target untouched, and turning translation back OFF
+never REMOVES the dep (uninstalling on a config flip is riskier than leaving
+it). Only web targets are provisioned, since backend and extension declare the
+SDK as a real dependency of the framework. The loud error above stays the backstop
+for hand-managed brands (`packages/manager/src/services/workspace/ensure/translation-sdk.js`,
+pinned by `packages/manager/test/workspace-translation-sdk.test.js`).
+
+## Engine protocol (`@omega.js/devkit/translate`)
+
+`translateStrings({ strings, language, languageName, brand, extraRules, send })`
+→ positionally-aligned translations:
+
+- **JSON array in → same-length JSON array out**, batches of 25.
+- **Batches fly concurrently**, `CONCURRENCY` wide (the constant at the top of
+  `packages/devkit/src/translate/engine.js`, currently 5 —
+  [#604](https://github.com/Omega-JS-Stack/omega/issues/604)). A batch is one
+  model call and the model's latency dominates it, so a serial pass paid that
+  latency once per 25 strings and one language took minutes it never needed.
+  Results are stitched back in BATCH order, never completion order, and
+  everything below still happens per batch, unchanged. Raise it only as far as
+  the providers' rate limits allow.
+- **Duplicates are deduped before batching** ([#529](https://github.com/Omega-JS-Stack/omega/issues/529)):
+  a page sends its title and description once per meta tag (`<title>`,
+  `og:title`, `twitter:title`), so the same string used to ride a batch three
+  times over — three times the AI spend, and adjacent twins are what a model
+  merges. Each unique string is translated ONCE and the translation is fanned
+  back to every occurrence. Occurrences key on the exact source string,
+  whitespace included, so a batch is 25 UNIQUE strings.
+- The `OMEGA-TRANSLATION-CONTROL` sentinel is appended to EVERY batch and must
+  return unchanged at its exact position — alignment proof per batch.
+- Validation failures (parse, length, sentinel) retry up to 2× then throw.
+- An ALIGNMENT failure (length or sentinel) that survives the retries splits the
+  batch in half and re-asks each half, down to one string
+  ([#523](https://github.com/Omega-JS-Stack/omega/issues/523)): a model that
+  merges a pair of strings does it every time, so retrying the same array can
+  only fail the same way — the playground's ship-the-docs page came back
+  25-for-26 on all six attempts, in both languages, and shipped untranslated.
+  A single string that still will not come back whole throws, and the caller
+  skips that page-language pair whole (never half-translated).
+- Original leading/trailing whitespace is re-applied to every translation.
+- Rules baked into the system prompt: preserve HTML/URLs/placeholders
+  (`$1`, `{name}`, `{{ value }}`), never translate the brand name.
+
+## The committed cache (`<app>/translations/`)
+
+`translations/{lang}/{namespace}.json` maps `sha256(source)[:12]` → translated
+string. Committed to git — that's the whole point:
+
+- **Incremental**: editing one source string changes one hash → exactly one
+  re-translation. Everything else is a cache hit (zero provider calls).
+- **Survives clones/CI**: a warm cache builds a fully-translated site with NO
+  AI credentials (kills the BXM parked finding where fresh clones burned live
+  Claude calls).
+- **Human-overridable**: hand-edit a translation VALUE in the cache file and
+  it sticks for as long as the source is unchanged (the value is the
+  translation; the key only changes when the SOURCE changes).
+- Maps are pruned to the current source set on save — no stale entries.
+
+`@omega.js/web` ships a second cache in exactly this shape for its OWN default
+pages, inside the package ([below](#framework-shipped-default-page-translations-621)).
+
+## Web (`@omega.js/web`)
+
+`omega build` translates everything by default (Ian's #24 final call): warm
+strings come from the committed cache instantly, cold strings translate live
+through the provider — a build ships the COMPLETE translated site whenever
+the provider delivers, and a warm cache means zero provider calls. A provider
+FAILURE skips that page-language pair whole, warning loudly with the page and
+the language (the build still exits 0): no half-translated copy ever ships
+behind full language chrome.
+`omega build --cached-only` skips cold page-language pairs WHOLE instead (no
+mixed-language copies, hreflang stays honest; the warning lists them) for
+provider-free builds.
+`omega translate` still runs the live pass standalone against an existing
+dist/ and exits 1 on failures. `OMEGA_TRANSLATE_ONLY=<route>` limits any of
+these to one page (canary/debug).
+
+Per page × language: text nodes/`<title>`/meta/attribute copy translate
+(cache-first), then the copy lands at `dist/{lang}/...` with `<html lang dir>`
+(RTL-aware), canonical + `og:url` + `og:locale` localized, internal links
+rewritten to `/{lang}/...`, and hreflang + `og:locale:alternate` tags
+stitched into BOTH the copy and the original — naming only the languages
+actually PRODUCED for that page (a pair skipped cold or failed is never
+advertised, on the copies as on the originals), so hreflang never lies.
+`og:locale` carries Open Graph's `language_TERRITORY` form (`en_US`,
+`es_ES`) from the devkit language SSOT's locale map — on translated copies
+and on the source pages the head include renders. Cache namespace:
+`pages/{route}` (`pages/home` for `/`).
+
+On a site served under a base path ([#355](https://github.com/Omega-JS-Stack/omega/issues/355)),
+link rewriting composes **prefix, then language**: the pass reads the mount
+point off the `<html data-omega-path-prefix>` stamp the build wrote (so
+`omega translate` standalone sees it too), takes the route from underneath it,
+and mounts the language segment after it — `/workkit/es/pricing`, never
+`/es/workkit/pricing` ([#359](https://github.com/Omega-JS-Stack/omega/issues/359)).
+Exclusions are matched on that same underneath-the-prefix route. ABSOLUTE URLs
+(canonical, `og:url`, hreflang alternates, the sitemap entries) are built from
+`brand.url`, which for a mounted site already carries the path — nothing
+prefixes them twice.
+
+Never sent to the PROVIDER, and the framework owns the list
+([#605](https://github.com/Omega-JS-Stack/omega/issues/605)): every one of its
+OWN default pages whose layout says it is plumbing rather than marketing copy —
+the auth flows, the `/app` shell, the account/payment/portal screens, the legal
+boilerplate, `404`, and the redirect stubs (`/login`, `/account`, `/cancel`, …).
+Those pages still get their `/{lang}/` copies — from the translations PACKAGED
+with `@omega.js/web`, at no cost to the brand (next section).
+The list is DERIVED from the packaged defaults tree
+(`packages/web/defaults/pages/**`, read by `src/translate/default-routes.js`),
+never typed out, so a default page that moves or arrives cannot drift out of it,
+and each excluded route guards its subtree too. On top of that: socials
+redirects (config `socials` keys), the `admin`/`test`/`team`/`updates` folders,
+every known language-code folder, plus config `translation.exclude` — which is
+for the BRAND's own pages, and only those. A brand that lists `signin` or
+`account` is listing something the framework already skips.
+Element opt-out: `data-omega-no-translate`. Collector fixes vs UJM:
+`aria-describedby`/`aria-labelledby` are NOT collected (ID refs), `value`
+only on button-type inputs (hidden-input tokens stay intact).
+
+### Framework-shipped default-page translations ([#621](https://github.com/Omega-JS-Stack/omega/issues/621))
+
+The default pages above render the SAME chrome on every brand, so the framework
+translates them ONCE and ships the result: `packages/web/translations/{lang}/pages/{route}.json`,
+the identical `{lang}/{namespace}.json` shape as a consumer's own cache (same
+loader, same `sha256(source)[:12]` keys, same prune-on-save, hand-fixable the
+same way), committed to the package and published under `files`.
+
+The keys are brand-NEUTRAL. The generator renders with a fixture brand and
+replaces every occurrence of it with the sentinel `__OMEGA_BRAND__` before
+hashing; the read-through replaces the CONSUMER's `brand.name` with the same
+token before the lookup and puts it back on the way out, so "Sign in to MiniCo"
+and "Sign in to Acme" are one packaged entry (`src/translate/packaged-defaults.js`).
+
+Consumer side, on every pass — `omega build`, `--cached-only`, `omega translate`
+alike, since it never touches a provider:
+
+- Each default route gets its `dist/{lang}/…` copy with the same localized
+  chrome, hreflang and sitemap entry as any other page. Link rewriting is the
+  same pass too, which means links OUT to brand pages gain the language segment
+  while links between two default routes (signin → signup) do not — those routes
+  are excluded from rewriting, and that is unchanged from #605.
+- A string the package does not carry (copy the brand overrode, a page the
+  framework has not regenerated for) stays in the source language and is
+  COUNTED — one log line per route names the miss count. Never guessed at.
+- A brand whose NAME is a word the chrome itself uses ("Sign") still gets every
+  string that does not interpolate the brand — the lookup falls back to the raw
+  key when the sentinel-normalized one misses. The strings that DO interpolate
+  it (`Sign in to Sign`) miss, and stay in the source language.
+- A route the package carries nothing for gets NO copy, so hreflang keeps
+  telling the truth. That is how the legal boilerplate stays one language:
+  `terms`/`privacy`/`cookies` are deliberately not generated.
+- A configured language the package does not ship is one log line for the whole
+  run, not an error — those routes stay in the source language.
+- A route the brand named in `translation.exclude` is left alone entirely.
+
+**Shipped set: `es`, `fa`.** Regenerating, or extending the set, is one command
+in `packages/web` (the ONLY place the framework's own pages ever reach a
+provider):
+
+```bash
+npm run translate:defaults                      # the shipped set
+npm run translate:defaults -- --languages es,fa,de   # …plus a new one
+```
+
+It renders the defaults tree through the real production build against a
+throwaway consumer (no brand repo involved), harvests with the same collector
+the pass uses, translates ONLY the strings the packaged cache is missing —
+across all routes at once, so the header/footer chrome every default page
+repeats is paid for exactly once — and writes the files back. Idempotent: a
+re-run costs nothing, adding a language costs only that language. A provider
+failure, or a translation that dropped the sentinel, STOPS the run and writes
+nothing.
+
+`dist/sitemap.xml` (emitted by the build in the source language only) is
+rewritten afterwards so it tells the same story: every PRODUCED copy joins it
+as its own `<url>`, and each entry of a translated set — source and copies
+alike — carries the full `xhtml:link rel="alternate"` list (`x-default` at the
+source language) plus the source entry's `lastmod`/`changefreq`/`priority`.
+Entries stay in loc byte order. The language-prefixed entries are owned by that
+pass: each run drops them all and re-emits only what it produced, so a skipped
+or failed pair is listed nowhere.
+
+The visitor-facing **language switcher** is the footer dropup in the shared
+base footer include (`_includes/frontend/sections/footer.html`, the base layer
+every theme inherits). It renders CLIENT-SIDE from the page's own
+`link[rel="alternate"][hreflang]` tags — the produced-only SSOT above — so the
+menu can never offer a copy that was not written: `core/js/core/language-switcher.js`
+drops `x-default`, labels each row with its native name (`Intl.DisplayNames` in
+that language's own locale, upper-cased code as the fallback), marks
+`documentElement.lang` as current, and leaves the mount empty and hidden when
+fewer than two languages exist. Selecting a language is a plain link to that
+alternate's href — never a redirect or a negotiation.
+
+Not here yet: no default homepage exists in the D8 set, so brand sites
+translate their own `index` when they add one.
+
+## Extension (`@omega.js/extension`)
+
+Build-mode gulp `translate` task (setup/dev builds only deploy):
+
+- **messages**: per-KEY incremental — unique `message` values without a cache
+  entry translate (CWS limits ride the prompt as extra rules; violations warn
+  with the file path to shorten). `dist/_locales/{lang}/messages.json` is
+  COMPOSED from the EN source + cache (English fallback per missing key, so
+  the file is always complete; developer `description` fields stay English).
+- **description**: whole-document per language →
+  `translations/{lang}/description.md`, first line
+  `<!-- omega:source <hash> -->` (stripped on read; source edit →
+  re-translate). The package task ships them as store assets
+  (`packaged/assets/description/{lang}.md`).
+
+Languages/provider come from resolved config — the old hardcoded 16-language
+list in `gulp/config/locales.js` is gone (only the CWS `limits` remain there).
+
+## Testing
+
+- devkit `test/translate.test.js` — engine protocol, providers, cache,
+  language SSOT, settings reader (fake `send`).
+- web `test/translate.test.js` — handcrafted dist through the real pipeline:
+  copies/chrome/links/exclusions/alternates/cache/override/only-filter, the
+  produced-languages-only alternates, and the loud failure skip.
+- web `test/language-switcher.test.js` — the switcher's DOM read (x-default
+  dropped, duplicates collapsed, current marked, escaping) and the built footer
+  mount in classy and newsflash.
+- extension `build/translate.test.js` — compose + description marker glue.
+- Live canary (cp96, local Claude): omega-brand `/about` → es (102 strings,
+  rerun 0 calls) and the extension's 4 messages (2 unique) + 2,703-char
+  description → es, both idempotent; artifacts committed under each target's
+  `translations/`.

package/docs/shared/updates.md

@@ -0,0 +1,61 @@
+# Dependency updates (`omega update`)
+
+One shared implementation (`@omega.js/devkit/update`) behind every framework's `omega update` verb (aliases: `outdated`, `out` — npu's muscle memory), thin wiring in web/desktop/extension (router commands), backend (colon-style command class), and the manager (brand-root fan-out). Semantics mirror Ian's `npu out` (node-power-user): report first, apply deliberately, and never trust a brand-new release.
+
+## The report (default — no flags)
+
+For each dependency of the target's `package.json` (prod + dev, grouped):
+
+| Column | Meaning |
+|---|---|
+| Current | the base version in `package.json` (`^1.2.3` → `1.2.3`) |
+| Installed | the physical `node_modules` copy (nearest, climbing — npm hoists in brand monorepos) |
+| Wanted | highest published version satisfying the range (npm-outdated semantics) |
+| Latest | the registry `dist-tags.latest` |
+| Bump | `patch` / `minor` / `major` — Current → Latest classification |
+| Released | Latest's publish date + age in days |
+| Status | `QUARANTINED` when Latest is younger than `--min-age` days (default **7**) and not already installed |
+
+Only rows needing attention print; a fully-current tree reports one line. Rows sort prod-first.
+
+**Quarantine (supply-chain caution, npu's `--min-age` semantics):** a release published < 7 days ago may be a compromised publish — it is flagged and **excluded from `--apply`**. `--min-age N` changes the window; `--min-age 0` or `--force-fresh` disables it. Unpublished packages (the pre-publish `@omega.js/*` set) report `not on the registry (unpublished?)` instead of a version row.
+
+**`file:`/`link:`/git specs are SKIPPED** with a dim note — they have no registry story. In the local era every brand's `@omega.js/*` dep is a `file:` spec, so the verb never touches the linked frameworks.
+
+## Applying (`--apply`)
+
+- Default tier is **non-breaking**: each dep rides to its highest same-major version (npu's minor tier) — quarantined targets are held and listed.
+- **Majors are never auto-applied**: breaking jumps are listed as held; `--apply --major` opts in explicitly.
+- Installs run through **`npu install`** when npu is on the machine (Socket supply-chain firewall); otherwise plain `npm install` with a loud warning. Dev deps install with `--save-dev` in their own pass.
+
+## The @omega.js family is pinned, and `omega update` is its ONE mover ([#794](https://github.com/Omega-JS-Stack/omega/issues/794))
+
+Every `@omega.js/*` spec the manager writes into a brand is an EXACT pin, never a
+caret: `"@omega.js/manager": "0.1.0"` at the brand root, `"@omega.js/<framework>":
+"0.1.0"` in each target, all at the manager's own version (the family ships
+lockstep — [publishing.md](publishing.md)). A caret would let one target float
+ahead alone on somebody's `npm update`, which is how a brand ends up serving two
+copies of `@omega.js/client` and validating one omega.json5 with two validators.
+
+Pinned, the only thing that moves a brand is `omega update --apply` at the brand
+ROOT (a bare run reports and installs nothing), and it moves every target — and
+the root's own manager pin — together. `--apply` installs an `@omega.js/*` dep with
+`--save-exact`, in its own command per dep group, so the mover never un-pins
+what it just moved (npm's default save-prefix would write `^<version>` back);
+every other dependency keeps npm's default prefix, because the pin is the
+FAMILY's rule and not a rule for the whole tree.
+
+The manager's boot check enforces the other half: a brand whose installed
+versions have drifted is refused before any service or dev leg runs
+([../manager/brand.md](../manager/brand.md)). The local era is untouched — a
+`file:` spec has no registry story, so the verb skips it and the boot check
+exempts it. `omega i live` (the publish-day flip back off `file:` specs) writes
+the same exact pin ([local-dev.md](local-dev.md) § API surface).
+
+## Brand root
+
+`omega update` at a brand root (manager) fans out over the brand's targets — cp251's deploy fan-out shape: same target discovery, same `--target=<target|dir>` picker ([#780](https://github.com/Omega-JS-Stack/omega/issues/780)), every other flag forwarded verbatim, each target answering through its own framework's `update` verb. Unlike deploy, targets are **independent**: one failing target never blocks the rest (any failure still exits 1). The brand-root shell `package.json` rides the walk as its LAST leg ([#794](https://github.com/Omega-JS-Stack/omega/issues/794)), scoped to the one `@omega.js/*` dependency it carries — `@omega.js/manager` — and run in-process through the same devkit implementation (there is no framework bin at the root to spawn; it would dispatch straight back into this command). A brand's own root tooling is never touched, and a picked run (`--target=`) skips the root, because the picker names targets. Without that leg a manager-behind brand could never heal itself: the boot check would refuse every verb, and the fix it names would move every target except the one that was wrong.
+
+## Testing
+
+Registry lookups, the clock, npu detection, and exec are all injectable — the devkit suite (`packages/devkit/test/update.test.js`) runs entirely offline against fixture packuments with a frozen clock; the manager fan-out test spawns fake framework bins; framework structure tests pin the wiring. The live path is the thin defaults (native `fetch` of the full packument — the abbreviated form carries no publish times).

package/docs/template-kit.md

@@ -0,0 +1,128 @@
+# @omega.js/template-kit — the omega_* template surface as plain JS
+
+The complete filter/tag surface of jekyll-uj-powertools (READ-ONLY reference
+repo), ported to engine-neutral JavaScript for the SSG bake-off and
+`@omega.js/web`. Private workspace package (`packages/template-kit`), vendored
+into frameworks at prepare time like the other shared packages.
+
+**Names are `omega_*` (#44).** The Jekyll-era `uj_` spelling is retired with no
+aliases: `{% uj_icon %}` is an undefined tag, `| uj_liquify` an undefined
+filter, and `site.uj.*` is `site.omega.*`. A legacy consumer gets the rename
+mechanically from `omega migrate`'s `legacy-prefix` rule; a shipped surface
+that reintroduces one fails web's `test/legacy-prefixes.test.js` guard.
+
+Two consumption paths (plan §4 A0):
+- **Eleventy / any LiquidJS host**: `registerLiquid(engine, options)` — registers everything under the `omega_*` names (the Ruby's behavior, one spelling newer).
+- **Astro / direct**: import the plain functions (`filters`, `TAGS`, `jekyllCompat`) and call them.
+
+## Filters (from `lib/filters/main.rb`)
+
+| Name (registered) | Kind | Notes |
+|---|---|---|
+| `omega_strip_ads` | pure | strips `<ad-unit>` blocks + adunit includes |
+| `omega_json_escape` | pure | JSON-escape, no surrounding quotes |
+| `omega_random` | pure | `Math.floor(random * n)` |
+| `omega_hash` | pure | **byte-parity with Ruby verified**: full 128-bit MD5 as BigInt, mod max (`'hello'→994@1000`, `'somiibo'→305@360`, checked against ruby 4.0.0) |
+| `omega_title_case` | pure | Ruby per-word `capitalize` parity ("hello WORLD" → "Hello World") |
+| `omega_jsonify` | pure | pretty JSON, configurable indent |
+| `omega_append_param` | pure | `?`/`&`-aware query param append |
+| `omega_cachebreak` | pure | appends `cb=<process-consistent ms timestamp>` |
+| `omega_pluralize` | pure | singular only for exactly 1; default plural = singular+`s` |
+| `omega_commaify` | pure | **deliberate divergence**: Ruby also groups decimal digits (`1234.5678`→`1,234.5,678`, a latent bug); ours commas the whole part only (`1,234.5678`) |
+| `omega_increment_return` | context | per-render-context counter (WeakMap in the adapter) |
+| `omega_liquify` | context | recursive Liquid render, max depth 10, no-change guard |
+| `omega_content_format` | context | liquify + markdownify when `page.extension === '.md'` (markdown converter injected) |
+
+## Tags (from `lib/tags/*.rb`) — registered names are EXACT, incl. the four unprefixed ones
+
+| Name | Kind | Engine needs |
+|---|---|---|
+| `iftruthy` / `iffalsy` | block | — (nil/false/`''`/0 falsy, Ruby table) |
+| `iffile` | block | `options.fileExists(path)` |
+| `urlmatches` | inline | `page.url` (index.html-normalized comparison) |
+| `omega_readtime` | inline | page content default; 269 wpm, min 1 |
+| `omega_fake_comments` | inline | words % 13 |
+| `omega_external` | inline | `site.url` |
+| `omega_social` | inline | `page.resolved.socials.*` + SOCIAL_URLS data |
+| `omega_language` | inline | LANGUAGES data (184 codes, machine-extracted from the Ruby) |
+| `omega_translation_url` | inline | `site.translation` {default, languages, exclude} |
+| `omega_logo` | inline | `options.logos.dir`; per-instance SVG id prefixing (url()/href/xlink:href refs rewritten) |
+| `omega_image` | inline | pure HTML builder (picture + webp sources + lazy placeholders; `max_width`, `webp=false`, external `<img>`) |
+| `omega_video` | inline | pure HTML builder (flag attrs, mime map, lazy sources) |
+| `omega_member` | inline | `options.getCollection('team')` — docs `{ id, url, data }` |
+| `omega_post` | inline | `options.getCollection/getCollectionNames` — id / substring / custom `post.id` matching across collections |
+
+Port simplification: the Ruby `member`/`post` `image-tag` property re-parsed a
+`{% omega_image %}` template string; the JS calls the shared `buildImageHtml()`
+directly — same output, no re-parse.
+
+Tag options (`src/variable-resolver.js`): a typed literal resolves TYPED —
+`max_width=640` is the number 640 and `webp=false` the boolean ([#102](https://github.com/Omega-JS-Stack/omega/issues/102));
+quote it (`max_width="640"`) to keep a string. A bare word keeps its literal
+text unless the context has it (`class=card` works), a dotted path always
+resolves, and a missing path yields `null` so a typo never renders its own
+name into the page.
+
+## Jekyll-style helper pack (`src/jekyll-compat.js`)
+
+These are omega's own template helpers under the familiar Jekyll-style names —
+the names are the authoring surface Ian writes in, and the contract is CORRECT
+BEHAVIOR, not emulation of Jekyll internals. Where Jekyll's own semantics are
+surprising, these do the sane thing and the tests pin it ([#102](https://github.com/Omega-JS-Stack/omega/issues/102)).
+
+`slugify` is the ONE slugifier ([#488](https://github.com/Omega-JS-Stack/omega/issues/488)):
+downcase, non-alphanumeric runs become `-`. It is what LINKS a taxonomy term
+and what the term's page is GENERATED at (`src/collections.js`), so `A&R` is
+`a-r` on both sides. Eleventy ships a universal `slugify` of its own (`&` →
+"and") that used to shadow it in templates — `src/engine.js` claims the name
+back through a plugin, because a term whose link and page disagree is a
+guaranteed 404 the framework's own link check fails the build on.
+
+Implemented: `slugify`, `date_to_xmlschema`, `date_to_rfc822`, `jsonify`,
+`strip_html`, `markdownify`, `relative_url`, `absolute_url`,
+`number_of_words`, `where_exp`, `group_by_exp` (`push` comes from LiquidJS).
+The `*_exp` filters read the SIMPLE expression subset (`item.path <op>
+literal`, contains, bare paths) — extend it when a site needs more.
+`where_exp` keeps the items whose expression is truthy; `group_by_exp` buckets
+by the expression's VALUE, one group per distinct value in first-seen order
+(an absent value groups under `''`).
+
+## Adapter contract (`registerLiquid(engine, options)`)
+
+```js
+registerLiquid(new Liquid({ jekyllInclude: true }), {
+  site,                                  // the site.* global — pair with @omega.js/config's toSiteGlobal()
+  getCollection: (name) => docs,         // docs: { id: '/team/x', url, data }  (Jekyll doc parity)
+  getCollectionNames: () => [...],
+  fileExists: (path) => boolean,
+  markdown: (content) => html,           // e.g. markdown-it render
+  icons: { fontAwesomeDirs, aliasFile, flagsDir, style },
+  logos: { dir },
+});
+```
+
+`site.*` comes from `@omega.js/config`'s **`toSiteGlobal(resolvedConfig)`**
+(`packages/config/src/site-global.js`): identity mapping of the resolved
+config (machinery keys `targets`/`enabled` stripped; `url` derived from
+`brand.url` unless explicit; `baseurl` defaulted) — the site.* audit showed
+the resolved omega.json5 shape IS the template shape. Engine-owned keys
+(`site.posts`, `site.pages`, `site.data`, `site.time`) are the SSG's
+responsibility. `site.collections` is not among them ([#207](https://github.com/Omega-JS-Stack/omega/issues/207)):
+it carries the `targets.web.collections` DECLARATION through the identity
+mapping, and the engine reads it to generate each declared collection's pages.
+
+## What is deliberately NOT here
+
+The Ruby plugin's generators/hooks (`inject-properties.rb` = `page.resolved`,
+`blog-taxonomy.rb`, `dynamic-pages.rb`, `limit-collections.rb`,
+`parallel-build.rb`, `markdown-images.rb`) are ENGINE features, not template
+functions — each bake-off candidate maps them natively (Eleventy: data
+cascade / eleventyComputed; Astro: helpers). Plan §4 A1.
+
+## Usage numbers that set the porting priority (2026-07-06 audit)
+
+UJM theme/blueprints: `uj_icon` 612 (retired — icons are native markup since [#619](https://github.com/Omega-JS-Stack/omega/issues/619)), `iftruthy` ~370, `omega_content_format` 97,
+`iffalsy` 72, `omega_liquify` 71, `omega_member` 62, `omega_cachebreak` 34,
+`omega_title_case` 27, `urlmatches` 19, `omega_commaify` 18, `omega_post` 17,
+`omega_readtime` 15, everything else single digits. somiibo adds only
+`uj_icon`/`omega_liquify`/`omega_content_format` + iftruthy/iffalsy/urlmatches.