@lumenflow/cli 3.10.1 → 3.11.0

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

package/templates/core/ai/onboarding/starting-prompt.md.template

@@ -13,10 +13,12 @@ This is the complete onboarding document for AI agents working with LumenFlow. R
 Before concluding a command doesn't exist, **always check what's available**:
 
 ```bash
-pnpm lumenflow:commands    # List ALL available CLI commands (100+)
+pnpm lumenflow:commands    # List public CLI commands, aliases, and legacy surfaces
 ```
 
 LumenFlow has commands for WU lifecycle, maintenance, memory, initiatives, orchestration, metrics, packs, and more. Never guess or assume — run `pnpm lumenflow:commands` first.
+Repo-only scripts such as `pnpm docs:validate` and `pnpm pre-release:check` are monorepo scripts,
+not part of that public command list.
 
 ### Help-First Rule
 
@@ -102,7 +104,9 @@ If work spans multiple WUs or multiple days, create an initiative first.
 When creating WUs or scoping initiatives, always evaluate whether the assigned lane fits the actual work:
 
 - **Check code_paths alignment**: Compare the WU's `code_paths` against lane definitions in `workspace.yaml`. If the majority of paths belong to a different lane, propose a lane change.
-- **Use lane:suggest**: Run `pnpm lane:suggest --paths "src/file.ts"` to get a recommendation.
+- **Use lane inference tooling correctly**:
+  - For a WU lane recommendation, run `pnpm wu:infer-lane --id WU-XXXX`.
+  - To regenerate derived lane taxonomy metadata, run `pnpm lane:suggest --output .lumenflow.lane-inference.yaml`.
 - **Propose changes proactively**: If scope expansion during implementation pushes a WU beyond its lane's boundaries, flag the mismatch to the user and suggest either a lane change or a WU split.
 - **Initiative-level review**: When planning an initiative with multiple WUs, ensure each WU is assigned to the lane whose `code_paths` best cover the work. Systematic mismatches signal that lane taxonomy may need updating.
 
@@ -112,7 +116,7 @@ When creating WUs or scoping initiatives, always evaluate whether the assigned l
 
 ```bash
 # 1. Check your assigned WU
-cat docs/04-operations/tasks/wu/WU-XXXX.yaml
+cat {{DOCS_TASKS_PATH}}/wu/WU-XXXX.yaml
 
 # 2. Claim the WU (creates isolated worktree)
 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
@@ -125,13 +129,12 @@ pnpm bootstrap
 
 # 4. Do your work here (not in main!)
 
-# 5. Run gates before completion
-pnpm gates              # For code changes
-pnpm gates --docs-only  # For documentation changes
+# 5. Prep from the worktree (runs the correct gates)
+pnpm wu:prep --id WU-XXXX
+# This prints the copy-paste completion command
 
 # 6. Return to main and complete
-cd /path/to/main/checkout
-pnpm wu:done --id WU-XXXX
+cd /path/to/main/checkout && pnpm wu:done --id WU-XXXX
 ```
 
 ## Quick Start -- Cloud / Branch-PR (Copy This)
@@ -140,7 +143,7 @@ For cloud agents (Codex, Claude web, CI bots) that cannot create local worktrees
 
 ```bash
 # 1. Check your assigned WU
-cat docs/04-operations/tasks/wu/WU-XXXX.yaml
+cat {{DOCS_TASKS_PATH}}/wu/WU-XXXX.yaml
 
 # 2. Claim in cloud mode (no worktree, sets claimed_mode: branch-pr)
 pnpm wu:claim --id WU-XXXX --lane "Lane Name" --cloud
@@ -158,28 +161,28 @@ pnpm wu:done --id WU-XXXX
 pnpm wu:cleanup --id WU-XXXX
 ```
 
-**Cloud activation methods (in precedence order):**
+**Activation is explicit-only:**
 
 1. `--cloud` flag on `wu:claim` (explicit, always wins)
 2. `LUMENFLOW_CLOUD=1` environment variable (explicit, always wins)
-3. Config-driven auto-detection when `cloud.auto_detect: true` in `workspace.yaml`
 
-**Auto-detection configuration:**
+Runtime identity env vars such as `CLAUDECODE`, `CODEX`, or `CI` do not activate cloud mode.
+The `cloud.auto_detect` and `env_signals` config keys remain schema-supported metadata,
+but they do not change runtime activation behavior.
 
 ```yaml
 # workspace.yaml
 cloud:
-  auto_detect: true # default: false (opt-in)
-  env_signals: # checked only when auto_detect is true
-    - name: CI # presence check (any non-empty value)
-    - name: CODEX
-    - name: GITHUB_ACTIONS
-      equals: 'true' # exact match required
+  auto_detect: false
+  env_signals: []
 ```
 
-When `auto_detect` is enabled, `wu:claim` checks the listed environment signals
-and activates cloud mode if any match. No vendor-specific signals are hardcoded;
-all signals are user-configured.
+Use explicit activation instead:
+
+```bash
+pnpm wu:claim --id WU-XXXX --lane "Lane Name" --cloud
+LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
+```
 
 ---
 
