@synap-core/cli 1.8.0 → 1.11.0

package/node_modules/@synap/hub-rest-client/dist/index.d.ts

@@ -24,6 +24,15 @@ 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;
 }
 interface HubDocument {
     id: string;
@@ -32,6 +41,9 @@ interface HubDocument {
     workspaceId: string | null;
     createdAt: string;
     updatedAt: string;
+    userId?: string;
+    type?: "text" | "markdown" | "code" | "html" | "pdf" | "docx";
+    language?: string | null;
 }
 interface HubChannel {
     id: string;
@@ -58,6 +70,8 @@ interface HubUser {
     email?: string;
     name?: string;
     scopes?: string[];
+    /** True only when the server authenticated this request as an agent credential. */
+    isAgent: boolean;
 }
 interface HubMemoryResult {
     id: string;
@@ -77,12 +91,32 @@ 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;
+    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;
+    }>;
 }
 interface UpdateEntityInput {
     title?: string;
@@ -98,6 +132,45 @@ 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. */
+interface UpdateDocumentInput {
+    content: string;
+    title?: string;
+    agentUserId?: string;
+    sourceMessageId?: string;
+    sessionId?: string;
+}
+interface HubDocumentChange {
+    op: "insert" | "delete" | "replace";
+    position?: number;
+    range?: [number, number];
+    text?: string;
+}
+/** Submit a governed edit proposal without replacing a document directly. */
+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. */
+interface HubDocumentProposalResult {
+    id?: string;
+    proposalId?: string;
+    status?: string;
+    reviewUrl?: string;
+    [key: string]: unknown;
 }
 interface StoreMemoryInput {
     fact: string;
@@ -124,12 +197,59 @@ interface PodStatus {
     healthy: boolean;
     version?: string;
 }
+/**
+ * A single tappable chip in a structured follow-up. Mirrors the IS `structure`
+ * output and the frontend capture-pipeline contract EXACTLY (do NOT narrow).
+ */
+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. */
+interface StructuredFollowUp {
+    question: string;
+    suggestions: FollowUpChip[];
+}
+/** One field of an AI-authored dynamic form. `type` is a free string (field kind). */
+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). */
+interface DynamicFormSpec {
+    title?: string;
+    note?: string;
+    fields: DynamicFormField[];
+}
 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;
@@ -149,10 +269,29 @@ interface CaptureRelation {
 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;
+        profileSlug: string;
         score: number;
     }>>;
 }
@@ -163,11 +302,116 @@ 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. */
+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;
+    }>;
+}
+interface CaptureGraphRelation {
+    sourceRef: string;
+    targetRef: string;
+    type: string;
+}
+/** Optional post-approval external-channel binding for an entity in the graph. */
+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.
+ */
+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. */
+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;
+}
+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;
 }
 interface CaptureExecuteResponse {
     created: Array<{
@@ -181,6 +425,33 @@ 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;
+    };
+}
+/** One substrate's slice of an `ask` answer (semantic / procedural / episodic). */
+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`.
+ */
+interface AskResponse {
+    query: string;
+    routedTo: string[];
+    intent: string;
+    answers?: AskAnswerBlock[];
+    verdict?: string;
+    [key: string]: unknown;
 }
 interface HubRelation {
     id: string;
@@ -204,22 +475,30 @@ interface HubGraphResult {
     edges: HubGraphEdge[];
 }
 /**
- * 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
  */
 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;
 }
 interface HubConnectionsResult {
@@ -229,6 +508,8 @@ interface HubConnectionsResult {
         graph: number;
         structural: number;
         threads: number;
+        contextChannels?: number;
+        focusSessions?: number;
     };
 }
 interface HubProfile {
@@ -241,6 +522,10 @@ 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;
 }
 interface HubPropertyDef {
     id: string;
@@ -256,6 +541,15 @@ 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;
 }
 interface HubDiscoverProfile {
     slug: string;
@@ -263,14 +557,91 @@ 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;
 }
 interface HubDiscoverResult {
     profiles: HubDiscoverProfile[];
     commands: Record<string, string>;
     hint: string;
 }
+/** Progressive-disclosure controls for GET /discover. */
+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[];
+}
+type HubOrientScope = "workspaces" | "projects" | "profiles";
+type HubOrientDetail = "light" | "full";
+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;
+}
+interface HubOrientWorkspace {
+    id: string;
+    name: string;
+    domain: string | null;
+    entityCount: number;
+    onboarding?: Record<string, unknown>;
+    description?: string | null;
+    profiles?: HubOrientProfile[];
+}
+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.
+ */
+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. */
+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;
+}
+interface HubOrientOptions {
+    detail?: HubOrientDetail;
+    scope?: HubOrientScope[];
+    workspaceId?: string;
+    projectId?: string;
+}
 interface HubThread {
     id: string;
     name?: string;
@@ -315,6 +686,9 @@ interface HubView {
     profileSlug?: string;
     workspaceId?: string;
     config?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    profileId?: string | null;
+    userId?: string;
     createdAt: string;
     updatedAt: string;
 }
@@ -341,8 +715,34 @@ interface HubUserContext {
     activeThreads: HubThread[];
     workspaceSummary?: Record<string, unknown>;
 }
+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.
+ */
+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[];
+}
 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;
@@ -358,16 +758,18 @@ 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;
 }
 interface CreateThreadInput {
     name?: string;
@@ -386,13 +788,220 @@ interface CreateRelationInput {
     workspaceId?: string;
     userId?: string;
 }
+/** Attach an existing role-profile to a primary-kind entity. */
+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`.
+ */
+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;
+}
 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;
