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

package/dist/setup/setup-guides.controller.d.ts

@@ -0,0 +1,18 @@
+import type { z } from "zod";
+import { type Principal } from "../identity/principal.js";
+import { type OrgContext } from "../orgs/org.guard.js";
+import { SetupGuidesQuery } from "./setup-guides.schemas.js";
+import { type SetupGuideListEntry, SetupGuidesService } from "./setup-guides.service.js";
+/**
+ * The org's setup guides as the caller sees them (spec 2026-11-09-setup-guides-v2-design.md §12):
+ * per guide its targets, their drift, a summary of the cached check states and the web page of
+ * each. `catalog.read` here; which guides and targets a role sees is the service's (the guide
+ * route's place and audience actions).
+ */
+export declare class SetupGuidesController {
+    private readonly guides;
+    constructor(guides: SetupGuidesService);
+    list(principal: Principal, org: OrgContext, q: z.infer<typeof SetupGuidesQuery>): Promise<{
+        guides: SetupGuideListEntry[];
+    }>;
+}

package/dist/setup/setup-guides.controller.js

@@ -0,0 +1,48 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Controller, Get, Inject } from "@nestjs/common";
+import { CurrentPrincipal, requireUser } from "../identity/principal.js";
+import { createZodDto } from "../infra/validation/create-zod-dto.js";
+import { ZQuery } from "../infra/validation/zod-params.js";
+import { CurrentOrg, OrgAction } from "../orgs/org.guard.js";
+import { SetupGuidesQuery } from "./setup-guides.schemas.js";
+import { SetupGuidesService } from "./setup-guides.service.js";
+class SetupGuidesQueryDto extends createZodDto(SetupGuidesQuery, "SetupGuidesQuery") {
+}
+/**
+ * The org's setup guides as the caller sees them (spec 2026-11-09-setup-guides-v2-design.md §12):
+ * per guide its targets, their drift, a summary of the cached check states and the web page of
+ * each. `catalog.read` here; which guides and targets a role sees is the service's (the guide
+ * route's place and audience actions).
+ */
+let SetupGuidesController = class SetupGuidesController {
+    guides;
+    constructor(guides) {
+        this.guides = guides;
+    }
+    async list(principal, org, q) {
+        const p = requireUser(principal);
+        return {
+            guides: await this.guides.list({ orgId: org.orgId, role: org.role, accountId: p.account.id }, q),
+        };
+    }
+};
+__decorate([
+    Get(),
+    OrgAction("catalog.read"),
+    __param(0, CurrentPrincipal()),
+    __param(1, CurrentOrg()),
+    __param(2, ZQuery(SetupGuidesQueryDto))
+], SetupGuidesController.prototype, "list", null);
+SetupGuidesController = __decorate([
+    Controller("api/v1/orgs/:orgId/setup-guides"),
+    __param(0, Inject(SetupGuidesService))
+], SetupGuidesController);
+export { SetupGuidesController };

package/dist/setup/setup-guides.schemas.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+import type { RouteSchemas } from "../platform/route-schemas.js";
+/** `GET /orgs/:orgId/setup-guides`: the language of the guide titles (zh falls back to en). */
+export declare const SetupGuidesQuery: z.ZodObject<{
+    locale: z.ZodOptional<z.ZodEnum<{
+        en: "en";
+        zh: "zh";
+    }>>;
+}, z.core.$strict>;
+export declare const SETUP_GUIDE_ROUTES: readonly RouteSchemas[];

package/dist/setup/setup-guides.schemas.js

@@ -0,0 +1,6 @@
+import { z } from "zod";
+/** `GET /orgs/:orgId/setup-guides`: the language of the guide titles (zh falls back to en). */
+export const SetupGuidesQuery = z.object({ locale: z.enum(["en", "zh"]).optional() }).strict();
+export const SETUP_GUIDE_ROUTES = [
+    { route: "GET /api/v1/orgs/:orgId/setup-guides", query: SetupGuidesQuery },
+];

