hive-lite 0.1.2 → 0.1.6

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`
@@ -143,7 +144,7 @@ node bin/hive.js find "Update server API for Action Inbox hierarchy" --from-spli
 
 When `--from-split` and `--phase` point to a recorded split phase, Hive Lite constrains routing to that phase's primary area. Generated split notes include `--area <primaryAreaId>` so copied commands stay narrowly scoped even if the original intent was broad.
 If the split note or phase cannot be found, Hive Lite does not treat the copied command as an edit permit. If `--area` disagrees with the recorded phase area, the recorded phase area wins and Hive Lite prints a warning.
-When Hive Lite is run from a source checkout with `node /path/to/bin/hive.js`, generated split notes render that Node command first and include `hive-lite` as a package-alias fallback when available.
+When Hive Lite is run from a source checkout, generated split notes may render the caller's current CLI invocation and include `hive-lite` as a package-alias fallback when available.
 
 ### Check And Validate A Change
 
@@ -235,7 +236,7 @@ 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` and `next` report `hive_init_required` until the repo has been initialized with `hive-lite init`. Hive Lite skills should stop in this state and ask the human/operator to run init explicitly before start, finish, or map-maintenance workflows continue.
+Inside a git repo, `status` reports `hive_init_required` until required Hive Lite setup files exist. `status` and `next` recommend `$hive-lite-bootstrap`, which is the first-time setup and setup-repair skill that may run init, build the first Project Map, and prepare the setup/map commit before product work starts.
 
 Committed by default:
 
@@ -267,7 +268,7 @@ node bin/hive.js next --json
 Typical `phaseGuess` values:
 
 - `repo_setup_required`: current directory is not inside a git repo
-- `hive_init_required`: run `hive-lite init` explicitly before using Hive Lite skills
+- `hive_init_required`: use `$hive-lite-bootstrap` for first-time setup or setup repair 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`

package/docs/cli-semantics.md

@@ -45,15 +45,15 @@ It reads:
 By default, `status --json` and `next --json` filter split notes to reduce exploratory clutter. They show active unfinished split notes that already have accepted phase progress. If no active split exists, they show only the newest unstarted split note. `splitNoteSummary` reports how many split notes were hidden by this default policy. Use `status --all --json` to inspect every runtime split note.
 `splitNoteSummary.primaryRecentSplitNote` identifies the split note selected as primary from the visible notes. `splitNoteSummary.otherActiveSplitNotes` lists older active-progress split notes so an operator can tell whether additional historical split work exists.
 
-Hive Lite cannot detect the currently running agent CLI. If the caller provides `--agent <codex|claude|gemini|all>` or `--path <skills-dir>`, `next` treats the recommended Hive Lite operator skill as a precondition. When the selected target is missing that skill or has a stale copy, `phaseGuess` becomes `skill_preflight` and `primaryAction.kind` becomes `install_operator_skill`.
+Hive Lite cannot detect the currently running agent CLI. If the caller provides `--agent <codex|claude|gemini|all>` or `--path <skills-dir>`, `next` treats the recommended Hive Lite operator skill as a precondition. When the selected target is missing that skill or has a stale copy, `phaseGuess` becomes `skill_preflight` and `primaryAction.kind` becomes `sync_operator_skill`.
 
 ### `phaseGuess`
 
 | 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. | Stop skill workflows. Run `hive-lite init` explicitly from the repo root, commit or preserve setup files, then rerun `next`. |
-| `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`. |
+| `hive_init_required` | Current git repo does not have required Hive Lite setup files. | Use `$hive-lite-bootstrap` for first-time setup or setup repair before product work. |
+| `skill_preflight` | The selected agent target is missing the operator skill needed for the next Hive Lite step, or has a stale copy. | Run the recommended `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. |
 | `map` | Project Map is missing, invalid, critical, or needs attention. | Use `$hive-lite-map-maintainer` to bootstrap, refresh, or repair the map. |
