viepilot 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -9,7 +9,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Enhanced
 
-- **M1.15 / Phase 18 (FEAT-004) in progress** — npm publish distribution scaffold: package publish metadata, release scripts, secure GitHub Actions `release-npm` workflow, and maintainer publish/rollback guide. Final registry smoke verify is blocked pending npm publish auth.
+- **M1.17 / Phase 21 (ENH-013) completed** — realigned README metrics (`npm run readme:sync` with `cloc`) and moved `.viepilot` to local-only (`.gitignore` + untracked index).
+- **M1.15 / Phase 18 (FEAT-004) completed** — npm distribution flow is now fully closed: publish pipeline passes and package released to npm as `viepilot@1.0.1`.
+- **M1.15 / Phase 19 (FEAT-005) completed** — installer now supports keyboard selector UX (arrow/space/enter), added `viepilot uninstall` command (`--target`, `--yes`, `--dry-run`), and switched dev installer to copy-first flow to avoid symlink-based skill discovery failures.
+- **M1.16 / Phase 20 (FEAT-006) completed** — added README LOC auto-sync command (`npm run readme:sync`) driven by `cloc` with non-blocking fallback, installer `cloc` dependency checks/guidance, and a donate section in README with PayPal/MOMO links.
 
 ### Fixed
 
@@ -17,6 +20,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Documentation
 
+- `README.md`, `docs/user/quick-start.md` — updated install wizard controls and uninstall command examples.
+- `README.md`, `docs/troubleshooting.md`, `docs/user/quick-start.md` — documented README metric sync flow, `cloc` fallback/install guidance, and maintainer usage.
+- `docs/troubleshooting.md` — added selector TTY fallback guidance and uninstall/reinstall recovery flow for legacy symlink installs.
 - `README.md` — Project Scale LOC + M1.11 completion banner; Documentation row includes `api/`
 - `.viepilot/audit-report.md` — PASS after README metric sync (`/vp-audit`)
 - `docs/api/*` — added framework-appropriate API index (no HTTP surface; points to CLI/file model)

package/README.md

@@ -16,13 +16,19 @@ ViePilot là bộ skill framework cho phép AI assistant (Claude, GPT, etc.) ph
 
 ViePilot is a skill framework that enables AI assistants to develop projects **autonomously**, with **control points**, and **recovery capability**. Built with professional standards: Semantic Versioning, Conventional Commits, Keep a Changelog.
 
