@lumenflow/cli 4.11.0 → 4.12.1

package/dist/wu-rename.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-rename.js","sourceRoot":"","sources":["../src/wu-rename.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "4.11.0",
+  "version": "4.12.1",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -147,6 +147,7 @@
     "wu-prune": "./dist/wu-prune.js",
     "wu-recover": "./dist/wu-recover.js",
     "wu-release": "./dist/wu-release.js",
+    "wu-rename": "./dist/wu-rename.js",
     "wu-repair": "./dist/wu-repair.js",
     "wu-sandbox": "./dist/wu-sandbox.js",
     "wu-status": "./dist/wu-status.js",
@@ -187,13 +188,13 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/agent": "4.11.0",
-    "@lumenflow/control-plane-sdk": "4.11.0",
-    "@lumenflow/core": "4.11.0",
-    "@lumenflow/initiatives": "4.11.0",
-    "@lumenflow/memory": "4.11.0",
-    "@lumenflow/metrics": "4.11.0",
-    "@lumenflow/kernel": "4.11.0"
+    "@lumenflow/agent": "4.12.1",
+    "@lumenflow/core": "4.12.1",
+    "@lumenflow/initiatives": "4.12.1",
+    "@lumenflow/kernel": "4.12.1",
+    "@lumenflow/memory": "4.12.1",
+    "@lumenflow/metrics": "4.12.1",
+    "@lumenflow/control-plane-sdk": "4.12.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

package/packs/agent-runtime/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-agent-runtime@4.11.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
+> @lumenflow/packs-agent-runtime@4.12.1 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/agent-runtime
 > tsc
 

