fraim-framework 2.0.182 → 2.0.183

package/dist/src/ai-hub/conversation-store.js

@@ -68,6 +68,10 @@ class AiHubConversationStore {
     constructor(stateFilePath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'ai-hub-conversations.json')) {
         this.stateFilePath = stateFilePath;
     }
+    listProjectPaths() {
+        const state = this.readStore();
+        return Object.keys(state.projects || {}).map((projectPath) => normalizeProjectPath(projectPath));
+    }
     loadProject(projectPath) {
         const state = this.readStore();
         const normalizedProjectPath = normalizeProjectPath(projectPath);

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

@@ -52,6 +52,13 @@ function parseArgs(argv) {
     }
     return { projectPath, preferredPort };
 }
+function applyUserDataOverride() {
+    const userDataDir = process.env.FRAIM_AI_HUB_USER_DATA_DIR;
+    if (!userDataDir)
+        return;
+    fs_1.default.mkdirSync(userDataDir, { recursive: true });
+    electron_1.app.setPath('userData', userDataDir);
+}
 // ---------------------------------------------------------------------------
 // Tray icon resolution — prefers bundled icon, falls back to a 1×1 empty image
 // so the app never crashes if assets aren't present.
@@ -271,6 +278,7 @@ async function launchDesktopShell(options) {
 // ---------------------------------------------------------------------------
 async function bootstrap() {
     const options = parseArgs(process.argv.slice(2));
+    applyUserDataOverride();
     // Single-instance lock — if another instance is already running, focus it
     // and exit rather than spawning a second server + window.
     // Skip when FRAIM_AI_HUB_FAKE_HOST=1 (test mode) so Playwright can launch

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

@@ -4,7 +4,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AiHubPreferencesStore = void 0;
+exports.normalizeAiHubProjectList = normalizeAiHubProjectList;
 const fs_1 = __importDefault(require("fs"));
+const crypto_1 = require("crypto");
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const DEFAULT_CATEGORY = 'marketing';
@@ -16,7 +18,88 @@ const defaultPreferences = (projectPath) => ({
     recentJobIds: [],
     recentJobInstructions: {},
     personaKey: null,
+    projects: normalizeAiHubProjectList([], projectPath),
 });
+function normalizeProjectPath(projectPath) {
+    return path_1.default.resolve(projectPath || process.cwd());
+}
+function canonicalProjectPath(projectPath) {
+    const normalized = normalizeProjectPath(projectPath);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function projectPathExists(projectPath) {
+    try {
+        return fs_1.default.statSync(projectPath).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function projectIdForPath(projectPath) {
+    return `p-${(0, crypto_1.createHash)('sha1').update(canonicalProjectPath(projectPath)).digest('base64url').slice(0, 16)}`;
+}
+function uniqueProjectId(entry, seenIds) {
+    const fallbackId = projectIdForPath(entry.folderPath);
+    const rawId = typeof entry.id === 'string' ? entry.id.trim() : '';
+    const preferredId = rawId && rawId !== 'p-current' ? rawId : fallbackId;
+    let id = preferredId;
+    let suffix = 2;
+    while (seenIds.has(id)) {
+        id = `${fallbackId}-${suffix}`;
+        suffix += 1;
+    }
+    seenIds.add(id);
+    return id;
+}
+function withUniqueProjectIds(projects) {
+    const seenIds = new Set();
+    return projects.map((entry) => ({ ...entry, id: uniqueProjectId(entry, seenIds) }));
+}
+function normalizeProjectEntry(raw, fallbackPath) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const value = raw;
+    const rawPath = typeof value.folderPath === 'string'
+        ? value.folderPath
+        : (typeof value.path === 'string'
+            ? value.path
+            : (typeof value.folder === 'string' ? value.folder : fallbackPath));
+    if (!rawPath || typeof rawPath !== 'string')
+        return null;
+    const folderPath = normalizeProjectPath(rawPath);
+    const basename = path_1.default.basename(folderPath) || folderPath;
+    const team = Array.isArray(value.team) ? value.team.filter((entry) => typeof entry === 'string') : [];
+    const rawId = typeof value.id === 'string' ? value.id.trim() : '';
+    return {
+        id: rawId || projectIdForPath(folderPath),
+        name: typeof value.name === 'string' && value.name.length > 0 ? value.name : basename,
+        folderPath,
+        intent: typeof value.intent === 'string' ? value.intent : '',
+        outcome: typeof value.outcome === 'string' ? value.outcome : '',
+        rules: typeof value.rules === 'string' ? value.rules : '',
+        brief: typeof value.brief === 'string' ? value.brief : (typeof value.intent === 'string' ? value.intent : ''),
+        team,
+        updatedAt: typeof value.updatedAt === 'string' ? value.updatedAt : undefined,
+    };
+}
+function normalizeAiHubProjectList(projects, currentProjectPath, options = {}) {
+    const byPath = new Map();
+    const currentKey = currentProjectPath ? normalizeProjectPath(currentProjectPath) : null;
+    const add = (entry) => {
+        if (!entry)
+            return;
+        const key = normalizeProjectPath(entry.folderPath);
+        if (!options.includeMissing && key !== currentKey && !projectPathExists(key))
+            return;
+        const existing = byPath.get(key);
+        byPath.set(key, existing ? { ...existing, ...entry, folderPath: key } : { ...entry, folderPath: key });
+    };
+    if (currentProjectPath)
+        add(normalizeProjectEntry({ folderPath: currentProjectPath }, currentProjectPath));
+    for (const project of projects)
+        add(normalizeProjectEntry(project));
+    return withUniqueProjectIds(Array.from(byPath.values()));
+}
 class AiHubPreferencesStore {
     constructor(stateFilePath = path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'ai-hub-state.json')) {
         this.stateFilePath = stateFilePath;
@@ -37,6 +120,7 @@ class AiHubPreferencesStore {
                     : {},
                 personaKey: typeof raw.personaKey === 'string' ? raw.personaKey : null,
                 apiKey: typeof raw.apiKey === 'string' && raw.apiKey.length > 0 ? raw.apiKey : undefined,
+                projects: normalizeAiHubProjectList(Array.isArray(raw.projects) ? raw.projects : [], projectPath),
             };
         }
         catch {
@@ -47,6 +131,20 @@ class AiHubPreferencesStore {
         fs_1.default.mkdirSync(path_1.default.dirname(this.stateFilePath), { recursive: true });
         fs_1.default.writeFileSync(this.stateFilePath, JSON.stringify(preferences, null, 2));
     }
+    saveProjects(projectPath, projects) {
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        const preferences = this.load(normalizedProjectPath);
+        const nextProjects = normalizeAiHubProjectList(projects, normalizedProjectPath);
+        this.save({ ...preferences, projectPath: normalizedProjectPath, projects: nextProjects });
+        return nextProjects;
+    }
+    mergeProjects(projectPath, projects) {
+        const normalizedProjectPath = normalizeProjectPath(projectPath);
+        const preferences = this.load(normalizedProjectPath);
+        const nextProjects = normalizeAiHubProjectList([...(preferences.projects || []), ...projects], normalizedProjectPath);
+        this.save({ ...preferences, projectPath: normalizedProjectPath, projects: nextProjects });
+        return nextProjects;
+    }
     remember(preferences, jobId, instructions) {
         const recentJobIds = jobId
             ? [jobId, ...preferences.recentJobIds.filter((value) => value !== jobId)].slice(0, 8)

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

@@ -1373,6 +1373,19 @@ class AiHubServer {
         }
     }
     getHttpsPort() { return this.httpsPort; }
+    knownProjects(projectPath, extras = []) {
+        const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
+        const preferences = this.preferencesStore.load(normalizedProjectPath);
+        const conversationProjects = this.conversationStore.listProjectPaths().map((folderPath) => ({ folderPath }));
+        return (0, preferences_1.normalizeAiHubProjectList)([
+            ...(preferences.projects || []),
+            ...conversationProjects,
+            ...extras,
+        ], normalizedProjectPath);
+    }
+    saveKnownProjects(projectPath, projects) {
+        return this.preferencesStore.saveProjects(path_1.default.resolve(projectPath || this.projectPath), this.knownProjects(projectPath, projects));
+    }
     async bootstrapResponse(projectPath, apiKey) {
         const normalizedProjectPath = path_1.default.resolve(projectPath || this.projectPath);
         const employees = this.hostRuntime.detectEmployees();
@@ -1402,6 +1415,9 @@ class AiHubServer {
         const managerTemplates = (0, catalog_1.discoverManagerTemplates)(normalizedProjectPath, catalogOptions);
         const { personas, subscriptionActive, workspaceId, userKey } = await this.computePersonas(apiKey || preferences.apiKey);
         const managerTeam = await this.computeManagerTeam(workspaceId, userKey);
+        const projects = this.knownProjects(normalizedProjectPath);
+        preferences = { ...preferences, projectPath: normalizedProjectPath, projects };
+        this.preferencesStore.save(preferences);
         // Issue #347: enrich the activeRun the same way GET /runs/:id does
         // so the bootstrap surface (used on first paint) carries stages and
         // live totals — not just the raw run state.
@@ -1418,6 +1434,7 @@ class AiHubServer {
             personas,
             subscriptionActive,
             activeRun,
+            projects,
             // Issue #512 (S3) — additive manager-flow projections.
             firstRun: this.computeFirstRun(normalizedProjectPath, jobs.length, personas),
             teamContext: this.computeTeamContext(normalizedProjectPath),
@@ -2183,6 +2200,26 @@ class AiHubServer {
                 return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not persist conversation.' });
             }
         });
+        this.app.get('/api/ai-hub/projects', (req, res) => {
+            const projectPath = typeof req.query.projectPath === 'string' && req.query.projectPath.length > 0
+                ? path_1.default.resolve(req.query.projectPath)
+                : this.projectPath;
+            return res.json({ projectPath, projects: this.knownProjects(projectPath), source: 'disk' });
+        });
+        this.app.put('/api/ai-hub/projects', (req, res) => {
+            try {
+                const body = (req.body ?? {});
+                const projectPath = ensureDirectoryPath(body.projectPath || this.projectPath);
+                if (!Array.isArray(body.projects)) {
+                    return res.status(400).json({ error: 'projects array required' });
+                }
+                const projects = this.saveKnownProjects(projectPath, body.projects);
+                return res.json({ projectPath, projects, source: 'disk' });
+            }
+            catch (error) {
+                return res.status(400).json({ error: error instanceof Error ? error.message : 'Could not persist projects.' });
+            }
+        });
         this.app.post('/api/ai-hub/api-key', (req, res) => {
             const { apiKey } = req.body;
             if (!apiKey || typeof apiKey !== 'string')

package/dist/src/cli/distribution/marketplace-bundles.js

@@ -202,7 +202,7 @@ function validateTargetMatrix(repoRoot, result) {
     const relPath = path_1.default.join(TARGET_ROOT, 'marketplace-targets.json');
     const targetMatrix = readJsonObject(repoRoot, relPath, result);
     if (!targetMatrix) {
-        return { remoteMcpUrl: null, oauthAuthorizationServer: null, productVersion: null };
+        return { remoteMcpUrl: null, oauthAuthorizationServer: null, productVersion: null, contactEmail: null };
     }
     assertEqual(targetMatrix.schema, 'fraim-marketplace-targets-v1', relPath, 'schema', result);
     assertEqual(targetMatrix.issue, 674, relPath, 'issue', result);
@@ -218,6 +218,13 @@ function validateTargetMatrix(repoRoot, result) {
     if (!productVersion) {
         addIssue(result.errors, relPath, 'product.packageVersion must be set');
     }
+    const contactEmail = product ? stringValue(product.contactEmail) : null;
+    if (!contactEmail) {
+        addIssue(result.errors, relPath, 'product.contactEmail must be set');
+    }
+    if (contactEmail && product) {
+        assertEqual(product.support, contactEmail, relPath, 'product.support', result);
+    }
     const packageVersion = readPackageVersion(repoRoot, result);
     if (productVersion && packageVersion) {
         assertEqual(productVersion, packageVersion, relPath, 'product.packageVersion', result);
@@ -229,7 +236,7 @@ function validateTargetMatrix(repoRoot, result) {
         ? requireHttpsUrl(remoteMcp.oauthAuthorizationServer, relPath, 'remoteMcp.oauthAuthorizationServer', result)
         : null;
     validateTargetEntries(repoRoot, relPath, asArray(targetMatrix.targets), result);
-    return { remoteMcpUrl, oauthAuthorizationServer, productVersion };
+    return { remoteMcpUrl, oauthAuthorizationServer, productVersion, contactEmail };
 }
 function validateOpenAiAssets(repoRoot, openAiRoot, result) {
     assertFile(repoRoot, path_1.default.join(openAiRoot, 'README.md'), result);
@@ -254,6 +261,7 @@ function validateOpenAiPacketFields(packet, relPath, targetDetails, result) {
     else {
         assertEqual(app.name, 'FRAIM', relPath, 'app.name', result);
         requireHttpsUrl(app.website, relPath, 'app.website', result);
+        assertEqual(app.support, targetDetails.contactEmail, relPath, 'app.support', result);
         requireHttpsUrl(app.privacyPolicy, relPath, 'app.privacyPolicy', result);
         requireHttpsUrl(app.termsOfService, relPath, 'app.termsOfService', result);
     }
@@ -288,7 +296,7 @@ function validateOpenAiPacket(repoRoot, result, targetDetails) {
     assertEqual(packet.schema, 'fraim-openai-app-submission-packet-v1', relPath, 'schema', result);
     validateOpenAiPacketFields(packet, relPath, targetDetails, result);
 }
-function validatePolicyPages(repoRoot, result) {
+function validatePolicyPages(repoRoot, targetDetails, result) {
     for (const relPath of POLICY_PAGE_PATHS) {
         if (!assertFile(repoRoot, relPath, result)) {
             continue;
@@ -297,7 +305,7 @@ function validatePolicyPages(repoRoot, result) {
         if (!content.includes('FRAIM')) {
             addIssue(result.errors, relPath, 'policy page must identify FRAIM');
         }
-        if (!content.includes('support@fraimworks.ai')) {
+        if (targetDetails.contactEmail && !content.includes(targetDetails.contactEmail)) {
             addIssue(result.errors, relPath, 'policy page must include support contact');
         }
     }
@@ -337,11 +345,12 @@ function validateCodexManifestInterface(repoRoot, pluginRoot, manifestRelPath, m
         assertRelativeAsset(repoRoot, pluginRoot, screenshot, manifestRelPath, `interface.screenshots[${index}]`, result);
     }
 }
-function validateCodexManifest(repoRoot, pluginRoot, manifest, manifestRelPath, productVersion, result) {
+function validateCodexManifest(repoRoot, pluginRoot, manifest, manifestRelPath, productVersion, contactEmail, result) {
     if (!manifest)
         return;
     assertEqual(manifest.name, 'fraim', manifestRelPath, 'name', result);
     assertEqual(manifest.version, productVersion, manifestRelPath, 'version', result);
+    assertEqual(asObject(manifest.author)?.email, contactEmail, manifestRelPath, 'author.email', result);
     assertEqual(manifest.skills, './skills/', manifestRelPath, 'skills', result);
     assertEqual(manifest.mcpServers, './.mcp.json', manifestRelPath, 'mcpServers', result);
     const manifestInterface = asObject(manifest.interface);
@@ -400,17 +409,21 @@ function validateCodexPackage(repoRoot, result, targetDetails) {
     const manifest = readJsonObject(repoRoot, manifestRelPath, result);
     const mcpConfig = readJsonObject(repoRoot, mcpRelPath, result);
     validateCodexMarketplace(marketplace, marketplaceRelPath, result);
-    validateCodexManifest(repoRoot, pluginRoot, manifest, manifestRelPath, targetDetails.productVersion, result);
+    validateCodexManifest(repoRoot, pluginRoot, manifest, manifestRelPath, targetDetails.productVersion, targetDetails.contactEmail, result);
     validateCodexMcpConfig(mcpConfig, mcpRelPath, targetDetails.remoteMcpUrl, result);
     validateCodexSkill(repoRoot, skillRelPath, result);
 }
-function validateSimpleMarketplaceManifest(marketplace, marketplaceRelPath, expectedName, expectedSource, productVersion, result) {
+function validateSimpleMarketplaceManifest(marketplace, marketplaceRelPath, expectedName, expectedSource, productVersion, contactEmail, result) {
     if (!marketplace)
         return;
     assertEqual(marketplace.name, expectedName, marketplaceRelPath, 'name', result);
-    if (!asObject(marketplace.owner)) {
+    const owner = asObject(marketplace.owner);
+    if (!owner) {
         addIssue(result.errors, marketplaceRelPath, 'owner must be an object');
     }
+    else {
+        assertEqual(owner.email, contactEmail, marketplaceRelPath, 'owner.email', result);
+    }
     const entries = asArray(marketplace.plugins);
     const fraimEntry = entries
         .map((entry) => asObject(entry))
@@ -421,6 +434,10 @@ function validateSimpleMarketplaceManifest(marketplace, marketplaceRelPath, expe
     }
     assertEqual(fraimEntry.source, expectedSource, marketplaceRelPath, 'fraim.source', result);
     assertEqual(fraimEntry.version, productVersion, marketplaceRelPath, 'fraim.version', result);
+    const author = asObject(fraimEntry.author);
+    if (author) {
+        assertEqual(author.email, contactEmail, marketplaceRelPath, 'fraim.author.email', result);
+    }
 }
 function validateMcpRegistryPackage(repoRoot, result, targetDetails) {
     const registryRoot = path_1.default.join(TARGET_ROOT, 'mcp-registry');
@@ -467,11 +484,12 @@ function validateCursorPackage(repoRoot, result, targetDetails) {
     const mcpConfig = readJsonObject(repoRoot, mcpRelPath, result);
     assertFile(repoRoot, path_1.default.join(cursorRoot, 'README.md'), result);
     assertFile(repoRoot, path_1.default.join(pluginRoot, 'README.md'), result);
-    validateSimpleMarketplaceManifest(rootMarketplace, ROOT_CURSOR_MARKETPLACE_PATH, 'fraim-marketplace', 'marketplaces/fraim/cursor/plugins/fraim', targetDetails.productVersion, result);
-    validateSimpleMarketplaceManifest(targetMarketplace, targetMarketplaceRelPath, 'fraim-marketplace', 'plugins/fraim', targetDetails.productVersion, result);
+    validateSimpleMarketplaceManifest(rootMarketplace, ROOT_CURSOR_MARKETPLACE_PATH, 'fraim-marketplace', 'marketplaces/fraim/cursor/plugins/fraim', targetDetails.productVersion, targetDetails.contactEmail, result);
+    validateSimpleMarketplaceManifest(targetMarketplace, targetMarketplaceRelPath, 'fraim-marketplace', 'plugins/fraim', targetDetails.productVersion, targetDetails.contactEmail, result);
     if (manifest) {
         assertEqual(manifest.name, 'fraim', manifestRelPath, 'name', result);
         assertEqual(manifest.version, targetDetails.productVersion, manifestRelPath, 'version', result);
+        assertEqual(asObject(manifest.author)?.email, targetDetails.contactEmail, manifestRelPath, 'author.email', result);
         assertEqual(manifest.rules, 'rules/', manifestRelPath, 'rules', result);
         assertEqual(manifest.skills, 'skills/', manifestRelPath, 'skills', result);
         assertEqual(manifest.commands, 'commands/', manifestRelPath, 'commands', result);
@@ -514,10 +532,11 @@ function validateCopilotPackage(repoRoot, result, targetDetails) {
     const mcpConfig = readJsonObject(repoRoot, mcpRelPath, result);
     assertFile(repoRoot, path_1.default.join(vscodeRoot, 'README.md'), result);
     assertFile(repoRoot, path_1.default.join(pluginRoot, 'README.md'), result);
-    validateSimpleMarketplaceManifest(rootMarketplace, ROOT_COPILOT_MARKETPLACE_PATH, 'fraim-copilot-marketplace', 'marketplaces/fraim/vscode/plugins/fraim', targetDetails.productVersion, result);
+    validateSimpleMarketplaceManifest(rootMarketplace, ROOT_COPILOT_MARKETPLACE_PATH, 'fraim-copilot-marketplace', 'marketplaces/fraim/vscode/plugins/fraim', targetDetails.productVersion, targetDetails.contactEmail, result);
     if (manifest) {
         assertEqual(manifest.name, 'fraim', manifestRelPath, 'name', result);
         assertEqual(manifest.version, targetDetails.productVersion, manifestRelPath, 'version', result);
+        assertEqual(asObject(manifest.author)?.email, targetDetails.contactEmail, manifestRelPath, 'author.email', result);
         assertEqual(manifest.skills, 'skills/', manifestRelPath, 'skills', result);
         assertEqual(manifest.commands, 'commands/', manifestRelPath, 'commands', result);
         assertEqual(manifest.mcpServers, '.mcp.json', manifestRelPath, 'mcpServers', result);
@@ -559,7 +578,7 @@ function validateMarketplaceBundles(repoRoot = process.cwd()) {
     assertFile(repoRoot, ACCEPTANCE_EVIDENCE_PATH, result);
     const targetDetails = validateTargetMatrix(repoRoot, result);
     validateOpenAiPacket(repoRoot, result, targetDetails);
-    validatePolicyPages(repoRoot, result);
+    validatePolicyPages(repoRoot, targetDetails, result);
     validateCodexPackage(repoRoot, result, targetDetails);
     validateMcpRegistryPackage(repoRoot, result, targetDetails);
     validateCursorPackage(repoRoot, result, targetDetails);

package/dist/src/services/admin-service.js

@@ -166,7 +166,7 @@ class AdminService {
         });
         const emailService = new email_service_1.EmailService();
         const baseUrl = process.env.BASE_URL || 'https://fraimworks.ai';
-        await emailService.sendEmailCode(emailLower, `${baseUrl}/get-started`, verificationCode, { purpose: 'request-access' });
+        await emailService.sendEmailCode(emailLower, `${baseUrl}/?email=${encodeURIComponent(emailLower)}`, verificationCode, { purpose: 'request-access' });
         console.log('[FRAIM] request_access email_code_sent', { userId: emailLower });
         return {
             success: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.182",
+  "version": "2.0.183",
   "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

@@ -428,6 +428,12 @@
   </div>
 
       </div><!-- /.workspace-conv -->
+      <div class="proj-switch-mask" id="proj-switch-mask" role="status" aria-live="polite" aria-hidden="true">
+        <div class="proj-switch-panel">
+          <span class="proj-switch-spinner" aria-hidden="true"></span>
+          <span id="proj-switch-label">Loading project...</span>
+        </div>
+      </div>
     </div><!-- /#proj-workspace -->
   </section><!-- /#area-projects -->
 

package/public/ai-hub/script.js

@@ -50,6 +50,8 @@ const state = {
   _hireStripPending: null,
 };
 
+const bootstrapCache = new Map();
+
 const els = {};
 
 // ---------------------------------------------------------------------------
@@ -120,14 +122,16 @@ async function requestJson(url, options) {
   return payload;
 }
 
-async function loadBootstrap(projectPath, docUrl) {
-  const params = new URLSearchParams();
-  if (projectPath) params.set('projectPath', projectPath);
-  if (docUrl) params.set('docUrl', docUrl);
-  const query = params.toString() ? '?' + params.toString() : '';
-  const fetchOptions = {};
-  if (state.storedApiKey) fetchOptions.headers = { 'x-api-key': state.storedApiKey };
-  const bootstrap = await requestJson(`/api/ai-hub/bootstrap${query}`, fetchOptions);
+function bootstrapCacheKey(projectPath, docUrl) {
+  return `${tfCanonicalProjectPath(projectPath || '')}::${docUrl || ''}`;
+}
+
+function cacheBootstrapPayload(bootstrap, docUrl) {
+  if (!bootstrap || !bootstrap.project || !bootstrap.project.path) return;
+  bootstrapCache.set(bootstrapCacheKey(bootstrap.project.path, docUrl), bootstrap);
+}
+
+function applyBootstrap(bootstrap, docUrl) {
   state.bootstrap = bootstrap;
   state.projectPath = bootstrap.project.path;
   state.selectedEmployeeId = state.selectedEmployeeId || bootstrap.preferences.employeeId;
@@ -162,6 +166,45 @@ async function loadBootstrap(projectPath, docUrl) {
   // Issue #540: render the persona grid and manager team pool.
   renderPersonaGrid();
   renderManagerTeamPool();
+  cacheBootstrapPayload(bootstrap, docUrl);
+}
+
+async function fetchBootstrap(projectPath, docUrl) {
+  const params = new URLSearchParams();
+  if (projectPath) params.set('projectPath', projectPath);
+  if (docUrl) params.set('docUrl', docUrl);
+  const query = params.toString() ? '?' + params.toString() : '';
+  const fetchOptions = {};
+  if (state.storedApiKey) fetchOptions.headers = { 'x-api-key': state.storedApiKey };
+  const bootstrap = await requestJson(`/api/ai-hub/bootstrap${query}`, fetchOptions);
+  cacheBootstrapPayload(bootstrap, docUrl);
+  return bootstrap;
+}
+
+async function refreshBootstrapInBackground(projectPath, docUrl) {
+  try {
+    const bootstrap = await fetchBootstrap(projectPath, docUrl);
+    if (tfCanonicalProjectPath(state.projectPath) !== tfCanonicalProjectPath(bootstrap.project.path)) return;
+    applyBootstrap(bootstrap, docUrl);
+    await hydrateConversationsFromServer();
+    tfRefreshAfterBootstrap();
+  } catch (error) {
+    console.warn('[512] Background project refresh failed:', error);
+  }
+}
+
+async function loadBootstrap(projectPath, docUrl, options) {
+  const opts = options || {};
+  const requestedKey = bootstrapCacheKey(projectPath || state.projectPath, docUrl);
+  if (opts.preferCache && bootstrapCache.has(requestedKey)) {
+    const cached = bootstrapCache.get(requestedKey);
+    applyBootstrap(cached, docUrl);
+    if (opts.backgroundRefresh !== false) refreshBootstrapInBackground(projectPath, docUrl);
+    return cached;
+  }
+  const bootstrap = await fetchBootstrap(projectPath, docUrl);
+  applyBootstrap(bootstrap, docUrl);
+  return bootstrap;
 }
 
 // ---------------------------------------------------------------------------
@@ -348,6 +391,11 @@ function friendlyProjectName(p) {
   return parts.slice(-2).join('/') || p;
 }
 
+function friendlyProjectShortName(p) {
+  const friendly = friendlyProjectName(p);
+  return friendly.split(/[\\/]/).filter(Boolean).pop() || friendly;
+}
+
 // ---------------------------------------------------------------------------
 // Conversation persistence (per project, in localStorage)
 // ---------------------------------------------------------------------------
@@ -5982,20 +6030,137 @@ function tfPersonaByKey(key) { return tfPersonas().find((p) => p.key === key) ||
 // ---------------------------------------------------------------------------
 // Persistence (projects + assignments, mirrors the conversation model)
 // ---------------------------------------------------------------------------
+function tfCanonicalProjectPath(folderPath) {
+  const value = String(folderPath || '').replace(/\\/g, '/').replace(/\/+$/, '');
+  return /^[A-Za-z]:\//.test(value) ? value.toLowerCase() : value;
+}
+
+function tfProjectIdForPath(folderPath) {
+  const canonical = tfCanonicalProjectPath(folderPath);
+  let hash = 0;
+  for (let i = 0; i < canonical.length; i++) hash = ((hash << 5) - hash + canonical.charCodeAt(i)) | 0;
+  return 'p-' + Math.abs(hash).toString(36);
+}
+
+function tfNormalizeProject(raw, fallbackPath) {
+  if (!raw || typeof raw !== 'object') return null;
+  const folderPath = raw.folderPath || raw.path || raw.folder || fallbackPath || '';
+  if (!folderPath) return null;
+  const cleanPath = String(folderPath);
+  const rawId = typeof raw.id === 'string' ? raw.id.trim() : '';
+  return {
+    id: rawId || tfProjectIdForPath(cleanPath),
+    name: raw.name || friendlyProjectShortName(cleanPath),
+    folderPath: cleanPath,
+    intent: raw.intent || '',
+    outcome: raw.outcome || '',
+    rules: raw.rules || '',
+    brief: raw.brief || raw.intent || '',
+    team: Array.isArray(raw.team) ? raw.team.filter((key) => typeof key === 'string') : [],
+    updatedAt: raw.updatedAt || undefined,
+  };
+}
+
+function tfApplyUniqueProjectIds(projects) {
+  const seen = new Set();
+  return (projects || []).map((project) => {
+    const fallbackId = tfProjectIdForPath(project.folderPath || project.path || project.folder);
+    const rawId = typeof project.id === 'string' ? project.id.trim() : '';
+    let id = rawId && rawId !== 'p-current' ? rawId : fallbackId;
+    let suffix = 2;
+    while (seen.has(id)) {
+      id = `${fallbackId}-${suffix}`;
+      suffix += 1;
+    }
+    seen.add(id);
+    return { ...project, id };
+  });
+}
+
+function tfMergeProjects(projects) {
+  const merged = new Map();
+  const add = (project) => {
+    const normalized = tfNormalizeProject(project);
+    if (!normalized) return;
+    const key = tfCanonicalProjectPath(normalized.folderPath);
+    const existing = merged.get(key);
+    if (existing) {
+      const next = { ...existing, ...normalized, folderPath: normalized.folderPath || existing.folderPath };
+      if ((!Array.isArray(normalized.team) || normalized.team.length === 0) && Array.isArray(existing.team) && existing.team.length > 0) {
+        next.team = existing.team;
+      }
+      merged.set(key, next);
+    } else {
+      merged.set(key, normalized);
+    }
+  };
+  for (const project of tf.projects || []) add(project);
+  for (const project of projects || []) add(project);
+  tf.projects = tfApplyUniqueProjectIds(Array.from(merged.values()));
+}
+
+function tfProjectForPath(folderPath) {
+  const key = tfCanonicalProjectPath(folderPath);
+  return tf.projects.find((project) => tfCanonicalProjectPath(project.folderPath || project.path || project.folder) === key) || null;
+}
+
+function tfEnsureCurrentProject() {
+  if (!state.projectPath) return null;
+  const current = tfNormalizeProject({
+    id: tfProjectIdForPath(state.projectPath),
+    name: friendlyProjectShortName(state.projectPath),
+    folderPath: state.projectPath,
+    team: tfHiredPersonas().map((p) => p.key),
+  }, state.projectPath);
+  tfMergeProjects([current]);
+  const resolved = tfProjectForPath(state.projectPath);
+  if (!tf.activeProjectId || !tf.projects.some((project) => project.id === tf.activeProjectId)) {
+    tf.activeProjectId = resolved ? resolved.id : tf.projects[0]?.id || null;
+  }
+  return resolved;
+}
+
 function tfLoadStorage() {
-  try { tf.projects = JSON.parse(window.localStorage.getItem(STORAGE_KEY_PROJECTS_512) || '[]'); }
+  try {
+    const stored = JSON.parse(window.localStorage.getItem(STORAGE_KEY_PROJECTS_512) || '[]');
+    const normalized = Array.isArray(stored) ? stored.map((project) => tfNormalizeProject(project)).filter(Boolean) : [];
+    tf.projects = tfApplyUniqueProjectIds(normalized);
+  }
   catch { tf.projects = []; }
   try { tf.assignments = JSON.parse(window.localStorage.getItem(STORAGE_KEY_ASSIGNMENTS_512) || '{}'); }
   catch { tf.assignments = {}; }
 }
 function tfPersistProjects() {
   try { window.localStorage.setItem(STORAGE_KEY_PROJECTS_512, JSON.stringify(tf.projects)); } catch {}
+  if (!state.projectPath) return;
+  requestJson('/api/ai-hub/projects', {
+    method: 'PUT',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ projectPath: state.projectPath, projects: tf.projects }),
+  }).catch((error) => console.warn('[512] Could not persist projects to local disk:', error));
 }
 function tfPersistAssignments() {
   try { window.localStorage.setItem(STORAGE_KEY_ASSIGNMENTS_512, JSON.stringify(tf.assignments)); } catch {}
 }
 function tfProjectAssignments(projectId) { return tf.assignments[projectId] || []; }
 
+function tfSetProjectSwitching(active, project) {
+  const workspace = document.getElementById('proj-workspace');
+  const mask = document.getElementById('proj-switch-mask');
+  const label = document.getElementById('proj-switch-label');
+  if (workspace) {
+    workspace.classList.toggle('project-switching', !!active);
+    workspace.setAttribute('aria-busy', active ? 'true' : 'false');
+  }
+  if (mask) mask.setAttribute('aria-hidden', active ? 'false' : 'true');
+  if (label && project) {
+    label.textContent = `Loading ${project.name || friendlyProjectShortName(project.folderPath || project.path || project.folder)}...`;
+  }
+  document.querySelectorAll('#proj-tabs .ptab').forEach((tab) => {
+    if (tab.id !== 'ptab-add') tab.disabled = !!active;
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Status dots — derived from each conversation's read-side run projection.
 //   red = needs you, amber = working, green = done, grey = idle/no run.
@@ -6023,9 +6188,13 @@ function tfConvForAssignment(assignment) {
 }
 // #521 R6.5: all past runs of a job across the workspace (newest first) — powers
 // the run history under the Company/Manager rail jobs, same as the project tree.
-function tfConversationsForJob(jobId) {
+function tfConversationsForJob(jobId, opts) {
   const out = [];
-  for (const list of Object.values(state.conversations || {})) {
+  const projectPath = opts && opts.projectPath;
+  const lists = projectPath
+    ? [state.conversations[projectPath] || []]
+    : Object.values(state.conversations || {});
+  for (const list of lists) {
     for (const c of (list || [])) if (c && c.jobId === jobId) out.push(c);
   }
   out.sort((a, b) => (b.updatedAt || b.createdAt || 0) - (a.updatedAt || a.createdAt || 0));
@@ -6079,7 +6248,7 @@ function tfShowArea(area) {
   window.scrollTo(0, 0);
 }
 
-function tfSelectProjectView(view, projectId) {
+async function tfSelectProjectView(view, projectId) {
   tf.projectView = view;
   if (projectId) tf.activeProjectId = projectId;
   // Always return to the conversation when changing views.
@@ -6100,9 +6269,16 @@ function tfSelectProjectView(view, projectId) {
     // When switching to a project workspace, switch the active folder so all
     // runs, context reads, and learnings scope to that project's disk location.
     const proj = tf.projects.find((p) => p.id === tf.activeProjectId);
-    if (proj && proj.folderPath && proj.folderPath !== state.projectPath) {
-      tfSwitchProjectFolder(proj.folderPath).catch((e) =>
-        console.warn('[512] tfSwitchProjectFolder failed:', e));
+    const folderPath = proj && (proj.folderPath || proj.path || proj.folder);
+    if (folderPath && tfCanonicalProjectPath(folderPath) !== tfCanonicalProjectPath(state.projectPath)) {
+      try {
+        tfSetProjectSwitching(true, proj);
+        await tfSwitchProjectFolder(folderPath);
+      } catch (e) {
+        console.warn('[512] tfSwitchProjectFolder failed:', e);
+      } finally {
+        tfSetProjectSwitching(false);
+      }
     }
     // #521 fix: invalidate the project-scoped context cache whenever the active
     // project changes — covers new-project creation (where state.projectPath is
@@ -6417,7 +6593,7 @@ function kbMakeCard(conv) {
   // Kanban/Cards overview is read-only. Clicking anywhere on the card navigates to the workspace.
   const navigate = () => {
     if (!conv.id) return;
-    const _proj = conv.projectPath ? tf.projects.find((p) => p.folderPath === conv.projectPath) : null;
+    const _proj = conv.projectPath ? tfProjectForPath(conv.projectPath) : null;
     tfSelectProjectView('workspace', _proj ? _proj.id : tf.activeProjectId);
     switchToConversation(conv.id);
   };
@@ -7789,7 +7965,7 @@ function tfProjectUpdatesSection() {
   av.textContent = '🔄';
   const id = document.createElement('div'); id.className = 'eh-id';
   const nm = document.createElement('div'); nm.className = 'eh-name'; nm.style.fontSize = '14px'; nm.textContent = 'Project Updates';
-  const totalRuns = JOBS.reduce((n, j) => n + tfConversationsForJob(j.id).length, 0);
+  const totalRuns = JOBS.reduce((n, j) => n + tfConversationsForJob(j.id, { projectPath: state.projectPath }).length, 0);
   const role = document.createElement('div'); role.className = 'eh-role';
   role.textContent = totalRuns ? (totalRuns + (totalRuns === 1 ? ' run' : ' runs')) : 'Onboarding & learnings';
   id.appendChild(nm); id.appendChild(role);
@@ -7811,7 +7987,7 @@ function tfProjectUpdatesSection() {
     const head = document.createElement('div'); head.className = 'pu-job-name';
     head.textContent = j.ico + '  ' + j.name;
     group.appendChild(head);
-    const runs = tfConversationsForJob(j.id);
+    const runs = tfConversationsForJob(j.id, { projectPath: state.projectPath });
     if (!runs.length) {
       const none = document.createElement('div'); none.className = 'eh-empty'; none.textContent = 'No runs yet.';
       group.appendChild(none);
@@ -9045,8 +9221,13 @@ async function tfCreateProject() {
  * the server's preferences store records it so it survives restart.
  */
 async function tfSwitchProjectFolder(folderPath) {
-  if (!folderPath || folderPath === state.projectPath) return;
-  state.projectPath = folderPath;
+  const normalized = tfNormalizeProject({ folderPath });
+  if (!normalized) return;
+  if (tfCanonicalProjectPath(normalized.folderPath) === tfCanonicalProjectPath(state.projectPath)) {
+    await hydrateConversationsFromServer();
+    return;
+  }
+  state.projectPath = normalized.folderPath;
   // #521 fix: the context cache (state._ctxCache) is keyed by context key only
   // (projectContext/projectBrief/projectRules), NOT by project — so without this
   // the new project's Brief section would render the PREVIOUS project's content
@@ -9056,7 +9237,23 @@ async function tfSwitchProjectFolder(folderPath) {
   for (const k of ['projectContext', 'projectBrief', 'projectRules']) delete cache[k];
   // loadBootstrap sends projectPath as a query param — the server records it
   // in its preferences store so this folder becomes the default on next load.
-  await loadBootstrap(folderPath);
+  const cachedConversations = Array.isArray(state.conversations[normalized.folderPath]);
+  const conversationsPromise = cachedConversations ? null : hydrateConversationsFromServer();
+  await loadBootstrap(normalized.folderPath, undefined, { preferCache: true });
+  if (cachedConversations) {
+    renderRail();
+    renderActive();
+    hydrateConversationsFromServer().catch((error) =>
+      console.warn('[512] Could not refresh project conversations:', error)
+    );
+  } else {
+    await conversationsPromise;
+  }
+  tfMergeProjects(state.bootstrap && Array.isArray(state.bootstrap.projects) ? state.bootstrap.projects : []);
+  const currentProject = tfEnsureCurrentProject();
+  if (currentProject) tf.activeProjectId = currentProject.id;
+  tfPersistProjects();
+  tfRefreshAfterBootstrap();
 }
 
 // ---------------------------------------------------------------------------
@@ -9078,7 +9275,7 @@ function tfOpenAssignJob(employeeKey) {
   const filterKey = employeeKey || null;
   const filterPersona = filterKey ? tfPersonaByKey(filterKey) : null;
   const filterName = filterPersona ? (filterPersona.displayName || filterKey) : null;
-  if (title) title.textContent = filterKey ? ('Jobs for ' + filterName) : 'Assign a job';
+  if (title) title.textContent = filterKey ? ('Assign a job to ' + filterName) : 'Assign a job';
 
   const allJobs = (state.bootstrap && state.bootstrap.jobs) || [];
   const personasToShow = filterKey ? hired.filter((p) => p.key === filterKey) : hired;
@@ -9132,7 +9329,7 @@ function tfOpenAssignJob(employeeKey) {
       if (specificJobs.length > 0) {
         const specLabel = document.createElement('div');
         specLabel.className = 'cat-label';
-        specLabel.textContent = (filterName || persona.displayName) + '’s specialty';
+        specLabel.textContent = (filterName || persona.displayName) + "'s jobs";
         listWrap.appendChild(specLabel);
         specificJobs.forEach(function(job) { listWrap.appendChild(buildJobRow(av, job, persona)); });
       }
@@ -9538,19 +9735,15 @@ function tfInitShell() {
   const tabs = document.getElementById('hub-tabs');
   if (tabs) tabs.hidden = false;
   tfLoadStorage();
+  tfMergeProjects(state.bootstrap && Array.isArray(state.bootstrap.projects) ? state.bootstrap.projects : []);
   tfWireShell();
   tfPopulateAccountMenu(); // #533: show the real account identity, not "SM"
   // Seed a project from the loaded folder so the workspace reuses the existing
   // conversation machinery for that real project path.
-  if (state.projectPath && !tf.projects.length) {
-    const proj = {
-      id: 'p-current',
-      name: friendlyProjectName(state.projectPath),
-      intent: '', brief: '', team: tfHiredPersonas().map((p) => p.key), path: state.projectPath,
-    };
-    tf.projects.push(proj);
-    if (!tf.assignments[proj.id]) tf.assignments[proj.id] = [];
-    tf.activeProjectId = proj.id;
+  const currentProject = tfEnsureCurrentProject();
+  if (currentProject && !tf.assignments[currentProject.id]) tf.assignments[currentProject.id] = [];
+  if (currentProject) {
+    tf.activeProjectId = currentProject.id;
     tfPersistProjects();
   } else if (tf.projects.length && !tf.activeProjectId) {
     tf.activeProjectId = tf.projects[0].id;
@@ -9577,6 +9770,9 @@ function tfInitShell() {
 // Refresh shell-derived UI after a bootstrap reload (e.g. project picked).
 function tfRefreshAfterBootstrap() {
   if (!tf.enabled) return;
+  tfMergeProjects(state.bootstrap && Array.isArray(state.bootstrap.projects) ? state.bootstrap.projects : []);
+  tfEnsureCurrentProject();
+  tfPersistProjects();
   tfRenderProjectTabs();
   if (tf.area === 'company') tfRenderCompany();
   else if (tf.area === 'manager') tfRenderManager();

package/public/ai-hub/styles.css

@@ -2915,6 +2915,50 @@ body.hub-shell { display: flex; flex-direction: column; height: 100vh; overflow:
   display: flex;
   flex: 1;
   min-height: 0;
+  position: relative;
+}
+.proj-switch-mask {
+  position: absolute;
+  inset: 0;
+  z-index: 30;
+  display: none;
+  align-items: center;
+  justify-content: center;
+  background: rgba(250, 250, 250, .74);
+  backdrop-filter: blur(2px);
+  pointer-events: auto;
+}
+#proj-workspace.project-switching .proj-switch-mask { display: flex; }
+.proj-switch-panel {
+  display: inline-flex;
+  align-items: center;
+  gap: 10px;
+  min-height: 38px;
+  max-width: min(320px, calc(100vw - 48px));
+  padding: 9px 14px;
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  background: var(--surface);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, .12);
+  color: var(--text);
+  font-size: 13px;
+  font-weight: 600;
+}
+.proj-switch-spinner {
+  width: 16px;
+  height: 16px;
+  border: 2px solid rgba(0, 0, 0, .14);
+  border-top-color: var(--accent);
+  border-radius: 50%;
+  flex: 0 0 auto;
+  animation: proj-switch-spin .8s linear infinite;
+}
+@keyframes proj-switch-spin {
+  to { transform: rotate(360deg); }
+}
+.ptab:disabled {
+  cursor: wait;
+  opacity: .72;
 }
 .tree-sidebar {
   width: var(--tree-sidebar-width);