@fiodos/cli 0.1.4 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.4",
+  "version": "0.1.9",
   "description": "Fiodos CLI — analyzes your app's source code and generates the in-app voice-agent manifest, then wires the orb. Powers `npx @fiodos/cli analyze`.",
   "type": "commonjs",
   "bin": {

package/src/aiAnalyze.js

@@ -96,9 +96,9 @@ const PLATFORM_GUIDES = {
     appKindLabel: 'a web app (React, Next.js, Vite, react-router, or similar)',
     screenWord: 'page/view/route',
     routeHintLine:
-      'No reliable static route list is available for web apps, so infer routes/views from the router setup, page/route components, and navigation calls (react-router <Route>, Next.js pages, navigate()/<Link>). Routes you propose are NOT statically verified, so only include ones you can actually see in the code.',
+      'No reliable static route list is available for web apps, so infer routes/views from the router setup, page/route components, and navigation calls (react-router <Route>, Next.js pages, navigate()/<Link>). Routes you propose are NOT statically verified, so only include ones you can actually see in the code below.',
     actionHintLine:
-      'Actions are functions wired to UI: handlers inside components, store/context actions (Zustand, Redux, React Context), or service functions. Set "handler" to that real function name exactly.',
+      'Actions are functions wired to UI IN THE SOURCE FILES PROVIDED BELOW: handlers inside components, store/context actions (Zustand, Redux, React Context), or service functions. Set "handler" to that real function name exactly. CRITICAL: the manifest is for THIS web deployment only — do NOT include routes or actions from mobile/native code that is not in the file list (even if you infer it exists elsewhere in the monorepo).',
   },
   mobile: {
     appKindLabel: 'a mobile app (Expo / React Native)',

package/src/ast.js

@@ -73,8 +73,42 @@ function extractFromFile(filePath, appRoot) {
     imports: [],
     linkingCalls: [],
     defaultExportName: null,
+    // Internal navigation destinations referenced in this file (route strings):
+    // <Link href|to>, <a href>, router.push/replace, navigate(), redirect().
+    // Used by the surface-scoring layer to build the navigation reachability
+    // graph (which screens are reachable from the deployed entry). External
+    // links (http, mailto, tel, #anchors) are excluded.
+    navTargets: [],
+    // True when this file DEFINES the app's route table (react-router <Route>,
+    // createBrowserRouter, Angular RouterModule.forRoot/provideRouter, Vue
+    // createRouter). Such a file's links act as GLOBAL navigation (available
+    // from any screen), unlike a per-section sidebar.
+    routeHost: false,
+    // Soft signals that this file sits behind authentication (used ONLY to keep
+    // an orphaned cluster ACTIVE — never to disable). Identifiers/paths that
+    // commonly indicate an auth gate.
+    authSignals: [],
   };
 
+  // Collect an internal route string if it looks like an in-app path.
+  function pushNavTarget(value) {
+    if (!value || typeof value !== 'string') return;
+    const v = value.trim();
+    if (!v) return;
+    // Only same-app paths. Drop external/protocol/anchor/empty targets.
+    if (!v.startsWith('/')) return;
+    if (v.startsWith('//')) return; // protocol-relative external
+    out.navTargets.push(v);
+  }
+
+  // GATING constructs only (a redirect/block when unauthenticated) — NOT mere
+  // session reading (useUser/useSession): reading the user does not gate access,
+  // and counting it would wrongly protect public-but-orphaned pages from being
+  // disabled. Used solely to KEEP an orphaned cluster active (SaaS guard).
+  const AUTH_HINT_RE =
+    /(requireAuth|withAuth|ProtectedRoute|RequireAuth|AuthGuard|authGuard|ensureAuth|canActivate|redirectToLogin|RedirectToSignIn|SignedOut)/;
+  const AUTH_PATH_RE = /\/(login|signin|sign-in|sign_in)\b/i;
+
   function jsxAttr(attrs, names) {
     for (const attr of attrs.properties) {
       if (ts.isJsxAttribute(attr) && names.includes(attr.name.getText())) {
@@ -118,6 +152,10 @@ function extractFromFile(filePath, appRoot) {
         }
       }
       out.imports.push({ from: node.moduleSpecifier.text, names });
+      for (const n of names) {
+        if (AUTH_HINT_RE.test(n)) out.authSignals.push(n);
+      }
+      if (AUTH_PATH_RE.test(node.moduleSpecifier.text)) out.authSignals.push(node.moduleSpecifier.text);
     }
 
     // default export name (screen component)
@@ -157,6 +195,34 @@ function extractFromFile(filePath, appRoot) {
           }
         }
         out.navCalls.push({ verb, target, file: rel });
+        if (verb !== 'back' && verb !== 'goBack') pushNavTarget(target);
+      }
+
+      // Next.js / framework redirects: redirect('/x'), permanentRedirect('/x').
+      if (/^(redirect|permanentRedirect)$/.test(exprText) && node.arguments[0]) {
+        pushNavTarget(literalText(node.arguments[0]));
+      }
+      // react-router imperative: navigate('/x') / history.push('/x').
+      if (/(^|\.)navigate$/.test(exprText) && node.arguments[0]) {
+        pushNavTarget(literalText(node.arguments[0]));
+      }
+      // Bare push('/x') from a destructured useRouter()/useNavigate() hook.
+      if (exprText === 'push' && node.arguments[0]) {
+        pushNavTarget(literalText(node.arguments[0]));
+      }
+      // Route-table definitions → this file's links are GLOBAL navigation.
+      if (/^(createBrowserRouter|createHashRouter|createMemoryRouter|createRouter)$/.test(exprText)) {
+        out.routeHost = true;
+      }
+      if (/\.(forRoot|forChild)$/.test(exprText) || /^provideRouter$/.test(exprText)) {
+        out.routeHost = true;
+      }
+
+      // Auth gate by call: redirect('/login') etc. is captured above as a nav
+      // target; also flag it as an auth signal when the path looks like a gate.
+      if (/^(redirect|replace|push)$/.test(exprText.split('.').pop() || '') && node.arguments[0]) {
+        const t = literalText(node.arguments[0]);
+        if (t && AUTH_PATH_RE.test(t)) out.authSignals.push(t);
       }
 
       // Alert.alert(title, message?, buttons?)
@@ -217,6 +283,12 @@ function extractFromFile(filePath, appRoot) {
     if (ts.isJsxSelfClosingElement(node) || ts.isJsxOpeningElement(node)) {
       const tag = node.tagName.getText();
       const attrs = node.attributes;
+      // Any element carrying an internal route via href/to (next/link <Link>,
+      // <a href>, react-router <Link to>/<Navigate to>/<Redirect to>).
+      const linkTarget = jsxAttr(attrs, ['href', 'to']);
+      if (linkTarget) pushNavTarget(linkTarget);
+      // react-router <Route> table → global navigation host.
+      if (tag === 'Route') out.routeHost = true;
       if (/Button/i.test(tag) || tag === 'TouchableOpacity' || tag === 'Pressable') {
         const title = jsxAttr(attrs, ['title', 'label', 'accessibilityLabel']);
         const handler = jsxAttrHandlerName(attrs, ['onPress']);

package/src/collect.js

@@ -21,7 +21,12 @@ const path = require('path');
 const PROFILES = {
   web: {
     exts: ['.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte'],
-    skipDirs: ['node_modules', 'assets', '.git', 'dist', 'build', '.expo', 'android', 'ios', 'coverage', '.next', 'web-build'],
+    skipDirs: [
+      'node_modules', 'assets', '.git', 'dist', 'build', '.expo', 'android', 'ios', 'coverage',
+      '.next', 'web-build',
+      // Monorepo siblings: never mix mobile/native code into a web analysis.
+      'mobile', 'native', 'flutter', 'react-native', 'expo',
+    ],
   },
   mobile: {
     exts: ['.ts', '.tsx', '.js', '.jsx'],

package/src/graph.js

@@ -157,4 +157,4 @@ function mapScreens(routes, graph) {
   return { screens, stores };
 }
 
-module.exports = { buildGraph, mapScreens };
+module.exports = { buildGraph, mapScreens, closure };

package/src/index.js

@@ -31,7 +31,8 @@
  *   After analysis, a web target is OFFERED automatic wiring of <FiodosAgent/>
  *   into the app's root layout. It asks before editing your code; on "no" (or a
  *   non-interactive shell) it prints the ready-to-paste snippet instead.
- *     --yes          accept the wiring/env without the prompt (CI / express)
+ *     --yes          accept orb/handler wiring without prompts (CI / express)
+ *     --write-env-yes write the API key to .env without asking (CI only)
  *     --no-wire      skip wiring entirely (analysis/publish unaffected)
  *     --no-write-env skip the offer to align the app's .env with the published
  *                    key/URL (see below)
@@ -39,10 +40,11 @@
  * Avoiding the silent "orb fetches the wrong backend" failure:
  *   After --publish the CLI (1) re-fetches the manifest with the SAME key+URL to
  *   confirm the orb will find it, printing the exact key/URL your app must use,
- *   and (2) on web, OFFERS to write that key/URL into the app's env file
- *   (.env.local for Next, .env for Vite) so the runtime matches what you
- *   published. It never overwrites a differing value silently — it warns and
- *   asks first. Disable with --no-write-env.
+ *   and (2) on web, ASKS at the END whether to write that key/URL into the
+ *   app's env file (.env.local for Next, .env for Vite). If you say yes it
+ *   writes; if you say no it prints the exact file path and lines to add.
+ *   Independent of --yes (which only skips orb/handler prompts). CI: --write-env-yes.
+ *   Disable entirely with --no-write-env.
  *
  * AI key — HYBRID model:
  *   DEFAULT (hosted): the AI analysis runs on the Fiodos backend with FIODOS'S
@@ -88,11 +90,13 @@ loadEnv();
 
 const { scanRoutes } = require('./routes');
 const { collectFiles } = require('./collect');
+const { resolveAnalysisRoot } = require('./resolveAnalysisRoot');
 const { analyzeWithAI, correctActionWiring, DEFAULT_MODEL, resolveModel } = require('./aiAnalyze');
 const { verifyManifest } = require('./verify');
 const { wireWebOrb, reportWireResult } = require('./wireWeb');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
-const { offerWriteEnv } = require('./writeEnv');
+const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
+const { scoreSurface } = require('./scoreSurface');
 
 function arg(flag, fallback) {
   const i = process.argv.indexOf(flag);
@@ -158,24 +162,49 @@ async function withSpinner(label, work) {
   const orbFrames = ['◴', '◷', '◶', '◵'];
   const brailleFrames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   const { blue, cyan, dim, reset } = fyodosTermColors();
+  let currentLabel = label;
   let frame = 0;
+  let id = null;
   const start = Date.now();
-  const tick = () => {
+
+  const render = () => {
     const sec = Math.floor((Date.now() - start) / 1000);
     const orb = orbFrames[frame % orbFrames.length];
     const tail = brailleFrames[frame % brailleFrames.length];
     const line =
-      `${cyan}${orb}${reset} ${blue}Fiodos${reset} ${dim}${tail}${reset}  ${label}… ${dim}${sec}s${reset}`;
+      `${cyan}${orb}${reset} ${blue}Fiodos${reset} ${dim}${tail}${reset}  ${currentLabel}… ${dim}${sec}s${reset}`;
     process.stderr.write(`\r\x1b[K${line}`);
     frame += 1;
   };
-  tick();
-  const id = setInterval(tick, 140);
+
+  const clearLine = () => process.stderr.write('\r\x1b[K');
+
+  const startSpinner = () => {
+    render();
+    id = setInterval(render, 140);
+  };
+
+  const pause = () => {
+    if (id) {
+      clearInterval(id);
+      id = null;
+      clearLine();
+    }
+  };
+
+  const resume = () => {
+    if (!id) startSpinner();
+  };
+
+  const setLabel = (next) => {
+    currentLabel = next;
+  };
+
+  startSpinner();
   try {
-    return await work();
+    return await work({ setLabel, pause, resume });
   } finally {
-    clearInterval(id);
-    process.stderr.write('\r\x1b[K');
+    pause();
   }
 }
 
@@ -187,7 +216,8 @@ async function main() {
   // Default output dir lives in the OS temp dir, NOT inside the installed
   // package (when run via npx, __dirname is under node_modules and writing
   // there pollutes the package). Operators can still override with --out.
-  const safeName = path.basename(path.resolve(appRoot)).replace(/[^a-z0-9_-]/gi, '_') || 'app';
+  const inputRoot = path.resolve(appRoot);
+  const safeName = path.basename(inputRoot).replace(/[^a-z0-9_-]/gi, '_') || 'app';
   const outDir = arg('--out', path.join(os.tmpdir(), 'fiodos', 'analysis', safeName));
   // Model precedence: explicit --model (operator override) > backend plan model
   // (resolved below from the analysis-quota pre-check) > DEFAULT_MODEL fallback.
@@ -197,30 +227,47 @@ async function main() {
   const useLLM = !process.argv.includes('--no-llm');
   fs.mkdirSync(outDir, { recursive: true });
 
-  // ── 1. Static route scan (cheap facts; also the route verifier's ground truth)
-  // Platform: auto-detected from the presence of an expo-router app/ dir, or
-  // forced with --platform web|mobile. Web apps have no static route ground
-  // truth, so the AI proposes routes and we keep them unverified (honest flag).
-  const { appDir, routes: scannedRoutes } = scanRoutes(appRoot);
   const platformArg = (arg('--platform', '') || '').toLowerCase();
   const KNOWN_PLATFORMS = ['web', 'mobile', 'flutter', 'ios', 'android'];
-  const platform = KNOWN_PLATFORMS.includes(platformArg)
-    ? platformArg
-    : detectPlatform(appRoot, appDir);
+  const forcedPlatform = KNOWN_PLATFORMS.includes(platformArg) ? platformArg : null;
+
+  // ── 1. Static route scan (cheap facts; also the route verifier's ground truth)
+  // Platform: auto-detected from package.json / native manifests, or forced with
+  // --platform. Web apps have no static route ground truth, so the AI proposes
+  // routes and we keep them unverified (honest flag).
+  const { appDir, routes: scannedRoutes } = scanRoutes(inputRoot);
+  const platform = forcedPlatform ?? detectPlatform(inputRoot, appDir);
+
+  // Monorepos: scope analysis to the sub-app for this platform (e.g. frontend/
+  // for Next, mobile/ for Expo) so the web orb never inherits mobile actions.
+  const explicitAnalysisRoot = arg('--analysis-root', '');
+  const scope = explicitAnalysisRoot
+    ? { root: path.resolve(explicitAnalysisRoot), scoped: true, reason: '--analysis-root' }
+    : resolveAnalysisRoot(inputRoot, platform);
+  const analysisRoot = scope.root;
+  if (scope.scoped) {
+    const rel = path.relative(inputRoot, analysisRoot) || '.';
+    logDev(
+      `Scoped to ${rel} (${platform} app) — analyzing this folder only, not the whole repo.`,
+    );
+    logDev(`[scope] input=${inputRoot} analysis=${analysisRoot} reason=${scope.reason}`);
+  }
+
+  const { appDir: scopedAppDir, routes: scopedRoutes } = scanRoutes(analysisRoot);
   // The expo-router filesystem scan ONLY describes a mobile app. A Next.js App
   // Router web app also has an app/ dir, so the scan would otherwise produce
   // bogus "routes" and misclassify the project; for web we ignore it and let
   // the AI propose routes (the documented web contract).
   // Only Expo/RN ('mobile') has a static route ground truth. Web AND the native
   // platforms (flutter/ios/android) have the AI infer routes (kept unverified).
-  const routes = platform === 'mobile' ? scannedRoutes : [];
+  const routes = platform === 'mobile' ? scopedRoutes : [];
   const verifyRoutes = platform === 'mobile' && routes.length > 0;
-  const appMeta = readAppMeta(appRoot);
+  const appMeta = readAppMeta(analysisRoot);
   logDev(`[static] platform=${platform} routes=${routes.length}` +
     (platform === 'web' ? ' (web: routes inferred by AI, not statically verified)' : ''));
 
   // ── 2. Collect source files (rule-based, budget-aware) ────────────────────
-  const { included, omitted, estimatedTokens } = collectFiles(appRoot, { maxInputTokens, platform });
+  const { included, omitted, estimatedTokens } = collectFiles(analysisRoot, { maxInputTokens, platform });
   fs.writeFileSync(path.join(outDir, 'files-sent.json'), JSON.stringify({
     included: included.map((f) => f.rel),
     omitted,
@@ -244,14 +291,14 @@ async function main() {
     // is not acceptable for this app.
     ({ manifest, provenance } = routesOnlyManifest(appMeta, routes));
     logDev('[no-llm] static-only manifest (routes only, no actions)');
-    logUser(`Static analysis complete — ${manifest.routes.length} routes`);
+    logUser('Static analysis complete');
   } else {
     // Hybrid AI-key model. DEFAULT: hosted analysis via the Fiodos backend
     // proxy (Fiodos's AI key, no key needed by the developer). With
     // --own-ai-key the analysis runs locally against the developer's own
     // provider key (privacy path: source code goes straight to the AI and
     // never reaches Fiodos). --no-llm (handled above) sends no code anywhere.
-    loadAppEnv(path.resolve(appRoot));
+    loadAppEnv(analysisRoot);
     const { apiKey, apiUrl } = resolveApiTarget();
     const useProxy = !process.argv.includes('--own-ai-key');
 
@@ -276,10 +323,9 @@ async function main() {
     }
 
     // ── 3. AI reads the code ────────────────────────────────────────────────
-    logUser('Analyzing your project — may take 1–2 min');
     const { parsed, usage, costUSD, elapsedMs, promptChars, model: usedModel, analysisToken: token } =
       await withSpinner(
-        'Analyzing your project with AI',
+        'Analyzing your project — may take 1–2 min',
         () => analyzeWithAI({
           appMeta, files: included, omitted, staticRoutes: routes, model, platform,
           useProxy, apiKey, apiUrl,
@@ -304,7 +350,7 @@ async function main() {
     const droppedRoutes = provenance.routes.filter((r) => !r.included).length;
     logDev(`[verify] kept routes=${manifest.routes.length} actions=${manifest.actions.length}` +
       ` | dropped: ${droppedRoutes} routes, ${droppedActions} actions (unproven evidence)`);
-    logUser(`Analysis complete — ${manifest.routes.length} routes, ${manifest.actions.length} actions`);
+    logUser('Analysis complete');
 
     fs.writeFileSync(path.join(outDir, 'evidence.json'), JSON.stringify({
       evidence, wiring, uncertain: parsed.uncertain || [],
@@ -334,6 +380,34 @@ async function main() {
   // the rest 'allow'. Closed-by-default still applies regardless of this hint.
   annotateExternalAgentRecommendations(manifest);
 
+  // ── 4c. Product-surface scoring (conservative, default-OFF for clear noise).
+  // Existence is already proven; this asks the SEPARATE question "is this part
+  // of the live product surface the orb should expose by default?". Routes/
+  // actions whose screens are UNREACHABLE by navigation from the deployed entry
+  // (orphans / dead code / a secondary app mirrored in the repo) AND not behind
+  // auth are annotated low-confidence and published DISABLED-by-default — never
+  // dropped (no new hallucination risk) and never empties an auth-gated app.
+  // Anything uncertain stays ACTIVE (fail towards including). The on/off lives
+  // in the workspace's disabled-intent sets (reused infra); the developer flips
+  // it in the dashboard. Web-first; other platforms are not scored yet.
+  let surface = { disabledRouteIntents: [], disabledActionIntents: [], stats: { applied: false } };
+  try {
+    surface = scoreSurface({ manifest, evidence, included, analysisRoot, platform });
+    for (const r of manifest.routes) {
+      const s = surface.routes && surface.routes[r.intent];
+      if (s) { r.surfaceConfidence = s.confidence; r.surfaceReason = s.reason; }
+    }
+    for (const a of manifest.actions) {
+      const s = surface.actions && surface.actions[a.intent];
+      if (s) { a.surfaceConfidence = s.confidence; a.surfaceReason = s.reason; }
+    }
+    logDev(`[surface] ${JSON.stringify(surface.stats)}`);
+  } catch (e) {
+    // Scoring is best-effort: a failure must never block publishing. Fail OPEN
+    // (everything stays active) — consistent with the "fail towards including".
+    logDev(`[surface] skipped: ${e.message}`);
+  }
+
   // ── 5. Final gate: the real @fiodos/core validator ─────────────────────────
   // Loaded as a package dependency (not a monorepo path) so it resolves when
   // the CLI is installed from npm.
@@ -352,14 +426,34 @@ async function main() {
   logDev(`[done] manifest: ${manifest.routes.length} routes, ${manifest.actions.length} actions`);
   logDev(`[done] output → ${outDir}`);
 
-  if (process.argv.includes('--publish')) {
-    loadAppEnv(path.resolve(appRoot));
-    await publishManifest(manifest, {
-      ...analysisMeta,
-      generatedAt: new Date().toISOString(),
-      routesIncluded: manifest.routes.length,
-      actionsIncluded: manifest.actions.length,
-    }, analysisToken);
+  const publishing = process.argv.includes('--publish');
+  const publishMeta = {
+    ...analysisMeta,
+    generatedAt: new Date().toISOString(),
+    routesIncluded: manifest.routes.length,
+    actionsIncluded: manifest.actions.length,
+    // Conservative default-OFF set for low-confidence (orphan) routes/actions.
+    // The backend applies these to the workspace's disabled-intent sets ONLY on
+    // the first publish / when the developer has not customized scope (no
+    // clobbering manual choices). Empty when scoring did not apply.
+    scopeDefaults: {
+      disabledRouteIntents: surface.disabledRouteIntents || [],
+      disabledActionIntents: surface.disabledActionIntents || [],
+    },
+  };
+
+  // Informative, non-blocking summary (the dashboard is where scope is managed).
+  const offR = (surface.disabledRouteIntents || []).length;
+  const offA = (surface.disabledActionIntents || []).length;
+  if (surface.stats && surface.stats.applied && (offR || offA)) {
+    const onR = manifest.routes.length - offR;
+    const onA = manifest.actions.length - offA;
+    logUser(`Main surface (active): ${onR} route(s), ${onA} action(s)`);
+    logUser(
+      `Detected but off by default: ${offR} route(s), ${offA} action(s) — ` +
+      `not reachable from your app's home (likely internal/secondary screens)`,
+    );
+    logUser('Review or re-enable any of them in your dashboard → Agent configuration');
   }
 
   // ── 6. Web: offer to wire the orb into the app (consent-based) ─────────────
@@ -370,46 +464,8 @@ async function main() {
     const { apiKey, apiUrl } = resolveApiTarget();
     const assumeYes = process.argv.includes('--yes') || process.argv.includes('--wire-yes');
     const noWire = process.argv.includes('--no-wire');
-
-    // ── 5b. Offer to align the app's .env with the published key/URL (consent).
-    // Removes the second manual copy of the key — the root cause of the silent
-    // "orb fetches the wrong backend" failure. Skipped with --no-write-env.
-    if (process.argv.includes('--publish') && !process.argv.includes('--no-write-env')) {
-      try {
-        await offerWriteEnv({
-          appRoot: path.resolve(appRoot),
-          apiKey,
-          apiUrl,
-          defaultApiUrl: DEFAULT_API_URL,
-          assumeYes,
-          log: logUser,
-        });
-      } catch (e) {
-        logDev(`[write-env] skipped: ${e.message}`);
-      }
-    }
-    // --no-orb-wire skips ONLY the orb mount (useful to test handler wiring in
-    // isolation without modifying the app's entrypoint / package.json).
-    if (!process.argv.includes('--no-orb-wire')) {
-      const result = await wireWebOrb(path.resolve(appRoot), {
-        apiUrl,
-        colors: fyodosTermColors(),
-        assumeYes,
-        noWire,
-        runTest: !process.argv.includes('--no-wire-test'),
-      });
-      reportWireResult(result, fyodosTermColors());
-    }
-
-    // ── 7. Web: SECOND consent — connect detected actions to real app functions.
-    // The orb is mounted but the agent cannot DO anything until each manifest
-    // action is bridged to the function that performs it. We prepare that wiring,
-    // write a readable document into the project's Fiodos folder, and ask a
-    // separate, informed [yes/no] before touching anything. Security is enforced
-    // upstream by the engine, so generated handlers can never skip a confirmation.
+    let envWriteResult = null;
     const { runPostWireTest } = require('./postWireTest');
-    // Corrector: when a wired action fails install-time verification, re-prompt the
-    // AI with the concrete error to fix THAT action. Disable with --no-self-correct.
     const selfCorrect = !process.argv.includes('--no-self-correct');
     const corrector = selfCorrect
       ? async (args) => {
@@ -417,7 +473,7 @@ async function main() {
           return fixed;
         }
       : null;
-    const handlerResult = await wireHandlers(path.resolve(appRoot), {
+    const handlerOpts = {
       manifest,
       evidence,
       wiring,
@@ -425,14 +481,87 @@ async function main() {
       colors: fyodosTermColors(),
       assumeYes,
       noWire,
+      quiet: !isVerbose(),
       runTest: !process.argv.includes('--no-wire-test'),
       revertOnFailure: true,
       testRunner: runPostWireTest,
       corrector,
       files: included,
       maxAttempts: Number(process.env.FYODOS_WIRE_MAX_ATTEMPTS || 3),
-    });
-    reportHandlerResult(handlerResult, fyodosTermColors());
+    };
+
+    const runWebWire = async ({ setLabel, pause, resume }) => {
+      // --no-orb-wire skips ONLY the orb mount (useful to test handler wiring in
+      // isolation without modifying the app's entrypoint / package.json).
+      if (!process.argv.includes('--no-orb-wire')) {
+        setLabel('Mounting the orb in your app');
+        if (!assumeYes) pause();
+        const result = await wireWebOrb(analysisRoot, {
+          apiUrl,
+          colors: fyodosTermColors(),
+          assumeYes,
+          noWire,
+          runTest: !process.argv.includes('--no-wire-test'),
+        });
+        if (!assumeYes) resume();
+        reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() });
+        if (
+          publishing &&
+          apiKey &&
+          (result.status === 'added' || result.status === 'already')
+        ) {
+          await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
+        }
+      }
+
+      setLabel('Wiring actions to your app');
+      if (!assumeYes) pause();
+      const handlerResult = await wireHandlers(analysisRoot, handlerOpts);
+      if (!assumeYes) resume();
+      reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() });
+    };
+
+    if (publishing) {
+      loadAppEnv(analysisRoot);
+      await withSpinner('Publishing to your project', async (spinner) => {
+        await publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true });
+        await runWebWire(spinner);
+      });
+      logUser('Published to your project');
+    } else {
+      await withSpinner('Mounting the orb in your app', runWebWire);
+    }
+
+    // ── 8. API key in environment (LAST step — always asks; independent of --yes)
+    // --yes only skips orb/handler prompts. --write-env-yes skips this one (CI).
+    // If the developer declines, we show a copy-paste reminder here at the end.
+    if (publishing && !process.argv.includes('--no-write-env')) {
+      try {
+        envWriteResult = await offerWriteEnv({
+          appRoot: analysisRoot,
+          apiKey,
+          apiUrl,
+          defaultApiUrl: DEFAULT_API_URL,
+          assumeYes: process.argv.includes('--write-env-yes'),
+          log: logUser,
+          logDev,
+        });
+        if (
+          envWriteResult &&
+          (envWriteResult.status === 'declined by user' || envWriteResult.status === 'manual')
+        ) {
+          printEnvManualReminder(envWriteResult.writePlan, { logUser, logDev });
+        }
+      } catch (e) {
+        logDev(`[write-env] skipped: ${e.message}`);
+      }
+    }
+  } else if (publishing) {
+    loadAppEnv(analysisRoot);
+    await withSpinner('Publishing to your project', () =>
+      publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true }),
+    );
+    logUser('Published to your project');
   }
 }
 
@@ -653,7 +782,7 @@ function printQuotaBlocked(quota) {
   );
 }
 
-async function publishManifest(manifest, meta, analysisToken = null) {
+async function publishManifest(manifest, meta, analysisToken = null, opts = {}) {
   const { apiKey, apiUrl } = resolveApiTarget();
   if (!apiKey) {
     console.error(
@@ -686,17 +815,13 @@ async function publishManifest(manifest, meta, analysisToken = null) {
     process.exit(1);
   }
   const body = await res.json();
-  logUser(`Published to your project — ${body.routes} routes, ${body.actions} actions`);
+  if (!opts.skipSuccessLog) {
+    logUser('Published to your project');
+  }
   logDev(`[publish] OK — ${body.routes} routes, ${body.actions} actions received at ${body.receivedAt}`);
 
-  // ── Self-check: confirm the orb will actually FIND this manifest ───────────
-  // Re-fetch it the way the SDK does at runtime (GET /v1/client/manifest with
-  // the SAME key + URL). This catches the silent-failure setup BEFORE the
-  // developer is left wondering why the orb never appears, and prints the exact
-  // key/URL their app must use so they can compare with their .env.
+  // Self-check: confirm the orb will find this manifest (silent unless --verbose).
   await verifyOrbCanFetch({ apiKey, apiUrl });
-
-  logUser('Open the dashboard → Agent settings → "Reload analysis" to review');
 }
 
 /**
@@ -705,6 +830,23 @@ async function publishManifest(manifest, meta, analysisToken = null) {
  * and URL their running app must use. Never hard-fails the publish (the publish
  * already succeeded); a failed re-fetch is surfaced as an actionable warning.
  */
+async function postOrbWired({ apiKey, apiUrl, file }) {
+  if (!apiKey) return;
+  try {
+    const res = await fetch(`${apiUrl}/v1/developer/orb-wired`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
+      body: JSON.stringify({ file: file || '', platform: 'web' }),
+    });
+    if (res.ok) {
+      logDev(`[orb-wired] install proof recorded (${file || 'web'})`);
+    } else {
+      logDev(`[orb-wired] could not record install proof: HTTP ${res.status}`);
+    }
+  } catch (e) {
+    logDev(`[orb-wired] skipped: ${e.message || e}`);
+  }
+}
 async function verifyOrbCanFetch({ apiKey, apiUrl }) {
   try {
     const res = await fetch(`${apiUrl}/v1/client/manifest`, {
@@ -714,27 +856,15 @@ async function verifyOrbCanFetch({ apiKey, apiUrl }) {
     if (res.ok) {
       const data = await res.json().catch(() => null);
       if (data && data.manifest) {
-        logUser(
-          `✓ Verified: your orb will find this manifest using API key ${apiKey.slice(0, 12)}… ` +
-            `against ${apiUrl}.`,
-        );
-        logUser(
-          'Make sure your app uses this SAME key and URL in its .env ' +
-            '(NEXT_PUBLIC_FYODOS_API_KEY / VITE_FYODOS_API_KEY, and the API URL).',
+        logDev(
+          `[verify] manifest reachable with key ${apiKey.slice(0, 12)}… against ${apiUrl}`,
         );
         return true;
       }
     }
-    logUser(
-      `⚠︎ Published, but could not re-read the manifest from ${apiUrl} (HTTP ${res.status}). ` +
-        'Check that your app uses this same key and URL.',
-    );
+    logDev(`[verify] published but re-fetch failed: HTTP ${res.status}`);
   } catch (e) {
     logDev(`[verify] re-fetch failed: ${e.message}`);
-    logUser(
-      `⚠︎ Published, but could not reach ${apiUrl} to verify. ` +
-        'Confirm your app points to this same URL and key.',
-    );
   }
   return false;
 }