@open-product-primer/cli 1.0.0 → 1.2.0

package/dist/commands/init.js

@@ -59,23 +59,43 @@ function initCommand() {
             console.log(chalk_1.default.green('✓') + ' OpenSpec detected');
         if (graphify.detected)
             console.log(chalk_1.default.green('✓') + ' Graphify detected');
+        console.log('');
+        const okfEnabled = await (0, install_agent_1.promptOkfFrontmatter)();
         const primerDir = path.join(projectRoot, 'oprim');
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'decisions'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'bets'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'reviews'));
+        (0, scaffold_1.ensureDir)(path.join(primerDir, 'notes'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'templates'));
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'scripts'));
-        const configWritten = (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'config.yaml'), (0, templates_1.configTemplate)(projectName, openspec.detected, graphify.detected));
+        const configWritten = (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'config.yaml'), (0, templates_1.configTemplate)(projectName, openspec.detected, graphify.detected, okfEnabled));
         const sequenceWritten = (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'sequence.yaml'), templates_1.sequenceTemplate);
-        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'pdr.md'), templates_1.pdrTemplate);
-        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'bet-decision.md'), templates_1.betDecisionTemplate);
+        const pdrContent = okfEnabled ? (0, templates_1.okfFrontmatter)('pdr', '<Decision title>') + templates_1.pdrTemplate : templates_1.pdrTemplate;
+        const betContent = okfEnabled
+            ? (0, templates_1.okfFrontmatter)('bet-decision', '<Bet title>') + templates_1.betDecisionTemplate
+            : templates_1.betDecisionTemplate;
+        const kpiContent = okfEnabled
+            ? (0, templates_1.okfFrontmatter)('kpi-review', 'KPI Review: BET-XXX') + templates_1.kpiReviewTemplate
+            : templates_1.kpiReviewTemplate;
+        // Notes always carry frontmatter — minimal tier by default, OKF tier (adds `description`)
+        // when opted in — unlike the other three templates, which have no frontmatter when disabled.
+        const noteContent = okfEnabled
+            ? (0, templates_1.okfFrontmatter)('note', '<Note title>') + templates_1.noteTemplate
+            : (0, templates_1.noteMinimalFrontmatter)('<Note title>') + templates_1.noteTemplate;
+        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'pdr.md'), pdrContent);
+        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'bet-decision.md'), betContent);
         (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'criteria.yaml'), templates_1.criteriaTemplate);
-        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'kpi-review.md'), templates_1.kpiReviewTemplate);
+        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'kpi-review.md'), kpiContent);
         (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'discovery.md'), templates_1.discoveryTemplate);
+        (0, scaffold_1.writeFile)(path.join(primerDir, 'templates', 'note.md'), noteContent);
         (0, scaffold_1.writeFile)(path.join(primerDir, 'scripts', 'generate-sequence-view.js'), templates_1.sequenceViewScriptTemplate);
+        if (okfEnabled) {
+            (0, scaffold_1.writeFile)(path.join(primerDir, 'index.md'), (0, templates_1.indexTemplate)(projectName));
+        }
         (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'decisions', '.gitkeep'), '');
         (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'bets', '.gitkeep'), '');
         (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'reviews', '.gitkeep'), '');
+        (0, scaffold_1.writeFileIfAbsent)(path.join(primerDir, 'notes', '.gitkeep'), '');
         console.log('\n' + chalk_1.default.green('✓') + ' oprim/ workspace created');
         const configStatus = configWritten ? 'written' : 'preserved (already exists)';
         const sequenceStatus = sequenceWritten ? 'written' : 'preserved (already exists)';
