fraim-framework 2.0.189 → 2.0.191

package/dist/src/ai-hub/desktop-main.js

@@ -62,6 +62,55 @@ function isTrustedInAppNavigation(targetUrl, hubUrl) {
         return false;
     }
 }
+function connectedSurfaceParam(value) {
+    return value === 'account' || value === 'analytics' || value === 'brain' ? value : null;
+}
+function connectedSurfaceForHostedUrl(targetUrl, hubUrl) {
+    try {
+        const parsed = new URL(targetUrl);
+        const hub = new URL(hubUrl);
+        const remote = new URL((0, remote_hub_gateway_1.resolveFraimRemoteUrl)());
+        if (parsed.origin === hub.origin || parsed.origin !== remote.origin)
+            return null;
+        const pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+        if (pathname === '/account')
+            return 'account';
+        if (pathname === '/analytics')
+            return 'analytics';
+        if (pathname === '/fraim-brain' || pathname === '/fraim-brain.html')
+            return 'brain';
+        if (pathname === '/ai-hub') {
+            return connectedSurfaceParam(parsed.searchParams.get('connected') || parsed.searchParams.get('open'));
+        }
+        if (pathname === '/auth/sign-in.html' || pathname === '/auth/recovery.html' || pathname === '/auth/error.html') {
+            return connectedSurfaceParam(parsed.searchParams.get('surface'));
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function localHubConnectedUrl(hubUrl, surface, sourceUrl) {
+    const target = new URL(hubUrl);
+    target.search = '';
+    target.hash = '';
+    target.searchParams.set('connected', surface);
+    if (sourceUrl) {
+        try {
+            const source = new URL(sourceUrl);
+            const apiKey = source.searchParams.get('api-key') || source.searchParams.get('apiKey');
+            if (apiKey)
+                target.searchParams.set('api-key', apiKey);
+        }
+        catch { /* ignore malformed source URLs */ }
+    }
+    return target.toString();
+}
+function wrappedHostedNavigationUrl(targetUrl, hubUrl) {
+    const surface = connectedSurfaceForHostedUrl(targetUrl, hubUrl);
+    return surface ? localHubConnectedUrl(hubUrl, surface, targetUrl) : null;
+}
 // ---------------------------------------------------------------------------
 // Tray icon resolution — prefers bundled icon, falls back to a 1×1 empty image
 // so the app never crashes if assets aren't present.
@@ -216,11 +265,42 @@ async function createWindow(url) {
         mainWindow.on('closed', () => electron_1.nativeTheme.removeListener('updated', applyOverlay));
     }
     mainWindow.webContents.setWindowOpenHandler(({ url: targetUrl }) => {
+        const wrappedUrl = wrappedHostedNavigationUrl(targetUrl, url);
+        if (wrappedUrl) {
+            void mainWindow?.loadURL(wrappedUrl);
+            return { action: 'deny' };
+        }
         if (isTrustedInAppNavigation(targetUrl, url)) {
             void mainWindow?.loadURL(targetUrl);
         }
         return { action: 'deny' };
     });
+    mainWindow.webContents.on('will-navigate', (event, targetUrl) => {
+        const wrappedUrl = wrappedHostedNavigationUrl(targetUrl, url);
+        if (!wrappedUrl)
+            return;
+        event.preventDefault();
+        if (mainWindow?.webContents.getURL() !== wrappedUrl) {
+            void mainWindow?.loadURL(wrappedUrl);
+        }
+    });
+    mainWindow.webContents.on('will-redirect', (details) => {
+        if (!details.isMainFrame)
+            return;
+        const wrappedUrl = wrappedHostedNavigationUrl(details.url, url);
+        if (!wrappedUrl)
+            return;
+        details.preventDefault();
+        if (mainWindow?.webContents.getURL() !== wrappedUrl) {
+            void mainWindow?.loadURL(wrappedUrl);
+        }
+    });
+    mainWindow.webContents.on('did-navigate', (_event, targetUrl) => {
+        const wrappedUrl = wrappedHostedNavigationUrl(targetUrl, url);
+        if (!wrappedUrl || mainWindow?.webContents.getURL() === wrappedUrl)
+            return;
+        void mainWindow?.loadURL(wrappedUrl);
+    });
     mainWindow.once('ready-to-show', () => mainWindow?.show());
     // Closing the window hides it to the tray rather than quitting the app.
     // The server keeps running so Word can still reach the task pane.

package/dist/src/ai-hub/server.js

@@ -128,10 +128,19 @@ function buildHubPersonaHireUrl(personaKey, hireMode = 'job') {
     const params = new URLSearchParams({ persona: personaKey, mode: hireMode });
     return `/pricing?${params.toString()}`;
 }
-function buildHostedAuthUrl(surface, redirectTo) {
+function buildLocalHubReturnUrl(req, surface) {
+    const proto = req.protocol || 'http';
+    const host = req.get('host') || '127.0.0.1';
+    const target = new URL('/ai-hub/', `${proto}://${host}`);
+    target.searchParams.set('connected', surface);
+    return target.toString();
+}
+function buildHostedAuthUrl(surface, redirectTo, hubReturn) {
     const target = new URL('/auth/sign-in.html', (0, remote_hub_gateway_1.resolveFraimRemoteUrl)());
     target.searchParams.set('surface', surface);
     target.searchParams.set('redirect_to', redirectTo);
+    if (hubReturn)
+        target.searchParams.set('hub_return', hubReturn);
     return target.toString();
 }
 function buildHostedPathUrl(pathname, queryString) {
@@ -2012,13 +2021,20 @@ class AiHubServer {
         if (!this.dbService) {
             this.app.get(/^\/auth(\/.*)?$/, (req, res) => {
                 const parsed = new URL(req.originalUrl, 'http://127.0.0.1');
+                if (parsed.pathname === '/auth/sign-in.html' && !parsed.searchParams.has('hub_return')) {
+                    const rawSurface = parsed.searchParams.get('surface');
+                    const surface = rawSurface === 'account' || rawSurface === 'brain' || rawSurface === 'analytics'
+                        ? rawSurface
+                        : 'analytics';
+                    parsed.searchParams.set('hub_return', buildLocalHubReturnUrl(req, surface));
+                }
                 res.redirect(buildHostedPathUrl(parsed.pathname, parsed.search));
             });
-            this.app.get(['/account', '/account/'], (_req, res) => {
-                res.redirect(buildHostedAuthUrl('account', '/account/'));
+            this.app.get(['/account', '/account/'], (req, res) => {
+                res.redirect(buildHostedAuthUrl('account', '/account/', buildLocalHubReturnUrl(req, 'account')));
             });
-            this.app.get(['/analytics', '/analytics/'], (_req, res) => {
-                res.redirect(buildHostedAuthUrl('analytics', '/analytics/'));
+            this.app.get(['/analytics', '/analytics/'], (req, res) => {
+                res.redirect(buildHostedAuthUrl('analytics', '/analytics/', buildLocalHubReturnUrl(req, 'analytics')));
             });
         }
         else {

package/dist/src/routes/app-routes.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.registerAppRoutes = registerAppRoutes;
+exports.registerProtectedAppRoutes = registerProtectedAppRoutes;
 const path_1 = __importDefault(require("path"));
 /**
  * Serve the unified tabs experience at the root path.
@@ -30,3 +31,95 @@ function registerAppRoutes(app, deps) {
         }
     });
 }
+function requestBaseUrl(req) {
+    const fromEnv = process.env.FRAIM_PUBLIC_BASE_URL;
+    if (fromEnv && /^https?:\/\//i.test(fromEnv))
+        return fromEnv.replace(/\/+$/, '');
+    const firstHeader = (value) => Array.isArray(value) ? value[0] : value;
+    const proto = firstHeader(req.headers['x-forwarded-proto']) || req.protocol || 'http';
+    const host = firstHeader(req.headers['x-forwarded-host']) || req.get('host') || 'localhost';
+    return `${proto.split(',')[0]}://${host.split(',')[0]}`.replace(/\/+$/, '');
+}
+function hostedProjectSummary() {
+    const projectPath = process.cwd();
+    return {
+        path: projectPath,
+        exists: true,
+        hasFraim: true,
+        needsOnboarding: false,
+        message: '',
+    };
+}
+function hostedTeamContext() {
+    const emptyFile = { present: false, displayPath: '' };
+    return {
+        orgContext: emptyFile,
+        managerContext: emptyFile,
+        orgRules: emptyFile,
+        managerRules: emptyFile,
+        projectContext: emptyFile,
+        projectBrief: emptyFile,
+        projectQa: emptyFile,
+        projectRules: emptyFile,
+    };
+}
+/**
+ * Protected app routes for hosted web surfaces.
+ *
+ * The deployed server owns authentication/session identity and can provide a
+ * narrow bootstrap contract for the hosted Hub shell. It intentionally does not
+ * instantiate the local AiHubServer runtime, which belongs to the companion app.
+ */
+function registerProtectedAppRoutes(app, deps) {
+    void deps;
+    app.get('/api/ai-hub/bootstrap', (req, res) => {
+        const apiKeyData = req.apiKeyData;
+        if (!apiKeyData?.userId) {
+            return res.status(401).json({ error: 'Authentication required' });
+        }
+        const project = hostedProjectSummary();
+        const projectName = path_1.default.basename(project.path) || 'FRAIM';
+        const projectEntry = {
+            id: 'hosted-fraim',
+            name: projectName,
+            folderPath: project.path,
+            intent: '',
+            outcome: '',
+            rules: '',
+            brief: '',
+        };
+        return res.json({
+            title: 'AI Hub',
+            remoteBaseUrl: requestBaseUrl(req),
+            project,
+            preferences: {
+                projectPath: project.path,
+                employeeId: 'claude',
+                categoryId: 'hosted',
+                recentJobIds: [],
+                recentJobInstructions: {},
+                personaKey: null,
+                projects: [projectEntry],
+            },
+            categories: [],
+            jobs: [],
+            managerTemplates: [],
+            employees: [
+                { id: 'claude', label: 'Claude', available: true, detail: 'Hosted' },
+            ],
+            personas: [],
+            subscriptionActive: false,
+            projects: [projectEntry],
+            firstRun: { install: true, company: true, hire: true, project: true },
+            teamContext: hostedTeamContext(),
+            brain: {
+                learnings: { organization: 0, manager: 0, project: 0, rawSignals: 0 },
+                catalog: { jobs: 0, skills: 0, rules: 0 },
+            },
+            userEmail: apiKeyData.userId,
+            assignments: { byProject: {}, source: 'client-localStorage' },
+            managerHiring: { qualities: [], services: [], roles: {} },
+            managerTeam: [],
+        });
+    });
+}

package/dist/src/routes/auth-routes.js

@@ -238,7 +238,11 @@ function registerPublicAuthRoutes(app, deps) {
             if (surface === 'mobile') {
                 return res.status(200).json({ ok: true, mobileCode: issueMobileExchangeCode(apiKeyData.key) });
             }
-            return res.status(200).json({ ok: true, redirectTo: requestedRedirect });
+            // The account UI can reveal the user's API key immediately after a
+            // valid session is established. Return it here as well so embedded
+            // Hub auth can hand the key to its parent without depending on
+            // third-party iframe cookies.
+            return res.status(200).json({ ok: true, redirectTo: requestedRedirect, apiKey: apiKeyData.key });
         }
         catch (err) {
             console.error('[FRAIM AUTH] /api/auth/email/verify-code error:', err instanceof Error ? err.message : String(err));

package/dist/src/routes/oauth-routes.js

@@ -61,6 +61,38 @@ function buildBaseUrl(req) {
 function callbackUrl(req, provider) {
     return `${buildBaseUrl(req)}/api/auth/oauth/${provider}/callback`;
 }
+function isLoopbackHost(hostname) {
+    return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+}
+function safeLoopbackHubReturn(input) {
+    if (typeof input !== 'string' || !input)
+        return undefined;
+    if (input.includes('\n') || input.includes('\r'))
+        return undefined;
+    try {
+        const url = new URL(input);
+        if ((url.protocol !== 'http:' && url.protocol !== 'https:') || !isLoopbackHost(url.hostname))
+            return undefined;
+        if (url.username || url.password)
+            return undefined;
+        if (!url.pathname.startsWith('/ai-hub/'))
+            return undefined;
+        return url.toString();
+    }
+    catch {
+        return undefined;
+    }
+}
+function buildHubReturnRedirect(hubReturn, surface, apiKey) {
+    if (!hubReturn || !apiKey)
+        return null;
+    const target = new URL(hubReturn);
+    if (!target.searchParams.get('connected') && surface !== 'mobile') {
+        target.searchParams.set('connected', surface);
+    }
+    target.searchParams.set('api-key', apiKey);
+    return target.toString();
+}
 function decodeJwtPayload(jwt) {
     const parts = jwt.split('.');
     if (parts.length !== 3)
@@ -86,9 +118,10 @@ function registerOAuthRoutes(app, deps) {
     });
     // Helper used by both providers to finalise authentication once we have a verified email.
     async function completeSignIn(req, res, params) {
-        const { verifiedEmail, provider, surface, redirectTo, intent } = params;
+        const { verifiedEmail, provider, surface, redirectTo, intent, hubReturn } = params;
         const lower = verifiedEmail.toLowerCase();
         const apiKeyData = await dbService.getApiKeyByUserId(lower, false);
+        let apiKeyForHubReturn = apiKeyData?.key ?? '';
         if (!apiKeyData && intent !== 'signup') {
             // Sign-in is NOT a sign-up. If the verified email doesn't already match a
             // FRAIM account, route the user to the sign-up flow. Account creation is
@@ -107,7 +140,7 @@ function registerOAuthRoutes(app, deps) {
             return res.redirect(`/auth/error.html?reason=no_account`);
         }
         if (!apiKeyData && intent === 'signup') {
-            await (0, account_provisioning_1.ensureTrialApiKey)(dbService, lower);
+            apiKeyForHubReturn = await (0, account_provisioning_1.ensureTrialApiKey)(dbService, lower);
         }
         const sessionId = (0, oauth_helpers_1.generateSessionId)();
         await dbService.createAuthSession({
@@ -121,6 +154,10 @@ function registerOAuthRoutes(app, deps) {
         await (0, audit_log_1.auditLog)('SESSION_CREATED', { userId: lower, sessionId, surface, provider, outcome: 'success' });
         (0, cookie_service_1.setSessionCookie)(res, sessionId);
         (0, cookie_service_1.clearOAuthPendingCookie)(res);
+        const hubRedirect = buildHubReturnRedirect(hubReturn, surface, apiKeyForHubReturn);
+        if (hubRedirect) {
+            return res.redirect(hubRedirect);
+        }
         res.redirect(redirectTo);
     }
     app.get('/api/auth/oauth/:provider/start', (req, res, next) => {
@@ -136,6 +173,7 @@ function registerOAuthRoutes(app, deps) {
         const surface = (0, oauth_helpers_1.pickSurfaceOrDefault)(req.query.surface);
         const intent = pickIntent(req.query.intent);
         const redirectTo = (0, oauth_helpers_1.safeRedirectPath)(req.query.redirect_to, (0, oauth_helpers_1.defaultRedirectForSurface)(surface));
+        const hubReturn = safeLoopbackHubReturn(req.query.hub_return);
         try {
             const codeVerifier = (0, oauth_helpers_1.generatePkceVerifier)();
             const stateNonce = (0, oauth_helpers_1.generateStateNonce)();
@@ -148,6 +186,7 @@ function registerOAuthRoutes(app, deps) {
                 codeVerifier,
                 stateNonce,
                 redirectTo,
+                hubReturn,
             });
             (0, cookie_service_1.setOAuthPendingCookie)(res, pendingId);
             await (0, audit_log_1.auditLog)('OAUTH_START', { provider, surface, ip: (0, oauth_helpers_1.clientIpFromReq)(req), outcome: 'success' });
@@ -257,6 +296,7 @@ function registerOAuthRoutes(app, deps) {
                 surface: pending.surface,
                 redirectTo: pending.redirectTo,
                 intent: pickIntent(pending.intent),
+                hubReturn: pending.hubReturn,
             });
         }
         catch (err) {
@@ -350,6 +390,7 @@ function registerOAuthRoutes(app, deps) {
                 surface: pending.surface,
                 redirectTo: pending.redirectTo,
                 intent: pickIntent(pending.intent),
+                hubReturn: pending.hubReturn,
             });
         }
         catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.189",
+  "version": "2.0.191",
   "description": "FRAIM: AI Workforce Infrastructure — the organizational capability that turns AI agents into an accountable workforce, their operators into capable AI managers, and executives into leaders with clear optics on AI proficiency.",
   "main": "index.js",
   "bin": {

package/public/ai-hub/script.js

@@ -45,11 +45,13 @@ const state = {
   selectedJob: null,   // chosen in modal step 1
   selectedEmployeeId: null,
   selectedPersonaKey: null,  // R4: null = "All employees"
-  modalPersonaFilter: null,  // R3+: filter inside new-job modal; null = "All jobs"
-  storedApiKey: null,        // R2: loaded from preferences, sent on bootstrap
-  remoteBaseUrl: null,
-  connectedReturnArea: 'projects',
-  panelState: {},            // { [convId]: { coach?: boolean } }
+  modalPersonaFilter: null,  // R3+: filter inside new-job modal; null = "All jobs"
+  storedApiKey: null,        // R2: loaded from preferences, sent on bootstrap
+  remoteBaseUrl: null,
+  connectedReturnArea: 'projects',
+  connectedSurface: null,
+  pendingConnectedSurfaceAfterAuth: null,
+  panelState: {},            // { [convId]: { coach?: boolean } }
   wordContext: null,         // WordContext pushed from taskpane.html via postMessage
   // Pending coaching job selected via a quick-coach button or template picker.
   // Sent as coachingJobId in the next continueRun call and then cleared.
@@ -146,6 +148,34 @@ async function requestJson(url, options) {
   return payload;
 }
 
+function tfIsLoopbackHost(hostname) {
+  return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
+}
+
+function tfIsLoopbackOrigin(origin) {
+  try {
+    const parsed = new URL(origin);
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') && tfIsLoopbackHost(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function tfConsumeReturnedApiKeyFromUrl() {
+  try {
+    if (!tfIsLoopbackHost(window.location.hostname)) return null;
+    const url = new URL(window.location.href);
+    const apiKey = url.searchParams.get('api-key') || url.searchParams.get('apiKey');
+    if (!apiKey) return null;
+    url.searchParams.delete('api-key');
+    url.searchParams.delete('apiKey');
+    window.history.replaceState({}, document.title, `${url.pathname}${url.search}${url.hash}`);
+    return apiKey;
+  } catch {
+    return null;
+  }
+}
+
 function bootstrapCacheKey(projectPath, docUrl) {
   return `${tfCanonicalProjectPath(projectPath || '')}::${docUrl || ''}`;
 }
@@ -155,14 +185,14 @@ function cacheBootstrapPayload(bootstrap, docUrl) {
   bootstrapCache.set(bootstrapCacheKey(bootstrap.project.path, docUrl), bootstrap);
 }
 
-function applyBootstrap(bootstrap, docUrl) {
-  state.bootstrap = bootstrap;
-  state.projectPath = bootstrap.project.path;
-  state.remoteBaseUrl = bootstrap.remoteBaseUrl || null;
-  if (bootstrap.preferences && bootstrap.preferences.apiKey) {
-    state.storedApiKey = bootstrap.preferences.apiKey;
-  }
-  state.selectedEmployeeId = state.selectedEmployeeId || bootstrap.preferences.employeeId;
+function applyBootstrap(bootstrap, docUrl) {
+  state.bootstrap = bootstrap;
+  state.projectPath = bootstrap.project.path;
+  state.remoteBaseUrl = bootstrap.remoteBaseUrl || null;
+  if (bootstrap.preferences && bootstrap.preferences.apiKey) {
+    state.storedApiKey = bootstrap.preferences.apiKey;
+  }
+  state.selectedEmployeeId = state.selectedEmployeeId || bootstrap.preferences.employeeId;
   // Restore persona selection persisted on the server side.
   if (bootstrap.preferences && bootstrap.preferences.personaKey !== undefined) {
     state.selectedPersonaKey = bootstrap.preferences.personaKey;
@@ -235,6 +265,20 @@ async function loadBootstrap(projectPath, docUrl, options) {
   return bootstrap;
 }
 
+function hostedHubNeedsSignIn(error) {
+  if (!error || error.status !== 401) return false;
+  const host = window.location.hostname;
+  return host !== 'localhost' && host !== '127.0.0.1';
+}
+
+function redirectHostedHubToSignIn() {
+  const redirectTo = `${window.location.pathname}${window.location.search}${window.location.hash}` || '/ai-hub/';
+  const target = new URL('/auth/sign-in.html', window.location.origin);
+  target.searchParams.set('surface', 'account');
+  target.searchParams.set('redirect_to', redirectTo);
+  window.location.href = target.toString();
+}
+
 // ---------------------------------------------------------------------------
 // Word context bridge (postMessage from taskpane.html parent frame)
 // ---------------------------------------------------------------------------
@@ -5917,6 +5961,11 @@ function wireEvents() {
   const isFirstRun = urlParams.get('firstRun') === 'true';
   const surface = urlParams.get('surface') || 'hub';
   const docUrl = urlParams.get('docUrl') || '';
+  const requestedConnectedSurface = tfRequestedConnectedSurface();
+  const returnedApiKey = tfConsumeReturnedApiKeyFromUrl();
+  if (returnedApiKey && requestedConnectedSurface) {
+    state.pendingConnectedSurfaceAfterAuth = requestedConnectedSurface;
+  }
 
   // Apply surface class before bootstrap so CSS takes effect immediately.
   if (surface !== 'hub') document.body.dataset.surface = surface;
@@ -5926,9 +5975,17 @@ function wireEvents() {
 
   try {
     await loadBootstrap(null, docUrl);
+    if (returnedApiKey) {
+      await tfRememberConnectedApiKey(returnedApiKey);
+      tfOpenRequestedConnectedSurface();
+    }
     await hydrateConversationsFromServer();
     startBgConvPoll();
   } catch (error) {
+    if (hostedHubNeedsSignIn(error)) {
+      redirectHostedHubToSignIn();
+      return;
+    }
     showStatus(error.message, true);
     return;
   }
@@ -6211,7 +6268,7 @@ const STORAGE_KEY_ASSIGNMENTS_512 = 'fraim.aiHub.assignments.v1';
 
 const tf = {
   enabled: false,
-  area: 'projects',          // company | manager | projects | brain | connected
+  area: 'projects',          // company | manager | projects | brain | connected
   projectView: 'overview',   // overview | workspace
   activeProjectId: null,
   projects: [],              // [{ id, name, intent, brief }] — roster derived from hired personas, not stored
@@ -9242,107 +9299,158 @@ function tfToggleAccountMenu(e) {
   const menu = document.getElementById('account-menu');
   if (menu) menu.classList.toggle('open');
 }
-function tfCloseAccountMenu() {
-  const menu = document.getElementById('account-menu');
-  if (menu) menu.classList.remove('open');
-}
-
-const CONNECTED_SURFACES = {
-  account: { title: 'Account', path: '/account/' },
-  analytics: { title: 'Analytics', path: '/analytics/' },
-  brain: { title: 'Brain', path: '/fraim-brain.html', redirectPath: '/fraim-brain' },
-};
-
-function tfConnectedRemoteBase() {
-  const fallback = window.location.origin;
-  const raw = state.remoteBaseUrl || (state.bootstrap && state.bootstrap.remoteBaseUrl) || fallback;
-  try {
-    return new URL(raw, fallback).toString();
-  } catch {
-    return fallback;
-  }
-}
-
-function tfConnectedApiKey() {
-  return state.storedApiKey || (state.bootstrap && state.bootstrap.preferences && state.bootstrap.preferences.apiKey) || '';
-}
-
-function tfConnectedSurfaceUrl(surface) {
-  const cfg = CONNECTED_SURFACES[surface];
-  const remoteBase = tfConnectedRemoteBase();
-  if (!cfg) return remoteBase;
-  const apiKey = tfConnectedApiKey();
-  if (apiKey) {
-    const target = new URL(cfg.path, remoteBase);
-    target.searchParams.set('api-key', apiKey);
-    return target.toString();
-  }
-  const signIn = new URL('/auth/sign-in.html', remoteBase);
-  signIn.searchParams.set('surface', surface);
-  signIn.searchParams.set('redirect_to', cfg.redirectPath || cfg.path);
-  return signIn.toString();
-}
-
-function tfOpenConnectedSurface(surface) {
-  const cfg = CONNECTED_SURFACES[surface];
-  if (!cfg) return;
-  tfCloseAccountMenu();
-  state.connectedReturnArea = (tf.area && tf.area !== 'connected') ? tf.area : 'projects';
-  const url = tfConnectedSurfaceUrl(surface);
-  const title = document.getElementById('connected-title');
-  const origin = document.getElementById('connected-origin');
-  const frame = document.getElementById('connected-frame');
-  if (title) title.textContent = cfg.title;
-  if (origin) {
-    try { origin.textContent = new URL(url).origin; }
-    catch { origin.textContent = ''; }
-  }
-  if (frame) {
-    frame.title = `FRAIM ${cfg.title}`;
-    frame.src = url;
-  }
-  tfShowArea('connected');
-}
-
-function tfCloseConnectedSurface() {
-  const frame = document.getElementById('connected-frame');
-  if (frame) frame.removeAttribute('src');
-  const returnArea = state.connectedReturnArea && state.connectedReturnArea !== 'connected'
-    ? state.connectedReturnArea
-    : 'projects';
-  tfShowArea(returnArea);
-}
-
+function tfCloseAccountMenu() {
+  const menu = document.getElementById('account-menu');
+  if (menu) menu.classList.remove('open');
+}
+
+const CONNECTED_SURFACES = {
+  account: { title: 'Account', path: '/account/' },
+  analytics: { title: 'Analytics', path: '/analytics/' },
+  brain: { title: 'Brain', path: '/fraim-brain.html', redirectPath: '/fraim-brain' },
+};
+
+function tfConnectedRemoteBase() {
+  const fallback = window.location.origin;
+  const raw = state.remoteBaseUrl || (state.bootstrap && state.bootstrap.remoteBaseUrl) || fallback;
+  try {
+    return new URL(raw, fallback).toString();
+  } catch {
+    return fallback;
+  }
+}
+
+function tfConnectedApiKey() {
+  return state.storedApiKey || (state.bootstrap && state.bootstrap.preferences && state.bootstrap.preferences.apiKey) || '';
+}
+
+function tfConnectedRedirectPath(surface, cfg, remoteBase) {
+  try {
+    if (new URL(remoteBase).origin === window.location.origin) {
+      return `/ai-hub/?connected=${encodeURIComponent(surface)}`;
+    }
+  } catch {}
+  return cfg.redirectPath || cfg.path;
+}
+
+function tfConnectedHubReturnUrl(surface) {
+  if (!tfIsLoopbackOrigin(window.location.origin)) return '';
+  try {
+    const target = new URL('/ai-hub/', window.location.origin);
+    target.searchParams.set('connected', surface);
+    return target.toString();
+  } catch {
+    return '';
+  }
+}
+
+function tfConnectedSurfaceUrl(surface) {
+  const cfg = CONNECTED_SURFACES[surface];
+  const remoteBase = tfConnectedRemoteBase();
+  if (!cfg) return remoteBase;
+  const apiKey = tfConnectedApiKey();
+  try {
+    if (new URL(remoteBase).origin === window.location.origin) {
+      return new URL(cfg.path, remoteBase).toString();
+    }
+  } catch {}
+  if (apiKey) {
+    const target = new URL(cfg.path, remoteBase);
+    target.searchParams.set('api-key', apiKey);
+    return target.toString();
+  }
+  const signIn = new URL('/auth/sign-in.html', remoteBase);
+  signIn.searchParams.set('surface', surface);
+  signIn.searchParams.set('embedded', '1');
+  signIn.searchParams.set('redirect_to', tfConnectedRedirectPath(surface, cfg, remoteBase));
+  const hubReturn = tfConnectedHubReturnUrl(surface);
+  if (hubReturn) signIn.searchParams.set('hub_return', hubReturn);
+  return signIn.toString();
+}
+
+function tfOpenConnectedSurface(surface) {
+  const cfg = CONNECTED_SURFACES[surface];
+  if (!cfg) return;
+  tfCloseAccountMenu();
+  state.connectedReturnArea = (tf.area && tf.area !== 'connected') ? tf.area : 'projects';
+  state.connectedSurface = surface;
+  const url = tfConnectedSurfaceUrl(surface);
+  const title = document.getElementById('connected-title');
+  const origin = document.getElementById('connected-origin');
+  const frame = document.getElementById('connected-frame');
+  if (title) title.textContent = cfg.title;
+  if (origin) {
+    try { origin.textContent = new URL(url).origin; }
+    catch { origin.textContent = ''; }
+  }
+  if (frame) {
+    frame.title = `FRAIM ${cfg.title}`;
+    frame.src = url;
+  }
+  tfShowArea('connected');
+}
+
+function tfCloseConnectedSurface() {
+  const frame = document.getElementById('connected-frame');
+  if (frame) frame.removeAttribute('src');
+  state.connectedSurface = null;
+  const returnArea = state.connectedReturnArea && state.connectedReturnArea !== 'connected'
+    ? state.connectedReturnArea
+    : 'projects';
+  tfShowArea(returnArea);
+}
+
 async function tfHandleConnectedAuthMessage(event) {
   const frame = document.getElementById('connected-frame');
   if (frame && frame.contentWindow && event.source !== frame.contentWindow) return;
   let remoteOrigin = '';
   try { remoteOrigin = new URL(tfConnectedRemoteBase()).origin; }
-  catch { return; }
-  if (event.origin !== remoteOrigin) return;
+  catch { return; }
+  if (event.origin !== remoteOrigin) return;
   const msg = event.data || {};
   if (!msg || msg.type !== 'fraim-auth-api-key' || typeof msg.apiKey !== 'string' || !msg.apiKey) return;
-  if (msg.apiKey === state.storedApiKey) return;
-  state.storedApiKey = msg.apiKey;
-  if (state.bootstrap && state.bootstrap.preferences) {
-    state.bootstrap.preferences.apiKey = msg.apiKey;
-  }
-  try {
-    await requestJson('/api/ai-hub/api-key', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ apiKey: msg.apiKey }),
-    });
-  } catch (error) {
-    console.warn('[ai-hub] Could not persist connected auth key:', error);
+  const previousKey = tfConnectedApiKey();
+  await tfRememberConnectedApiKey(msg.apiKey);
+  if (state.connectedSurface) {
+    const nextUrl = tfConnectedSurfaceUrl(state.connectedSurface);
+    const frameEl = document.getElementById('connected-frame');
+    if (frameEl) {
+      try {
+        const current = new URL(frameEl.src || '', window.location.href);
+        const next = new URL(nextUrl, window.location.href);
+        if (previousKey === msg.apiKey && current.origin === next.origin && current.pathname === next.pathname) {
+          return;
+        }
+      } catch {}
+      frameEl.src = nextUrl;
+    }
   }
 }
-
-// ---------------------------------------------------------------------------
-// Theme (#700): explicit light/dark with an in-app toggle. The <head> bootstrap
+
+async function tfRememberConnectedApiKey(apiKey) {
+  const changed = apiKey !== state.storedApiKey;
+  state.storedApiKey = apiKey;
+  if (state.bootstrap && state.bootstrap.preferences) {
+    state.bootstrap.preferences.apiKey = apiKey;
+  }
+  if (changed) {
+    try {
+      await requestJson('/api/ai-hub/api-key', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ apiKey }),
+      });
+    } catch (error) {
+      console.warn('[ai-hub] Could not persist connected auth key:', error);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Theme (#700): explicit light/dark with an in-app toggle. The <head> bootstrap
 // sets [data-theme] pre-paint (no flash) from localStorage['fraim-theme'] or the
 // OS preference; here we reflect it in the toggle control and persist changes.
-// Embedded connected surfaces receive live theme updates via postMessage.
+// Embedded connected surfaces receive live theme updates via postMessage.
 // ---------------------------------------------------------------------------
 function tfCurrentTheme() {
   return document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light';
@@ -9362,18 +9470,18 @@ function tfApplyTheme(theme, persist) {
   document.documentElement.setAttribute('data-theme', t);
   if (persist) { try { localStorage.setItem('fraim-theme', t); } catch (e) {} }
   tfSyncThemeToggle(t);
-  // Keep embedded surfaces in sync live, including the connected main-server frame.
-  try {
-    document.querySelectorAll('iframe').forEach((f) => {
-      if (!f.contentWindow) return;
-      let targetOrigin = location.origin;
-      try {
-        if (f.src) targetOrigin = new URL(f.src, location.href).origin;
-      } catch (e) {}
-      f.contentWindow.postMessage({ type: 'fraim-theme-change', theme: t }, targetOrigin);
-    });
-  } catch (e) {}
-}
+  // Keep embedded surfaces in sync live, including the connected main-server frame.
+  try {
+    document.querySelectorAll('iframe').forEach((f) => {
+      if (!f.contentWindow) return;
+      let targetOrigin = location.origin;
+      try {
+        if (f.src) targetOrigin = new URL(f.src, location.href).origin;
+      } catch (e) {}
+      f.contentWindow.postMessage({ type: 'fraim-theme-change', theme: t }, targetOrigin);
+    });
+  } catch (e) {}
+}
 function tfToggleTheme(e) {
   if (e) e.stopPropagation();
   tfApplyTheme(tfCurrentTheme() === 'dark' ? 'light' : 'dark', true);
@@ -10099,31 +10207,31 @@ function tfWireShell() {
   for (const tab of document.querySelectorAll('.hub-tab')) {
     tab.addEventListener('click', () => tfShowArea(tab.dataset.area));
   }
-  const avatar = document.getElementById('avatar-btn');
-  if (avatar) avatar.addEventListener('click', tfToggleAccountMenu);
-  tfWireThemeToggle();
-  const accountItem = document.getElementById('am-account');
-  if (accountItem) accountItem.addEventListener('click', (e) => {
-    e.preventDefault();
-    tfOpenConnectedSurface('account');
-  });
-  const brainItem = document.getElementById('am-brain');
-  if (brainItem) brainItem.addEventListener('click', () => {
-    tfOpenConnectedSurface('brain');
-  });
-  const analyticsItem = document.getElementById('am-analytics');
-  if (analyticsItem) analyticsItem.addEventListener('click', (e) => {
-    e.preventDefault();
-    tfOpenConnectedSurface('analytics');
-  });
-  const connectedClose = document.getElementById('connected-close');
-  if (connectedClose) connectedClose.addEventListener('click', tfCloseConnectedSurface);
-  if (!tf.connectedAuthMessageWired) {
-    window.addEventListener('message', tfHandleConnectedAuthMessage);
-    tf.connectedAuthMessageWired = true;
-  }
-  const signout = document.getElementById('am-signout');
-  if (signout) signout.addEventListener('click', () => { window.location.href = '/auth/sign-in.html'; });
+  const avatar = document.getElementById('avatar-btn');
+  if (avatar) avatar.addEventListener('click', tfToggleAccountMenu);
+  tfWireThemeToggle();
+  const accountItem = document.getElementById('am-account');
+  if (accountItem) accountItem.addEventListener('click', (e) => {
+    e.preventDefault();
+    tfOpenConnectedSurface('account');
+  });
+  const brainItem = document.getElementById('am-brain');
+  if (brainItem) brainItem.addEventListener('click', () => {
+    tfOpenConnectedSurface('brain');
+  });
+  const analyticsItem = document.getElementById('am-analytics');
+  if (analyticsItem) analyticsItem.addEventListener('click', (e) => {
+    e.preventDefault();
+    tfOpenConnectedSurface('analytics');
+  });
+  const connectedClose = document.getElementById('connected-close');
+  if (connectedClose) connectedClose.addEventListener('click', tfCloseConnectedSurface);
+  if (!tf.connectedAuthMessageWired) {
+    window.addEventListener('message', tfHandleConnectedAuthMessage);
+    tf.connectedAuthMessageWired = true;
+  }
+  const signout = document.getElementById('am-signout');
+  if (signout) signout.addEventListener('click', () => { window.location.href = '/auth/sign-in.html'; });
   document.addEventListener('click', (e) => {
     const menu = document.getElementById('account-menu');
     if (menu && menu.classList.contains('open') && !(e.target.closest && e.target.closest('.nav-right'))) {
@@ -10231,15 +10339,15 @@ function tfWireShell() {
     ['assign-job-modal', tfCloseAssignJob],
     ['np-modal', tfCloseNewProject],
   ];
-  document.addEventListener('keydown', (e) => {
-    if (e.key !== 'Escape') return;
-    if (tf.area === 'connected') {
-      e.stopPropagation();
-      tfCloseConnectedSurface();
-      return;
-    }
-    for (const [id, fn] of escClosers) {
-      const el = document.getElementById(id);
+  document.addEventListener('keydown', (e) => {
+    if (e.key !== 'Escape') return;
+    if (tf.area === 'connected') {
+      e.stopPropagation();
+      tfCloseConnectedSurface();
+      return;
+    }
+    for (const [id, fn] of escClosers) {
+      const el = document.getElementById(id);
       if (el && !el.hidden) { e.stopPropagation(); fn(); return; }
     }
   });
@@ -10274,6 +10382,36 @@ function tfPopulateAccountMenu() {
   if (avatarBtn) avatarBtn.textContent = id.initials;
 }
 
+function tfRequestedConnectedSurface() {
+  try {
+    const params = new URLSearchParams(window.location.search);
+    const surface = params.get('connected') || params.get('open');
+    return CONNECTED_SURFACES[surface] ? surface : null;
+  } catch {
+    return null;
+  }
+}
+
+function tfClearConnectedSurfaceRequest() {
+  try {
+    const url = new URL(window.location.href);
+    url.searchParams.delete('connected');
+    url.searchParams.delete('open');
+    window.history.replaceState({}, document.title, `${url.pathname}${url.search}${url.hash}`);
+  } catch {}
+}
+
+function tfOpenRequestedConnectedSurface() {
+  if (!tf.enabled) return;
+  const pendingAfterAuth = state.pendingConnectedSurfaceAfterAuth;
+  if (pendingAfterAuth && !tfConnectedApiKey()) return;
+  const surface = pendingAfterAuth || tfRequestedConnectedSurface();
+  if (!surface) return;
+  state.pendingConnectedSurfaceAfterAuth = null;
+  tfClearConnectedSurfaceRequest();
+  setTimeout(() => tfOpenConnectedSurface(surface), 0);
+}
+
 function tfInitShell() {
   if (typeof surface !== 'undefined' && surface !== 'hub') return;
   if (document.body.dataset.surface && document.body.dataset.surface !== 'hub') return;
@@ -10312,6 +10450,7 @@ function tfInitShell() {
   // the project workspace. Re-render once the workspace is selected so manager
   // delegation boards are visible on first load, not only after a refresh tick.
   renderActive();
+  tfOpenRequestedConnectedSurface();
 }
 
 // Refresh shell-derived UI after a bootstrap reload (e.g. project picked).