@lumenflow/cli 3.10.0 → 3.11.0

package/templates/core/ai/onboarding/agent-safety-card.md.template

@@ -27,20 +27,20 @@ Quick reference for AI agents working in LumenFlow projects.
 | `git stash` (on main)    | Hides work       |
 | `git clean -fd`          | Deletes files    |
 | Work in main after claim | Breaks isolation |
-| Skip wu:done             | Incomplete WU    |
+| Skip wu:prep or wu:done  | Incomplete WU    |
 
 ---
 
 ## Always Do
 
-| Action                     | Why              |
-| -------------------------- | ---------------- |
-| Read WU spec first         | Understand scope |
-| cd to worktree after claim | Isolation        |
-| Write tests before code    | TDD              |
-| Run gates before wu:done   | Quality          |
-| Run wu:done                | Complete WU      |
-| Stay within code_paths     | Scope discipline |
+| Action                               | Why                               |
+| ------------------------------------ | --------------------------------- |
+| Read WU spec first                   | Understand scope                  |
+| cd to worktree after claim           | Isolation                         |
+| Write tests before code              | TDD                               |
+| Run wu:prep in the claimed workspace | Quality and lifecycle correctness |
+| Run wu:done from main                | Complete WU                       |
+| Stay within code_paths               | Scope discipline                  |
 
 ---
 
@@ -96,7 +96,7 @@ If same error happens 3 times:
 
 ```bash
 # Check lane availability
-cat docs/04-operations/tasks/status.md
+cat {{DOCS_TASKS_PATH}}/status.md
 
 # Claim a WU
 pnpm wu:claim --id WU-XXX --lane <Lane>
@@ -104,13 +104,11 @@ pnpm wu:claim --id WU-XXX --lane <Lane>
 # Work in worktree
 cd worktrees/<lane>-wu-xxx
 
-# Run gates
-pnpm gates          # Code changes
-pnpm gates --docs-only  # Docs changes
+# Prep in the claimed workspace
+pnpm wu:prep --id WU-XXX
 
-# Complete WU
-cd /path/to/main
-pnpm wu:done --id WU-XXX
+# Complete from main
+cd /path/to/main && pnpm wu:done --id WU-XXX
 ```
 
 ---
@@ -118,6 +116,7 @@ pnpm wu:done --id WU-XXX
 ## Completion Checklist
 
 - [ ] Gates pass
+- [ ] Run wu:prep in the claimed workspace
 - [ ] cd to main
 - [ ] Run wu:done
 - [ ] Verify success output

package/templates/core/ai/onboarding/first-15-mins.md.template

@@ -0,0 +1,80 @@
+# First 15 Minutes with LumenFlow
+
+**Last updated:** {{DATE}}
+
+A fast start for agents entering an existing LumenFlow project.
+
+---
+
+## Minute 0-2: Verify the Workspace
+
+```bash
+ls LUMENFLOW.md AGENTS.md workspace.yaml
+pnpm exec lumenflow doctor
+```
+
+If the doctor reports a repo-level problem, stop there and fix it before claiming work.
+
+---
+
+## Minute 2-5: Read the Required Docs
+
+1. Open `LUMENFLOW.md` for the lifecycle overview.
+2. Scan `AGENTS.md` for repo-specific workflow rules.
+3. Review `.lumenflow/constraints.md` for the non-negotiables.
+4. Open `starting-prompt.md` if you need the full onboarding flow.
+
+---
+
+## Minute 5-8: Find the Work
+
+```bash
+cat {{DOCS_TASKS_PATH}}/status.md
+ls {{DOCS_TASKS_PATH}}/wu/*.yaml | head -5
+```
+
+Read the assigned WU spec before touching files.
+
+---
+
+## Minute 8-12: Claim and Move
+
+```bash
+pnpm wu:claim --id WU-XXX --lane "Framework: CLI"
+cd worktrees/framework-cli-wu-xxx
+pnpm bootstrap
+```
+
+After `wu:claim`, all implementation work happens in the worktree, not in the main checkout.
+
+---
+
+## Minute 12-15: Start the Right Cycle
+
+For code WUs:
+
+```bash
+pnpm test -- --run
+```
+
+For docs-heavy WUs:
+
+```bash
+pnpm format {{DOCS_ONBOARDING_PATH}}/*.md
+```
+
+Before completion, always use the two-step flow:
+
+```bash
+pnpm wu:prep --id WU-XXX
+cd <project-root> && pnpm wu:done --id WU-XXX
+```
+
+---
+
+## Key Reminders
+
+- Stay in the claimed worktree.
+- Run `pnpm lumenflow:commands` for public CLI discovery, then `--help` before first use.
+- Use `pnpm wu:prep` before `pnpm wu:done`; do not jump straight to `wu:done`.
+- If context starts getting heavy, read `./wu-sizing-guide.md` before pushing further.

