@cuylabs/channel-slack 0.5.1 → 0.7.0

package/dist/transports/index.js

@@ -0,0 +1,24 @@
+import {
+  createSlackBoltApp
+} from "../chunk-QJYCHWN6.js";
+import {
+  acquireSlackSocketModePostgresLock,
+  acquireSlackSocketModeProcessLock,
+  createSlackSdkLogger,
+  createSlackSocketBoltApp,
+  createSlackSocketModeRestartGuard,
+  createSlackSocketModeRuntime,
+  redactSlackSocketModeLogValue
+} from "../chunk-73QXT7MA.js";
+import "../chunk-S3SWPYXJ.js";
+export {
+  acquireSlackSocketModePostgresLock,
+  acquireSlackSocketModeProcessLock,
+  createSlackBoltApp,
+  createSlackBoltApp as createSlackHttpBoltApp,
+  createSlackSdkLogger,
+  createSlackSocketBoltApp,
+  createSlackSocketModeRestartGuard,
+  createSlackSocketModeRuntime,
+  redactSlackSocketModeLogValue
+};

package/dist/transports/socket/index.d.ts

@@ -0,0 +1,94 @@
+import { AppOptions, SocketModeReceiverOptions, App } from '@slack/bolt';
+export { LogLevel as SlackSdkLogLevel, Logger as SlackSdkLogger } from '@slack/bolt';
+import { e as SlackDirectAuthOptions, d as SlackDirectAuthMode } from '../../types-B9NfCVrk.js';
+import { L as Logger } from '../../logging-Bl3HfcC8.js';
+export { S as SlackSocketModeReceiverRuntimeOptions, a as SlackSocketModeRestartGuard, b as SlackSocketModeRuntime, c as SlackSocketModeRuntimeOptions, d as SlackSocketModeRuntimePolicy, e as createSlackSdkLogger, f as createSlackSocketModeRestartGuard, g as createSlackSocketModeRuntime, r as redactSlackSocketModeLogValue } from '../../runtime-BNBHOZSQ.js';
+import 'node:http';
+
+/**
+ * `createSlackSocketBoltApp` — builds a Socket Mode Bolt `App` from the
+ * package's structured auth options. Mirrors `createSlackBoltApp` without
+ * owning any assistant/app surface mounting.
+ */
+
+type ControlledSocketBoltAppOption = "receiver" | "socketMode" | "appToken" | "token" | "authorize" | "botId" | "botUserId" | "clientId" | "clientSecret" | "stateSecret" | "redirectUri" | "installationStore" | "scopes" | "installerOptions";
+type ControlledSocketModeReceiverOption = "appToken" | "clientId" | "clientSecret" | "stateSecret" | "redirectUri" | "installationStore" | "scopes" | "installerOptions" | "logger" | "logLevel";
+interface CreateSlackSocketBoltAppOptions {
+    /**
+     * Slack app-level token (`xapp-...`) with `connections:write` scope.
+     * @default process.env.SLACK_APP_TOKEN
+     */
+    appToken?: string;
+    /**
+     * Convenience override for single-workspace mode.
+     * @default process.env.SLACK_BOT_TOKEN
+     */
+    botToken?: string;
+    /**
+     * Direct-mode auth configuration.
+     *
+     * - omit for single-workspace token mode
+     * - use `{ mode: "oauth", ... }` for Bolt-managed installs
+     * - use `{ mode: "authorize", authorize }` for external token resolution
+     */
+    auth?: SlackDirectAuthOptions;
+    /**
+     * Additional Bolt `App` options passed after this package sets Socket Mode
+     * and auth. Use for logger/clientOptions and non-auth native Bolt config.
+     */
+    boltAppOptions?: Partial<Omit<AppOptions, ControlledSocketBoltAppOption>>;
+    /**
+     * Additional native Socket Mode receiver options. Use this for websocket
+     * health tuning such as ping timeouts, reconnect behavior, and receiver
+     * error handling. Auth/OAuth fields stay controlled by this helper.
+     */
+    socketModeReceiverOptions?: Partial<Omit<SocketModeReceiverOptions, ControlledSocketModeReceiverOption>>;
+}
+interface CreateSlackSocketBoltAppResult {
+    boltApp: App;
+    authMode: SlackDirectAuthMode;
+}
+declare function createSlackSocketBoltApp(options?: CreateSlackSocketBoltAppOptions): Promise<CreateSlackSocketBoltAppResult>;
+
+interface SlackSocketModeProcessLockOptions {
+    appSlug: string;
+    appToken?: string;
+    enabled?: boolean;
+    lockDir?: string;
+    logger?: Logger;
+}
+interface SlackSocketModeProcessLock {
+    path: string;
+    release(): void;
+}
+declare function acquireSlackSocketModeProcessLock({ appSlug, appToken, enabled, lockDir, logger, }: SlackSocketModeProcessLockOptions): SlackSocketModeProcessLock | undefined;
+
+interface SlackSocketModePostgresLockClient {
+    query<T = unknown>(sql: string, values?: readonly unknown[]): Promise<{
+        rows: T[];
+        rowCount?: number | null;
+    }>;
+    release?: () => void;
+}
+interface SlackSocketModePostgresLockPool {
+    connect(): Promise<SlackSocketModePostgresLockClient>;
+    end?: () => Promise<void>;
+}
+interface SlackSocketModePostgresLockOptions {
+    appSlug: string;
+    appToken?: string;
+    client?: SlackSocketModePostgresLockClient;
+    connectionString?: string;
+    enabled?: boolean;
+    logger?: Logger;
+    namespace?: string;
+    pool?: SlackSocketModePostgresLockPool;
+}
+interface SlackSocketModePostgresLock {
+    path: string;
+    close(): Promise<void>;
+    release(): Promise<void>;
+}
+declare function acquireSlackSocketModePostgresLock({ appSlug, appToken, client, connectionString, enabled, logger, namespace, pool, }: SlackSocketModePostgresLockOptions): Promise<SlackSocketModePostgresLock | undefined>;
+
+export { type CreateSlackSocketBoltAppOptions, type CreateSlackSocketBoltAppResult, type SlackSocketModePostgresLock, type SlackSocketModePostgresLockClient, type SlackSocketModePostgresLockOptions, type SlackSocketModePostgresLockPool, type SlackSocketModeProcessLock, type SlackSocketModeProcessLockOptions, acquireSlackSocketModePostgresLock, acquireSlackSocketModeProcessLock, createSlackSocketBoltApp };

