fraim-framework 2.0.163 → 2.0.165

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

@@ -0,0 +1,208 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORG_CACHE_MANAGED_HEADER = exports.ORG_SYNC_METADATA_FILE = exports.ORG_CACHE_DIRNAME = void 0;
+exports.getOrgCacheDir = getOrgCacheDir;
+exports.readOrgCacheMetadata = readOrgCacheMetadata;
+exports.getOrgCacheAgeHours = getOrgCacheAgeHours;
+exports.syncOrgCache = syncOrgCache;
+/**
+ * Org cache sync (issue #563).
+ *
+ * Materializes the organization's shared context/rules/learnings into the
+ * managed read-only cache at ~/.fraim/org/, from either backend:
+ *   - git: shallow snapshot of the customer-owned org repo (R7)
+ *   - fraim-cloud: GET /api/org/pack from the FRAIM server (R6)
+ *
+ * Cache files are managed content: marked, overwritten on every sync, and
+ * never a write target for agents (R2.2). A failed refresh never throws:
+ * an existing cache is served stale with its age (R2.3, R4.3).
+ */
+const axios_1 = __importDefault(require("axios"));
+const fs_1 = __importDefault(require("fs"));
+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");
+exports.ORG_CACHE_DIRNAME = 'org';
+exports.ORG_SYNC_METADATA_FILE = '.org-sync-metadata.json';
+exports.ORG_CACHE_MANAGED_HEADER = '<!-- FRAIM_ORG_SYNC_MANAGED_CONTENT -->';
+/** Subdirectories of the org pack that sync into the cache (spec R7.1). */
+const ORG_PACK_DIRS = ['context', 'rules', 'learnings'];
+/**
+ * Pack files must stay inside the three org pack directories. Applied to
+ * every relativePath before it touches the filesystem, so a compromised
+ * backend response can never write outside the cache directory.
+ */
+const SAFE_PACK_RELATIVE_PATH = /^(context|rules|learnings)\/[\w.-]+\.md$/;
+function getOrgCacheDir() {
+    return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), exports.ORG_CACHE_DIRNAME);
+}
+function readOrgCacheMetadata() {
+    try {
+        const metadataPath = path_1.default.join(getOrgCacheDir(), exports.ORG_SYNC_METADATA_FILE);
+        if (!fs_1.default.existsSync(metadataPath))
+            return null;
+        return JSON.parse(fs_1.default.readFileSync(metadataPath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function getOrgCacheAgeHours() {
+    const metadata = readOrgCacheMetadata();
+    if (!metadata?.syncedAt)
+        return null;
+    const syncedAt = Date.parse(metadata.syncedAt);
+    if (Number.isNaN(syncedAt))
+        return null;
+    return Math.max(0, (Date.now() - syncedAt) / 3_600_000);
+}
+function decorateManagedOrgFile(content, backend) {
+    const normalized = content.replace(/^/, '');
+    if (normalized.startsWith(exports.ORG_CACHE_MANAGED_HEADER))
+        return normalized;
+    const writePath = backend === 'git'
+        ? 'open a pull request against your organization repo'
+        : 'update it through the organization-onboarding flow';
+    const marker = [
+        exports.ORG_CACHE_MANAGED_HEADER,
+        '> [!IMPORTANT]',
+        '> Synced from your organization\'s shared context. Local edits are overwritten on the next sync.',
+        `> To change this content, ${writePath}.`,
+        ''
+    ].join('\n');
+    return `${marker}\n${normalized}`;
+}
+function collectGitPackFiles(snapshotDir) {
+    const files = [];
+    for (const dirName of ORG_PACK_DIRS) {
+        const dirPath = path_1.default.join(snapshotDir, dirName);
+        if (!fs_1.default.existsSync(dirPath))
+            continue;
+        for (const entry of fs_1.default.readdirSync(dirPath, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            files.push({
+                relativePath: `${dirName}/${entry.name}`,
+                content: fs_1.default.readFileSync(path_1.default.join(dirPath, entry.name), 'utf8')
+            });
+        }
+    }
+    return files;
+}
+async function fetchCloudPack(remoteUrl, apiKey) {
+    const response = await axios_1.default.get(`${remoteUrl.replace(/\/$/, '')}/api/org/pack`, {
+        headers: { 'x-api-key': apiKey },
+        timeout: 30_000
+    });
+    const files = Array.isArray(response.data?.files) ? response.data.files : [];
+    return {
+        files: files.filter((f) => typeof f?.relativePath === 'string' &&
+            SAFE_PACK_RELATIVE_PATH.test(f.relativePath) &&
+            typeof f?.content === 'string'),
+        version: String(response.data?.version ?? '0')
+    };
+}
+/** Replace the cache contents atomically: stage fully, then swap. */
+function materializeCache(files, metadata) {
+    const cacheDir = getOrgCacheDir();
+    const stagingDir = `${cacheDir}.staging-${process.pid}`;
+    fs_1.default.rmSync(stagingDir, { recursive: true, force: true });
+    fs_1.default.mkdirSync(stagingDir, { recursive: true });
+    for (const file of files) {
+        if (!SAFE_PACK_RELATIVE_PATH.test(file.relativePath))
+            continue;
+        const destination = path_1.default.join(stagingDir, file.relativePath);
+        fs_1.default.mkdirSync(path_1.default.dirname(destination), { recursive: true });
+        fs_1.default.writeFileSync(destination, decorateManagedOrgFile(file.content, metadata.backend));
+    }
+    fs_1.default.writeFileSync(path_1.default.join(stagingDir, exports.ORG_SYNC_METADATA_FILE), JSON.stringify(metadata, null, 2));
+    fs_1.default.rmSync(cacheDir, { recursive: true, force: true });
+    fs_1.default.renameSync(stagingDir, cacheDir);
+}
+/**
+ * New-machine onboarding (R1.3, AC1): when this machine has an API key but no
+ * organization block yet, probe the FRAIM server. If the account owns org
+ * artifacts, persist the fraim-cloud organization block so `fraim setup` +
+ * `fraim sync` is the complete second-machine flow. Quietly resolves null on
+ * any failure or when the account has no org.
+ */
+async function discoverCloudOrganization(options) {
+    try {
+        const apiKey = options?.apiKey || (0, user_config_1.readUserFraimConfig)().apiKey;
+        if (!apiKey || apiKey === 'local-dev' || apiKey === 'test-mode-key')
+            return null;
+        const remoteUrl = options?.remoteUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        const pack = await fetchCloudPack(remoteUrl, apiKey);
+        if (pack.files.length === 0)
+            return null;
+        (0, user_config_1.writeUserFraimConfig)({ organization: { backend: 'fraim-cloud' } });
+        return (0, user_config_1.getOrganizationConfig)();
+    }
+    catch {
+        return null;
+    }
+}
+function failureOutcome(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const existing = readOrgCacheMetadata();
+    if (existing) {
+        return {
+            status: 'stale',
+            metadata: existing,
+            ageHours: getOrgCacheAgeHours() ?? 0,
+            error: message
+        };
+    }
+    return { status: 'absent', error: message };
+}
+/**
+ * Refresh the org cache from the configured backend (R4.1). Never throws:
+ * returns 'disabled' (no org configured), 'synced', 'stale' (refresh failed,
+ * existing cache served with age), or 'absent' (refresh failed, no cache).
+ */
+async function syncOrgCache(options) {
+    let organization = (0, user_config_1.getOrganizationConfig)();
+    if (!organization) {
+        organization = await discoverCloudOrganization(options);
+        if (!organization)
+            return { status: 'disabled' };
+    }
+    try {
+        if (organization.backend === 'git') {
+            const snapshot = (0, git_org_sync_1.fetchOrgRepoSnapshot)(organization.gitUrl);
+            try {
+                const metadata = {
+                    version: snapshot.sha,
+                    backend: 'git',
+                    source: organization.gitUrl,
+                    syncedAt: new Date().toISOString()
+                };
+                materializeCache(collectGitPackFiles(snapshot.dir), metadata);
+                return { status: 'synced', metadata };
+            }
+            finally {
+                snapshot.cleanup();
+            }
+        }
+        const remoteUrl = options?.remoteUrl || process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
+        const apiKey = options?.apiKey || (0, user_config_1.readUserFraimConfig)().apiKey;
+        if (!apiKey)
+            throw new Error('No FRAIM API key available for the fraim-cloud org backend.');
+        const pack = await fetchCloudPack(remoteUrl, apiKey);
+        const metadata = {
+            version: pack.version,
+            backend: 'fraim-cloud',
+            source: remoteUrl,
+            syncedAt: new Date().toISOString()
+        };
+        materializeCache(pack.files, metadata);
+        return { status: 'synced', metadata };
+    }
+    catch (error) {
+        return failureOutcome(error);
+    }
+}

package/dist/src/cli/utils/project-bootstrap.js

@@ -9,7 +9,11 @@ exports.buildInitProjectSummary = buildInitProjectSummary;
 exports.printInitProjectSummary = printInitProjectSummary;
 const chalk_1 = __importDefault(require("chalk"));
 const ONBOARDING_VIDEO_PLAYLIST_URL = 'https://fraimworks.ai/resources.html#videos';
-function formatModeLabel(mode) {
+function formatModeLabel(result) {
+    if (result.mode === 'conversational' && result.repositoryDetected) {
+        return 'Pending project onboarding';
+    }
+    const mode = result.mode;
     switch (mode) {
         case 'conversational':
             return 'Conversational';
@@ -19,7 +23,11 @@ function formatModeLabel(mode) {
             return 'Integrated';
     }
 }
-function getModeSpecificNextStep(mode) {
+function getModeSpecificNextStep(result) {
+    if (result.mode === 'conversational' && result.repositoryDetected) {
+        return `The agent will create fraim/config.json during onboarding, preserve the detected repository identity, then focus on project context, validation commands, durable project rules, and any optional automation choices. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
+    }
+    const mode = result.mode;
     switch (mode) {
         case 'conversational':
             return `The agent will create fraim/config.json during onboarding, then focus on project context, validation commands, and durable project rules. For a walkthrough, watch the onboarding videos at ${ONBOARDING_VIDEO_PLAYLIST_URL}.`;
@@ -53,7 +61,8 @@ function buildInitProjectSummary(result) {
     return {
         status: 'FRAIM project initialized.',
         fields: {
-            mode: formatModeLabel(result.mode),
+            mode: formatModeLabel(result),
+            projectContext: result.repositoryDetected ? 'repository-backed' : 'local-folder',
             project: result.projectName,
             repositoryDetection: result.repositoryDetected ? 'detected' : 'not detected',
             issueTracking: result.issueTrackingDetected ? 'detected' : 'not detected',
@@ -64,19 +73,23 @@ function buildInitProjectSummary(result) {
         warnings: [...result.warnings],
         nextStep: {
             prompt: 'Tell your AI agent "Onboard this project".',
-            explanation: getModeSpecificNextStep(result.mode)
+            explanation: getModeSpecificNextStep(result)
         }
     };
 }
 function printInitProjectSummary(result) {
     const summary = buildInitProjectSummary(result);
-    const showRepositoryDetails = result.mode !== 'conversational';
+    const showRepositoryDetection = result.mode !== 'conversational' || result.repositoryDetected;
+    const showIssueTrackingDetails = result.mode !== 'conversational';
     console.log(chalk_1.default.green(`\n${summary.status}`));
     console.log(chalk_1.default.blue('Project summary:'));
-    console.log(chalk_1.default.gray(`   Mode: ${summary.fields.mode}`));
+    console.log(chalk_1.default.gray(`   Automation mode: ${summary.fields.mode}`));
+    console.log(chalk_1.default.gray(`   Project context: ${summary.fields.projectContext}`));
     console.log(chalk_1.default.gray(`   Project: ${summary.fields.project}`));
-    if (showRepositoryDetails) {
+    if (showRepositoryDetection) {
         console.log(chalk_1.default.gray(`   Repository detection: ${summary.fields.repositoryDetection}`));
+    }
+    if (showIssueTrackingDetails) {
         console.log(chalk_1.default.gray(`   Issue tracking: ${summary.fields.issueTracking}`));
     }
     console.log(chalk_1.default.gray(`   Sync: ${summary.fields.sync}`));

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

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readUserFraimConfig = readUserFraimConfig;
+exports.writeUserFraimConfig = writeUserFraimConfig;
+exports.getOrganizationConfig = getOrganizationConfig;
+/**
+ * Typed read/write helpers for the user-level FRAIM config (~/.fraim/config.json),
+ * including the organization block introduced by issue #563.
+ *
+ * The user-level config is machine-scoped and distinct from the workspace
+ * config (fraim/config.json). Honors the FRAIM_USER_DIR override used by tests.
+ */
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const project_fraim_paths_1 = require("../../core/utils/project-fraim-paths");
+function getUserConfigPath() {
+    return path_1.default.join((0, project_fraim_paths_1.getUserFraimDirPath)(), 'config.json');
+}
+function readUserFraimConfig() {
+    try {
+        const configPath = getUserConfigPath();
+        if (!fs_1.default.existsSync(configPath))
+            return {};
+        const parsed = JSON.parse(fs_1.default.readFileSync(configPath, 'utf8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Shallow-merge a patch into the user config and persist it. Existing keys
+ * not named in the patch are preserved. Setting a key to undefined removes it.
+ */
+function writeUserFraimConfig(patch) {
+    const current = readUserFraimConfig();
+    const merged = { ...current, ...patch };
+    for (const key of Object.keys(patch)) {
+        if (patch[key] === undefined)
+            delete merged[key];
+    }
+    const dir = (0, project_fraim_paths_1.getUserFraimDirPath)();
+    fs_1.default.mkdirSync(dir, { recursive: true });
+    fs_1.default.writeFileSync(getUserConfigPath(), JSON.stringify(merged, null, 2));
+    return merged;
+}
+/**
+ * Resolve the validated organization configuration, or null when no valid
+ * organization is configured on this machine (R1.1).
+ */
+function getOrganizationConfig() {
+    const raw = readUserFraimConfig().organization;
+    if (!raw || typeof raw !== 'object')
+        return null;
+    if (raw.backend === 'git') {
+        const gitUrl = typeof raw.gitUrl === 'string' ? raw.gitUrl.trim() : '';
+        if (!gitUrl)
+            return null;
+        return { backend: 'git', gitUrl, id: raw.id };
+    }
+    if (raw.backend === 'fraim-cloud') {
+        return { backend: 'fraim-cloud', id: raw.id };
+    }
+    return null;
+}

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

@@ -296,6 +296,9 @@ exports.FRAIM_CONFIG_SCHEMA = {
                         },
                         "instanceUrl": {
                             "kind": "string"
+                        },
+                        "accessScript": {
+                            "kind": "string"
                         }
                     }
                 },
@@ -390,6 +393,12 @@ exports.FRAIM_CONFIG_SCHEMA = {
                                     },
                                     "instructions": {
                                         "kind": "string"
+                                    },
+                                    "accessScript": {
+                                        "kind": "string"
+                                    },
+                                    "purpose": {
+                                        "kind": "string"
                                     }
                                 }
                             }
@@ -588,6 +597,7 @@ exports.SUPPORTED_FRAIM_CONFIG_PATHS = [
     "integrations.itsm",
     "integrations.itsm.provider",
     "integrations.itsm.instanceUrl",
+    "integrations.itsm.accessScript",
     "integrations.identity",
     "integrations.identity.provider",
     "automation",

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

@@ -341,20 +341,40 @@ function computeOldestL0AgeDays(workspaceRoot, userId) {
     }
     return oldest;
 }
+/**
+ * Resolve an L2 org-scope learning file (issue #563): a repo-local override
+ * (`fraim/personalized-employee/learnings/`) wins, then the synced org cache
+ * (`~/.fraim/org/learnings/`). Org learnings are part of the shared org pack,
+ * so a synced copy must be readable by the agent even with no repo-local copy.
+ * Mirrors the org context/rules resolution order. Returns `present:false` with
+ * the repo path/display when neither tier has the file.
+ */
+function resolveOrgLearningFile(repoLearningsBase, fileName) {
+    const repoPath = (0, path_1.join)(repoLearningsBase, fileName);
+    if ((0, fs_1.existsSync)(repoPath)) {
+        return { present: true, path: repoPath, displayPath: `${REPO_LEARNINGS_REL}/${fileName}` };
+    }
+    const cachePath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'org', 'learnings', fileName);
+    if ((0, fs_1.existsSync)(cachePath)) {
+        return { present: true, path: cachePath, displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/learnings/${fileName}`) };
+    }
+    return { present: false, path: repoPath, displayPath: `${REPO_LEARNINGS_REL}/${fileName}` };
+}
 function buildLearningContextSection(workspaceRoot, userId, forJob) {
     const roots = getLearningRoots(workspaceRoot);
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
     const threshold = getScoreThreshold(workspaceRoot);
-    const l2MistakePath = (0, path_1.join)(roots.repoLearningsBase, 'org-mistake-patterns.md');
-    const l2PrefPath = (0, path_1.join)(roots.repoLearningsBase, 'org-preferences.md');
-    const l2CoachPath = (0, path_1.join)(roots.repoLearningsBase, 'org-manager-coaching.md');
-    const l2ValidatedPath = (0, path_1.join)(roots.repoLearningsBase, 'org-validated-patterns.md');
-    const l2MistakePresent = (0, fs_1.existsSync)(l2MistakePath);
-    const l2PrefPresent = (0, fs_1.existsSync)(l2PrefPath);
-    const l2CoachPresent = (0, fs_1.existsSync)(l2CoachPath);
-    const l2ValidatedPresent = (0, fs_1.existsSync)(l2ValidatedPath);
-    const l2MistakeStats = l2MistakePresent ? scanMistakePatternFile(l2MistakePath, threshold, 'mistake-patterns') : null;
-    const l2ValidatedStats = l2ValidatedPresent ? scanMistakePatternFile(l2ValidatedPath, threshold, 'validated-patterns') : null;
+    // L2 org learnings resolve repo-local first, then the synced org cache (#563).
+    const l2Mistake = resolveOrgLearningFile(roots.repoLearningsBase, 'org-mistake-patterns.md');
+    const l2Pref = resolveOrgLearningFile(roots.repoLearningsBase, 'org-preferences.md');
+    const l2Coach = resolveOrgLearningFile(roots.repoLearningsBase, 'org-manager-coaching.md');
+    const l2Validated = resolveOrgLearningFile(roots.repoLearningsBase, 'org-validated-patterns.md');
+    const l2MistakePresent = l2Mistake.present;
+    const l2PrefPresent = l2Pref.present;
+    const l2CoachPresent = l2Coach.present;
+    const l2ValidatedPresent = l2Validated.present;
+    const l2MistakeStats = l2MistakePresent ? scanMistakePatternFile(l2Mistake.path, threshold, 'mistake-patterns') : null;
+    const l2ValidatedStats = l2ValidatedPresent ? scanMistakePatternFile(l2Validated.path, threshold, 'validated-patterns') : null;
     const l1Mistake = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-mistake-patterns.md`);
     const l1Pref = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-preferences.md`);
     const l1Coach = resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, `${resolvedUserId}-manager-coaching.md`);
@@ -394,13 +414,13 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     if (hasL2) {
         section += '### L2 - Org patterns\n';
         if (l2MistakePresent)
-            section += `\`${REPO_LEARNINGS_REL}/org-mistake-patterns.md\`  (entries above score threshold)\n`;
+            section += `\`${l2Mistake.displayPath}\`  (entries above score threshold)\n`;
         if (l2PrefPresent)
-            section += `\`${REPO_LEARNINGS_REL}/org-preferences.md\`  (all entries)\n`;
+            section += `\`${l2Pref.displayPath}\`  (all entries)\n`;
         if (l2CoachPresent)
-            section += `\`${REPO_LEARNINGS_REL}/org-manager-coaching.md\`  (manager-facing; all entries)\n`;
+            section += `\`${l2Coach.displayPath}\`  (manager-facing; all entries)\n`;
         if (l2ValidatedPresent)
-            section += `\`${REPO_LEARNINGS_REL}/org-validated-patterns.md\`  (entries above score threshold)\n`;
+            section += `\`${l2Validated.displayPath}\`  (entries above score threshold)\n`;
         const l2DormantTotal = (l2MistakeStats?.dormant || 0) + (l2ValidatedStats?.dormant || 0);
         if (l2DormantTotal > 0) {
             section += `Dormant: ${l2DormantTotal} org pattern${l2DormantTotal !== 1 ? 's' : ''} below threshold\n`;
@@ -465,12 +485,13 @@ function buildLearningContextSection(workspaceRoot, userId, forJob) {
     return section;
 }
 /**
- * Resolve an organization/manager-scope context file. These are user-level and
- * portable across repos, but a repo-local copy (under `fraim/…`) wins when
- * present — mirroring how personal learnings layer (repo-local shadows
- * user-level) in `resolvePersonalLearningFile`.
+ * Resolve an organization/manager-scope context file (issue #563 order, R3.1):
+ *   1. repo-local override (`fraim/personalized-employee/…`) — wins when present
+ *   2. managed org cache (`~/.fraim/org/…`) — the synced shared org layer;
+ *      eligible for org files only, never manager files (R3.3)
+ *   3. legacy machine-local (`~/.fraim/personalized-employee/…`)
  */
-function resolveOrgContextFile(workspaceRoot, relativePath) {
+function resolveOrgContextFile(workspaceRoot, relativePath, orgCacheEligible = true) {
     try {
         const repoPath = (0, path_1.join)((0, project_fraim_paths_1.getWorkspaceFraimDir)(workspaceRoot), 'personalized-employee', relativePath);
         if ((0, fs_1.existsSync)(repoPath)) {
@@ -479,6 +500,15 @@ function resolveOrgContextFile(workspaceRoot, relativePath) {
                 displayPath: (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`personalized-employee/${relativePath}`)
             };
         }
+        if (orgCacheEligible) {
+            const cachePath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'org', relativePath);
+            if ((0, fs_1.existsSync)(cachePath)) {
+                return {
+                    present: true,
+                    displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/${relativePath}`)
+                };
+            }
+        }
         const userPath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', relativePath);
         if ((0, fs_1.existsSync)(userPath)) {
             return {
@@ -518,11 +548,12 @@ function resolveProjectContextFile(workspaceRoot, relativePath) {
  * lists only present files, and returns '' when none exist.
  */
 function buildTeamContextSection(workspaceRoot, forJob) {
-    // Organization layer (user-level, portable; repo-local override wins).
+    // Organization layer: repo override, then org cache, then legacy machine-local.
+    // Manager files are personal and never resolve from the shared org cache (R3.3).
     const orgContext = resolveOrgContextFile(workspaceRoot, 'context/org_context.md');
-    const managerContext = resolveOrgContextFile(workspaceRoot, 'context/manager_context.md');
+    const managerContext = resolveOrgContextFile(workspaceRoot, 'context/manager_context.md', false);
     const orgRules = resolveOrgContextFile(workspaceRoot, 'rules/org_rules.md');
-    const managerRules = resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md');
+    const managerRules = resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md', false);
     // Project layer (repo-local only).
     const projectContext = resolveProjectContextFile(workspaceRoot, 'context/project_context.md');
     const projectBrief = resolveProjectContextFile(workspaceRoot, 'context/project_brief.md');
@@ -571,9 +602,9 @@ function buildTeamContextSection(workspaceRoot, forJob) {
 function resolveTeamContextFiles(workspaceRoot) {
     return {
         orgContext: resolveOrgContextFile(workspaceRoot, 'context/org_context.md'),
-        managerContext: resolveOrgContextFile(workspaceRoot, 'context/manager_context.md'),
+        managerContext: resolveOrgContextFile(workspaceRoot, 'context/manager_context.md', false),
         orgRules: resolveOrgContextFile(workspaceRoot, 'rules/org_rules.md'),
-        managerRules: resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md'),
+        managerRules: resolveOrgContextFile(workspaceRoot, 'rules/manager_rules.md', false),
         projectContext: resolveProjectContextFile(workspaceRoot, 'context/project_context.md'),
         projectBrief: resolveProjectContextFile(workspaceRoot, 'context/project_brief.md'),
         projectQa: resolveProjectContextFile(workspaceRoot, 'context/project_qa.md'),
@@ -627,6 +658,23 @@ function resolveTeamContextFile(workspaceRoot, key) {
             scope
         };
     }
+    // Synced org cache (org files only, never manager files — R3.3). Reads
+    // resolve here, but the cache is managed content: it is never a write
+    // destination (R5.1), so writePath stays empty and the caller must route
+    // edits through the org backend's propose-and-approve flow.
+    if (key === 'org' || key === 'orgRules') {
+        const cachePath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'org', relativePath);
+        if ((0, fs_1.existsSync)(cachePath)) {
+            return {
+                present: true,
+                readPath: cachePath,
+                writePath: '',
+                displayPath: (0, project_fraim_paths_1.getUserFraimDisplayPath)(`org/${relativePath}`),
+                scope,
+                managedByOrgSync: true
+            };
+        }
+    }
     const userPath = (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'personalized-employee', relativePath);
     const userDisplay = (0, project_fraim_paths_1.getUserFraimDisplayPath)(`personalized-employee/${relativePath}`);
     return {
@@ -674,11 +722,12 @@ function countLearningEntries(filePath) {
 function countPreservedLearnings(workspaceRoot, userId) {
     const roots = getLearningRoots(workspaceRoot);
     const resolvedUserId = resolveLearningUserId(workspaceRoot, userId, roots);
-    // L2 organization-scope preserved files (repo-local org-* files).
-    const organization = countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-mistake-patterns.md')) +
-        countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-preferences.md')) +
-        countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-manager-coaching.md')) +
-        countLearningEntries((0, path_1.join)(roots.repoLearningsBase, 'org-validated-patterns.md'));
+    // L2 organization-scope preserved files: repo-local override, then the
+    // synced org cache (#563), matching what buildLearningContextSection injects.
+    const organization = countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-mistake-patterns.md').path) +
+        countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-preferences.md').path) +
+        countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-manager-coaching.md').path) +
+        countLearningEntries(resolveOrgLearningFile(roots.repoLearningsBase, 'org-validated-patterns.md').path);
     const resolve = (fileName) => resolvePersonalLearningFile(roots.repoLearningsBase, roots.globalPersonalBase, roots.globalPersonalDisplayBase, fileName);
     // L1 manager-facing reverse-mentoring file.
     const manager = countLearningEntries(resolve(`${resolvedUserId}-manager-coaching.md`).path);

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

@@ -415,6 +415,7 @@ class FraimLocalMCPServer {
         this.mentoringResponseCache = null;
         this.connectSyncInFlight = null;
         this.latestConnectSyncWarning = null;
+        this.orgCacheRefreshInFlight = false;
         this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
@@ -748,6 +749,35 @@ class FraimLocalMCPServer {
         finally {
             this.connectSyncInFlight = null;
         }
+        this.maybeRefreshOrgCache(String(requestId));
+    }
+    /**
+     * Issue #563 (R4.2): opportunistically refresh the managed org cache
+     * (~/.fraim/org/) at session bootstrap when it is missing or older than
+     * 24 hours. Fire-and-forget: session start never blocks on the org
+     * backend, and a failed refresh leaves the existing cache serving stale
+     * with its age (R4.3).
+     */
+    maybeRefreshOrgCache(requestId) {
+        if (this.orgCacheRefreshInFlight)
+            return;
+        this.orgCacheRefreshInFlight = true;
+        void Promise.resolve().then(() => __importStar(require('../cli/utils/org-pack-sync'))).then(async ({ getOrgCacheAgeHours, syncOrgCache }) => {
+            const ageHours = getOrgCacheAgeHours();
+            if (ageHours !== null && ageHours < 24)
+                return;
+            const outcome = await syncOrgCache();
+            if (outcome.status !== 'disabled') {
+                const version = outcome.metadata ? ` (version ${outcome.metadata.version.slice(0, 12)})` : '';
+                this.log(`[req:${requestId}] Org cache refresh at connect: ${outcome.status}${version}`);
+            }
+        })
+            .catch((error) => {
+            this.logError(`[req:${requestId}] Org cache refresh failed: ${error?.message || error}`);
+        })
+            .finally(() => {
+            this.orgCacheRefreshInFlight = false;
+        });
     }
     /**
      * Automatically detect machine information

package/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 /**
  * FRAIM Framework - Smart Entry Point

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim-framework",
-  "version": "2.0.163",
+  "version": "2.0.165",
   "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": {
@@ -104,7 +104,6 @@
     "@types/prompts": "^2.4.9",
     "@types/semver": "^7.7.1",
     "fast-glob": "^3.3.3",
-    "html-to-docx": "^1.8.0",
     "markdown-it": "^14.1.1",
     "markdown-it-highlightjs": "^4.3.0",
     "playwright": "^1.58.2",

package/public/ai-hub/index.html

@@ -9,7 +9,7 @@
   <!-- Detect Electron + host platform before CSS paints so html.electron / html.mac /
        html.win / html.linux rules apply on first render (no flash, correct native chrome). -->
   <script>(function(){var h=document.documentElement,ua=navigator.userAgent;if(/Electron/.test(ua))h.classList.add('electron');var p=(navigator.userAgentData&&navigator.userAgentData.platform)||navigator.platform||'';if(/mac/i.test(p)||/Mac|iPhone|iPad|iPod/.test(ua))h.classList.add('mac');else if(/win/i.test(p)||/Windows/.test(ua))h.classList.add('win');else if(/linux/i.test(p)||/Linux|X11/.test(ua))h.classList.add('linux');})();</script>
-  <link rel="stylesheet" href="./styles.css">
+  <link rel="stylesheet" href="./styles.css?v=conv-panels-20260611b">
   <link rel="stylesheet" href="./review.css">
 </head>
 <body>
@@ -363,7 +363,7 @@
               <summary>
                 <span class="panel-summary-copy">
                   <span class="panel-kicker">Micro-manage</span>
-                  <span class="panel-summary-text">Raw host details</span>
+                  <span class="panel-summary-text">Raw host events and tool calls</span>
                 </span>
               </summary>
               <pre class="micro-log" id="micro-log"></pre>