@lumenflow/cli 3.9.2 → 3.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/cli",
-  "version": "3.9.2",
+  "version": "3.9.6",
   "description": "Command-line interface for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -180,13 +180,13 @@
     "xstate": "^5.28.0",
     "yaml": "^2.8.2",
     "zod": "^4.3.6",
-    "@lumenflow/agent": "3.9.2",
-    "@lumenflow/control-plane-sdk": "3.9.2",
-    "@lumenflow/kernel": "3.9.2",
-    "@lumenflow/initiatives": "3.9.2",
-    "@lumenflow/memory": "3.9.2",
-    "@lumenflow/core": "3.9.2",
-    "@lumenflow/metrics": "3.9.2"
+    "@lumenflow/agent": "3.9.6",
+    "@lumenflow/core": "3.9.6",
+    "@lumenflow/control-plane-sdk": "3.9.6",
+    "@lumenflow/initiatives": "3.9.6",
+    "@lumenflow/memory": "3.9.6",
+    "@lumenflow/kernel": "3.9.6",
+    "@lumenflow/metrics": "3.9.6"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.18",

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

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-sidekick@3.9.1 build /home/tom/source/hellmai/lumenflow-dev/packages/@lumenflow/packs/sidekick
+> @lumenflow/packs-sidekick@3.9.6 build /home/runner/work/lumenflow-dev/lumenflow-dev/packages/@lumenflow/packs/sidekick
 > tsc
 

package/packs/sidekick/manifest.ts

