@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-init/init-entry-merge-model.mjs

@@ -0,0 +1,33 @@
+const managedBlockPattern = /<!-- vibecoding:start[^>]*-->[\s\S]*?<!-- vibecoding:end -->/g;
+
+export function normalizedEntryTemplateText(templateText, { managedBlockStart, managedBlockEnd }) {
+  const text = String(templateText || '').trim();
+  if (!text.includes(managedBlockStart) || !text.includes(managedBlockEnd)) {
+    return `${managedBlockStart}\n${text}\n${managedBlockEnd}\n`;
+  }
+  return `${text}\n`;
+}
+
+export function managedBlocks(text) {
+  return [...String(text || '').matchAll(managedBlockPattern)];
+}
+
+export function appendManagedBlock(existingText, blockText) {
+  const trimmedRight = String(existingText || '').replace(/[\t ]+$/gm, '').replace(/\s*$/, '');
+  if (!trimmedRight) return blockText;
+  return `${trimmedRight}\n\n${blockText}`;
+}
+
+export function entryFileMergePlan({ currentText, template, merge }) {
+  const blocks = managedBlocks(currentText);
+
+  if (merge === 'preview') return { type: 'merge-preview', contents: template };
+  if (blocks.length > 1) return { type: 'conflict', reason: `multiple managed blocks (${blocks.length})` };
+  if (blocks.length === 1) {
+    const next = String(currentText || '').replace(managedBlockPattern, String(template || '').trim());
+    return { type: 'merge-replace', contents: `${next.replace(/\s*$/, '')}\n`, write: true };
+  }
+  if (merge === 'append') return { type: 'merge-append', contents: appendManagedBlock(currentText, template), write: true };
+  if (merge === 'replace') return { type: 'conflict', reason: 'no managed block to replace' };
+  return { type: 'skip', reason: 'exists; no managed block; use --merge=preview or --merge=append' };
+}

package/tools/vibe-init/init-install-manifest-model.mjs

