pmpt-cli 1.15.0 → 1.18.0

package/README.md

@@ -10,6 +10,8 @@
 
 Plan with 5 questions. Build with AI. Save every version. Share and reproduce.
 
+Every session, every decision, every constraint — accumulated in one file your AI can always read.
+
 [Quick Start](#quick-start) · [Commands](#commands) · [MCP Server](#mcp-server) · [Explore Projects](#explore-projects)
 
 </div>
@@ -65,6 +67,7 @@ pmpt explore
 | | Without pmpt | With pmpt |
 |---|---|---|
 | **Planning** | Stare at blank screen, write vague prompts | Answer 5 guided questions, get structured AI prompt |
+| **Context** | Re-explain the same decisions every AI session | AI reads pmpt.md and knows why things are the way they are |
 | **Tracking** | Lose track of what you built and how | Every version auto-saved with full history |
 | **Sharing** | Share finished code only | Share the entire journey — others can reproduce it |
 
@@ -92,8 +95,14 @@ The generated prompt is **automatically copied to your clipboard**. Just paste i
 
 | Command | Description |
 |---------|-------------|
-| `pmpt init` | Initialize project and start tracking |
+| `pmpt init` | Initialize project — sets up `.pmpt/`, selects AI tool, creates entry points |
+| `pmpt harness` | Add harness to existing project — missing pmpt.md sections + index.md + tool entry points |
 | `pmpt plan` | 5 questions → AI prompt (auto-copied to clipboard) |
+| `pmpt plan --template` | Generate a fillable `answers.json` (Windows/PowerShell friendly) |
+| `pmpt plan --answers-file <f>` | Run plan non-interactively from a JSON file |
+| `pmpt constraint add "<rule>"` | Add an architecture rule to pmpt.md |
+| `pmpt constraint list` | List all constraints |
+| `pmpt constraint remove <n>` | Remove a constraint by index |
 | `pmpt save` | Save current state as a snapshot |
 | `pmpt watch` | Auto-detect file changes and save versions |
 | `pmpt status` | Check project status, tracked files, and quality score |
@@ -213,18 +222,37 @@ All tools accept an optional `projectPath` parameter (defaults to cwd).
 
 ```
 your-project/
+├── CLAUDE.md              # Claude Code entry point → points to .pmpt/index.md
+├── .cursorrules           # Cursor entry point      → points to .pmpt/index.md
+├── AGENTS.md              # Codex entry point       → points to .pmpt/index.md
 └── .pmpt/
+    ├── index.md           # AI context map (entry point for all tools)
     ├── config.json        # Project configuration
-    ├── docs/              # Generated documents
+    ├── docs/
+    │   ├── pmpt.md        # Single source of truth — architecture, constraints,
+    │   │                  #   decisions, lessons, progress, snapshot log
     │   ├── plan.md        # Product plan (features checklist)
-    │   ├── pmpt.md        # Progress tracking & decisions
-    │   └── pmpt.ai.md     # AI-ready prompt (project context & instructions)
+    │   └── pmpt.ai.md     # AI-ready prompt (paste into your AI tool)
     └── .history/          # Auto-saved version history
         ├── v1-2024-02-20/
         ├── v2-2024-02-21/
         └── ...
 ```
 
+### pmpt.md — Single Source of Truth
+
+`pmpt.md` is the living document that your AI reads at the start of every session. It accumulates everything the AI needs to understand your project:
+
+| Section | What to record |
+|---------|---------------|
+| `## Architecture` | High-level structure — update as it evolves |
+| `## Active Work` | What's currently being built (clear when done) |
+| `## Decisions` | WHY, not just WHAT — include what led to each decision |
+| `## Constraints` | Platform/library limitations and workarounds |
+| `## Lessons` | Anti-patterns: what failed → root cause → fix applied |
+
+The more you fill this in, the less you re-explain to AI every session.
+
 ---
 
 ## .pmpt File Format

package/dist/commands/constraint.js

@@ -0,0 +1,92 @@
+import * as p from '@clack/prompts';
+import { resolve } from 'path';
+import { isInitialized } from '../lib/config.js';
+import { readConstraints, addConstraint, removeConstraint } from '../lib/harness.js';
+export async function cmdConstraint(action, options = {}) {
+    const projectPath = resolve(process.cwd());
+    if (!isInitialized(projectPath)) {
+        p.intro('pmpt constraint');
+        p.log.error('Project not initialized. Run `pmpt init` first.');
+        process.exit(1);
+    }
+    if (action === 'list') {
+        const constraints = readConstraints(projectPath);
+        p.intro('pmpt constraint list');
+        if (constraints.length === 0) {
+            p.log.info('No constraints defined yet.');
+            p.log.message(`  pmpt constraint add "<rule>"`);
+        }
+        else {
+            p.log.message('');
+            constraints.forEach((rule, i) => {
+                p.log.message(`  ${i + 1}. ${rule}`);
+            });
+            p.log.message('');
+            p.log.info(`${constraints.length} constraint(s) in .pmpt/docs/constraints.md`);
+        }
+        p.outro('');
+        return;
+    }
+    if (action === 'add') {
+        p.intro('pmpt constraint add');
+        let rule = options.rule;
+        if (!rule) {
+            const input = await p.text({
+                message: 'Enter constraint rule:',
+                placeholder: 'e.g., UI does not import Service directly',
+                validate: (v) => (!v ? 'Rule cannot be empty' : undefined),
+            });
+            if (p.isCancel(input)) {
+                p.cancel('Cancelled');
+                process.exit(0);
+            }
+            rule = input;
+        }
+        const ok = addConstraint(projectPath, rule);
+        if (!ok) {
+            p.log.error('Could not find ## Constraints section in .pmpt/docs/pmpt.md');
+            process.exit(1);
+        }
+        p.log.success(`Added: ${rule}`);
+        p.log.info('File: .pmpt/docs/pmpt.md');
+        p.outro('');
+        return;
+    }
+    if (action === 'remove') {
+        p.intro('pmpt constraint remove');
+        const constraints = readConstraints(projectPath);
+        if (constraints.length === 0) {
+            p.log.warn('No constraints to remove.');
+            p.outro('');
+            return;
+        }
+        let idx;
+        if (options.index) {
+            idx = parseInt(options.index, 10);
+        }
+        else {
+            // Interactive selection
+            const choice = await p.select({
+                message: 'Select constraint to remove:',
+                options: constraints.map((rule, i) => ({
+                    value: String(i + 1),
+                    label: `${i + 1}. ${rule}`,
+                })),
+            });
+            if (p.isCancel(choice)) {
+                p.cancel('Cancelled');
+                process.exit(0);
+            }
+            idx = parseInt(choice, 10);
+        }
+        const removed = removeConstraint(projectPath, idx);
+        if (removed === null) {
+            p.log.error(`No constraint at index ${idx}.`);
+        }
+        else {
+            p.log.success(`Removed: ${removed}`);
+        }
+        p.outro('');
+        return;
+    }
+}

package/dist/commands/harness.js

@@ -0,0 +1,59 @@
+import * as p from '@clack/prompts';
+import { resolve, basename } from 'path';
+import { isInitialized } from '../lib/config.js';
+import { addMissingSections, ensureIndexMd, ensureCursorRules, ensureAgentsMd, ensureClaudeMdRef, } from '../lib/harness.js';
+export async function cmdHarness(path) {
+    const projectPath = path ? resolve(path) : process.cwd();
+    const projectName = basename(projectPath);
+    p.intro('pmpt harness');
+    if (!isInitialized(projectPath)) {
+        p.log.error('Project not initialized. Run `pmpt init` first.');
+        process.exit(1);
+    }
+    // 1. Add missing sections to pmpt.md
+    const added = addMissingSections(projectPath);
+    if (added.length > 0) {
+        p.log.success(`Added to pmpt.md: ${added.join(', ')}`);
+    }
+    else {
+        p.log.info('pmpt.md already has all harness sections.');
+    }
+    // 2. Create .pmpt/index.md
+    ensureIndexMd(projectPath, projectName);
+    p.log.success('Created: .pmpt/index.md');
+    // 3. Ask which AI tool
+    const toolChoice = await p.select({
+        message: 'Which AI coding tool do you use?',
+        options: [
+            { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md → .pmpt/index.md' },
+            { value: 'cursor', label: 'Cursor', hint: '.cursorrules → .pmpt/index.md' },
+            { value: 'codex', label: 'Codex', hint: 'AGENTS.md → .pmpt/index.md' },
+            { value: 'all', label: 'All of the above' },
+            { value: 'skip', label: 'Skip' },
+        ],
+    });
+    if (p.isCancel(toolChoice) || toolChoice === 'skip') {
+        p.outro('Done. .pmpt/index.md created, pmpt.md updated.');
+        return;
+    }
+    const tool = toolChoice;
+    const created = [];
+    if (tool === 'claude' || tool === 'all') {
+        ensureClaudeMdRef(projectPath);
+        created.push('CLAUDE.md (updated)');
+    }
+    if (tool === 'cursor' || tool === 'all') {
+        ensureCursorRules(projectPath);
+        created.push('.cursorrules');
+    }
+    if (tool === 'codex' || tool === 'all') {
+        ensureAgentsMd(projectPath, projectName);
+        created.push('AGENTS.md');
+    }
+    if (created.length > 0) {
+        p.log.success(`Created: ${created.join(', ')}`);
+    }
+    p.log.message('');
+    p.log.info('AI tools will now read .pmpt/index.md → .pmpt/docs/pmpt.md at session start.');
+    p.outro('Harness ready.');
+}

package/dist/commands/init.js

@@ -7,6 +7,7 @@ import { cmdPlan } from './plan.js';
 import { scanProject, scanResultToAnswers } from '../lib/scanner.js';
 import { savePlanDocuments, initPlanProgress, savePlanProgress, generateAnswersTemplate } from '../lib/plan.js';
 import { copyToClipboard } from '../lib/clipboard.js';
+import { setupHarnessForTools } from '../lib/harness.js';
 export async function cmdInit(path, options) {
     p.intro('pmpt init');
     const projectPath = path ? resolve(path) : process.cwd();
@@ -100,14 +101,34 @@ export async function cmdInit(path, options) {
         // Add pmpt MCP instructions to CLAUDE.md and register .mcp.json for Claude Code
         ensurePmptClaudeMd(projectPath);
         ensureMcpJson(projectPath);
+        // Ask which AI tool to set up harness for
+        const toolChoice = await p.select({
+            message: 'Which AI coding tool do you use?',
+            options: [
+                { value: 'claude', label: 'Claude Code', hint: 'CLAUDE.md + .pmpt/index.md' },
+                { value: 'cursor', label: 'Cursor', hint: '.cursorrules + .pmpt/index.md' },
+                { value: 'codex', label: 'Codex', hint: 'AGENTS.md + .pmpt/index.md' },
+                { value: 'all', label: 'All of the above', hint: 'Create all entry points' },
+                { value: 'skip', label: 'Skip', hint: 'Set up later with `pmpt harness`' },
+            ],
+        });
+        if (p.isCancel(toolChoice)) {
+            p.cancel('Cancelled');
+            process.exit(0);
+        }
+        if (toolChoice !== 'skip') {
+            setupHarnessForTools(projectPath, basename(projectPath), toolChoice);
+        }
         // Build folder structure display
         const notes = [
             `Path: ${config.projectPath}`,
             '',
             'Folder structure:',
             `  .pmpt/`,
+            `  ├── index.md        AI entry point`,
             `  ├── config.json     Config`,
-            `  ├── docs/           Your docs`,
+            `  ├── docs/`,
+            `  │   └── pmpt.md     Source of truth (architecture, constraints, decisions)`,
             `  └── .history/       Snapshots`,
         ];
         if (config.repo) {
@@ -301,16 +322,25 @@ function ensureMinimalDocs(projectPath) {
     const skeleton = [
         `# ${name}`,
         '',
+        '## Architecture',
+        '<!-- High-level structure. Update as it evolves. -->',
+        '',
+        '## Active Work',
+        '<!-- What\'s currently being built. Clear when done, move to Snapshot Log. -->',
+        '',
         '## Progress',
         '- Project initialized',
         '',
         '## Snapshot Log',
         '',
         '## Decisions',
+        '<!-- WHY, not just WHAT. Format: - [Decision] → [Reason] -->',
         '',
         '## Constraints',
+        '<!-- Platform/library limitations. Format: - [Tool]: limitation → workaround -->',
         '',
         '## Lessons',
+        '<!-- Anti-patterns. Format: - [What failed] → [Root cause] → [Fix applied] -->',
         '',
     ].join('\n');
     writeFileSync(pmptMdPath, skeleton, 'utf-8');

package/dist/index.js

@@ -46,6 +46,8 @@ import { cmdDiff } from './commands/diff.js';
 import { cmdInternalSeed } from './commands/internal-seed.js';
 import { cmdMcpSetup } from './commands/mcp-setup.js';
 import { cmdDoctor } from './commands/doctor.js';
+import { cmdConstraint } from './commands/constraint.js';
+import { cmdHarness } from './commands/harness.js';
 import { trackCommand } from './lib/api.js';
 import { checkForUpdates } from './lib/update-check.js';
 import { createRequire } from 'module';
@@ -153,6 +155,27 @@ program
     ...options,
     template: options.template === true ? 'answers.json' : options.template,
 }));
+program
+    .command('harness [path]')
+    .description('Set up AI context harness for existing projects — adds missing pmpt.md sections and creates tool entry points')
+    .action(cmdHarness);
+program
+    .command('constraint <action>')
+    .description('Manage architecture constraints — add, list, or remove rules')
+    .option('-r, --rule <rule>', 'Rule text (for add)')
+    .option('-i, --index <n>', 'Rule index (for remove)')
+    .addHelpText('after', `
+  Actions:
+    add     Add a constraint rule
+    list    List all constraints
+    remove  Remove a constraint by index
+
+  Examples:
+    pmpt constraint add "UI does not import Service directly"
+    pmpt constraint list
+    pmpt constraint remove 2
+  `)
+    .action((action, options) => cmdConstraint(action, options));
 program
     .command('logout')
     .description('Clear saved GitHub authentication')

package/dist/lib/harness.js

@@ -0,0 +1,230 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { getConfigDir, getDocsDir } from './config.js';
+// ─── index.md — lightweight map pointing to pmpt.md ───────────────
+export function generateIndexMd(projectName) {
+    return `# ${projectName} — Project Context
+
+> AI entry point. Read this first, then follow the links below.
+
+## Map
+
+| File | Purpose |
+|------|---------|
+| [.pmpt/docs/pmpt.md](.pmpt/docs/pmpt.md) | **Source of truth** — architecture, constraints, decisions, progress |
+| [.pmpt/docs/pmpt.ai.md](.pmpt/docs/pmpt.ai.md) | Full AI prompt — paste into your AI tool to get started |
+
+## Rules for AI
+
+1. Read \`.pmpt/docs/pmpt.md\` before making any code changes
+2. Follow every rule listed in the **## Constraints** section of pmpt.md
+3. After milestones, call \`mcp__pmpt__pmpt_save\` (or \`pmpt save\` in terminal)
+4. Update pmpt.md when architecture, constraints, or features change
+`;
+}
+// ─── Tool-specific entry points ────────────────────────────────────
+export function generateCursorRules() {
+    return `# Project Rules
+
+See \`.pmpt/index.md\` for the project context map.
+
+The single source of truth is \`.pmpt/docs/pmpt.md\`.
+Always check the **## Constraints** section before making code changes.
+After completing milestones, run \`pmpt save\` in terminal.
+`;
+}
+export function generateAgentsMd(projectName) {
+    return `# ${projectName} — Agent Instructions
+
+See \`.pmpt/index.md\` for the project context map.
+
+The single source of truth is \`.pmpt/docs/pmpt.md\`.
+Always check the **## Constraints** section before making code changes.
+After completing milestones, run \`pmpt save\` in terminal.
+`;
+}
+// ─── Setup functions ───────────────────────────────────────────────
+export function ensureIndexMd(projectPath, projectName) {
+    const configDir = getConfigDir(projectPath);
+    mkdirSync(configDir, { recursive: true });
+    const indexPath = join(configDir, 'index.md');
+    if (!existsSync(indexPath)) {
+        writeFileSync(indexPath, generateIndexMd(projectName), 'utf-8');
+    }
+}
+export function ensureCursorRules(projectPath) {
+    const path = join(projectPath, '.cursorrules');
+    if (!existsSync(path)) {
+        writeFileSync(path, generateCursorRules(), 'utf-8');
+    }
+}
+export function ensureAgentsMd(projectPath, projectName) {
+    const path = join(projectPath, 'AGENTS.md');
+    if (!existsSync(path)) {
+        writeFileSync(path, generateAgentsMd(projectName), 'utf-8');
+    }
+}
+export function setupHarnessForTools(projectPath, projectName, tools) {
+    // index.md is always created — it's the lightweight map
+    ensureIndexMd(projectPath, projectName);
+    if (tools === 'cursor' || tools === 'all') {
+        ensureCursorRules(projectPath);
+    }
+    if (tools === 'codex' || tools === 'all') {
+        ensureAgentsMd(projectPath, projectName);
+    }
+    if (tools === 'claude' || tools === 'all') {
+        ensureClaudeMdIndexRef(projectPath);
+    }
+}
+export function ensureClaudeMdRef(projectPath) {
+    ensureClaudeMdIndexRef(projectPath);
+}
+function ensureClaudeMdIndexRef(projectPath) {
+    const claudeMdPath = join(projectPath, 'CLAUDE.md');
+    const marker = '<!-- pmpt-index -->';
+    const section = `${marker}\nSee \`.pmpt/index.md\` for project context. Single source of truth: \`.pmpt/docs/pmpt.md\`.\n<!-- /pmpt-index -->`;
+    if (!existsSync(claudeMdPath))
+        return;
+    const content = readFileSync(claudeMdPath, 'utf-8');
+    if (content.includes(marker))
+        return;
+    const pmptMarker = '<!-- pmpt -->';
+    if (content.includes(pmptMarker)) {
+        writeFileSync(claudeMdPath, content.replace(pmptMarker, section + '\n\n' + pmptMarker), 'utf-8');
+    }
+    else {
+        writeFileSync(claudeMdPath, section + '\n\n' + content, 'utf-8');
+    }
+}
+// ─── pmpt.md section migration ────────────────────────────────────
+const HARNESS_SECTIONS = [
+    {
+        heading: '## Architecture',
+        comment: '<!-- High-level structure. Update as it evolves. -->\n<!-- Example: "Next.js frontend → Cloudflare Workers API → D1 database" -->',
+    },
+    {
+        heading: '## Active Work',
+        comment: '<!-- What\'s currently being built. Clear when done, move to Snapshot Log. -->',
+    },
+    {
+        heading: '## Constraints',
+        comment: '<!-- Platform or library limitations discovered during development. -->\n<!-- Format: - [Platform/Tool]: what doesn\'t work → workaround used -->',
+    },
+    {
+        heading: '## Lessons',
+        comment: '<!-- Anti-patterns and "tried X, broke because Y" discoveries. -->\n<!-- Format: - [What failed] → [Root cause] → [Fix applied] -->',
+    },
+];
+/**
+ * Add missing harness sections to an existing pmpt.md.
+ * Returns list of section headings that were added.
+ */
+export function addMissingSections(projectPath) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return [];
+    let content = readFileSync(pmptMdPath, 'utf-8');
+    const added = [];
+    for (const section of HARNESS_SECTIONS) {
+        if (content.includes(section.heading))
+            continue;
+        // Insert before ## Decisions if it exists, otherwise append
+        const insertBefore = '## Decisions';
+        const block = `${section.heading}\n${section.comment}\n`;
+        if (content.includes(insertBefore)) {
+            content = content.replace(insertBefore, block + '\n' + insertBefore);
+        }
+        else {
+            content = content.trimEnd() + '\n\n' + block;
+        }
+        added.push(section.heading);
+    }
+    if (added.length > 0) {
+        writeFileSync(pmptMdPath, content, 'utf-8');
+    }
+    return added;
+}
+// ─── Constraint management — reads/writes pmpt.md ## Constraints ──
+export function readConstraints(projectPath) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return [];
+    const lines = readFileSync(pmptMdPath, 'utf-8').split('\n');
+    const inSection = { value: false };
+    const rules = [];
+    for (const line of lines) {
+        if (line.trim() === '## Constraints') {
+            inSection.value = true;
+            continue;
+        }
+        if (inSection.value && line.startsWith('## '))
+            break;
+        if (inSection.value && line.trimStart().startsWith('- ') && !line.includes('<!--')) {
+            rules.push(line.trimStart().slice(2).trim());
+        }
+    }
+    return rules;
+}
+export function addConstraint(projectPath, rule) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return false;
+    const lines = readFileSync(pmptMdPath, 'utf-8').split('\n');
+    let sectionEnd = -1;
+    let inSection = false;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim() === '## Constraints') {
+            inSection = true;
+            continue;
+        }
+        if (inSection && lines[i].startsWith('## ')) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    const newLine = `- ${rule}`;
+    if (sectionEnd !== -1) {
+        // Insert before next section, after any existing content
+        lines.splice(sectionEnd, 0, newLine);
+    }
+    else if (inSection) {
+        lines.push(newLine);
+    }
+    else {
+        return false;
+    }
+    writeFileSync(pmptMdPath, lines.join('\n'), 'utf-8');
+    return true;
+}
+export function removeConstraint(projectPath, index) {
+    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
+    if (!existsSync(pmptMdPath))
+        return null;
+    const lines = readFileSync(pmptMdPath, 'utf-8').split('\n');
+    let inSection = false;
+    let ruleCount = 0;
+    let removedRule = null;
+    const newLines = lines.filter((line) => {
+        if (line.trim() === '## Constraints') {
+            inSection = true;
+            return true;
+        }
+        if (inSection && line.startsWith('## ')) {
+            inSection = false;
+            return true;
+        }
+        if (inSection && line.trimStart().startsWith('- ') && !line.includes('<!--')) {
+            ruleCount++;
+            if (ruleCount === index) {
+                removedRule = line.trimStart().slice(2).trim();
+                return false;
+            }
+        }
+        return true;
+    });
+    if (removedRule === null)
+        return null;
+    writeFileSync(pmptMdPath, newLines.join('\n'), 'utf-8');
+    return removedRule;
+}

