@omega.js/manager 0.1.0

package/dist/services/update/write/targets.js

@@ -0,0 +1,206 @@
+/**
+ * Install + build every target-mapped dir.
+ *
+ * Install is ONE `npm install` at the brand root (npm workspaces cover every
+ * target), and it's dependency-resolution-gated for idempotency: if 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 (the monorepo's sandbox brand) never grows a stray node_modules.
+ *
+ * Build runs each target's own `npm run build`; targets without a build script are
+ * recorded as skipped, not failed (a backend's "build" is its deploy story).
+ * Those builds are the slow tail of every walk, so they are INCREMENTAL
+ * (#445): a target whose own files AND whose installed `@omega.js/*` frameworks
+ * are both unchanged since its last successful build is converged and skips
+ * with one line (lib/fingerprint.js), the fingerprint pair living in
+ * `.omega/cache/update.json` (lib/cache.js). Either set fresh → the full build
+ * for that target; `--force` ignores the cache, and so does a brand whose cache
+ * is missing or unreadable.
+ *
+ * Output shape matches omega-manager's update service so RunSummary's
+ * drill-down works unchanged: { results: { [target]: { steps: [{ phase,
+ * success, error?, skipped? }] } } }.
+ */
+const path = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+
+const { envLayerFiles, ENV_ENVIRONMENTS } = require('../../../vendor/config/index.js');
+
+const { runCommand } = require('../../../lib/run-command.js');
+const { readCompanyMarker } = require('../../../lib/company.js');
+const { fingerprintTarget, resolvePackageDir } = require('../lib/fingerprint.js');
+const { readCache, writeCache, CACHE_VERSION } = require('../lib/cache.js');
+
+/**
+ * One env LAYER's files: the base `.env` plus its `.env.<environment>` overlays.
+ *
+ * The overlay spelling is @omega.js/config's (`envLayerFiles`, #586), never a
+ * join written out here, and EVERY environment is fingerprinted because a build
+ * can run under any of them and an absent file digests as `absent` either way.
+ * Fingerprinting the base file by exact path was the gap ([#681](https://github.com/Omega-JS-Stack/omega/issues/681)):
+ * an overlay is a real layer of the cascade and carries the values that DIFFER
+ * per environment, so an overlay edit left the target converged and its build
+ * served the old value.
+ *
+ * @param {string} label - The layer's fingerprint label ('brand-env').
+ * @param {string} root - The dir whose `.env` is this layer.
+ * @returns {Array<{ label: string, file: string }>} One entry per layer file.
+ */
+function envLayerEntries(label, root) {
+  const base = path.join(root, '.env');
+  const files = [...new Set(ENV_ENVIRONMENTS.flatMap((environment) => envLayerFiles(base, environment)))];
+
+  return files.map((file) => ({
+    label: file === base ? label : `${label}.${file.slice(base.length + 1)}`,
+    file,
+  }));
+}
+
+/**
+ * The merge-chain files OUTSIDE the target tree that its build still reads:
+ * brand config/.env, and the company pair when the brand carries a marker.
+ * A brand-config edit must dirty every target's fingerprint, or the
+ * converged skip serves stale output.
+ */
+function chainFiles(brandRoot) {
+  const files = [
+    { label: 'brand-config', file: path.join(brandRoot, 'config', 'omega.json5') },
+    ...envLayerEntries('brand-env', brandRoot),
+  ];
+
+  const marker = readCompanyMarker(brandRoot);
+  if (marker) {
+    files.push(
+      { label: 'company-config', file: path.join(marker.companyRoot, 'config', 'omega.json5') },
+      ...envLayerEntries('company-env', marker.companyRoot),
+    );
+  }
+
+  return files;
+}
+
+/**
+ * Collect declared deps (dependencies + devDependencies) missing from an
+ * target's resolution climb.
+ */
+function missingDeps(targetPath) {
+  const pkg = jetpack.read(path.join(targetPath, 'package.json'), 'json');
+  if (!pkg) return [];
+
+  const declared = Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+  return declared.filter((name) => !resolvePackageDir(targetPath, name));
+}
+
+module.exports = async ({ brandRoot, targets, options }) => {
+  const mappedTargets = targets.filter((entry) => entry.target);
+  const results = {};
+  let failed = false;
+
+  // ─── Install phase (once, at the brand root) ──────────────────────────────
+  const missing = mappedTargets.flatMap((entry) => missingDeps(entry.path).map((dep) => `${entry.name}:${dep}`));
+  const installSteps = [];
+
+  if (missing.length === 0) {
+    console.log(`      ${chalk.dim('⊘ install: all dependencies resolve')}`);
+    installSteps.push({ phase: 'install', success: true, skipped: true });
+  } else if (options.dryRun) {
+    console.log(`      ${chalk.yellow('⊘')} install: would run npm install ${chalk.dim(`(missing: ${missing.join(', ')})`)} ${chalk.dim('[DRY RUN]')}`);
+    installSteps.push({ phase: 'install', success: true, skipped: true, dryRun: true });
+  } else {
+    console.log(`      ${chalk.dim('→')} npm install ${chalk.dim(`(missing: ${missing.join(', ')})`)}`);
+    const result = await runCommand('npm', ['install', '--no-audit', '--no-fund'], brandRoot);
+    installSteps.push({ phase: 'install', ...result });
+    if (!result.success) {
+      failed = true;
+      // Local-first era: the frameworks aren't on the registry yet
+      if (missing.some((entry) => entry.includes('@omega.js/'))) {
+        console.log(`      ${chalk.yellow('⚠')} @omega.js/* packages are not published yet — link them per target with ${chalk.bold('mgr i local')} (or a workspace/file: reference).`);
+      }
+    }
+  }
+
+  results.root = { steps: installSteps };
+
+  // ─── Build phase (per target, incremental) ────────────────────────────────
+  const cache = readCache(brandRoot);
+  const chain = chainFiles(brandRoot);
+  const nextTargets = {};
+
+  for (const entry of mappedTargets) {
+    const steps = [];
+    const cached = cache.targets[entry.name];
+
+    if (failed) {
+      // Nothing was rebuilt, so last run's verdict for this target still stands
+      if (cached) nextTargets[entry.name] = cached;
+      steps.push({ phase: 'build', success: true, skipped: true, reason: 'install failed' });
+      results[entry.name] = { steps };
+      continue;
+    }
+
+    const pkg = jetpack.read(path.join(entry.path, 'package.json'), 'json');
+    // Only worth sweeping when there's a cached verdict to compare against
+    // and the run is allowed to honour it
+    const fingerprint = cached && pkg?.scripts?.build && !options.force
+      ? fingerprintTarget(entry.path, chain)
+      : null;
+    const converged = Boolean(fingerprint)
+      && cached.files === fingerprint.files
+      && cached.frameworks === fingerprint.frameworks;
+
+    if (!pkg?.scripts?.build) {
+      console.log(`      ${chalk.dim(`⊘ ${entry.name}: no build script`)}`);
+      steps.push({ phase: 'build', success: true, skipped: true, reason: 'no build script' });
+    } else if (converged) {
+      console.log(`      ${chalk.dim(`⊘ ${entry.name}: converged (target files + @omega.js/* unchanged)`)}`);
+      nextTargets[entry.name] = cached;
+      steps.push({ phase: 'build', success: true, skipped: true, reason: 'converged' });
+    } else if (options.dryRun) {
+      console.log(`      ${chalk.yellow('⊘')} ${entry.name}: would run npm run build ${chalk.dim('[DRY RUN]')}`);
+      steps.push({ phase: 'build', success: true, skipped: true, dryRun: true });
+    } else {
+      // Non-interactive runs (pipeline, CI, and `omega dev`'s boot manage
+      // cycle — #228) must be deterministic: web builds use the committed
+      // translation cache only — never a live LLM pass mid-run (the same law
+      // deploys follow). New strings translate on the next interactive run.
+      const buildArgs = ['run', 'build'];
+      if (entry.target === 'web' && process.env.OMEGA_NON_INTERACTIVE === '1') {
+        buildArgs.push('--', '--cached-only');
+      }
+      console.log(`      ${chalk.dim('→')} ${entry.name}: npm ${buildArgs.join(' ')}`);
+      const result = await runCommand('npm', buildArgs, entry.path);
+      steps.push({ phase: 'build', ...result });
+
+      if (result.success) {
+        // Re-fingerprint AFTER the build: a build that writes back into its
+        // own sources (the web translation cache) would otherwise leave the
+        // target looking fresh forever. A failed build records nothing, so the
+        // next run retries it.
+        nextTargets[entry.name] = { ...fingerprintTarget(entry.path, chain), updatedAt: new Date().toISOString() };
+      } else {
+        failed = true;
+      }
+    }
+
+    results[entry.name] = { steps };
+  }
+
+  // One write, only when something moved (a build landed, a target left the
+  // brand, or the file was missing/unreadable and this rebuilds it). Keys are
+  // sorted so a converged rerun produces the byte-identical file it read.
+  const nextCache = {
+    version: CACHE_VERSION,
+    targets: Object.fromEntries(Object.keys(nextTargets).sort().map((name) => [name, nextTargets[name]])),
+  };
+
+  if (!options.dryRun && JSON.stringify(nextCache) !== JSON.stringify(cache)) {
+    writeCache(brandRoot, nextCache);
+  }
+
+  return {
+    status: failed ? 'error' : 'success',
+    output: { results },
+  };
+};

package/dist/services/workspace/ensure/agents.js

@@ -0,0 +1,42 @@
+/**
+ * Ensure the brand agent-docs chain (Ian 2026-07-20): root AGENTS.md opens
+ * with the framework-guide import, root CLAUDE.md is the one-line
+ * `@AGENTS.md` pointer. Consumer content is preserved; a content-bearing
+ * CLAUDE.md warns with the move-it message instead of being clobbered.
+ */
+const chalk = require('chalk').default;
+
+const { ensureAgentsMd, ensureClaudePointer, ensureGuideLink, IMPORT_LINE, CLAUDE_POINTER } = require('../../../lib/agents-md.js');
+
+module.exports = async ({ brandRoot, brand }) => {
+  const brandName = brand.config?.brand?.name || brand.id;
+
+  const guide = ensureGuideLink(brandRoot);
+  const guideLabel = {
+    present: 'node_modules/@omega.js/AGENTS.md links the framework map',
+    created: 'Linked node_modules/@omega.js/AGENTS.md at the framework map',
+    healed: 'Relinked node_modules/@omega.js/AGENTS.md at the framework map',
+    skipped: 'No resolvable framework map yet (pre-install) — link skipped',
+  }[guide];
+  console.log(`      ${chalk.green('✓')} ${guideLabel}`);
+
+  const agents = ensureAgentsMd(brandRoot, brandName);
+  const agentsLabel = {
+    present: `AGENTS.md imports the framework guide (${IMPORT_LINE})`,
+    created: 'Created AGENTS.md with the framework-guide import',
+    healed: 'Healed AGENTS.md — framework-guide import moved to line 1 (your content preserved)',
+  }[agents];
+  console.log(`      ${chalk.green('✓')} ${agentsLabel}`);
+
+  const claude = ensureClaudePointer(brandRoot);
+  if (claude === 'content-bearing') {
+    console.log(`      ${chalk.yellow('⚠')} CLAUDE.md carries content — move it into AGENTS.md (below the import) and reduce CLAUDE.md to the one-line \`${CLAUDE_POINTER}\` pointer`);
+    return { status: 'warned', reason: 'CLAUDE.md carries content — move it into AGENTS.md', output: { guide, agents, claude } };
+  }
+  console.log(`      ${chalk.green('✓')} CLAUDE.md ${claude === 'created' ? 'created as' : 'is'} the \`${CLAUDE_POINTER}\` pointer`);
+
+  if (agents === 'present' && claude === 'present' && (guide === 'present' || guide === 'skipped')) {
+    return null;
+  }
+  return { output: { guide, agents, claude } };
+};

package/dist/services/workspace/ensure/claude-settings.js

@@ -0,0 +1,34 @@
+/**
+ * Ensure the brand's committed `.claude/settings.json` registers the omega
+ * marketplace from the installed manager package and enables the plugin
+ * ([#62](https://github.com/Omega-JS-Stack/omega/issues/62)) — the consumer
+ * half of the plugin install. Only a PUBLISHED install carries the vendored
+ * marketplace; the local era skips (the developer's user-scope install serves
+ * those sessions). Consumer settings are never clobbered.
+ */
+const chalk = require('chalk').default;
+
+const { ensureClaudeSettings, SETTINGS_FILE, PLUGIN_ID } = require('../../../lib/claude-settings.js');
+
+module.exports = async ({ brandRoot }) => {
+  const result = ensureClaudeSettings(brandRoot);
+
+  if (result === 'skipped') {
+    console.log(`      ${chalk.green('✓')} No vendored omega plugin in node_modules/@omega.js/manager (local era) — ${SETTINGS_FILE} left alone`);
+    return null;
+  }
+
+  if (result === 'invalid') {
+    console.log(`      ${chalk.yellow('⚠')} ${SETTINGS_FILE} is not valid JSON — fix it so the omega plugin (${PLUGIN_ID}) can be registered`);
+    return { status: 'warned', reason: `${SETTINGS_FILE} is not valid JSON`, output: { claudeSettings: result } };
+  }
+
+  const label = {
+    present: `${SETTINGS_FILE} enables the omega plugin (${PLUGIN_ID})`,
+    created: `Created ${SETTINGS_FILE} — the omega plugin loads in every session here`,
+    healed: `Healed ${SETTINGS_FILE} — omega plugin registered (your other settings preserved)`,
+  }[result];
+  console.log(`      ${chalk.green('✓')} ${label}`);
+
+  return result === 'present' ? null : { output: { claudeSettings: result } };
+};

package/dist/services/workspace/ensure/config.js

@@ -0,0 +1,54 @@
+/**
+ * Ensure omega.json5 health. The brand file is the manager's input — a brand
+ * config that fails to load (parse error, secret-shaped keys, legacy targets
+ * array) or fails schema validation is an ERROR: there is nothing sound to
+ * reconcile services against. Target-level findings are warnings — each
+ * framework's own setup/audit is the hard gate for its surface.
+ */
+const chalk = require('chalk').default;
+
+const { loadConfig, hasOmegaConfig } = require('../../../vendor/config/index.js');
+
+module.exports = async ({ brand, targets }) => {
+  // Brand config failed to LOAD (thrown by @omega.js/config — secrets, parse, targets array)
+  if (brand.configError) {
+    console.log(`      ${chalk.red('✗')} ${brand.configError}`);
+    return { status: 'error', error: brand.configError };
+  }
+
+  // Brand config loaded but has schema findings
+  if (brand.configErrors.length > 0) {
+    for (const error of brand.configErrors) {
+      console.log(`      ${chalk.red('✗')} brand: ${error}`);
+    }
+    return { status: 'error', error: `brand config invalid: ${brand.configErrors.join('; ')}` };
+  }
+
+  console.log(`      ${chalk.green('✓')} brand config valid ${chalk.dim(`(${brand.files?.app || 'config/omega.json5'})`)}`);
+
+  // Per-target validation for dirs that carry their own config and map to a target
+  const findings = [];
+  for (const entry of targets) {
+    if (!entry.target || !hasOmegaConfig(entry.path)) continue;
+
+    try {
+      const { errors } = loadConfig(entry.path, entry.target);
+      for (const error of errors) {
+        findings.push(`${entry.name}: ${error}`);
+      }
+    } catch (error) {
+      // A target config that cannot load at all (secrets, parse) is still a hard stop
+      console.log(`      ${chalk.red('✗')} ${entry.name}: ${error.message}`);
+      return { status: 'error', error: `${entry.name}: ${error.message}` };
+    }
+  }
+
+  if (findings.length > 0) {
+    for (const finding of findings) {
+      console.log(`      ${chalk.yellow('⚠')} ${finding}`);
+    }
+    return { status: 'warned', reason: findings.join('; '), output: { findings } };
+  }
+
+  return null;
+};

package/dist/services/workspace/ensure/defaults.js

@@ -0,0 +1,60 @@
+/**
+ * Self-healing config ([#478](https://github.com/Omega-JS-Stack/omega/issues/478)):
+ * every manage run materializes the schema-defaulted blocks the brand's
+ * omega.json5 does not carry yet, so a subsystem that exists has its config
+ * structure visible and editable in the file — never an invisible framework
+ * fallback. A newly added default therefore appears in every consumer's config
+ * on the next run.
+ *
+ * What it never does: overwrite. `missingDefaults()` names only the keys the
+ * brand has not authored, the comment-preserving editor inserts them (each
+ * block documented with the schema's own description), and a converged config
+ * leaves the file byte-identical. Keys with no sane framework answer — owner
+ * decisions, provisioned ids, anything secret-shaped — carry no schema default
+ * and are never written here.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+const JSON5 = require('json5');
+
+const { missingDefaults, defaultComments, writeConfigValues, resolveConfigPath, FILE_NAME } = require('../../../vendor/config/index.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async ({ brandRoot, options = {} }) => {
+  const configPath = resolveConfigPath(brandRoot);
+  if (!configPath) {
+    console.log(`      ${chalk.dim(`⊘ no ${join('config', FILE_NAME)} yet (the config operation reports it)`)}`);
+    return null;
+  }
+
+  // The RAW file, not the resolved config: resolution already merged the
+  // defaults in, so every block would read as present.
+  const missing = missingDefaults(JSON5.parse(jetpack.read(configPath)));
+
+  if (missing.length === 0) {
+    console.log(`      ${chalk.green('✓')} ${FILE_NAME} carries every schema default`);
+    return null;
+  }
+
+  const blocks = missing.map((entry) => entry.path);
+
+  if (options.dryRun) {
+    return dryRunPlan(
+      `materialize ${blocks.join(', ')} in ${FILE_NAME}`,
+      { output: { defaults: { planned: blocks } } },
+    );
+  }
+
+  writeConfigValues(
+    brandRoot,
+    Object.fromEntries(missing.map((entry) => [entry.path, entry.value])),
+    { comments: defaultComments() },
+  );
+
+  for (const block of blocks) {
+    console.log(`      ${chalk.green('+')} ${FILE_NAME} ← ${chalk.cyan(block)} ${chalk.dim('(schema default)')}`);
+  }
+
+  return { output: { defaults: { materialized: blocks } } };
+};

package/dist/services/workspace/ensure/env-keys.js

@@ -0,0 +1,55 @@
+/**
+ * Ensure the brand .env carries every key OMEGA generates for itself — the
+ * env schema's `generated` entries (@omega.js/config, #581) — the manage-time
+ * half of the mint the onboard scaffold does for a fresh brand (#569). A brand
+ * onboarded before a key existed gains it here instead of discovering the hole
+ * at the first send.
+ *
+ * Presence is judged on the RESOLVED value (`process.env`, which manage
+ * already layered shell > brand .env > company .env), so a company-managed
+ * brand never shadows its company's value with a fresh one. A minted value
+ * is published into `process.env` too, so the same run's builds compose it
+ * into their targets — the key is live one manage after the gap, not two.
+ * Values are never printed: the run says WHICH key it minted, never what.
+ *
+ * The mint itself is lib/env-secret.js's `mintGeneratedKey` — shared with the
+ * setup contract, which mints a single key for a service that reached it
+ * before this op ran (#635).
+ */
+const chalk = require('chalk').default;
+
+const { generatedEnvKeys } = require('../../../vendor/config/index.js');
+const { mintGeneratedKey } = require('../../../lib/env-secret.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async (context) => {
+  const { brandRoot, options = {} } = context;
+
+  const minted = [];
+  const planned = [];
+  const present = [];
+
+  for (const name of Object.keys(generatedEnvKeys())) {
+    if (process.env[name]) {
+      present.push(name);
+      continue;
+    }
+
+    if (options.dryRun) {
+      dryRunPlan(`mint ${name} into the brand .env`);
+      planned.push(name);
+      continue;
+    }
+
+    // The mint — and its success line — live once, in lib/env-secret.js, so
+    // this op and the setup contract report an identical key identically
+    mintGeneratedKey(brandRoot, name);
+    minted.push(name);
+  }
+
+  if (present.length > 0) {
+    console.log(`      ${chalk.green('✓')} generated keys (${present.length} present)`);
+  }
+
+  return { output: { envKeys: { minted, planned, present } } };
+};

package/dist/services/workspace/ensure/env-order.js

@@ -0,0 +1,66 @@
+/**
+ * Ensure the brand .env (and the company .env when the brand is
+ * company-managed) is in the canonical order — groups, comments, and
+ * placeholders from the env-order SSOT, hand comments travelling with
+ * their keys, duplicates collapsed to the dotenv winner. A converged file
+ * rewrites nothing; a file the reorderer can't parse (multi-line values,
+ * export forms) is left untouched with a note, never a failure.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const { applyEnvOrder } = require('../../../lib/env-order.js');
+const { dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async (context) => {
+  const { brandRoot, companyRoot, brandConfig, options = {} } = context;
+
+  const roots = [
+    { label: 'brand', root: brandRoot, isBrand: true },
+    ...(companyRoot ? [{ label: 'company', root: companyRoot, isBrand: false }] : []),
+  ];
+
+  const summary = {};
+  for (const { label, root, isBrand } of roots) {
+    const envPath = join(root, '.env');
+    if (!jetpack.exists(envPath)) {
+      console.log(`      ${chalk.dim(`⊘ no ${label} .env yet`)}`);
+      summary[label] = 'missing';
+      continue;
+    }
+
+    const result = applyEnvOrder(jetpack.read(envPath), {
+      // Only the brand file gets a default header minted (we know its name);
+      // an existing header always wins
+      defaultHeader: isBrand
+        ? [`# ${brandConfig.brand.name} — brand secrets (gitignored; loaded before every omega run).`]
+        : [],
+    });
+
+    if (result.skipped) {
+      console.log(`      ${chalk.dim(`⊘ ${label} .env left as-is (${result.skipped})`)}`);
+      summary[label] = 'skipped';
+      continue;
+    }
+    if (!result.changed) {
+      console.log(`      ${chalk.green('✓')} ${label} .env order (current)`);
+      summary[label] = 'current';
+      continue;
+    }
+    if (options.dryRun) {
+      dryRunPlan(`reorder the ${label} .env into canonical groups`);
+      summary[label] = 'planned';
+      continue;
+    }
+
+    jetpack.write(envPath, result.content);
+    const dupNote = result.duplicatesCollapsed > 0
+      ? chalk.dim(` (${result.duplicatesCollapsed} duplicate line${result.duplicatesCollapsed === 1 ? '' : 's'} collapsed, last value kept)`)
+      : '';
+    console.log(`      ${chalk.green('✓')} ${label} .env reordered${dupNote}`);
+    summary[label] = 'reordered';
+  }
+
+  return { output: { envOrder: summary } };
+};

package/dist/services/workspace/ensure/env-rules.js

@@ -0,0 +1,97 @@
+/**
+ * Say, at MANAGE time, which env keys the brand's OWN config made mandatory
+ * and nobody has filled in — the env schema's `requiredWhen` rules
+ * ([#626](https://github.com/Omega-JS-Stack/omega/issues/626)).
+ *
+ * Every one of those rules used to be discovered LATE and per target: the
+ * extension's build threw on a GA4 stream with no Measurement Protocol secret,
+ * the backend 403'd every protected POST when a reCAPTCHA site key had no
+ * secret half, the captcha service paired the halves with its own if. The
+ * schema declares each rule once, checkEnvRules (@omega.js/config) evaluates
+ * it, and this op is the earliest place a human hears about it.
+ *
+ * Evaluated PER ENABLED TARGET, against that target's RESOLVED config
+ * ([#627](https://github.com/Omega-JS-Stack/omega/issues/627) review): the
+ * values these rules read live where the services write them, and that is the
+ * target section — the analytics service provisions one GA4 stream per surface
+ * (targets.<t>.analytics.providers.google.id) and leaves the shared slot null.
+ * A brand-ROOT evaluation therefore saw NOTHING for the canonical brand shape,
+ * and over-fired for the shared-id one (every per-target secret at once,
+ * including targets the brand does not even enable). The resolution is
+ * @omega.js/config's own (loadConfig with a target overlays targets.<type>);
+ * entries no enabled target claims are never evaluated.
+ *
+ * The few entries no target reads at all (SENTRY_AUTH_TOKEN — the monitoring
+ * SERVICE's) are judged against the brand config AND every enabled target's
+ * resolved one ([#683](https://github.com/Omega-JS-Stack/omega/issues/683)):
+ * the same disease one level over. A target-less key belongs to a SERVICE, but
+ * the config path that requires it is written wherever that service writes its
+ * values — the monitoring service provisions one Sentry project per surface
+ * and lands the DSN in targets.<t>.monitoring.providers.sentry.dsn with the
+ * shared slot null. Truthy in ANY enabled target (or at the root) owes the key
+ * once; the per-key dedupe below is what makes the union one violation.
+ *
+ * It WARNS and never fails. A half-configured brand is a normal step on the way
+ * to a configured one (the key is a dashboard visit away), and a manage run
+ * that refuses to reconcile over it would be a hostage note. The lanes that
+ * CANNOT proceed — a production backend boot — refuse on their own.
+ *
+ * Presence is judged on the RESOLVED cascade (`process.env`, which manage
+ * layered shell > brand .env > company .env before any service ran), so a
+ * company-supplied value counts. Violations name the BRAND-LEVEL key
+ * (GOOGLE_ANALYTICS_SECRET_WEB, not the GOOGLE_ANALYTICS_SECRET it is
+ * delivered to a target as): that is the name a human puts in the .env.
+ */
+const chalk = require('chalk').default;
+
+const { ENV_SCHEMA, loadConfig, getEnabledTargets, TARGETS } = require('../../../vendor/config/index.js');
+const { checkEnvRules } = require('../../../vendor/config/env-rules.js');
+const { DEFAULTS } = require('../../../config.js');
+
+// The entries no target reads (`targets: []`) — a service's own key, which no
+// target-resolved view could ever raise. The checker's `schema` seam scopes a
+// pass to them without this op ever reading a rule itself.
+const TARGETLESS_SCHEMA = ENV_SCHEMA.filter((entry) => entry.targets && entry.targets.length === 0);
+
+module.exports = async (context) => {
+  const { brandRoot, brandConfig } = context;
+
+  // Key presence in `targets` IS the enablement signal; a custom target (#603)
+  // is a brand's own dir, not a framework the schema delivers keys to.
+  const enabled = getEnabledTargets(brandConfig).filter((target) => TARGETS.includes(target));
+
+  const violations = [];
+  const seen = new Set();
+  const collect = (found) => {
+    for (const violation of found) {
+      if (violation.rule !== 'requiredWhen' || seen.has(violation.key)) continue;
+      seen.add(violation.key);
+      violations.push(violation);
+    }
+  };
+
+  collect(checkEnvRules(brandConfig, process.env, { schema: TARGETLESS_SCHEMA }));
+
+  for (const target of enabled) {
+    // The per-target view is @omega.js/config's resolution, not a merge of our
+    // own: same chain as every framework's own load (company ← brand shared ←
+    // brand targets.<type>), so this op and the target's build read one config.
+    const { config } = loadConfig(brandRoot, target, { defaults: DEFAULTS });
+    collect(checkEnvRules(config, process.env, { target }));
+    // …and the service's own keys against that same view (#683): a target-less
+    // entry names no target, so nothing here scopes it — this asks whether the
+    // path that requires it is truthy on THIS surface.
+    collect(checkEnvRules(config, process.env, { schema: TARGETLESS_SCHEMA }));
+  }
+
+  if (violations.length === 0) {
+    console.log(`      ${chalk.green('✓')} config-required env keys (all present)`);
+    return { output: { envRules: { violations } } };
+  }
+
+  for (const { key, path } of violations) {
+    console.log(`      ${chalk.yellow('⚠')} ${chalk.cyan(key)} is missing from the .env cascade — ${chalk.cyan(path)} in omega.json5 requires it`);
+  }
+
+  return { output: { envRules: { violations } } };
+};

package/dist/services/workspace/ensure/gitignore.js

@@ -0,0 +1,18 @@
+/**
+ * Ensure .omega/ and logs/ are gitignored at the brand root — the secrets
+ * store and run output never get committed. Idempotent: checks for existing entries
+ * before appending. The shared ensure also covers company roots (runCompany).
+ */
+const chalk = require('chalk').default;
+
+const { ensureOmegaIgnored } = require('../../../lib/gitignore.js');
+
+module.exports = async ({ brandRoot }) => {
+  if (ensureOmegaIgnored(brandRoot) === 'present') {
+    console.log(`      ${chalk.green('✓')} .gitignore has the omega entries`);
+    return null;
+  }
+
+  console.log(`      ${chalk.green('✓')} Added missing omega entries to .gitignore`);
+  return { output: { gitignore: 'added' } };
+};