@@ -0,0 +1,137 @@
+import {
+  installedAgentExperienceContract,
+  installedAgentExperiencePrompts,
+  runtimeInstallFirstTurnAcceptance,
+} from './init-installed-agent-experience-contract.mjs';
+
+export const runtimeInstallEntrypoints = {
+  runtime_cli_present: false,
+  doctor_cli_present: false,
+};
+
+export const runtimeInstallInvocation = {
+  mode: 'external-kit-repo-or-package',
+  project_argument: '<project-root>',
+  local_project_tool_entrypoints: false,
+  notes: [
+    'The installed business project only stores opt-in metadata under .vibecoding/.',
+    'Run runtime or doctor commands from the Vibecoding kit source repo or a packaged CLI distribution.',
+  ],
+};
+
+export const runtimeInstallBoundaries = {
+  creates_state_directory_by_default: false,
+  auto_runtime_enabled: false,
+  hook_registration: false,
+  daemon: false,
+  watcher: false,
+  mcp: false,
+  platform_api: false,
+  session_create: false,
+  runtime_action: false,
+  business_source_write: false,
+  source_merge: false,
+  git: false,
+  worktree: false,
+  external_network: false,
+};
+
+export const runtimeInstallRecommendedCommands = [
+  'node <vibecoding-kit>/tools/vibe-doctor/index.mjs <project-root>',
+  'node <vibecoding-kit>/tools/vibe-runtime/index.mjs compatibility --report --root <project-root>',
+];
+
+export function runtimeInstallManifest({ kitDirectoryName, options, selectedPlatforms }) {
+  const selected = selectedPlatforms(options.platform).sort();
+  const manifest = {
+    version: 1,
+    stage: 'Stage 55',
+    manifest_kind: 'installed-runtime-opt-in',
+    installed_at: new Date().toISOString(),
+    root_layout: 'installed-project',
+    kit_directory: kitDirectoryName,
+    installed_project_entrypoints: runtimeInstallEntrypoints,
+    runtime_invocation: runtimeInstallInvocation,
+    opt_in: true,
+    default_enabled: false,
+    docs_installed: Boolean(options.withDocs),
+    platforms: selected,
+    boundaries: runtimeInstallBoundaries,
+    installed_agent_experience_contract: installedAgentExperienceContract(options.automationProfile),
+    agent_session_start_contract: runtimeInstallFirstTurnAcceptance,
+    recommended_commands: runtimeInstallRecommendedCommands,
+  };
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+export function installConfigManifest({
+  entryFilesForPlatform,
+  exists,
+  installedPath,
+  kitDirectoryName,
+  managedBlocks,
+  options,
+  readText,
+  runtimeManifestFileName,
+  selectedPlatforms,
+  toNative,
+  actions,
+}) {
+  const plannedEntryManagedState = (file) => {
+    const target = toNative(options.target, file);
+
+    for (let index = actions.length - 1; index >= 0; index -= 1) {
+      const action = actions[index];
+      if (action.target !== target) continue;
+      if (['copy', 'merge-append', 'merge-replace'].includes(action.type)) return true;
+      if (['skip', 'conflict', 'merge-preview'].includes(action.type)) break;
+    }
+
+    return exists(target) && managedBlocks(readText(target)).length === 1;
+  };
+
+  const selected = selectedPlatforms(options.platform).sort();
+  const managedEntries = Object.fromEntries(
+    entryFilesForPlatform(options.platform).map((file) => [file, plannedEntryManagedState(file)]),
+  );
+
+  const requestedProfile = options.automationProfile;
+  const profile = requestedProfile === 'default' ? 'vibe-guided' : requestedProfile;
+  const manifest = {
+    version: 1,
+    profile: 'standard',
+    automation_profile: profile,
+    automation_profile_boundary: {
+      default_profile: profile === 'vibe-guided',
+      vibe_guided_profile: profile === 'vibe-guided',
+      parity_profile: profile === 'superpowers-parity',
+      session_start_strength: profile === 'superpowers-parity' ? 'strict-skill-first-summary' : 'vibe-guided-lightweight-routing',
+      full_skill_injection: false,
+      automatic_skill_execution: false,
+      automatic_subagent_execution: false,
+      automatic_source_write: false,
+      automatic_git_write: false,
+    },
+    platforms: selected,
+    interaction: profile === 'superpowers-parity' ? 'strict-skill-first' : 'vibe-guided',
+    installed_agent_experience_contract: installedAgentExperienceContract(profile),
+    acceptance_prompts: installedAgentExperiencePrompts,
+    agent_session_start_contract: {
+      ...runtimeInstallFirstTurnAcceptance,
+      session_start_strength: profile === 'superpowers-parity' ? 'strict-skill-first-visible-route' : 'vibe-guided-lightweight-routing',
+      profile_activation: profile === 'superpowers-parity' ? 'installed-config' : 'default-vibe-guided-config',
+    },
+    runtime: {
+      enabled: options.withRuntime || exists(installedPath(options.target, runtimeManifestFileName)),
+    },
+    managed_entries: managedEntries,
+    docs_installed: Boolean(options.withDocs),
+    lifecycle: {
+      update: 'managed-assets-and-managed-blocks-only',
+      repair: 'missing-assets-and-managed-entries-only',
+      uninstall: 'remove-managed-blocks-and-kit-directory-preserve-runtime-state',
+    },
+  };
+
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}

package/tools/vibe-init/init-installed-agent-experience-contract.mjs

@@ -0,0 +1,172 @@
+export const installedAgentExperienceContractVersion = 2;
+
+export const installedAgentExperiencePrompts = Object.freeze({
+  first_turn: '我想给这个项目加一个小功能，请先判断下一步。',
+  continue_task: '继续按已有计划推进下一步，但先告诉我当前 TODO、验证策略和停止条件。',
+  bug_debug: '这个命令失败了，先定位原因，再说明修复和验证路径。',
+  completion_closeout: '请判断这个任务能不能收口，给出验证证据、缺口和下一步人工动作。',
+  review_feedback: '这段 review feedback 怎么处理？先分类、说明是否阻塞、验证路径和停止条件。',
+});
+
+export const installedBusinessUxRegressionPrompts = Object.freeze([
+  'first_turn',
+  'continue_task',
+  'bug_debug',
+  'completion_closeout',
+  'review_feedback',
+]);
+
+export const installedAgentExperienceForbiddenActionMarkers = Object.freeze([
+  'hidden_execution=false',
+  'command_execution=false',
+  'skill_execution_claimed=false',
+  'subagent_dispatch_claimed=false',
+  'business_source_write=false',
+  'git_write_claimed=false',
+  'platform_api=false',
+  'model_invocation=false',
+  'push=false',
+  'pr=false',
+  'merge=false',
+]);
+
+function normalizeInstalledExperienceProfile(profile = 'vibe-guided') {
+  if (profile === 'superpowers-parity') return 'superpowers-parity';
+  return 'vibe-guided';
+}
+
+export function installedAgentExperienceExpectedResponseShape(profile = 'vibe-guided') {
+  const normalizedProfile = normalizeInstalledExperienceProfile(profile);
+  const strict = normalizedProfile === 'superpowers-parity';
+  return {
+    first_turn: [
+      'read .vibecoding/skills/using-vibecoding/SKILL.md by file path',
+      strict ? 'state strict skill-first visible route' : 'state lightweight route and visible next manual action',
+      'state validation strategy or evidence gap before source-changing work',
+      'do not inject the full workflow skill table by default',
+      'do not claim workflow skill execution without evidence',
+    ],
+    continue_task: [
+      'show current TODO or plan trace before continuing',
+      'state next manual action and stop condition',
+      'keep execution, subagent, source write, and git actions blocked unless explicitly scoped',
+    ],
+    bug_debug: [
+      'reproduce or explain why reproduction is unavailable before modifying code',
+      'state root-cause evidence before fix claims',
+      'bind fix completion to validation evidence',
+    ],
+    completion_closeout: [
+      'read completion_evidence.task_completion_summary first when available',
+      'summarize validation evidence and unresolved gaps',
+      'state whether the task is ready to hand off without push, PR, merge, or remote action claims',
+    ],
+    review_feedback: [
+      'classify feedback as blocking bug, design concern, test gap, documentation gap, disputed feedback, or out-of-scope feedback',
+      'state whether the feedback blocks the next task before fixing or continuing',
+      'bind any required change to affected files, verification path, and stop condition',
+      'do not auto-call reviewers, auto-repair, commit, push, PR, merge, or claim completion without evidence',
+    ],
+  };
+}
+
+export function installedAgentExperienceProfileSummary(profile = 'vibe-guided') {
+  const normalizedProfile = normalizeInstalledExperienceProfile(profile);
+  const strict = normalizedProfile === 'superpowers-parity';
+  return {
+    automation_profile: normalizedProfile,
+    vibe_guided_profile: !strict,
+    default_profile: !strict,
+    parity_profile: strict,
+    experience_mode: strict ? 'strict-skill-first-visible-route' : 'vibe-guided-lightweight-routing',
+    tiny_context_default: true,
+    full_skill_injection: false,
+    automatic_skill_execution: false,
+    automatic_command_execution: false,
+    automatic_subagent_execution: false,
+    automatic_source_write: false,
+    automatic_git_write: false,
+    remote_or_platform_action: false,
+  };
+}
+
+export function installedAgentExperienceContract(profile = 'vibe-guided') {
+  return {
+    version: installedAgentExperienceContractVersion,
+    stage: 'Stage 18',
+    contract_kind: 'installed-agent-experience-contract-v2',
+    profile_summary: installedAgentExperienceProfileSummary(profile),
+    skill_bootstrap: {
+      expected_first_skill: 'using-vibecoding',
+      skill_path: '.vibecoding/skills/using-vibecoding/SKILL.md',
+      registry_fallback_to_file_path: true,
+      context_policy: 'tiny_context',
+      full_skill_injection: false,
+      skill_execution_claimed: false,
+      command_execution_claimed: false,
+      subagent_dispatch_claimed: false,
+      git_write_claimed: false,
+    },
+    acceptance_prompts: installedAgentExperiencePrompts,
+    expected_response_shape: installedAgentExperienceExpectedResponseShape(profile),
+    closeout_summary_entry: 'completion_evidence.task_completion_summary',
+    installed_business_ux_regression: {
+      stage: 'Stage 25',
+      regression_kind: 'installed-business-ux-regression-pack',
+      prompts: [...installedBusinessUxRegressionPrompts],
+      context_policy_default: 'tiny_context',
+      one_screen_response_required: true,
+      maintainer_stage_table_allowed_by_default: false,
+      superpowers_parity_execution_authorized: false,
+      forbidden_regressions: [
+        'full_skill_injection',
+        'maintainer_runtime_stage_table_leak',
+        'hidden_execution_claim',
+        'automatic_test_claim',
+        'git_pr_push_merge_claim',
+      ],
+    },
+    installed_multiround_close_loop_acceptance: {
+      stage: 'Stage 27',
+      acceptance_kind: 'installed-multiround-ux-close-loop-acceptance',
+      marker: 'installed_multiround_close_loop',
+      prompts: [...installedBusinessUxRegressionPrompts],
+      required_round_markers: ['using-vibecoding', 'visible_route', 'next_manual_action', 'validation evidence or evidence gap', 'stop_condition'],
+      closeout_markers: ['completion_evidence.task_completion_summary', 'session --close', 'review_feedback', 'next_task_gate.blocked'],
+      automatic_execution_authorized: false,
+      reviewer_or_repair_auto_invocation: false,
+    },
+    forbidden_action_markers: [...installedAgentExperienceForbiddenActionMarkers],
+    boundary_assertions: {
+      installed_experience_contract_artifact: false,
+      state_directory_created: false,
+      command_execution: false,
+      runtime_action: false,
+      skill_execution: false,
+      business_source_write: false,
+      git: false,
+      git_write: false,
+      commit: false,
+      push: false,
+      pr: false,
+      merge: false,
+      platform_api: false,
+      external_network: false,
+      model_invocation: false,
+      subagent: false,
+      daemon: false,
+      watcher: false,
+    },
+    deterministic: true,
+    local_only: true,
+    read_only: true,
+  };
+}
+
+export const runtimeInstallFirstTurnAcceptance = {
+  expected_first_skill: 'using-vibecoding',
+  skill_path: '.vibecoding/skills/using-vibecoding/SKILL.md',
+  fallback_to_file_path: true,
+  first_turn_acceptance_prompt: installedAgentExperiencePrompts.first_turn,
+  expected_first_turn_behavior: installedAgentExperienceExpectedResponseShape('vibe-guided').first_turn,
+};

package/tools/vibe-init/init-platform-model.mjs

@@ -0,0 +1,11 @@
+export function selectedPlatforms(platform) {
+  if (platform === 'all') return ['claude', 'codex', 'cursor', 'opencode', 'pi'];
+  return [platform];
+}
+
+export function entryFilesForPlatform(platform) {
+  const entries = [];
+  if (platform === 'all' || platform === 'claude') entries.push('CLAUDE.md');
+  if (platform === 'all' || platform === 'cursor' || platform === 'codex') entries.push('AGENTS.md');
+  return [...new Set(entries)];
+}

package/tools/vibe-init/init-presentation.mjs

@@ -0,0 +1,149 @@
+import path from 'node:path';
+
+import { installedAgentExperiencePrompts } from './init-installed-agent-experience-contract.mjs';
+
+function formatCommandArg(value) {
+  const text = String(value);
+  if (text.length === 0) return '""';
+  if (!/[\s"]/.test(text)) return text;
+  return `"${text.replaceAll('"', '\\"')}"`;
+}
+
+export function printCheck({ checkTarget, options, repoRoot, toNative }) {
+  console.log('Vibecoding Kit Init Check');
+  console.log(`Target: ${options.target}`);
+  console.log(`Platform: ${options.platform}`);
+  console.log(`Automation profile: ${options.automationProfile}`);
+  console.log('');
+
+  for (const item of checkTarget(options)) {
+    const prefix = item.status === 'ok' ? '[ok]' : item.status === 'warn' ? '[warn]' : '[info]';
+    console.log(`${prefix} ${item.label}`);
+    if (item.detail) console.log(`       ${item.detail}`);
+  }
+
+  console.log('');
+  console.log('Next:');
+  console.log(`  node ${formatCommandArg(path.relative(options.target, toNative(repoRoot, 'tools/vibe-init/index.mjs')))} --target ${formatCommandArg(options.target)} --platform ${options.platform}`);
+  console.log(`  node ${formatCommandArg(path.relative(options.target, toNative(repoRoot, 'tools/vibe-doctor/index.mjs')))} ${formatCommandArg(options.target)}`);
+}
+
+export function printMergePreview({ entryFilesForPlatform, exists, normalizedTemplateText, options, toNative }) {
+  console.log('Vibecoding Kit Merge Preview');
+  console.log(`Target: ${options.target}`);
+  console.log(`Platform: ${options.platform}`);
+  console.log(`Automation profile: ${options.automationProfile}`);
+  console.log('');
+
+  for (const file of entryFilesForPlatform(options.platform)) {
+    const targetFile = toNative(options.target, file);
+    if (!exists(targetFile)) {
+      console.log(`[skip] ${file} does not exist in target. vibe-init can copy the full template.`);
+      console.log('');
+      continue;
+    }
+
+    console.log(`--- ${file} managed block preview ---`);
+    console.log(normalizedTemplateText(file).trim());
+    console.log(`--- end ${file} ---`);
+    console.log('');
+  }
+}
+
+function printSummaryHeader({ kitDirectoryName, options }) {
+  console.log('Vibecoding Kit Init');
+  console.log(`Target: ${options.target}`);
+  console.log(`Platform: ${options.platform}`);
+  console.log(`Automation profile: ${options.automationProfile}`);
+  console.log(`Layout: installed (${kitDirectoryName}/)`);
+  console.log(`Docs: ${options.withDocs ? 'included' : 'skipped'}`);
+  console.log(`Runtime opt-in: ${options.withRuntime ? 'installed' : 'skipped'}`);
+  console.log(`Mode: ${options.check ? 'check' : options.mergePreview ? 'merge-preview' : options.dryRun ? 'dry-run' : 'write'}`);
+  console.log(`Entry merge: ${options.merge}`);
+  console.log('');
+}
+
+function printAction(options, action) {
+  if (action.type === 'copy') {
+    console.log(`[copy] ${path.relative(options.target, action.target)}`);
+  } else if (action.type === 'write') {
+    console.log(`[write] ${path.relative(options.target, action.target)}`);
+  } else if (action.type === 'mkdir') {
+    console.log(`[mkdir] ${path.relative(options.target, action.target) || '.'}`);
+  } else if (action.type === 'skip') {
+    console.log(`[skip] ${path.relative(options.target, action.target)} (${action.reason})`);
+  } else if (action.type === 'merge-append') {
+    console.log(`[merge-append] ${path.relative(options.target, action.target)}`);
+  } else if (action.type === 'merge-replace') {
+    console.log(`[merge-replace] ${path.relative(options.target, action.target)}`);
+  } else if (action.type === 'merge-preview') {
+    console.log(`[merge-preview] ${path.relative(options.target, action.target)}`);
+  } else if (action.type === 'conflict') {
+    console.log(`[conflict] ${path.relative(options.target, action.target)} (${action.reason})`);
+  }
+}
+
+function printSummaryNextSteps({ entryFilesForPlatform, kitDirectoryName, options, runtimeManifestFileName }) {
+  const acceptancePrompt = installedAgentExperiencePrompts.first_turn;
+  const closeoutPrompt = installedAgentExperiencePrompts.completion_closeout;
+  console.log('Next:');
+  console.log(`  1. Run diagnostics from the Vibecoding kit repo or packaged CLI: node <vibecoding-kit>/tools/vibe-doctor/index.mjs ${formatCommandArg(options.target)}`);
+  console.log(`  2. Check entry file(s): ${entryFilesForPlatform(options.platform).join(', ')}`);
+  console.log(`  3. Check workflow skills: ${kitDirectoryName}/skills/using-vibecoding/SKILL.md`);
+  console.log(`  4. First-turn acceptance prompt: ${acceptancePrompt}`);
+  console.log(`     Expected: read ${kitDirectoryName}/skills/using-vibecoding/SKILL.md by file path, state route + visible next action, and do not execute commands/tests/subagents/source/git without explicit permission.`);
+  console.log(`  5. Completion closeout acceptance prompt: ${closeoutPrompt}`);
+  console.log('     Expected: read completion_evidence.task_completion_summary when available, summarize validation evidence + gaps, and do not claim push/PR/merge/remote actions.');
+  console.log(`  6. Review feedback acceptance prompt: ${installedAgentExperiencePrompts.review_feedback}`);
+  console.log('     Expected: classify feedback, state blocker status, verification path, and stop condition before repair or next-task claims.');
+  console.log('     Installed agent experience contract v2: installed-agent-experience-contract-v2 with first_turn, continue_task, bug_debug, completion_closeout, and review_feedback prompt shapes.');
+  console.log(`     Profile behavior: ${options.automationProfile === 'superpowers-parity' ? 'strict skill-first visible route' : 'Vibe Guided lightweight routing'}.`);
+  if (options.withRuntime) {
+    console.log(`  7. Check runtime opt-in manifest: ${kitDirectoryName}/${runtimeManifestFileName}`);
+    console.log(`  8. Run compatibility report from the Vibecoding kit repo or packaged CLI: node <vibecoding-kit>/tools/vibe-runtime/index.mjs compatibility --report --root ${formatCommandArg(options.target)}`);
+  } else {
+    console.log(`  7. Optional read-only start helper: node <vibecoding-kit>/tools/vibe-runtime/index.mjs workflow --start --prompt ${formatCommandArg(acceptancePrompt)} --json --root ${formatCommandArg(options.target)}`);
+  }
+}
+
+function skippedEntryActions({ actions, entryFilesForPlatform, options }) {
+  return actions.filter(
+    (action) => ['skip', 'conflict', 'merge-preview'].includes(action.type) && entryFilesForPlatform(options.platform).includes(path.basename(action.target)),
+  );
+}
+
+function printSkippedEntryMergeOptions({ actions, entryFilesForPlatform, options, repoRoot, toNative }) {
+  if (skippedEntryActions({ actions, entryFilesForPlatform, options }).length === 0) return;
+
+  console.log('');
+  console.log('Existing entry file(s) were not overwritten. Safe merge options:');
+  console.log(`  preview: node ${formatCommandArg(path.relative(options.target, toNative(repoRoot, 'tools/vibe-init/index.mjs')))} --target ${formatCommandArg(options.target)} --platform ${options.platform} --merge=preview`);
+  console.log(`  append:  node ${formatCommandArg(path.relative(options.target, toNative(repoRoot, 'tools/vibe-init/index.mjs')))} --target ${formatCommandArg(options.target)} --platform ${options.platform} --merge=append`);
+}
+
+export function printSummary({ actions, entryFilesForPlatform, kitDirectoryName, options, repoRoot, runtimeManifestFileName, toNative }) {
+  const counts = actions.reduce(
+    (acc, action) => {
+      acc[action.type] = (acc[action.type] ?? 0) + 1;
+      return acc;
+    },
+    {},
+  );
+
+  printSummaryHeader({ kitDirectoryName, options });
+
+  for (const action of actions) {
+    printAction(options, action);
+  }
+
+  console.log('');
+  console.log(`Summary: ${counts.copy ?? 0} copy, ${counts.write ?? 0} write, ${counts.mkdir ?? 0} mkdir, ${counts.skip ?? 0} skip`);
+  console.log('');
+  printSummaryNextSteps({ entryFilesForPlatform, kitDirectoryName, options, runtimeManifestFileName });
+  printSkippedEntryMergeOptions({ actions, entryFilesForPlatform, options, repoRoot, toNative });
+
+  if (options.dryRun) {
+    console.log('');
+    console.log('Dry-run only. Re-run without --dry-run to write files.');
+  }
+}

package/tools/vibe-lifecycle/README.md

@@ -0,0 +1,37 @@
+# vibe-lifecycle
+
+`vibe-lifecycle` owns the installed-project lifecycle after `vibe init`.
+
+It is intentionally separate from the runtime workflow state machine:
+
+- It reads and writes `.vibecoding/config.json`.
+- It updates or repairs `.vibecoding/` installed assets.
+- It only changes `CLAUDE.md` / `AGENTS.md` inside Vibecoding managed blocks.
+- It removes `.vibecoding/` during uninstall.
+- It does not create, delete, or modify `.vibecoding-state/`.
+
+## Commands
+
+```bash
+node tools/vibe-lifecycle/index.mjs update --root <project> --dry-run
+node tools/vibe-lifecycle/index.mjs repair --root <project> --dry-run
+node tools/vibe-lifecycle/index.mjs uninstall --root <project> --dry-run
+```
+
+The packaged wrapper exposes the same lifecycle:
+
+```bash
+vibe update --root <project> --dry-run
+vibe repair --root <project> --dry-run
+vibe uninstall --root <project> --dry-run
+```
+
+`update`, `repair`, and `uninstall` are dry-run by default. Use `--confirm` or `--yes` to apply the printed plan.
+
+## Lifecycle boundaries
+
+- `update` refreshes installed assets and existing managed blocks.
+- `repair` restores missing installed assets and missing entries only when `.vibecoding/config.json` marks them as managed.
+- `uninstall` removes Vibecoding managed blocks and `.vibecoding/`, while preserving user content and `.vibecoding-state/`.
+
+Existing entry files without a managed block are never overwritten by lifecycle commands.