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

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

@@ -10,11 +10,12 @@ A plugin is a directory, packed into a `.tgz` with `capybara-plugin pack` (the p
   skills/<name>/SKILL.md         skills (scanned unless plugin.json lists them)
   connectors/<id>.json           connector templates (scanned unless listed)
   agents/<name>.md               agent templates (scanned unless listed)
+  themes/<id>.json               themes (scanned unless listed)
   src/index.ts                   the extension (optional; bundled by the packer)
   migrations/*.sql, ui/**        extension migrations and UI files (optional)
 ```
 
-A plugin without `src/index.ts` is declarative: skills and templates only, no code runs.
+A plugin without `src/index.ts` is declarative: skills, templates and themes only, no code runs.
 
 ## plugin.json
 
@@ -37,6 +38,8 @@ 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 |
+| `themes` | array of object | no |
+| `setupGuides` | array of object | no |
 | `extension` | object | no |
 <!-- /generated -->
 
@@ -47,10 +50,22 @@ Rules that the schema cannot show:
   release candidates, ranges on official packages are written `^0.1.0-rc.0`.
 - `description` is a string or `{ en, zh? }`; `displayName` is `{ zh, en }`.
 - `icon` is a `./` path to an `.svg` or `.png` inside the plugin.
-- `skills`, `connectorTemplates`, `agents` list paths starting with `./` that stay inside the plugin.
+- `skills`, `connectorTemplates`, `agents`, `themes` list paths starting with `./` that stay inside the plugin.
   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`).
+- `themes`: at most 10 `<id>.json` files; the id is the file's base name. A theme file is checked
+  by `parseThemeFile` (schema `https://capybarahq.com/schemas/theme.v1.schema.json`).
+- `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.8";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -23,9 +23,14 @@ 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";
+export * from "./theme.js";
+export * from "./theme-assets.js";
+export * from "./theme-readability.js";
+export * from "./theme-tokens.generated.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.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.8";
 export * from "./agent-template.js";
 export * from "./bootstrap.js";
 export * from "./cards.js";
@@ -23,9 +23,14 @@ 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";
+export * from "./theme.js";
+export * from "./theme-assets.js";
+export * from "./theme-readability.js";
+export * from "./theme-tokens.generated.js";
 export * from "./tool.js";
 export * from "./tool-key.js";
 export * from "./ui.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,9 +1,12 @@
 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";
+import { type PluginThemeRef } from "./theme.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:
+ * bundle of at most one extension, skills, connector templates, agent templates and themes, packed as
+ * an npm-pack tgz:
  *
  * ```
  * package/package.json                  npm metadata; version equals plugin.json version
@@ -11,13 +14,14 @@ import { type ConnectorTemplateSpec, type LocalizedName, type StaticExtensionMan
  * package/skills/<name>/SKILL.md        skills
  * package/connectors/<id>.json          connector templates ({@link ConnectorTemplateFile})
  * package/agents/<name>.md              agent templates (parsed by `parseAgentTemplate`)
+ * package/themes/<id>.json              themes (parsed by `parseThemeFile`)
  * package/dist/index.mjs                extension entry (only with an extension)
  * package/migrations/*.sql, package/ui/**
  * ```
  *
  * Paths start with `./` and stay inside the plugin root. Omitting `skills` / `connectorTemplates`
- * / `agents` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md`" (done by the
- * kernel when it reads the package). `extension` is written by the packer, never by hand.
+ * / `agents` / `themes` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md` /
+ * `themes/*.json`" (done by the kernel when it reads the package). `extension` is written by the packer, never by hand.
  *
  * The committed JSON Schema (`schemas/plugin.v1.schema.json`) is generated from
  * {@link PluginManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
@@ -39,6 +43,8 @@ export declare const PLUGIN_MANIFEST_LIMITS: {
     readonly connectorTemplates: 20;
     /** Agent templates ({@link AGENT_TEMPLATE_LIMITS}`.perPlugin`). */
     readonly agents: 64;
+    /** Themes ({@link THEME_LIMITS}`.perPlugin`). */
+    readonly themes: 10;
     readonly descriptionChars: 1024;
     readonly publisherChars: 100;
     readonly displayNameChars: 100;
@@ -123,6 +129,13 @@ export interface PluginManifest {
     connectorTemplates?: PluginConnectorTemplateRef[];
     /** Agent templates; omitted = scan `agents/*.md`. */
     agents?: PluginAgentRef[];
+    /** Themes; omitted = scan `themes/*.json`. */
+    themes?: PluginThemeRef[];
+    /**
+     * 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 +144,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,9 +5,12 @@ 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";
+import { THEME_LIMITS, themeIdOf } from "./theme.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:
+ * bundle of at most one extension, skills, connector templates, agent templates and themes, packed as
+ * an npm-pack tgz:
  *
  * ```
  * package/package.json                  npm metadata; version equals plugin.json version
@@ -15,13 +18,14 @@ import { hasUpperBound } from "./semver-range.js";
  * package/skills/<name>/SKILL.md        skills
  * package/connectors/<id>.json          connector templates ({@link ConnectorTemplateFile})
  * package/agents/<name>.md              agent templates (parsed by `parseAgentTemplate`)
+ * package/themes/<id>.json              themes (parsed by `parseThemeFile`)
  * package/dist/index.mjs                extension entry (only with an extension)
  * package/migrations/*.sql, package/ui/**
  * ```
  *
  * Paths start with `./` and stay inside the plugin root. Omitting `skills` / `connectorTemplates`
- * / `agents` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md`" (done by the
- * kernel when it reads the package). `extension` is written by the packer, never by hand.
+ * / `agents` / `themes` means "scan `skills/*\/SKILL.md` / `connectors/*.json` / `agents/*.md` /
+ * `themes/*.json`" (done by the kernel when it reads the package). `extension` is written by the packer, never by hand.
  *
  * The committed JSON Schema (`schemas/plugin.v1.schema.json`) is generated from
  * {@link PluginManifestSchema} by `pnpm gen:package-schemas` and drift-checked by
@@ -43,6 +47,8 @@ export const PLUGIN_MANIFEST_LIMITS = {
     connectorTemplates: 20,
     /** Agent templates ({@link AGENT_TEMPLATE_LIMITS}`.perPlugin`). */
     agents: AGENT_TEMPLATE_LIMITS.perPlugin,
+    /** Themes ({@link THEME_LIMITS}`.perPlugin`). */
+    themes: THEME_LIMITS.perPlugin,
     descriptionChars: 1024,
     publisherChars: 100,
     displayNameChars: 100,
@@ -97,6 +103,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 +201,13 @@ const schema = z
     }))
         .max(L.agents)
         .optional(),
