fraim-framework 2.0.188 → 2.0.190

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

@@ -10,6 +10,7 @@ const fs_1 = __importDefault(require("fs"));
 const server_1 = require("./server");
 const cert_store_1 = require("./cert-store");
 const office_sideload_1 = require("./office-sideload");
+const remote_hub_gateway_1 = require("./remote-hub-gateway");
 // ---------------------------------------------------------------------------
 // State
 // ---------------------------------------------------------------------------
@@ -50,6 +51,66 @@ function applyUserDataOverride() {
     fs_1.default.mkdirSync(userDataDir, { recursive: true });
     electron_1.app.setPath('userData', userDataDir);
 }
+function isTrustedInAppNavigation(targetUrl, hubUrl) {
+    try {
+        const parsed = new URL(targetUrl);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+            return false;
+        return parsed.origin === new URL(hubUrl).origin || parsed.origin === new URL((0, remote_hub_gateway_1.resolveFraimRemoteUrl)()).origin;
+    }
+    catch {
+        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.
@@ -204,9 +265,42 @@ async function createWindow(url) {
         mainWindow.on('closed', () => electron_1.nativeTheme.removeListener('updated', applyOverlay));
     }
     mainWindow.webContents.setWindowOpenHandler(({ url: targetUrl }) => {
-        void electron_1.shell.openExternal(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,6 +128,26 @@ function buildHubPersonaHireUrl(personaKey, hireMode = 'job') {
     const params = new URLSearchParams({ persona: personaKey, mode: hireMode });
     return `/pricing?${params.toString()}`;
 }
+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) {
+    const target = new URL(pathname, (0, remote_hub_gateway_1.resolveFraimRemoteUrl)());
+    target.search = queryString;
+    return target.toString();
+}
 function buildHubPersonaAvatarUrl(personaKey) {
     return loadPersonaHiringModule()?.buildPersonaAvatarUrl(personaKey) ?? '';
 }
@@ -1407,6 +1427,7 @@ class AiHubServer {
         const activeRun = latest ? this.enrichRunForResponse(latest) : undefined;
         return {
             title: 'AI Hub',
+            remoteBaseUrl: (0, remote_hub_gateway_1.resolveFraimRemoteUrl)(),
             project,
             preferences,
             categories: (0, catalog_1.getAiHubCategories)(normalizedProjectPath, catalogOptions),
@@ -1997,26 +2018,47 @@ class AiHubServer {
         // Issue #512: Serve the account and analytics pages from public/.
         // These live outside of /ai-hub so they need explicit routes.
         const publicDir = resolveAiHubPublicDir().replace(/[\\/]ai-hub$/, '');
-        this.app.get('/account', (_req, res) => {
-            const filePath = path_1.default.join(publicDir, 'account', 'index.html');
-            if (fs_1.default.existsSync(filePath)) {
-                res.sendFile(filePath);
-            }
-            else {
-                res.status(404).send('Account page not found.');
-            }
-        });
-        this.app.use('/account', express_1.default.static(path_1.default.join(publicDir, 'account')));
-        this.app.get('/analytics', (_req, res) => {
-            const filePath = path_1.default.join(publicDir, 'analytics', 'index.html');
-            if (fs_1.default.existsSync(filePath)) {
-                res.sendFile(filePath);
-            }
-            else {
-                res.status(404).send('Analytics page not found.');
-            }
-        });
-        this.app.use('/analytics', express_1.default.static(path_1.default.join(publicDir, 'analytics')));
+        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/', buildLocalHubReturnUrl(req, 'account')));
+            });
+            this.app.get(['/analytics', '/analytics/'], (req, res) => {
+                res.redirect(buildHostedAuthUrl('analytics', '/analytics/', buildLocalHubReturnUrl(req, 'analytics')));
+            });
+        }
+        else {
+            this.app.get('/account', (_req, res) => {
+                const filePath = path_1.default.join(publicDir, 'account', 'index.html');
+                if (fs_1.default.existsSync(filePath)) {
+                    res.sendFile(filePath);
+                }
+                else {
+                    res.status(404).send('Account page not found.');
+                }
+            });
+            this.app.use('/account', express_1.default.static(path_1.default.join(publicDir, 'account')));
+            this.app.get('/analytics', (_req, res) => {
+                const filePath = path_1.default.join(publicDir, 'analytics', 'index.html');
+                if (fs_1.default.existsSync(filePath)) {
+                    res.sendFile(filePath);
+                }
+                else {
+                    res.status(404).send('Analytics page not found.');
+                }
+            });
+            this.app.use('/analytics', express_1.default.static(path_1.default.join(publicDir, 'analytics')));
+        }
         // Issue #478: Serve the PowerPoint task pane HTML and manifest.
         // Office JS appends query strings (?_host_Info=PowerPoint$Win32$...) to every
         // request, so we must strip them before resolving the file path. Use a custom

package/dist/src/core/ai-mentor.js

@@ -96,7 +96,7 @@ class AIMentor {
         const metadataPhases = Object.keys(workflow.metadata.phases || {});
         const initialPhase = workflow.metadata.initialPhase || metadataPhases[0] || Array.from(workflow.phases.keys())[0] || 'starting';
         const overview = workflow.overview.trim();
-        return [
+        const lines = [
             overview,
             '',
             '---',
@@ -104,7 +104,16 @@ class AIMentor {
             '## Start Here',
             `- Initial phase: \`${initialPhase}\``,
             '- Call `seekMentoring` to load the instructions for this phase.'
-        ].join('\n');
+        ];
+        // A job that produces reviewable repository changes must resolve its workspace
+        // before starting. The mode conditional (branch/worktree vs in place) lives in
+        // the skill and is evaluated by the agent from its own local settings.
+        if (workflow.metadata.producesRepoChanges === true) {
+            lines.push('', '## Set Up Your Workspace First', '- This job changes the repository. Before phase work, read and follow'
+                + ' `get_fraim_file({ path: "skills/engineering/set-up-workspace.md" })`'
+                + ' to work on the issue\'s branch when a repository is configured, or in place otherwise.');
+        }
+        return lines.join('\n');
     }
     async generateStartingMessage(workflow, phaseId, skipIncludes) {
         const entityType = 'Job';

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.188",
+  "version": "2.0.190",
   "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/index.html

@@ -33,18 +33,18 @@
             <div class="am-email" id="am-email"></div>
           </div>
         </div>
-        <a class="am-item" id="am-account" href="/account">
+        <button class="am-item" id="am-account" type="button">
           <span class="am-ico">👤</span>
           <div><div class="am-label">Account</div><div class="am-sub">API key, sessions, billing</div></div>
-        </a>
+        </button>
         <button class="am-item" id="am-brain" type="button">
           <span class="am-ico">🧠</span>
           <div><div class="am-label">Brain</div><div class="am-sub">Everything your team knows</div></div>
         </button>
-        <a class="am-item" id="am-analytics" href="/analytics">
+        <button class="am-item" id="am-analytics" type="button">
           <span class="am-ico">📊</span>
           <div><div class="am-label">Analytics</div><div class="am-sub">Usage, cost, and ROI</div></div>
-        </a>
+        </button>
         <button class="am-item am-theme" id="am-theme-toggle" type="button" role="switch" aria-checked="false">
           <span class="am-ico" id="am-theme-ico">🌙</span>
           <div><div class="am-label">Dark mode</div><div class="am-sub" id="am-theme-sub">Off</div></div>
@@ -141,7 +141,21 @@
     </div>
   </section>
 
-  <!-- Issue #512: Projects area wraps the existing single-surface Hub. -->
+  <section class="hub-area" id="area-connected" hidden>
+    <div class="connected-shell">
+      <div class="connected-toolbar">
+        <div class="connected-title-block">
+          <div class="connected-kicker" id="connected-kicker">Connected FRAIM</div>
+          <div class="connected-title" id="connected-title">Account</div>
+        </div>
+        <div class="connected-origin" id="connected-origin"></div>
+        <button class="connected-close" id="connected-close" type="button">Back</button>
+      </div>
+      <iframe id="connected-frame" class="connected-frame" title="FRAIM connected surface" allow="clipboard-read; clipboard-write"></iframe>
+    </div>
+  </section>
+
+  <!-- Issue #512: Projects area wraps the existing single-surface Hub. -->
   <section class="hub-area on" id="area-projects">
     <div class="proj-tabs" id="proj-tabs">
       <button class="ptab on" id="ptab-overview" type="button" data-view="overview">Overview</button>

package/public/ai-hub/script.js

@@ -47,6 +47,10 @@ const state = {
   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',
+  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.
@@ -144,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 || ''}`;
 }
@@ -156,6 +188,10 @@ function cacheBootstrapPayload(bootstrap, docUrl) {
 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) {
@@ -229,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)
 // ---------------------------------------------------------------------------
@@ -5911,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;
@@ -5920,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;
   }
@@ -6205,7 +6268,7 @@ const STORAGE_KEY_ASSIGNMENTS_512 = 'fraim.aiHub.assignments.v1';
 
 const tf = {
   enabled: false,
-  area: 'projects',          // company | manager | projects | brain
+  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
@@ -9241,11 +9304,143 @@ function tfCloseAccountMenu() {
   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;
+  const msg = event.data || {};
+  if (!msg || msg.type !== 'fraim-auth-api-key' || typeof msg.apiKey !== 'string' || !msg.apiKey) return;
+  await tfRememberConnectedApiKey(msg.apiKey);
+  if (state.connectedSurface) {
+    const nextUrl = tfConnectedSurfaceUrl(state.connectedSurface);
+    const frameEl = document.getElementById('connected-frame');
+    if (frameEl) frameEl.src = nextUrl;
+  }
+}
+
+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.
-// Same-origin key sharing keeps /account and /analytics in sync on their next load.
+// Embedded connected surfaces receive live theme updates via postMessage.
 // ---------------------------------------------------------------------------
 function tfCurrentTheme() {
   return document.documentElement.getAttribute('data-theme') === 'dark' ? 'dark' : 'light';
@@ -9265,10 +9460,15 @@ function tfApplyTheme(theme, persist) {
   document.documentElement.setAttribute('data-theme', t);
   if (persist) { try { localStorage.setItem('fraim-theme', t); } catch (e) {} }
   tfSyncThemeToggle(t);
-  // Keep any same-origin embedded surface (e.g. an analytics iframe) in sync live.
+  // Keep embedded surfaces in sync live, including the connected main-server frame.
   try {
     document.querySelectorAll('iframe').forEach((f) => {
-      if (f.contentWindow) f.contentWindow.postMessage({ type: 'fraim-theme-change', theme: t }, location.origin);
+      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) {}
 }
@@ -10000,8 +10200,26 @@ function tfWireShell() {
   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', () => { tfCloseAccountMenu(); tfShowArea('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) => {
@@ -10113,6 +10331,11 @@ function tfWireShell() {
   ];
   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; }
@@ -10149,6 +10372,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;
@@ -10187,6 +10440,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).

package/public/ai-hub/styles.css

@@ -2752,7 +2752,7 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
 .am-av { width: 32px; height: 32px; border-radius: 50%; background: var(--accent); color: #fff; display: flex; align-items: center; justify-content: center; font-size: 11px; font-weight: 700; flex-shrink: 0; }
 .am-name { font-size: 13px; font-weight: 700; }
 .am-email { font-size: 11px; color: var(--muted); }
-.am-item { display: flex; align-items: flex-start; gap: 10px; padding: 9px 16px; cursor: pointer; font-size: 13px; }
+.am-item { display: flex; align-items: flex-start; gap: 10px; width: 100%; padding: 9px 16px; cursor: pointer; font-size: 13px; color: var(--text); text-align: left; text-decoration: none; border: 0; background: none; }
 .am-item:hover { background: var(--bg); }
 .am-ico { font-size: 14px; width: 18px; text-align: center; flex-shrink: 0; margin-top: 1px; }
 .am-label { font-weight: 600; }
@@ -2768,12 +2768,75 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
 .am-theme[aria-checked="true"] .am-switch-knob { transform: translateX(16px); }
 
 /* Hub areas */
-.hub-area { display: none; flex: 1; overflow: hidden; }
-.hub-area.on { display: flex; flex-direction: column; }
-.hub-area-page { max-width: 860px; margin: 0 auto; padding: 28px 24px 48px; overflow-y: auto; flex: 1; /* authoritative rule — see also Round-2 override below which is now removed */ }
-
-/* #521 R6: Company/Manager use the same rail + main shell as the project workspace. */
-.area-shell { display: flex; flex: 1; min-height: 0; }
+.hub-area { display: none; flex: 1; overflow: hidden; }
+.hub-area.on { display: flex; flex-direction: column; }
+.hub-area-page { max-width: 860px; margin: 0 auto; padding: 28px 24px 48px; overflow-y: auto; flex: 1; /* authoritative rule — see also Round-2 override below which is now removed */ }
+
+.connected-shell {
+  display: flex;
+  flex: 1;
+  min-height: 0;
+  flex-direction: column;
+  background: var(--bg);
+}
+.connected-toolbar {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+  min-height: 52px;
+  padding: 8px 16px;
+  background: var(--surface);
+  border-bottom: 1px solid var(--line);
+  flex-shrink: 0;
+}
+.connected-title-block {
+  min-width: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 1px;
+}
+.connected-kicker {
+  font-size: 10px;
+  font-weight: 700;
+  letter-spacing: .04em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+.connected-title {
+  font-size: 14px;
+  font-weight: 700;
+  color: var(--text);
+}
+.connected-origin {
+  min-width: 0;
+  flex: 1;
+  color: var(--muted);
+  font-size: 12px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.connected-close {
+  border: 1px solid var(--line);
+  background: var(--surface);
+  color: var(--text);
+  border-radius: 8px;
+  padding: 6px 12px;
+  font-size: 13px;
+  font-weight: 600;
+  flex-shrink: 0;
+}
+.connected-close:hover { background: var(--bg); }
+.connected-frame {
+  flex: 1;
+  min-height: 0;
+  width: 100%;
+  border: 0;
+  background: var(--surface);
+}
+
+/* #521 R6: Company/Manager use the same rail + main shell as the project workspace. */
+.area-shell { display: flex; flex: 1; min-height: 0; }
 .area-rail { width: 244px; flex-shrink: 0; background: var(--surface); border-right: 1px solid var(--line); overflow-y: auto; padding: 6px 0; }
 .area-main { flex: 1; min-width: 0; display: flex; flex-direction: column; overflow: hidden; }
 .area-rail-head { font-size: 11px; font-weight: 700; letter-spacing: .04em; text-transform: uppercase; color: var(--muted); padding: 14px 16px 6px; }