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

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/sandbox.d.ts

@@ -21,11 +21,23 @@ export interface SandboxLimits {
     /** Egress allowlist (used when `egress` is `allowlist`); each entry passes {@link validateAllowHost}. */
     allowHosts: string[];
 }
+/** The absolute roots inside one instance (a device may place them anywhere on its host). */
+export interface SandboxRoots {
+    workspace: string;
+    skills: string;
+    tmp: string;
+}
+/** The roots every container-like provider uses; the same paths as {@link SANDBOX_ROOTS}. */
+export declare const DEFAULT_SANDBOX_ROOTS: Readonly<SandboxRoots>;
 /** The provider's instance handle. */
 export interface SandboxHandle {
     /** The provider's instance id. */
     id: string;
+    /** The instance's roots; absent means {@link DEFAULT_SANDBOX_ROOTS}. */
+    roots?: SandboxRoots;
 }
+/** The roots of an instance, falling back to {@link DEFAULT_SANDBOX_ROOTS}. */
+export declare function rootsOf(h: SandboxHandle): SandboxRoots;
 /** The provider's file system handle (an environment's files, independent of any instance). */
 export interface FileSystemHandle {
     /** The provider's file system id. */
@@ -226,7 +238,17 @@ export interface SandboxProvider {
         isDir: boolean;
     } | null>;
 }
-/** 校验沙箱内路径：返回错误列表，空数组表示合法。 */
-export declare function validateSandboxPath(p: string): string[];
+/**
+ * The root-independent checks of a path inside an instance (non-empty, at most 4096 characters, no
+ * control characters or backslashes, absolute, no empty or `..` segments); returns the errors,
+ * empty when valid. {@link validateSandboxPath} adds root membership.
+ */
+export declare function validateSandboxPathShape(p: string): string[];
+/**
+ * Checks a path inside an instance; returns the errors, empty when valid: the
+ * {@link validateSandboxPathShape} checks, then root membership. `roots`: the instance's roots
+ * ({@link rootsOf}); absent means {@link SANDBOX_ROOTS}. The path must be one of them or under one.
+ */
+export declare function validateSandboxPath(p: string, roots?: SandboxRoots): string[];
 /** 校验出站白名单主机名：小写、无协议与端口、可选前导 `*.`、IDN 只认 punycode。 */
 export declare function validateAllowHost(h: string): string[];

package/dist/sandbox.js

@@ -13,6 +13,16 @@ export const SANDBOX_EXTENSION_POINT = "sandbox@2";
 /** The roots inside the sandbox the model may access. */
 export const SANDBOX_ROOTS = ["/workspace", "/skills", "/tmp"];
 const MAX_PATH_LENGTH = 4096;