@@ -103,7 +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 all skills. Run `hive-lite init` explicitly from the repo root. |
+| `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 setup repair. |
 | `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`. |
@@ -146,7 +146,7 @@ node bin/hive.js find "<phase.findIntent>" --from-split split_xxx --phase phase_
 `--from-split` + `--phase` constrains routing to the selected phase's primary area when the split note is available.
 If the split note or phase cannot be found, the result is not an edit permit and `phaseDependencyStatus.canStartNormally` is `false`.
 If `--area` disagrees with the recorded phase area, Hive Lite routes to the recorded phase area and reports a warning.
-Split-note markdown renders the current Hive Lite CLI invocation first, such as `node /path/to/bin/hive.js ...` when run from a source checkout, and includes `hive-lite ...` as a fallback for environments where the package alias is installed.
+Split-note markdown renders the current Hive Lite CLI invocation first when run from a source checkout, and includes `hive-lite ...` as a fallback for environments where the package alias is installed.
 
 ## `skills`
 
@@ -158,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`
@@ -185,8 +186,8 @@ node bin/hive.js skills doctor --path ~/.codex/skills --json
 | Status | Meaning | What To Do |
 | --- | --- | --- |
 | `current` | Installed copy matches bundled copy. | Nothing needed. |
-| `missing` | Skill is not installed at the target path. | Run `skills install`. |
-| `stale` | Skill exists but differs from the bundled copy. | Run `skills sync` or `skills install --force` if you want to overwrite. |
+| `missing` | Skill is not installed at the target path. | Run `skills sync`. |
+| `stale` | Skill exists but differs from the bundled copy. | Run `skills sync`. |
 
 Install missing skills:
 

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

@@ -0,0 +1,171 @@
+---
+name: hive-lite-bootstrap
+description: Use this skill when a git repository is adopting Hive Lite for the first time or has incomplete Hive Lite setup files. It checks 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, or repair incomplete required Hive Lite setup files before product work starts:
+
+```text
+check repo -> run hive-lite init when needed -> build or repair 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 or incomplete setup repair, not for ordinary coding work or ordinary map health cleanup.
+
+## 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 either the worktree was clean before first init, or the only dirty entries are Hive Lite setup/map artifacts involved in setup repair.
+- 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 use this skill to fix ordinary map health findings after required setup files exist. Use `$hive-lite-map-maintainer` for stale paths, scope, roles, validation, aliases, or other Project Map quality cleanup.
+- 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 `hive-lite` is not available, stop and tell the user:
+
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
+
+## 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.state = hive_init_required` because required setup files are missing, this is a setup repair condition. Continue only when dirty entries are limited to Hive Lite setup/map artifacts.
+
+If `git status --short` shows a deleted tracked `.hive/map/*.yaml` file from an existing committed Project Map, stop and ask whether to restore that file from git before rebuilding anything. Do not silently replace a previously committed map file with a default empty file.
+
+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 this only for first-time setup, partial setup, or user-approved setup repair:
+
+```bash
+hive-lite init
+```
+
+Then continue in the same turn. Do not ask the user to commit yet; first build or repair 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:
+- mode: <first-time / setup repair / already initialized>
+- hive-lite init: <run / already initialized / not run>
+
+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

@@ -27,11 +27,12 @@ Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-map
 - Next phase after split accept: output a `$hive-lite-start-prompt` handoff.
 - Map repair or refresh needed during finish: output a `$hive-lite-map-maintainer` handoff; do not edit map files here.
 
-If the target handoff skill is unavailable in the active agent CLI, tell the user to install or sync Hive Lite skills for their agent first. Hive Lite cannot detect the running agent by itself; use the user's agent target such as `codex`, `claude`, or `gemini`:
+If a Hive Lite handoff skill is missing or stale, stop and tell the user to update the CLI and sync skills:
 
 ```bash
-hive-lite skills doctor --agent <codex|claude|gemini>
-hive-lite skills install --agent <codex|claude|gemini>
+npm install -g hive-lite@latest --registry https://registry.npmjs.org
+hive-lite --version
+hive-lite skills sync --agent all
 ```
 
 ## Boundaries