@@ -83,6 +103,7 @@ function initCommand() {
         console.log('  ' + chalk_1.default.gray('oprim/sequence.yaml') + ' — ' + sequenceStatus);
         console.log('  ' + chalk_1.default.gray('oprim/templates/') + ' — refreshed');
         console.log('  ' + chalk_1.default.gray('oprim/scripts/') + ' — refreshed');
+        console.log('  ' + chalk_1.default.gray('OKF frontmatter') + ' — ' + (okfEnabled ? 'enabled' : 'disabled'));
         // ── Agent selection ───────────────────────────────────────────────────────
         let selectedAgents;
         const flaggedAgents = opts.agent;

package/dist/commands/update.js

@@ -51,6 +51,10 @@ function updateCommand() {
         .action(async () => {
         const projectRoot = process.cwd();
         const configAgents = (0, detect_1.readAgentsFromConfig)(projectRoot);
+        // okf.enabled is persisted at init time; update reads it (no re-prompt) since
+        // already-scaffolded oprim/templates/*.md files are never rewritten here.
+        const okfEnabled = (0, detect_1.readOkfEnabledFromConfig)(projectRoot);
+        console.log(chalk_1.default.dim(`OKF frontmatter: ${okfEnabled ? 'enabled' : 'disabled'} (persisted from init)`));
         const primerDir = path.join(projectRoot, 'oprim');
         (0, scaffold_1.ensureDir)(path.join(primerDir, 'scripts'));
         (0, scaffold_1.writeFile)(path.join(primerDir, 'scripts', 'generate-sequence-view.js'), templates_1.sequenceViewScriptTemplate);

package/dist/lib/detect.d.ts

@@ -7,5 +7,6 @@ export declare function detectGraphify(projectRoot: string): {
     graphDir: string | null;
 };
 export declare function readAgentsFromConfig(projectRoot: string): string[] | null;
+export declare function readOkfEnabledFromConfig(projectRoot: string): boolean;
 export declare function detectAvailableAgents(projectRoot: string): string[];
 export declare function writeAgentsToConfig(agents: string[], projectRoot: string): void;

package/dist/lib/detect.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectOpenSpec = detectOpenSpec;
 exports.detectGraphify = detectGraphify;
 exports.readAgentsFromConfig = readAgentsFromConfig;
+exports.readOkfEnabledFromConfig = readOkfEnabledFromConfig;
 exports.detectAvailableAgents = detectAvailableAgents;
 exports.writeAgentsToConfig = writeAgentsToConfig;
 const fs = __importStar(require("fs"));
@@ -62,6 +63,15 @@ function readAgentsFromConfig(projectRoot) {
         return null;
     return agents;
 }
+function readOkfEnabledFromConfig(projectRoot) {
+    const configPath = path.join(projectRoot, 'oprim', 'config.yaml');
+    if (!fs.existsSync(configPath))
+        return false;
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const config = yaml.load(content);
+    const okf = config?.['okf'];
+    return Boolean(okf?.['enabled']);
+}
 function detectAvailableAgents(projectRoot) {
     const detected = [];
     if (fs.existsSync(path.join(projectRoot, '.claude')))

package/dist/lib/install-agent.d.ts

@@ -3,6 +3,7 @@ export declare const SUPPORTED_AGENTS: readonly Agent[];
 export declare function promptFrameworkSelection(projectRoot: string): Promise<string>;
 export declare function promptAgentSelection(projectRoot: string): Promise<string[]>;
 export declare function promptPdrSurfacing(): Promise<boolean>;
+export declare function promptOkfFrontmatter(): Promise<boolean>;
 export declare function installAgentSkills(agent: Agent, projectRoot: string, framework?: string, pdrSurfacing?: boolean): void;
 export declare const OPRIM_CONTEXT_SKILL_STEP = "## Step 0: Check relevant product decisions\nInvoke the `oprim:context` skill using the Skill tool. If matching PDRs are surfaced, review them before proceeding. If no PDRs match or `oprim/decisions/` is empty, the skill exits silently \u2014 continue to Step 1 immediately.";
 export declare const CLAUDE_SKILLS: Record<string, string>;

package/dist/lib/install-agent.js

@@ -40,6 +40,7 @@ exports.CURSOR_COMMANDS = exports.CURSOR_SKILLS = exports.POOLSIDE_SKILLS = expo
 exports.promptFrameworkSelection = promptFrameworkSelection;
 exports.promptAgentSelection = promptAgentSelection;
 exports.promptPdrSurfacing = promptPdrSurfacing;
+exports.promptOkfFrontmatter = promptOkfFrontmatter;
 exports.installAgentSkills = installAgentSkills;
 exports.writeAgentInstructionFile = writeAgentInstructionFile;
 exports.codexInstructions = codexInstructions;
@@ -96,6 +97,13 @@ async function promptPdrSurfacing() {
     const { confirm } = await Promise.resolve().then(() => __importStar(require('@inquirer/prompts')));
     return confirm({ message: 'Enable proactive PDR surfacing in skills? (y/N)', default: false });
 }
+async function promptOkfFrontmatter() {
+    const { confirm } = await Promise.resolve().then(() => __importStar(require('@inquirer/prompts')));
+    return confirm({
+        message: 'Enable OKF (Open Knowledge Format) frontmatter on scaffolded artifacts? (y/N)',
+        default: false,
+    });
+}
 function installAgentSkills(agent, projectRoot, framework = 'openspec', pdrSurfacing = false) {
     if (agent === 'claude') {
         const claudeDir = path.join(projectRoot, '.claude');
@@ -286,6 +294,7 @@ function removeContextStepFromFile(content) {
 exports.CLAUDE_SKILLS = {
     'oprim-pdr': pdrSkill(),
     'oprim-bet': betSkill(),
+    'oprim-note': noteSkill(),
     'oprim-criteria': criteriaSkill(),
     'oprim-review': reviewSkill(),
     'oprim-archive': archiveSkill(),
@@ -293,7 +302,7 @@ exports.CLAUDE_SKILLS = {
 };
 // ─── Claude command wrappers (thin, invoke skill) ────────────────────────────
 exports.CLAUDE_COMMANDS = {
-    'promote.md': claudeWrapper('OPRIM: Promote', 'Promote a prioritized bet to an OpenSpec change', promoteContent()),
+    'promote.md': claudeWrapper('OPRIM: Promote', 'Promote a note into a bet, or a prioritized bet into an OpenSpec change', 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()),
 };
@@ -301,6 +310,7 @@ exports.CLAUDE_COMMANDS = {
 exports.POOLSIDE_SKILLS = {
     'oprim-pdr': pdrSkill(),
     'oprim-bet': betSkill(),
+    'oprim-note': noteSkill(),
     'oprim-criteria': criteriaSkill(),
     'oprim-review': reviewSkill(),
     'oprim-archive': archiveSkill(),
@@ -310,15 +320,17 @@ exports.POOLSIDE_SKILLS = {
 exports.CURSOR_SKILLS = {
     'oprim-pdr': pdrSkill(),
     'oprim-bet': betSkill(),
+    'oprim-note': noteSkill(),
     'oprim-criteria': criteriaSkill(),
     'oprim-review': reviewSkill(),
 };
 // ─── Cursor command files (full inline — no Skill tool in Cursor) ────────────
 exports.CURSOR_COMMANDS = {
-    'oprim-promote.md': cursorWrapper('oprim-promote', 'Promote a prioritized bet to an OpenSpec change', promoteContent()),
+    'oprim-promote.md': cursorWrapper('oprim-promote', 'Promote a note into a bet, or a prioritized bet into an OpenSpec change', promoteContent()),
     'oprim-sequence.md': cursorWrapper('oprim-sequence', 'Validate and update the primer sequencing board', sequenceInlineContent()),
     'oprim-pdr.md': cursorWrapper('oprim-pdr', 'Create a new Product Decision Record with auto-assigned ID', pdrInlineContent()),
     'oprim-bet.md': cursorWrapper('oprim-bet', 'Create a new bet decision and register it on the sequencing board', betInlineContent()),
+    'oprim-note.md': cursorWrapper('oprim-note', 'Create a new atomic note for lightweight thinking capture', noteInlineContent()),
     'oprim-criteria.md': cursorWrapper('oprim-criteria', 'Create or append to a criteria.yaml contract for a bet', criteriaInlineContent()),
     'oprim-review.md': cursorWrapper('oprim-review', "Create a KPI review artifact pre-filled from a bet's criteria contract", reviewInlineContent()),
 };
@@ -372,7 +384,12 @@ Ask: Context (what forced this decision), Decision (clear statement), Alternativ
 ### 4. Check for supersession
 Ask: "Does this supersede an existing PDR? If so, which ID? (Enter to skip)"
 
+### 4b. Check for OKF frontmatter
+Read \`oprim/templates/pdr.md\`. If it begins with a YAML frontmatter block (\`---\` ... \`---\`), this workspace has OKF frontmatter enabled. Ask for a one-line description and comma-separated tags (subject-area keywords). Prepare a frontmatter block with \`type: pdr\`, \`title: <title>\`, \`description: <description>\`, \`tags: [<tags>]\`, \`timestamp: <today's date, ISO 8601>\`, to prepend in step 5.
+If no frontmatter block is found in the template, skip this step — write the file with no frontmatter, matching current behavior.
+
 ### 5. Write the PDR file
+Prepend the frontmatter block from step 4b, if one was prepared.
 \`\`\`
 # PDR-NNN: <title>
 
@@ -461,7 +478,12 @@ Then ask about each of the four risk dimensions (Low / Medium / High + short rat
 - "**Feasibility risk**: Can we build this with our current skills, time, and technology? (Low / Medium / High — and why?)"
 - "**Business viability risk**: Does this solution work for the business (revenue, legal, ops)? (Low / Medium / High — and why?)"
 
+### 4b. Check for OKF frontmatter
+Read \`oprim/templates/bet-decision.md\`. If it begins with a YAML frontmatter block (\`---\` ... \`---\`), this workspace has OKF frontmatter enabled. Ask for a one-line description and comma-separated tags (subject-area keywords). Prepare a frontmatter block with \`type: bet-decision\`, \`title: <title>\`, \`description: <description>\`, \`tags: [<tags>]\`, \`timestamp: <today's date, ISO 8601>\`, to prepend in step 5.
+If no frontmatter block is found in the template, skip this step — write the file with no frontmatter, matching current behavior.
+
 ### 5. Write oprim/bets/BET-NNN-<slug>/bet-decision.md
+Prepend the frontmatter block from step 4b, if one was prepared.
 \`\`\`
 # Decision: BET-NNN <title>
 <!-- Naming tip: verb + object [for context] — e.g. "Improve bet naming for scannability" not "Naming" -->
@@ -517,6 +539,75 @@ Ask: "Do you want to scaffold a discovery.md now? (y/N)"
 ### 8. Report what was created
 `;
 }
+function noteSkill() {
+    return `---
+name: oprim-note
+description: Create a new atomic note in oprim/notes/ for lightweight thinking capture, with tiered frontmatter and optional bet links
+---
+
+Create a new note in \`oprim/notes/\` for lightweight thinking capture — an observation, idea, or connection that hasn't yet earned a place in a bet or PDR.
+
+**Interactive prompts:** Use the **AskUserQuestion tool** for every question in this skill — do not write questions as plain text.
+
+## What you're creating
+
+A note is a small, disposable unit of thinking: an observation, a stray idea, or a connection between bets, captured before it's proven enough to belong in a discovery hypothesis or bet-decision. Notes carry no owner and no kill criterion — they're not commitments. Promote a note into a bet later with \`/oprim:promote NOTE-NNN\` once it's worth committing to.
+
+## Steps
+
+### 1. Get the note title
+If not provided, ask: "What is this note about? (a short title)"
+
+### 2. Assign the next NOTE ID
+Scan \`oprim/notes/\` for files matching \`NOTE-(\\d+)-\`. Extract the numeric part from each match. Assign max+1, zero-padded to 3 digits. Default \`001\` if none found.
+
+### 2b. Derive the slug
+From the note title: lowercase all characters, replace any character that is not a letter or digit with a hyphen, collapse consecutive hyphens to one, strip leading/trailing hyphens, truncate to 40 characters at the last hyphen boundary. This becomes \`<slug>\`.
+Output path: \`oprim/notes/NOTE-NNN-<slug>.md\`
+
+### 3. Gather the note body
+Ask: "What's the observation, idea, or connection?" (free-form prose — this becomes the note body).
+
+### 4. Gather tags
+Read \`oprim/config.yaml\`. If it has a \`notes:\` section with a \`tags:\` list, show it and ask the user to pick from it or add new ones. If \`notes.tags\` is absent or empty, ask for tags directly (comma-separated) — there's no vocabulary yet to constrain against.
+A tag not already in \`notes.tags\` SHALL be accepted, never rejected, and appended to \`oprim/config.yaml\`'s \`notes.tags\` list (creating the \`notes:\` section if absent) — the vocabulary grows from usage rather than requiring upfront authoring.
+
+### 5. Gather optional bet links
+Ask: "Does this relate to any existing bets? (comma-separated BET-IDs, or Enter to skip)"
+
+### 6. Check the frontmatter tier
+Read \`oprim/templates/note.md\`.
+- If it exists and its frontmatter block contains a \`description:\` field, this workspace is on the **OKF tier** — ask for a one-line description.
+- If it exists with no \`description:\` field, use the **minimal tier** — skip the description.
+- If the file doesn't exist (project initialized before notes were introduced), read \`oprim/config.yaml\` directly: \`okf.enabled: true\` → OKF tier (ask for a description); otherwise → minimal tier.
+
+### 7. Write oprim/notes/NOTE-NNN-<slug>.md
+
+Minimal tier:
+\`\`\`
+---
+type: note
+title: "<title>"
+tags: [<tags>]
+timestamp: <today, ISO 8601>
+---
+
+# Note: <title>
+
+<body>
+
+## Bets
+- <BET-IDs from step 5, or "None">
+\`\`\`
+
+OKF tier: same as above, with \`description: "<description>"\` inserted immediately after \`title\`.
+
+### 8. Link back from referenced bets
+For each BET-ID gathered in step 5: read \`oprim/bets/BET-NNN/bet-decision.md\`, and add \`- Notes: NOTE-NNN\` under its \`## Links\` section (append to an existing \`Notes:\` line, or add a new one).
+
+### 9. Report what was created
+`;
+}
 function criteriaSkill() {
     return `---
 name: oprim-criteria
@@ -820,7 +911,12 @@ Ask: reviewer name, decision quality notes.
 ### 5. Output path
 \`oprim/reviews/YYYY-MM-DD-BET-NNN-kpi.md\` (today's date)
 
+### 5b. Check for OKF frontmatter
+Read \`oprim/templates/kpi-review.md\`. If it begins with a YAML frontmatter block (\`---\` ... \`---\`), this workspace has OKF frontmatter enabled. Ask for a one-line description and comma-separated tags (derived from the reviewed bet's subject area). Prepare a frontmatter block with \`type: kpi-review\`, \`title: <bet ID and title>\`, \`description: <description>\`, \`tags: [<tags>]\`, \`timestamp: <review date, ISO 8601>\`, to prepend in step 6.
+If no frontmatter block is found in the template, skip this step — write the file with no frontmatter, matching current behavior.
+
 ### 6. Write the review file
+Prepend the frontmatter block from step 5b, if one was prepared.
 \`\`\`markdown
 # KPI Review: BET-NNN
 
@@ -851,6 +947,9 @@ function pdrInlineContent() {
 function betInlineContent() {
     return `Create a new bet in \`oprim/bets/\`. First explain: "A bet is a product decision you're committing to explore — a problem worth solving, a hypothesis worth testing, or a direction worth taking. You'll name it, explain why now, and set a kill criterion." Then show: "Naming tip: verb + object [for context] — Good: 'Improve bet naming for scannability' / Bad: 'Naming'". Scan \`BET-(\\d+)\` dirs for next ID (zero-padded, default 001). Check \`oprim/sequence.yaml\` exists (stop if not — advise oprim init). After receiving the title, validate: if fewer than 4 words OR fewer than 25 characters, warn "this title may be too vague", suggest a reformulation, and ask "Proceed anyway? (y/N)" — if "n", prompt for a revised title. Gather: decision (default Build now), owner, review date, why-now, alternatives, expected outcomes, kill criteria, PDR links. Write \`oprim/bets/BET-NNN/bet-decision.md\` with an inline naming tip comment in the header. Append entry to sequence.yaml backlog: \`{id, title, blocked_by: [], unlocks: [], requires_pdrs: []}\`. Then ask: "Do you want to scaffold a discovery.md now? (y/N)" — if "y", write \`oprim/bets/BET-NNN/discovery.md\` from the discovery template (sections: Problem Framing, User Research Signals, Competitive Context, Open Questions); if "n" or Enter, skip silently. Report what was created.`;
 }
+function noteInlineContent() {
+    return `Create a new note in \`oprim/notes/\` for lightweight thinking capture — an observation, idea, or connection that hasn't yet earned a place in a bet or PDR. Notes carry no owner or kill criterion; promote one into a bet later with \`/oprim:promote NOTE-NNN\`. Ask for a short title. Scan \`oprim/notes/NOTE-(\\d+)-\` for the next id (zero-padded, default 001). Ask for the note body (free-form), tags, and optional related BET-IDs. Tags are checked against \`oprim/config.yaml\`'s \`notes.tags\`; any new tag is accepted and appended to that list rather than rejected — the vocabulary grows from usage. Read \`oprim/templates/note.md\` — if its frontmatter has a \`description:\` field, this workspace is on the OKF tier and needs a one-line description; if it has no \`description:\` field, use the minimal tier; if the file doesn't exist, fall back to reading \`okf.enabled\` directly from \`oprim/config.yaml\`. Write \`oprim/notes/NOTE-NNN-<slug>.md\` with the correct frontmatter tier and a \`## Bets\` section listing any related BET-IDs. For each related bet, append \`- Notes: NOTE-NNN\` to that bet-decision's \`## Links\` section. Report what was created.`;
+}
 function criteriaInlineContent() {
     return `Add metrics to \`oprim/bets/BET-NNN/criteria.yaml\`. Verify bet dir exists. Gather: metric ID, name, baseline, target, timeframe, launch date, segment. Ask source type (amplitude or bigquery). Amplitude: event, aggregation, denominator_event. BigQuery: table, metric_column, filter, aggregation, denominator_query. If file exists: append to metrics list (never overwrite). If not: create. Ask if adding more metrics. Report what was created.`;
 }
@@ -1009,11 +1108,16 @@ function mergeClaudeSettingsHooks(claudeDir) {
 // ─── Legacy content (promote remains inline; sequence now delegates to skill) ─
 function promoteContent() {
     return `
-Promote a prioritized bet to an OpenSpec change and link criteria contracts.
+Promote an atomic note into a bet, or a prioritized bet into an OpenSpec change. The promotion path is determined solely by the prefix of the ID argument — there is no separate command for each.
 
-**Input**: Specify a bet ID (e.g., \`/oprim:promote BET-042\`) or omit to be prompted.
+**Input**: Specify an ID (e.g., \`/oprim:promote BET-042\` or \`/oprim:promote NOTE-005\`) or omit to be prompted.
 
-**Steps**
+### 0. Determine the promotion path from the ID prefix
+- \`BET-\` → **A. Bet → OpenSpec change**
+- \`NOTE-\` → **B. Note → Bet**
+- Anything else → report "Unrecognized ID prefix — expected BET- or NOTE-" and stop. Do not silently do nothing.
+
+## A. Bet → OpenSpec change
 
 1. **Locate the bet** — read \`oprim/bets/BET-XXX/bet-decision.md\`
 2. **Validate status** — decision must be "Build now"
@@ -1033,6 +1137,16 @@ Promote a prioritized bet to an OpenSpec change and link criteria contracts.
    - \`specs/<capability>/spec.md\` for each capability in \`## Capabilities\`
    If any artifact is missing, create it before reporting done.
 8. **Report** — show what was linked and what remains for engineering
+
+## B. Note → Bet
+
+1. **Locate the note** — read \`oprim/notes/NOTE-XXX-<slug>.md\`
+2. **Assign the next BET ID** — scan both \`oprim/bets/\` and \`oprim/bets/archived/\` for directories matching \`BET-(\\d+)(-[^/]*)?\`, max+1 zero-padded to 3 digits (default 001) — same convention \`oprim-bet\` uses
+3. **Derive the slug** from the note's title (lowercase, non-alphanumeric → hyphen, collapse/trim hyphens, truncate to 40 chars at a hyphen boundary)
+4. **Draft the bet** — write \`oprim/bets/BET-NNN-<slug>/bet-decision.md\` from the standard bet-decision structure, pre-filling only \`## Why now\` from the note's body. Leave \`Alternatives considered\`, \`Expected outcomes\`, and \`Kill criteria / rollback trigger\` as template placeholders — draft from the note, don't fabricate content it doesn't support. Ask for \`Owner\` and \`Review date\`; default \`Decision: Build now\` and \`Date\` to today.
+5. **Register the new bet** — append to \`oprim/sequence.yaml\` backlog: \`{id, title, blocked_by: [], unlocks: [], requires_pdrs: []}\`
+6. **Link back** — add \`Bets: BET-NNN\` to the note (creating or extending its \`## Bets\` section)
+7. **Report** — show the new bet's path and flag that \`Alternatives considered\`, \`Expected outcomes\`, and \`Kill criteria\` still need authoring before this bet can itself be promoted
 `;
 }
 function sequenceContent() {
@@ -1092,6 +1206,18 @@ Create a new bet in \`oprim/bets/\` and register it on the sequencing board.
 8. Ask: "Scaffold a discovery.md now? (y/N)" — if "y", write \`oprim/bets/BET-NNN/discovery.md\`.
 9. Report what was created.
 
+### Note authoring (oprim-note)
+Create a new note in \`oprim/notes/\` for lightweight thinking capture — not a bet, no owner or kill criterion.
+
+1. Ask for a short title.
+2. Assign next NOTE ID: scan \`oprim/notes/NOTE-(\\d+)-\`, max+1 zero-padded to 3 digits (default 001).
+3. Ask for the note body (free-form), tags, and optional related BET-IDs.
+4. Tags: check against \`oprim/config.yaml\`'s \`notes.tags\` — accept and append any new tag rather than rejecting it (the vocabulary grows from usage).
+5. Check \`oprim/templates/note.md\`: a \`description:\` field in its frontmatter means the OKF tier (gather a one-line description); no field means the minimal tier; if the file is missing, fall back to \`okf.enabled\` in \`oprim/config.yaml\`.
+6. Write \`oprim/notes/NOTE-NNN-<slug>.md\` with the correct frontmatter tier and a \`## Bets\` section.
+7. For each related bet, append \`- Notes: NOTE-NNN\` to that bet's \`## Links\` section.
+8. Report what was created.
+
 ### Criteria authoring (oprim-criteria)
 Create or append to \`oprim/bets/BET-NNN/criteria.yaml\`.
 

package/dist/lib/templates.d.ts

@@ -1,7 +1,11 @@
-export declare function configTemplate(projectName: string, openspecEnabled: boolean, graphifyEnabled: boolean): string;
+export declare function configTemplate(projectName: string, openspecEnabled: boolean, graphifyEnabled: boolean, okfEnabled: boolean): string;
+export declare function okfFrontmatter(type: string, titleHint: string): string;
+export declare function noteMinimalFrontmatter(titleHint: string): string;
+export declare function indexTemplate(projectName: string): string;
 export declare const sequenceTemplate = "wip_limits:\n  now: 2\n\nnow: []\nnext: []\nlater: []\nbacklog: []\n";
 export declare const pdrTemplate = "# PDR-XXX: <Decision title>\n\n## Status\nProposed | Accepted | Deprecated | Superseded by PDR-YYY\n\n## Context\n<What forced this decision?>\n\n## Decision\n<Clear statement of what is decided>\n\n## Alternatives considered\n- <Alternative A and why rejected>\n- <Alternative B and why rejected>\n\n## Consequences\n- Positive: <...>\n- Trade-offs: <...>\n- Follow-ups: <...>\n\n## Evidence\n- <Research link>\n- <Data link>\n\n## Related\n- Bets: <BET-IDs>\n- OpenSpec: <change paths>\n- Supersedes: <PDR-ID or none>\n";
 export declare const betDecisionTemplate = "# Decision: BET-XXX <Bet title>\n<!-- Naming tip: verb + object [for context] \u2014 e.g. \"Improve bet naming for scannability\" not \"Naming\" -->\n\n## Status\n- Decision: Build now | Defer | Kill\n- Date: YYYY-MM-DD\n- Owner: <name>\n- Review date: YYYY-MM-DD\n\n## Why now\n- <prioritization rationale>\n\n## Alternatives considered\n- <alternative + reason>\n\n## Expected outcomes\n- <metric: baseline -> target in timeframe>\n\n## Kill criteria / rollback trigger\n- <condition and action>\n\n## Links\n- PDRs: <PDR-IDs>\n- OpenSpec change: <path once promoted>\n";
+export declare const noteTemplate = "# Note: <Note title>\n\n<Capture the observation, idea, or connection while it's fresh.>\n\n## Bets\n- <BET-IDs this note relates to, or \"None\">\n";
 export declare const criteriaTemplate = "metrics:\n  - id: metric_id\n    name: \"Metric name\"\n    baseline: 0.00\n    target: 0.00\n    timeframe: \"30 days post-launch\"\n    launch_date: \"YYYY-MM-DD\"\n    source:\n      type: amplitude\n      definition:\n        event: event_name\n        aggregation: unique_users\n        denominator_event: null\n    segment: null\n";
 export declare const discoveryTemplate = "# Discovery: BET-XXX <Bet title>\n\n## Problem Framing\n- **Problem statement**: <What problem are we solving and for whom?>\n- **Evidence this is real**: <Data, support tickets, user quotes, etc.>\n- **Why it matters**: <Business or user impact if left unsolved>\n\n## User Research Signals\n- **Research conducted**: <Interviews, surveys, usability tests, etc.>\n- **Key findings**: <What did we learn?>\n- **Assumptions to validate**: <What are we still unsure about?>\n\n## Competitive Context\n- **How others solve this**: <Competitor or adjacent solutions>\n- **Our differentiation**: <Why our approach is better or different>\n- **Gaps / opportunities**: <What's underserved in the market?>\n\n## Open Questions\n- [ ] <Question 1 \u2014 what needs to be answered before committing?>\n- [ ] <Question 2>\n- [ ] <Question 3>\n";
 export declare const sequenceViewScriptTemplate = "#!/usr/bin/env node\n'use strict';\n\nconst fs = require('fs');\nconst path = require('path');\n\nconst SEQUENCE_PATH = path.join(process.cwd(), 'oprim/sequence.yaml');\nconst OUTPUT_PATH = path.join(process.cwd(), 'oprim/sequence-view.md');\nconst MAX_LABEL_LEN = 40;\n\nfunction parseSequenceYaml(text) {\n  const BUCKETS = ['now', 'next', 'later', 'backlog'];\n  const result = Object.fromEntries(BUCKETS.map(b => [b, []]));\n  let section = null, item = null, listField = null;\n\n  for (const raw of text.split('\\n')) {\n    const trimmed = raw.trim();\n    if (!trimmed || trimmed.startsWith('#')) continue;\n    const indent = raw.length - raw.trimStart().length;\n\n    if (indent === 0) {\n      const m = trimmed.match(/^(\\w+):/);\n      if (m) { section = BUCKETS.includes(m[1]) ? m[1] : null; item = null; listField = null; }\n      continue;\n    }\n\n    if (!section) continue;\n\n    if (indent === 2 && trimmed.startsWith('- ')) {\n      item = {}; result[section].push(item); listField = null;\n      const rest = trimmed.slice(2);\n      const m = rest.match(/^(\\w+):\\s*(.*)/);\n      if (m) item[m[1]] = m[2].replace(/^['\"]|['\"]$/g, '').trim();\n      continue;\n    }\n\n    if (indent === 4 && item) {\n      const m = trimmed.match(/^(\\w+):\\s*(.*)/);\n      if (!m) continue;\n      const [, key, val] = m;\n      const v = val.trim();\n      if (v === '[]') { item[key] = []; listField = null; }\n      else if (v === '') { item[key] = []; listField = key; }\n      else { item[key] = v.replace(/^['\"]|['\"]$/g, ''); listField = null; }\n      continue;\n    }\n\n    if (indent === 6 && item && listField && trimmed.startsWith('- ')) {\n      item[listField].push(trimmed.slice(2).trim());\n    }\n  }\n  return result;\n}\n\nfunction nodeId(betId) { return betId.replace(/-/g, ''); }\n\nfunction truncate(title) {\n  return title.length > MAX_LABEL_LEN ? title.slice(0, MAX_LABEL_LEN - 3) + '...' : title;\n}\n\nfunction generateMermaidBlock(seq) {\n  const lines = ['```mermaid', 'graph TD'];\n  const ACTIVE = [['now', 'Now'], ['next', 'Next'], ['later', 'Later']];\n\n  for (const [key, label] of ACTIVE) {\n    const bets = seq[key] || [];\n    if (!bets.length) continue;\n    lines.push('    subgraph ' + label);\n    for (const bet of bets) {\n      lines.push('        ' + nodeId(bet.id) + '[\"' + bet.id + ': ' + truncate(bet.title) + '\"]');\n    }\n    lines.push('    end');\n  }\n\n  for (const [key] of ACTIVE) {\n    for (const bet of (seq[key] || [])) {\n      for (const blocker of (bet.blocked_by || [])) {\n        lines.push('    ' + nodeId(bet.id) + ' --> ' + nodeId(blocker));\n      }\n    }\n  }\n\n  lines.push('```');\n  return lines.join('\\n');\n}\n\nfunction generateBacklogSection(seq) {\n  const backlog = seq.backlog || [];\n  if (!backlog.length) return '';\n  return '\\n\\n### Backlog\\n' + backlog.map(b => '- **' + b.id + '**: ' + b.title).join('\\n');\n}\n\nfunction main() {\n  const seq = parseSequenceYaml(fs.readFileSync(SEQUENCE_PATH, 'utf8'));\n  const header = [\n    '<!-- Auto-generated from oprim/sequence.yaml. Do not edit directly. -->',\n    '<!-- Regenerate by running: node oprim/scripts/generate-sequence-view.js -->',\n    '',\n    '# Sequencing Board',\n    '',\n    '',\n  ].join('\\n');\n  fs.writeFileSync(OUTPUT_PATH, header + generateMermaidBlock(seq) + generateBacklogSection(seq) + '\\n');\n  console.log('Written: oprim/sequence-view.md');\n}\n\nmain();\n";

package/dist/lib/templates.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.kpiReviewTemplate = exports.sequenceViewScriptTemplate = exports.discoveryTemplate = exports.criteriaTemplate = exports.betDecisionTemplate = exports.pdrTemplate = exports.sequenceTemplate = void 0;
+exports.kpiReviewTemplate = exports.sequenceViewScriptTemplate = exports.discoveryTemplate = exports.criteriaTemplate = exports.noteTemplate = exports.betDecisionTemplate = exports.pdrTemplate = exports.sequenceTemplate = void 0;
 exports.configTemplate = configTemplate;
-function configTemplate(projectName, openspecEnabled, graphifyEnabled) {
+exports.okfFrontmatter = okfFrontmatter;
+exports.noteMinimalFrontmatter = noteMinimalFrontmatter;
+exports.indexTemplate = indexTemplate;
+function configTemplate(projectName, openspecEnabled, graphifyEnabled, okfEnabled) {
     return `version: 1
 project:
   name: "${projectName}"
@@ -14,6 +17,8 @@ integrations:
   graphify:
     enabled: ${graphifyEnabled}
     graph_dir: graphify-out
+okf:
+  enabled: ${okfEnabled}
 measurement:
   amplitude:
     enabled: false
@@ -25,6 +30,41 @@ sequencing:
     now: 2
 `;
 }
+// OKF (Open Knowledge Format) — https://github.com/GoogleCloudPlatform/okf
+function okfFrontmatter(type, titleHint) {
+    return `---
+type: ${type}
+title: "${titleHint}"
+description: "<one-line summary>"
+tags: []
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+---
+
+`;
+}
+// Minimal frontmatter tier for notes — always on, independent of OKF opt-in.
+// Deliberately smaller than okfFrontmatter(): no `description` field.
+function noteMinimalFrontmatter(titleHint) {
+    return `---
+type: note
+title: "${titleHint}"
+tags: []
+timestamp: YYYY-MM-DDTHH:MM:SSZ
+---
+
+`;
+}
+function indexTemplate(projectName) {
+    return `${okfFrontmatter('index', `${projectName} — oprim workspace`)}# ${projectName} — oprim workspace
+
+OKF (Open Knowledge Format) bundle entrypoint for this oprim workspace.
+
+## Contents
+- [Bets](./bets/) — product bet decisions
+- [Decisions](./decisions/) — Product Decision Records (PDRs)
+- [Reviews](./reviews/) — KPI reviews
+`;
+}
 exports.sequenceTemplate = `wip_limits:
   now: 2
 
@@ -87,6 +127,13 @@ exports.betDecisionTemplate = `# Decision: BET-XXX <Bet title>
 - PDRs: <PDR-IDs>
 - OpenSpec change: <path once promoted>
 `;
+exports.noteTemplate = `# Note: <Note title>
+
+<Capture the observation, idea, or connection while it's fresh.>
+
+## Bets
+- <BET-IDs this note relates to, or "None">
+`;
 exports.criteriaTemplate = `metrics:
   - id: metric_id
     name: "Metric name"

package/package.json

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