@@ -237,21 +240,26 @@ pnpm wu:claim --id WU-123 --lane "Framework: CLI" --cloud
 
 **Why:** Worktrees isolate your changes. Main checkout is protected by git hooks. Branch-PR mode is the valid exception for cloud agents that cannot create local worktrees.
 
-### Rule 2: ALWAYS Run wu:done
+### Rule 2: Use wu:prep Then wu:done
 
-After gates pass, you MUST run `pnpm wu:done --id WU-XXXX` from the main checkout. Do not just write "To complete: run wu:done" - actually run it.
+Completion is a two-step flow:
+
+1. From the worktree, run `pnpm wu:prep --id WU-XXXX`
+2. From main, copy-paste the printed `pnpm wu:done --id WU-XXXX` command
+
+Do not just write "to complete: run wu:done" and stop.
 
 ```bash
 # WRONG
 "Work complete. Next step: run pnpm wu:done --id WU-123"
 
 # RIGHT
-cd /path/to/main
-pnpm wu:done --id WU-123
+pnpm wu:prep --id WU-123
+cd /path/to/main && pnpm wu:done --id WU-123
 # Then report: "WU-123 completed. Changes merged to main."
 ```
 
-**Why:** wu:done merges your changes, creates the completion stamp, and releases the lane lock.
+**Why:** `wu:prep` runs the correct gates in the claimed workspace. `wu:done` then merges or opens the PR, writes the completion metadata, and releases the lane lock.
 
 ### Rule 3: Use Relative Paths Only
 
@@ -333,6 +341,16 @@ pnpm config:set --key gates.minCoverage --value 85
 pnpm config:set --key agents.methodology.principles --value Library-First,KISS
 ```
 
+For lanes:
+
+- `workspace.yaml` (`software_delivery.lanes.definitions`) is the source of truth for lane validation and claim-time lane checks.
+- `.lumenflow.lane-inference.yaml` is derived metadata for suggestion/classification workflows.
+- After lane definition changes, regenerate taxonomy metadata with:
+
+```bash
+pnpm lane:suggest --output .lumenflow.lane-inference.yaml
+```
+
 ### Modifying WU YAML Specs
 
 ```bash
@@ -384,7 +402,7 @@ git add . && git commit -m "your message"
 **Fix:** Regenerate the backlog or manually add the missing WU:
 
 ```bash
-# In worktree, edit docs/04-operations/tasks/backlog.md
+# In worktree, edit {{DOCS_TASKS_PATH}}/backlog.md
 # Add the missing WU reference in the appropriate section
 ```
 
@@ -490,6 +508,33 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 
 **IMPORTANT:** The `--client` flag identifies your IDE/tool environment, NOT the underlying AI model. Use `--client windsurf` even if Windsurf is running a Claude agent.
 
+### Guidance Profiles (WU-2309 / WU-2329)
+
+`wu:brief` verification guidance is profile-aware and ships with sensible built-in defaults.
+Project-local `.lumenflow/templates` is optional and only needed when you want different wording,
+extra project commands, or client-specific overrides.
+
+- New installs get the current defaults automatically.
+- Existing installs get the runtime defaults after `pnpm lumenflow:upgrade --latest`.
+- Run `pnpm docs:sync --force` when you also want refreshed scaffolded onboarding docs and
+  supported vendor assets.
+
+Default profiles:
+
+- Behavior/logic changes: follow project policy (`methodology.testing`: `tdd`, `test-after`, or `none`).
+- Structured-content-only changes (`.yaml/.yml/.json/.md/.mdx`): use parse/schema/lint/eval evidence; TDD checkpoint is omitted.
+- UI presentation hints: prefer smoke/manual/integration/E2E verification and use unit tests for pure logic or explicitly required checks.
+
+Common override points include `visual-directive`, `structured-content-directive`,
+`verification-requirements`, and `design-context-ui`.
+
+Domain-specific commands must come from local configuration, not core framework code:
+
+- Template manifest: `.lumenflow/templates/manifest.yaml`
+- Base templates: `.lumenflow/templates/spawn-prompt/*.md`
+- Client overrides: `.lumenflow/templates.{client}/spawn-prompt/*.md`
+- Client config: `workspace.yaml` under `software_delivery.agents.clients.*`
+
 ### Sub-Agent Coordination
 
 - Sub-agents work in isolated micro-worktrees
@@ -501,23 +546,22 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 
 ## WU Lifecycle Commands
 
