@open-product-primer/cli 2.0.0 → 2.1.0

package/README.md

@@ -27,5 +27,11 @@ Bin aliases: `open-product-primer`, `oprim`.
 | `oprim update` | Refresh `/oprim:*` assistant commands and skills |
 | `oprim doctor` | Verify scaffold, integrations, and measurement env |
 | `oprim measure` | Run KPI measurement pipeline for a bet |
+| `oprim context` | Print resolved remote context content (`--source <name>` to scope to one) |
+| `oprim context init` | Declare the current project a citable remote context (`--description`); prefer the guided `/oprim:context-init` skill in Claude Code |
+| `oprim context register` | Register a remote context source (`--git <url>` or `--local <path>`, `--name`, optional `--description`) |
+| `oprim context list` | List every registered source's name, kind, and description without fully resolving any of them |
+
+A remote context is an oprim workspace bundled somewhere outside the current project's directory — a remote git repo or a local sibling directory — that this project can reference read-only. Content resolves fresh on demand (never a persistent clone you have to `git pull` yourself); `oprim context list` is the cheap way to see what's registered before pulling full content.
 
 Full documentation: [github.com/eshraw/open-product-primer](https://github.com/eshraw/open-product-primer).

package/dist/cli.js

@@ -11,6 +11,7 @@ const doctor_1 = require("./commands/doctor");
 const migrate_1 = require("./commands/migrate");
 const measure_1 = require("./commands/measure");
 const ovw_1 = require("./commands/ovw");
+const context_1 = require("./commands/context");
 const package_json_1 = __importDefault(require("../package.json"));
 const program = new commander_1.Command();
 program
@@ -23,4 +24,5 @@ program.addCommand((0, doctor_1.doctorCommand)());
 program.addCommand((0, migrate_1.migrateCommand)());
 program.addCommand((0, measure_1.measureCommand)());
 program.addCommand((0, ovw_1.ovwCommand)());
+program.addCommand((0, context_1.contextCommand)());
 program.parse();

package/dist/commands/context.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function contextCommand(): Command;

package/dist/commands/context.js

@@ -0,0 +1,188 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contextCommand = contextCommand;
+const commander_1 = require("commander");
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const remote_context_1 = require("../lib/remote-context");
+const scaffold_1 = require("../lib/scaffold");
+function sourceKind(source) {
+    return (0, remote_context_1.isGitSource)(source) ? 'git' : 'path';
+}
+function initSubcommand() {
+    return new commander_1.Command('init')
+        .description('Declare the current project as a citable remote context')
+        .option('--description <text>', 'canonical description of what this context contains')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        if ((0, scaffold_1.fileExists)((0, remote_context_1.identityFilePath)(projectRoot))) {
+            console.log(chalk_1.default.yellow('A remote context identity already exists at ') + chalk_1.default.cyan('.oprim-context/context.yaml'));
+            return;
+        }
+        const name = path.basename(projectRoot);
+        (0, remote_context_1.writeIdentity)(projectRoot, { name, version: '1', description: opts.description });
+        console.log(chalk_1.default.green('✓') + ' .oprim-context/context.yaml created');
+        console.log(`  name: ${name}`);
+        if (opts.description) {
+            console.log(`  description: ${opts.description}`);
+        }
+        else {
+            console.log(chalk_1.default.yellow('  no description set') +
+                ' — other projects referencing this context via ' +
+                chalk_1.default.cyan('oprim context list') +
+                ' will see it as description-less.');
+        }
+    });
+}
+function registerSubcommand() {
+    return new commander_1.Command('register')
+        .description('Register a remote context source in the current project')
+        .option('--git <url>', 'git remote URL of the remote context')
+        .option('--local <path>', 'local filesystem path of the remote context')
+        .requiredOption('--name <name>', 'name to register this source under')
+        .option('--description <text>', 'local note about why this source was registered')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        if ((opts.git && opts.local) || (!opts.git && !opts.local)) {
+            console.error(chalk_1.default.red('Exactly one of --git or --local is required.'));
+            process.exit(1);
+        }
+        const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+        if ((0, remote_context_1.findSourceByName)(config, opts.name)) {
+            console.error(chalk_1.default.red(`A source named "${opts.name}" is already registered.`));
+            process.exit(1);
+        }
+        const source = opts.git
+            ? { name: opts.name, git: opts.git, description: opts.description }
+            : { name: opts.name, path: opts.local, description: opts.description };
+        config.enabled = true;
+        config.sources.push(source);
+        (0, remote_context_1.writeRemoteContextConfig)(projectRoot, config);
+        console.log(chalk_1.default.green('✓') + ` Registered "${opts.name}" (${sourceKind(source)})`);
+        const result = (0, remote_context_1.resolveIdentityOnly)(source);
+        if (result.error) {
+            console.log(chalk_1.default.yellow('  Could not confirm this source yet: ') +
+                result.error +
+                chalk_1.default.dim(' — try `oprim context list` or `oprim doctor` to retry later.'));
+            return;
+        }
+        if (result.nameMismatch) {
+            console.log(chalk_1.default.yellow(`  Warning: declared name "${result.nameMismatch.declared}" does not match resolved identity name "${result.nameMismatch.resolved}".`));
+        }
+        if (result.identity?.description) {
+            console.log(`  ${chalk_1.default.dim('description:')} ${result.identity.description}`);
+        }
+        else {
+            console.log(chalk_1.default.dim('  (no canonical description set on this source)'));
+        }
+    });
+}
+function listSubcommand() {
+    return new commander_1.Command('list')
+        .description('List every registered remote context source, without fully resolving any of them')
+        .action(() => {
+        const projectRoot = process.cwd();
+        const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+        if (!config.enabled || config.sources.length === 0) {
+            console.log('No remote contexts configured.');
+            return;
+        }
+        for (const source of config.sources) {
+            const kind = sourceKind(source);
+            console.log(`${chalk_1.default.bold(source.name)} ${chalk_1.default.dim(`(${kind})`)}`);
+            const result = (0, remote_context_1.resolveIdentityOnly)(source);
+            if (result.error) {
+                console.log('  ' + chalk_1.default.red(`unresolved: ${result.error}`));
+            }
+            else {
+                const desc = result.identity?.description;
+                console.log('  ' + (desc ? desc : chalk_1.default.dim('no description set')));
+                if (result.nameMismatch) {
+                    console.log(chalk_1.default.yellow(`  name mismatch: declared "${result.nameMismatch.declared}", resolved "${result.nameMismatch.resolved}"`));
+                }
+            }
+            if (source.description) {
+                console.log('  ' + chalk_1.default.dim(`local note: ${source.description}`));
+            }
+            console.log('');
+        }
+    });
+}
+function contextCommand() {
+    const cmd = new commander_1.Command('context')
+        .description('Print resolved remote context content')
+        .option('--source <name>', 'limit output to a single named source')
+        .action((opts) => {
+        const projectRoot = process.cwd();
+        const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+        if (!config.enabled || config.sources.length === 0) {
+            console.log('No remote contexts configured.');
+            return;
+        }
+        let sources = config.sources;
+        if (opts.source) {
+            const match = (0, remote_context_1.findSourceByName)(config, opts.source);
+            if (!match) {
+                console.error(chalk_1.default.red(`No source named "${opts.source}" is registered.`));
+                process.exit(1);
+            }
+            sources = [match];
+        }
+        for (const source of sources) {
+            console.log(chalk_1.default.bold(`═══ ${source.name} ═══`));
+            const result = (0, remote_context_1.resolveFull)(source);
+            if (result.error) {
+                console.log(chalk_1.default.red(`  unresolved: ${result.error}`));
+                continue;
+            }
+            if (result.stale) {
+                console.log(chalk_1.default.yellow('  (stale — last successful fetch could not be refreshed)'));
+            }
+            if (result.nameMismatch) {
+                console.log(chalk_1.default.yellow(`  name mismatch: declared "${result.nameMismatch.declared}", resolved "${result.nameMismatch.resolved}"`));
+            }
+            console.log((0, remote_context_1.assembleOprimWorkspaceContent)(result.workspaceRoot));
+            console.log('');
+        }
+    });
+    cmd.addCommand(initSubcommand());
+    cmd.addCommand(registerSubcommand());
+    cmd.addCommand(listSubcommand());
+    return cmd;
+}