package/dist/setup/setup-guides.service.d.ts

@@ -0,0 +1,126 @@
+import type { SetupGuideAudience, SetupGuideBlock, SetupGuidePlace } from "@capybara-hq/plugin-sdk";
+import { ComponentScopeService } from "../catalog/component-scope.service.js";
+import { type GuideQuery, PluginGuides, type UnresolvedReason } from "../extensions/plugin-guides.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { type CheckCaller, SetupChecksService } from "./setup-checks.service.js";
+/** The cached check states of one target, counted (`running` while a run holds the lock). */
+export interface SetupCheckSummary {
+    ok: number;
+    failing: number;
+    unknown: number;
+    running: number;
+    notRun: number;
+}
+/** Something a guide is for: a channel connection, a connector, or a template without one yet. */
+export interface SetupGuideTarget {
+    kind: "channel-connection" | "connector" | "connector-template";
+    /** The connection or connector id; the template id for `connector-template`. */
+    id: string;
+    name: string;
+    /** The guide changed since the target was set up (its ack): the versions; null otherwise. */
+    drift: {
+        from: string;
+        to: string;
+    } | null;
+    /** Null when there is nothing to check yet (a template without a connector) or it is unreadable. */
+    checks: SetupCheckSummary | null;
+    /** The web page where the person does this setup (enters values, acks the guide). */
+    webPath: string;
+}
+/** One guide the caller may see in the org, with its targets (`GET /orgs/:orgId/setup-guides`). */
+export interface SetupGuideListEntry {
+    itemId: string;
+    plugin: string;
+    guideId: string;
+    place: SetupGuidePlace;
+    /** The connector template of a `connector-template` guide; null for other places. */
+    template: string | null;
+    /** The section rendered: org admins get the admin guides, members their member sections. */
+    audience: SetupGuideAudience;
+    title: string;
+    targets: SetupGuideTarget[];
+}
+/** A rendered guide as one Markdown document, for an agent assisting the person (`setup.read`). */
+export interface SetupGuideDocument {
+    itemId: string;
+    plugin: string;
+    guideId: string;
+    place: SetupGuidePlace;
+    title: string;
+    /** Blocks joined; checks as `- [check <id>] <label>` lines. */
+    markdown: string;
+    modes: string[];
+    mode: string | null;
+    audiences: SetupGuideAudience[];
+    audience: SetupGuideAudience;
+    checks: {
+        id: string;
+        label: string;
+    }[];
+    unresolved: {
+        name: string;
+        reason: UnresolvedReason;
+    }[];
+    target: {
+        kind: "channel-connection" | "connector";
+        id: string;
+    } | null;
+    webPath: string;
+    /** What stays with the person, and where they do it. */
+    handover: string;
+}
+/** The web page of a target (`apps/web` routes; the guide sections live there). */
+export declare const setupWebPath: {
+    connection: (id: string) => string;
+    newConnection: () => string;
+    connector: (id: string) => string;
+    /** A member's connector section: the connector's row on their connections page (§9.3). */
+    memberConnections: () => string;
+    template: (itemId: string) => string;
+};
+/** The blocks of a rendered guide as one Markdown document (checks as `- [check <id>]` lines). */
+export declare function guideMarkdown(title: string, blocks: readonly SetupGuideBlock[]): string;
+/**
+ * The setup guides of an org as a person sees them (spec 2026-11-09-setup-guides-v2-design.md §12:
+ * `GET /orgs/:orgId/setup-guides`, the `Platform` tool's `setup.guides` and `setup.read`). Nothing
+ * new is decided here: guides, visibility, drift and actions are `PluginGuides`' (the guide route's
+ * rules), check states are `SetupChecksService.states` (cached, nothing runs), the templates on in
+ * the org are `ComponentScopeService.orgList`'s. Rendered text carries no secret (§6.3) and check
+ * states only their fixed, redacted fields (§10.8). Stateless: everything comes from PG and Redis.
+ */
+export declare class SetupGuidesService {
+    private readonly db;
+    private readonly guides;
+    private readonly checks;
+    private readonly components;
+    private readonly log;
+    constructor(db: KernelDb, guides: Pick<PluginGuides, "render" | "connectionStates" | "connectorStates">, checks: Pick<SetupChecksService, "states">, components: Pick<ComponentScopeService, "orgList">, log: Pick<KernelLogger, "warn">);
+    /**
+     * The guides the caller may see, each with its targets: org admins (`channels.manage`) the
+     * channel connections; org admins (`connectors.manage`) the connectors made from templates and
+     * the templates on in the org without a connector, admin audience; members (`connectors.use`
+     * without `connectors.manage`) the connectors whose template guide has a member section, member
+     * audience, without drift (only an admin acks). Each target carries its cached check summary.
+     * A guide that cannot be rendered (gone, a stored document unreadable) is left out and logged.
+     */
+    list(caller: CheckCaller, q?: {
+        locale?: "en" | "zh" | undefined;
+    }): Promise<SetupGuideListEntry[]>;
+    /** The cached check summary of a target, or null when the guide cannot be read for it. */
+    private summary;
+    private renderOrSkip;
+    /** The org's channel connections whose plugin has a guide the org sees. */
+    private connections;
+    /**
+     * The org's connectors made from a template with a guide; for org admins also the templates on
+     * in the org that have a guide and no connector yet.
+     */
+    private connectors;
+    /**
+     * One guide rendered for the caller as a Markdown document (`setup.read`): the guide route's
+     * rendering (`PluginGuides.render`, its visibility, action and target rules), joined, with the
+     * page where the person enters values and acks.
+     */
+    read(caller: CheckCaller, itemId: string, guideId: string, q: GuideQuery): Promise<SetupGuideDocument>;
+}

