fraim 2.0.271 → 2.0.272

package/dist/src/cli/utils/remote-sync.js

@@ -12,6 +12,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SYNCED_CONTENT_BANNER_MARKER = void 0;
+exports.fetchRegistryFiles = fetchRegistryFiles;
+exports.syncScriptsToUserDir = syncScriptsToUserDir;
 exports.syncFromRemote = syncFromRemote;
 const axios_1 = __importDefault(require("axios"));
 const fs_1 = require("fs");
@@ -177,6 +179,42 @@ function applySyncedContentBanner(file) {
     const banner = buildSyncedContentBanner(typeLabel);
     return insertAfterFrontmatter(file.content, banner);
 }
+/**
+ * Fetch all registry files from the remote FRAIM server.
+ * Extracted so callers can partition the result (scripts vs project stubs).
+ */
+async function fetchRegistryFiles(remoteUrl, apiKey) {
+    const response = await fetchRegistrySync(remoteUrl, apiKey);
+    return response.data.files || [];
+}
+/**
+ * Sync script files to the user-level ~/.fraim/scripts/ directory.
+ * Extracted from syncFromRemote so it can run without a project root.
+ */
+async function syncScriptsToUserDir(files) {
+    const scriptFiles = files.filter(f => f.type === 'script');
+    if (scriptFiles.length === 0)
+        return 0;
+    const userDir = (0, script_sync_utils_1.getUserFraimDir)();
+    const scriptsDir = (0, path_1.join)(userDir, 'scripts');
+    if (!(0, fs_1.existsSync)(scriptsDir)) {
+        (0, fs_1.mkdirSync)(scriptsDir, { recursive: true });
+    }
+    cleanDirectory(scriptsDir, (candidatePath) => {
+        if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(scriptsDir)) {
+            assertPathInsideDirectory(scriptsDir, candidatePath, 'script directory');
+        }
+    });
+    for (const file of scriptFiles) {
+        const { filePath } = resolveUserRegistryFile(scriptsDir, file.path, 'script file');
+        const fileDir = (0, path_1.dirname)(filePath);
+        if (!(0, fs_1.existsSync)(fileDir)) {
+            (0, fs_1.mkdirSync)(fileDir, { recursive: true });
+        }
+        (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
+    }
+    return scriptFiles.length;
+}
 /**
  * Sync jobs and scripts from remote FRAIM server
  */
