@shiplens/cli 1.4.4 → 1.4.6

package/lib/assets/actions.json

@@ -649,9 +649,9 @@
       "title": "Shiplens CLI One-Click Setup & Analytics Initialization",
       "suffix": "None",
       "category": "Initial Setup",
-      "prompt": "Set up Shiplens analytics: extract project description, install SDK, create the project, and retrieve the live dashboard URL.",
+      "prompt": "Set up Shiplens analytics: install SDK, create the project, and retrieve the live dashboard URL.",
       "steps": [
-        "1. Run CLI initialization command:\n- Windows: npx.cmd --yes @shiplens/cli init\n- macOS/Linux: npx --yes @shiplens/cli init",
+        "1. Run CLI initialization command:\n- Windows: npx.cmd --yes @shiplens/cli init --json\n- macOS/Linux: npx --yes @shiplens/cli init --json",
         "2. Present the standard project & dashboard summary (including: Project Name, App ID, Code Injection file, User Account Status, Live Dashboard / Activation URL);",
         "3. Immediately prompt the user for their email address (informing them that you will register on their behalf and Shiplens will send an activation email for 50,000 monthly free events and project binding);",
         "4. Upon receiving the user's email, run: npx.cmd --yes @shiplens/cli auth bind --email <email> --json."
@@ -660,12 +660,27 @@
       "foundation": "",
       "source": ""
     },