package/dist/commands/doctor.js

@@ -44,6 +44,7 @@ const chalk_1 = __importDefault(require("chalk"));
 const detect_1 = require("../lib/detect");
 const measure_1 = require("../lib/measure");
 const integrity_1 = require("../lib/integrity");
+const remote_context_1 = require("../lib/remote-context");
 const AGENT_DIRS = {
     claude: '.claude',
     cursor: '.cursor',
@@ -103,6 +104,52 @@ function checkClaudeHooks(projectRoot, checks) {
         required: false,
     });
 }
+// bet-026 — validates each configured remote_context.sources entry using the identity-only
+// fetch (cheap: single file, not a full workspace pull), plus a separate "ever fully
+// resolved" nudge that only applies to git sources (local paths have no persistent cache).
+function checkRemoteContexts(projectRoot, checks) {
+    const config = (0, remote_context_1.readRemoteContextConfig)(projectRoot);
+    if (!config.enabled || config.sources.length === 0)
+        return;
+    for (const source of config.sources) {
+        const kind = (0, remote_context_1.isGitSource)(source) ? 'git' : 'path';
+        const result = (0, remote_context_1.resolveIdentityOnly)(source);
+        if (result.error) {
+            checks.push({
+                name: `remote_context: ${source.name} (${kind})`,
+                pass: false,
+                note: `${kind === 'git' ? 'Remote unreachable' : 'Path not found'}: ${result.error} — run 'oprim context list' to retry`,
+                required: false,
+            });
+            continue;
+        }
+        if (!result.identity) {
+            checks.push({
+                name: `remote_context: ${source.name} (${kind})`,
+                pass: false,
+                note: `Missing remote context identity — ask the source project to run 'oprim context init'`,
+                required: false,
+            });
+            continue;
+        }
+        checks.push({
+            name: `remote_context: ${source.name} (${kind})`,
+            pass: true,
+            note: result.nameMismatch
+                ? `Name mismatch: declared "${result.nameMismatch.declared}", resolved "${result.nameMismatch.resolved}"`
+                : undefined,
+            required: false,
+        });
+        if ((0, remote_context_1.isGitSource)(source) && !(0, remote_context_1.hasEverFullyResolved)(source)) {
+            checks.push({
+                name: `remote_context: ${source.name} never fully resolved`,
+                pass: false,
+                note: `Run 'oprim context --source ${source.name}' to pull its content for the first time`,
+                required: false,
+            });
+        }
+    }
+}
 function doctorCommand() {
     return new commander_1.Command('doctor')
         .description('Check oprim install health and integration readiness')
@@ -209,6 +256,8 @@ function doctorCommand() {
         (0, integrity_1.checkSequenceIntegrity)(projectRoot, checks);
         // ── Skill version drift checks ────────────────────────────────────────────
         (0, integrity_1.checkSkillVersionDrift)(projectRoot, checks);
+        // ── Remote context checks ─────────────────────────────────────────────────
+        checkRemoteContexts(projectRoot, checks);
         // ── Agent environment checks ──────────────────────────────────────────────
         const configAgents = (0, detect_1.readAgentsFromConfig)(projectRoot);
         if (configAgents !== null) {

package/dist/lib/config-merge.js

@@ -7,7 +7,11 @@ exports.mergeSpecFramework = mergeSpecFramework;
 const CONFIG_SCHEMA_FIELDS = [
     { key: 'context', block: 'context: ""\n' },
     { key: 'rules', block: 'rules: {}\n' },
-    { key: 'store', block: 'store:\n  enabled: false\n' },
+    // bet-026 — supersedes the old inert `store:` key (BET-025). `store` is intentionally left
+    // out of this table going forward: a project that already has it keeps it untouched (this
+    // merge only adds missing keys, never removes existing ones), but new/updated configs only
+    // ever gain `remote_context`.
+    { key: 'remote_context', block: 'remote_context:\n  enabled: false\n  sources: []\n' },
 ];
 function existingTopLevelKeys(content) {
     const keys = new Set();

package/dist/lib/install-agent.js

@@ -382,12 +382,14 @@ exports.CLAUDE_SKILLS = {
     'oprim-review': reviewSkill(),
     'oprim-archive': archiveSkill(),
     'oprim-sequence': oprimSequenceSkill(),
+    'oprim-context-init': contextInitSkill(),
 };
 // ─── Claude command wrappers (thin, invoke skill) ────────────────────────────
 exports.CLAUDE_COMMANDS = {
     'promote.md': claudeWrapper('OPRIM: Promote', 'Promote a note into a bet, or a prioritized bet into a capability spec', promoteContent()),
     'sequence.md': claudeWrapper('OPRIM: Sequence', 'Validate and update the primer sequencing board', sequenceContent()),
     'archive.md': claudeWrapper('OPRIM: Archive', 'Archive a completed bet — move it out of the active board', archiveCommandContent()),
+    'context-init.md': claudeWrapper('OPRIM: Context Init', 'Declare the current project a citable remote context, guided by a short Q&A to draft its description', 'Use the Skill tool to invoke the `oprim-context-init` skill.'),
 };
 // ─── Poolside skill playbooks ─────────────────────────────────────────────────
 exports.POOLSIDE_SKILLS = {
@@ -1057,6 +1059,43 @@ Prepend the frontmatter block from step 5b, if one was prepared.
 ### 7. Report what was created
 `;
 }
+function contextInitSkill() {
+    return `---
+name: oprim-context-init
+description: Guide the user through drafting a description before declaring the current project a citable remote context
+---
+
+Declare the current project a citable remote context, with a clear description other projects and agents can use to decide whether to pull it.
+
+**Interactive prompts:** Use the **AskUserQuestion tool** for every question in this skill — do not write questions as plain text.
+
+## What this does
+
+A remote context is an oprim workspace (decisions, bets, specs) that other projects can reference read-only via \`oprim context register\`. Without a description, other projects have no cheap way to know what a remote context covers short of fully pulling it — so this skill exists to make sure one gets written.
+
+## Steps
+
+### 1. Check for an existing identity
+Check whether \`.oprim-context/context.yaml\` already exists in the current project. If it does, report that a remote context identity already exists (do not re-run the drafting flow below) and stop.
+
+### 2. Ask what this workspace covers
+Ask the user, one at a time:
+- "What does this project's oprim workspace cover? (e.g. product decisions, a specific domain, a team's specs)"
+- "Who is this meant for — which teams or projects would reference it?"
+
+If the user declines to answer either question, treat that as opting out of guided drafting — skip to step 4 with no description.
+
+### 3. Draft and confirm the description
+From the answers, draft a single-sentence description (aim for under 120 characters — this is what \`oprim context list\` will show other projects). Show the draft to the user and ask: "Use this description? (Enter to accept, or type a replacement)"
+
+### 4. Call oprim context init
+- If a description was drafted or accepted: use the Bash tool to run \`oprim context init --description "<final text>"\`.
+- If the user opted out in step 2: warn clearly that the resulting remote context will show as description-less in \`oprim context list\`, then use the Bash tool to run \`oprim context init\` with no \`--description\` flag.
+
+### 5. Report what was created
+Report the path (\`.oprim-context/context.yaml\`) and the description that was set (or the description-less warning, if opted out).
+`;
+}
 function specAuthoringSkill() {
     return `---
 name: oprim-spec

package/dist/lib/remote-context.d.ts

@@ -0,0 +1,50 @@
+export interface GitSource {
+    name: string;
+    git: string;
+    description?: string;
+}
+export interface PathSource {
+    name: string;
+    path: string;
+    description?: string;
+}
+export type RemoteContextSource = GitSource | PathSource;
+export interface RemoteContextConfig {
+    enabled: boolean;
+    sources: RemoteContextSource[];
+}
+export interface RemoteContextIdentity {
+    name: string;
+    version: string;
+    description?: string;
+}
+export declare function isGitSource(source: RemoteContextSource): source is GitSource;
+export declare function isPathSource(source: RemoteContextSource): source is PathSource;
+export declare function readRemoteContextConfig(projectRoot: string): RemoteContextConfig;
+export declare function writeRemoteContextConfig(projectRoot: string, config: RemoteContextConfig): void;
+export declare function findSourceByName(config: RemoteContextConfig, name: string): RemoteContextSource | undefined;
+export declare function identityFilePath(rootDir: string): string;
+export declare function readIdentity(rootDir: string): RemoteContextIdentity | null;
+export declare function writeIdentity(rootDir: string, identity: RemoteContextIdentity): void;
+export interface ResolvedIdentity {
+    identity: RemoteContextIdentity | null;
+    stale: boolean;
+    error?: string;
+    nameMismatch?: {
+        declared: string;
+        resolved: string;
+    };
+}
+export interface ResolvedContent {
+    workspaceRoot: string;
+    stale: boolean;
+    error?: string;
+    nameMismatch?: {
+        declared: string;
+        resolved: string;
+    };
+}
+export declare function resolveIdentityOnly(source: RemoteContextSource): ResolvedIdentity;
+export declare function hasEverFullyResolved(source: RemoteContextSource): boolean;
+export declare function resolveFull(source: RemoteContextSource): ResolvedContent;
+export declare function assembleOprimWorkspaceContent(workspaceRoot: string): string;

package/dist/lib/remote-context.js

@@ -0,0 +1,299 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGitSource = isGitSource;
+exports.isPathSource = isPathSource;
+exports.readRemoteContextConfig = readRemoteContextConfig;
+exports.writeRemoteContextConfig = writeRemoteContextConfig;
+exports.findSourceByName = findSourceByName;
+exports.identityFilePath = identityFilePath;
+exports.readIdentity = readIdentity;
+exports.writeIdentity = writeIdentity;
+exports.resolveIdentityOnly = resolveIdentityOnly;
+exports.hasEverFullyResolved = hasEverFullyResolved;
+exports.resolveFull = resolveFull;
+exports.assembleOprimWorkspaceContent = assembleOprimWorkspaceContent;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const crypto = __importStar(require("crypto"));
+const child_process_1 = require("child_process");
+const yaml = __importStar(require("js-yaml"));
+function isGitSource(source) {
+    return 'git' in source && typeof source.git === 'string';
+}
+function isPathSource(source) {
+    return 'path' in source && typeof source.path === 'string';
+}
+// ─── oprim/config.yaml — remote_context block ──────────────────────────────
+const REMOTE_CONTEXT_KEY = 'remote_context';
+function configPath(projectRoot) {
+    return path.join(projectRoot, 'oprim', 'config.yaml');
+}
+function readRemoteContextConfig(projectRoot) {
+    const p = configPath(projectRoot);
+    if (!fs.existsSync(p))
+        return { enabled: false, sources: [] };
+    const parsed = yaml.load(fs.readFileSync(p, 'utf-8'));
+    const raw = parsed?.[REMOTE_CONTEXT_KEY];
+    if (!raw)
+        return { enabled: false, sources: [] };
+    return {
+        enabled: raw.enabled ?? false,
+        sources: Array.isArray(raw.sources) ? raw.sources : [],
+    };
+}
+// Surgical replace of just the `remote_context:` top-level block, leaving every other
+// line in oprim/config.yaml byte-for-byte untouched — mirrors the non-destructive approach
+// in config-merge.ts (never parse+re-dump the whole file).
+function replaceTopLevelBlock(content, key, blockContent) {
+    const lines = content.split('\n');
+    const startIdx = lines.findIndex((l) => new RegExp(`^${key}:`).test(l));
+    const blockLines = blockContent.replace(/\n$/, '').split('\n');
+    if (startIdx === -1) {
+        const separator = content.endsWith('\n') || content === '' ? '' : '\n';
+        return content + separator + blockLines.join('\n') + '\n';
+    }
+    let endIdx = lines.length;
+    for (let i = startIdx + 1; i < lines.length; i++) {
+        if (/^[A-Za-z_]/.test(lines[i])) {
+            endIdx = i;
+            break;
+        }
+    }
+    return [...lines.slice(0, startIdx), ...blockLines, ...lines.slice(endIdx)].join('\n');
+}
+function writeRemoteContextConfig(projectRoot, config) {
+    const p = configPath(projectRoot);
+    const existing = fs.existsSync(p) ? fs.readFileSync(p, 'utf-8') : '';
+    const dumped = yaml.dump({ [REMOTE_CONTEXT_KEY]: config }, { lineWidth: -1 });
+    const updated = replaceTopLevelBlock(existing, REMOTE_CONTEXT_KEY, dumped);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, updated, 'utf-8');
+}
+function findSourceByName(config, name) {
+    return config.sources.find((s) => s.name === name);
+}
+// ─── Remote context identity (.oprim-context/context.yaml) ─────────────────
+function identityFilePath(rootDir) {
+    return path.join(rootDir, '.oprim-context', 'context.yaml');
+}
+function readIdentity(rootDir) {
+    const p = identityFilePath(rootDir);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const parsed = yaml.load(fs.readFileSync(p, 'utf-8'));
+        if (!parsed?.name || !parsed?.version)
+            return null;
+        return { name: parsed.name, version: parsed.version, description: parsed.description };
+    }
+    catch {
+        return null;
+    }
+}
+function writeIdentity(rootDir, identity) {
+    const p = identityFilePath(rootDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, yaml.dump(identity, { lineWidth: -1 }), 'utf-8');
+}
+// ─── Cache directory layout (git sources only) ─────────────────────────────
+// 5 minutes — see design.md open question. Overridable for tests that need to exercise
+// post-throttle-window behavior without actually waiting.
+function throttleMs() {
+    const override = process.env['OPRIM_REMOTE_CONTEXT_THROTTLE_MS'];
+    return override ? Number(override) : 5 * 60 * 1000;
+}
+// Overridable so tests never write into the real user's home directory.
+function cacheRoot() {
+    return process.env['OPRIM_REMOTE_CONTEXT_CACHE_DIR'] ?? path.join(os.homedir(), '.oprim', 'remote-context-cache');
+}
+function sourceCacheKey(source) {
+    const hash = crypto.createHash('sha1').update(source.git).digest('hex').slice(0, 12);
+    return `${source.name}-${hash}`;
+}
+function fullCacheDir(source) {
+    return path.join(cacheRoot(), sourceCacheKey(source), 'full');
+}
+function identityCacheDir(source) {
+    return path.join(cacheRoot(), sourceCacheKey(source), 'identity');
+}
+function markerPath(dir) {
+    return path.join(dir, '.oprim-last-fetch');
+}
+function isWithinThrottle(dir) {
+    const marker = markerPath(dir);
+    if (!fs.existsSync(marker))
+        return false;
+    const last = Number(fs.readFileSync(marker, 'utf-8').trim() || '0');
+    return Date.now() - last < throttleMs();
+}
+function touchMarker(dir) {
+    fs.writeFileSync(markerPath(dir), String(Date.now()), 'utf-8');
+}
+function git(args, cwd) {
+    (0, child_process_1.execFileSync)('git', args, { cwd, stdio: 'ignore' });
+}
+function withNameMismatch(source, identity) {
+    if (!identity)
+        return undefined;
+    if (identity.name === source.name)
+        return undefined;
+    return { declared: source.name, resolved: identity.name };
+}
+// ─── Git source resolution ─────────────────────────────────────────────────
+function ensureFullGitClone(source) {
+    const dir = fullCacheDir(source);
+    const exists = fs.existsSync(path.join(dir, '.git'));
+    if (exists && isWithinThrottle(dir)) {
+        return { dir, stale: false };
+    }
+    try {
+        if (!exists) {
+            fs.mkdirSync(path.dirname(dir), { recursive: true });
+            git(['clone', '--depth', '1', '--quiet', source.git, dir]);
+        }
+        else {
+            git(['fetch', '--depth', '1', '--quiet', 'origin', 'HEAD'], dir);
+            git(['reset', '--hard', '--quiet', 'FETCH_HEAD'], dir);
+        }
+        touchMarker(dir);
+        return { dir, stale: false };
+    }
+    catch (err) {
+        if (exists) {
+            // Last-known-good fallback — resolution degrades to stale rather than failing outright.
+            return { dir, stale: true };
+        }
+        return { dir, stale: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function ensureIdentityOnlyGitClone(source) {
+    const dir = identityCacheDir(source);
+    const exists = fs.existsSync(path.join(dir, '.git'));
+    if (exists && isWithinThrottle(dir)) {
+        return { dir };
+    }
+    try {
+        if (!exists) {
+            fs.mkdirSync(path.dirname(dir), { recursive: true });
+            // Partial clone (blob:none) + cone sparse-checkout scoped to .oprim-context/ — this is
+            // the "targeted single-file fetch" from design.md decision 5, implemented as an
+            // equivalent narrow fetch: git only downloads the one blob it needs to check out,
+            // not the whole workspace. `git archive --remote` was considered and rejected — GitHub
+            // and most managed git hosts disable the upload-archive service, so it isn't portable.
+            git(['clone', '--filter=blob:none', '--no-checkout', '--depth', '1', '--quiet', source.git, dir]);
+            git(['sparse-checkout', 'init', '--cone'], dir);
+            git(['sparse-checkout', 'set', '.oprim-context'], dir);
+            git(['checkout', '--quiet'], dir);
+        }
+        else {
+            git(['fetch', '--depth', '1', '--quiet', 'origin', 'HEAD'], dir);
+            git(['reset', '--hard', '--quiet', 'FETCH_HEAD'], dir);
+        }
+        touchMarker(dir);
+        return { dir };
+    }
+    catch (err) {
+        return { dir, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+function resolveIdentityOnly(source) {
+    if (isPathSource(source)) {
+        if (!fs.existsSync(source.path)) {
+            return { identity: null, stale: false, error: `path not found: ${source.path}` };
+        }
+        const identity = readIdentity(source.path);
+        return { identity, stale: false, nameMismatch: withNameMismatch(source, identity) };
+    }
+    const { dir, error } = ensureIdentityOnlyGitClone(source);
+    if (error)
+        return { identity: null, stale: false, error };
+    const identity = readIdentity(dir);
+    return { identity, stale: false, nameMismatch: withNameMismatch(source, identity) };
+}
+// Local-path sources are always read live (no persistent cache), so "has this ever been
+// resolved" is only a meaningful question for git sources, where full resolution populates
+// a durable cache directory that outlives any single command invocation.
+function hasEverFullyResolved(source) {
+    if (isPathSource(source))
+        return true;
+    return fs.existsSync(path.join(fullCacheDir(source), '.git'));
+}
+function resolveFull(source) {
+    if (isPathSource(source)) {
+        if (!fs.existsSync(source.path)) {
+            return { workspaceRoot: source.path, stale: false, error: `path not found: ${source.path}` };
+        }
+        const identity = readIdentity(source.path);
+        return {
+            workspaceRoot: source.path,
+            stale: false,
+            nameMismatch: withNameMismatch(source, identity),
+        };
+    }
+    const { dir, stale, error } = ensureFullGitClone(source);
+    if (error)
+        return { workspaceRoot: dir, stale: false, error };
+    const identity = readIdentity(dir);
+    return { workspaceRoot: dir, stale, nameMismatch: withNameMismatch(source, identity) };
+}
+// ─── Assembling oprim/ workspace content for printing ──────────────────────
+function walkTextFiles(dir, base, out) {
+    if (!fs.existsSync(dir))
+        return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        const rel = path.join(base, entry.name);
+        if (entry.isDirectory()) {
+            walkTextFiles(full, rel, out);
+        }
+        else if (entry.isFile() && /\.(md|yaml|yml)$/.test(entry.name)) {
+            out.push(rel);
+        }
+    }
+}
+function assembleOprimWorkspaceContent(workspaceRoot) {
+    const oprimDir = path.join(workspaceRoot, 'oprim');
+    const files = [];
+    walkTextFiles(oprimDir, 'oprim', files);
+    files.sort();
+    return files
+        .map((rel) => {
+        const content = fs.readFileSync(path.join(workspaceRoot, rel), 'utf-8');
+        return `─── ${rel} ───\n${content}`;
+    })
+        .join('\n\n');
+}

package/dist/lib/templates.js

@@ -31,8 +31,9 @@ sequencing:
     now: 2
 context: ""
 rules: {}
-store:
+remote_context:
   enabled: false
+  sources: []
 `;
 }
 // OKF (Open Knowledge Format) — https://github.com/GoogleCloudPlatform/okf

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-product-primer/cli",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Open Product Primer CLI — product decisions, sequencing, and KPI tracking for repositories",
   "keywords": [
     "product",