package/packs/agent-runtime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-agent-runtime",
-  "version": "4.11.0",
+  "version": "4.12.1",
   "description": "Agent runtime pack scaffold for LumenFlow — governed model-turn execution, pack config, and provider capability baselines",
   "keywords": [
     "lumenflow",

package/packs/sidekick/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-sidekick@4.11.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
+> @lumenflow/packs-sidekick@4.12.1 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
 > tsc
 

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "4.11.0",
+  "version": "4.12.1",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",

package/packs/software-delivery/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-software-delivery@4.11.0 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
+> @lumenflow/packs-software-delivery@4.12.1 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/software-delivery
 > tsc
 

package/packs/software-delivery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-software-delivery",
-  "version": "4.11.0",
+  "version": "4.12.1",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/templates/core/.lumenflow/constraints.md.template

@@ -59,6 +59,8 @@ If you see something broken on main (failing gates, format issues, typos, lint e
 
 **If you're on main and want to change something: STOP. Create a WU first.**
 
+**If main is already dirty from an unexpected command side effect:** Use `git restore` and `git clean -n` (dry run) to recover — never hand-edit files to "undo" a generator. See [.lumenflow/rules/git-safety.md](rules/git-safety.md) section "Main Went Dirty Unexpectedly" for the full recovery procedure.
+
 ---
 
 ### 2. WUs Are Specs, Not Code

package/templates/core/AGENTS.md.template

@@ -111,6 +111,7 @@ For detailed troubleshooting, see [troubleshooting-wu-done.md]({{DOCS_ONBOARDING
 3. **Gates Before Done**: Run `pnpm gates` before `wu:done`
 4. **Never Bypass Hooks**: No `--no-verify`
 5. **Vendor-Agnostic Dirty-Main Guard**: `wu:prep` and `wu:done` hard-block when main has non-allowlisted dirty files during worktree WUs (including MCP/tool-originated writes). `branch-pr` mode is exempt.
+6. **Docs Parity For Behavior Changes**: If you change LumenFlow behavior or workflow guidance, update internal docs, Starlight docs, or both as appropriate. Generated reference docs do not cover narrative behavior changes by themselves.
 
 For the complete set of non-negotiable constraints (git safety, forbidden commands, skip-gates policy, and more), see [.lumenflow/constraints.md](.lumenflow/constraints.md).
 
@@ -172,6 +173,19 @@ This file provides universal guidance for all AI agents. Additional vendor-speci
   - `apps/docs/src/data/language-support.yaml`
   - `apps/docs/src/data/example-repos.yaml`
 
+## Documentation Obligations
+
+When LumenFlow behavior changes, decide documentation impact explicitly instead of assuming
+`docs:generate` is sufficient.
+
+- Update **internal docs** when the change affects agent workflow, maintainer workflow, onboarding,
+  or repo-specific operating rules.
+- Update **Starlight docs** when the change affects public CLI behavior, pack behavior, language
+  guidance, or user-facing workflow expectations.
+- Update **both** when the same behavior change affects agents internally and users externally.
+- State the outcome in your completion notes or report: `Internal docs`, `Starlight docs`, `Both`,
+  or `None`.
+
 ---
 
 ## Further Reading

package/templates/core/LUMENFLOW.md.template

@@ -200,6 +200,22 @@ For cloud agents (Codex/Claude web/CI) operating on feature branches:
 - **apps/docs/src/data/language-support.yaml** - Language guide support metadata
 - **apps/docs/src/data/example-repos.yaml** - Companion example-repo mapping
 
+### Documentation Obligations
+
+`pnpm docs:generate` only keeps generated reference pages in sync. It does **not** update narrative
+workflow guidance for you.
+
+When behavior changes:
+
+- Update **internal docs** (`AGENTS.md`, `LUMENFLOW.md`, onboarding docs) when the change affects
+  agent workflow, maintainer workflow, onboarding, or repo-specific operating rules.
+- Update **Starlight docs** (`apps/docs/src/content/docs/**`) when the change affects public CLI
+  behavior, pack behavior, language guides, or user-facing workflow expectations.
+- Update **both** when the same behavior change affects agents internally and users externally.
+
+Do not mark a behavior-change WU complete until you have explicitly decided: `Internal docs`,
+`Starlight docs`, `Both`, or `None`.
+
 ### Client/Vendor Overlays
 
 - **CLAUDE.md** - Claude Code overlay (single file at root)

package/templates/core/ai/onboarding/docs-generation.md.template

@@ -16,6 +16,29 @@ LumenFlow automatically generates CLI and configuration reference documentation
 | Config Reference | `packages/@lumenflow/core/src/lumenflow-config-schema.ts` | `apps/docs/src/content/docs/reference/config.mdx` |
 | MCP Reference    | `packages/@lumenflow/mcp/src/tools.ts`                    | `apps/docs/src/content/docs/reference/mcp.mdx`    |
 
+## What This Does Not Cover
+
+Generated reference docs are only one part of docs parity.
+
+`pnpm docs:generate` does **not** update narrative behavior docs such as:
+
+- `AGENTS.md`
+- `LUMENFLOW.md`
+- `{{DOCS_ONBOARDING_PATH}}/**`
+- `apps/docs/src/content/docs/packs/**`
+- `apps/docs/src/content/docs/kernel/**`
+- `apps/docs/src/content/docs/packs/software-delivery/languages/**`
+
+When behavior changes, make an explicit docs decision:
+
+- **Internal docs** when the change affects agent workflow, maintainer workflow, onboarding, or
+  repo-specific operating rules
+- **Starlight docs** when the change affects public CLI behavior, pack behavior, language guides,
+  or user-facing workflow expectations
+- **Both** when the same behavior change affects internal agents and external users
+
+If you changed behavior and only ran `pnpm docs:generate`, your docs work is probably incomplete.
+
 ## Example Tagging Conventions
 
 Docs example parity now distinguishes between copy-paste workflow examples and illustrative

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

@@ -208,7 +208,7 @@ pnpm gates
 # Output: format:check failed
 
 # Instinct: "I should help fix this!"
-{{format_fix_command}}
+pnpm prettier --write apps/docs/src/content/docs/concepts/lanes.mdx
 # Files modified on main - BAD!
 ```
 
@@ -226,7 +226,7 @@ pnpm gates
 pnpm wu:create --lane "Content: Documentation" --title "Fix format issues" ...
 pnpm wu:claim --id WU-XXX --lane "Content: Documentation"
 cd worktrees/content-documentation-wu-xxx
-{{format_fix_command}}  # Safe in worktree (preset-appropriate formatter)
+pnpm prettier --write <files>  # Safe in worktree
 ```
 
 **Why:** The "helpful fix" instinct is dangerous. Even small fixes (format, typos, lint) must go through a worktree. Commits are blocked by hooks, but files are still modified, requiring cleanup with `git checkout -- <files>`.

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

@@ -130,27 +130,42 @@ you want to refresh docs without upgrading packages (e.g., after manually editin
 
 ## 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 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 (ownership-guarded, v3.19.0)                                                              |
-| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                        |
-| `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                               |
-| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                       |
-| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379) |
-| `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` is scoped only when the active preset supports path-scoped execution) |
+| `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 (ownership-guarded, v3.19.0)                                                               |
+| `pnpm wu:unblock --id WU-XXX`                                  | Unblock WU (ownership-guarded, v3.19.0)                                                                         |
+| `pnpm wu:release --id WU-XXX --reason "..."`                   | Release orphaned WU (ownership-guarded, v3.19.0)                                                                |
+| `pnpm wu:status --id WU-XXX`                                   | Show WU status, location, valid commands                                                                        |
+| `pnpm wu:brief --id WU-XXX --client <client>`                  | **MANDATORY after wu:claim.** Generate handoff prompt + record evidence. wu:done blocks without this (WU-2379)  |
+| `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                                                                 |
+
+Common surgical `wu:edit` patterns:
+
+```bash
+# Rename one code_path entry without rewriting the full array
+pnpm wu:edit --id WU-123 \
+  --rename-code-paths "docs/08_concepts.md=docs/08_crosscutting_concepts.md"
+
+# Remove one stale code_path entry
+pnpm wu:edit --id WU-123 --remove-code-paths "docs/old-path.md"
+
+# Rename one scoped unit test path without replacing all test paths
+pnpm wu:edit --id WU-123 \
+  --rename-test-paths-unit "tests/old-name.test.ts=tests/new-name.test.ts"
+```
 
 ### WU Maintenance
 
@@ -210,11 +225,9 @@ only run when matching files change. Supports `error` (blocks), `warn` (logs), a
 severity levels. See workspace-spec.mdx for schema.
 
 **Formatting: always scope to changed files only.**
-Use `{{format_fix_command}}` — never unscoped `pnpm format`.
+Use `pnpm prettier --write <changed-files...>` — never unscoped `pnpm format`.
 Running `pnpm format` reformats every file in the repo, creating hundreds of
 dirty YAML/initiative changes that pollute the worktree and block `wu:done`.
-The command above is resolved at init time from your gate preset (WU-2547), so
-`.NET` repos get `dotnet format`, Python repos get `ruff format`, etc.
 
 ---
 
@@ -467,6 +480,22 @@ For the complete orchestration workflow (delegation, memory coordination, failur
 | `pnpm docs:generate` | Generate CLI documentation |
 | `pnpm docs:validate` | Validate CLI documentation |
 
+### Documentation Decision Rule
+
+For behavior changes, make an explicit docs decision instead of assuming generated reference docs
+cover everything:
+
+- **Internal docs**: agent workflow, maintainer workflow, onboarding, or repo-specific operating
+  rules changed.
+- **Starlight docs**: public CLI behavior, pack behavior, language guidance, or user-facing
+  workflow changed.
+- **Both**: the same behavior change affects agents internally and users externally.
+- **None**: no user-facing or agent-facing guidance changed.
+
+`pnpm docs:generate` only covers generated reference pages. Narrative workflow docs in
+`AGENTS.md`, `LUMENFLOW.md`, onboarding docs, and `apps/docs/src/content/docs/**` still need
+manual updates when behavior changes.
+
 ---
 
 ## Release

package/templates/core/ai/onboarding/release-process.md.template

@@ -240,34 +240,48 @@ The workflow:
 1. Installs D2 (`astro-d2` prerequisite)
 2. Builds docs with `pnpm --filter @lumenflow/docs build`
 3. Uploads `apps/docs/dist` as a workflow artifact
-4. Deploys to Vercel when `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` secrets are configured
+4. Deploys to Vercel when `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` Actions secrets are configured and valid
+5. Skips deploy cleanly when those secrets are absent, while still preserving the build artifact for inspection
 
 ### Deployment
 
-Production deploy is still manual via Vercel CLI:
+Production deploy normally happens through `.github/workflows/docs.yml` on a release tag push. When the workflow reaches the Vercel step successfully, it runs these commands against `apps/docs/`:
 
 ```bash
-cd apps/docs
-pnpm build
-vercel --prod
+pnpm dlx vercel pull --yes --environment=production --cwd apps/docs --token "$VERCEL_TOKEN"
+pnpm dlx vercel build --prod --cwd apps/docs --token "$VERCEL_TOKEN"
+pnpm dlx vercel deploy --prebuilt --prod --cwd apps/docs --token "$VERCEL_TOKEN"
+```
+
+Use a manual Vercel CLI deploy only as a recovery path when the GitHub Actions run needs to be replayed outside a tag push or `workflow_dispatch`. In that case, export the same values used by Actions:
+
+```bash
+export VERCEL_TOKEN=<token>
+export VERCEL_ORG_ID=<team-id>
+export VERCEL_PROJECT_ID=<project-id>
 ```
 
 ### When to Deploy
 
+- Release tags (`v*`) automatically trigger the docs workflow
+- Use `workflow_dispatch` when you need to rebuild or redeploy docs without cutting a new release tag
 - After any changes to `apps/docs/src/content/docs/**`
 - After version bumps (to update any version references)
 - After adding new features documented in Starlight
 
-### Vercel Project
+### Required Secrets
+
+- **`VERCEL_TOKEN`**: deploy token used by the workflow's Vercel CLI steps
+- **`VERCEL_ORG_ID`**: Vercel team/org that owns the production docs project
+- **`VERCEL_PROJECT_ID`**: Vercel project that serves `lumenflow.dev`
 
-- **Project**: `lumenflow-docs` (ID: `prj_myK4BzfHKctGhxfvALJaMOXVLx4g`)
-- **Domain**: lumenflow.dev
-- **Team**: lumenflow
+Treat those GitHub Actions secrets as the source of truth for automated docs deploys. Do not rely on the repo-root `.vercel/project.json` for docs releases; it may be linked to a different Vercel project such as the monorepo preview app.
 
 ### Important Notes
 
 - **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/lumenflow`
 - **Link to npm**: Use <https://www.npmjs.com/org/lumenflow> for package links
+- **Secret failures are explicit**: if `VERCEL_TOKEN` is invalid, the workflow will fail at `vercel pull`; rotating the Actions secret and rerunning `docs.yml` is the correct fix
 
 ---
 
@@ -394,7 +408,7 @@ pnpm release --release-version 1.3.0 --skip-publish --dry-run
 pnpm release --release-version 1.3.0 --skip-publish
 ```
 
-This handles version bump and tag locally; GitHub Actions handles npm publish, docs build, and GitHub release creation.
+This handles version bump and tag locally; GitHub Actions handles npm publish, GitHub release creation, and the docs build/deploy path when the Vercel secrets are configured correctly.
 
 ### Release Steps (Manual)
 
@@ -423,16 +437,21 @@ If you need more control:
    gh release view v1.3.0
    ```
 
-4. **Verify docs workflow** (if docs changed)
+4. **Verify docs workflow** (if docs changed or the release should refresh public docs)
 
    ```bash
    gh run list --workflow=docs.yml --limit 1
    ```
 
-5. **Deploy Starlight docs** (if content changed and you are deploying manually)
+5. **Manual Starlight recovery deploy** (only if you need to replay deploy outside the normal workflow)
 
    ```bash
-   cd apps/docs && pnpm build && vercel --prod
+   export VERCEL_TOKEN=<token>
+   export VERCEL_ORG_ID=<team-id>
+   export VERCEL_PROJECT_ID=<project-id>
+   pnpm dlx vercel pull --yes --environment=production --cwd apps/docs --token "$VERCEL_TOKEN"
+   pnpm dlx vercel build --prod --cwd apps/docs --token "$VERCEL_TOKEN"
+   pnpm dlx vercel deploy --prebuilt --prod --cwd apps/docs --token "$VERCEL_TOKEN"
    ```
 
 ### After Release
@@ -445,13 +464,13 @@ If you need more control:
 
 ## Keeping Components in Sync
 
-| Change Type      | npm           | Docs                    | Packs   |
-| ---------------- | ------------- | ----------------------- | ------- |
-| Bug fix in CLI   | Tag + publish | Auto\*                  | No      |
-| New CLI command  | Tag + publish | Auto\*                  | No      |
-| Pack changes     | Tag + publish | No                      | Publish |
-| Docs-only update | No            | Build workflow + deploy | No      |
-| Full release     | Tag + publish | Build workflow + deploy | Publish |
+| Change Type      | npm           | Docs                            | Packs   |
+| ---------------- | ------------- | ------------------------------- | ------- |
+| Bug fix in CLI   | Tag + publish | Auto\*                          | No      |
+| New CLI command  | Tag + publish | Auto\*                          | No      |
+| Pack changes     | Tag + publish | No                              | Publish |
+| Docs-only update | No            | `workflow_dispatch` + deploy    | No      |
+| Full release     | Tag + publish | Tag-triggered workflow + deploy | Publish |
 
 \* CLI/config reference docs regenerate automatically during `wu:done` when trigger files change. See [Automatic Docs Generation](./docs-generation.md).
 
@@ -467,9 +486,10 @@ If you need more control:
 
 ### Vercel deploy fails
 
-1. Check build locally: `cd apps/docs && pnpm build`
-2. Check Vercel CLI auth: `vercel whoami`
-3. Check project link: `vercel link`
+1. Check build locally: `pnpm --filter @lumenflow/docs build`
+2. Check the `VERCEL_TOKEN` GitHub Actions secret is valid; an invalid token fails at `vercel pull`
+3. Check `VERCEL_ORG_ID` and `VERCEL_PROJECT_ID` still target the production docs project for `lumenflow.dev`
+4. If you must replay deploy locally, export the same `VERCEL_*` values and run the same `vercel pull/build/deploy` sequence used in `docs.yml`
 
 ---
 

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

@@ -197,13 +197,14 @@ LUMENFLOW_CLOUD=1 pnpm wu:claim --id WU-XXXX --lane "Lane Name"
 These are the mistakes agents make most often. Memorize these before reading anything else:
 
 1. **wu:done deletes the worktree.** After it completes, your shell CWD is invalid. Immediately `cd` back to the project root.
-2. **When wu:done reports branch drift or a non-fast-forward error, rerun it from main.** It auto-rebases by default when it can. Never manually `git rebase` on main.
+2. **When wu:done reports branch drift, a non-fast-forward error, or patch-equivalent local-main catch-up, rerun it from main first.** It auto-rebases the lane branch when it can and now reconciles patch-equivalent local-main divergence after atomic push. Never manually `git rebase` on main.
 3. **Always run `--help` before first use of any command.** Don't guess flags — 30 seconds reading help saves 5 minutes of failed attempts.
 4. **Never `pnpm update @lumenflow/*` directly.** Use `pnpm lumenflow:upgrade --latest` (uses micro-worktree isolation).
 5. **State files are auto-generated.** Never manually edit `wu-events.jsonl`, `backlog.md`, or `status.md` — lifecycle commands manage them.
-6. **wu:edit requires a clean worktree.** Commit `wu-events.jsonl` and other changes before running `wu:edit`.
+6. **Structural `wu:edit` changes require a clean worktree.** Metadata-only edits such as `--notes`, `--acceptance`, and scoped test-path updates can run on a dirty worktree, but scope-changing edits like `--code-paths`, `--remove-code-paths`, `--rename-code-paths`, `--lane`, or `--plan` still require a clean state.
 7. **Don't edit on main then stash to a worktree.** If a hook blocks you on main, that means you need a WU. Create one and work in the worktree from the start.
 8. **Don't modify another agent's WU to free a lane.** `wu:block`, `wu:unblock`, `wu:release`, and `wu:recover` enforce ownership guards (v3.19.0). If you hit a `SESSION OWNERSHIP VIOLATION`, wait for the owning WU to complete or block itself — never use `--override-owner` without explicit human instruction.
+9. **Behavior changes need a docs decision.** Update internal docs, Starlight docs, or both when behavior changes. Generated reference docs alone do not cover narrative workflow changes.
 
 ---
 
@@ -289,7 +290,7 @@ When gates fail, read the error and fix it. Common failures and fixes:
 
 | Failure        | Cause                   | Fix                                    |
 | -------------- | ----------------------- | -------------------------------------- |
-| `format:check` | Formatter check failed  | `{{format_fix_command}}`               |
+| `format:check` | Prettier formatting     | `pnpm prettier --write <file>`         |
 | `backlog-sync` | WU missing from backlog | Regenerate backlog or add WU reference |
 | `typecheck`    | TypeScript errors       | Fix the type errors                    |
 | `lint`         | ESLint violations       | `pnpm lint --fix` or manual fix        |
@@ -461,18 +462,26 @@ Do not use `git stash`, switch local main, or otherwise mutate main just to prov
 
 ### Scenario 6: wu:done reports branch drift or a non-fast-forward error
 
-**Cause:** Another agent or process pushed to main between your fetch and push (race condition).
+**Cause:** Another agent or process pushed to main between your fetch and push (race condition), or
+your local `main` needs to catch up after the atomic push path.
 
-**Fix:** Rerun `wu:done` from main. It has built-in auto-rebase for this case. If the rerun still fails with a real conflict, resolve the conflict in the worktree, rerun `wu:prep` if needed, then return to main and rerun `wu:done`.
+**Fix:** Rerun `wu:done` from main first. It has built-in lane auto-rebase for branch drift and
+automatic local-main reconciliation for patch-equivalent divergence after a successful atomic push.
+If the rerun still fails with a real conflict, resolve the conflict in the worktree, rerun
+`wu:prep` if needed, then return to main and rerun `wu:done`.
 
 ```bash
 # WRONG - never manually rebase main
 git rebase origin/main  # DON'T DO THIS
 
-# RIGHT - just rerun the command
+# RIGHT - just rerun the command from main first
 pnpm wu:done --id WU-XXX
 ```
 
+If the rerun still reports a true local-main mismatch after a completed atomic push, treat that as
+an abnormal recovery case and use the surfaced recovery guidance or `pnpm wu:recover --id WU-XXX`
+instead of rebasing `main` manually.
+
 ---
 
 ## Delegating Sub-Agents with wu:brief / wu:delegate
@@ -597,6 +606,7 @@ Before reporting a WU complete, verify:
 - [ ] `pnpm wu:done --id WU-XXX` ran successfully
 - [ ] Output shows "Marked done, pushed, and cleaned up"
 - [ ] Worktree was removed (check `ls worktrees/`)
+- [ ] Required docs updates were made, or you can explicitly justify `Internal docs`, `Starlight docs`, `Both`, or `None`
 
 ---
 

package/templates/core/ai/onboarding/troubleshooting-wu-done.md.template

@@ -66,7 +66,8 @@ cd /path/to/main && pnpm wu:done --id WU-XXX
 ```
 
 If `wu:done` reports branch drift, parallel completions, or a non-fast-forward push, rerun it from
-main. It auto-rebases by default when possible. Do not manually rebase `main`.
+main. It auto-rebases the lane branch when possible and also catches up patch-equivalent local-main
+divergence after atomic push. Do not manually rebase `main`.
 
 ---
 
@@ -131,7 +132,7 @@ Feature WUs **must** include `spec_refs` (use `pnpm wu:create --plan` if the pla
 ### "non-fast-forward" or "branch is behind main"
 
 If `wu:done` reports branch drift or a non-fast-forward push, another completion landed while your
-WU was in progress.
+WU was in progress or your local `main` needs to catch up after the atomic push path.
 
 ```bash
 # Retry from main first
@@ -142,6 +143,9 @@ pnpm wu:done --id WU-XXX
 - If the rerun succeeds, you are done.
 - If the rerun reports an auto-rebase conflict, return to the worktree, resolve the conflict there,
   rerun `pnpm wu:prep --id WU-XXX` if needed, then retry `wu:done` from main.
+- If the rerun still reports a true local-main mismatch after a completed atomic push, stop and use
+  the surfaced recovery guidance or `pnpm wu:recover --id WU-XXX` rather than manually rebasing
+  `main`.
 - Do **not** manually `git rebase` the main checkout.
 
 ---