@omega.js/manager 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/testing.md

@@ -0,0 +1,34 @@
+# The testing service — health checks after the walk
+
+The `testing` service runs LAST: per-target health checks after every other service has had
+its pass. Local checks read the repo; live checks fetch the deployed brand. A dry run never
+touches the network — every live check prints a "would" line instead.
+
+## What it checks
+
+| Target | Checks |
+|---|---|
+| `web` | `package.json`, `dist/index.html`, the installed framework version vs npm latest, and a homepage fetch. |
+| `backend` | `package.json`, `firebase.json`, the staged `dist/` build output, the installed framework version vs npm latest, and API health + the deployed version (skipped for a shared Firebase project). |
+| every target | `package.json`, and the framework version when declared. |
+| repo-level (once) | A clean working tree, and the latest GitHub Actions run (only with `repo.providers.github.org` configured). |
+
+Results roll up honestly: any failed check makes the service an error, any warning makes it
+warned. The output shape matches omega-manager's testing service, so the run summary's
+drill-down works unchanged.
+
+## Config
+
+No config of its own; it reads the brand's targets, `repo.providers.github.org`, and
+`cloud.shared`. Injection seams for the network-free tests ride `options` (`fetch`, `exec`,
+`retryDelayMs`).
+
+## Gotchas
+
+- **A custom-mode backend has no `firebase.json`** to demand
+  ([#584](https://github.com/Omega-JS-Stack/omega/issues/584)): that is the one Firebase-only
+  check, noted with its reason instead of failed. The staged `dist/` check still runs — a
+  custom backend builds like any other.
+- **Not ported from omega-manager**: the `build.json` check (a UJM artifact — `@omega.js/web`
+  has no build manifest) and the stash check (nothing stashes in the new update service).
+  GitHub Actions is repo-level here, because a brand is one repo.

package/docs/update.md

@@ -0,0 +1,36 @@
+# The update service — install and build every target
+
+The `update` service is the install + build pass: one `npm install` at the brand root (npm
+workspaces cover every target), then each target's own `npm run build`. It is the slow tail of
+every walk, and it runs late — after everything that writes a target's inputs, before the
+account and testing services that talk to a deployed brand.
+
+## What it reconciles
+
+One operation, `targets`:
+
+- **Install** is dependency-resolution-gated for idempotency: when every target's declared
+  deps already resolve through the `node_modules` climb, the install is skipped — so a second
+  run is a no-op, and a brand nested inside a larger workspace never grows a stray
+  `node_modules`.
+- **Build** runs each target's `npm run build`. A target with no build script is recorded as
+  SKIPPED, not failed (a backend's "build" is its deploy story).
+
+The service skips entirely when no dir maps to a target.
+
+## The incremental cache
+
+The `update` service is incremental ([#445](https://github.com/Omega-JS-Stack/omega/issues/445)): per target it fingerprints TWO input sets, the target's own tree (a stat sweep that excludes `node_modules`, `dist`, `logs`, `.temp`, `.omega`, `.cache`, `.firebase` and log files, so a build can never dirty its own inputs) plus the merge-chain files above it: brand and company `omega.json5` and `.env`, each `.env` counted with its `.env.<environment>` overlays, whose spelling comes from @omega.js/config's `envLayerFiles` rather than a path joined here, so an overlay edit dirties the target exactly like a base-file edit ([#681](https://github.com/Omega-JS-Stack/omega/issues/681)). The second set is the installed identity of every `@omega.js/*` dependency the target declares (an npm install contributes its version string; a local link, whose version stands still inside the monorepo, contributes the link target's version plus a sweep of its build output). Both unchanged since that target's last successful build → it is converged and skips with one line; either one fresh → the full build for that target. The pair lives in `.omega/cache/update.json` — derived data, so it sits with the brand's other caches rather than in config — and `omega manage --force` ignores it. A missing or unreadable cache is not an error: the run treats every target as fresh, builds, and rewrites the file.
+
+Both fingerprints are stat walks — relative path, size and mtime — so no file contents are
+ever read.
+
+## Gotchas
+
+- **A failed cache write warns and the walk continues.** A cache is an optimization, never a
+  reason to fail a run.
+- **A brand-config edit invalidates every target.** The merge-chain files fold into each
+  target's fingerprint on purpose: a config change that left every target "converged" would
+  serve stale output silently.
+- **Phases beyond install/build** (bump, deploy, sync) live in the deliberate verbs, not here —
+  see [deploys.md](shared/deploys.md).

package/docs/workspace.md

@@ -0,0 +1,64 @@
+# The workspace service — the brand monorepo itself
+
+The `workspace` service runs FIRST in every walk, and on the boot lane too: everything
+downstream assumes a sane brand monorepo. It reconciles the repo's own shape — root
+`package.json` workspaces, a dir per enabled target, config health, the agent-docs chain,
+the `.env` files — and it is the one service that touches no network at all.
+
+## What it reconciles
+
+| Operation | What it does |
+|---|---|
+| `structure` | Root `package.json` declares `targets/*` and every enabled target has its dir. A dir mapping to no target WARNS; an enabled target with no dir is an ERROR naming the dir to create. Array-form targets expect one dir per instance (`main` → the canonical dir, any other id → `<canonical>-<id>`). |
+| `config` | `config/omega.json5` loads and validates. A brand file that fails to load or validate is an ERROR — there is nothing sound to reconcile against. Per-target findings are warnings; each framework's own audit is the hard gate for its surface. |
+| `defaults` | Materializes the schema-defaulted blocks the brand file does not carry yet ([#478](https://github.com/Omega-JS-Stack/omega/issues/478)), each with the schema's own description as its comment. Never overwrites: a converged config is byte-identical. |
+| `gitignore` | `.omega/` and `logs/` are ignored at the brand root — the secrets store and run output never get committed. |
+| `scripts` | Root `package.json` scripts say `omega` (a legacy omega-manager brand is healed) and a `deploy` script exists; each framework target's scripts sync to its framework's `projectScripts` declaration. Those standard keys are FRAMEWORK-owned ([#689](https://github.com/Omega-JS-Stack/omega/issues/689)): the walk and the framework's own ensureTarget both rewrite them to the defaults on every run, so a hand-edited standard script heals instead of drifting — customize behavior through hook points, never by editing one. Keys the framework never declares are the consumer's own and are never touched. The walk runs it at all as the onboard→dev cycle break (#675): the dev fan-out reaches those verbs THROUGH these scripts. Exceptions: a custom target maps to no framework, so it is skipped whole (#603); a custom-server backend is skipped PER KEY (#584) — it owns `start`, `deploy`, `emulator` and `test:emulator` (the verbs its mode refuses, named by the framework's `projectScriptsCustomOwned`), which are never written and never scaffolded, while `test` and `test:static` stay framework-owned. Script VALUES only; no other key is touched. |
+| `agents` | The brand's agent-docs chain: `node_modules/@omega.js/AGENTS.md` links the framework map, root `AGENTS.md` opens with the import, root `CLAUDE.md` is the one-line pointer. Consumer content is preserved; a content-bearing `CLAUDE.md` warns instead of being clobbered. |
+| `claude-settings` | The committed `.claude/settings.json` that enables the omega plugin (below). |
+| `workflows` | Deletes the brand root's composed `.github/workflows/<target>-*.yml` for targets the config no longer enables ([#636](https://github.com/Omega-JS-Stack/omega/issues/636)). Only files carrying the GENERATED header AND the composed name — the brand's own workflows share that dir and are never candidates. The target's DIR is left alone. |
+| `env-keys` | Mints the env schema's `generated` keys into the brand `.env` when the cascade has none ([#569](https://github.com/Omega-JS-Stack/omega/issues/569)). |
+| `env-order` | Rewrites the brand (and company) `.env` into the canonical group order. The `.env.<environment>` overlays beside it are a human's hand-picked few, not a canonical inventory, so nothing reorders them. |
+| `env-rules` | Names the keys the brand's own config made mandatory and nobody filled in ([#626](https://github.com/Omega-JS-Stack/omega/issues/626)). |
+| `translation-sdk` | A translating web target declares + installs `@anthropic-ai/claude-agent-sdk` ([#168](https://github.com/Omega-JS-Stack/omega/issues/168)). |
+
+## Config and credentials
+
+No credential of its own — nothing here leaves the machine. It reads `targets` (which dirs
+must exist), the whole of `config/omega.json5` (the `config` and `defaults` ops), and each
+target's own config for the translation check.
+
+## The `.env` ops, and why presence is judged on the RESOLVED value
+
+`env-keys` and `env-rules` both read `process.env` — which `manage.js` already layered as
+shell > brand `.env` > company `.env`, each of those overlaid by its own
+`.env.<environment>` file ([#586](https://github.com/Omega-JS-Stack/omega/issues/586)) —
+never the brand file alone. A company-managed brand therefore never shadows its company's
+value with a freshly minted one, and neither does a brand whose value lives only in an
+overlay. A minted value is
+published into `process.env` too, so the same run's builds compose it: the key is live one
+manage after the gap, not two. Values are never printed; the run says WHICH key it minted.
+
+`env-order` leaves a file it cannot parse (multi-line values, `export` forms) untouched
+with a note. `env-rules` WARNS and never fails — a half-configured brand is a normal step
+on the way to a configured one, and the lanes that truly cannot proceed (a production
+backend boot) refuse on their own. Its rules are evaluated per enabled target against that
+target's resolved config, so a per-surface key is judged where the services write it — and
+a TARGET-LESS rule (a service's own key, like `SENTRY_AUTH_TOKEN`) is owed when its config
+path is truthy in the brand root or in ANY enabled target's resolved config
+([#683](https://github.com/Omega-JS-Stack/omega/issues/683)), because that is where the
+service wrote the value that requires it.
+
+## The `claude-settings` op
+
+The `claude-settings` op ([#62](https://github.com/Omega-JS-Stack/omega/issues/62)) writes the OTHER half of a brand's agent setup: the committed `.claude/settings.json` that registers the omega marketplace shipped inside the installed manager package (`./node_modules/@omega.js/manager`) and enables `omega@omega`, so every session in that brand — anyone's, on any machine — loads the plugin. Gated on a published install: the installed manager must carry the vendored `.claude-plugin/marketplace.json` ([publishing.md](shared/publishing.md)) and be a real directory rather than a symlink into the monorepo, so the local era skips and the developer's own user-scope install serves those sessions. Idempotent and non-clobbering — the two omega keys are deep-merged, a correct file is not rewritten, and a settings file that doesn't parse is reported, never overwritten (`src/lib/claude-settings.js`, pinned by `test/claude-settings.test.js`).
+
+## Gotchas
+
+- **Custom targets are checked BY DIR.** A `type: 'custom'` target maps to no framework, so
+  `structure` reads the declaration's dir name and never counts it among the unmapped — one
+  of only two manage ops that see custom targets at all ([config.md](shared/config.md) § Custom targets).
+- **`defaults` never invents an owner decision.** Keys with no sane framework answer —
+  provisioned ids, anything secret-shaped — carry no schema default and are never written.
+- **`translation-sdk` never removes.** Turning translation off leaves the dep in place;
+  uninstalling on a config flip is riskier than leaving it.

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "@omega.js/manager",
+  "version": "0.1.0",
+  "description": "The OMEGA orchestration engine — walks every service in dependency order and reconciles each to the brand's omega.json5, idempotently, against a brand monorepo. omega-manager's brains, ported service by service. Private until first publish.",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "bin": {
+    "omega": "./bin/omega",
+    "omg": "./bin/omg",
+    "mgr": "./bin/omega"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "claude-plugin/",
+    "dist/",
+    "docs/"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./cli": "./dist/cli-run.js",
+    "./service-runner": "./dist/lib/service-runner.js",
+    "./run-summary": "./dist/lib/run-summary.js",
+    "./brand": "./dist/lib/brand.js",
+    "./manage": "./dist/manage.js"
+  },
+  "scripts": {
+    "start": "npm run prepare:watch",
+    "prepare": "node -e \"require('@omega.js/devkit/prepare-guard')() && require('prepare-package')()\"",
+    "prepare:watch": "node -e \"require('prepare-package/watch')()\"",
+    "test": "node --require @omega.js/devkit/test/stdout-guard --test test/*.test.js"
+  },
+  "preparePackage": {
+    "input": "./src",
+    "output": "./dist",
+    "replace": {},
+    "type": "copy",
+    "hooks": {
+      "after": [
+        "node -e \"require('@omega.js/devkit/vendor')()\"",
+        "node -e \"require('@omega.js/devkit/prepare-guard').rewire()\""
+      ],
+      "afterBlocking": true
+    }
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "@omega.js/backend": "0.1.0",
+    "@omega.js/mcp-router": "0.1.0",
+    "ag-psd": "^31.0.2",
+    "canvas": "^3.2.3",
+    "chalk": "^5.6.2",
+    "dotenv": "^17.4.2",
+    "fs-jetpack": "^5.1.0",
+    "json5": "^2.2.3",
+    "node-powertools": "^3.0.0",
+    "opentype.js": "^2.0.0",
+    "png2icons": "^2.0.1",
+    "psl": "^1.15.0",
+    "puppeteer": "^24.43.1",
+    "sharp": "^0.35.3",
+    "stripe": "^22.3.0",
+    "ws": "^8.21.0",
+    "yargs": "^18.0.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/claude-agent-sdk": ">=0.2"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@omega.js/account": "*",
+    "@omega.js/config": "*",
+    "@omega.js/devkit": "*",
+    "prepare-package": "^2.2.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "author": "ITW Creative Works",
+  "license": "Elastic-2.0"
+}