@lumenflow/cli 3.8.6 → 3.9.0

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

@@ -18,6 +18,10 @@ Reference for CLI commands. Organized by category for quick discovery.
 > pnpm wu:delete --help    # See wu:delete options
 > pnpm wu:escalate --help  # See wu:escalate options
 > ```
+>
+> **Never conclude a command doesn't exist without running `pnpm lumenflow:commands` first.**
+>
+> Maintainer reference for validation ownership: [validator-boundaries.md](../../validator-boundaries.md).
 
 ## Help-First Usage Examples By Category
 
@@ -26,6 +30,7 @@ Run `--help` first, then run the real command with explicit flags.
 | Category            | Help-First Example                    | Real Command Example                                                     |
 | ------------------- | ------------------------------------- | ------------------------------------------------------------------------ |
 | Setup & Development | `pnpm bootstrap --help`               | `pnpm bootstrap`                                                         |
+| Tooling Operations  | `pnpm lumenflow:upgrade --help`       | `pnpm lumenflow:upgrade --latest`                                        |
 | WU Lifecycle        | `pnpm wu:claim --help`                | `pnpm wu:claim --id WU-1561 --lane "Operations: Tooling"`                |
 | WU Maintenance      | `pnpm wu:recover --help`              | `pnpm wu:recover --id WU-1561`                                           |
 | Gates & Quality     | `pnpm gates --help`                   | `pnpm gates --docs-only`                                                 |
@@ -39,7 +44,8 @@ Run `--help` first, then run the real command with explicit flags.
 | Documentation       | `pnpm docs:validate --help`           | `pnpm docs:validate`                                                     |
 | Release             | `pnpm pre-release:check --help`       | `pnpm pre-release:check`                                                 |
 | Configuration       | `pnpm config:set --help`              | `pnpm config:set --key methodology.testing --value test-after`           |
-| Agent Utilities     | `pnpm agent:issues-query --help`      | `pnpm agent:issues-query`                                                |
+| Agent Utilities     | `pnpm agent:session --help`           | `pnpm agent:session`                                                     |
+| Packs               | `pnpm pack:install --help`            | `pnpm pack:install --name software-delivery`                             |
 
 ---
 
@@ -62,6 +68,7 @@ Run `--help` first, then run the real command with explicit flags.
 | `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):**
@@ -81,26 +88,53 @@ pnpm exec lumenflow --client all      # All clients
 
 ---
 
+## Tooling Operations (No WU Required)
+
+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                 |
+
+**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.
+
+> **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.
+
+---
+
 ## 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: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                    |
-| `pnpm wu:brief --id WU-XXX --evidence-only`     | Record wu:brief evidence only (self-implementation path)     |
-| `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 and record delegation lineage                |
-| `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)            |
+| 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 and record delegation lineage                         |
+| `pnpm wu:sandbox --id WU-XXX -- <cmd>`          | Run command through hardened WU sandbox backend                       |
 
 ### WU Maintenance
 
@@ -116,27 +150,29 @@ pnpm exec lumenflow --client all      # All clients
 | `pnpm wu:infer-lane --id WU-XXX` | Infer lane from code paths/description   |
 | `pnpm wu:delete --id WU-XXX`     | Delete WU spec and cleanup               |
 | `pnpm wu:unlock-lane --lane <L>` | Unlock stuck lane                        |
+| `pnpm wu:proto --lane <Lane>`    | Create WU prototype (lightweight draft)  |
 
 ---
 
 ## 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 |
+| 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) |
 
 ¹ **Script aliases:** `spec:linter` and `tasks:validate` are pnpm script aliases
 for `wu:validate --all`. They are not standalone CLI commands.
@@ -226,10 +262,7 @@ Supported mismatch fixes:
 
 ## Configuration
 
-| Command                                           | Description                                     |
-| ------------------------------------------------- | ----------------------------------------------- |
-| `pnpm config:get --key <dotpath>`                 | Read a value from `workspace.yaml`              |
-| `pnpm config:set --key <dotpath> --value <value>` | Set a value in `workspace.yaml` (Zod-validated) |
+See **Tooling Operations** section above for `config:set` and `config:get` commands.
 
 `config:set` validates against the Zod schema before writing and uses the micro-worktree
 pattern for atomic commits. Always use these commands instead of raw Write/Edit on