@@ -182,9 +182,11 @@ const TOOL_INPUT_SCHEMAS: Record<SidekickToolName, Record<string, unknown>> = {
   'channel:send': {
     type: 'object',
     properties: {
+      provider: { type: 'string' },
       channel: { type: 'string' },
       content: { type: 'string', minLength: 1 },
       sender: { type: 'string' },
+      metadata: { type: 'object', additionalProperties: true },
       dry_run: { type: 'boolean' },
     },
     required: ['content'],
@@ -193,9 +195,12 @@ const TOOL_INPUT_SCHEMAS: Record<SidekickToolName, Record<string, unknown>> = {
   'channel:receive': {
     type: 'object',
     properties: {
+      provider: { type: 'string' },
       channel: { type: 'string' },
+      cursor: { type: 'string' },
       limit: { type: 'integer', minimum: 1 },
       since: { type: 'string' },
+      metadata: { type: 'object', additionalProperties: true },
     },
     additionalProperties: false,
   },

package/packs/sidekick/manifest.yaml

@@ -235,6 +235,8 @@ tools:
     input_schema:
       type: object
       properties:
+        provider:
+          type: string
         channel:
           type: string
         content:
@@ -242,6 +244,9 @@ tools:
           minLength: 1
         sender:
           type: string
+        metadata:
+          type: object
+          additionalProperties: true
         dry_run:
           type: boolean
       required: [content]
@@ -259,13 +264,20 @@ tools:
     input_schema:
       type: object
       properties:
+        provider:
+          type: string
         channel:
           type: string
+        cursor:
+          type: string
         limit:
           type: integer
           minimum: 1
         since:
           type: string
+        metadata:
+          type: object
+          additionalProperties: true
       additionalProperties: false
     output_schema:
       type: object

package/packs/sidekick/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/packs-sidekick",
-  "version": "3.9.2",
+  "version": "3.9.6",
   "description": "Sidekick personal assistant pack for LumenFlow — 16 tools for task management, typed memory, channels, routines, and audit",
   "keywords": [
     "lumenflow",
@@ -27,6 +27,7 @@
     "./storage": "./dist/tool-impl/storage.js",
     "./tools": "./dist/tools/index.js",
     "./tool-impl": "./dist/tool-impl/index.js",
+    "./tool-impl/channel-transports": "./dist/tool-impl/channel-transports.js",
     "./tool-impl/channel-tools": "./dist/tool-impl/channel-tools.js",
     "./tool-impl/memory-tools": "./dist/tool-impl/memory-tools.js",
     "./tool-impl/routine-tools": "./dist/tool-impl/routine-tools.js",

package/packs/sidekick/tool-impl/channel-tools.ts

@@ -1,6 +1,7 @@
 // Copyright (c) 2026 Hellmai Ltd
 // SPDX-License-Identifier: AGPL-3.0-only
 
+import { getChannelTransport } from './channel-transports.js';
 import { getStoragePort, type ChannelMessageRecord, type ChannelRecord } from './storage.js';
 import {
   asInteger,
@@ -29,6 +30,26 @@ const TOOL_NAMES = {
 const OUTBOX_CAP = 100;
 const DEFAULT_CHANNEL_NAME = 'default';
 
+function asOptionalRecord(value: unknown): Record<string, unknown> | undefined {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+  return value as Record<string, unknown>;
+}
+
+function withTransportMetadata<T extends Record<string, unknown>>(
+  data: T,
+  metadata: Record<string, unknown> | undefined,
+): T & Record<string, unknown> {
+  if (!metadata) {
+    return data;
+  }
+  return {
+    ...data,
+    metadata,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // channel:configure
 // ---------------------------------------------------------------------------
@@ -99,6 +120,77 @@ async function channelConfigureTool(
 // channel:send
 // ---------------------------------------------------------------------------
 
+async function channelSendViaTransport(
+  input: Record<string, unknown>,
+  context: ToolContextLike | undefined,
+  provider: string,
+  channel: string,
+  content: string,
+): Promise<ToolOutput> {
+  const workspaceId = asNonEmptyString(context?.workspace_id);
+  if (!workspaceId) {
+    return failure(
+      'WORKSPACE_CONTEXT_REQUIRED',
+      'workspace_id is required when provider is specified.',
+    );
+  }
+
+  const transport = getChannelTransport(provider);
+  if (!transport) {
+    return failure(
+      'INTEGRATION_PROVIDER_NOT_REGISTERED',
+      `No channel transport registered for provider: ${provider}`,
+    );
+  }
+
+  if (isDryRun(input)) {
+    return success({
+      dry_run: true,
+      provider,
+      capability: 'send',
+      channel,
+      content,
+    });
+  }
+
+  const transportResult = await transport.send({
+    workspaceId,
+    provider,
+    channel,
+    content,
+    metadata: asOptionalRecord(input.metadata),
+  });
+
+  const outputData = withTransportMetadata(
+    {
+      provider,
+      capability: 'send',
+      channel,
+      ...(transportResult.externalMessageId !== undefined
+        ? { externalMessageId: transportResult.externalMessageId }
+        : {}),
+      ...(transportResult.failureClass ? { failureClass: transportResult.failureClass } : {}),
+      ...(transportResult.retryAfterSeconds !== undefined
+        ? { retryAfterSeconds: transportResult.retryAfterSeconds }
+        : {}),
+    },
+    transportResult.metadata,
+  );
+
+  if (!transportResult.success) {
+    return {
+      success: false,
+      error: {
+        code: 'INTEGRATION_PROVIDER_SEND_FAILED',
+        message: transportResult.error ?? `Provider send failed for provider: ${provider}`,
+      },
+      data: outputData,
+    };
+  }
+
+  return success(outputData);
+}
+
 async function channelSendTool(input: unknown, context?: ToolContextLike): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const content = asNonEmptyString(parsed.content);
@@ -108,6 +200,12 @@ async function channelSendTool(input: unknown, context?: ToolContextLike): Promi
   }
 
   const channelName = asNonEmptyString(parsed.channel) ?? DEFAULT_CHANNEL_NAME;
+  const provider = asNonEmptyString(parsed.provider);
+
+  if (provider) {
+    return channelSendViaTransport(parsed, context, provider, channelName, content);
+  }
+
   const sender = asNonEmptyString(parsed.sender) ?? 'assistant';
   const now = nowIso();
 
@@ -175,10 +273,86 @@ async function channelSendTool(input: unknown, context?: ToolContextLike): Promi
 // channel:receive
 // ---------------------------------------------------------------------------
 
+async function channelReceiveViaTransport(
+  input: Record<string, unknown>,
+  context: ToolContextLike | undefined,
+  provider: string,
+  channel: string,
+  limit: number | null,
+): Promise<ToolOutput> {
+  const workspaceId = asNonEmptyString(context?.workspace_id);
+  if (!workspaceId) {
+    return failure(
+      'WORKSPACE_CONTEXT_REQUIRED',
+      'workspace_id is required when provider is specified.',
+    );
+  }
+
+  const transport = getChannelTransport(provider);
+  if (!transport) {
+    return failure(
+      'INTEGRATION_PROVIDER_NOT_REGISTERED',
+      `No channel transport registered for provider: ${provider}`,
+    );
+  }
+
+  const cursor = asNonEmptyString(input.cursor) ?? undefined;
+
+  const transportResult = await transport.receive({
+    workspaceId,
+    provider,
+    channel,
+    cursor,
+    limit: limit && limit > 0 ? limit : undefined,
+    metadata: asOptionalRecord(input.metadata),
+  });
+
+  const outputData = withTransportMetadata(
+    {
+      provider,
+      capability: 'read',
+      channel,
+      ...(transportResult.records !== undefined ? { records: transportResult.records } : {}),
+      ...(transportResult.nextCursor !== undefined
+        ? { nextCursor: transportResult.nextCursor }
+        : {}),
+      ...(transportResult.failureClass ? { failureClass: transportResult.failureClass } : {}),
+      ...(transportResult.retryAfterSeconds !== undefined
+        ? { retryAfterSeconds: transportResult.retryAfterSeconds }
+        : {}),
+    },
+    transportResult.metadata,
+  );
+
+  if (!transportResult.success) {
+    return {
+      success: false,
+      error: {
+        code: 'INTEGRATION_PROVIDER_RECEIVE_FAILED',
+        message: transportResult.error ?? `Provider receive failed for provider: ${provider}`,
+      },
+      data: outputData,
+    };
+  }
+
+  return success(outputData);
+}
+
 async function channelReceiveTool(input: unknown, _context?: ToolContextLike): Promise<ToolOutput> {
   const parsed = toRecord(input);
   const channelName = asNonEmptyString(parsed.channel);
   const limit = asInteger(parsed.limit);
+  const provider = asNonEmptyString(parsed.provider);
+
+  if (provider) {
+    return channelReceiveViaTransport(
+      parsed,
+      _context,
+      provider,
+      channelName ?? DEFAULT_CHANNEL_NAME,
+      limit,
+    );
+  }
 
   const storage = getStoragePort();
   const messages = await storage.readStore('messages');

package/packs/sidekick/tool-impl/channel-transports.ts

@@ -0,0 +1,75 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { getSidekickRuntimeContext } from './runtime-context.js';
+
+export interface ChannelTransport {
+  provider: string;
+  send(req: {
+    workspaceId: string;
+    provider: string;
+    channel: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+  }): Promise<{
+    success: boolean;
+    error?: string;
+    externalMessageId?: string;
+    failureClass?: 'retryable' | 'terminal';
+    retryAfterSeconds?: number;
+    metadata?: Record<string, unknown>;
+  }>;
+  receive(req: {
+    workspaceId: string;
+    provider: string;
+    channel: string;
+    cursor?: string;
+    limit?: number;
+    metadata?: Record<string, unknown>;
+  }): Promise<{
+    success: boolean;
+    error?: string;
+    records?: unknown[];
+    nextCursor?: string;
+    failureClass?: 'retryable' | 'terminal';
+    retryAfterSeconds?: number;
+    metadata?: Record<string, unknown>;
+  }>;
+}
+
+function normalizeProvider(provider: string): string {
+  return provider.trim().toLowerCase();
+}
+
+function getRegistry(): Map<string, ChannelTransport> | undefined {
+  return getSidekickRuntimeContext()?.channelTransports;
+}
+
+export function registerChannelTransport(transport: ChannelTransport): void {
+  const provider = normalizeProvider(transport.provider);
+  if (provider.length === 0) {
+    throw new Error('channel transport provider must be a non-empty string.');
+  }
+  const registry = getRegistry();
+  if (!registry) {
+    throw new Error('channel transport registry is unavailable outside sidekick runtime context.');
+  }
+  registry.set(provider, transport);
+}
+
+export function getChannelTransport(provider: string): ChannelTransport | undefined {
+  const normalized = normalizeProvider(provider);
+  if (normalized.length === 0) {
+    return undefined;
+  }
+  const registry = getRegistry();
+  return registry?.get(normalized);
+}
+
+export function clearChannelTransports(): void {
+  const registry = getRegistry();
+  if (!registry) {
+    return;
+  }
+  registry.clear();
+}

package/packs/sidekick/tool-impl/index.ts

@@ -20,3 +20,10 @@ export {
   runWithStoragePort,
   setDefaultStoragePort,
 } from './storage.js';
+
+export {
+  type ChannelTransport,
+  clearChannelTransports,
+  getChannelTransport,
+  registerChannelTransport,
+} from './channel-transports.js';

package/packs/sidekick/tool-impl/runtime-context.ts

@@ -0,0 +1,24 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { ChannelTransport } from './channel-transports.js';
+import type { StoragePort } from './storage.js';
+
+export interface SidekickRuntimeContext {
+  storagePort: StoragePort;
+  channelTransports: Map<string, ChannelTransport>;
+}
+
+const runtimeContext = new AsyncLocalStorage<SidekickRuntimeContext>();
+
+export function getSidekickRuntimeContext(): SidekickRuntimeContext | undefined {
+  return runtimeContext.getStore();
+}
+
+export async function runWithSidekickRuntimeContext<T>(
+  context: SidekickRuntimeContext,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return runtimeContext.run(context, fn);
+}

package/packs/sidekick/tool-impl/shared.ts

@@ -7,6 +7,7 @@ import type { AuditEvent } from './storage.js';
 export interface ToolContextLike {
   tool_name?: string;
   receipt_id?: string;
+  workspace_id?: string;
 }
 
 export interface ToolOutput {

package/packs/sidekick/tool-impl/storage.ts

@@ -1,10 +1,10 @@
 // Copyright (c) 2026 Hellmai Ltd
 // SPDX-License-Identifier: AGPL-3.0-only
 
-import { AsyncLocalStorage } from 'node:async_hooks';
 import { randomBytes } from 'node:crypto';
 import { appendFile, mkdir, open, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { getSidekickRuntimeContext, runWithSidekickRuntimeContext } from './runtime-context.js';
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -299,7 +299,6 @@ export class FsStoragePort implements StoragePort {
 // Injection helpers (AsyncLocalStorage-based)
 // ---------------------------------------------------------------------------
 
-const storageContext = new AsyncLocalStorage<StoragePort>();
 let defaultStoragePort: StoragePort = new FsStoragePort();
 
 export function setDefaultStoragePort(port: StoragePort): void {
@@ -307,9 +306,16 @@ export function setDefaultStoragePort(port: StoragePort): void {
 }
 
 export function getStoragePort(): StoragePort {
-  return storageContext.getStore() ?? defaultStoragePort;
+  return getSidekickRuntimeContext()?.storagePort ?? defaultStoragePort;
 }
 
 export async function runWithStoragePort<T>(port: StoragePort, fn: () => Promise<T>): Promise<T> {
-  return storageContext.run(port, fn);
+  const existingContext = getSidekickRuntimeContext();
+  return runWithSidekickRuntimeContext(
+    {
+      storagePort: port,
+      channelTransports: existingContext?.channelTransports ?? new Map(),
+    },
+    fn,
+  );
 }

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

@@ -1,4 +1,4 @@
 
-> @lumenflow/packs-software-delivery@3.9.1 build /home/tom/source/hellmai/lumenflow-dev/packages/@lumenflow/packs/software-delivery
+> @lumenflow/packs-software-delivery@3.9.6 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": "3.9.2",
+  "version": "3.9.6",
   "description": "Software delivery pack for LumenFlow — work units, gates, lanes, initiatives, and agent coordination",
   "keywords": [
     "lumenflow",

package/templates/core/LUMENFLOW.md.template

@@ -230,30 +230,30 @@ For the full worktree lifecycle (parallel execution, bootstrap, isolation guaran
 
 > **Complete CLI reference (100+ commands):** See [quick-ref-commands.md](docs/04-operations/_frameworks/lumenflow/agent/onboarding/quick-ref-commands.md). Always run `<command> --help` for the authoritative option list.
 
-| Command                   | Description                                            |
-| ------------------------- | ------------------------------------------------------ |
-| `pnpm wu:create`          | Create new WU spec                                     |
-| `pnpm wu:claim`           | Claim WU, update canonical state, create worktree      |
-| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done                |
-| `pnpm wu:done`            | Complete WU (merge, stamp, cleanup)                    |
-| `pnpm wu:status`          | Show WU status, location, and valid commands           |
-| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies               |
-| `pnpm wu:block`           | Block WU (transitions to blocked, frees lane)          |
-| `pnpm wu:unblock`         | Unblock WU (transitions to in_progress)                |
-| `pnpm wu:release`         | Release orphaned WU (in_progress to ready for reclaim) |
-| `pnpm wu:brief`           | Generate handoff prompt + record evidence              |
-| `pnpm wu:delegate`        | Generate prompt + record delegation lineage            |
-| `pnpm wu:escalate`        | Show or resolve WU escalation status                   |
-| `pnpm wu:delete`          | Delete WU spec and cleanup                             |
-| `pnpm gates`              | Run quality gates (`--docs-only` for docs WUs)         |
-| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy)    |
-| `pnpm docs:generate`      | Regenerate CLI/config reference docs from source       |
-| `pnpm docs:validate`      | Verify generated docs are up-to-date                   |
-| `pnpm lane:status`        | Show lane lifecycle status + next step                 |
-| `pnpm lane:setup`         | Create/update draft lane artifacts                     |
-| `pnpm lane:validate`      | Validate lane artifacts before lock                    |
-| `pnpm lane:lock`          | Lock lane lifecycle for delivery WUs                   |
-| `pnpm mem:checkpoint`     | Save memory checkpoint                                 |
+| Command                   | Description                                               |
+| ------------------------- | --------------------------------------------------------- |
+| `pnpm wu:create`          | Create new WU spec                                        |
+| `pnpm wu:claim`           | Claim WU, update canonical state, create worktree         |
+| `pnpm wu:prep`            | Run gates in worktree, prep for wu:done                   |
+| `pnpm wu:done`            | Complete WU (merge, stamp, cleanup)                       |
+| `pnpm wu:status`          | Show WU status, location, and valid commands              |
+| `pnpm wu:recover`         | Analyze and fix WU state inconsistencies                  |
+| `pnpm wu:block`           | Block WU (transitions to blocked, frees lane)             |
+| `pnpm wu:unblock`         | Unblock WU (transitions to in_progress)                   |
+| `pnpm wu:release`         | Release orphaned WU (in_progress to ready for reclaim)    |
+| `pnpm wu:brief`           | Generate handoff prompt + record evidence                 |
+| `pnpm wu:delegate`        | Generate prompt + record lineage + brief hash attestation |
+| `pnpm wu:escalate`        | Show or resolve WU escalation status                      |
+| `pnpm wu:delete`          | Delete WU spec and cleanup                                |
+| `pnpm gates`              | Run quality gates (`--docs-only` for docs WUs)            |
+| `pnpm lumenflow:commands` | List all public commands (primary + alias + legacy)       |
+| `pnpm docs:generate`      | Regenerate CLI/config reference docs from source          |
+| `pnpm docs:validate`      | Verify generated docs are up-to-date                      |
+| `pnpm lane:status`        | Show lane lifecycle status + next step                    |
+| `pnpm lane:setup`         | Create/update draft lane artifacts                        |
+| `pnpm lane:validate`      | Validate lane artifacts before lock                       |
+| `pnpm lane:lock`          | Lock lane lifecycle for delivery WUs                      |
+| `pnpm mem:checkpoint`     | Save memory checkpoint                                    |
 
 Commands include **context-aware validation** that checks location, WU status, and git state. When validation fails, commands provide copy-paste ready fix commands. Configure in `workspace.yaml` under `software_delivery.experimental.context_validation`.
 The Starlight CLI reference page is intentionally curated to primary commands; use `pnpm lumenflow:commands` for complete discovery.

package/templates/core/ai/onboarding/agent-invocation-guide.md.template

@@ -106,8 +106,17 @@ This is useful when:
 
 `wu:delegate` records **delegation intent**: that a brief was generated for a target WU with explicit parent lineage.
 
+It also stores **brief attestation metadata** (SHA-256 prompt hash, client, timestamp, prompt length) for the generated handoff payload.
+
 It does **not** by itself prove pickup or execution. Pickup/execution confirmation comes from lifecycle evidence (claim/completion events, checkpoints, signals, and final `wu:done`).
 
+`wu:done` now enforces, for initiative-governed and explicitly delegated WUs:
+
+- Delegation lineage exists
+- Claim-time pickup evidence exists
+- Delegation brief attestation exists
+- Attested prompt hash matches recorded `wu:brief` evidence for the target WU
+
 ---
 
 ## 2c) Self-Implementation Evidence-Only Flow (WU-2222)

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

@@ -133,7 +133,7 @@ files, no manual git, no WU ceremony. Only actual **code changes** need WUs.
 | `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: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

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

@@ -10,20 +10,20 @@ 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               |
-| Pack registry  | `apps/web/` + pack tarballs | Manual deploy + curl publish        |
+| Component      | Location                    | Deployment                                          |
+| -------------- | --------------------------- | --------------------------------------------------- |
+| npm packages   | `packages/@lumenflow/*`     | Auto via GitHub Actions on tag push (`publish.yml`) |
+| Starlight docs | `apps/docs/`                | Separate GitHub Actions workflow (`docs.yml`)       |
+| Pack registry  | `apps/web/` + pack tarballs | Manual deploy + curl publish                        |
 
 ---
 
 ## Release Command
 
-The `pnpm release` command automates the entire release process:
+The `pnpm release` command automates version bump + tagging, and optionally npm publish:
 
 ```bash
-pnpm release --release-version 1.3.0
+pnpm release --release-version 1.3.0 --skip-publish
 ```
 
 ### What It Does
@@ -34,7 +34,7 @@ pnpm release --release-version 1.3.0
 4. Bumps all `@lumenflow/*` package versions using micro-worktree isolation
 5. Builds all packages
 6. Creates and pushes git tag `vX.Y.Z`
-7. Publishes to npm
+7. Optionally publishes to npm (unless `--skip-publish`)
 
 ### Options
 
@@ -50,19 +50,16 @@ pnpm release --release-version 1.3.0
 ### Examples
 
 ```bash
-# Full release
-pnpm release --release-version 1.3.0
-
-# Preview what would happen
-pnpm release --release-version 1.3.0 --dry-run
-
 # Version bump and tag only (CI will publish)
 pnpm release --release-version 1.3.0 --skip-publish
+
+# Preview what would happen
+pnpm release --release-version 1.3.0 --skip-publish --dry-run
 ```
 
 ### Authentication
 
-For npm publish, set one of these environment variables:
+For direct CLI npm publish (without `--skip-publish`), set one of these environment variables:
 
 ```bash
 export NPM_TOKEN=<your-npm-token>
@@ -179,8 +176,11 @@ The `.github/workflows/publish.yml` workflow:
 
 1. Checks out the tagged commit
 2. Installs dependencies
-3. Builds all packages
-4. Publishes to npm with `pnpm -r publish --access public`
+3. Builds publishable workspace packages only (`./packages/**`)
+4. Publishes to npm with `pnpm -r --filter "./packages/**" publish --access public --no-git-checks`
+5. Creates the GitHub release object (`gh release create ... --generate-notes`)
+
+`publish.yml` intentionally does **not** build `apps/docs` or `apps/web`, so docs/tooling dependencies cannot block npm publishing.
 
 ### Required Secrets
 
@@ -226,9 +226,25 @@ The public docs at <https://lumenflow.dev> are built from `apps/docs/`.
 
 **Automatic Generation:** CLI and config reference docs are automatically generated from code. See [Automatic Docs Generation](./docs-generation.md) for details on the single-source-of-truth pattern.
 
+### Build Workflow
+
+Starlight docs build in a separate workflow: `.github/workflows/docs.yml`.
+
+Trigger:
+
+- Tag push (`v*`)
+- Manual run (`workflow_dispatch`)
+
+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
+
 ### Deployment
 
-Starlight docs are deployed **manually** via Vercel CLI:
+Production deploy is still manual via Vercel CLI:
 
 ```bash
 cd apps/docs
@@ -368,17 +384,17 @@ The `@lumenflow/docs` package requires `d2` (diagramming tool) which is not avai
 
 ### Release Steps (Automated)
 
-Use the release command for the standard workflow:
+Use this as the standard workflow:
 
 ```bash
 # Preview first
-pnpm release --release-version 1.3.0 --dry-run
+pnpm release --release-version 1.3.0 --skip-publish --dry-run
 
-# Execute release
-pnpm release --release-version 1.3.0
+# Execute (version bump + tag, publish delegated to GitHub Actions)
+pnpm release --release-version 1.3.0 --skip-publish
 ```
 
-This handles version bump, build, tag, and npm publish automatically.
+This handles version bump and tag locally; GitHub Actions handles npm publish, docs build, and GitHub release creation.
 
 ### Release Steps (Manual)
 
@@ -398,21 +414,22 @@ If you need more control:
    git push origin v1.3.0
    ```
 
-3. **Verify npm publish**
+3. **Verify npm publish + GitHub release**
 
    ```bash
    gh run list --workflow=publish.yml --limit 1
    # Wait for completion, then verify
    npm view @lumenflow/cli version
+   gh release view v1.3.0
    ```
 
-4. **Create GitHub release**
+4. **Verify docs workflow** (if docs changed)
 
    ```bash
-   gh release create v1.3.0 --title "v1.3.0 - Title" --notes "Release notes..."
+   gh run list --workflow=docs.yml --limit 1
    ```
 
-5. **Deploy Starlight docs** (if content changed)
+5. **Deploy Starlight docs** (if content changed and you are deploying manually)
 
    ```bash
    cd apps/docs && pnpm build && vercel --prod
@@ -428,13 +445,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            | Deploy | No      |
-| Full release     | Tag + publish | 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            | Build workflow + deploy | No      |
+| Full release     | Tag + publish | Build workflow + deploy | Publish |
 
 \* CLI/config reference docs regenerate automatically during `wu:done` when trigger files change. See [Automatic Docs Generation](./docs-generation.md).