@capybara-hq/plugin-sdk 0.1.0-rc.6 → 0.1.0-rc.7

package/agent-docs/connector-templates.md

@@ -30,6 +30,7 @@ The file is strict. Top-level fields:
 | `displayName` | object | yes |
 | `description` | string | no |
 | `icon` | string | no |
+| `defaultEnabled` | boolean | no |
 | `template` | object | yes |
 <!-- /generated -->
 

package/agent-docs/plugin-format.md

@@ -37,6 +37,7 @@ file is strict: an unknown key is an error. Fields (agent templates are listed u
 | `skills` | array of object | no |
 | `connectorTemplates` | array of object | no |
 | `agents` | array of object | no |
+| `setupGuides` | array of object | no |
 | `extension` | object | no |
 <!-- /generated -->
 
@@ -51,6 +52,16 @@ Rules that the schema cannot show:
   Omit them to scan the default folders. Names and ids are unique within the plugin.
 - `dependencies`: plugin name plus semver range; no self-dependency.
 - `agents`: at most 64 templates (see `agent-templates`).
+- `setupGuides` (at most 8): setup material shown where a person configures what the plugin
+  brings. Each guide has an `id`, a `place` (`channel-connection`: 新建渠道 and the channel detail;
+  the plugin's extension must provide `channel@1`), a `title` and `steps` (`{ en, zh? }`, plain
+  text, a backtick pair shows as inline code) and `files` (`./` paths ending in `.tmpl`, `.yaml`,
+  `.yml`, `.json` or `.txt`, at most 64 KiB of text, with a `title` and a `language` of `yaml`,
+  `json` or `text`). A step or file may carry `mode` (`long_connection` or `webhook`) to apply to
+  that inbound mode only; ship one file per mode instead of conditionals. The kernel fills
+  `{{publicUrl}}`, `{{webhookUrl}}`, `{{signInCallbackUrl}}`, `{{connectionName}}`, `{{orgName}}`,
+  `{{pluginName}}`, `{{pluginVersion}}` and `{{mode}}` (never a secret); in YAML and JSON put a
+  placeholder inside double quotes. `capybara-plugin pack` refuses any other placeholder.
 - `extension` is written by the packer; never write it by hand.
 
 ## Importing

package/dist/cards.d.ts

@@ -10,6 +10,13 @@ export type ChannelCard = {
     toolName: string;
     appName?: string;
     agentName: string;
+    /**
+     * One line saying what the call does, as the web shows it: the tool's confirmation summary
+     * (e.g. a Platform operation's), else the tool's title and key argument; may be empty.
+     * Never the raw call input (it may hold a whole prompt, and a group sees the card); the
+     * full input is behind `webUrl`. Plain text written by the kernel from model-controlled
+     * values: render it as text, never as markup. The name is kept from when it held the input.
+     */
     inputPreview: string;
     scopes: ("once" | "session" | "always")[];
     expiresAt: string;

package/dist/cards.js

@@ -92,7 +92,7 @@ export function validateChannelCard(card) {
     }
 }
 /**
- * 把模型可控的值（审批标题、输入预览、提问标题、回答摘要）放进代码里，退回文本里它们不会变成链接、强调或 HTML：
+ * 把模型可控的值（审批标题、调用摘要、提问标题、回答摘要）放进代码里，退回文本里它们不会变成链接、强调或 HTML：
  * 单行用行内代码，多行用围栏代码块（以换行开头），分隔符都比值里最长的反引号串更长（CommonMark 6.1 / 4.5）。
  * 选代码而不是给标点加反斜杠：代码是 CommonMark / GFM 里唯一保证内容按原样显示的写法（反斜杠挡不住 GFM 的裸网址
  * 自动链接，各渠道转换器对反斜杠的处理也不一致）。
@@ -119,7 +119,7 @@ const TEXT = {
         connect: (app) => `[Connect] ${app} needs to be connected.`,
         tool: "Tool",
         agent: "Agent",
-        input: "Input",
+        summary: "Summary",
         status: "Status",
         reason: "Reason",
         expires: "Expires",
@@ -149,7 +149,7 @@ const TEXT = {
         connect: (app) => `【连接】需要连接 ${app}。`,
         tool: "工具",
         agent: "Agent",
-        input: "输入",
+        summary: "摘要",
         status: "状态",
         reason: "原因",
         expires: "过期时间",
@@ -187,7 +187,7 @@ export function renderCardAsText(card, locale) {
                 withCode(t.approval, asCode(card.title)),
                 line(t.tool, card.appName ? `${card.appName} / ${card.toolName}` : card.toolName),
                 line(t.agent, card.agentName),
-                line(t.input, asCode(card.inputPreview)),
+                ...(card.inputPreview !== "" ? [line(t.summary, asCode(card.inputPreview))] : []),
                 line(t.status, card.decidedBy ? `${state} (${card.decidedBy})` : state),
             ];
             if (card.state === "denied" && card.denyReason)

package/dist/channel.d.ts

@@ -21,6 +21,21 @@ export interface InboundSender {
     tenantId: string;
     displayName?: string;
     avatarUrl?: string;
+    /**
+     * The sender's time zone on the platform, an IANA name (`Asia/Shanghai`; Slack `users.info`
+     * `user.tz`), when the platform gives one. Include it on `message` events when you can get it
+     * within the acknowledgement deadline (cache it per user); leave it out otherwise. It wins over
+     * the person's account setting and the org default for the run's date and zone (run context
+     * spec §3.4); a name the kernel does not know is ignored.
+     */
+    timeZone?: string;
+    /**
+     * The sender's language on the platform: `zh` / `en` or a BCP 47 tag (`zh-CN`, `en-US`; Slack
+     * `users.info` with `include_locale=true`, `user.locale`), when the platform gives one. The
+     * kernel normalizes it (`zh` and `zh-*` are Chinese, any other tag English); it wins over the
+     * person's latest web UI language and the org default (run context spec §3.4).
+     */
+    locale?: string;
 }
 /**
  * 渠道交给内核的入站事件。插件的约定：
@@ -76,7 +91,11 @@ export interface ChannelSendArgs {
      */
     message: OutboundMessage;
     signal: AbortSignal;