package/dist/setup/setup-guides.service.js

@@ -0,0 +1,315 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { ComponentScopeService } from "../catalog/component-scope.service.js";
+import { ApiError } from "../errors.js";
+import { PluginGuides, } from "../extensions/plugin-guides.js";
+import { KernelDb } from "../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { can } from "../orgs/roles.js";
+import { SetupChecksService } from "./setup-checks.service.js";
+const enc = encodeURIComponent;
+/** The web page of a target (`apps/web` routes; the guide sections live there). */
+export const setupWebPath = {
+    connection: (id) => `/channels/${enc(id)}`,
+    newConnection: () => "/channels/new",
+    connector: (id) => `/connectors/${enc(id)}?tab=guide`,
+    /** A member's connector section: the connector's row on their connections page (§9.3). */
+    memberConnections: () => "/account/connections",
+    template: (itemId) => `/connectors/install?template=${enc(itemId)}`,
+};
+/**
+ * The page a rendered guide belongs on: a member's connections page for the member audience, else
+ * its target's, else where a target is created.
+ */
+function webPathOf(g) {
+    if (g.audience === "member")
+        return setupWebPath.memberConnections();
+    if (g.target?.kind === "channel-connection")
+        return setupWebPath.connection(g.target.id);
+    if (g.target?.kind === "connector")
+        return setupWebPath.connector(g.target.id);
+    return g.place === "channel-connection"
+        ? setupWebPath.newConnection()
+        : setupWebPath.template(g.itemId);
+}
+/** A fence longer than any run of backticks in the text. */
+function fenceFor(text) {
+    const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((m) => m[0].length));
+    return "`".repeat(Math.max(3, longest + 1));
+}
+/** The blocks of a rendered guide as one Markdown document (checks as `- [check <id>]` lines). */
+export function guideMarkdown(title, blocks) {
+    const parts = [`# ${title}`];
+    for (const b of blocks) {
+        if (b.kind === "markdown")
+            parts.push(b.text.trimEnd());
+        else if (b.kind === "check")
+            parts.push(`- [check ${b.id}] ${b.label}`);
+        else {
+            const fence = fenceFor(b.text);
+            const code = `${fence}${b.language}\n${b.text.replace(/\n$/, "")}\n${fence}`;
+            parts.push(b.title === null ? code : `**${b.title}**\n\n${code}`);
+        }
+    }
+    return `${parts.join("\n\n")}\n`;
+}
+function summarize(states) {
+    const out = { ok: 0, failing: 0, unknown: 0, running: 0, notRun: 0 };
+    for (const s of Object.values(states)) {
+        if (s.status === "ok")
+            out.ok += 1;
+        else if (s.status === "failing")
+            out.failing += 1;
+        else if (s.status === "running")
+            out.running += 1;
+        else if (s.status === "not_run")
+            out.notRun += 1;
+        else
+            out.unknown += 1;
+    }
+    return out;
+}
+/**
+ * The setup guides of an org as a person sees them (spec 2026-11-09-setup-guides-v2-design.md §12:
+ * `GET /orgs/:orgId/setup-guides`, the `Platform` tool's `setup.guides` and `setup.read`). Nothing
+ * new is decided here: guides, visibility, drift and actions are `PluginGuides`' (the guide route's
+ * rules), check states are `SetupChecksService.states` (cached, nothing runs), the templates on in
+ * the org are `ComponentScopeService.orgList`'s. Rendered text carries no secret (§6.3) and check
+ * states only their fixed, redacted fields (§10.8). Stateless: everything comes from PG and Redis.
+ */
+let SetupGuidesService = class SetupGuidesService {
+    db;
+    guides;
+    checks;
+    components;
+    log;
+    constructor(db, guides, checks, components, log) {
+        this.db = db;
+        this.guides = guides;
+        this.checks = checks;
+        this.components = components;
+        this.log = log;
+    }
+    /**
+     * The guides the caller may see, each with its targets: org admins (`channels.manage`) the
+     * channel connections; org admins (`connectors.manage`) the connectors made from templates and
+     * the templates on in the org without a connector, admin audience; members (`connectors.use`
+     * without `connectors.manage`) the connectors whose template guide has a member section, member
+     * audience, without drift (only an admin acks). Each target carries its cached check summary.
+     * A guide that cannot be rendered (gone, a stored document unreadable) is left out and logged.
+     */
+    async list(caller, q = {}) {
+        const org = { orgId: caller.orgId, role: caller.role };
+        const pending = [
+            ...(can(caller.role, "channels.manage") ? await this.connections(org) : []),
+            ...(await this.connectors(org)),
+        ];
+        const entries = new Map();
+        for (const p of pending) {
+            const key = `${p.itemId}/${p.guideId}/${p.audience}`;
+            let entry = entries.get(key);
+            if (entry === undefined) {
+                const g = await this.renderOrSkip(org, p.itemId, p.guideId, {
+                    audience: p.audience,
+                    locale: q.locale ?? "en",
+                });
+                // members get a guide only when it has a member section (the web's How to connect rule, §9.3);
+                // text outside every section applies to all audiences, so admins need no section
+                if (g === null || (p.audience === "member" && !g.audiences.includes("member")))
+                    continue;
+                entry = {
+                    itemId: g.itemId,
+                    plugin: g.plugin,
+                    guideId: g.id,
+                    place: g.place,
+                    template: g.template,
+                    audience: p.audience,
+                    title: g.title,
+                    targets: [],
+                };
+                entries.set(key, entry);
+            }
+            const { checked, ...target } = p.target;
+            entry.targets.push({
+                ...target,
+                checks: checked ? await this.summary(caller, p) : null,
+            });
+        }
+        return [...entries.values()];
+    }
+    /** The cached check summary of a target, or null when the guide cannot be read for it. */
+    async summary(caller, p) {
+        try {
+            return summarize(await this.checks.states(caller, p.itemId, p.guideId, {
+                audience: p.audience,
+                connectionId: p.query.connectionId,
+                connectorId: p.query.connectorId,
+            }));
+        }
+        catch (err) {
+            if (err instanceof ApiError)
+                return null;
+            throw err;
+        }
+    }
+    async renderOrSkip(org, itemId, guideId, q) {
+        try {
+            return await this.guides.render(org, itemId, guideId, q);
+        }
+        catch (err) {
+            if (!(err instanceof ApiError))
+                throw err;
+            this.log.warn("setup guide left out of the list", { itemId, guideId, code: err.code });
+            return null;
+        }
+    }
+    /** The org's channel connections whose plugin has a guide the org sees. */
+    async connections(org) {
+        const rows = await this.db
+            .selectFrom("channel_connections")
+            .select(["id", "plugin", "name", "guide_ack"])
+            .where("org_id", "=", org.orgId)
+            .where("deleted_at", "is", null)
+            .orderBy("created_at")
+            .orderBy("id")
+            .execute();
+        const states = await this.guides.connectionStates(rows.map((r) => ({ id: r.id, plugin: r.plugin, guideAck: r.guide_ack ?? null })), org);
+        return rows.flatMap((r) => pendingOf(states.get(r.id), "admin", {
+            kind: "channel-connection",
+            id: r.id,
+            name: r.name,
+            query: { connectionId: r.id },
+            webPath: setupWebPath.connection(r.id),
+        }));
+    }
+    /**
+     * The org's connectors made from a template with a guide; for org admins also the templates on
+     * in the org that have a guide and no connector yet.
+     */
+    async connectors(org) {
+        const admin = can(org.role, "connectors.manage");
+        if (!admin && !can(org.role, "connectors.use"))
+            return [];
+        const audience = admin ? "admin" : "member";
+        const rows = await this.db
+            .selectFrom("connectors as c")
+            .leftJoin("platform_connector_templates as t", "t.id", "c.platform_template_id")
+            .select([
+            "c.id",
+            "c.name",
+            "c.guide_ack",
+            "c.platform_template_id",
+            "t.catalog_item_id",
+            "t.template_id",
+        ])
+            .where("c.org_id", "=", org.orgId)
+            .where("c.deleted_at", "is", null)
+            .orderBy("c.created_at")
+            .orderBy("c.id")
+            .execute();
+        const states = await this.guides.connectorStates(rows.map((r) => ({
+            id: r.id,
+            itemId: r.catalog_item_id ?? null,
+            templateId: r.template_id ?? null,
+            guideAck: r.guide_ack ?? null,
+        })), org);
+        const out = rows.flatMap((r) => {
+            const state = states.get(r.id);
+            return pendingOf(state && (admin ? state : { ...state, guideDrift: null }), audience, {
+                kind: "connector",
+                id: r.id,
+                name: r.name,
+                query: { connectorId: r.id },
+                webPath: admin ? setupWebPath.connector(r.id) : setupWebPath.memberConnections(),
+            });
+        });
+        if (!admin)
+            return out;
+        const made = new Set(rows.flatMap((r) => (r.platform_template_id ? [r.platform_template_id] : [])));
+        const templates = await this.components.orgList(org.orgId, { kind: "connector_template" });
+        for (const t of templates) {
+            if (!t.on || made.has(t.id) || !t.guide || t.itemId === null)
+                continue;
+            out.push({
+                itemId: t.guide.itemId,
+                guideId: t.guide.guideId,
+                audience,
+                query: {},
+                target: {
+                    kind: "connector-template",
+                    id: t.name,
+                    name: t.displayName?.en ?? t.name,
+                    drift: null,
+                    webPath: setupWebPath.template(t.itemId),
+                    checked: false,
+                },
+            });
+        }
+        return out;
+    }
+    /**
+     * One guide rendered for the caller as a Markdown document (`setup.read`): the guide route's
+     * rendering (`PluginGuides.render`, its visibility, action and target rules), joined, with the
+     * page where the person enters values and acks.
+     */
+    async read(caller, itemId, guideId, q) {
+        const g = await this.guides.render({ orgId: caller.orgId, role: caller.role }, itemId, guideId, q);
+        const webPath = webPathOf(g);
+        return {
+            itemId: g.itemId,
+            plugin: g.plugin,
+            guideId: g.id,
+            place: g.place,
+            title: g.title,
+            markdown: guideMarkdown(g.title, g.blocks),
+            modes: g.modes,
+            mode: g.mode,
+            audiences: g.audiences,
+            audience: g.audience,
+            checks: g.checks.map((c) => ({ id: c.id, label: c.label })),
+            unresolved: g.unresolved,
+            target: g.target,
+            webPath,
+            handover: `Secrets (tokens, signing secrets, client secrets) are typed by the person into their fields on ${webPath}; never ask for one in the conversation. Connecting a personal account and confirming the app was updated (the guide acknowledgement) also happen on that page.`,
+        };
+    }
+};
+SetupGuidesService = __decorate([
+    Injectable(),
+    __param(0, Inject(KernelDb)),
+    __param(1, Inject(PluginGuides)),
+    __param(2, Inject(SetupChecksService)),
+    __param(3, Inject(ComponentScopeService)),
+    __param(4, Inject(KERNEL_LOGGER))
+], SetupGuidesService);
+export { SetupGuidesService };
+/** A pending target from a guide state; none when the target has no guide the org sees. */
+function pendingOf(state, audience, t) {
+    const ref = state?.setupGuide;
+    if (!ref)
+        return [];
+    return [
+        {
+            itemId: ref.itemId,
+            guideId: ref.guideId,
+            audience,
+            query: t.query,
+            target: {
+                kind: t.kind,
+                id: t.id,
+                name: t.name,
+                drift: state.guideDrift,
+                webPath: t.webPath,
+                checked: true,
+            },
+        },
+    ];
+}

