minimal-vibe-coding-kit 0.4.0 → 0.4.1

package/.agents/skills/coding-level/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coding-level
-description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked.
+description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked. A project default may be recorded in backbone.yml conventions.custom_rules.
 disable-model-invocation: true
 argument-hint: "[0-5]"
 ---
@@ -20,6 +20,13 @@ argument-hint: "[0-5]"
 
 1. Read `$ARGUMENTS` as N. If N is not an integer 0–5, reply with the table above and ask for a valid N.
 2. Read `references/level-<N>.md`, state once which level is now active, and apply that persona to every reply until `/coding-level` is invoked again.
+3. Ask once: "Save level N as the project default?" If yes, add or update the `Default coding level: N` entry in `backbone.yml` `conventions.custom_rules` (show the diff and wait for approval, per kit rules).
+
+## Project default
+
+- First-time init records a default as a `backbone.yml` `conventions.custom_rules` entry: `Default coding level: N (<Register>)`.
+- Sessions without an explicit `/coding-level` start from that default level.
+- `/coding-level N` overrides the default for the current session only, unless the user saves it in step 3.
 
 ## Scope
 

package/.agents/skills/path-sensitive-shell-safety/SKILL.md

@@ -48,6 +48,7 @@ No empty, unset, broad, symlinked, or unintended path may reach a destructive co
 
 ## Required outcomes
 
+- Prefer a recoverable delete (`trash`) over permanent `rm` for user files; permanent deletion requires explicit confirmation of the exact paths. If `trash` is missing, recommend installing it (macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS with Node `npm i -g trash-cli`).
 - A blank branch may follow the documented default-branch fallback policy.
 - An explicit branch must fail if missing; never silently deploy another branch.
 - A blank folder/base value must fail before any `rm`, `mv`, `cp`, `rsync`, `find`, Docker, or Git cleanup command runs.

package/.claude/rules/safe-delete.md

