@capybara-hq/kernel 0.1.0-rc.12 → 0.1.0-rc.14

package/dist/admin/admin.schemas.d.ts

@@ -53,6 +53,19 @@ export declare const DeploymentSettingsBody: z.ZodObject<{
     uiTheme: z.ZodOptional<z.ZodObject<{
         id: z.ZodNullable<z.ZodString>;
     }, z.core.$strict>>;
+    uiArrangement: z.ZodOptional<z.ZodRecord<z.ZodEnum<{
+        "agent.detail.section": "agent.detail.section";
+        "conversation.panel": "conversation.panel";
+        "conversation.properties.section": "conversation.properties.section";
+        "conversation.tool-result.card": "conversation.tool-result.card";
+        "file.preview": "file.preview";
+        "org.page": "org.page";
+        "org.settings.section": "org.settings.section";
+        "platform.page": "platform.page";
+    }> & z.core.$partial, z.ZodNullable<z.ZodObject<{
+        hidden: z.ZodArray<z.ZodString>;
+        order: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>>;
 }, z.core.$strict>;
 export declare const PurposeParams: z.ZodObject<{
     purpose: z.ZodString;

package/dist/agents/agent-lookup.d.ts

@@ -49,6 +49,11 @@ export declare function visibleTo(viewerAccountId: string | null): (eb: Expressi
  * the live org). Deleted agents are never visible.
  */
 export declare function isAgentVisibleTo(db: KernelSchemaDb, agentId: string, accountId: string): Promise<boolean>;
+/**
+ * {@link isAgentVisibleTo} for an agent of `orgId` only: an agent the account can read in another
+ * org is not visible here (UI slots spec R6, the `agent.detail.section` scope rule).
+ */
+export declare function isAgentVisibleIn(db: KernelSchemaDb, orgId: string, agentId: string, accountId: string): Promise<boolean>;
 /**
  * Reads agents for a viewer (the visibility rule {@link visibleTo}): the part of `AgentsService`
  * the conversations, the skill invoker and the attachments read, with no dependency on the

package/dist/agents/agent-lookup.js

@@ -67,6 +67,21 @@ export async function isAgentVisibleTo(db, agentId, accountId) {
         .executeTakeFirst();
     return row !== undefined;
 }
+/**
+ * {@link isAgentVisibleTo} for an agent of `orgId` only: an agent the account can read in another
+ * org is not visible here (UI slots spec R6, the `agent.detail.section` scope rule).
+ */
+export async function isAgentVisibleIn(db, orgId, agentId, accountId) {
+    const row = await db
+        .selectFrom("agents")
+        .select("id")
+        .where("id", "=", agentId)
+        .where("org_id", "=", orgId)
+        .where("deleted_at", "is", null)
+        .where(visibleTo(accountId))
+        .executeTakeFirst();
+    return row !== undefined;
+}
 /**
  * Reads agents for a viewer (the visibility rule {@link visibleTo}): the part of `AgentsService`
  * the conversations, the skill invoker and the attachments read, with no dependency on the

package/dist/background/background.module.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { Module } from "@nestjs/common";
 import { ConversationAccessModule } from "../conversations/access.js";
 import { EventLogModule } from "../conversations/event-log.js";
-import { EnvironmentsModule } from "../environments/environments.module.js";
+import { DevicesModule } from "../devices/devices.module.js";
 import { SandboxModule } from "../sandbox/sandbox.module.js";
 import { BackgroundTaskFinisher } from "./finish.js";
 import { BackgroundTaskStopper } from "./stop.js";
@@ -28,7 +28,7 @@ BackgroundModule = __decorate([
         imports: [
             BackgroundStoreModule,
             SandboxModule,
-            EnvironmentsModule,
+            DevicesModule,
             EventLogModule,
             ConversationAccessModule,
         ],

package/dist/background/launch-lock.d.ts

@@ -3,7 +3,7 @@ import { XactLock } from "../infra/database/xact-lock.js";
 /**
  * The launch lock of one root conversation (decision R9: one provider per transaction-scoped
  * lock): serializes background task reservations in its tree, so the count of running tasks
- * checked against `sandbox.background.maxTasks` (per root conversation, whatever environment it
+ * checked against `sandbox.background.maxTasks` (per root conversation, whatever device it
  * works in) and the insert of the new row are one step. Joins the
  * caller's transaction (`mandatory`), which holds it until it ends.
  */

package/dist/background/launch-lock.js

@@ -14,7 +14,7 @@ import { XactLock } from "../infra/database/xact-lock.js";
 /**
  * The launch lock of one root conversation (decision R9: one provider per transaction-scoped
  * lock): serializes background task reservations in its tree, so the count of running tasks
- * checked against `sandbox.background.maxTasks` (per root conversation, whatever environment it
+ * checked against `sandbox.background.maxTasks` (per root conversation, whatever device it
  * works in) and the insert of the new row are one step. Joins the
  * caller's transaction (`mandatory`), which holds it until it ends.
  */

package/dist/background/poll.job.d.ts

@@ -21,7 +21,7 @@ export declare const launchAbandonedAfterMs: (cfg: KernelConfig) => number;
 /**
  * The worker's background task jobs (spec 2026-11-05-background-bash-design §4.3), each once per
  * tick across replicas:
- * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every environment
+ * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every device
  *   instance with running tasks (of any conversation using it), one exec through
  *   `SandboxService.ifRunning` (which never creates or resumes an instance) reports each task's
  *   exit file and liveness; ended tasks finish through {@link BackgroundTaskFinisher}. Each poll
@@ -47,7 +47,7 @@ export declare class BackgroundTaskPollJob {
      * result: they never started), with a `changed: "background"` frame to their conversations.
      */
     pollOnce(signal?: AbortSignal): Promise<number>;
-    /** Polls the tasks of one environment instance; returns how many finished. */
+    /** Polls the tasks of one device instance; returns how many finished. */
     private pollSandbox;
     /** The poll exec of one instance: each task's report by id. */
     private pollExec;

package/dist/background/poll.job.js

@@ -44,7 +44,7 @@ const POLL_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
 /**
  * The worker's background task jobs (spec 2026-11-05-background-bash-design §4.3), each once per
  * tick across replicas:
- * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every environment
+ * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every device
  *   instance with running tasks (of any conversation using it), one exec through
  *   `SandboxService.ifRunning` (which never creates or resumes an instance) reports each task's
  *   exit file and liveness; ended tasks finish through {@link BackgroundTaskFinisher}. Each poll
@@ -93,8 +93,8 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
         for (const t of await this.store.runningStarted()) {
             if (t.sid === null || t.sandboxCreatedAt === null)
                 continue;
-            // one exec per instance: the tasks of every conversation sharing the environment
-            const key = `${t.environmentId} ${t.sandboxCreatedAt.getTime()}`;
+            // one exec per instance: the tasks of every conversation sharing the device
+            const key = `${t.deviceId} ${t.sandboxCreatedAt.getTime()}`;
             groups.set(key, [...(groups.get(key) ?? []), t]);
         }
         let finished = 0;
@@ -102,9 +102,9 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
             if (signal.aborted)
                 break;
             try {
-                // the environment's provider is not there (no cloud provider, `@device` not served):
+                // the device's provider is not there (no cloud provider, `@local` not served):
                 // its tasks stay as they are until it is
-                const env = tasks[0]?.environmentId ?? null;
+                const env = tasks[0]?.deviceId ?? null;
                 if (env === null ? !this.sandbox.cloudAvailable : !(await this.sandbox.availableFor(env))) {
                     continue;
                 }
@@ -114,7 +114,7 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
                 if (signal.aborted)
                     break;
                 this.log.warn("cannot poll background tasks; retrying next tick", {
-                    environmentId: tasks[0]?.environmentId,
+                    deviceId: tasks[0]?.deviceId,
                     err,
                 });
             }
@@ -123,13 +123,13 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
             this.log.info("background tasks finished", { count: finished });
         return finished;
     }
-    /** Polls the tasks of one environment instance; returns how many finished. */
+    /** Polls the tasks of one device instance; returns how many finished. */
     async pollSandbox(tasks, signal) {
         const [first] = tasks;
-        // a task from before environments has no instance any more
-        const r = first.environmentId === null
+        // a task from before devices has no instance any more
+        const r = first.deviceId === null
             ? { kind: "not_running", status: "gone" }
-            : await this.sandbox.ifRunning(first.environmentId, { createdAt: first.sandboxCreatedAt }, (p, h, sig) => this.pollExec(actingAs(p, taskActor(first)), h, tasks, sig), signal);
+            : await this.sandbox.ifRunning(first.deviceId, { createdAt: first.sandboxCreatedAt }, (p, h, sig) => this.pollExec(actingAs(p, taskActor(first)), h, tasks, sig), signal);
         const now = new Date();
         let n = 0;
         for (const t of tasks) {

package/dist/background/stop.d.ts

@@ -43,7 +43,7 @@ export declare class BackgroundTaskStopper {
     stop(task: BackgroundTaskRow, why: StopReason, signal?: AbortSignal): Promise<BackgroundTaskRow>;
     /**
      * SIGTERM, the grace period, SIGKILL until the session is empty, then the last lines: in the
-     * task's own instance only (`ifRunning`); a task from before environments has none.
+     * task's own instance only (`ifRunning`); a task from before devices has none.
      */
     private signalTask;
     /**

package/dist/background/stop.js

@@ -138,12 +138,12 @@ let BackgroundTaskStopper = class BackgroundTaskStopper {
     }
     /**
      * SIGTERM, the grace period, SIGKILL until the session is empty, then the last lines: in the
-     * task's own instance only (`ifRunning`); a task from before environments has none.
+     * task's own instance only (`ifRunning`); a task from before devices has none.
      */
     async signalTask(cur, sid, signal) {
-        if (cur.environmentId === null)
+        if (cur.deviceId === null)
             return { kind: "not_running", status: "gone" };
-        return this.sandbox.ifRunning(cur.environmentId, { createdAt: cur.sandboxCreatedAt }, async (tp, h, sig) => {
+        return this.sandbox.ifRunning(cur.deviceId, { createdAt: cur.sandboxCreatedAt }, async (tp, h, sig) => {
             const p = actingAs(tp, taskActor(cur));
             const term = await p.exec(h, {
                 command: termScript(cur.id, sid),

package/dist/background/store.d.ts

@@ -14,10 +14,10 @@ export interface BackgroundTaskRow {
      */
     sandboxConversationId: string;
     /**
-     * The environment the task runs in (the root conversation's when it was launched): its instance
-     * is where the task's processes are. Null only for tasks from before environments (all finished).
+     * The device the task runs in (the root conversation's when it was launched): its instance
+     * is where the task's processes are. Null only for tasks from before devices (all finished).
      */
-    environmentId: string | null;
+    deviceId: string | null;
     runId: string;
     callId: string;
     triggerAccountId: string;
@@ -157,10 +157,10 @@ export declare class BackgroundTaskStore {
     /** Moves the read offset forward only (a concurrent reader never moves it back). */
     advanceOffset(id: string, to: number): Promise<void>;
     /**
-     * Finished tasks of an environment whose process may still exist (any conversation's: they
+     * Finished tasks of a device whose process may still exist (any conversation's: they
      * share the instance).
      */
-    pendingKills(environmentId: string): Promise<BackgroundTaskRow[]>;
+    pendingKills(deviceId: string): Promise<BackgroundTaskRow[]>;
     clearKill(ids: string[]): Promise<void>;
     /** Deletes finished tasks that ended before `before`; a running one is never deleted. */
     pruneFinished(before: Date): Promise<number>;

package/dist/background/store.js

@@ -18,7 +18,7 @@ const toRow = (r) => ({
     orgId: r.org_id,
     conversationId: r.conversation_id,
     sandboxConversationId: r.sandbox_conversation_id,
-    environmentId: r.environment_id,
+    deviceId: r.device_id,
     runId: r.run_id,
     callId: r.call_id,
     triggerAccountId: r.trigger_account_id,
@@ -195,7 +195,7 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             org_id: row.orgId,
             conversation_id: row.conversationId,
             sandbox_conversation_id: row.sandboxConversationId,
-            environment_id: row.environmentId,
+            device_id: row.deviceId,
             run_id: row.runId,
             call_id: row.callId,
             trigger_account_id: row.triggerAccountId,
@@ -314,14 +314,14 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             .execute();
     }
     /**
-     * Finished tasks of an environment whose process may still exist (any conversation's: they
+     * Finished tasks of a device whose process may still exist (any conversation's: they
      * share the instance).
      */
-    async pendingKills(environmentId) {
+    async pendingKills(deviceId) {
         const rows = await this.db
             .selectFrom("background_tasks")
             .selectAll()
-            .where("environment_id", "=", environmentId)
+            .where("device_id", "=", deviceId)
             .where("kill_pending", "=", true)
             .orderBy("started_at", "asc")
             .execute();

package/dist/background/tasks.service.d.ts

@@ -1,6 +1,6 @@
 import { ConversationAccess } from "../conversations/access.js";
 import { EventLog } from "../conversations/event-log.js";
-import { ConversationEnvironments } from "../environments/conversation-environments.js";
+import { ConversationDevices } from "../devices/conversation-devices.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { BackgroundTaskStopper } from "./stop.js";
@@ -45,8 +45,8 @@ export declare class BackgroundTasks {
     private readonly sandbox;
     private readonly eventLog;
     private readonly db;
-    private readonly environments;
-    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "availableFor" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, environments: Pick<ConversationEnvironments, "forTool">);
+    private readonly devices;
+    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "availableFor" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, devices: Pick<ConversationDevices, "forTool">);
     /**
      * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
      * in the root's sandbox, agent map spec §6); `conversation.not_found` when not visible.
@@ -63,12 +63,12 @@ export declare class BackgroundTasks {
      */
     stop(orgId: string, conversationId: string, accountId: string, taskId: string, actorTokenId?: string, auditDetail?: Record<string, unknown>): Promise<BackgroundTaskView>;
     /**
-     * Whether the task's environment may still be used by its conversation's owner (the access
+     * Whether the task's device may still be used by its conversation's owner (the access
      * re-check every sandbox tool call makes); when it may not, the live read is skipped.
      */
-    private environmentUsable;
+    private deviceUsable;
     /**
-     * The end of the task's output, at most `tail` bytes. Read live when the task's environment
+     * The end of the task's output, at most `tail` bytes. Read live when the task's device
      * instance runs (never resuming a suspended one); a finished task whose sandbox does not run answers
      * with the last lines its finished event kept. Anything else is
      * `background_task.output_unavailable` (409).

package/dist/background/tasks.service.js

@@ -12,7 +12,7 @@ import { Inject, Injectable } from "@nestjs/common";
 import { ConversationAccess } from "../conversations/access.js";
 import { EventLog } from "../conversations/event-log.js";
 import { conversationTree } from "../conversations/tree.js";
-import { ConversationEnvironments } from "../environments/conversation-environments.js";
+import { ConversationDevices } from "../devices/conversation-devices.js";
 import { ApiError } from "../errors.js";
 import { audit } from "../identity/audit.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -44,15 +44,15 @@ let BackgroundTasks = class BackgroundTasks {
     sandbox;
     eventLog;
     db;
-    environments;
-    constructor(access, store, stopper, sandbox, eventLog, db, environments) {
+    devices;
+    constructor(access, store, stopper, sandbox, eventLog, db, devices) {
         this.access = access;
         this.store = store;
         this.stopper = stopper;
         this.sandbox = sandbox;
         this.eventLog = eventLog;
         this.db = db;
-        this.environments = environments;
+        this.devices = devices;
     }
     /**
      * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
@@ -119,12 +119,12 @@ let BackgroundTasks = class BackgroundTasks {
         return this.view(after, conversationId);
     }
     /**
-     * Whether the task's environment may still be used by its conversation's owner (the access
+     * Whether the task's device may still be used by its conversation's owner (the access
      * re-check every sandbox tool call makes); when it may not, the live read is skipped.
      */
-    async environmentUsable(orgId, taskConversationId) {
+    async deviceUsable(orgId, taskConversationId) {
         try {
-            await this.environments.forTool(orgId, await rootConversationOf(this.db.db, taskConversationId));
+            await this.devices.forTool(orgId, await rootConversationOf(this.db.db, taskConversationId));
             return true;
         }
         catch (e) {
@@ -134,7 +134,7 @@ let BackgroundTasks = class BackgroundTasks {
         }
     }
     /**
-     * The end of the task's output, at most `tail` bytes. Read live when the task's environment
+     * The end of the task's output, at most `tail` bytes. Read live when the task's device
      * instance runs (never resuming a suspended one); a finished task whose sandbox does not run answers
      * with the last lines its finished event kept. Anything else is
      * `background_task.output_unavailable` (409).
@@ -143,14 +143,14 @@ let BackgroundTasks = class BackgroundTasks {
         const task = await this.owned(orgId, conversationId, accountId, taskId);
         if (task.sid !== null &&
             task.sandboxCreatedAt !== null &&
-            task.environmentId !== null &&
-            (await this.sandbox.availableFor(task.environmentId)) &&
-            (await this.environmentUsable(orgId, task.conversationId))) {
+            task.deviceId !== null &&
+            (await this.sandbox.availableFor(task.deviceId)) &&
+            (await this.deviceUsable(orgId, task.conversationId))) {
             const createdAt = task.sandboxCreatedAt;
             // the person reading it acts in the task's conversation
             const actor = { accountId, conversationId: task.conversationId };
             try {
-                const r = await this.sandbox.ifRunning(task.environmentId, { createdAt }, async (p, h, signal) => {
+                const r = await this.sandbox.ifRunning(task.deviceId, { createdAt }, async (p, h, signal) => {
                     const res = await actingAs(p, actor).exec(h, {
                         command: tailScript(task.id, tail),
                         cwd: rootsOf(h).workspace,
@@ -185,7 +185,7 @@ BackgroundTasks = __decorate([
     __param(3, Inject(SandboxService)),
     __param(4, Inject(EventLog)),
     __param(5, Inject(KernelDb)),
-    __param(6, Inject(ConversationEnvironments))
+    __param(6, Inject(ConversationDevices))
 ], BackgroundTasks);
 export { BackgroundTasks };
 /** Prints `size <bytes>` and `out <base64 of the last `tail` bytes>`. Relative to the workspace root. */

package/dist/catalog/admin-catalog.controller.d.ts

@@ -1,8 +1,9 @@
 import type { FastifyReply } from "fastify";
 import { z } from "zod";
+import { PluginGuides, type RenderedSetupGuide } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
-import { CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
+import { AdminCatalogGuideQuery, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogNpmImportBody as NpmBody, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody } from "./admin-catalog.schemas.js";
 import { type CatalogItemDetail, type CatalogItemView, CatalogService, type PermissionsMismatch } from "./catalog.service.js";
 import { CatalogScopeService, type ScopePreview } from "./catalog-scope.service.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
@@ -38,7 +39,8 @@ export declare class AdminCatalogController {
     private readonly scope;
     private readonly updater;
     private readonly icons;
-    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater, icons: PluginIcons);
+    private readonly guides;
+    constructor(catalog: CatalogService, pluginImport: PluginImport, orgCatalog: OrgCatalogService, scope: CatalogScopeService, updater: PlatformPluginUpdater, icons: PluginIcons, guides: PluginGuides);
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
      * `application/octet-stream`, at most `packages.maxBytes`): reads and checks the whole plugin
@@ -124,6 +126,15 @@ export declare class AdminCatalogController {
      * `sendCatalogIcon`). No icon -> 404 `catalog.icon_not_found`.
      */
     icon(id: string, reply: FastifyReply): Promise<void>;
+    /**
+     * A setup guide of the item as the platform sees it (spec 2026-11-09-setup-guides-v2-design.md
+     * §9.3; the admin console's connector template page): any live item, the admin audience, no org
+     * (`orgName` unresolved, reason `no_org`), no target, no checks run. Unknown item -> 404
+     * `catalog.item_not_found`, unknown guide -> 404 `catalog.guide_not_found`.
+     */
+    guide(itemId: string, guideId: string, q: z.infer<typeof AdminCatalogGuideQuery>): Promise<{
+        guide: RenderedSetupGuide;
+    }>;
     /**
      * What a scope change (`{ scope, orgs? }`, `orgs` only with `named`) or a disable
      * (`{ disabled: true }`) would take away: `{ affected: [{ orgId, orgName, agents,

package/dist/catalog/admin-catalog.controller.js

@@ -10,11 +10,12 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Controller, Delete, Get, HttpCode, Inject, Param, Post, Put, Req, Res, } from "@nestjs/common";
 import { z } from "zod";
 import { ApiError } from "../errors.js";
+import { PluginGuides } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { CurrentPrincipal, patTokenId, requireUser, SuperAdmin, } from "../identity/principal.js";
 import { createZodDto } from "../infra/validation/create-zod-dto.js";
 import { ZBody, ZQuery } from "../infra/validation/zod-params.js";
-import { CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
+import { AdminCatalogGuideQuery, CatalogItemsQuery, CatalogUpdateBody, CatalogUpdatePreviewBody, CatalogDisabledBody as DisabledBody, CatalogGitImportBody as GitBody, CatalogHash as Hash, CatalogNpmImportBody as NpmBody, CatalogScopeOrgs as Orgs, CatalogScope as Scope, CatalogScopeBody as ScopeBody, CatalogScopePreviewBody as ScopePreviewBody, CatalogShownBody as ShownBody, } from "./admin-catalog.schemas.js";
 import { CatalogService, } from "./catalog.service.js";
 import { CatalogScopeService } from "./catalog-scope.service.js";
 import { sendCatalogIcon } from "./org-catalog.controller.js";
@@ -42,6 +43,8 @@ class CatalogImportConfirmBody extends createZodDto(ConfirmBody, "CatalogImportC
 }
 class CatalogGitImportBody extends createZodDto(GitBody, "CatalogGitImportBody") {
 }
+class AdminCatalogGuideQueryDto extends createZodDto(AdminCatalogGuideQuery, "AdminCatalogGuideQuery") {
+}
 class CatalogItemsQueryDto extends createZodDto(CatalogItemsQuery, "CatalogItemsQuery") {
 }
 class CatalogNpmImportBody extends createZodDto(NpmBody, "CatalogNpmImportBody") {
@@ -75,13 +78,15 @@ let AdminCatalogController = class AdminCatalogController {
     scope;
     updater;
     icons;
-    constructor(catalog, pluginImport, orgCatalog, scope, updater, icons) {
+    guides;
+    constructor(catalog, pluginImport, orgCatalog, scope, updater, icons, guides) {
         this.catalog = catalog;
         this.pluginImport = pluginImport;
         this.orgCatalog = orgCatalog;
         this.scope = scope;
         this.updater = updater;
         this.icons = icons;
+        this.guides = guides;
     }
     /**
      * Prepares the import of an uploaded plugin (an npm-pack tgz as the raw body,
@@ -189,6 +194,15 @@ let AdminCatalogController = class AdminCatalogController {
     async icon(id, reply) {
         await sendCatalogIcon(reply, await this.orgCatalog.icon(id, true));
     }
+    /**
+     * A setup guide of the item as the platform sees it (spec 2026-11-09-setup-guides-v2-design.md
+     * §9.3; the admin console's connector template page): any live item, the admin audience, no org
+     * (`orgName` unresolved, reason `no_org`), no target, no checks run. Unknown item -> 404
+     * `catalog.item_not_found`, unknown guide -> 404 `catalog.guide_not_found`.
+     */
+    async guide(itemId, guideId, q) {
+        return { guide: await this.guides.renderForPlatform(itemId, guideId, q) };
+    }
     /**
      * What a scope change (`{ scope, orgs? }`, `orgs` only with `named`) or a disable
      * (`{ disabled: true }`) would take away: `{ affected: [{ orgId, orgName, agents,
@@ -331,6 +345,12 @@ __decorate([
     __param(0, Param("id")),
     __param(1, Res())
 ], AdminCatalogController.prototype, "icon", null);
+__decorate([
+    Get(":itemId/guides/:guideId"),
+    __param(0, Param("itemId")),
+    __param(1, Param("guideId")),
+    __param(2, ZQuery(AdminCatalogGuideQueryDto))
+], AdminCatalogController.prototype, "guide", null);
 __decorate([
     Post("items/:id/scope/preview"),
     HttpCode(200),
@@ -395,6 +415,7 @@ AdminCatalogController = __decorate([
     __param(2, Inject(OrgCatalogService)),
     __param(3, Inject(CatalogScopeService)),
     __param(4, Inject(PlatformPluginUpdater)),
-    __param(5, Inject(PluginIcons))
+    __param(5, Inject(PluginIcons)),
+    __param(6, Inject(PluginGuides))
 ], AdminCatalogController);
 export { AdminCatalogController };

package/dist/catalog/admin-catalog.schemas.d.ts

@@ -69,4 +69,14 @@ export declare const CatalogDisabledBody: z.ZodObject<{
 export declare const CatalogShownBody: z.ZodObject<{
     shownToOthers: z.ZodBoolean;
 }, z.core.$strict>;
+/**
+ * `GET :itemId/guides/:guideId`, the super admin's preview of a setup guide (spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3): only the document language; no org, no target.
+ */
+export declare const AdminCatalogGuideQuery: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strict>;
 export declare const ADMIN_CATALOG_ROUTES: readonly RouteSchemas[];

package/dist/catalog/admin-catalog.schemas.js

@@ -52,6 +52,13 @@ export const CatalogDisabledBody = z
     .object({ disabled: z.boolean(), scopeHash: CatalogHash.optional() })
     .strict();
 export const CatalogShownBody = z.object({ shownToOthers: z.boolean() }).strict();
+/**
+ * `GET :itemId/guides/:guideId`, the super admin's preview of a setup guide (spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3): only the document language; no org, no target.
+ */
+export const AdminCatalogGuideQuery = z
+    .object({ locale: z.enum(["en", "zh"]).optional() })
+    .strict();
 export const ADMIN_CATALOG_ROUTES = [
     { route: "GET /api/v1/admin/catalog/items", query: CatalogItemsQuery },
     { route: "GET /api/v1/admin/catalog/items/:id", params: CatalogIdPathParams },

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

@@ -72,6 +72,14 @@ export interface OrgCatalogTemplate {
     editableEndpoint: string[];
     auth: Record<string, unknown>;
     ownership: "org" | "personal" | null;
+    /**
+     * The template's setup guide in the item's latest version (`GET …/catalog/:itemId/guides/
+     * :guideId`), null without one (spec 2026-11-09-setup-guides-v2-design.md §9.3).
+     */
+    guide: {
+        itemId: string;
+        guideId: string;
+    } | null;
 }
 /** `GET /orgs/:orgId/catalog/:itemId`: the item and what the install wizard needs (latest version). */
 export interface OrgCatalogDetail {
@@ -105,7 +113,7 @@ export interface OrgCatalogDetail {
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export declare function orgTemplateView(id: string, file: ConnectorTemplateFile): OrgCatalogTemplate;
+export declare function orgTemplateView(id: string, file: ConnectorTemplateFile, guide?: OrgCatalogTemplate["guide"]): OrgCatalogTemplate;
 /** An item's icon (the latest version's plugin icon). */
 export interface CatalogIcon {
     data: Uint8Array;

package/dist/catalog/catalog-content.js

@@ -16,7 +16,7 @@ import { satisfiesRange } from "./versions.js";
  * A connector template as an org sees it (the install wizard and the upgrade preview's inputs):
  * presets and editable paths, no credentials.
  */
-export function orgTemplateView(id, file) {
+export function orgTemplateView(id, file, guide = null) {
     const t = file.template;
     return {
         id,
@@ -29,6 +29,7 @@ export function orgTemplateView(id, file) {
         auth: t.auth,
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+        guide,
     };
 }
 const iconNotFound = () => new ApiError("catalog.icon_not_found", "This catalog item has no icon");

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

@@ -1,4 +1,4 @@
-import type { PluginManifest } from "@capybara-hq/plugin-sdk";
+import { type PluginManifest } from "@capybara-hq/plugin-sdk";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 type Db = Pick<KernelSchemaDb, "selectFrom" | "insertInto" | "deleteFrom">;
 /** A stored file as a version row lists it. */
@@ -9,7 +9,8 @@ interface FileMeta {
 }
 /**
  * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
- * icons (given by the caller, which parsed the templates) and the setup guide files.
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
  */
 export declare function displayFilePaths(m: PluginManifest, templateIcons?: string[]): Set<string>;
 /**

package/dist/catalog/catalog-files.js

@@ -1,16 +1,18 @@
 // Catalog display files in PG (`catalog_files`, migration 0100): a plugin's icon, its connector
-// templates' icons and its setup guide files. They are small (64 KiB each at most, by the plugin
+// templates' icons and its setup guide documents. They are small (64 KiB each at most, by the plugin
 // format) and must be readable without object storage: a bootstrap plugin is imported before any
 // object-store extension runs, and the object-store plugin's own icon can never wait for itself.
 // Skills, connector templates and agent templates stay in object storage under the version's
 // `object_prefix` (they are copied into platform components there).
 import { createHash } from "node:crypto";
+import { setupGuideDocPath } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import { ApiError } from "../errors.js";
 import { packagePath } from "../packages/tgz.js";
 /**
  * The display file paths of a plugin (package paths): the plugin icon, the connector templates'
- * icons (given by the caller, which parsed the templates) and the setup guide files.
+ * icons (given by the caller, which parsed the templates) and the setup guide documents (both
+ * languages; the caller keeps the ones the package has).
  */
 export function displayFilePaths(m, templateIcons = []) {
     const out = new Set();
@@ -18,9 +20,10 @@ export function displayFilePaths(m, templateIcons = []) {
         out.add(packagePath(m.icon));
     for (const icon of templateIcons)
         out.add(packagePath(icon));
-    for (const g of m.setupGuides ?? [])
-        for (const f of g.files ?? [])
-            out.add(packagePath(f.path));
+    for (const g of m.setupGuides ?? []) {
+        out.add(setupGuideDocPath(g.id, "en"));
+        out.add(setupGuideDocPath(g.id, "zh"));
+    }
     return out;
 }
 /**