@fiodos/cli 0.1.14 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "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/index.js

@@ -93,7 +93,7 @@ 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 { wireWebOrb, reportWireResult, connectOrbRegistries, reportRegistriesResult } = require('./wireWeb');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
 const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
 const { scoreSurface, computeSurface } = require('./scoreSurface');
@@ -526,6 +526,9 @@ async function main() {
 
       // --no-orb-wire skips ONLY the orb mount (useful to test handler wiring in
       // isolation without modifying the app's entrypoint / package.json).
+      let orbProofPosted = false;
+      let orbMounted = false;
+      let orbMountFile = '';
       if (!process.argv.includes('--no-orb-wire')) {
         setLabel(orbMountSpinnerLabel(platform));
         if (!assumeYes) pause();
@@ -538,16 +541,22 @@ async function main() {
         });
         if (!assumeYes) resume();
         report(() => reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() }));
+        orbMounted = result.status === 'added' || result.status === 'already';
         if (
           publishing &&
           apiKey &&
           (result.status === 'added' || result.status === 'already')
         ) {
           // Records the install proof so the dashboard onboarding orb check can
-          // complete without booting the app. If the backend can't record it
-          // (e.g. an outdated deployment without the endpoint), keep it as a
-          // dev-only trace — it is not actionable noise for the end developer.
-          const proof = await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
+          // complete without booting the app. We post 'pending' here: the orb is
+          // mounted, but action wiring (below) has NOT happened yet — so the
+          // dashboard must keep showing "installing" until we post the terminal
+          // status after wireHandlers. If the backend can't record it (e.g. an
+          // outdated deployment without the endpoint), keep it as a dev-only
+          // trace — it is not actionable noise for the end developer.
+          orbMountFile = result.file || '';
+          const proof = await postOrbWired({ apiKey, apiUrl, file: orbMountFile, actionsStatus: 'pending' });
+          orbProofPosted = true;
           if (proof && proof.ok === false && proof.reason !== 'no-api-key') {
             logDev(`[orb-wired] install proof not recorded (status=${proof.status || proof.reason}); dashboard check will rely on a runtime ping`);
           }
@@ -559,6 +568,40 @@ async function main() {
       const handlerResult = await wireHandlers(analysisRoot, handlerOpts);
       if (!assumeYes) resume();
       report(() => reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() }));
+
+      // Second pass — connect the generated registry to the mounted orb so it
+      // EXECUTES actions, not just navigates. Removes the manual "paste
+      // registries={…}" step. Only when the orb is mounted AND there are
+      // auto-wired handlers (autoCount > 0): nav-only / all-manual apps don't
+      // need a registry and are left untouched. Idempotent + reversible.
+      const handlerApplied =
+        handlerResult &&
+        (handlerResult.status === 'applied' || handlerResult.status === 'applied-untested') &&
+        (handlerResult.autoCount || 0) > 0 &&
+        handlerResult.registryFile;
+      if (orbMounted && handlerApplied && !process.argv.includes('--no-orb-wire')) {
+        const connected = connectOrbRegistries(analysisRoot, {
+          registryFileAbs: handlerResult.registryFile,
+        });
+        report(() => reportRegistriesResult(connected, fyodosTermColors(), { quiet: !isVerbose() }));
+      }
+
+      // Finalize the install proof: now that the (slow) action wiring is done,
+      // tell the dashboard the terminal status so its "actions connected" tick
+      // turns green for real — never before wiring actually finished. Only do
+      // this when we already posted the mount proof, so --no-orb-wire and
+      // runtime-only flows don't get a spurious install record.
+      if (orbProofPosted) {
+        const { status, total, done } = actionsWiredFromHandlerResult(handlerResult);
+        await postOrbWired({
+          apiKey,
+          apiUrl,
+          file: orbMountFile,
+          actionsStatus: status,
+          actionsTotal: total,
+          actionsDone: done,
+        });
+      }
     };
 
     if (publishing) {
@@ -870,16 +913,29 @@ async function publishManifest(manifest, meta, analysisToken = null, opts = {})
  * 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 }) {
+async function postOrbWired({
+  apiKey,
+  apiUrl,
+  file,
+  actionsStatus = 'pending',
+  actionsTotal = 0,
+  actionsDone = 0,
+}) {
   if (!apiKey) return { ok: false, reason: 'no-api-key' };
   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' }),
+      body: JSON.stringify({
+        file: file || '',
+        platform: 'web',
+        actionsStatus,
+        actionsTotal,
+        actionsDone,
+      }),
     });
     if (res.ok) {
-      logDev(`[orb-wired] install proof recorded (${file || 'web'})`);
+      logDev(`[orb-wired] install proof recorded (${file || 'web'}, actions=${actionsStatus} ${actionsDone}/${actionsTotal})`);
       return { ok: true };
     }
     logDev(`[orb-wired] could not record install proof: HTTP ${res.status}`);
@@ -889,6 +945,35 @@ async function postOrbWired({ apiKey, apiUrl, file }) {
     return { ok: false, reason: e.message || String(e) };
   }
 }