package/dist/lib/plan.js

@@ -118,17 +118,27 @@ After completing each feature above:
 
 ### What to Record in pmpt.md
 
-**## Decisions** — Record WHY, not just WHAT. Include the data or observation that led to the decision.
-- Bad: "Set minimum description length to 150 chars"
-- Good: "Set minimum description length to 150 chars (50-char threshold caused 60% low-quality entries)"
+pmpt.md is the **single source of truth** for this project. AI tools read it to understand context before every session. Keep it accurate.
 
-**## Constraints** — Record platform/library limitations discovered during development.
-- Examples: DB quirks, API limits, framework restrictions, version incompatibilities
-- Format: \`- [Platform]: what doesn't work → workaround used\`
+**## Architecture** — High-level structure. Update when the architecture changes.
+- Example: \`Next.js (SSG) → Cloudflare Workers API → D1 database\`
+- Include the WHY if the stack choice was non-obvious
 
-**## Lessons** — Record anti-patterns and "we tried X, it broke because Y" discoveries.
-- Examples: wrong deletion order causing FK errors, caching issues, race conditions
+**## Active Work** — What's currently being built. One or two items max.
+- Clear this section when done, then move to Snapshot Log
+- Example: \`- Implementing user auth (started 2025-03-17)\`
+
+**## Decisions** — Record WHY, not just WHAT. Include what led to the decision.
+- Bad: "Switched to SQLite"
+- Good: "Switched SQLite → Postgres: deploy target moved to serverless, needed connection pooling"
+
+**## Constraints** — Platform or library limitations discovered during development.
+- Format: \`- [Platform/Tool]: what doesn't work → workaround used\`
+- Example: \`- Cloudflare Workers: no native fs access → use KV for file storage\`
+
+**## Lessons** — Anti-patterns and "tried X, broke because Y" discoveries.
 - Format: \`- [What failed] → [Root cause] → [Fix applied]\`
+- Example: \`- JWT refresh on mobile broke → tokens expired before retry → added sliding expiry\`
 `;
 }
 // Generate human-facing project document (pmpt.md)
