@synap-core/cli 1.8.0 → 1.11.0

package/node_modules/@synap/hub-rest-client/src/types.ts

@@ -28,6 +28,15 @@ export interface HubEntity {
   dueDate?: string;
   content?: string;
   url?: string;
+  /** Short, server-generated summary suitable for lists and agent context. */
+  preview?: string | null;
+  /** Optional long-form summary returned by entity detail routes. */
+  description?: string | null;
+  /** Linked versioned document, when this entity has long-form content. */
+  documentId?: string | null;
+  /** System-managed fields returned by the canonical entity wire codec. */
+  systemData?: Record<string, unknown>;
+  version?: number;
 }
 
 export interface HubDocument {
@@ -37,18 +46,16 @@ export interface HubDocument {
   workspaceId: string | null;
   createdAt: string;
   updatedAt: string;
+  userId?: string;
+  type?: "text" | "markdown" | "code" | "html" | "pdf" | "docx";
+  language?: string | null;
 }
 
 export interface HubChannel {
   id: string;
   name: string;
   type:
-    | "personal"
-    | "thread"
-    | "sub_thread"
-    | "feed"
-    | "external"
-    | "agent_collab";
+    "personal" | "thread" | "sub_thread" | "feed" | "external" | "agent_collab";
   workspaceId: string | null;
   agentType?: string;
   contextObjectType?:
@@ -82,6 +89,8 @@ export interface HubUser {
   email?: string;
   name?: string;
   scopes?: string[];
+  /** True only when the server authenticated this request as an agent credential. */
+  isAgent: boolean;
 }
 
 export interface HubMemoryResult {
@@ -109,12 +118,35 @@ export interface CreateEntityInput {
   profileSlug: string;
   title: string;
   workspaceId?: string;
+  /** Existing project to file this entity into via `belongs_to_project`. */
+  projectId?: string;
+  /** Short description rendered with the entity; long-form text belongs in content. */
+  description?: string;
   properties?: Record<string, unknown>;
   content?: string;
   url?: string;
   status?: string;
   priority?: "low" | "medium" | "high" | "urgent";
   dueDate?: string;
+  // Agent attribution — the IS threads these so writes are recorded as agent
+  // actions (governance/provenance); the CLI omits them. The backend reads them
+  // from the body (sessionId is also accepted via the x-session-id header).
+  agentUserId?: string;
+  sessionId?: string;
+  reasoning?: string;
+  /** Origin signal for audit/provenance. It does not grant permissions. */
+  source?: HubWriteSource;
+  sourceMessageId?: string;
+  extractedFromMessageId?: string;
+  /** Role profiles to attach with this entity when the write applies inline. */
+  facets?: Array<{
+    /** `profileSlug` is accepted by REST; `slug` remains valid for legacy callers. */
+    profileSlug?: string;
+    slug?: string;
+    status?: string;
+    properties?: Record<string, unknown>;
+    contextEntityId?: string;
+  }>;
 }
 
 export interface UpdateEntityInput {
@@ -132,6 +164,49 @@ export interface CreateDocumentInput {
   content?: string;
   workspaceId?: string;
   entityId?: string;
+  type?: HubDocument["type"];
+  reasoning?: string;
+  agentUserId?: string;
+  sourceMessageId?: string;
+  sessionId?: string;
+}
+
+/** Full-document replacement input for PATCH /documents/:id. */
+export interface UpdateDocumentInput {
+  content: string;
+  title?: string;
+  agentUserId?: string;
+  sourceMessageId?: string;
+  sessionId?: string;
+}
+
+export interface HubDocumentChange {
+  op: "insert" | "delete" | "replace";
+  position?: number;
+  range?: [number, number];
+  text?: string;
+}
+
+/** Submit a governed edit proposal without replacing a document directly. */
+export interface CreateDocumentProposalInput {
+  documentId: string;
+  agentUserId?: string;
+  threadId?: string;
+  sourceMessageId?: string;
+  sessionId?: string;
+  proposalType?: "ai_edit" | "user_suggestion" | "review_comment";
+  changes: HubDocumentChange[];
+  proposedContent: string;
+  originalContent?: string;
+}
+
+/** Proposal rows vary slightly by pod version; these stable fields are shared. */
+export interface HubDocumentProposalResult {
+  id?: string;
+  proposalId?: string;
+  status?: string;
+  reviewUrl?: string;
+  [key: string]: unknown;
 }
 
 export interface StoreMemoryInput {
@@ -167,12 +242,64 @@ export interface PodStatus {
 
 // ─── Capture pipeline types ───────────────────────────────────────────────────
 
+/**
+ * A single tappable chip in a structured follow-up. Mirrors the IS `structure`
+ * output and the frontend capture-pipeline contract EXACTLY (do NOT narrow).
+ */
+export interface FollowUpChip {
+  label: string;
+  value: string;
+  action:
+    "link_entity" | "set_property" | "add_relation" | "confirm" | "dismiss";
+  icon?: string;
+  entityId?: string;
+  propertyKey?: string;
+}
+
+/** Structured follow-up the IS may emit instead of a plain string question. */
+export interface StructuredFollowUp {
+  question: string;
+  suggestions: FollowUpChip[];
+}
+
+/** One field of an AI-authored dynamic form. `type` is a free string (field kind). */
+export interface DynamicFormField {
+  key: string;
+  label: string;
+  type: string;
+  constraints?: {
+    enum?: string[];
+    min?: number;
+    max?: number;
+    pattern?: string;
+  };
+  required?: boolean;
+  help?: string;
+}
+
+/** AI-authored guided-capture form spec (additive, null-safe). */
+export interface DynamicFormSpec {
+  title?: string;
+  note?: string;
+  fields: DynamicFormField[];
+}
+
 export interface CaptureProposal {
   tempId: string;
   profileSlug: string;
   title: string;
   description?: string;
+  /** Long-form body preserved through plan → commit as a linked document. */
+  content?: string;
   properties?: Record<string, unknown>;
+  /** Role profiles proposed alongside the primary kind. */
+  facets?: Array<{
+    profileSlug: string;
+    status?: string;
+    properties?: Record<string, unknown>;
+    /** Batch-local entity reference used by captureExecute. */
+    contextTempId?: string;
+  }>;
   confidence: number;
   action: "create" | "link" | "dismiss";
   linkedEntityId?: string;
@@ -194,10 +321,39 @@ export interface CaptureRelation {
 export interface CaptureStructureResponse {
   proposals: CaptureProposal[];
   relations: CaptureRelation[];
-  followUp: string | null;
+  /** The intelligence service was unavailable, so the pod returned a raw-note fallback. */
+  degraded?: boolean;
+  followUp: string | StructuredFollowUp | null;
+  formSpec?: DynamicFormSpec | null;
+  targetWorkspaceId?: string | null;
+  targetWorkspaceConfidence?: number | null;
+  targetWorkspaceReason?: string | null;
+  targetProjectId?: string | null;
+  /**
+   * Soft meta-structure suggestions (display-only chips). Never materialize.
+   * Additive — absent when the model has nothing to suggest.
+   */
+  architectureSuggestions?: Array<{
+    kind?:
+      | "workspace_template"
+      | "new_workspace"
+      | "project"
+      | "view"
+      | "role"
+      | "playbook";
+    title: string;
+    reason?: string;
+    confidence?: number;
+    payload?: Record<string, unknown>;
+  }>;
   dedupCandidates?: Record<
     string,
-    Array<{ entityId: string; title: string; score: number }>
+    Array<{
+      entityId: string;
+      title: string;
+      profileSlug: string;
+      score: number;
+    }>
   >;
 }
 
@@ -208,11 +364,122 @@ export interface CaptureExecuteInput {
     title: string;
     description?: string;
     properties?: Record<string, unknown>;
-    action: "create" | "link" | "dismiss";
+    /** Legacy structure-output field; the execute route ignores it. */
+    action?: "create" | "link" | "dismiss";
     linkedEntityId?: string;
     confidence?: number;
+    /** Long-form body materialized as a linked document by the capture pipeline. */
+    content?: string;
+    /** Reuse an existing entity instead of creating one for this batch entry. */
+    existingEntityId?: string;
+    /** Role profiles to attach after the primary kind materializes. */
+    facets?: Array<{
+      profileSlug: string;
+      status?: string;
+      properties?: Record<string, unknown>;
+      contextTempId?: string;
+    }>;
   }>;
   relations?: CaptureRelation[];
+  /** Cross-cutting project lens to file the created entities into. */
+  projectId?: string | null;
+  /** Explicit reviewed placement override; unlike workspaceId it is never inferred. */
+  targetWorkspaceId?: string | null;
+  /** Preserve the original binary source with the primary derived entity. */
+  keepRaw?: boolean;
+  file?: {
+    /** Base64 payload; server caps it at about 5MB decoded. */
+    content: string;
+    mimeType: string;
+    filename?: string;
+  };
+  /** Client-stable retry namespace for this capture execution. */
+  idempotencyKey?: string;
+  /**
+   * Workspace routing (shared across all capture doors). Forward the AI's
+   * structure hints + the caller's mode so the door auto-routes; the backend
+   * decides the final workspace (auto/ask/locked, confidence + membership gated).
+   */
+  workspaceRouting?: "auto" | "ask" | "locked";
+  aiWorkspaceId?: string | null;
+  aiWorkspaceConfidence?: number | null;
+  aiWorkspaceReason?: string | null;
+}
+
+/** One planned entity in the proposal-first graph capture door. */
+export interface CaptureGraphEntity {
+  /** Batch-local ID used by relations and bindings. Must be unique per request. */
+  ref: string;
+  profileSlug: string;
+  title?: string;
+  /** Short descriptive body retained on the approved entity. */
+  description?: string;
+  /** Long-form body materialized through the canonical document path on approval. */
+  content?: string;
+  properties?: Record<string, unknown>;
+  /** Link this graph node to an existing entity rather than creating it. */
+  existingEntityId?: string;
+  /** Role profiles to attach after the primary kind materializes. */
+  facets?: Array<{
+    profileSlug: string;
+    status?: string;
+    properties?: Record<string, unknown>;
+    contextRef?: string;
+  }>;
+}
+
+export interface CaptureGraphRelation {
+  sourceRef: string;
+  targetRef: string;
+  type: string;
+}
+
+/** Optional post-approval external-channel binding for an entity in the graph. */
+export interface CaptureGraphBinding {
+  externalChannelId: string;
+  entityRef: string;
+  branchPurpose?: "client-comms" | "team";
+  title?: string;
+}
+
+/**
+ * Bounded original-input context retained in proposal data for review/retry.
+ * It is deliberately not a materialized source artifact or entity provenance.
+ */
+export interface CaptureGraphRawSource {
+  rawText?: string;
+  sourceUrl?: string;
+  label?: string;
+  mimeType?: string;
+  hash?: string;
+  idempotencyKey?: string;
+}
+
+/** Input for POST /capture/graph. The server always creates one composite proposal. */
+export interface SubmitCaptureGraphInput {
+  workspaceId?: string | null;
+  /** Existing project to file every newly created graph entity into on approval. */
+  projectId?: string | null;
+  /** Origin signal preserved through proposal approval and materialization. */
+  source?: HubWriteSource;
+  sourceMessageId?: string;
+  sessionId?: string;
+  rawSource?: CaptureGraphRawSource;
+  entities: CaptureGraphEntity[];
+  relations?: CaptureGraphRelation[];
+  bindings?: CaptureGraphBinding[];
+  summary?: string;
+}
+
+export interface SubmitCaptureGraphResult {
+  /** Composite graph writes are proposal-first, so this receipt begins pending. */
+  writeReceipt?: HubWriteReceipt;
+  proposalId?: string;
+  entityCount: number;
+  relationCount: number;
+  bindingCount: number;
+  reviewUrl?: string;
+  summary: string;
 }
 
 export interface CaptureExecuteResponse {
@@ -227,6 +494,37 @@ export interface CaptureExecuteResponse {
     targetTempId: string;
     relationType: string;
   }>;
+  /** Set when AUTO routing moved the capture to the AI-resolved workspace. */
+  movedToWorkspace?: string;
+  /** Set in ASK mode — a suggested switch for the surface to confirm. */
+  pendingWorkspaceSwitch?: {
+    suggestedWorkspaceId: string;
+    reason: string | null;
+    confidence: number | null;
+  };
+}
+
+// ─── Recall (ask) ──────────────────────────────────────────────────────────────
+
+/** One substrate's slice of an `ask` answer (semantic / procedural / episodic). */
+export interface AskAnswerBlock {
+  substrate: string;
+  items: Array<Record<string, unknown>>;
+  status: "ok" | "error";
+}
+
+/**
+ * The provenance-tagged result of `ask` — glass-box: it says which substrates
+ * were queried (`routedTo`), what the query's cue suggested (`intent`), and the
+ * per-substrate answer blocks. Shape mirrors the backend `AskResult`.
+ */
+export interface AskResponse {
+  query: string;
+  routedTo: string[];
+  intent: string;
+  answers?: AskAnswerBlock[];
+  verdict?: string;
+  [key: string]: unknown;
 }
 
 // ─── Relations & Graph ───────────────────────────────────────────────────────
@@ -257,22 +555,30 @@ export interface HubGraphResult {
 }
 
 /**
- * A single link returned by getConnections() — unified view across three sources:
+ * A single link returned by getConnections() across the local graph:
  *  - `"graph"` : an explicit row in the relations table
- *  - `"property"` : derived from another entity's `entity_id` property pointing here
- *  - `"thread"` : a chat thread created, updated, or referenced this entity
+ *  - `"property"` : an inbound or outbound `entity_id` property edge
+ *  - `"thread"` / `"context_channel"` : a channel that touched or is about this entity
+ *  - `"focus_session"` : a session anchored to this entity
  */
 export interface HubConnection {
   entityId: string;
   entity: HubEntity | null;
   label: string;
   direction: "outgoing" | "incoming" | "structural";
-  source: "graph" | "property" | "thread";
+  source: "graph" | "property" | "thread" | "context_channel" | "focus_session";
+  relationId?: string;
   relationType?: string;
   propertySlug?: string;
   propertyLabel?: string;
   channelId?: string;
   channelRelationshipType?: string;
+  channelTitle?: string | null;
+  channelWorkspaceId?: string | null;
+  focusSessionId?: string;
+  focusSessionGoal?: string;
+  focusSessionStatus?: string;
+  focusSessionWorkspaceId?: string | null;
   createdAt?: string | null;
 }
 
@@ -283,6 +589,8 @@ export interface HubConnectionsResult {
     graph: number;
     structural: number;
     threads: number;
+    contextChannels?: number;
+    focusSessions?: number;
   };
 }
 
@@ -298,6 +606,10 @@ export interface HubProfile {
   icon?: string;
   color?: string;
   properties?: HubPropertyDef[];
+  /** Primary entity kind or attachable role/facet. Defaults to kind on old pods. */
+  profileKind?: "kind" | "role";
+  /** Kinds this role can be attached to; null means the pod did not constrain it. */
+  applicableKinds?: string[] | null;
 }
 
 export interface HubPropertyDef {
@@ -325,6 +637,15 @@ export interface HubDiscoverProperty {
   type: string;
   options?: string[];
   required?: boolean;
+  /** Default the validator applies when this property is omitted. */
+  defaultValue?: unknown;
+  /** Exact validation constraints used by the property validator. */
+  constraints?: Record<string, unknown>;
+  /** Target kind for an entity_id property, when configured. */
+  targetProfileSlug?: string;
+  /** Base definitions are always visible; workspace definitions require this lens. */
+  schemaScope?: "base" | "workspace";
+  workspaceId?: string | null;
 }
 
 export interface HubDiscoverProfile {
@@ -333,8 +654,12 @@ export interface HubDiscoverProfile {
   scope: "pod" | "workspace";
   description?: string | null;
   icon?: string | null;
-  properties: HubDiscoverProperty[];
-  createCommand: string;
+  /** Omitted by the summary tier. */
+  properties?: HubDiscoverProperty[];
+  /** Omitted by the summary tier. */
+  createCommand?: string;
+  profileKind?: "kind" | "role";
+  applicableKinds?: string[] | null;
 }
 
 export interface HubDiscoverResult {
@@ -343,18 +668,88 @@ export interface HubDiscoverResult {
   hint: string;
 }
 
+/** Progressive-disclosure controls for GET /discover. */
+export interface HubDiscoverOptions {
+  /**
+   * Omit to read the base/pod schema only. Supplying a workspace resolves only
+   * that workspace's overlays; callers must never substitute a default here.
+   */
+  workspaceId?: string;
+  /** Return the digest tier without property schemas. */
+  summary?: boolean;
+  /** Limit full discovery to these profile slugs when the pod supports it. */
+  profileSlugs?: string[];
+}
+
+export type HubOrientScope = "workspaces" | "projects" | "profiles";
+export type HubOrientDetail = "light" | "full";
+
+export interface HubOrientProfile {
+  slug: string;
+  name: string;
+  profileKind: "kind" | "role";
+  applicableKinds?: string[] | null;
+  /** Placement for entities of this kind; distinct from profile visibility. */
+  entityScope?: "pod" | "workspace" | null;
+}
+
+export interface HubOrientWorkspace {
+  id: string;
+  name: string;
+  domain: string | null;
+  entityCount: number;
+  onboarding?: Record<string, unknown>;
+  description?: string | null;
+  profiles?: HubOrientProfile[];
+}
+
+export interface HubOrientProject {
+  id: string;
+  name: string;
+  description: string | null;
+  status: string | null;
+  workspaceId: string | null;
+  homeWorkspace: string | null;
+}
+
+/**
+ * Prompt-facing team roster for a workspace (no emails). Present when the
+ * pinned/sample workspace has human members. Treat as internal — not contacts.
+ */
+export interface HubOrientTeamRoster {
+  instructionBlock: string | null;
+  names: string[];
+  members: Array<{ displayName: string; personId?: string | null }>;
+}
+
+/** Canonical session bootstrap response shared by MCP, CLI, and REST surfaces. */
+export interface HubOrientResult {
+  me: { userId: string; scopes: string[] };
+  detail: HubOrientDetail;
+  projects: HubOrientProject[];
+  projectCount: number;
+  workspaces: HubOrientWorkspace[];
+  workspaceCount: number;
+  profiles: HubOrientProfile[];
+  note: string;
+  /** Internal team for the pinned/sample workspace — omitted when empty. */
+  teamRoster?: HubOrientTeamRoster;
+}
+
+export interface HubOrientOptions {
+  detail?: HubOrientDetail;
+  scope?: HubOrientScope[];
+  workspaceId?: string;
+  projectId?: string;
+}
+
 // ─── Threads & Channels ──────────────────────────────────────────────────────
 
 export interface HubThread {
   id: string;
   name?: string;
   type:
-    | "personal"
-    | "thread"
-    | "sub_thread"
-    | "feed"
-    | "external"
-    | "agent_collab";
+    "personal" | "thread" | "sub_thread" | "feed" | "external" | "agent_collab";
   workspaceId?: string;
   agentType?: string;
   contextObjectType?:
@@ -421,6 +816,9 @@ export interface HubView {
   profileSlug?: string;
   workspaceId?: string;
   config?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  profileId?: string | null;
+  userId?: string;
   createdAt: string;
   updatedAt: string;
 }
@@ -462,8 +860,43 @@ export interface HubUserContext {
 
 // ─── Governance ───────────────────────────────────────────────────────────────
 
+export type HubWriteSource =
+  | "intelligence"
+  | "agent"
+  | "openwebui-pipeline"
+  | "extension"
+  | "cli"
+  | "n8n"
+  | "raycast";
+
+/**
+ * Truthful outcome envelope shared by direct and proposal-first write doors.
+ * `partial` means independently-applied sub-operations failed; it never
+ * implies an atomic rollback.
+ */
+export interface HubWriteReceipt {
+  state: "pending" | "applied" | "partial";
+  proposalId?: string;
+  reviewUrl?: string;
+  entityId?: string;
+  proposedEntityId?: string;
+  profileSlug?: string;
+  effectiveWorkspaceId?: string | null;
+  projectId?: string;
+  source?: HubWriteSource;
+  facets?: Array<{
+    slug: string;
+    outcome: "attached" | "proposed" | "dropped" | "error" | string;
+    facetId?: string;
+    proposalId?: string;
+    error?: string;
+  }>;
+  warnings?: string[];
+}
+
 export interface HubGovernanceResult {
-  status: "approved" | "proposed" | "denied";
+  /** `created` is an inline, materialized write; `proposed` remains pending. */
+  status: "approved" | "created" | "proposed" | "denied";
   id?: string;
   proposalId?: string;
   reason?: string;
@@ -479,16 +912,18 @@ export interface HubGovernanceResult {
    */
   reasoning?: string;
   /**
-   * Pod-relative path for the review UI: `/proposals/{id}`.
+   * Pod-relative path into the app: `/open/{id}`.
    * Present on `proposed` responses.
    */
   reviewPath?: string;
   /**
-   * Absolute URL for the review UI (defaults to `studio.synap.live`,
-   * overridable via `SYNAP_APP_URL` on the pod). Surface this directly to
-   * the user so they can approve without digging through the app.
+   * Absolute clickable link into the app: `${PUBLIC_URL}/open/{id}`. The pod
+   * resolves the id's type server-side and bounces to the Electron app. Surface
+   * this directly to the user so they can approve without digging through the app.
    */
   reviewUrl?: string;
+  /** Additive receipt for write-aware clients. Legacy clients may keep using status/id. */
+  writeReceipt?: HubWriteReceipt;
 }
 
 // ─── Write input types ────────────────────────────────────────────────────────
@@ -512,13 +947,247 @@ export interface CreateRelationInput {
   userId?: string;
 }
 
+/** Attach an existing role-profile to a primary-kind entity. */
+export interface AttachFacetInput {
+  entityId: string;
+  profileSlug?: string;
+  profileId?: string;
+  workspaceId?: string | null;
+  contextEntityId?: string | null;
+  status?: string;
+  properties?: Record<string, unknown>;
+  reasoning?: string;
+}
+
+/**
+ * Result of `POST /entities/{entityId}/facets`.
+ *
+ * NOT a `HubGovernanceResult`: the facet door's inline-write status is
+ * `attached` (never `created`/`approved`), and it reports the new row as
+ * `facetId` rather than `id`. Source of truth for both branches:
+ * `entities.attachFacet` in `packages/api/src/routers/entities.ts`.
+ */
+export interface HubAttachFacetResult {
+  status: "attached" | "proposed";
+  message?: string;
+  /** Present on the inline `attached` branch. */
+  facetId?: string;
+  /** The materialized facet row on `attached`; `null` on `proposed`. */
+  facet?: Record<string, unknown> | null;
+  /** Present on the `proposed` branch. */
+  proposalId?: string;
+  proposalType?: string;
+  reviewUrl?: string;
+}
+
 export interface CreateViewInput {
   name: string;
   type: HubView["type"];
   profileSlug?: string;
   workspaceId: string;
   config?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
   userId?: string;
+  agentUserId?: string;
+  reasoning?: string;
+  sourceMessageId?: string;
+}
+
+export interface UpdateViewInput {
+  name?: string;
+  config?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+  workspaceId?: string;
+  userId?: string;
+  agentUserId?: string;
+  reasoning?: string;
+  sourceMessageId?: string;
+}
+
+export interface BentoWidgetInput {
+  /** Canonical Hub-router field naming the cell type. */
+  key: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  config?: Record<string, unknown>;
+  props?: Record<string, unknown>;
+}
+
+export interface ArrangeBentoViewInput {
+  workspaceId?: string;
+  userId?: string;
+  widgets: BentoWidgetInput[];
+  agentUserId?: string;
+  reasoning?: string;
+  sourceMessageId?: string;
+}
+
+export interface HubBentoArrangementResult {
+  status: string;
+  viewId?: string;
+  widgetCount?: number;
+  message?: string;
+  proposalId?: string;
+  reviewUrl?: string;
+}
+
+// ─── Capabilities & teaching substrate ─────────────────────────────────────
+
+export interface HubCapabilityVerb {
+  id?: string;
+  verbId?: string;
+  label?: string;
+  type?: "read" | "write";
+  enabled?: boolean;
+  granted?: boolean;
+  runnable?: boolean;
+  governance?: "auto" | "propose";
+  effectiveExecMode?: string;
+  govDefault?: string;
+  [key: string]: unknown;
+}
+
+/** Flat capability read-model for callers that need every granted verb. */
+export interface HubCapability {
+  id?: string;
+  name?: string;
+  key?: string;
+  kind?: string;
+  description?: string | null;
+  verbs?: HubCapabilityVerb[];
+  governance?: Record<string, unknown>;
+  approved?: boolean;
+  [key: string]: unknown;
+}
+
+export interface HubCapabilityCatalogConnection {
+  required: boolean;
+  kind: "provider" | "vault" | null;
+  provider?: string;
+  /** `unavailable`: this pod's Nango doesn't declare the provider — no connect action exists. */
+  state: "connected" | "missing" | "expired" | "unavailable";
+  account?: string;
+}
+
+export interface HubCapabilityCatalogCard {
+  id: string | null;
+  key: string;
+  name: string;
+  description?: string | null;
+  source: "installed" | "available";
+  status:
+    | "available"
+    | "needs_connection"
+    | "connected"
+    | "draft"
+    | "ready"
+    | "partial"
+    | "unavailable";
+  connection?: HubCapabilityCatalogConnection;
+  verbs: Array<{
+    verbId: string;
+    label: string;
+    type: "read" | "write";
+    enabled: boolean;
+    governance: "auto" | "propose";
+    runnable: boolean;
+  }>;
+  nextAction: {
+    kind: "add" | "connect" | "enable" | "run" | "none";
+    hint: string;
+  };
+}
+
+export interface HubCapabilityCatalogResult {
+  capabilities: HubCapabilityCatalogCard[];
+}
+
+/** One action the shared capability execute door can launch immediately. */
+export interface HubRunnableCapabilityAction {
+  skillId?: string;
+  verbId?: string;
+  label: string;
+  description?: string | null;
+  tool: string | null;
+  connection?: {
+    required: true;
+    state: "connected";
+    provider: string;
+  };
+  governance: "auto";
+  executionMode?: string;
+  parameters: Record<string, unknown>;
+}
+
+export interface HubRunnableCapabilityActionsResult {
+  actions: HubRunnableCapabilityAction[];
+}
+
+export interface ExecuteCapabilityInput {
+  verbId?: string;
+  skillId?: string;
+  parameters?: Record<string, unknown>;
+  workspaceId?: string;
+  connectionSelector?: {
+    connectionId?: string;
+    contextObjectId?: string;
+  };
+}
+
+export type ExecuteCapabilityResult =
+  | {
+      status: "run" | "dry-run";
+      skillId: string;
+      result?: unknown;
+      dryRun?: boolean;
+    }
+  | { proposed: true; proposalId: string; reviewUrl?: string };
+
+export interface HubAgentSkill {
+  id: string;
+  slug: string;
+  name: string;
+  description: string | null;
+  topics: string[];
+  body: string | null;
+  source: string | null;
+  author: string | null;
+  version: string | null;
+  tags: string[];
+  teachesTools: string[];
+  skillGroup: string | null;
+  alwaysOn: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ListAgentSkillsOptions {
+  topic?: string;
+  query?: string;
+  tag?: string;
+  /** Restrict to the seeded system/* teaching catalog. */
+  system?: boolean;
+  /** Include visible workspace-scoped skills for this selected lens. */
+  workspaceId?: string;
+  limit?: number;
+  offset?: number;
+}
+
+export interface HubAgentSkillsResult {
+  skills: HubAgentSkill[];
+  total: number;
+}
+
+export interface GetCapabilityBriefsInput {
+  tools: string[];
+  workspaceId?: string;
+  door?: "chat" | "automation";
+}
+
+export interface HubCapabilityBriefsResult {
+  briefs: Record<string, string>;
 }
 
 export interface ExecuteCommandInput {
@@ -585,12 +1254,7 @@ export interface UpdateAutomationInput {
 // ─── Subscriptions / Reactions (Pulse) ───────────────────────────────────────
 
 export type ReactionKind =
-  | "automation"
-  | "ai_feed"
-  | "ai_react"
-  | "notify"
-  | "webhook"
-  | "message_out";
+  "automation" | "ai_feed" | "ai_react" | "notify" | "webhook" | "message_out";
 
 export type ReactionLens = "all" | "internal" | "external";
 
@@ -609,11 +1273,7 @@ export interface HubReactionEvent {
 // ─── Notifications ────────────────────────────────────────────────────────────
 
 export type NotificationSourceType =
-  | "proposal"
-  | "connector"
-  | "agent"
-  | "system"
-  | "inbox_item";
+  "proposal" | "connector" | "agent" | "system" | "inbox_item";
 
 export interface CreateNotificationInput {
   userId: string;