@@ -200,9 +238,7 @@ async function syncFromRemote(options) {
         const assertWorkspacePath = (0, project_fraim_paths_1.createWorkspaceFraimPathAsserter)(options.projectRoot);
         console.log(chalk_1.default.blue('🔄 Syncing from remote FRAIM server...'));
         console.log(chalk_1.default.gray(`   Remote: ${remoteUrl}`));
-        // Fetch registry files from remote server
-        const response = await fetchRegistrySync(remoteUrl, apiKey);
-        const files = response.data.files || [];
+        const files = options.registryFiles || await fetchRegistryFiles(remoteUrl, apiKey);
         if (!files || files.length === 0) {
             console.log(chalk_1.default.yellow('⚠️  No files received from remote server'));
             return {
@@ -297,29 +333,9 @@ async function syncFromRemote(options) {
             (0, fs_1.writeFileSync)(filePath, applySyncedContentBanner(file), 'utf8');
             console.log(chalk_1.default.gray(`  + ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)(`ai-employee/rules/${relativePath}`)} (stub)`));
         }
-        // Sync scripts to user directory
+        // Scripts are synced by machine-level layer (syncScriptsToUserDir).
+        // Only count them for the result.
         const scriptFiles = files.filter(f => f.type === 'script');
-        const userDir = (0, script_sync_utils_1.getUserFraimDir)();
-        const scriptsDir = (0, path_1.join)(userDir, 'scripts');
-        if (!(0, fs_1.existsSync)(scriptsDir)) {
-            (0, fs_1.mkdirSync)(scriptsDir, { recursive: true });
-        }
-        // Clean existing scripts
-        cleanDirectory(scriptsDir, (candidatePath) => {
-            if ((0, path_1.resolve)(candidatePath) !== (0, path_1.resolve)(scriptsDir)) {
-                assertPathInsideDirectory(scriptsDir, candidatePath, 'script directory');
-            }
-        });
-        // Write script files
-        for (const file of scriptFiles) {
-            const { filePath, relativePath } = resolveUserRegistryFile(scriptsDir, file.path, 'script file');
-            const fileDir = (0, path_1.dirname)(filePath);
-            if (!(0, fs_1.existsSync)(fileDir)) {
-                (0, fs_1.mkdirSync)(fileDir, { recursive: true });
-            }
-            (0, fs_1.writeFileSync)(filePath, file.content, 'utf8');
-            console.log(chalk_1.default.gray(`  + ${relativePath}`));
-        }
         // Sync docs to fraim/docs/
         const docsFiles = files.filter(f => f.type === 'docs');
         const docsDir = (0, project_fraim_paths_1.getWorkspaceFraimPath)(options.projectRoot, 'docs');

package/dist/src/first-run/types.js

@@ -64,8 +64,8 @@ exports.FIRST_RUN_AGENT_OPTIONS = [
         detectAliases: ['agy', 'antigravity', 'antigravity-cli'],
         loginCommand: 'agy auth login',
         launchCommand: 'agy',
-        // agy has no npm package — install via https://antigravity.google/cli/
         installPackage: '',
+        installUrl: 'https://antigravity.google/cli/',
     },
 ];
 /**

package/dist/src/local-mcp-server/learning-usage-command.js

@@ -0,0 +1,408 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.learningUsageCommand = void 0;
+/**
+ * Issue #1103 - command surface used by the learning-usage script.
+ *
+ * The read and analysis side of the usage record. The write side of an offer is the
+ * proxy (no agent involvement, R2); the write side of a firing is an attestation in
+ * a retrospective, which `record-firings` reads back.
+ */
+const commander_1 = require("commander");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const learning_context_builder_1 = require("./learning-context-builder");
+const learning_usage_analysis_1 = require("./learning-usage-analysis");
+const learning_usage_store_1 = require("./learning-usage-store");
+const learning_usage_attestation_1 = require("./learning-usage-attestation");
+function resolveWorkspaceRoot(options) {
+    return node_path_1.default.resolve(options.workspaceRoot || options.root || process.cwd());
+}
+function resolveUser(options) {
+    const email = options.user || process.env.FRAIM_ACTIVE_USER_EMAIL || '';
+    if (!email.trim()) {
+        throw new Error('Missing active user email. Pass --user <email> or set FRAIM_ACTIVE_USER_EMAIL.');
+    }
+    return email.trim();
+}
+function emit(payload, json, text) {
+    process.stdout.write(json ? `${JSON.stringify(payload, null, 2)}\n` : `${text()}\n`);
+}
+function addCommonOptions(command) {
+    return command
+        .option('--workspace-root <path>', 'Workspace root containing fraim/config.json')
+        .option('--root <path>', 'Alias for --workspace-root')
+        .option('--user <email>', 'Active user email')
+        .option('--json', 'Print JSON');
+}
+// ── offers ───────────────────────────────────────────────────────────────────
+const offersCommand = addCommonOptions(new commander_1.Command('offers'))
+    .description('List the learning entries and rule files the runtime delivered, so an attestation is written against the record rather than memory')
+    .option('--job <name>', 'The job whose context was loaded', 'unknown')
+    .option('--domain <domain>', 'Learning domain the job resolved to')
+    .option('--session', 'Use the session frame rather than the job frame')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const user = resolveUser(options);
+    const forJob = !options.session;
+    // Prefer what the runtime recorded for this job, because that is what was
+    // actually delivered. Re-deriving from the files on disk answers a subtly
+    // different question — what would be delivered now — and the two diverge if a
+    // learning file changed during the job.
+    const store = (0, learning_usage_store_1.readUsageStore)();
+    const recorded = Object.values(store.entries)
+        .filter((entry) => entry.offered.log.some((offer) => offer.job === options.job))
+        .map((entry) => {
+        const last = [...entry.offered.log].reverse().find((offer) => offer.job === options.job);
+        return {
+            key: entry.key,
+            family: entry.family,
+            id: entry.key.startsWith('L-') ? entry.key : null,
+            title: entry.titles[entry.titles.length - 1] ?? entry.key,
+            fileType: entry.fileType ?? 'unknown',
+            level: entry.level ?? 'unknown',
+            displayPath: '',
+            severity: null,
+            aboveThreshold: last.aboveThreshold,
+        };
+    });
+    const source = recorded.length > 0 ? 'offer-record' : 'derived';
+    const offered = recorded.length > 0
+        ? recorded
+        : [
+            ...(0, learning_context_builder_1.collectOfferedLearningEntries)(workspaceRoot, user, forJob, options.domain ?? null),
+            ...(0, learning_context_builder_1.collectOfferedRuleFiles)(workspaceRoot, forJob),
+        ];
+    const payload = { job: options.job, forJob, source, offered };
+    emit(payload, options.json, () => {
+        if (payload.offered.length === 0) {
+            return `No offer record and nothing resolves for job ${options.job}. Do not attest any firing for this job.`;
+        }
+        const rows = payload.offered.map((o) => `| ${o.id ?? '(no id)'} | ${o.title} | ${o.fileType} | ${o.aboveThreshold ? 'yes' : 'no'} |`);
+        const header = source === 'offer-record'
+            ? `Entries offered for job ${options.job}, from the offer record:`
+            : `No offer record exists for job ${options.job} yet, so this is what would be delivered now. Say so when you attest against it.`;
+        return [
+            header,
+            '',
+            '| Id | Title | Family | Above threshold |',
+            '|---|---|---|---|',
+            ...rows,
+        ].join('\n');
+    });
+});
+// ── record-firings ───────────────────────────────────────────────────────────
+const recordFiringsCommand = addCommonOptions(new commander_1.Command('record-firings'))
+    .description('Read the firing section of a retrospective and write the attested firings into the usage record')
+    .requiredOption('--retrospective <path>', 'Retrospective file to read')
+    .option('--job <name>', 'The job that produced the retrospective')
+    .option('--agent <name>', 'Agent that attested')
+    .option('--model <model>', 'Model that attested')
+    .option('--legacy', 'Also accept the pre-#1103 prose form')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const user = resolveUser(options);
+    const filePath = node_path_1.default.resolve(options.retrospective);
+    if (!node_fs_1.default.existsSync(filePath)) {
+        throw new Error(`Retrospective not found: ${filePath}`);
+    }
+    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const source = node_path_1.default.relative(workspaceRoot, filePath).replace(/\\/g, '/');
+    const result = (0, learning_usage_attestation_1.recordAttestationsFromRetrospective)(workspaceRoot, user, {
+        content,
+        source,
+        job: options.job ?? 'unknown',
+        agent: options.agent ?? null,
+        model: options.model ?? null,
+        legacy: Boolean(options.legacy),
+    });
+    emit(result, options.json, () => {
+        const lines = [
+            `Section state: ${result.sectionState}`,
+            `Items read: ${result.itemsRead}`,
+            `Recorded: ${result.applied}`,
+            `Already recorded: ${result.alreadyRecorded}`,
+            `Unmatched: ${result.unmatched.length}`,
+            `Rejected: ${result.rejected.length}`,
+        ];
+        for (const item of result.unmatched)
+            lines.push(`  unmatched: ${item.title} — ${item.reason}`);
+        for (const item of result.rejected)
+            lines.push(`  rejected: ${item.reason}`);
+        return lines.join('\n');
+    });
+});
+// ── classify ─────────────────────────────────────────────────────────────────
+const classifyCommand = addCommonOptions(new commander_1.Command('classify'))
+    .description('Say whether a recurrence was ignored (the entry was in context) or not-offered (it never reached the agent), because the two need different fixes')
+    .option('--entry <id>', 'The entry id, for an entry that carries one')
+    .option('--title <title>', 'The exact entry title, for an entry with no id yet. Use with --family')
+    .option('--family <family>', 'The entry family: mistake-patterns, preferences, validated-patterns, or manager-coaching')
+    .requiredOption('--job <name>', 'The job the recurrence happened in')
+    .requiredOption('--date <YYYY-MM-DD>', 'The date the mistake recurred')
+    .option('--window <days>', 'How far back an offer still counts as in-context', '30')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    // `--title` plus `--family` exists so a caller never has to build the composite
+    // title key by hand. An entry title is corpus content and can contain any
+    // character, so an agent assembling `T:<family>:<title>` into a shell command
+    // would be interpolating untrusted text into a command line. Passing the title
+    // as its own argument keeps it a single argv entry.
+    let key;
+    if (options.entry) {
+        key = String(options.entry);
+    }
+    else if (options.title && options.family) {
+        key = (0, learning_usage_store_1.titleUsageKey)(String(options.family), String(options.title));
+    }
+    else {
+        throw new Error('Pass --entry <id>, or --title <title> together with --family <family>.');
+    }
+    const store = (0, learning_usage_store_1.readUsageStore)();
+    const diagnosis = (0, learning_usage_analysis_1.classifyRecurrence)(store, {
+        key,
+        job: options.job,
+        date: options.date,
+        windowDays: Number.parseInt(options.window, 10) || 30,
+    });
+    void workspaceRoot;
+    emit(diagnosis, options.json, () => [
+        `Classification: ${diagnosis.classification}`,
+        `Diagnosis: ${diagnosis.diagnosis}`,
+        `Recommendation: ${diagnosis.recommendation}`,
+        `Raise the recurrence count: ${diagnosis.recurrenceBump ? 'yes' : 'no'}`,
+    ].join('\n'));
+});
+// ── candidates ───────────────────────────────────────────────────────────────
+const candidatesCommand = addCommonOptions(new commander_1.Command('candidates'))
+    .description('List retirement candidates: offered often under the current model with no firing under it, paired with a structural signal')
+    .option('--model <model>', 'Override the current model (defaults to the most recently offered-to model)')
+    .option('--detector <path>', 'Path to the corpus hygiene detector that provides the structural signal')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const result = (0, learning_usage_analysis_1.findRetirementCandidates)((0, learning_usage_store_1.readUsageStore)(), {
+        workspaceRoot,
+        limits,
+        currentModel: options.model ?? undefined,
+        structuralSignalPath: options.detector,
+    });
+    emit(result, options.json, () => {
+        if (result.candidates.length === 0) {
+            return `No retirement candidates. Current model: ${result.currentModel ?? 'unknown'}; threshold ${result.offerThreshold} offers.`;
+        }
+        const lines = [`Current model: ${result.currentModel ?? 'unknown'}. Threshold: ${result.offerThreshold} offers.`, ''];
+        for (const c of result.candidates) {
+            const earlier = c.firedUnderEarlierModels.map((m) => `${m.count} under ${m.model}`).join(', ') || 'none under any earlier model';
+            lines.push(`- ${c.title}`, `  Offered ${c.offeredUnderCurrentModel} times under the current model, fired ${c.firedUnderCurrentModel}. Earlier: ${earlier}.`, `  Structural signal: ${c.structural}. ${c.structuralDetail}`, `  Recommendation: ${c.recommendation}`);
+        }
+        return lines.join('\n');
+    });
+});
+// ── standing ─────────────────────────────────────────────────────────────────
+const standingCommand = addCommonOptions(new commander_1.Command('standing'))
+    .description('Assess each entry as promoted, standard or demoted from its usage record, and list the ones whose standing should change')
+    .option('--changes-only', 'Print only the entries whose standing should change')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const report = (0, learning_usage_analysis_1.assessStanding)((0, learning_usage_store_1.readUsageStore)(), { limits });
+    const payload = options.changesOnly ? { ...report, assessments: report.changes } : report;
+    emit(payload, options.json, () => {
+        const rows = (options.changesOnly ? report.changes : report.assessments);
+        if (rows.length === 0) {
+            return options.changesOnly
+                ? 'No standing changes. Every measured entry is already where the record says it belongs.'
+                : 'No entry has a usage record yet, so there is nothing to assess.';
+        }
+        const lines = [];
+        if (report.changes.length > 0) {
+            lines.push(`${report.changes.length} entr${report.changes.length === 1 ? 'y' : 'ies'} should change standing.`, '');
+        }
+        for (const a of rows) {
+            lines.push(`- ${a.title}`);
+            lines.push(`  ${a.standing}${a.recommendation ? ` (recommend: ${a.recommendation})` : ''}. ${a.reason}`);
+        }
+        lines.push('', 'Nothing is applied here. Run sleep-on-learnings to decide.');
+        return lines.join('\n');
+    });
+});
+// ── report ───────────────────────────────────────────────────────────────────
+const reportCommand = addCommonOptions(new commander_1.Command('report'))
+    .description('Answer which learnings are still earning their place, from the record rather than from memory')
+    .option('--window <days>', 'Reporting window', '90')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const report = (0, learning_usage_analysis_1.buildUsageReport)((0, learning_usage_store_1.readUsageStore)(), {
+        workspaceRoot,
+        limits,
+        windowDays: Number.parseInt(options.window, 10) || 90,
+    });
+    emit(report, options.json, () => {
+        const lines = [
+            `${report.totals.entriesOffered} entries were offered. ${report.totals.entriesWithFirings} fired. ${report.totals.entriesNeverFired} have never fired.`,
+        ];
+        if (report.workingHardest.length) {
+            lines.push('', 'Working hardest');
+            report.workingHardest.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Offered ${e.offered} times, fired ${e.fired}. Last fired ${e.lastFired ?? 'never'}.`));
+        }
+        if (report.neverFired.length) {
+            lines.push('', 'Never fired');
+            report.neverFired.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. Offered ${e.offered} times, never fired.`));
+        }
+        if (report.ignoredWhileInContext.length) {
+            lines.push('', 'Ignored while in context');
+            report.ignoredWhileInContext.forEach((e, i) => lines.push(`${i + 1}. ${e.title}. In context and the work went against it, so the entry needs work rather than another recurrence.`));
+        }
+        lines.push('', 'Nothing is retired from this view. Run sleep-on-learnings to decide.');
+        return lines.join('\n');
+    });
+});
+// ── backfill ─────────────────────────────────────────────────────────────────
+const backfillCommand = addCommonOptions(new commander_1.Command('backfill'))
+    .description('Read the firings already attested in existing retrospectives, matching only on an id or an exact title, and report what could not be matched')
+    .option('--agent <name>', 'Agent to attribute the backfilled records to', 'backfill')
+    .option('--model <model>', 'Model to attribute the backfilled records to')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const user = resolveUser(options);
+    const report = (0, learning_usage_attestation_1.runBackfill)(workspaceRoot, user, {
+        agent: options.agent ?? 'backfill',
+        model: options.model ?? null,
+    });
+    emit(report, options.json, () => [
+        `Files scanned: ${report.filesScanned} (${report.filesWithSection} carry the section, ${report.synthesizedFilesRead} already synthesized)`,
+        `Items read: ${report.itemsRead}`,
+        `Applied: ${report.applied}`,
+        `Already recorded: ${report.alreadyRecorded}`,
+        `Unmatched: ${report.unmatched.length}`,
+        `Rejected: ${report.rejected.length}`,
+        '',
+        'Only an id or an exact title resolves. A low match rate is expected on retrospectives written before entries carried ids, and is reported rather than resolved by similarity matching.',
+    ].join('\n'));
+});
+/**
+ * Add the `**Id**` line to entries that do not have one.
+ *
+ * This is a format migration, not a change to any lesson: it inserts one
+ * identifier line per entry and touches nothing else. R19 forbids a new write path
+ * into the corpus for usage data, and this is not one — it writes no usage data,
+ * and it is run explicitly by the manager rather than by any automatic path.
+ */
+function stampFile(filePath, fileType, apply) {
+    const content = node_fs_1.default.readFileSync(filePath, 'utf8');
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    const lines = content.split(/\r?\n/);
+    const headingRe = (0, learning_context_builder_1.learningEntryHeadingRegex)();
+    const idRe = (0, learning_context_builder_1.learningEntryIdLineRegex)();
+    const out = [];
+    let stamped = 0;
+    let alreadyStamped = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        out.push(line);
+        const header = line.match(headingRe);
+        if (!header)
+            continue;
+        // Look ahead to the next entry heading for an existing id line.
+        let hasId = false;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (headingRe.test(lines[j]))
+                break;
+            if (idRe.test(lines[j].trim())) {
+                hasId = true;
+                break;
+            }
+        }
+        if (hasId) {
+            alreadyStamped++;
+            continue;
+        }
+        const title = header[2].trim();
+        if (!title)
+            continue;
+        // Insert immediately after the heading, keeping the blank line that usually
+        // follows it so the file's shape is unchanged.
+        if (lines[i + 1] !== undefined && lines[i + 1].trim() === '') {
+            out.push('');
+            out.push(`**Id**: ${(0, learning_context_builder_1.generateLearningEntryId)(fileType, title)}`);
+            i++;
+        }
+        else {
+            out.push(`**Id**: ${(0, learning_context_builder_1.generateLearningEntryId)(fileType, title)}`);
+        }
+        stamped++;
+    }
+    if (apply && stamped > 0) {
+        node_fs_1.default.writeFileSync(filePath, out.join(eol), 'utf8');
+    }
+    return { file: filePath, entriesStamped: stamped, entriesAlreadyStamped: alreadyStamped };
+}
+const FILE_TYPES = ['mistake-patterns', 'preferences', 'validated-patterns', 'manager-coaching'];
+function fileTypeFromName(fileName) {
+    for (const type of FILE_TYPES) {
+        if (fileName.includes(type))
+            return type;
+    }
+    return null;
+}
+const stampIdsCommand = addCommonOptions(new commander_1.Command('stamp-ids'))
+    .description('Add the stable Id line to learning entries that do not have one. A format migration: it inserts one identifier line per entry and changes no lesson text')
+    .option('--dir <path>', 'Learning directory to stamp (repeatable)', (value, previous) => [...previous, value], [])
+    .option('--apply', 'Write the changes. Without this flag the command reports what it would do')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const dirs = options.dir.length
+        ? options.dir.map((d) => node_path_1.default.resolve(d))
+        : [node_path_1.default.join(workspaceRoot, 'fraim', 'personalized-employee', 'learnings')];
+    const results = [];
+    for (const dir of dirs) {
+        if (!node_fs_1.default.existsSync(dir))
+            continue;
+        for (const fileName of node_fs_1.default.readdirSync(dir)) {
+            if (!fileName.endsWith('.md'))
+                continue;
+            const fileType = fileTypeFromName(fileName);
+            if (!fileType)
+                continue;
+            results.push(stampFile(node_path_1.default.join(dir, fileName), fileType, Boolean(options.apply)));
+        }
+    }
+    const payload = {
+        apply: Boolean(options.apply),
+        filesScanned: results.length,
+        entriesStamped: results.reduce((sum, r) => sum + r.entriesStamped, 0),
+        entriesAlreadyStamped: results.reduce((sum, r) => sum + r.entriesAlreadyStamped, 0),
+        files: results,
+    };
+    emit(payload, options.json, () => [
+        `${payload.apply ? 'Stamped' : 'Would stamp'} ${payload.entriesStamped} entries across ${payload.filesScanned} files.`,
+        `${payload.entriesAlreadyStamped} entries already carry an id.`,
+        payload.apply ? '' : 'Re-run with --apply to write the changes.',
+    ].filter(Boolean).join('\n'));
+});
+// ── prune ────────────────────────────────────────────────────────────────────
+const pruneCommand = addCommonOptions(new commander_1.Command('prune'))
+    .description('Apply the configured retention window and log bounds to the usage record. Aggregate counters are never pruned')
+    .action((options) => {
+    const workspaceRoot = resolveWorkspaceRoot(options);
+    const limits = (0, learning_usage_store_1.resolveUsageLimits)(workspaceRoot);
+    const result = (0, learning_usage_store_1.pruneUsageStore)(limits);
+    emit({ ...result, storePath: (0, learning_usage_store_1.resolveUsageStorePath)(), limits }, options.json, () => `Pruned ${result.prunedOfferRecords} offer records and ${result.prunedFiringRecords} firing records across ${result.entries} entries. Aggregates unchanged.`);
+});
+// ── root ─────────────────────────────────────────────────────────────────────
+exports.learningUsageCommand = new commander_1.Command('learning-usage')
+    .description('Read and analyse the learning and rule usage record (issue #1103)')
+    .addCommand(offersCommand)
+    .addCommand(recordFiringsCommand)
+    .addCommand(classifyCommand)
+    .addCommand(candidatesCommand)
+    .addCommand(standingCommand)
+    .addCommand(reportCommand)
+    .addCommand(backfillCommand)
+    .addCommand(stampIdsCommand)
+    .addCommand(pruneCommand);

