pmpt-cli 1.8.3 → 1.9.1

package/dist/commands/clone.js

@@ -1,6 +1,6 @@
 import * as p from '@clack/prompts';
 import { join, dirname, resolve, sep } from 'path';
-import { existsSync, mkdirSync, writeFileSync, readdirSync } from 'fs';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, readdirSync } from 'fs';
 import { isInitialized, getConfigDir, getHistoryDir, getDocsDir, initializeProject } from '../lib/config.js';
 import { validatePmptFile, isSafeFilename } from '../lib/pmptFile.js';
 import { fetchPmptFile, trackClone } from '../lib/api.js';
@@ -110,6 +110,46 @@ export async function cmdClone(slug) {
     if (pmptData.docs) {
         restoreDocs(docsDir, pmptData.docs);
     }
+    // Write AI-facing clone guide to pmpt.ai.md
+    const author = pmptData.meta.author || 'unknown';
+    const projectName = pmptData.meta.projectName;
+    const cloneVersionCount = pmptData.history.length;
+    const versionGuide = pmptData.history.map((v) => {
+        const summary = v.summary || Object.keys(v.files).join(', ');
+        return `- v${v.version}: ${summary}`;
+    }).join('\n');
+    // Read original pmpt.ai.md if it exists (from the cloned project)
+    const aiMdPath = join(docsDir, 'pmpt.ai.md');
+    const originalAiMd = existsSync(aiMdPath) ? readFileSync(aiMdPath, 'utf-8') : '';
+    const cloneGuide = [
+        `<!-- This file is for AI tools only. Do not edit manually. -->`,
+        `<!-- Paste this into Claude Code, Codex, Cursor, or any AI coding tool. -->`,
+        '',
+        `# Cloned Project — Fresh Start`,
+        '',
+        `This project was cloned from **@${author}**'s project **"${projectName}"**.`,
+        `The original AI prompt below is for **reference only**. Do not execute it as-is.`,
+        '',
+        `## Context`,
+        '',
+        `- This is a new project. Use the original as inspiration, but build an independent product.`,
+        `- If the original prompt below contains checkboxes, those reflect the **original author's progress**, not this project's. Everything here starts from scratch.`,
+        `- The original evolved over ${cloneVersionCount} versions:`,
+        versionGuide,
+        '',
+        `## Instructions for AI`,
+        '',
+        `1. Read the original prompt below to understand the project's structure and approach.`,
+        `2. Reference the version history (v1→v${cloneVersionCount}) to follow a similar step-by-step evolution pattern.`,
+        `3. Start with core features (like v1) and incrementally add functionality.`,
+        `4. Write new pmpt.md and pmpt.ai.md for this project. Do not copy the original content verbatim.`,
+        `5. Update pmpt.md (human-facing) with progress tracking.`,
+        '',
+        '---',
+        '',
+        originalAiMd,
+    ].join('\n');
+    writeFileSync(aiMdPath, cloneGuide, 'utf-8');
     if (pmptData.plan) {
         writeFileSync(join(pmptDir, 'plan-progress.json'), JSON.stringify({
             completed: true,

package/dist/commands/diff.js

@@ -74,16 +74,23 @@ function printSummary(diffs) {
     p.log.info(`${pc.green(`+${additions}`)} additions, ${pc.red(`-${deletions}`)} deletions`);
 }
 export function cmdDiff(v1, v2, pathOrOptions, maybeOptions) {
-    // Commander passes args differently depending on how many positionals are given.
-    // pmpt diff v1 --file x       → (v1, options)
-    // pmpt diff v1 v2             → (v1, v2, options)
-    // pmpt diff v1 v2 /path       → (v1, v2, path, options)
+    // Commander passes args in order: pmpt diff v1 [v2] [path] [options]
+    // Smart parsing: if v2 looks like a path (not a version pattern), treat it as path.
     let v2Str;
     let path;
     let options = {};
+    const isVersion = (s) => /^v?\d+$/.test(s);
     if (typeof v2 === 'object') {
+        // pmpt diff v1 --file x → (v1, options)
         options = v2;
     }
+    else if (v2 !== undefined && !isVersion(v2)) {
+        // pmpt diff v1 /some/path → v2 is actually a path
+        path = v2;
+        if (typeof pathOrOptions === 'object') {
+            options = pathOrOptions;
+        }
+    }
     else {
         v2Str = v2;
         if (typeof pathOrOptions === 'object') {

package/dist/commands/plan.js

@@ -52,7 +52,11 @@ export async function cmdPlan(path, options) {
             const { existsSync } = await import('fs');
             const { join } = await import('path');
             const pmptDir = getPmptDir(projectPath);
-            const promptPath = join(pmptDir, 'pmpt.md');
+            // Prefer pmpt.ai.md, fall back to pmpt.md for older projects
+            let promptPath = join(pmptDir, 'pmpt.ai.md');
+            if (!existsSync(promptPath)) {
+                promptPath = join(pmptDir, 'pmpt.md');
+            }
             try {
                 if (existsSync(promptPath)) {
                     const content = readFileSync(promptPath, 'utf-8');
@@ -153,16 +157,22 @@ export async function cmdPlan(path, options) {
     p.log.message('');
     p.log.success('Two documents have been created:');
     p.log.message('');
+    const pmptMdPath = promptPath.replace('pmpt.ai.md', 'pmpt.md');
     const docExplanation = [
         `1. plan.md — Your product overview`,
         `   • Features checklist to track progress`,
         `   • Reference for you`,
         `   Location: ${planPath}`,
         '',
-        `2. pmpt.md — AI prompt (THE IMPORTANT ONE!)`,
+        `2. pmpt.md — Your project document`,
+        `   • Track progress, decisions, and milestones`,
+        `   • Human-readable — write in any language`,
+        `   Location: ${pmptMdPath}`,
+        '',
+        `3. pmpt.ai.md — AI prompt (THE IMPORTANT ONE!)`,
         `   • Copy this to Claude Code / Codex / Cursor`,
         `   • AI will help you build step by step`,
-        `   • AI will update this doc as you progress`,
+        `   • Always in English for best AI performance`,
         `   Location: ${promptPath}`,
     ];
     p.note(docExplanation.join('\n'), 'What are these files?');

package/dist/commands/publish.js

@@ -44,23 +44,23 @@ export async function cmdPublish(path, options) {
         p.outro('');
         return;
     }
-    // Validate pmpt.md exists and has content
-    const pmptMdPath = join(getDocsDir(projectPath), 'pmpt.md');
-    if (!existsSync(pmptMdPath)) {
-        p.log.error('pmpt.md not found. Run `pmpt plan` to generate it first.');
+    // Validate pmpt.ai.md exists and has content
+    const docsDir = getDocsDir(projectPath);
+    const aiMdPath = join(docsDir, 'pmpt.ai.md');
+    if (!existsSync(aiMdPath)) {
+        p.log.error('pmpt.ai.md not found. Run `pmpt plan` to generate it first.');
         process.exit(1);
     }
-    const pmptMdContent = readFileSync(pmptMdPath, 'utf-8').trim();
-    if (pmptMdContent.length === 0) {
-        p.log.error('pmpt.md is empty. Run `pmpt plan` to generate content.');
+    const aiMdContent = readFileSync(aiMdPath, 'utf-8').trim();
+    if (aiMdContent.length === 0) {
+        p.log.error('pmpt.ai.md is empty. Run `pmpt plan` to generate content.');
         process.exit(1);
     }
     // Quality gate
-    const docsDir = getDocsDir(projectPath);
     const trackedFiles = glob.sync('**/*.md', { cwd: docsDir });
     const hasGit = snapshots.some(s => !!s.git);
     const quality = computeQuality({
-        pmptMd: pmptMdContent,
+        pmptAiMd: aiMdContent,
         planAnswers: planProgress?.answers ?? null,
         versionCount: snapshots.length,
         docFiles: trackedFiles,

package/dist/commands/recover.js

@@ -14,14 +14,14 @@ export async function cmdRecover(path) {
     }
     p.intro('pmpt recover');
     const docsDir = getDocsDir(projectPath);
-    const pmptMdPath = join(docsDir, 'pmpt.md');
+    const aiMdPath = join(docsDir, 'pmpt.ai.md');
     const planMdPath = join(docsDir, 'plan.md');
     // Check current state
-    const currentExists = existsSync(pmptMdPath);
-    const currentContent = currentExists ? readFileSync(pmptMdPath, 'utf-8').trim() : '';
+    const currentExists = existsSync(aiMdPath);
+    const currentContent = currentExists ? readFileSync(aiMdPath, 'utf-8').trim() : '';
     if (currentExists && currentContent.length > 100) {
         const proceed = await p.confirm({
-            message: `pmpt.md exists (${currentContent.length} chars). Overwrite with recovered version?`,
+            message: `pmpt.ai.md exists (${currentContent.length} chars). Overwrite with recovered version?`,
             initialValue: false,
         });
         if (p.isCancel(proceed) || !proceed) {
@@ -59,24 +59,28 @@ export async function cmdRecover(path) {
             context.push('');
         }
     }
-    // 3. Last known good pmpt.md from history
+    // 3. Last known good pmpt.ai.md from history
     const snapshots = getAllSnapshots(projectPath);
-    let lastPmptMd = null;
-    let lastPmptVersion = 0;
+    let lastAiMd = null;
+    let lastAiMdVersion = 0;
     if (snapshots.length > 0) {
         for (let i = snapshots.length - 1; i >= 0; i--) {
-            const content = resolveFileContent(snapshots, i, 'pmpt.md');
+            // Try pmpt.ai.md first, fall back to pmpt.md for older projects
+            let content = resolveFileContent(snapshots, i, 'pmpt.ai.md');
+            if (!content || content.trim().length <= 50) {
+                content = resolveFileContent(snapshots, i, 'pmpt.md');
+            }
             if (content && content.trim().length > 50) {
-                lastPmptMd = content;
-                lastPmptVersion = snapshots[i].version;
+                lastAiMd = content;
+                lastAiMdVersion = snapshots[i].version;
                 break;
             }
         }
     }
-    if (lastPmptMd) {
-        context.push(`## Last Known pmpt.md (from v${lastPmptVersion})`);
+    if (lastAiMd) {
+        context.push(`## Last Known AI Prompt (from v${lastAiMdVersion})`);
         context.push('```markdown');
-        context.push(lastPmptMd);
+        context.push(lastAiMd);
         context.push('```');
         context.push('');
     }
@@ -119,18 +123,18 @@ export async function cmdRecover(path) {
         sources.push('plan answers');
     if (existsSync(planMdPath))
         sources.push('plan.md');
-    if (lastPmptMd)
-        sources.push(`history v${lastPmptVersion}`);
+    if (lastAiMd)
+        sources.push(`history v${lastAiMdVersion}`);
     if (existsSync(pkgPath))
         sources.push('package.json');
     p.log.info(`Found context: ${sources.join(', ')}`);
     // Build recovery prompt
     const projectName = planProgress?.answers?.projectName || basename(projectPath);
-    const prompt = `# pmpt.md Recovery Request
+    const prompt = `# pmpt.ai.md Recovery Request
 
-I need you to regenerate the \`.pmpt/docs/pmpt.md\` file for my project "${projectName}".
+I need you to regenerate the \`.pmpt/docs/pmpt.ai.md\` file for my project "${projectName}".
 
-This file is the main AI prompt document — it contains the product development context that gets pasted into AI tools (Claude Code, Codex, Cursor, etc.) to continue development.
+This file is the AI instruction document — it contains the product development context that gets pasted into AI tools (Claude Code, Codex, Cursor, etc.) to continue development. It is separate from \`pmpt.md\` which is the human-facing project document.
 
 ## Available Context
 
@@ -138,9 +142,12 @@ ${context.join('\n')}
 
 ## Instructions
 
-Based on the context above, regenerate \`.pmpt/docs/pmpt.md\` with the following structure:
+Based on the context above, regenerate \`.pmpt/docs/pmpt.ai.md\` with the following structure:
 
 \`\`\`
+<!-- This file is for AI tools only. Do not edit manually. -->
+<!-- Paste this into Claude Code, Codex, Cursor, or any AI coding tool. -->
+
 # {Project Name} — Product Development Request
 
 ## What I Want to Build
@@ -170,16 +177,16 @@ I'll confirm progress at each step before moving to the next.
 
 ## Documentation Rule
 
-**Important:** Update this document (located at \`.pmpt/docs/pmpt.md\`) at these moments:
+**Important:** When you make progress, update \`.pmpt/docs/pmpt.md\` (the human-facing project document) at these moments:
 - When architecture or tech decisions are finalized
 - When a feature is implemented (mark as done)
 - When a development phase is completed
 - When requirements change or new decisions are made
 \`\`\`
 
-${lastPmptMd ? 'Use the "Last Known pmpt.md" as the primary reference — update it rather than starting from scratch.' : 'Generate a fresh pmpt.md based on the available context.'}
+${lastAiMd ? 'Use the "Last Known AI Prompt" as the primary reference — update it rather than starting from scratch.' : 'Generate a fresh pmpt.ai.md based on the available context.'}
 
-Write the content directly to \`.pmpt/docs/pmpt.md\`. After writing, run \`pmpt save\` to create a snapshot.`;
+Write the content to \`.pmpt/docs/pmpt.ai.md\`. After writing, run \`pmpt save\` to create a snapshot.`;
     // Copy to clipboard
     const copied = copyToClipboard(prompt);
     if (copied) {
@@ -191,7 +198,7 @@ Write the content directly to \`.pmpt/docs/pmpt.md\`. After writing, run \`pmpt
     }
     p.note([
         '1. Paste the prompt into your AI tool (Claude Code, Cursor, etc.)',
-        '2. The AI will regenerate .pmpt/docs/pmpt.md',
+        '2. The AI will regenerate .pmpt/docs/pmpt.ai.md',
         '3. Run `pmpt save` to snapshot the recovered file',
     ].join('\n'), 'Next Steps');
     p.outro('');

package/dist/commands/status.js

@@ -37,12 +37,12 @@ export function cmdStatus(path) {
     p.note(notes.join('\n'), 'Project Info');
     // Quality Score
     const docsDir = getDocsDir(projectPath);
-    const pmptMdPath = join(docsDir, 'pmpt.md');
-    const pmptMd = existsSync(pmptMdPath) ? readFileSync(pmptMdPath, 'utf-8') : null;
+    const aiMdPath = join(docsDir, 'pmpt.ai.md');
+    const pmptAiMd = existsSync(aiMdPath) ? readFileSync(aiMdPath, 'utf-8') : null;
     const planProgress = getPlanProgress(projectPath);
     const hasGit = snapshots.some(s => !!s.git);
     const quality = computeQuality({
-        pmptMd,
+        pmptAiMd,
         planAnswers: planProgress?.answers ?? null,
         versionCount: snapshots.length,
         docFiles: tracked,

package/dist/lib/plan.js

@@ -41,7 +41,7 @@ export const PLAN_QUESTIONS = [
         required: false,
     },
 ];
-// Generate AI prompt (language-agnostic template)
+// Generate AI instruction file (pmpt.ai.md) — always English, AI-facing
 export function generateAIPrompt(answers) {
     // Parse features (support comma, semicolon, or newline separators)
     const features = answers.coreFeatures
@@ -56,7 +56,10 @@ export function generateAIPrompt(answers) {
     const techSection = answers.techStack
         ? `\n## Tech Stack Preferences\n${answers.techStack}\n`
         : '';
-    return `# ${answers.projectName} — Product Development Request
+    return `<!-- This file is for AI tools only. Do not edit manually. -->
+<!-- Paste this into Claude Code, Codex, Cursor, or any AI coding tool. -->
+
+# ${answers.projectName} — Product Development Request
 
 ## What I Want to Build
 ${answers.productIdea}
@@ -77,32 +80,50 @@ I'll confirm progress at each step before moving to the next.
 
 ## Documentation Rule
 
-**Important:** Update this document (located at \`.pmpt/docs/pmpt.md\`) at these moments:
+**Important:** When you make progress, update \`.pmpt/docs/pmpt.md\` (the human-facing project document) at these moments:
 - When architecture or tech decisions are finalized
 - When a feature is implemented (mark as done)
 - When a development phase is completed
 - When requirements change or new decisions are made
 
-Add a "## Progress" section below and keep it updated:
-\`\`\`
+Keep the Progress and Snapshot Log sections in pmpt.md up to date.
+After significant milestones, run \`pmpt save\` to create a snapshot.
+`;
+}
+// Generate human-facing project document (pmpt.md)
+export function generateHumanDoc(answers) {
+    const features = answers.coreFeatures
+        .split(/[,;\n]/)
+        .map((f) => f.trim())
+        .filter((f) => f)
+        .map((f) => `- [ ] ${f}`)
+        .join('\n');
+    const contextSection = answers.additionalContext
+        ? `\n## Additional Context\n${answers.additionalContext}\n`
+        : '';
+    const techSection = answers.techStack
+        ? `\n## Tech Stack\n${answers.techStack}\n`
+        : '';
+    return `# ${answers.projectName}
+
+## Product Idea
+${answers.productIdea}
+${contextSection}
+## Features
+${features}
+${techSection}
 ## Progress
-- [x] Completed item
-- [ ] Pending item
-\`\`\`
+- [ ] Project setup
+- [ ] Core features implementation
+- [ ] Testing & polish
 
-Also, add a "## Snapshot Log" section to record what was built at each checkpoint:
-\`\`\`
 ## Snapshot Log
 ### v1 - Initial Setup
-- Set up project structure
-- Installed dependencies: React, Tailwind
-
-### v2 - Auth Feature
-- Implemented login/signup
-- Added JWT authentication
-\`\`\`
+- Project initialized with pmpt
 
-This helps others understand what was built at each version when they import this project.
+---
+*This document tracks your project progress. Update it as you build.*
+*AI instructions are in \`pmpt.ai.md\` — paste that into your AI tool.*
 `;
 }
 // Generate plan document
@@ -166,8 +187,12 @@ export function savePlanDocuments(projectPath, answers) {
     const planPath = join(pmptDir, 'plan.md');
     const planContent = generatePlanDocument(answers);
     writeFileSync(planPath, planContent, 'utf-8');
-    // Save AI prompt to pmpt folder
-    const promptPath = join(pmptDir, 'pmpt.md');
+    // Save human-facing project document
+    const pmptMdPath = join(pmptDir, 'pmpt.md');
+    const pmptMdContent = generateHumanDoc(answers);
+    writeFileSync(pmptMdPath, pmptMdContent, 'utf-8');
+    // Save AI instruction file
+    const promptPath = join(pmptDir, 'pmpt.ai.md');
     const promptContent = generateAIPrompt(answers);
     writeFileSync(promptPath, promptContent, 'utf-8');
     // Create initial snapshot

package/dist/lib/pmptFile.js

@@ -130,8 +130,11 @@ const AI_GUIDE = [
     '- "plan" contains the original intent: what the creator wanted to build, key features, and tech preferences.',
     '- "history" is an ordered array of snapshots (v1, v2, v3...). Each snapshot captures every tracked file at that point in time.',
     '- To understand the evolution, compare files across versions sequentially. Look for what was added, removed, or rewritten between each version.',
-    '- "docs" contains the latest working documents (plan.md for the product plan, pmpt.md for the AI prompt used).',
-    '- "git" fields in each version link snapshots to source code commits, showing when code changes happened alongside document changes.',
+    '- "docs" contains the latest working documents:',
+    '  - plan.md: product plan overview',
+    '  - pmpt.md: human-facing project document (progress, decisions, milestones)',
+    '  - pmpt.ai.md: AI instruction file (paste into AI tools like Claude Code, Codex, Cursor)',
+    '- "git" fields in each version link snapshots to source code commits.',
     '',
     'Key insight: The value of this file is not just the final result — it is the journey. The sequence of iterations reveals how decisions were made, what was tried, and how the product evolved through AI-assisted development.',
 ].join('\n');

package/dist/lib/quality.js

@@ -5,11 +5,11 @@
 const MIN_PUBLISH_SCORE = 40;
 export function computeQuality(data) {
     const details = [];
-    // 1. pmpt.md content (30 points)
+    // 1. pmpt.ai.md content (30 points)
     {
         let score = 0;
         let tip;
-        const len = data.pmptMd?.trim().length ?? 0;
+        const len = data.pmptAiMd?.trim().length ?? 0;
         if (len > 0)
             score += 10;
         if (len >= 200)
@@ -18,10 +18,10 @@ export function computeQuality(data) {
             score += 10;
         if (score < 30) {
             tip = len === 0
-                ? 'Run `pmpt plan` to generate pmpt.md'
-                : `pmpt.md is ${len} chars — expand to 500+ for full score`;
+                ? 'Run `pmpt plan` to generate pmpt.ai.md'
+                : `pmpt.ai.md is ${len} chars — expand to 500+ for full score`;
         }
-        details.push({ label: 'pmpt.md content', score, maxScore: 30, tip });
+        details.push({ label: 'AI prompt', score, maxScore: 30, tip });
     }
     // 2. Plan completeness (25 points)
     {
@@ -66,7 +66,7 @@ export function computeQuality(data) {
         let tip;
         if (data.docFiles.includes('plan.md'))
             score += 5;
-        if (data.docFiles.includes('pmpt.md'))
+        if (data.docFiles.includes('pmpt.ai.md'))
             score += 5;
         if (data.docFiles.length > 2)
             score += 5;
@@ -74,8 +74,8 @@ export function computeQuality(data) {
             const missing = [];
             if (!data.docFiles.includes('plan.md'))
                 missing.push('plan.md');
-            if (!data.docFiles.includes('pmpt.md'))
-                missing.push('pmpt.md');
+            if (!data.docFiles.includes('pmpt.ai.md'))
+                missing.push('pmpt.ai.md');
             if (data.docFiles.length <= 2)
                 missing.push('additional docs');
             tip = `Add: ${missing.join(', ')}`;

package/package.json

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