hive-lite 0.1.1 → 0.1.3

package/README.md

@@ -78,8 +78,9 @@ When you pass `next --agent <codex|claude|gemini>` or `next --path <skills-dir>`
 
 ### Install Agent Skills
 
-Hive Lite ships three operator skills:
+Hive Lite ships four operator skills:
 
+- `hive-lite-bootstrap`
 - `hive-lite-start-prompt`
 - `hive-lite-finish`
 - `hive-lite-map-maintainer`
@@ -235,6 +236,8 @@ node bin/hive.js map-dump
 
 Hive Lite requires a git repository. If the current directory is not inside a git worktree, `status` and `next` will report `repo_setup_required`, and workflow commands such as `init`, `find`, `check`, `validate`, and `accept` stop. Hive Lite does not initialize git automatically; switch to the correct repo root or manually initialize git and create an initial commit first.
 
+Inside a git repo, `status` reports `hive_init_required` until the repo has been initialized with `hive-lite init`. `next` recommends `$hive-lite-bootstrap`, which is the first-time setup skill that may run init, build the first Project Map, and prepare the setup/map commit before product work starts.
+
 Committed by default:
 
 ```text
@@ -264,6 +267,8 @@ node bin/hive.js next --json
 
 Typical `phaseGuess` values:
 
+- `repo_setup_required`: current directory is not inside a git repo
+- `hive_init_required`: use `$hive-lite-bootstrap` for first-time setup before product work
 - `preflight`: dirty worktree must be committed, stashed, isolated, or stopped before a new requirement
 - `finish`: an in-progress or accepted-uncommitted Hive change should be closed with `$hive-lite-finish`
 - `map`: Project Map needs bootstrap, refresh, or repair via `$hive-lite-map-maintainer`
@@ -287,6 +292,8 @@ node bin/hive.js status --json
 
 It classifies the current repo as:
 
+- `repo_setup_required`: not inside a git worktree
+- `hive_init_required`: git repo exists, but required Hive Lite setup files are missing
 - `clean`: safe to start a new `find`
 - `unmanaged_dirty`: dirty files are not tied to a Hive Change Record
 - `in_progress`: dirty files belong to an unfinished Hive Change Record

package/docs/cli-semantics.md

@@ -35,6 +35,7 @@ Human output explains the result. JSON output is a stable contract with fields s
 It reads:
 
 - git repo presence
+- Hive Lite initialization state
 - worktree state
 - latest Hive Change Record
 - Project Map health
@@ -51,6 +52,7 @@ Hive Lite cannot detect the currently running agent CLI. If the caller provides
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `repo_setup_required` | Current directory is not inside a git repo. | Stop. Switch to the correct repo root, or manually initialize git and create an initial commit before using Hive Lite. |
+| `hive_init_required` | Current git repo does not have required Hive Lite setup files. | Use `$hive-lite-bootstrap` for first-time setup before product work. |
 | `skill_preflight` | The selected agent target is missing the operator skill needed for the next Hive Lite step. | Run the recommended `skills install` or `skills sync`, then rerun `next`. |
 | `preflight` | Worktree has unmanaged dirty changes. | Stop before starting new work. Commit, stash, use a separate worktree, or stop. |
 | `finish` | A Hive change is in progress, or was accepted without commit. | Use `$hive-lite-finish` to check, validate, record evidence, accept, or commit. |
@@ -101,6 +103,7 @@ node bin/hive.js status --json
 | Value | Meaning | What To Do |
 | --- | --- | --- |
 | `repo_setup_required` | Not inside a git worktree. | Stop. Do not auto-run `git init`. |
+| `hive_init_required` | Inside a git worktree, but required Hive Lite setup files are missing. | Stop ordinary start/finish/map-maintainer skills. Use `$hive-lite-bootstrap` for first-time setup, or run `hive-lite init` manually as the low-level fallback. |
 | `clean` | Worktree is clean. | It is safe to start `find`. |
 | `unmanaged_dirty` | Dirty files are not tied to a Hive Change Record. | Stop and ask the human to commit, stash, use a worktree, or stop. |
 | `in_progress` | Dirty files belong to an unfinished Hive Change Record. | Continue finish flow: `check`, `validate`, manual evidence, or `accept`. |
@@ -155,6 +158,7 @@ Hive Lite does not detect which agent CLI is installed or currently running. `sk
 
 Bundled skills:
 
+- `hive-lite-bootstrap`
 - `hive-lite-start-prompt`
 - `hive-lite-finish`
 - `hive-lite-map-maintainer`

