bestagentkits · thieung · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026 · Aug 13, 2026
diff --git 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
@@ -69,16 +69,21 @@ 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
      the audit skill's
      [`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
@@ -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
@@ -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/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
@@ -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
@@ -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
@@ -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
@@ -1,13 +1,20 @@
 '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';
 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
@@ -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
@@ -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
@@ -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
@@ -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,15 +35,15 @@ 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 |
 | --- | --- |
 | macOS | Intel (`amd64`) and Apple silicon (`arm64`) |
 | 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
@@ -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,15 +33,15 @@ 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 |
 | --- | --- |
 | macOS | Intel (`amd64`) và Apple silicon (`arm64`) |
 | 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ợ.