minimal-vibe-coding-kit 0.3.0 → 0.4.1

package/.cursor/rules/030-autoresearch-loop.mdc

@@ -1,6 +1,6 @@
 ---
 description: Metric-driven autoresearch loop rules for repeated repo improvement.
-globs: ["src/**", "app/**", "lib/**", ".vbkit-docs/**", "skills/**", ".vbkit-scripts/**", ".vbkit-commands/**", ".claude/**", ".cursor/**", ".agents/**"]
+globs: ["src/**", "app/**", "lib/**", ".vibekit/docs/**", ".vibekit/skills/**", ".vibekit/scripts/**", ".vibekit/commands/**", ".claude/**", ".cursor/**", ".agents/**"]
 alwaysApply: false
 ---
 

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/parallel-analysis/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: parallel-analysis
+description: Fan out 2-5 independent read-only analysis lanes across the repo using your configured executor (Cursor CLI Composer, Claude subagents, or Codex CLI), then merge the lane reports and verify them with a refutation pass. Use for repo-wide questions, large uncommitted-diff reviews, multi-doc reading, impact analysis, or consistency audits. On first use it asks which provider/model to use and saves the answer so it never asks again.
+argument-hint: "<analysis question, diff, or review target>"
+user-invocable: true
+effort: medium
+---
+
+# Parallel Analysis (Multi-Agent Fan-Out)
+
+Split a large analysis into independent read-only lanes, run them concurrently
+with the configured executor, merge the lane reports, and verify merged claims
+with a skeptical refutation pass. One round of parallel lanes replaces slow
+serial reading; the verification lane replaces manual double-checking.
+
+This skill is project-agnostic: it works in any repo where the kit is
+installed, using that repo's `backbone.yml` (if present) for boundaries.
+
+## Best Use
+
+- Repo-wide questions ("where is X handled, what depends on Y").
+- Reviewing a large uncommitted diff by concern (backend vs frontend vs i18n
+  vs scripts).
+- Reading several large docs, plans, or reference trees at once.
+- Pre-change impact analysis across packages/apps listed in `backbone.yml`
+  `paths.apps`.
+- Consistency audits (docs vs code, rules vs skills, config vs actual layout).
+
+Do NOT use for single-file questions or quick lookups; direct reads are faster.
+
+## Executor Setup (first use only)
+
+Lane execution is delegated to ONE configured executor. The choice is stored
+in `.vibekit/parallel-analysis.json`; while that file exists and its preflight
+passes, NEVER ask again.
+
+1. **If `.vibekit/parallel-analysis.json` exists**: read it, run the matching
+   preflight below, and proceed silently on success. If preflight fails
+   (binary missing, logged out), tell the user what broke, offer to re-run
+   setup, and update the file with their answer.
+2. **If it does not exist**: detect what is available, then ask the user ONE
+   question — "Which provider should run parallel analysis lanes?" — using the
+   harness-native prompt (AskUserQuestion in Claude Code; a plain chat
+   question in Cursor/Codex). Offer, in this order:
+   - **Cursor CLI + Composer 2.5 Fast (recommended)** — fastest lane executor;
+     requires `cursor-agent` installed and logged in.
+   - **Claude subagents** — no extra install; lanes run as read-only Claude
+     Code subagents (Explore/general-purpose). Choose this automatically if
+     the user declines external CLIs.
+   - **Codex CLI** — lanes run via `codex exec` in a read-only sandbox with
+     the best available Codex model.
+3. **Resolve the model** for the chosen provider (see per-executor notes),
+   confirm the resolved value in one line, and write the config file. Include
+   a fallback executor so lanes still run when the primary is unavailable.
+
+### Preflights and model resolution
+
+- `cursor-cli`: `cursor-agent status` must report logged in (otherwise the
+  user runs `cursor-agent login` once). Resolve the model with
+  `cursor-agent --list-models` and prefer the Composer 2.5 fast variant
+  (e.g. `composer-2.5-fast`); if absent, use the newest Composer model and
+  record what was picked.
+- `claude-subagents`: available whenever running inside Claude Code; no
+  binary needed. Use read-only subagent types only.
+- `codex-cli`: `codex --version` must succeed. Use the CLI's default/best
+  coding model unless the user names one; record the resolved model.
+
+### Config file — `.vibekit/parallel-analysis.json`
+
+```json
+{
+  "executor": "cursor-cli",
+  "model": "composer-2.5-fast",
+  "fallback": "claude-subagents",
+  "configuredAt": "2026-07-16T07:30:00Z"
+}
+```
+
+`executor` is one of `cursor-cli` | `claude-subagents` | `codex-cli`. The file
+is local state (gitignored by default); a team may commit it deliberately to
+share a default. To change the choice later, delete the file or ask for
+"parallel-analysis setup" again.
+
+## Running a lane (per executor)
+
+Every lane is READ-ONLY: search, read, summarize — never edit files, execute
+project binaries, run hooks, or trigger installs/deploys/migrations.
+
+- `cursor-cli`:
+
+  ```sh
+  cursor-agent -p --mode ask --output-format text \
+    --model "<configured-model>" \
+    --workspace "<repo-root>" \
+    "<lane brief>"
+  ```
+
+  Never pass `--force` or `--yolo`; `--mode ask` keeps Composer read-only.
+  One workspace per lane; a question spanning multiple repos becomes one lane
+  per repo.
+- `claude-subagents`: launch each lane as a read-only subagent with the lane
+  brief as its prompt, all lanes in ONE message so they run concurrently.
+- `codex-cli`:
+
+  ```sh
+  codex exec --sandbox read-only -C "<repo-root>" "<lane brief>"
+  ```
+
+If the harness cannot run lanes concurrently (plain CLI loop), run them
+back-to-back without changing the briefs — merge and verification stay the
+same.
+
+## Workflow
+
+1. **Scope.** State the question in one sentence. Split it into 2-5 lanes that
+   are independent of each other (by directory, package, concern, or doc set).
+   If lanes would depend on each other's output, merge them or run two rounds.
+2. **Brief.** Give each lane a numbered brief: exact paths, the questions to
+   answer, and the required return format ("facts only, numbered sections,
+   findings as `file:line — issue — why it matters`").
+3. **Launch all lanes at once** with the configured executor.
+4. **Prepare while waiting.** Build the merge skeleton; do not duplicate lane
+   work.
+5. **Merge.** Combine lane reports into one findings list. Mark conflicts
+   between lanes and unknowns explicitly — never average away a disagreement.
+6. **Verify.** Run one verification lane that receives the merged claims (not
+   the reasoning) with the instruction: "Default-skeptical: confirm or refute
+   each claim against the repo with file:line evidence." Drop or re-investigate
+   every refuted claim; never silently keep one.
+7. **Deliver.** Report merged findings, what was verified, and remaining
+   unknowns. For issue triage, classify surviving findings with the
+   `reviewing-4p-priorities` skill (P0-P4). Decisions and edits stay in the
+   main session under the repo's normal review rules.
+
+## Lane brief template
+
+```text
+Lane <n>: <one-line purpose>
+Workspace: <repo root>
+Paths: <exact dirs/files>
+Read-only. Do not modify anything or execute binaries/scripts.
+Questions:
+1. <specific question>
+2. <specific question>
+Return: numbered sections matching the questions, facts only,
+findings as file:line — issue — why it matters.
+```
+
+## Guardrails
+
+- 2-5 lanes per round; needing more means the question is under-scoped.
+- Lanes are read-only; only the main session edits files. Agent-surface edits
+  (`backbone.yml`, `AGENTS.md`, `CLAUDE.md`, `.claude/**`, `.cursor/**`,
+  `.agents/**`, `.codex/**`, kit skills/commands) additionally require the
+  `agentshield-security-review` skill afterwards.
+- Respect `backbone.yml` `policy.protected_paths` in every lane brief.
+- Never put secrets in lane briefs or executor prompts: no `.env*` contents,
+  credentials, tokens, private keys, or customer data.
+- This skill produces analysis, not decisions; a lane may not conclude
+  "therefore change X" without main-session review.

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

@@ -0,0 +1,69 @@
+---
+name: path-sensitive-shell-safety
+description: Guardrail workflow for shell changes that use path variables, remote base directories, repo folders, checkout repair, or destructive filesystem commands such as rm, mv, cp, rsync, find -delete, git clean, or git reset.
+argument-hint: "<script path, command, or safety review target>"
+user-invocable: true
+effort: medium
+---
+
+# Path-Sensitive Shell Safety
+
+Use this skill before editing or reviewing shell, deploy, installer, cleanup, or repair logic that builds filesystem paths from variables or touches remote repositories.
+
+Common triggers:
+
+- Path variables such as `remote_base`, `repo_dir`, `repo_folder`, `target_dir`, `backup_dir`, `worktree`, `site`, `app`, or user-entered folder names.
+- Destructive or path-sensitive commands: `rm`, `mv`, `cp -a`, `rsync --delete`, `find -delete`, `docker volume rm`, `git clean`, `git reset`, checkout repair, clone replacement, or symlink-sensitive copy.
+- Git sync that decides which branch or remote checkout will be deployed.
+
+## Safety objective
+
+No empty, unset, broad, symlinked, or unintended path may reach a destructive command. Validate values before joining paths, validate the joined path before use, and validate containment immediately before the command.
+
+## Required workflow
+
+1. Identify the command with the highest blast radius.
+2. List every variable that contributes to its path or repository target.
+3. Classify each variable:
+   - trusted constant;
+   - config value;
+   - remote/server value;
+   - user/operator input;
+   - derived path.
+4. Validate raw inputs before joining:
+   - required and non-empty;
+   - expected shape: absolute base path or safe single folder segment;
+   - no traversal, newlines, glob metacharacters, leading option dash, or control characters;
+   - explicit allowlist for server roots when possible.
+5. Join paths with quoted expansions only. Do not use `eval`.
+6. Canonicalize existing paths with physical resolution (`pwd -P` or `realpath`) before destructive work.
+7. Assert containment:
+   - target is inside the approved base;
+   - target is not `/`, `.`, `..`, `$HOME`, the base root itself, or another broad system directory;
+   - target is not a symlink unless the operation explicitly supports symlinks.
+8. Put the final guard directly next to the dangerous command.
+9. Use command terminators and quoting: `-- "$path"` where supported.
+10. For Git sync, verify expected origin, selected branch policy, fetch success, clean worktree, fast-forward state, and final `HEAD == origin/<branch>` before build/deploy.
+11. Run the repo validation command and AgentShield probe when this changes agent surfaces or automation rules.
+
+## 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.
+- A repair flow may move an unusable checkout to a timestamped backup only after a verified replacement exists.
+- No automatic cleanup should delete backups, locks, runtime data, uploads, volumes, databases, or environment files without separate explicit confirmation.
+
+## Review priority
+
+Use `reviewing-4p-priorities` if triage is needed:
+
+- P0: unsafe path command already caused data loss or can expose/delete secrets in the active environment.
+- P1: unchecked empty/broad variable can reach destructive commands in deploy/repair/install paths.
+- P2: guard exists but misses edge cases such as symlinks, traversal, explicit branch fallback, or wrong origin.
+- P3/P4: documentation clarity or minor naming improvements after the safety invariant is already enforced.
+
+## Reference
+
+Use `references/workflow.md` for copy-ready guard patterns and review checklist.

package/.cursor/skills/path-sensitive-shell-safety/references/workflow.md

@@ -0,0 +1,127 @@
+# Path-Sensitive Shell Safety Reference
+
+This reference gives reusable guard patterns for shell scripts. Adapt names and allowlists to the repo, but keep the invariant: validate raw input, validate the joined path, then guard immediately before the dangerous command.
+
+## Baseline guard functions
+
+```bash
+die() {
+  printf 'ERROR: %s\n' "$*" >&2
+  exit 1
+}
+
+require_nonempty() {
+  local name="${1:?missing name}"
+  local value="${2-}"
+  [[ -n "$value" ]] || die "$name is required"
+  [[ "$value" != *$'\n'* && "$value" != *$'\r'* ]] || die "$name contains a newline"
+}
+
+validate_abs_base_path() {
+  local name="${1:?missing name}"
+  local value="${2-}"
+  require_nonempty "$name" "$value"
+  [[ "$value" == /* ]] || die "$name must be an absolute path: $value"
+  [[ "$value" != "/" && "$value" != "." && "$value" != ".." ]] || die "$name is too broad: $value"
+  [[ "$value" != *"/../"* && "$value" != *"/./"* && "$value" != *"//"* ]] || die "$name contains unsafe traversal: $value"
+  case "$value" in
+    /bin|/boot|/dev|/etc|/home|/lib|/lib64|/opt|/private|/root|/sbin|/srv|/sys|/tmp|/usr|/var)
+      die "$name points at a broad system directory: $value"
+      ;;
+  esac
+}
+
+validate_folder_segment() {
+  local name="${1:?missing name}"
+  local value="${2-}"
+  require_nonempty "$name" "$value"
+  [[ "$value" != -* ]] || die "$name must not start with '-': $value"
+  [[ "$value" != "." && "$value" != ".." ]] || die "$name is unsafe: $value"
+  [[ "$value" != */* && "$value" != *\\* ]] || die "$name must be one folder segment: $value"
+  [[ "$value" =~ ^[A-Za-z0-9._#@+=:-]+$ ]] || die "$name contains unsupported characters: $value"
+}
+
+join_child_path() {
+  local base="${1:?missing base}"
+  local child="${2:?missing child}"
+  printf '%s/%s\n' "${base%/}" "$child"
+}
+```
+
+## Containment guard
+
+```bash
+canonical_existing_dir() {
+  local path_value="${1:?missing path}"
+  [[ -d "$path_value" ]] || die "not a directory: $path_value"
+  [[ ! -L "$path_value" ]] || die "refusing symlink directory: $path_value"
+  (cd -P -- "$path_value" && pwd) || die "cannot resolve directory: $path_value"
+}
+
+assert_child_under_parent() {
+  local parent="${1:?missing parent}"
+  local child="${2:?missing child}"
+  [[ "$child" != "$parent" ]] || die "refusing to operate on parent directory itself: $child"
+  case "$child" in
+    "$parent"/*) ;;
+    *) die "path escapes parent: child=$child parent=$parent" ;;
+  esac
+}
+```
+
+## Safer remove wrapper
+
+Use a wrapper instead of inline deletion when a path contains variables.
+
+```bash
+safe_rm_rf_dir() {
+  local label="${1:?missing label}"
+  local target="${2-}"
+  local allowed_parent="${3-}"
+
+  validate_abs_base_path "$label target" "$target"
+  validate_abs_base_path "$label allowed parent" "$allowed_parent"
+
+  [[ -d "$target" ]] || die "$label target is not an existing directory: $target"
+  [[ ! -L "$target" ]] || die "$label target is a symlink: $target"
+
+  local parent_real
+  parent_real="$(canonical_existing_dir "$allowed_parent")"
+
+  local target_real
+  target_real="$(canonical_existing_dir "$target")"
+
+  assert_child_under_parent "$parent_real" "$target_real"
+  rm -rf -- "$target_real"
+}
+```
+
+Never call the wrapper with a broad parent such as `/`, `/opt`, `/var`, `/tmp`, or `$HOME`. Use the narrowest app-owned parent.
+
+## Git sync guard checklist
+
+- Validate the checkout directory is inside the approved app base.
+- Validate the origin URL or host matches the expected repository.
+- Fetch with bounded timeout and non-interactive credentials.
+- Explicit branch:
+  - require the exact remote branch;
+  - fail with an actionable message if it is missing.
+- Blank branch:
+  - current valid upstream;
+  - remote default branch;
+  - `main`;
+  - `master`.
+- Refuse dirty, local-ahead, or diverged worktrees unless the operator chooses a guided repair command.
+- After sync, verify `git rev-parse HEAD` equals `git rev-parse "origin/<branch>"`.
+- Build or deploy only after the equality check passes.
+
+## Review checklist
+
+- Are all path variables checked with `[[ -n "$value" ]]` or a stronger helper before use?
+- Are folder names validated as segments before joining?
+- Is the final path canonicalized or otherwise proven inside the base?
+- Is the destructive command adjacent to its guard?
+- Does the command use quoted expansions and `--` where available?
+- Does the code fail closed for missing explicit branches?
+- Does repair preserve runtime data and keep backups instead of deleting them?
+- Does validation cover empty values, traversal, symlink, wrong origin, dirty checkout, branch with `#`, and missing branch?

package/.vibekit/commands/vibe-finalize.md

@@ -0,0 +1,3 @@
+# vibe-finalize
+
+Graduate this project once init and the first prompt are complete. Run `node .vibekit/scripts/vibekit-finalize.mjs . --propose` to preview, then `--write --yes` to move one-time bootstrap files (.vibekit/init/FIRST_TIME_INIT.md, .vibekit/init/FIRST_PROMPT.md, .vibekit/init/PUSH_TO_GITHUB.md, .vibekit/init/CLAUDE-template.md) into `_vibekit-cleanup/` for deletion. It refuses to run on the kit source repo and is reversible with `--restore --write`.

package/{.vbkit-docs → .vibekit/docs}/AUTORESEARCH_LEDGER.md

@@ -4,8 +4,8 @@ This file summarizes the improvement loop used to build and maintain the enhance
 
 | Experiment | Metric | Result | Kept reason |
 |---|---:|---|---|
-| Baseline review | `node .vbkit-scripts/validate-kit.mjs .` -> `171/0f/0w` | keep | established current kit health before new edits |
-| Package manifest coverage | `node .vbkit-scripts/validate-kit.mjs .` -> `215/0f/0w` | keep | validates npm bin targets and shipped `files` entries |
-| Codex and CI coverage | `node .vbkit-scripts/validate-kit.mjs .` -> `221/0f/0w` | keep | validates Codex support files and core CI workflow commands |
+| Baseline review | `node .vibekit/scripts/validate-kit.mjs .` -> `171/0f/0w` | keep | established current kit health before new edits |
+| Package manifest coverage | `node .vibekit/scripts/validate-kit.mjs .` -> `215/0f/0w` | keep | validates npm bin targets and shipped `files` entries |
+| Codex and CI coverage | `node .vibekit/scripts/validate-kit.mjs .` -> `221/0f/0w` | keep | validates Codex support files and core CI workflow commands |
 
 Final validation results for each run are recorded in `.autoresearch/logs/` and summarized in `results.tsv`.

package/{.vbkit-docs → .vibekit/docs}/BACKBONE_REFERENCE.md

@@ -17,7 +17,7 @@
 
 `meta.template_status` is the durable init flag.
 
-- `uninitialized`: agent must run `FIRST_TIME_INIT.md`.
+- `uninitialized`: agent must run `.vibekit/init/FIRST_TIME_INIT.md`.
 - `initialized`: agent skips init and proceeds.
 
 `.vibekit/INIT_DONE` is a local cache only. It helps prevent same-machine repeat init, but does not need to be committed.

package/{.vbkit-docs → .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
@@ -9,7 +21,7 @@
 ## Node install
 
 ```bash
-node .vbkit-scripts/mvck.mjs install /path/to/project --profile all
+node .vibekit/scripts/mvck.mjs install /path/to/project --profile all
 ```
 
 Profiles:
@@ -31,8 +43,8 @@ The installer:
 Preview without writing:
 
 ```bash
-node .vbkit-scripts/mvck.mjs install /path/to/project --profile all --dry-run
-node .vbkit-scripts/mvck.mjs install /path/to/project --profile all --dry-run --json
+node .vibekit/scripts/mvck.mjs install /path/to/project --profile all --dry-run
+node .vibekit/scripts/mvck.mjs install /path/to/project --profile all --dry-run --json
 ```
 
 ## Update an existing project
@@ -42,12 +54,12 @@ When a newer kit version ships, refresh kit-owned files without touching user-ow
 ```bash
 npx --yes minimal-vibe-coding-kit@latest update .
 # or from a local kit clone:
-node /path/to/kit/.vbkit-scripts/mvck.mjs update /path/to/project
+node /path/to/kit/.vibekit/scripts/mvck.mjs update /path/to/project
 ```
 
 The updater:
 
-- refreshes kit-owned surfaces (`skills/`, `.vbkit-commands/`, `.vbkit-scripts/`, `.vbkit-docs/`, and the `.claude/`, `.cursor/`, `.agents/`, `.codex*` mirrors) and adds any new kit skills;
+- refreshes kit-owned surfaces (`.vibekit/skills/`, `.vibekit/commands/`, `.vibekit/scripts/`, `.vibekit/docs/`, and the `.claude/`, `.cursor/`, `.agents/`, `.codex*` mirrors) and adds any new kit skills;
 - never overwrites `backbone.yml`, `CLAUDE.md`, `AGENTS.md` content outside the managed block, or `settings.json` files — those are seeded only if missing;
 - backs up every replaced kit file to `.vibekit/update-backup/<timestamp>/` (disable with `--no-backup`);
 - never deletes files you added, and skips re-seeding one-time files after `mvck finalize`;
@@ -60,30 +72,30 @@ npx --yes minimal-vibe-coding-kit@latest update . --dry-run
 npx --yes minimal-vibe-coding-kit@latest update . --dry-run --json
 ```
 
-Note: run the updater from a newer kit (npx or a local clone), not via the project's own `.vbkit-scripts/mvck.mjs` copy — source and target would be the same files.
+Note: run the updater from a newer kit (npx or a local clone), not via the project's own `.vibekit/scripts/mvck.mjs` copy — source and target would be the same files.
 
 ## After install
 
-Paste the universal prompt from `FIRST_PROMPT.md`, or run:
+Paste the universal prompt from `.vibekit/init/FIRST_PROMPT.md`, or run:
 
 ```bash
-node .vbkit-scripts/init-backbone.mjs . --propose
+node .vibekit/scripts/init-backbone.mjs . --propose
 ```
 
 Use a preset when you already know the target stack:
 
 ```bash
-node .vbkit-scripts/mvck.mjs init . --preset nextjs --propose
-node .vbkit-scripts/mvck.mjs init . --preset wordpress --propose
-node .vbkit-scripts/mvck.mjs init . --preset python --propose
-node .vbkit-scripts/mvck.mjs init . --preset laravel --propose
-node .vbkit-scripts/mvck.mjs init . --preset docker --propose
+node .vibekit/scripts/mvck.mjs init . --preset nextjs --propose
+node .vibekit/scripts/mvck.mjs init . --preset wordpress --propose
+node .vibekit/scripts/mvck.mjs init . --preset python --propose
+node .vibekit/scripts/mvck.mjs init . --preset laravel --propose
+node .vibekit/scripts/mvck.mjs init . --preset docker --propose
 ```
 
 Review the proposal. After approval:
 
 ```bash
-node .vbkit-scripts/init-backbone.mjs . --write --yes
+node .vibekit/scripts/init-backbone.mjs . --write --yes
 ```
 
 ## Doctor
@@ -91,13 +103,13 @@ node .vbkit-scripts/init-backbone.mjs . --write --yes
 Run a read-only health check after install:
 
 ```bash
-node .vbkit-scripts/mvck.mjs doctor .
+node .vibekit/scripts/mvck.mjs doctor .
 ```
 
 Generate a handoff report:
 
 ```bash
-node .vbkit-scripts/mvck.mjs doctor . --write-report
+node .vibekit/scripts/mvck.mjs doctor . --write-report
 ```
 
 ## Native reasoning skills

package/{.vbkit-docs → .vibekit/docs}/RESEARCH_NOTES.md

@@ -14,7 +14,7 @@ The kit follows these design decisions:
 
 ```text
 Goal: improve Minimal Vibe Coding Kit quality.
-Metric command: node .vbkit-scripts/validate-kit.mjs .
+Metric command: node .vibekit/scripts/validate-kit.mjs .
 Direction: higher pass count and zero failures.
 Editable paths: docs, scripts, skills, commands, .claude, .cursor, .agents, .codex-plugin, .github, root templates.
 Protected paths: .git, .env*, node_modules, vendor packages, secrets, lockfiles.

package/{.vbkit-docs → .vibekit/docs}/SECURITY_MODEL.md

@@ -6,7 +6,7 @@ Review these before merging changes:
 
 - `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
 - `.claude/**`, `.cursor/**`, `.agents/**`, `.codex-plugin/**`
-- `skills/**`, `.vbkit-commands/**`, `.vbkit-scripts/**`, `hooks/**`
+- `.vibekit/skills/**`, `.vibekit/commands/**`, `.vibekit/scripts/**`, `hooks/**`
 - `.mcp.json`, `mcp.json`, `mcp-configs/**`
 - installer scripts and CI workflows
 
@@ -15,7 +15,7 @@ Review these before merging changes:
 Read-only probe:
 
 ```bash
-node .vbkit-scripts/agentshield-probe.mjs .
+node .vibekit/scripts/agentshield-probe.mjs .
 ```
 
 Full scanner when available:

package/{.vbkit-docs → .vibekit/docs}/TOOLING_GUIDE.md

@@ -2,7 +2,7 @@
 
 ## Claude Code
 
-Use root `CLAUDE.md` plus project skills in `.claude/skills/`. Keep long instructions out of `CLAUDE.md` and in skills. The kit provides shims that point to canonical shared skills under `skills/`.
+Use root `CLAUDE.md` plus project skills in `.claude/skills/`. Keep long instructions out of `CLAUDE.md` and in skills. The kit provides shims that point to canonical shared skills under `.vibekit/skills/`.
 
 ## Cursor
 
@@ -14,7 +14,7 @@ Use `AGENTS.md` for repo instructions and `.agents/skills/*/SKILL.md` for skills
 
 ## Shared skill strategy
 
-Canonical skill bodies live in `skills/<skill-name>/`. Harness-specific folders contain small shims:
+Canonical skill bodies live in `.vibekit/skills/<skill-name>/`. Harness-specific folders contain small shims:
 
 - `.claude/skills/<skill-name>/SKILL.md`
 - `.agents/skills/<skill-name>/SKILL.md`

package/{.vbkit-docs → .vibekit/docs}/templates/CONTEXT_TEMPLATE.md

@@ -43,5 +43,5 @@ Non-obvious things that have surprised people. Save the next agent the debugging
 
 ---
 
-Related: `.vbkit-docs/PRD.md` (intent and focus) and `backbone.yml` (project map, commands,
+Related: `.vibekit/docs/PRD.md` (intent and focus) and `backbone.yml` (project map, commands,
 protected paths). Link `project.context` in `backbone.yml` to this file.

package/{.vbkit-docs → .vibekit/docs}/templates/PRD_TEMPLATE.md

@@ -44,5 +44,5 @@ If existing code: which module, surface, or flow are we improving first, and why
 
 ---
 
-Linked context: see `.vbkit-docs/CONTEXT.md` for domain terminology and `backbone.yml`
+Linked context: see `.vibekit/docs/CONTEXT.md` for domain terminology and `backbone.yml`
 for the project map (`project.mode`, `project.prd`, conventions, commands).

package/{CLAUDE-template.md → .vibekit/init/CLAUDE-template.md}

@@ -7,7 +7,7 @@ This file is intentionally small. Shared rules live in `AGENTS.md`, project fact
 ## Startup
 
 1. Read `backbone.yml`.
-2. If `meta.template_status` is `uninitialized`, follow `FIRST_TIME_INIT.md` before other work.
+2. If `meta.template_status` is `uninitialized`, follow `.vibekit/init/FIRST_TIME_INIT.md` before other work.
 3. If initialized, follow `backbone.yml` `conventions` and continue with the user's task.
 
 ## Useful skills
@@ -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