package/dist/src/local-mcp-server/learning-usage-store.js

@@ -139,8 +139,8 @@ function emptyStore() {
  * The shallow `record.offered && record.fired` this replaced was not enough. A
  * record whose sub-objects exist but are empty passed it and then threw in
  * `buildUsageReport` (`record.offered.log is not iterable`),
- * `findRetirementCandidates` and `deriveStanding`, so `fraim learning-usage
- * report` and `candidates` failed outright instead of degrading. That state is
+ * `findRetirementCandidates` and `deriveStanding`, so usage reports and
+ * candidate analysis failed outright instead of degrading. That state is
  * reachable: the store is a JSON file inside the manager home, which is commonly
  * a synced folder, so an interrupted write or a partial sync produces valid JSON
  * with a hollow record.

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

@@ -12,7 +12,7 @@ const PROVIDERS = {
         description: 'GitHub repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://github.com/settings/tokens',
-        setupInstructions: 'Run "fraim add-provider github" — your IDE handles OAuth automatically on first use',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current GitHub and host guidance',
         mcpServer: {
             type: 'http',
             url: 'https://api.githubcopilot.com/mcp/'
@@ -25,7 +25,7 @@ const PROVIDERS = {
         description: 'GitLab repository and issue management',
         capabilities: ['code', 'issues', 'integrated'],
         docsUrl: 'https://gitlab.com/-/profile/personal_access_tokens',
-        setupInstructions: 'Create a Personal Access Token at https://gitlab.com/-/profile/personal_access_tokens with api scope',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current GitLab and host guidance',
         mcpServer: {
             type: 'http',
             url: 'https://gitlab.com/api/v4/mcp',
@@ -49,7 +49,7 @@ const PROVIDERS = {
             }
         ],
         docsUrl: 'https://dev.azure.com',
-        setupInstructions: 'Create a Personal Access Token in Azure DevOps with Code (Read & Write) and Work Items (Read & Write) scopes',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current Azure DevOps and host guidance',
         mcpServer: {
             type: 'stdio',
             command: 'npx',
@@ -91,7 +91,7 @@ const PROVIDERS = {
             }
         ],
         docsUrl: 'https://id.atlassian.com/manage-profile/security/api-tokens',
-        setupInstructions: 'Create an API Token at https://id.atlassian.com/manage-profile/security/api-tokens',
+        setupInstructions: 'Ask your agent to use the FRAIM connect-mcp skill and follow current Jira and host guidance',
         mcpServer: {
             type: 'stdio',
             command: 'uvx',

package/package.json

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