-    /** 连接所属组织的界面语言：插件自己渲染的文案（卡片按钮、降级文本里的固定词）按它选择。 */
+    /**
+     * The recipient's language (the sender's platform language, else their latest web language,
+     * else the org's): the wording the extension renders itself (card buttons, fixed words in the
+     * text fallback) follows it.
+     */
     locale: Locale;
     /**
      * 幂等键（可选）：不超过 40 个 `[A-Za-z0-9_-]` 字符，同一条逻辑消息的每次重试（崩溃后其他副本续投、

package/dist/connector-auth.d.ts

@@ -50,6 +50,7 @@ export declare const ConnectorAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         client_secret_basic: "client_secret_basic";
         client_secret_post: "client_secret_post";
     }>>;
+    tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>, z.ZodObject<{
     type: z.ZodLiteral<"oauth_client">;
     ownership: z.ZodLiteral<"org">;
@@ -59,6 +60,7 @@ export declare const ConnectorAuthSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         client_secret_basic: "client_secret_basic";
         client_secret_post: "client_secret_post";
     }>>;
+    tokenTypes: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>], "type">;
 /** 认证预设（{@link ConnectorAuthSchema} 的输出）。 */
 export type ConnectorAuthPreset = z.infer<typeof ConnectorAuthSchema>;

package/dist/connector-auth.js

@@ -23,6 +23,19 @@ const Scopes = z
     .max(200)
     .regex(/^[\x21\x23-\x5B\x5D-\x7E]+$/, "Invalid scope"))
     .max(50);
