@fiodos/cli 0.1.25 → 0.1.26

package/src/wireSession.js

@@ -61,14 +61,22 @@ const {
   buildBridgeModule,
   insertImportBlock,
   insertRegisterBlock,
+  deriveBridgeAnchor,
 } = require('./wireHandlers');
 
 const SESSION_BASENAME = 'session.generated';
 const DOC_BASENAME = 'FYODOS_SESSION.md';
 const IS_AUTH_EXPORT = 'fyodosIsAuthenticated';
 const USER_ID_EXPORT = 'fyodosGetUserId';
+const CAPS_EXPORT = 'fyodosGetSessionCapabilities';
 const BRIDGE_IS_AUTH = '__fyodos_is_authenticated';
 const BRIDGE_USER_ID = '__fyodos_user_id';
+const BRIDGE_CAPABILITIES = '__fyodos_capabilities';
+
+// Capability flags are short snake_case names ("has_payment_method"). Anything
+// else is dropped: a malformed name could never match the manifest's
+// requiredCapabilities anyway, so wiring it would be dead weight.
+const CAPABILITY_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
 
 // Session edits carry their OWN markers: wireHandlers' stripFiodosBlocks
 // removes every FYODOS:BRIDGE block in a file, so if the session registration
@@ -128,11 +136,46 @@ function verifyExpr({ expr, importedNames, extraOk = new Set(), what }) {
   return null;
 }
 
+/**
+ * Verify the AI's fine-grained session capabilities (Eje B audience map:
+ * "has_payment_method", "is_admin"…) INDIVIDUALLY: a hallucinated capability
+ * is dropped with an honest note while the rest of the session wiring still
+ * applies — one bad flag must never cost the whole auth awareness.
+ * Returns { caps: [{ name, expr }], notes: [reason...] }.
+ */
+function verifyCapabilities({ rawCapabilities, exprKey, importedNames, extraOk = new Set() }) {
+  const caps = [];
+  const notes = [];
+  const seen = new Set();
+  for (const c of Array.isArray(rawCapabilities) ? rawCapabilities : []) {
+    const name = String((c && c.name) || '').trim();
+    const expr = String((c && c[exprKey]) || '').trim();
+    if (!CAPABILITY_NAME_RE.test(name)) {
+      notes.push(`capability '${name || '(unnamed)'}' dropped: not a short snake_case name`);
+      continue;
+    }
+    if (seen.has(name)) continue;
+    if (!expr) {
+      notes.push(`capability '${name}' dropped: no '${exprKey}' expression was provided`);
+      continue;
+    }
+    const err = verifyExpr({ expr, importedNames, extraOk, what: `capability '${name}'` });
+    if (err) {
+      notes.push(`capability '${name}' dropped: ${err}`);
+      continue;
+    }
+    seen.add(name);
+    caps.push({ name, expr });
+  }
+  return { caps: caps.slice(0, 8), notes };
+}
+
 /**
  * Turn the AI's `session` block into a verified plan, or { reason }.
  * Plan shapes:
- *   { strategy:'module', imports, isAuthExpr, userIdExpr|null }
- *   { strategy:'bridge', bridge:{ file, anchor, scope, imports, isAuthInvoke, userIdInvoke|null } }
+ *   { strategy:'module', imports, isAuthExpr, userIdExpr|null, capabilities, capabilityNotes }
+ *   { strategy:'bridge', bridge:{ file, anchor, scope, imports, isAuthInvoke, userIdInvoke|null,
+ *     capabilities }, capabilityNotes }
  */
 function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
   if (!session || typeof session !== 'object') return { reason: 'no session block' };
