@sun-asterisk/sungen 3.2.2 → 3.2.3

package/src/capabilities/discover.ts

@@ -10,8 +10,12 @@
  * load first, then `LOCAL_DRIVERS` (db → api), then `core` — i.e. the historical ui → db → api → core
  * composition order, so pattern composition / compiled output is byte-identical.
  *
- * A driver that isn't installed is simply skipped (capabilities are opt-in). Errors thrown *inside* a
- * present driver propagate — only a genuinely absent package is swallowed (resolve-then-require).
+ * An OPT-IN driver that isn't installed is simply skipped (capabilities are opt-in). A BUNDLED
+ * driver (a core dependency, e.g. `@sungen/driver-ui`) that fails to resolve is NOT opt-in — it
+ * signals a broken/incomplete install, so it warns LOUDLY instead of degrading silently to
+ * "Unrecognized step pattern". Errors thrown *inside* a present driver propagate — only a genuinely
+ * absent package is swallowed (resolve-then-require). Nothing here throws: the CLI must keep working
+ * (`--version`, `capability remove`) even when a driver is missing/broken.
  */
 import { createRequire } from 'module';
 import * as path from 'path';
@@ -25,6 +29,15 @@ import { LOCAL_DRIVERS, registerCoreCapability } from './builtins';
  */
 const EXTERNAL_DRIVERS = ['@sungen/driver-ui', '@sungen/driver-db', '@sungen/driver-api', '@sungen/driver-mobile'];
 
+/**
+ * Bundled (non-opt-in) drivers: shipped as a core dependency (`drivers.yaml` `bundled: true`), so the
+ * project gets them without `sungen capability add`. If one fails to resolve it is NOT a declined
+ * opt-in — it is a broken install (e.g. a dev workspace that skipped `npm install`, so the workspace
+ * symlink for the package is missing). Surface it LOUDLY: otherwise the entire UI step vocabulary is
+ * absent and every step silently compiles to "Unrecognized step pattern" with no clue why.
+ */
+const BUNDLED_DRIVERS = new Set(['@sungen/driver-ui']);
+
 function loadExternalDriver(name: string): void {
   // Resolve from the user's PROJECT first, then from core's own location. Opt-in drivers
   // (`sungen capability add db|api`) install into the PROJECT's node_modules — a globally-installed
@@ -51,7 +64,20 @@ function loadExternalDriver(name: string): void {
     }
     return; // found at this anchor (loaded or warned) — don't fall through to other anchors
   }