+/**
+ * More `token_type` values the token endpoint may return for a bearer token (case-insensitive;
+ * `Bearer` and Slack's `user` are always accepted). The token is still sent as
+ * `Authorization: Bearer`. Never `DPoP`: such a token is bound to a key the kernel does not hold.
+ */
+const TokenTypes = z
+    .array(z
+    .string()
+    .min(1)
+    .max(32)
+    .regex(/^[A-Za-z][A-Za-z0-9_.-]*$/, "Invalid token type")
+    .refine((t) => t.toLowerCase() !== "dpop", "DPoP tokens are not bearer tokens"))
+    .max(5);
 /** 认证方式：只有类型与非密钥字段；凭据值走内核的 `credential` / 凭据接口。 */
 export const ConnectorAuthSchema = z.discriminatedUnion("type", [
     z.object({ type: z.literal("none") }).strict(),
@@ -57,6 +70,7 @@ export const ConnectorAuthSchema = z.discriminatedUnion("type", [
         scopes: Scopes.optional(),
         client: z.enum(["dcr", "manual"]),
         tokenAuthMethod: TokenAuthMethod.optional(),
+        tokenTypes: TokenTypes.optional(),
     })
         .strict()
         .superRefine((a, ctx) => {
@@ -91,6 +105,7 @@ export const ConnectorAuthSchema = z.discriminatedUnion("type", [
         tokenUrl: OAuthUrl,
         scopes: Scopes.optional(),
         tokenAuthMethod: TokenAuthMethod.optional(),
+        tokenTypes: TokenTypes.optional(),
     })
         .strict(),
 ]);

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export declare const SDK_VERSION = "0.1.0-rc.6";
+export declare const SDK_VERSION = "0.1.0-rc.7";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -23,6 +23,7 @@ export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";
 export * from "./sandbox.js";
 export * from "./secret.js";
+export * from "./setup-guide.js";
 export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export const SDK_VERSION = "0.1.0-rc.6";
+export const SDK_VERSION = "0.1.0-rc.7";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -23,6 +23,7 @@ export * from "./plugin-manifest.js";
 export * from "./plugin-package.js";
 export * from "./sandbox.js";
 export * from "./secret.js";
+export * from "./setup-guide.js";
 export * from "./skill.js";
 export * from "./skill-invocation.js";
 export * from "./storage.js";

package/dist/marketplace.d.ts

@@ -28,6 +28,8 @@ export declare const MARKETPLACE_LIMITS: {
     readonly plugins: 5000;
     readonly permissionKeys: 500;
     readonly urlChars: 2000;
+    /** Bytes of an entry icon (the plugin icon limit, {@link CONNECTOR_TEMPLATE_LIMITS}). */
+    readonly iconBytes: number;
 };
 /** Where a marketplace entry's plugin comes from. */
 export type MarketplaceSource = {
@@ -75,6 +77,18 @@ export interface MarketplaceEntry {
     };
     /** https URL. */
     homepage?: string;
+    /**
+     * The plugin's icon for marketplace lists, before the plugin is imported (display only; an
+     * imported plugin shows its own icon). Either an absolute `https://` URL whose path ends in
+     * `.svg` / `.png`, or `./<path>.svg|png` inside the marketplace's repository, read at the commit
+     * the marketplace was refreshed at (git marketplaces only; ignored in a marketplace fetched over
+     * http). The kernel downloads it on refresh (network rules of the marketplace downloads, never
+     * with the marketplace token), keeps it when it really is an svg / png of at most
+     * {@link MARKETPLACE_LIMITS}`.iconBytes`, and treats a URL's content as fixed: a new icon needs a
+     * new URL. A missing or invalid icon never fails the refresh. `capybara-plugin marketplace
+     * --write` fills it with the repository path of the plugin's `plugin.json` `icon`.
+     */
+    icon?: string;
     /**
      * This version is deprecated (`true`, or with a reason shown to admins): browsing lists it under
      * the plugin's other versions, never as the one to import, and the kernel refuses importing it
@@ -103,6 +117,8 @@ export interface MarketplaceParseOptions {
     /** Tests only: allow http on loopback addresses for `git` / `archive` URLs. */
     allowInsecureLoopback?: boolean;
 }
+/** An entry icon's file extension (of the URL's path, or of the repository path). */
+export declare const MARKETPLACE_ICON_RE: RegExp;
 /**
  * The zod schema of `marketplace.json` (https only; non-strict: unknown fields dropped). The JSON
  * Schema is generated with `z.toJSONSchema(MarketplaceManifestSchema, { io: "input" })`.
@@ -117,6 +133,16 @@ export declare function parseMarketplaceManifest(json: unknown, opts?: Marketpla
 };
 /** The entry's version: `version`, else the npm source's version, else `null` (the plugin's own). */
 export declare function marketplaceEntryVersion(e: MarketplaceEntry): string | null;
+/**
+ * The entry's icon (see {@link MarketplaceEntry.icon}): `{ url }` for an absolute URL, `{ path }`
+ * (normalized, without the leading `./`) for a path inside the marketplace's repository, `null`
+ * without one.
+ */
+export declare function marketplaceEntryIcon(e: Pick<MarketplaceEntry, "icon">): {
+    url: string;
+} | {
+    path: string;
+} | null;
 /**
  * The entry's deprecation (see {@link MarketplaceEntry.deprecated}): `null` when it is not
  * deprecated (absent or `false`), else its reason (`null` without one).

package/dist/marketplace.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { CATALOG_ITEM_NAME_RE, isSafePackagePath, NPM_PACKAGE_NAME_RE, SEMVER_VERSION_RE, SHA512_INTEGRITY_RE, } from "./plugin-package.js";
+import { CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, isSafePackagePath, NPM_PACKAGE_NAME_RE, SEMVER_VERSION_RE, SHA512_INTEGRITY_RE, } from "./plugin-package.js";
 /**
  * The marketplace manifest `marketplace.json` (package ecosystem spec §5.2): a list of plugins,
  * each with one source. One entry is one version. `capybara-plugin marketplace --write` lists one
@@ -29,6 +29,8 @@ export const MARKETPLACE_LIMITS = {
     plugins: 5000,
     permissionKeys: 500,
     urlChars: 2000,
+    /** Bytes of an entry icon (the plugin icon limit, {@link CONNECTOR_TEMPLATE_LIMITS}). */
+    iconBytes: CONNECTOR_TEMPLATE_LIMITS.iconBytes,
 };
 const M = MARKETPLACE_LIMITS;
 const MAX_ERRORS = 50;
@@ -37,6 +39,13 @@ const PERMISSION_KEY_RE = /^[a-z][a-z.]{0,62}(?::[^\r\n]{1,256})?$/;
 const SHA256_INTEGRITY_RE = /^sha256-[A-Za-z0-9+/]{43}=$/;
 const COMMIT_RE = /^[0-9a-f]{40}$/;
 const HTTPS_URL_RE = /^https:\/\/\S+$/;
+/** An entry icon's file extension (of the URL's path, or of the repository path). */
+export const MARKETPLACE_ICON_RE = /\.(?:svg|png)$/i;
+// Spelled without the `i` flag so the generated JSON Schema keeps the rule
+const ICON_EXT = "\\.(?:[sS][vV][gG]|[pP][nN][gG])";
+const ICON_URL_RE = new RegExp(`^https://[^\\s?#]+${ICON_EXT}(?:\\?[^\\s#]*)?$`);
+const ICON_URL_OR_LOOPBACK_RE = new RegExp(`^(?:https://[^\\s?#]+|http://(?:127\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}|localhost|\\[::1\\])(?::\\d{1,5})?/[^\\s?#]*)${ICON_EXT}(?:\\?[^\\s#]*)?$`);
+const ICON_PATH_RE = new RegExp(`^\\./[^\\s?#]+${ICON_EXT}$`);
 const HTTPS_OR_LOOPBACK_RE = /^(?:https:\/\/\S+|http:\/\/(?:127\.\d{1,3}\.\d{1,3}\.\d{1,3}|localhost|\[::1\])(?::\d{1,5})?(?:\/\S*)?)$/;
 const urlString = (re) => z
     .string()
@@ -55,6 +64,15 @@ const exactVersion = (what) => z
     .string()
     .max(256)
     .regex(SEMVER_VERSION_RE, { message: `${what} must be an exact semver version` });
+/** The path of a URL (empty when it does not parse). */
+const urlPathname = (s) => {
+    try {
+        return new URL(s).pathname;
+    }
+    catch {
+        return "";
+    }
+};
 /** `./<safe path>` inside the marketplace repo. */
 const repoPath = z
     .string()
@@ -144,6 +162,12 @@ function buildSchema(opts) {
         })
             .optional(),
         homepage: urlString(HTTPS_URL_RE).optional(),
