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

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.8";
+    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

package/dist/catalog/plugin-upgrade.js

@@ -20,6 +20,7 @@ import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionBlobs } from "../extensions/blobs.js";
 import { permissionSetOfPackage, readExtensionPackage } from "../extensions/package.js";
 import { blockingKeys, diffPermissions } from "../extensions/permission-set.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { ExtensionRegistry } from "../extensions/registry.js";
 import { audit } from "../identity/audit.js";
 import { SuperAdminLock } from "../identity/super-admin.js";
@@ -143,11 +144,14 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
     connectors;
     sync;
     log;
+    guides;
     constructor(kdb, txHost, adminLock, itemLock, orgLock, locks, storage, registry, ops, 
     /** Reads the target's extension package (its permissions, for `needsApproval`). */
     blobs, config, platform, 
     /** Template dependencies (the deployed connector kinds). */
-    installer, connectors, sync, log) {
+    installer, connectors, sync, log, 
+    /** The connector template guides an update changes (the preview's `guideChanges`). */
+    guides) {
         this.kdb = kdb;
         this.txHost = txHost;
         this.adminLock = adminLock;
@@ -164,13 +168,21 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
         this.connectors = connectors;
         this.sync = sync;
         this.log = log;
+        this.guides = guides;
     }
     get db() {
         return this.kdb.db;
     }
     /** The update preview (see the class comment); writes nothing. */
     async preview(itemId, version) {
-        return previewOf(await this.diff(itemId, version));
+        return this.withGuideChanges(await this.diff(itemId, version));
+    }
+    /** The preview of a diff with the template guides it changes. */
+    async withGuideChanges(d) {
+        return {
+            ...previewOf(d),
+            guideChanges: await this.guides.templateGuideChanges(d.itemId, d.from, d.to),
+        };
     }
     /**
      * The update preview of a new version of an org's own plugin (ruling P3-12): the item must be
@@ -186,7 +198,7 @@ let PlatformPluginUpdater = class PlatformPluginUpdater {
         if (staged !== undefined && staged.version !== version) {
             throw new Error(`internal: previewForOwner got the staged target of version ${staged.version} for version ${version}`);
         }
-        const preview = previewOf(await this.diff(itemId, version, {
+        const preview = await this.withGuideChanges(await this.diff(itemId, version, {
             owner: { orgId },
             ...(staged !== undefined && { target: staged }),
         }));
@@ -1502,10 +1514,11 @@ PlatformPluginUpdater = __decorate([
     __param(12, Inject(PluginInstaller)),
     __param(13, Inject(ConnectorsService)),
     __param(14, Inject(PluginScopeSync)),
-    __param(15, Inject(KERNEL_LOGGER))
+    __param(15, Inject(KERNEL_LOGGER)),
+    __param(16, Inject(PluginGuides))
 ], PlatformPluginUpdater);
 export { PlatformPluginUpdater };
-/** The preview of a diff. */
+/** The preview of a diff (without `guideChanges`, which reads PG). */
 function previewOf(d) {
     return {
         itemId: d.itemId,

package/dist/channels/channels.module.js

@@ -12,7 +12,7 @@ import { OnWorkerEvent, WorkerHost } from "@nestjs/bullmq";
 import { Inject, Injectable, Module } from "@nestjs/common";
 import { ConversationsModule } from "../conversations/conversations.module.js";
 import { EventLogModule } from "../conversations/event-log.js";
-import { EnvironmentsModule } from "../environments/environments.module.js";
+import { DevicesModule } from "../devices/devices.module.js";
 import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { IdentityModule } from "../identity/identity.module.js";
 import { configuredProcessor, } from "../infra/queue/configured-processor.js";
@@ -39,7 +39,7 @@ let ChannelsModule = class ChannelsModule {
 ChannelsModule = __decorate([
     Module({
         imports: [
-            EnvironmentsModule,
+            DevicesModule,
             EventLogModule,
             ExtensionsModule,
             IdentityModule,

package/dist/channels/connections.controller.d.ts

@@ -13,7 +13,7 @@ import { ChannelConnections, type ChannelConnectionView } from "./connections.se
  * the URL of its plugin's icon on the org's catalog route (null without one, or when the org may
  * not see the plugin's catalog item; maintainer decision 2026-11-08), and its plugin's setup guide
  * with the drift since the connection was set up (`setupGuide`, `guideDrift`; spec
- * 2026-11-08-plugin-setup-guides-design.md §6).
+ * 2026-11-09-setup-guides-v2-design.md §11).
  */
 export type ChannelConnectionPage = ChannelConnectionView & ConnectionGuideState & {
     pluginDisplayName: LocalizedName | null;

package/dist/channels/connections.controller.js

@@ -93,7 +93,7 @@ let ChannelConnectionsController = class ChannelConnectionsController {
      */
     async ackGuide(principal, org, id, body) {
         const p = requireUser(principal);
-        const view = await this.channels.ackGuide(org.orgId, id, body.hash, p.account.id, patTokenId(p));
+        const view = await this.channels.ackGuide({ orgId: org.orgId, role: org.role }, id, body.hash, p.account.id, patTokenId(p));
         return { channel: await this.withPlugin(org, view) };
     }
     async remove(principal, org, id) {

package/dist/channels/connections.service.d.ts

@@ -12,6 +12,7 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
 import { type KernelLogger } from "../log.js";
 import { OrgLock } from "../orgs/org-lock.js";
+import type { OrgRole } from "../orgs/roles.js";
 import { ChannelJobs } from "./jobs.js";
 import type { ChannelLocale } from "./phrases.js";
 /** 连接配置里全部密钥字段存成一行：`{ 点路径: 值 }` 的 JSON。 */
@@ -112,7 +113,7 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     private readonly log;
     readonly txHost: TransactionHost;
-    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
     private readonly guides;
     private readonly unsubscribe;
     /** `<plugin>@<version>` whose invalid connection hints were warned about (a log dedupe only). */
@@ -126,7 +127,7 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     config: Pick<KernelConfigService, "get">, events: Pick<KernelEvents, "on">, 
     /** Secret values handled here (written or decrypted) are redacted from the logs (`addOrgSecrets`). */
     log: Pick<KernelLogger, "warn" | "addOrgSecrets">, txHost: TransactionHost, 
-    /** The setup guide acks (spec 2026-11-08-plugin-setup-guides-design.md §6). */
+    /** The setup guide acks (spec 2026-11-09-setup-guides-v2-design.md §11). */
     guides: Pick<PluginGuides, "currentAck" | "ackDrifted">);
     /** Unsubscribes after the stop phases: events emitted while they drain are still handled. */
     onApplicationShutdown(): void;
@@ -186,11 +187,15 @@ export declare class ChannelConnections implements OnApplicationShutdown {
     private updateIn;
     /**
      * 「我已更新应用」: records the plugin's current channel-connection guide for the connection's
-     * mode as the one it is set up with. `hash` is the template hash of the guide the person was
+     * mode as the one it is set up with. `hash` is the drift hash of the guide the person was
      * shown; when the plugin has moved on since, 409 `channel.guide_changed` (show the new guide
-     * first). A plugin without a guide -> 404 `catalog.guide_not_found`.
+     * first). A plugin without a guide, or whose item the org's catalog does not show -> 404
+     * `catalog.guide_not_found`.
      */
-    ackGuide(orgId: string, id: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
+    ackGuide(org: {
+        orgId: string;
+        role: OrgRole;
+    }, id: string, hash: string, actorAccountId: string, actorTokenId?: string): Promise<ChannelConnectionView>;
     /** The row of {@link ackGuide}, in its own transaction. */
     private ackIn;
     /** 删除（软删除，同一事务删掉密钥）；持有长连接的副本收到广播后断开。 */
@@ -211,6 +216,18 @@ export declare class ChannelConnections implements OnApplicationShutdown {
      * 持有长连接的副本立即断开（扫描复核只是兜底）。只广播，失败只记日志。
      */
     notifyOrgChanged(orgId: string, plugin?: string): Promise<void>;
+    /**
+     * For setup checks (setup guides v2 §10.4): the input revision of a live connection of the org
+     * on `plugin`: the `updated_at` of its row and of its secrets row (ISO), never a value. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`.
+     */
+    checkRevision(orgId: string, plugin: string, id: string): Promise<string>;
+    /**
+     * For setup checks (setup guides v2 §10.8): the stored secret values of a live connection of the
+     * org on `plugin` (every secret field, decrypted), what a check's result is redacted by. Missing,
+     * deleted, of another org or plugin -> `channel.not_found`. Never echo them.
+     */
+    checkSecrets(orgId: string, plugin: string, id: string): Promise<string[]>;
     /**
      * The extension implementation and full config a connection needs to run (decrypted secrets
      * included, validated against `connectionSchema`). Connection missing / deleted ->