@@ -51,9 +52,20 @@ Run Hive Lite from the target repo root. Prefer the package command:
 hive-lite <args>
 ```
 
-If `hive-lite` is not available, try 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.
+If `hive-lite` is not available, stop and tell the user:
 
-In command examples below, replace `hive-lite` with the resolved command.
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -61,7 +73,7 @@ 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. Tell the user to run `hive-lite init` from the repo root first. If they expected an existing Hive Lite change, they may be in the wrong directory.
+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 or setup repair. If the user expected an existing Hive Lite change, they may be in the wrong directory or missing setup files.
 
 Find one of:
 
@@ -275,6 +287,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

@@ -23,11 +23,12 @@ Do not assume this skill can invoke `$hive-lite-start-prompt` or `$hive-lite-fin
 - For coding work after map repair: output a `$hive-lite-start-prompt` handoff.
 - For finishing a code change: do not continue here; use `$hive-lite-finish`.
 
-If the target handoff skill is unavailable in the active agent CLI, tell the user to install or sync Hive Lite skills for their agent first. Hive Lite cannot detect the running agent by itself; use the user's agent target such as `codex`, `claude`, or `gemini`:
+If a Hive Lite handoff skill is missing or stale, stop and tell the user to update the CLI and sync skills:
 
 ```bash
-hive-lite skills doctor --agent <codex|claude|gemini>
-hive-lite skills install --agent <codex|claude|gemini>
+npm install -g hive-lite@latest --registry https://registry.npmjs.org
+hive-lite --version
+hive-lite skills sync --agent all
 ```
 
 ## Authority Boundary
@@ -35,7 +36,7 @@ hive-lite skills install --agent <codex|claude|gemini>
 Setup precondition:
 
 - This skill must not run `hive-lite init`.
-- If Hive Lite is not initialized or is partially initialized, stop immediately and tell the user to run `hive-lite init` from the target repo root, then rerun this skill.
+- If Hive Lite setup is missing or incomplete, stop immediately and recommend `$hive-lite-bootstrap` for first-time setup or setup repair.
 - Do not create `.hive/map` manually, do not edit `.hive/config.yaml`, and do not edit `.gitignore`.
 
 Map-maintenance authority:
@@ -61,9 +62,20 @@ Run Hive Lite from the target repo root. Prefer the package command:
 hive-lite <args>
 ```
 
-If `hive-lite` is not available, try an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. If it is still unclear, ask for the Hive Lite CLI path.
+If `hive-lite` is not available, stop and tell the user:
 
-In examples below, replace `hive-lite` with the resolved command.
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -80,14 +92,11 @@ If it reports `hive.state = repo_setup_required`, stop immediately. Do not run `
 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.
-
-Please run this once from the repo root:
-  hive-lite init
+Hive Lite setup is missing or incomplete in this repo.
 