+
+// Map a wireHandlers() result to the terminal action-wiring status the backend
+// records, plus how many actions ended up wired. Drives the onboarding's third
+// "actions connected" tick so it only goes green once wiring truly finished.
+function actionsWiredFromHandlerResult(handlerResult) {
+  const r = handlerResult || {};
+  const total = Number(r.autoCount || 0) + Number(r.manualCount || 0);
+  const done = Number(r.autoCount || 0);
+  let status;
+  switch (r.status) {
+    case 'no-actions':
+      status = 'none';
+      break;
+    case 'skipped':
+      status = 'skipped';
+      break;
+    case 'reverted':
+    case 'failed':
+      status = 'failed';
+      break;
+    case 'applied':
+    case 'applied-untested':
+      status = r.partial ? 'partial' : 'complete';
+      break;
+    default:
+      status = 'complete';
+  }
+  return { status, total, done };
+}
 async function verifyOrbCanFetch({ apiKey, apiUrl }) {
   try {
     const res = await fetch(`${apiUrl}/v1/client/manifest`, {

package/src/wireHandlers.js

@@ -736,13 +736,15 @@ function buildRegistryModule(plan, opts = {}) {
   }
 
   // Self-contained types (no @fyodos import) so the file typechecks even before
-  // the SDK is installed; the shape stays structurally compatible with
-  // ActionRegistries when passed to <FiodosAgent registries={...}/>.
+  // the SDK is installed; the shape MUST stay assignable to @fiodos/core's
+  // ActionRegistries so `<FiodosAgent registries={...}/>` type-checks. In
+  // particular idempotencyCheckers must match IdempotencyChecker —
+  // `(context) => Promise<{ alreadyApplied; message? }>` — not a boolean.
   const typeDefs = ts
     ? 'type FiodosActionResult = { success: boolean; data?: Record<string, unknown>; error?: string };\n' +
       'type FiodosRegistries = {\n' +
       '  handlers: Record<string, (params: Record<string, any>) => Promise<FiodosActionResult>>;\n' +
-      '  idempotencyCheckers: Record<string, (params: Record<string, any>) => boolean | Promise<boolean>>;\n' +
+      '  idempotencyCheckers: Record<string, (context: Record<string, any>) => Promise<{ alreadyApplied: boolean; message?: string }>>;\n' +
       '};\n'
     : '';
   const resultType = ts ? ': Promise<FiodosActionResult>' : '';
@@ -751,14 +753,11 @@ function buildRegistryModule(plan, opts = {}) {
   const handlerBlocks = plan.auto.map((e) => {
     const takesParams = e.usesParams != null ? e.usesParams : /\bparams\b/.test(e.callExpr);
     const arg = takesParams ? `params${paramsType}` : `_params${paramsType}`;
-    const confNote = e.requireConfirmation
-      ? '\n      // Confirmation action: the Fiodos engine already asked for confirmation BEFORE calling here.'
-      : '';
     // `: unknown` lets the truthiness test below be legal even when the wired
     // call returns void (e.g. db.delete(...)) — otherwise TS errors on `result &&`.
     const resultDecl = ts ? 'const result: unknown' : 'const result';
     return (
-      `    ${e.handler}: async (${arg})${resultType} => {${confNote}\n` +
+      `    ${e.handler}: async (${arg})${resultType} => {\n` +
       `      try {\n` +
       `        ${resultDecl} = await Promise.resolve(${e.callExpr});\n` +
       `        return { success: true, data: (result && typeof result === 'object') ? result as Record<string, unknown> : { result } };\n` +
@@ -772,20 +771,19 @@ function buildRegistryModule(plan, opts = {}) {
   // Plain-JS variant: drop the `as` cast.
   const handlerText = (ts ? handlerBlocks.join('\n') : handlerBlocks.join('\n').replace(/ as Record<string, unknown>/g, ''));
 
-  const manualNotes = plan.manual.map(
-    (e) => `    // MANUAL — '${e.intent}' (${e.handler}): ${e.reason}`,
+  // List each handler that needs manual wiring once. Skip any handler already
+  // auto-wired above (the same handler name can back both an auto-wired and a
+  // manual intent — listing it as "manual" would contradict the wired entry).
+  const autoHandlers = new Set(plan.auto.map((e) => e.handler));
+  const manualHandlers = [...new Set(plan.manual.map((e) => e.handler))].filter(
+    (h) => !autoHandlers.has(h),
+  );
+  const manualNotes = manualHandlers.map(
+    (h) => `    // ${h}: needs manual wiring — see ${DOC_BASENAME}`,
   );
 
   const header =
-    `/**\n` +
-    ` * ${GENERATED_MARKER}.\n` +
-    ` * Do not edit by hand: re-run the Fiodos installer to regenerate it.\n` +
-    ` * Read ${DOC_BASENAME} (same folder) to see what it wires and why.\n` +
-    ` *\n` +
-    ` * SECURITY: this file only CALLS your functions. It never decides whether a\n` +
-    ` * sensitive action runs — the Fiodos engine applies the manifest confirmations\n` +
-    ` * (requireConfirmation / voiceConfirmation) BEFORE invoking any handler here.\n` +
-    ` */\n`;
+    `/** ${GENERATED_MARKER}. Do not edit — re-run the Fiodos installer to regenerate. */\n`;
 
   const decl = esm
     ? `export const ${REGISTRY_EXPORT}${ts ? ': FiodosRegistries' : ''} = {`
@@ -801,8 +799,6 @@ function buildRegistryModule(plan, opts = {}) {
     `${handlerText}\n` +
     (manualNotes.length ? `${manualNotes.join('\n')}\n` : '') +
     `  },\n` +
-    `  // Idempotency checkers read your app state; implement them by hand if\n` +
-    `  // an action declares idempotencyCheck (see ${DOC_BASENAME}).\n` +
     `  idempotencyCheckers: {},\n` +
     `};\n` +
     (esm ? '' : `\nmodule.exports = { ${REGISTRY_EXPORT} };\n`);
@@ -821,12 +817,7 @@ function buildBridgeModule(opts = {}) {
   const esm = opts.esm !== false;
   const header =
     `${GENERATED_FILE_DIRECTIVES}` +
-    `/**\n` +
-    ` * ${GENERATED_MARKER} (bridge holder).\n` +
-    ` * Do not edit by hand. Your component registers its real functions here and the\n` +
-    ` * generated handlers invoke them. This is what connects the agent to the state\n` +
-    ` * living inside your components, without creating disconnected instances.\n` +
-    ` */\n`;
+    `/** ${GENERATED_MARKER} (bridge holder). Do not edit — re-run the Fiodos installer to regenerate. */\n`;
   if (ts) {
     return (
       `${header}\n` +
@@ -964,134 +955,48 @@ function confLabel(e) {
 function buildHandlerDoc(plan, ctx = {}) {
   const {
     appName = 'your app', framework = 'web', registryRel = '', mountSnippet = '',
-    bridgeRel = '', edits = [], verification = null,
+    bridgeRel = '', edits = [],
   } = ctx;
-  const L = [];
-  L.push('# Fiodos action wiring (handler wiring)');
-  L.push('');
-  L.push(
-    'This document describes **exactly** what Fiodos will do to connect the ' +
-      'actions detected in your app with the real functions that run them. ' +
-      '**Nothing is applied until you accept in the terminal.**',
-  );
-  L.push('');
   const review = plan.review || plan.manual || [];
-  const aiCount = plan.auto.filter((e) => e.source === 'ai').length;
-  L.push(`- App: **${appName}**`);
-  L.push(`- Detected framework: **${framework}**`);
-  L.push(`- Actions that will be wired automatically: **${plan.auto.length}** ` +
-    `(${aiCount} wired by the AI, ${plan.auto.length - aiCount} by the mechanical fallback detector)`);
-  L.push(`- Actions that need review: **${review.length}**`);
+  const bridgeEntries = plan.auto.filter((e) => e.kind === 'bridge');
+  const confirmed = plan.entries.filter((e) => e.requireConfirmation);
+  const L = [];
+
+  L.push('# Fiodos — action wiring');
   L.push('');
-  L.push('## How is this wiring generated?');
+  L.push('Connects each action in your manifest to the real function in your app that runs it.');
   L.push('');
-  L.push(
-    'The **same AI** that analyzed your code to detect the actions also proposed ' +
-      'how to run them: which real function/module to call and how to map the parameters. ' +
-      'Then a **mechanical verifier** checks that every referenced symbol ' +
-      'really exists in your code before writing anything. If the AI proposes something ' +
-      'the verifier cannot find, that action is left **for review**, never wired blindly.',
-  );
+  L.push(`- App: \`${appName}\``);
+  L.push(`- Framework: \`${framework}\``);
+  L.push(`- Wired automatically: ${plan.auto.length}`);
+  L.push(`- Need manual wiring: ${review.length}`);
   L.push('');
-  if (Array.isArray(verification) && verification.length) {
-    L.push('## Automatic verification (real effect + retries)');
-    L.push('');
-    L.push(
-      'After your "yes", the install **does not trust** that the wiring compiles: for each ' +
-        'action it runs a **wire → verify → diagnose → correct** loop with no ' +
-        'human intervention. Verification checks (1) that the project **still ' +
-        'builds** with that action wired and, when it is safe to simulate, (2) that ' +
-        'invoking the handler **changes the real state** (the task is added, etc.). If an ' +
-        'action fails, the AI receives the **concrete error** and retries with corrected ' +
-        'wiring (up to several attempts). An action is only marked **ready** when it passes ' +
-        'verification; if it is not achieved after the retries, **only that action is ' +
-        'reverted** and marked below as "could not be wired" — never left faking it.',
-    );
-    L.push('');
-    L.push('| Action (intent) | Result | Attempts | Verification | Detail |');
-    L.push('| --- | --- | --- | --- | --- |');
-    for (const v of verification) {
-      const res = v.status === 'ready' ? '✅ ready' : '❌ could not';
-      let lvl = '—';
-      if (v.status === 'ready') {
-        lvl = v.level === 'effect' ? 'real effect (UI)'
-          : v.level === 'unverifiable' ? '⚠️ effect NOT verifiable (review by hand)'
-            : 'compilation';
-      }
-      const detail = String(v.detail || v.error || '').replace(/\|/g, '\\|').slice(0, 160);
-      L.push(`| \`${v.intent}\` | ${res} | ${v.attempts} | ${lvl} | ${detail} |`);
-    }
-    L.push('');
-    L.push('_"real effect (UI)" = the real component was mounted in a test DOM (jsdom) with ' +
-      'the framework\'s standard tooling (React: react-dom; Vue: vue + @vue/compiler-sfc), ' +
-      'the wired handler was invoked and the **change in the UI/state was observed** (the task appears, ' +
-      'the item toggles, etc.). For the data layer (Dexie/store) the effect is observed by running ' +
-      'the action against a real instance. "compilation" = it compiles and the real symbol exists and is ' +
-      'invoked, but the effect could not be safely simulated here. "⚠️ effect NOT verifiable" = ' +
-      'the wiring was applied but the real effect could not be confirmed automatically (component not ' +
-      'mountable in isolation, or a sensitive action that is not fired) — **review/test by hand**. ' +
-      'Sensitive actions (with confirmation) are **never** fired in the test._');
-    L.push('');
-  }
 
-  L.push('## Why is it needed?');
-  L.push('');
-  L.push(
-    'The orb is already mounted, but the agent cannot **run** actions until ' +
-      'each manifest action is connected to your app\'s real function. ' +
-      'This wiring is that bridge: it translates each action (e.g. `addToCart`) into a ' +
-      'call to your function (e.g. `useShop.getState().addToCart(...)`).',
-  );
-  L.push('');
-  const bridgeEntries = plan.auto.filter((e) => e.kind === 'bridge');
-  L.push('## Which files are created / edited');
+  L.push('## Files');
   L.push('');
-  L.push(`- **CREATES** \`${registryRel}\` — the generated handler registry.`);
+  L.push(`- Creates \`${registryRel}\` — the handler registry.`);
   if (bridgeEntries.length && bridgeRel) {
-    L.push(`- **CREATES** \`${bridgeRel}\` — the "bridge" where your component registers its real functions.`);
+    L.push(`- Creates \`${bridgeRel}\` — bridge where your components register live functions.`);
   }
   if (edits.length) {
-    L.push('- **EDITS the following files OF YOURS** (only adds lines marked with ' +
-      '`FYODOS:BRIDGE`, reversible):');
-    for (const ed of edits) L.push(`  - \`${ed.file}\` — registers: ${ed.intents.map((i) => `\`${i}\``).join(', ')}`);
-  } else {
-    L.push('- **No existing file of yours is edited** (all actions were ' +
-      'reachable from a module).');
+    L.push('- Edits (only reversible `FYODOS:BRIDGE` blocks):');
+    for (const ed of edits) L.push(`  - \`${ed.file}\` — ${ed.intents.map((i) => `\`${i}\``).join(', ')}`);
   }
-  L.push('- To enable it, pass the generated registry to `<FiodosAgent/>` (see "How to enable it").');
   L.push('');
 
-  if (edits.length) {
-    L.push('## EXACT changes inside your components');
-    L.push('');
-    L.push('These are the lines Fiodos will add to your files (each block sits between ' +
-      '`FYODOS:BRIDGE:START` / `END` markers, so you can remove or revert them without touching ' +
-      'your own code):');
-    L.push('');
-    for (const ed of edits) {
-      L.push(`### \`${ed.file}\``);
-      L.push('');
-      L.push('After the last `import` line, this is added:');
-      L.push('');
-      L.push('```ts');
-      L.push(ed.importBlock);
-      L.push('```');
-      L.push('');
-      L.push(ed.file.endsWith('.vue')
-        ? 'Right before `</script>`, this is added:'
-        : `Next to the anchor \`${(ed.anchor || '').trim().slice(0, 80)}\`, this is added:`);
-      L.push('');
-      L.push('```ts');
-      L.push(ed.registerBlock.replace(/^\s+/gm, (s) => s)); // keep as-is
-      L.push('```');
-      L.push('');
-    }
-  }
+  L.push('## Enable it');
+  L.push('');
+  L.push('Pass the generated registry to your orb:');
+  L.push('');
+  L.push('```tsx');
+  L.push(mountSnippet || `import { ${REGISTRY_EXPORT} } from './${registryRel.split('/').pop()}';\n\n<FiodosAgent registries={${REGISTRY_EXPORT}} />`);
+  L.push('```');
+  L.push('');
 
   if (plan.auto.length) {
-    L.push(`## Actions that will be wired automatically (${plan.auto.length})`);
+    L.push(`## Wired automatically (${plan.auto.length})`);
     L.push('');
-    L.push('| Action (intent) | How it runs | Where | Parameters | Type | Security |');
+    L.push('| Action | Runs | Where | Params | Type | Confirmation |');
     L.push('| --- | --- | --- | --- | --- | --- |');
     for (const e of plan.auto) {
       const expr = e.kind === 'bridge' ? e.bridge.invoke : e.callExpr;
@@ -1100,84 +1005,43 @@ function buildHandlerDoc(plan, ctx = {}) {
       const params = e.manifestParams.length
         ? e.manifestParams.map((p) => `${p.name}${p.required ? '*' : ''}`).join(', ')
         : '—';
-      const kind = e.kind === 'bridge'
-        ? 'bridge (edits your component)'
-        : (e.source === 'ai' ? 'module (AI)' : 'module (mechanical)');
+      const kind = e.kind === 'bridge' ? 'bridge' : 'module';
       L.push(`| \`${e.intent}\` | ${call} | ${where} | ${params} | ${kind} | ${confLabel(e)} |`);
     }
     L.push('');
-    L.push('_`*` = required parameter. Each call was proposed by the AI reading your ' +
-      'code and **confirmed by the verifier** (the symbols exist). Parameters ' +
-      'are mapped **by name**, never by position._');
+    L.push('`*` = required parameter. Parameters are mapped by name.');
     L.push('');
   }
 
   if (review.length) {
-    L.push(`## Actions that need REVIEW (${review.length})`);
+    L.push(`## Needs manual wiring (${review.length})`);
     L.push('');
-    L.push(
-      'For these actions, neither did the AI propose **verifiable** wiring nor did the ' +
-        'mechanical fallback detector find the function safely. Wiring them wrong would be ' +
-        'worse than leaving them unwired, so they are marked for review and we explain why:',
-    );
+    L.push(`Add a handler in \`${registryRel}\` that calls your function and returns \`{ success: true }\` (or \`{ success: false, message }\`).`);
     L.push('');
+    L.push('| Action | Handler | Reason |');
+    L.push('| --- | --- | --- |');
     for (const e of review) {
-      L.push(`### \`${e.intent}\` — ${e.label}`);
-      L.push('');
-      L.push(`- Expected handler: \`${e.handler}\``);
-      if (e.file) L.push(`- Evidence file: \`${e.file}\``);
-      L.push(`- Reason: ${e.reason}`);
-      L.push(
-        `- What to do: add a handler \`${e.handler}\` in \`${registryRel}\` (or in your ` +
-          'own registry) that calls the real function and returns ' +
-          '`{ success: true }` (or `{ success: false, message }`).',
-      );
-      L.push('');
+      // Keep the reason to a clean one-liner: collapse whitespace, drop the
+      // npm/compiler dump after the first `|`, and cap length (no leaked paths).
+      const reason = String(e.reason || '')
+        .split('|')[0]
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 160);
+      L.push(`| \`${e.intent}\` | \`${e.handler}\` | ${reason} |`);
     }
+    L.push('');
   }
 
-  const confirmed = plan.entries.filter((e) => e.requireConfirmation);
   L.push('## Security');
   L.push('');
-  L.push(
-    '- The generated wiring **only calls** your functions. It **never** decides whether a ' +
-      'sensitive action runs: the Fiodos engine applies the manifest confirmations ' +
-      '(`requireConfirmation` / `voiceConfirmation`) **before** invoking ' +
-      'the handler. It is impossible for the auto-wiring to skip a confirmation.',
-  );
+  L.push('- The wiring only calls your functions; the Fiodos engine enforces manifest confirmations (`requireConfirmation` / `voiceConfirmation`) before any handler runs.');
+  L.push('- No secrets are read or embedded — only function names and the parameters the manifest declares.');
   if (confirmed.length) {
-    L.push('- Actions protected by confirmation (the agent will ask to confirm before running them):');
-    for (const e of confirmed) {
-      L.push(`  - \`${e.intent}\` — ${confLabel(e)}.`);
-    }
-  } else {
-    L.push('- None of the detected actions require confirmation in the manifest.');
+    L.push(`- Confirmation-protected actions: ${confirmed.map((e) => `\`${e.intent}\``).join(', ')}.`);
   }
-  L.push('- The wiring does not read, embed or expose secrets; it only references function');
-  L.push('  names and the parameters the manifest already declares.');
   L.push('');
 
-  L.push('## How to enable it');
-  L.push('');
-  if (mountSnippet) {
-    L.push('Pass the generated registry to your `<FiodosAgent/>`:');
-    L.push('');
-    L.push('```tsx');
-    L.push(mountSnippet);
-    L.push('```');
-  } else {
-    L.push('Import `' + REGISTRY_EXPORT + '` from the generated file and pass it as ' +
-      '`registries` to your `<FiodosAgent/>`.');
-  }
-  L.push('');
-  L.push('## If you said "no"');
-  L.push('');
-  L.push(
-    'Your code was not touched. You can implement the wiring yourself following ' +
-      'this document, or re-run the installer to accept the auto-wiring ' +
-      '(`--wire-yes` to accept without prompting).',
-  );
-  L.push('');
   return L.join('\n');
 }
 

package/src/wireWeb.js

@@ -24,6 +24,10 @@ const {
   writeConsentDoc,
   agentJsx,
   envExpr,
+  registryRelImport,
+  addRegistriesToMountSource,
+  addRegistriesToBootstrapSource,
+  buildEntryBootstrapBlock,
   IMPORT_NAME,
   WRAPPER_BASENAME,
 } = require('./wireWebMount');
@@ -60,17 +64,24 @@ function firstExisting(appRoot, rels) {
 
 function detectTarget(appRoot, framework = detectFramework(appRoot)) {
   if (framework === 'vue') {
-    const f = firstExisting(appRoot, ['src/App.vue', 'src/main.ts', 'src/main.js']);
+    // Prefer the entry module (deterministic anchor → bootstrap injection). Fall
+    // back to the SFC <template> strategy only when there is no entry file.
+    const entry = firstExisting(appRoot, ['src/main.ts', 'src/main.js']);
+    if (entry) return { kind: 'vue-entry', file: entry, ext: path.extname(entry), framework };
+    const f = firstExisting(appRoot, ['src/App.vue']);
     return f ? { kind: 'vue', file: f, ext: path.extname(f), framework } : { kind: 'vue', file: null, framework };
   }
   if (framework === 'sveltekit') {
-    const f = firstExisting(appRoot, [
-      'src/routes/+layout.svelte', 'src/routes/+page.svelte', 'src/App.svelte',
-    ]);
-    return f ? { kind: 'sveltekit', file: f, ext: '.svelte', framework } : { kind: 'sveltekit', file: null, framework };
+    // SvelteKit owns the bootstrap (no src/main.ts), but src/hooks.client.ts runs
+    // once in the browser — the ideal, template-free spot. Create it if missing.
+    const existing = firstExisting(appRoot, ['src/hooks.client.ts', 'src/hooks.client.js']);
+    const file = existing || path.join(appRoot, 'src/hooks.client.ts');
+    return { kind: 'sveltekit-hooks', file, ext: path.extname(file), framework };
   }
   if (framework === 'svelte') {
-    const f = firstExisting(appRoot, ['src/App.svelte', 'src/routes/+layout.svelte', 'src/main.ts']);
+    const entry = firstExisting(appRoot, ['src/main.ts', 'src/main.js']);
+    if (entry) return { kind: 'svelte-entry', file: entry, ext: path.extname(entry), framework };
+    const f = firstExisting(appRoot, ['src/App.svelte']);
     return f ? { kind: 'svelte', file: f, ext: '.svelte', framework } : { kind: 'svelte', file: null, framework };
   }
   if (framework === 'angular') {
@@ -160,6 +171,15 @@ function printSnippet(target, framework, colors, appRoot, reason) {
     console.error(`${dim}Reason: ${reason}${reset}\n`);
   }
 
+  // Entry-file bootstrap frameworks: the safe fallback is the same one-shot call
+  // we would have auto-injected into the entry module — no <template> edit.
+  const entryKind = target && /(-entry|-hooks)$/.test(target.kind || '');
+  if (entryKind) {
+    const where = path.relative(appRoot, target.file);
+    console.error(`${dim}In ${where}, after your imports:${reset}\n`);
+    console.error(buildEntryBootstrapBlock());
+    return;
+  }
   if (framework === 'vue') {
     const where = target && target.file ? path.relative(appRoot, target.file) : 'src/App.vue';
     console.error(`${dim}In ${where}:${reset}\n`);
@@ -243,10 +263,23 @@ async function wireWebOrb(appRoot, opts = {}) {
   };
 
   const backups = backupFiles(plan.files);
+  // Files the installer creates from scratch (e.g. SvelteKit src/hooks.client.ts)
+  // are not in `backups`; a revert must DELETE them, not leave an orphan behind.
+  const createdFiles = plan.files.filter((f) => !(f in backups));
+  const revertAll = () => {
+    revertFiles(backups);
+    for (const f of createdFiles) {
+      try {
+        if (fs.existsSync(f)) fs.unlinkSync(f);
+      } catch {
+        /* best-effort */
+      }
+    }
+  };
   try {
     applyMount(plan);
     if (!verifyMounted(plan)) {
-      revertFiles(backups);
+      revertAll();
       printSnippet(target, framework, colors, appRoot, 'post-edit verification failed — FiodosAgent not found in edited files');
       return { status: 'failed', file: plan.rel };
     }
@@ -265,7 +298,7 @@ async function wireWebOrb(appRoot, opts = {}) {
         return { status: 'added', file: plan.rel, test };
       }
       // Build failed with the orb mounted — was the app building WITHOUT it?
-      revertFiles(backups);
+      revertAll();
       const baseline = await build();
       if (baseline.ok) {
         // Built before, fails now → the mount is the regression. Keep it reverted.
@@ -282,7 +315,7 @@ async function wireWebOrb(appRoot, opts = {}) {
     writeConsentDoc(appRoot, plan);
     return { status: 'added', file: plan.rel };
   } catch (err) {
-    revertFiles(backups);
+    revertAll();
     printSnippet(target, framework, colors, appRoot, err.message || String(err));
     return { status: 'failed', file: plan.rel, error: err };
   }
@@ -317,9 +350,121 @@ function reportWireResult(result, colors = {}, opts = {}) {
   }
 }
 
+/**
+ * Second pass (after handler wiring): connect the generated registry to the
+ * already-mounted orb so it EXECUTES actions, not just navigates. This is what
+ * removes the manual "paste registries={…}" step. Idempotent and reversible:
+ * the prop lives inside the FYODOS:ORB block. React-family mounts only —
+ * Vue/Svelte/Angular SDKs receive handlers differently and are left to the doc.
+ * Nav-only apps (no auto-wired handlers) never reach here (the caller gates on
+ * autoCount > 0), so they are not given a needless registries prop.
+ */
+function connectOrbRegistries(appRoot, opts = {}) {
+  const { registryFileAbs, exportName = 'fyodosGeneratedRegistries' } = opts;
+  if (!registryFileAbs || !fs.existsSync(registryFileAbs)) return { status: 'no-registry' };
+
+  const framework = detectFramework(appRoot);
+  const target = detectTarget(appRoot, framework);
+  if (!target || !target.file) return { status: 'no-target' };
+
+  // Entry-file bootstrap (Vue / Svelte / SvelteKit): the registries go INTO the
+  // createFiodosAgent({…}) call we injected into the entry module — same safe,
+  // idempotent, reversible block. No manual "pass registries" step anywhere.
+  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, registryFileAbs);
+    const fileRel = path.relative(appRoot, target.file);
+    const backups = backupFiles([target.file]);
+    try {
+      const res = addRegistriesToBootstrapSource(source, importPath);
+      if (!res.changed) {
+        return { status: res.reason === 'already' ? 'already' : '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 };
+    }
+  }
+
+  // Only React-family mounts accept a `registries={...}` prop.
+  const reactKinds = new Set(['vite', 'next-pages', 'next-app']);
+  if (!reactKinds.has(target.kind)) return { status: 'unsupported-framework', framework };
+
+  // <FiodosAgent/> lives in the client wrapper for the Next App Router, in the
+  // entry/root file otherwise.
+  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, registryFileAbs);
+  const fileRel = path.relative(appRoot, mountFile);
+  const backups = backupFiles([mountFile]);
+  try {
+    const res = addRegistriesToMountSource(source, exportName, importPath);
+    if (!res.changed) {
+      return { status: res.reason === 'already' ? 'already' : '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 };
+  }
+}
+
+function reportRegistriesResult(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} · ${dim || ''}connected actions to the orb (registries=) in ${result.file}${reset || ''}`);
+      break;
+    case 'already':
+      if (quiet) return;
+      console.error(`${tag} · ${dim || ''}orb already wired to actions in ${result.file}${reset || ''}`);
+      break;
+    case 'unsupported-framework':
+      console.error(`${tag} · ${dim || ''}pass the generated registry to your orb manually (see FYODOS_HANDLERS.md)${reset || ''}`);
+      break;
+    case 'failed':
+      console.error(`${tag} · ✗ could not auto-connect actions to the orb${result.file ? ` in ${result.file}` : ''}. See FYODOS_HANDLERS.md.`);
+      break;
+    default:
+      // not-mounted / no-registry / no-target: silent. The orb still navigates,
+      // and the doc shows how to connect actions by hand if needed.
+      break;
+  }
+}
+
 module.exports = {
   wireWebOrb,
   reportWireResult,
+  connectOrbRegistries,
+  reportRegistriesResult,
   detectFramework,
   detectTarget,
 };

package/src/wireWebMount.js

@@ -60,6 +60,75 @@ function insertImportAfterLastImport(source, importLine) {
   return lines.join('\n');
 }
 
+// Insert a multi-line block right after the last top-level import. The block may
+// itself contain import statements — placed after the existing ones they stay
+// valid top-level imports (ESM hoists them anyway). Used by the entry-file
+// bootstrap so the orb starts before the app mounts.
+function insertBlockAfterLastImport(source, block) {
+  const lines = source.split('\n');
+  let lastImport = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^\s*import\b/.test(lines[i])) lastImport = i;
+  }
+  if (lastImport === -1) return `${block}\n\n${source}`;
+  lines.splice(lastImport + 1, 0, '', block);
+  return lines.join('\n');
+}
+
+// ── Entry-file bootstrap (Vue / Svelte / SvelteKit) ───────────────────────────
+// Instead of editing a framework <template> (no deterministic anchor, fragile),
+// we inject a one-shot createFiodosAgent() call into the app's entry module
+// (src/main.ts, hooks.client.ts). The orb mounts itself to document.body, so it
+// never needs to live in the component tree. The whole call lives between
+// FYODOS:ORB markers → idempotent (re-runs strip & rewrite) and reversible.
+const BOOTSTRAP_ALIAS = '__fiodosCreateAgent';
+const BOOTSTRAP_REGISTRY_EXPORT = 'fyodosGeneratedRegistries';
+
+function buildEntryBootstrapBlock(opts = {}) {
+  const { registryImportPath } = opts;
+  const lines = [];
+  lines.push(ORB_SCRIPT_START);
+  lines.push(`import { createFiodosAgent as ${BOOTSTRAP_ALIAS} } from '@fiodos/web-core';`);
+  if (registryImportPath) {
+    lines.push(`import { ${BOOTSTRAP_REGISTRY_EXPORT} } from '${registryImportPath}';`);
+  }
+  lines.push(`${BOOTSTRAP_ALIAS}({`);
+  lines.push('  apiKey: import.meta.env.VITE_FYODOS_API_KEY,');
+  lines.push('  baseUrl: import.meta.env.VITE_FYODOS_API_URL,');
+  if (registryImportPath) lines.push(`  registries: ${BOOTSTRAP_REGISTRY_EXPORT},`);
+  lines.push('  mount: true,');
+  lines.push('});');
+  lines.push(ORB_SCRIPT_END);
+  return lines.join('\n');
+}
+
+function injectEntryBootstrap(plan, opts = {}) {
+  const file = plan.target.file;
+  let source = fs.existsSync(file) ? readFile(file) : '';
+  source = stripMarkedRegion(source, ORB_SCRIPT_START, ORB_SCRIPT_END).replace(/\n{3,}$/, '\n');
+  const block = buildEntryBootstrapBlock(opts);
+  let next;
+  if (!source.trim()) {
+    next = `${block}\n`;
+  } else {
+    next = insertBlockAfterLastImport(source, block);
+  }
+  writeFile(file, next.endsWith('\n') ? next : `${next}\n`);
+}
+
+// Idempotently rewrite an existing entry-bootstrap block to carry the generated
+// registries (second pass, after handler wiring). Returns { changed, source, reason? }.
+function addRegistriesToBootstrapSource(source, registryImportPath) {
+  if (!source.includes(ORB_SCRIPT_START)) return { changed: false, source, reason: 'not-mounted' };
+  if (/\n\s*registries:\s/.test(source.slice(source.indexOf(ORB_SCRIPT_START)))) {
+    return { changed: false, source, reason: 'already' };
+  }
+  const stripped = stripMarkedRegion(source, ORB_SCRIPT_START, ORB_SCRIPT_END).replace(/\n{3,}$/, '\n');
+  const block = buildEntryBootstrapBlock({ registryImportPath });
+  const next = insertBlockAfterLastImport(stripped.trimEnd(), block);
+  return { changed: true, source: next.endsWith('\n') ? next : `${next}\n` };
+}
+
 function envExpr(framework, kind, ts) {
   if (framework === 'vite' || framework === 'vue' || framework === 'svelte' || framework === 'sveltekit') {
     if (kind === 'key') {
@@ -87,6 +156,42 @@ function isAlreadyMounted(source) {
   return /FiodosAgent|fyodos-agent|FYODOS:ORB:START/.test(source);
 }
 
+// Import specifier (no extension, normalized slashes) from the file holding the
+// orb mount to the generated registry module.
+function registryRelImport(fromFile, registryAbs) {
+  let rel = path
+    .relative(path.dirname(fromFile), registryAbs)
+    .replace(/\\/g, '/')
+    .replace(/\.(tsx?|jsx?|mjs|cjs)$/, '');
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  return rel;
+}
+
+// Idempotently add `registries={EXPORT}` to the mounted <FiodosAgent/> and
+// import EXPORT from the generated registry. React-family mounts only. The prop
+// lands INSIDE the FYODOS:ORB block, so removing that block reverts it; the
+// import follows the existing FiodosAgent import convention (added once,
+// harmless if the block is later removed). Returns { changed, source, reason? }.
+function addRegistriesToMountSource(source, exportName, importPath) {
+  if (new RegExp(`registries=\\{${escapeRe(exportName)}\\}`).test(source)) {
+    return { changed: false, source, reason: 'already' };
+  }
+  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];
+  const baseIndent = m[1] || '';
+  const propMatch = tag.match(/\n([ \t]*)(?:apiKey|api-key|apiUrl|baseUrl)/);
+  const propIndent = propMatch ? propMatch[1] : `${baseIndent}  `;
+  const newTag = tag.replace(/\n?[ \t]*\/>$/, `\n${propIndent}registries={${exportName}}\n${baseIndent}/>`);
+  let next = source.replace(tag, newTag);
+  const importLine = `import { ${exportName} } from '${importPath}';`;
+  if (!next.includes(importLine)) {
+    next = insertImportAfterLastImport(next, importLine);
+  }
+  return { changed: true, source: next };
+}
+
 /**
  * Assess whether we can inject safely. Returns { ok, reason?, strategy, files, rel }.
  */
@@ -95,6 +200,19 @@ function assessMount(target, framework, appRoot) {
     return { ok: false, reason: 'could not locate a framework entry file (e.g. src/main.tsx, App.vue, +layout.svelte)' };
   }
   const rel = path.relative(appRoot, target.file);
+
+  // Entry-file bootstrap (Vue / Svelte / SvelteKit). The orb is injected into the
+  // app's entry module, not a <template>. For SvelteKit hooks the file may not
+  // exist yet — we create it (safe: a brand-new client hook only adds our block).
+  const entryKinds = new Set(['vue-entry', 'svelte-entry', 'sveltekit-hooks']);
+  if (entryKinds.has(target.kind)) {
+    const exists = fs.existsSync(target.file);
+    if (exists && isAlreadyMounted(readFile(target.file))) {
+      return { ok: false, reason: 'orb already present', already: true, rel };
+    }
+    return { ok: true, strategy: 'entry-bootstrap', files: [target.file], rel, framework, target, createIfMissing: !exists };
+  }
+
   const source = readFile(target.file);
   if (isAlreadyMounted(source)) {
     return { ok: false, reason: 'orb already present', already: true, rel };
@@ -105,14 +223,22 @@ function assessMount(target, framework, appRoot) {
       if (!source.includes('</body>')) {
         return { ok: false, reason: `${rel} has no </body> — cannot mount the orb wrapper safely` };
       }
-      return { ok: true, strategy: 'next-app', files: [target.file], rel, framework, target };
+      // The client wrapper we create lives next to the layout. Listing it in
+      // `files` means a revert DELETES it (it isn't in the backups) instead of
+      // leaving an orphan that imports @fiodos/react.
+      const ts = target.ext === '.tsx';
+      const wrapperFile = path.join(path.dirname(target.file), `${WRAPPER_BASENAME}${ts ? '.tsx' : '.jsx'}`);
+      return { ok: true, strategy: 'next-app', files: [target.file, wrapperFile], rel, framework, target };
     }
     case 'next-pages':
     case 'vite': {
       if (/createRoot\s*\(/.test(source) && /\.render\s*\(/.test(source)) {
         return { ok: true, strategy: 'vite-main', files: [target.file], rel, framework, target };
       }
-      if (/return\s*\([\s\S]*/.test(source)) {
+      // Accept any component that returns JSX — `return (` OR a bare `return <…/>`
+      // (the create-next-app default `_app.tsx`). We wrap the returned element in
+      // a fragment so the orb sits beside it without breaking adjacent-JSX rules.
+      if (/return\s*[<(]/.test(source)) {
         return { ok: true, strategy: 'react-return', files: [target.file], rel, framework, target };
       }
       return { ok: false, reason: `${rel} is not a recognizable React entry (no createRoot().render() or JSX return)` };
@@ -163,8 +289,13 @@ function resolveAngularTemplate(tsFile, tsSource) {
 }
 
 function describePlan(plan) {
-  const lines = [`Will edit: ${plan.files.map((f) => path.basename(f)).join(', ')}`];
+  const action = plan.createIfMissing ? 'Will create' : 'Will edit';
+  const lines = [`${action}: ${plan.files.map((f) => path.basename(f)).join(', ')}`];
   switch (plan.strategy) {
+    case 'entry-bootstrap':
+      lines.push('Add createFiodosAgent({ apiKey, baseUrl, mount }) after the imports');
+      lines.push('Orb self-mounts to document.body (no <template> edit, marked FYODOS:ORB:*)');
+      break;
     case 'next-app':
       lines.push(`Create ${WRAPPER_BASENAME} client wrapper next to layout`);
       lines.push(`Import wrapper and mount before </body>`);
@@ -262,6 +393,57 @@ function injectViteMain(plan) {
   writeFile(target.file, source);
 }
 
+// Wrap the component's last `return <jsx>` (with or without parentheses) in a
+// fragment that holds the original element AND the orb. Wrapping ANY single
+// returned expression as `<>{expr}{orb}</>` is always valid JSX, so this is the
+// universal, adjacent-JSX-safe fallback when there is no closing-tag anchor to
+// slot into (e.g. the create-next-app default `return <Component {...pageProps} />`).
+// Returns the new source, or null when no returnable JSX expression is found.
+function wrapLastReturnInFragment(source, orbJsx) {
+  const kw = /\breturn\b/g;
+  let m;
+  let retIdx = -1;
+  while ((m = kw.exec(source))) retIdx = m.index;
+  if (retIdx === -1) return null;
+
+  let i = retIdx + 'return'.length;
+  while (i < source.length && /\s/.test(source[i])) i += 1;
+  if (source[i] !== '(' && source[i] !== '<') return null;
+  const exprStart = i;
+
+  // Scan to the end of this one expression: stop at an unmatched ')' or '}'
+  // (the wrapping paren / function body) or a top-level ';'.
+  let round = 0;
+  let curly = 0;
+  let end = source.length;
+  for (let j = exprStart; j < source.length; j += 1) {
+    const c = source[j];
+    if (c === '(') round += 1;
+    else if (c === ')') {
+      if (round === 0) { end = j; break; }
+      round -= 1;
+    } else if (c === '{') curly += 1;
+    else if (c === '}') {
+      if (curly === 0) { end = j; break; }
+      curly -= 1;
+    } else if (c === ';' && round === 0 && curly === 0) { end = j; break; }
+  }
+
+  let expr = source.slice(exprStart, end).trim();
+  if (expr.startsWith('(') && expr.endsWith(')')) expr = expr.slice(1, -1).trim();
+  if (!expr) return null;
+
+  const ind = '    ';
+  const orbIndented = orbJsx
+    .split('\n')
+    .map((l) => (l ? `${ind}  ${l}` : l))
+    .join('\n');
+  const wrapped =
+    `(\n${ind}<>\n${ind}  ${expr}\n${orbIndented}\n${ind}</>\n${ind.slice(2)})`;
+
+  return source.slice(0, exprStart) + wrapped + source.slice(end);
+}
+
 function injectReactReturn(plan) {
   const { target, framework } = plan;
   const ts = target.ext === '.tsx';
@@ -281,12 +463,11 @@ function injectReactReturn(plan) {
       return;
     }
   }
-  const ret = source.lastIndexOf('return (');
-  if (ret === -1) throw new Error('no return ( found');
-  const close = source.indexOf(');', ret);
-  if (close === -1) throw new Error('no return close');
-  source = `${source.slice(0, close)}\n      ${orbBlock}\n    ${source.slice(close)}`;
-  writeFile(target.file, source);
+  // No closing-tag anchor (e.g. `return <Component {...pageProps} />`): wrap the
+  // returned element + orb in a fragment so adjacent JSX is always valid.
+  const wrapped = wrapLastReturnInFragment(source, orbBlock);
+  if (wrapped == null) throw new Error('no returnable JSX expression found');
+  writeFile(target.file, wrapped);
 }
 
 function injectVueSfc(plan) {
@@ -363,6 +544,9 @@ function injectAngularComponent(plan) {
 
 function applyMount(plan) {
   switch (plan.strategy) {
+    case 'entry-bootstrap':
+      injectEntryBootstrap(plan);
+      break;
     case 'next-app':
       injectNextApp(plan);
       break;
@@ -398,18 +582,17 @@ function writeConsentDoc(appRoot, plan) {
   const dir = path.join(appRoot, 'src', 'fyodos');
   fs.mkdirSync(dir, { recursive: true });
   const doc = [
-    '# Fiodos orb mount (auto-generated)',
+    '# Fiodos — orb mount',
     '',
-    `Date: ${new Date().toISOString()}`,
-    `Strategy: ${plan.strategy}`,
-    `Files edited:`,
-    ...plan.files.map((f) => `- ${path.relative(appRoot, f)}`),
+    'Mounts `<FiodosAgent />` in your app. The orb connects to the Fiodos backend',
+    'with your project API key and fetches its manifest and appearance on its own;',
+    'nothing else to paste.',
     '',
-    'Changes are wrapped in FYODOS:ORB:START / FYODOS:ORB:END markers.',
-    'Remove those blocks (and the Fiodos import) to revert manually.',
+    `- Strategy: \`${plan.strategy}\``,
+    `- Files: ${plan.files.map((f) => `\`${path.relative(appRoot, f)}\``).join(', ')}`,
     '',
-    'Planned edits:',
-    ...describePlan(plan).map((l) => `- ${l}`),
+    'Edits sit between `FYODOS:ORB:START` / `FYODOS:ORB:END` markers. Remove those',
+    'blocks (and the Fiodos import) to revert.',
     '',
   ].join('\n');
   writeFile(path.join(dir, 'FYODOS_ORB_MOUNT.md'), doc);
@@ -430,6 +613,10 @@ module.exports = {
   revertFiles,
   writeConsentDoc,
   isAlreadyMounted,
+  registryRelImport,
+  addRegistriesToMountSource,
+  addRegistriesToBootstrapSource,
+  buildEntryBootstrapBlock,
   IMPORT_NAME,
   WRAPPER_BASENAME,
 };