fraim 2.0.212 → 2.0.214

package/dist/src/cli/commands/setup.js

@@ -374,12 +374,13 @@ const runSetup = async (options) => {
         }
     }
     else {
-        // Hub path: launch the Hub with firstRun=true and let the user pick a project there.
+        // Hub path (#866 R1): launch the FRAIM Hub desktop app and let the user pick a
+        // project there. The desktop shell opens its own window, so there is no URL to print.
         const { FirstRunSessionService } = await Promise.resolve().then(() => __importStar(require('../../first-run/session-service')));
         const svc = new FirstRunSessionService({ key: 'setup-hub-launch', projectRoot: process.cwd() });
         const result = await svc.openHub();
         if (result.ok) {
-            console.log(chalk_1.default.green(`\n  Hub is open at ${result.hubUrl}`));
+            console.log(chalk_1.default.green('\n  FRAIM Hub is opening in the desktop app.'));
             console.log(chalk_1.default.gray('  Your AI employee will help you onboard your first project.'));
         }
         else {

package/dist/src/cli/utils/local-folder-sync.js

@@ -0,0 +1,178 @@
+"use strict";
+/**
+ * Local-folder backend for per-layer learnings (issue #834).
+ *
+ * Supports OneDrive, SharePoint, Google Drive for Desktop, and any
+ * other sync client that maintains a locally-accessible folder. FRAIM
+ * reads from and writes to the declared local path; the OS sync client
+ * handles upload and download. No cloud API calls, no OAuth tokens.
+ *
+ * Layout expected under localPath:
+ *   context/   — org_context.md / manager_context.md
+ *   rules/     — org_rules.md / manager_rules.md
+ *   learnings/ — synthesized learning files (allowlisted names only)
+ *
+ * Conflict resolution
+ * -------------------
+ * Sync clients write conflict copies when two machines write the same
+ * file before either syncs. FRAIM skips conflict copies on read (they
+ * never override the canonical file) and uses atomic temp-rename on
+ * write (minimises the window where the client picks up a partial file).
+ *
+ * Known conflict-copy patterns:
+ *   OneDrive / SharePoint:
+ *     "file (User Name's conflicted copy 2026-07-18).md"
+ *     "file-UserName-PC.md" (some Windows clients)
+ *   Google Drive for Desktop:
+ *     "file (1).md"
+ *   Dropbox:
+ *     "file (Jane's conflicted copy 2026-07-18).md"
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFLICT_COPY_RE = exports.LOCAL_FOLDER_PACK_DIRS = void 0;
+exports.isConflictCopy = isConflictCopy;
+exports.countConflictCopies = countConflictCopies;
+exports.collectLocalFolderFiles = collectLocalFolderFiles;
+exports.writeLocalFolderFile = writeLocalFolderFile;
+exports.localFolderVersion = localFolderVersion;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+/** Pack subdirectories expected in every local-folder backend. */
+exports.LOCAL_FOLDER_PACK_DIRS = ['context', 'rules', 'learnings'];
+/**
+ * Matches the conflict-copy filename patterns produced by OneDrive,
+ * SharePoint, Google Drive for Desktop, and Dropbox.
+ *
+ * Deliberately does NOT match ordinary parenthesised names like
+ * "sprint-retro (Q2 2026).md" — only the well-known suffix patterns.
+ */
+exports.CONFLICT_COPY_RE = /[\s-](\([^)]*'s conflicted copy \d{4}-\d{2}-\d{2}\)|\(\d+\)|[\w-]+-PC)\.md$/i;
+/** True when the filename looks like a sync-client conflict copy. */
+function isConflictCopy(fileName) {
+    return exports.CONFLICT_COPY_RE.test(fileName);
+}
+/**
+ * Count conflict-copy files directly under dirPath/learnings (non-recursive).
+ * Used by the Hub UI to surface an amber "N conflicts" indicator.
+ */
+function countConflictCopies(localPath) {
+    let count = 0;
+    for (const dirName of exports.LOCAL_FOLDER_PACK_DIRS) {
+        const dir = path_1.default.join(localPath, dirName);
+        if (!fs_1.default.existsSync(dir))
+            continue;
+        try {
+            for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+                if (entry.isFile() && isConflictCopy(entry.name))
+                    count++;
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    return count;
+}
+/**
+ * Collect pack files from the local folder, applying the same path
+ * allowlist as the git and cloud backends. Conflict copies are skipped.
+ *
+ * pathGuard is a function (relativePath) => boolean — callers pass
+ * isSafePackPath (org) or isManagerPackRelativePath (manager).
+ */
+function collectLocalFolderFiles(localPath, pathGuard) {
+    const files = [];
+    for (const dirName of exports.LOCAL_FOLDER_PACK_DIRS) {
+        const dir = path_1.default.join(localPath, dirName);
+        if (!fs_1.default.existsSync(dir))
+            continue;
+        try {
+            for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+                if (!entry.isFile())
+                    continue;
+                if (isConflictCopy(entry.name))
+                    continue;
+                const rel = `${dirName}/${entry.name}`;
+                if (!pathGuard(rel))
+                    continue;
+                const content = fs_1.default.readFileSync(path_1.default.join(dir, entry.name), 'utf8');
+                files.push({ relativePath: rel, content });
+            }
+        }
+        catch { /* non-fatal — missing subdirs are fine */ }
+    }
+    return files;
+}
+/**
+ * Atomically write a file into the local folder.
+ *
+ * Writes to a hidden temp file first (.fraim-tmp-<uuid>.<ext>), then
+ * renames into place. This limits the window the OS sync client sees a
+ * partial file to the ~1ms of the rename syscall.
+ *
+ * Pre-write stale-read guard: if the target file exists and was modified
+ * more recently than lastSyncedAt, returns { skipped: true } so callers
+ * can re-sync before writing. Pass undefined to skip the guard.
+ */
+function writeLocalFolderFile(localPath, relativePath, content, lastSyncedAt) {
+    const dest = path_1.default.join(localPath, relativePath);
+    const dir = path_1.default.dirname(dest);
+    // Stale-read guard.
+    if (lastSyncedAt && fs_1.default.existsSync(dest)) {
+        const mtime = fs_1.default.statSync(dest).mtimeMs;
+        if (mtime > lastSyncedAt.getTime()) {
+            return {
+                written: false,
+                skipped: true,
+                reason: `Remote update detected (file mtime ${new Date(mtime).toISOString()} > lastSyncedAt ${lastSyncedAt.toISOString()}). Re-sync before writing.`,
+            };
+        }
+    }
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    const ext = path_1.default.extname(relativePath);
+    const tmpName = `.fraim-tmp-${crypto_1.default.randomUUID()}${ext}`;
+    const tmp = path_1.default.join(dir, tmpName);
+    try {
+        fs_1.default.writeFileSync(tmp, content, 'utf8');
+        fs_1.default.renameSync(tmp, dest);
+        return { written: true, skipped: false };
+    }
+    catch (err) {
+        try {
+            fs_1.default.rmSync(tmp, { force: true });
+        }
+        catch { /* ignore */ }
+        throw err;
+    }
+}
+/**
+ * A stable version string for the local-folder backend — a hex digest
+ * of the most recent mtime across all pack files. Changes whenever any
+ * file in the folder is written (by this machine or the sync client).
+ */
+function localFolderVersion(localPath) {
+    const mtimes = [];
+    for (const dirName of exports.LOCAL_FOLDER_PACK_DIRS) {
+        const dir = path_1.default.join(localPath, dirName);
+        if (!fs_1.default.existsSync(dir))
+            continue;
+        try {
+            for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+                if (!entry.isFile() || isConflictCopy(entry.name))
+                    continue;
+                try {
+                    mtimes.push(fs_1.default.statSync(path_1.default.join(dir, entry.name)).mtimeMs);
+                }
+                catch { /* skip files we can't stat */ }
+            }
+        }
+        catch { /* non-fatal */ }
+    }
+    if (mtimes.length === 0)
+        return '0';
+    const hash = crypto_1.default.createHash('sha1');
+    hash.update(mtimes.sort((a, b) => a - b).join(','));
+    return hash.digest('hex').slice(0, 12);
+}

package/dist/src/cli/utils/manager-pack-sync.js

@@ -25,6 +25,7 @@ const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const manager_pack_1 = require("../../core/manager-pack");
 const git_org_sync_1 = require("./git-org-sync");
+const local_folder_sync_1 = require("./local-folder-sync");
 const user_config_1 = require("./user-config");
 exports.MANAGER_CACHE_DIRNAME = 'manager';
 exports.MANAGER_SYNC_METADATA_FILE = '.manager-sync-metadata.json';
@@ -59,7 +60,9 @@ function decorateManagedManagerFile(content, backend) {
         return normalized;
     const writePath = backend === 'git'
         ? 'open a pull request against your manager storage repo'
-        : 'publish the change through your FRAIM manager storage flow';
+        : backend === 'local-folder'
+            ? 'edit the file in your synced folder and let the sync client upload it'
+            : 'publish the change through your FRAIM manager storage flow';
     const marker = [
         exports.MANAGER_CACHE_MANAGED_HEADER,
         '> [!IMPORTANT]',
@@ -151,7 +154,24 @@ async function syncManagerCache(options) {
         if (!managerStorage)
             return { status: 'disabled' };
     }
+    // single-machine: no remote sync; content stays local. Return disabled so
+    // callers know there is nothing to refresh (issue #834).
+    if (managerStorage.backend === 'single-machine') {
+        return { status: 'disabled' };
+    }
     try {
+        if (managerStorage.backend === 'local-folder') {
+            const localPath = managerStorage.localPath;
+            const files = (0, local_folder_sync_1.collectLocalFolderFiles)(localPath, manager_pack_1.isManagerPackRelativePath);
+            const metadata = {
+                version: (0, local_folder_sync_1.localFolderVersion)(localPath),
+                backend: 'local-folder',
+                source: localPath,
+                syncedAt: new Date().toISOString(),
+            };
+            materializeCache(files, metadata);
+            return { status: 'synced', metadata };
+        }
         if (managerStorage.backend === 'git') {
             const snapshot = (0, git_org_sync_1.fetchOrgRepoSnapshot)(managerStorage.gitUrl);
             try {

package/dist/src/cli/utils/manager-publish.js

@@ -16,6 +16,7 @@ const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const manager_pack_1 = require("../../core/manager-pack");
 const user_config_1 = require("./user-config");
+const local_folder_sync_1 = require("./local-folder-sync");
 const ALLOWED_GIT_URL = /^(https?:\/\/|ssh:\/\/|git:\/\/|file:\/\/|[\w.-]+@[\w.-]+:)/;
 function managerPackRelativePathFor(filePath) {
     const relativePath = (0, manager_pack_1.managerPackRelativePathForFileName)(filePath);
@@ -42,6 +43,18 @@ async function publishManagerArtifacts(artifacts, opts) {
             throw new Error(`Invalid manager-pack path '${artifact.relativePath}' (must be context/manager_context.md, rules/manager_rules.md, or learnings/<user>-*.md).`);
         }
     }
+    if (managerStorage.backend === 'local-folder') {
+        const localPath = managerStorage.localPath;
+        const writtenPaths = [];
+        for (const artifact of artifacts) {
+            const result = (0, local_folder_sync_1.writeLocalFolderFile)(localPath, artifact.relativePath, artifact.content);
+            if (result.skipped) {
+                throw new Error(`Skipped writing '${artifact.relativePath}' to local folder: ${result.reason} Re-sync before publishing.`);
+            }
+            writtenPaths.push(path_1.default.join(localPath, artifact.relativePath));
+        }
+        return { backend: 'local-folder', writtenPaths };
+    }
     if (managerStorage.backend === 'fraim-cloud') {
         const remoteUrl = opts?.remoteUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         const apiKey = opts?.apiKey || (0, user_config_1.readUserFraimConfig)().apiKey;

package/dist/src/cli/utils/org-pack-sync.js

@@ -28,6 +28,7 @@ const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
 const user_config_1 = require("./user-config");
 const git_org_sync_1 = require("./git-org-sync");
+const local_folder_sync_1 = require("./local-folder-sync");
 exports.ORG_CACHE_DIRNAME = 'org';
 exports.ORG_SYNC_METADATA_FILE = '.org-sync-metadata.json';
 exports.ORG_CACHE_MANAGED_HEADER = '<!-- FRAIM_ORG_SYNC_MANAGED_CONTENT -->';
@@ -90,7 +91,9 @@ function decorateManagedOrgFile(content, backend) {
         return normalized;
     const writePath = backend === 'git'
         ? 'open a pull request against your organization repo'
-        : 'update it through the organization-onboarding flow';
+        : backend === 'local-folder'
+            ? 'edit the file in your synced folder and let the sync client upload it'
+            : 'update it through the organization-onboarding flow';
     const marker = [
         exports.ORG_CACHE_MANAGED_HEADER,
         '> [!IMPORTANT]',
@@ -201,7 +204,24 @@ async function syncOrgCache(options) {
         if (!organization)
             return { status: 'disabled' };
     }
+    // single-machine: no remote sync; content stays local. Return disabled so
+    // callers know there is nothing to refresh (issue #834).
+    if (organization.backend === 'single-machine') {
+        return { status: 'disabled' };
+    }
     try {
+        if (organization.backend === 'local-folder') {
+            const localPath = organization.localPath;
+            const files = (0, local_folder_sync_1.collectLocalFolderFiles)(localPath, isSafePackPath);
+            const metadata = {
+                version: (0, local_folder_sync_1.localFolderVersion)(localPath),
+                backend: 'local-folder',
+                source: localPath,
+                syncedAt: new Date().toISOString(),
+            };
+            materializeCache(files, metadata);
+            return { status: 'synced', metadata };
+        }
         if (organization.backend === 'git') {
             const snapshot = (0, git_org_sync_1.fetchOrgRepoSnapshot)(organization.gitUrl);
             try {

package/dist/src/cli/utils/org-publish.js

@@ -22,6 +22,7 @@ const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
 const user_config_1 = require("./user-config");
+const local_folder_sync_1 = require("./local-folder-sync");
 const PACK_RELATIVE_PATH = /^(context|rules|learnings)\/[\w.-]+\.md$/;
 const ALLOWED_GIT_URL = /^(https?:\/\/|ssh:\/\/|git:\/\/|file:\/\/|[\w.-]+@[\w.-]+:)/;
 /**
@@ -63,6 +64,18 @@ async function publishOrgArtifacts(artifacts, opts) {
             throw new Error(`Invalid org-pack path '${a.relativePath}' (must be context|rules|learnings/<name>.md).`);
         }
     }
+    if (organization.backend === 'local-folder') {
+        const localPath = organization.localPath;
+        const writtenPaths = [];
+        for (const a of artifacts) {
+            const result = (0, local_folder_sync_1.writeLocalFolderFile)(localPath, a.relativePath, a.content);
+            if (result.skipped) {
+                throw new Error(`Skipped writing '${a.relativePath}' to local folder: ${result.reason} Re-sync before publishing.`);
+            }
+            writtenPaths.push(path_1.default.join(localPath, a.relativePath));
+        }
+        return { backend: 'local-folder', writtenPaths };
+    }
     if (organization.backend === 'fraim-cloud') {
         const remoteUrl = opts?.remoteUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         const apiKey = opts?.apiKey || (0, user_config_1.readUserFraimConfig)().apiKey;

package/dist/src/cli/utils/user-config.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getLayerBackend = getLayerBackend;
+exports.setLayerBackend = setLayerBackend;
 exports.readUserFraimConfig = readUserFraimConfig;
 exports.writeUserFraimConfig = writeUserFraimConfig;
 exports.getInstalledIdes = getInstalledIdes;
@@ -19,6 +21,23 @@ exports.getManagerStorageConfig = getManagerStorageConfig;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+/** Resolve the backend config for a named layer, or null when unconfigured (issue #834). */
+function getLayerBackend(layer) {
+    if (layer === 'org')
+        return getOrganizationConfig();
+    if (layer === 'manager')
+        return getManagerStorageConfig();
+    return null;
+}
+/** Write the backend config for a named layer (issue #834). */
+function setLayerBackend(layer, config) {
+    if (layer === 'org') {
+        writeUserFraimConfig({ organization: config });
+    }
+    else if (layer === 'manager') {
+        writeUserFraimConfig({ managerStorage: config });
+    }
+}
 function getUserConfigPath() {
     return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'config.json');
 }
@@ -77,6 +96,15 @@ function getOrganizationConfig() {
     if (raw.backend === 'fraim-cloud') {
         return { backend: 'fraim-cloud', id: raw.id };
     }
+    if (raw.backend === 'local-folder') {
+        const localPath = typeof raw.localPath === 'string' ? raw.localPath.trim() : '';
+        if (!localPath)
+            return null;
+        return { backend: 'local-folder', localPath };
+    }
+    if (raw.backend === 'single-machine') {
+        return { backend: 'single-machine' };
+    }
     return null;
 }
 /**
@@ -96,5 +124,14 @@ function getManagerStorageConfig() {
     if (raw.backend === 'fraim-cloud') {
         return { backend: 'fraim-cloud', id: raw.id };
     }
+    if (raw.backend === 'local-folder') {
+        const localPath = typeof raw.localPath === 'string' ? raw.localPath.trim() : '';
+        if (!localPath)
+            return null;
+        return { backend: 'local-folder', localPath };
+    }
+    if (raw.backend === 'single-machine') {
+        return { backend: 'single-machine' };
+    }
     return null;
 }

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

@@ -3,9 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AIMentor = void 0;
 const include_resolver_1 = require("./utils/include-resolver");
 class AIMentor {
-    constructor(resolver) {
+    constructor(resolver, skillDedup) {
         this.jobCache = new Map();
         this.resolver = resolver;
+        this.skillDedup = skillDedup;
     }
     /**
      * Handle mentoring/coaching request from agent
@@ -50,7 +51,7 @@ class AIMentor {
         return null;
     }
     async resolveIncludes(content, basePath) {
-        return (0, include_resolver_1.resolveIncludes)(content, this.resolver, basePath);
+        return (0, include_resolver_1.resolveIncludes)(content, this.resolver, basePath, this.skillDedup);
     }
     assertNoUnresolvedIncludes(content, context) {
         const matches = content.match(/\{\{include:[^}]+\}\}/g);
@@ -87,11 +88,6 @@ class AIMentor {
     getCompactPhaseAuthority() {
         return AIMentor.COMPACT_PHASE_AUTHORITY;
     }
-    async prependPhaseAuthority(message, isPhased) {
-        if (!isPhased)
-            return message;
-        return `${this.getCompactPhaseAuthority()}\n\n${message}`;
-    }
     buildPhasedJobOverview(workflow) {
         const metadataPhases = Object.keys(workflow.metadata.phases || {});
         const initialPhase = workflow.metadata.initialPhase || metadataPhases[0] || Array.from(workflow.phases.keys())[0] || 'starting';
@@ -143,7 +139,7 @@ class AIMentor {
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${targetPhase} (starting)`);
         }
         return {
-            message: await this.prependPhaseAuthority(message, true),
+            message,
             nextPhase: targetPhase,
             status: 'starting'
         };
@@ -188,7 +184,7 @@ class AIMentor {
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${phaseId} (complete)`);
         }
         return {
-            message: await this.prependPhaseAuthority(message, true),
+            message,
             nextPhase: nextPhaseId,
             status: 'complete'
         };
@@ -216,7 +212,7 @@ class AIMentor {
             this.assertNoUnresolvedIncludes(message, `${workflow.metadata.name}:${targetPhaseId} (${status})`);
         }
         return {
-            message: await this.prependPhaseAuthority(message, true),
+            message,
             nextPhase: targetPhaseId,
             status
         };

package/dist/src/core/fraim-config-schema.generated.js

@@ -163,6 +163,22 @@ exports.FRAIM_CONFIG_SCHEMA = {
         "apiKey": {
             "kind": "string"
         },
+        "projectStorage": {
+            "kind": "object",
+            "properties": {
+                "backend": {
+                    "kind": "enum",
+                    "values": [
+                        "git",
+                        "single-machine"
+                    ],
+                    "required": true
+                },
+                "gitUrl": {
+                    "kind": "string"
+                }
+            }
+        },
         "competitors": {
             "kind": "record",
             "value": {
@@ -619,6 +635,9 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "customizations.postCleanupHook",
     "remoteUrl",
     "apiKey",
+    "projectStorage",
+    "projectStorage.backend",
+    "projectStorage.gitUrl",
     "competitors",
     "compliance",
     "compliance.regulations",

package/dist/src/core/utils/include-resolver.js

@@ -51,9 +51,11 @@ function resolveIncludesWithIndex(content, fileIndex) {
  *
  * @param content - Raw content that may contain {{include:path}} directives
  * @param resolver - RegistryResolver instance
+ * @param basePath - Path of the current file, used to resolve relative ./ includes
+ * @param dedup - Optional session-level dedup hook (issue #801)
  * @returns Content with all resolvable includes inlined
  */
-async function resolveIncludes(content, resolver, basePath) {
+async function resolveIncludes(content, resolver, basePath, dedup) {
     let result = content;
     let pass = 0;
     while (result.includes('{{include:') && pass < exports.MAX_INCLUDE_PASSES) {
@@ -70,13 +72,24 @@ async function resolveIncludes(content, resolver, basePath) {
                 const dir = basePath.includes('/') ? basePath.substring(0, basePath.lastIndexOf('/')) : '';
                 targetPath = dir ? `${dir}/${filePath.substring(2)}` : filePath.substring(2);
             }
+            // Session-level dedup (issue #801): if this target's full content was
+            // already emitted earlier in the session, substitute a backreference
+            // rather than fetching and inlining it again.
+            if (dedup && dedup.isAlreadyEmitted(targetPath)) {
+                result = result.split(match).join(dedup.backreference(targetPath));
+                continue;
+            }
             try {
                 const fileContent = await resolver.getFile(targetPath);
                 if (fileContent !== null) {
                     // Recursively resolve includes in the newly fetched content
-                    const resolvedContent = await resolveIncludes(fileContent, resolver, targetPath);
+                    const resolvedContent = await resolveIncludes(fileContent, resolver, targetPath, dedup);
                     // Replace all occurrences of this specific include
                     result = result.split(match).join(resolvedContent);
+                    // Mark as emitted only after a successful full inline, so a failed
+                    // fetch never causes a later occurrence to be silently backreferenced.
+                    if (dedup)
+                        dedup.recordEmitted(targetPath);
                 }
                 else {
                     console.warn(`⚠️ Include file not found via resolver: ${targetPath} (original: ${filePath}, base: ${basePath})`);

package/dist/src/first-run/session-service.js

@@ -37,6 +37,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FIRST_RUN_ROW_IDS = exports.FirstRunSessionService = void 0;
+exports.buildFirstRunHubLaunchArgs = buildFirstRunHubLaunchArgs;
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
@@ -48,7 +49,6 @@ const auto_mcp_setup_1 = require("../cli/setup/auto-mcp-setup");
 const setup_1 = require("../cli/commands/setup");
 const script_sync_utils_1 = require("../cli/utils/script-sync-utils");
 const managed_agent_paths_1 = require("../cli/utils/managed-agent-paths");
-const ports_1 = require("../core/utils/ports");
 const types_1 = require("./types");
 Object.defineProperty(exports, "FIRST_RUN_ROW_IDS", { enumerable: true, get: function () { return types_1.FIRST_RUN_ROW_IDS; } });
 const install_state_1 = require("./install-state");
@@ -213,6 +213,16 @@ function surfaceForAgent(option) {
         status: 'configured',
     };
 }
+/**
+ * Issue #866 R1/R2: arguments for launching the FRAIM Hub from first-run.
+ * The Hub opens as the Electron desktop app — `fraim-hub` launches the desktop
+ * shell whenever `--browser` is absent. We omit `--project-path` so the desktop
+ * Hub opens with no active project (the invocation directory is not a project);
+ * the user opens or creates a project inside the Hub.
+ */
+function buildFirstRunHubLaunchArgs() {
+    return ['-y', 'fraim-hub@latest'];
+}
 class FirstRunSessionService {
     constructor(options) {
         // Issue #646: the key may be absent when first-run is launched by the macOS
@@ -933,7 +943,7 @@ class FirstRunSessionService {
     async openHub() {
         if (this.fakeMode) {
             // Tests don't actually want a Hub server running — just confirm intent.
-            return { ok: true, message: 'Fake-mode Hub open requested.', hubUrl: 'http://127.0.0.1:0/ai-hub/' };
+            return { ok: true, desktop: true, message: 'Fake-mode Hub open requested.' };
         }
         // Hub launches a real CLI process, so folder-only config surfaces are not
         // enough here. Require a runnable command in the managed or ambient PATH.
@@ -947,18 +957,13 @@ class FirstRunSessionService {
             };
         }
         try {
-            const port = await (0, ports_1.findAvailablePort)(43091);
             const npxBinary = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-            const projectPath = this.state.workspacePath || process.cwd();
-            const child = (0, child_process_1.spawn)(npxBinary, [
-                '-y',
-                'fraim-hub@latest',
-                '--browser',
-                '--port',
-                String(port),
-                '--project-path',
-                projectPath,
-            ], {
+            // Issue #866 R1/R2: launch the FRAIM Hub desktop (Electron) app, not a
+            // browser tab. `fraim-hub` opens the desktop shell whenever `--browser` is
+            // absent, and picks its own port + window — so there is no browser URL for
+            // the first-run tab to navigate to. We also omit `--project-path` so the
+            // Hub opens with no active project (the launch directory is not a project).
+            const child = (0, child_process_1.spawn)(npxBinary, buildFirstRunHubLaunchArgs(), {
                 detached: true,
                 stdio: 'ignore',
             });
@@ -966,12 +971,11 @@ class FirstRunSessionService {
                 appendInstallLog(`hub-open-spawn-error ${spawnError instanceof Error ? spawnError.message : String(spawnError)}`);
             });
             child.unref();
-            const hubUrl = `http://127.0.0.1:${port}/ai-hub/`;
-            appendInstallLog(`hub-opened ${hubUrl}`);
+            appendInstallLog('hub-opened desktop');
             return {
                 ok: true,
-                message: `Hub is opening at ${hubUrl}. From now on, run \`npx fraim-hub@latest --browser\` to launch it again.`,
-                hubUrl,
+                desktop: true,
+                message: 'FRAIM Hub is opening in the desktop app. You can close this tab. From now on, run `npx fraim-hub@latest` to launch it again.',
             };
         }
         catch (error) {
@@ -979,7 +983,7 @@ class FirstRunSessionService {
             appendInstallLog(`hub-open-failed ${detail}`);
             return {
                 ok: false,
-                message: `Could not open the Hub automatically: ${detail}. Run \`npx fraim-hub@latest --browser\` from a terminal to open it manually.`,
+                message: `Could not open the Hub automatically: ${detail}. Run \`npx fraim-hub@latest\` from a terminal to open it manually.`,
             };
         }
     }

package/dist/src/local-mcp-server/learning-context-builder.js

@@ -867,6 +867,8 @@ const PENDING_KIND_LABEL = {
     'coaching-moment': 'Coaching moment',
     'retrospective': 'Retrospective',
 };
+/** Filename infix that separates hot (.md) from cold-tier (.cold.md) learning files (#861). */
+const COLD_FILE_SUFFIX = '.cold';
 // Parse `## [P-…] Title` entries out of a learning file WITH their effective
 // score + last-seen (unlike parseLearningEntries, which drops that bookkeeping
 // for the Hub text display). Used only by the brain-dot projection.
@@ -941,12 +943,19 @@ function collectBrainLearningDots(workspaceRoot, userId) {
     for (const fileType of fileTypes) {
         const region = exports.BRAIN_LEARNING_FILETYPE_TO_REGION[fileType];
         const typeLabel = BRAIN_LEARNING_FILETYPE_LABEL[fileType];
-        // L1 personal
+        // L1 personal (hot file)
         const personal = resolvePersonal(`${resolvedUserId}-${fileType}.md`);
         const personalEntries = parseBrainLearningEntries(personal.path, fileType);
         if (personalEntries.length) {
             processed.push({ type: fileType, typeLabel, region, scope: 'personal', displayPath: personal.displayPath, entries: personalEntries });
         }
+        // L1 cold sibling — only emitted when the .cold.md file exists alongside the hot file
+        const coldFileName = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
+        const coldResolved = resolvePersonal(coldFileName);
+        const coldEntries = parseBrainLearningEntries(coldResolved.path, fileType);
+        if (coldEntries.length) {
+            processed.push({ type: fileType, typeLabel, region, scope: 'cold', displayPath: coldResolved.displayPath, entries: coldEntries });
+        }
         // L2 org
         const org = resolveOrgLearningFile(roots.repoLearningsBase, `org-${fileType}.md`);
         const orgEntries = parseBrainLearningEntries(org.path, fileType);
@@ -987,7 +996,7 @@ function listDomainLearningFiles(dir, prefix, fileType) {
 // Parse the `## [P-…] Title` entries (and their body prose) out of one learning
 // file. Score/Last seen/Recurrences metadata lines are dropped — the Hub shows
 // the human-readable learning, not the bookkeeping.
-function parseLearningEntries(filePath, displayPath, category, level, domain = 'global') {
+function parseLearningEntries(filePath, displayPath, category, level, domain = 'global', tier) {
     if (!(0, fs_1.existsSync)(filePath))
         return [];
     let content;
@@ -1013,7 +1022,10 @@ function parseLearningEntries(filePath, displayPath, category, level, domain = '
         const header = line.match(headingRe);
         if (header) {
             flush();
-            current = { severity: header[1], title: header[2].trim(), body: '', source: displayPath, category, level, domain };
+            const entry = { severity: header[1], title: header[2].trim(), body: '', source: displayPath, category, level, domain };
+            if (tier !== undefined)
+                entry.tier = tier;
+            current = entry;
             continue;
         }
         if (!current)
@@ -1061,10 +1073,15 @@ function readPreservedLearnings(workspaceRoot, userId, scope, level = 'machine')
     for (const cat of cats) {
         const fileType = exports.CATEGORY_TO_FILETYPE[cat];
         const f = `${resolvedUserId}-${fileType}.md`;
-        out.push(...parseLearningEntries((0, path_1.join)(dir, f), `${displayBase}/${f}`, cat, level));
+        out.push(...parseLearningEntries((0, path_1.join)(dir, f), `${displayBase}/${f}`, cat, level, 'global', 'hot'));
+        // Cold sibling — only read when it exists alongside the hot file (#861).
+        const coldF = `${resolvedUserId}-${fileType}${COLD_FILE_SUFFIX}.md`;
+        if ((0, fs_1.existsSync)((0, path_1.join)(dir, coldF))) {
+            out.push(...parseLearningEntries((0, path_1.join)(dir, coldF), `${displayBase}/${coldF}`, cat, level, 'global', 'cold'));
+        }
         // #806: domain-scoped personal learnings alongside the flat global file.
         for (const { fileName, domain } of listDomainLearningFiles(dir, resolvedUserId, fileType)) {
-            out.push(...parseLearningEntries((0, path_1.join)(dir, fileName), `${displayBase}/${fileName}`, cat, level, domain));
+            out.push(...parseLearningEntries((0, path_1.join)(dir, fileName), `${displayBase}/${fileName}`, cat, level, domain, 'hot'));
         }
     }
     return out;

package/dist/src/local-mcp-server/skill-include-dedup.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionSkillDedup = void 0;
+exports.isSkillIncludePath = isSkillIncludePath;
+/**
+ * A registry skill lives under a `skills/` path segment (e.g.
+ * `skills/communication/active-listening.md`). Only these are eligible for
+ * session dedup; delivery/orchestration/template includes are inlined normally.
+ */
+function isSkillIncludePath(targetPath) {
+    return /(^|\/)skills\//.test(targetPath);
+}
+/**
+ * Session-scoped skill-include dedup (issue #801).
+ *
+ * FRAIM jobs inline `{{include:skills/...}}` on every phase that references a
+ * skill, so a skill used in multiple phases of one job is re-inlined in full on
+ * each `seekMentoring` turn. This dedup records the first full emission of a
+ * skill in a session; later inclusions of the same skill are replaced with a
+ * short backreference that names the skill and gives a reload path. The reload
+ * path means a context compaction between phases cannot silently strip the
+ * guidance — the agent can re-fetch the skill on demand.
+ *
+ * The `emitted` set is owned by the long-lived proxy server (one per session)
+ * and passed by reference; each per-request AIMentor shares the same set. The
+ * server clears it on `fraim_connect` so a resumed/compacted session re-emits
+ * skills in full.
+ */
+class SessionSkillDedup {
+    constructor(emitted) {
+        this.emitted = emitted;
+    }
+    isAlreadyEmitted(targetPath) {
+        return isSkillIncludePath(targetPath) && this.emitted.has(targetPath);
+    }
+    recordEmitted(targetPath) {
+        if (isSkillIncludePath(targetPath)) {
+            this.emitted.add(targetPath);
+        }
+    }
+    backreference(targetPath) {
+        const name = targetPath.replace(/^.*\//, '').replace(/\.md$/, '');
+        return `> [Skill \`${name}\` was included earlier in this session; its full text is omitted here to reduce token cost. If it is no longer in your context, reload it with \`get_fraim_file({ path: "${targetPath}" })\`.]`;
+    }
+}
+exports.SessionSkillDedup = SessionSkillDedup;

package/dist/src/local-mcp-server/stdio-server.js

@@ -69,6 +69,7 @@ const otlp_metrics_receiver_js_1 = require("./otlp-metrics-receiver.js");
 const token_adapter_registry_js_1 = require("./token-adapter-registry.js");
 const learning_context_builder_js_1 = require("./learning-context-builder.js");
 const learning_domains_js_1 = require("../config/learning-domains.js");
+const skill_include_dedup_js_1 = require("./skill-include-dedup.js");
 /**
  * Handle template substitution logic separately for better testability
  */
@@ -437,6 +438,11 @@ class FraimLocalMCPServer {
         this.jobStartCache = new Map();
         this.connectSyncInFlight = null;
         this.latestConnectSyncWarning = null;
+        // Issue #801: registry-path set of skills already inlined this session. Shared
+        // by reference into each per-request AIMentor so a skill referenced by multiple
+        // phases of a job is emitted in full once, then backreferenced. Cleared on
+        // fraim_connect so a resumed/compacted session re-emits skills in full.
+        this.sessionEmittedSkills = new Set();
         this.orgCacheRefreshInFlight = false;
         this.managerCacheRefreshInFlight = false;
         this.writer = writer || process.stdout.write.bind(process.stdout);
@@ -1334,6 +1340,10 @@ class FraimLocalMCPServer {
         finalizedResponse = await this.resolveIncludesInResponse(finalizedResponse, requestSessionId, requestId);
         // 3. After fraim_connect succeeds, capture user email and inject learning context.
         if (toolName === 'fraim_connect' && !finalizedResponse.error) {
+            // Issue #801: a (re)connect starts/resumes a session. Reset the skill-dedup
+            // set so skills are re-emitted in full — the agent's earlier context may
+            // have been compacted away, so backreferencing it would be unsafe.
+            this.sessionEmittedSkills.clear();
             const text = finalizedResponse.result?.content?.[0]?.text;
             if (typeof text === 'string') {
                 let responseText = text;
@@ -1738,7 +1748,17 @@ class FraimLocalMCPServer {
      */
     getMentor(requestSessionId) {
         const resolver = this.getRegistryResolver(requestSessionId);
-        return new ai_mentor_1.AIMentor(resolver);
+        return new ai_mentor_1.AIMentor(resolver, this.buildSkillDedup());
+    }
+    /**
+     * Build the session-level skill-include dedup (issue #801). Returns undefined
+     * when disabled via FRAIM_DISABLE_SKILL_CACHE, so includes inline in full
+     * exactly as before (no behavior change on the kill switch).
+     */
+    buildSkillDedup() {
+        if (process.env.FRAIM_DISABLE_SKILL_CACHE === '1')
+            return undefined;
+        return new skill_include_dedup_js_1.SessionSkillDedup(this.sessionEmittedSkills);
     }
     normalizeRepoContext(repo) {
         if (!repo || typeof repo !== 'object')

package/dist/src/middleware/auth.js

@@ -61,6 +61,17 @@ class AuthMiddleware {
         const sessionFromCookie = (0, cookie_service_1.readSessionCookie)(req);
         const sessionFromBearer = (0, cookie_service_1.readBearerToken)(req);
         const sessionToken = sessionFromCookie || sessionFromBearer;
+        const isMcpHandshake = req.method === 'POST' &&
+            p === '/mcp' &&
+            req.body?.jsonrpc === '2.0' &&
+            (req.body?.method === 'initialize' || req.body?.method === 'ping');
+        // Some hosted MCP clients, including Microsoft 365 Copilot's agent-tools
+        // runtime, perform initialize/ping before attaching OAuth credentials.
+        // Allow only those non-mutating handshake methods through; tool discovery
+        // and tool calls still require the normal authenticated path below.
+        if (!apiKey && !sessionToken && isMcpHandshake) {
+            return next();
+        }
         // If a session token is present and there's no API key, resolve it.
         if (!apiKey && sessionToken) {
             try {

package/dist/src/middleware/telemetry.js

@@ -31,6 +31,7 @@ class TelemetryMiddleware {
             const exemptMethods = [
                 'initialize',
                 'notifications/initialized',
+                'ping',
                 'tools/list',
                 'resources/list',
                 'prompts/list',

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

@@ -139,6 +139,9 @@ class McpService {
             else if (method === 'tools/call') {
                 result = await this.handleToolCall(params, context);
             }
+            else if (method === 'ping') {
+                result = {};
+            }
             else if (method === 'notifications/initialized') {
                 // Notifications don't need a response
                 return null;
@@ -454,7 +457,14 @@ class McpService {
             content: [{
                     type: 'text',
                     text: response
-                }]
+                }],
+            structuredContent: {
+                jobs: matches.map(job => ({
+                    name: job.name,
+                    description: job.description,
+                    category: job.category
+                }))
+            }
         };
     }
     async handleListFiles(type, category) {
@@ -572,6 +582,13 @@ class McpService {
                     type: 'text',
                     text: lines.join('\n')
                 }],
+            structuredContent: {
+                sessionId,
+                userId: session.userId,
+                agent: session.agent,
+                machine: session.machine,
+                repo: session.repo
+            },
             sessionId: sessionId
         };
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.212",
+  "version": "2.0.214",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {

package/public/first-run/script.js

@@ -466,7 +466,7 @@
       try { await api('/api/first-run/set-preference', 'POST', { choice: 'hub' }); } catch (_) {}
       try {
         hubBtn.disabled = true;
-        setStatus('Opening Hub...');
+        setStatus('Opening the FRAIM Hub desktop app...');
         const openResp = await api('/api/first-run/open-hub', 'POST');
         if (openResp && openResp.needsAgentSetup) {
           state.activeStep = 'agents';
@@ -474,7 +474,10 @@
           setStatus(openResp.message, 'error');
           return;
         }
-        if (openResp && openResp.hubUrl) window.location.replace(openResp.hubUrl);
+        // Issue #866 R1: the Hub opens as the Electron desktop app, so the
+        // first-run tab does not navigate itself to a browser Hub. Confirm and
+        // let the user close this tab.
+        setStatus((openResp && openResp.message) || 'FRAIM Hub is opening in the desktop app. You can close this tab.');
       } catch (err) {
         hubBtn.disabled = false;
         setStatus(err.message, 'error');