-Then commit or otherwise preserve the setup files, and rerun:
-  $hive-lite-map-maintainer
-  这是已有项目第一次接入 Hive Lite。请建立第一版 Project Map，不要改应用代码。
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite，或 Hive Lite setup 文件缺失。请完成初始化或 setup 修复，建立第一版 Project Map，不要改应用代码。
 ```
 
 For older Hive Lite versions that do not report `hive.initialized`, check for required setup files before continuing:
@@ -125,7 +134,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, stop immediately and tell the user to run `hive-lite init` from the repo root. Do not create missing map files manually.
+If any required map file is missing, stop immediately and recommend `$hive-lite-bootstrap` as a setup repair handoff. Do not create missing map files manually. If the repo already had a committed Project Map, tell the user that restoring the missing file from git is safer than silently rebuilding it from defaults.
 
 ### 3. Verify Current Map
 

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

@@ -8,8 +8,8 @@ Use when an existing project is adopting Hive Lite for the first time.
 
 Precondition:
 
-- `hive-lite init` has already been run explicitly by the user/operator.
-- If Hive Lite setup files are missing, stop and tell the user to run `hive-lite init`; do not run it from this skill.
+- 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:
 
@@ -101,7 +101,7 @@ Only apply a delta when the user explicitly asks or confirms. Reject stale or lo
 
 ## recovery
 
-Use when initialized map files are invalid YAML or structurally broken. If required Hive Lite setup or map files are missing, stop and tell the user to run `hive-lite init` from the repo root.
+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:
 

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

@@ -24,18 +24,19 @@ Do not assume this skill can invoke another skill automatically. Handoffs are te
 - To map maintenance: output a `$hive-lite-map-maintainer` prompt and stop.
 - To finish work after coding: include `$hive-lite-finish` in the final instructions, but do not run finish actions here.
 
-If the target handoff skill is unavailable in the active agent CLI, tell the user to install or sync Hive Lite skills for their agent first. Hive Lite cannot detect the running agent by itself; use the user's agent target such as `codex`, `claude`, or `gemini`:
+If a Hive Lite handoff skill is missing or stale, stop and tell the user to update the CLI and sync skills:
 
 ```bash
-hive-lite skills doctor --agent <codex|claude|gemini>
-hive-lite skills install --agent <codex|claude|gemini>
+npm install -g hive-lite@latest --registry https://registry.npmjs.org
+hive-lite --version
+hive-lite skills sync --agent all
 ```
 
 ## Boundaries
 
 - 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`.
-- Do not run `hive-lite init`. If Hive Lite is not initialized or is partially initialized, stop and tell the user to run `hive-lite init` from the repo root before using this skill.
+- Do not run `hive-lite init`. If Hive Lite setup is missing or incomplete, 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.
@@ -49,9 +50,20 @@ Run Hive Lite from the target repo root. Prefer the package command:
 hive-lite <args>
 ```
 
-If `hive-lite` is not available, try an explicit path already given by the user or conversation context, such as `node /path/to/hive-lite/bin/hive.js <args>`. Do not spend a long time searching the target repo; ask for the Hive Lite CLI path if it is not obvious.
+If `hive-lite` is not available, stop and tell the user:
 
-In command examples below, replace `hive-lite` with the resolved command.
+```text
+I can't find the `hive-lite` command.
+
+Please install or update Hive Lite CLI:
+  npm install -g hive-lite@latest --registry https://registry.npmjs.org
+  hive-lite --version
+  hive-lite skills sync --agent all
+
+Then rerun this skill.
+```
+
+Keep user-facing recovery guidance to the install/update block above unless the user explicitly says they are developing Hive Lite itself.
 
 ## Workflow
 
@@ -78,14 +90,13 @@ If status reports `hive.state = repo_setup_required`, stop immediately. Do not r
 If status 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.
+Hive Lite setup is missing or incomplete in this repo.
 
-Please run this once from the repo root:
-  hive-lite init
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite，或 Hive Lite setup 文件缺失。请完成初始化或 setup 修复，建立第一版 Project Map，不要改应用代码。
 
-After the setup files are committed or otherwise preserved, rerun:
-  $hive-lite-map-maintainer
-  这是已有项目第一次接入 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.
 ```
 
 For older Hive Lite versions that do not report `hive.initialized`, check whether these files exist before continuing:
@@ -100,9 +111,9 @@ For older Hive Lite versions that do not report `hive.initialized`, check whethe
 
 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`.
+If `hive-lite status --json` is unavailable, stop and tell the user to update Hive Lite CLI and sync skills. Do not fall back to git-only status for normal pilot use.
 
-Continue only when `canStartNewRequirement` is true or fallback git status is clean. If not clean, read [preflight.md](references/preflight.md), present options, and stop immediately unless the user had already explicitly chosen an option before this step.
+Continue only when `canStartNewRequirement` is true. If not clean, read [preflight.md](references/preflight.md), present options, and stop immediately unless the user had already explicitly chosen an option before this step.
 
 After any preflight action, rerun `hive-lite status --json`; continue only when the target worktree is clean.
 

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

@@ -11,14 +11,13 @@ If `hive-lite status --json` reports `hive.state = hive_init_required` or `hive.
 Say:
 
 ```text
-Hive Lite is not initialized in this repo yet.
+Hive Lite setup is missing or incomplete in this repo.
 
-Please run this once from the repo root:
-  hive-lite init
+Recommended next step:
+  $hive-lite-bootstrap
+  这是已有项目第一次接入 Hive Lite，或 Hive Lite setup 文件缺失。请完成初始化或 setup 修复，建立第一版 Project Map，不要改应用代码。
 
-After the setup files are committed or otherwise preserved, rerun:
-  $hive-lite-map-maintainer
-  这是已有项目第一次接入 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 continue to find/map repair/start prompt until Hive Lite setup exists.
@@ -108,7 +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 a skill.
+- Do not run `hive-lite init` from this start skill; first-time setup and setup repair belong 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.2",
+  "version": "0.1.6",
   "description": "Local Project Map + Change Control for coding agents.",
   "keywords": [
     "codex",

package/src/cli.js

@@ -103,7 +103,7 @@ function requireHiveInitialized(cwd, commandName) {
     const missing = status.hive.missingSetupFiles && status.hive.missingSetupFiles.length > 0
       ? ` Missing: ${status.hive.missingSetupFiles.join(', ')}.`
       : '';
-    throw new Error(`${commandName} requires Hive Lite initialization. Run hive-lite init from the repo root first.${missing}`);
+    throw new Error(`${commandName} requires Hive Lite initialization. Use $hive-lite-bootstrap first.${missing}`);
   }
 }
 

package/src/lib/health.js

@@ -69,7 +69,7 @@ function readYamlHealth(root, name, fallback, findings) {
       field: '',
       message: `.hive/map/${name} is missing.`,
       impact: 'Hive Lite cannot evaluate Project Map health.',
-      fix: 'Run hive-lite init or restore the missing map file.',
+      fix: 'Use $hive-lite-bootstrap for first-time or partial setup. If this repo already had a committed Project Map, restore the missing map file from git instead of rebuilding it silently.',
     });
     return { doc: fallback, valid: false };
   }

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',
@@ -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';
@@ -154,21 +162,21 @@ function applySkillPreflight(root, options, current) {
     ...current,
     phaseGuess: 'skill_preflight',
     primaryAction: action({
-      kind: 'install_operator_skill',
-      label: `Install ${preflight.requiredSkill}`,
-      command: preflight.installCommand,
-      explanation: 'The recommended next operator step requires this Hive Lite skill in the selected agent target.',
+      kind: 'sync_operator_skill',
+      label: `Sync ${preflight.requiredSkill}`,
+      command: preflight.syncCommand,
+      explanation: 'The recommended next operator step requires a current Hive Lite skill in the selected agent target.',
     }),
     secondaryActions: [
       action({
         ...blockedAction,
         enabled: false,
-        disabledReason: `Install ${preflight.requiredSkill} first for the selected agent target.`,
+        disabledReason: `Sync ${preflight.requiredSkill} first for the selected agent target.`,
       }),
       ...current.secondaryActions,
     ],
-    summaryForHuman: `需要先安装 ${preflight.requiredSkill}，然后再继续 Hive Lite operator flow。`,
-    summaryForAgent: `The selected agent target is missing ${preflight.requiredSkill}. Run skills install before using the handoff skill.`,
+    summaryForHuman: `需要先同步 ${preflight.requiredSkill}，然后再继续 Hive Lite operator flow。`,
+    summaryForAgent: `The selected agent target is missing or has a stale ${preflight.requiredSkill}. Run skills sync before using the handoff skill.`,
     operatorSkillPreflight: preflight,
   };
 }
@@ -227,13 +235,13 @@ function evaluateNextAction(cwd, options = {}) {
   } else if (workspace.hive.state === 'hive_init_required') {
     phaseGuess = 'hive_init_required';
     primaryAction = action({
-      kind: 'run_hive_init',
-      label: 'Run hive-lite init',
-      command: 'hive-lite init',
-      explanation: 'This git repository has not been initialized for Hive Lite. Run init explicitly before using Hive Lite skills.',
+      kind: 'run_bootstrap_skill',
+      label: 'Use hive-lite-bootstrap',
+      prompt: bootstrapPrompt(),
+      explanation: 'This git repository is missing required Hive Lite setup files. Use the bootstrap skill to initialize or repair setup, build the first Project Map when needed, and prepare the setup/map commit before product work starts.',
     });
-    summaryForHuman = '当前项目还没有初始化 Hive Lite。请先在项目根目录运行 hive-lite init，然后提交 setup/map 文件，再用 hive-lite-map-maintainer 建立 Project Map。';
-    summaryForAgent = 'Hive Lite is not initialized. Stop all skill workflows and tell the human to run hive-lite init first.';
+    summaryForHuman = '当前项目缺少 Hive Lite setup 文件。建议使用 hive-lite-bootstrap 完成首次接入或 setup 修复，并在开始第一个需求前准备 setup/map 提交。';
+    summaryForAgent = 'Hive Lite setup is missing or incomplete. 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',
@@ -214,11 +215,11 @@ function targetSelection(options = {}, command = 'doctor') {
   };
 }
 
-function installCommandForOptions(options = {}) {
-  if (options.path && options.path !== true) return `hive-lite skills install --path ${options.path}`;
-  if (options.agent && options.agent !== true) return `hive-lite skills install --agent ${options.agent}`;
-  if (options.all) return 'hive-lite skills install --agent all';
-  return 'hive-lite skills install --agent <codex|claude|gemini>';
+function syncCommandForOptions(options = {}) {
+  if (options.path && options.path !== true) return `hive-lite skills sync --path ${options.path}`;
+  if (options.agent && options.agent !== true) return `hive-lite skills sync --agent ${options.agent}`;
+  if (options.all) return 'hive-lite skills sync --agent all';
+  return 'hive-lite skills sync --agent all';
 }
 
 function skillPreflight(cwd, skillName, options = {}) {
@@ -245,7 +246,7 @@ function skillPreflight(cwd, skillName, options = {}) {
     requiredSkill: skillName,
     targetSelection: targetSelection(options, 'doctor'),
     ready: targets.length > 0 && targets.every((target) => target.status === 'current'),
-    installCommand: installCommandForOptions(options),
+    syncCommand: syncCommandForOptions(options),
     targets,
   };
 }

package/src/lib/status.js

@@ -226,8 +226,8 @@ function actionsFor(state, latestId, diffMatches) {
   }
   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.'),
+      action('run_bootstrap_skill', 'Use hive-lite-bootstrap', '$hive-lite-bootstrap', 'Use the first-time setup or setup repair skill before ordinary start, finish, or map-maintainer workflows.'),
+      action('stop', 'Stop', null, 'Do not run start, finish, or map-maintainer skills until Hive Lite setup is complete.'),
     ];
   }
   if (state === 'clean') {
@@ -314,7 +314,7 @@ function evaluateWorkspaceStatus(cwd, options = {}) {
 
   if (!initialized) {
     state = 'hive_init_required';
-    reason = 'Hive Lite is not initialized in this git repository. Run hive-lite init before using Hive Lite skills.';
+    reason = 'Hive Lite setup is missing or incomplete in this git repository. Use $hive-lite-bootstrap for first-time setup or setup repair.';
   } else if (dirty && latest.change) {
     if (accepted(latest.change) && !committed(latest.change) && diffMatches) {
       state = 'accepted_uncommitted';