+        icon: z
+            .union([
+            urlString(opts.allowInsecureLoopback ? ICON_URL_OR_LOOPBACK_RE : ICON_URL_RE).refine((s) => MARKETPLACE_ICON_RE.test(urlPathname(s)), { message: "an icon URL's path must end in .svg or .png" }),
+            repoPath.regex(ICON_PATH_RE, { message: "icon must be a .svg or .png file" }),
+        ])
+            .optional(),
         deprecated: z
             .union([
             z.boolean(),
@@ -248,6 +272,14 @@ const SOURCE_FORMS = ["path", "git", "npm", "archive"];
  * form the source uses instead, or that it must use exactly one form.
  */
 function explainSource(json, issue) {
+    if (issue.code === "invalid_union" && issue.path[issue.path.length - 1] === "icon") {
+        return [
+            {
+                path: issue.path,
+                message: 'icon must be an https URL whose path ends in .svg or .png, or a "./" path inside the repository ending in .svg or .png',
+            },
+        ];
+    }
     if (issue.code !== "invalid_union" || issue.path[issue.path.length - 1] !== "source") {
         return [issue];
     }
@@ -272,6 +304,16 @@ export function marketplaceEntryVersion(e) {
         return e.source.npm.version;
     return null;
 }
+/**
+ * The entry's icon (see {@link MarketplaceEntry.icon}): `{ url }` for an absolute URL, `{ path }`
+ * (normalized, without the leading `./`) for a path inside the marketplace's repository, `null`
+ * without one.
+ */
+export function marketplaceEntryIcon(e) {
+    if (e.icon === undefined)
+        return null;
+    return e.icon.startsWith("./") ? { path: e.icon.slice(2) } : { url: e.icon };
+}
 /**
  * The entry's deprecation (see {@link MarketplaceEntry.deprecated}): `null` when it is not
  * deprecated (absent or `false`), else its reason (`null` without one).

package/dist/plugin-manifest.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { type JsonSchema } from "./config-ui.js";
 import { type ConnectorTemplateSpec, type LocalizedName, type StaticExtensionManifest } from "./plugin-package.js";
+import { type PluginSetupGuide } from "./setup-guide.js";
 /**
  * The plugin manifest `.capybara-plugin/plugin.json` (package ecosystem spec §4.1). A plugin is a
  * bundle of at most one extension, skills and connector templates, packed as an npm-pack tgz:
@@ -123,6 +124,11 @@ export interface PluginManifest {
     connectorTemplates?: PluginConnectorTemplateRef[];
     /** Agent templates; omitted = scan `agents/*.md`. */
     agents?: PluginAgentRef[];
+    /**
+     * Setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): steps and template files the
+     * kernel renders for a place (`channel-connection`); see {@link PluginSetupGuide}.
+     */
+    setupGuides?: PluginSetupGuide[];
     extension?: PluginExtensionSection;
 }
 /** A connector template file `connectors/<id>.json`; the template id is the file's base name. */
@@ -131,6 +137,12 @@ export interface ConnectorTemplateFile {
     description?: string;
     /** Safe path relative to the plugin root (an optional leading `./`), .svg / .png. */
     icon?: string;
+    /**
+     * `false`: the template starts switched off in every org, even where its plugin is on, until an
+     * org admin switches it on (it then needs no org input while off). Default `true`: on wherever
+     * its plugin is. Ignored for a builtin plugin.
+     */
+    defaultEnabled?: boolean;
     /** Validated by {@link validateConnectorTemplate}. */
     template: ConnectorTemplateSpec;
 }

package/dist/plugin-manifest.js

@@ -5,6 +5,7 @@ import { CONFIG_UI_LIMITS } from "./config-ui.js";
 import { defineExtension, EXTENSION_NAME_RE } from "./define-extension.js";
 import { CATALOG_ITEM_NAME_RE, CONNECTOR_TEMPLATE_LIMITS, isSafePackagePath, SEMVER_VERSION_RE, validateConnectorTemplate, } from "./plugin-package.js";
 import { hasUpperBound } from "./semver-range.js";
+import { SETUP_GUIDE_FILE_RE, SETUP_GUIDE_LANGUAGES, SETUP_GUIDE_LIMITS, SETUP_GUIDE_MODES, SETUP_GUIDE_PLACES, } from "./setup-guide.js";
 /**
  * The plugin manifest `.capybara-plugin/plugin.json` (package ecosystem spec §4.1). A plugin is a
  * bundle of at most one extension, skills and connector templates, packed as an npm-pack tgz:
@@ -97,6 +98,33 @@ const configSchemaJson = z
     .refine((v) => new TextEncoder().encode(JSON.stringify(v)).length <= CONFIG_UI_LIMITS.configSchemaBytes, {
     message: `must be at most ${CONFIG_UI_LIMITS.configSchemaBytes} bytes of JSON (${CONFIG_UI_LIMITS.configSchemaBytes / 1024} KiB)`,
 });
+const guideText = (max, what) => z.strictObject({ en: text(max, `${what}.en`), zh: text(max, `${what}.zh`).optional() });
+const setupGuide = z.strictObject({
+    id: z.string().regex(CATALOG_ITEM_NAME_RE, {
+        message: "id must match ^[a-z0-9][a-z0-9-]{0,63}$",
+    }),
+    place: z.enum(SETUP_GUIDE_PLACES),
+    title: guideText(SETUP_GUIDE_LIMITS.titleChars, "title"),
+    steps: z
+        .array(z.strictObject({
+        en: text(SETUP_GUIDE_LIMITS.stepChars, "en"),
+        zh: text(SETUP_GUIDE_LIMITS.stepChars, "zh").optional(),
+        mode: z.string().max(64).optional(),
+    }))
+        .max(SETUP_GUIDE_LIMITS.steps)
+        .optional(),
+    files: z
+        .array(z.strictObject({
+        path: dotPath("path").regex(SETUP_GUIDE_FILE_RE, {
+            message: "path must be a .tmpl, .yaml, .yml, .json or .txt file",
+        }),
+        title: guideText(SETUP_GUIDE_LIMITS.titleChars, "title"),
+        language: z.enum(SETUP_GUIDE_LANGUAGES),
+        mode: z.string().max(64).optional(),
+    }))
+        .max(SETUP_GUIDE_LIMITS.files)
+        .optional(),
+});
 const extensionSection = z.strictObject({
     entry: dotPath("entry").refine((p) => p.endsWith(".mjs"), {
         message: "entry must be a .mjs file",
@@ -168,6 +196,7 @@ const schema = z
     }))
         .max(L.agents)
         .optional(),
+    setupGuides: z.array(setupGuide).max(SETUP_GUIDE_LIMITS.guides).optional(),
     extension: extensionSection.optional(),
 })
     .superRefine((m, ctx) => {
@@ -206,6 +235,37 @@ const schema = z
             issue(["agents", i, "path"], `duplicate agent template path ${a.path}`);
         agentPaths.add(a.path);
     });
+    const guideIds = new Set();
+    m.setupGuides?.forEach((g, i) => {
+        if (guideIds.has(g.id))
+            issue(["setupGuides", i, "id"], `duplicate setup guide id ${g.id}`);
+        guideIds.add(g.id);
+        if ((g.steps?.length ?? 0) === 0 && (g.files?.length ?? 0) === 0) {
+            issue(["setupGuides", i], "a setup guide needs at least one step or file");
+        }
+        const modes = SETUP_GUIDE_MODES[g.place];
+        const badMode = (mode, path) => {
+            if (mode !== undefined && !modes.includes(mode)) {
+                issue(path, `mode must be one of ${modes.join(", ")} for place ${g.place}`);
+            }
+        };
+        g.steps?.forEach((s, j) => {
+            badMode(s.mode, ["setupGuides", i, "steps", j, "mode"]);
+        });
+        const paths = new Set();
+        g.files?.forEach((f, j) => {
+            badMode(f.mode, ["setupGuides", i, "files", j, "mode"]);
+            if (paths.has(f.path)) {
+                issue(["setupGuides", i, "files", j, "path"], `duplicate file ${f.path} in the guide`);
+            }
+            paths.add(f.path);
+        });
+        if (g.place === "channel-connection" &&
+            m.extension !== undefined &&
+            !m.extension.manifest.provides.some((p) => p.startsWith("channel@"))) {
+            issue(["setupGuides", i, "place"], "a channel-connection guide needs the plugin's extension to provide channel@1");
+        }
+    });
     if (m.extension === undefined &&
         m.skills?.length === 0 &&
         m.connectorTemplates?.length === 0 &&
@@ -281,6 +341,7 @@ const templateFile = z
         message: "icon must be a relative .svg or .png path inside the plugin",
     })
         .optional(),
+    defaultEnabled: z.boolean().optional(),
     template,
 })
     // Field rules (no credentials, auth presets, editableEndpoint, ...) belong to validateConnectorTemplate.

package/dist/setup-guide.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Plugin setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): setup material a plugin
+ * ships (steps and template files such as Slack's app manifest) that the kernel renders with a
+ * fixed set of safe, deterministic variables and the web shows where the person needs it. The
+ * format lives in `plugin.json` `setupGuides` ({@link PluginSetupGuide}); this module holds the
+ * places, their modes and variables, the limits and the pure renderer.
+ *
+ * Placeholders are `{{name}}` (spaces inside the braces allowed) with `name` matching
+ * `[A-Za-z][A-Za-z0-9]*`. There is no other syntax: no conditionals, loops, filters or escapes. A
+ * placeholder the place does not define, or one without a value, stays as written.
+ */
+/** Where a guide is shown. `channel-connection`: 新建渠道 and the channel detail page. */
+export declare const SETUP_GUIDE_PLACES: readonly ["channel-connection"];
+export type SetupGuidePlace = (typeof SETUP_GUIDE_PLACES)[number];
+/**
+ * The modes of each place: a step or file with `mode` applies to that mode only.
+ * `channel-connection`: the connection's `inboundMode`.
+ */
+export declare const SETUP_GUIDE_MODES: Readonly<Record<SetupGuidePlace, readonly string[]>>;
+/**
+ * The variables of each place. None is a secret: the kernel fills them from public URLs, names and
+ * versions only (`publicUrl`, `webhookUrl`, `signInCallbackUrl`, `connectionName`, `orgName`,
+ * `pluginName`, `pluginVersion`, `mode`).
+ */
+export declare const SETUP_GUIDE_VARIABLES: Readonly<Record<SetupGuidePlace, readonly string[]>>;
+/** Languages of a template file: the code block's label and how values are escaped. */
+export declare const SETUP_GUIDE_LANGUAGES: readonly ["yaml", "json", "text"];
+export type SetupGuideLanguage = (typeof SETUP_GUIDE_LANGUAGES)[number];
+/** Limits of setup guides. */
+export declare const SETUP_GUIDE_LIMITS: {
+    /** Guides per plugin. */
+    readonly guides: 8;
+    /** Steps per guide. */
+    readonly steps: 20;
+    /** Files per guide. */
+    readonly files: 8;
+    /** Characters of a step (each language). */
+    readonly stepChars: 2000;
+    /** Characters of a title (each language). */
+    readonly titleChars: 100;
+    /** Bytes of a template file. */
+    readonly fileBytes: number;
+};
+/** File names a template file may have (checked on the path). */
+export declare const SETUP_GUIDE_FILE_RE: RegExp;
+/** Localized text: English, optional Chinese (falls back to English). */
+export interface SetupGuideText {
+    en: string;
+    zh?: string;
+}
+/** A step: plain text (a backtick pair is shown as inline code), optionally for one mode. */
+export interface SetupGuideStep extends SetupGuideText {
+    mode?: string;
+}
+/** A template file of a guide. */
+export interface SetupGuideFile {
+    /** `./…` inside the plugin, `.tmpl` / `.yaml` / `.yml` / `.json` / `.txt`. */
+    path: string;
+    title: SetupGuideText;
+    language: SetupGuideLanguage;
+    mode?: string;
+}
+/** A setup guide in `plugin.json` `setupGuides`. */
+export interface PluginSetupGuide {
+    /** `^[a-z0-9][a-z0-9-]{0,63}$`, unique in the plugin. */
+    id: string;
+    place: SetupGuidePlace;
+    title: SetupGuideText;
+    steps?: SetupGuideStep[];
+    files?: SetupGuideFile[];
+}
+/** The placeholder names a text uses, each once, in order of first use. */
+export declare function setupGuidePlaceholders(text: string): string[];
+/** The placeholders of a text that the place does not define (the toolchain refuses them). */
+export declare function unknownSetupGuidePlaceholders(text: string, place: SetupGuidePlace): string[];
+/** The modes a guide's steps and files use, in the place's order (empty: no mode switch). */
+export declare function setupGuideModes(guide: PluginSetupGuide): string[];
+/**
+ * Renders a guide text: each `{{name}}` with a value in `values` is replaced by it, escaped for
+ * `language` (`yaml` / `json`: JSON-string-escaped without quotes, so a placeholder inside double
+ * quotes stays one string; `text`: control characters become spaces). A placeholder whose value is
+ * null or undefined stays as written and is listed in `unresolved` when `known` holds it; one not
+ * in `known` stays as written and is not listed. Never runs code; deterministic.
+ */
+export declare function renderSetupGuideText(text: string, values: Readonly<Record<string, string | null | undefined>>, language: SetupGuideLanguage, known?: readonly string[]): {
+    text: string;
+    unresolved: string[];
+};
+/**
+ * Whether a guide's template file is usable: present, at most {@link SETUP_GUIDE_LIMITS}`.fileBytes`,
+ * valid UTF-8 text without NUL. The problem (English, naming the path), or undefined when it is.
+ * Shared by the packer and the kernel's package reader.
+ */
+export declare function setupGuideFileProblem(path: string, data: Uint8Array | undefined): string | undefined;

package/dist/setup-guide.js

@@ -0,0 +1,135 @@
+/**
+ * Plugin setup guides (spec `2026-11-08-plugin-setup-guides-design.md`): setup material a plugin
+ * ships (steps and template files such as Slack's app manifest) that the kernel renders with a
+ * fixed set of safe, deterministic variables and the web shows where the person needs it. The
+ * format lives in `plugin.json` `setupGuides` ({@link PluginSetupGuide}); this module holds the
+ * places, their modes and variables, the limits and the pure renderer.
+ *
+ * Placeholders are `{{name}}` (spaces inside the braces allowed) with `name` matching
+ * `[A-Za-z][A-Za-z0-9]*`. There is no other syntax: no conditionals, loops, filters or escapes. A
+ * placeholder the place does not define, or one without a value, stays as written.
+ */
+/** Where a guide is shown. `channel-connection`: 新建渠道 and the channel detail page. */
+export const SETUP_GUIDE_PLACES = ["channel-connection"];
+/**
+ * The modes of each place: a step or file with `mode` applies to that mode only.
+ * `channel-connection`: the connection's `inboundMode`.
+ */
+export const SETUP_GUIDE_MODES = {
+    "channel-connection": ["long_connection", "webhook"],
+};
+/**
+ * The variables of each place. None is a secret: the kernel fills them from public URLs, names and
+ * versions only (`publicUrl`, `webhookUrl`, `signInCallbackUrl`, `connectionName`, `orgName`,
+ * `pluginName`, `pluginVersion`, `mode`).
+ */
+export const SETUP_GUIDE_VARIABLES = {
+    "channel-connection": [
+        "publicUrl",
+        "webhookUrl",
+        "signInCallbackUrl",
+        "connectionName",
+        "orgName",
+        "pluginName",
+        "pluginVersion",
+        "mode",
+    ],
+};
+/** Languages of a template file: the code block's label and how values are escaped. */
+export const SETUP_GUIDE_LANGUAGES = ["yaml", "json", "text"];
+/** Limits of setup guides. */
+export const SETUP_GUIDE_LIMITS = {
+    /** Guides per plugin. */
+    guides: 8,
+    /** Steps per guide. */
+    steps: 20,
+    /** Files per guide. */
+    files: 8,
+    /** Characters of a step (each language). */
+    stepChars: 2000,
+    /** Characters of a title (each language). */
+    titleChars: 100,
+    /** Bytes of a template file. */
+    fileBytes: 64 * 1024,
+};
+/** File names a template file may have (checked on the path). */
+export const SETUP_GUIDE_FILE_RE = /\.(?:tmpl|ya?ml|json|txt)$/i;
+const PLACEHOLDER_RE = /\{\{\s*([A-Za-z][A-Za-z0-9]*)\s*\}\}/g;
+/** The placeholder names a text uses, each once, in order of first use. */
+export function setupGuidePlaceholders(text) {
+    const out = [];
+    for (const m of text.matchAll(PLACEHOLDER_RE)) {
+        const name = m[1];
+        if (!out.includes(name))
+            out.push(name);
+    }
+    return out;
+}
+/** The placeholders of a text that the place does not define (the toolchain refuses them). */
+export function unknownSetupGuidePlaceholders(text, place) {
+    const known = SETUP_GUIDE_VARIABLES[place];
+    return setupGuidePlaceholders(text).filter((n) => !known.includes(n));
+}
+/** The modes a guide's steps and files use, in the place's order (empty: no mode switch). */
+export function setupGuideModes(guide) {
+    const used = new Set();
+    for (const s of guide.steps ?? [])
+        if (s.mode !== undefined)
+            used.add(s.mode);
+    for (const f of guide.files ?? [])
+        if (f.mode !== undefined)
+            used.add(f.mode);
+    return SETUP_GUIDE_MODES[guide.place].filter((m) => used.has(m));
+}
+// biome-ignore lint/suspicious/noControlCharactersInRegex: control characters are what is replaced
+const CONTROL_RE = /[\u0000-\u001f\u007f]/g;
+/** A value as inserted into a text of the language (see {@link renderSetupGuideText}). */
+function escapeValue(value, language) {
+    if (language === "text")
+        return value.replace(CONTROL_RE, " ");
+    // JSON string escaping without the quotes: valid inside a JSON string and a YAML double-quoted
+    // scalar, whatever the value holds
+    return JSON.stringify(value).slice(1, -1);
+}
+/**
+ * Renders a guide text: each `{{name}}` with a value in `values` is replaced by it, escaped for
+ * `language` (`yaml` / `json`: JSON-string-escaped without quotes, so a placeholder inside double
+ * quotes stays one string; `text`: control characters become spaces). A placeholder whose value is
+ * null or undefined stays as written and is listed in `unresolved` when `known` holds it; one not
+ * in `known` stays as written and is not listed. Never runs code; deterministic.
+ */
+export function renderSetupGuideText(text, values, language, known = Object.keys(values)) {
+    const unresolved = [];
+    const out = text.replace(PLACEHOLDER_RE, (whole, name) => {
+        if (!known.includes(name))
+            return whole;
+        const v = Object.hasOwn(values, name) ? values[name] : undefined;
+        if (v === null || v === undefined) {
+            if (!unresolved.includes(name))
+                unresolved.push(name);
+            return whole;
+        }
+        return escapeValue(v, language);
+    });
+    return { text: out, unresolved };
+}
+/**
+ * Whether a guide's template file is usable: present, at most {@link SETUP_GUIDE_LIMITS}`.fileBytes`,
+ * valid UTF-8 text without NUL. The problem (English, naming the path), or undefined when it is.
+ * Shared by the packer and the kernel's package reader.
+ */
+export function setupGuideFileProblem(path, data) {
+    if (data === undefined)
+        return `${path} not found in the package`;
+    if (data.byteLength > SETUP_GUIDE_LIMITS.fileBytes) {
+        return `${path} is larger than ${SETUP_GUIDE_LIMITS.fileBytes} bytes`;
+    }
+    let text;
+    try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(data);
+    }
+    catch {
+        return `${path} is not valid UTF-8 text`;
+    }
+    return text.includes("\u0000") ? `${path} is not a text file (it contains NUL)` : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capybara-hq/plugin-sdk",
-  "version": "0.1.0-rc.6",
+  "version": "0.1.0-rc.7",
   "description": "Capybara plugin SDK: the types and pure functions plugins are written against",
   "license": "Apache-2.0",
   "repository": {

package/schemas/connector-template.v1.schema.json

@@ -36,6 +36,9 @@
       "type": "string",
       "maxLength": 512
     },
+    "defaultEnabled": {
+      "type": "boolean"
+    },
     "template": {
       "type": "object",
       "properties": {

package/schemas/marketplace.v1.schema.json

@@ -129,6 +129,20 @@
             "maxLength": 2000,
             "pattern": "^https:\\/\\/\\S+$"
           },
+          "icon": {
+            "anyOf": [
+              {
+                "type": "string",
+                "maxLength": 2000,
+                "pattern": "^https:\\/\\/[^\\s?#]+\\.(?:[sS][vV][gG]|[pP][nN][gG])(?:\\?[^\\s#]*)?$"
+              },
+              {
+                "type": "string",
+                "maxLength": 512,
+                "pattern": "^\\.\\/[^\\s?#]+\\.(?:[sS][vV][gG]|[pP][nN][gG])$"
+              }
+            ]
+          },
           "deprecated": {
             "anyOf": [
               {

package/schemas/plugin.v1.schema.json

@@ -194,6 +194,142 @@
         "additionalProperties": false
       }
     },
+    "setupGuides": {
+      "maxItems": 8,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9-]{0,63}$"
+          },
+          "place": {
+            "type": "string",
+            "enum": [
+              "channel-connection"
+            ]
+          },
+          "title": {
+            "type": "object",
+            "properties": {
+              "en": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100,
+                "pattern": "\\S"
+              },
+              "zh": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 100,
+                "pattern": "\\S"
+              }
+            },
+            "required": [
+              "en"
+            ],
+            "additionalProperties": false
+          },
+          "steps": {
+            "maxItems": 20,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "en": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 2000,
+                  "pattern": "\\S"
+                },
+                "zh": {
+                  "type": "string",
+                  "minLength": 1,
+                  "maxLength": 2000,
+                  "pattern": "\\S"
+                },
+                "mode": {
+                  "type": "string",
+                  "maxLength": 64
+                }
+              },
+              "required": [
+                "en"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "files": {
+            "maxItems": 8,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "path": {
+                  "type": "string",
+                  "minLength": 3,
+                  "maxLength": 512,
+                  "allOf": [
+                    {
+                      "pattern": "^\\.\\/"
+                    },
+                    {
+                      "pattern": "\\.(?:tmpl|ya?ml|json|txt)$"
+                    }
+                  ]
+                },
+                "title": {
+                  "type": "object",
+                  "properties": {
+                    "en": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 100,
+                      "pattern": "\\S"
+                    },
+                    "zh": {
+                      "type": "string",
+                      "minLength": 1,
+                      "maxLength": 100,
+                      "pattern": "\\S"
+                    }
+                  },
+                  "required": [
+                    "en"
+                  ],
+                  "additionalProperties": false
+                },
+                "language": {
+                  "type": "string",
+                  "enum": [
+                    "yaml",
+                    "json",
+                    "text"
+                  ]
+                },
+                "mode": {
+                  "type": "string",
+                  "maxLength": 64
+                }
+              },
+              "required": [
+                "path",
+                "title",
+                "language"
+              ],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": [
+          "id",
+          "place",
+          "title"
+        ],
+        "additionalProperties": false
+      }
+    },
     "extension": {
       "type": "object",
       "properties": {