package/templates/core/ai/onboarding/first-wu-mistakes.md.template

@@ -254,7 +254,7 @@ pnpm wu:edit --id WU-1348 --notes "Research findings: ..."
 **Option 2: Direct file edit**
 
 ```bash
-# Edit docs/04-operations/tasks/wu/WU-1348.yaml directly
+# Edit {{DOCS_TASKS_PATH}}/wu/WU-1348.yaml directly
 ```
 
 ### Recognizing Implied Directives
@@ -311,7 +311,7 @@ sizing_estimate:
   exception_reason: All markdown documentation files, low complexity
 ```
 
-2. **Split the WU** if the estimate genuinely exceeds session capacity (see [wu-sizing-guide.md](../../wu-sizing-guide.md) section 3 for splitting patterns).
+2. **Split the WU** if the estimate genuinely exceeds session capacity (see [wu-sizing-guide.md](./wu-sizing-guide.md) section 3 for splitting patterns).
 
 **Strict mode:** Teams can enforce sizing compliance for delegated work with `--strict-sizing` on `wu:brief`. In strict mode, missing or non-compliant sizing metadata blocks the operation.
 
@@ -320,7 +320,7 @@ sizing_estimate:
 pnpm wu:brief --id WU-XXX --client claude-code --strict-sizing
 ```
 
-See the [WU Sizing Guide](../../wu-sizing-guide.md) section 1.4 for the full contract specification.
+See the [WU Sizing Guide](./wu-sizing-guide.md) section 1.4 for the full contract specification.
 
 ---
 

package/templates/core/ai/onboarding/initiative-orchestration.md.template

@@ -10,7 +10,7 @@ Step-by-step guide for agents orchestrating multi-WU initiatives. This document
 
 Before orchestrating an initiative, ensure:
 
-1. The initiative YAML exists at `docs/04-operations/tasks/initiatives/INIT-XXX.yaml`
+1. The initiative YAML exists at `{{DOCS_TASKS_PATH}}/initiatives/INIT-XXX.yaml`
 2. All WUs are linked to the initiative via `initiative:add-wu`
 3. Dependencies between WUs are defined (blocking relationships)
 4. Lane lifecycle is locked (`pnpm lane:status` shows `locked`)

package/templates/core/ai/onboarding/lane-inference.md.template

@@ -0,0 +1,64 @@
+# Lane Inference
+
+**Last updated:** {{DATE}}
+
+Lanes define which area of the system a WU belongs to. Use the lane tools before creating or reshaping work.
+
+---
+
+## The Two Inputs
+
+Lane fit is driven by:
+
+1. The WU `code_paths`
+2. The implementation description or acceptance criteria
+
+If those disagree with the assigned lane, fix the lane or split the WU.
+
+---
+
+## Runtime Checks
+
+```bash
+pnpm wu:infer-lane --id WU-XXX
+pnpm lane:status
+```
+
+Use `wu:infer-lane` for a WU-level recommendation and `lane:status` for current lifecycle state.
+
+---
+
+## Taxonomy Source
+
+Lane metadata is stored in `.lumenflow.lane-inference.yaml`.
+
+Regenerate it when taxonomy drifts from `workspace.yaml`:
+
+```bash
+pnpm lane:suggest --output .lumenflow.lane-inference.yaml
+pnpm lane:validate
+```
+
+---
+
+## Before Delivery WUs
+
+Lane lifecycle must be complete before the first delivery WU:
+
+```bash
+pnpm lane:setup
+pnpm lane:validate
+pnpm lane:lock
+```
+
+`locked` means delivery WUs can be created safely.
+
+---
+
+## Common Failure Mode
+
+If a WU touches files outside the assigned lane's code paths, do not just keep coding.
+
+- Propose a lane change if the WU is genuinely in the wrong lane.
+- Split the WU if the work spans multiple lanes.
+- Update the taxonomy only when the lane model itself is outdated.