package/dist/transports/socket/index.js

@@ -0,0 +1,19 @@
+import {
+  acquireSlackSocketModePostgresLock,
+  acquireSlackSocketModeProcessLock,
+  createSlackSdkLogger,
+  createSlackSocketBoltApp,
+  createSlackSocketModeRestartGuard,
+  createSlackSocketModeRuntime,
+  redactSlackSocketModeLogValue
+} from "../../chunk-73QXT7MA.js";
+import "../../chunk-S3SWPYXJ.js";
+export {
+  acquireSlackSocketModePostgresLock,
+  acquireSlackSocketModeProcessLock,
+  createSlackSdkLogger,
+  createSlackSocketBoltApp,
+  createSlackSocketModeRestartGuard,
+  createSlackSocketModeRuntime,
+  redactSlackSocketModeLogValue
+};

package/dist/types-B9NfCVrk.d.ts

@@ -0,0 +1,141 @@
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+/**
+ * OAuth and installation type declarations for the direct Slack adapter.
+ *
+ * Pure types — no runtime imports beyond `node:http` request/response.
+ * Mirrors the public surface of `@slack/oauth` enough that callers can
+ * implement custom installation/state stores without depending on Bolt's
+ * internal types.
+ */
+
+type SlackDirectAuthMode = "single-workspace" | "oauth" | "authorize";
+interface SlackOAuthError extends Error {
+    code: string;
+}
+interface SlackInstallURLOptions {
+    scopes?: string[];
+    userScopes?: string[];
+    redirectUri?: string;
+    metadata?: string;
+    teamId?: string;
+}
+interface SlackInstallationQuery {
+    teamId: string | undefined;
+    enterpriseId: string | undefined;
+    userId?: string;
+    conversationId?: string;
+    isEnterpriseInstall: boolean;
+}
+interface SlackInstallation {
+    team?: {
+        id: string;
+        name?: string;
+    } | undefined;
+    enterprise?: {
+        id: string;
+        name?: string;
+    } | undefined;
+    user: {
+        id: string;
+        token?: string;
+        refreshToken?: string;
+        expiresAt?: number;
+        scopes?: string[];
+    };
+    bot?: {
+        token: string;
+        refreshToken?: string;
+        expiresAt?: number;
+        scopes: string[];
+        id?: string;
+        userId?: string;
+    };
+    incomingWebhook?: {
+        url: string;
+        channel?: string;
+        channelId?: string;
+        configurationUrl?: string;
+    };
+    appId?: string;
+    tokenType?: "bot";
+    enterpriseUrl?: string;
+    isEnterpriseInstall?: boolean;
+    authVersion?: "v1" | "v2";
+    metadata?: string;
+}
+interface SlackInstallationStore {
+    storeInstallation(installation: SlackInstallation, logger?: unknown): Promise<void>;
+    fetchInstallation(query: SlackInstallationQuery, logger?: unknown): Promise<SlackInstallation>;
+    deleteInstallation?(query: SlackInstallationQuery, logger?: unknown): Promise<void>;
+}
+interface SlackStateStore {
+    generateStateParam(installOptions: SlackInstallURLOptions, now: Date): Promise<string>;
+    verifyStateParam(now: Date, state: string): Promise<SlackInstallURLOptions>;
+}
+interface SlackOAuthInstallPathOptions {
+    beforeRedirection?: (request: IncomingMessage, response: ServerResponse, options?: SlackInstallURLOptions) => Promise<boolean>;
+}
+interface SlackOAuthCallbackOptions {
+    beforeInstallation?: (options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+    afterInstallation?: (installation: SlackInstallation, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<boolean>;
+    success?: (installation: SlackInstallation, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => void;
+    successAsync?: (installation: SlackInstallation, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<void>;
+    failure?: (error: SlackOAuthError, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => void;
+    failureAsync?: (error: SlackOAuthError, options: SlackInstallURLOptions, request: IncomingMessage, response: ServerResponse) => Promise<void>;
+}
+interface SlackAuthorizeSource {
+    teamId: string | undefined;
+    enterpriseId: string | undefined;
+    userId?: string;
+    conversationId?: string;
+    isEnterpriseInstall: boolean;
+}
+interface SlackAuthorizeResult {
+    botToken?: string;
+    userToken?: string;
+    botId?: string;
+    botUserId?: string;
+    userId?: string;
+    teamId?: string;
+    enterpriseId?: string;
+    [key: string]: unknown;
+}
+type SlackAuthorizeFn = (source: SlackAuthorizeSource, body?: unknown) => Promise<SlackAuthorizeResult>;
+interface SlackSingleWorkspaceAuthOptions {
+    mode?: "single-workspace";
+    botToken?: string;
+    botId?: string;
+    botUserId?: string;
+}
+interface SlackOAuthAuthOptions {
+    mode: "oauth";
+    clientId?: string;
+    clientSecret?: string;
+    stateSecret?: string;
+    installationStore: SlackInstallationStore;
+    stateStore?: SlackStateStore;
+    stateVerification?: boolean;
+    legacyStateVerification?: boolean;
+    stateCookieName?: string;
+    stateCookieExpirationSeconds?: number;
+    redirectUri?: string;
+    scopes?: string[];
+    userScopes?: string[];
+    metadata?: string;
+    installPath?: string;
+    callbackPath?: string;
+    renderHtmlForInstallPath?: (url: string) => string;
+    installPathOptions?: SlackOAuthInstallPathOptions;
+    callbackOptions?: SlackOAuthCallbackOptions;
+    directInstall?: boolean;
+    authVersion?: "v1" | "v2";
+    authorizationUrl?: string;
+}
+interface SlackCustomAuthorizeAuthOptions {
+    mode: "authorize";
+    authorize: SlackAuthorizeFn;
+}
+type SlackDirectAuthOptions = SlackSingleWorkspaceAuthOptions | SlackOAuthAuthOptions | SlackCustomAuthorizeAuthOptions;
+
+export type { SlackAuthorizeFn as S, SlackAuthorizeResult as a, SlackAuthorizeSource as b, SlackCustomAuthorizeAuthOptions as c, SlackDirectAuthMode as d, SlackDirectAuthOptions as e, SlackInstallation as f, SlackInstallationQuery as g, SlackInstallationStore as h, SlackOAuthAuthOptions as i, SlackOAuthCallbackOptions as j, SlackOAuthError as k, SlackOAuthInstallPathOptions as l, SlackSingleWorkspaceAuthOptions as m, SlackStateStore as n };

package/dist/views/index.d.ts

@@ -0,0 +1,98 @@
+import { App } from '@slack/bolt';
+import { View, HomeView } from '@slack/types';
+
+type SlackViewCallbackId = string | RegExp;
+interface SlackViewApiResponse {
+    ok?: boolean;
+    view?: unknown;
+    [key: string]: unknown;
+}
+interface SlackViewsClient {
+    views?: {
+        open?: unknown;
+        push?: unknown;
+        update?: unknown;
+        publish?: unknown;
+    };
+}
+interface OpenSlackModalOptions {
+    client: SlackViewsClient;
+    triggerId: string;
+    view: View;
+    token?: string;
+}
+interface PushSlackModalOptions {
+    client: SlackViewsClient;
+    triggerId: string;
+    view: View;
+    token?: string;
+}
+interface UpdateSlackViewOptions {
+    client: SlackViewsClient;
+    view: View;
+    viewId?: string;
+    externalId?: string;
+    hash?: string;
+    token?: string;
+}
+interface PublishSlackHomeViewOptions {
+    client: SlackViewsClient;
+    userId: string;
+    view: HomeView;
+    hash?: string;
+    token?: string;
+}
+interface SlackViewPayload {
+    id?: string;
+    callback_id?: string;
+    private_metadata?: string;
+    state?: unknown;
+    hash?: string;
+    [key: string]: unknown;
+}
+interface SlackViewActor {
+    userId?: string;
+    teamId?: string;
+    enterpriseId?: string;
+}
+interface SlackViewSubmissionAckResponse {
+    response_action: "clear" | "errors" | "push" | "update";
+    errors?: Record<string, string>;
+    view?: View;
+}
+interface SlackViewWorkflowContext<TMetadata = unknown> {
+    body: unknown;
+    client: SlackViewsClient;
+    view: SlackViewPayload;
+    callbackId?: string;
+    triggerId?: string;
+    actor: SlackViewActor;
+    metadata: TMetadata | undefined;
+}
+interface RegisterSlackViewWorkflowOptions<TMetadata = unknown> {
+    boltApp: App;
+    callbackId: SlackViewCallbackId;
+    decodePrivateMetadata?: (privateMetadata: string | undefined, context: Omit<SlackViewWorkflowContext<TMetadata>, "metadata">) => TMetadata | undefined;
+    onSubmission?: (context: SlackViewWorkflowContext<TMetadata>) => SlackViewSubmissionAckResponse | void | Promise<SlackViewSubmissionAckResponse | void>;
+    onClose?: (context: SlackViewWorkflowContext<TMetadata>) => void | Promise<void>;
+    onError?: (error: unknown, context: Omit<SlackViewWorkflowContext<TMetadata>, "metadata"> & {
+        metadata?: TMetadata | undefined;
+    }) => void | Promise<void>;
+}
+interface SlackViewWorkflowRegistration {
+    callbackId: SlackViewCallbackId;
+}
+
+declare function openSlackModal({ client, triggerId, view, token, }: OpenSlackModalOptions): Promise<SlackViewApiResponse>;
+declare function pushSlackModal({ client, triggerId, view, token, }: PushSlackModalOptions): Promise<SlackViewApiResponse>;
+declare function updateSlackView({ client, view, viewId, externalId, hash, token, }: UpdateSlackViewOptions): Promise<SlackViewApiResponse>;
+declare function publishSlackHomeView({ client, userId, view, hash, token, }: PublishSlackHomeViewOptions): Promise<SlackViewApiResponse>;
+
+declare const SLACK_VIEW_PRIVATE_METADATA_MAX_CHARS = 3000;
+declare function encodeSlackViewPrivateMetadata(value: unknown): string;
+declare function decodeSlackViewPrivateMetadata<T = unknown>(privateMetadata: string | undefined): T | undefined;
+declare function readSlackViewPrivateMetadata<T = unknown>(view: Pick<SlackViewPayload, "private_metadata">): T | undefined;
+
+declare function registerSlackViewWorkflow<TMetadata = unknown>({ boltApp, callbackId, decodePrivateMetadata, onSubmission, onClose, onError, }: RegisterSlackViewWorkflowOptions<TMetadata>): SlackViewWorkflowRegistration;
+
+export { type OpenSlackModalOptions, type PublishSlackHomeViewOptions, type PushSlackModalOptions, type RegisterSlackViewWorkflowOptions, SLACK_VIEW_PRIVATE_METADATA_MAX_CHARS, type SlackViewActor, type SlackViewApiResponse, type SlackViewCallbackId, type SlackViewPayload, type SlackViewSubmissionAckResponse, type SlackViewWorkflowContext, type SlackViewWorkflowRegistration, type SlackViewsClient, type UpdateSlackViewOptions, decodeSlackViewPrivateMetadata, encodeSlackViewPrivateMetadata, openSlackModal, publishSlackHomeView, pushSlackModal, readSlackViewPrivateMetadata, registerSlackViewWorkflow, updateSlackView };

package/dist/views/index.js

@@ -0,0 +1,22 @@
+import {
+  SLACK_VIEW_PRIVATE_METADATA_MAX_CHARS,
+  decodeSlackViewPrivateMetadata,
+  encodeSlackViewPrivateMetadata,
+  openSlackModal,
+  publishSlackHomeView,
+  pushSlackModal,
+  readSlackViewPrivateMetadata,
+  registerSlackViewWorkflow,
+  updateSlackView
+} from "../chunk-IRFKUPJN.js";
+export {
+  SLACK_VIEW_PRIVATE_METADATA_MAX_CHARS,
+  decodeSlackViewPrivateMetadata,
+  encodeSlackViewPrivateMetadata,
+  openSlackModal,
+  publishSlackHomeView,
+  pushSlackModal,
+  readSlackViewPrivateMetadata,
+  registerSlackViewWorkflow,
+  updateSlackView
+};

package/docs/README.md

@@ -0,0 +1,32 @@
+# Channel Slack Docs
+
+`@cuylabs/channel-slack` is the reusable Slack mechanics package. Start with
+the package boundary, then use the reference and recipes for the feature surface
+your adapter or application needs.
+
+## Reference
+
+- [Package boundary](reference/channel-slack-boundary.md)
+- [Exports and peer expectations](reference/exports.md)
+- [Source layout](reference/source-layout.md)
+
+## Concepts
+
+- [Activity parsing](concepts/activity.md)
+- [Artifacts](concepts/artifacts.md)
+- [Entrypoints](concepts/entrypoints.md)
+- [Message policy](concepts/message-policy.md)
+- [Setup requirements](concepts/setup-requirements.md)
+- [Supplemental history](concepts/supplemental-history.md)
+- [Transport runtime](concepts/transport-runtime.md)
+- [Views](concepts/views.md)
+
+## Recipes
+
+- [App mention handler](recipes/app-mention-handler.md)
+- [Assistant thread handler](recipes/assistant-thread-handler.md)
+- [Socket Mode app](recipes/socket-mode-app.md)
+- [Slash command and shortcut handler](recipes/slash-command-and-shortcut.md)
+- [Publish an artifact](recipes/publish-artifact.md)
+- [Generate a Slack manifest](recipes/generate-slack-manifest.md)
+- [History visibility filter](recipes/history-visibility.md)

package/docs/concepts/activity.md

@@ -1,8 +1,8 @@
 # Activity
 
-An activity is the normalized message shape an agent adapter receives from
-Slack. It is intentionally smaller than a raw Slack event and does not depend on
-Bolt.
+An activity is the normalized Slack message shape an adapter or application can
+map into its own runtime. It is intentionally smaller than a raw Slack event and
+does not depend on Bolt.
 
 ```typescript
 import { parseSlackMentionActivity } from "@cuylabs/channel-slack/core";

package/docs/concepts/artifacts.md

@@ -0,0 +1,56 @@
+# Artifacts
+
+Artifacts publish generated outputs to Slack without depending on any agent
+runtime. The package accepts a structural Slack Web API client, so callers can
+pass a real `WebClient`, a scoped client from a request handler, or a test
+double with the methods they use.
+
+```typescript
+import { publishSlackArtifact } from "@cuylabs/channel-slack/artifacts";
+
+const publication = await publishSlackArtifact({
+  client,
+  channelId: activity.channelId,
+  threadTs: activity.threadTs ?? activity.messageTs,
+  artifact: {
+    kind: "text",
+    title: "Investigation summary",
+    summary: "Key findings from the thread.",
+    text: reportMarkdown,
+  },
+});
+```
+
+## Artifact Kinds
+
+- `text`: uploads text as a Slack file by default. Set `publishAs: "message"`
+  to post it as a Block Kit message instead.
+- `file`: uploads binary or text data from `data` or `filePath`.
+- `image`: uploads an image file and requires `altText`.
+- `link`: posts a Block Kit message with a Slack-formatted link.
+- `canvas`: creates or updates a Slack Canvas from Markdown.
+
+## Results
+
+`publishSlackArtifact` returns a `SlackArtifactPublication` with:
+
+- `method`: `message`, `file`, or `canvas`.
+- the original `artifact`.
+- the raw Slack API `response`.
+- target metadata such as `channelId`, `threadTs`, `messageTs`, `fileId`, or
+  `canvasId` when Slack returns it.
+
+## Slack Client Surface
+
+Only the method required by the selected artifact kind must exist:
+
+- message/link artifacts use `client.chat.postMessage`.
+- text/file/image file uploads use `client.files.uploadV2`.
+- Canvas creation uses `client.conversations.canvases.create` for channel
+  canvases when available, or `client.canvases.create` otherwise.
+- Canvas updates use `client.canvases.edit`.
+
+## Setup
+
+The `artifacts` setup feature adds `chat:write` and `files:write`.
+The `canvas-artifacts` setup feature adds `canvases:write`.

package/docs/concepts/entrypoints.md

@@ -0,0 +1,73 @@
+# Entrypoints
+
+Entrypoints normalize Slack slash command and shortcut payloads into small
+package contracts. They do not start a turn or choose a runtime request shape.
+
+```typescript
+import { parseSlackSlashCommandEntrypoint } from "@cuylabs/channel-slack/entrypoints";
+
+const entrypoint = parseSlackSlashCommandEntrypoint(payload);
+```
+
+## Slash Commands
+
+`parseSlackSlashCommandEntrypoint` returns:
+
+- `kind: "slash-command"`.
+- `command`: the invoked slash command, such as `/ask`.
+- `activity`: a `SlackActivityInfo` shape with channel, user, team, and text.
+- optional Slack request metadata such as `triggerId`, `responseUrl`,
+  `channelName`, `teamDomain`, `appId`, and enterprise fields.
+
+The parser treats the command text as the model-facing text. A host adapter can
+map `entrypoint.activity.text` into its own runtime input while preserving the
+Slack metadata for routing, logging, or response targets.
+
+## Shortcuts
+
+Use `parseSlackShortcutEntrypoint` when one handler receives both global and
+message shortcuts:
+
+```typescript
+import { parseSlackShortcutEntrypoint } from "@cuylabs/channel-slack/entrypoints";
+
+const entrypoint = parseSlackShortcutEntrypoint(payload);
+```
+
+Global shortcuts return `kind: "global-shortcut"` and include trigger/user/team
+metadata, but no selected message.
+
+Message shortcuts return `kind: "message-shortcut"`, include the selected
+message text, and also expose `activity` so a runtime adapter can treat the
+selection as a Slack turn candidate.
+
+## Setup
+
+Passing `slashCommands` or `shortcuts` to setup helpers automatically enables
+the matching feature, the `commands` scope, and Slack interactivity settings.
+
+```typescript
+import { createSlackAppManifest } from "@cuylabs/channel-slack/setup";
+
+const manifest = createSlackAppManifest({
+  name: "My Agent",
+  preset: false,
+  transport: "http",
+  baseUrl: "https://agent.example.com",
+  slashCommands: [
+    {
+      command: "/ask",
+      description: "Ask the agent",
+      usage_hint: "summarize this thread",
+    },
+  ],
+  shortcuts: [
+    {
+      type: "message",
+      name: "Summarize message",
+      callback_id: "summarize_message",
+      description: "Summarize the selected Slack message",
+    },
+  ],
+});
+```

package/docs/concepts/setup-requirements.md

@@ -19,6 +19,10 @@ const requirements = getSlackSetupRequirements({
 - `agent-app`: Assistant, app mentions, direct messages, and feedback.
 
 Pass `preset: false` and provide `features` when an app needs exact control.
+Supplying `slashCommands` or `shortcuts` automatically enables the matching
+feature and adds the Slack `commands` scope plus interactivity settings.
+The `artifacts` feature adds `chat:write` and `files:write`; the
+`canvas-artifacts` feature adds `canvases:write`.
 
 ## Features
 
@@ -32,12 +36,31 @@ Feature selections produce:
   Socket Mode.
 - environment variables needed by the chosen transport.
 
+Common feature selections:
+
+- `assistant`: Assistant view events, `assistant:write`, and `chat:write`.
+- `app-mentions`: app mention event subscription and reply permission.
+- `direct-messages`: DM message events and DM history/read scopes.
+- `channel-messages`: passive channel/group message events and history scopes.
+- `slash-commands`: `commands` scope and interactivity.
+- `shortcuts`: `commands` scope and interactivity.
+- `artifacts`: `chat:write` and `files:write`.
+- `canvas-artifacts`: `canvases:write`.
+- `history`: channel, group, DM, and MPIM history scopes.
+- `feedback` and `interactivity`: `chat:write` plus interactivity.
+- `user-profiles` and `user-emails`: Slack user profile scopes.
+- `workspace-search`: Slack search scopes.
+
 ## Manifests
 
 `createSlackAppManifest` produces a Slack app manifest from the same
 requirements. `compareSlackAppManifest` checks an existing manifest-like object
 against requirements and returns path-level findings.
 
+Pass `slashCommands` and `shortcuts` to include those manifest sections. For
+HTTP transport, command and interactivity URLs are filled from `baseUrl` and
+`eventsPath` unless a command defines its own `url`.
+
 ## Inspection
 
 `inspectSlackAppSetup` combines requirements with a live token inspection. It

package/docs/concepts/{bolt-runtime.md → transport-runtime.md}

@@ -1,7 +1,12 @@
-# Bolt Runtime
+# Transport Runtime
 
-The Bolt helpers create Slack transports and auth wiring. They deliberately do
-not register handlers, own prompts, run agents, or choose deployment policy.
+The transport helpers create Slack apps with Bolt auth wiring. They deliberately
+do not register handlers, own prompts, run agents, or choose deployment policy.
+
+Use transport-specific imports:
+
+- `@cuylabs/channel-slack/transports/http`
+- `@cuylabs/channel-slack/transports/socket`
 
 ## HTTP
 
@@ -41,7 +46,7 @@ Postgres advisory lock before starting the Socket Mode app:
 import {
   acquireSlackSocketModePostgresLock,
   createSlackSocketModeRuntime,
-} from "@cuylabs/channel-slack/bolt";
+} from "@cuylabs/channel-slack/transports/socket";
 
 const postgresLock = await acquireSlackSocketModePostgresLock({
   appSlug: "my-agent",