-| Command                                        | Description                              | When to Use                 |
-| ---------------------------------------------- | ---------------------------------------- | --------------------------- |
-| `pnpm wu:status --id WU-XXX`                   | Show WU state and valid commands         | Check current state         |
-| `pnpm wu:claim --id WU-XXX --lane "Lane"`      | Claim WU and create worktree (default)   | Start working (local)       |
-| `pnpm wu:claim --id WU-XXX --lane "L" --cloud` | Claim WU in branch-pr mode (no worktree) | Start working (cloud)       |
-| `pnpm wu:edit --id WU-XXX --field value`       | Edit WU spec fields                      | Update notes/desc           |
-| `pnpm wu:brief --id WU-XXX --client X`         | Generate handoff prompt + evidence       | Complex WUs                 |
-| `pnpm wu:brief --id WU-XXX --evidence-only`    | Record evidence only (no prompt output)  | Self-implementation path    |
-| `pnpm wu:delegate --id WU-XXX --parent-wu P`   | Generate prompt + record delegation      | Auditable delegation flows  |
-| `pnpm gates`                                   | Run quality gates                        | Before wu:done              |
-| `pnpm gates --docs-only`                       | Run docs-only gates                      | For documentation WUs       |
-| `pnpm wu:done --id WU-XXX`                     | Complete WU (merge or PR, cleanup)       | After gates pass            |
-| `pnpm wu:cleanup --id WU-XXX`                  | Post-merge cleanup (branch-pr)           | After PR merge (cloud only) |
-| `pnpm wu:escalate --id WU-XXX`                 | Show or resolve escalation status        | Escalation-triggered WUs    |
-| `pnpm wu:escalate --resolve --id WU-XXX`       | Resolve human escalation                 | Before wu:done (escalation) |
-| `pnpm wu:delete --id WU-XXX`                   | Delete WU spec and cleanup               | Cancel stale/throwaway WUs  |
-| `pnpm wu:recover --id WU-XXX`                  | Fix inconsistent WU state                | When state is broken        |
+| Command                                        | Description                                     | When to Use                 |
+| ---------------------------------------------- | ----------------------------------------------- | --------------------------- |
+| `pnpm wu:status --id WU-XXX`                   | Show WU state and valid commands                | Check current state         |
+| `pnpm wu:claim --id WU-XXX --lane "Lane"`      | Claim WU and create worktree (default)          | Start working (local)       |
+| `pnpm wu:claim --id WU-XXX --lane "L" --cloud` | Claim WU in branch-pr mode (no worktree)        | Start working (cloud)       |
+| `pnpm wu:edit --id WU-XXX --field value`       | Edit WU spec fields                             | Update notes/desc           |
+| `pnpm wu:brief --id WU-XXX --client X`         | Generate handoff prompt + evidence              | Complex WUs                 |
+| `pnpm wu:brief --id WU-XXX --evidence-only`    | Record evidence only (no prompt output)         | Self-implementation path    |
+| `pnpm wu:delegate --id WU-XXX --parent-wu P`   | Generate prompt + record delegation             | Auditable delegation flows  |
+| `pnpm wu:prep --id WU-XXX`                     | Run gates in claimed workspace, prep completion | Before wu:done              |
+| `pnpm wu:done --id WU-XXX`                     | Complete WU (merge or PR, cleanup)              | After gates pass            |
+| `pnpm wu:cleanup --id WU-XXX`                  | Post-merge cleanup (branch-pr)                  | After PR merge (cloud only) |
+| `pnpm wu:escalate --id WU-XXX`                 | Show or resolve escalation status               | Escalation-triggered WUs    |
+| `pnpm wu:escalate --resolve --id WU-XXX`       | Resolve human escalation                        | Before wu:done (escalation) |
+| `pnpm wu:delete --id WU-XXX`                   | Delete WU spec and cleanup                      | Cancel stale/throwaway WUs  |
+| `pnpm wu:recover --id WU-XXX`                  | Fix inconsistent WU state                       | When state is broken        |
 
 ---
 
@@ -525,7 +569,7 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 
 ```
 /path/to/repo/
-├── docs/04-operations/tasks/
+├── {{DOCS_TASKS_PATH}}/
 │   ├── backlog.md              # All WUs listed here (auto-generated, don't edit)
 │   └── wu/WU-XXXX.yaml         # Individual WU specs
 ├── worktrees/
@@ -544,7 +588,7 @@ pnpm wu:delegate --id WU-XXXX --parent-wu WU-YYYY --client <client-type>
 Before reporting a WU complete, verify:
 
 - [ ] All acceptance criteria in WU YAML are satisfied
-- [ ] Gates pass (`pnpm gates` or `pnpm gates --docs-only`)
+- [ ] `pnpm wu:prep --id WU-XXX` ran successfully in the claimed workspace
 - [ ] `pnpm wu:done --id WU-XXX` ran successfully
 - [ ] Output shows "Marked done, pushed, and cleaned up"
 - [ ] Worktree was removed (check `ls worktrees/`)
@@ -685,4 +729,5 @@ rm -rf /tmp/nextjs-scaffold
 - [troubleshooting-wu-done.md](troubleshooting-wu-done.md) - Why agents forget wu:done
 - [first-wu-mistakes.md](first-wu-mistakes.md) - Common mistakes to avoid
 - [quick-ref-commands.md](quick-ref-commands.md) - Command reference
+- [wu-sizing-guide.md](wu-sizing-guide.md) - Context safety and WU sizing
 - [initiative-orchestration.md](initiative-orchestration.md) - Initiative orchestration, delegation, recovery