+}
+interface UpdateViewInput {
+    name?: string;
+    config?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    workspaceId?: string;
+    userId?: string;
+    agentUserId?: string;
+    reasoning?: string;
+    sourceMessageId?: string;
+}
+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>;
+}
+interface ArrangeBentoViewInput {
+    workspaceId?: string;
     userId?: string;
+    widgets: BentoWidgetInput[];
+    agentUserId?: string;
+    reasoning?: string;
+    sourceMessageId?: string;
+}
+interface HubBentoArrangementResult {
+    status: string;
+    viewId?: string;
+    widgetCount?: number;
+    message?: string;
+    proposalId?: string;
+    reviewUrl?: string;
+}
+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. */
+interface HubCapability {
+    id?: string;
+    name?: string;
+    key?: string;
+    kind?: string;
+    description?: string | null;
+    verbs?: HubCapabilityVerb[];
+    governance?: Record<string, unknown>;
+    approved?: boolean;
+    [key: string]: unknown;
+}
+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;
+}
+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;
+    };
+}
+interface HubCapabilityCatalogResult {
+    capabilities: HubCapabilityCatalogCard[];
+}
+/** One action the shared capability execute door can launch immediately. */
+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>;
+}
+interface HubRunnableCapabilityActionsResult {
+    actions: HubRunnableCapabilityAction[];
+}
+interface ExecuteCapabilityInput {
+    verbId?: string;
+    skillId?: string;
+    parameters?: Record<string, unknown>;
+    workspaceId?: string;
+    connectionSelector?: {
+        connectionId?: string;
+        contextObjectId?: string;
+    };
+}
+type ExecuteCapabilityResult = {
+    status: "run" | "dry-run";
+    skillId: string;
+    result?: unknown;
+    dryRun?: boolean;
+} | {
+    proposed: true;
+    proposalId: string;
+    reviewUrl?: string;
+};
+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;
+}
+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;
+}
+interface HubAgentSkillsResult {
+    skills: HubAgentSkill[];
+    total: number;
+}
+interface GetCapabilityBriefsInput {
+    tools: string[];
+    workspaceId?: string;
+    door?: "chat" | "automation";
+}
+interface HubCapabilityBriefsResult {
+    briefs: Record<string, string>;
 }
 interface ExecuteCommandInput {
     slug: string;
@@ -506,20 +1115,60 @@ interface HubRestClientConfig {
     apiKey: string;
     /** Default workspace ID — used when not specified per call */
     workspaceId?: string;
-    /** Optional request timeout in ms (default: 30000) */
+    /** Optional request timeout in ms (default: 30000). Fallback when read/write timeouts are unset. */
     timeoutMs?: number;
+    /** Optional read (GET) timeout in ms (default: timeoutMs ?? 30000). */
+    readTimeoutMs?: number;
+    /** Optional write (non-GET) timeout in ms (default: timeoutMs ?? 30000). */
+    writeTimeoutMs?: number;
+    /**
+     * Max attempts for a request (default: 3). Retries ONLY on network failure or
+     * 5xx — never on 4xx, never on a caller-provided abort. Set to 1 to disable.
+     */
+    maxAttempts?: number;
 }
 declare class HubRestClient {
     private readonly base;
     private readonly headers;
     private readonly timeoutMs;
+    private readonly readTimeoutMs;
+    private readonly writeTimeoutMs;
+    private readonly maxAttempts;
     readonly workspaceId: string | undefined;
     /** Cached from GET /users/me — avoids repeated identity calls. */
     private resolvedUserId;
     constructor(config: HubRestClientConfig);
     /** User id for the current API key (Hub REST requires userId on several GETs). */
     private resolveUserId;
-    private request;
+    /**
+     * The ONE shared request loop. Per-method timeout (GET = read, else write, or a
+     * caller override) + up to `maxAttempts` with exponential backoff. Retries ONLY
+     * on a network failure or 5xx; NEVER on a 4xx or a caller abort. Returns the raw
+     * `Response` for any non-5xx (ok OR 4xx) — the typed entry points below decide
+     * how to interpret it. This is the single source of retry/timeout truth, shared
+     * by the CLI and the IS's `ISHubClient` (which reuses the protected entry points
+     * rather than re-implementing fetch).
+     */
+    private fetchWithRetry;
+    /** Build a HubApiError from a non-ok Response (reads the JSON error body). */
+    private toHubError;
+    /** Parse a 2xx body, tolerating an empty/204 response (returns undefined). */
+    private parseBody;
+    /**
+     * Typed JSON request — throws `HubApiError` on any non-2xx. Protected so the IS
+     * subclass reuses it. Tolerates an empty/204 body (returns `undefined`).
+     */
+    protected request<T>(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+    /**
+     * Like `request<T>` but returns `null` on 404/403 (the "absent/forbidden →
+     * empty" contract several IS reads use) instead of throwing.
+     */
+    protected requestOrNull<T>(method: string, path: string, body?: unknown, signal?: AbortSignal): Promise<T | null>;
+    /**
+     * The raw `Response` (same retry/timeout infra), for the few callers that read
+     * `.text()`, branch on status themselves, or need a per-call timeout override.
+     */
+    protected requestRaw(method: string, path: string, body?: unknown, signal?: AbortSignal, timeoutMsOverride?: number): Promise<Response>;
     getMe(): Promise<HubUser>;
     getWorkspaces(): Promise<HubWorkspace[]>;
     provisionAgentWorkspace(input: {
@@ -585,6 +1234,12 @@ declare class HubRestClient {
      * Goes through governance — may return "proposed".
      */
     createRelation(input: CreateRelationInput): Promise<HubGovernanceResult>;
+    /**
+     * Attach a role-profile through the canonical governed facet door. A result
+     * may be `proposed`; callers must surface its review information instead of
+     * claiming the role was applied.
+     */
+    attachFacet(input: AttachFacetInput): Promise<HubAttachFacetResult>;
     /**
      * Delete a relation by ID (get from getRelations()).
      */
@@ -603,10 +1258,10 @@ declare class HubRestClient {
         workspaceId?: string;
     }): Promise<HubGraphResult>;
     /**
-     * Unified view of everything connected to an entity. Merges three sources:
+     * Unified view of everything connected to an entity across the local graph:
      *   1. Graph relations — explicit rows in the relations table (both directions)
-     *   2. Structural links — entities whose `entity_id` properties point to this entity
-     *   3. Thread connections — chat threads that touched this entity
+     *   2. Structural links — inbound and outbound `entity_id` property edges
+     *   3. Channel and focus-session connections around this entity
      *
      * Prefer this over `getRelations()` / `traverseGraph()` when you want the complete
      * picture — those only see the relations table and miss property-based links that
@@ -622,12 +1277,20 @@ declare class HubRestClient {
         workspaceId?: string;
         limit?: number;
     }): Promise<HubConnectionsResult>;
+    /**
+     * Canonical session bootstrap shared by the MCP, CLI, and external surfaces.
+     * It is deliberately a lens map, not a profile/schema dump; use discover()
+     * only for the selected profiles needed by the next action.
+     */
+    orient(options?: HubOrientOptions): Promise<HubOrientResult>;
     /**
      * List all entity profile types in the workspace.
      * Always call before creating entities to discover what types are available.
      * Returns system profiles (always present) + custom workspace profiles.
      */
-    listProfiles(workspaceId: string): Promise<HubProfile[]>;
+    listProfiles(workspaceId: string, options?: {
+        detail?: "full";
+    }): Promise<HubProfile[]>;
     /**
      * List property definitions for a workspace, optionally filtered by profile.
      */
@@ -641,7 +1304,7 @@ declare class HubRestClient {
      * schemas (including custom workspace profiles) and the canonical CLI
      * command map. Replaces static skill file profile descriptions.
      */
-    discover(workspaceId?: string): Promise<HubDiscoverResult>;
+    discover(options?: string | HubDiscoverOptions): Promise<HubDiscoverResult>;
     /**
      * List threads (channels) accessible to a user.
      */
@@ -714,6 +1377,11 @@ declare class HubRestClient {
     listProposals(options?: {
         status?: "pending" | "approved" | "rejected";
         workspaceId?: string;
+        /**
+         * "workspace" (default) — applies the client workspaceId filter.
+         * "all" — omits workspaceId so results span every workspace the user can see.
+         */
+        scope?: "workspace" | "all";
         limit?: number;
     }): Promise<HubProposal[]>;
     /**
@@ -734,6 +1402,10 @@ declare class HubRestClient {
      * Create a new view. Goes through governance.
      */
     createView(input: CreateViewInput): Promise<HubGovernanceResult>;
+    /** Update a view through the existing governed Hub route. */
+    updateView(viewId: string, input: UpdateViewInput): Promise<HubView | HubGovernanceResult>;
+    /** Replace a bento view's widget arrangement through the existing Hub route. */
+    arrangeBentoView(viewId: string, input: ArrangeBentoViewInput): Promise<HubBentoArrangementResult>;
     /**
      * Get a document by ID with full markdown content.
      */
@@ -745,6 +1417,36 @@ declare class HubRestClient {
     createDocument(input: CreateDocumentInput & {
         workspaceId?: string;
     }): Promise<HubGovernanceResult>;
+    /** Propose a full document-content replacement through the governed Hub route. */
+    updateDocument(documentId: string, input: UpdateDocumentInput): Promise<HubDocumentProposalResult>;
+    /** Submit a structured, reviewable document-edit proposal. */
+    createDocumentProposal(input: CreateDocumentProposalInput): Promise<HubDocumentProposalResult>;
+    /** Flat capability read-model. Prefer getCapabilityCatalog() for presentation. */
+    listCapabilities(options?: {
+        workspaceId?: string;
+    }): Promise<HubCapability[]>;
+    /** Status-computed, pack-grouped capability catalog for every external surface. */
+    getCapabilityCatalog(options?: {
+        workspaceId?: string;
+        extraKey?: string;
+    }): Promise<HubCapabilityCatalogResult>;
+    /** List only approved, connected actions that this client can execute now. */
+    listRunnableCapabilityActions(options?: {
+        workspaceId?: string;
+        query?: string;
+        kind?: string;
+        limit?: number;
+    }): Promise<HubRunnableCapabilityActionsResult>;
+    /** Run one registered capability through the shared governance gate. */
+    executeCapability(input: ExecuteCapabilityInput): Promise<ExecuteCapabilityResult>;
+    /** List the compact system teaching catalog, or search the available skill index. */
+    listAgentSkills(options?: ListAgentSkillsOptions): Promise<HubAgentSkillsResult>;
+    /** Load one skill body only when it is relevant to the agent's next action. */
+    getAgentSkillBySlug(slug: string, options?: {
+        workspaceId?: string;
+    }): Promise<HubAgentSkill>;
+    /** Compose just-in-time teaching and governance briefs for selected tools. */
+    getCapabilityBriefs(input: GetCapabilityBriefsInput): Promise<HubCapabilityBriefsResult>;
     /**
      * List available commands (automation shortcuts) in the workspace.
      */
@@ -784,6 +1486,34 @@ declare class HubRestClient {
     captureExecute(input: CaptureExecuteInput & {
         workspaceId?: string;
     }): Promise<CaptureExecuteResponse>;
+    /**
+     * Submit a designed entity graph as ONE reviewable composite proposal.
+     *
+     * This is intentionally distinct from captureExecute(): execute materializes
+     * a prior structure result immediately, while this door keeps an autonomous
+     * graph plan reviewable and applies entities, relations, and bindings together
+     * only after approval.
+     */
+    submitCaptureGraph(input: SubmitCaptureGraphInput): Promise<SubmitCaptureGraphResult>;
+    /**
+     * `ask` — the unified recall verb. Routes a natural-language question across
+     * all knowledge substrates (semantic entities, procedural runbooks, episodic
+     * facts) server-side and returns ONE provenance-tagged answer. The canonical
+     * recall door — prefer it over the fragmented searchEntities / recallMemory.
+     * The server builds the profile catalog from the caller's workspace; the
+     * client only sends the query (+ optional scope).
+     */
+    ask(input: {
+        query: string;
+        workspaceId?: string;
+        limit?: number;
+        /**
+         * Return just the glass-box understanding + routing (no retrieval) — for a
+         * caller that routes a query before fetching results (e.g. a palette
+         * completing a type word). `answers` comes back empty.
+         */
+        parseOnly?: boolean;
+    }): Promise<AskResponse>;
     /**
      * List automations for the current user, optionally filtered by workspace and status.
      */
@@ -885,8 +1615,18 @@ declare class HubApiError extends Error {
  * These functions are the canonical implementations shared between
  * the Synap CLI and the Raycast extension. They use the native fetch API
  * and have zero Node.js-specific dependencies.
+ *
+ * ⚠️ `assertValidPodUrl` below is a DUPLICATE of the guard in
+ * `@synap-core/auth-bootstrap` (`src/url.ts`). It is copied, not imported,
+ * because this package is deliberately zero-dependency. The two copies must
+ * be kept in sync — change one, change the other.
  */
 
+/** Shared per-request knobs for the credential-bearing bootstrap calls. */
+interface BootstrapRequestOptions {
+    /** Allow `http://` pod URLs (localhost / local-mode dev only). */
+    allowHttp?: boolean;
+}
 /**
  * Check whether a Synap pod is healthy.
  * Hits `GET {podUrl}/health` with a 5s timeout.
@@ -902,6 +1642,6 @@ declare function checkPodHealth(podUrl: string): Promise<PodStatus>;
  *
  * Endpoint: `POST {podUrl}/api/hub/setup/agent`
  */
-declare function setupAgent(podUrl: string, provisioningToken: string, agentType?: string): Promise<AgentSetupResult>;
+declare function setupAgent(podUrl: string, provisioningToken: string, agentType: string, opts?: BootstrapRequestOptions): Promise<AgentSetupResult>;
 
-export { type AgentSetupResult, type CaptureExecuteInput, type CaptureExecuteResponse, type CaptureProposal, type CaptureRelation, type CaptureStructureResponse, type CreateDocumentInput, type CreateEntityInput, type CreateRelationInput, type CreateThreadInput, type CreateViewInput, type ExecuteCommandInput, type HubAgentUser, HubApiError, type HubChannel, type HubCommand, type HubConnection, type HubConnectionsResult, type HubDiscoverProfile, type HubDiscoverProperty, type HubDiscoverResult, type HubDocument, type HubEntity, type HubGovernanceResult, type HubGraphEdge, type HubGraphNode, type HubGraphResult, type HubListResponse, type HubMemoryResult, type HubMessage, type HubProfile, type HubPropertyDef, type HubProposal, type HubRelation, HubRestClient, type HubRestClientConfig, type HubSearchResult, type HubSingleResponse, type HubThread, type HubThreadContext, type HubUser, type HubUserContext, type HubView, type HubWorkspace, type HubWorkspacesListResponse, type PodStatus, type SendToChannelInput, type StoreMemoryInput, type UpdateEntityInput, checkPodHealth, setupAgent };
+export { type AgentSetupResult, type ArrangeBentoViewInput, type AskAnswerBlock, type AskResponse, type BentoWidgetInput, type CaptureExecuteInput, type CaptureExecuteResponse, type CaptureGraphBinding, type CaptureGraphEntity, type CaptureGraphRawSource, type CaptureGraphRelation, type CaptureProposal, type CaptureRelation, type CaptureStructureResponse, type CreateDocumentInput, type CreateDocumentProposalInput, type CreateEntityInput, type CreateRelationInput, type CreateThreadInput, type CreateViewInput, type ExecuteCapabilityResult, type ExecuteCommandInput, type GetCapabilityBriefsInput, type HubAgentSkill, type HubAgentSkillsResult, type HubAgentUser, HubApiError, type HubAttachFacetResult, type HubBentoArrangementResult, type HubCapability, type HubCapabilityBriefsResult, type HubCapabilityCatalogCard, type HubCapabilityCatalogConnection, type HubCapabilityCatalogResult, type HubCapabilityVerb, type HubChannel, type HubCommand, type HubConnection, type HubConnectionsResult, type HubDiscoverOptions, type HubDiscoverProfile, type HubDiscoverProperty, type HubDiscoverResult, type HubDocument, type HubDocumentChange, type HubDocumentProposalResult, type HubEntity, type HubGovernanceResult, type HubGraphEdge, type HubGraphNode, type HubGraphResult, type HubListResponse, type HubMemoryResult, type HubMessage, type HubOrientDetail, type HubOrientOptions, type HubOrientProfile, type HubOrientProject, type HubOrientResult, type HubOrientScope, type HubOrientTeamRoster, type HubOrientWorkspace, type HubProfile, type HubPropertyDef, type HubProposal, type HubRelation, HubRestClient, type HubRestClientConfig, type HubRunnableCapabilityAction, type HubRunnableCapabilityActionsResult, type HubSearchResult, type HubSingleResponse, type HubThread, type HubThreadContext, type HubUser, type HubUserContext, type HubView, type HubWorkspace, type HubWorkspacesListResponse, type HubWriteReceipt, type HubWriteSource, type ListAgentSkillsOptions, type PodStatus, type SendToChannelInput, type StoreMemoryInput, type SubmitCaptureGraphInput, type SubmitCaptureGraphResult, type UpdateDocumentInput, type UpdateEntityInput, type UpdateViewInput, checkPodHealth, setupAgent };