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

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.11";
 };
 /** 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/org-extension.controller.d.ts

@@ -1,5 +1,6 @@
-import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { LocalizedName, SuggestedAppearance } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+import { type ClientBuildSummary, ClientBuilds } from "../client/client-builds.service.js";
 import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { OrgExtensionConfigs, type OrgExtensionView } from "../extensions/org-config.js";
 import { OrgOverrides, type OrgOverrideView } from "../extensions/org-overrides.js";
@@ -7,6 +8,8 @@ import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { type OrgToolSwitch, OrgToolSwitches, type OrgToolSwitchResult } from "../tools/org-tool-switches.js";
+import { AppearanceApplyBody } from "./appearance.schemas.js";
+import { type AppearanceResult, AppearanceService } from "./appearance.service.js";
 import { OrgExtensionParams as ExtensionParams, OrgExtensionToolParams as ToolParams, OrgToolSwitchPut as ToolSwitchPut } from "./org-extension.schemas.js";
 import { OrgExtensionSwitch } from "./org-extension-switch.js";
 import type { UninstallPreview } from "./plugin-install.js";
@@ -31,20 +34,26 @@ declare const OverridesTake: z.ZodObject<{
 /**
  * One extension of the org list: the org view plus the plugin's display name, 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 item) and the extension points it provides (`channel@1`, `web-search@1`, … the names
- * only, also for members).
+ * plugin's item), the extension points it provides (`channel@1`, `web-search@1`, … the names
+ * only, also for members), the plugin's suggested appearance (null without one; the page offers
+ * 应用此插件的外观 to org admins when set, client extensions spec §6.5) and the client build of the
+ * running package (files with sizes, total, client API version; null without one: the permission
+ * review's 客户端代码 group, spec §5.4).
  */
 export type OrgExtensionItem = OrgExtensionView & {
     displayName: LocalizedName | null;
     icon: string | null;
     provides: string[];
+    suggestedAppearance: SuggestedAppearance | null;
+    client: ClientBuildSummary | null;
 };
 /**
  * What a member sees of an extension: its state and the points it provides (names only, what the
- * 扩展 page sorts by), never the org config, the secrets' state, the config schema or the
- * permission list.
+ * 扩展 page sorts by), never the org config, the secrets' state, the config schema, the
+ * permission list, the suggested appearance (members cannot apply it) or the client build (part of
+ * the permission review).
  */