package/dist/setup/setup.module.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Setup guide checks (spec 2026-11-09-setup-guides-v2-design.md §10): the registry of kernel and
+ * extension checks, the kernel's own `capybara:*` checks (registered on init) and the service that runs them (cache, single flight, cooldown, the org's
+ * concurrency cap, the time limit, redaction), and the org's guide list (`SetupGuidesService`). Its
+ * controllers are the api role's; the `Platform` tool's `setup` operations use the same services.
+ */
+export declare class SetupModule {
+}

package/dist/setup/setup.module.js

@@ -0,0 +1,31 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { Module } from "@nestjs/common";
+import { CatalogModule } from "../catalog/catalog.module.js";
+import { ChannelsModule } from "../channels/channels.module.js";
+import { ExtensionsModule } from "../extensions/extensions.module.js";
+import { ToolsModule } from "../tools/tools.module.js";
+import { KernelChecks } from "./kernel-checks.js";
+import { SetupCheckRegistry } from "./setup-check-registry.js";
+import { SetupChecksService } from "./setup-checks.service.js";
+import { SetupGuidesService } from "./setup-guides.service.js";
+/**
+ * Setup guide checks (spec 2026-11-09-setup-guides-v2-design.md §10): the registry of kernel and
+ * extension checks, the kernel's own `capybara:*` checks (registered on init) and the service that runs them (cache, single flight, cooldown, the org's
+ * concurrency cap, the time limit, redaction), and the org's guide list (`SetupGuidesService`). Its
+ * controllers are the api role's; the `Platform` tool's `setup` operations use the same services.
+ */
+let SetupModule = class SetupModule {
+};
+SetupModule = __decorate([
+    Module({
+        imports: [ExtensionsModule, ChannelsModule, ToolsModule, CatalogModule],
+        providers: [SetupCheckRegistry, SetupChecksService, SetupGuidesService, KernelChecks],
+        exports: [SetupCheckRegistry, SetupChecksService, SetupGuidesService],
+    })
+], SetupModule);
+export { SetupModule };

