@capybara-hq/kernel 0.1.0-rc.13 → 0.1.0-rc.14

package/dist/catalog/admin-catalog.controller.d.ts

@@ -1,8 +1,9 @@
 import type { FastifyReply } from "fastify";
 import { z } from "zod";
+import { PluginGuides, type RenderedSetupGuide } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
-import { CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
+import { AdminCatalogGuideQuery, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
 import { type CatalogItemDetail, type CatalogItemView, CatalogService, type PermissionsMismatch } from "./catalog.service.js";
 import { CatalogScopeService, type ScopePreview } from "./catalog-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
@@ -38,7 +39,8 @@ export declare class AdminCatalogController {
     private readonly scope;
     private readonly updater;
     private readonly icons;
-    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater, icons: PluginIcons);
+    private readonly guides;
+    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater, icons: PluginIcons, guides: PluginGuides);
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
      * `application/octet-stream`, at most `packages.maxBytes`): reads and checks the whole plugin
@@ -124,6 +126,15 @@ export declare class AdminCatalogController {
      * `sendCatalogIcon`). No icon -> 404 `catalog.icon_not_found`.
      */
     icon(id: string, reply: FastifyReply): Promise<void>;
+    /**
+     * A setup guide of the item as the platform sees it (spec 2026-11-09-setup-guides-v2-design.md
+     * §9.3; the admin console's connector template page): any live item, the admin audience, no org
+     * (`orgName` unresolved, reason `no_org`), no target, no checks run. Unknown item -> 404
+     * `catalog.item_not_found`, unknown guide -> 404 `catalog.guide_not_found`.
+     */
+    guide(itemId: string, guideId: string, q: z.infer<typeof AdminCatalogGuideQuery>): Promise<{
+        guide: RenderedSetupGuide;
+    }>;
     /**
      * What a scope change (`{ scope, orgs? }`, `orgs` only with `named`) or a disable
      * (`{ disabled: true }`) would take away: `{ affected: [{ orgId, orgName, agents,

package/dist/catalog/admin-catalog.controller.js

@@ -10,11 +10,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
-import { CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
+import { AdminCatalogGuideQuery, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
 import { CatalogService, } from "./catalog.service.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { sendCatalogIcon } from "./org-catalog.controller.js";
@@ -42,6 +43,8 @@ class CatalogImportConfirmBody extends createZodDto(ConfirmBody, "CatalogImportC
 }
 class CatalogGitImportBody extends createZodDto(GitBody, "CatalogGitImportBody") {
 }
+class AdminCatalogGuideQueryDto extends createZodDto(AdminCatalogGuideQuery, "AdminCatalogGuideQuery") {
+}
 class CatalogItemsQueryDto extends createZodDto(CatalogItemsQuery, "CatalogItemsQuery") {
 }
 class CatalogNpmImportBody extends createZodDto(NpmBody, "CatalogNpmImportBody") {
@@ -75,13 +78,15 @@ let AdminCatalogController = class AdminCatalogController {
     scope;
     updater;
     icons;
-    constructor(catalog, pluginImport, orgCatalog, scope, updater, icons) {
+    guides;
+    constructor(catalog, pluginImport, orgCatalog, scope, updater, icons, guides) {
         this.catalog = catalog;
         this.pluginImport = pluginImport;
         this.orgCatalog = orgCatalog;
         this.scope = scope;
         this.updater = updater;
         this.icons = icons;
+        this.guides = guides;
     }
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
@@ -189,6 +194,15 @@ let AdminCatalogController = class AdminCatalogController {
     async icon(id, reply) {
         await sendCatalogIcon(reply, await this.orgCatalog.icon(id, true));
     }
+    /**
+     * A setup guide of the item as the platform sees it (spec 2026-11-09-setup-guides-v2-design.md
+     * §9.3; the admin console's connector template page): any live item, the admin audience, no org
+     * (`orgName` unresolved, reason `no_org`), no target, no checks run. Unknown item -> 404
+     * `catalog.item_not_found`, unknown guide -> 404 `catalog.guide_not_found`.
+     */
+    async guide(itemId, guideId, q) {
+        return { guide: await this.guides.renderForPlatform(itemId, guideId, q) };
+    }
     /**
      * What a scope change (`{ scope, orgs? }`, `orgs` only with `named`) or a disable
      * (`{ disabled: true }`) would take away: `{ affected: [{ orgId, orgName, agents,
@@ -331,6 +345,12 @@ __decorate([
     __param(0, Param("id")),
     __param(1, Res())
 ], AdminCatalogController.prototype, "icon", null);
+__decorate([
+    Get(":itemId/guides/:guideId"),
+    __param(0, Param("itemId")),
+    __param(1, Param("guideId")),
+    __param(2, ZQuery(AdminCatalogGuideQueryDto))
+], AdminCatalogController.prototype, "guide", null);
 __decorate([
     Post("items/:id/scope/preview"),
     HttpCode(200),
@@ -395,6 +415,7 @@ AdminCatalogController = __decorate([
     __param(2, Inject(OrgCatalogService)),
     __param(3, Inject(CatalogScopeService)),
     __param(4, Inject(PlatformPluginUpdater)),
-    __param(5, Inject(PluginIcons))
+    __param(5, Inject(PluginIcons)),
+    __param(6, Inject(PluginGuides))
 ], AdminCatalogController);
 export { AdminCatalogController };

package/dist/catalog/admin-catalog.schemas.d.ts

@@ -69,4 +69,14 @@ export declare const CatalogDisabledBody: z.ZodObject<{
 export declare const CatalogShownBody: z.ZodObject<{
     shownToOthers: z.ZodBoolean;
 }, z.core.$strict>;
+/**
+ * `GET :itemId/guides/:guideId`, the super admin's preview of a setup guide (spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3): only the document language; no org, no target.
+ */
+export declare const AdminCatalogGuideQuery: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strict>;
 export declare const ADMIN_CATALOG_ROUTES: readonly RouteSchemas[];