@@ -269,14 +302,14 @@ If the plan exists only in conversation, use `--plan` on `wu:create` to generate
 stub in `$LUMENFLOW_HOME/plans/` and automatically set the WU's `plan` field to the
 `lumenflow://plans/` URI. Feature WUs should have a `plan` field; notes do not replace the plan link.
 
-| Command                                                                  | Description                                                   |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------- |
+| Command                                                                  | Description                                                         |
+| ------------------------------------------------------------------------ | ------------------------------------------------------------------- |
 | `pnpm plan:create --id INIT-XXX --title "..."`                           | Create a repo-native plan file in configured `directories.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                               |
-| `pnpm initiative:plan --initiative INIT-XXX --plan <path>`               | Legacy-compatible initiative linking command                  |
-| `pnpm initiative:plan --initiative INIT-XXX --create`                    | Legacy-compatible create-and-link flow                        |
+| `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                                     |
+| `pnpm initiative:plan --initiative INIT-XXX --plan <path>`               | Legacy-compatible initiative linking command                        |
+| `pnpm initiative:plan --initiative INIT-XXX --create`                    | Legacy-compatible create-and-link flow                              |
 
 ### Linking Plans
 
@@ -355,15 +388,19 @@ pnpm initiative:edit --id INIT-025 --phase-id 1 --phase-status in_progress
 | `pnpm orchestrate:monitor`                   | Monitor delegation/agent activity |
 | `pnpm delegation:list`                       | List active delegation records    |
 
+For the complete orchestration workflow (delegation, memory coordination, failure recovery, checkpoint-per-wave mechanics), see [initiative-orchestration.md](initiative-orchestration.md).
+
 ---
 
 ## Metrics & Flow
 
-| Command                 | Description                  |
-| ----------------------- | ---------------------------- |
-| `pnpm flow:report`      | Generate flow metrics report |
-| `pnpm flow:bottlenecks` | Identify flow bottlenecks    |
-| `pnpm metrics:snapshot` | Capture metrics snapshot     |
+| Command                 | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `pnpm flow:report`      | Generate flow metrics report                           |
+| `pnpm flow:bottlenecks` | Identify flow bottlenecks                              |
+| `pnpm metrics:snapshot` | Capture metrics snapshot                               |
+| `pnpm metrics`          | View workflow metrics                                  |
+| `pnpm strict:progress`  | Report strict TypeScript backlog and guard regressions |
 
 ---
 
@@ -390,9 +427,45 @@ pnpm initiative:edit --id INIT-025 --phase-id 1 --phase-status in_progress
 
 ## Agent Utilities
 
-| Command                   | Description                        |
-| ------------------------- | ---------------------------------- |
-| `pnpm agent:issues-query` | Query GitHub issues for agent work |
+| Command                   | Description                                  |
+| ------------------------- | -------------------------------------------- |
+| `pnpm agent:session`      | Start agent session (registers active agent) |
+| `pnpm agent:session-end`  | End agent session                            |
+| `pnpm agent:log-issue`    | Log issue during agent session               |
+| `pnpm agent:issues-query` | Query GitHub issues for agent work           |
+| `pnpm task:claim`         | Claim a task directly through KernelRuntime  |
+
+---
+
+## Packs
+
+| Command                            | Description                          |
+| ---------------------------------- | ------------------------------------ |
+| `pnpm pack:author`                 | Author a secure domain pack          |
+| `pnpm pack:scaffold --name <name>` | Scaffold a new domain pack           |
+| `pnpm pack:validate --path <path>` | Validate a domain pack for integrity |
+| `pnpm pack:hash --path <path>`     | Compute integrity hash for a pack    |
+| `pnpm pack:publish --path <path>`  | Publish a domain pack to registry    |
+| `pnpm pack:install --name <name>`  | Install a domain pack into workspace |
+| `pnpm pack:search --query <query>` | Search for packs in registry         |
+
+---
+
+## Audited File & Git Wrappers
+
+These commands wrap standard file/git operations with audit trail logging.
+Use them when audit evidence is required (e.g., during WU execution).
+
+| Command                          | Description                      |
+| -------------------------------- | -------------------------------- |
+| `pnpm file:read --path <path>`   | Read file with audit trail       |
+| `pnpm file:write --path <path>`  | Write file with audit trail      |
+| `pnpm file:edit --path <path>`   | Edit file with audit trail       |
+| `pnpm file:delete --path <path>` | Delete file with audit trail     |
+| `pnpm git:status`                | Show git status with audit trail |
+| `pnpm git:diff`                  | Show git diff with audit trail   |
+| `pnpm git:log`                   | Show git log with audit trail    |
+| `pnpm git:branch`                | Show git branch with audit trail |
 
 ---
 