@@ -153,24 +163,38 @@ ${contextSection}
 ## Features
 ${features}
 ${techSection}
+## Architecture
+<!-- High-level structure. Update as it evolves. -->
+<!-- Example: "Next.js frontend → Express API → PostgreSQL" -->
+
+## Active Work
+<!-- What's currently being built. Clear when done, move to Snapshot Log. -->
+
 ## Progress
 - [ ] Project setup
 - [ ] Core features implementation
 - [ ] Testing & polish
 
 ## Snapshot Log
-### v1 - Initial Setup
+### v1 — Initial Setup
 - Project initialized with pmpt
 
 ## Decisions
+<!-- WHY, not just WHAT. Include what led to the decision. -->
+<!-- Format: - [Decision] → [Reason / data that led to it] -->
 
 ## Constraints
+<!-- Platform or library limitations discovered during development. -->
+<!-- Format: - [Platform/Tool]: what doesn't work → workaround used -->
 
 ## Lessons
+<!-- Anti-patterns and "tried X, broke because Y" discoveries. -->
+<!-- Format: - [What failed] → [Root cause] → [Fix applied] -->
 
 ---
-*This document tracks your project progress. Update it as you build.*
-*AI instructions are in \`pmpt.ai.md\` — paste that into your AI tool.*
+*This document is the single source of truth for this project.*
+*AI tools read this to understand context, constraints, and current state.*
+*AI instructions are in \`pmpt.ai.md\` — paste that into your AI tool to get started.*
 `;
 }
 // Generate plan document

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pmpt-cli",
-  "version": "1.15.0",
+  "version": "1.18.0",
   "description": "Record and share your AI-driven product development journey",
   "type": "module",
   "bin": {