-  // not installed at any anchor — capabilities are opt-in, so skip silently
+  // Not resolvable at ANY anchor.
+  if (BUNDLED_DRIVERS.has(name)) {
+    // A bundled default is missing → broken install, not a declined opt-in. Warn loudly so the user
+    // sees the real cause instead of a wall of "Unrecognized step pattern".
+    console.warn(
+      `⚠ sungen: the bundled driver "${name}" could not be resolved — its step patterns are MISSING, ` +
+      `so steps will compile to "// Unrecognized step pattern".\n` +
+      `  This means the install is incomplete. Fix:\n` +
+      `    • in an app project:   run \`npm install\`\n` +
+      `    • in the sungen monorepo: run \`npm install\` at the repo ROOT (bootstraps the workspace symlink for ${name})`,
+    );
+    return;
+  }
+  // Opt-in driver not installed — capabilities are opt-in, so skip silently.
 }
 
 export function discoverAndRegisterCapabilities(): void {

package/src/cli/commands/add-flow.ts

@@ -7,6 +7,7 @@ export function registerAddFlowCommand(program: Command): void {
     .requiredOption('--flow <name>', 'Flow name')
     .option('-p, --path <path>', 'Starting page route path (e.g. /login)')
     .option('-d, --description <text>', 'Flow description')
+    .option('--reach <steps>', 'Mobile navigation recipe for the flow\'s starting screen: a ">"-separated list of nav steps from app launch, e.g. "tap [My Page] tab > tap [Settings] row". Scaffolded into the Background. Ignored (with a warning) on web projects.')
     .action(async (options) => {
       try {
         const { FlowManager } = require('../../orchestrator/flow-manager');
@@ -16,6 +17,7 @@ export function registerAddFlowCommand(program: Command): void {
           name: options.flow,
           path: options.path,
           description: options.description,
+          reach: options.reach,
         });
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);

package/src/cli/commands/add.ts

@@ -11,6 +11,8 @@ export function registerAddCommand(program: Command): void {
     .option('-c, --capture', 'Auto-capture a live-page screenshot to requirements/ui/ (requires --path)')
     .option('-f, --feature <name>', 'Add additional feature file to existing screen')
     .option('-d, --description <text>', 'Screen description')
+    .option('--platform <platform>', 'Optional per-OS tag: android | ios. Emits @platform:android/ios on the stub for OS-specific screens. Does NOT affect directory routing (always qa/screens/). Omit for cross-platform mobile or web.')
+    .option('--reach <steps>', 'Mobile navigation recipe (in-app web-path analog): a ">"-separated list of nav steps from app launch to this screen, e.g. "tap [My Page] tab > tap [Settings] row". Scaffolded into the Background; capture-mobile replays it. Ignored (with a warning) on web projects.')
     .option('--figma <url>', "Figma share URL — fetch design node and generate spec_figma.md + ui/*.png. QUOTE the URL ('...'): the '&' in Figma links backgrounds the shell otherwise.")
     .option('--refresh', 'Bypass Figma cache and re-fetch from API (use with --figma)')
     .option('--scale <n>', 'PNG export scale factor (default: 2)', parseFloat, 2)
@@ -38,6 +40,8 @@ export function registerAddCommand(program: Command): void {
             capture: options.capture,
             feature: options.feature,
             description: options.description,
+            platform: options.platform,
+            reach: options.reach,
           });
         } else {
           console.log(`Screen "${options.screen}" already exists — refreshing Figma assets only.`);

package/src/cli/commands/capability.ts

@@ -8,12 +8,34 @@ import {
 } from '../../harness/capability';
 import { buildPlan, MANUAL_REASONS } from '../../harness/capability-plan';
 import { adapterRegistry } from '../../generators/test-generator/adapters';
+import { emitMobileRuntime, installMobileDriver } from '../../orchestrator/mobile-runtime-scaffolder';
 
 /** The running CLI's (core) version — opt-in drivers install in lockstep with it (not `@latest`). */
 function coreVersion(): string {
   try { return require('../../../package.json').version || 'latest'; } catch { return 'latest'; }
 }
 
+/**
+ * Add `test:mobile` to the project's package.json scripts (if absent).
+ * Idempotent — skips if the script is already set.
+ * Returns true if the script was added, false if already present or no package.json.
+ */
+function addMobileScript(cwd: string): boolean {
+  const pkgPath = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgPath)) return false;
+  let pkg: Record<string, any>;
+  try {
+    pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+  } catch {
+    return false;
+  }
+  if (!pkg.scripts || typeof pkg.scripts !== 'object') pkg.scripts = {};
+  if (pkg.scripts['test:mobile']) return false;
+  pkg.scripts['test:mobile'] = 'wdio run wdio.conf.ts';
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n', 'utf-8');
+  return true;
+}
+
 /**
  * Verify a capability driver (db/api/…) installed into the PROJECT exposes the capability SPI entry
  * (`sungenDriver.register`). Resolved from the project's node_modules so it works with a globally
@@ -137,13 +159,33 @@ export function registerCapabilityCommand(program: Command): void {
     .command('add <driver>')
     .description('Enable a driver: install its package (if external) + record it in qa/capabilities.yaml')
     .option('--skip-install', 'Only record in the profile; do not run npm install')
-    .action((driver: string, o: { skipInstall?: boolean }) => {
+    .option('--force', 'Switch the project platform even if a different one is already set (sungen is one platform per project)')
+    .action((driver: string, o: { skipInstall?: boolean; force?: boolean }) => {
       try {
         const cwd = process.cwd();
         const meta = driverMeta(driver);
         if (!meta) {
           throw new Error(`Unknown driver "${driver}". Known: ${Object.keys(loadDriverCatalog()).join(', ')}`);
         }
+
+        // Guard: a platform driver (web/mobile) sets the project's SINGLE platform. If a DIFFERENT
+        // platform is already set, adding this one would silently FLIP it (e.g. web → mobile) and make
+        // the existing feature files compile for the wrong runtime. Refuse unless --force, and point at
+        // the correct path for a web+mobile repo (two separate project folders).
+        const current = readCapabilities(cwd);
+        if (meta.kind === 'platform' && current.platform && current.platform !== driver && !o.force) {
+          const initHint = driver === 'mobile' ? ' --mobile --app-package <pkg>' : ' --base-url <url>';
+          console.error(
+            `✗ This project's platform is already "${current.platform}". Adding "${driver}" would SWITCH it to "${driver}".\n` +
+            `  sungen is ONE platform per project — this is NOT "${current.platform} + ${driver}" together.\n` +
+            `  • Want BOTH web and mobile? Keep this project and create a SEPARATE folder for ${driver}:\n` +
+            `      sungen init ${driver}-tests${initHint}\n` +
+            `  • Really converting ${current.platform} → ${driver}? Re-run with --force\n` +
+            `      (your existing ${current.platform} feature files would then compile for ${driver}).`,
+          );
+          process.exit(1);
+        }
+
         const adapterName = meta.adapter || meta.id;
         const bundled = adapterRegistry.hasAdapter(adapterName); // e.g. `web` is bundled in Phase 2a
 
@@ -176,6 +218,27 @@ export function registerCapabilityCommand(program: Command): void {
         const platform = meta.kind === 'platform' ? driver : profile.platform;
         writeCapabilities(cwd, { platform, enabled });
         console.log(`✓ capability "${driver}" enabled${meta.kind === 'platform' ? ` (platform=${driver})` : ''}.`);
+
+        // Emit the mobile runtime harness when the mobile platform driver is added.
+        // Idempotent: emitMobileRuntime skips files that already exist.
+        if (platform === 'mobile') {
+          console.log('');
+          console.log('🔧 Emitting mobile runtime harness...');
+          const result = emitMobileRuntime(cwd, { enabled: true });
+          for (const f of result.created) console.log(`  ✓ created  ${f}`);
+          for (const f of result.skipped) console.log(`  – skipped  ${f} (already exists)`);
+
+          // Add test:mobile script to package.json (idempotent)
+          if (addMobileScript(cwd)) {
+            console.log('  ✓ created  package.json scripts[test:mobile]');
+          } else {
+            console.log('  – skipped  package.json scripts[test:mobile] (already exists)');
+          }
+
+          // Best-effort driver install — non-fatal so capability add still succeeds offline.
+          installMobileDriver(cwd);
+        }
+
         console.log('');
       } catch (e) {
         console.error('Error:', e instanceof Error ? e.message : e);

package/src/cli/commands/delivery.ts

@@ -21,6 +21,7 @@ import {
   writeCsv,
 } from '../../exporters/csv-exporter';
 import { renderXlsxMultiSheet, writeXlsx, buildApiDetailRows, addApiDetailSheet } from '../../exporters/xlsx-exporter';
+import { resolvePlatformAppId } from '../../exporters/mobile-app-id';
 import { EnvironmentInfo, PreflightCheck, ScreenSummary, TestCaseRow, ApiCatalogEntry } from '../../exporters/types';
 
 const COLOR = {
@@ -394,6 +395,40 @@ function getEnvironment(cwd: string): EnvironmentInfo {
   return { baseURL, projectName, executor };
 }
 
+/**
+ * True when this is a mobile project (`platform: mobile` in qa/capabilities.yaml).
+ * Mobile results are written PER-OS (`<feature>-test-result.android|ios.json`) —
+ * android/ios are separate platform runs, not locales of one run — so delivery
+ * emits one csv+xlsx per OS and skips the (empty/misleading) base aggregate.
+ */
+function isMobileProject(cwd: string): boolean {
+  try {
+    const p = path.join(cwd, 'qa', 'capabilities.yaml');
+    if (!fs.existsSync(p)) return false;
+    const parsed = parseYaml(fs.readFileSync(p, 'utf-8')) as { platform?: string } | null;
+    return parsed?.platform === 'mobile';
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Remove a stale base (no-suffix) deliverable pair for a feature. Used in mobile
+ * per-OS mode where the base `<feature>-testcases.{csv,xlsx}` is not produced —
+ * deletes leftovers from a previous (pre-per-OS) delivery so the folder only
+ * holds the per-OS files.
+ */
+function removeBaseDeliverables(cwd: string, featureBaseName: string): void {
+  const dir = path.join(cwd, 'qa', 'deliverables');
+  for (const ext of ['csv', 'xlsx']) {
+    const f = path.join(dir, `${featureBaseName}-testcases.${ext}`);
+    if (fs.existsSync(f)) {
+      fs.rmSync(f);
+      log(`  ${COLOR.gray}removed stale base deliverable ${path.relative(cwd, f)} (mobile → per-OS files)${COLOR.reset}`);
+    }
+  }
+}
+
 // ----------------------------------------------------------------------------
 // Per-screen export
 // ----------------------------------------------------------------------------
@@ -440,10 +475,15 @@ async function exportTarget(
     //                   one CSV per locale (CSV has no sheet concept).
     //     <2 variants → single-sheet XLSX with the canonical 'Testcases' sheet.
     if (explicitEnv) {
+      // Mobile: a stale base (no-suffix) pair from a pre-per-OS run is misleading
+      // sitting next to the env-suffixed file — drop it.
+      if (isMobileProject(cwd)) removeBaseDeliverables(cwd, target.featureBaseName);
       const rows = buildTestCaseRows({
         screen: label,
         featureName: feature.featureName,
-        featurePath,
+        // OS-precise env column: a mobile dual-id Path resolves to just the
+        // android package / ios bundle id for SUNGEN_ENV=android|ios.
+        featurePath: resolvePlatformAppId(featurePath, explicitEnv),
         merged,
         testData: loadTestData(testDataFile),
         results: resolveResultsPath(cwd, target) ? loadPlaywrightReport(resolveResultsPath(cwd, target)!) : null,
@@ -470,6 +510,50 @@ async function exportTarget(
     }
 
     const variants = discoverLocaleVariants(cwd, target);
+
+    // Mobile: emit ONE deliverable per OS (csv + xlsx), each from its own
+    // `<feature>-test-result.<os>.json`. Android/iOS are SEPARATE platform runs,
+    // not locales of one run, so a single aggregated base workbook is empty &
+    // misleading — produce per-OS files and skip the base (issue: per-OS delivery).
+    if (isMobileProject(cwd)) {
+      // OS runs = variants whose first dot-segment is android|ios (incl. env-suffixed
+      // android.staging / ios.ja). A bare locale variant is NOT an OS run and stays on
+      // the standard aggregation path below.
+      const osVariants = variants.filter((v) => !!v.resultsPath && /^(android|ios)(\.|$)/.test(v.locale));
+      if (osVariants.length > 0) {
+        removeBaseDeliverables(cwd, target.featureBaseName); // drop any stale no-suffix pair
+        let mobileSummary: ScreenSummary | null = null;
+        for (const variant of osVariants) {
+          const variantRows = buildTestCaseRows({
+            screen: label,
+            featureName: feature.featureName,
+            featurePath: resolvePlatformAppId(featurePath, variant.locale), // OS-precise app id
+            merged,
+            testData: loadTestData(testDataFile, variant.locale || null),
+            results: variant.resultsPath ? loadPlaywrightReport(variant.resultsPath) : null,
+            env,
+            selectorKeyMap,
+          });
+          const csv = renderCsv(buildSummary(label, variantRows, ''), variantRows, specLink);
+          const csvPath = writeCsv(cwd, target.featureBaseName, csv, variant.locale);
+          const autoRows = variantRows.filter((r) => r.testcaseType !== 'Manual');
+          const manualRows = variantRows.filter((r) => r.testcaseType === 'Manual');
+          const wb = renderXlsxMultiSheet([
+            { sheetName: 'Auto', summary: buildSummary(label, autoRows, ''), rows: autoRows, specLink },
+            { sheetName: 'Manual', summary: buildSummary(label, manualRows, ''), rows: manualRows, specLink },
+          ]);
+          await writeXlsx(cwd, target.featureBaseName, wb, variant.locale);
+          const s = buildSummary(label, variantRows, path.relative(cwd, csvPath));
+          // Prefer the android line for the single summary-table row (deterministic);
+          // startsWith covers env-suffixed android.staging etc.
+          if (!mobileSummary || variant.locale.startsWith('android')) mobileSummary = s;
+        }
+        return mobileSummary;
+      }
+      // Mobile but no per-OS results yet → fall through to the base export below
+      // so the test CASES still deliver (execution columns empty/pending).
+    }
+
     let primarySummary: ScreenSummary | null = null;
     let primaryCsvPath = '';
     // XLSX is split by automation type: an "Auto" sheet (automatable TCs, results differ per
@@ -487,7 +571,10 @@ async function exportTarget(
       const variantRows = buildTestCaseRows({
         screen: label,
         featureName: feature.featureName,
-        featurePath,
+        // No-op for web (URL Path); for a mobile fall-through (a no-suffix result
+        // json) this collapses the dual-id to the android package so the combined
+        // dual-id never leaks into the env column.
+        featurePath: resolvePlatformAppId(featurePath, variant.locale),
         merged,
         testData: variantTestData,
         results: variantResults,

package/src/cli/commands/eval.ts

@@ -5,8 +5,8 @@ export function registerEvalCommand(program: Command): void {
   program
     .command('eval')
     .description('Eval harness: quality checks on Sungen\'s own skills/instructions (dev/CI)')
-    .option('--skills', 'Static skill-lint: frontmatter, line budget, claude↔github sync, registration')
-    .option('--dir <path>', 'Templates dir to lint (default: bundled ai-instructions)')
+    .option('--skills', 'Static skill-lint: frontmatter, line budget, cap-fence validity')
+    .option('--dir <path>', 'Single-source dir to lint (default: bundled ai-src)')
     .option('--json', 'Output the raw findings JSON')
     .action((options) => {
       try {
@@ -16,7 +16,7 @@ export function registerEvalCommand(program: Command): void {
         if (options.json) { console.log(JSON.stringify(r, null, 2)); process.exit(r.errors > 0 ? 2 : 0); }
         console.log('');
         console.log(`━━━ Skill-lint: ${r.checked} skill template(s) ━━━`);
-        if (!r.findings.length) console.log('  ✓ all skills pass (frontmatter · line-budget · variant-sync · registration)');
+        if (!r.findings.length) console.log('  ✓ all skills pass (frontmatter · line-budget · cap-fence)');
         for (const f of r.findings) console.log(`  ${f.level === 'error' ? '✗' : '⚠'} [${f.rule}] ${f.file} — ${f.detail}`);
         console.log('');
         process.exit(r.errors > 0 ? 2 : 0);

package/src/cli/commands/gate.ts

@@ -0,0 +1,44 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runGate, renderGate, GatePhase } from '../../harness/journey';
+
+function findScreenDir(name: string): string | null {
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+const PHASES: GatePhase[] = ['create', 'run', 'deliver'];
+
+export function registerGateCommand(program: Command): void {
+  program
+    .command('gate')
+    .description('Inter-phase HALT gate (#381): a phase boundary passes only when its required obligations are satisfied or explicitly waived. Exit 2 = HALT (no silent bad output crosses the boundary).')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('-p, --phase <phase>', `Phase boundary: ${PHASES.join(' | ')}`)
+    .option('--json', 'Output the raw verdict')
+    .action((options) => {
+      try {
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name>');
+        const phase = options.phase as GatePhase;
+        if (!PHASES.includes(phase)) throw new Error(`Provide --phase <${PHASES.join('|')}>`);
+        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const verdict = runGate(process.cwd(), name, phase);
+        if (options.json) console.log(JSON.stringify(verdict, null, 2));
+        else console.log(renderGate(verdict));
+
+        // Exit 2 on HALT — usable in CI / the orchestration loop to block the next phase.
+        process.exit(verdict.status === 'halt' ? 2 : 0);
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/generate.ts

@@ -219,7 +219,8 @@ export function registerGenerateCommand(program: Command): void {
           for (const w of ddWarnings.slice(0, 20)) console.log(`   ${w.scenario ? w.scenario + ': ' : ''}${w.message}`);
         }
 
-        console.log(`Next step: npx playwright test --ui\n`);
+        const nextStep = platform === 'mobile' ? 'npm run test:mobile' : 'npx playwright test --ui';
+        console.log(`Next step: ${nextStep}\n`);
       } catch (error) {
         console.error('Error:', error instanceof Error ? error.message : error);
         process.exit(1);

package/src/cli/commands/init.ts

@@ -4,11 +4,58 @@ export function registerInitCommand(program: Command): void {
   program
     .command('init [projectName]')
     .description('Initialize Sungen project (optionally create and initialize in a new project folder)')
-    .requiredOption('--base-url <url>', 'Base URL for Playwright tests (e.g. https://your-app.com)')
-    .action(async (projectName: string | undefined, options: { baseUrl: string }) => {
+    .option('--base-url <url>', 'Base URL for Playwright (web) tests (e.g. https://your-app.com). Required for web projects (omit only with --mobile)')
+    .option('--mobile', 'Mobile project (Appium/WebdriverIO): scaffold ONLY the mobile harness — no Playwright config, no Chromium download, no --base-url needed')
+    .option('--app-package <pkg>', 'Android appPackage for mobile (e.g. com.example.app). Used with --mobile')
+    .option('--app-activity <activity>', 'Android appActivity for mobile (e.g. com.example.app.MainActivity). OPTIONAL — omit to let Appium auto-resolve the launcher activity from --app-package; pass it only to pin a non-standard launcher. Used with --mobile')
+    .option('--app-apk <path>', 'Path to an .apk to install & run for mobile (alternative to package/activity). Used with --mobile')
+    .option('--android-udid <udid>', 'Default Android device/emulator UDID for mobile (default: emulator-5554)')
+    .option('--ios-bundle-id <id>', 'iOS bundle id for mobile (e.g. com.example.app.dev) — default app when MOBILE_PLATFORM=ios|both. Used with --mobile')
+    .option('--ios-device <name>', "iOS Simulator device name for mobile (default: 'iPhone 16'). Used with --mobile")
+    .option('--ios-version <ver>', "iOS Simulator platform version for mobile (default: '18.0'). Used with --mobile")
+    .option(
+      '--assistant <name>',
+      'AI assistant to install for: claude | copilot | codex | all (repeatable). Default: claude',
+      (val: string, acc: string[]) => { acc.push(val); return acc; },
+      [] as string[],
+    )
+    .option('--force', 'Overwrite user config files (CLAUDE.md, AGENTS.md, copilot-instructions.md)', false)
+    .action(async (projectName: string | undefined, options: {
+      baseUrl?: string;
+      mobile?: boolean;
+      appPackage?: string;
+      appActivity?: string;
+      appApk?: string;
+      androidUdid?: string;
+      iosBundleId?: string;
+      iosDevice?: string;
+      iosVersion?: string;
+      assistant?: string[];
+      force?: boolean;
+    }) => {
       try {
+        // `--mobile` = a mobile-only project: no web scaffolding, no base URL needed.
+        // Plain `init` = a web project and requires `--base-url`.
+        const mobile = !!options.mobile;
+        if (!mobile && !options.baseUrl) {
+          console.error('❌ --base-url is required for a web project. For a mobile project pass --mobile (no base URL needed).');
+          process.exit(1);
+        }
+        const { resolveAssistants } = require('../../orchestrator/ai-skills/resolve-assistants');
         const { ProjectInitializer } = require('../../orchestrator/project-initializer');
-        const initializer = new ProjectInitializer(options.baseUrl);
+        const initializer = new ProjectInitializer(options.baseUrl || '', {
+          agents: resolveAssistants(options.assistant),
+          force: options.force ?? false,
+          enabled: mobile,
+          mobileOnly: mobile,
+          appPackage: options.appPackage,
+          appActivity: options.appActivity,
+          appApk: options.appApk,
+          androidUdid: options.androidUdid,
+          iosBundleId: options.iosBundleId,
+          iosDevice: options.iosDevice,
+          iosVersion: options.iosVersion,
+        });
         await initializer.initialize(projectName);
       } catch (error) {
         console.error('❌ Init failed:', error);

package/src/cli/commands/journey.ts

@@ -0,0 +1,72 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs';
+import { runJourney, waive, signoff, renderJourneyBoard, rollupJourney, renderRollupBoard } from '../../harness/journey';
+import { reportSlug } from '../../harness/unit-paths';
+
+function findScreenDir(name: string): string | null {
+  const candidates = [
+    path.join(process.cwd(), 'qa', 'screens', name),
+    path.join(process.cwd(), 'qa', 'flows', name),
+    path.join(process.cwd(), 'qa', 'api', name),
+  ];
+  for (const c of candidates) if (fs.existsSync(c)) return c;
+  return null;
+}
+
+export function registerJourneyCommand(program: Command): void {
+  program
+    .command('journey')
+    .description('Durable "you are here" board (#381): obligations + what-to-review + next, synthesised read-only from the audit report + ledger already on disk.')
+    .option('-s, --screen <name>', 'Screen / flow / api unit name')
+    .option('--all', 'Roll up every unit (screens + flows + api) into one board — the serial review surface for multi-unit fan-out')
+    .option('--waive <obligation>', 'Waive an obligation (e.g. OB-coverage) — requires --reason')
+    .option('--reason <text>', 'The reason a waived obligation is acceptable (mandatory with --waive)')
+    .option('--signoff', 'Sign off the review queue — the single human gate (allowed only when every other obligation is satisfied/waived)')
+    .option('--by <name>', 'Who is signing off (recorded with --signoff)')
+    .option('--json', 'Output the raw JSON report')
+    .action((options) => {
+      try {
+        if (options.all) {
+          const rows = rollupJourney(process.cwd());
+          const board = renderRollupBoard(rows);
+          const outDir = path.join(process.cwd(), '.sungen', 'journey');
+          fs.mkdirSync(outDir, { recursive: true });
+          fs.writeFileSync(path.join(outDir, '_rollup.json'), JSON.stringify(rows, null, 2), 'utf-8');
+          fs.writeFileSync(path.join(outDir, '_rollup.board.md'), board, 'utf-8');
+          if (options.json) console.log(JSON.stringify(rows, null, 2));
+          else { console.log(''); console.log(board); console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, '_rollup.board.md'))}`); console.log(''); }
+          return;
+        }
+
+        const name = options.screen;
+        if (!name) throw new Error('Provide --screen <name> (or --all for the roll-up)');
+        if (!findScreenDir(name)) throw new Error(`Not found: qa/screens/${name}, qa/flows/${name}, or qa/api/${name}`);
+
+        const report = options.waive
+          ? waive(process.cwd(), name, options.waive, options.reason || '')
+          : options.signoff
+            ? signoff(process.cwd(), name, options.by)
+            : runJourney(process.cwd(), name);
+
+        const outDir = path.join(process.cwd(), '.sungen', 'journey');
+        fs.mkdirSync(outDir, { recursive: true });
+        const slug = reportSlug(name);
+        fs.writeFileSync(path.join(outDir, `${slug}.json`), JSON.stringify(report, null, 2), 'utf-8');
+        const board = renderJourneyBoard(report);
+        fs.writeFileSync(path.join(outDir, `${slug}.board.md`), board, 'utf-8');
+
+        if (options.json) {
+          console.log(JSON.stringify(report, null, 2));
+        } else {
+          console.log('');
+          console.log(board);
+          console.log(`  Board: ${path.relative(process.cwd(), path.join(outDir, `${slug}.board.md`))}`);
+          console.log('');
+        }
+      } catch (error) {
+        console.error('Error:', error instanceof Error ? error.message : error);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/update.ts

@@ -30,6 +30,13 @@ export function registerUpdateCommand(program: Command): void {
       'Reinstall @sun-asterisk/sungen (stable by default, --beta for prerelease) + refresh AI rules, commands, skills',
     )
     .option('--dry-run', 'Show what would be updated without making changes')
+    .option(
+      '--assistant <name>',
+      'AI assistant to install for: claude | copilot | codex | all (repeatable). Default: claude',
+      (val: string, acc: string[]) => { acc.push(val); return acc; },
+      [] as string[],
+    )
+    .option('--force', 'Overwrite user config files (CLAUDE.md, AGENTS.md, copilot-instructions.md)', false)
     .option(
       '--beta',
       'Switch to the BETA channel (installs @beta — prerelease builds for testing)',
@@ -44,7 +51,7 @@ export function registerUpdateCommand(program: Command): void {
       'Skip the npm install step (refresh project AI assets only)',
       false,
     )
-    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean }) => {
+    .action(async (options: { dryRun?: boolean; beta?: boolean; tag?: string; skipNpmInstall?: boolean; assistant?: string[]; force?: boolean }) => {
       try {
         const skipNpm =
           Boolean(options.skipNpmInstall) || process.env[SKIP_NPM_ENV] === '1';
@@ -56,13 +63,14 @@ export function registerUpdateCommand(program: Command): void {
         if (!skipNpm) {
           reinstallSungen(channel);
           printCurrentVersion(channel);
-          reExecUpdateForAIAssets(options.dryRun ?? false);
+          reExecUpdateForAIAssets(options.dryRun ?? false, options.assistant ?? [], options.force ?? false);
           return;
         }
 
+        const { resolveAssistants } = require('../../orchestrator/ai-skills/resolve-assistants');
         const { AIRulesUpdater } = require('../../orchestrator/ai-rules-updater');
         const updater = new AIRulesUpdater(process.cwd());
-        await updater.update(options.dryRun ?? false);
+        await updater.update(options.dryRun ?? false, { agents: resolveAssistants(options.assistant), force: options.force ?? false });
       } catch (error) {
         console.error('❌ Update failed:', error);
         process.exit(1);
@@ -96,9 +104,11 @@ function printCurrentVersion(channel: string): void {
   console.log('');
 }
 
-function reExecUpdateForAIAssets(dryRun: boolean): void {
+function reExecUpdateForAIAssets(dryRun: boolean, assistants: string[], force: boolean): void {
   const args = ['update'];
   if (dryRun) args.push('--dry-run');
+  if (force) args.push('--force');
+  for (const a of assistants) args.push('--assistant', a);
 
   const result = spawnSync('sungen', args, {
     stdio: 'inherit',

package/src/cli/index.ts

@@ -16,6 +16,8 @@ import { registerAddFlowCommand } from './commands/add-flow';
 import { registerDashboardCommand } from './commands/dashboard';
 import { registerAuditCommand } from './commands/audit';
 import { registerDepthLintCommand } from './commands/depth-lint';
+import { registerJourneyCommand } from './commands/journey';
+import { registerGateCommand } from './commands/gate';
 import { registerIngestCommand } from './commands/ingest';
 import { registerEvalCommand } from './commands/eval';
 import { registerManifestCommand } from './commands/manifest';
@@ -59,6 +61,8 @@ async function main() {
   registerDashboardCommand(program);
   registerAuditCommand(program);
   registerDepthLintCommand(program);
+  registerJourneyCommand(program);
+  registerGateCommand(program);
   registerManifestCommand(program);
   registerLedgerCommand(program);
   registerFeedbackCommand(program);

package/src/dashboard/snapshot-builder.ts

@@ -22,6 +22,7 @@ import { loadSelectorKeyMap } from '../exporters/selector-key-resolver';
 import { loadPlaywrightReport } from '../exporters/playwright-report-parser';
 import { mergeFeatureAndSpec } from '../exporters/scenario-merger';
 import { buildScreenSnapshot } from '../exporters/json-exporter';
+import { resolvePlatformAppId } from '../exporters/mobile-app-id';
 import { getPackageVersion } from '../exporters/package-info';
 import { EnvironmentInfo } from '../exporters/types';
 import {
@@ -167,6 +168,12 @@ function buildOneFeature(
   // Discover locale variants by scanning <feature>-test-result*.json files.
   // Always includes base ('') as the first entry, even if its results file
   // is missing — UI still needs to render the feature.
+  // NOTE (mobile): for a `platform: mobile` project the "locale" variants are
+  // actually the per-OS runs (android / ios) — the dashboard reuses the locale
+  // switcher to surface them as tabs. The env column per tab is OS-precise (see
+  // resolvePlatformAppId below), but the top-level featurePath (base variant)
+  // defaults to the Android id. Delivery has a dedicated per-OS path; aligning the
+  // dashboard onto a distinct "platform" axis is a possible follow-up.
   const variants = discoverLocaleVariants(genBase, featureBaseName);
 
   // Build per-locale ScreenSnapshot, then collect into FeatureSnapshot.locales[].
@@ -185,7 +192,9 @@ function buildOneFeature(
       screen: featureBaseName,
       isFlow: target.isFlow,
       featureName: feature.featureName,
-      featurePath,
+      // OS-precise env column: a mobile dual-id Path resolves to just the android
+      // package / ios bundle id for the android|ios result variant.
+      featurePath: resolvePlatformAppId(featurePath, variant.locale),
       specLink,
       merged,
       testData,

package/src/exporters/csv-exporter.ts

@@ -202,7 +202,9 @@ export function buildSummary(screen: string, rows: TestCaseRow[], outputFile: st
 function formatEnv(baseURL: string, featurePath: string | undefined, projectName: string): string {
   const base = (baseURL || '').replace(/\/+$/, '');
   const p = (featurePath || '').replace(/^\/+/, '');
-  const url = p ? `${base}/${p}` : base;
+  // Join with '/' only when there is a baseURL (web). For mobile baseURL is empty
+  // and `p` is an app id (e.g. com.kngroup.media.converter) — emit it bare, no '/'.
+  const url = base && p ? `${base}/${p}` : (p || base);
   return `${url} (${projectName})`;
 }