+### Support ViePilot
+
+Nếu ViePilot giúp ích cho bạn, bạn có thể ủng hộ một ly cafe:
+- PayPal: [https://paypal.me/SATCODING](https://paypal.me/SATCODING)
+- MOMO: [https://me.momo.vn/aMINujUPTbIRtbTli6Fd](https://me.momo.vn/aMINujUPTbIRtbTli6Fd)
+
 ---
 
 ## Quy mô dự án / Project Scale
 
 | Chỉ số / Metric | Giá trị / Value |
 |-----------------|-----------------|
-| Total LOC | **~24,000+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
+| Total LOC | **~22,384+** (`.md`, `.js`, `.cjs`, `.yml`, `.json`, `.sh`; không gồm `node_modules`) |
 | Skills | **14** |
 | Workflows | **12** |
 | Templates | **16** (Project: 11, Phase: 5) |
@@ -31,6 +37,8 @@ ViePilot is a skill framework that enables AI assistants to develop projects **a
 | ViePilot phases (repo) | **15** hoàn thành (xem `.viepilot/TRACKER.md`) |
 | Standards | 5 (SemVer, Commits, Changelog, Comments, Contributors) |
 
+> Metric `Total LOC` có thể được refresh tự động bằng `npm run readme:sync` (dùng `cloc`; nếu thiếu `cloc` script sẽ fallback an toàn).
+
 ### Phân bổ / Breakdown
 
 | Thành phần / Component | Số lượng / Count | Mô tả / Description |
@@ -187,17 +195,22 @@ Tổng thể / Overall:  ██████████████████
 ```bash
 git clone https://github.com/0-CODE/viepilot.git
 cd viepilot
-npx @0/viepilot install
+npx viepilot install
 ```
 
-Chọn target profile trong wizard:
+Chọn target profile trong wizard (phím mũi tên + space + enter):
 - Claude Code
 - Cursor Agent
 - Cursor IDE
 
 Non-interactive:
 ```bash
-npx @0/viepilot install --target cursor-agent --yes
+npx viepilot install --target cursor-agent --yes
+```
+
+Gỡ cài đặt:
+```bash
+npx viepilot uninstall --target cursor-agent --yes
 ```
 
 ### Cách 2: Thủ công / Manual

package/bin/viepilot.cjs

@@ -7,6 +7,7 @@
 const path = require('path');
 const { spawnSync } = require('child_process');
 const readline = require('readline');
+const fs = require('fs');
 
 const TARGETS = [
   { id: 'claude-code', label: 'Claude Code' },
@@ -20,6 +21,7 @@ ViePilot CLI
 
 Usage:
   viepilot install [options]
+  viepilot uninstall [options]
   viepilot --help
   viepilot --list-targets
 
@@ -29,6 +31,11 @@ Install options:
   --dry-run                  Print actions only, do not execute installers
   --list-targets             Print supported targets and exit
   --help                     Show help
+
+Uninstall options:
+  --target <id|id,id|all>   Remove installed assets for selected profile(s)
+  --yes                     Non-interactive mode (skip confirmations)
+  --dry-run                 Print actions only, do not remove files
 `);
 }
 
@@ -68,6 +75,35 @@ function parseInstallArgs(args) {
   return options;
 }
 
+function parseUninstallArgs(args) {
+  const options = {
+    yes: false,
+    dryRun: false,
+    targets: null,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--yes') options.yes = true;
+    else if (arg === '--dry-run') options.dryRun = true;
+    else if (arg === '--target') {
+      const value = args[i + 1];
+      if (!value) {
+        throw new Error('Missing value for --target');
+      }
+      options.targets = value;
+      i++;
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
 function normalizeTargets(rawTargets) {
   if (!rawTargets) return null;
   if (rawTargets === 'all') return TARGETS.map((t) => t.id);
@@ -80,6 +116,96 @@ function normalizeTargets(rawTargets) {
   return [...new Set(parsed)];
 }
 
+function createSelectorState(items, mode = 'multi') {
+  return {
+    mode,
+    items,
+    cursor: 0,
+    selected: mode === 'single' ? new Set([0]) : new Set(),
+  };
+}
+
+function applySelectorKey(state, keyName) {
+  const next = {
+    ...state,
+    selected: new Set([...state.selected]),
+  };
+  const lastIndex = next.items.length - 1;
+
+  if (keyName === 'up') {
+    next.cursor = next.cursor === 0 ? lastIndex : next.cursor - 1;
+    return next;
+  }
+  if (keyName === 'down') {
+    next.cursor = next.cursor === lastIndex ? 0 : next.cursor + 1;
+    return next;
+  }
+  if (keyName === 'space') {
+    if (next.mode === 'single') {
+      next.selected = new Set([next.cursor]);
+    } else if (next.selected.has(next.cursor)) {
+      next.selected.delete(next.cursor);
+    } else {
+      next.selected.add(next.cursor);
+    }
+    return next;
+  }
+  return next;
+}
+
+function renderSelector(state, title) {
+  process.stdout.write('\x1Bc');
+  console.log(title);
+  console.log('');
+  for (let i = 0; i < state.items.length; i++) {
+    const item = state.items[i];
+    const isCursor = i === state.cursor;
+    const isSelected = state.selected.has(i);
+    const marker = state.mode === 'single' ? (isSelected ? '(*)' : '( )') : (isSelected ? '[x]' : '[ ]');
+    const pointer = isCursor ? '>' : ' ';
+    console.log(`${pointer} ${marker} ${item.label} (${item.id})`);
+  }
+  console.log('');
+  console.log('Keys: ↑/↓ move, space select, enter confirm, q cancel');
+}
+
+function runKeyboardSelector(items, mode, title) {
+  return new Promise((resolve) => {
+    let state = createSelectorState(items, mode);
+    renderSelector(state, title);
+    readline.emitKeypressEvents(process.stdin);
+    const shouldRestoreRaw = process.stdin.isTTY;
+    if (shouldRestoreRaw) process.stdin.setRawMode(true);
+
+    const onKeypress = (_, key) => {
+      if (!key) return;
+      if (key.name === 'q' || (key.ctrl && key.name === 'c')) {
+        cleanup();
+        resolve([]);
+        return;
+      }
+      if (key.name === 'return') {
+        const selected = [...state.selected].sort((a, b) => a - b).map((idx) => state.items[idx].id);
+        cleanup();
+        resolve(selected);
+        return;
+      }
+      if (['up', 'down', 'space'].includes(key.name)) {
+        state = applySelectorKey(state, key.name);
+        renderSelector(state, title);
+      }
+    };
+
+    const cleanup = () => {
+      process.stdin.off('keypress', onKeypress);
+      if (shouldRestoreRaw) process.stdin.setRawMode(false);
+      console.log('');
+    };
+
+    process.stdin.on('keypress', onKeypress);
+  });
+}
+
 function ask(question) {
   return new Promise((resolve) => {
     const rl = readline.createInterface({
@@ -94,34 +220,27 @@ function ask(question) {
 }
 
 async function interactiveTargetSelection() {
-  console.log('\nSelect install targets (comma-separated numbers):');
-  TARGETS.forEach((t, idx) => {
-    console.log(`  ${idx + 1}. ${t.label} (${t.id})`);
-  });
-  console.log('  4. All targets');
-  console.log('  0. Cancel');
-  const answer = await ask('Choice: ');
-
-  if (answer === '0') return [];
-  if (answer === '4') return TARGETS.map((t) => t.id);
-
-  const indexes = answer
-    .split(',')
-    .map((x) => Number(x.trim()))
-    .filter((n) => Number.isInteger(n) && n >= 1 && n <= TARGETS.length);
-
-  const selected = [...new Set(indexes.map((n) => TARGETS[n - 1].id))];
-  return selected;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log('\nSelect install targets (comma-separated numbers):');
+    TARGETS.forEach((t, idx) => {
+      console.log(`  ${idx + 1}. ${t.label} (${t.id})`);
+    });
+    console.log(`  ${TARGETS.length + 1}. All targets`);
+    console.log('  0. Cancel');
+    const answer = await ask('Choice: ');
+    if (answer === '0') return [];
+    if (answer === String(TARGETS.length + 1)) return TARGETS.map((t) => t.id);
+    const indexes = answer
+      .split(',')
+      .map((x) => Number(x.trim()))
+      .filter((n) => Number.isInteger(n) && n >= 1 && n <= TARGETS.length);
+    return [...new Set(indexes.map((n) => TARGETS[n - 1].id))];
+  }
+  return runKeyboardSelector(TARGETS, 'multi', 'Select install targets');
 }
 
 function handlerForTarget(target) {
   const root = path.join(__dirname, '..');
-  if (target === 'cursor-agent') {
-    return {
-      script: path.join(root, 'dev-install.sh'),
-      env: { VIEPILOT_AUTO_YES: '1', VIEPILOT_INSTALL_PROFILE: target },
-    };
-  }
   return {
     script: path.join(root, 'install.sh'),
     env: { VIEPILOT_AUTO_YES: '1', VIEPILOT_INSTALL_PROFILE: target },
@@ -187,6 +306,92 @@ async function installCommand(rawArgs) {
   return failed.length === 0 ? 0 : 1;
 }
 
+function computeUninstallPaths(targets) {
+  const home = process.env.HOME || '';
+  const cursorSkills = path.join(home, '.cursor', 'skills');
+  const vpRoot = path.join(home, '.cursor', 'viepilot');
+  const paths = [];
+
+  if (targets.some((t) => t === 'cursor-agent' || t === 'cursor-ide')) {
+    if (fs.existsSync(cursorSkills)) {
+      for (const entry of fs.readdirSync(cursorSkills)) {
+        if (entry.startsWith('vp-')) {
+          paths.push(path.join(cursorSkills, entry));
+        }
+      }
+    } else {
+      paths.push(path.join(cursorSkills, 'vp-*'));
+    }
+  }
+
+  paths.push(vpRoot);
+  paths.push('/usr/local/bin/vp-tools');
+  paths.push('/usr/local/bin/viepilot');
+
+  return [...new Set(paths)];
+}
+
+function removePathSafely(targetPath, dryRun) {
+  if (!fs.existsSync(targetPath)) {
+    return { path: targetPath, status: 'missing' };
+  }
+  if (dryRun) {
+    return { path: targetPath, status: 'planned' };
+  }
+  try {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+    return { path: targetPath, status: 'removed' };
+  } catch (error) {
+    return { path: targetPath, status: 'failed', reason: error.message };
+  }
+}
+
+async function uninstallCommand(rawArgs) {
+  const options = parseUninstallArgs(rawArgs);
+  if (options.help) {
+    printHelp();
+    return 0;
+  }
+  let selectedTargets = normalizeTargets(options.targets);
+  if (!selectedTargets) {
+    if (options.yes) {
+      selectedTargets = TARGETS.map((t) => t.id);
+    } else if (process.stdin.isTTY && process.stdout.isTTY) {
+      selectedTargets = await runKeyboardSelector(TARGETS, 'single', 'Select uninstall profile');
+      if (selectedTargets.length === 0) {
+        console.log('Uninstall canceled.');
+        return 0;
+      }
+    } else {
+      selectedTargets = TARGETS.map((t) => t.id);
+    }
+  }
+
+  if (!options.yes && (!process.stdin.isTTY || !process.stdout.isTTY)) {
+    throw new Error('Non-interactive uninstall requires --yes');
+  }
+  if (!options.yes) {
+    const answer = await ask(`Uninstall ViePilot for target ${selectedTargets.join(', ')}? (y/N) `);
+    if (!/^y(es)?$/i.test(answer)) {
+      console.log('Uninstall canceled.');
+      return 0;
+    }
+  }
+
+  const actions = computeUninstallPaths(selectedTargets).map((p) => removePathSafely(p, options.dryRun));
+  const failed = actions.filter((a) => a.status === 'failed');
+
+  console.log('\nUninstall summary:');
+  for (const action of actions) {
+    if (action.status === 'removed') console.log(`- ${action.path}: removed`);
+    else if (action.status === 'planned') console.log(`- ${action.path}: planned`);
+    else if (action.status === 'missing') console.log(`- ${action.path}: not found`);
+    else console.log(`- ${action.path}: failed (${action.reason})`);
+  }
+
+  return failed.length === 0 ? 0 : 1;
+}
+
 async function main() {
   const [, , command, ...rest] = process.argv;
   if (!command || command === '--help' || command === '-h') {
@@ -197,14 +402,14 @@ async function main() {
     printTargets();
     process.exit(0);
   }
-  if (command !== 'install') {
+  if (command !== 'install' && command !== 'uninstall') {
     console.error(`Unknown command: ${command}`);
     printHelp();
     process.exit(1);
   }
 
   try {
-    const code = await installCommand(rest);
+    const code = command === 'install' ? await installCommand(rest) : await uninstallCommand(rest);
     process.exit(code);
   } catch (error) {
     console.error(`Error: ${error.message}`);
@@ -218,5 +423,9 @@ if (require.main === module) {
 
 module.exports = {
   parseInstallArgs,
+  parseUninstallArgs,
   normalizeTargets,
+  createSelectorState,
+  applySelectorKey,
+  computeUninstallPaths,
 };

package/dev-install.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 
 # ViePilot Development Installation Script
-# Creates symlinks to development version for instant updates
+# Installs development build without symlink dependency by default
 
 set -e
 
@@ -25,15 +25,29 @@ echo " VIEPILOT DEV INSTALLER"
 echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 echo -e "${NC}"
 
-echo -e "${YELLOW}Development mode installation${NC}"
+echo -e "${YELLOW}Development mode installation (copy-first for reliability)${NC}"
 echo "  Source: $SCRIPT_DIR"
 echo "  Target: $CURSOR_SKILLS_DIR, $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
 echo ""
 
+check_cloc_dependency() {
+    if command -v cloc >/dev/null 2>&1; then
+        echo -e "  ${GREEN}✓${NC} cloc detected"
+        return 0
+    fi
+
+    echo -e "${YELLOW}  cloc not found.${NC}"
+    echo "  README LOC auto-sync will fallback safely, but metrics won't refresh automatically."
+    echo "  Install suggestion:"
+    echo "    - macOS: brew install cloc"
+    echo "    - Ubuntu/Debian: sudo apt-get install -y cloc"
+    echo "    - Windows: choco install cloc"
+}
+
 # Confirm
 if [ "$AUTO_YES" != "1" ]; then
-    read -p "This will replace existing installation with symlinks. Continue? (y/n) " -n 1 -r
+    read -p "This will replace existing installation with dev files. Continue? (y/n) " -n 1 -r
     echo
     if [[ ! $REPLY =~ ^[Yy]$ ]]; then
         echo "Installation cancelled."
@@ -61,32 +75,41 @@ if [ -d "$VIEPILOT_DIR" ] || [ -L "$VIEPILOT_DIR" ]; then
 fi
 
 echo ""
-echo -e "${BLUE}Creating skill symlinks...${NC}"
+echo -e "${BLUE}Installing skills...${NC}"
 
-# Create skill symlinks
+# Install skill copies (avoid symlink discovery issues)
 mkdir -p "$CURSOR_SKILLS_DIR"
 for skill in "$SCRIPT_DIR"/skills/vp-*/; do
     skill_name=$(basename "$skill")
-    ln -s "$skill" "$CURSOR_SKILLS_DIR/$skill_name"
+    cp -R "$skill" "$CURSOR_SKILLS_DIR/$skill_name"
     echo -e "  ${GREEN}✓${NC} $skill_name"
 done
 
 echo ""
-echo -e "${BLUE}Creating viepilot symlinks...${NC}"
+echo -e "${BLUE}Installing viepilot files...${NC}"
 
-# Create viepilot directory and symlinks
+# Install file copies (avoid symlink discovery issues)
 mkdir -p "$VIEPILOT_DIR"
-ln -s "$SCRIPT_DIR/workflows" "$VIEPILOT_DIR/workflows"
-ln -s "$SCRIPT_DIR/templates" "$VIEPILOT_DIR/templates"
-ln -s "$SCRIPT_DIR/bin" "$VIEPILOT_DIR/bin"
-ln -s "$SCRIPT_DIR/lib" "$VIEPILOT_DIR/lib"
-ln -s "$SCRIPT_DIR/ui-components" "$VIEPILOT_DIR/ui-components"
+mkdir -p "$VIEPILOT_DIR/workflows"
+mkdir -p "$VIEPILOT_DIR/templates"
+mkdir -p "$VIEPILOT_DIR/bin"
+mkdir -p "$VIEPILOT_DIR/lib"
+mkdir -p "$VIEPILOT_DIR/ui-components"
+
+cp -R "$SCRIPT_DIR/workflows/"* "$VIEPILOT_DIR/workflows/"
+cp -R "$SCRIPT_DIR/templates/"* "$VIEPILOT_DIR/templates/"
+cp -R "$SCRIPT_DIR/bin/"* "$VIEPILOT_DIR/bin/"
+cp -R "$SCRIPT_DIR/lib/"* "$VIEPILOT_DIR/lib/"
+if [ -d "$SCRIPT_DIR/ui-components" ]; then
+    cp -R "$SCRIPT_DIR/ui-components/"* "$VIEPILOT_DIR/ui-components/"
+fi
 
 echo -e "  ${GREEN}✓${NC} workflows"
 echo -e "  ${GREEN}✓${NC} templates"
 echo -e "  ${GREEN}✓${NC} bin"
 echo -e "  ${GREEN}✓${NC} lib"
 echo -e "  ${GREEN}✓${NC} ui-components"
+check_cloc_dependency
 
 # Count installed
 SKILL_COUNT=$(ls -d "$CURSOR_SKILLS_DIR"/vp-*/ 2>/dev/null | wc -l | tr -d ' ')
@@ -97,13 +120,10 @@ echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━
 echo -e "${GREEN} DEV INSTALLATION COMPLETE ✓${NC}"
 echo -e "${GREEN}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
 echo ""
-echo "Installed (via symlinks):"
+echo "Installed (copy mode):"
 echo "  - Skills: $SKILL_COUNT"
 echo "  - Workflows: $WORKFLOW_COUNT"
 echo ""
-echo -e "${YELLOW}Development mode enabled!${NC}"
-echo "Any changes to $SCRIPT_DIR will be reflected immediately."
-echo ""
-echo "To switch back to stable installation:"
-echo "  ./install.sh"
+echo -e "${YELLOW}Development mode enabled (reliable copy mode).${NC}"
+echo "Re-run this script after local changes to refresh installed files."
 echo ""

package/docs/dev/deployment.md

@@ -7,13 +7,13 @@ ViePilot là một local framework — không có server để deploy. "Deployme
 ### Method 1: npm distribution (recommended for users)
 
 ```bash
-npx @0/viepilot install
+npx viepilot install
 ```
 
 Direct target mode:
 
 ```bash
-npx @0/viepilot install --target cursor-agent --yes
+npx viepilot install --target cursor-agent --yes
 ```
 
 ### Method 2: Git Clone + Install Script (maintainers/dev)
@@ -116,7 +116,7 @@ Secret required:
 npm run smoke:published
 # or explicitly:
 npx viepilot --help
-npx @0/viepilot install --help
+npx viepilot install --help
 ```
 
 Optional version pin:

package/docs/troubleshooting.md

@@ -30,6 +30,33 @@ Use `--yes` for no prompt and `--target` to avoid interactive selection.
 
 ---
 
+### Interactive selector doesn't work (arrow/space keys)
+
+**Cause**: Terminal is non-TTY (CI, redirected stdin/out).  
+ViePilot tự fallback về mode nhập số trong môi trường non-TTY.
+
+```bash
+npx viepilot install --target cursor-agent --yes
+```
+
+---
+
+### README LOC metric is not updating
+
+**Cause**: `cloc` is not installed, so `readme:sync` skips update by design.
+
+```bash
+# Install cloc (macOS)
+brew install cloc
+
+# Then rerun metric sync
+npm run readme:sync
+```
+
+On Linux/Windows, use your package manager (`apt`, `dnf`, `choco`) to install `cloc`.
+
+---
+
 ### `./install.sh: Permission denied`
 
 **Cause**: Script not executable.
@@ -46,12 +73,9 @@ chmod +x install.sh
 **Cause**: ViePilot bin not in PATH.
 
 ```bash
-# Check if symlink exists
-ls -la ~/.local/bin/vp-tools
-
-# If missing, re-run dev install
+# Re-run installer to refresh local bin
 cd /path/to/viepilot
-./dev-install.sh
+npx viepilot install --target cursor-agent --yes
 ```
 
 ---
@@ -72,6 +96,12 @@ cp -r skills/vp-* ~/.cursor/skills/
 
 Then restart Cursor.
 
+If issue happens after old dev symlink installs:
+```bash
+npx viepilot uninstall --yes
+npx viepilot install --target cursor-agent --yes
+```
+
 ---
 
 ## Project Initialization Issues

package/docs/user/quick-start.md

@@ -23,17 +23,22 @@ Bạn: Review, approve, hoặc rollback
 ```bash
 git clone https://github.com/0-CODE/viepilot
 cd viepilot
-npx @0/viepilot install
+npx viepilot install
 ```
 
-Chọn profile cài đặt trong wizard:
+Chọn profile cài đặt trong wizard (arrow keys + space + enter):
 - `claude-code`
 - `cursor-agent`
 - `cursor-ide`
 
 Non-interactive:
 ```bash
-npx @0/viepilot install --target cursor-agent --yes
+npx viepilot install --target cursor-agent --yes
+```
+
+Uninstall:
+```bash
+npx viepilot uninstall --target cursor-agent --yes
 ```
 
 Verify:
@@ -43,6 +48,12 @@ vp-tools help
 # Hiển thị targets + ViePilot CLI Tools
 ```
 
+Optional (maintainers):
+```bash
+npm run readme:sync
+# refresh README Total LOC metrics via cloc
+```
+
 ---
 
 ## Step 2: Create a New Project

package/install.sh

@@ -40,6 +40,50 @@ echo "  ViePilot: $VIEPILOT_DIR"
 echo "  Profile: $INSTALL_PROFILE"
 echo ""
 
+install_cloc_best_effort() {
+    if command -v cloc >/dev/null 2>&1; then
+        echo "  ✓ cloc detected"
+        return 0
+    fi
+
+    echo -e "${YELLOW}  cloc not found.${NC}"
+    echo "  README metric auto-sync can still run with fallback, but LOC refresh will be skipped."
+    echo "  Suggested install:"
+    echo "    - macOS: brew install cloc"
+    echo "    - Ubuntu/Debian: sudo apt-get install -y cloc"
+    echo "    - Windows: choco install cloc"
+
+    if [ "$AUTO_YES" = "1" ]; then
+        return 0
+    fi
+
+    read -p "  Attempt automatic cloc install now (best effort)? (y/n) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        return 0
+    fi
+
+    if command -v brew >/dev/null 2>&1; then
+        brew install cloc || true
+    elif command -v apt-get >/dev/null 2>&1; then
+        sudo apt-get update && sudo apt-get install -y cloc || true
+    elif command -v dnf >/dev/null 2>&1; then
+        sudo dnf install -y cloc || true
+    elif command -v yum >/dev/null 2>&1; then
+        sudo yum install -y cloc || true
+    elif command -v pacman >/dev/null 2>&1; then
+        sudo pacman -Sy --noconfirm cloc || true
+    else
+        echo -e "${YELLOW}  Could not detect supported package manager. Install cloc manually.${NC}"
+    fi
+
+    if command -v cloc >/dev/null 2>&1; then
+        echo "  ✓ cloc installed"
+    else
+        echo -e "${YELLOW}  cloc is still unavailable; continuing without blocking installation.${NC}"
+    fi
+}
+
 # Confirm installation
 if [ "$AUTO_YES" != "1" ]; then
     read -p "Continue with installation? (y/n) " -n 1 -r
@@ -102,6 +146,9 @@ chmod +x "$VIEPILOT_DIR/bin/vp-tools.cjs"
 chmod +x "$VIEPILOT_DIR/bin/viepilot.cjs"
 echo "    ✓ vp-tools.cjs + viepilot.cjs + lib/cli-shared.cjs"
 
+echo "  Checking optional dependency for README metric sync..."
+install_cloc_best_effort
+
 # Create symlink in PATH (optional)
 echo ""
 if [ "$AUTO_YES" != "1" ]; then

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "viepilot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "**Autonomous Vibe Coding Framework / Bộ khung phát triển tự động có kiểm soát**",
   "main": "index.js",
   "bin": {
@@ -14,6 +14,7 @@
     "test": "jest",
     "test:coverage": "jest --coverage",
     "test:watch": "jest --watch",
+    "readme:sync": "node scripts/sync-readme-metrics.cjs",
     "lint:cli": "node --check bin/vp-tools.cjs && node --check bin/viepilot.cjs",
     "verify:release": "npm run lint:cli && npm test && npm pack --dry-run",
     "prepublishOnly": "npm run verify:release",

package/skills/vp-auto/SKILL.md

@@ -63,6 +63,7 @@ If required task details are missing, do not implement until task contract is re
 
 **Updates on milestone complete:**
 - `README.md` — version badge, skills/workflows counts, Skills Reference table, Workflows table, Project Structure, Completion Status
+- `README.md` metrics — run `npm run readme:sync` when script exists; if `cloc` missing, continue with logged guidance (non-blocking)
 
 **After:** Project built, or paused for user intervention.
 </objective>

package/workflows/autonomous.md

@@ -323,6 +323,11 @@ fi
 Update README.md — **generic updates (all projects)**:
 1. Any version number mentions: update to `$ACTUAL_VERSION`
 2. Any "last updated" or "as of" date references
+3. If project contains `README` metrics table and `scripts/sync-readme-metrics.cjs`, run:
+   ```bash
+   npm run readme:sync || true
+   ```
+   - If `cloc` is unavailable, script must log guidance and continue (non-blocking).
 
 **viepilot framework only** (skip if `skills/` directory does not exist):
 ```bash