package/docs/skills/hive-lite-bootstrap/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: hive-lite-bootstrap
+description: Use this skill when a git repository is adopting Hive Lite for the first time. It checks first-time setup state, may run `hive-lite init`, builds the first Project Map without changing product code, verifies readiness, and prepares a user-approved commit for Hive Lite setup and map files before any product requirement starts.
+---
+
+# Hive Lite Bootstrap
+
+## Purpose
+
+Onboard a git repository to Hive Lite for the first time:
+
+```text
+check repo -> run hive-lite init when needed -> build first Project Map -> verify -> commit setup/map after approval
+```
+
+This skill is the only Hive Lite operator skill that may run `hive-lite init`. Use it for first-time project setup, not for ordinary coding work.
+
+## Boundaries
+
+- Do not edit application source, tests, product docs, package files, secrets, CI, or generated artifacts.
+- You may run `hive-lite init` only when the target is already a git repo and the worktree was clean before init.
+- You may directly edit only:
+  - `.hive/map/project.yaml`
+  - `.hive/map/areas.yaml`
+  - `.hive/map/rules.yaml`
+  - `.hive/map/validation.yaml`
+- Preserve setup artifacts created by `hive-lite init`, including `.hive/config.yaml` and Hive Lite `.gitignore` runtime/evidence rules. Do not manually curate or remove them.
+- Do not start a product requirement, run `hive-lite find`, create a Change Record, accept risk, push, merge, deploy, or run app tests.
+- Commit only after explicit human approval, or when the user's request already explicitly asked you to commit the Hive Lite bootstrap.
+- If committing, include only Hive Lite setup/map files and the Hive Lite `.gitignore` change. Never include product-code changes.
+
+## Find The CLI
+
+Run Hive Lite from the target repo root. Prefer:
+
+```bash
+hive-lite <args>
+```
+
+If unavailable, use an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. Ask for the CLI path if it is not obvious.
+
+## Workflow
+
+### 1. Preflight
+
+Run:
+
+```bash
+hive-lite status --json
+git status --short
+```
+
+Stop if the directory is not a git repo. Tell the user to switch to the repo root, or initialize git and create an initial commit before using Hive Lite.
+
+Stop if `git status --short` shows pre-existing non-Hive changes. Ask the user to commit, stash, or use another worktree first. Do not run `hive-lite init` into a dirty product worktree.
+
+If Hive Lite is already initialized, do not rerun init. Continue only if the user asked to build or repair the first Project Map; otherwise explain that setup already exists and recommend `$hive-lite-map-maintainer` or `$hive-lite-start-prompt`.
+
+### 2. Initialize
+
+If status reports `hive.state = hive_init_required` or `hive.initialized = false`, run:
+
+```bash
+hive-lite init
+```
+
+Then continue in the same turn. Do not ask the user to commit yet; first build the initial Project Map.
+
+### 3. Build First Map
+
+Run:
+
+```bash
+hive-lite map verify --json
+hive-lite map prompt --focus "highest value product and workflow areas" --max-areas 8
+```
+
+Inspect the repo with deterministic commands such as:
+
+```bash
+rg --files
+rg "<routing term>"
+```
+
+Edit only `.hive/map/*.yaml`. Build 3-8 high-value, narrow areas that make near-term product requests routable. Do not try to map the whole project.
+
+### 4. Verify
+
+Run:
+
+```bash
+hive-lite map verify --json
+hive-lite map health --json
+```
+
+If areas were created, spot-check important areas with:
+
+```bash
+hive-lite map health --area <area_id> --json
+```
+
+Success means:
+
+- map verify is ok
+- the first useful areas have no critical health findings
+- the map is not empty
+- no product files were changed
+
+### 5. Commit Boundary
+
+Before any product requirement starts, the Hive Lite setup and initial Project Map should have a git commit boundary.
+
+If the user already explicitly asked to commit, and `git status --short` contains only Hive Lite setup/map files plus the Hive Lite `.gitignore` update, run:
+
+```bash
+git add .hive/config.yaml .hive/map/project.yaml .hive/map/areas.yaml .hive/map/rules.yaml .hive/map/validation.yaml .gitignore
+git commit -m "Initialize Hive Lite Project Map"
+```
+
+If the user did not explicitly approve committing, stop and ask for approval. Provide the exact command above and say that the user can reply with:
+
+```text
+可以提交。commit message 用：Initialize Hive Lite Project Map
+```
+
+Do not start `$hive-lite-start-prompt` until the setup/map files are committed or otherwise isolated.
+
+## Return Summary
+
+Return:
+
+```text
+Hive Lite bootstrap complete.
+
+Setup:
+- hive-lite init: <run / already initialized>
+
+Project Map:
+- changed files: <files>
+- areas created or updated: <area ids>
+
+Verification:
+- hive-lite map verify --json: <ok/fail>
+- hive-lite map health --json: <status and finding counts>
+
+Commit:
+- <committed / waiting for approval>
+- command or commit sha if applicable
+
+Next:
+- After the setup/map commit exists, start the first requirement with `$hive-lite-start-prompt`.
+```
+