+    {
+      "id": "setup_bind_project",
+      "title": "Use Shiplens CLI to Install Analytics SDK & Link to Existing Account",
+      "suffix": "None",
+      "category": "Initial Setup",
+      "prompt": "Use Shiplens CLI to install the analytics SDK in this new project and link it to the user's existing Shiplens account:",
+      "steps": [
+        "1. Run the project setup & initialization command:\n- Windows: npx.cmd --yes @shiplens/cli init --json\n- macOS/Linux: npx --yes @shiplens/cli init --json",
+        "2. Inspect returned `user_account_status` and credential states:\n- [Branch A: Logged in & linked] (`logged_in_linked`):\n- [Branch B: No local credentials detected] (`not_logged_in_unlinked` or `activation_required=true`):\n- [Branch C: Account quota / project limit reached] (Error `QUOTA_EXCEEDED` / `PLAN_LIMIT` / unable to link):",
+        "3. Output the final project summary and dashboard link, confirming the project is ready for analytics queries."
+      ],
+      "commands": [],
+      "foundation": "",
+      "source": ""
+    },
     {
       "id": "remove_sdk",
-      "title": "Remove Shiplens SDK & Analytics Data",
+      "title": "Delete Shiplens Project Analytics Data & SDK (No Longer Needed)",
       "suffix": "None",
       "category": "Initial Setup",
-      "prompt": "Remove Shiplens SDK integration and analytics data:",
+      "prompt": "Delete Shiplens project analytics data and SDK integration (analytics no longer needed):",
       "steps": [
         "1. Read `.shiplens.json` in the project root to get project name, app_id, and instrumented file paths.",
         "2. Clearly display the project name and app_id to be deleted, warn the user that historical events and hosted data will be permanently purged, and pause for explicit user confirmation (\"Confirm deleting this project\").",
@@ -678,7 +693,7 @@
     },
     {
       "id": "uninstall_cli",
-      "title": "Uninstall Shiplens CLI",
+      "title": "Delete Shiplens CLI and Restore Project",
       "suffix": "None",
       "category": "Initial Setup",
       "prompt": "Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the above requirements. - Windows: npm.cmd uninstall -g @shiplens/cli - macOS/Linux: npm uninstall -g @shiplens/cli",
@@ -689,10 +704,10 @@
     },
     {
       "id": "generate_context",
-      "title": "Generate Context Descriptions for All Pages and Buttons",
+      "title": "Use Shiplens CLI to Generate Context Descriptions for All Pages and Buttons",
       "suffix": "None",
       "category": "Initial Setup",
-      "prompt": "Map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can map numbers and IDs to concrete functionality:",
+      "prompt": "Use Shiplens CLI to map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can understand the business context behind each metric:",
       "steps": [
         "1. Check `./.shiplens.json` for current app_id and project name.",
         "2. Inspect frontend code and routes to extract feature descriptions, user-facing copy, and button texts, locations, and actions.",

package/lib/cli.js

@@ -16,7 +16,7 @@ const { handleContext } = require('./commands/context');
 const { handleMcp } = require('./commands/mcp');
 const { handleAction } = require('./commands/action');
 
-let VERSION = '1.4.4';
+let VERSION = '1.4.6';
 try {
   const pkg = require('../package.json');
   if (pkg.version) VERSION = pkg.version;
@@ -90,7 +90,7 @@ Core Commands:
   heatmap       Retrieve click heatmaps and skeleton wireframes
   dashboards    AI dashboard management and one-click creation (list, create [--ai])
   doctor        Run full end-to-end diagnostics on SDK, credentials, and network
-  context       Manage business context dictionary (push, pull, show)
+  context       Manage business context dictionary (generate, push, pull, show)
   action        Retrieve deterministic steps, commands, and theory for analysis actions (list, <action_id>)
   mcp serve     Run local MCP proxy server with device credentials
 

package/lib/commands/context.js

@@ -1,6 +1,7 @@
 const fs = require('fs');
 const path = require('path');
 const { getLocalConfig } = require('../config');
+const { generateProjectContext } = require('../context-generator');
 
 /**
  * Get standard storage path for business context: .shiplens/contexts/<app_id>.md
@@ -37,7 +38,7 @@ async function executeWithSafeFallback(fn, maxRetries = 2, baseMs = 500) {
 }
 
 /**
- * Handle context command (push, pull, show)
+ * Handle context command (generate, push, pull, show)
  */
 async function handleContext(subcommand, args, flags, ctx) {
   const targetSub = subcommand || 'show';
@@ -47,6 +48,23 @@ async function handleContext(subcommand, args, flags, ctx) {
   const projectName = flags.name || localCfg.project_name || '';
 
   switch (targetSub) {
+    case 'generate':
+    case 'scan':
+    case 'extract': {
+      const genResult = generateProjectContext(process.cwd(), appId, projectName, flags.framework || localCfg.framework);
+      ctx.output({
+        ok: true,
+        action: 'generate',
+        app_id: appId,
+        file: genResult.filePath,
+        rel_file: genResult.relPath,
+        pages_count: genResult.totalPages,
+        buttons_count: genResult.totalButtons,
+        message: `Project business context scanned and saved to ${genResult.relPath} (${genResult.totalPages} pages, ${genResult.totalButtons} buttons).`,
+      });
+      break;
+    }
+
     case 'push': {
       if (!fs.existsSync(filePath)) {
         const displayPath = path.relative(process.cwd(), filePath) || filePath;
@@ -173,7 +191,7 @@ async function handleContext(subcommand, args, flags, ctx) {
     }
 
     default:
-      throw new Error(`Unknown context subcommand: ${targetSub}. Supported: push, pull, show`);
+      throw new Error(`Unknown context subcommand: ${targetSub}. Supported: generate, push, pull, show`);
   }
 }
 

package/lib/commands/init.js

@@ -3,6 +3,7 @@ const { detectProject, detectExistingApp, injectSDK, injectSkill, installSDKDepe
 const { saveLocalConfig } = require('../config');
 const { saveDeviceEnv } = require('../device-env');
 const { resolveTaxonomyFromIDs, formatTaxonomySummary } = require('../taxonomy');
+const { generateProjectContext } = require('../context-generator');
 
 async function handleInit(args, flags, ctx) {
   const start = Date.now();
@@ -30,49 +31,29 @@ async function handleInit(args, flags, ctx) {
 
   // 1. Safety check for existing project configuration
   const existing = detectExistingApp(wd);
+  let isReusedExisting = false;
+
   if (existing.has_existing && !flags.force) {
-    if (ctx.isJSON) {
-      const result = {
-        ok: false,
-        code: 'PROJECT_EXISTS_LOCALLY',
-        message: `Existing Shiplens configuration detected (App ID: ${existing.app_id}) in ${existing.source_file}. ` +
-          `Option 1 [Recommended]: Keep existing statistics and project ID. ` +
-          `Option 2: Use --force to overwrite and request a new App ID from cloud (Note: Old dashboard stops receiving new data).`,
-        existing_app_id: existing.app_id,
-        source_file: existing.source_file,
-        project_name: existing.project_name || projectName,
-        dashboard_url: `${ctx.client.baseURL}/dashboard/${existing.app_id}`,
-      };
-      ctx.output(result);
-      process.exitCode = 1;
-      return;
-    } else if (!process.stdin.isTTY) {
-      console.log(`\n⚠️  Existing Shiplens project detected!`);
-      console.log(`📌 App ID: ${existing.app_id} (Source: ${existing.source_file})`);
-      console.log(`📊 Dashboard: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
-      console.log(`🛑 Non-interactive terminal detected (CI/Agent). Existing configuration preserved.`);
-      console.log(`💡 Option 1 [Recommended]: Keep existing setup, retain App ID and historical statistics;`);
-      console.log(`💡 Option 2: Overwrite with --force to create a new project:`);
-      console.log(`   npx.cmd --yes @shiplens/cli init --force\n`);
-      return;
+    if (ctx.isJSON || !process.stdin.isTTY) {
+      // Non-interactive or JSON mode (Agent/CI): Fast-forward / Idempotent reuse of existing config
+      isReusedExisting = true;
     } else {
       console.log(`\n⚠️  Existing Shiplens project detected!`);
       console.log(`📌 App ID: ${existing.app_id} (Source: ${existing.source_file})`);
       console.log(`📊 Dashboard: ${ctx.client.baseURL}/dashboard/${existing.app_id}`);
-      console.log(`\n💡 Option 1 [Recommended]: Keep existing setup, retain App ID and historical statistics;`);
-      console.log(`💡 Option 2: Overwrite with --force to request a brand new App ID from cloud (Note: Old dashboard stops receiving new data, old and new data cannot be merged):`);
+      console.log(`\n💡 Option 1 [Recommended]: Keep existing setup, retain App ID and historical statistics (Press Enter or N);`);
+      console.log(`💡 Option 2: Overwrite with --force to request a brand new App ID from cloud (y):`);
       console.log(`   npx.cmd --yes @shiplens/cli init --force\n`);
 
       const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
       const confirmed = await new Promise((resolve) => {
-        rl.question('Overwrite and create a new project? (y/N): ', (ans) => {
+        rl.question('Overwrite and create a brand new project? (y/N): ', (ans) => {
           rl.close();
           resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
         });
       });
       if (!confirmed) {
-        console.log('🛑 Operation cancelled. Existing configuration preserved.');
-        return;
+        isReusedExisting = true;
       }
     }
   }
@@ -80,40 +61,52 @@ async function handleInit(args, flags, ctx) {
   // 2. Inject AI Skill (.agents/skills/shiplens/SKILL.md & Agent rules)
   const skillFile = injectSkill(wd);
 
-  // 3. Register project on cloud
+  // 3. Register project on cloud (or reuse existing)
   let appId = '';
   let dashboardUrl = '';
   let accountStatus = 'not_logged_in_unlinked';
   let accountStatusText = 'Not Logged In (Default state after first installation or no valid local credentials)';
 
-  try {
-    const connResp = await ctx.client.connect({
-      project_name: projectName,
-      description,
-      industry,
-      genre_id: genreId,
-      subgenre_id: subgenreId,
-      feature_tags: featureTagIds.join(','),
-      platform: framework,
-    });
-    appId = connResp.app_id;
-    dashboardUrl = connResp.dashboard_url || `${ctx.client.baseURL}/dashboard/${appId}`;
-
+  if (isReusedExisting) {
+    appId = existing.app_id;
+    dashboardUrl = `${ctx.client.baseURL}/dashboard/${appId}`;
     if (ctx.resolvedAuth && ctx.resolvedAuth.is_present) {
-      if (connResp.account_linked !== false && connResp.linked !== false && !connResp.unlinked) {
-        accountStatus = 'logged_in_linked';
-        accountStatusText = 'Logged In (Project linked to account)';
-      } else {
-        accountStatus = 'logged_in_unlinked';
-        accountStatusText = 'Logged In (Project not linked to account)';
-      }
+      accountStatus = 'logged_in_linked';
+      accountStatusText = 'Logged In (Project linked to account)';
     } else {
       accountStatus = 'not_logged_in_unlinked';
       accountStatusText = 'Not Logged In (Default state after first installation or no valid local credentials)';
     }
-  } catch (netErr) {
-    netErr.code = netErr.code || 'CONNECT_FAILED';
-    throw netErr;
+  } else {
+    try {
+      const connResp = await ctx.client.connect({
+        project_name: projectName,
+        description,
+        industry,
+        genre_id: genreId,
+        subgenre_id: subgenreId,
+        feature_tags: featureTagIds.join(','),
+        platform: framework,
+      });
+      appId = connResp.app_id;
+      dashboardUrl = connResp.dashboard_url || `${ctx.client.baseURL}/dashboard/${appId}`;
+
+      if (ctx.resolvedAuth && ctx.resolvedAuth.is_present) {
+        if (connResp.account_linked !== false && connResp.linked !== false && !connResp.unlinked) {
+          accountStatus = 'logged_in_linked';
+          accountStatusText = 'Logged In (Project linked to account)';
+        } else {
+          accountStatus = 'logged_in_unlinked';
+          accountStatusText = 'Logged In (Project not linked to account)';
+        }
+      } else {
+        accountStatus = 'not_logged_in_unlinked';
+        accountStatusText = 'Not Logged In (Default state after first installation or no valid local credentials)';
+      }
+    } catch (netErr) {
+      netErr.code = netErr.code || 'CONNECT_FAILED';
+      throw netErr;
+    }
   }
 
   // 4. Inject SDK code
@@ -132,7 +125,13 @@ async function handleInit(args, flags, ctx) {
     last_synced_at: new Date().toISOString(),
   });
 
-  // 6. Install SDK dependency
+  // 6. Automatically scan page structures & generate UI business context (.shiplens/contexts/<app_id>.md)
+  let contextResult = null;
+  try {
+    contextResult = generateProjectContext(wd, appId, projectName, framework);
+  } catch (e) {}
+
+  // 7. Install SDK dependency
   let installResult = { success: true, manager: 'skipped' };
   if (!flags['no-install'] && detected.package_manager) {
     installResult = await installSDKDependency(wd, detected.package_manager);
@@ -160,7 +159,7 @@ async function handleInit(args, flags, ctx) {
     }
   }
 
-  // 7. Bind email if specified
+  // 8. Bind email if specified
   let targetEmail = flags.email;
   if (targetEmail === 'auto') {
     targetEmail = getGitEmail();
@@ -188,6 +187,8 @@ async function handleInit(args, flags, ctx) {
 
   const result = {
     ok: true,
+    reconnected: isReusedExisting,
+    reused_existing: isReusedExisting,
     app_id: appId,
     project_name: projectName,
     description: description || undefined,
@@ -201,6 +202,10 @@ async function handleInit(args, flags, ctx) {
     sdk_manager: installResult.manager,
     skill_injected: true,
     skill_file: skillFile,
+    context_generated: !!contextResult,
+    context_file: contextResult ? contextResult.relPath : undefined,
+    context_pages_count: contextResult ? contextResult.totalPages : 0,
+    context_buttons_count: contextResult ? contextResult.totalButtons : 0,
     package_manager: detected.package_manager,
     auth_status: authStatus,
     shiplens_env_written: authStatus === 'magic_link_sent',
@@ -209,12 +214,17 @@ async function handleInit(args, flags, ctx) {
     bound_email: targetEmail || undefined,
     elapsed_ms: elapsed,
     atomic_completed: true,
+    message: isReusedExisting
+      ? `Existing Shiplens project detected and successfully verified (App ID: ${appId}).`
+      : `Shiplens SDK successfully integrated and project created.`,
   };
 
   ctx.output(result, () => {
     console.log(`\n==================================================`);
-    console.log(`✅ Shiplens SDK successfully integrated (${elapsed} ms)\n`);
-    console.log(`📦 Project & Dashboard Information`);
+    console.log(isReusedExisting
+      ? `✅ Shiplens SDK verified & reconnected (${elapsed} ms)\n`
+      : `✅ Shiplens SDK successfully integrated (${elapsed} ms)\n`);
+    console.log(`📦 Project & Dashboard Information` + (isReusedExisting ? ` (Existing setup preserved)` : ''));
     console.log(`Project Name: ${projectName}`);
     if (description) {
       console.log(`Description: ${description}`);
@@ -228,6 +238,9 @@ async function handleInit(args, flags, ctx) {
     console.log(`Live Dashboard / Activation URL: 🔗 ${dashboardUrl}`);
     console.log(`User Account: ${accountStatusText}`);
     console.log(`🧠 AI Skill Ready: ${skillFile}`);
+    if (contextResult && contextResult.relPath) {
+      console.log(`📑 Business Context: ${contextResult.relPath} (${contextResult.totalPages} pages, ${contextResult.totalButtons} buttons mapped)`);
+    }
     console.log(`🔒 [SHIPLENS_ATOMIC_COMPLETED] Setup completed atomically. No extra commands needed.`);
     console.log(`==================================================\n`);
 

package/lib/context-generator.js

@@ -0,0 +1,174 @@
+const fs = require('fs');
+const path = require('path');
+const { detectProjectPages } = require('./scanner');
+const { extractPageSkeleton } = require('./extractor');
+
+/**
+ * Infer page purpose from headings, descriptions, and route name
+ */
+function inferPagePurpose(page, headings, descriptions, faqs) {
+  if (descriptions && descriptions.length > 0) {
+    return descriptions[0];
+  }
+  if (headings && headings.length > 0) {
+    return headings.join(' / ');
+  }
+  if (page.path === '/') {
+    return 'Primary landing / core product overview page';
+  }
+  const cleanName = page.name.replace(/[^a-zA-Z0-9_\- ]/g, '');
+  return `Core ${cleanName} feature page`;
+}
+
+/**
+ * Infer intent and next step for interactive controls
+ */
+function inferButtonIntent(btn, page) {
+  if (btn.action_hint) {
+    return btn.action_hint;
+  }
+  const t = (btn.text || '').toLowerCase();
+  if (t.includes('start') || t.includes('free') || t.includes('try') || t.includes('get started') || t.includes('免费') || t.includes('试用')) {
+    return 'Primary conversion CTA / onboarding initiation';
+  }
+  if (t.includes('sign up') || t.includes('register') || t.includes('注册')) {
+    return 'User account registration';
+  }
+  if (t.includes('login') || t.includes('sign in') || t.includes('登录')) {
+    return 'User authentication login';
+  }
+  if (t.includes('upgrade') || t.includes('buy') || t.includes('pro') || t.includes('pricing') || t.includes('订阅') || t.includes('购买')) {
+    return 'Monetization checkout / subscription upgrade';
+  }
+  if (t.includes('save') || t.includes('submit') || t.includes('保存') || t.includes('提交')) {
+    return 'Save settings or submit form data';
+  }
+  if (t.includes('delete') || t.includes('remove') || t.includes('删除')) {
+    return 'Delete or purge data item';
+  }
+  if (t.includes('calculate') || t.includes('search') || t.includes('filter') || t.includes('计算') || t.includes('查询')) {
+    return 'Execute calculation / filter workflow';
+  }
+  return `Trigger ${btn.tag} interaction on ${page.path}`;
+}
+
+/**
+ * Generate standard business context markdown and write to .shiplens/contexts/<app_id>.md
+ * @param {string} dir Project root directory
+ * @param {string} appId Target App ID
+ * @param {string} projectName Project Name
+ * @param {string} framework Framework detected
+ * @returns {{ filePath: string, relPath: string, totalPages: number, totalButtons: number, markdown: string }}
+ */
+function generateProjectContext(dir = process.cwd(), appId, projectName = 'My App', framework = 'custom') {
+  const { framework: detectedFramework, pages } = detectProjectPages(dir);
+  const activeFramework = framework || detectedFramework;
+
+  const pageDetails = [];
+  let totalButtonsCount = 0;
+
+  for (const p of pages) {
+    const skeleton = extractPageSkeleton(p.filePath, p.path, p.name);
+    const purpose = inferPagePurpose(p, skeleton.headings, skeleton.descriptions, skeleton.faqs);
+    totalButtonsCount += skeleton.raw_buttons.length;
+    pageDetails.push({
+      ...p,
+      relFilePath: path.relative(dir, p.filePath).replace(/\\/g, '/'),
+      purpose,
+      headings: skeleton.headings,
+      faqs: skeleton.faqs,
+      feature_bullets: skeleton.feature_bullets,
+      descriptions: skeleton.descriptions,
+      buttons: skeleton.raw_buttons.map((b) => ({
+        ...b,
+        intent: inferButtonIntent(b, p),
+      })),
+    });
+  }
+
+  const now = new Date().toISOString();
+  const mdLines = [
+    '# Shiplens Project Business Context & UI Dictionary',
+    '',
+    `> **Project Name**: ${projectName}`,
+    `> **App ID**: ${appId}`,
+    `> **Framework**: ${activeFramework}`,
+    `> **Generated At**: ${now}`,
+    '',
+    '---',
+    '',
+    '## 1. Page & Route Catalog',
+    '',
+  ];
+
+  if (pageDetails.length === 0) {
+    mdLines.push('*No frontend template pages detected during initial static scanning.*');
+    mdLines.push('');
+  } else {
+    for (const p of pageDetails) {
+      mdLines.push(`### Page: ${p.name} (\`${p.path}\`)`);
+      mdLines.push(`- **Source File**: [\`${p.relFilePath}\`](file:///${path.resolve(dir, p.relFilePath).replace(/\\/g, '/')})`);
+      mdLines.push(`- **Page Purpose**: ${p.purpose}`);
+
+      if (p.headings.length > 0) {
+        mdLines.push(`- **Key Headings**: ${p.headings.map((h) => `\`${h}\``).join(', ')}`);
+      }
+      if (p.feature_bullets.length > 0) {
+        mdLines.push('- **Feature Highlights**:');
+        for (const f of p.feature_bullets.slice(0, 5)) {
+          mdLines.push(`  - ${f}`);
+        }
+      }
+      if (p.faqs.length > 0) {
+        mdLines.push('- **FAQ Context**:');
+        for (const f of p.faqs.slice(0, 3)) {
+          mdLines.push(`  - Q: ${f.q}${f.a ? ` -> A: ${f.a}` : ''}`);
+        }
+      }
+
+      if (p.buttons.length > 0) {
+        mdLines.push('');
+        mdLines.push(`#### Interactive Elements & Buttons (${p.buttons.length}):`);
+        mdLines.push('| Button ID | Text / Label | Selector | Inferred Action / Intent |');
+        mdLines.push('| :--- | :--- | :--- | :--- |');
+        for (const b of p.buttons) {
+          const textDisplay = (b.text || '').replace(/\|/g, '\\|').trim() || '(icon/action)';
+          mdLines.push(`| \`${b.id}\` | ${textDisplay} | \`${b.selector}\` | ${b.intent} |`);
+        }
+      } else {
+        mdLines.push('- **Interactive Elements**: *(No buttons or interactive controls found on this page)*');
+      }
+      mdLines.push('');
+    }
+  }
+
+  mdLines.push('---');
+  mdLines.push('');
+  mdLines.push('## 2. Business Metric Grounding');
+  mdLines.push(`- **Total Pages Mapped**: ${pageDetails.length}`);
+  mdLines.push(`- **Total Interactive Controls**: ${totalButtonsCount}`);
+  mdLines.push('- **Usage**: When analyzing drop-offs, funnels, or heatmaps, reference the Button IDs and Page Purposes above to translate technical telemetry into actionable product insights.');
+  mdLines.push('');
+
+  const markdownContent = mdLines.join('\n');
+
+  // Standard storage path: .shiplens/contexts/<app_id>.md
+  const contextDir = path.join(dir, '.shiplens', 'contexts');
+  fs.mkdirSync(contextDir, { recursive: true });
+  const targetFilePath = path.join(contextDir, `${appId}.md`);
+  fs.writeFileSync(targetFilePath, markdownContent, 'utf8');
+
+  return {
+    filePath: targetFilePath,
+    relPath: path.relative(dir, targetFilePath).replace(/\\/g, '/'),
+    totalPages: pageDetails.length,
+    totalButtons: totalButtonsCount,
+    markdown: markdownContent,
+  };
+}
+
+module.exports = {
+  generateProjectContext,
+  inferPagePurpose,
+  inferButtonIntent,
+};

package/lib/extractor.js

@@ -0,0 +1,300 @@
+const fs = require('fs');
+
+/**
+ * 清洗代码字符串，去除注释、import、CSS-in-JS 与复杂逻辑噪音
+ * @param {string} rawCode 原始文件代码
+ * @returns {string} 精简后的模板与文案字符串
+ */
+function cleanCode(rawCode) {
+  return rawCode
+    // 移除多行注释与 JSDoc
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    // 移除单行注释
+    .replace(/\/\/.*$/gm, '')
+    // 移除 import 语句
+    .replace(/^import\s+[\s\S]*?from\s+['"].*?['"];?/gm, '')
+    // 移除 require 语句
+    .replace(/const\s+.*?=\s*require\(.*?\);?/gm, '');
+}
+
+/**
+ * 深度提取页面内的多维富文本文案：
+ * 包含：H1~H6 标题、FAQ 折叠问答、套餐权益列表 (li)、卡片段落描述 (p)、Badge 标签
+ * @param {string} code 清洗后的代码
+ * @returns {{ headings: string[], faqs: Array<{ q: string, a?: string }>, feature_bullets: string[], descriptions: string[] }}
+ */
+function extractRichPageContent(code) {
+  const headings = [];
+  const faqs = [];
+  const featureBullets = [];
+  const descriptions = [];
+
+  // 1. 提取 H1 到 H6 标题
+  const headingRegex = /<h[1-6][^>]*>([\s\S]*?)<\/h[1-6]>/gi;
+  let match;
+  while ((match = headingRegex.exec(code)) !== null) {
+    const text = cleanTagContent(match[1]);
+    if (text && text.length > 1 && text.length < 120 && !headings.includes(text)) {
+      headings.push(text);
+    }
+  }
+
+  // 2. 提取 FAQ 问答结构 (<details><summary> 或常见 FAQ 容器)
+  const detailsRegex = /<details[^>]*>[\s\S]*?<summary[^>]*>([\s\S]*?)<\/summary>([\s\S]*?)<\/details>/gi;
+  while ((match = detailsRegex.exec(code)) !== null) {
+    const question = cleanTagContent(match[1]);
+    const answer = cleanTagContent(match[2]);
+    if (question && question.length > 2) {
+      faqs.push({
+        q: question,
+        ...(answer ? { a: answer.slice(0, 150) } : {})
+      });
+    }
+  }
+
+  // 匹配 dt/dd 键值问答
+  const dtRegex = /<dt[^>]*>([\s\S]*?)<\/dt>[\s\S]*?<dd[^>]*>([\s\S]*?)<\/dd>/gi;
+  while ((match = dtRegex.exec(code)) !== null) {
+    const q = cleanTagContent(match[1]);
+    const a = cleanTagContent(match[2]);
+    if (q && q.length > 2 && !faqs.some(f => f.q === q)) {
+      faqs.push({ q, ...(a ? { a: a.slice(0, 150) } : {}) });
+    }
+  }
+
+  // 3. 提取套餐权益与核心特性列表 (<li>)
+  const liRegex = /<li[^>]*>([\s\S]*?)<\/li>/gi;
+  while ((match = liRegex.exec(code)) !== null) {
+    const text = cleanTagContent(match[1]);
+    if (text && text.length > 2 && text.length < 100 && !featureBullets.includes(text)) {
+      featureBullets.push(text);
+    }
+  }
+
+  // 4. 提取核心描述段落 (<p> 及含有 desc/title/text 类的元素)
+  const pRegex = /<p[^>]*>([\s\S]*?)<\/p>/gi;
+  while ((match = pRegex.exec(code)) !== null) {
+    const text = cleanTagContent(match[1]);
+    if (text && text.length > 5 && text.length < 200 && !descriptions.includes(text) && !headings.includes(text)) {
+      descriptions.push(text);
+    }
+  }
+
+  return {
+    headings: headings.slice(0, 8),
+    faqs: faqs.slice(0, 10),
+    feature_bullets: featureBullets.slice(0, 12),
+    descriptions: descriptions.slice(0, 6)
+  };
+}
+
+/**
+ * 提取页面内所有的交互按钮、链接和提交控件
+ * 采用状态机/匹配法准确跳过 JSX 属性中的 arrow function `() =>` 和花括号
+ * @param {string} code 清洗后的代码
+ * @returns {Array<{ id: string, tag: string, text: string, selector: string, label?: string, action_hint?: string }>}
+ */
+function extractInteractiveElements(code) {
+  const elements = [];
+  let elementIndex = 1;
+
+  // 匹配所有 <button, <a, <Link, <input, <div, <span 开头的标签
+  const tagStartRegex = /<([a-zA-Z0-9_-]+)\s+/g;
+  let match;
+
+  while ((match = tagStartRegex.exec(code)) !== null) {
+    const tag = match[1];
+    const targetTags = ['button', 'a', 'link', 'input', 'div', 'span'];
+    if (!targetTags.includes(tag.toLowerCase())) {
+      continue;
+    }
+
+    const startIndex = match.index;
+    let index = startIndex + match[0].length;
+    let inQuotes = null;
+    let braceDepth = 0;
+    let isSelfClosing = false;
+    let tagEndIndex = -1;
+
+    // 解析属性直到遇到真正的 '>'
+    while (index < code.length) {
+      const char = code[index];
+      const prevChar = code[index - 1];
+
+      if (inQuotes) {
+        if (char === inQuotes && prevChar !== '\\') {
+          inQuotes = null;
+        }
+      } else if (char === '"' || char === "'" || char === '`') {
+        inQuotes = char;
+      } else if (char === '{') {
+        braceDepth += 1;
+      } else if (char === '}') {
+        braceDepth = Math.max(0, braceDepth - 1);
+      } else if (char === '>' && braceDepth === 0) {
+        tagEndIndex = index;
+        if (code[index - 1] === '/') {
+          isSelfClosing = true;
+        }
+        break;
+      }
+      index += 1;
+    }
+
+    if (tagEndIndex === -1) continue;
+
+    const attrs = code.slice(startIndex + tag.length + 1, tagEndIndex);
+    let innerContent = '';
+
+    if (!isSelfClosing) {
+      // 寻找对应的闭合标签 </tag>
+      const closeTagStr = `</${tag}>`;
+      const closeTagIndex = code.indexOf(closeTagStr, tagEndIndex + 1);
+      if (closeTagIndex !== -1 && closeTagIndex - tagEndIndex < 2000) {
+        innerContent = code.slice(tagEndIndex + 1, closeTagIndex);
+      }
+    }
+
+    // 判断是否可交互
+    const isExplicitButton = /^(button|a|link)$/i.test(tag);
+    const hasClick = /onClick|@click|v-on:click|role=["']button["']/i.test(attrs);
+    const isSubmit = /type=["']submit["']/i.test(attrs);
+
+    if (!isExplicitButton && !hasClick && !isSubmit) {
+      continue;
+    }
+
+    // 提取 id
+    const idMatch = attrs.match(/\bid=["']([^"']+)["']/i);
+    const rawId = idMatch ? idMatch[1] : null;
+
+    // 提取 data-shiplens-label
+    const labelMatch = attrs.match(/data-shiplens-label=["']([^"']+)["']/i);
+    const explicitLabel = labelMatch ? labelMatch[1] : null;
+
+    // 提取 class/className
+    const classMatch = attrs.match(/(?:class|className)=["']([^"']+)["']/i);
+    const classStr = classMatch ? cleanClassName(classMatch[1]) : '';
+
+    // 提取文案
+    const text = cleanTagContent(innerContent) || extractInputValue(attrs);
+
+    // 提取 href / to / onClick 提示
+    const hrefMatch = attrs.match(/(?:href|to)=["']([^"']+)["']/i);
+    const href = hrefMatch ? hrefMatch[1] : '';
+
+    const clickMatch = attrs.match(/(?:onClick|@click)=["']?\{?([^"'>}]+)\}?["']?/i);
+    const clickHandler = clickMatch ? clickMatch[1].trim() : '';
+
+    // 生成稳定 ID
+    const stableId = explicitLabel 
+      || rawId 
+      || generateIdFromTextOrClass(text, classStr, tag, elementIndex);
+
+    // 生成可读 CSS 选择器
+    const selector = rawId 
+      ? `#${rawId}` 
+      : classStr 
+      ? `${tag.toLowerCase()}.${classStr.split(' ')[0]}` 
+      : `${tag.toLowerCase()}`;
+
+    // 动作推断线索
+    let actionHint = '';
+    if (href) actionHint = `navigate to ${href}`;
+    else if (clickHandler) actionHint = `calls ${clickHandler}`;
+    else if (isSubmit) actionHint = 'submit form';
+
+    elements.push({
+      id: stableId,
+      tag: tag.toLowerCase(),
+      text: text || '(图标/无文案)',
+      selector: selector,
+      ...(explicitLabel ? { label: explicitLabel } : {}),
+      ...(actionHint ? { action_hint: actionHint } : {})
+    });
+
+    elementIndex += 1;
+  }
+
+  // 去重保底（相同 id 保留第一个）
+  const seenIds = new Set();
+  return elements.filter(el => {
+    if (seenIds.has(el.id)) return false;
+    seenIds.add(el.id);
+    return true;
+  });
+}
+
+function cleanTagContent(content) {
+  if (!content) return '';
+  return content
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\{[^}]*\}/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function extractInputValue(attrs) {
+  const match = attrs.match(/value=["']([^"']+)["']/i);
+  return match ? match[1].trim() : '';
+}
+
+function cleanClassName(classStr) {
+  if (!classStr) return '';
+  return classStr
+    .split(/\s+/)
+    .filter(c => c && !/^(css-|_[a-z0-9]{5,}|[a-z0-9]{8,})/i.test(c))
+    .slice(0, 2)
+    .join(' ');
+}
+
+function generateIdFromTextOrClass(text, classStr, tag, index) {
+  if (text && text.length >= 2 && text.length <= 30 && /^[\u4e00-\u9fa5a-zA-Z0-9_\-\s]+$/.test(text)) {
+    const slug = text
+      .trim()
+      .toLowerCase()
+      .replace(/\s+/g, '_')
+      .replace(/[\u4e00-\u9fa5]+/g, (match) => `btn_${encodeURIComponent(match).replace(/%/g, '').slice(0, 8)}`)
+      .replace(/[^a-zA-Z0-9_]/g, '');
+    if (slug) return `btn_${slug.slice(0, 20)}`;
+  }
+
+  if (classStr) {
+    const firstClass = classStr.split(' ')[0].replace(/[^a-zA-Z0-9_-]/g, '');
+    if (firstClass) return `btn_${firstClass}`;
+  }
+
+  return `btn_${tag.toLowerCase()}_${index}`;
+}
+
+/**
+ * 完整解析一个页面的结构与富文本骨架
+ * @param {string} filePath 文件路径
+ * @param {string} routePath 对应路由
+ * @param {string} pageName 页面候选名称
+ * @returns {{ path: string, name: string, headings: string[], faqs: Array, feature_bullets: string[], descriptions: string[], raw_buttons: Array }}
+ */
+function extractPageSkeleton(filePath, routePath, pageName) {
+  if (!fs.existsSync(filePath)) {
+    return { path: routePath, name: pageName, headings: [], faqs: [], feature_bullets: [], descriptions: [], raw_buttons: [] };
+  }
+
+  const rawCode = fs.readFileSync(filePath, 'utf-8');
+  const code = cleanCode(rawCode);
+  const richContent = extractRichPageContent(code);
+  const rawButtons = extractInteractiveElements(code);
+
+  return {
+    path: routePath,
+    name: pageName,
+    ...richContent,
+    raw_buttons: rawButtons
+  };
+}
+
+module.exports = {
+  cleanCode,
+  extractRichPageContent,
+  extractInteractiveElements,
+  extractPageSkeleton
+};

package/lib/injector.js

@@ -394,7 +394,7 @@ async function installSDKDependency(dir, pkgManager = 'npm') {
     },
   ];
 
-  const TIER1_DELAY_MS = 20 * 1000; // 20s
+  const TIER1_DELAY_MS = 5 * 1000; // 5s (fast-forward backup mirrors on high latency)
   const TOTAL_TIMEOUT_MS = 5 * 60 * 1000; // 5min
 
   return new Promise((resolve) => {

package/lib/scanner.js

@@ -0,0 +1,152 @@
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * 递归扫描目录中的代码文件
+ * @param {string} dir 目标目录
+ * @param {string[]} extensions 支持的扩展名
+ * @param {string[]} ignoreDirs 忽略的目录
+ * @returns {string[]} 文件绝对路径列表
+ */
+function scanFiles(dir, extensions = ['.tsx', '.jsx', '.vue', '.html', '.svelte', '.js', '.ts'], ignoreDirs = ['node_modules', '.git', '.next', 'dist', 'build', 'out', '.agents']) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!ignoreDirs.includes(entry.name)) {
+        results.push(...scanFiles(fullPath, extensions, ignoreDirs));
+      }
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (extensions.includes(ext)) {
+        results.push(fullPath);
+      }
+    }
+  }
+  return results;
+}
+
+/**
+ * 自动探测项目类型并提取页面路由列表
+ * @param {string} rootDir 项目根目录
+ * @returns {{ framework: string, pages: Array<{ path: string, filePath: string, name: string }> }}
+ */
+function detectProjectPages(rootDir) {
+  const pages = [];
+  let framework = 'custom';
+
+  // 1. 检测 Next.js App Router (src/app 或 app)
+  const appRouterDir = fs.existsSync(path.join(rootDir, 'src', 'app')) 
+    ? path.join(rootDir, 'src', 'app') 
+    : fs.existsSync(path.join(rootDir, 'app')) 
+    ? path.join(rootDir, 'app') 
+    : null;
+
+  if (appRouterDir) {
+    framework = 'nextjs-app-router';
+    const allFiles = scanFiles(appRouterDir, ['.tsx', '.jsx', '.js', '.ts']);
+    for (const file of allFiles) {
+      const baseName = path.basename(file);
+      if (/^page\.(tsx|jsx|js|ts)$/.test(baseName)) {
+        const relDir = path.relative(appRouterDir, path.dirname(file));
+        const routePath = relDir === '' ? '/' : `/${relDir.replace(/\\/g, '/').replace(/\(.*?\)\/?/g, '')}`;
+        pages.push({
+          path: routePath || '/',
+          filePath: file,
+          name: routePath === '/' ? 'Home (首页)' : routePath
+        });
+      }
+    }
+  }
+
+  // 2. 检测 Next.js / Nuxt Pages Router (src/pages 或 pages)
+  if (pages.length === 0) {
+    const pagesRouterDir = fs.existsSync(path.join(rootDir, 'src', 'pages')) 
+      ? path.join(rootDir, 'src', 'pages') 
+      : fs.existsSync(path.join(rootDir, 'pages')) 
+      ? path.join(rootDir, 'pages') 
+      : null;
+
+    if (pagesRouterDir) {
+      framework = 'pages-router';
+      const allFiles = scanFiles(pagesRouterDir, ['.tsx', '.jsx', '.vue', '.js', '.ts']);
+      for (const file of allFiles) {
+        const rel = path.relative(pagesRouterDir, file);
+        const nameWithoutExt = rel.replace(/\.[^/.]+$/, '').replace(/\\/g, '/');
+        if (nameWithoutExt.startsWith('_') || nameWithoutExt.startsWith('api/')) continue;
+
+        const routePath = nameWithoutExt === 'index' ? '/' : `/${nameWithoutExt.replace(/\/index$/, '')}`;
+        pages.push({
+          path: routePath,
+          filePath: file,
+          name: routePath === '/' ? 'Home (首页)' : routePath
+        });
+      }
+    }
+  }
+
+  // 3. 检测通用 Vite / React / Vue (src/views, src/routes, src/pages, 或扫描全部 .vue/.tsx 组件)
+  if (pages.length === 0) {
+    const candidateDirs = ['src/views', 'src/pages', 'src/routes', 'src/components', 'src'].map(d => path.join(rootDir, d));
+    for (const cDir of candidateDirs) {
+      if (fs.existsSync(cDir)) {
+        const files = scanFiles(cDir, ['.tsx', '.jsx', '.vue', '.html', '.svelte']);
+        for (const file of files) {
+          const base = path.basename(file, path.extname(file));
+          // 过滤通用辅助或原子组件 (如 Button, Icon, Header)
+          if (/^(Page|View|Screen|Home|Pricing|Login|Dashboard|Checkout|Register|Setting|About)/i.test(base)) {
+            const cleanName = base.toLowerCase().replace(/(page|view|screen)$/i, '');
+            const routePath = cleanName === 'home' || cleanName === 'index' ? '/' : `/${cleanName}`;
+            pages.push({
+              path: routePath,
+              filePath: file,
+              name: base
+            });
+          }
+        }
+        if (pages.length > 0) {
+          framework = 'vite-react-vue';
+          break;
+        }
+      }
+    }
+  }
+
+  // 4. 静态 HTML 项目保底
+  if (pages.length === 0) {
+    const htmlFiles = scanFiles(rootDir, ['.html'], ['node_modules', '.git', 'dist']);
+    if (htmlFiles.length > 0) {
+      framework = 'static-html';
+      for (const file of htmlFiles) {
+        const rel = path.relative(rootDir, file).replace(/\\/g, '/');
+        const routePath = rel === 'index.html' ? '/' : `/${rel.replace(/\.html$/, '')}`;
+        pages.push({
+          path: routePath,
+          filePath: file,
+          name: path.basename(file)
+        });
+      }
+    }
+  }
+
+  // 去重保底
+  const uniqueMap = new Map();
+  for (const p of pages) {
+    if (!uniqueMap.has(p.path)) {
+      uniqueMap.set(p.path, p);
+    }
+  }
+
+  return {
+    framework,
+    pages: Array.from(uniqueMap.values())
+  };
+}
+
+module.exports = {
+  scanFiles,
+  detectProjectPages
+};

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@shiplens/cli",
-  "version": "1.4.4",
+  "version": "1.4.6",
   "description": "Shiplens CLI — Automated Web User Analytics & AI Agent Analysis Engine",
   "main": "lib/index.js",
   "bin": {
-    "cli": "./bin/shiplens.js",
-    "shiplens": "./bin/shiplens.js",
-    "shiplens-cli": "./bin/shiplens.js"
+    "cli": "bin/shiplens.js",
+    "shiplens": "bin/shiplens.js",
+    "shiplens-cli": "bin/shiplens.js"
   },
   "keywords": [
     "shiplens",

package/prompts/prompts_cli_en-US.md

@@ -2,7 +2,7 @@
 
 ---
 
-## Scenario Outline (42 Scenarios)
+## Scenario Outline (43 Scenarios)
 
 > **How to use**: Scan this outline to find the matching scenario, then jump to its full section below for deterministic CLI commands and analysis steps.
 
@@ -61,16 +61,17 @@
 34. [Track and Measure User Aha Moment](#track-and-measure-user-aha-moment)
 35. [Track Subscription Revenue & Build Daily Subscription Dashboard](#track-subscription-revenue--build-daily-subscription-dashboard)
 
-### Initial Setup (4)
-36. [Shiplens CLI One-Click Setup & Analytics Initialization](#shiplens-cli-one-click-setup--analytics-initialization)
-37. [Remove Shiplens SDK & Analytics Data](#remove-shiplens-sdk--analytics-data)
-38. [Uninstall Shiplens CLI](#uninstall-shiplens-cli)
-39. [Generate Context Descriptions for All Pages and Buttons](#generate-context-descriptions-for-all-pages-and-buttons)
+### Initial Setup (5)
+36. [Shiplens CLI One-Click Setup & Analytics Initialization](#shiplens-cli-one-click-setup-analytics-initialization)
+37. [Use Shiplens CLI to Install Analytics SDK & Link to Existing Account](#use-shiplens-cli-to-install-analytics-sdk-link-to-existing-account)
+38. [Delete Shiplens Project Analytics Data & SDK (No Longer Needed)](#delete-shiplens-project-analytics-data-sdk-no-longer-needed)
+39. [Delete Shiplens CLI](#delete-shiplens-cli)
+40. [Use Shiplens CLI to Generate Context Descriptions for All Pages and Buttons](#use-shiplens-cli-to-generate-context-descriptions-for-all-pages-and-buttons)
 
 ### Troubleshooting & Diagnostics (3)
-40. [Test Shiplens Telemetry Pipeline and Environment](#test-shiplens-telemetry-pipeline-and-environment)
-41. [Enable Local Debug Mode and Verify Event Reporting](#enable-local-debug-mode-and-verify-event-reporting)
-42. [Test Event Reporting in Production Build & Release Environments](#test-event-reporting-in-production-build--release-environments)
+41. [Test Shiplens Telemetry Pipeline and Environment](#test-shiplens-telemetry-pipeline-and-environment)
+42. [Enable Local Debug Mode and Verify Event Reporting](#enable-local-debug-mode-and-verify-event-reporting)
+43. [Test Event Reporting in Production Build & Release Environments](#test-event-reporting-in-production-build--release-environments)
 
 ---
 
@@ -734,18 +735,44 @@ Sources:
 
 #### [setup_init] Shiplens CLI One-Click Setup & Analytics Initialization (Suffix: None)
 ```text
-Set up Shiplens analytics: extract project description, install SDK, create the project, and retrieve the live dashboard URL.
+Set up Shiplens analytics: install SDK, create the project, and retrieve the live dashboard URL.
 1. Run CLI initialization command:
-   - Windows: npx.cmd --yes @shiplens/cli init
-   - macOS/Linux: npx --yes @shiplens/cli init
+   - Windows: npx.cmd --yes @shiplens/cli init --json
+   - macOS/Linux: npx --yes @shiplens/cli init --json
 2. Present the standard project & dashboard summary (including: Project Name, App ID, Code Injection file, User Account Status, Live Dashboard / Activation URL);
 3. Immediately prompt the user for their email address (informing them that you will register on their behalf and Shiplens will send an activation email for 50,000 monthly free events and project binding);
 4. Upon receiving the user's email, run: npx.cmd --yes @shiplens/cli auth bind --email <email> --json.
 ```
 
-#### [remove_sdk] Remove Shiplens SDK & Analytics Data (Suffix: None)
+#### [setup_bind_project] Use Shiplens CLI to Install Analytics SDK & Link to Existing Account (Suffix: None)
 ```text
-Remove Shiplens SDK integration and analytics data:
+Use Shiplens CLI to install the analytics SDK in this new project and link it to the user's existing Shiplens account:
+
+1. Run the project setup & initialization command:
+   - Windows: npx.cmd --yes @shiplens/cli init --json
+   - macOS/Linux: npx --yes @shiplens/cli init --json
+   (Automatically detects framework, installs SDK dependency, injects code entry, and creates cloud project)
+
+2. Inspect returned `user_account_status` and credential states:
+   - [Branch A: Logged in & linked] (`logged_in_linked`):
+     No extra step needed; present the project summary card containing App ID, Project Name, Injected file, and Live Dashboard URL (`dashboard_url`).
+   - [Branch B: No local credentials detected] (`not_logged_in_unlinked` or `activation_required=true`):
+     Prompt the user for their registered Shiplens account email, and upon reply run:
+     `npx.cmd --yes @shiplens/cli auth bind --email <email> --json`
+     Instruct the user to click the Magic Link in the email to authorize and complete project binding.
+   - [Branch C: Account quota / project limit reached] (Error `QUOTA_EXCEEDED` / `PLAN_LIMIT` / unable to link):
+     Clearly notify the user that their current free/existing tier project limit or monthly event quota is full;
+     Provide upgrade instructions: recommend upgrading to Pro / Team tier (URL: https://shiplens.dev/pricing or console settings) for expanded project limits and advanced analytics;
+     Note that once upgraded, re-running the bind command will activate immediately without modifying code.
+
+3. Output the final project summary and dashboard link, confirming the project is ready for analytics queries.
+
+Please prioritize calling Shiplens CLI (Action: setup_bind_project) to execute the above requirements.
+```
+
+#### [remove_sdk] Delete Shiplens Project Analytics Data & SDK (No Longer Needed) (Suffix: None)
+```text
+Delete Shiplens project analytics data and SDK integration (analytics no longer needed):
 1. Read `.shiplens.json` in the project root to get project name, app_id, and instrumented file paths.
 2. Clearly display the project name and app_id to be deleted, warn the user that historical events and hosted data will be permanently purged, and pause for explicit user confirmation ("Confirm deleting this project").
 3. Upon confirmation, remove SDK imports/instrumentation code from local frontend files, and delete `./.shiplens.json` and `.shiplens/contexts/<app_id>.md`.
@@ -754,16 +781,16 @@ Remove Shiplens SDK integration and analytics data:
 Please prioritize calling Shiplens CLI (Action: remove_sdk) to execute the above requirements.
 ```
 
-#### [uninstall_cli] Uninstall Shiplens CLI (Suffix: None)
+#### [uninstall_cli] Delete Shiplens CLI and Restore Project (Suffix: None)
 ```text
 Please prioritize calling Shiplens CLI (Action: uninstall_cli) to execute the above requirements.
  - Windows: npm.cmd uninstall -g @shiplens/cli
  - macOS/Linux: npm uninstall -g @shiplens/cli
 ```
 
-#### [generate_context] Generate Context Descriptions for All Pages and Buttons (Suffix: None)
+#### [generate_context] Use Shiplens CLI to Generate Context Descriptions for All Pages and Buttons (Suffix: None)
 ```text
-Map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can map numbers and IDs to concrete functionality:
+Use Shiplens CLI to map pages, features, and button layouts into `.shiplens/contexts/<app_id>.md` so AI analytics can understand the business context behind each metric:
 1. Check `./.shiplens.json` for current app_id and project name.
 2. Inspect frontend code and routes to extract feature descriptions, user-facing copy, and button texts, locations, and actions.
 3. Write structured details into `.shiplens/contexts/<app_id>.md`, binding app_id and project name in the header.