+    themes: z
+        .array(z.strictObject({
+        path: dotPath("path").refine((p) => p.endsWith(".json") && CATALOG_ITEM_NAME_RE.test(themeIdOf(p)), { message: "path must be a <id>.json file with id matching ^[a-z0-9][a-z0-9-]{0,63}$" }),
+    }))
+        .max(L.themes)
+        .optional(),
+    setupGuides: z.array(setupGuide).max(SETUP_GUIDE_LIMITS.guides).optional(),
     extension: extensionSection.optional(),
 })
     .superRefine((m, ctx) => {
@@ -206,11 +246,50 @@ const schema = z
             issue(["agents", i, "path"], `duplicate agent template path ${a.path}`);
         agentPaths.add(a.path);
     });
+    const themeIds = new Set();
+    m.themes?.forEach((t, i) => {
+        const id = themeIdOf(t.path);
+        if (themeIds.has(id))
+            issue(["themes", i, "path"], `duplicate theme id ${id}`);
+        themeIds.add(id);
+    });
+    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 &&
-        (m.agents === undefined || m.agents.length === 0)) {
-        issue([], "a plugin must contain an extension, a skill, a connector template or an agent template");
+        (m.agents === undefined || m.agents.length === 0) &&
+        (m.themes === undefined || m.themes.length === 0)) {
+        issue([], "a plugin must contain an extension, a skill, a connector template, an agent template or a theme");
     }
     const ext = m.extension;
     if (ext === undefined)
@@ -281,6 +360,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.