package/docs/skills/hive-lite-bootstrap/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Hive Lite Bootstrap"
+  short_description: "Initialize Hive Lite for a repo"
+  default_prompt: "Use $hive-lite-bootstrap when this repository is adopting Hive Lite for the first time. Initialize Hive Lite, build the first Project Map, and prepare the setup/map commit before product work starts."
+
+policy:
+  allow_implicit_invocation: true

package/docs/skills/hive-lite-finish/SKILL.md

@@ -61,6 +61,8 @@ In command examples below, replace `hive-lite` with the resolved command.
 
 Run `hive-lite status --json` first. If it reports `hive.state = repo_setup_required`, stop immediately. Do not run check/validate/accept and do not initialize git automatically. Tell the user to switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
 
+If it reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself, and do not run check/validate/accept. Recommend `$hive-lite-bootstrap` for first-time setup. If the user expected an existing Hive Lite change, they may be in the wrong directory.
+
 Find one of:
 
 - context id from the coding agent output, such as `ctx_xxx`,
@@ -273,6 +275,20 @@ Accepted and committed.
 - Split next phase: <handoff prompt or none>
 ```
 
+If `Map Delta Candidate` is not `none`, do not apply it from this skill. Explain that the accepted change suggests a possible Project Map improvement and output this handoff:
+
+```text
+$hive-lite-map-maintainer
+请 review 这个 Map Delta Candidate：
+<delta_id>
+
+只判断是否 apply 或 reject 这个 map delta。
+不要改应用代码。
+不要开始新需求。
+```
+
+Tell the user that map delta review can happen before or after the next requirement, but reviewing it before similar future requests may improve routing.
+
 If no commit was created because the user explicitly asked not to commit, warn that a new Hive Lite requirement should not start until the worktree is clean.
 
 ## Response Style

package/docs/skills/hive-lite-map-maintainer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hive-lite-map-maintainer
-description: Use this skill when maintaining a Hive Lite Project Map instead of implementing product code. It handles first-time map bootstrap, existing-map refresh after drift, intent-triggered map repair from find/context gaps, map health cleanup, and map delta review/apply workflows while editing only `.hive/map/*.yaml`.
+description: Use this skill when maintaining a Hive Lite Project Map instead of implementing product code. It handles first map creation after explicit Hive Lite init, existing-map refresh after drift, intent-triggered map repair from find/context gaps, map health cleanup, and map delta review/apply workflows while directly editing only `.hive/map/*.yaml`.
 ---
 
 # Hive Lite Map Maintainer
@@ -32,18 +32,15 @@ hive-lite skills install --agent <codex|claude|gemini>
 
 ## Authority Boundary
 
-This skill has lifecycle-scoped authority.
+Setup precondition:
 
-Bootstrap / repair exception:
+- This skill must not run `hive-lite init`.
+- If Hive Lite is not initialized or is partially initialized, stop immediately and recommend `$hive-lite-bootstrap` for first-time setup.
+- Do not create `.hive/map` manually, do not edit `.hive/config.yaml`, and do not edit `.gitignore`.
 
-- If Hive Lite is not initialized, partially initialized, or explicitly being initialized, this skill may run the approved bootstrap command, normally `hive-lite init`.
-- Preserve setup side effects produced by the bootstrap command, including `.hive/config.yaml`, `.hive/map/*.yaml`, Hive Lite runtime/evidence directories, and `.gitignore` entries for those runtime/evidence directories.
-- These bootstrap side effects are authorized setup artifacts. Do not delete, revert, or "clean up" them merely because they are outside `.hive/map/`.
-- Do not hand-edit setup files as ordinary map maintenance. If setup files are missing or inconsistent after bootstrap, report a setup/repair condition or rerun an approved bootstrap/repair command when the task allows it.
+Map-maintenance authority:
 
-Normal map-maintenance mode:
-
-- After Hive Lite is initialized, directly edit only:
+- Directly edit only:
   - `.hive/map/project.yaml`
   - `.hive/map/areas.yaml`
   - `.hive/map/rules.yaml`
@@ -53,7 +50,7 @@ Normal map-maintenance mode:
 - Do not run `hive check`, `hive validate`, `hive accept`, app formatters, app tests, commits, pushes, merges, deploys, or destructive git commands.
 - Do not call an LLM API from Hive Lite. Use Hive Lite CLI facts plus repo inspection.
 - Do not turn the map into a wiki. Only add information that improves `find` or `check`.
-- Durable setup and map changes require human awareness. Summarize setup effects separately from map edits and tell the user to run/approve commit separately.
+- Durable map changes require human awareness. Summarize map edits and tell the user to run/approve commit separately.
 - Apply Map Delta Candidates only when the user explicitly asked for or confirmed that action. Otherwise list/summarize them and stop.
 
 ## Find The CLI
@@ -80,6 +77,34 @@ hive-lite status --json
 
 If it reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init`, do not create `.hive/map`, and do not initialize git automatically. Tell the user to switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
 
+If it reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself. Tell the user:
+
+```text
+Hive Lite is not initialized in this repo yet.
+
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
+
+If the bootstrap skill is not available, run `hive-lite init` from the repo root, then rerun:
+  $hive-lite-map-maintainer
+  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
+
+Do not commit immediately after init. Build the first Project Map first, then commit Hive Lite setup and map files together before starting the first product requirement.
+```
+
+For older Hive Lite versions that do not report `hive.initialized`, check for required setup files before continuing:
+
+```text
+.hive/config.yaml
+.hive/map/project.yaml
+.hive/map/areas.yaml
+.hive/map/rules.yaml
+.hive/map/validation.yaml
+```
+
+If any are missing, stop with the same message. Do not run init automatically.
+
 ### 1. Establish Mode
 
 Read [lifecycle.md](references/lifecycle.md), then classify the task as one of:
@@ -103,16 +128,7 @@ Before any mode-specific work, check whether the target repo has the required Hi
 .hive/map/validation.yaml
 ```
 
-If any required map file is missing, run:
-
-```bash
-hive-lite init
-```
-
-This is setup work. Do it automatically; do not ask the user whether to initialize Hive Lite. Then continue with bootstrap or recovery.
-Preserve all setup artifacts created by `hive-lite init`; do not remove `.hive/config.yaml` or Hive Lite `.gitignore` entries as part of cleanup.
-
-If the target directory is not a git repo or Hive Lite init fails, stop and report the blocker instead of inventing map files manually.
+If any required map file is missing, stop immediately and recommend `$hive-lite-bootstrap`. Do not create missing map files manually.
 
 ### 3. Verify Current Map
 
@@ -195,8 +211,8 @@ Mode:
 - <bootstrap|refresh|intent_repair|continuous_delta|recovery>
 
 Hive Lite setup:
-- <initialized with hive-lite init / no setup changes / setup repair needed>
-- Setup artifacts preserved: <.hive/config.yaml, .gitignore runtime rules, runtime directories, or none>
+- initialized: yes
+- setup changes made by this skill: none
 
 Changed map files:
 - <file or none>

package/docs/skills/hive-lite-map-maintainer/references/lifecycle.md

@@ -6,6 +6,11 @@ Choose one mode before editing the map.
 
 Use when an existing project is adopting Hive Lite for the first time.
 
+Precondition:
+
+- Hive Lite setup already exists, normally because `$hive-lite-bootstrap` ran first.
+- If Hive Lite setup files are missing, stop and recommend `$hive-lite-bootstrap`; do not run `hive-lite init` from this skill.
+
 Goal:
 
 - Create the first 3-8 high-value product/work areas.
@@ -15,11 +20,10 @@ Goal:
 Suggested flow:
 
 ```bash
-hive-lite init
 hive-lite map prompt --focus "highest value product and workflow areas" --max-areas 8
 ```
 
-Preserve setup artifacts created by `hive-lite init`, including `.hive/config.yaml`, Hive Lite runtime/evidence directories, and `.gitignore` runtime/evidence rules. Then inspect repo files and edit `.hive/map/*.yaml` directly.
+Inspect repo files and edit `.hive/map/*.yaml` directly.
 
 Success:
 
@@ -97,7 +101,7 @@ Only apply a delta when the user explicitly asks or confirms. Reject stale or lo
 
 ## recovery
 
-Use when map files are missing, invalid YAML, or structurally broken.
+Use when initialized map files are invalid YAML or structurally broken. If required Hive Lite setup or map files are missing, stop and recommend `$hive-lite-bootstrap`.
 
 Goal:
 
@@ -107,8 +111,7 @@ Goal:
 Suggested flow:
 
 ```bash
-hive-lite init
-hive-lite map verify
+hive-lite map verify --json
 ```
 
 If invalid YAML cannot be repaired safely, stop and report the exact error.

package/docs/skills/hive-lite-start-prompt/SKILL.md

@@ -35,7 +35,7 @@ hive-lite skills install --agent <codex|claude|gemini>
 
 - Do not directly edit application source, tests, docs, `.gitignore`, generated artifacts, `.hive/context`, `.hive/changes`, or `.hive/deltas`.
 - Only edit these Project Map files when map repair is needed: `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, `.hive/map/validation.yaml`.
-- Bootstrap exception: when Hive Lite map files are missing, this skill may run `hive-lite init` and must preserve setup artifacts created by that command, including `.hive/config.yaml`, runtime/evidence directories, and Hive Lite `.gitignore` entries. Do not delete or revert those artifacts merely because they are outside `.hive/map/`.
+- Do not run `hive-lite init`. If Hive Lite is not initialized or is partially initialized, stop and recommend `$hive-lite-bootstrap` before using this skill.
 - Do not run `hive check`, `hive validate`, `hive accept`, commits, formatters, or app tests for the new requirement. Those belong after the coding agent changes code.
 - During preflight, you may help finish or isolate pre-existing work only after explicit user confirmation.
 - Never discard changes with destructive commands such as `git reset --hard`, `git checkout --`, or forced branch switches.
@@ -67,21 +67,37 @@ Read [input-calibration.md](references/input-calibration.md). Produce:
 
 ### 2. Preflight The Worktree
 
-If `.hive/map/project.yaml`, `.hive/map/areas.yaml`, `.hive/map/rules.yaml`, or `.hive/map/validation.yaml` is missing, run:
+Run:
 
 ```bash
-hive-lite init
+hive-lite status --json
 ```
 
-Do this automatically; do not ask the user whether to initialize Hive Lite. Initialization is setup work, not the requested product change. Preserve all setup artifacts created by `hive-lite init`; do not remove `.hive/config.yaml` or Hive Lite `.gitignore` entries as cleanup.
+If status reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init` and do not initialize git automatically. Tell the user to switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
 
-Run:
+If status reports `hive.state = hive_init_required`, or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` yourself. Tell the user:
 
-```bash
-hive-lite status --json
+```text
+Hive Lite is not initialized in this repo yet.
+
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
+
+Do not start the product requirement yet. After bootstrap builds the first map, commit the Hive Lite setup and map files together, then rerun this start skill with the original requirement.
 ```
 
-If status reports `hive.state = repo_setup_required`, stop immediately. Do not run `hive-lite init` and do not initialize git automatically. Tell the user to switch to the correct git repo root, or manually initialize git and create an initial commit before using Hive Lite.
+For older Hive Lite versions that do not report `hive.initialized`, check whether these files exist before continuing:
+
+```text
+.hive/config.yaml
+.hive/map/project.yaml
+.hive/map/areas.yaml
+.hive/map/rules.yaml
+.hive/map/validation.yaml
+```
+
+If any are missing, stop with the same message. Do not run init automatically and do not create missing map files manually.
 
 If the command is unavailable in an older Hive Lite, fall back to `git status --porcelain`.
 

package/docs/skills/hive-lite-start-prompt/references/preflight.md

@@ -4,23 +4,23 @@ Use this reference when `hive-lite status --json` is not clean.
 
 The goal is to protect the Change Record boundary. A new Hive Lite requirement must start from a clean worktree.
 
-## After Automatic Init
+## Hive Lite Not Initialized
 
-If the worktree is dirty only because this skill just ran `hive-lite init`, explain that Hive Lite was initialized automatically and stop before starting the product requirement.
+If `hive-lite status --json` reports `hive.state = hive_init_required` or `hive.initialized = false`, stop immediately. Do not run `hive-lite init` from this skill.
 
-Present options:
+Say:
 
 ```text
-Hive Lite has been initialized for this repo. The setup files need a git boundary before a product requirement can start.
+Hive Lite is not initialized in this repo yet.
 
-Options:
-1. Commit the Hive Lite setup files.
-2. Stash the setup files.
-3. Create a separate git worktree for the product requirement.
-4. Stop.
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。
+
+After bootstrap builds the first map, commit the Hive Lite setup and map files together before starting the product requirement.
 ```
 
-Do not ask whether to run init; init has already been performed. Do ask before committing, stashing, or creating a worktree.
+Do not continue to find/map repair/start prompt until Hive Lite setup exists.
 
 ## States
 
@@ -107,6 +107,7 @@ hive-lite accept <chg_id> --commit -m "<message>"
 ## Safety Rules
 
 - Do not continue to `find` while status is not clean.
+- Do not run `hive-lite init` from this start skill; first-time setup belongs to `$hive-lite-bootstrap`.
 - Do not initialize git automatically.
 - Do not assume "new branch" cleans the worktree; dirty files usually follow branch switches.
 - Prefer commit, stash, or separate git worktree.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hive-lite",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",
@@ -37,4 +37,4 @@
   "engines": {
     "node": ">=16"
   }
-}
+}

package/src/cli.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const { version: packageVersion } = require('../package.json');
 const { requireGitRepo } = require('./lib/git');
 const { evaluateMapHealth } = require('./lib/health');
 const { createMapPrompt, initProject, loadProjectMap, suggestMap, verifyProjectMap } = require('./lib/map');
@@ -51,11 +52,20 @@ function isHelpFlag(arg) {
   return arg === '--help' || arg === '-h';
 }
 
+function isVersionArg(arg) {
+  return arg === 'version' || arg === '--version' || arg === '-v';
+}
+
+function printVersion() {
+  console.log(packageVersion);
+}
+
 function printHelp() {
   console.log(`
 Hive Lite - local Project Map + Change Control
 
 Usage:
+  hive-lite version
   hive-lite init
   hive-lite doctor
   hive-lite status [--json] [--all]
@@ -87,6 +97,16 @@ function currentCliCommandArgv() {
   return [process.execPath, path.resolve(process.argv[1])];
 }
 
+function requireHiveInitialized(cwd, commandName) {
+  const status = evaluateWorkspaceStatus(cwd);
+  if (status.hive.initialized === false) {
+    const missing = status.hive.missingSetupFiles && status.hive.missingSetupFiles.length > 0
+      ? ` Missing: ${status.hive.missingSetupFiles.join(', ')}.`
+      : '';
+    throw new Error(`${commandName} requires Hive Lite initialization. Use $hive-lite-bootstrap first, or run hive-lite init from the repo root as the low-level fallback.${missing}`);
+  }
+}
+
 function printInit(result) {
   console.log('Hive Lite initialized.');
   console.log(`Repo: ${result.root}`);
@@ -531,6 +551,11 @@ function printWorkspaceStatus(result) {
   console.log(`Hive State: ${result.hive.state}`);
   console.log(`Can Start New Requirement: ${result.canStartNewRequirement ? 'yes' : 'no'}`);
   console.log(`Reason: ${result.hive.reason}`);
+  if (result.hive.initialized === false && result.hive.missingSetupFiles && result.hive.missingSetupFiles.length > 0) {
+    console.log('');
+    console.log('Missing Hive Lite Setup Files:');
+    for (const file of result.hive.missingSetupFiles) console.log(`  - ${file}`);
+  }
   if (result.hive.latestChange) {
     console.log('');
     console.log('Latest Change:');
@@ -732,6 +757,11 @@ async function main(argv) {
     return;
   }
 
+  if (isVersionArg(command)) {
+    printVersion();
+    return;
+  }
+
   if (subcommand === 'help' || isHelpFlag(subcommand) || isHelpFlag(subsubcommand) || rest.some(isHelpFlag)) {
     printHelp();
     return;
@@ -795,6 +825,7 @@ async function main(argv) {
     const intent = parsed.positional.join(' ').trim();
     if (!intent) throw new Error('find requires an intent string');
     const root = requireGitRepo(process.cwd(), 'hive-lite find');
+    requireHiveInitialized(root, 'hive-lite find');
     const result = createContextPacket(root, intent, {
       ...parsed.flags,
       cliCommandArgv: currentCliCommandArgv(),
@@ -808,7 +839,8 @@ async function main(argv) {
   }
 
   if (command === 'check') {
-    requireGitRepo(process.cwd(), 'hive-lite check');
+    const root = requireGitRepo(process.cwd(), 'hive-lite check');
+    requireHiveInitialized(root, 'hive-lite check');
     const parsed = parseArgs([subcommand, subsubcommand, ...rest].filter((item) => item !== undefined));
     const changeId = parsed.positional[0] || null;
     const result = createOrUpdateChange(process.cwd(), {
@@ -821,7 +853,8 @@ async function main(argv) {
   }
 
   if (command === 'validate') {
-    requireGitRepo(process.cwd(), 'hive-lite validate');
+    const root = requireGitRepo(process.cwd(), 'hive-lite validate');
+    requireHiveInitialized(root, 'hive-lite validate');
     const parsed = parseArgs([subcommand, subsubcommand, ...rest].filter((item) => item !== undefined));
     if (!parsed.flags.json && !parsed.flags.manual) {
       parsed.flags.onStart = (item) => {
@@ -837,7 +870,8 @@ async function main(argv) {
   }
 
   if (command === 'accept') {
-    requireGitRepo(process.cwd(), 'hive-lite accept');
+    const root = requireGitRepo(process.cwd(), 'hive-lite accept');
+    requireHiveInitialized(root, 'hive-lite accept');
     const parsed = parseArgs([subcommand, subsubcommand, ...rest].filter((item) => item !== undefined));
     const result = acceptChange(process.cwd(), parsed.positional[0] || null, parsed.flags);
     if (parsed.flags.json) console.log(JSON.stringify(result, null, 2));
@@ -868,6 +902,7 @@ async function main(argv) {
       return;
     }
     if (subcommand === 'prompt') {
+      requireHiveInitialized(root, 'hive-lite map prompt');
       const parsed = parseArgs([subsubcommand, ...rest].filter((item) => item !== undefined));
       const result = createMapPrompt(root, parsed.flags);
       if (parsed.flags.json) console.log(JSON.stringify(result, null, 2));
@@ -876,10 +911,12 @@ async function main(argv) {
     }
     if (subcommand === 'delta') {
       if (subsubcommand === 'list') {
+        requireHiveInitialized(root, 'hive-lite map delta list');
         printDeltas(allDeltas(root));
         return;
       }
       if (subsubcommand === 'apply') {
+        requireHiveInitialized(root, 'hive-lite map delta apply');
         const parsed = parseArgs(rest);
         const id = parsed.positional[0];
         if (!id) throw new Error('map delta apply requires a delta id');
@@ -890,6 +927,7 @@ async function main(argv) {
         return;
       }
       if (subsubcommand === 'reject') {
+        requireHiveInitialized(root, 'hive-lite map delta reject');
         const parsed = parseArgs(rest);
         const id = parsed.positional[0];
         if (!id) throw new Error('map delta reject requires a delta id');

package/src/lib/next.js

@@ -94,6 +94,13 @@ function startPrompt() {
   ].join('\n');
 }
 
+function bootstrapPrompt() {
+  return [
+    '$hive-lite-bootstrap',
+    '这是已有项目第一次接入 Hive Lite。请完成初始化，建立第一版 Project Map，不要改应用代码。完成后在开始第一个需求前准备 Hive Lite setup/map 提交。',
+  ].join('\n');
+}
+
 function finishPrompt(changeId) {
   return [
     '$hive-lite-finish',
@@ -105,7 +112,7 @@ function mapMaintainerPrompt(mode) {
   if (mode === 'bootstrap') {
     return [
       '$hive-lite-map-maintainer',
-      '这个项目第一次使用 Hive Lite，请初始化并建立第一版 3-8 个高价值 areas。保留 hive-lite init 创建的 setup 产物，例如 .hive/config.yaml 和 .gitignore runtime 规则；初始化后只直接编辑 .hive/map/*.yaml。',
+      '这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。',
     ].join('\n');
   }
   if (mode === 'delta') {
@@ -137,6 +144,7 @@ function chooseSplit(status) {
 
 function requiredSkillForAction(actionItem) {
   if (!actionItem) return null;
+  if (actionItem.kind === 'run_bootstrap_skill') return 'hive-lite-bootstrap';
   if (actionItem.kind === 'run_start_skill' || actionItem.kind === 'continue_split') return 'hive-lite-start-prompt';
   if (actionItem.kind === 'run_finish_skill' || actionItem.kind === 'commit_accepted_change') return 'hive-lite-finish';
   if (actionItem.kind === 'run_map_maintainer') return 'hive-lite-map-maintainer';
@@ -177,11 +185,13 @@ function evaluateNextAction(cwd, options = {}) {
   const root = repoRoot(cwd);
   const workspace = evaluateWorkspaceStatus(root);
   const repoSetupRequired = workspace.hive.state === 'repo_setup_required';
-  const mapHealth = repoSetupRequired
+  const hiveInitRequired = workspace.hive.state === 'hive_init_required';
+  const setupRequired = repoSetupRequired || hiveInitRequired;
+  const mapHealth = setupRequired
     ? { status: 'not_checked', critical: 0, warnings: 0, info: 0, areasChecked: 0, topFindings: [] }
     : mapHealthSummary(root);
-  const latestChange = repoSetupRequired ? null : latestChangeSummary(root);
-  const deltas = repoSetupRequired ? [] : pendingDeltas(root);
+  const latestChange = setupRequired ? null : latestChangeSummary(root);
+  const deltas = setupRequired ? [] : pendingDeltas(root);
   const warnings = [];
   const secondaryActions = [];
 
@@ -222,6 +232,16 @@ function evaluateNextAction(cwd, options = {}) {
     });
     summaryForHuman = '当前目录不是 git repo。Hive Lite 不能安全开始；请切到正确的 repo 根目录，或你自己先完成 git 初始化和初始提交。';
     summaryForAgent = 'No git repository detected. Stop. Do not run find/check/accept or initialize git automatically.';
+  } else if (workspace.hive.state === 'hive_init_required') {
+    phaseGuess = 'hive_init_required';
+    primaryAction = action({
+      kind: 'run_bootstrap_skill',
+      label: 'Use hive-lite-bootstrap',
+      prompt: bootstrapPrompt(),
+      explanation: 'This git repository has not been initialized for Hive Lite. Use the bootstrap skill to initialize, build the first Project Map, and prepare the setup/map commit before product work starts.',
+    });
+    summaryForHuman = '当前项目还没有初始化 Hive Lite。建议使用 hive-lite-bootstrap 完成首次接入：初始化、建立第一版 Project Map，并在开始第一个需求前准备 setup/map 提交。';
+    summaryForAgent = 'Hive Lite is not initialized. Stop ordinary start/finish/map-maintainer workflows and hand off to hive-lite-bootstrap.';
   } else if (!workspace.canStartNewRequirement) {
     if (workspace.hive.state === 'in_progress') {
       phaseGuess = 'finish';

package/src/lib/skills.js

@@ -4,6 +4,7 @@ const os = require('os');
 const path = require('path');
 
 const SKILL_NAMES = [
+  'hive-lite-bootstrap',
   'hive-lite-start-prompt',
   'hive-lite-finish',
   'hive-lite-map-maintainer',

package/src/lib/status.js

@@ -6,6 +6,14 @@ const { latestChangeId, loadChange } = require('./change');
 const { exists, readJson } = require('./fsx');
 const { hiveDir } = require('./map');
 
+const REQUIRED_HIVE_SETUP_FILES = [
+  '.hive/config.yaml',
+  '.hive/map/project.yaml',
+  '.hive/map/areas.yaml',
+  '.hive/map/rules.yaml',
+  '.hive/map/validation.yaml',
+];
+
 function sha256(value) {
   return createHash('sha256').update(value || '').digest('hex');
 }
@@ -204,6 +212,10 @@ function action(kind, label, command, description) {
   return { kind, label, command, description };
 }
 
+function missingHiveSetupFiles(root) {
+  return REQUIRED_HIVE_SETUP_FILES.filter((file) => !exists(path.join(root, file)));
+}
+
 function actionsFor(state, latestId, diffMatches) {
   if (state === 'repo_setup_required') {
     return [
@@ -212,6 +224,12 @@ function actionsFor(state, latestId, diffMatches) {
       action('manual_git_setup', 'Set up git manually', null, 'If this is a new project, review .gitignore, initialize git, and create an initial commit yourself before running Hive Lite.'),
     ];
   }
+  if (state === 'hive_init_required') {
+    return [
+      action('run_hive_init', 'Run Hive Lite init', 'hive-lite init', 'Initialize Hive Lite setup files before using Hive Lite skills.'),
+      action('stop', 'Stop', null, 'Do not run start, finish, or map-maintainer skills until Hive Lite has been initialized.'),
+    ];
+  }
   if (state === 'clean') {
     return [
       action('start_requirement', 'Start a Hive Lite requirement', 'hive-lite find "<intent>" --json', 'The worktree is clean enough to generate a new Context Packet.'),
@@ -281,6 +299,8 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
   const root = repoRoot(cwd);
   const files = changedFiles(root);
   const dirty = files.length > 0;
+  const missingSetupFiles = missingHiveSetupFiles(root);
+  const initialized = missingSetupFiles.length === 0;
   const currentDiff = dirty ? diffFromHead(root) : '';
   const currentDiffHash = dirty ? diffHash(currentDiff) : null;
   const latest = latestChange(root);
@@ -292,7 +312,10 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
     ? 'Working tree has dirty files that are not known to be an accepted or in-progress Hive change.'
     : 'Working tree is clean.';
 
-  if (dirty && latest.change) {
+  if (!initialized) {
+    state = 'hive_init_required';
+    reason = 'Hive Lite is not initialized in this git repository. Use $hive-lite-bootstrap for first-time setup, or run hive-lite init as the low-level fallback.';
+  } else if (dirty && latest.change) {
     if (accepted(latest.change) && !committed(latest.change) && diffMatches) {
       state = 'accepted_uncommitted';
       reason = 'The dirty diff matches the latest accepted Hive change, but no commit was created.';
@@ -330,6 +353,8 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
     hive: {
       state,
       reason,
+      initialized,
+      missingSetupFiles,
       latestChange: latestSummary,
     },
     canStartNewRequirement: state === 'clean',