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

package/dist/catalog/plugin-import.js

@@ -8,11 +8,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { createHash, randomUUID } from "node:crypto";
-import { PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
+import { appearanceIssues, PLUGIN_MANIFEST_FILE, parseSkillMd, pluginDescription, SDK_VERSION, SKILL_ENTRY_FILE, } from "@capybara-hq/plugin-sdk";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import semver from "semver";
+import { ClientBuilds } from "../client/client-builds.service.js";
+import { checkClientFiles } from "../client/client-files.js";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
@@ -112,14 +114,17 @@ const reviewStale = (review) => new ApiError("plugin.review_stale", `The review
 const mismatch = (what) => new ApiError("marketplace.package_mismatch", `The downloaded package does not match the marketplace entry: ${what}`);
 /**
  * The API error of a plugin package that cannot be read in a catalog path: the pre-0.1.0 format ->
- * `catalog.legacy_format`; a failing theme (themes spec §5) -> `theme.invalid` (details
- * `[{ theme, errors }]`) or `theme.unreadable` (details `[{ theme, issues }]`, the failing pairs);
- * anything else -> `catalog.invalid_manifest` (issues as details).
+ * `catalog.legacy_format`; undeclared client code -> `client.undeclared`; a failing theme (themes
+ * spec §5) -> `theme.invalid` (details `[{ theme, errors }]`) or `theme.unreadable` (details
+ * `[{ theme, issues }]`, the failing pairs); anything else -> `catalog.invalid_manifest` (issues as
+ * details).
  */
 export function catalogPackageError(e) {
     const legacy = e.code === "catalog.legacy_format" || e.code === "extension.legacy_format";
     if (legacy)
         return new ApiError("catalog.legacy_format", e.message, e.issues);
+    if (e.code === "client.undeclared")
+        return new ApiError("client.undeclared", e.message);
     if (e.code === "theme.invalid" || e.code === "theme.unreadable") {
         return themeApiError(e);
     }
@@ -160,6 +165,7 @@ let PluginImport = class PluginImport {
     txHost;
     platform;
     maintenance;
+    clientBuilds;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     files;
     /**
@@ -180,7 +186,9 @@ let PluginImport = class PluginImport {
     /** The platform rows of a new item's components, written after the confirm's commit. */
     platform, 
     /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    maintenance) {
+    maintenance, 
+    /** The client build of a dropped org upload's package is deleted with it. */
+    clientBuilds) {
         this.kdb = kdb;
         this.adminLock = adminLock;
         this.orgLock = orgLock;
@@ -197,6 +205,7 @@ let PluginImport = class PluginImport {
         this.txHost = txHost;
         this.platform = platform;
         this.maintenance = maintenance;
+        this.clientBuilds = clientBuilds;
         this.files = storage;
     }
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
@@ -341,6 +350,22 @@ let PluginImport = class PluginImport {
             ? await readingPackage(() => readExtensionPackage(bytes, { maxBytes, hostSdkVersion: SDK_VERSION }))
             : undefined;
         const content = this.checkContent(pkg, format);
+        // suggestedAppearance.theme against the themes the scan found (the manifest may not list them)
+        const appearance = appearanceIssues(m, pkg.themes.map((t) => t.id));
+        if (appearance.length > 0)
+            throw invalid(appearance);
+        // Client code (client extensions spec §9.1): the section re-checked and every file against it
+        // (keys, listed = present, sizes, sha384 recomputed, the CSS layer wrap); delivered from object
+        // storage, so refused without one. The store checks the bytes it writes again. A bootstrap
+        // plugin never carries it: a bootstrap run may have no object store (it may be a bootstrap
+        // plugin itself), and a required entry failing on that would stop the start.
+        if (ext?.section.client !== undefined) {
+            if (source.kind === "bootstrap") {
+                throw new ApiError("client.invalid", `Bootstrap plugin ${m.name} ships client code (extension.client), which a bootstrap plugin may not carry: its files are kept in object storage, which a bootstrap run may not have (the object store may be a bootstrap plugin itself); take ${m.name} out of bootstrap.json and import it into the catalog instead`);
+            }
+            checkClientFiles(ext.section.client, pkg.files);
+            this.files.assertAvailable();
+        }
         // A name live for another owner (an org's for the super admin; the platform's or another
         // org's for an org) -> 409 plugin.name_taken naming it (P3-14); the same owner adds a version
         await assertNameFree(this.db, m.name, owner?.orgId ?? null);
@@ -475,13 +500,16 @@ let PluginImport = class PluginImport {
                 .sort()
             : [];
         const mismatch = permissionsMismatch(opts.expect?.marketplace?.permissions, ext ? keys : undefined);
+        const manifest = normalizedManifest(pkg);
+        const replacements = manifest.suggestedAppearance?.replacements;
         const staged = {
             itemId,
             packageName,
             version,
             contentDigest: pkg.contentDigest,
             size: tgz.size,
-            manifest: normalizedManifest(pkg),
+            manifest,
+            ...(replacements !== undefined && { appearanceOrder: Object.keys(replacements) }),
             files: content.files.map(({ path, size, sha256 }) => ({ path, size, sha256 })),
             ...(mismatch !== null && { permissionsMismatch: mismatch }),
             sourceFormat: format,
@@ -785,6 +813,22 @@ let PluginImport = class PluginImport {
         // Checked again before this upload claims anything (ruling P3-51)
         if (owner !== undefined)
             await assertPackageFree(t, staged.packageName, owner.orgId);
+        // The item's name lock and its live row before the extension's install lock: the global lock
+        // order is the item, then the install lock (ruling P3-50; ExtensionAdminOps.install locks the
+        // source item row before the install lock, an org deletion its items before it). Taken after
+        // the install lock instead, a confirmation of an org upload racing a replacement upload
+        // deadlocks (40P01).
+        const m = manifest;
+        await this.itemLock.lock(m.name);
+        // The scope the audit records: the review's for a new item, the item's own for a new version
+        // of a live item (which keeps its scope)
+        const existing = await t
+            .selectFrom("catalog_items")
+            .select(["id", "scope", "awaiting_confirmation", "package_name"])
+            .where("name", "=", m.name)
+            .where("deleted_at", "is", null)
+            .forUpdate()
+            .executeTakeFirst();
         let now;
         let previous;
         if (reviewed) {
@@ -817,8 +861,6 @@ let PluginImport = class PluginImport {
                 previous = await this.approve(actor, review, staged, now, stored, opts);
             }
         }
-        const m = manifest;
-        await this.itemLock.lock(m.name);
         // Under the name's lock: the first confirm of a name wins, a later one of another owner is
         // refused naming it, before anything of it is written (P3-14)
         await assertNameFree(t, m.name, owner?.orgId ?? null);
@@ -826,15 +868,6 @@ let PluginImport = class PluginImport {
             await assertNameNotReserved(t, m.name);
             await this.resolveDependencies(m, owner);
         }
-        // The scope the audit records: the review's for a new item, the item's own for a new version
-        // of a live item (which keeps its scope)
-        const existing = await t
-            .selectFrom("catalog_items")
-            .select(["id", "scope", "awaiting_confirmation", "package_name"])
-            .where("name", "=", m.name)
-            .where("deleted_at", "is", null)
-            .forUpdate()
-            .executeTakeFirst();
         const actual = existing === undefined
             ? scope
             : {
@@ -879,6 +912,7 @@ let PluginImport = class PluginImport {
             version: staged.version,
             contentDigest: staged.contentDigest,
             manifest: m,
+            appearanceOrder: staged.appearanceOrder ?? null,
             listing: {
                 publisher: m.publisher,
                 description: pluginDescription(m.description).en,
@@ -1307,8 +1341,27 @@ let PluginImport = class PluginImport {
                 .executeTakeFirst());
         if (used !== undefined)
             return;
-        // extension_blobs (a PG-stored package) goes with the row (ON DELETE CASCADE)
+        const build = await t
+            .selectFrom("extension_client_builds")
+            .select("object_prefix")
+            .where("package_sha256", "=", sha)
+            .executeTakeFirst();
+        // extension_blobs (a PG-stored package) and extension_client_builds go with the row (ON
+        // DELETE CASCADE)
         await t.deleteFrom("extension_packages").where("sha256", "=", sha).execute();
+        if (build !== undefined) {
+            afterCommit(async () => {
+                try {
+                    await this.clientBuilds.deleteFiles(sha, build.object_prefix);
+                }
+                catch (err) {
+                    this.log.warn("cannot delete an expired org upload's client build objects", {
+                        sha256: sha,
+                        err,
+                    });
+                }
+            });
+        }
         // The object only once the row is gone for good: a failure leaves an unreferenced object
         // (harmless; a later upload of the same bytes rewrites it), never a row without its bytes
         if (pkg.blob_store === "object") {
@@ -1377,7 +1430,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);
@@ -1588,6 +1641,7 @@ let PluginImport = class PluginImport {
             warnings,
             reviewHash: extensionReviewHash(set, warnings),
             sensitive: permissions.some((g) => g.sensitive) || warnings.length > 0,
+            ...(pkg.section.client !== undefined && { client: reviewClient(pkg) }),
         };
     }
     async readStored(sha256) {
@@ -1654,7 +1708,8 @@ PluginImport = __decorate([
     __param(13, Inject(KERNEL_LOGGER)),
     __param(14, Inject(TransactionHost)),
     __param(15, Inject(PlatformComponents)),
-    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME)))
+    __param(16, Inject(getQueueToken(MAINTENANCE_QUEUE_NAME))),
+    __param(17, Inject(ClientBuilds))
 ], PluginImport);
 export { PluginImport };
 /**
@@ -1751,6 +1806,27 @@ export function pluginReviewHash(r, files) {
     ]);
     return createHash("sha256").update(canonical).digest("hex").slice(0, 32);
 }
+/** The client code of a read extension package for its review (sizes from the package's files). */
+function reviewClient(pkg) {
+    const c = pkg.section.client;
+    const sizes = new Map(pkg.files.map((f) => [f.path, f.size]));
+    const files = [
+        ...(c.entry !== undefined ? [c.entry] : []),
+        ...(c.styles ?? []),
+        ...(c.assets ?? []),
+    ].map((path) => {
+        // checkClientFiles ran first: every listed file is in the package
+        const size = sizes.get(path.slice(2));
+        if (size === undefined)
+            throw new Error(`client file ${path} is not in the package`);
+        return { path, size };
+    });
+    return {
+        files,
+        totalBytes: files.reduce((n, f) => n + f.size, 0),
+        apiVersion: c.apiVersion,
+    };
+}
 /**
  * A version change that is a downgrade (the imported version below the installed one) whose
  * version has migrations not run on this deployment -> `extension.downgrade_unsupported` (the same

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

@@ -16,9 +16,11 @@ export { LEGACY_FORMAT_MESSAGE, packagePath };
  */
 /**
  * Codes of {@link PluginPackageError}: `theme.invalid` / `theme.unreadable` when the package's only
- * problems are in its themes (themes spec §5: a failing theme refuses the whole plugin).
+ * problems are in its themes (themes spec §5: a failing theme refuses the whole plugin);
+ * `client.undeclared` for an `extension.client` section whose manifest lacks
+ * `permissions.client: true` (client extensions spec §5.4: client code is always reviewed).
  */
-export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format" | "theme.invalid" | "theme.unreadable";
+export type PluginPackageErrorCode = "catalog.invalid_manifest" | "catalog.legacy_format" | "theme.invalid" | "theme.unreadable" | "client.undeclared";
 /** The problems of one theme of a refused plugin (English; `unreadable:` lines for readability). */
 export interface PluginThemeProblem {
     /** The theme id (the file's base name). */

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 };
@@ -12,9 +12,11 @@ export class PluginPackageError extends Error {
     constructor(code, issues, themes) {
         super(code === "catalog.legacy_format"
             ? (issues[0] ?? LEGACY_FORMAT_MESSAGE)
-            : code === "theme.invalid" || code === "theme.unreadable"
-                ? `Theme ${themes?.[0]?.theme ?? "?"} ${code === "theme.invalid" ? "is invalid" : "is not readable"}: ${issues[0] ?? "unknown problem"}`
-                : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
+            : code === "client.undeclared"
+                ? (issues[0] ?? code)
+                : code === "theme.invalid" || code === "theme.unreadable"
+                    ? `Theme ${themes?.[0]?.theme ?? "?"} ${code === "theme.invalid" ? "is invalid" : "is not readable"}: ${issues[0] ?? "unknown problem"}`
+                    : `Invalid plugin package: ${issues[0] ?? "unknown problem"}`);
         this.name = "PluginPackageError";
         this.code = code;
         this.issues = issues;
@@ -78,6 +80,27 @@ export function iconProblem(path, data) {
     return /<svg[\s>/]/i.test(text) ? undefined : `${path} is not an SVG document`;
 }
 /** package.json parsed, or undefined when it is not valid (only used to name a legacy package). */
+/**
+ * Client code the extension manifest does not declare (an `extension.client` section without
+ * `permissions.client: true`), read from the raw plugin.json before it is parsed, so the refusal
+ * names it (`client.undeclared`) instead of being one parse problem among others.
+ */
+function clientUndeclared(text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    const ext = isObj(raw) ? raw.extension : undefined;
+    if (!isObj(ext) || ext.client === undefined)
+        return undefined;
+    const perms = isObj(ext.manifest) ? ext.manifest.permissions : undefined;
+    if (isObj(perms) && perms.client === true)
+        return undefined;
+    return `${PLUGIN_MANIFEST_FILE}: extension.client ships client code, but the extension manifest does not declare permissions.client: true; client code must be declared so it is reviewed (capybara-plugin pack writes both)`;
+}
 const parsedOrUndefined = (data) => {
     try {
         return parsePackageJsonFile({ data });
@@ -201,6 +224,9 @@ export function readPluginFiles(files, opts) {
         const text = decode(manifestBytes);
         if (text === undefined)
             return invalid([`${PLUGIN_MANIFEST_FILE} is not valid UTF-8 text`]);
+        const undeclared = clientUndeclared(text);
+        if (undeclared !== undefined)
+            throw new PluginPackageError("client.undeclared", [undeclared]);
         const parsed = parsePluginManifest(text);
         if ("errors" in parsed) {
             return invalid(parsed.errors.map((e) => `${PLUGIN_MANIFEST_FILE}: ${e}`));
@@ -362,18 +388,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/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 ->