From 65378fc61abfc67b83a98c925078b6a3a3b78519 Mon Sep 17 00:00:00 2001
From: Thieu Nguyen <79964592+thieung@users.noreply.github.com>
Date: Thu, 13 Aug 2026 12:35:27 +0700
Subject: [PATCH 1/3] docs: beta v2.13.0-beta.2 release update (#62)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* docs: beta v2.13.0-beta.2 release update

Syncs beta channel to v2.13.0-beta.2 via sync-release.mjs (171 reference
files, ak-gui asset metadata refreshed for 4 platforms). Adds the new
ak orchestrate command group (start / resume / status / stop) as EN+VI
prose, mirrored into content/docs/stable/** for whole-copy parity.
Updates ak config prefs set/unset and index prose to cover the new
worktree.root leaf. Adds ak orchestrate to the root CLI outcome table.
Bumps release-quality-shape baseline to 398 source / 397 built routes.

* docs: bump search-index baseline for orchestrate group

* docs: keep orchestrate group off stable channel until promote

The prior commit mirrored the new ak orchestrate CLI group + config prefs
worktree.root prose into content/docs/stable/reference/cli/** to satisfy
cli-reference-routes.test.mjs's strict beta==stable route parity. That
would publish /en/stable/reference/cli/orchestrate/** on merge even
though channels.stable.tag is still v2.12.0, where the ak orchestrate
command does not exist upstream — misleading anyone reading the stable
docs.

Fix by relaxing the invariant to beta ⊇ stable (whole-copy promote stays
safe as long as every stable route also exists in beta; beta may include
routes authored ahead of the next promote) and removing the mirrored
orchestrate group + prose deltas from content/docs/stable/. The next
stable promote picks these up as part of its normal whole-copy step.

- cli-reference-routes.test.mjs: expected counts are per-channel; assert
  EN/VI parity within each channel and stable ⊆ beta across channels.
- release-quality-shape.mjs: per-channel source/route baselines; new
  addMissingSubset() replaces the strict equality cross-channel check.
- release-quality-metrics.mjs: per-channel searchPagesPerLocaleChannel.
- release-quality.test.mjs: fixtures updated to the object shape.

* fix: allow beta-only search routes

* fix: avoid unavailable channel links
---
 app/[lang]/(docs)/[...slug]/page.tsx          |   9 +-
 app/[lang]/(docs)/layout.tsx                  |  10 +-
 channels.json                                 |   8 +-
 components/beta-banner.tsx                    |  12 +-
 components/channel-selector.tsx               |  17 ++-
 components/product-docs-layout.tsx            |  15 ++-
 .../beta/desktop-app/getting-started.en.mdx   |   4 +-
 .../beta/desktop-app/getting-started.vi.mdx   |   4 +-
 content/docs/beta/desktop-app/index.en.mdx    |  10 +-
 content/docs/beta/desktop-app/index.vi.mdx    |  10 +-
 .../docs/beta/desktop-app/installation.en.mdx |  34 +++---
 .../docs/beta/desktop-app/installation.vi.mdx |  34 +++---
 .../beta/desktop-app/troubleshooting.en.mdx   |  12 +-
 .../beta/desktop-app/troubleshooting.vi.mdx   |  12 +-
 content/docs/beta/desktop-app/updating.en.mdx |   6 +-
 content/docs/beta/desktop-app/updating.vi.mdx |   6 +-
 .../reference/cli/config/prefs/index.en.mdx   |   4 +-
 .../reference/cli/config/prefs/index.vi.mdx   |   6 +-
 .../reference/cli/config/prefs/set.en.mdx     |  45 +++++---
 .../reference/cli/config/prefs/set.vi.mdx     |  42 ++++---
 .../reference/cli/config/prefs/unset.en.mdx   |  30 ++---
 .../reference/cli/config/prefs/unset.vi.mdx   |  29 +++--
 content/docs/beta/reference/cli/index.en.mdx  |   1 +
 content/docs/beta/reference/cli/index.vi.mdx  |   1 +
 content/docs/beta/reference/cli/meta.json     |   1 +
 content/docs/beta/reference/cli/meta.vi.json  |   1 +
 .../reference/cli/orchestrate/index.en.mdx    |  90 +++++++++++++++
 .../reference/cli/orchestrate/index.vi.mdx    |  90 +++++++++++++++
 .../beta/reference/cli/orchestrate/meta.json  |  10 ++
 .../reference/cli/orchestrate/meta.vi.json    |  10 ++
 .../reference/cli/orchestrate/resume.en.mdx   |  93 ++++++++++++++++
 .../reference/cli/orchestrate/resume.vi.mdx   |  93 ++++++++++++++++
 .../reference/cli/orchestrate/start.en.mdx    | 103 ++++++++++++++++++
 .../reference/cli/orchestrate/start.vi.mdx    | 103 ++++++++++++++++++
 .../reference/cli/orchestrate/status.en.mdx   |  93 ++++++++++++++++
 .../reference/cli/orchestrate/status.vi.mdx   |  93 ++++++++++++++++
 .../reference/cli/orchestrate/stop.en.mdx     |  89 +++++++++++++++
 .../reference/cli/orchestrate/stop.vi.mdx     |  89 +++++++++++++++
 content/docs/beta/reference/release-notes.mdx |  21 +++-
 lib/channel-route-href.mjs                    |  18 +++
 reference-derived/.generated                  |   6 +-
 reference-derived/ak.mdx                      |   1 +
 reference-derived/ak_config_prefs.mdx         |   4 +-
 reference-derived/ak_config_prefs_set.mdx     |  14 ++-
 reference-derived/ak_config_prefs_unset.mdx   |   5 +-
 reference-derived/ak_orchestrate.mdx          |  40 +++++++
 reference-derived/ak_orchestrate_resume.mdx   |  39 +++++++
 reference-derived/ak_orchestrate_start.mdx    |  39 +++++++
 reference-derived/ak_orchestrate_status.mdx   |  39 +++++++
 reference-derived/ak_orchestrate_stop.mdx     |  39 +++++++
 reference-derived/index.mdx                   |  14 ++-
 reference-raw/ak.mdx                          |   1 +
 reference-raw/ak_config_prefs.mdx             |   4 +-
 reference-raw/ak_config_prefs_set.mdx         |  16 +--
 reference-raw/ak_config_prefs_unset.mdx       |   7 +-
 reference-raw/ak_orchestrate.mdx              |  62 +++++++++++
 reference-raw/ak_orchestrate_resume.mdx       |  59 ++++++++++
 reference-raw/ak_orchestrate_start.mdx        |  59 ++++++++++
 reference-raw/ak_orchestrate_status.mdx       |  59 ++++++++++
 reference-raw/ak_orchestrate_stop.mdx         |  59 ++++++++++
 reference-raw/index.mdx                       |   5 +
 scripts/channel-route-href.test.mjs           |  40 +++++++
 scripts/cli-reference-routes.test.mjs         |  36 ++++--
 scripts/release-quality-metrics.mjs           |  25 ++++-
 scripts/release-quality-shape.mjs             |  71 +++++++-----
 scripts/release-quality.test.mjs              |  62 ++++++++---
 66 files changed, 1936 insertions(+), 227 deletions(-)
 create mode 100644 content/docs/beta/reference/cli/orchestrate/index.en.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/index.vi.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/meta.json
 create mode 100644 content/docs/beta/reference/cli/orchestrate/meta.vi.json
 create mode 100644 content/docs/beta/reference/cli/orchestrate/resume.en.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/resume.vi.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/start.en.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/start.vi.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/status.en.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/status.vi.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/stop.en.mdx
 create mode 100644 content/docs/beta/reference/cli/orchestrate/stop.vi.mdx
 create mode 100644 lib/channel-route-href.mjs
 create mode 100644 reference-derived/ak_orchestrate.mdx
 create mode 100644 reference-derived/ak_orchestrate_resume.mdx
 create mode 100644 reference-derived/ak_orchestrate_start.mdx
 create mode 100644 reference-derived/ak_orchestrate_status.mdx
 create mode 100644 reference-derived/ak_orchestrate_stop.mdx
 create mode 100644 reference-raw/ak_orchestrate.mdx
 create mode 100644 reference-raw/ak_orchestrate_resume.mdx
 create mode 100644 reference-raw/ak_orchestrate_start.mdx
 create mode 100644 reference-raw/ak_orchestrate_status.mdx
 create mode 100644 reference-raw/ak_orchestrate_stop.mdx
 create mode 100644 scripts/channel-route-href.test.mjs

diff --git a/app/[lang]/(docs)/[...slug]/page.tsx b/app/[lang]/(docs)/[...slug]/page.tsx
index e517d3f..17eb289 100644
--- a/app/[lang]/(docs)/[...slug]/page.tsx
+++ b/app/[lang]/(docs)/[...slug]/page.tsx
@@ -54,6 +54,9 @@ export default async function Page(props: PageProps<'/[lang]/[...slug]'>) {
   const eyebrow = breadcrumb.at(-1)?.name;
 
   const channel = channelFromSlug(params.slug);
+  const stableRouteExists = channel === 'beta' && params.slug
+    ? source.getPage(['stable', ...params.slug.slice(1)], params.lang) !== undefined
+    : false;
 
   return (
     <main className="contents">
@@ -65,7 +68,11 @@ export default async function Page(props: PageProps<'/[lang]/[...slug]'>) {
         breadcrumb={{ enabled: false }}
       >
         {channel === 'beta' && (
-          <BetaBanner locale={params.lang} slug={params.slug ?? []} />
+          <BetaBanner
+            locale={params.lang}
+            slug={params.slug ?? []}
+            stableRouteExists={stableRouteExists}
+          />
         )}
         {eyebrow && (
           <p className="mb-3 font-mono text-xs font-medium uppercase tracking-[0.09em] text-fd-primary">
diff --git a/app/[lang]/(docs)/layout.tsx b/app/[lang]/(docs)/layout.tsx
index b559da4..9ec1ac7 100644
--- a/app/[lang]/(docs)/layout.tsx
+++ b/app/[lang]/(docs)/layout.tsx
@@ -1,4 +1,5 @@
 import { ProductDocsLayout } from '@/components/product-docs-layout';
+import { unavailableChannelUrls } from '@/lib/channel-route-href.mjs';
 import { source } from '@/lib/source';
 import type { SerializedPageTree } from 'fumadocs-core/source/client';
 
@@ -14,9 +15,16 @@ export default async function Layout({
   const tree = JSON.parse(
     JSON.stringify(await source.serializePageTree(source.getPageTree(lang))),
   ) as SerializedPageTree;
+  const unavailableUrls = unavailableChannelUrls(
+    source.getPages(lang).map((page) => page.url),
+  );
 
   return (
-    <ProductDocsLayout locale={lang} tree={tree}>
+    <ProductDocsLayout
+      locale={lang}
+      tree={tree}
+      unavailableUrls={unavailableUrls}
+    >
       {children}
     </ProductDocsLayout>
   );
diff --git a/channels.json b/channels.json
index 79ae5e0..884cecf 100644
--- a/channels.json
+++ b/channels.json
@@ -6,9 +6,9 @@
     "syncedAt": "2026-08-08T12:00:11+00:00"
   },
   "beta": {
-    "version": "2.12.1-beta.8",
-    "tag": "v2.12.1-beta.8",
-    "sha": "1376205a3953306d5f80ff9d61f2a94c6267dfa7",
-    "syncedAt": "2026-08-11T05:59:40Z"
+    "version": "2.13.0-beta.2",
+    "tag": "v2.13.0-beta.2",
+    "sha": "e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2",
+    "syncedAt": "2026-08-12T06:17:36Z"
   }
 }
diff --git a/components/beta-banner.tsx b/components/beta-banner.tsx
index 3dbd5c3..21d1b38 100644
--- a/components/beta-banner.tsx
+++ b/components/beta-banner.tsx
@@ -1,6 +1,6 @@
 import Link from 'next/link';
+import { channelRouteHref } from '@/lib/channel-route-href.mjs';
 import { getChannelVersion } from '@/lib/channels';
-import { localePath } from '@/lib/locale-path';
 
 // Persistent beta-channel notice. Rendered on every `beta/` docs page (keyed on
 // the slug's channel prefix by the caller). The version is read from
@@ -56,21 +56,21 @@ const copy = {
 export function BetaBanner({
   locale,
   slug,
+  stableRouteExists,
 }: {
   locale: string;
   slug: string[];
+  stableRouteExists: boolean;
 }) {
   const t = copy[locale as keyof typeof copy] ?? copy.en;
   const version = getChannelVersion('beta');
   const stableVersion = getChannelVersion('stable');
   const mirrorsStable = version !== null && version === stableVersion;
-  // Same page on the stable channel = swap the leading `beta` segment.
-  // Static params retain percent-encoded spaces; pass decoded segments to
-  // Next's Link so it applies URL encoding exactly once.
-  const stableHref = localePath(
+  const stableHref = channelRouteHref(
     locale,
     'stable',
-    ...slug.slice(1).map((segment) => decodeURI(segment)),
+    slug.slice(1),
+    stableRouteExists,
   );
 
   return (
diff --git a/components/channel-selector.tsx b/components/channel-selector.tsx
index 3ce392b..1908d5a 100644
--- a/components/channel-selector.tsx
+++ b/components/channel-selector.tsx
@@ -1,5 +1,6 @@
 'use client';
 
+import { channelRouteHref } from '@/lib/channel-route-href.mjs';
 import { cn } from '@/lib/cn';
 import { getChannelVersion } from '@/lib/channels';
 import Link from 'next/link';
@@ -7,7 +8,13 @@ import { usePathname } from 'next/navigation';
 
 const channels = ['stable', 'beta'] as const;
 
-export function ChannelSelector({ locale }: { locale: string }) {
+export function ChannelSelector({
+  locale,
+  unavailableUrls,
+}: {
+  locale: string;
+  unavailableUrls: Set<string>;
+}) {
   const pathname = usePathname();
   const segments = pathname.split('/').filter(Boolean);
   const activeChannel = channels.find((channel) => segments[1] === channel) ?? 'stable';
@@ -18,7 +25,13 @@ export function ChannelSelector({ locale }: { locale: string }) {
       <div className="grid grid-cols-2 rounded-lg border bg-fd-secondary/50 p-1">
         {channels.map((channel) => {
           const active = channel === activeChannel;
-          const href = `/${locale}/${channel}${remainder.length > 0 ? `/${remainder.join('/')}` : ''}`;
+          const targetPath = `/${locale}/${channel}${remainder.length > 0 ? `/${remainder.join('/')}` : ''}`;
+          const href = channelRouteHref(
+            locale,
+            channel,
+            remainder,
+            !unavailableUrls.has(targetPath),
+          );
           const version = getChannelVersion(channel);
 
           return (
diff --git a/components/product-docs-layout.tsx b/components/product-docs-layout.tsx
index 3f37aea..31191d8 100644
--- a/components/product-docs-layout.tsx
+++ b/components/product-docs-layout.tsx
@@ -19,16 +19,22 @@ export function ProductDocsLayout({
   children,
   locale,
   tree,
+  unavailableUrls,
 }: {
   children: ReactNode;
   locale: string;
   tree: SerializedPageTree;
+  unavailableUrls: string[];
 }) {
   const pathname = usePathname();
   const product = activeProduct(pathname);
   const channelSegment = pathname.split('/').filter(Boolean)[1];
   const channel = channelSegment === 'beta' ? 'beta' : 'stable';
   const pageTree = useMemo(() => deserializePageTree(tree), [tree]);
+  const unavailableUrlSet = useMemo(
+    () => new Set(unavailableUrls),
+    [unavailableUrls],
+  );
   const filteredTree = useMemo(
     () => filterTreeByProduct(pageTree, product),
     [pageTree, product],
@@ -44,7 +50,14 @@ export function ProductDocsLayout({
       tabs={tabs}
       tabMode="top"
       containerProps={{ className: 'ak-product-docs-layout' }}
-      sidebar={{ banner: <ChannelSelector locale={locale} /> }}
+      sidebar={{
+        banner: (
+          <ChannelSelector
+            locale={locale}
+            unavailableUrls={unavailableUrlSet}
+          />
+        ),
+      }}
       {...baseOptions(locale)}
     >
       {children}
diff --git a/content/docs/beta/desktop-app/getting-started.en.mdx b/content/docs/beta/desktop-app/getting-started.en.mdx
index 3ac70ce..f664913 100644
--- a/content/docs/beta/desktop-app/getting-started.en.mdx
+++ b/content/docs/beta/desktop-app/getting-started.en.mdx
@@ -39,12 +39,12 @@ installed and entitled Kits, configuration, health, licenses, and updates.
 Review the results before applying changes.
 
 The optional Kit step installs only the Kits you select, globally for the
-detected coding agents, from the Kit catalog used by Desktop v2.12.1-beta.8. You can
+detected coding agents, from the Kit catalog used by Desktop v2.13.0-beta.2. You can
 skip it when you do not have a matching runtime or entitlement. After
 installation, restart the coding assistant or open a new runtime session before
 using the new skills.
 
-Desktop v2.12.1-beta.8 does not start a Kit skill or agent run. Launch the installed
+Desktop v2.13.0-beta.2 does not start a Kit skill or agent run. Launch the installed
 skill from its coding assistant, or use the appropriate CLI workflow.
 
 ## Use the main workflows
diff --git a/content/docs/beta/desktop-app/getting-started.vi.mdx b/content/docs/beta/desktop-app/getting-started.vi.mdx
index d9558cd..66b70fd 100644
--- a/content/docs/beta/desktop-app/getting-started.vi.mdx
+++ b/content/docs/beta/desktop-app/getting-started.vi.mdx
@@ -38,11 +38,11 @@ ký, Kit đã cài và được cấp quyền, cấu hình, health, license và
 kết quả trước khi áp dụng thay đổi.
 
 Bước Kit tuỳ chọn chỉ cài các Kit bạn chọn, ở global scope cho coding agent đã
-phát hiện, từ Kit catalog mà Desktop v2.12.1-beta.8 sử dụng. Bạn có thể bỏ qua nếu không
+phát hiện, từ Kit catalog mà Desktop v2.13.0-beta.2 sử dụng. Bạn có thể bỏ qua nếu không
 có runtime hoặc entitlement phù hợp. Sau khi cài, hãy khởi động lại coding
 assistant hoặc mở runtime session mới trước khi dùng skill mới.
 
-Desktop v2.12.1-beta.8 không khởi động skill của Kit hay agent run. Hãy khởi chạy skill
+Desktop v2.13.0-beta.2 không khởi động skill của Kit hay agent run. Hãy khởi chạy skill
 đã cài trong coding assistant hoặc dùng quy trình CLI phù hợp.
 
 ## Dùng các quy trình chính
diff --git a/content/docs/beta/desktop-app/index.en.mdx b/content/docs/beta/desktop-app/index.en.mdx
index 005eaa5..469bb2d 100644
--- a/content/docs/beta/desktop-app/index.en.mdx
+++ b/content/docs/beta/desktop-app/index.en.mdx
@@ -6,11 +6,11 @@ description: Choose the AgentKit Desktop App when you want a native interface fo
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="info">
-  These pages describe AgentKit Desktop **v2.12.1-beta.8**. Artifact filenames,
+  These pages describe AgentKit Desktop **v2.13.0-beta.2**. Artifact filenames,
   bytes, and SHA-256 hashes are refreshed from the release page.
   Screenshots in `public/gui/` may still show earlier layouts and will be
   recaptured in a follow-up pass; the described behavior matches the
-  v2.12.1-beta.8 packages.
+  v2.13.0-beta.2 packages.
 </Callout>
 
 AgentKit Desktop gives you a native window for inspecting and managing the
@@ -35,7 +35,7 @@ a Desktop download hint rather than finding an app you installed elsewhere.
 Read the [`ak gui` reference](../reference/cli/gui) for
 the exact command boundary.
 
-## Supported v2.12.1-beta.8 packages
+## Supported v2.13.0-beta.2 packages
 
 | Operating system | Desktop architectures |
 | --- | --- |
@@ -43,7 +43,7 @@ the exact command boundary.
 | Linux | x64 (`amd64`) only |
 | Windows | x64 (`amd64`) only |
 
-There is no v2.12.1-beta.8 Desktop package for Linux ARM64 or Windows ARM64. The CLI
+There is no v2.13.0-beta.2 Desktop package for Linux ARM64 or Windows ARM64. The CLI
 remains available on both. Other operating systems, architectures, and 32-bit
 hosts are not included in the Desktop release matrix.
 
@@ -65,7 +65,7 @@ After activating an App license on this device, Desktop can:
 - Edit AgentKit configuration, inspect effective settings, and locate local
   AgentKit data stores.
 
-Desktop v2.12.1-beta.8 does not launch a Kit skill or agent run. Run the installed skill
+Desktop v2.13.0-beta.2 does not launch a Kit skill or agent run. Run the installed skill
 inside its coding assistant, or use the appropriate CLI command. Desktop then
 reads the resulting local Activity and session evidence where that runtime is
 supported.
diff --git a/content/docs/beta/desktop-app/index.vi.mdx b/content/docs/beta/desktop-app/index.vi.mdx
index aa6455b..258454c 100644
--- a/content/docs/beta/desktop-app/index.vi.mdx
+++ b/content/docs/beta/desktop-app/index.vi.mdx
@@ -6,10 +6,10 @@ description: Chọn ứng dụng AgentKit Desktop khi bạn muốn giao diện n
 import { Callout } from 'fumadocs-ui/components/callout';
 
 <Callout type="info">
-  Các trang này mô tả AgentKit Desktop **v2.12.1-beta.8**. Tên artifact, kích thước
+  Các trang này mô tả AgentKit Desktop **v2.13.0-beta.2**. Tên artifact, kích thước
   và SHA-256 đã được refresh từ trang release. Ảnh chụp trong `public/gui/`
   có thể vẫn hiển thị layout cũ và sẽ được chụp lại ở đợt sau; nội dung
-  mô tả hành vi khớp với gói v2.12.1-beta.8.
+  mô tả hành vi khớp với gói v2.13.0-beta.2.
 </Callout>
 
 AgentKit Desktop cung cấp cửa sổ native để kiểm tra và quản lý trạng thái
@@ -33,7 +33,7 @@ cũng không chứa Wails: chạy `ak gui` từ artifact đó sẽ in gợi ý t
 vì tìm ứng dụng bạn đã cài ở nơi khác. Đọc [tham chiếu `ak gui`](../reference/cli/gui) để biết ranh giới chính xác của
 lệnh.
 
-## Gói v2.12.1-beta.8 được hỗ trợ
+## Gói v2.13.0-beta.2 được hỗ trợ
 
 | Hệ điều hành | Kiến trúc Desktop |
 | --- | --- |
@@ -41,7 +41,7 @@ lệnh.
 | Linux | Chỉ x64 (`amd64`) |
 | Windows | Chỉ x64 (`amd64`) |
 
-Không có gói Desktop v2.12.1-beta.8 cho Linux ARM64 hoặc Windows ARM64. CLI vẫn khả dụng
+Không có gói Desktop v2.13.0-beta.2 cho Linux ARM64 hoặc Windows ARM64. CLI vẫn khả dụng
 trên cả hai. Ma trận phát hành Desktop không bao gồm hệ điều hành, kiến trúc hay
 host 32-bit khác.
 
@@ -63,7 +63,7 @@ Sau khi kích hoạt license App trên thiết bị này, Desktop có thể:
 - Chỉnh cấu hình AgentKit, kiểm tra thiết lập hiệu lực và tìm local data store
   của AgentKit.
 
-Desktop v2.12.1-beta.8 không khởi chạy skill của Kit hay agent run. Hãy chạy skill đã
+Desktop v2.13.0-beta.2 không khởi chạy skill của Kit hay agent run. Hãy chạy skill đã
 cài trong coding assistant của nó hoặc dùng lệnh CLI phù hợp. Sau đó Desktop sẽ
 đọc bằng chứng Activity và session cục bộ thu được nếu runtime đó được hỗ trợ.
 
diff --git a/content/docs/beta/desktop-app/installation.en.mdx b/content/docs/beta/desktop-app/installation.en.mdx
index d86f8e6..32bf9a4 100644
--- a/content/docs/beta/desktop-app/installation.en.mdx
+++ b/content/docs/beta/desktop-app/installation.en.mdx
@@ -1,28 +1,28 @@
 ---
 title: Install the Desktop app
-description: Download, verify, and open the exact AgentKit Desktop v2.12.1-beta.8 package for a supported platform.
+description: Download, verify, and open the exact AgentKit Desktop v2.13.0-beta.2 package for a supported platform.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
 After this page, you will have opened a checksum-verified AgentKit Desktop
-v2.12.1-beta.8 package. Desktop is a manual download in this release; the CLI installer
+v2.13.0-beta.2 package. Desktop is a manual download in this release; the CLI installer
 does not install it.
 
 ## Download the matching package
 
 Download the artifact and its `.sha256` sidecar from the official
-[AgentKit v2.12.1-beta.8 release](https://github.com/bestagentkits/agentkit/releases/tag/v2.12.1-beta.8).
+[AgentKit v2.13.0-beta.2 release](https://github.com/bestagentkits/agentkit/releases/tag/v2.13.0-beta.2).
 
 | Platform | Artifact | Bytes | SHA-256 |
 | --- | --- | ---: | --- |
-| macOS Intel | `ak-gui_2.12.1-beta.8_darwin_amd64.zip` | 12,920,008 | `1e106fdfeea218310f18104c6990605efd4036729a30a0da2d6c84e4d359ff91` |
-| macOS Apple silicon | `ak-gui_2.12.1-beta.8_darwin_arm64.zip` | 11,940,163 | `da083e8bb1c994adf818249e3e01ef7d68b3544bf155b94aab3c4513f014c11f` |
-| Linux x64 | `ak-gui_2.12.1-beta.8_linux_amd64.AppImage` | 90,003,960 | `3a9650190fa12c557e4933be42f0bd134413560e576324e4f2c4f4ce9af27336` |
-| Windows x64 | `ak-gui_2.12.1-beta.8_windows_amd64.zip` | 13,024,094 | `b5ba1d9594ea215916ac77439acc0fe515b2edaaeacc3c5a3e9644d30458e759` |
+| macOS Intel | `ak-gui_2.13.0-beta.2_darwin_amd64.zip` | 13,000,394 | `9e6926e815fb87d04bfb8603a9027f7fb8aab03a5eb3eb90b42f6b3490a9e566` |
+| macOS Apple silicon | `ak-gui_2.13.0-beta.2_darwin_arm64.zip` | 12,011,474 | `a5ab23b9a47faf326cc98c9625a27d45a70f1e989d81e5cd82cabee4990ce497` |
+| Linux x64 | `ak-gui_2.13.0-beta.2_linux_amd64.AppImage` | 90,057,208 | `b0b353a23dc30fe749546b366d0870df71da3dcfad8972e1d3858caf04d3f550` |
+| Windows x64 | `ak-gui_2.13.0-beta.2_windows_amd64.zip` | 13,074,322 | `31ad439bf569d6fd75ce29d5672966a81e33065a5724aaa261fbc64ce61dab08` |
 
-There is no Desktop artifact for Linux ARM64 or Windows ARM64 in v2.12.1-beta.8.
-Do not substitute the similarly named `ak_2.12.1-beta.8_*` archive: that is the CLI
+There is no Desktop artifact for Linux ARM64 or Windows ARM64 in v2.13.0-beta.2.
+Do not substitute the similarly named `ak_2.13.0-beta.2_*` archive: that is the CLI
 artifact and contains no Wails window.
 
 ## Verify the download
@@ -34,7 +34,7 @@ digest differs.
 ### macOS
 
 ```bash
-shasum -a 256 ak-gui_2.12.1-beta.8_darwin_arm64.zip
+shasum -a 256 ak-gui_2.13.0-beta.2_darwin_arm64.zip
 ```
 
 Replace `arm64` with `amd64` for an Intel Mac.
@@ -42,13 +42,13 @@ Replace `arm64` with `amd64` for an Intel Mac.
 ### Linux
 
 ```bash
-sha256sum ak-gui_2.12.1-beta.8_linux_amd64.AppImage
+sha256sum ak-gui_2.13.0-beta.2_linux_amd64.AppImage
 ```
 
 ### Windows PowerShell
 
 ```powershell
-Get-FileHash .\ak-gui_2.12.1-beta.8_windows_amd64.zip -Algorithm SHA256
+Get-FileHash .\ak-gui_2.13.0-beta.2_windows_amd64.zip -Algorithm SHA256
 ```
 
 <Callout type="warn">
@@ -83,8 +83,8 @@ on; do not apply a system-wide exception.
 Keep the AppImage in a user-controlled applications directory, then run:
 
 ```bash
-chmod +x ak-gui_2.12.1-beta.8_linux_amd64.AppImage
-./ak-gui_2.12.1-beta.8_linux_amd64.AppImage
+chmod +x ak-gui_2.13.0-beta.2_linux_amd64.AppImage
+./ak-gui_2.13.0-beta.2_linux_amd64.AppImage
 ```
 
 If it reports a FUSE error, install your distribution's FUSE compatibility
@@ -92,7 +92,7 @@ package and retry the same verified AppImage. Do not run it as root.
 
 ### Windows
 
-1. Extract `ak-gui_2.12.1-beta.8_windows_amd64.zip` to a user-controlled applications
+1. Extract `ak-gui_2.13.0-beta.2_windows_amd64.zip` to a user-controlled applications
    folder.
 2. Run `ak-gui.exe` from the extracted folder.
 
@@ -115,12 +115,12 @@ Desktop installation.
 
 ## Remove Desktop
 
-There is no Desktop uninstaller in v2.12.1-beta.8. Quit the app, optionally sign out
+There is no Desktop uninstaller in v2.13.0-beta.2. Quit the app, optionally sign out
 from **Profile** to clear the local App session, then remove only the item you
 installed:
 
 - `/Applications/agentkit.app` on macOS;
-- The exact `ak-gui_2.12.1-beta.8_linux_amd64.AppImage` on Linux; or
+- The exact `ak-gui_2.13.0-beta.2_linux_amd64.AppImage` on Linux; or
 - The extracted Desktop folder containing `ak-gui.exe` on Windows.
 
 This does not remove the CLI, installed Kits, runtime files, or AgentKit state.
diff --git a/content/docs/beta/desktop-app/installation.vi.mdx b/content/docs/beta/desktop-app/installation.vi.mdx
index 469e7b6..23d8692 100644
--- a/content/docs/beta/desktop-app/installation.vi.mdx
+++ b/content/docs/beta/desktop-app/installation.vi.mdx
@@ -1,28 +1,28 @@
 ---
 title: Cài ứng dụng Desktop
-description: Tải, xác minh và mở đúng gói AgentKit Desktop v2.12.1-beta.8 cho nền tảng được hỗ trợ.
+description: Tải, xác minh và mở đúng gói AgentKit Desktop v2.13.0-beta.2 cho nền tảng được hỗ trợ.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-Sau trang này, bạn sẽ mở một gói AgentKit Desktop v2.12.1-beta.8 đã được xác minh
+Sau trang này, bạn sẽ mở một gói AgentKit Desktop v2.13.0-beta.2 đã được xác minh
 checksum. Desktop được tải thủ công trong bản phát hành này; trình cài CLI không
 cài ứng dụng.
 
 ## Tải gói phù hợp
 
 Tải artifact và sidecar `.sha256` của nó từ [bản phát hành AgentKit
-v2.12.1-beta.8](https://github.com/bestagentkits/agentkit/releases/tag/v2.12.1-beta.8) chính thức.
+v2.13.0-beta.2](https://github.com/bestagentkits/agentkit/releases/tag/v2.13.0-beta.2) chính thức.
 
 | Nền tảng | Artifact | Byte | SHA-256 |
 | --- | --- | ---: | --- |
-| macOS Intel | `ak-gui_2.12.1-beta.8_darwin_amd64.zip` | 12,920,008 | `1e106fdfeea218310f18104c6990605efd4036729a30a0da2d6c84e4d359ff91` |
-| macOS Apple silicon | `ak-gui_2.12.1-beta.8_darwin_arm64.zip` | 11,940,163 | `da083e8bb1c994adf818249e3e01ef7d68b3544bf155b94aab3c4513f014c11f` |
-| Linux x64 | `ak-gui_2.12.1-beta.8_linux_amd64.AppImage` | 90,003,960 | `3a9650190fa12c557e4933be42f0bd134413560e576324e4f2c4f4ce9af27336` |
-| Windows x64 | `ak-gui_2.12.1-beta.8_windows_amd64.zip` | 13,024,094 | `b5ba1d9594ea215916ac77439acc0fe515b2edaaeacc3c5a3e9644d30458e759` |
+| macOS Intel | `ak-gui_2.13.0-beta.2_darwin_amd64.zip` | 13,000,394 | `9e6926e815fb87d04bfb8603a9027f7fb8aab03a5eb3eb90b42f6b3490a9e566` |
+| macOS Apple silicon | `ak-gui_2.13.0-beta.2_darwin_arm64.zip` | 12,011,474 | `a5ab23b9a47faf326cc98c9625a27d45a70f1e989d81e5cd82cabee4990ce497` |
+| Linux x64 | `ak-gui_2.13.0-beta.2_linux_amd64.AppImage` | 90,057,208 | `b0b353a23dc30fe749546b366d0870df71da3dcfad8972e1d3858caf04d3f550` |
+| Windows x64 | `ak-gui_2.13.0-beta.2_windows_amd64.zip` | 13,074,322 | `31ad439bf569d6fd75ce29d5672966a81e33065a5724aaa261fbc64ce61dab08` |
 
-Không có artifact Desktop cho Linux ARM64 hoặc Windows ARM64 trong v2.12.1-beta.8.
-Đừng thay bằng archive có tên gần giống `ak_2.12.1-beta.8_*`: đó là artifact CLI và
+Không có artifact Desktop cho Linux ARM64 hoặc Windows ARM64 trong v2.13.0-beta.2.
+Đừng thay bằng archive có tên gần giống `ak_2.13.0-beta.2_*`: đó là artifact CLI và
 không chứa cửa sổ Wails.
 
 ## Xác minh tệp tải xuống
@@ -33,7 +33,7 @@ và sidecar đã tải. Dừng lại nếu kích thước tệp hoặc digest kh
 ### macOS
 
 ```bash
-shasum -a 256 ak-gui_2.12.1-beta.8_darwin_arm64.zip
+shasum -a 256 ak-gui_2.13.0-beta.2_darwin_arm64.zip
 ```
 
 Thay `arm64` bằng `amd64` trên máy Mac Intel.
@@ -41,13 +41,13 @@ Thay `arm64` bằng `amd64` trên máy Mac Intel.
 ### Linux
 
 ```bash
-sha256sum ak-gui_2.12.1-beta.8_linux_amd64.AppImage
+sha256sum ak-gui_2.13.0-beta.2_linux_amd64.AppImage
 ```
 
 ### Windows PowerShell
 
 ```powershell
-Get-FileHash .\ak-gui_2.12.1-beta.8_windows_amd64.zip -Algorithm SHA256
+Get-FileHash .\ak-gui_2.13.0-beta.2_windows_amd64.zip -Algorithm SHA256
 ```
 
 <Callout type="warn">
@@ -82,8 +82,8 @@ lệ cho toàn hệ thống.
 Giữ AppImage trong thư mục ứng dụng do người dùng kiểm soát, rồi chạy:
 
 ```bash
-chmod +x ak-gui_2.12.1-beta.8_linux_amd64.AppImage
-./ak-gui_2.12.1-beta.8_linux_amd64.AppImage
+chmod +x ak-gui_2.13.0-beta.2_linux_amd64.AppImage
+./ak-gui_2.13.0-beta.2_linux_amd64.AppImage
 ```
 
 Nếu có lỗi FUSE, hãy cài gói tương thích FUSE của distribution rồi thử lại cùng
@@ -91,7 +91,7 @@ AppImage đã xác minh. Đừng chạy ứng dụng bằng root.
 
 ### Windows
 
-1. Giải nén `ak-gui_2.12.1-beta.8_windows_amd64.zip` vào thư mục ứng dụng do người dùng
+1. Giải nén `ak-gui_2.13.0-beta.2_windows_amd64.zip` vào thư mục ứng dụng do người dùng
    kiểm soát.
 2. Chạy `ak-gui.exe` trong thư mục đã giải nén.
 
@@ -113,11 +113,11 @@ Chạy `ak gui` từ CLI tiêu chuẩn không khởi chạy bản cài Desktop r
 
 ## Gỡ Desktop
 
-Không có trình gỡ Desktop trong v2.12.1-beta.8. Hãy thoát ứng dụng, tuỳ chọn đăng xuất
+Không có trình gỡ Desktop trong v2.13.0-beta.2. Hãy thoát ứng dụng, tuỳ chọn đăng xuất
 trong **Profile** để xoá App session cục bộ, rồi chỉ xoá mục bạn đã cài:
 
 - `/Applications/agentkit.app` trên macOS;
-- Đúng tệp `ak-gui_2.12.1-beta.8_linux_amd64.AppImage` trên Linux; hoặc
+- Đúng tệp `ak-gui_2.13.0-beta.2_linux_amd64.AppImage` trên Linux; hoặc
 - Thư mục Desktop đã giải nén chứa `ak-gui.exe` trên Windows.
 
 Thao tác này không gỡ CLI, Kit đã cài, tệp runtime hay trạng thái AgentKit.
diff --git a/content/docs/beta/desktop-app/troubleshooting.en.mdx b/content/docs/beta/desktop-app/troubleshooting.en.mdx
index 7325daa..f02a726 100644
--- a/content/docs/beta/desktop-app/troubleshooting.en.mdx
+++ b/content/docs/beta/desktop-app/troubleshooting.en.mdx
@@ -3,7 +3,7 @@ title: Troubleshoot the Desktop app
 description: Diagnose first-launch, license, local-data, platform, and staged-update problems without deleting user state.
 ---
 
-Start with the symptom below. Keep the verified v2.12.1-beta.8 artifact and preserve
+Start with the symptom below. Keep the verified v2.13.0-beta.2 artifact and preserve
 AgentKit state while you diagnose the issue.
 
 ## The window does not open
@@ -11,9 +11,9 @@ AgentKit state while you diagnose the issue.
 | Symptom | Meaning | Safe next step |
 | --- | --- | --- |
 | `ak gui` prints a Desktop download hint and exits `1` | You ran the standard non-Wails CLI artifact | Run the verified Desktop artifact directly |
-| Linux ARM64 or Windows ARM64 prints an availability warning and exits `0` | v2.12.1-beta.8 has no Desktop package for that architecture | Use the CLI or browser dashboard; do not substitute an x64 binary |
+| Linux ARM64 or Windows ARM64 prints an availability warning and exits `0` | v2.13.0-beta.2 has no Desktop package for that architecture | Use the CLI or browser dashboard; do not substitute an x64 binary |
 | macOS blocks the app | Gatekeeper has not allowed this bundle | Recheck SHA-256, then use the allow-once flow in [Installation](./installation) |
-| Linux reports permission denied | The AppImage is not executable | Run `chmod +x ak-gui_2.12.1-beta.8_linux_amd64.AppImage` as your user |
+| Linux reports permission denied | The AppImage is not executable | Run `chmod +x ak-gui_2.13.0-beta.2_linux_amd64.AppImage` as your user |
 | Linux reports a FUSE error | The host lacks the AppImage FUSE compatibility layer | Install the distribution's compatibility package; do not run as root |
 | Windows shows SmartScreen | Windows is evaluating the downloaded executable | Recheck SHA-256 before choosing **More info → Run anyway** for the matching release artifact |
 | Windows reports that Microsoft Edge WebView2 Runtime was not found | The startup preflight could not find the required WebView2 runtime | Install or repair WebView2 from [Microsoft's official download page](https://developer.microsoft.com/microsoft-edge/webview2/consumer/), then retry |
@@ -56,7 +56,7 @@ Sign out** clears only the local App slot; `ak logout` clears only the CLI slot.
 - Removing a project in Desktop removes only its AgentKit registry entry. It
   does not delete the project directory.
 
-Desktop v2.12.1-beta.8 does not launch Kit skills or agent runs. Run the skill in its
+Desktop v2.13.0-beta.2 does not launch Kit skills or agent runs. Run the skill in its
 coding assistant before expecting new Activity or session evidence.
 
 ## A port is busy
@@ -75,7 +75,7 @@ does not stop a dashboard or API server started separately.
 
 ## An update will not complete
 
-- Windows x64 rejects paired Desktop apply in v2.12.1-beta.8. Download and verify the
+- Windows x64 rejects paired Desktop apply in v2.13.0-beta.2. Download and verify the
   replacement Desktop zip manually.
 - On macOS or Linux x64, keep the matching standard CLI installed and preserve
   `$AGENTKIT_HOME/updater/pending-binary-update.json` plus its reported staging
@@ -98,7 +98,7 @@ Quit Desktop, open a terminal, and launch the exact installed executable:
 ```
 
 ```bash
-./ak-gui_2.12.1-beta.8_linux_amd64.AppImage
+./ak-gui_2.13.0-beta.2_linux_amd64.AppImage
 ```
 
 ```powershell
diff --git a/content/docs/beta/desktop-app/troubleshooting.vi.mdx b/content/docs/beta/desktop-app/troubleshooting.vi.mdx
index f008a57..9c7a1bf 100644
--- a/content/docs/beta/desktop-app/troubleshooting.vi.mdx
+++ b/content/docs/beta/desktop-app/troubleshooting.vi.mdx
@@ -3,7 +3,7 @@ title: Xử lý sự cố ứng dụng Desktop
 description: Chẩn đoán lỗi khởi chạy đầu, license, dữ liệu cục bộ, nền tảng và staged update mà không xoá trạng thái người dùng.
 ---
 
-Bắt đầu từ triệu chứng bên dưới. Giữ artifact v2.12.1-beta.8 đã xác minh và bảo toàn
+Bắt đầu từ triệu chứng bên dưới. Giữ artifact v2.13.0-beta.2 đã xác minh và bảo toàn
 trạng thái AgentKit trong khi chẩn đoán.
 
 ## Cửa sổ không mở
@@ -11,9 +11,9 @@ trạng thái AgentKit trong khi chẩn đoán.
 | Triệu chứng | Ý nghĩa | Bước an toàn tiếp theo |
 | --- | --- | --- |
 | `ak gui` in gợi ý tải Desktop và thoát `1` | Bạn đã chạy artifact CLI tiêu chuẩn không có Wails | Chạy trực tiếp artifact Desktop đã xác minh |
-| Linux ARM64 hoặc Windows ARM64 in cảnh báo khả dụng rồi thoát `0` | v2.12.1-beta.8 không có gói Desktop cho kiến trúc đó | Dùng CLI hoặc browser dashboard; đừng thay bằng binary x64 |
+| Linux ARM64 hoặc Windows ARM64 in cảnh báo khả dụng rồi thoát `0` | v2.13.0-beta.2 không có gói Desktop cho kiến trúc đó | Dùng CLI hoặc browser dashboard; đừng thay bằng binary x64 |
 | macOS chặn ứng dụng | Gatekeeper chưa cho phép bundle này | Kiểm tra lại SHA-256, rồi dùng quy trình allow-once trong [Cài đặt](./installation) |
-| Linux báo permission denied | AppImage chưa có quyền executable | Chạy `chmod +x ak-gui_2.12.1-beta.8_linux_amd64.AppImage` bằng user của bạn |
+| Linux báo permission denied | AppImage chưa có quyền executable | Chạy `chmod +x ak-gui_2.13.0-beta.2_linux_amd64.AppImage` bằng user của bạn |
 | Linux báo lỗi FUSE | Host thiếu lớp tương thích AppImage FUSE | Cài gói tương thích của distribution; đừng chạy bằng root |
 | Windows hiển thị SmartScreen | Windows đang đánh giá executable đã tải | Kiểm tra lại SHA-256 trước khi chọn **More info → Run anyway** cho artifact phát hành khớp |
 | Windows báo không tìm thấy Microsoft Edge WebView2 Runtime | Startup preflight không tìm thấy WebView2 runtime bắt buộc | Cài hoặc repair WebView2 từ [trang download chính thức của Microsoft](https://developer.microsoft.com/microsoft-edge/webview2/consumer/), rồi thử lại |
@@ -55,7 +55,7 @@ của `$AGENTKIT_HOME/auth/session.json`. Đừng dán tệp đó vào yêu cầ
 - Xoá project trong Desktop chỉ xoá mục registry AgentKit. Thao tác này không
   xoá thư mục project.
 
-Desktop v2.12.1-beta.8 không khởi động skill của Kit hay agent run. Hãy chạy skill
+Desktop v2.13.0-beta.2 không khởi động skill của Kit hay agent run. Hãy chạy skill
 trong coding assistant trước khi chờ Activity hoặc bằng chứng session mới.
 
 ## Một port đang bận
@@ -74,7 +74,7 @@ không dừng dashboard hoặc API server được khởi động riêng.
 
 ## Update không hoàn tất
 
-- Windows x64 từ chối paired Desktop apply trong v2.12.1-beta.8. Hãy tải và xác minh
+- Windows x64 từ chối paired Desktop apply trong v2.13.0-beta.2. Hãy tải và xác minh
   zip Desktop thay thế theo cách thủ công.
 - Trên macOS hoặc Linux x64, hãy giữ CLI tiêu chuẩn khớp version đã cài và bảo
   toàn `$AGENTKIT_HOME/updater/pending-binary-update.json` cùng thư mục staging
@@ -97,7 +97,7 @@ Thoát Desktop, mở terminal và khởi chạy đúng executable đã cài:
 ```
 
 ```bash
-./ak-gui_2.12.1-beta.8_linux_amd64.AppImage
+./ak-gui_2.13.0-beta.2_linux_amd64.AppImage
 ```
 
 ```powershell
diff --git a/content/docs/beta/desktop-app/updating.en.mdx b/content/docs/beta/desktop-app/updating.en.mdx
index d5a2652..43736b4 100644
--- a/content/docs/beta/desktop-app/updating.en.mdx
+++ b/content/docs/beta/desktop-app/updating.en.mdx
@@ -3,7 +3,7 @@ title: Update the Desktop app
 description: Use AgentKit's signed paired-update flow, restart safely, and recover without bypassing verification.
 ---
 
-Desktop auto-update is opt-in in v2.12.1-beta.8. Before enabling it, install the
+Desktop auto-update is opt-in in v2.13.0-beta.2. Before enabling it, install the
 standard `ak` CLI separately and keep the CLI and Desktop on the same release.
 
 ```bash
@@ -26,12 +26,12 @@ manager detection still applies to the resolved candidate.
 
 ## Know the platform boundary
 
-| Desktop platform | v2.12.1-beta.8 paired update |
+| Desktop platform | v2.13.0-beta.2 paired update |
 | --- | --- |
 | macOS Intel and Apple silicon | Supported for a matching CLI and Desktop transaction |
 | Linux x64 | Supported for a matching CLI and Desktop transaction |
 | Windows x64 | Paired Desktop apply is rejected; download and verify the new Desktop zip manually |
-| Linux ARM64 and Windows ARM64 | No v2.12.1-beta.8 Desktop package to update |
+| Linux ARM64 and Windows ARM64 | No v2.13.0-beta.2 Desktop package to update |
 
 Windows can use the CLI's trusted helper for a CLI-only update, but that does
 not update the extracted Desktop app.
diff --git a/content/docs/beta/desktop-app/updating.vi.mdx b/content/docs/beta/desktop-app/updating.vi.mdx
index 36f7ccb..408388d 100644
--- a/content/docs/beta/desktop-app/updating.vi.mdx
+++ b/content/docs/beta/desktop-app/updating.vi.mdx
@@ -3,7 +3,7 @@ title: Cập nhật ứng dụng Desktop
 description: Dùng quy trình paired update có chữ ký của AgentKit, restart an toàn và khôi phục mà không bỏ qua xác minh.
 ---
 
-Desktop auto-update là opt-in trong v2.12.1-beta.8. Trước khi bật, hãy cài CLI `ak` tiêu
+Desktop auto-update là opt-in trong v2.13.0-beta.2. Trước khi bật, hãy cài CLI `ak` tiêu
 chuẩn riêng và giữ CLI cùng Desktop ở một bản phát hành.
 
 ```bash
@@ -26,12 +26,12 @@ diện package manager trên candidate đã resolve.
 
 ## Biết ranh giới nền tảng
 
-| Nền tảng Desktop | Paired update trong v2.12.1-beta.8 |
+| Nền tảng Desktop | Paired update trong v2.13.0-beta.2 |
 | --- | --- |
 | macOS Intel và Apple silicon | Hỗ trợ transaction CLI và Desktop khớp nhau |
 | Linux x64 | Hỗ trợ transaction CLI và Desktop khớp nhau |
 | Windows x64 | Paired Desktop apply bị từ chối; hãy tải và xác minh zip Desktop mới theo cách thủ công |
-| Linux ARM64 và Windows ARM64 | Không có gói Desktop v2.12.1-beta.8 để update |
+| Linux ARM64 và Windows ARM64 | Không có gói Desktop v2.13.0-beta.2 để update |
 
 Windows có thể dùng trusted helper của CLI cho update chỉ CLI, nhưng thao tác đó
 không update ứng dụng Desktop đã giải nén.
diff --git a/content/docs/beta/reference/cli/config/prefs/index.en.mdx b/content/docs/beta/reference/cli/config/prefs/index.en.mdx
index d1e684d..19c65ed 100644
--- a/content/docs/beta/reference/cli/config/prefs/index.en.mdx
+++ b/content/docs/beta/reference/cli/config/prefs/index.en.mdx
@@ -23,8 +23,8 @@ into a preference payload.
 | --- | --- | --- |
 | See effective authored values | `ak config prefs resolve` | Reads user and current-project config, then deep-merges project over user. |
 | Check config syntax and schema | `ak config prefs validate` | Reads existing user/project files, or one explicit `--file`; writes nothing. |
-| Pin one Hook toggle or the automatic journal step | `ak config prefs set <key> <true\|false>` | Backs up an existing selected config, then atomically writes one `hooks.<name>` boolean or the exact `journal.auto` leaf. |
-| Stop pinning one Hook toggle or `journal.auto` | `ak config prefs unset <key>` | Removes one selected-scope `hooks.<name>` or `journal.auto` leaf when present, with a backup before rewrite. |
+| Pin one Hook toggle, the automatic journal step, or the default worktree root | `ak config prefs set <key> <value>` | Backs up an existing selected config, then atomically writes one `hooks.<name>` boolean, the exact `journal.auto` leaf, or the exact `worktree.root` path. |
+| Stop pinning one Hook toggle, `journal.auto`, or `worktree.root` | `ak config prefs unset <key>` | Removes one selected-scope `hooks.<name>`, `journal.auto`, or `worktree.root` leaf when present, with a backup before rewrite. |
 
 These commands do not edit provider keys, API tokens, update settings, or other
 setup-owned sections.
diff --git a/content/docs/beta/reference/cli/config/prefs/index.vi.mdx b/content/docs/beta/reference/cli/config/prefs/index.vi.mdx
index d6e2887..d4176d6 100644
--- a/content/docs/beta/reference/cli/config/prefs/index.vi.mdx
+++ b/content/docs/beta/reference/cli/config/prefs/index.vi.mdx
@@ -1,6 +1,6 @@
 ---
 title: ak config prefs
-description: Chọn thao tác tra cứu, validate hoặc thay đổi Hook toggle hay journal.auto có giới hạn, đồng thời giữ đúng scope, default, secret và ranh giới backup.
+description: Chọn thao tác tra cứu, validate hoặc thay đổi Hook toggle, journal.auto, hay worktree.root có giới hạn, đồng thời giữ đúng scope, default, secret và ranh giới backup.
 ---
 
 Dùng `ak config prefs` để tìm các lệnh resolve hoặc thay đổi giá trị preference
@@ -23,8 +23,8 @@ nhóm thành preference payload.
 | --- | --- | --- |
 | Xem giá trị đã ghi có hiệu lực | `ak config prefs resolve` | Đọc config user và project hiện tại, rồi deep-merge project lên user. |
 | Kiểm tra cú pháp và schema config | `ak config prefs validate` | Đọc tệp user/project hiện có hoặc một `--file` rõ ràng; không ghi gì. |
-| Ghim một Hook toggle hoặc bước journal tự động | `ak config prefs set <key> <true\|false>` | Backup config đã chọn nếu tồn tại, rồi ghi atomically một boolean `hooks.<name>` hoặc đúng leaf `journal.auto`. |
-| Ngừng ghim một Hook toggle hoặc `journal.auto` | `ak config prefs unset <key>` | Xoá một leaf `hooks.<name>` hoặc `journal.auto` trong scope đã chọn khi tồn tại, có backup trước khi ghi lại. |
+| Ghim một Hook toggle, bước journal tự động, hoặc worktree root mặc định | `ak config prefs set <key> <value>` | Backup config đã chọn nếu tồn tại, rồi ghi atomically một boolean `hooks.<name>`, đúng leaf `journal.auto`, hoặc đúng path `worktree.root`. |
+| Ngừng ghim một Hook toggle, `journal.auto`, hoặc `worktree.root` | `ak config prefs unset <key>` | Xoá một leaf `hooks.<name>`, `journal.auto`, hoặc `worktree.root` trong scope đã chọn khi tồn tại, có backup trước khi ghi lại. |
 
 Các lệnh này không chỉnh provider key, API token, update setting hay section
 khác do setup quản lý.
diff --git a/content/docs/beta/reference/cli/config/prefs/set.en.mdx b/content/docs/beta/reference/cli/config/prefs/set.en.mdx
index a96e5b1..d462191 100644
--- a/content/docs/beta/reference/cli/config/prefs/set.en.mdx
+++ b/content/docs/beta/reference/cli/config/prefs/set.en.mdx
@@ -1,14 +1,15 @@
 ---
 title: ak config prefs set
-description: Set one bounded Hook boolean or the journal.auto preference with exact scope, schema, backup, atomic-write, output, and manual-recovery behavior.
+description: Set one bounded Hook boolean, the journal.auto preference, or the worktree.root default with exact scope, schema, backup, atomic-write, output, and manual-recovery behavior.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-Use `ak config prefs set` to pin one Hook soft-preference or the `journal.auto`
-preference to `true` or `false` in the user config or the current project's
-config. The command changes the selected file immediately; it does not
-unregister or install a Hook and does not stop explicit `/ak:journal`.
+Use `ak config prefs set` to pin one Hook soft-preference, the `journal.auto`
+preference, or the `worktree.root` default location in the user config or the
+current project's config. The command changes the selected file immediately;
+it does not unregister or install a Hook and does not stop explicit
+`/ak:journal`.
 
 ## Usage
 
@@ -30,24 +31,31 @@ does not prompt, so `--yes` and `--no-interactive` do not change it. There is no
 
 ## Key and value validation
 
-Two key shapes are accepted:
+Three key shapes are accepted:
 
 - `hooks.<name>` — `<name>` must be a lowercase kebab-case Hook script basename
   matching `^[a-z0-9]+(?:-[a-z0-9]+)*$` and cannot contain another dot.
 - `journal.auto` — the exact literal, no nested keys under `journal`.
+- `worktree.root` — the exact literal, no nested keys under `worktree`.
 
-The value must be the exact lowercase literal `true` or `false`.
+For `hooks.<name>` and `journal.auto` the value must be the exact lowercase
+literal `true` or `false`. For `worktree.root` the value is a filesystem path;
+project scope only accepts a relative path (resolved against the project root),
+while user scope accepts either a relative path (also resolved against the
+project root) or an absolute path.
 
 ```bash
 ak config prefs set hooks.simplify-gate false
 ak config prefs set hooks.simplify-gate true --scope project
 ak config prefs set journal.auto false
+ak config prefs set worktree.root /Volumes/Portable/agentkit-worktrees
+ak config prefs set worktree.root ../my-app-worktrees --scope project
 ```
 
 Keys such as `keys.anthropic`, `api.token`, `telemetry.enabled`,
-`hooks.Bad-Name`, `hooks.a.b`, and any `journal.<other>` are rejected before a
-preference write. This allowlist prevents the command from being used as a
-general secret or config editor.
+`hooks.Bad-Name`, `hooks.a.b`, any `journal.<other>`, and any
+`worktree.<other>` are rejected before a preference write. This allowlist
+prevents the command from being used as a general secret or config editor.
 
 For a Hook toggle, `false` lets a Hook that honors this preference exit early
 on its next run; `true` records the opposite preference. Harness registration
@@ -58,6 +66,15 @@ end of `plan`, `cook`, `fix`, `ship`, and `bootstrap` workflows without
 unregistering hooks or blocking an explicit `/ak:journal`. `true` records the
 opposite preference. The built-in default is `true`.
 
+For `worktree.root`, the value picks the default location that `ak:worktree`
+uses when `--worktree-root` is not passed. Project scope refuses an absolute
+value with a warning and falls through to the next scope, because a committed
+project config can arrive from an untrusted clone. User scope accepts an
+absolute path, which is the right choice for a portable-drive or
+external-volume worktree layout. The built-in default is unset, so
+`ak:worktree` continues to fall back to the `WORKTREE_ROOT` environment
+variable and its built-in location chain.
+
 ## Scope and filesystem effects
 
 | Scope | Target | Additional effect |
@@ -65,10 +82,10 @@ opposite preference. The built-in default is `true`.
 | `user` | `$AGENTKIT_HOME/config.yaml`, normally `~/.agentkit/config.yaml` | A missing file is created. |
 | `project` | `<cwd>/.agentkit/config.yaml` | If absent, AgentKit scaffolds the project template and `.agentkit/.gitignore` first. The project config is intended to be committed, so do not place credentials in it. |
 
-The writer changes only the selected `hooks.<name>` or `journal.auto` leaf. It
-preserves other sections, unmodelled YAML, comments, key order, and the schema
-editor directive. If `hooks` or `journal` already exists but is not a mapping,
-the write is refused.
+The writer changes only the selected `hooks.<name>`, `journal.auto`, or
+`worktree.root` leaf. It preserves other sections, unmodelled YAML, comments,
+key order, and the schema editor directive. If `hooks`, `journal`, or
+`worktree` already exists but is not a mapping, the write is refused.
 
 Before writing, AgentKit validates the whole candidate against the schema
 embedded in this binary. Existing legacy spellings can produce warnings but do
diff --git a/content/docs/beta/reference/cli/config/prefs/set.vi.mdx b/content/docs/beta/reference/cli/config/prefs/set.vi.mdx
index 59b5bcc..0ae854a 100644
--- a/content/docs/beta/reference/cli/config/prefs/set.vi.mdx
+++ b/content/docs/beta/reference/cli/config/prefs/set.vi.mdx
@@ -1,14 +1,14 @@
 ---
 title: ak config prefs set
-description: Đặt một boolean Hook có giới hạn hoặc preference journal.auto với hành vi chính xác về scope, schema, backup, atomic write, đầu ra và khôi phục thủ công.
+description: Đặt một boolean Hook có giới hạn, preference journal.auto, hoặc mặc định worktree.root với hành vi chính xác về scope, schema, backup, atomic write, đầu ra và khôi phục thủ công.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-Dùng `ak config prefs set` để ghim một soft-preference của Hook hoặc
-preference `journal.auto` thành `true` hoặc `false` trong config user hay
-config của project hiện tại. Lệnh thay đổi tệp đã chọn ngay; lệnh không
-unregister hay cài Hook và không chặn `/ak:journal` gọi tường minh.
+Dùng `ak config prefs set` để ghim một soft-preference của Hook, preference
+`journal.auto`, hoặc mặc định `worktree.root` trong config user hay config
+của project hiện tại. Lệnh thay đổi tệp đã chọn ngay; lệnh không unregister
+hay cài Hook và không chặn `/ak:journal` gọi tường minh.
 
 ## Cách dùng
 
@@ -30,23 +30,31 @@ không có `--dry-run`, `--force` hay preview mode.
 
 ## Validate key và value
 
-Hai dạng key được chấp nhận:
+Ba dạng key được chấp nhận:
 
 - `hooks.<name>` — `<name>` phải là basename Hook script dạng kebab-case chữ
   thường, khớp `^[a-z0-9]+(?:-[a-z0-9]+)*$` và không được chứa thêm dấu chấm.
 - `journal.auto` — literal chính xác, không có key con nào dưới `journal`.
+- `worktree.root` — literal chính xác, không có key con nào dưới `worktree`.
 
-Value phải là literal chữ thường chính xác `true` hoặc `false`.
+Với `hooks.<name>` và `journal.auto`, value phải là literal chữ thường chính
+xác `true` hoặc `false`. Với `worktree.root`, value là một filesystem path;
+project scope chỉ chấp nhận relative path (resolve theo project root), còn
+user scope chấp nhận cả relative path (cũng resolve theo project root) lẫn
+absolute path.
 
 ```bash
 ak config prefs set hooks.simplify-gate false
 ak config prefs set hooks.simplify-gate true --scope project
 ak config prefs set journal.auto false
+ak config prefs set worktree.root /Volumes/Portable/agentkit-worktrees
+ak config prefs set worktree.root ../my-app-worktrees --scope project
 ```
 
 Key như `keys.anthropic`, `api.token`, `telemetry.enabled`, `hooks.Bad-Name`,
-`hooks.a.b`, và mọi `journal.<other>` bị từ chối trước khi ghi preference.
-Allowlist này ngăn lệnh trở thành editor config hoặc secret tổng quát.
+`hooks.a.b`, mọi `journal.<other>`, và mọi `worktree.<other>` bị từ chối
+trước khi ghi preference. Allowlist này ngăn lệnh trở thành editor config
+hoặc secret tổng quát.
 
 Với Hook toggle, `false` cho phép Hook có đọc preference này exit sớm ở lần
 chạy tiếp theo; `true` ghi preference ngược lại. Harness registration không
@@ -57,6 +65,14 @@ Với `journal.auto`, `false` chặn bước `/ak:journal` tự động ở cu
 chặn `/ak:journal` gọi tường minh. `true` ghi preference ngược lại. Default
 tích hợp là `true`.
 
+Với `worktree.root`, value chọn vị trí mặc định mà `ak:worktree` dùng khi
+không truyền `--worktree-root`. Project scope từ chối value là absolute path
+với warning và fall through xuống scope kế tiếp, vì project config được
+commit có thể đến từ clone không đáng tin. User scope chấp nhận absolute
+path, phù hợp cho layout worktree trên ổ portable hoặc volume ngoài. Default
+tích hợp là unset, nên `ak:worktree` tiếp tục fallback về biến môi trường
+`WORKTREE_ROOT` và chuỗi vị trí tích hợp sẵn.
+
 ## Scope và tác động filesystem
 
 | Scope | Target | Tác động thêm |
@@ -64,10 +80,10 @@ tích hợp là `true`.
 | `user` | `$AGENTKIT_HOME/config.yaml`, thường là `~/.agentkit/config.yaml` | Tệp thiếu sẽ được tạo. |
 | `project` | `<cwd>/.agentkit/config.yaml` | Nếu thiếu, AgentKit scaffold project template và `.agentkit/.gitignore` trước. Project config được thiết kế để commit, vì vậy không đặt credential vào đó. |
 
-Writer chỉ thay leaf `hooks.<name>` hoặc `journal.auto` đã chọn. Các section
-khác, YAML chưa được model, comment, thứ tự key và schema editor directive
-được giữ lại. Nếu `hooks` hoặc `journal` đã tồn tại nhưng không phải mapping,
-lệnh từ chối ghi.
+Writer chỉ thay leaf `hooks.<name>`, `journal.auto`, hoặc `worktree.root` đã
+chọn. Các section khác, YAML chưa được model, comment, thứ tự key và schema
+editor directive được giữ lại. Nếu `hooks`, `journal`, hoặc `worktree` đã
+tồn tại nhưng không phải mapping, lệnh từ chối ghi.
 
 Trước khi ghi, AgentKit validate toàn bộ candidate bằng schema nhúng trong
 binary. Cách viết cũ có thể tạo warning nhưng không tự làm validation thất bại;
diff --git a/content/docs/beta/reference/cli/config/prefs/unset.en.mdx b/content/docs/beta/reference/cli/config/prefs/unset.en.mdx
index b67d3f2..417a0c2 100644
--- a/content/docs/beta/reference/cli/config/prefs/unset.en.mdx
+++ b/content/docs/beta/reference/cli/config/prefs/unset.en.mdx
@@ -1,14 +1,16 @@
 ---
 title: ak config prefs unset
-description: Remove one scoped hook or journal.auto preference, understand fallback behavior, and recover from the reported config backup.
+description: Remove one scoped hook, journal.auto, or worktree.root preference, understand fallback behavior, and recover from the reported config backup.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-Use `ak config prefs unset` to remove an explicit `hooks.<name>` toggle or the
-`journal.auto` leaf from one config scope. The preference then inherits the
-value from the other scope when one exists, or uses its built-in default
-(`journal.auto` defaults to `true`).
+Use `ak config prefs unset` to remove an explicit `hooks.<name>` toggle, the
+`journal.auto` leaf, or the `worktree.root` leaf from one config scope. The
+preference then inherits the value from the other scope when one exists, or
+uses its built-in default (`journal.auto` defaults to `true`; `worktree.root`
+defaults to unset, so `ak:worktree` falls back to `WORKTREE_ROOT` and the
+built-in location chain).
 
 ## Usage
 
@@ -16,10 +18,10 @@ value from the other scope when one exists, or uses its built-in default
 ak config prefs unset <key>
 ```
 
-The command requires exactly one positional argument. The key must be either
-`hooks.<name>`, where `<name>` is a lowercase kebab-case hook script name, or
-the exact literal `journal.auto`. It cannot remove credentials or values from
-other config sections.
+The command requires exactly one positional argument. The key must be one of
+`hooks.<name>` (where `<name>` is a lowercase kebab-case hook script name),
+the exact literal `journal.auto`, or the exact literal `worktree.root`. It
+cannot remove credentials or values from other config sections.
 
 ## Command flag
 
@@ -42,6 +44,7 @@ Unset a user preference:
 ```bash
 ak config prefs unset hooks.simplify-gate
 ak config prefs unset journal.auto
+ak config prefs unset worktree.root
 ```
 
 Unset only the current project's preference:
@@ -49,6 +52,7 @@ Unset only the current project's preference:
 ```bash
 ak config prefs unset hooks.simplify-gate --scope project
 ak config prefs unset journal.auto --scope project
+ak config prefs unset worktree.root --scope project
 ```
 
 The command does not search parent directories for a project config. Run it
@@ -57,10 +61,10 @@ from the project directory whose `.agentkit/config.yaml` you intend to edit.
 ## Files, backups, and schema boundary
 
 When the selected key exists, AgentKit backs up the previous config under the
-AgentKit home, removes only that leaf, prunes an empty `hooks` or `journal`
-section, and atomically rewrites the config. The success output reports the
-backup path. Other keys, comments, ordering, and the editor directive are
-preserved.
+AgentKit home, removes only that leaf, prunes an empty `hooks`, `journal`, or
+`worktree` section, and atomically rewrites the config. The success output
+reports the backup path. Other keys, comments, ordering, and the editor
+directive are preserved.
 
 If the key or config file is already absent, the command succeeds as a no-op:
 it does not create, rewrite, or back up a file. There is no confirmation prompt,
diff --git a/content/docs/beta/reference/cli/config/prefs/unset.vi.mdx b/content/docs/beta/reference/cli/config/prefs/unset.vi.mdx
index 8549cea..a15644f 100644
--- a/content/docs/beta/reference/cli/config/prefs/unset.vi.mdx
+++ b/content/docs/beta/reference/cli/config/prefs/unset.vi.mdx
@@ -1,14 +1,16 @@
 ---
 title: ak config prefs unset
-description: Xoá một tuỳ chọn hook hoặc journal.auto theo scope, hiểu cơ chế fallback và khôi phục từ bản sao lưu config được báo cáo.
+description: Xoá một tuỳ chọn hook, journal.auto, hoặc worktree.root theo scope, hiểu cơ chế fallback và khôi phục từ bản sao lưu config được báo cáo.
 ---
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-Dùng `ak config prefs unset` để xoá một toggle `hooks.<name>` đã đặt rõ ràng
-hoặc leaf `journal.auto` khỏi một scope config. Sau đó preference kế thừa giá
-trị từ scope còn lại nếu có, hoặc dùng giá trị mặc định tích hợp (`journal.auto`
-mặc định là `true`).
+Dùng `ak config prefs unset` để xoá một toggle `hooks.<name>` đã đặt rõ ràng,
+leaf `journal.auto`, hoặc leaf `worktree.root` khỏi một scope config. Sau đó
+preference kế thừa giá trị từ scope còn lại nếu có, hoặc dùng giá trị mặc
+định tích hợp (`journal.auto` mặc định là `true`; `worktree.root` mặc định
+là unset, nên `ak:worktree` fallback về `WORKTREE_ROOT` và chuỗi vị trí tích
+hợp sẵn).
 
 ## Cách dùng
 
@@ -16,9 +18,10 @@ mặc định là `true`).
 ak config prefs unset <key>
 ```
 
-Lệnh yêu cầu đúng một argument theo vị trí. Key phải là `hooks.<name>`, trong
-đó `<name>` là tên script hook chữ thường theo kebab-case, hoặc literal chính
-xác `journal.auto`. Lệnh không thể xoá credential hoặc giá trị thuộc phần
+Lệnh yêu cầu đúng một argument theo vị trí. Key phải là một trong
+`hooks.<name>` (trong đó `<name>` là tên script hook chữ thường theo
+kebab-case), literal chính xác `journal.auto`, hoặc literal chính xác
+`worktree.root`. Lệnh không thể xoá credential hoặc giá trị thuộc phần
 config khác.
 
 ## Cờ của lệnh
@@ -42,6 +45,7 @@ Xoá một tuỳ chọn user:
 ```bash
 ak config prefs unset hooks.simplify-gate
 ak config prefs unset journal.auto
+ak config prefs unset worktree.root
 ```
 
 Chỉ xoá tuỳ chọn của project hiện tại:
@@ -49,6 +53,7 @@ Chỉ xoá tuỳ chọn của project hiện tại:
 ```bash
 ak config prefs unset hooks.simplify-gate --scope project
 ak config prefs unset journal.auto --scope project
+ak config prefs unset worktree.root --scope project
 ```
 
 Lệnh không tìm config project trong các thư mục cha. Hãy chạy lệnh từ thư mục
@@ -57,10 +62,10 @@ project có `.agentkit/config.yaml` mà bạn muốn chỉnh sửa.
 ## Tệp, bản sao lưu và ranh giới schema
 
 Khi key đã tồn tại trong scope được chọn, AgentKit sao lưu config trước đó bên
-dưới AgentKit home, chỉ xoá leaf tương ứng, dọn phần `hooks` hoặc `journal` nếu
-phần này trở thành rỗng rồi ghi lại config theo cách atomic. Đầu ra thành công
-báo đường dẫn bản sao lưu. Các key khác, comment, thứ tự và editor directive
-được giữ nguyên.
+dưới AgentKit home, chỉ xoá leaf tương ứng, dọn phần `hooks`, `journal`, hoặc
+`worktree` nếu phần này trở thành rỗng rồi ghi lại config theo cách atomic.
+Đầu ra thành công báo đường dẫn bản sao lưu. Các key khác, comment, thứ tự và
+editor directive được giữ nguyên.
 
 Nếu key hoặc tệp config đã không tồn tại, lệnh vẫn thành công dưới dạng no-op:
 lệnh không tạo, ghi lại hay sao lưu tệp. Lệnh không hỏi xác nhận, không đọc
diff --git a/content/docs/beta/reference/cli/index.en.mdx b/content/docs/beta/reference/cli/index.en.mdx
index 76975e5..f70beb2 100644
--- a/content/docs/beta/reference/cli/index.en.mdx
+++ b/content/docs/beta/reference/cli/index.en.mdx
@@ -26,6 +26,7 @@ Browse by outcome below, or use the CLI Reference sidebar to open any command.
 | Create or register a project | Project lifecycle commands | `ak init`, `ak new`, `ak projects` |
 | Install runtime capabilities | Kit and component commands | `ak kit`, `ak skills`, `ak agents`, `ak commands`, `ak skill` |
 | Run and inspect work | Execution and activity commands | `ak run`, `ak activity`, `ak sessions`, `ak content`, `ak data`, `ak analytics` |
+| Supervise external CLI job graphs | Orchestration commands (Darwin only) | `ak orchestrate start`, `ak orchestrate status`, `ak orchestrate resume`, `ak orchestrate stop` |
 | Plan and connect tools | Planning and integration commands | `ak plan`, `ak journal`, `ak mcp`, `ak api`, `ak watch` |
 | Diagnose and recover | Health and recovery commands | `ak doctor`, `ak audit`, `ak diagnostics`, `ak backups`, `ak recover`, `ak migrate` |
 | Update or remove installations | Maintenance commands | `ak update`, `ak self-update`, `ak versions`, `ak changelog`, `ak uninstall` |
diff --git a/content/docs/beta/reference/cli/index.vi.mdx b/content/docs/beta/reference/cli/index.vi.mdx
index 42efdc1..09f30c0 100644
--- a/content/docs/beta/reference/cli/index.vi.mdx
+++ b/content/docs/beta/reference/cli/index.vi.mdx
@@ -26,6 +26,7 @@ bất kỳ lệnh nào.
 | Tạo hoặc đăng ký project | Nhóm lệnh vòng đời project | `ak init`, `ak new`, `ak projects` |
 | Cài capability cho runtime | Nhóm lệnh Kit và component | `ak kit`, `ak skills`, `ak agents`, `ak commands`, `ak skill` |
 | Chạy và kiểm tra công việc | Nhóm lệnh thực thi và hoạt động | `ak run`, `ak activity`, `ak sessions`, `ak content`, `ak data`, `ak analytics` |
+| Giám sát job graph CLI bên ngoài | Nhóm lệnh orchestrate (chỉ Darwin) | `ak orchestrate start`, `ak orchestrate status`, `ak orchestrate resume`, `ak orchestrate stop` |
 | Lập kế hoạch và kết nối công cụ | Nhóm lệnh kế hoạch và tích hợp | `ak plan`, `ak journal`, `ak mcp`, `ak api`, `ak watch` |
 | Chẩn đoán và khôi phục | Nhóm lệnh sức khoẻ và khôi phục | `ak doctor`, `ak audit`, `ak diagnostics`, `ak backups`, `ak recover`, `ak migrate` |
 | Cập nhật hoặc gỡ cài đặt | Nhóm lệnh bảo trì | `ak update`, `ak self-update`, `ak versions`, `ak changelog`, `ak uninstall` |
diff --git a/content/docs/beta/reference/cli/meta.json b/content/docs/beta/reference/cli/meta.json
index a460382..87ec735 100644
--- a/content/docs/beta/reference/cli/meta.json
+++ b/content/docs/beta/reference/cli/meta.json
@@ -34,6 +34,7 @@
     "feedback",
     "gui",
     "mcp",
+    "orchestrate",
     "plan",
     "run",
     "skill",
diff --git a/content/docs/beta/reference/cli/meta.vi.json b/content/docs/beta/reference/cli/meta.vi.json
index 7a38732..957fb38 100644
--- a/content/docs/beta/reference/cli/meta.vi.json
+++ b/content/docs/beta/reference/cli/meta.vi.json
@@ -34,6 +34,7 @@
     "feedback",
     "gui",
     "mcp",
+    "orchestrate",
     "plan",
     "run",
     "skill",
diff --git a/content/docs/beta/reference/cli/orchestrate/index.en.mdx b/content/docs/beta/reference/cli/orchestrate/index.en.mdx
new file mode 100644
index 0000000..2799f0b
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/index.en.mdx
@@ -0,0 +1,90 @@
+---
+title: ak orchestrate
+description: Run and supervise a graph of external CLI jobs under a durable local worker with process-group ownership, persisted run state, crash-safe reconnect, and Darwin-only v1 scope.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use `ak orchestrate` to start, resume, check, and stop a graph of external CLI
+jobs under a dedicated local worker supervisor. The worker owns each job's
+process group, persists durable run state under `AGENTKIT_HOME`, and survives
+the launching client or coordinator exiting. This is the process-lifecycle
+layer that the `/ak:orchestrate` skill delegates to when supervising CLI job
+graphs.
+
+<Callout type="warning">
+  `ak orchestrate` v1 supports **Darwin only** (macOS). Every other GOOS
+  returns an explicit unsupported error with exit code `6`. Callers running
+  on Linux or Windows should fall back to a coordinator-owned subprocess and
+  accept the disclosed interruption gap.
+</Callout>
+
+## Usage
+
+```bash
+ak orchestrate
+```
+
+The bare group command prints help. Use one of the subcommands to act on a
+run.
+
+## Choose an orchestrate subcommand
+
+| Goal | Command | Effect |
+| --- | --- | --- |
+| Launch a new run from a validated job graph | `ak orchestrate start <job-graph.json>` | Validates the graph, generates a fresh opaque run ID, spawns a detached worker that owns every job's process group, blocks until the worker durably persists run state and proves readiness, then prints the run ID and initial status. |
+| Reconnect after a client or coordinator crash | `ak orchestrate resume <run-id> <job-graph.json>` | Confirms the graph's digest still matches the running record and reports its current state — never relaunches jobs or creates a second process tree. Falls back to read-only reclassification when the worker itself crashed. |
+| Report a run's current lifecycle state | `ak orchestrate status <run-id>` | Reaches the run's live worker through its verified control socket when reachable, otherwise reconciles persisted state against a fresh identity probe. Reports PID/PGID, heartbeat, last-output time, and per-job current-command labels. |
+| Cancel a run's live jobs | `ak orchestrate stop <run-id>` | Sends SIGTERM to every signal-authorized job in the verified process group, waits a bounded grace period, then SIGKILLs only a job whose group is still alive under the same verified identity. Never guesses a kill target from persisted state. |
+
+`start` always creates a new run; retrying the same graph does not reuse an
+existing run ID. Only `resume <run-id>` continues an existing run.
+
+## Filesystem and privacy boundary
+
+Each run writes state, per-job output logs, and a control socket under
+`AGENTKIT_HOME/orchestrate/runs/<run-id>/`. The worker never persists
+prompts, raw command arguments, environment values, or secrets — only the
+launch graph, per-job status, PID/PGID identity, and bounded stdout/stderr
+that the graph explicitly captures.
+
+The launch graph digest is bound to the run ID at `start`. `resume` verifies
+this digest against the graph file supplied to it; a mismatch is refused
+with exit code `1` rather than silently continuing under a different graph.
+
+## Job graph shape
+
+The graph file is a JSON document listing jobs by `id`, `command`, `args`,
+`work_dir`, `env`, and `depends_on`. Full schema and validation rules live
+under the `/ak:orchestrate` skill's job specification; this reference page
+covers only the `ak orchestrate` binary's process-lifecycle semantics.
+
+## Output modes
+
+| Mode | Trigger |
+| --- | --- |
+| `pretty` | Default on a TTY (colors, ASCII markers). |
+| `plain` | Auto when stdout is piped or `--no-interactive` is set. |
+| `json` | `--json` (single-object envelope, NDJSON-safe). |
+
+Shared flags (`--json`, `--no-interactive`, `--quiet`, `--verbose`, `--yes`)
+are described in [CLI conventions](../cli-conventions). `--json` implies
+`--no-interactive`.
+
+## Exit behavior
+
+| Exit | Meaning |
+| --- | --- |
+| `0` | The requested subcommand succeeded. |
+| `1` | Runtime error (state I/O, launch failure, signal failure, graph digest mismatch, run not found, corrupt state). |
+| `2` | Flag parsing failed. |
+| `3` | User cancelled (SIGINT, prompt-cancel). |
+| `6` | Unsupported platform (v1 requires Darwin). |
+
+## Related commands
+
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate status`](./status)
+- [`ak orchestrate stop`](./stop)
+- [CLI conventions](../cli-conventions)
diff --git a/content/docs/beta/reference/cli/orchestrate/index.vi.mdx b/content/docs/beta/reference/cli/orchestrate/index.vi.mdx
new file mode 100644
index 0000000..351dee2
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/index.vi.mdx
@@ -0,0 +1,90 @@
+---
+title: ak orchestrate
+description: Chạy và giám sát một graph các job CLI bên ngoài dưới worker cục bộ bền bỉ với process-group ownership, run state bền vững, reconnect an toàn khi crash và phạm vi v1 chỉ hỗ trợ Darwin.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Dùng `ak orchestrate` để start, resume, check và stop một graph các job CLI
+bên ngoài dưới một worker supervisor cục bộ chuyên biệt. Worker sở hữu
+process group của mỗi job, ghi run state bền vững dưới `AGENTKIT_HOME`, và
+tồn tại qua sự kiện client hay coordinator đã launch thoát. Đây là lớp
+process-lifecycle mà skill `/ak:orchestrate` uỷ quyền tới khi giám sát job
+graph CLI.
+
+<Callout type="warning">
+  `ak orchestrate` v1 chỉ hỗ trợ **Darwin** (macOS). Mọi GOOS khác trả về lỗi
+  unsupported rõ ràng với mã thoát `6`. Caller chạy trên Linux hay Windows
+  nên fallback về subprocess do coordinator sở hữu và chấp nhận khoảng
+  trống khi bị interrupt được ghi chú công khai.
+</Callout>
+
+## Cách dùng
+
+```bash
+ak orchestrate
+```
+
+Lệnh nhóm trần chỉ in help. Dùng một trong các subcommand để thao tác trên
+một run.
+
+## Chọn subcommand orchestrate
+
+| Mục tiêu | Lệnh | Tác động |
+| --- | --- | --- |
+| Launch run mới từ job graph đã validate | `ak orchestrate start <job-graph.json>` | Validate graph, sinh run ID opaque mới, spawn worker detached sở hữu process group của mọi job, block đến khi worker durably persist run state và chứng minh readiness, rồi in run ID và status ban đầu. |
+| Reconnect sau khi client hoặc coordinator crash | `ak orchestrate resume <run-id> <job-graph.json>` | Xác nhận digest của graph còn khớp với record đang chạy và báo state hiện tại — không bao giờ relaunch job hay tạo process tree thứ hai. Fallback về reclassification read-only khi chính worker đã crash. |
+| Báo state lifecycle hiện tại của run | `ak orchestrate status <run-id>` | Với qua control socket đã verify của worker live khi tới được, ngược lại reconcile persisted state so với identity probe mới. Báo PID/PGID, heartbeat, thời gian output cuối và nhãn current-command cho từng job. |
+| Cancel các job live của run | `ak orchestrate stop <run-id>` | Gửi SIGTERM tới mọi job được cấp signal trong process group đã verify, chờ khoảng grace bounded, rồi SIGKILL chỉ job có group vẫn còn sống dưới cùng identity đã verify. Không bao giờ đoán target kill từ persisted state. |
+
+`start` luôn tạo run mới; retry cùng graph không tái dùng run ID cũ. Chỉ
+`resume <run-id>` mới tiếp tục một run có sẵn.
+
+## Ranh giới filesystem và quyền riêng tư
+
+Mỗi run ghi state, log output từng job và một control socket dưới
+`AGENTKIT_HOME/orchestrate/runs/<run-id>/`. Worker không persist prompt,
+argument command thô, giá trị environment hay secret — chỉ launch graph,
+status từng job, identity PID/PGID và stdout/stderr bounded mà graph chỉ
+định capture.
+
+Digest launch graph gắn với run ID ở `start`. `resume` verify digest này so
+với file graph được cấp cho nó; mismatch bị từ chối với mã thoát `1` thay
+vì âm thầm chạy tiếp dưới graph khác.
+
+## Cấu trúc job graph
+
+File graph là JSON liệt kê các job qua `id`, `command`, `args`, `work_dir`,
+`env`, `depends_on`. Schema và luật validate đầy đủ nằm trong job
+specification của skill `/ak:orchestrate`; trang tham chiếu này chỉ bao phủ
+ngữ nghĩa process-lifecycle của binary `ak orchestrate`.
+
+## Chế độ đầu ra
+
+| Chế độ | Kích hoạt |
+| --- | --- |
+| `pretty` | Mặc định trên TTY (màu, marker ASCII). |
+| `plain` | Tự động khi stdout piped hoặc đặt `--no-interactive`. |
+| `json` | `--json` (envelope một object, an toàn NDJSON). |
+
+Các cờ dùng chung (`--json`, `--no-interactive`, `--quiet`, `--verbose`,
+`--yes`) được mô tả trong [quy ước CLI](../cli-conventions). `--json` ngầm
+định `--no-interactive`.
+
+## Kết quả và mã thoát
+
+| Mã thoát | Ý nghĩa |
+| --- | --- |
+| `0` | Subcommand được yêu cầu thành công. |
+| `1` | Lỗi runtime (I/O state, launch thất bại, signal thất bại, digest graph không khớp, run không tìm thấy, state hỏng). |
+| `2` | Parse cờ thất bại. |
+| `3` | Người dùng huỷ (SIGINT, prompt-cancel). |
+| `6` | Nền tảng không hỗ trợ (v1 yêu cầu Darwin). |
+
+## Lệnh liên quan
+
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate status`](./status)
+- [`ak orchestrate stop`](./stop)
+- [Quy ước CLI](../cli-conventions)
diff --git a/content/docs/beta/reference/cli/orchestrate/meta.json b/content/docs/beta/reference/cli/orchestrate/meta.json
new file mode 100644
index 0000000..5938246
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/meta.json
@@ -0,0 +1,10 @@
+{
+  "title": "orchestrate",
+  "pages": [
+    "index",
+    "start",
+    "resume",
+    "status",
+    "stop"
+  ]
+}
diff --git a/content/docs/beta/reference/cli/orchestrate/meta.vi.json b/content/docs/beta/reference/cli/orchestrate/meta.vi.json
new file mode 100644
index 0000000..5938246
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/meta.vi.json
@@ -0,0 +1,10 @@
+{
+  "title": "orchestrate",
+  "pages": [
+    "index",
+    "start",
+    "resume",
+    "status",
+    "stop"
+  ]
+}
diff --git a/content/docs/beta/reference/cli/orchestrate/resume.en.mdx b/content/docs/beta/reference/cli/orchestrate/resume.en.mdx
new file mode 100644
index 0000000..4b94de0
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/resume.en.mdx
@@ -0,0 +1,93 @@
+---
+title: ak orchestrate resume
+description: Reconnect to an existing orchestrated run after a client or coordinator crash, verifying the graph digest and reclassifying orphaned jobs without ever relaunching a second process tree.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use `ak orchestrate resume` to reconnect to an existing run after this
+terminal, its shell, or its coordinating process was interrupted while the
+run was in flight. Resume never relaunches jobs or creates a second process
+tree; a live worker either confirms it is still supervising the recorded
+run, or the command falls back to a read-only reclassification of persisted
+state.
+
+<Callout type="info">
+  Resume is the safe reconnect after a client or coordinator crash. When the
+  worker itself crashed mid-run, an adopted job is left as `orphaned` for a
+  human (or a fresh `start`) to act on — resume never silently continues an
+  unsupervised process tree.
+</Callout>
+
+## Usage
+
+```bash
+ak orchestrate resume <run-id> <job-graph.json>
+```
+
+Supply exactly two positional arguments — the run ID printed by
+[`ak orchestrate start`](./start), and the same job graph file used at
+dispatch. The graph's digest is compared against the digest bound to the
+persisted run; a mismatch is refused with exit code `1`.
+
+## Command flags
+
+Shared flags (`--json`, `--no-interactive`, `--quiet`, `--verbose`, `--yes`)
+are described in [CLI conventions](../cli-conventions). `--json` returns a
+single-object result envelope.
+
+## Reconnect semantics
+
+| Case | Result |
+| --- | --- |
+| Live, verified worker is reachable | Resume confirms the graph digest still matches and reports current state. No processes are touched. |
+| Worker itself crashed | Read-only reclassification of the persisted record against a fresh identity probe. Jobs whose original worker died mid-run stay marked `orphaned`. |
+| Graph digest does not match the persisted record | Refused with exit code `1`. Correct the graph file or `start` a fresh run. |
+| Run ID not found | Refused with exit code `1`. |
+
+Resume never re-executes work, never redispatches a second process tree,
+and never adopts an orphan into a new supervisor without an explicit human
+step.
+
+## Filesystem effects
+
+- Read-only against a live worker.
+- Persists a reclassification of orphaned or unknown jobs when the worker
+  itself crashed.
+
+The launch graph file must be exactly the one used at `start`. The digest
+comparison is byte-stable against the persisted `launch-graph.json`, not a
+loose semantic diff.
+
+## Human and JSON output
+
+`--json` returns:
+
+```json
+{
+  "action": "resume",
+  "run_id": "<opaque>",
+  "worker_state": "live | crashed | unreachable",
+  "graph_digest_matches": true,
+  "jobs": [
+    { "id": "<job-id>", "state": "running | completed | orphaned | ..." }
+  ]
+}
+```
+
+## Exit behavior
+
+| Exit | Meaning | Safe next step |
+| --- | --- | --- |
+| `0` | Reconnected, or reclassification recorded. | Inspect per-job state; act on any `orphaned` job explicitly. |
+| `1` | Digest mismatch, run not found, or state corrupt/unsupported. | Do not force resume; investigate the persisted record or `start` a fresh run. |
+| `2` | Flag parsing failed. | Correct the flags. |
+| `3` | Interrupted. | Re-run resume with the same arguments. |
+| `6` | Platform unsupported. | Non-Darwin has no persisted worker to reconnect to. |
+
+## Related commands
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate status`](./status)
+- [`ak orchestrate stop`](./stop)
diff --git a/content/docs/beta/reference/cli/orchestrate/resume.vi.mdx b/content/docs/beta/reference/cli/orchestrate/resume.vi.mdx
new file mode 100644
index 0000000..fe0d767
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/resume.vi.mdx
@@ -0,0 +1,93 @@
+---
+title: ak orchestrate resume
+description: Reconnect tới một run orchestrate có sẵn sau khi client hay coordinator crash, verify digest graph và reclassify job orphan mà không bao giờ relaunch process tree thứ hai.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Dùng `ak orchestrate resume` để reconnect tới một run có sẵn sau khi
+terminal này, shell của nó, hay process coordinating của nó bị interrupt
+trong khi run đang in flight. Resume không bao giờ relaunch job hay tạo
+process tree thứ hai; một worker live hoặc xác nhận nó vẫn đang giám sát
+run đã ghi, hoặc lệnh fallback về reclassification read-only của persisted
+state.
+
+<Callout type="info">
+  Resume là cách reconnect an toàn sau khi client hay coordinator crash. Khi
+  chính worker crash giữa chừng, job đã adopt sẽ được để lại là `orphaned`
+  để một con người (hoặc lệnh `start` mới) xử lý — resume không bao giờ âm
+  thầm tiếp tục process tree không được giám sát.
+</Callout>
+
+## Cách dùng
+
+```bash
+ak orchestrate resume <run-id> <job-graph.json>
+```
+
+Cung cấp đúng hai argument theo vị trí — run ID do
+[`ak orchestrate start`](./start) in, và cùng file job graph đã dùng lúc
+dispatch. Digest của graph được so với digest gắn với run đã persist;
+mismatch bị từ chối với mã thoát `1`.
+
+## Cờ của lệnh
+
+Các cờ dùng chung (`--json`, `--no-interactive`, `--quiet`, `--verbose`,
+`--yes`) được mô tả trong [quy ước CLI](../cli-conventions). `--json` trả
+về envelope kết quả một object.
+
+## Ngữ nghĩa reconnect
+
+| Trường hợp | Kết quả |
+| --- | --- |
+| Worker live, đã verify, tới được | Resume xác nhận digest graph vẫn khớp và báo state hiện tại. Không đụng vào process nào. |
+| Chính worker đã crash | Reclassification read-only persisted record so với identity probe mới. Job có worker gốc chết giữa chừng được đánh dấu `orphaned`. |
+| Digest graph không khớp record persisted | Từ chối với mã thoát `1`. Sửa file graph hoặc `start` một run mới. |
+| Run ID không tìm thấy | Từ chối với mã thoát `1`. |
+
+Resume không bao giờ chạy lại công việc, không bao giờ redispatch process
+tree thứ hai, và không bao giờ adopt orphan vào supervisor mới mà không
+có bước con người rõ ràng.
+
+## Tác động filesystem
+
+- Read-only đối với worker live.
+- Persist một reclassification job orphan hay unknown khi chính worker
+  đã crash.
+
+File launch graph phải chính xác là file đã dùng ở `start`. So digest là
+byte-stable so với `launch-graph.json` đã persist, không phải diff ngữ
+nghĩa lỏng.
+
+## Đầu ra dành cho người dùng và JSON
+
+`--json` trả về:
+
+```json
+{
+  "action": "resume",
+  "run_id": "<opaque>",
+  "worker_state": "live | crashed | unreachable",
+  "graph_digest_matches": true,
+  "jobs": [
+    { "id": "<job-id>", "state": "running | completed | orphaned | ..." }
+  ]
+}
+```
+
+## Kết quả và mã thoát
+
+| Mã thoát | Ý nghĩa | Bước tiếp theo an toàn |
+| --- | --- | --- |
+| `0` | Đã reconnect hoặc reclassification được ghi. | Kiểm tra state từng job; hành động rõ ràng với bất kỳ job `orphaned` nào. |
+| `1` | Digest không khớp, run không tìm thấy, hoặc state hỏng/không hỗ trợ. | Không force resume; điều tra record persisted hoặc `start` một run mới. |
+| `2` | Parse cờ thất bại. | Sửa các cờ. |
+| `3` | Bị interrupt. | Chạy lại resume với cùng argument. |
+| `6` | Nền tảng không hỗ trợ. | Ngoài Darwin không có worker persisted để reconnect. |
+
+## Lệnh liên quan
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate status`](./status)
+- [`ak orchestrate stop`](./stop)
diff --git a/content/docs/beta/reference/cli/orchestrate/start.en.mdx b/content/docs/beta/reference/cli/orchestrate/start.en.mdx
new file mode 100644
index 0000000..c255864
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/start.en.mdx
@@ -0,0 +1,103 @@
+---
+title: ak orchestrate start
+description: Launch a new orchestrated run from a validated job graph file with fresh run ID, detached worker, process-group ownership, and durable readiness proof.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use `ak orchestrate start` to validate a job graph file, generate a fresh
+opaque run ID, and spawn a detached worker that owns every job's process
+group for that run. The command blocks until the worker durably persists
+run state and proves readiness, then prints the run ID and initial status.
+
+`start` always creates a new run; retrying the same graph does not reuse an
+existing run ID. Only [`ak orchestrate resume`](./resume) continues an
+existing run.
+
+## Usage
+
+```bash
+ak orchestrate start <job-graph.json>
+```
+
+Supply exactly one positional argument — the path to a JSON file describing
+the job graph. The file is validated before the worker is spawned; an
+invalid graph exits with code `1` and no run state is written.
+
+## Command flags
+
+Shared flags (`--json`, `--no-interactive`, `--quiet`, `--verbose`, `--yes`)
+are described in [CLI conventions](../cli-conventions). `--json` implies
+`--no-interactive` and returns a single-object envelope suitable for
+scripted `run-id` extraction.
+
+## Job graph validation
+
+The graph file must supply, for each job:
+
+- `id` — opaque identifier unique within the graph.
+- `command` — the executable to run.
+- `args` — an argument array.
+- `work_dir` — the launch working directory.
+- `env` — an environment mapping.
+- `depends_on` — the ids of jobs that must complete first.
+
+Validation is schema-strict. A malformed field, cycle in `depends_on`, or
+unknown job id rejects the graph before the worker is spawned.
+
+## Filesystem effects
+
+On successful launch, the worker writes:
+
+- `AGENTKIT_HOME/orchestrate/runs/<run-id>/state.json` — durable run state.
+- `AGENTKIT_HOME/orchestrate/runs/<run-id>/jobs/<job-id>/stdout.log` and
+  `stderr.log` — bounded per-job output.
+- `AGENTKIT_HOME/orchestrate/runs/<run-id>/launch-graph.json` — the exact
+  graph digest bound to this run.
+- A control socket used by [`ak orchestrate status`](./status),
+  [`ak orchestrate resume`](./resume), and [`ak orchestrate stop`](./stop).
+
+The worker never persists prompts, raw argv, environment values, or secrets
+outside what the graph explicitly captures.
+
+## Human and JSON output
+
+Human success prints the run ID and per-job initial status. `--json`
+returns:
+
+```json
+{
+  "action": "start",
+  "run_id": "<opaque>",
+  "graph_digest": "sha256:<hex>",
+  "jobs": [
+    { "id": "<job-id>", "state": "queued" }
+  ]
+}
+```
+
+## Exit behavior
+
+| Exit | Meaning | Safe next step |
+| --- | --- | --- |
+| `0` | The worker reached readiness and persisted run state. | Poll with `ak orchestrate status <run-id>`. |
+| `1` | Job graph invalid, or the worker failed to reach readiness. | Correct the graph or inspect the reported reason; no run state was left behind on validation failure. |
+| `2` | Flag parsing failed. | Correct the flags. |
+| `3` | Interrupted before readiness. | Inspect `AGENTKIT_HOME/orchestrate/runs/` for a partial run; re-run when ready. |
+| `6` | Platform unsupported (v1 requires Darwin). | Use a coordinator-owned subprocess on non-Darwin platforms. |
+
+## Verify the launch
+
+```bash
+ak orchestrate status <run-id>
+```
+
+Reads the live worker's control socket to confirm the process group is
+alive under the same verified identity that `start` recorded.
+
+## Related commands
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate status`](./status)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate stop`](./stop)
diff --git a/content/docs/beta/reference/cli/orchestrate/start.vi.mdx b/content/docs/beta/reference/cli/orchestrate/start.vi.mdx
new file mode 100644
index 0000000..0df7a48
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/start.vi.mdx
@@ -0,0 +1,103 @@
+---
+title: ak orchestrate start
+description: Launch một run mới đã được orchestrate từ file job graph đã validate với run ID mới, worker detached, sở hữu process group và chứng minh readiness bền vững.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Dùng `ak orchestrate start` để validate file job graph, sinh run ID opaque
+mới, và spawn một worker detached sở hữu process group của mọi job trong
+run đó. Lệnh block đến khi worker durably persist run state và chứng minh
+readiness, rồi in run ID và status ban đầu.
+
+`start` luôn tạo run mới; retry cùng graph không tái dùng run ID cũ. Chỉ
+[`ak orchestrate resume`](./resume) mới tiếp tục một run có sẵn.
+
+## Cách dùng
+
+```bash
+ak orchestrate start <job-graph.json>
+```
+
+Cung cấp đúng một argument theo vị trí — path tới file JSON mô tả job
+graph. File được validate trước khi worker được spawn; graph không hợp lệ
+thoát với mã `1` và không có run state nào được ghi.
+
+## Cờ của lệnh
+
+Các cờ dùng chung (`--json`, `--no-interactive`, `--quiet`, `--verbose`,
+`--yes`) được mô tả trong [quy ước CLI](../cli-conventions). `--json` ngầm
+định `--no-interactive` và trả về envelope một object phù hợp để script
+trích xuất `run-id`.
+
+## Validate job graph
+
+File graph phải cung cấp, cho mỗi job:
+
+- `id` — định danh opaque duy nhất trong graph.
+- `command` — executable để chạy.
+- `args` — array argument.
+- `work_dir` — working directory để launch.
+- `env` — mapping environment.
+- `depends_on` — id các job phải hoàn tất trước.
+
+Validate là schema-strict. Field sai dạng, chu trình trong `depends_on`,
+hoặc job id không xác định sẽ từ chối graph trước khi worker được spawn.
+
+## Tác động filesystem
+
+Khi launch thành công, worker ghi:
+
+- `AGENTKIT_HOME/orchestrate/runs/<run-id>/state.json` — run state bền
+  vững.
+- `AGENTKIT_HOME/orchestrate/runs/<run-id>/jobs/<job-id>/stdout.log` và
+  `stderr.log` — output bounded từng job.
+- `AGENTKIT_HOME/orchestrate/runs/<run-id>/launch-graph.json` — digest
+  graph chính xác gắn với run này.
+- Một control socket dùng bởi [`ak orchestrate status`](./status),
+  [`ak orchestrate resume`](./resume) và [`ak orchestrate stop`](./stop).
+
+Worker không persist prompt, argv thô, giá trị environment, hay secret
+ngoài những gì graph chỉ định capture.
+
+## Đầu ra dành cho người dùng và JSON
+
+Thành công dạng người dùng in run ID và status ban đầu từng job. `--json`
+trả về:
+
+```json
+{
+  "action": "start",
+  "run_id": "<opaque>",
+  "graph_digest": "sha256:<hex>",
+  "jobs": [
+    { "id": "<job-id>", "state": "queued" }
+  ]
+}
+```
+
+## Kết quả và mã thoát
+
+| Mã thoát | Ý nghĩa | Bước tiếp theo an toàn |
+| --- | --- | --- |
+| `0` | Worker đã đạt readiness và persist run state. | Poll bằng `ak orchestrate status <run-id>`. |
+| `1` | Job graph không hợp lệ hoặc worker không đạt được readiness. | Sửa graph hoặc đọc lý do được báo; không có run state nào được để lại khi validate thất bại. |
+| `2` | Parse cờ thất bại. | Sửa các cờ. |
+| `3` | Bị interrupt trước readiness. | Kiểm tra `AGENTKIT_HOME/orchestrate/runs/` xem run có bị dở dang không; chạy lại khi sẵn sàng. |
+| `6` | Nền tảng không hỗ trợ (v1 yêu cầu Darwin). | Dùng subprocess do coordinator sở hữu trên nền tảng ngoài Darwin. |
+
+## Xác minh launch
+
+```bash
+ak orchestrate status <run-id>
+```
+
+Đọc control socket của worker live để xác nhận process group vẫn sống dưới
+cùng identity đã verify mà `start` ghi lại.
+
+## Lệnh liên quan
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate status`](./status)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate stop`](./stop)
diff --git a/content/docs/beta/reference/cli/orchestrate/status.en.mdx b/content/docs/beta/reference/cli/orchestrate/status.en.mdx
new file mode 100644
index 0000000..185548f
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/status.en.mdx
@@ -0,0 +1,93 @@
+---
+title: ak orchestrate status
+description: Report an orchestrated run's current lifecycle state through the verified control socket, falling back to fresh identity probes rather than trusting a stale record as still running.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use `ak orchestrate status` to report a run's current lifecycle state. The
+command reaches the run's live worker through its verified control socket
+when reachable; otherwise it reconciles persisted state against a fresh
+identity probe. A stale record alone is never reported as still running.
+
+## Usage
+
+```bash
+ak orchestrate status <run-id>
+```
+
+Supply exactly one positional argument — the run ID printed by
+[`ak orchestrate start`](./start).
+
+## Command flags
+
+Shared flags (`--json`, `--no-interactive`, `--quiet`, `--verbose`, `--yes`)
+are described in [CLI conventions](../cli-conventions). `--json` returns a
+single-object envelope safe for scripted polling.
+
+## Reported fields
+
+For each job the command reports:
+
+- **State** — `queued`, `running`, `completed`, `failed`, `orphaned`, or
+  `unknown`.
+- **PID / PGID** — the verified identity when the worker is reachable.
+- **Heartbeat** — the last time the worker reported activity for the job.
+- **Last output time** — the last write to the job's stdout or stderr log.
+- **Current command label** — the graph-declared label the worker was
+  running when the state was recorded.
+
+<Callout type="warning">
+  A job whose original worker died mid-run is reported as `orphaned`, not
+  `running`. Trusting a persisted PID without a fresh identity probe would
+  risk reporting a reused OS PID from a different process as still supervised
+  work; the command explicitly refuses to do that.
+</Callout>
+
+## Filesystem effects
+
+Read-only, with one exception: a fresh reclassification (for example, the
+worker crashed since the last check) is persisted so subsequent commands
+see the same reality.
+
+## Human and JSON output
+
+`--json` returns:
+
+```json
+{
+  "action": "status",
+  "run_id": "<opaque>",
+  "worker_state": "live | crashed | unreachable",
+  "jobs": [
+    {
+      "id": "<job-id>",
+      "state": "running",
+      "pid": 12345,
+      "pgid": 12345,
+      "heartbeat": "<rfc3339>",
+      "last_output_at": "<rfc3339>",
+      "current_command_label": "<graph-label>"
+    }
+  ]
+}
+```
+
+Human output prints one job per row with the same fields.
+
+## Exit behavior
+
+| Exit | Meaning | Safe next step |
+| --- | --- | --- |
+| `0` | Status was reported successfully. | Consume the fields; do not infer `running` from a `pid` without matching `worker_state`. |
+| `1` | Run ID not found or run state corrupt/unsupported. | Do not retry the same input; investigate the persisted record. |
+| `2` | Flag parsing failed. | Correct the flags. |
+| `3` | Interrupted. | Re-run status. |
+| `6` | Platform unsupported. | Non-Darwin has no persisted worker to query. |
+
+## Related commands
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate stop`](./stop)
diff --git a/content/docs/beta/reference/cli/orchestrate/status.vi.mdx b/content/docs/beta/reference/cli/orchestrate/status.vi.mdx
new file mode 100644
index 0000000..c98b862
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/status.vi.mdx
@@ -0,0 +1,93 @@
+---
+title: ak orchestrate status
+description: Báo state lifecycle hiện tại của một run orchestrate qua control socket đã verify, fallback về identity probe mới thay vì tin record cũ như vẫn đang chạy.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Dùng `ak orchestrate status` để báo state lifecycle hiện tại của một run.
+Lệnh với qua control socket đã verify của worker live khi tới được; ngược
+lại reconcile persisted state so với identity probe mới. Chỉ mỗi record cũ
+không bao giờ được báo là vẫn đang chạy.
+
+## Cách dùng
+
+```bash
+ak orchestrate status <run-id>
+```
+
+Cung cấp đúng một argument theo vị trí — run ID do
+[`ak orchestrate start`](./start) in.
+
+## Cờ của lệnh
+
+Các cờ dùng chung (`--json`, `--no-interactive`, `--quiet`, `--verbose`,
+`--yes`) được mô tả trong [quy ước CLI](../cli-conventions). `--json` trả
+về envelope một object an toàn để script polling.
+
+## Field được báo
+
+Với mỗi job, lệnh báo:
+
+- **State** — `queued`, `running`, `completed`, `failed`, `orphaned`, hoặc
+  `unknown`.
+- **PID / PGID** — identity đã verify khi worker tới được.
+- **Heartbeat** — thời điểm cuối worker báo hoạt động cho job.
+- **Thời gian output cuối** — lần ghi cuối vào log stdout hoặc stderr của
+  job.
+- **Nhãn command hiện tại** — nhãn do graph khai báo mà worker đang chạy
+  lúc state được ghi.
+
+<Callout type="warning">
+  Job có worker gốc chết giữa chừng được báo là `orphaned`, không phải
+  `running`. Tin PID đã persist mà không có identity probe mới sẽ có nguy
+  cơ báo một OS PID được tái dùng từ process khác như công việc đang được
+  giám sát; lệnh từ chối rõ ràng làm việc đó.
+</Callout>
+
+## Tác động filesystem
+
+Read-only, với một ngoại lệ: reclassification mới (ví dụ, worker đã crash
+kể từ lần check trước) được persist để các lệnh sau thấy cùng thực tế.
+
+## Đầu ra dành cho người dùng và JSON
+
+`--json` trả về:
+
+```json
+{
+  "action": "status",
+  "run_id": "<opaque>",
+  "worker_state": "live | crashed | unreachable",
+  "jobs": [
+    {
+      "id": "<job-id>",
+      "state": "running",
+      "pid": 12345,
+      "pgid": 12345,
+      "heartbeat": "<rfc3339>",
+      "last_output_at": "<rfc3339>",
+      "current_command_label": "<graph-label>"
+    }
+  ]
+}
+```
+
+Đầu ra dành cho người dùng in một job mỗi hàng với cùng field.
+
+## Kết quả và mã thoát
+
+| Mã thoát | Ý nghĩa | Bước tiếp theo an toàn |
+| --- | --- | --- |
+| `0` | Status được báo thành công. | Dùng các field; đừng suy `running` từ `pid` mà không có `worker_state` khớp. |
+| `1` | Run ID không tìm thấy hoặc state hỏng/không hỗ trợ. | Không retry cùng input; điều tra record persisted. |
+| `2` | Parse cờ thất bại. | Sửa các cờ. |
+| `3` | Bị interrupt. | Chạy lại status. |
+| `6` | Nền tảng không hỗ trợ. | Ngoài Darwin không có worker persisted để query. |
+
+## Lệnh liên quan
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate stop`](./stop)
diff --git a/content/docs/beta/reference/cli/orchestrate/stop.en.mdx b/content/docs/beta/reference/cli/orchestrate/stop.en.mdx
new file mode 100644
index 0000000..7964004
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/stop.en.mdx
@@ -0,0 +1,89 @@
+---
+title: ak orchestrate stop
+description: Terminate an orchestrated run's live jobs with SIGTERM, a bounded grace period, then SIGKILL — always against a verified worker identity, never guessed from a stale persisted PID.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Use `ak orchestrate stop` to send SIGTERM to every signal-authorized job in
+the run's verified process group through the worker's control socket, wait
+a bounded grace period, then SIGKILL only a job whose group is still alive
+under the same verified identity. If no live, verified worker is reachable,
+the command reports that instead of guessing a kill target.
+
+<Callout type="warning">
+  Stop never falls back to signalling from a persisted PID alone. A reused
+  OS PID from a different process is not a valid kill target; the command
+  refuses to signal one and asks the operator to investigate instead.
+</Callout>
+
+## Usage
+
+```bash
+ak orchestrate stop <run-id>
+```
+
+Supply exactly one positional argument — the run ID printed by
+[`ak orchestrate start`](./start).
+
+## Command flags
+
+Shared flags (`--json`, `--no-interactive`, `--quiet`, `--verbose`, `--yes`)
+are described in [CLI conventions](../cli-conventions). Stop honors
+`--yes` and `--no-interactive` for scripted cancellation; the shutdown
+sequence itself does not prompt.
+
+## Shutdown sequence
+
+1. **Verify the worker.** Contact the run's control socket and confirm the
+   worker's identity matches the one recorded at `start`.
+2. **SIGTERM the process group.** Every signal-authorized job in the
+   verified group receives SIGTERM.
+3. **Wait the grace period.** The worker gives each job a bounded time to
+   exit cleanly.
+4. **SIGKILL survivors.** Only a job whose group is still alive under the
+   same verified identity receives SIGKILL.
+5. **Persist the outcome.** The stop request and its per-job result are
+   written to the run's state file.
+
+If step 1 fails — for example, the worker itself crashed — no signals are
+sent. Stop reports the unreachable worker and exits `1` rather than
+signalling a persisted PID that may now belong to a different process.
+
+## Filesystem effects
+
+Persists the stop request and its outcome to the run's state file. Does
+not delete run state, output logs, or the launch graph; those remain for
+inspection.
+
+## Human and JSON output
+
+`--json` returns:
+
+```json
+{
+  "action": "stop",
+  "run_id": "<opaque>",
+  "worker_state": "live | crashed | unreachable",
+  "signalled": ["<job-id>", "..."],
+  "killed": ["<job-id>", "..."],
+  "survived": []
+}
+```
+
+## Exit behavior
+
+| Exit | Meaning | Safe next step |
+| --- | --- | --- |
+| `0` | Every reachable, signal-authorized job was terminated. | Run `ak orchestrate status <run-id>` to verify. |
+| `1` | No live, verified worker was reachable, or a stop step failed. | Investigate; do not force-signal a persisted PID by hand. |
+| `2` | Flag parsing failed. | Correct the flags. |
+| `3` | User cancelled during the shutdown request. | Re-run stop when ready. |
+| `6` | Platform unsupported. | Non-Darwin has no persisted worker to stop. |
+
+## Related commands
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate status`](./status)
diff --git a/content/docs/beta/reference/cli/orchestrate/stop.vi.mdx b/content/docs/beta/reference/cli/orchestrate/stop.vi.mdx
new file mode 100644
index 0000000..e64f9ab
--- /dev/null
+++ b/content/docs/beta/reference/cli/orchestrate/stop.vi.mdx
@@ -0,0 +1,89 @@
+---
+title: ak orchestrate stop
+description: Terminate các job live của run orchestrate bằng SIGTERM, một khoảng grace bounded, rồi SIGKILL — luôn chống lại identity worker đã verify, không bao giờ đoán từ PID persisted cũ.
+---
+
+import { Callout } from 'fumadocs-ui/components/callout';
+
+Dùng `ak orchestrate stop` để gửi SIGTERM tới mọi job được cấp signal
+trong process group đã verify của run qua control socket của worker, chờ
+khoảng grace bounded, rồi SIGKILL chỉ job có group vẫn còn sống dưới cùng
+identity đã verify. Nếu không có worker live, đã verify tới được, lệnh
+báo điều đó thay vì đoán target kill.
+
+<Callout type="warning">
+  Stop không bao giờ fallback về signalling chỉ dựa trên PID persisted.
+  Một OS PID được tái dùng từ process khác không phải target kill hợp lệ;
+  lệnh từ chối signal nó và yêu cầu operator điều tra.
+</Callout>
+
+## Cách dùng
+
+```bash
+ak orchestrate stop <run-id>
+```
+
+Cung cấp đúng một argument theo vị trí — run ID do
+[`ak orchestrate start`](./start) in.
+
+## Cờ của lệnh
+
+Các cờ dùng chung (`--json`, `--no-interactive`, `--quiet`, `--verbose`,
+`--yes`) được mô tả trong [quy ước CLI](../cli-conventions). Stop tôn
+trọng `--yes` và `--no-interactive` cho cancellation dạng script; chính
+chuỗi shutdown không hỏi prompt.
+
+## Chuỗi shutdown
+
+1. **Verify worker.** Liên hệ control socket của run và xác nhận identity
+   của worker khớp với identity đã ghi ở `start`.
+2. **SIGTERM process group.** Mọi job được cấp signal trong group đã
+   verify nhận SIGTERM.
+3. **Chờ khoảng grace.** Worker cho mỗi job một khoảng thời gian bounded
+   để thoát sạch.
+4. **SIGKILL các job sống sót.** Chỉ job có group vẫn còn sống dưới cùng
+   identity đã verify nhận SIGKILL.
+5. **Persist kết quả.** Yêu cầu stop và kết quả từng job được ghi vào
+   state file của run.
+
+Nếu bước 1 thất bại — ví dụ, chính worker đã crash — không signal nào
+được gửi. Stop báo worker không tới được và thoát `1` thay vì signal PID
+persisted mà giờ có thể thuộc process khác.
+
+## Tác động filesystem
+
+Persist yêu cầu stop và kết quả của nó vào state file của run. Không xoá
+run state, log output, hay launch graph; các file đó vẫn để lại để kiểm
+tra.
+
+## Đầu ra dành cho người dùng và JSON
+
+`--json` trả về:
+
+```json
+{
+  "action": "stop",
+  "run_id": "<opaque>",
+  "worker_state": "live | crashed | unreachable",
+  "signalled": ["<job-id>", "..."],
+  "killed": ["<job-id>", "..."],
+  "survived": []
+}
+```
+
+## Kết quả và mã thoát
+
+| Mã thoát | Ý nghĩa | Bước tiếp theo an toàn |
+| --- | --- | --- |
+| `0` | Mọi job tới được, được cấp signal đã bị terminate. | Chạy `ak orchestrate status <run-id>` để xác minh. |
+| `1` | Không có worker live, đã verify tới được, hoặc một bước stop thất bại. | Điều tra; đừng force-signal PID persisted bằng tay. |
+| `2` | Parse cờ thất bại. | Sửa các cờ. |
+| `3` | Người dùng huỷ trong yêu cầu shutdown. | Chạy lại stop khi sẵn sàng. |
+| `6` | Nền tảng không hỗ trợ. | Ngoài Darwin không có worker persisted để stop. |
+
+## Lệnh liên quan
+
+- [`ak orchestrate`](./)
+- [`ak orchestrate start`](./start)
+- [`ak orchestrate resume`](./resume)
+- [`ak orchestrate status`](./status)
diff --git a/content/docs/beta/reference/release-notes.mdx b/content/docs/beta/reference/release-notes.mdx
index 390f0ae..b63a322 100644
--- a/content/docs/beta/reference/release-notes.mdx
+++ b/content/docs/beta/reference/release-notes.mdx
@@ -1,9 +1,9 @@
 ---
 title: Release notes
-description: Release notes for the beta channel (v2.12.1-beta.8).
+description: Release notes for the beta channel (v2.13.0-beta.2).
 generated: true
 ---
-# AgentKit v2.12.1-beta.8
+# AgentKit v2.13.0-beta.2
 
 ## Breaking changes
 
@@ -223,6 +223,11 @@ generated: true
 - **kits:** Adopt ak-hyperframes wrapping HeyGen HyperFrames CLI ([#1532](https://github.com/bestagentkits/agentkit-support/pull/1532))
 - **release:** Gate manual release announcements on publication facts ([#1460](https://github.com/bestagentkits/agentkit-support/pull/1460))
 - **ak-journal,ak-ship:** Media flags + --social publishing &#40;PR3/3&#41; ([#1536](https://github.com/bestagentkits/agentkit-support/pull/1536))
+- **ak-plan:** Add --debate for independent plan proposals and synthesis ([#1577](https://github.com/bestagentkits/agentkit-support/pull/1577))
+- **mcp:** Add remote &#40;http/sse&#41; transport discovery and write path ([#1578](https://github.com/bestagentkits/agentkit-support/pull/1578))
+- **kits:** Add design handoff and critique gate ([#1564](https://github.com/bestagentkits/agentkit-support/pull/1564))
+- **kits:** Add shared design-quality preflight for design skills ([#1570](https://github.com/bestagentkits/agentkit-support/pull/1570))
+- **worktree:** Configurable default worktree.root for ak:worktree ([#1571](https://github.com/bestagentkits/agentkit-support/pull/1571))
 
 ## Fixes and security
 
@@ -569,6 +574,12 @@ generated: true
 - **skills:** Resolve multix from npm latest
 - **desktop:** Show license activation errors ([#1556](https://github.com/bestagentkits/agentkit-support/pull/1556))
 - **fsutil:** Route file-replace writes through shared rename retry ([#1561](https://github.com/bestagentkits/agentkit-support/pull/1561))
+- **desktop:** Correct plan/phase status and add mark-completed actions ([#1579](https://github.com/bestagentkits/agentkit-support/pull/1579))
+- **claude-code:** Register write-observed postimage mode in writeStructured ([#1580](https://github.com/bestagentkits/agentkit-support/pull/1580))
+- **installer:** Support common shell path guidance ([#1575](https://github.com/bestagentkits/agentkit-support/pull/1575))
+- **mcpdiscovery:** Escape backslashes in JSON test fixtures for Windows paths ([#1584](https://github.com/bestagentkits/agentkit-support/pull/1584))
+- **orchestrate:** Supervise ak orchestrate CLI jobs so interruption can't orphan them ([#1581](https://github.com/bestagentkits/agentkit-support/pull/1581))
+- **skills:** Seed metadata.workflow frontmatter across 9 kit skills ([#1569](https://github.com/bestagentkits/agentkit-support/pull/1569))
 
 ## Documentation
 
@@ -620,6 +631,6 @@ generated: true
 
 ## Release provenance
 
-- Promoted source: `1376205a3953306d5f80ff9d61f2a94c6267dfa7`
-- Stable snapshot commit: `1376205a3953306d5f80ff9d61f2a94c6267dfa7`
-- Artifact checksums: [release-provenance.json](https://github.com/bestagentkits/agentkit-support/releases/download/v2.12.1-beta.8/release-provenance.json)
+- Promoted source: `e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2`
+- Stable snapshot commit: `e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2`
+- Artifact checksums: [release-provenance.json](https://github.com/bestagentkits/agentkit-support/releases/download/v2.13.0-beta.2/release-provenance.json)
diff --git a/lib/channel-route-href.mjs b/lib/channel-route-href.mjs
new file mode 100644
index 0000000..7c7d65b
--- /dev/null
+++ b/lib/channel-route-href.mjs
@@ -0,0 +1,18 @@
+export function channelRouteHref(locale, channel, remainder, targetExists) {
+  const root = `/${locale}/${channel}`;
+  if (!targetExists || remainder.length === 0) return root;
+  return `${root}/${remainder.map((segment) => decodeURI(segment)).join('/')}`;
+}
+
+export function unavailableChannelUrls(pageUrls) {
+  const urls = new Set(pageUrls);
+  const unavailable = new Set();
+  for (const url of urls) {
+    const match = url.match(/^\/([^/]+)\/(stable|beta)(\/.*)?$/);
+    if (!match) continue;
+    const targetChannel = match[2] === 'stable' ? 'beta' : 'stable';
+    const targetUrl = `/${match[1]}/${targetChannel}${match[3] ?? ''}`;
+    if (!urls.has(targetUrl)) unavailable.add(targetUrl);
+  }
+  return [...unavailable].sort();
+}
diff --git a/reference-derived/.generated b/reference-derived/.generated
index 8e51f64..92d7596 100644
--- a/reference-derived/.generated
+++ b/reference-derived/.generated
@@ -1,8 +1,8 @@
 {
   "generator": "ak-cli-reference",
   "source": "ak-cli",
-  "tag": "v2.12.1-beta.8",
-  "sha": "1376205a3953306d5f80ff9d61f2a94c6267dfa7",
-  "generatedAt": "2026-08-11T05:59:40Z",
+  "tag": "v2.13.0-beta.2",
+  "sha": "e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2",
+  "generatedAt": "2026-08-12T06:17:36Z",
   "note": "Machine-owned directory generated by the release-sync pipeline. Do not hand-edit."
 }
diff --git a/reference-derived/ak.mdx b/reference-derived/ak.mdx
index 9082b87..e98dc70 100644
--- a/reference-derived/ak.mdx
+++ b/reference-derived/ak.mdx
@@ -51,6 +51,7 @@ Global flags, output modes, and the standard exit codes (`0`–`3`) are shared b
 - [`ak mcp`](./ak_mcp) — Inspect local MCP server configuration
 - [`ak migrate`](./ak_migrate) — Migrate an existing ClaudeKit install to AgentKit
 - [`ak new`](./ak_new) — Bootstrap a new AgentKit project
+- [`ak orchestrate`](./ak_orchestrate) — Run and supervise external CLI job graphs (Darwin only)
 - [`ak plan`](./ak_plan) — Manage AgentKit plan directories
 - [`ak projects`](./ak_projects) — Manage the global AK project registry
 - [`ak recover`](./ak_recover) — Recover AgentKit state from a snapshot
diff --git a/reference-derived/ak_config_prefs.mdx b/reference-derived/ak_config_prefs.mdx
index ce31295..7ce89f8 100644
--- a/reference-derived/ak_config_prefs.mdx
+++ b/reference-derived/ak_config_prefs.mdx
@@ -29,6 +29,6 @@ Global flags, output modes, and the standard exit codes (`0`–`3`) are shared b
 
 - [`ak config`](./ak_config) — Open the local AgentKit dashboard
 - [`ak config prefs resolve`](./ak_config_prefs_resolve) — Print the resolved preference values
-- [`ak config prefs set`](./ak_config_prefs_set) — Set a hook soft-preference or the journal.auto preference in config.yaml
-- [`ak config prefs unset`](./ak_config_prefs_unset) — Remove a hook or journal.auto soft-preference so it returns to default
+- [`ak config prefs set`](./ak_config_prefs_set) — Set a hook, journal.auto, or worktree.root preference in config.yaml
+- [`ak config prefs unset`](./ak_config_prefs_unset) — Remove a hook, journal.auto, or worktree.root soft-preference so it returns to default
 - [`ak config prefs validate`](./ak_config_prefs_validate) — Check config.yaml against the AgentKit schema
diff --git a/reference-derived/ak_config_prefs_set.mdx b/reference-derived/ak_config_prefs_set.mdx
index 2c6260b..5d046f5 100644
--- a/reference-derived/ak_config_prefs_set.mdx
+++ b/reference-derived/ak_config_prefs_set.mdx
@@ -1,21 +1,21 @@
 ---
 title: "ak config prefs set"
-description: "Set a hook soft-preference or the journal.auto preference in config.yaml"
+description: "Set a hook, journal.auto, or worktree.root preference in config.yaml"
 generated: true
 ---
 
-Write a per-hook toggle or the single journal.auto leaf into config.yaml: `set hooks.<name> false` makes that hook exit early at its next run without unregistering it from the harness; `set journal.auto false` suppresses the automatic /ak:journal step at the end of plan/cook/fix/ship/bootstrap without affecting explicit /ak:journal. Only keys under `hooks.` and the exact key `journal.auto` may be set; the whole document is schema-checked before writing.
+Write a per-hook toggle, the journal.auto leaf, or the worktree.root leaf into config.yaml: `set hooks.<name> false` makes that hook exit early at its next run without unregistering it from the harness; `set journal.auto false` suppresses the automatic /ak:journal step at the end of plan/cook/fix/ship/bootstrap without affecting explicit /ak:journal; `set worktree.root <path>` sets the default ak:worktree location ak:worktree uses unless --worktree-root is passed. Only keys under `hooks.`, the exact key `journal.auto`, and the exact key `worktree.root` may be set; the whole document is schema-checked before writing. At project scope, worktree.root must be a relative path (resolved from the project root); at user scope it may also be absolute.
 
-**Who it's for:** Anyone disabling a hook or the automatic journal step for this machine or this project without editing YAML by hand.
+**Who it's for:** Anyone disabling a hook, opting out of the automatic journal step, or pointing ak:worktree at a non-default location (e.g. a portable drive) without editing YAML by hand.
 
-**When to use it:** Use it to turn a hook off (or back on) or to opt out of the automatic journal step; the harness registration and explicit /ak:journal are unchanged.
+**When to use it:** Use it to turn a hook off (or back on), to opt out of the automatic journal step, or to persist a default worktree root; the harness registration and explicit /ak:journal are unchanged.
 
 **What changes on disk:** Backs up then rewrites the selected scope's config.yaml (project scaffolds it when absent).
 
 ### Usage
 
 ```bash
-ak config prefs set <key> <true|false> [flags]
+ak config prefs set <key> <value> [flags]
 ```
 
 ### Examples
@@ -24,6 +24,8 @@ ak config prefs set <key> <true|false> [flags]
 ak config prefs set hooks.simplify-gate false            # disable for the user
 ak config prefs set hooks.simplify-gate true --scope project
 ak config prefs set journal.auto false                  # skip automatic /ak:journal
+ak config prefs set worktree.root /Volumes/Portable/agentkit-worktrees
+ak config prefs set worktree.root ../my-app-worktrees --scope project
 ```
 
 Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
@@ -38,7 +40,7 @@ Global flags, output modes, and the standard exit codes (`0`–`3`) are shared b
 
 | Code | Meaning |
 | --- | --- |
-| `1` | the key is not allowed, the value is not a bool, or the result fails the schema |
+| `1` | the key is not allowed, the value has the wrong type for the key, or the result fails the schema |
 
 ### Related commands
 
diff --git a/reference-derived/ak_config_prefs_unset.mdx b/reference-derived/ak_config_prefs_unset.mdx
index ee77ad7..82d93f3 100644
--- a/reference-derived/ak_config_prefs_unset.mdx
+++ b/reference-derived/ak_config_prefs_unset.mdx
@@ -1,10 +1,10 @@
 ---
 title: "ak config prefs unset"
-description: "Remove a hook or journal.auto soft-preference so it returns to default"
+description: "Remove a hook, journal.auto, or worktree.root soft-preference so it returns to default"
 generated: true
 ---
 
-Delete a per-hook toggle or the journal.auto leaf from config.yaml so the value returns to its inherited or built-in default (journal.auto defaults to true). Removing an absent key is a no-op. Only keys under `hooks.` and the exact key `journal.auto` may be unset.
+Delete a per-hook toggle, the journal.auto leaf, or the worktree.root leaf from config.yaml so the value returns to its inherited or built-in default (journal.auto defaults to true; worktree.root defaults to unset, so ak:worktree falls back to WORKTREE_ROOT / its built-in location chain). Removing an absent key is a no-op. Only keys under `hooks.`, the exact key `journal.auto`, and the exact key `worktree.root` may be unset.
 
 **Who it's for:** Power users cleaning up an explicit toggle they no longer want pinned.
 
@@ -24,6 +24,7 @@ ak config prefs unset <key> [flags]
 ak config prefs unset hooks.simplify-gate
 ak config prefs unset hooks.simplify-gate --scope project
 ak config prefs unset journal.auto
+ak config prefs unset worktree.root --scope project
 ```
 
 Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
diff --git a/reference-derived/ak_orchestrate.mdx b/reference-derived/ak_orchestrate.mdx
new file mode 100644
index 0000000..ec9eab5
--- /dev/null
+++ b/reference-derived/ak_orchestrate.mdx
@@ -0,0 +1,40 @@
+---
+title: "ak orchestrate"
+description: "Run and supervise external CLI job graphs (Darwin only)"
+generated: true
+---
+
+Start, resume, check, and stop a graph of external CLI jobs under a dedicated local worker supervisor. The worker owns each job's process group, persists durable run state under AGENTKIT_HOME, and survives the launching client or coordinator exiting. `start` always creates a new run; only `resume <run-id>` continues an existing one. v1 supports darwin only — every other GOOS returns an explicit unsupported error.
+
+**Who it's for:** The /ak:orchestrate skill's job-execution layer, and power devs scripting multi-job CLI runs directly.
+
+**When to use it:** Use `ak orchestrate start` to launch a validated job graph. If a client or coordinator is interrupted, use `ak orchestrate status`/`stop` with the same run ID to reconnect to the still-running worker instead of guessing at orphaned processes.
+
+**What changes on disk:** Writes run state, per-job output logs, and a control socket under AGENTKIT_HOME/orchestrate/runs/&lt;run-id&gt;/. Never persists prompts, raw command arguments, environment values, or secrets.
+
+### Examples
+
+```bash
+ak orchestrate start jobs.json           # launch a new run, prints its run ID
+ak orchestrate status <run-id>            # PID/PGID, heartbeat, last output, per-job state
+ak orchestrate resume <run-id> jobs.json  # reconnect after a client/coordinator crash
+ak orchestrate stop <run-id>               # TERM the group, grace period, then KILL
+ak orchestrate start jobs.json --json      # scripted run-id + status envelope
+```
+
+Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `1` | runtime error (state I/O, launch/signal failure) |
+| `6` | unsupported platform (v1 requires darwin) |
+
+### Related commands
+
+- [`ak`](./ak) — AgentKit CLI
+- [`ak orchestrate resume`](./ak_orchestrate_resume) — Reconnect to an existing run after a client or coordinator crash
+- [`ak orchestrate start`](./ak_orchestrate_start) — Launch a new orchestrated run from a job graph file
+- [`ak orchestrate status`](./ak_orchestrate_status) — Report a run's current lifecycle state
+- [`ak orchestrate stop`](./ak_orchestrate_stop) — Terminate a run's live jobs (TERM, grace period, then KILL)
diff --git a/reference-derived/ak_orchestrate_resume.mdx b/reference-derived/ak_orchestrate_resume.mdx
new file mode 100644
index 0000000..6b9309d
--- /dev/null
+++ b/reference-derived/ak_orchestrate_resume.mdx
@@ -0,0 +1,39 @@
+---
+title: "ak orchestrate resume"
+description: "Reconnect to an existing run after a client or coordinator crash"
+generated: true
+---
+
+Reconnect to run-id using the same job graph file that started it. If a live, verified worker is reachable, resume confirms the graph's digest still matches the running record and reports its current state — it never relaunches jobs or creates a second process tree. If the worker itself crashed, resume falls back to a read-only reclassification of the persisted record against a fresh identity probe; an adopted job whose original worker died mid-run stays orphaned for a human (or a fresh `start`) to act on rather than being silently continued.
+
+**Who it's for:** Both power devs scripting crash recovery and the /ak:orchestrate skill reconnecting after an interrupted coordinator.
+
+**When to use it:** After this terminal, its shell, or its coordinating process was interrupted or restarted while a run was in flight.
+
+**What changes on disk:** Read-only against a live worker; persists a reclassification of orphaned/unknown jobs when the worker crashed.
+
+### Usage
+
+```bash
+ak orchestrate resume <run-id> <job-graph.json> [flags]
+```
+
+### Examples
+
+```bash
+ak orchestrate resume 3f9a... jobs.json          # reconnect using the original job graph
+ak orchestrate resume 3f9a... jobs.json --json    # scripted result envelope
+```
+
+Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `1` | job graph does not match the persisted run's launch digest, run not found, or state is corrupt/unsupported |
+| `6` | unsupported platform (v1 requires darwin) |
+
+### Related commands
+
+- [`ak orchestrate`](./ak_orchestrate) — Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-derived/ak_orchestrate_start.mdx b/reference-derived/ak_orchestrate_start.mdx
new file mode 100644
index 0000000..75cb5c9
--- /dev/null
+++ b/reference-derived/ak_orchestrate_start.mdx
@@ -0,0 +1,39 @@
+---
+title: "ak orchestrate start"
+description: "Launch a new orchestrated run from a job graph file"
+generated: true
+---
+
+Validate a job graph file, generate a fresh opaque run ID, and spawn a detached worker that owns every job's process group for that run. Blocks until the worker durably persists run state and proves readiness, then prints the run ID and initial status. `start` always creates a new run; retrying the same graph does not reuse an existing run ID.
+
+**Who it's for:** The /ak:orchestrate skill's job-execution layer, and power devs scripting external CLI job graphs.
+
+**When to use it:** When you have a validated job graph (id/command/args/work_dir/env/depends_on per job) ready to launch.
+
+**What changes on disk:** Writes AGENTKIT_HOME/orchestrate/runs/&lt;run-id&gt;/ (state, per-job output logs, launch graph). Never persists prompts, raw argv, environment values, or secrets.
+
+### Usage
+
+```bash
+ak orchestrate start <job-graph.json> [flags]
+```
+
+### Examples
+
+```bash
+ak orchestrate start jobs.json          # launch, print run ID and initial status
+ak orchestrate start jobs.json --json    # scripted run-id + status envelope
+```
+
+Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `1` | job graph invalid, or the worker failed to reach readiness |
+| `6` | unsupported platform (v1 requires darwin) |
+
+### Related commands
+
+- [`ak orchestrate`](./ak_orchestrate) — Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-derived/ak_orchestrate_status.mdx b/reference-derived/ak_orchestrate_status.mdx
new file mode 100644
index 0000000..3eddb7d
--- /dev/null
+++ b/reference-derived/ak_orchestrate_status.mdx
@@ -0,0 +1,39 @@
+---
+title: "ak orchestrate status"
+description: "Report a run's current lifecycle state"
+generated: true
+---
+
+Reach the run's live worker through its verified control socket when reachable, otherwise reconcile persisted state against a fresh identity probe. Reports PID/PGID, heartbeat, last-output time, and a current-command label per job — a stale record alone is never reported as still running.
+
+**Who it's for:** Both power devs polling in scripts (--json) and interactive checks after a client/coordinator crash.
+
+**When to use it:** Checking on a run started earlier, including after this terminal or its coordinator was interrupted.
+
+**What changes on disk:** Read-only, except a fresh reclassification (e.g. worker crashed since the last check) is persisted.
+
+### Usage
+
+```bash
+ak orchestrate status <run-id> [flags]
+```
+
+### Examples
+
+```bash
+ak orchestrate status 3f9a...            # human-readable per-job table
+ak orchestrate status 3f9a... --json      # scripted status envelope
+```
+
+Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `1` | run ID not found, or run state is corrupt/unsupported |
+| `6` | unsupported platform (v1 requires darwin) |
+
+### Related commands
+
+- [`ak orchestrate`](./ak_orchestrate) — Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-derived/ak_orchestrate_stop.mdx b/reference-derived/ak_orchestrate_stop.mdx
new file mode 100644
index 0000000..43c885f
--- /dev/null
+++ b/reference-derived/ak_orchestrate_stop.mdx
@@ -0,0 +1,39 @@
+---
+title: "ak orchestrate stop"
+description: "Terminate a run's live jobs (TERM, grace period, then KILL)"
+generated: true
+---
+
+Send SIGTERM to every signal-authorized job in the run's verified process group through the worker's control socket, wait a bounded grace period, then SIGKILL only a job whose group is still alive under the same verified identity. Never falls back to signalling from persisted state: if no live, verified worker is reachable, this command reports that instead of guessing a kill target.
+
+**Who it's for:** Both power devs scripting cancellation and interactive use after `status` shows a run is no longer needed.
+
+**When to use it:** Cancelling a run explicitly, or cleaning up before starting a replacement.
+
+**What changes on disk:** Persists the stop request and its outcome to the run's state file.
+
+### Usage
+
+```bash
+ak orchestrate stop <run-id> [flags]
+```
+
+### Examples
+
+```bash
+ak orchestrate stop 3f9a...          # TERM, grace period, then KILL if still alive
+ak orchestrate stop 3f9a... --json    # scripted result envelope
+```
+
+Global flags, output modes, and the standard exit codes (`0`–`3`) are shared by every command — see [CLI conventions](../cli-conventions). The sections below list only what is specific to this command.
+
+### Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| `1` | no live, verified worker reachable for this run, or the stop failed |
+| `6` | unsupported platform (v1 requires darwin) |
+
+### Related commands
+
+- [`ak orchestrate`](./ak_orchestrate) — Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-derived/index.mdx b/reference-derived/index.mdx
index b8cb8ed..079282a 100644
--- a/reference-derived/index.mdx
+++ b/reference-derived/index.mdx
@@ -119,8 +119,8 @@ output modes, and standard exit codes are documented once in
 | [`ak config`](./ak_config) | Open the local AgentKit dashboard |
 | [`ak config prefs`](./ak_config_prefs) | Inspect resolved AgentKit preferences |
 | [`ak config prefs resolve`](./ak_config_prefs_resolve) | Print the resolved preference values |
-| [`ak config prefs set`](./ak_config_prefs_set) | Set a hook soft-preference or the journal.auto preference in config.yaml |
-| [`ak config prefs unset`](./ak_config_prefs_unset) | Remove a hook or journal.auto soft-preference so it returns to default |
+| [`ak config prefs set`](./ak_config_prefs_set) | Set a hook, journal.auto, or worktree.root preference in config.yaml |
+| [`ak config prefs unset`](./ak_config_prefs_unset) | Remove a hook, journal.auto, or worktree.root soft-preference so it returns to default |
 | [`ak config prefs validate`](./ak_config_prefs_validate) | Check config.yaml against the AgentKit schema |
 | [`ak config start`](./ak_config_start) | Start the local dashboard server |
 | [`ak config status`](./ak_config_status) | Show the running state of the dashboard server |
@@ -211,6 +211,16 @@ output modes, and standard exit codes are documented once in
 | [`ak migrate prefs`](./ak_migrate_prefs) | Migrate legacy ClaudeKit preferences into AgentKit config.yaml |
 | [`ak migrate rollback`](./ak_migrate_rollback) | Roll back a failed migration to its pre-apply state |
 
+## `ak orchestrate` — Run and supervise external CLI job graphs (Darwin only)
+
+| Command | Description |
+| --- | --- |
+| [`ak orchestrate`](./ak_orchestrate) | Run and supervise external CLI job graphs (Darwin only) |
+| [`ak orchestrate resume`](./ak_orchestrate_resume) | Reconnect to an existing run after a client or coordinator crash |
+| [`ak orchestrate start`](./ak_orchestrate_start) | Launch a new orchestrated run from a job graph file |
+| [`ak orchestrate status`](./ak_orchestrate_status) | Report a run's current lifecycle state |
+| [`ak orchestrate stop`](./ak_orchestrate_stop) | Terminate a run's live jobs (TERM, grace period, then KILL) |
+
 ## `ak plan` — Manage AgentKit plan directories
 
 | Command | Description |
diff --git a/reference-raw/ak.mdx b/reference-raw/ak.mdx
index 9aa7cb7..5909e19 100644
--- a/reference-raw/ak.mdx
+++ b/reference-raw/ak.mdx
@@ -85,6 +85,7 @@ Docs / feedback: https://github.com/bestagentkits/agentkit-support
 * [ak mcp](./ak_mcp)	 - Inspect local MCP server configuration
 * [ak migrate](./ak_migrate)	 - Migrate an existing ClaudeKit install to AgentKit
 * [ak new](./ak_new)	 - Bootstrap a new AgentKit project
+* [ak orchestrate](./ak_orchestrate)	 - Run and supervise external CLI job graphs (Darwin only)
 * [ak plan](./ak_plan)	 - Manage AgentKit plan directories
 * [ak projects](./ak_projects)	 - Manage the global AK project registry
 * [ak recover](./ak_recover)	 - Recover AgentKit state from a snapshot
diff --git a/reference-raw/ak_config_prefs.mdx b/reference-raw/ak_config_prefs.mdx
index a083dce..9113597 100644
--- a/reference-raw/ak_config_prefs.mdx
+++ b/reference-raw/ak_config_prefs.mdx
@@ -56,6 +56,6 @@ Exit codes:
 
 * [ak config](./ak_config)	 - Open the local AgentKit dashboard
 * [ak config prefs resolve](./ak_config_prefs_resolve)	 - Print the resolved preference values
-* [ak config prefs set](./ak_config_prefs_set)	 - Set a hook soft-preference or the journal.auto preference in config.yaml
-* [ak config prefs unset](./ak_config_prefs_unset)	 - Remove a hook or journal.auto soft-preference so it returns to default
+* [ak config prefs set](./ak_config_prefs_set)	 - Set a hook, journal.auto, or worktree.root preference in config.yaml
+* [ak config prefs unset](./ak_config_prefs_unset)	 - Remove a hook, journal.auto, or worktree.root soft-preference so it returns to default
 * [ak config prefs validate](./ak_config_prefs_validate)	 - Check config.yaml against the AgentKit schema
diff --git a/reference-raw/ak_config_prefs_set.mdx b/reference-raw/ak_config_prefs_set.mdx
index 98af7ef..5b0d826 100644
--- a/reference-raw/ak_config_prefs_set.mdx
+++ b/reference-raw/ak_config_prefs_set.mdx
@@ -1,28 +1,30 @@
 ---
 title: "ak config prefs set"
-description: "Set a hook soft-preference or the journal.auto preference in config.yaml"
+description: "Set a hook, journal.auto, or worktree.root preference in config.yaml"
 generated: true
 ---
 
 ## ak config prefs set
 
-Set a hook soft-preference or the journal.auto preference in config.yaml
+Set a hook, journal.auto, or worktree.root preference in config.yaml
 
 ### Synopsis
 
 What it does:
-  Write a per-hook toggle or the single journal.auto leaf into config.yaml: `set hooks.<name> false` makes that hook exit early at its next run without unregistering it from the harness; `set journal.auto false` suppresses the automatic /ak:journal step at the end of plan/cook/fix/ship/bootstrap without affecting explicit /ak:journal. Only keys under `hooks.` and the exact key `journal.auto` may be set; the whole document is schema-checked before writing.
+  Write a per-hook toggle, the journal.auto leaf, or the worktree.root leaf into config.yaml: `set hooks.<name> false` makes that hook exit early at its next run without unregistering it from the harness; `set journal.auto false` suppresses the automatic /ak:journal step at the end of plan/cook/fix/ship/bootstrap without affecting explicit /ak:journal; `set worktree.root <path>` sets the default ak:worktree location ak:worktree uses unless --worktree-root is passed. Only keys under `hooks.`, the exact key `journal.auto`, and the exact key `worktree.root` may be set; the whole document is schema-checked before writing. At project scope, worktree.root must be a relative path (resolved from the project root); at user scope it may also be absolute.
 
 Who it's for:
-  Anyone disabling a hook or the automatic journal step for this machine or this project without editing YAML by hand.
+  Anyone disabling a hook, opting out of the automatic journal step, or pointing ak:worktree at a non-default location (e.g. a portable drive) without editing YAML by hand.
 
 When to use it:
-  Use it to turn a hook off (or back on) or to opt out of the automatic journal step; the harness registration and explicit /ak:journal are unchanged.
+  Use it to turn a hook off (or back on), to opt out of the automatic journal step, or to persist a default worktree root; the harness registration and explicit /ak:journal are unchanged.
 
 Examples:
   ak config prefs set hooks.simplify-gate false            # disable for the user
   ak config prefs set hooks.simplify-gate true --scope project
   ak config prefs set journal.auto false                  # skip automatic /ak:journal
+  ak config prefs set worktree.root /Volumes/Portable/agentkit-worktrees
+  ak config prefs set worktree.root ../my-app-worktrees --scope project
 
 What changes on disk:
   Backs up then rewrites the selected scope's config.yaml (project scaffolds it when absent).
@@ -37,10 +39,10 @@ Exit codes:
   1  runtime error
   2  invalid flags
   3  user-cancel (SIGINT, prompt-cancel)
-  1  the key is not allowed, the value is not a bool, or the result fails the schema
+  1  the key is not allowed, the value has the wrong type for the key, or the result fails the schema
 
 ```
-ak config prefs set <key> <true|false> [flags]
+ak config prefs set <key> <value> [flags]
 ```
 
 ### Options
diff --git a/reference-raw/ak_config_prefs_unset.mdx b/reference-raw/ak_config_prefs_unset.mdx
index bb3af0a..89f0e45 100644
--- a/reference-raw/ak_config_prefs_unset.mdx
+++ b/reference-raw/ak_config_prefs_unset.mdx
@@ -1,17 +1,17 @@
 ---
 title: "ak config prefs unset"
-description: "Remove a hook or journal.auto soft-preference so it returns to default"
+description: "Remove a hook, journal.auto, or worktree.root soft-preference so it returns to default"
 generated: true
 ---
 
 ## ak config prefs unset
 
-Remove a hook or journal.auto soft-preference so it returns to default
+Remove a hook, journal.auto, or worktree.root soft-preference so it returns to default
 
 ### Synopsis
 
 What it does:
-  Delete a per-hook toggle or the journal.auto leaf from config.yaml so the value returns to its inherited or built-in default (journal.auto defaults to true). Removing an absent key is a no-op. Only keys under `hooks.` and the exact key `journal.auto` may be unset.
+  Delete a per-hook toggle, the journal.auto leaf, or the worktree.root leaf from config.yaml so the value returns to its inherited or built-in default (journal.auto defaults to true; worktree.root defaults to unset, so ak:worktree falls back to WORKTREE_ROOT / its built-in location chain). Removing an absent key is a no-op. Only keys under `hooks.`, the exact key `journal.auto`, and the exact key `worktree.root` may be unset.
 
 Who it's for:
   Power users cleaning up an explicit toggle they no longer want pinned.
@@ -23,6 +23,7 @@ Examples:
   ak config prefs unset hooks.simplify-gate
   ak config prefs unset hooks.simplify-gate --scope project
   ak config prefs unset journal.auto
+  ak config prefs unset worktree.root --scope project
 
 What changes on disk:
   Backs up then rewrites the selected scope's config.yaml when the key was present.
diff --git a/reference-raw/ak_orchestrate.mdx b/reference-raw/ak_orchestrate.mdx
new file mode 100644
index 0000000..6e50566
--- /dev/null
+++ b/reference-raw/ak_orchestrate.mdx
@@ -0,0 +1,62 @@
+---
+title: "ak orchestrate"
+description: "Run and supervise external CLI job graphs (Darwin only)"
+generated: true
+---
+
+## ak orchestrate
+
+Run and supervise external CLI job graphs (Darwin only)
+
+### Synopsis
+
+What it does:
+  Start, resume, check, and stop a graph of external CLI jobs under a dedicated local worker supervisor. The worker owns each job's process group, persists durable run state under AGENTKIT_HOME, and survives the launching client or coordinator exiting. `start` always creates a new run; only `resume <run-id>` continues an existing one. v1 supports darwin only — every other GOOS returns an explicit unsupported error.
+
+Who it's for:
+  The /ak:orchestrate skill's job-execution layer, and power devs scripting multi-job CLI runs directly.
+
+When to use it:
+  Use `ak orchestrate start` to launch a validated job graph. If a client or coordinator is interrupted, use `ak orchestrate status`/`stop` with the same run ID to reconnect to the still-running worker instead of guessing at orphaned processes.
+
+Examples:
+  ak orchestrate start jobs.json           # launch a new run, prints its run ID
+  ak orchestrate status &lt;run-id&gt;            # PID/PGID, heartbeat, last output, per-job state
+  ak orchestrate resume &lt;run-id&gt; jobs.json  # reconnect after a client/coordinator crash
+  ak orchestrate stop &lt;run-id&gt;               # TERM the group, grace period, then KILL
+  ak orchestrate start jobs.json --json      # scripted run-id + status envelope
+
+What changes on disk:
+  Writes run state, per-job output logs, and a control socket under AGENTKIT_HOME/orchestrate/runs/&lt;run-id&gt;/. Never persists prompts, raw command arguments, environment values, or secrets.
+
+Output modes:
+  pretty   default on TTY (colors, ASCII markers)
+  plain    auto when stdout piped or --no-interactive
+  json     --json (single-object envelope, NDJSON-safe)
+
+Exit codes:
+  0  success
+  1  runtime error
+  2  invalid flags
+  3  user-cancel (SIGINT, prompt-cancel)
+  1  runtime error (state I/O, launch/signal failure)
+  6  unsupported platform (v1 requires darwin)
+
+### Options
+
+```
+  -h, --help             help for orchestrate
+      --json             Emit machine-readable JSON (implies --no-interactive)
+      --no-interactive   Disable interactive prompts (CI-safe)
+  -q, --quiet            Suppress non-error output on stderr
+  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
+  -y, --yes              Assume yes for all prompts
+```
+
+### SEE ALSO
+
+* [ak](./ak)	 - AgentKit CLI
+* [ak orchestrate resume](./ak_orchestrate_resume)	 - Reconnect to an existing run after a client or coordinator crash
+* [ak orchestrate start](./ak_orchestrate_start)	 - Launch a new orchestrated run from a job graph file
+* [ak orchestrate status](./ak_orchestrate_status)	 - Report a run's current lifecycle state
+* [ak orchestrate stop](./ak_orchestrate_stop)	 - Terminate a run's live jobs (TERM, grace period, then KILL)
diff --git a/reference-raw/ak_orchestrate_resume.mdx b/reference-raw/ak_orchestrate_resume.mdx
new file mode 100644
index 0000000..b01d40e
--- /dev/null
+++ b/reference-raw/ak_orchestrate_resume.mdx
@@ -0,0 +1,59 @@
+---
+title: "ak orchestrate resume"
+description: "Reconnect to an existing run after a client or coordinator crash"
+generated: true
+---
+
+## ak orchestrate resume
+
+Reconnect to an existing run after a client or coordinator crash
+
+### Synopsis
+
+What it does:
+  Reconnect to run-id using the same job graph file that started it. If a live, verified worker is reachable, resume confirms the graph's digest still matches the running record and reports its current state — it never relaunches jobs or creates a second process tree. If the worker itself crashed, resume falls back to a read-only reclassification of the persisted record against a fresh identity probe; an adopted job whose original worker died mid-run stays orphaned for a human (or a fresh `start`) to act on rather than being silently continued.
+
+Who it's for:
+  Both power devs scripting crash recovery and the /ak:orchestrate skill reconnecting after an interrupted coordinator.
+
+When to use it:
+  After this terminal, its shell, or its coordinating process was interrupted or restarted while a run was in flight.
+
+Examples:
+  ak orchestrate resume 3f9a... jobs.json          # reconnect using the original job graph
+  ak orchestrate resume 3f9a... jobs.json --json    # scripted result envelope
+
+What changes on disk:
+  Read-only against a live worker; persists a reclassification of orphaned/unknown jobs when the worker crashed.
+
+Output modes:
+  pretty   default on TTY (colors, ASCII markers)
+  plain    auto when stdout piped or --no-interactive
+  json     --json (single-object envelope, NDJSON-safe)
+
+Exit codes:
+  0  success
+  1  runtime error
+  2  invalid flags
+  3  user-cancel (SIGINT, prompt-cancel)
+  1  job graph does not match the persisted run's launch digest, run not found, or state is corrupt/unsupported
+  6  unsupported platform (v1 requires darwin)
+
+```
+ak orchestrate resume <run-id> <job-graph.json> [flags]
+```
+
+### Options
+
+```
+  -h, --help             help for resume
+      --json             Emit machine-readable JSON (implies --no-interactive)
+      --no-interactive   Disable interactive prompts (CI-safe)
+  -q, --quiet            Suppress non-error output on stderr
+  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
+  -y, --yes              Assume yes for all prompts
+```
+
+### SEE ALSO
+
+* [ak orchestrate](./ak_orchestrate)	 - Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-raw/ak_orchestrate_start.mdx b/reference-raw/ak_orchestrate_start.mdx
new file mode 100644
index 0000000..f11d4ed
--- /dev/null
+++ b/reference-raw/ak_orchestrate_start.mdx
@@ -0,0 +1,59 @@
+---
+title: "ak orchestrate start"
+description: "Launch a new orchestrated run from a job graph file"
+generated: true
+---
+
+## ak orchestrate start
+
+Launch a new orchestrated run from a job graph file
+
+### Synopsis
+
+What it does:
+  Validate a job graph file, generate a fresh opaque run ID, and spawn a detached worker that owns every job's process group for that run. Blocks until the worker durably persists run state and proves readiness, then prints the run ID and initial status. `start` always creates a new run; retrying the same graph does not reuse an existing run ID.
+
+Who it's for:
+  The /ak:orchestrate skill's job-execution layer, and power devs scripting external CLI job graphs.
+
+When to use it:
+  When you have a validated job graph (id/command/args/work_dir/env/depends_on per job) ready to launch.
+
+Examples:
+  ak orchestrate start jobs.json          # launch, print run ID and initial status
+  ak orchestrate start jobs.json --json    # scripted run-id + status envelope
+
+What changes on disk:
+  Writes AGENTKIT_HOME/orchestrate/runs/&lt;run-id&gt;/ (state, per-job output logs, launch graph). Never persists prompts, raw argv, environment values, or secrets.
+
+Output modes:
+  pretty   default on TTY (colors, ASCII markers)
+  plain    auto when stdout piped or --no-interactive
+  json     --json (single-object envelope, NDJSON-safe)
+
+Exit codes:
+  0  success
+  1  runtime error
+  2  invalid flags
+  3  user-cancel (SIGINT, prompt-cancel)
+  1  job graph invalid, or the worker failed to reach readiness
+  6  unsupported platform (v1 requires darwin)
+
+```
+ak orchestrate start <job-graph.json> [flags]
+```
+
+### Options
+
+```
+  -h, --help             help for start
+      --json             Emit machine-readable JSON (implies --no-interactive)
+      --no-interactive   Disable interactive prompts (CI-safe)
+  -q, --quiet            Suppress non-error output on stderr
+  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
+  -y, --yes              Assume yes for all prompts
+```
+
+### SEE ALSO
+
+* [ak orchestrate](./ak_orchestrate)	 - Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-raw/ak_orchestrate_status.mdx b/reference-raw/ak_orchestrate_status.mdx
new file mode 100644
index 0000000..feb8221
--- /dev/null
+++ b/reference-raw/ak_orchestrate_status.mdx
@@ -0,0 +1,59 @@
+---
+title: "ak orchestrate status"
+description: "Report a run's current lifecycle state"
+generated: true
+---
+
+## ak orchestrate status
+
+Report a run's current lifecycle state
+
+### Synopsis
+
+What it does:
+  Reach the run's live worker through its verified control socket when reachable, otherwise reconcile persisted state against a fresh identity probe. Reports PID/PGID, heartbeat, last-output time, and a current-command label per job — a stale record alone is never reported as still running.
+
+Who it's for:
+  Both power devs polling in scripts (--json) and interactive checks after a client/coordinator crash.
+
+When to use it:
+  Checking on a run started earlier, including after this terminal or its coordinator was interrupted.
+
+Examples:
+  ak orchestrate status 3f9a...            # human-readable per-job table
+  ak orchestrate status 3f9a... --json      # scripted status envelope
+
+What changes on disk:
+  Read-only, except a fresh reclassification (e.g. worker crashed since the last check) is persisted.
+
+Output modes:
+  pretty   default on TTY (colors, ASCII markers)
+  plain    auto when stdout piped or --no-interactive
+  json     --json (single-object envelope, NDJSON-safe)
+
+Exit codes:
+  0  success
+  1  runtime error
+  2  invalid flags
+  3  user-cancel (SIGINT, prompt-cancel)
+  1  run ID not found, or run state is corrupt/unsupported
+  6  unsupported platform (v1 requires darwin)
+
+```
+ak orchestrate status <run-id> [flags]
+```
+
+### Options
+
+```
+  -h, --help             help for status
+      --json             Emit machine-readable JSON (implies --no-interactive)
+      --no-interactive   Disable interactive prompts (CI-safe)
+  -q, --quiet            Suppress non-error output on stderr
+  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
+  -y, --yes              Assume yes for all prompts
+```
+
+### SEE ALSO
+
+* [ak orchestrate](./ak_orchestrate)	 - Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-raw/ak_orchestrate_stop.mdx b/reference-raw/ak_orchestrate_stop.mdx
new file mode 100644
index 0000000..05ff757
--- /dev/null
+++ b/reference-raw/ak_orchestrate_stop.mdx
@@ -0,0 +1,59 @@
+---
+title: "ak orchestrate stop"
+description: "Terminate a run's live jobs (TERM, grace period, then KILL)"
+generated: true
+---
+
+## ak orchestrate stop
+
+Terminate a run's live jobs (TERM, grace period, then KILL)
+
+### Synopsis
+
+What it does:
+  Send SIGTERM to every signal-authorized job in the run's verified process group through the worker's control socket, wait a bounded grace period, then SIGKILL only a job whose group is still alive under the same verified identity. Never falls back to signalling from persisted state: if no live, verified worker is reachable, this command reports that instead of guessing a kill target.
+
+Who it's for:
+  Both power devs scripting cancellation and interactive use after `status` shows a run is no longer needed.
+
+When to use it:
+  Cancelling a run explicitly, or cleaning up before starting a replacement.
+
+Examples:
+  ak orchestrate stop 3f9a...          # TERM, grace period, then KILL if still alive
+  ak orchestrate stop 3f9a... --json    # scripted result envelope
+
+What changes on disk:
+  Persists the stop request and its outcome to the run's state file.
+
+Output modes:
+  pretty   default on TTY (colors, ASCII markers)
+  plain    auto when stdout piped or --no-interactive
+  json     --json (single-object envelope, NDJSON-safe)
+
+Exit codes:
+  0  success
+  1  runtime error
+  2  invalid flags
+  3  user-cancel (SIGINT, prompt-cancel)
+  1  no live, verified worker reachable for this run, or the stop failed
+  6  unsupported platform (v1 requires darwin)
+
+```
+ak orchestrate stop <run-id> [flags]
+```
+
+### Options
+
+```
+  -h, --help             help for stop
+      --json             Emit machine-readable JSON (implies --no-interactive)
+      --no-interactive   Disable interactive prompts (CI-safe)
+  -q, --quiet            Suppress non-error output on stderr
+  -V, --verbose          Extra diagnostic output on stderr (loses to --quiet)
+  -y, --yes              Assume yes for all prompts
+```
+
+### SEE ALSO
+
+* [ak orchestrate](./ak_orchestrate)	 - Run and supervise external CLI job graphs (Darwin only)
diff --git a/reference-raw/index.mdx b/reference-raw/index.mdx
index 096078f..5731ead 100644
--- a/reference-raw/index.mdx
+++ b/reference-raw/index.mdx
@@ -110,6 +110,11 @@ Generated reference for every released `ak` command.
 - [ak migrate prefs](./ak_migrate_prefs)
 - [ak migrate rollback](./ak_migrate_rollback)
 - [ak new](./ak_new)
+- [ak orchestrate](./ak_orchestrate)
+- [ak orchestrate resume](./ak_orchestrate_resume)
+- [ak orchestrate start](./ak_orchestrate_start)
+- [ak orchestrate status](./ak_orchestrate_status)
+- [ak orchestrate stop](./ak_orchestrate_stop)
 - [ak plan](./ak_plan)
 - [ak plan add-phase](./ak_plan_add-phase)
 - [ak plan archive](./ak_plan_archive)
diff --git a/scripts/channel-route-href.test.mjs b/scripts/channel-route-href.test.mjs
new file mode 100644
index 0000000..50f8d3d
--- /dev/null
+++ b/scripts/channel-route-href.test.mjs
@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  channelRouteHref,
+  unavailableChannelUrls,
+} from '../lib/channel-route-href.mjs';
+
+test('keeps the same route when it exists in the target channel', () => {
+  assert.equal(
+    channelRouteHref('en', 'stable', ['reference', 'cli'], true),
+    '/en/stable/reference/cli',
+  );
+});
+
+test('falls back to the target channel root for a channel-only route', () => {
+  assert.equal(
+    channelRouteHref('vi', 'stable', ['reference', 'cli', 'orchestrate'], false),
+    '/vi/stable',
+  );
+});
+
+test('decodes static route segments before building the target href', () => {
+  assert.equal(
+    channelRouteHref('en', 'stable', ['guides', 'hello%20world'], true),
+    '/en/stable/guides/hello world',
+  );
+});
+
+test('lists only channel counterpart URLs that do not exist', () => {
+  assert.deepEqual(
+    unavailableChannelUrls([
+      '/en/stable',
+      '/en/beta',
+      '/en/stable/reference/cli',
+      '/en/beta/reference/cli',
+      '/en/beta/reference/cli/orchestrate',
+    ]),
+    ['/en/stable/reference/cli/orchestrate'],
+  );
+});
diff --git a/scripts/cli-reference-routes.test.mjs b/scripts/cli-reference-routes.test.mjs
index 5a0e485..294c448 100644
--- a/scripts/cli-reference-routes.test.mjs
+++ b/scripts/cli-reference-routes.test.mjs
@@ -46,25 +46,43 @@ function inventory(channel, locale) {
   });
 }
 
-test('publishes 165 unique nested authored routes with full channel/locale parity', () => {
+test('publishes unique nested authored routes with EN+VI parity per channel and beta ⊇ stable', () => {
+  // Expected counts: stable = channels.stable.tag surface; beta = stable + any
+  // new command groups authored ahead of the next stable promote. Beta must
+  // strictly contain every stable route so promotion is a safe whole-copy;
+  // beta-only routes are the delta the next promote will publish.
+  const expected = {
+    stable: 165,
+    beta: 170,
+  };
   const shapes = new Map();
   for (const channel of channels) {
+    const channelExpected = expected[channel];
     for (const locale of locales) {
       const pages = inventory(channel, locale);
       const routes = pages.map((page) => page.slugs.slice(1).join('/'));
-      assert.equal(pages.length, 165, `${channel}/${locale} authored page count`);
-      assert.equal(new Set(routes).size, 165, `${channel}/${locale} route collisions`);
+      assert.equal(pages.length, channelExpected, `${channel}/${locale} authored page count`);
+      assert.equal(new Set(routes).size, channelExpected, `${channel}/${locale} route collisions`);
       assert.ok(routes.every((route) => !/[\s]|%20/i.test(route)));
       shapes.set(`${channel}/${locale}`, routes.sort());
     }
   }
 
-  const expected = shapes.get('stable/en');
-  for (const shape of shapes.values()) assert.deepEqual(shape, expected);
-  assert.ok(expected.includes('reference/cli'));
-  assert.ok(expected.includes('reference/cli/agents'));
-  assert.ok(expected.includes('reference/cli/agents/install'));
-  assert.ok(expected.includes('reference/cli/config/prefs/set'));
+  // EN and VI must match within each channel (locale parity).
+  assert.deepEqual(shapes.get('stable/vi'), shapes.get('stable/en'), 'stable EN/VI parity');
+  assert.deepEqual(shapes.get('beta/vi'), shapes.get('beta/en'), 'beta EN/VI parity');
+
+  // Beta must be a strict superset of stable (contains every stable route).
+  const stableRoutes = new Set(shapes.get('stable/en'));
+  const betaRoutes = new Set(shapes.get('beta/en'));
+  const missing = [...stableRoutes].filter((route) => !betaRoutes.has(route));
+  assert.deepEqual(missing, [], 'stable routes missing from beta');
+
+  const stable = shapes.get('stable/en');
+  assert.ok(stable.includes('reference/cli'));
+  assert.ok(stable.includes('reference/cli/agents'));
+  assert.ok(stable.includes('reference/cli/agents/install'));
+  assert.ok(stable.includes('reference/cli/config/prefs/set'));
 });
 
 test('title segments match nested filesystem paths', () => {
diff --git a/scripts/release-quality-metrics.mjs b/scripts/release-quality-metrics.mjs
index 56be0fb..eae2df5 100644
--- a/scripts/release-quality-metrics.mjs
+++ b/scripts/release-quality-metrics.mjs
@@ -20,8 +20,8 @@ import { collectPublishedChannelRoutes, inspectReleaseShape } from './release-qu
 
 export const RELEASE_QUALITY_BASELINE = Object.freeze({
   schemaVersion: 1,
-  reviewedAt: '2026-08-08',
-  sourceCommit: 'd77ca2667090b311b3ac2650852ede002b6bc338',
+  reviewedAt: '2026-08-13',
+  sourceCommit: 'e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2',
   channels: ['beta', 'stable'],
   locales: ['en', 'vi'],
   deterministic: {
@@ -31,7 +31,9 @@ export const RELEASE_QUALITY_BASELINE = Object.freeze({
     fileCountBudget: 23_154,
     searchBytes: 20_067_964,
     searchBudgetBytes: SEARCH_ASSET_BUDGET_BYTES,
-    searchPagesPerLocaleChannel: 391,
+    // Per-channel: stable stays bound to channels.stable.tag; beta may include
+    // pages authored ahead of the next stable promote.
+    searchPagesPerLocaleChannel: { stable: 391, beta: 396 },
     reviewedSearchOutsideChannelRoutes: ['_showcase'],
     reviewedSearchExcludedPublishedRoutes: ['reference/cli/ak'],
     maxAssetBytesExclusive: MAX_ASSET_BYTES,
@@ -140,8 +142,9 @@ function searchPageShape(exported, baseline, publishedRoutes) {
     }
     for (const channel of ['beta', 'stable']) {
       const count = routes[locale][channel].size;
-      if (count !== baseline.deterministic.searchPagesPerLocaleChannel) {
-        errors.push(`${locale}/${channel}: searchable page count ${count} does not match reviewed baseline ${baseline.deterministic.searchPagesPerLocaleChannel}`);
+      const expectedCount = baseline.deterministic.searchPagesPerLocaleChannel[channel];
+      if (count !== expectedCount) {
+        errors.push(`${locale}/${channel}: searchable page count ${count} does not match reviewed baseline ${expectedCount}`);
       }
       const expectedSearchRoutes = new Set(publishedRoutes[locale][channel]);
       for (const route of baseline.deterministic.reviewedSearchExcludedPublishedRoutes) {
@@ -162,7 +165,12 @@ function searchPageShape(exported, baseline, publishedRoutes) {
       new Set(baseline.deterministic.reviewedSearchOutsideChannelRoutes),
       outside[locale],
     );
-    addSetDifference(errors, `${locale} Beta/Stable searchable route parity`, routes[locale].beta, routes[locale].stable);
+    addMissingSubset(
+      errors,
+      `${locale} stable ⊆ beta searchable route shape`,
+      routes[locale].stable,
+      routes[locale].beta,
+    );
   }
   const [referenceLocale, ...otherLocales] = baseline.locales ?? ['en', 'vi'];
   for (const locale of otherLocales) {
@@ -194,6 +202,11 @@ function addSetDifference(errors, label, expected, actual) {
   if (missing.length || extra.length) errors.push(`${label}: missing [${missing.join(', ')}]; extra [${extra.join(', ')}]`);
 }
 
+function addMissingSubset(errors, label, expected, actual) {
+  const missing = [...expected].filter((value) => !actual.has(value)).sort();
+  if (missing.length) errors.push(`${label}: missing [${missing.join(', ')}]`);
+}
+
 export async function checkFixedQueries(searchPath, queries) {
   const { databases } = await loadSearchDatabases(searchPath);
   return queryReports(databases, queries);
diff --git a/scripts/release-quality-shape.mjs b/scripts/release-quality-shape.mjs
index 498f8f8..8da9b9b 100644
--- a/scripts/release-quality-shape.mjs
+++ b/scripts/release-quality-shape.mjs
@@ -8,12 +8,15 @@ import { repoRoot } from './lib/paths.mjs';
 
 export const RELEASE_SHAPE_BASELINE = Object.freeze({
   schemaVersion: 1,
-  reviewedAt: '2026-08-09',
-  sourceCommit: '85d343811d16d653bafd060a03ac755e09a51fc0',
+  reviewedAt: '2026-08-13',
+  sourceCommit: 'e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2',
   channels: ['beta', 'stable'],
   locales: ['en', 'vi'],
-  sourceRoutesPerLocaleChannel: 393,
-  routesPerLocaleChannel: 392,
+  // Per-channel: stable stays bound to channels.stable.tag; beta may include
+  // routes authored ahead of the next stable promote. Beta must remain a
+  // superset of stable so a whole-copy promote is safe.
+  sourceRoutesPerLocaleChannel: { stable: 393, beta: 398 },
+  routesPerLocaleChannel: { stable: 392, beta: 397 },
   reviewedSourceOnlyRoutes: [
     {
       route: 'changelog',
@@ -63,6 +66,17 @@ function addSetDifference(errors, label, expected, actual) {
   }
 }
 
+// Assert `actual` contains every value in `expected` (i.e., actual ⊇ expected).
+// Extra values in `actual` are allowed. Used for cross-channel comparison where
+// beta may include routes authored ahead of the next stable promote but must
+// still contain every stable route so a whole-copy promote is safe.
+function addMissingSubset(errors, label, expected, actual) {
+  const missing = sorted([...expected].filter((value) => !actual.has(value)));
+  if (missing.length) {
+    errors.push(`${label}: missing [${missing.join(', ')}]`);
+  }
+}
+
 async function collectMdx(directory, root = directory, files = []) {
   for (const entry of await readdir(directory, { withFileTypes: true })) {
     const path = join(directory, entry.name);
@@ -204,12 +218,14 @@ export async function inspectReleaseShape({
     }
     for (const locale of baseline.locales) {
       const sourceCount = observations[channel].sourceRoutes[locale].size;
-      if (sourceCount !== baseline.sourceRoutesPerLocaleChannel) {
-        errors.push(`${channel}/${locale}: source route count ${sourceCount} does not match reviewed baseline ${baseline.sourceRoutesPerLocaleChannel}`);
+      const expectedSourceCount = baseline.sourceRoutesPerLocaleChannel[channel];
+      if (sourceCount !== expectedSourceCount) {
+        errors.push(`${channel}/${locale}: source route count ${sourceCount} does not match reviewed baseline ${expectedSourceCount}`);
       }
       const count = observations[channel].routes[locale].size;
-      if (count !== baseline.routesPerLocaleChannel) {
-        errors.push(`${channel}/${locale}: route count ${count} does not match reviewed baseline ${baseline.routesPerLocaleChannel}`);
+      const expectedCount = baseline.routesPerLocaleChannel[channel];
+      if (count !== expectedCount) {
+        errors.push(`${channel}/${locale}: route count ${count} does not match reviewed baseline ${expectedCount}`);
       }
 
       const sourceOnly = new Set(
@@ -235,24 +251,25 @@ export async function inspectReleaseShape({
     }
   }
 
-  const referenceChannel = observations[baseline.channels[0]];
-  if (referenceChannel) {
-    for (const channel of baseline.channels.slice(1)) {
-      if (!observations[channel]) continue;
-      for (const locale of baseline.locales) {
-        addSetDifference(
-          errors,
-          `${baseline.channels[0]}/${channel} ${locale} source route shape`,
-          referenceChannel.sourceRoutes[locale],
-          observations[channel].sourceRoutes[locale],
-        );
-        addSetDifference(
-          errors,
-          `${baseline.channels[0]}/${channel} ${locale} route shape`,
-          referenceChannel.routes[locale],
-          observations[channel].routes[locale],
-        );
-      }
+  // Cross-channel guarantee: every stable route must exist in beta so a
+  // whole-copy promote stays safe. Extra beta-only routes (features authored
+  // ahead of the next promote) are allowed.
+  const stableChannel = observations.stable;
+  const betaChannel = observations.beta;
+  if (stableChannel && betaChannel) {
+    for (const locale of baseline.locales) {
+      addMissingSubset(
+        errors,
+        `stable ⊆ beta ${locale} source route shape`,
+        stableChannel.sourceRoutes[locale],
+        betaChannel.sourceRoutes[locale],
+      );
+      addMissingSubset(
+        errors,
+        `stable ⊆ beta ${locale} route shape`,
+        stableChannel.routes[locale],
+        betaChannel.routes[locale],
+      );
     }
   }
 
@@ -309,7 +326,7 @@ async function main() {
     for (const [channel, locales] of Object.entries(report.channels)) {
       console.log(`${channel}: ${Object.entries(locales).map(([locale, count]) => `${locale}=${count}`).join(', ')}`);
     }
-    console.log(`source routes per locale/channel: ${report.baseline.sourceRoutesPerLocaleChannel}`);
+    console.log(`source routes per locale/channel: ${JSON.stringify(report.baseline.sourceRoutesPerLocaleChannel)}`);
     console.log(`reviewed locale variants: ${report.reviewedVariants.length}`);
     console.log('release-quality-shape: route parity OK.');
   }
diff --git a/scripts/release-quality.test.mjs b/scripts/release-quality.test.mjs
index 96b5aef..a03c8e5 100644
--- a/scripts/release-quality.test.mjs
+++ b/scripts/release-quality.test.mjs
@@ -32,8 +32,8 @@ function shapeBaseline(overrides = {}) {
     sourceCommit: 'fixture',
     channels: ['beta', 'stable'],
     locales: ['en', 'vi'],
-    sourceRoutesPerLocaleChannel: 2,
-    routesPerLocaleChannel: 2,
+    sourceRoutesPerLocaleChannel: { stable: 2, beta: 2 },
+    routesPerLocaleChannel: { stable: 2, beta: 2 },
     reviewedSourceOnlyRoutes: [],
     reviewedGeneratedRoutes: [],
     reviewedVariants: [
@@ -78,7 +78,7 @@ function searchDocument(locale, route, title) {
   };
 }
 
-async function serializedSearchData() {
+async function serializedSearchData(routesByChannel) {
   const data = {};
   for (const [locale, title] of [['en', 'Installation'], ['vi', 'Cài đặt']]) {
     const database = create({
@@ -93,27 +93,39 @@ async function serializedSearchData() {
       },
       language: 'english',
     });
-    await insertMultiple(database, ['beta', 'stable'].map((channel) => {
-      const route = `/${locale}/${channel}/installation`;
-      return searchDocument(locale, route, title);
+    const routes = [
+      ['beta', 'installation'],
+      ['stable', 'installation'],
+      ...routesByChannel.beta.filter((route) => route !== 'installation').map((route) => ['beta', route]),
+      ...routesByChannel.stable.filter((route) => route !== 'installation').map((route) => ['stable', route]),
+    ];
+    await insertMultiple(database, routes.map(([channel, route]) => {
+      const url = `/${locale}/${channel}/${route}`;
+      return searchDocument(locale, url, route === 'installation' ? title : route);
     }));
     data[locale] = { type: 'advanced', ...save(database) };
   }
   return JSON.stringify({ type: 'i18n', data });
 }
 
-async function makeMetricFixture() {
+async function makeMetricFixture({ betaOnlyRoutes = [], stableOnlyRoutes = [] } = {}) {
   const root = await temporaryRoot('ak-release-metrics-');
   const outDir = join(root, 'out');
+  const routesByChannel = {
+    beta: ['installation', ...betaOnlyRoutes],
+    stable: ['installation', ...stableOnlyRoutes],
+  };
   const htmlPaths = [];
   for (const locale of ['en', 'vi']) {
     for (const channel of ['beta', 'stable']) {
-      const htmlPath = join(outDir, locale, channel, 'installation.html');
-      await write(htmlPath, '<h1>Installation</h1>');
-      htmlPaths.push(htmlPath);
+      for (const route of routesByChannel[channel]) {
+        const htmlPath = join(outDir, locale, channel, `${route}.html`);
+        await write(htmlPath, `<h1>${route}</h1>`);
+        htmlPaths.push(htmlPath);
+      }
     }
   }
-  const searchBody = await serializedSearchData();
+  const searchBody = await serializedSearchData(routesByChannel);
   await write(join(outDir, 'api', 'search'), searchBody);
   const searchBytes = (await stat(join(outDir, 'api', 'search'))).size;
   const htmlBytes = (await Promise.all(htmlPaths.map((htmlPath) => stat(htmlPath))))
@@ -125,11 +137,14 @@ async function makeMetricFixture() {
     deterministic: {
       outputBytes: searchBytes + htmlBytes,
       outputBudgetBytes: searchBytes + htmlBytes + 100,
-      fileCount: 5,
-      fileCountBudget: 6,
+      fileCount: htmlPaths.length + 1,
+      fileCountBudget: htmlPaths.length + 2,
       searchBytes,
       searchBudgetBytes: searchBytes + 10,
-      searchPagesPerLocaleChannel: 1,
+      searchPagesPerLocaleChannel: {
+        stable: routesByChannel.stable.length,
+        beta: routesByChannel.beta.length,
+      },
       reviewedSearchOutsideChannelRoutes: [],
       reviewedSearchExcludedPublishedRoutes: [],
       maxAssetBytesExclusive: searchBytes + 10,
@@ -177,7 +192,7 @@ test('rejects Stable and Beta route divergence', async () => {
 
 test('rejects authored routes that silently disappear from every built locale and channel', async () => {
   const fixture = await makeShapeFixture();
-  fixture.baseline.sourceRoutesPerLocaleChannel = 3;
+  fixture.baseline.sourceRoutesPerLocaleChannel = { stable: 3, beta: 3 };
   for (const channel of ['beta', 'stable']) {
     await write(join(fixture.docsRoot, channel, 'orphan.en.mdx'));
     await write(join(fixture.docsRoot, channel, 'orphan.vi.mdx'));
@@ -192,6 +207,23 @@ test('checks deterministic output budgets and fixed top-five relevance', async (
   assert.deepEqual(report.relevance.map((entry) => entry.rank), [2, 2]);
 });
 
+test('allows searchable routes authored only in beta', async () => {
+  const fixture = await makeMetricFixture({ betaOnlyRoutes: ['reference/beta-only'] });
+  const report = await inspectReleaseMetrics(fixture);
+  assert.deepEqual(report.searchShape.pages, {
+    en: { beta: 2, stable: 1 },
+    vi: { beta: 2, stable: 1 },
+  });
+});
+
+test('rejects searchable stable routes that are missing from beta', async () => {
+  const fixture = await makeMetricFixture({ stableOnlyRoutes: ['reference/stable-only'] });
+  await assert.rejects(
+    () => inspectReleaseMetrics(fixture),
+    /stable ⊆ beta searchable route shape: missing \[reference\/stable-only\]/,
+  );
+});
+
 test('rejects output growth beyond the reviewed deterministic budget', async () => {
   const fixture = await makeMetricFixture();
   fixture.baseline.deterministic.outputBudgetBytes = 1;

From 1317da8e4413605cae56f43d649efa60244987a2 Mon Sep 17 00:00:00 2001
From: Thieu Nguyen <79964592+thieung@users.noreply.github.com>
Date: Thu, 13 Aug 2026 17:41:21 +0700
Subject: [PATCH 2/3] docs: align release channel contract (#64)

---
 .agents/skills/ak-docs-release-audit/SKILL.md | 14 ++++--
 .agents/skills/ak-release-update/SKILL.md     | 15 ++++--
 AGENTS.md                                     | 11 +++--
 CLAUDE.md                                     |  8 ++--
 docs/workflows/post-launch-operations.md      | 48 +++++++------------
 docs/workflows/release-and-deploy.md          | 32 ++++++++-----
 6 files changed, 71 insertions(+), 57 deletions(-)

diff --git a/.agents/skills/ak-docs-release-audit/SKILL.md b/.agents/skills/ak-docs-release-audit/SKILL.md
index 97888ac..7b52db9 100644
--- a/.agents/skills/ak-docs-release-audit/SKILL.md
+++ b/.agents/skills/ak-docs-release-audit/SKILL.md
@@ -43,11 +43,15 @@ outside its evidence and need matched manual passes on the same Beta PR:
   `agentkit-kit-<kit>-<runtime>-<tag>.tar.gz` and comparing per-skill
   `SKILL.md` frontmatter (`user-invocable`, `disable-model-invocation`).
   Refresh `kit-catalog-identities.json`, add public skill pages EN+VI,
-  update `skills/meta.{json,vi.json}` and skill index tables, bump the
-  Kit overview `| Skills | N |` count. Mirror into
-  `content/docs/stable/**` so the tree stays whole-copy-ready for the
-  next promotion. `disable-model-invocation: true` without
-  `user-invocable: true` stays `internal` (no public page). Identity
+  update `skills/meta.{json,vi.json}` and skill index tables, and bump the
+  Kit overview `| Skills | N |` count in Beta only. Keep EN/VI route parity
+  inside Beta, but do not mirror Beta-only pages or prose into
+  `content/docs/stable/**`; Stable remains bound to `channels.stable.tag`
+  until a reviewed whole-copy promotion. The current `check:catalog` guard
+  still assumes identical Kit routes and counts across channels; if a
+  legitimate Beta-only Kit addition trips it, stop and fix the guard contract
+  rather than copying the addition into Stable. `disable-model-invocation:
+  true` without `user-invocable: true` stays `internal` (no public page). Identity
   checks alone miss body drift (existing pages that advertise a retired
   form when SKILL.md prose, `.env.example`, or `skill.yaml` change with
   identity stable). Run the body-diff pass in
diff --git a/.agents/skills/ak-release-update/SKILL.md b/.agents/skills/ak-release-update/SKILL.md
index bd7f347..2272772 100644
--- a/.agents/skills/ak-release-update/SKILL.md
+++ b/.agents/skills/ak-release-update/SKILL.md
@@ -69,8 +69,8 @@ examples, and error paths.
    impact-map returns `paths: []`). Await the exact statement
    `approve REQ-…`.
 5. **Handle contract v1 blind spots.** Run the manual passes in one PR:
-   - **CLI prose** — V1 authoring inside the approved paths only.
-   - **Kits** — diff kit tar bundles, author public skill pages EN+VI,
+   - **CLI prose** — V1 authoring inside the approved Beta paths only.
+   - **Kits** — diff kit tar bundles, author public Beta skill pages EN+VI,
      refresh `kit-catalog-identities.json`, update meta and skill index.
      See [`references/default-tab-detection.md`](references/default-tab-detection.md)
      for the diff-first classification. Also run the body-diff pass in
@@ -78,7 +78,12 @@ examples, and error paths.
      [`references/kit-prose-drift.md`](../ak-docs-release-audit/references/kit-prose-drift.md)
      against existing kit skill pages — identity checks miss prose drift
      when a skill's SKILL.md body, `.env.example`, or `skill.yaml`
-     changes while frontmatter stays stable.
+     changes while frontmatter stays stable. Do not copy Beta-only Kit or
+     CLI changes into Stable; `stable ⊆ beta` is the cross-channel contract,
+     and Stable changes only through promotion. The current `check:catalog`
+     guard still assumes identical Kit routes and counts across channels; if a
+     Beta-only Kit addition trips it, fix that guard contract instead of
+     mirroring the addition into Stable.
    - **Desktop** — Layer A bump automatically; Layer B semi-auto with
      owner gate; Layer C deferred. See
      [`references/desktop-3-layer.md`](references/desktop-3-layer.md).
@@ -95,6 +100,10 @@ examples, and error paths.
      stable/desktop-app reflects the stable build, not the beta build.
    Skip if the run does not target that channel.
 7. **Validate, commit, and open PR.**
+   Preserve exact EN/VI source, published, and searchable route parity within
+   each channel and `stable ⊆ beta` across channels. Per-channel route and search counts may differ when Beta contains
+   features awaiting promotion; update reviewed baselines only from a fresh
+   build, never by copying those features into Stable.
    Run `pnpm install --frozen-lockfile`, `test`, `typecheck`, `lint`,
    `check:catalog`, `check:reference`, `build`, `check:quality`,
    `check:assets`, `check:links`. Commit per pass with descriptive
diff --git a/AGENTS.md b/AGENTS.md
index 23968a6..8047bb6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -59,10 +59,13 @@ continuous with the marketing site. Do **not** invent colours, fonts, or radii.
 ## Content structure
 
 - **Two channels:** `content/docs/stable/` and `content/docs/beta/` are Fumadocs
-  root folders (`meta.json` `"root": true`) rendered as Sidebar Tabs. Their page
-  trees must stay **identical in shape** — promotion is a whole-copy, so any
-  asymmetry breaks it. Content is equal at launch and diverges only when the
-  release-sync pipeline writes into a channel.
+  root folders (`meta.json` `"root": true`) rendered as Sidebar Tabs. Within
+  each channel, EN and VI must publish the same route shape. Across channels,
+  Stable must remain a subset of Beta; Beta may add routes and prose ahead of
+  the next promotion. Never mirror Beta-only content into `stable/` to satisfy
+  parity checks — Stable changes only through the whole-copy promotion pipeline.
+  The executable contract lives in `scripts/release-quality-shape.mjs`,
+  `scripts/release-quality-metrics.mjs`, and the route tests.
 - **Bilingual:** Fumadocs i18n (`lib/i18n.ts`), locales `en` (default) + `vi`,
   URL-prefixed (`/en`, `/vi`). Files use `.en.mdx` / `.vi.mdx`; nav labels use
   `meta.json` + `meta.vi.json`. A missing `.vi.mdx` falls back to English
diff --git a/CLAUDE.md b/CLAUDE.md
index 041455e..aa23e99 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -24,6 +24,8 @@ Checked out as siblings of this repo (paths relative to the repo root):
 - Screenshots for those pages live in `public/gui/`; see
   [`public/gui/README.md`](./public/gui/README.md) for the capture and
   optimization manifest.
-- `stable` is machine-generated from `beta` by the promotion pipeline, so keep
-  new docs channel-neutral (relative links only) and keep the two channels
-  byte-identical for any page authored in both.
+- `stable` is machine-generated from an exact `beta` snapshot by the promotion
+  pipeline. Keep new docs channel-neutral (relative links only), author release
+  updates in Beta, and let Stable change only through reviewed whole-copy
+  promotion. EN and VI keep the same route shape within each channel; Beta may
+  contain routes and prose that Stable has not promoted yet.
diff --git a/docs/workflows/post-launch-operations.md b/docs/workflows/post-launch-operations.md
index bf23dcd..5c42c6b 100644
--- a/docs/workflows/post-launch-operations.md
+++ b/docs/workflows/post-launch-operations.md
@@ -40,37 +40,23 @@ as a deterministic gate.
 
 ## Committed baseline and budgets
 
-The baseline is committed in `scripts/release-quality-metrics.mjs` and
-`scripts/release-quality-shape.mjs`. Changing a baseline is a reviewed decision,
-not an automatic response to a red check.
-
-| Signal | Reviewed baseline | Gate |
-| --- | ---: | ---: |
-| Published routes per locale/channel | 377 | Exact |
-| Output files | 18,290 | 22,863 reviewed budget; Cloudflare hard limit remains below 100,000 |
-| Total `out/` bytes | 2,251,685,582 | 2,814,606,978 (+25%) |
-| Search bytes | 19,911,284 | 23,068,672 (22 MiB) |
-| Largest individual asset | Search, 19,911,284 bytes | Strictly below 26,214,400 (25 MiB) |
-
-The route guard compares exact EN/VI and Stable/Beta published route sets. Its
-source-to-output contract also requires exactly 378 authored routes and reviews
-the only two source-only routes: `changelog` (navigation data) and
-`reference/release-notes` (composed release data). Its reviewed non-native and
-generated classifications are:
-
-- `reference/cli-conventions`: channel-neutral English source with an explicit
-  Vietnamese body;
-- `reference/cli/ak`: generated legacy redirect in both locales.
-
-There are no live English-body fallbacks in the published matrix. A future
-missing Vietnamese body becomes an unclassified `english-fallback` and fails
-CI until a reviewer approves the exception and verifies that the page discloses
-the fallback. This prevents silent language fallback.
-
-The search index must contain exactly 376 page routes in each EN/VI and
-Beta/Stable partition, with exact route parity and an exact match to published
-routes after removing the reviewed generated redirect. The only reviewed
-searchable page outside a channel is `/_showcase`.
+The executable baselines live in `scripts/release-quality-shape.mjs` and
+`scripts/release-quality-metrics.mjs`; use `quality:receipt` to record their
+current values. Changing a count, budget, exclusion, or reviewed variant is a
+reviewed decision, not an automatic response to a red check.
+
+The shape gate requires exact EN/VI source and published-route parity within
+each channel. Across channels, every Stable route must exist in Beta, while Beta
+may contain additional routes awaiting promotion. The same `stable ⊆ beta`
+invariant applies to searchable routes. Search still requires exact EN/VI
+parity within each channel and an exact match between published and searchable
+routes after the reviewed exclusions.
+
+Reviewed source-only routes, generated routes, locale variants, out-of-channel
+search pages, output budgets, and Cloudflare limits are declared beside their
+checks in those scripts. Do not copy Beta-only content into Stable to make a
+count or parity check pass; fix the contract defect or update the reviewed
+per-channel baseline from a fresh build.
 
 ### Fixed search relevance
 
diff --git a/docs/workflows/release-and-deploy.md b/docs/workflows/release-and-deploy.md
index 69d1884..6dc6606 100644
--- a/docs/workflows/release-and-deploy.md
+++ b/docs/workflows/release-and-deploy.md
@@ -67,9 +67,15 @@ content.
 
 Re-running the same bundle/tag is **idempotent**.
 
+A Beta sync may publish routes that do not yet exist in Stable. EN and VI must
+keep identical source, published, and searchable route sets within each
+channel, while every Stable route in those sets must still exist in Beta. The quality gates in
+`scripts/release-quality-shape.mjs`, `scripts/release-quality-metrics.mjs`, and
+the route tests enforce this `stable ⊆ beta` contract.
+
 ### What Beta sync does *not* refresh
 
-`sync-release.mjs` is scoped to what the docs-bundle carries. Two surfaces
+`sync-release.mjs` is scoped to what the docs-bundle carries. Three surfaces
 drift silently across releases and need their own manual passes on the same
 Beta PR (or an immediate follow-up):
 
@@ -113,16 +119,20 @@ Beta PR (or an immediate follow-up):
    `skills/meta.{json,vi.json}` and `skills/index.{en,vi}.mdx`, refresh
    `kit-catalog-identities.json` (evidence anchor + bundle SHA256 + new
    identity entries), and bump the Kit overview `| Skills | N |` count in
-   `content/docs/beta/kits/{engineer,marketing}.{en,vi}.mdx`. Mirror the same
-   additions into `content/docs/stable/**` so the tree stays whole-copy-ready
-   for the next promotion. Skills marked `disable-model-invocation: true`
-   without `user-invocable: true` (for example `ak-common`) stay classified
-   `internal` in the catalog and get no public page.
-
-   The `check:catalog` guard reads the frozen catalog as ground truth, so it
-   only fails when docs and catalog disagree. It does not detect upstream
-   drift on its own — refresh the catalog against the new bundle first, then
-   let the guard verify the docs match.
+   `content/docs/beta/kits/{engineer,marketing}.{en,vi}.mdx`. Keep EN/VI route
+   parity inside Beta, but do not copy new pages or prose into
+   `content/docs/stable/**`. Stable remains bound to its recorded tag until the
+   reviewed whole-copy promotion consumes the exact Beta snapshot. Skills marked
+   `disable-model-invocation: true` without `user-invocable: true` (for example
+   `ak-common`) stay classified `internal` in the catalog and get no public page.
+
+   The current `check:catalog` guard reads one frozen catalog for both channels
+   and still requires identical Beta/Stable Kit routes, navigation, and overview
+   counts. Until that guard gains per-channel catalog state and `stable ⊆ beta`
+   checks, a legitimate Beta-only Kit addition will fail it. Stop and fix that
+   guard contract; never copy the new Kit page or count into Stable to obtain a
+   green check. The guard also does not detect upstream drift on its own — its
+   catalog evidence must first be refreshed against the new bundle.
 
 3. **Desktop App section.** `content/docs/beta/desktop-app/**` describes
    product-state for a specific Desktop release: artifact filenames, sizes,

From 50395b43476973e171a0ea0f8b9a4a6c5f24b52b Mon Sep 17 00:00:00 2001
From: Thieu Nguyen <79964592+thieung@users.noreply.github.com>
Date: Thu, 13 Aug 2026 17:56:04 +0700
Subject: [PATCH 3/3] docs(troubleshooting): add Grok Claude-compat Hook
 workaround (#63)

* docs(troubleshooting): add Grok Claude-compat Hook workaround

Document how to disable Claude hook scanning and use ~/.grok/hooks until AgentKit folds global settings commands. Do not recommend editing AgentKit-managed settings.json.

* docs: bump release-quality baselines for grok-hooks page

The new troubleshooting route is published on beta and stable, EN+VI.
Bump reviewed source/built/search counts by one per channel so
check:quality:shape matches the authored tree.
---
 .../beta/troubleshooting/configuration.en.mdx |   1 +
 .../beta/troubleshooting/configuration.vi.mdx |   1 +
 .../beta/troubleshooting/grok-hooks.en.mdx    | 114 ++++++++++++++++++
 .../beta/troubleshooting/grok-hooks.vi.mdx    | 114 ++++++++++++++++++
 .../docs/beta/troubleshooting/index.en.mdx    |   2 +
 .../docs/beta/troubleshooting/index.vi.mdx    |   2 +
 content/docs/beta/troubleshooting/meta.json   |   3 +-
 .../docs/beta/troubleshooting/meta.vi.json    |   3 +-
 .../troubleshooting/configuration.en.mdx      |   1 +
 .../troubleshooting/configuration.vi.mdx      |   1 +
 .../stable/troubleshooting/grok-hooks.en.mdx  | 114 ++++++++++++++++++
 .../stable/troubleshooting/grok-hooks.vi.mdx  | 114 ++++++++++++++++++
 .../docs/stable/troubleshooting/index.en.mdx  |   2 +
 .../docs/stable/troubleshooting/index.vi.mdx  |   2 +
 content/docs/stable/troubleshooting/meta.json |   3 +-
 .../docs/stable/troubleshooting/meta.vi.json  |   3 +-
 scripts/release-quality-metrics.mjs           |   4 +-
 scripts/release-quality-shape.mjs             |   6 +-
 18 files changed, 481 insertions(+), 9 deletions(-)
 create mode 100644 content/docs/beta/troubleshooting/grok-hooks.en.mdx
 create mode 100644 content/docs/beta/troubleshooting/grok-hooks.vi.mdx
 create mode 100644 content/docs/stable/troubleshooting/grok-hooks.en.mdx
 create mode 100644 content/docs/stable/troubleshooting/grok-hooks.vi.mdx

diff --git a/content/docs/beta/troubleshooting/configuration.en.mdx b/content/docs/beta/troubleshooting/configuration.en.mdx
index 8552365..6d8cb26 100644
--- a/content/docs/beta/troubleshooting/configuration.en.mdx
+++ b/content/docs/beta/troubleshooting/configuration.en.mdx
@@ -107,4 +107,5 @@ source and value, and a new runtime session behaves as expected.
 
 - [Runtime cannot find a Skill or Agent](./runtime-cannot-find-skill-or-agent)
 - [Kit installation problems](./kit-installation)
+- [Grok CLI Hook errors](./grok-hooks)
 - [CLI reference](../reference/cli)
diff --git a/content/docs/beta/troubleshooting/configuration.vi.mdx b/content/docs/beta/troubleshooting/configuration.vi.mdx
index 04e1e82..f513de5 100644
--- a/content/docs/beta/troubleshooting/configuration.vi.mdx
+++ b/content/docs/beta/troubleshooting/configuration.vi.mdx
@@ -106,4 +106,5 @@ giá trị, và session runtime mới hoạt động như mong đợi.
 
 - [Runtime không tìm thấy Skill hoặc Agent](./runtime-cannot-find-skill-or-agent)
 - [Lỗi cài Kit](./kit-installation)
+- [Lỗi Hook trên Grok CLI](./grok-hooks)
 - [Tham chiếu CLI](../reference/cli)
diff --git a/content/docs/beta/troubleshooting/grok-hooks.en.mdx b/content/docs/beta/troubleshooting/grok-hooks.en.mdx
new file mode 100644
index 0000000..2506d07
--- /dev/null
+++ b/content/docs/beta/troubleshooting/grok-hooks.en.mdx
@@ -0,0 +1,114 @@
+---
+title: Grok CLI Hook errors
+description: Stop Grok from failing Claude-compat Hooks without editing AgentKit-managed settings.json, then re-enable Claude scan after an AgentKit update that folds global Hook commands.
+---
+
+Use this page when Grok CLI reports Hook errors on every prompt or tool call,
+especially a missing `~/.claude/node`, after a global AgentKit Kit install for
+Claude Code.
+
+## Confirm the symptom
+
+Typical signs:
+
+- Grok shows Hook errors on `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse`, or `Stop`.
+- The failing path is `~/.claude/node`, or Node starts without the Hook script.
+- One-liner Hooks already stored as a single `command` string still run. Entries
+  with `"command": "node"` plus an `args` array fail.
+
+Grok reads `~/.claude/settings.json` by default. It treats `command` as a path
+relative to that JSON file, or as an inline shell command when the string
+contains whitespace. It does not use Claude's `args` array.
+
+## Do not edit AgentKit-managed settings
+
+Do not rewrite `command` / `args` inside `~/.claude/settings.json` or
+`<project>/.claude/settings.json`. `ak kit update` matches managed Hooks by
+the `.cjs` script path and writes the exec-form back.
+
+Do not create `~/.claude/node` as a symlink to your real Node binary. Grok still
+drops `args`, so that shim would start Node with no script.
+
+Do not add a second copy of the same Hooks under `~/.grok/hooks/` while Claude
+compat scanning stays on. Grok merges sources and the Hooks would run twice.
+
+## Workaround until AgentKit folds global Hooks
+
+Keep Claude Code on the AgentKit-managed settings file. Point Grok at its own
+Hook files and turn off Claude Hook scanning.
+
+1. In `~/.grok/config.toml`:
+
+```toml
+[compat.claude]
+hooks = false
+```
+
+The same switch is `GROK_CLAUDE_HOOKS_ENABLED=0` for one process.
+
+2. Add Grok-native Hook files under `~/.grok/hooks/`. Use a one-liner `command`
+   that includes the script path, matching the form Grok already accepts:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node '/Users/you/.claude/hooks/session-init.cjs'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Copy only the AgentKit Hooks you need from `~/.claude/settings.json`. Keep
+timeouts and matchers. Quote paths that contain spaces.
+
+3. Restart Grok and inspect `/hooks`. Project Hooks also need `/hooks-trust` or
+   `--trust` before they run.
+
+This overlay lives outside AgentKit ownership. Kit update and uninstall will
+not create, refresh, or delete `~/.grok/hooks/`. Re-check the overlay when a
+Kit adds or removes a Hook.
+
+Project-native Claude settings already emit portable `node "<script>"`
+shell-form. The failure is the **global** `~/.claude/settings.json` exec-form.
+
+## After the AgentKit fix ships
+
+The durable fix is AgentKit folding global Node Hooks into one quoted
+shell-form command with an absolute Node runner, then deleting `args`. Track
+[agentkit#1607](https://github.com/bestagentkits/agentkit/issues/1607).
+
+When that CLI is installed:
+
+```bash
+ak kit update engineer --target claude-code --global
+```
+
+Use the Kit name you actually installed. Then remove the Grok overlay if you
+no longer need it, set `[compat.claude] hooks = true` (or delete that key; the
+default is on), and start a new Grok session.
+
+`ak doctor` can confirm a Node runner is still resolvable. Do not treat doctor
+output as proof of Grok's stdin schema.
+
+## Residual behavior on Grok
+
+Even with a runnable `command`, some AgentKit Hooks were written for Claude
+Code's snake_case stdin JSON. Grok sends camelCase fields such as
+`hookEventName` and `toolName`. Those Hooks may no-op or fail-open on Grok.
+That is a separate schema mismatch, not the missing `~/.claude/node` path.
+
+## Related pages
+
+- [Configuration problems](./configuration)
+- [Kit installation problems](./kit-installation)
+- [Updates and recovery](./updates)
diff --git a/content/docs/beta/troubleshooting/grok-hooks.vi.mdx b/content/docs/beta/troubleshooting/grok-hooks.vi.mdx
new file mode 100644
index 0000000..d337c97
--- /dev/null
+++ b/content/docs/beta/troubleshooting/grok-hooks.vi.mdx
@@ -0,0 +1,114 @@
+---
+title: Lỗi Hook trên Grok CLI
+description: Tắt lỗi Hook Claude-compat trên Grok mà không sửa settings.json do AgentKit quản lý, rồi bật lại scan Claude sau bản AgentKit gộp command Hook global.
+---
+
+Dùng trang này khi Grok CLI báo lỗi Hook mỗi lần gửi prompt hoặc gọi tool, đặc
+biệt khi thiếu `~/.claude/node`, sau khi cài Kit AgentKit global cho Claude
+Code.
+
+## Xác nhận triệu chứng
+
+Dấu hiệu thường gặp:
+
+- Grok báo lỗi Hook trên `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse` hoặc `Stop`.
+- Đường dẫn lỗi là `~/.claude/node`, hoặc Node chạy mà không có script Hook.
+- Hook one-liner đã nằm trong một chuỗi `command` vẫn chạy. Entry
+  `"command": "node"` kèm mảng `args` thì thất bại.
+
+Grok mặc định đọc `~/.claude/settings.json`. Nó coi `command` là đường dẫn
+tương đối so với file JSON đó, hoặc là lệnh shell nội tuyến khi chuỗi có
+khoảng trắng. Nó không dùng mảng `args` của Claude.
+
+## Không sửa settings do AgentKit quản lý
+
+Không viết lại `command` / `args` trong `~/.claude/settings.json` hoặc
+`<project>/.claude/settings.json`. `ak kit update` nhận diện Hook được quản lý
+theo đường dẫn script `.cjs` rồi ghi lại dạng exec-form.
+
+Không tạo `~/.claude/node` thành symlink tới Node thật. Grok vẫn bỏ `args`,
+nên shim đó chỉ mở Node mà không chạy script.
+
+Không thêm bản sao Hook dưới `~/.grok/hooks/` khi vẫn bật scan Claude compat.
+Grok merge các nguồn và Hook sẽ chạy hai lần.
+
+## Workaround cho đến khi AgentKit gộp Hook global
+
+Giữ Claude Code trên file settings do AgentKit quản lý. Cho Grok dùng file Hook
+của chính nó và tắt scan Hook Claude.
+
+1. Trong `~/.grok/config.toml`:
+
+```toml
+[compat.claude]
+hooks = false
+```
+
+Cùng một công tắc cho một process: `GROK_CLAUDE_HOOKS_ENABLED=0`.
+
+2. Thêm file Hook native của Grok dưới `~/.grok/hooks/`. Dùng `command` one-liner
+   có đường dẫn script, đúng form Grok đã chấp nhận:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node '/Users/you/.claude/hooks/session-init.cjs'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Chỉ copy các Hook AgentKit bạn cần từ `~/.claude/settings.json`. Giữ timeout và
+matcher. Quote đường dẫn có khoảng trắng.
+
+3. Khởi động lại Grok và kiểm tra `/hooks`. Hook ở project còn cần
+   `/hooks-trust` hoặc `--trust` trước khi chạy.
+
+Overlay này nằm ngoài ownership của AgentKit. Cập nhật hoặc gỡ Kit sẽ không tạo,
+làm mới, hay xóa `~/.grok/hooks/`. Kiểm tra lại overlay khi Kit thêm hoặc bớt
+Hook.
+
+Settings Claude **project-native** đã emit dạng portable `node "<script>"`.
+Lỗi nằm ở exec-form **global** trong `~/.claude/settings.json`.
+
+## Sau khi bản sửa AgentKit được cài
+
+Sửa bền là AgentKit gộp Hook Node global thành một command shell-form đã quote,
+kèm absolute Node runner, rồi xóa `args`. Theo dõi
+[agentkit#1607](https://github.com/bestagentkits/agentkit/issues/1607).
+
+Khi CLI đó đã cài:
+
+```bash
+ak kit update engineer --target claude-code --global
+```
+
+Dùng đúng tên Kit bạn đã cài. Sau đó xóa overlay Grok nếu không còn cần, đặt
+`[compat.claude] hooks = true` (hoặc xóa key đó; mặc định là bật), rồi mở
+session Grok mới.
+
+`ak doctor` có thể xác nhận Node runner vẫn resolve được. Đừng coi output
+doctor là bằng chứng schema stdin của Grok.
+
+## Hành vi còn lại trên Grok
+
+Dù `command` đã chạy được, một số Hook AgentKit được viết cho JSON stdin
+snake_case của Claude Code. Grok gửi field camelCase như `hookEventName` và
+`toolName`. Các Hook đó có thể no-op hoặc fail-open trên Grok. Đó là lệch
+schema riêng, không phải lỗi thiếu `~/.claude/node`.
+
+## Trang liên quan
+
+- [Lỗi cấu hình](./configuration)
+- [Lỗi cài Kit](./kit-installation)
+- [Cập nhật và khôi phục](./updates)
diff --git a/content/docs/beta/troubleshooting/index.en.mdx b/content/docs/beta/troubleshooting/index.en.mdx
index 72dc118..4d3dbef 100644
--- a/content/docs/beta/troubleshooting/index.en.mdx
+++ b/content/docs/beta/troubleshooting/index.en.mdx
@@ -20,6 +20,8 @@ before reinstalling or changing files.
   recovery](./updates)
 - **A setting is invalid, ignored, or comes from the wrong scope:**
   [Configuration problems](./configuration)
+- **Grok CLI reports Hook errors or a missing `~/.claude/node`:** [Grok CLI
+  Hook errors](./grok-hooks)
 
 ## Safe diagnostic order
 
diff --git a/content/docs/beta/troubleshooting/index.vi.mdx b/content/docs/beta/troubleshooting/index.vi.mdx
index b4ef53a..aa5aa36 100644
--- a/content/docs/beta/troubleshooting/index.vi.mdx
+++ b/content/docs/beta/troubleshooting/index.vi.mdx
@@ -19,6 +19,8 @@ thái đã ghi nhận trước khi cài lại hoặc thay đổi tệp.
   phục](./updates)
 - **Thiết lập không hợp lệ, bị bỏ qua hoặc đến từ sai phạm vi:** [Lỗi cấu
   hình](./configuration)
+- **Grok CLI báo lỗi Hook hoặc thiếu `~/.claude/node`:** [Lỗi Hook trên Grok
+  CLI](./grok-hooks)
 
 ## Thứ tự chẩn đoán an toàn
 
diff --git a/content/docs/beta/troubleshooting/meta.json b/content/docs/beta/troubleshooting/meta.json
index abb0b32..d3ce7f0 100644
--- a/content/docs/beta/troubleshooting/meta.json
+++ b/content/docs/beta/troubleshooting/meta.json
@@ -7,6 +7,7 @@
     "kit-installation",
     "runtime-cannot-find-skill-or-agent",
     "updates",
-    "configuration"
+    "configuration",
+    "grok-hooks"
   ]
 }
diff --git a/content/docs/beta/troubleshooting/meta.vi.json b/content/docs/beta/troubleshooting/meta.vi.json
index 2b723c7..b7caf1a 100644
--- a/content/docs/beta/troubleshooting/meta.vi.json
+++ b/content/docs/beta/troubleshooting/meta.vi.json
@@ -7,6 +7,7 @@
     "kit-installation",
     "runtime-cannot-find-skill-or-agent",
     "updates",
-    "configuration"
+    "configuration",
+    "grok-hooks"
   ]
 }
diff --git a/content/docs/stable/troubleshooting/configuration.en.mdx b/content/docs/stable/troubleshooting/configuration.en.mdx
index 8552365..6d8cb26 100644
--- a/content/docs/stable/troubleshooting/configuration.en.mdx
+++ b/content/docs/stable/troubleshooting/configuration.en.mdx
@@ -107,4 +107,5 @@ source and value, and a new runtime session behaves as expected.
 
 - [Runtime cannot find a Skill or Agent](./runtime-cannot-find-skill-or-agent)
 - [Kit installation problems](./kit-installation)
+- [Grok CLI Hook errors](./grok-hooks)
 - [CLI reference](../reference/cli)
diff --git a/content/docs/stable/troubleshooting/configuration.vi.mdx b/content/docs/stable/troubleshooting/configuration.vi.mdx
index 04e1e82..f513de5 100644
--- a/content/docs/stable/troubleshooting/configuration.vi.mdx
+++ b/content/docs/stable/troubleshooting/configuration.vi.mdx
@@ -106,4 +106,5 @@ giá trị, và session runtime mới hoạt động như mong đợi.
 
 - [Runtime không tìm thấy Skill hoặc Agent](./runtime-cannot-find-skill-or-agent)
 - [Lỗi cài Kit](./kit-installation)
+- [Lỗi Hook trên Grok CLI](./grok-hooks)
 - [Tham chiếu CLI](../reference/cli)
diff --git a/content/docs/stable/troubleshooting/grok-hooks.en.mdx b/content/docs/stable/troubleshooting/grok-hooks.en.mdx
new file mode 100644
index 0000000..2506d07
--- /dev/null
+++ b/content/docs/stable/troubleshooting/grok-hooks.en.mdx
@@ -0,0 +1,114 @@
+---
+title: Grok CLI Hook errors
+description: Stop Grok from failing Claude-compat Hooks without editing AgentKit-managed settings.json, then re-enable Claude scan after an AgentKit update that folds global Hook commands.
+---
+
+Use this page when Grok CLI reports Hook errors on every prompt or tool call,
+especially a missing `~/.claude/node`, after a global AgentKit Kit install for
+Claude Code.
+
+## Confirm the symptom
+
+Typical signs:
+
+- Grok shows Hook errors on `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse`, or `Stop`.
+- The failing path is `~/.claude/node`, or Node starts without the Hook script.
+- One-liner Hooks already stored as a single `command` string still run. Entries
+  with `"command": "node"` plus an `args` array fail.
+
+Grok reads `~/.claude/settings.json` by default. It treats `command` as a path
+relative to that JSON file, or as an inline shell command when the string
+contains whitespace. It does not use Claude's `args` array.
+
+## Do not edit AgentKit-managed settings
+
+Do not rewrite `command` / `args` inside `~/.claude/settings.json` or
+`<project>/.claude/settings.json`. `ak kit update` matches managed Hooks by
+the `.cjs` script path and writes the exec-form back.
+
+Do not create `~/.claude/node` as a symlink to your real Node binary. Grok still
+drops `args`, so that shim would start Node with no script.
+
+Do not add a second copy of the same Hooks under `~/.grok/hooks/` while Claude
+compat scanning stays on. Grok merges sources and the Hooks would run twice.
+
+## Workaround until AgentKit folds global Hooks
+
+Keep Claude Code on the AgentKit-managed settings file. Point Grok at its own
+Hook files and turn off Claude Hook scanning.
+
+1. In `~/.grok/config.toml`:
+
+```toml
+[compat.claude]
+hooks = false
+```
+
+The same switch is `GROK_CLAUDE_HOOKS_ENABLED=0` for one process.
+
+2. Add Grok-native Hook files under `~/.grok/hooks/`. Use a one-liner `command`
+   that includes the script path, matching the form Grok already accepts:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node '/Users/you/.claude/hooks/session-init.cjs'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Copy only the AgentKit Hooks you need from `~/.claude/settings.json`. Keep
+timeouts and matchers. Quote paths that contain spaces.
+
+3. Restart Grok and inspect `/hooks`. Project Hooks also need `/hooks-trust` or
+   `--trust` before they run.
+
+This overlay lives outside AgentKit ownership. Kit update and uninstall will
+not create, refresh, or delete `~/.grok/hooks/`. Re-check the overlay when a
+Kit adds or removes a Hook.
+
+Project-native Claude settings already emit portable `node "<script>"`
+shell-form. The failure is the **global** `~/.claude/settings.json` exec-form.
+
+## After the AgentKit fix ships
+
+The durable fix is AgentKit folding global Node Hooks into one quoted
+shell-form command with an absolute Node runner, then deleting `args`. Track
+[agentkit#1607](https://github.com/bestagentkits/agentkit/issues/1607).
+
+When that CLI is installed:
+
+```bash
+ak kit update engineer --target claude-code --global
+```
+
+Use the Kit name you actually installed. Then remove the Grok overlay if you
+no longer need it, set `[compat.claude] hooks = true` (or delete that key; the
+default is on), and start a new Grok session.
+
+`ak doctor` can confirm a Node runner is still resolvable. Do not treat doctor
+output as proof of Grok's stdin schema.
+
+## Residual behavior on Grok
+
+Even with a runnable `command`, some AgentKit Hooks were written for Claude
+Code's snake_case stdin JSON. Grok sends camelCase fields such as
+`hookEventName` and `toolName`. Those Hooks may no-op or fail-open on Grok.
+That is a separate schema mismatch, not the missing `~/.claude/node` path.
+
+## Related pages
+
+- [Configuration problems](./configuration)
+- [Kit installation problems](./kit-installation)
+- [Updates and recovery](./updates)
diff --git a/content/docs/stable/troubleshooting/grok-hooks.vi.mdx b/content/docs/stable/troubleshooting/grok-hooks.vi.mdx
new file mode 100644
index 0000000..d337c97
--- /dev/null
+++ b/content/docs/stable/troubleshooting/grok-hooks.vi.mdx
@@ -0,0 +1,114 @@
+---
+title: Lỗi Hook trên Grok CLI
+description: Tắt lỗi Hook Claude-compat trên Grok mà không sửa settings.json do AgentKit quản lý, rồi bật lại scan Claude sau bản AgentKit gộp command Hook global.
+---
+
+Dùng trang này khi Grok CLI báo lỗi Hook mỗi lần gửi prompt hoặc gọi tool, đặc
+biệt khi thiếu `~/.claude/node`, sau khi cài Kit AgentKit global cho Claude
+Code.
+
+## Xác nhận triệu chứng
+
+Dấu hiệu thường gặp:
+
+- Grok báo lỗi Hook trên `SessionStart`, `UserPromptSubmit`, `PreToolUse`,
+  `PostToolUse` hoặc `Stop`.
+- Đường dẫn lỗi là `~/.claude/node`, hoặc Node chạy mà không có script Hook.
+- Hook one-liner đã nằm trong một chuỗi `command` vẫn chạy. Entry
+  `"command": "node"` kèm mảng `args` thì thất bại.
+
+Grok mặc định đọc `~/.claude/settings.json`. Nó coi `command` là đường dẫn
+tương đối so với file JSON đó, hoặc là lệnh shell nội tuyến khi chuỗi có
+khoảng trắng. Nó không dùng mảng `args` của Claude.
+
+## Không sửa settings do AgentKit quản lý
+
+Không viết lại `command` / `args` trong `~/.claude/settings.json` hoặc
+`<project>/.claude/settings.json`. `ak kit update` nhận diện Hook được quản lý
+theo đường dẫn script `.cjs` rồi ghi lại dạng exec-form.
+
+Không tạo `~/.claude/node` thành symlink tới Node thật. Grok vẫn bỏ `args`,
+nên shim đó chỉ mở Node mà không chạy script.
+
+Không thêm bản sao Hook dưới `~/.grok/hooks/` khi vẫn bật scan Claude compat.
+Grok merge các nguồn và Hook sẽ chạy hai lần.
+
+## Workaround cho đến khi AgentKit gộp Hook global
+
+Giữ Claude Code trên file settings do AgentKit quản lý. Cho Grok dùng file Hook
+của chính nó và tắt scan Hook Claude.
+
+1. Trong `~/.grok/config.toml`:
+
+```toml
+[compat.claude]
+hooks = false
+```
+
+Cùng một công tắc cho một process: `GROK_CLAUDE_HOOKS_ENABLED=0`.
+
+2. Thêm file Hook native của Grok dưới `~/.grok/hooks/`. Dùng `command` one-liner
+   có đường dẫn script, đúng form Grok đã chấp nhận:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node '/Users/you/.claude/hooks/session-init.cjs'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Chỉ copy các Hook AgentKit bạn cần từ `~/.claude/settings.json`. Giữ timeout và
+matcher. Quote đường dẫn có khoảng trắng.
+
+3. Khởi động lại Grok và kiểm tra `/hooks`. Hook ở project còn cần
+   `/hooks-trust` hoặc `--trust` trước khi chạy.
+
+Overlay này nằm ngoài ownership của AgentKit. Cập nhật hoặc gỡ Kit sẽ không tạo,
+làm mới, hay xóa `~/.grok/hooks/`. Kiểm tra lại overlay khi Kit thêm hoặc bớt
+Hook.
+
+Settings Claude **project-native** đã emit dạng portable `node "<script>"`.
+Lỗi nằm ở exec-form **global** trong `~/.claude/settings.json`.
+
+## Sau khi bản sửa AgentKit được cài
+
+Sửa bền là AgentKit gộp Hook Node global thành một command shell-form đã quote,
+kèm absolute Node runner, rồi xóa `args`. Theo dõi
+[agentkit#1607](https://github.com/bestagentkits/agentkit/issues/1607).
+
+Khi CLI đó đã cài:
+
+```bash
+ak kit update engineer --target claude-code --global
+```
+
+Dùng đúng tên Kit bạn đã cài. Sau đó xóa overlay Grok nếu không còn cần, đặt
+`[compat.claude] hooks = true` (hoặc xóa key đó; mặc định là bật), rồi mở
+session Grok mới.
+
+`ak doctor` có thể xác nhận Node runner vẫn resolve được. Đừng coi output
+doctor là bằng chứng schema stdin của Grok.
+
+## Hành vi còn lại trên Grok
+
+Dù `command` đã chạy được, một số Hook AgentKit được viết cho JSON stdin
+snake_case của Claude Code. Grok gửi field camelCase như `hookEventName` và
+`toolName`. Các Hook đó có thể no-op hoặc fail-open trên Grok. Đó là lệch
+schema riêng, không phải lỗi thiếu `~/.claude/node`.
+
+## Trang liên quan
+
+- [Lỗi cấu hình](./configuration)
+- [Lỗi cài Kit](./kit-installation)
+- [Cập nhật và khôi phục](./updates)
diff --git a/content/docs/stable/troubleshooting/index.en.mdx b/content/docs/stable/troubleshooting/index.en.mdx
index 72dc118..4d3dbef 100644
--- a/content/docs/stable/troubleshooting/index.en.mdx
+++ b/content/docs/stable/troubleshooting/index.en.mdx
@@ -20,6 +20,8 @@ before reinstalling or changing files.
   recovery](./updates)
 - **A setting is invalid, ignored, or comes from the wrong scope:**
   [Configuration problems](./configuration)
+- **Grok CLI reports Hook errors or a missing `~/.claude/node`:** [Grok CLI
+  Hook errors](./grok-hooks)
 
 ## Safe diagnostic order
 
diff --git a/content/docs/stable/troubleshooting/index.vi.mdx b/content/docs/stable/troubleshooting/index.vi.mdx
index b4ef53a..aa5aa36 100644
--- a/content/docs/stable/troubleshooting/index.vi.mdx
+++ b/content/docs/stable/troubleshooting/index.vi.mdx
@@ -19,6 +19,8 @@ thái đã ghi nhận trước khi cài lại hoặc thay đổi tệp.
   phục](./updates)
 - **Thiết lập không hợp lệ, bị bỏ qua hoặc đến từ sai phạm vi:** [Lỗi cấu
   hình](./configuration)
+- **Grok CLI báo lỗi Hook hoặc thiếu `~/.claude/node`:** [Lỗi Hook trên Grok
+  CLI](./grok-hooks)
 
 ## Thứ tự chẩn đoán an toàn
 
diff --git a/content/docs/stable/troubleshooting/meta.json b/content/docs/stable/troubleshooting/meta.json
index abb0b32..d3ce7f0 100644
--- a/content/docs/stable/troubleshooting/meta.json
+++ b/content/docs/stable/troubleshooting/meta.json
@@ -7,6 +7,7 @@
     "kit-installation",
     "runtime-cannot-find-skill-or-agent",
     "updates",
-    "configuration"
+    "configuration",
+    "grok-hooks"
   ]
 }
diff --git a/content/docs/stable/troubleshooting/meta.vi.json b/content/docs/stable/troubleshooting/meta.vi.json
index 2b723c7..b7caf1a 100644
--- a/content/docs/stable/troubleshooting/meta.vi.json
+++ b/content/docs/stable/troubleshooting/meta.vi.json
@@ -7,6 +7,7 @@
     "kit-installation",
     "runtime-cannot-find-skill-or-agent",
     "updates",
-    "configuration"
+    "configuration",
+    "grok-hooks"
   ]
 }
diff --git a/scripts/release-quality-metrics.mjs b/scripts/release-quality-metrics.mjs
index eae2df5..578cb9f 100644
--- a/scripts/release-quality-metrics.mjs
+++ b/scripts/release-quality-metrics.mjs
@@ -21,7 +21,7 @@ import { collectPublishedChannelRoutes, inspectReleaseShape } from './release-qu
 export const RELEASE_QUALITY_BASELINE = Object.freeze({
   schemaVersion: 1,
   reviewedAt: '2026-08-13',
-  sourceCommit: 'e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2',
+  sourceCommit: 'dca7e4d895f45ba8b786f949ae94072855d3a5a4',
   channels: ['beta', 'stable'],
   locales: ['en', 'vi'],
   deterministic: {
@@ -33,7 +33,7 @@ export const RELEASE_QUALITY_BASELINE = Object.freeze({
     searchBudgetBytes: SEARCH_ASSET_BUDGET_BYTES,
     // Per-channel: stable stays bound to channels.stable.tag; beta may include
     // pages authored ahead of the next stable promote.
-    searchPagesPerLocaleChannel: { stable: 391, beta: 396 },
+    searchPagesPerLocaleChannel: { stable: 392, beta: 397 },
     reviewedSearchOutsideChannelRoutes: ['_showcase'],
     reviewedSearchExcludedPublishedRoutes: ['reference/cli/ak'],
     maxAssetBytesExclusive: MAX_ASSET_BYTES,
diff --git a/scripts/release-quality-shape.mjs b/scripts/release-quality-shape.mjs
index 8da9b9b..f0882fa 100644
--- a/scripts/release-quality-shape.mjs
+++ b/scripts/release-quality-shape.mjs
@@ -9,14 +9,14 @@ import { repoRoot } from './lib/paths.mjs';
 export const RELEASE_SHAPE_BASELINE = Object.freeze({
   schemaVersion: 1,
   reviewedAt: '2026-08-13',
-  sourceCommit: 'e1f84b0b0203cb2578aad2e0c9b9b708233ec2c2',
+  sourceCommit: 'dca7e4d895f45ba8b786f949ae94072855d3a5a4',
   channels: ['beta', 'stable'],
   locales: ['en', 'vi'],
   // Per-channel: stable stays bound to channels.stable.tag; beta may include
   // routes authored ahead of the next stable promote. Beta must remain a
   // superset of stable so a whole-copy promote is safe.
-  sourceRoutesPerLocaleChannel: { stable: 393, beta: 398 },
-  routesPerLocaleChannel: { stable: 392, beta: 397 },
+  sourceRoutesPerLocaleChannel: { stable: 394, beta: 399 },
+  routesPerLocaleChannel: { stable: 393, beta: 398 },
   reviewedSourceOnlyRoutes: [
     {
       route: 'changelog',