-export type OrgExtensionMemberItem = Omit<OrgExtensionItem, "config" | "secrets" | "orgConfigSchema" | "permissions">;
+export type OrgExtensionMemberItem = Omit<OrgExtensionItem, "config" | "secrets" | "orgConfigSchema" | "permissions" | "suggestedAppearance" | "client">;
 /**
  * Org-level extension enablement and config (`/api/v1/orgs/:orgId/extensions`); responses echo only
  * non-secret config and whether each secret is set.
@@ -54,7 +63,9 @@ export declare class OrgExtensionConfigsController {
     private readonly displayNames;
     private readonly extSwitch;
     private readonly icons;
-    constructor(configs: OrgExtensionConfigs, displayNames: ExtensionDisplayNames, extSwitch: OrgExtensionSwitch, icons: PluginIcons);
+    private readonly appearance;
+    private readonly clientBuilds;
+    constructor(configs: OrgExtensionConfigs, displayNames: ExtensionDisplayNames, extSwitch: OrgExtensionSwitch, icons: PluginIcons, appearance: AppearanceService, clientBuilds: ClientBuilds);
     /**
      * The org's extensions (also the channel plugin options: those providing `channel@1`). Members
      * get the projection {@link OrgExtensionMemberItem}; admins the full view.
@@ -72,6 +83,15 @@ export declare class OrgExtensionConfigsController {
         preview: UninstallPreview;
         confirm: string;
     }>;
+    /**
+     * 应用此插件的外观 (client extensions spec §6.5), for a plugin whose extension is on in the org:
+     * sets the plugin's suggested theme as the org's default theme (keeping `personal`) and each
+     * suggested replacement as the org arrangement's `use` of its slot, in one transaction.
+     * `dryRun: true` answers the same changes and writes nothing. A theme not on in the org -> 400
+     * `theme.not_available` (nothing written); a replacement not available in the org is skipped.
+     * An extension not on in the org, or a plugin without a suggestion -> 404 `extension.not_found`.
+     */
+    applyAppearance(principal: Principal, org: OrgContext, { extension }: z.infer<typeof ExtensionParams>, body: z.infer<typeof AppearanceApplyBody>): Promise<AppearanceResult>;
 }
 /**
  * The org's two-level deployment config of an extension (spec A §5.3 to §5.6): following or a copy,

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

@@ -9,6 +9,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put } from "@nestjs/common";
 import { z } from "zod";
+import { ClientBuilds } from "../client/client-builds.service.js";
 import { ExtensionDisplayNames } from "../extensions/display-name.js";
 import { OrgExtensionConfigs, providesOf, } from "../extensions/org-config.js";
 import { OrgOverrides } from "../extensions/org-overrides.js";
@@ -19,6 +20,8 @@ import { ZBody, ZParam } from "../infra/validation/zod-params.js";
 import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
 import { roleAtLeast } from "../orgs/roles.js";
 import { OrgToolSwitches, } from "../tools/org-tool-switches.js";
+import { AppearanceApplyBody } from "./appearance.schemas.js";
+import { AppearanceService } from "./appearance.service.js";
 import { OrgExtensionParams as ExtensionParams, OrgExtensionToolParams as ToolParams, OrgToolSwitchPut as ToolSwitchPut, } from "./org-extension.schemas.js";
 import { OrgExtensionSwitch } from "./org-extension-switch.js";
 const PutBody = z
@@ -65,6 +68,8 @@ class OrgExtensionParamsDto extends createZodDto(ExtensionParams, "OrgExtensionP
 }
 class OrgExtensionToolParamsDto extends createZodDto(ToolParams, "OrgExtensionToolParams") {
 }
+class OrgAppearanceApplyBody extends createZodDto(AppearanceApplyBody, "OrgAppearanceApplyBody") {
+}
 class OrgOverridesPutBody extends createZodDto(OverridesPut, "OrgOverridesPutBody") {
 }
 class OrgOverridesTakeBody extends createZodDto(OverridesTake, "OrgOverridesTakeBody") {
@@ -78,11 +83,15 @@ let OrgExtensionConfigsController = class OrgExtensionConfigsController {
     displayNames;
     extSwitch;
     icons;
-    constructor(configs, displayNames, extSwitch, icons) {
+    appearance;
+    clientBuilds;
+    constructor(configs, displayNames, extSwitch, icons, appearance, clientBuilds) {
         this.configs = configs;
         this.displayNames = displayNames;
         this.extSwitch = extSwitch;
         this.icons = icons;
+        this.appearance = appearance;
+        this.clientBuilds = clientBuilds;
     }
     /**
      * The org's extensions (also the channel plugin options: those providing `channel@1`). Members
@@ -91,20 +100,25 @@ let OrgExtensionConfigsController = class OrgExtensionConfigsController {
     async list(org) {
         const views = await this.configs.list(org.orgId);
         const plugins = views.map((v) => v.plugin);
-        const [names, icons] = await Promise.all([
+        const admin = roleAtLeast(org.role, "admin");
+        const [names, icons, suggestions, clients] = await Promise.all([
             this.displayNames.many(plugins),
             this.icons.many(plugins, orgIconScope(org)),
+            admin ? this.appearance.suggestions(plugins) : new Map(),
+            admin ? this.clientBuilds.installedSummaries(plugins) : new Map(),
         ]);
         const items = views.map((v) => ({
             ...v,
             displayName: names.get(v.plugin) ?? null,
             icon: icons.get(v.plugin) ?? null,
             provides: providesOf(v),
+            suggestedAppearance: suggestions.get(v.plugin) ?? null,
+            client: clients.get(v.plugin) ?? null,
         }));
-        if (roleAtLeast(org.role, "admin"))
+        if (admin)
             return { extensions: items };
         return {
-            extensions: items.map(({ config: _c, secrets: _s, orgConfigSchema: _o, permissions: _p, ...rest }) => rest),
+            extensions: items.map(({ config: _c, secrets: _s, orgConfigSchema: _o, permissions: _p, suggestedAppearance: _a, client: _cl, ...rest }) => rest),
         };
     }
     /**
@@ -116,9 +130,11 @@ let OrgExtensionConfigsController = class OrgExtensionConfigsController {
         const r = await this.extSwitch.put(org.orgId, p.account.id, extension, body, patTokenId(p));
         if (r.kind === "preview")
             return { preview: r.preview, confirm: r.confirm };
-        const [displayName, icons] = await Promise.all([
+        const [displayName, icons, suggestions, clients] = await Promise.all([
             this.displayNames.get(r.view.plugin),
             this.icons.many([r.view.plugin], orgIconScope(org)),
+            this.appearance.suggestions([r.view.plugin]),
+            this.clientBuilds.installedSummaries([r.view.plugin]),
         ]);
         return {
             extension: {
@@ -126,9 +142,24 @@ let OrgExtensionConfigsController = class OrgExtensionConfigsController {
                 displayName,
                 icon: icons.get(r.view.plugin) ?? null,
                 provides: providesOf(r.view),
+                suggestedAppearance: suggestions.get(r.view.plugin) ?? null,
+                client: clients.get(r.view.plugin) ?? null,
             },
         };
     }
+    /**
+     * 应用此插件的外观 (client extensions spec §6.5), for a plugin whose extension is on in the org:
+     * sets the plugin's suggested theme as the org's default theme (keeping `personal`) and each
+     * suggested replacement as the org arrangement's `use` of its slot, in one transaction.
+     * `dryRun: true` answers the same changes and writes nothing. A theme not on in the org -> 400
+     * `theme.not_available` (nothing written); a replacement not available in the org is skipped.
+     * An extension not on in the org, or a plugin without a suggestion -> 404 `extension.not_found`.
+     */
+    applyAppearance(principal, org, { extension }, body) {
+        const p = requireUser(principal);
+        const tokenId = patTokenId(p);
+        return this.appearance.apply({ orgId: org.orgId }, extension, { accountId: p.account.id, ...(tokenId !== undefined && { tokenId }) }, body.dryRun === true);
+    }
 };
 __decorate([
     Get(),
@@ -143,12 +174,23 @@ __decorate([
     __param(2, Param("extension")),
     __param(3, ZBody(OrgExtensionPutBody))
 ], OrgExtensionConfigsController.prototype, "put", null);
+__decorate([
+    Post(":extension/appearance"),
+    HttpCode(200),
+    OrgAction("org.update"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZParam(OrgExtensionParamsDto)),
+    __param(3, ZBody(OrgAppearanceApplyBody))
+], OrgExtensionConfigsController.prototype, "applyAppearance", null);
 OrgExtensionConfigsController = __decorate([
     Controller("api/v1/orgs/:orgId/extensions"),
     __param(0, Inject(OrgExtensionConfigs)),
     __param(1, Inject(ExtensionDisplayNames)),
     __param(2, Inject(OrgExtensionSwitch)),
-    __param(3, Inject(PluginIcons))
+    __param(3, Inject(PluginIcons)),
+    __param(4, Inject(AppearanceService)),
+    __param(5, Inject(ClientBuilds))
 ], OrgExtensionConfigsController);
 export { OrgExtensionConfigsController };
 /**

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

@@ -1,5 +1,6 @@
 import { type AgentTemplate, type AgentTemplateTier, type LocalizedName, type PluginManifest, type ThemeScheme } from "@capybara-hq/plugin-sdk";
 import type { Queue } from "bullmq";
+import { ClientBuilds } from "../client/client-builds.service.js";
 import { ApiError } from "../errors.js";
 import { ExtensionAdminOps } from "../extensions/admin-ops.js";
 import { ExtensionAdmin } from "../extensions/admin-view.js";
@@ -103,6 +104,24 @@ export interface PluginReviewExtension {
     reviewHash: string;
     /** Sensitive permissions or migration warnings. */
     sensitive: boolean;
+    /**
+     * The extension's client code (client extensions spec §5.4, §9.1), for the 客户端代码 group of
+     * the review: every file of `extension.client` by its manifest key with its size, checked
+     * against its integrity when the import was prepared. Absent without client code.
+     */
+    client?: PluginReviewClient;
+}
+/** The client code of an extension in a review. */
+export interface PluginReviewClient {
+    /** Entry, styles and assets in that order; `path` is the manifest key (`./dist/client/...`). */
+    files: {
+        path: string;
+        size: number;
+    }[];
+    /** Total bytes. */
+    totalBytes: number;
+    /** The client API version the bundle was built against. */
+    apiVersion: number;
 }
 /** One connector template in a review. */
 export interface PluginReviewTemplate {
@@ -350,9 +369,10 @@ export interface StagedTarget {
 }
 /**
  * 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 declare function catalogPackageError(e: PluginPackageError | ExtensionPackageError): ApiError;
 export declare class PluginImport {
@@ -378,6 +398,8 @@ export declare class PluginImport {
     private readonly platform;
     /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
     private readonly maintenance;
+    /** The client build of a dropped org upload's package is deleted with it. */
+    private readonly clientBuilds;
     /** Where plugin files go (the kernel's object storage; the CLI's own, see {@link useCliStorage}). */
     private files;
     /**
@@ -398,7 +420,9 @@ export declare class PluginImport {
     /** The platform rows of a new item's components, written after the confirm's commit. */
     platform: PlatformComponents, 
     /** A failed platform sync enqueues a run of the migration job here (it heals the item). */
-    maintenance: Pick<Queue, "add">);
+    maintenance: Pick<Queue, "add">, 
+    /** The client build of a dropped org upload's package is deleted with it. */
+    clientBuilds: ClientBuilds);
     /** The kernel-schema handle of the current context (the transaction, else the pool). */
     private get db();
     /**