package/templates/core/ai/onboarding/local-only.md.template

@@ -0,0 +1,56 @@
+# Local-Only Development
+
+**Last updated:** {{DATE}}
+
+Use this local-only mode when the repo has no `origin` remote yet or you are intentionally working offline.
+
+---
+
+## Raw YAML Configuration
+
+Set the workspace config under `software_delivery.git`:
+
+```yaml
+software_delivery:
+  git:
+    requireRemote: false
+```
+
+---
+
+## Safer CLI Alternative
+
+Use the config command when possible instead of editing YAML directly:
+
+```bash
+pnpm config:set --key git.requireRemote --value false
+```
+
+The `git.requireRemote` dotpath is rooted under `software_delivery`.
+
+---
+
+## Behavior Changes
+
+When `requireRemote: false`:
+
+- `wu:create` skips remote fetch requirements.
+- `wu:claim` can proceed without pushing a lane branch.
+- Local evaluation and air-gapped testing remain unblocked.
+
+When `requireRemote: true` (default):
+
+- `wu:create` and `wu:claim` expect `origin/main`.
+- Team-visible coordination happens through the remote.
+
+---
+
+## Transitioning Back to Remote Mode
+
+```bash
+pnpm config:set --key git.requireRemote --value true
+git remote add origin <url>
+git push -u origin main
+```
+
+If the repo already has the correct remote, you can simply remove the override and resume the standard workflow.

package/templates/core/ai/onboarding/quick-ref-commands.md.template

@@ -5,10 +5,10 @@
 Reference for CLI commands. Organized by category for quick discovery.
 
 > **Rule (WU-1358, WU-1530, WU-2228):** This document is a quick reference, not the complete list.
-> LumenFlow has 100+ commands. To see ALL available commands:
+> Use `pnpm lumenflow:commands` for the public CLI surface:
 >
 > ```bash
-> pnpm lumenflow:commands    # List ALL CLI commands — the authoritative source
+> pnpm lumenflow:commands    # List public commands, aliases, and legacy surfaces
 > ```
 >
 > Before using any unfamiliar command, run `--help` first:
@@ -21,6 +21,9 @@ Reference for CLI commands. Organized by category for quick discovery.
 >
 > **Never conclude a command doesn't exist without running `pnpm lumenflow:commands` first.**
 >
+> Repo-only scripts such as `pnpm docs:validate`, `pnpm docs:generate`, and
+> `pnpm pre-release:check` are maintainer scripts, not part of the public CLI manifest.
+>
 > Maintainer reference for validation ownership: [validator-boundaries.md](../../validator-boundaries.md).
 
 ## Help-First Usage Examples By Category
@@ -36,7 +39,7 @@ Run `--help` first, then run the real command with explicit flags.
 | Gates & Quality     | `pnpm gates --help`                   | `pnpm gates --docs-only`                                                 |
 | Memory & Sessions   | `pnpm mem:checkpoint --help`          | `pnpm mem:checkpoint --wu WU-1561`                                       |
 | State Management    | `pnpm state:doctor --help`            | `pnpm state:doctor --json`                                               |
-| Dependencies        | `pnpm deps:add --help`                | `pnpm deps:add --pkg zod`                                                |
+| Repo-Only Scripts   | `pnpm docs:validate --help`           | `pnpm docs:validate`                                                     |
 | Plans               | `pnpm plan:link --help`               | `pnpm plan:link --id INIT-021 --plan lumenflow://plans/INIT-021-plan.md` |
 | Initiatives         | `pnpm initiative:status --help`       | `pnpm initiative:status --id INIT-021`                                   |
 | Orchestration       | `pnpm orchestrate:init-status --help` | `pnpm orchestrate:init-status --id INIT-021`                             |