@@ -153,7 +196,7 @@ function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
   if (session.strategy === 'bridge') {
     const b = session.bridge || {};
     const file = normRel(b.file);
-    const anchor = String(b.anchor || '').trim();
+    let anchor = String(b.anchor || '').trim();
     const isAuthInvoke = String(b.isAuthenticatedInvoke || '').trim();
     const userIdInvoke = String(b.userIdInvoke || '').trim() || null;
 
@@ -161,30 +204,49 @@ function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
     const content = readFileSafe(appRoot, file);
     if (content == null) return { reason: `could not read the component '${file}'` };
     if (!isAuthInvoke) return { reason: `no isAuthenticated expression was provided for '${file}'` };
-    if (!anchor) return { reason: `no insertion anchor was provided in '${file}'` };
     // The anchor must be unique in the file WITHOUT counting our own previous
-    // insertions (idempotent re-runs).
-    const occ = countOccurrences(stripSessionBlocks(content), anchor);
-    if (occ === 0) return { reason: `no safe insertion point was found in '${file}'` };
-    if (occ > 1) return { reason: `the insertion anchor appears ${occ} times in '${file}'; it is ambiguous` };
+    // insertions (idempotent re-runs). When the AI's anchor is missing or
+    // ambiguous, derive a deterministic one from the declaration of the symbol
+    // the invoke reads (same rescue as handler bridges) instead of giving up —
+    // safety is still guaranteed by the compile check + revert below.
+    const cleanContent = stripSessionBlocks(content);
+    const occ = anchor ? countOccurrences(cleanContent, anchor) : 0;
+    if (occ !== 1) {
+      const derived = deriveBridgeAnchor(cleanContent, isAuthInvoke);
+      if (derived) anchor = derived;
+      else if (!anchor || occ === 0) return { reason: `no safe insertion point was found in '${file}'` };
+      else return { reason: `the insertion anchor appears ${occ} times in '${file}'; it is ambiguous` };
+    }
 
     const v = verifyImports({ appRoot, rawImports: b.imports, importBaseDirRel: path.dirname(file) });
     if (v.reason) return v;
 
     // Identifiers must be in-file, imported, args-free locals or safe globals.
     const inFileOk = new Set();
-    for (const expr of [isAuthInvoke, userIdInvoke].filter(Boolean)) {
+    const capExprs = (Array.isArray(session.capabilities) ? session.capabilities : [])
+      .map((c) => String((c && c.invoke) || '').trim())
+      .filter(Boolean);
+    for (const expr of [isAuthInvoke, userIdInvoke, ...capExprs].filter(Boolean)) {
       for (const id of freeIdentifiers(expr)) {
         if (fileHasSymbol(appRoot, file, id)) inFileOk.add(id);
       }
+    }
+    for (const expr of [isAuthInvoke, userIdInvoke].filter(Boolean)) {
       const err = verifyExpr({ expr, importedNames: v.importedNames, extraOk: inFileOk, what: 'session' });
       if (err) return { reason: `${err} — in '${file}'` };
     }
+    const capsV = verifyCapabilities({
+      rawCapabilities: session.capabilities,
+      exprKey: 'invoke',
+      importedNames: v.importedNames,
+      extraOk: inFileOk,
+    });
 
     return {
       plan: {
         strategy: 'bridge',
         reason: String(session.reason || ''),
+        capabilityNotes: capsV.notes,
         bridge: {
           file,
           anchor,
@@ -192,6 +254,7 @@ function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
           imports: v.imports,
           isAuthInvoke,
           userIdInvoke,
+          capabilities: capsV.caps,
           importPathToBridge: relImport(path.dirname(file), path.join(fyodosDirRel, BRIDGE_BASENAME)),
         },
       },
@@ -209,6 +272,11 @@ function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
     const err = verifyExpr({ expr, importedNames: v.importedNames, what: 'session' });
     if (err) return { reason: err };
   }
+  const capsV = verifyCapabilities({
+    rawCapabilities: session.capabilities,
+    exprKey: 'call',
+    importedNames: v.importedNames,
+  });
 
   return {
     plan: {
@@ -217,6 +285,8 @@ function prepareSessionPlan({ appRoot, session, fyodosDirRel }) {
       imports: v.imports,
       isAuthExpr,
       userIdExpr,
+      capabilities: capsV.caps,
+      capabilityNotes: capsV.notes,
     },
   };
 }
@@ -240,6 +310,8 @@ function buildSessionModule(plan, opts = {}) {
   const esm = opts.esm !== false;
   const boolRet = ts ? ': boolean | null' : '';
   const strRet = ts ? ': string | null' : '';
+  const capsRet = ts ? ': Record<string, boolean> | null' : '';
+  const capsDecl = ts ? ': Record<string, boolean>' : '';
 
   const L = [];
   L.push(
@@ -282,6 +354,27 @@ function buildSessionModule(plan, opts = {}) {
     L.push('    return null;');
     L.push('  }');
     L.push('}');
+    L.push('');
+    L.push('/**');
+    L.push(' * Fine-grained session capability flags (audience map: has_payment_method,');
+    L.push(' * is_admin…). null = UNKNOWN — the orb then filters NOTHING (fail-open).');
+    L.push(' * Boolean flags only; never counts, names or any user data.');
+    L.push(' */');
+    L.push(`export function ${CAPS_EXPORT}()${capsRet} {`);
+    L.push('  try {');
+    L.push(`    const fn = getFiodosBridge()[${JSON.stringify(BRIDGE_CAPABILITIES)}];`);
+    L.push("    if (typeof fn !== 'function') return null;");
+    L.push('    const raw = fn();');
+    L.push("    if (!raw || typeof raw !== 'object') return null;");
+    L.push(`    const caps${capsDecl} = {};`);
+    L.push('    for (const k of Object.keys(raw)) {');
+    L.push("      if (typeof raw[k] === 'boolean') caps[k] = raw[k];");
+    L.push('    }');
+    L.push('    return Object.keys(caps).length > 0 ? caps : null;');
+    L.push('  } catch {');
+    L.push('    return null;');
+    L.push('  }');
+    L.push('}');
   } else {
     for (const imp of plan.imports || []) L.push(importLine(imp, esm));
     if ((plan.imports || []).length) L.push('');
@@ -310,9 +403,33 @@ function buildSessionModule(plan, opts = {}) {
       L.push('  return null;');
     }
     L.push('}');
+    L.push('');
+    L.push('/**');
+    L.push(' * Fine-grained session capability flags (audience map: has_payment_method,');
+    L.push(' * is_admin…). null = UNKNOWN — the orb then filters NOTHING (fail-open).');
+    L.push(' * Boolean flags only; never counts, names or any user data.');
+    L.push(' */');
+    L.push(`export function ${CAPS_EXPORT}()${capsRet} {`);
+    const moduleCaps = Array.isArray(plan.capabilities) ? plan.capabilities : [];
+    if (moduleCaps.length > 0) {
+      L.push(`  const caps${capsDecl} = {};`);
+      for (const c of moduleCaps) {
+        // Each flag is isolated: one throwing read stays UNKNOWN (omitted)
+        // instead of blanking every other capability.
+        L.push('  try {');
+        L.push(`    caps[${JSON.stringify(c.name)}] = Boolean(${c.expr});`);
+        L.push('  } catch {');
+        L.push('    /* unknown — omitted (fail-open) */');
+        L.push('  }');
+      }
+      L.push('  return Object.keys(caps).length > 0 ? caps : null;');
+    } else {
+      L.push('  return null;');
+    }
+    L.push('}');
   }
   L.push('');
-  if (!esm) L.push(`module.exports = { ${IS_AUTH_EXPORT}, ${USER_ID_EXPORT} };`);
+  if (!esm) L.push(`module.exports = { ${IS_AUTH_EXPORT}, ${USER_ID_EXPORT}, ${CAPS_EXPORT} };`);
   let body = L.join('\n');
   if (!esm) {
     // CommonJS build: `export function` is invalid — rewrite to plain functions.
@@ -329,6 +446,11 @@ function planSessionComponentEdit(appRoot, plan) {
 
   const methods = [`  ${JSON.stringify(BRIDGE_IS_AUTH)}: () => (${b.isAuthInvoke}),`];
   if (b.userIdInvoke) methods.push(`  ${JSON.stringify(BRIDGE_USER_ID)}: () => (${b.userIdInvoke}),`);
+  const caps = Array.isArray(b.capabilities) ? b.capabilities : [];
+  if (caps.length > 0) {
+    const entries = caps.map((c) => `${JSON.stringify(c.name)}: Boolean(${c.expr})`).join(', ');
+    methods.push(`  ${JSON.stringify(BRIDGE_CAPABILITIES)}: () => ({ ${entries} }),`);
+  }
 
   const importLines = [`import { registerFiodosBridge } from '${b.importPathToBridge}';`];
   for (const imp of b.imports || []) importLines.push(importLine(imp, true));
@@ -399,10 +521,22 @@ function buildSessionDoc(plan, ctx = {}) {
   L.push('');
   L.push(`- App: \`${appName}\``);
   L.push(`- Strategy: \`${plan.strategy}\`${plan.reason ? ` — ${plan.reason}` : ''}`);
-  L.push(`- Creates \`${sessionRel}\` — exports \`${IS_AUTH_EXPORT}()\` and \`${USER_ID_EXPORT}()\`.`);
+  L.push(`- Creates \`${sessionRel}\` — exports \`${IS_AUTH_EXPORT}()\`, \`${USER_ID_EXPORT}()\` and \`${CAPS_EXPORT}()\`.`);
   if (editedFile) {
     L.push(`- Edits \`${editedFile}\` (only reversible \`FYODOS:SESSION\` blocks) to register the live session.`);
   }
+  const planCaps =
+    plan.strategy === 'bridge'
+      ? (plan.bridge && plan.bridge.capabilities) || []
+      : plan.capabilities || [];
+  if (planCaps.length > 0) {
+    L.push(
+      `- Capability flags (audience map): ${planCaps.map((c) => `\`${c.name}\``).join(', ')} — boolean-only, read live from the same session source. Actions whose \`requiredCapabilities\` report false are hidden from that user's orb.`,
+    );
+  }
+  for (const note of plan.capabilityNotes || []) {
+    L.push(`- Capability left out: ${note}.`);
+  }
   L.push(`- Verification: ${verified ? 'build check passed' : verifyNote || 'compile check unavailable — applied with the mechanical symbol verification only'}.`);
   L.push('');
   L.push('## Honesty contract (tri-state)');
@@ -612,8 +746,10 @@ module.exports = {
   SESSION_BASENAME,
   IS_AUTH_EXPORT,
   USER_ID_EXPORT,
+  CAPS_EXPORT,
   BRIDGE_IS_AUTH,
   BRIDGE_USER_ID,
+  BRIDGE_CAPABILITIES,
   SESSION_EDIT_START,
   SESSION_EDIT_END,
 };

package/src/wireWeb.js

@@ -29,6 +29,8 @@ const {
   addRegistriesToBootstrapSource,
   addSessionToMountSource,
   addSessionToBootstrapSource,
+  addScreenToMountSource,
+  addScreenToBootstrapSource,
   buildEntryBootstrapBlock,
   IMPORT_NAME,
   WRAPPER_BASENAME,
@@ -511,6 +513,17 @@ function connectOrbSession(appRoot, opts = {}) {
   const { sessionFileAbs } = opts;
   if (!sessionFileAbs || !fs.existsSync(sessionFileAbs)) return { status: 'no-session-file' };
 
+  // Only connect the capability getter when the generated module actually
+  // exports it — referencing a missing export would break the app's build.
+  let sessionHasCapabilities = false;
+  try {
+    sessionHasCapabilities = fs
+      .readFileSync(sessionFileAbs, 'utf8')
+      .includes('fyodosGetSessionCapabilities');
+  } catch {
+    sessionHasCapabilities = false;
+  }
+
   const framework = detectFramework(appRoot);
   const target = detectTarget(appRoot, framework);
   if (!target || !target.file) return { status: 'no-target' };
@@ -527,7 +540,7 @@ function connectOrbSession(appRoot, opts = {}) {
     const fileRel = path.relative(appRoot, target.file);
     const backups = backupFiles([target.file]);
     try {
-      const res = addSessionToBootstrapSource(source, importPath);
+      const res = addSessionToBootstrapSource(source, importPath, { sessionHasCapabilities });
       if (!res.changed) {
         return { status: res.reason === 'already' ? 'already' : res.reason || 'not-mounted', file: fileRel };
       }
@@ -564,7 +577,82 @@ function connectOrbSession(appRoot, opts = {}) {
   const fileRel = path.relative(appRoot, mountFile);
   const backups = backupFiles([mountFile]);
   try {
-    const res = addSessionToMountSource(source, importPath);
+    const res = addSessionToMountSource(source, importPath, { sessionHasCapabilities });
+    if (!res.changed) {
+      return { status: res.reason || 'not-mounted', file: fileRel };
+    }
+    fs.writeFileSync(mountFile, res.source);
+    return { status: 'connected', file: fileRel };
+  } catch (e) {
+    revertFiles(backups);
+    return { status: 'failed', file: fileRel, error: e };
+  }
+}
+
+/**
+ * Fourth pass — connect the generated SCREEN-TRUTH module to the mounted orb,
+ * so the agent knows WHICH SCREEN the user is on even when screens are client
+ * state instead of URLs. Mirrors connectOrbSession: idempotent, reversible,
+ * never overrides a developer-wired getCurrentRoute.
+ */
+function connectOrbScreen(appRoot, opts = {}) {
+  const { screenFileAbs } = opts;
+  if (!screenFileAbs || !fs.existsSync(screenFileAbs)) return { status: 'no-screen-file' };
+
+  const framework = detectFramework(appRoot);
+  const target = detectTarget(appRoot, framework);
+  if (!target || !target.file) return { status: 'no-target' };
+
+  const bootstrapKinds = new Set(['vue-entry', 'svelte-entry', 'sveltekit-hooks']);
+  if (bootstrapKinds.has(target.kind)) {
+    let source;
+    try {
+      source = fs.readFileSync(target.file, 'utf8');
+    } catch {
+      return { status: 'not-mounted' };
+    }
+    const importPath = registryRelImport(target.file, screenFileAbs);
+    const fileRel = path.relative(appRoot, target.file);
+    const backups = backupFiles([target.file]);
+    try {
+      const res = addScreenToBootstrapSource(source, importPath);
+      if (!res.changed) {
+        return { status: res.reason === 'already' ? 'already' : res.reason || 'not-mounted', file: fileRel };
+      }
+      fs.writeFileSync(target.file, res.source);
+      return { status: 'connected', file: fileRel };
+    } catch (e) {
+      revertFiles(backups);
+      return { status: 'failed', file: fileRel, error: e };
+    }
+  }
+
+  const reactKinds = new Set(['vite', 'next-pages', 'next-app']);
+  if (!reactKinds.has(target.kind)) return { status: 'unsupported-framework', framework };
+
+  let mountFile = target.file;
+  if (target.kind === 'next-app') {
+    const dir = path.dirname(target.file);
+    mountFile =
+      [path.join(dir, `${WRAPPER_BASENAME}.tsx`), path.join(dir, `${WRAPPER_BASENAME}.jsx`)].find((f) =>
+        fs.existsSync(f),
+      ) || null;
+    if (!mountFile) return { status: 'not-mounted' };
+  }
+
+  let source;
+  try {
+    source = fs.readFileSync(mountFile, 'utf8');
+  } catch {
+    return { status: 'not-mounted' };
+  }
+  if (!/<FiodosAgent\b/.test(source)) return { status: 'not-mounted' };
+
+  const importPath = registryRelImport(mountFile, screenFileAbs);
+  const fileRel = path.relative(appRoot, mountFile);
+  const backups = backupFiles([mountFile]);
+  try {
+    const res = addScreenToMountSource(source, importPath);
     if (!res.changed) {
       return { status: res.reason || 'not-mounted', file: fileRel };
     }
@@ -576,6 +664,29 @@ function connectOrbSession(appRoot, opts = {}) {
   }
 }
 
+function reportScreenConnectResult(result, colors = {}, opts = {}) {
+  const quiet = opts.quiet !== false;
+  if (!result) return;
+  const { blue, cyan, dim, reset } = colors;
+  const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
+  switch (result.status) {
+    case 'connected':
+      console.error(`${tag} · screen truth connected to the orb mount (${result.file})`);
+      break;
+    case 'already':
+      if (!quiet) console.error(`${tag} · ${dim || ''}screen truth already connected to the mount${reset || ''}`);
+      break;
+    case 'dev-wired':
+      if (!quiet) {
+        console.error(`${tag} · ${dim || ''}the mount already has its own getCurrentRoute — left as is${reset || ''}`);
+      }
+      break;
+    default:
+      if (!quiet) console.error(`${tag} · ${dim || ''}screen truth not connected to the mount (${result.status})${reset || ''}`);
+      break;
+  }
+}
+
 function reportSessionConnectResult(result, colors = {}, opts = {}) {
   const quiet = opts.quiet !== false;
   if (!result) return;
@@ -632,6 +743,8 @@ module.exports = {
   reportRegistriesResult,
   connectOrbSession,
   reportSessionConnectResult,
+  connectOrbScreen,
+  reportScreenConnectResult,
   detectFramework,
   detectTarget,
 };

package/src/wireWebMount.js

@@ -87,9 +87,15 @@ const BOOTSTRAP_REGISTRY_EXPORT = 'fyodosGeneratedRegistries';
 // the mount automatically so auth awareness needs NO manual step.
 const SESSION_IS_AUTH_EXPORT = 'fyodosIsAuthenticated';
 const SESSION_USER_ID_EXPORT = 'fyodosGetUserId';
+// Capability flags (audience map) — only connected when the generated session
+// module actually exports it (older generated files do not).
+const SESSION_CAPS_EXPORT = 'fyodosGetSessionCapabilities';
+// Export of the generated screen-truth module (see wireScreen.js). Connected
+// to the mount automatically so state-driven screen awareness needs NO manual step.
+const SCREEN_ROUTE_EXPORT = 'fyodosGetCurrentRoute';
 
 function buildEntryBootstrapBlock(opts = {}) {
-  const { registryImportPath, sessionImportPath } = opts;
+  const { registryImportPath, sessionImportPath, screenImportPath, sessionHasCapabilities } = opts;
   const lines = [];
   lines.push(ORB_SCRIPT_START);
   lines.push(`import { createFiodosAgent as ${BOOTSTRAP_ALIAS} } from '@fiodos/web-core';`);
@@ -97,9 +103,12 @@ function buildEntryBootstrapBlock(opts = {}) {
     lines.push(`import { ${BOOTSTRAP_REGISTRY_EXPORT} } from '${registryImportPath}';`);
   }
   if (sessionImportPath) {
-    lines.push(
-      `import { ${SESSION_IS_AUTH_EXPORT}, ${SESSION_USER_ID_EXPORT} } from '${sessionImportPath}';`,
-    );
+    const sessionNames = [SESSION_IS_AUTH_EXPORT, SESSION_USER_ID_EXPORT];
+    if (sessionHasCapabilities) sessionNames.push(SESSION_CAPS_EXPORT);
+    lines.push(`import { ${sessionNames.join(', ')} } from '${sessionImportPath}';`);
+  }
+  if (screenImportPath) {
+    lines.push(`import { ${SCREEN_ROUTE_EXPORT} } from '${screenImportPath}';`);
   }
   lines.push(`${BOOTSTRAP_ALIAS}({`);
   lines.push('  apiKey: import.meta.env.VITE_FYODOS_API_KEY,');
@@ -108,7 +117,11 @@ function buildEntryBootstrapBlock(opts = {}) {
   if (sessionImportPath) {
     lines.push(`  isAuthenticated: ${SESSION_IS_AUTH_EXPORT},`);
     lines.push(`  getUserId: ${SESSION_USER_ID_EXPORT},`);
+    if (sessionHasCapabilities) {
+      lines.push(`  getSessionCapabilities: ${SESSION_CAPS_EXPORT},`);
+    }
   }
+  if (screenImportPath) lines.push(`  getCurrentRoute: ${SCREEN_ROUTE_EXPORT},`);
   lines.push('  mount: true,');
   lines.push('});');
   lines.push(ORB_SCRIPT_END);
@@ -136,10 +149,17 @@ function addRegistriesToBootstrapSource(source, registryImportPath) {
   if (/\n\s*registries:\s/.test(source.slice(source.indexOf(ORB_SCRIPT_START)))) {
     return { changed: false, source, reason: 'already' };
   }
-  // Preserve a session connection a previous pass already added to the block.
+  // Preserve session/screen connections previous passes already added.
   const sessionImportPath = extractBootstrapImportPath(source, SESSION_IS_AUTH_EXPORT);
+  const sessionHasCapabilities = Boolean(extractBootstrapImportPath(source, SESSION_CAPS_EXPORT));
+  const screenImportPath = extractBootstrapImportPath(source, SCREEN_ROUTE_EXPORT);
   const stripped = stripMarkedRegion(source, ORB_SCRIPT_START, ORB_SCRIPT_END).replace(/\n{3,}$/, '\n');
-  const block = buildEntryBootstrapBlock({ registryImportPath, sessionImportPath });
+  const block = buildEntryBootstrapBlock({
+    registryImportPath,
+    sessionImportPath,
+    screenImportPath,
+    sessionHasCapabilities,
+  });
   const next = insertBlockAfterLastImport(stripped.trimEnd(), block);
   return { changed: true, source: next.endsWith('\n') ? next : `${next}\n` };
 }
@@ -157,14 +177,42 @@ function extractBootstrapImportPath(source, name) {
 // Idempotently rewrite an existing entry-bootstrap block to carry the generated
 // SESSION connection (third pass, after session wiring). Preserves the
 // registries the second pass added. Returns { changed, source, reason? }.
-function addSessionToBootstrapSource(source, sessionImportPath) {
+function addSessionToBootstrapSource(source, sessionImportPath, opts = {}) {
   if (!source.includes(ORB_SCRIPT_START)) return { changed: false, source, reason: 'not-mounted' };
   if (/\n\s*isAuthenticated:\s/.test(source.slice(source.indexOf(ORB_SCRIPT_START)))) {
     return { changed: false, source, reason: 'already' };
   }
   const registryImportPath = extractBootstrapImportPath(source, BOOTSTRAP_REGISTRY_EXPORT);
+  const screenImportPath = extractBootstrapImportPath(source, SCREEN_ROUTE_EXPORT);
+  const stripped = stripMarkedRegion(source, ORB_SCRIPT_START, ORB_SCRIPT_END).replace(/\n{3,}$/, '\n');
+  const block = buildEntryBootstrapBlock({
+    registryImportPath,
+    sessionImportPath,
+    screenImportPath,
+    sessionHasCapabilities: Boolean(opts.sessionHasCapabilities),
+  });
+  const next = insertBlockAfterLastImport(stripped.trimEnd(), block);
+  return { changed: true, source: next.endsWith('\n') ? next : `${next}\n` };
+}
+
+// Idempotently rewrite an existing entry-bootstrap block to carry the generated
+// SCREEN-TRUTH connection (fourth pass, after screen wiring). Preserves the
+// registries and session earlier passes added. Returns { changed, source, reason? }.
+function addScreenToBootstrapSource(source, screenImportPath) {
+  if (!source.includes(ORB_SCRIPT_START)) return { changed: false, source, reason: 'not-mounted' };
+  if (/\n\s*getCurrentRoute:\s/.test(source.slice(source.indexOf(ORB_SCRIPT_START)))) {
+    return { changed: false, source, reason: 'already' };
+  }
+  const registryImportPath = extractBootstrapImportPath(source, BOOTSTRAP_REGISTRY_EXPORT);
+  const sessionImportPath = extractBootstrapImportPath(source, SESSION_IS_AUTH_EXPORT);
+  const sessionHasCapabilities = Boolean(extractBootstrapImportPath(source, SESSION_CAPS_EXPORT));
   const stripped = stripMarkedRegion(source, ORB_SCRIPT_START, ORB_SCRIPT_END).replace(/\n{3,}$/, '\n');
-  const block = buildEntryBootstrapBlock({ registryImportPath, sessionImportPath });
+  const block = buildEntryBootstrapBlock({
+    registryImportPath,
+    sessionImportPath,
+    screenImportPath,
+    sessionHasCapabilities,
+  });
   const next = insertBlockAfterLastImport(stripped.trimEnd(), block);
   return { changed: true, source: next.endsWith('\n') ? next : `${next}\n` };
 }
@@ -244,7 +292,8 @@ function addRegistriesToMountSource(source, exportName, importPath) {
 // `getUserId={fyodosGetUserId}` + the import. Skips (never overrides) a mount
 // where the developer already wired their own isAuthenticated. Same
 // reversibility model as addRegistriesToMountSource.
-function addSessionToMountSource(source, importPath) {
+function addSessionToMountSource(source, importPath, opts = {}) {
+  const withCapabilities = Boolean(opts.sessionHasCapabilities);
   const tagRe = /([ \t]*)<FiodosAgent\b[\s\S]*?\/>/;
   const m = source.match(tagRe);
   if (!m) return { changed: false, source, reason: 'not-mounted' };
@@ -259,15 +308,47 @@ function addSessionToMountSource(source, importPath) {
   const propMatch = tag.match(/\n([ \t]*)(?:apiKey|api-key|apiUrl|baseUrl|registries)/);
   const propIndent = propMatch ? propMatch[1] : `${baseIndent}  `;
   const hasUserId = /\bgetUserId=/.test(tag);
+  const addCaps = withCapabilities && !/\bgetSessionCapabilities=/.test(tag);
   const props =
     `\n${propIndent}isAuthenticated={${SESSION_IS_AUTH_EXPORT}}` +
-    (hasUserId ? '' : `\n${propIndent}getUserId={${SESSION_USER_ID_EXPORT}}`);
+    (hasUserId ? '' : `\n${propIndent}getUserId={${SESSION_USER_ID_EXPORT}}`) +
+    (addCaps ? `\n${propIndent}getSessionCapabilities={${SESSION_CAPS_EXPORT}}` : '');
   const newTag = tag.replace(/\n?[ \t]*\/>$/, `${props}\n${baseIndent}/>`);
   let next = source.replace(tag, newTag);
-  const names = hasUserId
-    ? SESSION_IS_AUTH_EXPORT
-    : `${SESSION_IS_AUTH_EXPORT}, ${SESSION_USER_ID_EXPORT}`;
-  const importLine = `import { ${names} } from '${importPath}';`;
+  const nameList = [SESSION_IS_AUTH_EXPORT];
+  if (!hasUserId) nameList.push(SESSION_USER_ID_EXPORT);
+  if (addCaps) nameList.push(SESSION_CAPS_EXPORT);
+  const importLine = `import { ${nameList.join(', ')} } from '${importPath}';`;
+  if (!next.includes(importLine)) {
+    next = insertImportAfterLastImport(next, importLine);
+  }
+  return { changed: true, source: next };
+}
+
+// Idempotently connect the generated SCREEN-TRUTH module to the mounted
+// <FiodosAgent/>: adds `getCurrentRoute={fyodosGetCurrentRoute}` + the import.
+// Skips (never overrides) a mount where the developer already wired their own
+// getCurrentRoute. Same reversibility model as addSessionToMountSource.
+function addScreenToMountSource(source, importPath) {
+  const tagRe = /([ \t]*)<FiodosAgent\b[\s\S]*?\/>/;
+  const m = source.match(tagRe);
+  if (!m) return { changed: false, source, reason: 'not-mounted' };
+  const tag = m[0];
+  if (new RegExp(`getCurrentRoute=\\{${escapeRe(SCREEN_ROUTE_EXPORT)}\\}`).test(tag)) {
+    return { changed: false, source, reason: 'already' };
+  }
+  if (/\bgetCurrentRoute=/.test(tag)) {
+    return { changed: false, source, reason: 'dev-wired' };
+  }
+  const baseIndent = m[1] || '';
+  const propMatch = tag.match(/\n([ \t]*)(?:apiKey|api-key|apiUrl|baseUrl|registries)/);
+  const propIndent = propMatch ? propMatch[1] : `${baseIndent}  `;
+  const newTag = tag.replace(
+    /\n?[ \t]*\/>$/,
+    `\n${propIndent}getCurrentRoute={${SCREEN_ROUTE_EXPORT}}\n${baseIndent}/>`,
+  );
+  let next = source.replace(tag, newTag);
+  const importLine = `import { ${SCREEN_ROUTE_EXPORT} } from '${importPath}';`;
   if (!next.includes(importLine)) {
     next = insertImportAfterLastImport(next, importLine);
   }
@@ -732,7 +813,10 @@ module.exports = {
   addRegistriesToBootstrapSource,
   addSessionToMountSource,
   addSessionToBootstrapSource,
+  addScreenToMountSource,
+  addScreenToBootstrapSource,
   buildEntryBootstrapBlock,
   IMPORT_NAME,
   WRAPPER_BASENAME,
+  SESSION_CAPS_EXPORT,
 };