package/dist/catalog/admin-catalog.schemas.js

@@ -52,6 +52,13 @@ export const CatalogDisabledBody = z
     .object({ disabled: z.boolean(), scopeHash: CatalogHash.optional() })
     .strict();
 export const CatalogShownBody = z.object({ shownToOthers: z.boolean() }).strict();
+/**
+ * `GET :itemId/guides/:guideId`, the super admin's preview of a setup guide (spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3): only the document language; no org, no target.
+ */
+export const AdminCatalogGuideQuery = z
+    .object({ locale: z.enum(["en", "zh"]).optional() })
+    .strict();
 export const ADMIN_CATALOG_ROUTES = [
     { route: "GET /api/v1/admin/catalog/items", query: CatalogItemsQuery },
     { route: "GET /api/v1/admin/catalog/items/:id", params: CatalogIdPathParams },

package/dist/catalog/catalog-content.d.ts

@@ -72,6 +72,14 @@ export interface OrgCatalogTemplate {
     editableEndpoint: string[];
     auth: Record<string, unknown>;
     ownership: "org" | "personal" | null;
+    /**
+     * The template's setup guide in the item's latest version (`GET …/catalog/:itemId/guides/
+     * :guideId`), null without one (spec 2026-11-09-setup-guides-v2-design.md §9.3).
+     */
+    guide: {
+        itemId: string;
+        guideId: string;
+    } | null;
 }
 /** `GET /orgs/:orgId/catalog/:itemId`: the item and what the install wizard needs (latest version). */
 export interface OrgCatalogDetail {
@@ -105,7 +113,7 @@ export interface OrgCatalogDetail {
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export declare function orgTemplateView(id: string, file: ConnectorTemplateFile): OrgCatalogTemplate;
+export declare function orgTemplateView(id: string, file: ConnectorTemplateFile, guide?: OrgCatalogTemplate["guide"]): OrgCatalogTemplate;
 /** An item's icon (the latest version's plugin icon). */
 export interface CatalogIcon {
     data: Uint8Array;

package/dist/catalog/catalog-content.js

@@ -16,7 +16,7 @@ import { satisfiesRange } from "./versions.js";
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export function orgTemplateView(id, file) {
+export function orgTemplateView(id, file, guide = null) {
     const t = file.template;
     return {
         id,
@@ -29,6 +29,7 @@ export function orgTemplateView(id, file) {
         auth: t.auth,
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+        guide,
     };
 }
 const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");

package/dist/catalog/catalog-files.d.ts

@@ -1,4 +1,4 @@
-import type { PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type PluginManifest } from "@capybara-hq/plugin-sdk";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 type Db = Pick<KernelSchemaDb, "selectFrom" | "insertInto" | "deleteFrom">;
 /** A stored file as a version row lists it. */
@@ -9,7 +9,8 @@ interface FileMeta {
 }
 /**
  * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
- * icons (given by the caller, which parsed the templates) and the setup guide files.
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
  */
 export declare function displayFilePaths(m: PluginManifest, templateIcons?: string[]): Set<string>;
 /**

package/dist/catalog/catalog-files.js

@@ -1,16 +1,18 @@
 // Catalog display files in PG (`catalog_files`, migration 0100): a plugin's icon, its connector
-// templates' icons and its setup guide files. They are small (64 KiB each at most, by the plugin
+// templates' icons and its setup guide documents. They are small (64 KiB each at most, by the plugin
 // format) and must be readable without object storage: a bootstrap plugin is imported before any
 // object-store extension runs, and the object-store plugin's own icon can never wait for itself.
 // Skills, connector templates and agent templates stay in object storage under the version's
 // `object_prefix` (they are copied into platform components there).
 import { createHash } from "node:crypto";
+import { setupGuideDocPath } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { packagePath } from "../packages/tgz.js";
 /**
  * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
- * icons (given by the caller, which parsed the templates) and the setup guide files.
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
  */
 export function displayFilePaths(m, templateIcons = []) {
     const out = new Set();
@@ -18,9 +20,10 @@ export function displayFilePaths(m, templateIcons = []) {
         out.add(packagePath(m.icon));
     for (const icon of templateIcons)
         out.add(packagePath(icon));
-    for (const g of m.setupGuides ?? [])
-        for (const f of g.files ?? [])
-            out.add(packagePath(f.path));
+    for (const g of m.setupGuides ?? []) {
+        out.add(setupGuideDocPath(g.id, "en"));
+        out.add(setupGuideDocPath(g.id, "zh"));
+    }
     return out;
 }
 /**

package/dist/catalog/component-scope.service.d.ts

@@ -1,5 +1,6 @@
 import type { LocalizedName, ThemeScheme } from "@capybara-hq/plugin-sdk";
 import { ApiError } from "../errors.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
@@ -172,6 +173,14 @@ export interface OrgOfferedComponentView extends OrgComponentView {
      * name as its owner (本组织 for the viewing org's own, the owner's name for another org's).
      */
     owner: Owner;
+    /**
+     * Connector templates only: the template's setup guide in its plugin's latest version (`GET
+     * …/catalog/:itemId/guides/:guideId`), null without one (spec 2026-11-09-setup-guides-v2 §9.3).
+     */
+    guide?: {
+        itemId: string;
+        guideId: string;
+    } | null;
 }
 /** The result of an org switch: the component, or (switching off without `confirm`) the preview. */
 export type ComponentSwitchResult = {
@@ -231,11 +240,15 @@ export declare class ComponentScopeService {
     /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
     private readonly promotion;
     readonly txHost: TransactionHost;
+    /** The connector templates' setup guides (the org list's `guide`). */
+    private readonly guides;
     constructor(kdb: KernelDb, adminLock: SuperAdminLock, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock: OrgLock, 
     /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
-    promotion: ComponentPromotion, txHost: TransactionHost);
+    promotion: ComponentPromotion, txHost: TransactionHost, 
+    /** The connector templates' setup guides (the org list's `guide`). */
+    guides: Pick<PluginGuides, "templateGuides">);
     private get db();
     /**
      * What the admin routes act on (ruling P3-23): the platform component `id`, an org row the org

package/dist/catalog/component-scope.service.js

@@ -12,6 +12,7 @@ import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { templateTypeClashes, templateTypeOf } from "../agents/templates.js";
 import { ApiError } from "../errors.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { audit } from "../identity/audit.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
 import { notifyItemShared } from "../inbox/org-notices.js";
@@ -124,16 +125,20 @@ let ComponentScopeService = class ComponentScopeService {
     orgLock;
     promotion;
     txHost;
+    guides;
     constructor(kdb, adminLock, 
     /** The org row lock (orgs/org-lock.ts): joins the caller's transaction. */
     orgLock, 
     /** Promote on share (ruling P3-3): an org row shown or associated becomes a platform row. */
-    promotion, txHost) {
+    promotion, txHost, 
+    /** The connector templates' setup guides (the org list's `guide`). */
+    guides) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.orgLock = orgLock;
         this.promotion = promotion;
         this.txHost = txHost;
+        this.guides = guides;
     }
     get db() {
         return this.kdb.db;
@@ -245,6 +250,9 @@ let ComponentScopeService = class ComponentScopeService {
             const st = await loadScopeState(this.db, kind, comps);
             const linked = await this.linkedCopies(orgId, kind);
             const owners = await ownersOf(this.db, comps.flatMap((c) => (c.ownerOrgId === null ? [] : [c.ownerOrgId])));
+            const guides = kind === "connector_template"
+                ? await this.guides.templateGuides(comps.flatMap((c) => c.itemId === null ? [] : [{ itemId: c.itemId, templateId: c.name }]))
+                : undefined;
             const rows = [];
             for (const c of comps) {
                 const p = pluginFactsOf(st, c.itemId, orgId);
@@ -273,6 +281,7 @@ let ComponentScopeService = class ComponentScopeService {
                     platformDefault: !locked && (c.scopeMode === "follow" ? p?.scope === "all" : c.scope === "all"),
                     linkedIds: linked.get(c.id) ?? [],
                     owner: ownerOf(c.ownerOrgId, owners),
+                    ...(guides !== undefined && { guide: guides.get(`${c.itemId}/${c.name}`) ?? null }),
                 });
             }
             rows.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
@@ -1067,7 +1076,8 @@ ComponentScopeService = __decorate([
     __param(1, Inject(SuperAdminLock)),
     __param(2, Inject(OrgLock)),
     __param(3, Inject(ComponentPromotion)),
-    __param(4, Inject(TransactionHost))
+    __param(4, Inject(TransactionHost)),
+    __param(5, Inject(PluginGuides))
 ], ComponentScopeService);
 export { ComponentScopeService };
 /** Whether `c` is the platform default theme `uiTheme` (locked on in every org, themes spec §7). */

package/dist/catalog/marketplaces.service.d.ts

@@ -188,7 +188,7 @@ export declare function headsToResolve(entries: readonly MarketplaceEntry[], imp
 /** The host versions (an entry's `minKernel` is judged against them). */
 export declare const HOST_VERSIONS: {
     readonly kernel: string;
-    readonly sdk: "0.1.0-rc.9";
+    readonly sdk: "0.1.0-rc.10";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;

package/dist/catalog/org-catalog.controller.d.ts

@@ -98,10 +98,11 @@ export declare class OrgCatalogController {
      */
     icon(org: OrgContext, itemId: string, reply: FastifyReply): Promise<void>;
     /**
-     * A setup guide of the item, rendered for this org (spec 2026-11-08-plugin-setup-guides-design.md
-     * §4): steps and template files with the place's variables filled in, the modes and the template
-     * hash. The item must be one the org's catalog shows; a `channel-connection` guide also needs
-     * `channels.manage` (checked by the service).
+     * A setup guide of the item, rendered for this org (spec 2026-11-09-setup-guides-v2-design.md
+     * §7.2): the document's blocks with the place's variables filled in, its modes, audiences and
+     * checks, the unresolved variables with their reasons, the drift hash and the target. The item
+     * must be one the org's catalog shows; the place and audience's action (`channels.manage`,
+     * `connectors.manage`, `connectors.use`) is checked by the service.
      */
     guide(org: OrgContext, itemId: string, guideId: string, q: z.infer<typeof CatalogGuideQuery>): Promise<{
         guide: RenderedSetupGuide;

package/dist/catalog/org-catalog.controller.js

@@ -129,10 +129,11 @@ let OrgCatalogController = class OrgCatalogController {
         await sendCatalogIcon(reply, icon);
     }
     /**
-     * A setup guide of the item, rendered for this org (spec 2026-11-08-plugin-setup-guides-design.md
-     * §4): steps and template files with the place's variables filled in, the modes and the template
-     * hash. The item must be one the org's catalog shows; a `channel-connection` guide also needs
-     * `channels.manage` (checked by the service).
+     * A setup guide of the item, rendered for this org (spec 2026-11-09-setup-guides-v2-design.md
+     * §7.2): the document's blocks with the place's variables filled in, its modes, audiences and
+     * checks, the unresolved variables with their reasons, the drift hash and the target. The item
+     * must be one the org's catalog shows; the place and audience's action (`channels.manage`,
+     * `connectors.manage`, `connectors.use`) is checked by the service.
      */
     async guide(org, itemId, guideId, q) {
         return { guide: await this.guides.render(org, itemId, guideId, q) };

package/dist/catalog/org-catalog.schemas.d.ts

@@ -63,6 +63,11 @@ export declare const OrgPluginSwitchBody: z.ZodObject<{
 export declare const CatalogItemPathParams: z.ZodObject<{
     itemId: z.ZodString;
 }, z.core.$strip>;
+/** `:itemId` / `:guideId` of the guide route (`@Param`). */
+export declare const CatalogGuidePathParams: z.ZodObject<{
+    itemId: z.ZodString;
+    guideId: z.ZodString;
+}, z.core.$strip>;
 /** `:installId` as the uninstall route takes it (`@Param`). */
 export declare const PluginInstallPathParams: z.ZodObject<{
     installId: z.ZodString;
@@ -77,12 +82,23 @@ export declare const CatalogRequestsListQuery: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 /**
- * `GET catalog/:itemId/guides/:guideId`: the mode to render (the place's modes, checked by the
- * service), a channel connection to render for, or the name typed so far on 新建渠道.
+ * `GET catalog/:itemId/guides/:guideId` (spec 2026-11-09-setup-guides-v2-design.md §7.2): the mode
+ * and audience to render (the place's, checked by the service), the document language, and the
+ * target: a channel connection or the name typed so far on 新建渠道 (`channel-connection`), a
+ * connector made from the template (`connector-template`).
  */
 export declare const CatalogGuideQuery: z.ZodObject<{
     mode: z.ZodOptional<z.ZodString>;
+    audience: z.ZodOptional<z.ZodEnum<{
+        admin: "admin";
+        member: "member";
+    }>>;
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
     connectionId: z.ZodOptional<z.ZodString>;
     name: z.ZodOptional<z.ZodString>;
+    connectorId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const ORG_CATALOG_ROUTES: readonly RouteSchemas[];

package/dist/catalog/org-catalog.schemas.js

@@ -53,6 +53,10 @@ export const OrgPluginSwitchBody = z
     .strict();
 /** `:itemId` as the routes take it (`@Param`). */
 export const CatalogItemPathParams = z.object({ itemId: z.string().min(1) });
+/** `:itemId` / `:guideId` of the guide route (`@Param`). */
+export const CatalogGuidePathParams = CatalogItemPathParams.extend({
+    guideId: z.string().min(1).max(64),
+});
 /** `:installId` as the uninstall route takes it (`@Param`). */
 export const PluginInstallPathParams = z.object({ installId: z.string().min(1) });
 /** The super admin's request list filter. */
@@ -60,19 +64,29 @@ export const CatalogRequestsListQuery = z.object({
     status: z.enum(["pending", "approved", "rejected", "cancelled"]).optional(),
 });
 /**
- * `GET catalog/:itemId/guides/:guideId`: the mode to render (the place's modes, checked by the
- * service), a channel connection to render for, or the name typed so far on 新建渠道.
+ * `GET catalog/:itemId/guides/:guideId` (spec 2026-11-09-setup-guides-v2-design.md §7.2): the mode
+ * and audience to render (the place's, checked by the service), the document language, and the
+ * target: a channel connection or the name typed so far on 新建渠道 (`channel-connection`), a
+ * connector made from the template (`connector-template`).
  */
 export const CatalogGuideQuery = z
     .object({
     mode: z.string().min(1).max(64).optional(),
+    audience: z.enum(["admin", "member"]).optional(),
+    locale: z.enum(["en", "zh"]).optional(),
     connectionId: z.string().min(1).max(100).optional(),
     name: z.string().max(100).optional(),
+    connectorId: z.string().min(1).max(100).optional(),
 })
     .strict();
 export const ORG_CATALOG_ROUTES = [
     { route: "GET /api/v1/orgs/:orgId/catalog" },
     { route: "GET /api/v1/orgs/:orgId/catalog/:itemId", params: CatalogItemPathParams },
+    {
+        route: "GET /api/v1/orgs/:orgId/catalog/:itemId/guides/:guideId",
+        params: CatalogGuidePathParams,
+        query: CatalogGuideQuery,
+    },
     {
         route: "POST /api/v1/orgs/:orgId/catalog/:itemId/requests",
         params: CatalogItemPathParams,

package/dist/catalog/org-catalog.service.js

@@ -9,6 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Inject, Injectable } from "@nestjs/common";
 import { ApiError } from "../errors.js";
+import { templateGuideOf } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { ExtensionAvailability } from "../extensions/unavailable.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -272,6 +273,11 @@ let OrgCatalogService = class OrgCatalogService {
             throw itemNotFound();
         const m = v.manifest;
         const templates = await readCatalogTemplates(this.storage, v);
+        // where each template's page finds its setup guide (spec 2026-11-09-setup-guides-v2 §9.3)
+        const guideOf = (templateId) => {
+            const g = templateGuideOf(m, templateId);
+            return g ? { itemId, guideId: g.id } : null;
+        };
         // Providers the install would switch on first (a refusal is the install's to report)
         const implied = await this.pluginInstaller
             .impliedProviders(orgId, m, templates, m.dependencies ?? [])
@@ -284,7 +290,7 @@ let OrgCatalogService = class OrgCatalogService {
             item,
             hasIcon: m.icon !== undefined,
             extension: m.extension ? m.name : null,
-            templates: templates.map((t) => orgTemplateView(t.id, t.file)),
+            templates: templates.map((t) => orgTemplateView(t.id, t.file, guideOf(t.id))),
             dependencies: [
                 ...(m.dependencies ?? []).map((d) => ({ name: d.name, range: d.version })),
                 ...implied.map((d) => ({ name: d.name, range: d.range, implied: true })),
@@ -292,7 +298,7 @@ let OrgCatalogService = class OrgCatalogService {
             skills: (m.skills ?? []).map((s) => packagePath(s.path)),
             agents: (m.agents ?? []).map((a) => packagePath(a.path)),
             missingTemplates: item.installed !== null && item.state === "needs_config"
-                ? ((await this.pluginInstaller.missingConnectors(orgId, itemId))?.templates ?? []).map((t) => orgTemplateView(t.id, t.file))
+                ? ((await this.pluginInstaller.missingConnectors(orgId, itemId))?.templates ?? []).map((t) => orgTemplateView(t.id, t.file, guideOf(t.id)))
                 : [],
         };
     }

package/dist/catalog/plugin-import.js

@@ -1377,7 +1377,7 @@ let PluginImport = class PluginImport {
             if (stored.has(path))
                 objectPaths.add(path);
         };
-        // The plugin icon and the setup guide templates (rendered by PluginGuides): display files
+        // The plugin icon and the setup guide documents (rendered by PluginGuides): display files
         const displayPaths = displayFilePaths(m, pkg.connectorTemplates.flatMap((c) => (c.file.icon === undefined ? [] : [c.file.icon])));
         for (const path of displayPaths)
             keep(path);

package/dist/catalog/plugin-package.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { AGENT_TEMPLATE_LIMITS, CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, hostSdkProblem, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, parseSkillMd, parseThemeFile, SKILL_ENTRY_FILE, setupGuideFileProblem, THEME_LIMITS, themeIdOf, validatePluginPackageJsonFor, validateThemeAssets, } from "@capybara-hq/plugin-sdk";
+import { AGENT_TEMPLATE_LIMITS, CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, hostSdkProblem, PLUGIN_MANIFEST_FILE, PLUGIN_MANIFEST_LIMITS, parseAgentTemplate, parseConnectorTemplateFile, parsePluginManifest, parseSkillMd, parseThemeFile, SKILL_ENTRY_FILE, setupGuideDocPath, setupGuideDocProblem, THEME_LIMITS, themeIdOf, validatePluginPackageJsonFor, validateSetupGuide, validateThemeAssets, } from "@capybara-hq/plugin-sdk";
 import { ApiError } from "../errors.js";
 import { HOST_ZOD_VERSION, LEGACY_FORMAT_MESSAGE, PackageTgzError, packagePath, parsePackageJsonFile, unpackPackageTgz, } from "../packages/tgz.js";
 export { LEGACY_FORMAT_MESSAGE, packagePath };
@@ -362,18 +362,46 @@ export function readPluginFiles(files, opts) {
             issues.push(`icon: ${problem}`);
     }
     const ext = manifest.extension;
-    // Setup guides: their template files are text within the size limit (spec
-    // 2026-11-08-plugin-setup-guides-design.md §2); a channel guide needs a channel extension, which
-    // the manifest parser checks when the extension section is there
+    // Setup guides v2 (spec 2026-11-09-setup-guides-v2-design.md §4.5): the documents are text
+    // within the limits and pass the SDK validator (an unknown variable is accepted: it renders as
+    // written); a channel guide needs a channel extension, which the manifest parser checks when the
+    // extension section is there; a template guide names one of the plugin's connector templates
+    const templateIds = new Set(connectorTemplates.map((t) => t.id));
     manifest.setupGuides?.forEach((g, i) => {
+        const at = `setupGuides.${i} (${g.id})`;
         if (g.place === "channel-connection" && ext === undefined) {
-            issues.push(`setupGuides.${i}: a channel-connection guide needs the plugin's extension to provide channel@1`);
+            issues.push(`${at}: a channel-connection guide needs the plugin's extension to provide channel@1`);
         }
-        g.files?.forEach((f, j) => {
-            const problem = setupGuideFileProblem(f.path, files.get(packagePath(f.path)));
+        // a listed template is checked by the manifest parser; scanned ones only here
+        if (g.template !== undefined &&
+            manifest.connectorTemplates === undefined &&
+            !templateIds.has(g.template)) {
+            issues.push(`${at}: template ${g.template} is not one of the plugin's connector templates`);
+        }
+        const docs = {};
+        for (const locale of ["en", "zh"]) {
+            const path = setupGuideDocPath(g.id, locale);
+            const data = files.get(path);
+            if (locale === "zh" && data === undefined)
+                continue;
+            const problem = setupGuideDocProblem(path, data);
             if (problem !== undefined)
-                issues.push(`setupGuides.${i}.files.${j}: ${problem}`);
-        });
+                issues.push(`${at}: ${problem}`);
+            else
+                docs[locale] = new TextDecoder().decode(data);
+        }
+        if (docs.en === undefined)
+            return;
+        for (const issue of validateSetupGuide({
+            place: g.place,
+            en: docs.en,
+            ...(docs.zh !== undefined && { zh: docs.zh }),
+            id: g.id,
+            allowUnknownVariables: true,
+        })) {
+            if (issue.level === "error")
+                issues.push(`${at}: ${issue.message}`);
+        }
     });
     if (ext !== undefined) {
         if (!files.has(packagePath(ext.entry))) {

package/dist/catalog/plugin-upgrade.d.ts

@@ -1,6 +1,7 @@
 import type { PluginManifest } from "@capybara-hq/plugin-sdk";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionBlobs } from "../extensions/blobs.js";
+import { PluginGuides, type TemplateGuideChange } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import type { SingleProviderNote } from "../extensions/single-provider.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
@@ -110,6 +111,13 @@ export interface PlatformUpdatePreview {
         needsApproval: boolean;
     } | null;
     connectorOrgs: PlatformUpdateConnectorOrg[];
+    /**
+     * Connector templates whose setup guide the update changes (code blocks or checks of the admin
+     * text): "the setup guide of template X changed; org admins of N orgs will be asked to update
+     * their app" (spec 2026-11-09-setup-guides-v2-design.md §11). Counts only. Not covered by
+     * `diffHash` (nothing the confirm does depends on it).
+     */
+    guideChanges: TemplateGuideChange[];
     /**
      * The themes the update removes that are on in some org (themes spec §6): the orgs whose default
      * each is and how many people picked it. Absent when no such theme is removed.
@@ -211,14 +219,20 @@ export declare class PlatformPluginUpdater {
     private readonly connectors;
     private readonly sync;
     private readonly log;
+    /** The connector template guides an update changes (the preview's `guideChanges`). */
+    private readonly guides;
     constructor(kdb: KernelDb, txHost: TransactionHost, adminLock: SuperAdminLock, itemLock: CatalogItemLock, orgLock: OrgLock, locks: LockService, storage: StorageService, registry: ExtensionRegistry, ops: ExtensionAdminOps, 
     /** Reads the target's extension package (its permissions, for `needsApproval`). */
     blobs: ExtensionBlobs, config: KernelConfigService, platform: PlatformComponents, 
     /** Template dependencies (the deployed connector kinds). */
-    installer: PluginInstaller, connectors: ConnectorsService, sync: PluginScopeSync, log: KernelLogger);
+    installer: PluginInstaller, connectors: ConnectorsService, sync: PluginScopeSync, log: KernelLogger, 
+    /** The connector template guides an update changes (the preview's `guideChanges`). */
+    guides: Pick<PluginGuides, "templateGuideChanges">);
     private get db();
     /** The update preview (see the class comment); writes nothing. */
     preview(itemId: string, version: string): Promise<PlatformUpdatePreview>;
+    /** The preview of a diff with the template guides it changes. */
+    private withGuideChanges;
     /**
      * The update preview of a new version of an org's own plugin (ruling P3-12): the item must be
      * owned by `orgId` (else 404, as for any item the org cannot see), the target carries no