@@ -53,23 +56,25 @@ Run `--help` first, then run the real command with explicit flags.
 
 **For this monorepo (development):**
 
-| Command                    | Description                                       |
-| -------------------------- | ------------------------------------------------- |
-| `pnpm setup`               | Install deps and build CLI (first time)           |
-| `pnpm bootstrap`           | Build CLI with dependency closure (worktree-safe) |
-| `pnpm build`               | Build all packages                                |
-| `pnpm build:dist`          | Build distribution packages                       |
-| `pnpm dev`                 | Start development mode                            |
-| `pnpm clean`               | Clean build artifacts and caches                  |
-| `pnpm pack:all`            | Pack all packages for distribution                |
-| `pnpm lumenflow:init`      | Scaffold LumenFlow in a project                   |
-| `pnpm docs:sync`           | Sync agent docs (for upgrades)                    |
-| `pnpm sync:templates`      | Sync templates to project                         |
-| `pnpm lumenflow:upgrade`   | Upgrade LumenFlow packages                        |
-| `pnpm lumenflow:doctor`    | Diagnose LumenFlow configuration                  |
-| `pnpm lumenflow:integrate` | Generate enforcement hooks for client             |
-| `pnpm cloud:connect`       | Configure cloud control-plane access              |
-| `npx lumenflow commands`   | List all available CLI commands                   |
+| Command                                            | Description                                                    |
+| -------------------------------------------------- | -------------------------------------------------------------- |
+| `pnpm setup`                                       | Install deps and build CLI (first time)                        |
+| `pnpm bootstrap`                                   | Build CLI with dependency closure (worktree-safe)              |
+| `pnpm build`                                       | Build all packages                                             |
+| `pnpm build:dist`                                  | Build distribution packages                                    |
+| `pnpm dev`                                         | Start development mode                                         |
+| `pnpm clean`                                       | Clean build artifacts and caches                               |
+| `pnpm pack:all`                                    | Pack all packages for distribution                             |
+| `pnpm exec lumenflow init`                         | Scaffold LumenFlow in a project                                |
+| `pnpm exec lumenflow init --docs-structure simple` | Use simple docs structure (`docs/tasks`)                       |
+| `pnpm exec lumenflow init --docs-structure arc42`  | Use arc42 docs structure (`{{DOCS_OPERATIONS_PATH}}`)                |
+| `pnpm docs:sync --force`                           | Refresh scaffolded onboarding docs and supported vendor assets |
+| `pnpm sync:templates`                              | Sync repo docs into bundled templates                          |
+| `pnpm lumenflow:upgrade`                           | Upgrade LumenFlow packages                                     |
+| `pnpm lumenflow:doctor`                            | Diagnose LumenFlow configuration                               |
+| `pnpm lumenflow:integrate`                         | Generate enforcement hooks for client                          |
+| `pnpm cloud:connect`                               | Configure cloud control-plane access                           |
+| `npx lumenflow commands`                           | List all available CLI commands                                |
 
 **For external projects (end users):**
 
@@ -78,12 +83,12 @@ Run `--help` first, then run the real command with explicit flags.
 pnpm add -D @lumenflow/cli  # or: npm install -D @lumenflow/cli
 
 # Initialize LumenFlow
-pnpm exec lumenflow
+pnpm exec lumenflow init
 
 # With client-specific overlays