@@ -713,8 +786,8 @@ Hooks provide automatic enforcement at the tool level:
 
 For a complete picture of how all WU commands, memory tools, and orchestration tools fit together, and for remediation of common failure modes, see:
 
-- **[Canonical Lifecycle Map](../../lumenflow-complete.md#26-canonical-lifecycle-map-wu-1635)** -- Command-mode matrix (worktree vs cloud/branch-PR), expected locations, and handoff points
-- **[Failure-Mode Runbook](../../lumenflow-complete.md#appendix-a-failure-mode-runbook-wu-1635)** -- Concrete remediation for main-behind-origin, partial-claim state, spawn-provenance enforcement, and wu:recover usage
+- **[Canonical Lifecycle Map](../../lumenflow-agent-capsule.md)** -- Command-mode matrix (worktree vs cloud/branch-PR), expected locations, and handoff points
+- **[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

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

@@ -2,7 +2,7 @@
 
 **Last updated:** {{DATE}}
 
-This document covers the complete release process for LumenFlow, including versioning, npm publishing, documentation updates, and the GitHub App.
+This document covers the complete release process for LumenFlow, including versioning, npm publishing, and documentation updates.
 
 ---
 
@@ -10,11 +10,11 @@ This document covers the complete release process for LumenFlow, including versi
 
 LumenFlow has several components that need to stay in sync:
 
-| Component      | Location                | Deployment                          |
-| -------------- | ----------------------- | ----------------------------------- |
-| npm packages   | `packages/@lumenflow/*` | Auto via GitHub Actions on tag push |
-| Starlight docs | `apps/docs/`            | Manual via Vercel CLI               |
-| GitHub App     | `apps/github-app/`      | Auto via Vercel Git integration     |
+| Component      | Location                    | Deployment                          |
+| -------------- | --------------------------- | ----------------------------------- |
+| npm packages   | `packages/@lumenflow/*`     | Auto via GitHub Actions on tag push |
+| Starlight docs | `apps/docs/`                | Manual via Vercel CLI               |
+| Pack registry  | `apps/web/` + pack tarballs | Manual deploy + curl publish        |
 
 ---
 
@@ -251,39 +251,108 @@ vercel --prod
 ### Important Notes
 
 - **No private repo links**: Starlight docs are public; never link to `github.com/hellmai/lumenflow-dev`
-- **Link to GitHub App**: Use <https://github.com/apps/lumenflow-by-hellmai> for GitHub links
 - **Link to npm**: Use <https://www.npmjs.com/org/lumenflow> for package links
 
 ---
 
-## GitHub App
+## Pack Registry Publishing
 
-The LumenFlow GitHub App provides workflow enforcement for teams.
+Packs are published to the registry at <https://registry.lumenflow.dev>. The registry is served by the `apps/web` Next.js app deployed to Vercel.
 
-### Components
+### Prerequisites
 
-- **App manifest**: `apps/github-app/app.yml`
-- **Webhook handler**: `apps/github-app/api/webhook.ts`
-- **Validation endpoints**: `apps/github-app/api/validate-token.ts`
+1. **Deploy `apps/web` to Vercel** before publishing. The registry API runs on the deployed app, so any code fixes (e.g. blob storage changes) must be live first.
+2. **Build the pack tarball** with `pnpm pack` from the pack directory.
+3. **Authenticate** with a GitHub token (`gh auth token`).
 
-### Deployment
+### Step 1: Deploy the Registry
+
+The `apps/web` Vercel project has `Root Directory: apps/web` configured. To deploy from the CLI, link the repo root to the `web` project:
+
+```bash
+# From repo root — link to the 'web' project (not 'lumenflow-dev')
+vercel link --project web --scope hellm-ai --yes
+
+# Deploy to production
+vercel --prod --yes
+```
+
+**Gotcha:** Do NOT run `vercel` from inside `apps/web/` — the Vercel root directory setting doubles the path (`apps/web/apps/web`). Always deploy from the repo root.
+
+**Gotcha:** The repo root `.vercel/project.json` may be linked to `lumenflow-dev` (the monorepo project). You must re-link to `web` before deploying the registry.
+
+After deploying, restore the link if needed:
+
+```bash
+vercel link --project lumenflow-dev --scope hellm-ai --yes
+```
+
+### Step 2: Build the Tarball
+
+```bash
+cd packages/@lumenflow/packs/software-delivery  # or sidekick, etc.
+pnpm pack
+# Creates: lumenflow-packs-software-delivery-X.Y.Z.tgz
+```
+
+### Step 3: Publish to Registry
+
+```bash
+curl -s -X POST \
+  -H "Authorization: Bearer $(gh auth token)" \
+  -H "Origin: https://registry.lumenflow.dev" \
+  -F "tarball=@packages/@lumenflow/packs/software-delivery/lumenflow-packs-software-delivery-X.Y.Z.tgz" \
+  -F "description=Software delivery pack for LumenFlow" \
+  -F "version=X.Y.Z" \
+  "https://registry.lumenflow.dev/api/registry/packs/software-delivery/versions"
+```
+
+Replace `software-delivery` with the pack ID and `X.Y.Z` with the version.
+
+**Important:** The `Origin` header must match `https://registry.lumenflow.dev` — CSRF validation will reject requests without it.
+
+### Step 4: Verify
+
+```bash
+# List all packs
+curl -s https://registry.lumenflow.dev/api/registry/packs
+
+# Check a specific pack
+curl -s https://registry.lumenflow.dev/api/registry/packs/software-delivery
+```
 
-The GitHub App is deployed **automatically** via Vercel Git integration when changes are pushed to `main`.
+### Step 5: Cleanup
 
-- **Project**: `lumenflow-app` (ID: `prj_JKfcHVb4QjzAxdjCIJwaUf5PWusG`)
-- **URL**: <https://lumenflow-app.vercel.app>
+```bash
+rm packages/@lumenflow/packs/software-delivery/lumenflow-packs-software-delivery-X.Y.Z.tgz
+```
 
-### Package Configuration
+### Vercel Projects Reference
 
-The `apps/github-app/package.json` must have `"private": true` to prevent npm publish attempts.
+| Project           | Domain                   | Purpose                 |
+| ----------------- | ------------------------ | ----------------------- |
+| `web`             | registry.lumenflow.dev   | Pack registry + web app |
+| `docs`            | lumenflow.dev            | Starlight documentation |
+| `lumenflow-dev`   | lumenflow-dev.vercel.app | Monorepo preview        |
+| `lumenflow-cloud` | cloud.lumenflow.dev      | Control plane           |
 
-### Environment Variables (Vercel)
+### Troubleshooting Pack Publishing
 
-| Variable                | Description                  |
-| ----------------------- | ---------------------------- |
-| `GITHUB_APP_ID`         | GitHub App ID                |
-| `GITHUB_PRIVATE_KEY`    | PEM private key for app auth |
-| `GITHUB_WEBHOOK_SECRET` | Webhook signature secret     |
+#### "Pack not found" after publish returns success
+
+The deploy running at publish time was using old code. Deploy first, then publish.
+
+#### Version conflict (409)
+
+The version already exists. Pack versions are immutable — bump the version number.
+
+#### CSRF error (403)
+
+Missing or wrong `Origin` header. Must be `https://registry.lumenflow.dev`.
+
+#### Vercel build fails with d2 error
+
+The `@lumenflow/docs` package requires `d2` (diagramming tool) which is not available on Vercel. Ensure you are deploying the `web` project (which uses `turbo build --filter=@lumenflow/web`) not the `lumenflow-dev` project (which builds all packages).
 
 ---
 
@@ -353,19 +422,19 @@ If you need more control:
 
 - [ ] Verify npm packages accessible: `npm view @lumenflow/cli`
 - [ ] Verify docs updated: <https://lumenflow.dev>
-- [ ] Verify GitHub App functional (if changed)
+- [ ] Verify packs published: `curl -s https://registry.lumenflow.dev/api/registry/packs`
 
 ---
 
 ## Keeping Components in Sync
 
-| Change Type      | npm           | Docs   | GitHub App   |
-| ---------------- | ------------- | ------ | ------------ |
-| Bug fix in CLI   | Tag + publish | Auto\* | No           |
-| New CLI command  | Tag + publish | Auto\* | No           |
-| Docs-only update | No            | Deploy | No           |
-| GitHub App fix   | No            | No     | Auto on push |
-| Full release     | Tag + publish | Deploy | Auto         |
+| 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            | Deploy | No      |
+| Full release     | Tag + publish | Deploy | Publish |
 
 \* CLI/config reference docs regenerate automatically during `wu:done` when trigger files change. See [Automatic Docs Generation](./docs-generation.md).
 
@@ -385,12 +454,6 @@ If you need more control:
 2. Check Vercel CLI auth: `vercel whoami`
 3. Check project link: `vercel link`
 
-### GitHub App webhook failures
-
-1. Check Vercel deployment logs
-2. Verify environment variables set
-3. Check webhook secret matches GitHub App settings
-
 ---
 
 ## Known Warnings

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

@@ -685,3 +685,4 @@ 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
+- [initiative-orchestration.md](initiative-orchestration.md) - Initiative orchestration, delegation, recovery

package/templates/core/ai/onboarding/test-ratchet.md.template

@@ -69,13 +69,7 @@ cat .lumenflow/test-baseline.json | grep -i "<test_name>"
 
 **Option B: Add to baseline** (for infrastructure issues only)
 
-```bash
-pnpm baseline:add \
-  --test "should handle edge case" \
-  --file "path/to/test.ts" \
-  --reason "CI flakiness - infrastructure issue" \
-  --fix-wu WU-XXXX
-```
+To add a test to the baseline, edit `.lumenflow/test-baseline.json` and document the reason in your WU notes.
 
 ---
 
@@ -127,5 +121,5 @@ When encountering test failures:
 ## Related Documentation
 
 - [constraints.md](../../../../../../.lumenflow/constraints.md) - Constraint #7: Test Ratchet
-- [lumenflow-complete.md](../../lumenflow-complete.md) - Definition of Done
+- [LumenFlow Agent Capsule](../../lumenflow-agent-capsule.md) - Definition of Done
 - [troubleshooting-wu-done.md](./troubleshooting-wu-done.md) - wu:done issues

package/templates/vendors/claude/.claude/CLAUDE.md.template

@@ -48,7 +48,7 @@ Essential commands for multi-agent coordination and context management:
 | `pnpm mem:inbox --since 30m`               | Check coordination signals        |
 | `pnpm mem:signal "msg" --wu WU-XXX`        | Broadcast signal to other agents  |
 | `pnpm mem:create "msg" --wu WU-XXX`        | Create memory node (bug capture)  |
-| `pnpm wu:spawn --id WU-XXX --client claude-code` | Spawn sub-agent prompt     |
+| `pnpm wu:brief --id WU-XXX --client claude-code` | Generate handoff prompt + record evidence |
 
 **When to checkpoint:**
 - After each acceptance criterion completed

package/templates/vendors/claude/.claude/skills/bug-classification/SKILL.md.template

@@ -2,7 +2,7 @@
 name: bug-classification
 description: Classify bugs (P0-P3) and determine fix-in-place vs separate Bug WU. Use when bug discovered mid-WU, deciding bug priority, or handling production issues.
 version: 1.0.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
 source_sections: §8 (Bug Handling Mid-WU)
 last_updated: {{DATE}}
 allowed-tools: Read, Grep
@@ -189,4 +189,4 @@ blocking: []
 
 ## Reference
 
-See [lumenflow-complete.md §8](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md) for complete bug handling guide.
+See [LumenFlow Agent Capsule](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md) for complete bug handling guide.

package/templates/vendors/claude/.claude/skills/code-quality/SKILL.md.template

@@ -2,15 +2,15 @@
 name: code-quality
 description: Shared patterns for SOLID/DRY code review, hexagonal architecture compliance, TypeScript best practices, and performance anti-patterns. Use when reviewing code quality, checking architecture boundaries, or validating TypeScript patterns.
 version: 1.1.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
-source_sections: §2 (Core Principles), §4 (Hexagonal Architecture)
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source_sections: Core Principles, Hexagonal Architecture
 last_updated: {{DATE}}
 allowed-tools: Read, Grep, Glob
 ---
 
 # Code Quality Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §2, §4 (canonical)
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
 
 ## When to Use
 

package/templates/vendors/claude/.claude/skills/context-management/SKILL.md.template

@@ -165,7 +165,7 @@ Always load context in this order for best comprehension:
 
 1. `LUMENFLOW.md` — Workflow fundamentals
 2. `README.md` — Project structure
-3. `lumenflow-complete.md` §§1-7 — Constraints
+3. `lumenflow-agent-capsule.md` — Constraints
 4. WU YAML — Current task spec
 5. Task instructions — What to do
 6. Constraints block — Critical rules (at END per "Lost in Middle" research)

package/templates/vendors/claude/.claude/skills/frontend-design/SKILL.md.template

@@ -2,7 +2,7 @@
 name: frontend-design
 description: Create distinctive, production-grade frontend interfaces. Use when building React components, pages, UI features, or when user requests visual/design work.
 version: 1.0.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
 last_updated: {{DATE}}
 allowed-tools: Read, Write, Edit, Bash
 ---

package/templates/vendors/claude/.claude/skills/lumenflow-gates/SKILL.md.template

@@ -2,15 +2,15 @@
 name: lumenflow-gates
 description: Quality gates troubleshooting (format, lint, typecheck, tests). Use when gates fail, debugging format/lint/typecheck errors, or determining if failure is from your changes vs pre-existing.
 version: 2.1.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
-source_sections: §6.4 (Validation & Gates)
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source_sections: Validation & Gates
 last_updated: {{DATE}}
 allowed-tools: Read, Bash, Grep
 ---
 
 # LumenFlow Gates Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §6.4 (canonical)
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
 
 ## When to Use
 
@@ -84,4 +84,4 @@ pnpm tasks:validate       # WU YAML validation
 
 ---
 
-**Full spec**: [lumenflow-complete.md §6.4](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md)
+**Full spec**: [LumenFlow Agent Capsule](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md)

package/templates/vendors/claude/.claude/skills/tdd-workflow/SKILL.md.template

@@ -2,15 +2,15 @@
 name: tdd-workflow
 description: Test-driven development workflow. RED-GREEN-REFACTOR applies to all code; 5-step ports-first for hex architecture. Use when implementing new features, writing tests, or working with hexagonal architecture.
 version: 2.1.0
-source: docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md
-source_sections: §5 (AI-TDD 5-Step Workflow), §4 (Hexagonal Architecture)
+source: docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md
+source_sections: AI-TDD 5-Step Workflow, Hexagonal Architecture
 last_updated: {{DATE}}
 allowed-tools: Read, Write, Edit, Bash, Grep
 ---
 
 # TDD Workflow Skill
 
-**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md` §5 (canonical)
+**Source**: `docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md` (canonical)
 
 ## When to Use
 
@@ -138,4 +138,4 @@ pnpm test:coverage           # Check coverage
 
 ---
 
-**Full spec**: [lumenflow-complete.md §5](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-complete.md)
+**Full spec**: [LumenFlow Agent Capsule](../../../docs/04-operations/_frameworks/lumenflow/lumenflow-agent-capsule.md)