+/** The roots every container-like provider uses; the same paths as {@link SANDBOX_ROOTS}. */
+export const DEFAULT_SANDBOX_ROOTS = Object.freeze({
+    workspace: "/workspace",
+    skills: "/skills",
+    tmp: "/tmp",
+});
+/** The roots of an instance, falling back to {@link DEFAULT_SANDBOX_ROOTS}. */
+export function rootsOf(h) {
+    return h.roots ?? DEFAULT_SANDBOX_ROOTS;
+}
 /**
  * The instance is definitely gone on the provider's side (container removed, E2B sandbox expired).
  * `exec` / `readFile` / `writeFile` / `stat` must throw it (not a plain Error) when they find the
@@ -58,8 +68,12 @@ export function isFileSystemGoneError(e) {
 export const SANDBOX_TAG_RE = /^[a-z0-9-]{1,64}$/;
 // biome-ignore lint/suspicious/noControlCharactersInRegex: 正是要拦控制字符
 const CONTROL = /[\u0000-\u001f\u007f]/;
-/** 校验沙箱内路径：返回错误列表，空数组表示合法。 */
-export function validateSandboxPath(p) {
+/**
+ * The root-independent checks of a path inside an instance (non-empty, at most 4096 characters, no
+ * control characters or backslashes, absolute, no empty or `..` segments); returns the errors,
+ * empty when valid. {@link validateSandboxPath} adds root membership.
+ */
+export function validateSandboxPathShape(p) {
     if (typeof p !== "string" || p.length === 0)
         return ["path must be a non-empty string"];
     if (p.length > MAX_PATH_LENGTH)
@@ -72,22 +86,41 @@ export function validateSandboxPath(p) {
         return ["path must be absolute"];
     if (p.includes("//"))
         return ["path must not contain empty segments"];
-    const errors = [];
     for (const seg of p.split("/")) {
         let decoded = seg;
         try {
             decoded = decodeURIComponent(seg);
         }
         catch {
-            // 非法百分号编码按字面处理
+            // invalid percent-encoding is taken literally
         }
         if (seg === ".." || decoded === ".." || decoded.includes("/") || decoded.includes("\\")) {
-            errors.push("path must not contain '..' segments");
-            break;
+            return ["path must not contain '..' segments"];
         }
     }
-    if (!SANDBOX_ROOTS.some((r) => p === r || p.startsWith(`${r}/`))) {
-        errors.push(`path must be under ${SANDBOX_ROOTS.join(", ")}`);
+    return [];
+}
+/** A structural error after which {@link validateSandboxPath} stops (before the root check). */
+const STOPS = new Set([
+    "path must be a non-empty string",
+    `path must be at most ${MAX_PATH_LENGTH} characters`,
+    "path must not contain control characters",
+    "path must not contain backslashes",
+    "path must be absolute",
+    "path must not contain empty segments",
+]);
+/**
+ * Checks a path inside an instance; returns the errors, empty when valid: the
+ * {@link validateSandboxPathShape} checks, then root membership. `roots`: the instance's roots
+ * ({@link rootsOf}); absent means {@link SANDBOX_ROOTS}. The path must be one of them or under one.
+ */
+export function validateSandboxPath(p, roots) {
+    const errors = validateSandboxPathShape(p);
+    if (errors.some((e) => STOPS.has(e)))
+        return errors;
+    const allowed = roots === undefined ? SANDBOX_ROOTS : [roots.workspace, roots.skills, roots.tmp];
+    if (!allowed.some((r) => p === r || p.startsWith(`${r}/`))) {
+        errors.push(`path must be under ${allowed.join(", ")}`);
     }
     return errors;
 }

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/dist/skill-invocation.d.ts

@@ -27,13 +27,14 @@ export declare function parseSkillArguments(args: string): string[];
 /**
  * A skill body with its arguments substituted (see the file header), without the wrapper.
  * `skillName` is the resolved skill's bare name and `digest` its version's `skillDigest`:
- * `${CLAUDE_SKILL_DIR}` becomes `/skills/<skillName>@<digest>` (a qualified `<plugin>:<name>` or a
- * digest that is not 12 lowercase hex digits throws a `TypeError`). `args` is trimmed;
+ * `${CLAUDE_SKILL_DIR}` becomes `<skillsRoot>/<skillName>@<digest>` (`skillsRoot`: the instance's
+ * skills root, default `/skills`; a qualified `<plugin>:<name>` or a digest that is not 12
+ * lowercase hex digits throws a `TypeError`). `args` is trimmed;
  * more than {@link SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters throw a `RangeError`, and
  * so does a result longer than {@link SKILL_INVOCATION_LIMITS.renderedMaxChars} (checked while
  * substituting, before the long string is built).
  */
-export declare function renderSkillBody(body: string, invocation: SkillInvocation, args: string, skillName: string, digest: string): string;
+export declare function renderSkillBody(body: string, invocation: SkillInvocation, args: string, skillName: string, digest: string, skillsRoot?: string): string;
 /** Input of {@link renderSkillInvocation}. */
 export interface RenderSkillInvocationInput {
     /**

package/dist/skill-invocation.js

@@ -112,16 +112,17 @@ const tooLong = () => new RangeError(`the rendered skill must be at most ${SKILL
 /**
  * A skill body with its arguments substituted (see the file header), without the wrapper.
  * `skillName` is the resolved skill's bare name and `digest` its version's `skillDigest`:
- * `${CLAUDE_SKILL_DIR}` becomes `/skills/<skillName>@<digest>` (a qualified `<plugin>:<name>` or a
- * digest that is not 12 lowercase hex digits throws a `TypeError`). `args` is trimmed;
+ * `${CLAUDE_SKILL_DIR}` becomes `<skillsRoot>/<skillName>@<digest>` (`skillsRoot`: the instance's
+ * skills root, default `/skills`; a qualified `<plugin>:<name>` or a digest that is not 12
+ * lowercase hex digits throws a `TypeError`). `args` is trimmed;
  * more than {@link SKILL_INVOCATION_LIMITS.argumentsMaxChars} characters throw a `RangeError`, and
  * so does a result longer than {@link SKILL_INVOCATION_LIMITS.renderedMaxChars} (checked while
  * substituting, before the long string is built).
  */
-export function renderSkillBody(body, invocation, args, skillName, digest) {
+export function renderSkillBody(body, invocation, args, skillName, digest, skillsRoot = SKILLS_SANDBOX_ROOT) {
     checkSkillName(skillName);
     checkDigest(digest);
-    const dir = skillSandboxDir(skillName, digest);
+    const dir = skillSandboxDir(skillName, digest, skillsRoot);
     const all = trimmedArgs(args);
     const values = parseSkillArguments(all);
     const named = invocation.arguments ?? [];

package/dist/skill.d.ts

@@ -49,10 +49,13 @@ export declare function skillDigest(files: {
     size: number;
     sha256: string;
 }[]): string;
-/** A skill version's directory in the sandbox: `/skills/<name>@<digest>` ({@link skillDigest}). */
-export declare function skillSandboxDir(name: string, digest: string): string;
-/** A skill file's path in the sandbox: `/skills/<name>@<digest>/<path>`. */
-export declare function skillSandboxPath(name: string, digest: string, path: string): string;
+/**
+ * A skill version's directory in the sandbox: `<root>/<name>@<digest>` ({@link skillDigest});
+ * `root` is the instance's skills root (`SandboxRoots.skills`, default `/skills`).
+ */
+export declare function skillSandboxDir(name: string, digest: string, root?: string): string;
+/** A skill file's path in the sandbox: `<root>/<name>@<digest>/<path>` ({@link skillSandboxDir}). */
+export declare function skillSandboxPath(name: string, digest: string, path: string, root?: string): string;
 /** {@link parseSkillMd} 成功时的结果。 */
 export interface ParsedSkillMd {
     name: string;

package/dist/skill.js

@@ -81,13 +81,16 @@ export function skillDigest(files) {
         .join("");
     return createHash("sha256").update(lines).digest("hex").slice(0, 12);
 }
-/** A skill version's directory in the sandbox: `/skills/<name>@<digest>` ({@link skillDigest}). */
-export function skillSandboxDir(name, digest) {
-    return `${SKILLS_SANDBOX_ROOT}/${name}@${digest}`;
+/**
+ * A skill version's directory in the sandbox: `<root>/<name>@<digest>` ({@link skillDigest});
+ * `root` is the instance's skills root (`SandboxRoots.skills`, default `/skills`).
+ */
+export function skillSandboxDir(name, digest, root = SKILLS_SANDBOX_ROOT) {
+    return `${root}/${name}@${digest}`;
 }
-/** A skill file's path in the sandbox: `/skills/<name>@<digest>/<path>`. */
-export function skillSandboxPath(name, digest, path) {
-    return `${skillSandboxDir(name, digest)}/${path}`;
+/** A skill file's path in the sandbox: `<root>/<name>@<digest>/<path>` ({@link skillSandboxDir}). */
+export function skillSandboxPath(name, digest, path, root = SKILLS_SANDBOX_ROOT) {
+    return `${skillSandboxDir(name, digest, root)}/${path}`;
 }
 const chars = (s) => [...s].length;
 /**