-pnpm exec lumenflow --client claude   # Claude Code
-pnpm exec lumenflow --client cursor   # Cursor IDE
-pnpm exec lumenflow --client all      # All clients
+pnpm exec lumenflow init --client claude   # Claude Code
+pnpm exec lumenflow init --client cursor   # Cursor IDE
+pnpm exec lumenflow init --client all      # All clients
 ```
 
 ---
@@ -93,21 +98,29 @@ pnpm exec lumenflow --client all      # All clients
 These commands use **micro-worktree isolation** internally — they handle their own
 commit and push atomically. Do NOT wrap them in a WU or use raw `pnpm update`/`git commit`.
 
-| Command                                           | Description                               |
-| ------------------------------------------------- | ----------------------------------------- |
-| `pnpm lumenflow:upgrade --version 3.5.0`          | Upgrade all 7 @lumenflow/\* packages      |
-| `pnpm lumenflow:upgrade --latest`                 | Upgrade to latest version                 |
-| `pnpm lumenflow:upgrade --latest --dry-run`       | Preview upgrade without executing         |
-| `pnpm config:set --key <dotpath> --value <value>` | Set workspace.yaml config (Zod-validated) |
-| `pnpm config:get --key <dotpath>`                 | Read workspace.yaml config                |
-| `pnpm cloud:connect`                              | Configure cloud control-plane access      |
-| `pnpm docs:sync`                                  | Sync agent docs after upgrade             |
-| `pnpm sync:templates`                             | Sync templates to project                 |
+| Command                                           | Description                                      |
+| ------------------------------------------------- | ------------------------------------------------ |
+| `pnpm lumenflow:upgrade --version 3.5.0`          | Upgrade all 7 @lumenflow/\* packages             |
+| `pnpm lumenflow:upgrade --latest`                 | Upgrade to latest version                        |
+| `pnpm lumenflow:upgrade --latest --dry-run`       | Preview upgrade without executing                |
+| `pnpm config:set --key <dotpath> --value <value>` | Set workspace.yaml config (Zod-validated)        |
+| `pnpm config:get --key <dotpath>`                 | Read workspace.yaml config                       |
+| `pnpm cloud:connect`                              | Configure cloud control-plane access             |
+| `pnpm docs:sync --force`                          | Refresh scaffolded onboarding docs after upgrade |
+| `pnpm sync:templates`                             | Sync repo docs into bundled templates            |
 
 **Key principle:** If a LumenFlow CLI command exists for the operation, use it instead of
 raw pnpm/git. These tooling commands commit directly to main via micro-worktree — no dirty
 files, no manual git, no WU ceremony. Only actual **code changes** need WUs.
 
+`docs:sync` refreshes the scaffolded onboarding set plus supported vendor assets. Existing
+tracked docs are skipped by default; use `--force` when you intentionally want the refresh.
+
+For existing installs, upgrade packages first with `pnpm lumenflow:upgrade --latest`, then run
+`pnpm docs:sync --force` if you want refreshed onboarding docs and vendor assets. The improved
+default `wu:brief` behavior comes from the package upgrade itself. New installs get those defaults
+automatically, and `.lumenflow/templates/` remains optional unless you want custom overrides.
+
 > **Anti-pattern:** Do NOT use `pnpm update @lumenflow/*` to upgrade packages.
 > This leaves dirty `package.json` and `pnpm-lock.yaml` on main.
 > Use `pnpm lumenflow:upgrade` instead — it handles everything atomically.
@@ -116,25 +129,28 @@ files, no manual git, no WU ceremony. Only actual **code changes** need WUs.
 
 ## WU Lifecycle
 
-| Command                                         | Description                                                           |
-| ----------------------------------------------- | --------------------------------------------------------------------- |
-| `pnpm wu:create --lane <Lane> --title "..." ..` | Create new WU spec (ID auto-generated; see fields below)              |
-| `pnpm wu:claim --id WU-XXX --lane <Lane>`       | Claim WU and create worktree (default)                                |
-| `pnpm wu:claim --id WU-XXX --lane <L> --cloud`  | Claim WU in cloud/branch-pr mode (no worktree)                        |
-| `pnpm wu:prep --id WU-XXX [--full-tests]`       | Run gates, prep for wu:done (`tests.unit` scoped by default)          |
-| `pnpm wu:done --id WU-XXX`                      | Complete WU (merge or PR, stamp, cleanup)                             |
-| `pnpm wu:edit --id WU-XXX --description "..."`  | Edit WU spec fields (run --help for all flags)                        |
-| `pnpm wu:escalate --id WU-XXX`                  | Show escalation status for a WU                                       |
-| `pnpm wu:escalate --resolve --id WU-XXX`        | Resolve escalation (sets resolved_by/resolved_at)                     |
-| `pnpm wu:block --id WU-XXX --reason "..."`      | Block WU with reason                                                  |
-| `pnpm wu:unblock --id WU-XXX`                   | Unblock WU                                                            |
-| `pnpm wu:release --id WU-XXX`                   | Release orphaned WU (in_progress to ready)                            |
-| `pnpm wu:status --id WU-XXX`                    | Show WU status, location, valid commands                              |
-| `pnpm wu:brief --id WU-XXX --client <client>`   | Generate handoff prompt + record evidence (claimed workspace/branch)  |
-| `pnpm wu:brief --id WU-XXX --evidence-only`     | Record wu:brief evidence only (self-implementation, no prompt output) |
-| `pnpm wu:brief --id WU-XXX --no-context`        | Generate prompt without memory context injection                      |
-| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`  | Generate prompt, record lineage, and store brief hash attestation     |
-| `pnpm wu:sandbox --id WU-XXX -- <cmd>`          | Run command through hardened WU sandbox backend                       |
+| Command                                                        | Description                                                           |
+| -------------------------------------------------------------- | --------------------------------------------------------------------- |
+| `pnpm wu:create --lane <Lane> --title "..." ..`                | Create new WU spec (ID auto-generated; see fields below)              |
+| `pnpm wu:claim --id WU-XXX --lane <Lane>`                      | Claim WU and create worktree (default)                                |
+| `pnpm wu:claim --id WU-XXX --lane <L> --cloud`                 | Claim WU in cloud/branch-pr mode (no worktree)                        |
+| `pnpm wu:prep --id WU-XXX [--full-tests]`                      | Run gates, prep for wu:done (`tests.unit` scoped by default)          |
+| `pnpm wu:done --id WU-XXX`                                     | Complete WU (merge or PR, stamp, cleanup)                             |
+| `pnpm wu:edit --id WU-XXX --description "..."`                 | Edit WU spec fields (run --help for all flags)                        |
+| `pnpm wu:escalate --id WU-XXX`                                 | Show escalation status for a WU                                       |
+| `pnpm wu:escalate --resolve --id WU-XXX`                       | Resolve escalation (sets resolved_by/resolved_at)                     |
+| `pnpm approval:request --type <type> --subject <json>`         | Request control-plane approval for an action                          |
+| `pnpm approval:review --id <approvalId> --decision <decision>` | Resolve an approval decision (`approved`/`rejected`/`expired`)        |
+| `pnpm approval:list [--status <status>]`                       | List approvals with optional status/type filters                      |
+| `pnpm wu:block --id WU-XXX --reason "..."`                     | Block WU with reason                                                  |
+| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU                                                            |
+| `pnpm wu:release --id WU-XXX`                                  | Release orphaned WU (in_progress to ready)                            |
+| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                              |
+| `pnpm wu:brief --id WU-XXX --client <client>`                  | Generate handoff prompt + record evidence (claimed workspace/branch)  |
+| `pnpm wu:brief --id WU-XXX --evidence-only`                    | Record wu:brief evidence only (self-implementation, no prompt output) |
+| `pnpm wu:brief --id WU-XXX --no-context`                       | Generate prompt without memory context injection                      |
+| `pnpm wu:delegate --id WU-XXX --parent-wu <P>`                 | Generate prompt, record lineage, and store brief hash attestation     |
+| `pnpm wu:sandbox --id WU-XXX -- <cmd>`                         | Run command through hardened WU sandbox backend                       |
 
 ### WU Maintenance
 
@@ -156,23 +172,23 @@ files, no manual git, no WU ceremony. Only actual **code changes** need WUs.
 
 ## Gates & Quality
 
-| Command                           | Description                                     |
-| --------------------------------- | ----------------------------------------------- |
-| `pnpm gates`                      | Run all quality gates                           |
-| `pnpm gates --docs-only`          | Run gates for docs changes                      |
-| `pnpm format`                     | Format all files (Prettier)                     |
-| `pnpm format:check`               | Check formatting without changes                |
-| `pnpm lint`                       | Run ESLint                                      |
-| `pnpm typecheck`                  | Run TypeScript type checking                    |
-| `pnpm test`                       | Run all tests (Vitest)                          |
-| `pnpm spec:linter`                | Validate WU specs (all) ¹                       |
-| `pnpm lane:health`                | Check lane config health                        |
-| `pnpm lane:suggest --paths "..."` | Suggest lane for code paths                     |
-| `pnpm lane:status`                | Show lane lifecycle status                      |
-| `pnpm lane:setup`                 | Create/update draft lane config                 |
-| `pnpm lane:validate`              | Validate lane draft artifacts                   |
-| `pnpm lane:lock`                  | Lock lane lifecycle for WU create               |
-| `pnpm lane:edit --lane <L>`       | Edit lane definition (rename, wip-limit, paths) |
+| Command                                                     | Description                                               |
+| ----------------------------------------------------------- | --------------------------------------------------------- |
+| `pnpm gates`                                                | Run all quality gates                                     |
+| `pnpm gates --docs-only`                                    | Run gates for docs changes                                |
+| `pnpm format`                                               | Format all files (Prettier)                               |
+| `pnpm format:check`                                         | Check formatting without changes                          |
+| `pnpm lint`                                                 | Run ESLint                                                |
+| `pnpm typecheck`                                            | Run TypeScript type checking                              |
+| `pnpm test`                                                 | Run all tests (Vitest)                                    |
+| `pnpm spec:linter`                                          | Validate WU specs (all) ¹                                 |
+| `pnpm lane:health`                                          | Check lane config health                                  |
+| `pnpm lane:suggest --output .lumenflow.lane-inference.yaml` | Regenerate lane inference taxonomy from project structure |
+| `pnpm lane:status`                                          | Show lane lifecycle status                                |
+| `pnpm lane:setup`                                           | Create/update draft lane config                           |
+| `pnpm lane:validate`                                        | Validate lane draft artifacts                             |
+| `pnpm lane:lock`                                            | Lock lane lifecycle for WU create                         |
+| `pnpm lane:edit --name <L>`                                 | Edit lane definition (rename, wip-limit, paths)           |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
@@ -281,12 +297,17 @@ and [YAML editing policy](../../../../../.lumenflow/rules/yaml-editing-policy.md
 
 ---
 
-## Dependencies
+## Repo-Only Scripts
+
+These scripts are useful in this monorepo, but they are **repo-only scripts** rather than part of
+the public CLI surface shown by `pnpm lumenflow:commands`.
 
-| Command                         | Description                    |
-| ------------------------------- | ------------------------------ |
-| `pnpm deps:add --pkg <name>`    | Add dependency to package      |
-| `pnpm deps:remove --pkg <name>` | Remove dependency from package |
+| Command                  | Description                            |
+| ------------------------ | -------------------------------------- |
+| `pnpm docs:validate`     | Validate generated docs against source |
+| `pnpm docs:generate`     | Regenerate docs outputs                |
+| `pnpm pre-release:check` | Run pre-release verification           |
+| `pnpm release:changeset` | Create or update release changesets    |
 
 ---
 
@@ -305,6 +326,7 @@ stub in `$LUMENFLOW_HOME/plans/` and automatically set the WU's `plan` field to
 | Command                                                                  | Description                                                         |
 | ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
 | `pnpm plan:create --id INIT-XXX --title "..."`                           | Create a repo-native plan file in configured `directories.plansDir` |
+| `pnpm plan:create --id INIT-XXX --title "..." --from <path>`             | Import external plan file into repo plansDir                        |
 | `pnpm plan:edit --id INIT-XXX --section Goal --content "..."`            | Edit a section in a plan file                                       |
 | `pnpm plan:link --id INIT-XXX --plan lumenflow://plans/INIT-XXX-plan.md` | Link plan URI to initiative or WU                                   |
 | `pnpm plan:promote --id INIT-XXX`                                        | Promote plan status to approved                                     |
@@ -319,6 +341,9 @@ stub in `$LUMENFLOW_HOME/plans/` and automatically set the WU's `plan` field to
 # Create a plan
 pnpm plan:create --id INIT-001 --title "Auth System Rollout"
 
+# Import an external plan into the repo
+pnpm plan:create --id INIT-001 --title "Auth System Rollout" --from ~/.claude/plans/my-plan.md
+
 # Link plan URI to initiative
 pnpm plan:link --id INIT-001 --plan lumenflow://plans/INIT-001-plan.md
 ```
@@ -399,6 +424,7 @@ For the complete orchestration workflow (delegation, memory coordination, failur
 | `pnpm flow:report`      | Generate flow metrics report                           |
 | `pnpm flow:bottlenecks` | Identify flow bottlenecks                              |
 | `pnpm metrics:snapshot` | Capture metrics snapshot                               |
+| `pnpm cost:summary`     | Summarize local cost telemetry by model, agent, and WU |
 | `pnpm metrics`          | View workflow metrics                                  |
 | `pnpm strict:progress`  | Report strict TypeScript backlog and guard regressions |
 
@@ -647,6 +673,16 @@ Check current lifecycle state any time:
 pnpm lane:status
 ```
 
+### Lane Taxonomy Drift (workspace.yaml vs inference)
+
+If lane commands report drift between `workspace.yaml` lane definitions and
+`.lumenflow.lane-inference.yaml`, sync taxonomy first, then re-validate:
+
+```bash
+pnpm lane:suggest --interactive --output .lumenflow.lane-inference.yaml
+pnpm lane:validate
+```
+
 ---
 
 ## Local / Offline Behavior (No Remote)
@@ -656,8 +692,9 @@ By default, `wu:create` and `wu:claim` expect an `origin` remote and will fetch
 For local-only or offline development, add this to `workspace.yaml`:
 
 ```yaml
-git:
-  requireRemote: false
+software_delivery:
+  git:
+    requireRemote: false
 ```
 
 When `requireRemote: false`:
@@ -677,9 +714,9 @@ When `requireRemote: true` (default):
 
 | Path                                      | Description          |
 | ----------------------------------------- | -------------------- |
-| `docs/04-operations/tasks/wu/WU-XXX.yaml` | WU specification     |
-| `docs/04-operations/tasks/status.md`      | Current status board |
-| `docs/04-operations/tasks/backlog.md`     | Backlog summary      |
+| `{{DOCS_TASKS_PATH}}/wu/WU-XXX.yaml` | WU specification     |
+| `{{DOCS_TASKS_PATH}}/status.md`      | Current status board |
+| `{{DOCS_TASKS_PATH}}/backlog.md`     | Backlog summary      |
 | `.lumenflow/stamps/WU-XXX.done`           | Completion stamp     |
 | `worktrees/<lane>-wu-xxx/`                | Worktree directory   |
 
@@ -740,18 +777,11 @@ pnpm wu:cleanup --id WU-XXX
 - Regenerates backlog.md and status.md
 - Deletes the lane branch (local and remote)
 
-**Cloud auto-detection (opt-in):**
+**Cloud activation is explicit-only:**
 
-```yaml
-# workspace.yaml
-cloud:
-  auto_detect: true # default: false
-  env_signals:
-    - name: CI
-    - name: CODEX
-    - name: GITHUB_ACTIONS
-      equals: 'true'
-```
+Branch-PR mode activates only through `--cloud` or `LUMENFLOW_CLOUD=1`.
+Runtime identity env vars such as `CLAUDECODE`, `CODEX`, `CI`, and configured
+`cloud.auto_detect` / `env_signals` values do not activate cloud mode.
 
 ### Enforcement Hooks (WU-1367)
 
@@ -790,4 +820,4 @@ For a complete picture of how all WU commands, memory tools, and orchestration t
 - **[Failure-Mode Runbook](../../lumenflow-agent-capsule.md)** -- Concrete remediation for main-behind-origin, partial-claim state, spawn-provenance enforcement, and wu:recover usage
 - **[Troubleshooting wu:done](./troubleshooting-wu-done.md)** -- Most common agent mistake (two-step wu:prep + wu:done workflow)
 - **[First WU Mistakes](./first-wu-mistakes.md)** -- Common first-time pitfalls and how to avoid them
-- **[WU Sizing Guide](../../wu-sizing-guide.md)** -- Context safety triggers, complexity assessment, and session strategies
+- **[WU Sizing Guide](./wu-sizing-guide.md)** -- Context safety triggers, complexity assessment, and session strategies