@@ -0,0 +1,11 @@
+# Safe delete rules
+
+- Never delete permanently by default. Prefer `trash` over `rm`, `rm -rf`, `rmdir`, and `find -delete` so deletions stay recoverable.
+- Before deleting, check availability with `command -v trash`. If available, use `trash <path>`.
+- If `trash` is missing, recommend installing it instead of falling back to `rm`:
+  - macOS 14 or newer: built in at `/usr/bin/trash`, nothing to install.
+  - Older macOS: `brew install trash` (https://formulae.brew.sh/formula/trash).
+  - Linux: `sudo apt install trash-cli` or `pip install trash-cli` (https://github.com/andreafrancia/trash-cli).
+  - Any OS with Node.js: `npm install --global trash-cli` (https://github.com/sindresorhus/trash-cli).
+- Permanent deletion requires the user's explicit approval of the exact paths, and the `path-sensitive-shell-safety` skill first when paths come from variables.
+- Honor the deletion preference recorded in `backbone.yml` `conventions.custom_rules` during first-time init.

package/.claude/skills/coding-level/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coding-level
-description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked.
+description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked. A project default may be recorded in backbone.yml conventions.custom_rules.
 disable-model-invocation: true
 argument-hint: "[0-5]"
 ---
@@ -20,6 +20,13 @@ argument-hint: "[0-5]"
 
 1. Read `$ARGUMENTS` as N. If N is not an integer 0–5, reply with the table above and ask for a valid N.
 2. Read `references/level-<N>.md`, state once which level is now active, and apply that persona to every reply until `/coding-level` is invoked again.
+3. Ask once: "Save level N as the project default?" If yes, add or update the `Default coding level: N` entry in `backbone.yml` `conventions.custom_rules` (show the diff and wait for approval, per kit rules).
+
+## Project default
+
+- First-time init records a default as a `backbone.yml` `conventions.custom_rules` entry: `Default coding level: N (<Register>)`.
+- Sessions without an explicit `/coding-level` start from that default level.
+- `/coding-level N` overrides the default for the current session only, unless the user saves it in step 3.
 
 ## Scope
 

package/.claude/skills/path-sensitive-shell-safety/SKILL.md

@@ -48,6 +48,7 @@ No empty, unset, broad, symlinked, or unintended path may reach a destructive co
 
 ## Required outcomes
 
+- Prefer a recoverable delete (`trash`) over permanent `rm` for user files; permanent deletion requires explicit confirmation of the exact paths. If `trash` is missing, recommend installing it (macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS with Node `npm i -g trash-cli`).
 - A blank branch may follow the documented default-branch fallback policy.
 - An explicit branch must fail if missing; never silently deploy another branch.
 - A blank folder/base value must fail before any `rm`, `mv`, `cp`, `rsync`, `find`, Docker, or Git cleanup command runs.

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-vibe-coding-kit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Reusable vibe coding skills and workflows for Codex-compatible repositories.",
   "author": {
     "name": "Minimal Vibe Coding Kit"

package/.cursor/rules/040-safe-delete.mdc

@@ -0,0 +1,16 @@
+---
+description: Safe-delete guardrail - prefer trash over rm so deletions stay recoverable.
+alwaysApply: true
+---
+
+# Safe delete rules
+
+- Never delete permanently by default. Prefer `trash` over `rm`, `rm -rf`, `rmdir`, and `find -delete` so deletions stay recoverable.
+- Before deleting, check availability with `command -v trash`. If available, use `trash <path>`.
+- If `trash` is missing, recommend installing it instead of falling back to `rm`:
+  - macOS 14 or newer: built in at `/usr/bin/trash`, nothing to install.
+  - Older macOS: `brew install trash` (https://formulae.brew.sh/formula/trash).
+  - Linux: `sudo apt install trash-cli` or `pip install trash-cli` (https://github.com/andreafrancia/trash-cli).
+  - Any OS with Node.js: `npm install --global trash-cli` (https://github.com/sindresorhus/trash-cli).
+- Permanent deletion requires the user's explicit approval of the exact paths, and the `path-sensitive-shell-safety` skill first when paths come from variables.
+- Honor the deletion preference recorded in `backbone.yml` `conventions.custom_rules` during first-time init.

package/.cursor/skills/coding-level/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coding-level
-description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked.
+description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked. A project default may be recorded in backbone.yml conventions.custom_rules.
 disable-model-invocation: true
 argument-hint: "[0-5]"
 ---
@@ -20,6 +20,13 @@ argument-hint: "[0-5]"
 
 1. Read `$ARGUMENTS` as N. If N is not an integer 0–5, reply with the table above and ask for a valid N.
 2. Read `references/level-<N>.md`, state once which level is now active, and apply that persona to every reply until `/coding-level` is invoked again.
+3. Ask once: "Save level N as the project default?" If yes, add or update the `Default coding level: N` entry in `backbone.yml` `conventions.custom_rules` (show the diff and wait for approval, per kit rules).
+
+## Project default
+
+- First-time init records a default as a `backbone.yml` `conventions.custom_rules` entry: `Default coding level: N (<Register>)`.
+- Sessions without an explicit `/coding-level` start from that default level.
+- `/coding-level N` overrides the default for the current session only, unless the user saves it in step 3.
 
 ## Scope
 

package/.cursor/skills/path-sensitive-shell-safety/SKILL.md

@@ -48,6 +48,7 @@ No empty, unset, broad, symlinked, or unintended path may reach a destructive co
 
 ## Required outcomes
 
+- Prefer a recoverable delete (`trash`) over permanent `rm` for user files; permanent deletion requires explicit confirmation of the exact paths. If `trash` is missing, recommend installing it (macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS with Node `npm i -g trash-cli`).
 - A blank branch may follow the documented default-branch fallback policy.
 - An explicit branch must fail if missing; never silently deploy another branch.
 - A blank folder/base value must fail before any `rm`, `mv`, `cp`, `rsync`, `find`, Docker, or Git cleanup command runs.

package/.vibekit/docs/INSTALL.md

@@ -1,5 +1,17 @@
 # Install guide
 
+## Install from npm
+
+```bash
+# one-shot (recommended) — adds nothing to the project's dependencies:
+npx --yes minimal-vibe-coding-kit@latest install /path/to/project
+
+# or, after `npm i -D minimal-vibe-coding-kit` inside the project:
+npx mvck install .
+```
+
+`npm i` alone only places the kit in `node_modules/` and nothing is active yet; `mvck install` (alias: `vibe-kit`) is the step that copies the kit files into the repo root.
+
 ## Local install
 
 ```bash

package/.vibekit/init/CLAUDE-template.md

@@ -16,11 +16,13 @@ This file is intentionally small. Shared rules live in `AGENTS.md`, project fact
 - `/autoresearch-coding` - run a metric-driven improvement loop.
 - `/security-scan` - run AgentShield-style review.
 - `/daily-enhance` - propose rule, skill, and workflow improvements.
+- `/coding-level N` - set explanation depth 0-5; the project default lives in `backbone.yml` `conventions.custom_rules`.
 
 ## Hard rules
 
 - Show a diff and wait for explicit approval before changing root instruction files, `backbone.yml`, rules, skills, or workflows.
 - Do not deploy, rotate secrets, run migrations, delete data, or rewrite remote history without explicit approval.
+- Prefer `trash` over `rm` for deletions; permanent deletes need explicit approval of the exact paths (see `.claude/rules/safe-delete.md`).
 - Keep `.autoresearch/`, `results.tsv`, and `.vibekit/reports/` local unless the user asks to commit them.
 
 ## English Learning & Grammar Correction

package/.vibekit/init/FIRST_TIME_INIT.md

@@ -69,6 +69,38 @@ Then:
 - Record domain terms and acronyms in `.vibekit/docs/CONTEXT.md` (scaffold from `.vibekit/docs/templates/CONTEXT_TEMPLATE.md`) and link it in `project.context`, so future agents stay concise.
 - Keep the PRD short: it captures intent and focus, not a full specification.
 
+## Setup preferences
+
+Ask these two questions right after the PRD interview. Persist both answers as `backbone.yml` `conventions.custom_rules` entries in the same proposed diff.
+
+### 1. Safe delete (trash instead of rm)
+
+1. Detect first: run `command -v trash` (read-only).
+2. If `trash` is available, ask: "Use `trash` instead of `rm` for deletions so they are recoverable? (recommended: yes)"
+3. If `trash` is missing, recommend installing it, then ask the same question:
+   - macOS 14 or newer: already built in at `/usr/bin/trash`, nothing to install.
+   - Older macOS: `brew install trash` (https://formulae.brew.sh/formula/trash)
+   - Linux: `sudo apt install trash-cli` or `pip install trash-cli` (https://github.com/andreafrancia/trash-cli)
+   - Any OS with Node.js: `npm install --global trash-cli` (https://github.com/sindresorhus/trash-cli)
+4. Record the answer as a custom rule:
+   - yes: `Deletion safety: use trash instead of rm; permanent deletes require explicit approval of the exact paths.`
+   - no: `Deletion safety: user declined trash; list the exact paths and wait for approval before any rm.`
+
+### 2. Default coding level
+
+Show this table exactly and ask: "Which explanation level should I use by default? Reply 0-5. You can change it anytime with `/coding-level N`."
+
+| N | Level | Short description |
+| --- | --- | --- |
+| 0 | ELI5 | New to code. Everything in plain words, no jargon. |
+| 1 | Junior | Knows the basics. Explains the why behind every step. |
+| 2 | Mid-level | Comfortable coder. Patterns, architecture, trade-offs. |
+| 3 | Senior | Concise. Trade-offs, edge cases, operational concerns. |
+| 4 | Tech Lead | Strategic. Risk, ROI, team and organizational impact. |
+| 5 | God | Expert peer. Minimal explanation, maximum signal. |
+
+Record the answer as a custom rule: `Default coding level: N (<Level>) - apply this explanation depth every session; change with /coding-level N.`
+
 ## FIRST_TIME_INIT_RULES
 
 Create project rules from evidence in the existing repo, not from a fixed language or framework template.

package/.vibekit/scripts/doctor.mjs

@@ -153,6 +153,13 @@ function statusLine(ok, label, detail) {
   return `${ok ? 'PASS' : 'WARN'} ${label}${detail ? ` - ${detail}` : ''}`;
 }
 
+const TRASH_INSTALL_HINT = 'macOS 14+ has it built in; older macOS: brew install trash; Linux: sudo apt install trash-cli; any OS with Node: npm i -g trash-cli';
+
+function trashAvailable() {
+  const result = spawnSync('trash', ['--help'], { encoding: 'utf8' });
+  return !(result.error && result.error.code === 'ENOENT');
+}
+
 const backbone = parseBackbone();
 const packageJson = readJson('package.json');
 const isKitTemplate = packageJson?.name === 'minimal-vibe-coding-kit';
@@ -194,8 +201,11 @@ for (const [surface, dir] of Object.entries(nativeSkillSurfaces)) {
 const commands = commandMap();
 const validation = runNodeScript('.vibekit/scripts/validate-kit.mjs');
 const probe = runProbe();
+const hasTrash = trashAvailable();
 const risks = [];
 
+if (!hasTrash) risks.push(`trash command not found; agents fall back to asking before rm. Install it for recoverable deletes (${TRASH_INSTALL_HINT}).`);
+
 if (!backbone) risks.push('backbone.yml is missing.');
 else if (backbone.templateStatus !== 'initialized' && !isKitTemplate) risks.push(`backbone.yml is ${backbone.templateStatus || 'unknown'}; run init before relying on it.`);
 if (!Object.values(surfaces).some(Boolean)) risks.push('No AI agent surfaces were detected.');
@@ -238,6 +248,10 @@ const report = {
     command: probe.command,
     status: probe.status
   },
+  safeDelete: {
+    trashAvailable: hasTrash,
+    installHint: hasTrash ? null : TRASH_INSTALL_HINT
+  },
   aiRulesLoaded: {
     sharedSkills: listFiles('.vibekit/skills').filter((f) => f.endsWith('SKILL.md')).length,
     claudeSkills: listFiles('.claude/skills').filter((f) => f.endsWith('SKILL.md')).length,
@@ -256,7 +270,8 @@ function renderMarkdown(data) {
     statusLine(Boolean(commands.validate), 'validation command detected', commands.validate || 'missing'),
     statusLine(protectedSane, 'protected paths are sane', `${data.protectedPaths.length} entries`),
     statusLine(validation.found && validation.status === 0, 'validation runs', validation.found ? `exit ${validation.status}` : 'missing'),
-    statusLine(probe.found && probe.status === 0, 'AgentShield probe runs', probe.found ? `exit ${probe.status}` : 'missing')
+    statusLine(probe.found && probe.status === 0, 'AgentShield probe runs', probe.found ? `exit ${probe.status}` : 'missing'),
+    statusLine(hasTrash, 'trash command available for safe deletes', hasTrash ? 'deletions are recoverable' : TRASH_INSTALL_HINT)
   ];
 
   return `# Vibe Report

package/.vibekit/scripts/init-backbone.mjs

@@ -1,8 +1,14 @@
 #!/usr/bin/env node
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 const args = process.argv.slice(2);
+
+function trashAvailable() {
+  const result = spawnSync('trash', ['--help'], { encoding: 'utf8' });
+  return !(result.error && result.error.code === 'ENOENT');
+}
 const shouldWrite = args.includes('--write');
 const yes = args.includes('--yes');
 
@@ -619,6 +625,9 @@ if (shouldWrite) {
   console.log(inferred.context === 'none'
     ? '- Offer to create .vibekit/docs/CONTEXT.md (glossary) from .vibekit/docs/templates/CONTEXT_TEMPLATE.md.'
     : `- CONTEXT glossary found at ${inferred.context}; keep it current.`);
+  console.log('\nSetup preferences (record answers in conventions.custom_rules; see FIRST_TIME_INIT.md "Setup preferences"):');
+  console.log(`- Safe delete: trash command ${trashAvailable() ? 'available' : 'NOT found (recommend: macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS `npm i -g trash-cli`)'} - ask: use trash instead of rm? (recommended: yes)`);
+  console.log('- Default coding level: ask 0-5 (0 ELI5, 1 Junior, 2 Mid-level, 3 Senior, 4 Tech Lead, 5 God); changeable later with /coding-level N.');
   console.log('\nConvention review questions:');
   for (const question of inferred.conventions.reviewQuestions) console.log(`- ${question}`);
   console.log('\nProposed backbone.yml:\n');

package/.vibekit/skills/coding-level/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: coding-level
-description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked.
+description: Set the coding-explanation register. /coding-level N (0=ELI5, 1=Junior, 2=Mid, 3=Senior, 4=Tech Lead, 5=God); active until reinvoked. A project default may be recorded in backbone.yml conventions.custom_rules.
 disable-model-invocation: true
 argument-hint: "[0-5]"
 ---
@@ -20,6 +20,13 @@ argument-hint: "[0-5]"
 
 1. Read `$ARGUMENTS` as N. If N is not an integer 0–5, reply with the table above and ask for a valid N.
 2. Read `references/level-<N>.md`, state once which level is now active, and apply that persona to every reply until `/coding-level` is invoked again.
+3. Ask once: "Save level N as the project default?" If yes, add or update the `Default coding level: N` entry in `backbone.yml` `conventions.custom_rules` (show the diff and wait for approval, per kit rules).
+
+## Project default
+
+- First-time init records a default as a `backbone.yml` `conventions.custom_rules` entry: `Default coding level: N (<Register>)`.
+- Sessions without an explicit `/coding-level` start from that default level.
+- `/coding-level N` overrides the default for the current session only, unless the user saves it in step 3.
 
 ## Scope
 

package/.vibekit/skills/path-sensitive-shell-safety/SKILL.md

@@ -48,6 +48,7 @@ No empty, unset, broad, symlinked, or unintended path may reach a destructive co
 
 ## Required outcomes
 
+- Prefer a recoverable delete (`trash`) over permanent `rm` for user files; permanent deletion requires explicit confirmation of the exact paths. If `trash` is missing, recommend installing it (macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS with Node `npm i -g trash-cli`).
 - A blank branch may follow the documented default-branch fallback policy.
 - An explicit branch must fail if missing; never silently deploy another branch.
 - A blank folder/base value must fail before any `rm`, `mv`, `cp`, `rsync`, `find`, Docker, or Git cleanup command runs.

package/AGENTS.md

@@ -31,6 +31,7 @@ Track every loop in `/tmp/design-{project_slug}.md`. Each loop entry must includ
 ### Safety
 
 - Never print full secrets.
+- Prefer `trash` over `rm` for deletions so they stay recoverable. Check `command -v trash` first; if missing, recommend installing it (macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS with Node `npm i -g trash-cli`) instead of falling back to `rm`. Permanent deletes require explicit user approval of the exact paths.
 - Do not run untrusted hooks, MCP servers, deploy scripts, package lifecycle scripts, migrations, or destructive shell commands just to inspect a repo.
 - Do not modify protected paths from `backbone.yml` without explicit approval.
 - Before editing or approving shell/deploy/installer/repair logic that uses path variables or destructive commands (`rm`, `mv`, `cp -a`, `rsync --delete`, `find -delete`, `git clean`, checkout replacement), use `path-sensitive-shell-safety` and prove base/folder/repo values are non-empty, contained, quoted, and not broad system paths.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.4.1 — 2026-07-17
+
+- Added a safe-delete guardrail across all three surfaces: new `.claude/rules/safe-delete.md` and `.cursor/rules/040-safe-delete.mdc` (always-on), a `### Safety` bullet in the `AGENTS.md` managed block for Codex, and a trash-first outcome in the `path-sensitive-shell-safety` skill (all mirrors). Agents prefer the recoverable `trash` command over `rm`, check `command -v trash` first, and recommend an install when missing (macOS 14+ built-in; older macOS `brew install trash`; Linux `sudo apt install trash-cli`; any OS with Node `npm i -g trash-cli`). `rm` was already deny-listed for Claude Code and Cursor in the kit settings.
+- First-time init now asks two setup preferences and records them in `backbone.yml` `conventions.custom_rules`: use `trash` instead of `rm` (with availability detection and install hints), and a default coding level chosen from a 0–5 table with one-line descriptions. Mirrored in the `init-backbone.mjs --propose` interview output.
+- `coding-level` skill (all mirrors): sessions now start from the `Default coding level: N` entry in `backbone.yml` when present; `/coding-level N` still overrides per session and can save a new default with approval. `CLAUDE-template.md` now lists `/coding-level` and the safe-delete rule.
+- `mvck doctor` reports a new safe-delete check: whether the `trash` command is available, with the per-OS install hint when it is not.
+- Fixed the npm package page rendering the Vietnamese README: moved `README.vi.md` to `docs/README.vi.md` so npm's readme detection always picks `README.md`.
+- Added an "Install from npm" section to `README.md`, `docs/README.vi.md`, and `.vibekit/docs/INSTALL.md`: one-shot `npx --yes minimal-vibe-coding-kit@latest install <path>`, or `npm i -D minimal-vibe-coding-kit` followed by `npx mvck install .`, with a note that files in `node_modules/` stay inactive until `mvck install` copies them into the repo root.
+- Switched README install/update/profile examples to the published npm package; the `github:` form and local `install.sh` remain documented as alternatives.
+- Synced version to 0.4.1 in `package.json`, both README badges, and `.codex-plugin/plugin.json`; added an npm badge.
+
 ## 0.4.0 — 2026-07-16
 
 - Trimmed the end-user install payload: `mvck install`/`update` no longer copy kit-maintainer files (`test-install.mjs`, `pack-dry-run.mjs`, `.vibekit/docs/RESEARCH_NOTES.md`, `.vibekit/docs/AUTORESEARCH_LEDGER.md`); `validate-kit` requires them only in the kit source repo.

package/README.md

@@ -1,11 +1,12 @@
 <div align="center">
 
-**Read in:** **English** · [Tiếng Việt](README.vi.md)
+**Read in:** **English** · [Tiếng Việt](docs/README.vi.md)
 
 # Minimal Vibe Coding Kit
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.4.0-2ea44f.svg)](CHANGELOG.md)
+[![npm](https://img.shields.io/badge/npm-minimal--vibe--coding--kit-cb3837?logo=npm)](https://www.npmjs.com/package/minimal-vibe-coding-kit)
+[![Version](https://img.shields.io/badge/version-0.4.1-2ea44f.svg)](CHANGELOG.md)
 ![Claude](https://img.shields.io/badge/Claude%20Code-Commands%20%26%20Skills-111111)
 ![Cursor](https://img.shields.io/badge/Cursor-Rules%20%26%20Commands-1f6feb)
 ![Codex](https://img.shields.io/badge/Codex-AGENTS.md%20%26%20Plugin-6f42c1)
@@ -27,6 +28,8 @@ A small kit of shared **rules**, **skills**, and **commands**, plus one **`backb
 - Never overwrites your existing `CLAUDE.md` / `AGENTS.md` — it only adds managed blocks.
 - Every setup write waits for your explicit approval.
 - Security review of agent surfaces (AgentShield) is part of the normal workflow.
+- Safe deletes by default: `rm` is deny-listed for Claude Code and Cursor, and all agents prefer the recoverable `trash` command (init checks it and recommends an install if missing).
+- First-time init asks two setup preferences — use `trash` instead of `rm`, and your default explanation level (0–5, changeable anytime with `/coding-level N`) — and records both in `backbone.yml`.
 
 ## Quick Start
 
@@ -35,10 +38,10 @@ Three steps, about two minutes.
 **1. Install into your project** (no clone needed):
 
 ```bash
-npx github:giang6283623/minimal-vibe-coding-kit install /path/to/your-project
+npx --yes minimal-vibe-coding-kit@latest install /path/to/your-project
 ```
 
-From a local clone instead: `./install.sh /path/to/your-project` (Windows: `./install.ps1 -Target C:\path\to\your-project`).
+Already ran `npm i minimal-vibe-coding-kit`, or prefer GitHub or a local clone? See [Install from npm](#install-from-npm).
 
 **2. Open the project in Claude Code, Cursor, or Codex and paste:**
 
@@ -58,6 +61,39 @@ Optional health check any time:
 node .vibekit/scripts/mvck.mjs doctor .
 ```
 
+## Install from npm
+
+The kit is published on npm as [`minimal-vibe-coding-kit`](https://www.npmjs.com/package/minimal-vibe-coding-kit). It is a **scaffolding CLI, not a library** — files sitting in `node_modules/` do nothing by themselves. Running `install` once copies the kit into your repo root, exactly like the GitHub installer does.
+
+**Option A — one-shot (recommended).** Nothing is added to your project's dependencies:
+
+```bash
+npx --yes minimal-vibe-coding-kit@latest install /path/to/your-project
+```
+
+**Option B — as a dependency.** If the package is (or will be) in your `package.json`, one more command is required:
+
+```bash
+npm i -D minimal-vibe-coding-kit
+npx mvck install .        # required — copies the kit out of node_modules into your repo
+```
+
+> **Important:** `npm i` alone only downloads the kit into `node_modules/` — nothing is active yet.
+> `mvck install` is the step that copies `.claude/`, `.cursor/`, `.agents/`, `.vibekit/`, and `backbone.yml` into your repo root.
+
+Either way, the short `mvck` command (alias: `vibe-kit`) is then available via `npx`:
+
+| Short command | What it does |
+| --- | --- |
+| `npx mvck install .` | Copy the kit into the repo (`--profile`, `--dry-run`, `--force`) |
+| `npx mvck update .` | Refresh kit-owned files after a new kit release |
+| `npx mvck doctor .` | Read-only health check |
+| `npx mvck validate .` | Structure validation |
+
+Then continue with **step 2** of the Quick Start (paste the init prompt).
+
+Other install paths: `npx github:giang6283623/minimal-vibe-coding-kit install /path/to/your-project`, or from a local clone `./install.sh /path/to/your-project` (Windows: `./install.ps1 -Target C:\path\to\your-project`).
+
 ## What lands in your repo
 
 Install adds exactly this — nothing else in your project is touched:
@@ -149,9 +185,9 @@ All 12 skills live in `.vibekit/skills/` and are mirrored for each tool. Invoke
 Install only the surfaces you use (default is `all`):
 
 ```bash
-npx github:giang6283623/minimal-vibe-coding-kit install . --profile claude          # Claude Code only
-npx github:giang6283623/minimal-vibe-coding-kit install . --profile claude,cursor   # Claude + Cursor
-npx github:giang6283623/minimal-vibe-coding-kit install . --profile codex           # Codex / AGENTS.md agents
+npx --yes minimal-vibe-coding-kit@latest install . --profile claude          # Claude Code only
+npx --yes minimal-vibe-coding-kit@latest install . --profile claude,cursor   # Claude + Cursor
+npx --yes minimal-vibe-coding-kit@latest install . --profile codex           # Codex / AGENTS.md agents
 ```
 
 Flags: `--force` (overwrite existing kit files), `--dry-run` (preview), `--json` (machine-readable plan).
@@ -161,8 +197,8 @@ Flags: `--force` (overwrite existing kit files), `--dry-run` (preview), `--json`
 Run inside your project when the kit ships new skills or scripts:
 
 ```bash
-npx github:giang6283623/minimal-vibe-coding-kit update . --dry-run   # preview
-npx github:giang6283623/minimal-vibe-coding-kit update .             # apply
+npx --yes minimal-vibe-coding-kit@latest update . --dry-run   # preview
+npx --yes minimal-vibe-coding-kit@latest update .             # apply
 ```
 
 `update` refreshes **kit-owned files only**, never touches `backbone.yml` or your own content, updates managed blocks in place, and backs up changed files to `.vibekit/update-backup/<timestamp>/`. Details: [.vibekit/docs/INSTALL.md](.vibekit/docs/INSTALL.md).

package/{README.vi.md → docs/README.vi.md}

@@ -1,11 +1,12 @@
 <div align="center">
 
-**Đọc bằng:** [English](README.md) · **Tiếng Việt**
+**Đọc bằng:** [English](../README.md) · **Tiếng Việt**
 
 # Minimal Vibe Coding Kit
 
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-0.4.0-2ea44f.svg)](CHANGELOG.md)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
+[![npm](https://img.shields.io/badge/npm-minimal--vibe--coding--kit-cb3837?logo=npm)](https://www.npmjs.com/package/minimal-vibe-coding-kit)
+[![Version](https://img.shields.io/badge/version-0.4.1-2ea44f.svg)](../CHANGELOG.md)
 ![Claude](https://img.shields.io/badge/Claude%20Code-Commands%20%26%20Skills-111111)
 ![Cursor](https://img.shields.io/badge/Cursor-Rules%20%26%20Commands-1f6feb)
 ![Codex](https://img.shields.io/badge/Codex-AGENTS.md%20%26%20Plugin-6f42c1)
@@ -27,6 +28,8 @@ Một bộ kit nhỏ gồm **rules**, **skills**, **commands** dùng chung, cộ
 - Không bao giờ ghi đè `CLAUDE.md` / `AGENTS.md` sẵn có — chỉ thêm managed block.
 - Mọi thao tác ghi khi setup đều chờ bạn duyệt.
 - Rà soát bảo mật bề mặt agent (AgentShield) là một phần của workflow bình thường.
+- Xóa an toàn mặc định: `rm` bị deny-list cho Claude Code và Cursor, mọi agent ưu tiên lệnh `trash` (khôi phục được; init sẽ kiểm tra và gợi ý cách cài nếu thiếu).
+- Init lần đầu hỏi hai tùy chọn — dùng `trash` thay `rm`, và mức giải thích mặc định (0–5, đổi bất cứ lúc nào với `/coding-level N`) — rồi lưu cả hai vào `backbone.yml`.
 
 ## Bắt đầu nhanh
 
@@ -35,10 +38,10 @@ Ba bước, khoảng hai phút.
 **1. Cài vào project của bạn** (không cần clone):
 
 ```bash
-npx github:giang6283623/minimal-vibe-coding-kit install /path/to/your-project
+npx --yes minimal-vibe-coding-kit@latest install /path/to/your-project
 ```
 
-Hoặc từ bản clone của repo này: `./install.sh /path/to/your-project` (Windows: `./install.ps1 -Target C:\path\to\your-project`).
+Đã chạy `npm i minimal-vibe-coding-kit`, hoặc muốn cài từ GitHub / bản clone? Xem [Cài từ npm](#cài-từ-npm).
 
 **2. Mở project trong Claude Code, Cursor hoặc Codex và dán:**
 
@@ -58,6 +61,39 @@ Kiểm tra sức khỏe bất cứ lúc nào:
 node .vibekit/scripts/mvck.mjs doctor .
 ```
 
+## Cài từ npm
+
+Kit được publish trên npm với tên [`minimal-vibe-coding-kit`](https://www.npmjs.com/package/minimal-vibe-coding-kit). Đây là **CLI scaffolding, không phải library** — file nằm trong `node_modules/` tự nó không làm gì cả. Chạy `install` một lần sẽ copy kit vào repo root của bạn, giống hệt installer từ GitHub.
+
+**Cách A — chạy một phát (khuyến nghị).** Không thêm gì vào dependencies của project:
+
+```bash
+npx --yes minimal-vibe-coding-kit@latest install /path/to/your-project
+```
+
+**Cách B — cài như dependency.** Nếu bạn đã (hoặc muốn) `npm i` package, cần thêm đúng một lệnh nữa:
+
+```bash
+npm i -D minimal-vibe-coding-kit
+npx mvck install .        # bắt buộc — copy kit từ node_modules ra repo của bạn
+```
+
+> **Quan trọng:** `npm i` một mình chỉ tải kit vào `node_modules/` — chưa có gì hoạt động.
+> `mvck install` mới là bước copy `.claude/`, `.cursor/`, `.agents/`, `.vibekit/` và `backbone.yml` vào repo root.
+
+Sau đó, lệnh ngắn `mvck` (alias: `vibe-kit`) dùng được qua `npx`:
+
+| Lệnh ngắn | Chức năng |
+| --- | --- |
+| `npx mvck install .` | Copy kit vào repo (`--profile`, `--dry-run`, `--force`) |
+| `npx mvck update .` | Làm mới file thuộc kit khi có bản phát hành mới |
+| `npx mvck doctor .` | Health check chỉ-đọc |
+| `npx mvck validate .` | Validate cấu trúc |
+
+Rồi tiếp tục **bước 2** của Bắt đầu nhanh (dán prompt init).
+
+Các cách cài khác: `npx github:giang6283623/minimal-vibe-coding-kit install /path/to/your-project`, hoặc từ bản clone `./install.sh /path/to/your-project` (Windows: `./install.ps1 -Target C:\path\to\your-project`).
+
 ## Những gì được cài vào repo của bạn
 
 Cài đặt chỉ thêm đúng những mục sau — không đụng vào bất cứ thứ gì khác:
@@ -149,9 +185,9 @@ Cả 12 skill nằm trong `.vibekit/skills/` và được mirror cho từng tool
 Chỉ cài các bề mặt bạn dùng (mặc định là `all`):
 
 ```bash
-npx github:giang6283623/minimal-vibe-coding-kit install . --profile claude          # chỉ Claude Code
-npx github:giang6283623/minimal-vibe-coding-kit install . --profile claude,cursor   # Claude + Cursor
-npx github:giang6283623/minimal-vibe-coding-kit install . --profile codex           # Codex / agent dùng AGENTS.md
+npx --yes minimal-vibe-coding-kit@latest install . --profile claude          # chỉ Claude Code
+npx --yes minimal-vibe-coding-kit@latest install . --profile claude,cursor   # Claude + Cursor
+npx --yes minimal-vibe-coding-kit@latest install . --profile codex           # Codex / agent dùng AGENTS.md
 ```
 
 Cờ: `--force` (ghi đè file kit sẵn có), `--dry-run` (xem trước), `--json` (kế hoạch dạng máy đọc).
@@ -161,11 +197,11 @@ Cờ: `--force` (ghi đè file kit sẵn có), `--dry-run` (xem trước), `--js
 Chạy trong project của bạn khi kit có skill hoặc script mới:
 
 ```bash
-npx github:giang6283623/minimal-vibe-coding-kit update . --dry-run   # xem trước
-npx github:giang6283623/minimal-vibe-coding-kit update .             # áp dụng
+npx --yes minimal-vibe-coding-kit@latest update . --dry-run   # xem trước
+npx --yes minimal-vibe-coding-kit@latest update .             # áp dụng
 ```
 
-`update` chỉ làm mới **file thuộc kit**, không bao giờ đụng `backbone.yml` hay nội dung của bạn, cập nhật managed block tại chỗ, và backup file bị thay vào `.vibekit/update-backup/<timestamp>/`. Chi tiết: [.vibekit/docs/INSTALL.md](.vibekit/docs/INSTALL.md).
+`update` chỉ làm mới **file thuộc kit**, không bao giờ đụng `backbone.yml` hay nội dung của bạn, cập nhật managed block tại chỗ, và backup file bị thay vào `.vibekit/update-backup/<timestamp>/`. Chi tiết: [.vibekit/docs/INSTALL.md](../.vibekit/docs/INSTALL.md).
 
 ### Vòng lặp Autoresearch
 
@@ -185,7 +221,7 @@ node .vibekit/scripts/agentshield-probe.mjs .                          # probe c
 npx ecc-agentshield scan --path . --format text --min-severity medium  # scan đầy đủ, tùy chọn
 ```
 
-Mọi thay đổi tới `CLAUDE.md`, `AGENTS.md`, `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`, hoặc `.vibekit/skills|commands|scripts/**` đều nên kích hoạt review. Mô hình: [.vibekit/docs/SECURITY_MODEL.md](.vibekit/docs/SECURITY_MODEL.md).
+Mọi thay đổi tới `CLAUDE.md`, `AGENTS.md`, `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`, hoặc `.vibekit/skills|commands|scripts/**` đều nên kích hoạt review. Mô hình: [.vibekit/docs/SECURITY_MODEL.md](../.vibekit/docs/SECURITY_MODEL.md).
 
 ### Doctor và báo cáo
 
@@ -202,14 +238,14 @@ npm test                # syntax + test cài đặt thật vào thư mục tạm
 npm run validate:all    # npm test + AgentShield probe + npm pack dry-run
 ```
 
-Checklist publish: [.vibekit/init/PUSH_TO_GITHUB.md](.vibekit/init/PUSH_TO_GITHUB.md). Tài liệu sâu hơn: [.vibekit/docs/](.vibekit/docs/).
+Checklist publish: [.vibekit/init/PUSH_TO_GITHUB.md](../.vibekit/init/PUSH_TO_GITHUB.md). Tài liệu sâu hơn: [.vibekit/docs/](../.vibekit/docs/).
 
 <details>
 <summary><strong>Khắc phục sự cố</strong></summary>
 
 | Triệu chứng | Cách xử lý |
 | --- | --- |
-| Agent bỏ qua luồng init | Chạy lại installer, hoặc copy [.vibekit/init/CLAUDE-template.md](.vibekit/init/CLAUDE-template.md) thành `CLAUDE.md`. |
+| Agent bỏ qua luồng init | Chạy lại installer, hoặc copy [.vibekit/init/CLAUDE-template.md](../.vibekit/init/CLAUDE-template.md) thành `CLAUDE.md`. |
 | Agent hỏi init lại mỗi phiên | Chạy init và duyệt; xác nhận `meta.template_status: initialized` trong `backbone.yml`. |
 | Dò sai stack | Xóa lockfile cũ, hoặc sửa `backbone.yml` trực tiếp. |
 | Agent chạm path không nên | Thêm path vào `policy.protected_paths` trong `backbone.yml` (hỗ trợ glob). |
@@ -220,13 +256,13 @@ Checklist publish: [.vibekit/init/PUSH_TO_GITHUB.md](.vibekit/init/PUSH_TO_GITHU
 
 ## Đóng góp
 
-Issue và PR luôn welcome tại [`giang6283623/minimal-vibe-coding-kit`](https://github.com/giang6283623/minimal-vibe-coding-kit). Trước khi mở PR: mirror thay đổi skill giữa `.claude/`, `.cursor/`, `.agents/`, giữ template trung lập, và chạy `npm run validate:all`. Xem [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+Issue và PR luôn welcome tại [`giang6283623/minimal-vibe-coding-kit`](https://github.com/giang6283623/minimal-vibe-coding-kit). Trước khi mở PR: mirror thay đổi skill giữa `.claude/`, `.cursor/`, `.agents/`, giữ template trung lập, và chạy `npm run validate:all`. Xem [CONTRIBUTING.md](../CONTRIBUTING.md), [SECURITY.md](../SECURITY.md), [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md).
 
 **Tác giả:** [GiangBV](https://www.linkedin.com/in/buivangiang1992), [AuPMH](https://www.linkedin.com/in/pham-au-2a1bb1162)
 **Powered by:** Caffeine, Determination, AI Collaboration, và những đêm code cuối tuần.
 
 ## Giấy phép
 
-MIT. Xem [LICENSE](LICENSE).
+MIT. Xem [LICENSE](../LICENSE).
 
 > 🇻🇳 *Nếu bạn yêu Việt Nam và con người Việt Nam, bạn hoàn toàn được dùng miễn phí mọi thứ trong đây.*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-vibe-coding-kit",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Project-agnostic AI coding workflow kit for Claude Code, Cursor, and Codex with AgentShield security review.",
   "type": "module",
   "bin": {
@@ -78,7 +78,7 @@
     "install.sh",
     "install.ps1",
     "README.md",
-    "README.vi.md",
+    "docs/README.vi.md",
     "SECURITY.md",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md",