package/dist/tools/connectors.controller.d.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
+import type { ConnectionGuideState } from "../extensions/plugin-guides.js";
 import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Principal } from "../identity/principal.js";
 import { type OrgContext } from "../orgs/org.guard.js";
 import { ConnectorAccountPolicies, type MemberToolPolicyView } from "./connector-account-policies.js";
-import { CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
+import { ConnectorGuideAckSchema, CredentialValue, MemberToolPoliciesBody } from "./connectors.schemas.js";
 import { type ConnectorDetail, type ConnectorPreview, type ConnectorSummary, ConnectorsService, type ToolIssue } from "./connectors.service.js";
 declare const CreateBody: z.ZodObject<{
     name: z.ZodString;
@@ -169,6 +170,14 @@ declare const UpdateBody: z.ZodObject<{
     }, z.core.$strict>>>;
     allowUnannotated: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+/**
+ * A connector as the org's pages show it: with its plugin's icon (`icon`, see `withIcons`), its
+ * template's setup guide and the drift since it was set up (`setupGuide`, `guideDrift`; spec
+ * 2026-11-09-setup-guides-v2-design.md §9.3, §11).
+ */
+export type ConnectorPage<T extends ConnectorSummary = ConnectorDetail> = T & ConnectionGuideState & {
+    icon: string | null;
+};
 /**
  * 连接器（`/api/v1/orgs/:orgId/connectors`）：读与个人凭据用 `connectors.use`（访客起），安装 / 修改 / 删除 / 刷新 /
  * 组织凭据用 `connectors.manage`（管理员起）；两者都仅限用户主体。
@@ -185,10 +194,11 @@ export declare class ConnectorsController {
      */
     private withIcons;
     list(org: OrgContext): Promise<{
-        connectors: (ConnectorSummary & {
-            icon: string | null;
-        })[];
+        connectors: ConnectorPage<ConnectorSummary>[];
     }>;
+    /** Adds the icon and the setup guide fields to connector views (one lookup each for all). */
+    private withGuides;
+    private withGuide;
     /**
      * The connector kinds the org can create connectors of, each with the plugin providing it (the
      * install wizard offers only these; an empty list means no connector extension is enabled).
@@ -200,7 +210,7 @@ export declare class ConnectorsController {
         }[];
     }>;
     create(principal: Principal, org: OrgContext, body: z.infer<typeof CreateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
     }>;
     /**
@@ -209,16 +219,14 @@ export declare class ConnectorsController {
      */
     preview(principal: Principal, org: OrgContext, body: z.infer<typeof PreviewBody>): Promise<ConnectorPreview>;
     get(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail & {
-            icon: string | null;
-        };
+        connector: ConnectorPage;
     }>;
     update(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof UpdateBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
     }>;
     remove(principal: Principal, org: OrgContext, connectorId: string): Promise<void>;
     refresh(principal: Principal, org: OrgContext, connectorId: string): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
         issues: ToolIssue[];
         changes: {
             added: string[];
@@ -228,7 +236,16 @@ export declare class ConnectorsController {
     }>;
     /** 复核待复核的工具（漂移检测，spec 7.3）：approve 采用新定义并启用，reject 停用并保留旧定义。 */
     review(principal: Principal, org: OrgContext, connectorId: string, name: string, body: z.infer<typeof ReviewBody>): Promise<{
-        connector: ConnectorDetail;
+        connector: ConnectorPage;
+    }>;
+    /**
+     * 「我已更新应用」: the org admin updated the third-party app to the connector template's current
+     * setup guide (`{ hash }` of the guide shown) -> 200 `{ connector }`; 409
+     * `connector.guide_changed` when the guide moved on since, 404 `catalog.guide_not_found` for a
+     * connector without a template guide.
+     */
+    ackGuide(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof ConnectorGuideAckSchema>): Promise<{
+        connector: ConnectorPage;
     }>;
     setOrgCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;
     setMyCredential(principal: Principal, org: OrgContext, connectorId: string, body: z.infer<typeof CredentialValue>): Promise<void>;