@octostar/platform-types 0.5.37 → 1.0.0

package/dist/platform-types.d.ts

@@ -1,8 +1,7 @@
 import type { ButtonProps } from 'antd';
-import { ItemType } from 'rc-menu/lib/interface';
+import type { ItemType } from 'antd/es/menu/interface';
 import { ModalProps } from 'antd';
 import { Properties } from 'csstype';
-import { QueryDslQueryContainer } from '@elastic/elasticsearch/lib/api/types';
 import type { TabNode } from 'flexlayout-react';
 
 /**
@@ -14,7 +13,6 @@ export declare interface ActionContext {
     graph?: GraphSpec & any;
     item?: WorkspaceItem;
     items?: WorkspaceItem[];
-    workspace?: Workspace;
     dataTransfer?: IDataTransfer;
     eventTopicPrefix?: string;
     selectedItems?: WorkspaceItem[];
@@ -68,6 +66,67 @@ export declare type AddCommentParams = {
  */
 export declare type AddListener<T> = (callback: Callback<T>) => Promise<Unsubscribe>;
 
+declare type AddToReportBaseInput = {
+    /** Optional: preselect a target report when the flow opens */
+    initialTargetUid?: string;
+    /** Optional: require a live in-memory insert target instead of silently appending to disk */
+    requireLiveInsert?: boolean;
+};
+
+/**
+ * @beta
+ * Arbitrary-content "Add to report" payload. The host app shows the same target-picker UI, but
+ * appends the supplied TipTap JSON blocks directly instead of building them from an entity.
+ */
+export declare type AddToReportBlocksInput = AddToReportBaseInput & {
+    mode: 'blocks';
+    /** Arbitrary TipTap JSON blocks to append directly into the target report */
+    blocks: ReportTiptapNode[];
+    /** Optional: short label shown in the flow and suggested report name */
+    sourceLabel?: string;
+    /** Optional: explanatory text shown in the flow instead of the entity checkbox section */
+    sourceDescription?: string;
+};
+
+/**
+ * @beta
+ * Checkbox payload for "Add to report" content.
+ */
+export declare type AddToReportContentSelection = {
+    coreData: boolean;
+    mainPicture: boolean;
+    allPictures: boolean;
+    relatedLinks: boolean;
+};
+
+/**
+ * @beta
+ * Entity-driven "Add to report" payload. The host app will build report blocks from the entity plus
+ * the usual checkbox selection.
+ */
+export declare type AddToReportEntityInput = AddToReportBaseInput & {
+    mode?: 'entity';
+    /** Entity to snapshot into the report */
+    sourceEntity: Entity;
+    /** Optional: override default checkbox state */
+    initialSelection?: Partial<AddToReportContentSelection>;
+};
+
+/**
+ * @beta
+ * Input for {@link ReportApi.presentAddToReportFlow}.
+ */
+export declare type AddToReportInput = AddToReportEntityInput | AddToReportBlocksInput;
+
+/**
+ * @beta
+ * Result after a successful append.
+ */
+export declare type AddToReportResult = {
+    targetOdocUid: string;
+    targetDisplayName: string;
+};
+
 /**
  * The interface for the AI client.
  */
@@ -147,11 +206,6 @@ export declare type AppRegistry = {
      * Registers an action.
      */
     registerAction: (action: DesktopActionMenuItem) => void;
-    /**
-     * @beta
-     * Registers a styler.
-     */
-    registerStyler: (styler: StylerConfig) => () => void;
 };
 
 /**
@@ -191,51 +245,6 @@ export declare type AttachmentResponseType = 'text' | 'blob' | 'arrayBuffer' | '
  */
 export declare type AttachmentType = string | Blob | ArrayBuffer | Record<string, any>;
 
-/**
- * @beta
- * Type representing a set of behaviors with various methods for entity and graph operations.
- */
-export declare type Behaviour = {
-    /**
-     * Gets the count of entities.
-     * @returns A promise that resolves to the number of entities.
-     */
-    getEntitiesCount?: () => Promise<number>;
-    /**
-     * Gets a list of entities.
-     * @param limit - Optional limit on the number of entities to retrieve.
-     * @returns A promise that resolves to an array of entities.
-     */
-    getEntities?: (limit?: number) => Promise<Entity[]>;
-    /**
-     * Gets a single entity.
-     * @returns A promise that resolves to an entity.
-     */
-    getEntity?: () => Promise<Entity>;
-    /**
-     * Gets the content associated with the behavior.
-     * @returns A promise that resolves to the content.
-     */
-    getContent?: () => Promise<any>;
-    /**
-     * Gets the graph specification.
-     * @returns A promise that resolves to the graph specification or undefined if not available.
-     */
-    getGraph?: () => Promise<GraphSpec | undefined>;
-    /**
-     * Opens the associated entity or content with the default action.
-     * @returns A promise that resolves when the operation is complete.
-     */
-    open?: () => Promise<void>;
-    /**
-     * Edits the associated entity or content with the default edit action.
-     * @returns A promise that resolves when the operation is complete.
-     */
-    edit?: () => Promise<void>;
-};
-
-declare type BigNumber = any;
-
 /**
  * @beta
  * Represents a filter clause with binary operations in a query object.
@@ -253,6 +262,30 @@ export declare interface BinaryObjectFilterClause {
  */
 export declare type BinaryOperator = '==' | '!=' | '>' | '>=' | '<' | '<=' | 'IN' | 'NOT IN' | 'regex' | 'LIKE' | 'ILIKE';
 
+export declare interface BrowseEntry {
+    id: string;
+    name: string;
+    kind: 'file' | 'directory';
+    size?: number | null;
+    modified_at?: string | null;
+    content_type_hint?: string | null;
+}
+
+export declare type BrowseKind = 'file' | 'directory' | 'any';
+
+export declare interface BrowseRequest {
+    path?: string;
+    kind?: BrowseKind;
+    limit?: number;
+}
+
+export declare interface BrowseResponse {
+    path: string;
+    entries: BrowseEntry[];
+    truncated: boolean;
+    next_cursor?: string | null;
+}
+
 /**
  * @beta
  * Type representing a callback function.
@@ -261,34 +294,6 @@ export declare type BinaryOperator = '==' | '!=' | '>' | '>=' | '<' | '<=' | 'IN
  */
 export declare type Callback<T> = (t: T) => void;
 
-export declare interface ChartDataResponseResult {
-    all_columns?: string[];
-    annotation_data: Record<string, any> | null;
-    cache_key: string | null;
-    cache_timeout: number | null;
-    cached_dttm: string | null;
-    /**
-     * Array of data records as dictionary
-     */
-    data: Record<any, any>[];
-    /**
-     * Name of each column, for retaining the order of the output columns.
-     */
-    colnames: string[];
-    /**
-     * Generic data types, based on the final output pandas dataframe.
-     */
-    coltypes: GenericDataType[];
-    error: string | null;
-    is_cached: boolean;
-    query: string;
-    rowcount: number;
-    stacktrace: string | null;
-    status: 'stopped' | 'failed' | 'pending' | 'running' | 'scheduled' | 'success' | 'timed_out';
-    from_dttm: number | null;
-    to_dttm: number | null;
-}
-
 export declare type ChatApiResponse = {
     response: {
         content: string;
@@ -353,6 +358,7 @@ export declare interface ChatMessage {
 export declare type ChatModel = {
     model_name: string;
     description: string;
+    is_default?: boolean;
 };
 
 /**
@@ -440,9 +446,9 @@ export declare interface Concept {
      */
     labelKeys: string[];
     /**
-     * All label keys for the concept.
+     * The display label from the ontology schema.
      */
-    allLabelKeys: string[];
+    label?: OntologyLabel;
 }
 
 /**
@@ -457,9 +463,7 @@ export declare type ConceptFilter = {
     /**
      * The filters to apply to the records of the concept.
      */
-    filters: (QueryObjectFilterClause & {
-        formattedLabel?: string;
-    })[];
+    filters: QueryObjectFilterClause[];
     /**
      * Indicates if the item only should be returned.
      * If true, only the item itself will be returned.
@@ -499,7 +503,7 @@ export declare type ConnectedEntity = Entity & {
  * @beta
  * Type representing the groups for a context menu.
  */
-export declare type ContextMenuGroup = 'add' | 'addto' | 'copy' | 'edit' | 'transform' | 'general' | 'open' | 'danger' | 'tags' | 'relations' | 'search' | 'actions' | 'file' | 'settings';
+export declare type ContextMenuGroup = 'add' | 'addto' | 'report' | 'copy' | 'edit' | 'transform' | 'general' | 'open' | 'danger' | 'tags' | 'relations' | 'search' | 'actions' | 'file' | 'settings';
 
 /**
  * @beta
@@ -519,6 +523,7 @@ export declare type ContextMenuOptions = {
     labels?: ContextMenuLabels;
     extras?: ItemType[];
     excludedKeys?: string[];
+    extraActionItems?: DesktopActionMenuItem[];
 };
 
 /**
@@ -582,6 +587,11 @@ export declare type CreateEntityFormProps = {
      * Concept related to the form.
      */
     concept?: string;
+    /**
+     * Root concept for the concept selector tree. When set, the concept selector
+     * only shows this concept and its subtypes. Defaults to 'os_workspace_item'.
+     */
+    conceptTreeRoot?: string;
 };
 
 export declare type CreateLinkChartFn = (params: CreateLinkChartParams) => Promise<WorkspaceItem | undefined>;
@@ -591,7 +601,6 @@ export declare type CreateLinkChartParams = {
     name: string;
     nodes?: Entity[];
     edges?: EdgeSpec[];
-    draft?: boolean;
     os_workspace?: string;
 };
 
@@ -626,6 +635,10 @@ export declare type CreateRelationsDialogProps = {
     defaultTargetConcept?: string;
 };
 
+export declare type CredentialMode = 'shared' | 'per_user' | 'either';
+
+export declare type CredType = 'password';
+
 /**
  * @beta
  * Type representing a custom event listener.
@@ -637,10 +650,19 @@ export declare type CustomEventListener<L> = (payload: L) => void;
 /**
  * @beta
  * Type representing a custom template, extending TemplateMetadata.
+ *
+ * `os_entity_uid` and `os_workspace` are optional here so an in-memory
+ * template built via `newCustomTemplate()` can still flow through
+ * `RenderableTemplate`-typed code paths. `SavedTemplate` narrows both
+ * to required strings.
  */
 export declare type CustomTemplate = TemplateMetadata & {
     /** The template content. */
     template: string;
+    /** Set once the template is persisted as a workspace item. */
+    os_entity_uid?: string;
+    /** Set once the template is persisted as a workspace item. */
+    os_workspace?: string;
 };
 
 /**
@@ -707,13 +729,50 @@ export declare type DataContextType = {
     removeFromGraph: (graph: GraphDataSpec) => void;
 };
 
-export declare type DataMask = {
-    extraFormData?: Record<string, any>;
-    filterState?: FilterState;
-    ownState?: Record<string, any>;
+export declare type DefaultLiveContextData = Record<string, any>;
+
+/**
+ * @beta
+ * A code-resident default template. Carries the same metadata as a
+ * `SavedTemplate` so it can flow through the existing template lookup
+ * pipeline, but renders via a real React component rather than a
+ * `react-live` string.
+ *
+ * Defaults always have `os_workspace === ''` — that's the marker
+ * `isDefaultTemplate` looks for and disambiguates them from workspace
+ * templates whose `os_workspace` is always a real UUID.
+ */
+export declare type DefaultTemplate = TemplateMetadata & {
+    /** Synthetic identifier, e.g. `default-template-PersonInfo`. */
+    os_entity_uid: string;
+    /** Empty string marks this as a code-resident default. */
+    os_workspace: '';
+    /** The React component that renders this template. */
+    component: (props: DefaultTemplateProps) => ReactNode;
+};
+
+/**
+ * @beta
+ * Props passed to a code-resident default template's React component.
+ */
+export declare type DefaultTemplateProps = {
+    /** The record this template is rendering for, if any. */
+    record?: WorkspaceItem;
+    /** The same context object passed to react-live templates. */
+    context?: any;
+    /** Optional extra scope variables forwarded from `<OsTemplate extraScope>`. */
+    extraScope?: Record<string, unknown>;
 };
 
-export declare type DefaultLiveContextData = Record<string, any>;
+/**
+ * Represents a deletion notification payload (from the firehose).
+ * Identity fields like `os_entity_uid` and `entity_label` may be empty.
+ * @beta
+ */
+export declare type DeletedEntity = Entity & {
+    '#deleted': true;
+    '#updated': number;
+};
 
 export declare interface DeleteResponse {
     tracking_id?: string;
@@ -771,9 +830,9 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
     listAllWorkspaces: (permissions?: WorkspacePermissionValue) => Promise<WorkspaceItem[]>;
     /**
      * This might not be enough, add a listener to {@link WorkspaceChangeEmitter.onOpenWorkspacesChanged} to keep getting updated.
-     * In react components, prefer useDesktopWorkspaces hook.
+     * In react components, prefer the `useOpenWorkspaces` hook for ids and `getEntity` for per-workspace data.
      */
-    getOpenWorkspaces: () => Promise<Workspace[]>;
+    getOpenWorkspaces: () => Promise<WorkspaceItem[]>;
     /**
      * Gets the OntologyAPI.
      * @returns a promise that resolves to the current ontology
@@ -791,22 +850,12 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * @returns A promise that resolves to the attachment of type T.
      */
     getAttachment: <T extends AttachmentType>(entity: Entity, options?: GetAttachmentOptions<T>) => Promise<T>;
-    /**
-     * @beta
-     * Gets options for stylers.
-     */
-    getStylerOptions: () => Promise<StylerOption[]>;
-    /**
-     * @beta
-     * Gets a styler by name and context.
-     */
-    getStyler: (name: string, context: DesktopStylerContext) => Promise<Styler>;
     /**
      * Gets a workspace by identifier.
      */
     getWorkspace: (ws: WorkspaceIdentifier, options?: {
         shouldRetry?: boolean;
-    }) => Promise<Workspace | undefined>;
+    }) => Promise<WorkspaceItem | undefined>;
     /**
      * Gets items in a workspace by name.
      */
@@ -860,15 +909,36 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
     /**
      * Gets templates by layout or filter
      */
-    getTemplates: (layout?: string | ((template: SavedTemplate) => boolean)) => Promise<SavedTemplate[]>;
+    getTemplates: (layout?: string | ((template: SavedTemplate) => boolean)) => Promise<RenderableTemplate[]>;
     /**
      * Gets a template by name or entity or filter with an optional default template.
      */
-    getTemplate: (name: string | Entity | ((template: SavedTemplate) => boolean), defaultTemplate?: string) => Promise<SavedTemplate>;
+    getTemplate: (name: string | Entity | ((template: SavedTemplate) => boolean), defaultTemplate?: string) => Promise<RenderableTemplate>;
     /**
      * Gets the named app if it is on the desktop and in a running state.
+     *
+     * MIGRATION (app authors): the app's iframe URL is no longer on
+     * `os_item_content.app_url` — that field is gone. The resolved URL is now
+     * exposed on the runtime-only `#appUrl` field of the returned item (see
+     * {@link RuntimeAppUrlWorkspaceItem}). It is hydrated from the K8s apps API
+     * and is NOT persisted, so don't read it off a stored/restored item.
+     */
+    getApp: (name: string) => Promise<RuntimeAppUrlWorkspaceItem | undefined>;
+    /**
+     * Resolve app folders by name within the given workspaces. Match is on
+     * `os_item_name`, case-insensitive. Use this instead of hardcoding app
+     * `entity_id`s on a home page or launcher — those ids are regenerated per
+     * environment, whereas the app name is stable across them.
+     *
+     * Returns one {@link App} per requested name that exists, in the order the
+     * names were given (unknown names are skipped). Each App carries its `folder`
+     * (open it via `desktop.open(app.folder)`) and, when found, its
+     * `manifest_entity` for loading the app's icon/description.
+     *
+     * @param names - App folder names to look up.
+     * @param workspace_ids - Workspaces to search; defaults to the currently open workspaces.
      */
-    getApp: (name: string) => Promise<WorkspaceItem | undefined>;
+    getApps: (names: string[], workspace_ids?: string[]) => Promise<App[]>;
     /**
      * Gets the context of an app by its octostar channel id.
      * @param octostarChannelId the id assigned to the app by the octostar platform
@@ -876,12 +946,10 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      */
     getAppContext: (octostarChannelId: string) => Promise<Record<string, any>>;
     /**
-     * Query workspace items by content type directly from the database.
-     * This ensures all items are retrieved, not just those loaded in memory.
+     * Workspace items matching `os_item_content_type`.
+     * Hydrated-in-memory types use Redux; others are loaded via an ontology query on the filesystem concept.
      *
-     * @param os_item_content_type - The content type to filter by
-     * @param workspace_ids - Optional list of workspace IDs to filter by. If not provided, searches across all open workspaces
-     * @returns Promise resolving to array of workspace items matching the content type
+     * @param workspace_ids - Optional workspace filter; if omitted, uses currently open workspaces for ontology fallback.
      */
     getItemsByContentType: (os_item_content_type: string, workspace_ids?: string[]) => Promise<WorkspaceItem[]>;
     /**
@@ -922,6 +990,11 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Fetches an entity from the index, or from the ontology if not found in the index.
      */
     fetchEntity: (entity: EntityBase, options?: FetchEntityOptions) => Promise<Entity>;
+    /**
+     * Resolves a fragment to the root file its `source_entity_uid` names.
+     * Returns null if the source cannot be found.
+     */
+    fetchFragmentSource: (fragment: Entity) => Promise<(Entity & Partial<WorkspaceItem>) | null>;
     /**
      * Extracts entities from some text which may be json or a list of urls.
      */
@@ -930,14 +1003,87 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Gets a file tree for a workspace or folder with optional file tree options.
      */
     getFilesTree: (workspace_or_folder: WorkspaceItem, options?: FileTreeOptions) => Promise<WorkspaceItem[]>;
+    /**
+     * Query workspace filesystem entities by content type / name patterns (ontology SQL).
+     */
+    queryFilesystemItemsInWorkspaces: (params: QueryFilesystemItemsParams) => Promise<WorkspaceItem[]>;
     /**
      * Show the search modal and return the selected results.
      */
     getSearchResults: (params: undefined | string | SearchProps, enableSelection?: boolean) => Promise<Entity[] | undefined>;
+    /**
+     * Show the search modal in query-return mode.
+     * The user refines the search and clicks "Return current search (N) results".
+     * Resolves with the underlying Elasticsearch query and total result count.
+     */
+    getSearchQuery: (params: undefined | string | SearchProps) => Promise<SearchQueryResult | undefined>;
     /**
      * Opens records with default action or as specified in the optional desktop action options.
      */
     open: (records: Entity | Entity[], options?: DesktopActionOptions) => Promise<void>;
+    /**
+     * Opens a fresh AI Chat seeded with a prompt and, optionally, context
+     * entities — the supported way to launch AI Chat from another application.
+     *
+     * Encapsulates building the chat workspace item (content type
+     * `application/vnd.octostar.chat+json`) in the active workspace and opening
+     * it with the AI Chat app, so callers don't hand-roll that flow. Every call
+     * mints a fresh chat, so the prompt always seeds; seeding is one-shot per
+     * chat, so a browser refresh won't re-send it.
+     *
+     * By default the prompt is auto-sent as the chat's first message (no skill
+     * armed). Pass `{ mode: 'draft' }` to only prefill the chat input and let
+     * the user hit send. Omitting `initialPrompt` (or passing an empty string)
+     * opens the chat unseeded and does not auto-send — useful to just start a
+     * chat over some context entities.
+     *
+     * By default the chat opens as a workbench tab. Pass `{ target: 'sidebar' }`
+     * to open it in the host's AI panel instead (making the panel
+     * visible and switching it to AI Chats); this requires the v3 app.
+     *
+     * @example
+     * ```ts
+     * await desktop.openNewAIChat('Summarize this document', [document]);
+     * await desktop.openNewAIChat('Draft to review', [entity], { mode: 'draft' });
+     * await desktop.openNewAIChat(undefined, [entity]); // unseeded chat over context
+     * await desktop.openNewAIChat('About this record', [entity], { mode: 'draft', target: 'sidebar' });
+     * ```
+     *
+     * @param initialPrompt - The prompt to seed the new chat with; omit to open unseeded.
+     * @param contextEntities - Entities to seed the chat's context.
+     * @param options - Seeding behavior; see {@link OpenNewAIChatOptions}.
+     */
+    openNewAIChat: (initialPrompt?: string, contextEntities?: Entity[], options?: OpenNewAIChatOptions) => Promise<void>;
+    /**
+     * Enumerates the host-registered context-menu actions whose group is in
+     * `groups` AND which accept the given record(s) — i.e. the same set the
+     * host would put under those group sub-menus of the right-click context
+     * menu, returned as plain data so a micro-frontend can render its own
+     * menu instead of triggering the host popup. Pass a single record or
+     * an array; for arrays the host applies the same `accepts({ items })`
+     * filter the context-menu builder uses.
+     *
+     * Typical groupings:
+     *   - `['open', 'edit']` — "Open with…" submenu (openers / editors).
+     *   - `['addto']`         — "Add to…" submenu (link chart, map, set, …).
+     *   - `['transform']`     — "Transform" submenu (slower; consider lazy).
+     *
+     * The returned items are not executable directly — invoke them with
+     * {@link invokeRegisteredAction} using the `key`. Keys are stable
+     * across registrations of the same action.
+     */
+    getRegisteredActions: (items: WorkspaceItem | WorkspaceItem[], groups: ContextMenuGroup[]) => Promise<RegisteredActionInfo[]>;
+    /**
+     * Invokes a previously-enumerated action (from
+     * {@link getRegisteredActions}) by its `key`, with the records the user
+     * wants to act on. The host resolves the registered action and runs its
+     * `invoke` callback with the same context shape the right-click flow
+     * would have built.
+     *
+     * Rejects when no registered action matches the key OR when the
+     * action's `accepts(...)` filter refuses the given items.
+     */
+    invokeRegisteredAction: (key: string, items: WorkspaceItem | WorkspaceItem[], options?: DesktopActionOptions) => Promise<void>;
     /**
      * Deletes an item or items recursively.
      */
@@ -950,6 +1096,12 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Deletes local concept records in a workspace by base concept.
      */
     delete_local_concept_records: (workspace_id: string, base_concept: string) => Promise<void>;
+    /**
+     * Deletes the records of ONE import source in a workspace (the per-source
+     * buckets the Content Browser shows under Records). Rejects with a 404 on an
+     * API that predates the endpoint, rather than deleting anything wider.
+     */
+    delete_workspace_records_by_source: (workspace_id: string, scope: RecordsSourceScope) => Promise<void>;
     /**
      * Searches the index using the query string
      * @param query OpenSearch qeuery string.
@@ -968,7 +1120,7 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
     /**
      * Renames a tab by its id.
      */
-    renameTab: (tabId: string, newName: string) => Promise<void>;
+    renameTab: (props: RenameTabProps) => Promise<void>;
     /**
      * Closes a tab with given properties.
      */
@@ -997,10 +1149,17 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Gets a system setting.
      */
     getSystemSetting: <T extends string | boolean>(key: string, defaultValue: T, show_protected?: boolean) => Promise<GetSystemSettingResponse<T>>;
+    /**
+     * Forward geocodes a query string into geographic coordinates.
+     * @param query - Free-text location query (address, place name, etc.)
+     * @param limit - Maximum number of results to return (default: 5)
+     * @returns Array of geocoding results
+     */
+    geocode: (query: string, limit?: number) => Promise<GeocodingResult[]>;
     /**
      * Wraps a promise with a progress bar.
      */
-    withProgressBar: <T>(promise: Promise<T>, options?: WithProgressBarOptions) => Promise<T>;
+    withProgressBar: <T>(promise: Promise<T>, options?: WithProgressBarOptions) => Promise<T | undefined>;
     /**
      * Shows a confirmation modal.
      */
@@ -1009,6 +1168,13 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Shows a file upload dialog.
      */
     showFileUpload: (folder: WorkspaceItem) => Promise<WorkspaceItem[]>;
+    /**
+     * Shows the "Add to Files" dialog scoped to a workspace: the user picks a
+     * target folder via a tree selector (defaulting to the workspace root),
+     * then uploads files into it. Fire-and-forget — the dialog handles the
+     * upload itself.
+     */
+    showUploadToFolder: (workspace: WorkspaceItem) => Promise<void>;
     /**
      * Shows a form for creating an entity.
      */
@@ -1021,10 +1187,6 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Shows a modal for saving as.
      */
     showSaveAsModal: (props: SaveAsModalProps) => Promise<WorkspaceItem | undefined>;
-    /**
-     * @deprecated This method is deprecated and will be removed in a future version. Use {@link createSetsFromItems} or {@link expandSet} instead.
-     */
-    getPasteContext: (options: PasteContextOptions) => Promise<Entity[]>;
     /**
      * Expands a set with optional options.
      */
@@ -1049,14 +1211,6 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Adds a comment to an entity.
      */
     addComment: (about: Entity, comment: AddCommentParams) => Promise<Entity>;
-    /**
-     * Adds a watch intent to an entity.
-     */
-    addWatchIntent: (entity: Entity, watcher: Watcher) => Promise<Entity>;
-    /**
-     * Removes a watch intent by workspace and intent ID.
-     */
-    removeWatchIntent: (os_workspace: string, intent_id: string) => Promise<void>;
     /**
      * Gets workspace permissions by IDs.
      */
@@ -1070,9 +1224,9 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      */
     deployApp: (app: WorkspaceItem | App, initialSecrets?: Record<string, string>) => Promise<WorkspaceItem>;
     /**
-     * Undeploys an application.
+     * Undeploys an application. `appId` is the k8s app id; without it the id is looked up from the apps API.
      */
-    undeployApp: (app: WorkspaceItem | App) => Promise<WorkspaceItem>;
+    undeployApp: (app: WorkspaceItem | App, appId?: string) => Promise<WorkspaceItem>;
     /**
      * Gets information about the current user.
      */
@@ -1094,13 +1248,25 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      */
     removeFromFocusList: (entities: Entity[], type?: 'single' | 'group', tabName?: string) => Promise<FocusListItem[]>;
     /**
-     * Gets the image URL for an entity.
+     * Gets the image URL for an entity: its own bytes when it is an image file,
+     * else its attached image, else its concept icon. With `maxWidth`, image
+     * bytes come as a downscaled server thumbnail (snapped to 512 or 2048 px)
+     * instead of the original.
      */
-    getImageUrl: (entity: EntityBase) => Promise<string>;
+    getImageUrl: (entity: EntityBase, options?: {
+        maxWidth?: number;
+    }) => Promise<string>;
     /**
      * Gets images for an entity.
      */
     getImages: (entity: Entity) => Promise<Entity[]>;
+    /**
+     * Gets batch images for an entity.
+     */
+    getBatchImages: (entities: Entity[]) => Promise<{
+        entity: Entity;
+        images: Entity[];
+    }[]>;
     /**
      * Gets icon code for an entity, concept, or string.
      */
@@ -1124,10 +1290,6 @@ export declare interface Desktop extends DesktopSettings, WorkspaceChangeEmitter
      * Get config files
      */
     getConfigFiles: (name: string) => Promise<WorkspaceItem[]>;
-    /**
-     * "Cache" for workspaces, avoiding to return a modal error, if this workspace was fetched before
-     */
-    workspaceStore: Record<string, Workspace>;
     getWhitelabelingInfo: () => Promise<{
         OCTOSTAR_MAIN_LOGO: string;
         OCTOSTAR_FAVICON: string;
@@ -1179,6 +1341,10 @@ export declare type DesktopActionMenuItem = {
      * Key for the menu item.
      */
     key: string;
+    /**
+     * Test id for the rendered menu item. Defaults to `menuitem-<key>`.
+     */
+    testId?: string;
     /**
      * Icon for the menu item.
      */
@@ -1211,6 +1377,12 @@ export declare type DesktopActionMenuItem = {
      * Filter for accepting the menu item.
      */
     accepts: DesktopActionFilter;
+    /**
+     * Render the item greyed-out and non-clickable. Use for an action that is
+     * deliberately shown-but-inert in some state (so the user learns it exists and
+     * why it's unavailable) rather than hidden.
+     */
+    disabled?: boolean;
     /**
      * Function to invoke the action.
      */
@@ -1288,6 +1460,23 @@ export declare type DesktopActionOptions = {
      * Open tab in a new tabset
      */
     newTabset?: boolean;
+    /**
+     * Open the tab in a new tabset docked on one side of this tabset, e.g. a view beside the tab it follows.
+     * Falls back to the default placement when the tabset no longer exists.
+     */
+    dockBeside?: {
+        tabsetId: string;
+        side: 'left' | 'right';
+    };
+    /**
+     * When `tabId` matches an existing tab, swap the tab's
+     * `component`/`config`/`name` in place instead of just focusing it.
+     * No delete + re-add, so the tab node stays alive at its current
+     * position and flexlayout re-runs the factory with the new entity —
+     * flicker-free content swap inside a single persistent tab.
+     * Ignored when the tab doesn't exist (falls through to normal open).
+     */
+    replaceContent?: boolean;
     /**
      * Wait for the tab to open
      */
@@ -1296,6 +1485,15 @@ export declare type DesktopActionOptions = {
      * Custom name of the tab.
      */
     tabName?: string;
+    /**
+     * When the open is requested from a global surface with NO active workspace (Home,
+     * Workspaces, …), host the record in the workspace it belongs to — opening that
+     * workspace — instead of the last-active / personal workspace. Set by
+     * entity deep links (`#entity/...`) so a pasted link lands the record in its
+     * own workspace. Ignored when a workspace is already active (the active workspace hosts
+     * it) or when the record carries no concrete workspace (draft / personal).
+     */
+    hostInOwnWorkspace?: boolean;
 };
 
 /**
@@ -1337,21 +1535,6 @@ export declare interface DesktopSettings {
     getDeveloperSettings: () => Promise<DeveloperSettings>;
 }
 
-/**
- * Context for desktop styler.
- * @beta
- */
-export declare type DesktopStylerContext = {
-    /**
-     * Graph specification.
-     */
-    graph: GraphSpec;
-    /**
-     * Selected graph specification.
-     */
-    selected?: GraphSpec;
-};
-
 /**
  * Developer settings exposed to micro-frontends.
  * @beta
@@ -1361,10 +1544,6 @@ export declare interface DeveloperSettings {
      * Override URL for the API server.
      */
     octostarAPIServer?: string;
-    /**
-     * Override URL for the search app.
-     */
-    searchAppUrl?: string;
 }
 
 export declare interface DownloadOptions {
@@ -1373,17 +1552,6 @@ export declare interface DownloadOptions {
     redirect?: boolean;
 }
 
-/**
- * Represents a draft workspace item.
- * @beta
- */
-export declare type DraftWorkspaceItem = WorkspaceItem & {
-    /**
-     * Indicates if the item is a draft. The attribute is not saved in persistence.
-     */
-    os_draft_item: true;
-};
-
 /**
  * Parameters for drag end.
  * @beta
@@ -1545,6 +1713,17 @@ export declare type EntityPasteContext = {
     fetch: (limit?: number) => Promise<Entity[]>;
 };
 
+/**
+ * @beta
+ * Type pairing one of an entity's relationships with its count.
+ */
+export declare type EntityRelationshipCount = {
+    /** The relationship the count belongs to. */
+    relationship: Relationship;
+    /** The count of the relationship. */
+    count: RelationshipCountEntry;
+};
+
 export declare interface EntityUiState {
     rename?: boolean;
     [key: string]: any;
@@ -1775,7 +1954,10 @@ export declare interface FilesAPIClient {
      * @param item - The file item to create
      * @returns The created entity
      */
-    createFile: (item: WorkspaceItem) => Promise<MkdirResponse>;
+    /** `clientKey`: the upload action's key; the pipeline groups the action's requests under it. */
+    createFile: (item: WorkspaceItem, options?: {
+        clientKey?: string;
+    }) => Promise<MkdirResponse>;
     /**
      * Get a download URL for a file
      *
@@ -1806,6 +1988,41 @@ export declare interface FilesAPIClient {
      * @returns The upload URL and fields
      */
     getUploadUrl: (os_workspace: string, entity_id: string, options: UploadOptions) => Promise<S3UploadResponse>;
+    /**
+     * Ask the server to fetch a public URL and ingest it directly into the
+     * workspace. Streams server-side — no bytes flow through the browser.
+     *
+     * @param os_workspace - The workspace ID
+     * @param body - URL + target parent folder, plus optional filename / content_type / overwrite
+     * @param signal - Optional AbortSignal that cancels the in-flight request (the server-side fetch is best-effort cancelled too)
+     * @returns The newly-created entity's id and resolved metadata
+     * @throws UploadFromUrlError on non-2xx responses, carrying the API's `{ detail.error_code, detail.message }` envelope
+     */
+    uploadFromUrl: (os_workspace: string, body: UploadFromUrlRequest, signal?: AbortSignal) => Promise<UploadFromUrlResponse>;
+    /**
+     * Peek inside a source-backed file (v1: zip archive) without extracting it.
+     * Returns one level of contents from the source at the given `inner` path
+     * (defaults to the source root).
+     *
+     * @param os_workspace - The workspace ID
+     * @param target - Either `{ path }` (workspace path to the source file) or `{ entity_id }` (the source's entity_id)
+     * @param options - Optional `inner` path inside the source to list
+     * @returns Folders + files visible at the inner path
+     */
+    peekSource: (os_workspace: string, target: PeekSourceTarget, options?: PeekSourceOptions) => Promise<SourcePeekResponse>;
+    /**
+     * Bulk-export inner paths from a source-backed archive into a workspace
+     * folder. `inner_paths` may freely mix files and folders; folders are
+     * expanded recursively server-side. The endpoint validates WRITE on the
+     * target workspace up front (HTTP 403 if denied), aborts the batch on
+     * folder-phase failures, and surfaces per-file failures in
+     * `response.errors[]` without aborting.
+     *
+     * @param os_workspace - Target workspace ID (the export destination)
+     * @param body - Source archive entity_id, inner paths, target folder ID
+     * @returns Created folder/file IDs plus per-entry errors
+     */
+    bulkExportSourceSubtree: (os_workspace: string, body: SourceExportRequest) => Promise<SourceExportResponse>;
 }
 
 /**
@@ -1835,28 +2052,6 @@ export declare type FileTreeOptions = {
     structure?: boolean;
 };
 
-export declare type Filter = {
-    cascadeParentIds: string[];
-    defaultDataMask: DataMask;
-    id: string;
-    name: string;
-    scope: NativeFilterScope;
-    filterType: string;
-    targets: [Partial<NativeFilterTarget>];
-    controlValues: Record<string, any>;
-    sortMetric?: string | null;
-    adhoc_filters?: Record<any, any>[];
-    granularity_sqla?: string;
-    granularity?: string;
-    time_grain_sqla?: string;
-    time_range?: string;
-    requiredFirst?: boolean;
-    tabsInScope?: string[];
-    chartsInScope?: number[];
-    type: 'NATIVE_FILTER';
-    description: string;
-};
-
 /**
  * @beta
  * Type representing a filter definition, which can be one of several specific filter types.
@@ -1891,11 +2086,6 @@ export declare type FilterReference = string | {
     ['require_all']: FilterReference[];
 };
 
-export declare type FilterState = {
-    value?: any;
-    [key: string]: any;
-};
-
 /**
  * Type for filter values.
  * @beta
@@ -1921,29 +2111,99 @@ export declare type FocusListItem = {
 } | NamedEntityGroup;
 
 /**
- * Options for pasting folders.
+ * Metadata fields extracted from a fragment entity.
  * @beta
  */
-export declare type FolderPasteOptions = {
-    /**
-     * Whether to include folders in the paste.
-     */
-    folders?: boolean;
-    /**
-     * Whether to include files in the paste.
-     */
-    files?: boolean;
-    /**
-     * Whether to paste recursively.
-     */
-    recursive?: boolean;
+export declare type FragmentInfo = {
+    fragment_page_number?: number;
+    /** Seconds for audio/video collections, a page for `document_*`, a row for `table_*`; the pipeline writes numbers, older indexes strings. */
+    fragment_start?: string | number;
+    fragment_end?: string | number;
+    fragment_index?: number;
+    fragment_count?: number;
+    fragment_collection_type?: string;
+    /** `[x1, y1, x2, y2]` in the parent image's pixels, as an array of numeric strings or comma-joined. */
+    fragment_image_bbox?: string | string[];
+    fragment_x_offset?: number;
+    fragment_y_offset?: number;
+    fragment_z_offset?: number;
+    fragment_keyframe_number?: number;
+    fragment_path_expression?: string;
+    /** Content type of the original file the fragment chain starts from, not of the direct parent. */
+    parent_os_item_content_type?: string;
+};
+
+/**
+ * Where inside its parent a fragment sits. A union, not a bag of optional
+ * offsets, because `fragment_start` is polymorphic: the pipeline emits seconds
+ * for `audio_split`/`video_*`, row ordinals for `table_row*`, and a repeat of
+ * the page for `document_*`.
+ */
+export declare type FragmentLocator = {
+    kind: 'page';
+    page: number;
+} | {
+    kind: 'time';
+    start: number;
+    end?: number;
+} | {
+    kind: 'rows';
+    start: number;
+    end?: number;
+} | {
+    kind: 'region';
+    box: FragmentRegion;
+} | {
+    kind: 'none';
+};
+
+/** Detected-region corners in the SOURCE image's pixel space. */
+export declare interface FragmentRegion {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+}
+
+/**
+ * Result of resolving a fragment entity to its source entity.
+ * @beta
+ */
+export declare type FragmentResolution = {
+    entity: Entity;
+    fragment: FragmentInfo | undefined;
 };
 
-declare enum GenericDataType {
-    NUMERIC = 0,
-    STRING = 1,
-    TEMPORAL = 2,
-    BOOLEAN = 3
+/**
+ * One entry in {@link ProcessingStatus.fragment_errors} /
+ * {@link ProcessingStatus.fragment_warnings} / {@link ProcessingStatus.warnings}.
+ *
+ * All fields are optional to match the backend `ChildProcessingStatus` contract:
+ * the pipeline serializes entries with `exclude_none=True`, so partial entries
+ * (e.g. a lenient-merge gap that only knows `entity_id`, or a processor that
+ * omits `reason`) are valid wire payloads.
+ * @beta
+ */
+export declare interface FragmentStatusEntry {
+    reason?: string;
+    status_code?: string;
+    timestamp?: string;
+    entity_id?: string;
+    entity_label?: string;
+    entity_type?: string;
+}
+
+/**
+ * Result from a geocoding query.
+ */
+export declare interface GeocodingResult {
+    latitude: number;
+    longitude: number;
+    address: string;
+    name: string;
+    country: string;
+    city: string;
+    type: string;
 }
 
 /**
@@ -1971,6 +2231,12 @@ export declare type GetSystemSettingResponse<T extends string | boolean = string
     security: boolean;
     type: string;
     value: T;
+    /**
+     * Set when `value` is the caller's default because the setting could not be
+     * fetched. `DesktopAPI.getSystemSetting` swallows the error, so callers that
+     * must tell "unset" from "unreadable" check this instead.
+     */
+    unavailable?: boolean;
 };
 
 export declare type GraphDataSpec = {
@@ -1991,6 +2257,28 @@ export declare type GraphSpec = {
     edges: EdgeSpec[];
 };
 
+/**
+ * Annotation keys never worth shipping with a hit list: `rag:fulltext` and
+ * `rag:chunks` carry every document's extracted text (a 200-hit search shipped
+ * ~10 MB of it to draw a list of names), `ner:entities` is a long array nothing
+ * renders, and the heavy `materialized` children are the detection copies with
+ * their vectors and the NER and geo rollups. The small
+ * `materialized.image:labels*` arrays ride along: they are how a card learns
+ * that a document holds a flagged image on one of its pages.
+ *
+ * An exclude list rather than an allowlist, deliberately: the small card-shaped
+ * annotations (`summary:txt`, `image:annotations-*`) have to ride along, and a
+ * field nobody thought of must arrive rather than vanish. Exported so any caller
+ * that shapes its own `_source` trims the same things — two lists would drift,
+ * and the drift shows up as a blank cell nobody can explain.
+ *
+ * Lives here with the rest of the wire contract — not in a UI package, and not
+ * in platform-api (whose barrel several test suites blanket-mock; a constant
+ * read at module scope must survive that). The Content Browser re-exports it
+ * for back-compat.
+ */
+export declare const HEAVY_ANNOTATION_FIELDS: readonly string[];
+
 /**
  * @beta
  * Type representing an HTTP transform definition.
@@ -2105,6 +2393,13 @@ export declare type IframeTransformDefinition = {
     tab_name?: string;
 };
 
+export declare const IMAGE_LABEL_FAMILIES: readonly ImageLabelFamilyFields[];
+
+export declare const IMAGE_LABEL_FIELDS: Readonly<Record<ImageLabelFamily, ImageLabelFamilyFields>>;
+
+/** `_source` paths for every family's own and rolled-up arrays. Small strings, never vectors. */
+export declare const IMAGE_LABEL_SOURCE_INCLUDES: readonly string[];
+
 /**
  * Represents information about an image.
  * @beta
@@ -2125,29 +2420,139 @@ export declare type ImageInfo = {
 };
 
 /**
- * Options for importing folders/files from a ZIP file.
- * @beta
+ * Step one of an exact label count: a plain terms aggregation per representation
+ * (own, rolled up, legacy nested), read for their keys only. Their counts would
+ * count a record once per representation, so step two recounts the keys. The
+ * nested leg ranks its keys by the records holding them, not by detections.
  */
-export declare type ImportFoldersOptions = {
-    /**
-     * Target folder or workspace for the import.
-     */
-    target: string;
-    /**
-     * Whether to overwrite existing items.
-     */
-    overwrite?: boolean;
-    /**
-     * Whether to include content in the import.
-     */
-    include_content?: boolean;
-};
+export declare function imageLabelCandidateAggs(fields: ImageLabelFamilyFields, { size, include, exclude }: ImageLabelCandidateOptions): Record<string, unknown>;
 
-export declare interface IndexSearchHitSource {
-    annotations?: {
-        data?: string;
-        crossFilters?: string;
-        'extract:metadata'?: string;
+export declare interface ImageLabelCandidateOptions {
+    size: number;
+    include?: string;
+    exclude?: string;
+}
+
+/**
+ * Candidate keys to ask each representation for, to rank `displaySize` labels: the
+ * general family's long tail needs headroom, the other vocabularies fit whole.
+ */
+export declare function imageLabelCandidateSize(fields: ImageLabelFamilyFields, displaySize: number): number;
+
+/** Step two: one `filters` entry per candidate, each the clause a pick of it matches. */
+export declare function imageLabelCountAggs(fields: ImageLabelFamilyFields, keys: readonly string[]): Record<string, unknown>;
+
+/**
+ * The image label contract shared with the index mapping (octostar-init-datasources)
+ * and the pipeline that writes it (octostar-api, TEAM-9205).
+ *
+ * Four families of image labels, each a nested detection array the pipeline
+ * writes (`image:annotations*`, boxes, confidence, vectors) and, derived from
+ * it, a keyword array of the record's own distinct labels (`image:labels*`).
+ * A record's descendants roll their labels up into
+ * `annotations.materialized.image:labels*`, strings only, so a document is
+ * discoverable by a label on a page or frame inside it without the nested
+ * objects.
+ *
+ * A query reads the two arrays directly, plus the nested detections of a
+ * record not reprocessed since the arrays existed. A fragment binds on its own
+ * labels only, so a page never matches on the labels of the images inside it;
+ * a top-level record binds on its own and its rolled-up labels. A count runs in
+ * two steps, candidates then one `filters` entry per candidate, so a record
+ * counts once per label whichever representations hold it.
+ *
+ * Label-only readers go through the shared reader in `@octostar/ui`
+ * (`readImageLabels`), which unions the own and rolled-up arrays with the
+ * legacy entries' labels while records written before the arrays existed are
+ * still around. Readers that need geometry, confidence or vectors keep reading
+ * `image:annotations*`.
+ */
+export declare type ImageLabelFamily = 'general' | 'key' | 'sensitive' | 'setting';
+
+export declare interface ImageLabelFamilyFields {
+    family: ImageLabelFamily;
+    /** The nested detection array the labels are derived from (`annotations.<key>`). */
+    annotationsKey: string;
+    /** The owner's own distinct labels (`annotations.<key>`); descendants' under `annotations.materialized.<key>`. */
+    labelsKey: string;
+    /** The record's own labels, keyword. */
+    ownField: string;
+    /** The labels rolled up from the record's descendants, keyword. */
+    rolledUpField: string;
+    /** The nested path and label keyword a query reached before the arrays existed. */
+    legacyNestedPath: string;
+    legacyLabelField: string;
+}
+
+/** The family whose own label array `field` is, if it is one. */
+export declare function imageLabelFamilyOfField(field: string): ImageLabelFamilyFields | undefined;
+
+/** What a pick of `values` matches: own labels, rolled-up labels on a top-level
+ * record, or the legacy detections. A record matching several legs is one hit. */
+export declare function imageLabelMatchClause(fields: ImageLabelFamilyFields, values: readonly string[]): Record<string, unknown>;
+
+/** `_source` paths a label-only reader needs: the own and rolled-up arrays of one family. */
+export declare function imageLabelSourceIncludes(name: ImageLabelFamily): string[];
+
+export declare type ImportConflictPolicy = 'rename' | 'skip' | 'overwrite';
+
+export declare interface ImportDestination {
+    /** Parent folder entity UUID; null = workspace root. */
+    os_parent_folder?: string | null;
+}
+
+export declare type ImportEntryKind = 'file' | 'directory';
+
+/**
+ * Options for importing folders/files from a ZIP file.
+ * @beta
+ */
+export declare type ImportFoldersOptions = {
+    /**
+     * Target folder or workspace for the import.
+     */
+    target: string;
+    /**
+     * Whether to overwrite existing items.
+     */
+    overwrite?: boolean;
+    /**
+     * Whether to include content in the import.
+     */
+    include_content?: boolean;
+};
+
+export declare interface ImportItem {
+    path: string;
+    kind: ImportEntryKind;
+}
+
+export declare type ImportMode = 'copy' | 'link';
+
+export declare interface ImportOptions {
+    /** `copy` streams bytes into S3 (durable); `link` references the mount live. */
+    mode?: ImportMode;
+    recursive?: boolean;
+    max_total_bytes?: number | null;
+    max_files?: number | null;
+    on_conflict?: ImportConflictPolicy;
+    preserve_modified_at?: boolean;
+}
+
+export declare interface ImportRequest {
+    os_workspace: string;
+    destination?: ImportDestination;
+    items: ImportItem[];
+    options?: ImportOptions;
+    /** Idempotency key (copy mode). A retry with the same id returns the existing task. */
+    tracking_id?: string | null;
+}
+
+export declare interface IndexSearchHitSource {
+    annotations?: {
+        data?: string;
+        crossFilters?: string;
+        'extract:metadata'?: string;
         'extract:src'?: string;
         'extract:txt'?: string;
         'extract:txtLang'?: string;
@@ -2168,6 +2573,19 @@ export declare interface IndexSearchHitSource {
         'image:annotations-setting'?: {
             label?: string;
         }[];
+        /** The record's own distinct labels per family, derived from the arrays above. */
+        'image:labels'?: string[];
+        'image:labels-key'?: string[];
+        'image:labels-sensitive'?: string[];
+        'image:labels-setting'?: string[];
+        /** Rolled up from the record's descendants. */
+        materialized?: {
+            'image:labels'?: string[];
+            'image:labels-key'?: string[];
+            'image:labels-sensitive'?: string[];
+            'image:labels-setting'?: string[];
+            'ner:entities'?: Record<string, string[]>;
+        };
         'ner:entities'?: {
             person?: string[];
             org?: string[];
@@ -2179,6 +2597,11 @@ export declare interface IndexSearchHitSource {
             email?: string[];
             ip_address?: string[];
             url?: string[];
+            address?: string[];
+            license_plate?: string[];
+            iban?: string[];
+            credit_card?: string[];
+            crypto?: string[];
         };
         'rag:chunks'?: {
             metadata?: {
@@ -2361,15 +2784,30 @@ export declare type InlineCode = {
     code: string;
 };
 
+/**
+ * @beta
+ * Type guard distinguishing code-resident default templates from
+ * workspace-stored ones.
+ */
+export declare function isDefaultTemplate(t: RenderableTemplate | undefined | null): t is DefaultTemplate;
+
+/**
+ * Type guard for {@link DeletedEntity}.
+ * @beta
+ */
+export declare function isDeletedEntity(value: unknown): value is DeletedEntity;
+
 export declare function isWorkspaceFileItem(item: WorkspaceItem): item is WorkspaceItem & {
     os_has_attachment: true;
 };
 
 /**
+ * True when `entity` is a workspace root.
  * @beta
- * Type representing a JavaScript file styler definition.
  */
-export declare type JavascriptFileStylerDefinition = JavascriptType & FileCode;
+export declare function isWorkspaceRoot(entity?: EntityBase | WorkspaceRecordIdentifier | {
+    os_item_type?: string;
+} | null): boolean;
 
 /**
  * @beta
@@ -2388,12 +2826,6 @@ export declare type JavascriptFilterDefinition = {
     code: string;
 };
 
-/**
- * @beta
- * Type representing an inline JavaScript styler definition.
- */
-export declare type JavascriptInlineStylerDefinition = JavascriptType & InlineCode;
-
 /**
  * @beta
  * Type representing an inline JavaScript transform definition.
@@ -2405,7 +2837,7 @@ export declare type JavascriptInlineTransformDefinition = JavascriptType & Inlin
  * Type representing a JavaScript transform definition.
  */
 export declare type JavascriptType = {
-    /** The type of the transform or styler, always 'javascript' for this type. */
+    /** The type of the transform, always 'javascript' for this type. */
     type: 'javascript';
 };
 
@@ -2427,13 +2859,15 @@ export declare type JobManifest = {
     /** Optional image for the job. */
     image?: string;
     /** Optional engine for the job. */
-    engine?: 'k8s' | 's3' | 'reactlive';
+    engine?: 'k8s' | 's3';
     /** Optional template for the job. */
     template?: string;
     /** Optional variant for the job. */
     variant?: string;
     /** Optional instance type for the job. */
     instance_type?: string;
+    /** Seconds the app declares it needs to start serving. The backend does not enforce it on a deploy. */
+    startup_timeout?: number;
     /** Whether to skip archiving the job. */
     no_archive?: boolean;
     /** Whether to generate a URL from logs. */
@@ -2446,8 +2880,6 @@ export declare type JobManifest = {
     transforms?: TransformDefinitions;
     /** Optional collection of filters for the job. */
     filters?: FilterDefinitions;
-    /** Optional collection of stylers for the job. */
-    stylers?: StylerDefinitions;
     /** Optional collection of services for the job. */
     services?: ServiceDefinitions;
     secrets?: ManifestSecrets;
@@ -2542,6 +2974,24 @@ export declare type ManifestSecrets = Record<string, {
     required?: boolean;
 }>;
 
+/**
+ * System-setting keys for the map surfaces. Every basemap the app offers comes
+ * from one of these; a key with no configured value means that basemap is not
+ * available and is not offered. Keys must match the definitions registered in
+ * `octostar-api` (`app/api/v1/settings/settings_definitions.py`), where admins
+ * edit them from the system settings page.
+ */
+export declare const MAP_SETTINGS_KEYS: {
+    /** Vector style JSON URL; backs the Streets basemap. */
+    readonly vectorTileStyleUrl: "os.general.vector_tile_style_url";
+    /** Raster tile URL template ({z}/{x}/{y}); backs the Tiles basemap. */
+    readonly rasterTileServerUrl: "os.general.tile_map_server_url";
+    /** Dark vector style JSON URL; backs the Dark basemap. */
+    readonly darkTileStyleUrl: "os.general.dark_tile_style_url";
+};
+
+export declare type MapSettingKey = (typeof MAP_SETTINGS_KEYS)[keyof typeof MAP_SETTINGS_KEYS];
+
 export declare type MkdirResponse = WorkspaceItem;
 
 /**
@@ -2566,6 +3016,106 @@ export declare type ModalTemplateProps = CustomTemplateIframeProps & {
     taskID?: string;
 };
 
+export declare interface MountAccess {
+    is_admin: boolean;
+    has_use_grant: boolean;
+}
+
+export declare interface MountCreate {
+    name: string;
+    description?: string | null;
+    scheme: MountScheme;
+    host: string;
+    port?: number | null;
+    share?: string | null;
+    base_path?: string;
+    credential_mode: CredentialMode;
+    shared_credentials?: SharedCredentialsInput;
+}
+
+export declare interface MountGrantCreate {
+    principal_type: PrincipalType;
+    principal_id: string;
+}
+
+export declare interface MountGrantResponse {
+    id: string;
+    mount_id: string;
+    principal_type: PrincipalType;
+    principal_id: string;
+    granted_by: string;
+    created_at: string;
+}
+
+/** Async result of a `mode="copy"` import (HTTP 202) — poll the task by tracking_id. */
+export declare interface MountImportCopyResponse {
+    tracking_id: string;
+    status_url: string;
+}
+
+/** One per-entry failure from a `link` import that did not abort the batch. */
+export declare interface MountImportLinkError {
+    path: string;
+    reason: string;
+}
+
+/** Synchronous result of a `mode="link"` import (HTTP 200). */
+export declare interface MountImportLinkResponse {
+    created_folder_ids: string[];
+    created_file_ids: string[];
+    errors: MountImportLinkError[];
+}
+
+export declare interface MountResponse {
+    id: string;
+    name: string;
+    description: string | null;
+    scheme: MountScheme;
+    enabled: boolean;
+    host: string;
+    port: number | null;
+    share: string | null;
+    base_path: string;
+    credential_mode: CredentialMode;
+    cred_type: CredType;
+    shared_credentials_set: boolean;
+    credentials_required: boolean;
+    last_validation_outcome: string | null;
+    last_validated_at: string | null;
+    created_by: string;
+    created_at: string;
+    last_updated_at: string;
+    my_access: MountAccess | null;
+}
+
+/**
+ * Mounts API DTOs (`/api/v2/mounts`, octostar-api #774 + #785).
+ *
+ * The request/response shapes for the Mounts admin + per-user-credential API.
+ * These live in the published SDK surface so any app (the admin UI, a future
+ * data explorer, …) consumes one shared vocabulary rather than redeclaring it.
+ * App-internal concerns — the typed fetch client, its error class, friendly-copy
+ * mapping — stay in the consuming app (`apps/octostar/src/lib/mountsApi.ts`).
+ */
+export declare type MountScheme = 'smb';
+
+/**
+ * PATCH body. Every field is optional, but `name`, `enabled`, `base_path` and
+ * `credential_mode` may NOT be sent as explicit `null` (omit to leave
+ * unchanged) — the backend returns 422 for an explicit null. `scheme`/`host`
+ * are immutable and are not part of this body.
+ */
+export declare interface MountUpdate {
+    name?: string;
+    description?: string | null;
+    enabled?: boolean;
+    port?: number | null;
+    share?: string | null;
+    base_path?: string;
+    credential_mode?: CredentialMode;
+    shared_credentials?: SharedCredentialsInput;
+}
+
 export declare interface MoveOptions {
     to_path?: string;
     entity_id?: string;
@@ -2601,21 +3151,6 @@ export declare type NamedEntityGroup = {
     type: 'group';
 };
 
-export declare interface NativeFilterColumn {
-    name: string;
-    displayName?: string;
-}
-
-export declare interface NativeFilterScope {
-    rootPath: string[];
-    excluded: number[];
-}
-
-export declare interface NativeFilterTarget {
-    datasetId: number;
-    column: NativeFilterColumn;
-}
-
 /**
  * @beta
  * Type representing a Nunjucks file transform definition. Not yet supported.
@@ -2636,7 +3171,7 @@ export declare type NunjucksInlineTransformDefinition = NunjucksType & {
  * Type representing a Nunjucks transform definition.
  */
 export declare type NunjucksType = {
-    /** The type of the transform or styler, always 'nunjucks' for this type. */
+    /** The type of the transform, always 'nunjucks' for this type. */
     type: 'nunjucks';
 };
 
@@ -2658,11 +3193,77 @@ export declare interface Ontology {
     getAvailableOntologies: () => Promise<string[]>;
     /**
      * Gets workspace relationship records for a given entity and relationship.
+     *
+     * When `pagination` is omitted the call uses the batched LRU and returns
+     * all rows (subject to `CONNECTIONS_QUERY_CAP_PER_ENTITY`). When provided,
+     * the call bypasses the cache and issues a single-entity targeted SQL with
+     * `ORDER BY os_entity_uid LIMIT/OFFSET` — used for progressive expansion
+     * on hyper-connected entities.
+     *
      * @param entity - The entity for which to get relationship records.
      * @param rel - The relationship or relationship name.
+     * @param pagination - Optional `{ limit, offset }`. When set, bypasses cache.
      * @returns A promise that resolves to an array of workspace relationships.
      */
-    getWorkspaceRelationshipRecords: (entity: Entity, rel: string | Relationship) => Promise<WorkspaceRelationship[]>;
+    getWorkspaceRelationshipRecords: (entity: Entity, rel: string | Relationship, pagination?: {
+        limit: number;
+        offset: number;
+    }) => Promise<WorkspaceRelationship[]>;
+    /**
+     * Paginated counterpart to {@link Ontology.getConnectedEntities}. Pulls one
+     * page using local-first → bigData spillover and returns `total` so the
+     * caller can drive a "Load more" affordance without a separate count call.
+     *
+     * @param entity - The entity for which to get connected entities.
+     * @param rel - The relationship or relationship name.
+     * @param pagination - `{ limit, offset }` for the page.
+     * @returns A promise resolving to `{ entities, total, hasMore }`.
+     */
+    getConnectedEntitiesPage: (entity: Entity, rel: string | Relationship, pagination: {
+        limit: number;
+        offset: number;
+    }) => Promise<{
+        entities: Entity[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * @beta
+     * Edge-stream counterpart to {@link Ontology.getConnectedEntitiesPage}. Pages
+     * over a single `projection=edge` stream whose rows carry their target entity,
+     * so no per-entity fetch follows.
+     *
+     * @param entity - The entity for which to get connected entities.
+     * @param rel - The relationship or relationship name.
+     * @param pagination - `{ limit, offset }` for the page.
+     * @param knownTotal - Count the caller already holds, reported back as `total`.
+     * @returns A promise resolving to `{ entities, total, hasMore }`.
+     */
+    getConnectedEntitiesPageFromEdgeQuery: (entity: Entity, rel: string | Relationship, pagination: {
+        limit: number;
+        offset: number;
+    }, knownTotal: number) => Promise<{
+        entities: Entity[];
+        total: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * @beta
+     * Batched edge-endpoint counterpart to {@link Ontology.getConnectedEntities},
+     * scoped to the Positions-map full-relationship sweep. Fetches every name in
+     * `relationshipNames` for `entity` in one batched request, grouping results
+     * by relationship name, instead of one request per relationship.
+     *
+     * Keyed by the names actually fetched: a name that is unknown or hidden by
+     * the relationship mapping is absent, so read it as `result[name] ?? []`.
+     *
+     * @param entity - The entity for which to get connected entities.
+     * @param relationshipNames - The relationship names to fetch, in one batch.
+     * @returns A promise resolving to an object keyed by relationship name. Plain
+     * object rather than a `Map` so it survives the post-robot bridge that serves
+     * embedded apps.
+     */
+    getConnectedEntitiesForRelationships: (entity: Entity, relationshipNames: string[]) => Promise<Record<string, Entity[]>>;
     /**
      * Clears the relationship cache for a given entity and relationship.
      * @param entity - The entity for which to clear the cache.
@@ -2676,16 +3277,29 @@ export declare interface Ontology {
      * @param entity - The entity for which to get connected entities.
      * @param relationship - The relationship or relationship name.
      * @param forceRefresh - Whether to force a refresh of the data.
+     * @param inverse - Whether to resolve the relationship in the inverse direction.
      * @returns A promise that resolves to an array of connected entities.
      */
-    getConnectedEntities: <T extends Entity>(entity: Entity, relationship: Relationship | string, forceRefresh?: boolean) => Promise<T[]>;
+    getConnectedEntities: <T extends Entity>(entity: Entity, relationship: Relationship | string, forceRefresh?: boolean, inverse?: boolean) => Promise<T[]>;
     /**
      * Gets connections by type for a given entity and concept.
+     *
+     * The underlying SQL is capped at `CONNECTIONS_QUERY_CAP` rows to prevent
+     * the backend from materialising hyper-connected entities' relationships
+     * (which would OOM the FastAPI pod). When the cap is hit, `truncated` is
+     * `true` and `connections` contains the first `CONNECTIONS_QUERY_CAP`
+     * entries; consumers should surface a "showing first N" notice and
+     * direct users to filter via Search.
+     *
      * @param entity - The entity for which to get connections.
      * @param concept - The concept for which to get connections.
-     * @returns A promise that resolves to an array of connections.
+     * @param handler - Optional callback invoked with the (possibly truncated) connection list.
+     * @returns A promise that resolves to the connections and whether the result was truncated.
      */
-    getConnectionsByType: <T extends Entity>(entity: Entity, concept: string, handler?: (connections: EConnection[]) => Promise<void>) => Promise<EConnection[]>;
+    getConnectionsByType: (entity: Entity, concept: string, handler?: (connections: EConnection[]) => Promise<void>) => Promise<{
+        connections: EConnection[];
+        truncated: boolean;
+    }>;
     /**
      * Gets the concept names.
      * @returns A promise that resolves to an array concept names.
@@ -2733,6 +3347,19 @@ export declare interface Ontology {
      * @returns A promise that resolves to either the actual entity data OR the input entity if not found.
      */
     getEntity: <T extends Entity>(e: Entity, refresh?: boolean, skipSideEffects?: boolean) => Promise<T>;
+    /**
+     * Resolves an entity to its stored ontology record, or `undefined` if it
+     * does not exist in the database.
+     *
+     * Unlike {@link getEntity} — which echoes its input back unchanged on a
+     * miss — this distinguishes "found" from "not found" by tagging the probe
+     * with a `'#original'` flag that only survives the round trip when the
+     * entity was not persisted.
+     *
+     * @param entity - The entity to resolve (only `entity_type` / `entity_id` are required).
+     * @returns The stored entity, or `undefined` if it was not found.
+     */
+    findEntity: <T extends Entity = Entity>(entity: EntityBase) => Promise<T | undefined>;
     /**
      * Gets the name of the ontology.
      * @returns A promise that resolves to the name of the ontology.
@@ -2746,6 +3373,13 @@ export declare interface Ontology {
      * @returns A promise that resolves to the relationship count result.
      */
     getRelationshipCount: (entity: Entity, rel: Relationship | string, forceRefresh?: boolean) => Promise<RelationshipCountResult>;
+    /**
+     * Gets the counts of every relationship of a given entity in a single request.
+     * @param entity - The entity for which to get the relationship counts.
+     * @param forceRefresh - Whether to force a refresh of the data.
+     * @returns A promise that resolves to one count per relationship of the entity.
+     */
+    getEntityRelationshipCounts: (entity: Entity, forceRefresh?: boolean) => Promise<EntityRelationshipCount[]>;
     /**
      * Gets the concept for a given entity.
      * @param entity - The entity for which to get the concept.
@@ -2775,10 +3409,9 @@ export declare interface Ontology {
      * Sends a query with a typed response.
      * @param query - The query string.
      * @param options - Optional options for sending the query.
-     * @param force_refresh - Whether to force a refresh of the data.
      * @returns A promise that resolves to an array of results.
      */
-    sendQueryT: <T>(query: string, options?: SendQueryOptions, force_refresh?: boolean) => Promise<T[]>;
+    sendQueryT: <T>(query: string, options?: SendQueryOptions) => Promise<T[]>;
     /**
      * Gets the system inheritance.
      * @returns A promise that resolves to an array of inheritances.
@@ -2805,9 +3438,10 @@ export declare interface Ontology {
      * @param entity - The entity to subscribe to.
      * @param callback - The callback to invoke on changes.
      * @param skipInitialCallback - Whether to skip the initial callback.
+     * @param options - Which notices to receive; by default every notice for the entity.
      * @returns A promise that resolves to an unsubscribe function.
      */
-    subscribe: <T>(entity: Entity, callback: Callback<T>, skipInitialCallback?: boolean) => Promise<Unsubscribe>;
+    subscribe: <T>(entity: Entity, callback: Callback<T>, skipInitialCallback?: boolean, options?: SubscribeOptions) => Promise<Unsubscribe>;
     /**
      * Generates a consistent UUID.
      * @param name - The name for which to generate the UUID.
@@ -2823,6 +3457,29 @@ export declare interface Ontology {
     updateCache: (entities: (Entity & WorkspaceItem)[]) => Promise<(Entity & WorkspaceItem)[]>;
 }
 
+/**
+ * The display label the ontology schema resolves for a concept, property or relationship.
+ * @beta
+ */
+export declare interface OntologyLabel {
+    /**
+     * The label in the session language.
+     */
+    text: string;
+    /**
+     * One form per CLDR plural category; sent for concepts only.
+     */
+    plural?: Record<string, string>;
+}
+
+/**
+ * Returns the display name of an ontology term: its schema label, or the English default the
+ * backend derives from the machine name. The server always sends `label.text`, so the fallback is
+ * reached only against a backend predating the label fields or with a fixture-built model.
+ * @beta
+ */
+export declare function ontologyLabel(label: OntologyLabel | undefined, machineName: string | undefined): string;
+
 /**
  * @beta
  * Type representing tags associated with an ontology.
@@ -2838,6 +3495,46 @@ export declare type OntologyTags = {
     tag_value: string;
 };
 
+/**
+ * Options for {@link Desktop.openNewAIChat}.
+ * @beta
+ */
+export declare type OpenNewAIChatOptions = {
+    /**
+     * How the prompt seeds the new chat:
+     * - `'send'` (default): the prompt is auto-sent as the chat's first message
+     *   on first mount.
+     * - `'draft'`: the prompt only prefills the chat input, leaving the user to
+     *   review and hit send.
+     */
+    mode?: 'send' | 'draft';
+    /**
+     * Where the new chat opens:
+     * - `'tab'` (default): as a workbench tab, via the AI Chat app.
+     * - `'sidebar'`: in the host's AI panel (making it visible and
+     *   switching it to AI Chats). Requires the v3 app to be present — a host
+     *   without an AI panel ignores it. The chat is seeded identically either
+     *   way (same one-shot `os_item_content` prompt/context fields).
+     */
+    target?: 'tab' | 'sidebar';
+};
+
+/**
+ * @beta
+ * A report (.odoc) that is open in the app (Composer tab and/or sidebar).
+ */
+export declare type OpenReportSummary = {
+    /** Workspace item entity uid */
+    os_entity_uid: string;
+    /** Display title (without .odoc when applicable) */
+    displayName: string;
+    /** Timestamp when the report was last updated, if known */
+    os_last_updated_at?: string;
+    surface: 'tab' | 'sidebar';
+    /** True when this is the document selected in the Composer sidebar */
+    isSidebarSelected?: boolean;
+};
+
 export declare const ORIGINAL_OS_PARENT_FOLDER = "#original_os_parent_folder";
 
 /**
@@ -3057,6 +3754,26 @@ export declare type OsProgress = {
      * Persist until complete for the progress item.
      */
     persistUntilComplete?: boolean;
+    /**
+     * Milliseconds after which a finished row clears. 0 removes it outright
+     * (its outcome is narrated elsewhere). Unset falls back to the
+     * persistUntilComplete behavior.
+     */
+    clearAfterMs?: number;
+    /**
+     * Why a job stopped before finishing, where `status` alone cannot tell: an
+     * upload batch reports `exception` whether it was cancelled, failed, or
+     * stopped by its failure breaker.
+     */
+    outcome?: 'cancelled' | 'failed' | 'stopped';
+    /**
+     * How many of a batch's items failed so far, where the label only says it in prose.
+     */
+    failedCount?: number;
+    /**
+     * How many of a batch's items have finished so far, where the label only says it in prose.
+     */
+    doneCount?: number;
 };
 
 /**
@@ -3093,42 +3810,30 @@ declare type ParentFolderOption = {
     os_parent_folder: string;
 };
 
-/**
- * Options for pasting context.
- * @beta
- */
-export declare type PasteContextOptions = {
-    /**
-     * First limit for the context.
-     */
-    limit1?: number;
-    /**
-     * Second limit for the context.
-     */
-    limit2?: number;
-    /**
-     * Record for the context.
-     */
-    record?: Entity;
-    /**
-     * Records for the context.
-     */
-    records?: Entity[];
-    /**
-     * Query for the context.
-     */
-    query?: ConceptFilter;
-    /**
-     * Whether to return a SavedSet entity when a folder is dropped.
-     */
-    preferSavedSet?: boolean;
-};
-
 declare type PathOption = {
     path: string;
     os_parent_folder?: never;
 };
 
+/** Options for peeking into a source-backed file (e.g. a zip). */
+export declare interface PeekSourceOptions {
+    /** Path inside the source to list. Defaults to '/' (the source root). */
+    inner?: string;
+}
+
+/**
+ * Address a source by either workspace path or entity_id (exactly one).
+ * The frontend usually has an entity_id from the workspace tree and skips
+ * the path-resolution dance; the path form remains for shell-style callers.
+ */
+export declare type PeekSourceTarget = {
+    path: string;
+    entity_id?: never;
+} | {
+    path?: never;
+    entity_id: string;
+};
+
 /**
  * @beta
  * Type representing a permission for a workspace item.
@@ -3144,6 +3849,22 @@ export declare type Permission = WorkspaceItem & {
     os_flags?: number;
 };
 
+/** Write-only credential blob a user PUTs for their own per-user access. */
+export declare interface PerUserCredentialInput {
+    username: string;
+    password: string;
+    domain?: string | null;
+}
+
+/** Metadata-only status of a user's saved per-user credential — never the secret. */
+export declare interface PerUserCredentialStatus {
+    set: boolean;
+    cred_type: CredType | null;
+    created_at: string | null;
+    last_updated_at: string | null;
+    last_used_at: string | null;
+}
+
 /**
  * @beta
  * Type representing a point in 2D space.
@@ -3155,6 +3876,44 @@ export declare type Point = {
     y: number;
 };
 
+export declare type PrincipalType = 'user' | 'role';
+
+/**
+ * Fragment-tree completion payload persisted by the backend's debounced
+ * recursive-rollup job. Returned in-line as
+ * {@link ProcessingStatus.detailed_status} for any entity whose subtree
+ * has been rolled up at least once. Mirrors
+ * `app/api/v1/pipeline/processing_status_models.py::ProcessingRecursiveStatus`.
+ * @beta
+ */
+export declare interface ProcessingRecursiveStatus {
+    total_indexed: number;
+    total_terminal: number;
+    total_running: number;
+    total_missing: number;
+    total_failed: number;
+    known_floor: number;
+    remaining_floor: number;
+    fully_complete: boolean;
+    tree_live: boolean;
+    has_missing_branches: boolean;
+    partial: boolean;
+    /**
+     * Sparse rollup-effective status code override.
+     * Consumers should compute the effective status as
+     * `detailed_status?.status_code ?? status_code`.
+     */
+    status_code?: ProcessingStatusCode;
+    /**
+     * Fragments left by PRIOR pipeline runs that the latest run did not
+     * re-create. They remain indexed and searchable in full — this count only
+     * flags that they are NOT counted toward this (last-run-scoped) completion
+     * rollup. Sparse: present only when > 0. Cleared by a reprocess that
+     * re-creates the whole tree, or by an explicit fragment cleanup.
+     */
+    orphaned_prior_fragments?: number;
+}
+
 /**
  * Represents the status of a processing operation.
  * @beta
@@ -3169,41 +3928,70 @@ export declare interface ProcessingStatus extends EntityBase {
      * The timeout for the processing operation.
      */
     timeout: number;
+    /**
+     * Number of direct child fragments declared by this entity. Used by the
+     * recursive rollup to detect declared-but-not-yet-indexed children.
+     */
+    n_child_fragments?: number;
+    /**
+     * UID of the global root this entity belongs to (the originally fragmented
+     * entity). `undefined` for global roots themselves.
+     */
+    source_entity_uid?: string;
+    /**
+     * UID of the direct parent in the fragment tree. `undefined` for global
+     * roots. Mirrors `document_fields.os_parent_uid`; pair with
+     * `source_entity_uid` on every fragment write.
+     */
+    os_parent_uid?: string;
+    /**
+     * UID of the workspace this entity belongs to. Mirrors
+     * `document_fields.os_workspace`. Set
+     * on every status write (roots and fragments).
+     */
+    os_workspace?: string;
+    /**
+     * Persisted recursive rollup for the root's fragment subtree.
+     * Always returned in-line by `/api/v1/pipeline/processing-status/get`
+     * when the debounced rollup job has written it; there is no separate
+     * "ask for recursive numbers" request flag.
+     */
+    detailed_status?: ProcessingRecursiveStatus;
+    /**
+     * SHA-256 of the canonical serialization of `detailed_status`. Used by the
+     * backend scripted update to short-circuit no-op writes.
+     */
+    detailed_status_hash?: string;
+    /**
+     * Per-fragment error entries collected by the recursive rollup.
+     * Each entry mirrors the offending fragment's `processing_status`
+     * (reason, status_code, timestamp, plus identity fields).
+     */
+    fragment_errors?: FragmentStatusEntry[];
+    /**
+     * Per-fragment warning entries collected by the recursive rollup
+     * (e.g. lenient-defragmentation gaps). Combine with `warnings` to
+     * get the user-facing total.
+     */
+    fragment_warnings?: FragmentStatusEntry[];
+    /**
+     * Warning entries raised on this entity's own processing (excluding
+     * its fragments). Pair with `fragment_warnings` for the total.
+     */
+    warnings?: FragmentStatusEntry[];
 }
 
 /**
- * Possible statuses of a NiFi pipeline task.
+ * Processing status codes returned for indexed / pipeline processing state.
  * @beta
  */
 export declare enum ProcessingStatusCode {
-    /** Queued and awaiting execution */
-    QUEUED = "QUEUED",
-    /** Currently running */
     RUNNING = "RUNNING",
-    /** Stopped manually */
-    STOPPED = "STOPPED",
-    /** Paused and can be resumed */
-    PAUSED = "PAUSED",
-    /** Completed successfully */
     COMPLETED = "COMPLETED",
-    /** Encountered a failure */
     FAILED = "FAILED",
-    /** Scheduled to run */
-    SCHEDULED = "SCHEDULED",
-    /** Starting up */
-    STARTING = "STARTING",
-    /** Shutting down */
-    STOPPING = "STOPPING",
-    /** Disabled and cannot run */
-    DISABLED = "DISABLED",
-    /** Invalid configuration */
-    INVALID = "INVALID",
-    /** Waiting for an external event */
-    WAITING = "WAITING",
-    /** Retrying after failure */
-    RETRYING = "RETRYING",
-    /** Status is unknown */
-    UNKNOWN = "UNKNOWN"
+    UNKNOWN = "UNKNOWN",
+    CANCELED = "CANCELED",
+    PARTIALLY_COMPLETED = "PARTIALLY_COMPLETED"
 }
 
 /**
@@ -3211,13 +3999,13 @@ export declare enum ProcessingStatusCode {
  */
 export declare type PromptOptions = {
     noThink?: boolean;
-    model?: string;
-    apiKey?: string;
-    stream?: boolean;
-    enableRag?: boolean;
-    cohereKey?: string;
     temperature?: number;
-    /** Importing Entity from model.ts breaks the build. */
+    /**
+     * Deprecated — completion mode does not fetch entity content. Passing a
+     * non-empty array throws at runtime. Kept in the type only so legacy
+     * callers in the Fusion subtree (broken, pending refactor) still compile.
+     * Importing Entity from model.ts breaks the build.
+     */
     context?: {
         entity_id: string;
         entity_label: string;
@@ -3242,6 +4030,10 @@ export declare interface Property {
      * The type of the property.
      */
     property_type: string;
+    /**
+     * The display label from the ontology schema.
+     */
+    label?: OntologyLabel;
 }
 
 /**
@@ -3278,6 +4070,16 @@ export declare type QueryBatchResult<T> = (QuerySuccessResult<T> | QueryErrorRes
     query_id: string;
 };
 
+/**
+ * @beta
+ * An opaque Elasticsearch query-DSL fragment. Previously imported from
+ * `@elastic/elasticsearch`, but that type is an `any`-sea and pulling the whole
+ * ES client (with its OpenTelemetry/undici transitive advisories) into the dev
+ * tree to type a single field wasn't worth it — consumers treat `query`
+ * opaquely (see content-browser queryComposition.ts / createEmbeddingFilter.ts).
+ */
+export declare type QueryDslQueryContainer = Record<string, unknown>;
+
 /**
  * @beta
  * Type representing an error query result.
@@ -3303,6 +4105,35 @@ export declare type QueryExecutor = {
     sendQuery: (query: Query, options?: SendQueryOptions) => Promise<QueryResponse>;
 };
 
+/**
+ * Filtered listing of `os_wsfs_object` rows via ontology (not from hydrated workspace.items).
+ * Supply at least one of `contentTypes`, `nameLikeLower`, `labelLikeLower` or `itemTypes`; with
+ * none it returns `[]`.
+ */
+export declare type QueryFilesystemItemsParams = {
+    workspaceIds: string[];
+    /** OR: os_item_content_type equals one of these */
+    contentTypes?: string[];
+    /** OR: lower(os_item_name) LIKE pattern (SQL LIKE, e.g. '%.odoc') */
+    nameLikeLower?: string[];
+    /** OR: lower(entity_label) LIKE pattern, for the name a row displays when it has a label */
+    labelLikeLower?: string[];
+    /** AND: os_item_type is one of these (`['os_file']` leaves folders out); enough on its own.
+     * Applied before `limit`, so excluded rows don't use up the cap. */
+    itemTypes?: string[];
+    /**
+     * Cap the rows returned, most-recently-updated first (the listing is always
+     * `ORDER BY os_last_updated_at DESC`).
+     *
+     * Unbounded by default because the pickers want the whole set. Pass it for any
+     * high-cardinality listing — the query selects every concept field and the
+     * workspace list is a fan-out, so an uncapped Files or Records section would
+     * pull every matching row of every workspace into memory. A caller that caps
+     * is showing a subset and should say so in its UI.
+     */
+    limit?: number;
+};
+
 /**
  * @beta
  * A union type that represents all possible filter clauses in a query object.
@@ -3322,11 +4153,6 @@ export declare type QueryResponse = any[];
  */
 export declare type QueryResult = ApiResult<any[]>;
 
-declare type QueryResult_2 = {
-    language: string;
-    query: string;
-};
-
 /**
  * @beta
  * Type representing a successful query result.
@@ -3357,6 +4183,15 @@ export declare type ReactNode = any;
  */
 export declare type ReactRef<T> = RefCallback<T> | RefObject<T> | null;
 
+/** The distinct candidate keys of a step-one response, own first. */
+export declare function readImageLabelCandidates(aggregations: Record<string, unknown> | undefined): string[];
+
+/** The non-zero counts of a step-two response, largest first, at most `size`. */
+export declare function readImageLabelCounts(aggregations: Record<string, unknown> | undefined, size: number): Array<{
+    key: string;
+    count: number;
+}>;
+
 /**
  * Represents a boolean value with an optional reason.
  * @beta
@@ -3368,17 +4203,6 @@ export declare type ReasonedBoolean = {
     reason: string;
 };
 
-export declare interface RecordData extends ChartDataResponseResult {
-    data: Record<string, any>[];
-}
-
-export declare type RecordFetchOptions = {
-    all_columns: string[];
-    order_by_cols: string[];
-    row_limit: number;
-    server_page_length: number;
-};
-
 /**
  * Interface for providing records.
  * @beta
@@ -3408,6 +4232,19 @@ export declare interface RecordProvider {
     getMessage: () => Promise<string | undefined>;
 }
 
+/**
+ * Which per-source bucket of a workspace's records to act on.
+ *
+ * `source_name` is the exact import origin; `null` targets the records that
+ * carry none (the "(No source)" bucket). Absent is not a value here — an
+ * unscoped bulk delete is a different call.
+ */
+export declare interface RecordsSourceScope {
+    source_name: string | null;
+    /** Narrow to one concept hierarchy inside the bucket, e.g. `Person`. */
+    concept?: string;
+}
+
 /**
  * @beta
  * Type representing a React ref callback.
@@ -3424,6 +4261,41 @@ export declare interface RefObject<T> {
     readonly current: T | null;
 }
 
+/**
+ * Serializable descriptor of a host-registered context-menu action — the
+ * subset of {@link DesktopActionMenuItem} that survives a structured-clone
+ * round-trip across the event-emitter bridge. Returned by
+ * {@link Desktop.getRegisteredActions} so micro-frontends can render their
+ * own group submenus ("Open with…", "Add to…", …) without taking a
+ * dependency on the host's registry.
+ *
+ * The `invoke` callback lives only in the host — call
+ * {@link Desktop.invokeRegisteredAction} with `key` to fire it.
+ * @beta
+ */
+export declare type RegisteredActionInfo = {
+    /** Stable identifier of the underlying registered action. Pass back
+     * to {@link Desktop.invokeRegisteredAction} to invoke. */
+    key: string;
+    /** Display label as registered. Always coerced to a string here
+     * (React-node labels are not serialisable across the bridge). */
+    label: string;
+    /** Icon hint — either a font-icon name or the full {@link IconProps}. */
+    icon?: Icon;
+    /** Group the action was registered under. Callers narrow by passing a
+     * specific group list to {@link Desktop.getRegisteredActions}. */
+    group: ContextMenuGroup;
+    /** Lower order = first in the rendered list. */
+    order?: number;
+    /** Builtin opener key when the action declares one (mirrors the host's
+     * `DesktopActionOptions.with` matching). Optional. */
+    with?: string;
+    /** App-service identifier when the action was registered by an app. */
+    service?: string;
+    /** AI description from the app manifest, when present. */
+    aiDescription?: string;
+};
+
 /**
  * Represents a relationship between concepts.
  * @beta
@@ -3445,6 +4317,10 @@ export declare interface Relationship {
      * Name of the relationship.
      */
     relationship_name: string;
+    /**
+     * The display label from the ontology schema.
+     */
+    label?: OntologyLabel;
     /**
      * Inverse name of the relationship.
      */
@@ -3478,13 +4354,13 @@ export declare interface Relationship {
      */
     mapping_json: string;
     /**
-     * Indicates if the relationship is inverse (1 for true, 0 for false).
+     * Indicates if the relationship is inverse (1 for true, 0 for false). Numeric only at the API.
      */
     is_inverse: number;
     /**
      * Indicates if the relationship is many-to-many (1 for true, 0 for false).
      */
-    is_mtm: number;
+    is_mtm: number | boolean;
     /**
      * Transitivity property of the relationship.
      */
@@ -3503,6 +4379,25 @@ export declare interface Relationship {
     description?: string;
 }
 
+/**
+ * @beta
+ * Type representing a relationship count together with its completeness.
+ */
+export declare type RelationshipCountEntry = {
+    /** The count, `null` if and only if `state` is `'unknown'`. */
+    value: number | null;
+    /** How complete the count is. */
+    state: RelationshipCountState;
+    /** How the count was derived. */
+    precision?: string;
+    /** The part of the count contributed by workspace-local relationships. */
+    workspace_value?: number;
+    /** The guaranteed lower bound of the count. */
+    at_least: number;
+    /** Stored records behind `value`; `null` when `value` is, absent from servers that predate it. */
+    record_count?: number | null;
+};
+
 /**
  * @beta
  * Type representing the result of a relationship count operation.
@@ -3514,6 +4409,12 @@ export declare type RelationshipCountResult = {
     expired?: boolean;
 };
 
+/**
+ * @beta
+ * Type representing how complete a relationship count is.
+ */
+export declare type RelationshipCountState = 'ok' | 'partial' | 'unknown';
+
 export declare type RemoteAppApi = {
     subscribeToContext: SubscribeToContextFn;
     unsubscribeFromContext: UnsubscribeFromContextFn;
@@ -3534,11 +4435,90 @@ export declare type RenameTabProps = {
     newName: string;
 };
 
+/**
+ * @beta
+ * Union of every shape a template lookup may return:
+ * - workspace-stored `SavedTemplate` (rendered via `react-live`),
+ * - code-resident `DefaultTemplate` (rendered as a real React component),
+ * - in-memory `CustomTemplate` produced by `newCustomTemplate()` before
+ *   it has been persisted.
+ *
+ * `SavedTemplate ⊂ CustomTemplate`, so this is structurally equivalent
+ * to `CustomTemplate | DefaultTemplate`; the explicit list is kept for
+ * readability.
+ */
+export declare type RenderableTemplate = SavedTemplate | DefaultTemplate | CustomTemplate;
+
+/**
+ * @beta
+ * Report / Composer integration API (Octostar app).
+ */
+export declare interface ReportApi {
+    /**
+     * Lists .odoc reports that are currently open (tabs and/or Composer sidebar), with metadata.
+     */
+    getOpenReportSummaries: () => Promise<OpenReportSummary[]>;
+    /**
+     * Lists .odoc files in open workspaces (same discovery as Composer empty state).
+     */
+    listWorkspaceReports: () => Promise<WorkspaceItem[]>;
+    /**
+     * Opens the shared "Add to report" modal.
+     *
+     * Supported payload modes:
+     * - `entity`/default: pick target, choose the usual checkboxes, and append a snapshot of an entity.
+     * - `blocks`: pick target, then append arbitrary TipTap JSON blocks directly.
+     */
+    presentAddToReportFlow: (input: AddToReportInput) => Promise<AddToReportResult | void>;
+}
+
+/**
+ * @beta
+ * Minimal TipTap/ProseMirror JSON node shape used by the report append APIs.
+ *
+ * This intentionally mirrors the recursive JSON structure without depending on TipTap packages
+ * from the public platform-types package.
+ */
+export declare type ReportTiptapNode = {
+    type?: string;
+    attrs?: Record<string, unknown>;
+    text?: string;
+    marks?: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    }[];
+    content?: ReportTiptapNode[];
+};
+
 declare type RootOption = {
     path?: never;
     os_parent_folder?: never;
 };
 
+/** {@link RuntimeAppUrlWorkspaceItem} for the raw `Entity` shape (e.g. the
+ *  synthetic iframe-transform items built in the job services). Same
+ *  runtime-only `#appUrl` contract — never persisted, never read off a
+ *  restored item. */
+export declare type RuntimeAppUrlEntity = Entity & {
+    '#appUrl'?: string;
+};
+
+/**
+ * A `WorkspaceItem` carrying the app's resolved iframe URL on the runtime-only
+ * `#appUrl` field.
+ *
+ * IMPORTANT: `#appUrl` is **runtime-only and never persisted**. It is hydrated
+ * in-memory from the K8s apps API (e.g. by `DesktopAPI.getApp` /
+ * `hydrateWithK8sState`) and is **stripped on any JSON round-trip** — notably
+ * the flexlayout tab-config serialization. Never read `#appUrl` off an item
+ * that was restored or deserialized; resolve the live URL via
+ * `useAppDeploymentState` instead. `os_item_content.app_url` no longer carries
+ * the URL — it is gone.
+ */
+export declare type RuntimeAppUrlWorkspaceItem = WorkspaceItem & {
+    '#appUrl'?: string;
+};
+
 export declare interface S3Headers {
     key: string;
     policy: string;
@@ -3580,45 +4560,9 @@ export declare type SaveAsModalProps = {
     omitFilename?: boolean;
 };
 
-export declare const SAVED_SEARCH_MESSAGE_TYPES: Readonly<{
-    getRecordsCount: "octostar:savedSearch:getRecordsCount";
-    getRecordsCountQuery: "octostar:savedSearch:getRecordsCountQuery";
-    getRecords: "octostar:savedSearch:getRecords";
-    getRecordsQuery: "octostar:savedSearch:getRecordsQuery";
-    getSavedSearchPasteContext: "octostar:savedSearch:getSavedSearchPasteContext";
-}>;
-
-export declare const SAVED_SEARCH_PREFIX = "octostar:savedSearch:";
-
-export declare interface SavedDatasource {
-    uid: string;
-    id: number;
-    name?: string;
-    table_name: string;
-    type: string;
-    main_dttm_col: string;
-}
-
-export declare interface SavedSearchAPIInterface {
-    getRecordsCount: (savedSearchIdn: WorkspaceItemIdentifier<SavedSearchContent>) => Promise<BigNumber | number | null>;
-    getRecordsCountQuery: (savedSearchIdn: WorkspaceItemIdentifier<SavedSearchContent>) => Promise<number | null>;
-    getRecords: (savedSearchIdn: WorkspaceItemIdentifier<SavedSearchContent>, options?: Partial<RecordFetchOptions>) => Promise<RecordData | null>;
-    getRecordsQuery: (savedSearchIdn: WorkspaceItemIdentifier<SavedSearchContent>, options?: RecordFetchOptions) => Promise<QueryResult_2 | null>;
-    getSavedSearchPasteContext: (savedSearchIdn: WorkspaceItemIdentifier<SavedSearchContent>) => Promise<EntityPasteContext>;
-}
-
-export declare interface SavedSearchContent {
-    concept: string;
-    dataset: true;
-    filters: Filter[];
-    crossFilters: DataMask[];
-    datasourcesInScope: Record<string, SavedDatasource>;
-    initialCount?: number;
-}
-
 export declare interface SavedSetContent {
     lastFiredQuery: string;
-    uiState: Record<string, any>;
+    uiState: Record<string, unknown>;
 }
 
 /**
@@ -3630,8 +4574,6 @@ export declare type SavedTemplate = CustomTemplate & {
     os_entity_uid: string;
     /** The workspace to which the template belongs. */
     os_workspace: string;
-    /** The CSS content of the template. */
-    css_content?: string;
 };
 
 /**
@@ -3650,10 +4592,6 @@ export declare type SaveFileOptions = {
  * @beta
  */
 export declare type SaveOptions = SaveFileOptions & {
-    /**
-     * Whether to save as a draft.
-     */
-    draft?: boolean;
     /**
      * Whether to save as a new file.
      */
@@ -3668,12 +4606,69 @@ export declare type SaveOptions = SaveFileOptions & {
  * @beta
  * Type representing the search filter.
  */
-export declare type SearchFilter = {
+export declare interface SearchFilter {
     label?: string;
     entity?: Entity;
     query?: QueryDslQueryContainer;
     imageUrl?: string;
-};
+    /**
+     * Optional long-form descriptor for this filter. Chips in the UI use
+     * the short `label` on their face and surface `tooltip` in a hover
+     * tooltip — useful when the label alone is ambiguous (for example a
+     * "Folder: Reports" chip whose `tooltip` disambiguates to the full
+     * breadcrumb "WorkspaceName / Projects / 2025 / Reports").
+     */
+    tooltip?: string;
+    /**
+     * Optional classification of how this filter participates in the final
+     * Elasticsearch query. Filters tagged `'scope'` (i.e. those produced by
+     * "Open with the Search Engine" or by dropping items onto search-app) are
+     * combined with OR (`bool.should`); other kinds combine with AND
+     * (`bool.must`). When omitted, the filter behaves as a `bool.must` clause
+     * for backwards compatibility.
+     */
+    kind?: 'scope' | 'concept' | 'text' | 'image';
+    /**
+     * When `true`, this filter is a **hard browsing scope** that must survive a
+     * facet's self-exclusion: it represents the universe the user opened into
+     * (e.g. the "Files" or "Records" section they launched the Search Engine
+     * from), not a pivotable facet pick. Normally an AND-combined (`'concept'`)
+     * filter whose query references a facet's own field is dropped from that
+     * facet's bucket counts so the user can pivot between sibling values; a
+     * pinned scope is kept regardless, so the by-type facet stays constrained to
+     * the section you opened. No effect on OR-combined (`'scope'`) filters, which
+     * already survive self-exclusion. Defaults to unpinned.
+     */
+    pinned?: boolean;
+}
+
+/**
+ * One raw engine hit, the subset of the ES/OpenSearch hit shape Octostar
+ * reads. Lives here — not in a UI package — because both the Content
+ * Browser and the app's search layer consume the same hits; the UI
+ * package re-exports it for back-compat.
+ */
+export declare interface SearchHit {
+    _id: string;
+    _index?: string;
+    _score?: number;
+    _source: Record<string, unknown>;
+    highlight?: Record<string, string[]>;
+    inner_hits?: Record<string, {
+        hits: {
+            total?: {
+                value: number;
+                relation: 'eq' | 'gte';
+            } | number;
+            hits: SearchInnerHit[];
+        };
+    }>;
+}
+
+export declare interface SearchInnerHit {
+    _score?: number | null;
+    _source?: Record<string, unknown>;
+}
 
 /**
  * @beta
@@ -3685,6 +4680,36 @@ export declare interface SearchOptions {
      */
     limit?: number;
     workspace_ids?: string[];
+    /** Cheaper than listing everywhere-else; neither grants access. */
+    exclude_workspace_ids?: string[];
+    /**
+     * Entity types to exclude.
+     */
+    exclude_entity_types?: string[];
+    /**
+     * Narrow to these types. {@link limit} is applied on `_score` alone, so without
+     * this a broad term spends the whole result set on types the caller discards.
+     */
+    entity_types?: string[];
+    /**
+     * Look up these entities by uid, with an empty query. Treat an absent one as
+     * "ask again".
+     */
+    os_entity_uids?: string[];
+    /**
+     * How wide to match. See {@link SearchScope}.
+     */
+    scope?: SearchScope;
+    /**
+     * Override the response shape. The default ships every field except the heavy
+     * annotation blobs (extracted text, chunks, NER arrays), which is what a hit
+     * list needs; pass this only when a caller genuinely wants something narrower
+     * or one of the excluded keys.
+     */
+    source?: {
+        includes?: string[];
+        excludes?: string[];
+    };
 }
 
 /**
@@ -3708,6 +4733,7 @@ export declare interface SearchProps {
      * the default image to use for the search.
      */
     image?: WorkspaceItem;
+    selectMode?: 'single' | 'multi';
     /**
      * disable ask AI
      */
@@ -3726,6 +4752,30 @@ export declare interface SearchProps {
     searchInfoDescription?: React.ReactNode;
 }
 
+/**
+ * @beta
+ * Represents the result of a query-mode search: the raw Elasticsearch query
+ * plus the total number of matching documents.
+ */
+export declare interface SearchQueryResult {
+    query: Record<string, unknown>;
+    numberOfResults: number;
+}
+
+/**
+ * How wide a text search matches — THE declaration; every other scope type
+ * derives from it (`FinderSearchScope` adds an `'off'` rung on top).
+ *
+ * `names` is a filter-a-list surface: the name only, and also *inside* it
+ * (`atch` → `match.pdf`), which the analyzed tiers cannot do — a hit whose
+ * text mentions the term but whose name does not reads as wrong there.
+ * `names+contents` is the full relevance ladder, extracted text included.
+ *
+ * One value rather than two flags: they were only ever set together, and a
+ * caller asking for substring matching without names-only meant nothing.
+ */
+export declare type SearchScope = 'names' | 'names+contents';
+
 /**
  * @beta
  * Interface representing the properties for the SearchXperienceModal component, extending SearchXperienceProps.
@@ -3794,6 +4844,19 @@ export declare type SemanticBinding = {
     props?: SemanticBindingProps;
 };
 
+/**
+ * @beta
+ * Options of one concept in an app manifest's `semantic_bindings`.
+ */
+export declare interface SemanticBindingOptions {
+    /** Order among the bindings for an entity. Lower comes first. */
+    priority?: number;
+    /** `record_viewer` only: open the tab full screen. */
+    maximized?: boolean;
+    /** Sift-compatible query evaluated against the entity. The binding applies only when it matches. */
+    filter?: Record<string, unknown>;
+}
+
 /**
  * @beta
  * Type representing the properties for a template binding.
@@ -3805,17 +4868,25 @@ export declare interface SemanticBindingProps {
     priority?: number;
     /** Whether the result should be shown in large mode by default */
     maximized?: boolean;
+    /** Sift-compatible query evaluated against the entity. When present, the binding only matches if the filter passes. */
+    filter?: Record<string, any>;
     /** Other properties */
     [key: string]: any;
 }
 
 /**
  * @beta
- * Type representing multiple semantic bindings.
+ * An app manifest's `semantic_bindings`: the bindings per role. The platform reads `opener`
+ * (a double-click on a matching entity opens the app) and `record_viewer` (the app is a Record Viewer tab).
  */
-export declare type SemanticBindings = {
-    [k in SemanticBindingType]: (ConceptName | SemanticBinding)[];
-};
+export declare type SemanticBindings = Partial<Record<SemanticBindingType, SemanticBindingSpec>>;
+
+/**
+ * @beta
+ * The bindings of one role: a concept name, a list of concept names and one-key maps of concept to options,
+ * or a map of concept to options.
+ */
+export declare type SemanticBindingSpec = ConceptName | (ConceptName | Record<ConceptName, SemanticBindingOptions | null>)[] | Record<ConceptName, SemanticBindingOptions | null>;
 
 /**
  * @beta
@@ -3887,58 +4958,48 @@ export declare type ServiceDefinitions = Record<string, ServiceDefinition>;
 export declare type ServiceRole = 'context_menu' | 'record_view' | 'set_view';
 
 export declare type SetsOptions = {
-    /**
-     * Workspace items for the context.
-     */
     workspace_items?: WorkspaceItem[];
-    /**
-     * Limit for the context.
-     */
     limit?: number;
-    /**
-     * Offset for the context.
-     */
     offset?: number;
+    datasource?: 'timbr' | 'opensearch';
     /**
-     * Datasource for the context.
-     */
-    datasource?: string;
-    /**
-     * Recursive for the context.
-     */
-    recursive?: boolean;
-    /**
-     * Include count for the context.
+     * Controls recursion depth for hierarchical expansion.
+     * true = flatten mode (bulk query, all descendants at once).
+     * false = direct children only.
+     * number(N) = incremental expansion up to N levels deep.
      */
+    recursive?: boolean | number;
     include_count?: boolean;
-    /**
-     * Include root for the context.
-     */
     include_root?: boolean;
-    /**
-     * Include all fields for the context.
-     */
     include_all_fields?: boolean;
-    /**
-     * OS exact concept filter for the context.
-     */
-    os_exact_concept_filter?: string[];
-    /**
-     * When limit1 and limit2 are provided,
-     * the user will be prompted to choose the number of records to add
-     * if the count is greater than limit1.
-     */
+    include_types?: string[];
+    exclude_types?: string[];
+    expand_types?: string[];
+    no_expand_types?: string[];
+    /** UI-only prompt threshold. */
     limit1?: number;
-    /**
-     * When limit1 and limit2 are provided,
-     * the user will be prompted to choose the number of records to add
-     * if the count is greater than limit1.
-     */
+    /** UI-only prompt threshold. */
     limit2?: number;
+    workspace_sidebar_set?: boolean;
+    expand_abstract_sets_recursively?: boolean;
+    deduplicate?: boolean;
+    sort_by?: SetsSortBy[];
+};
+
+export declare type SetsSortBy = {
+    field: string;
+    direction: 'asc' | 'desc';
 };
 
 export declare type SetTransformResultFn = (args: any[]) => Promise<void>;
 
+export declare interface SharedCredentialsInput {
+    cred_type?: CredType;
+    username: string;
+    password: string;
+    domain?: string | null;
+}
+
 /**
  * @beta
  * Type representing the details of an ontology to be shown.
@@ -3993,138 +5054,97 @@ export declare enum SortOrder {
     HIDE = -1
 }
 
+/** A per-entry failure surfaced in the bulk-export response. */
+export declare interface SourceExportError {
+    inner_path: string;
+    reason: string;
+}
+
 /**
- * @beta
- * Options for streaming JSON line data from an API.
+ * Request body for `POST /api/v1/files/source/export/{ws}` — bulk export of
+ * multiple inner paths (files and/or folders) from a source-backed archive
+ * into a workspace folder. Folders expand recursively server-side; dedup and
+ * the two-phase folder-then-file upsert also happen server-side.
  */
-export declare interface StreamJsonOptions<T> extends FetchOptions {
-    /**
-     * The asynchronous function to process each JSON object.
-     */
-    jsonHandler: (value: T) => Promise<void>;
+export declare interface SourceExportRequest {
+    entity_id: string;
+    inner_paths: string[];
+    target_parent_folder: string;
 }
 
 /**
- * @beta
- * Options for streaming text data from an API.
+ * Response from `POST /api/v1/files/source/export/{ws}`. `errors[]` collects
+ * per-file failures that did NOT abort the batch (folder-phase failures
+ * abort with a 4xx/5xx instead of surfacing here).
  */
-export declare interface StreamTextOptions extends FetchOptions {
-    /**
-     * The asynchronous function to process each line of text.
-     */
-    handler: (line: string) => Promise<void>;
+export declare interface SourceExportResponse {
+    created_folder_ids: string[];
+    created_file_ids: string[];
+    errors: SourceExportError[];
 }
 
 /**
- * @beta
- * Type representing a styler with methods for getting G6 node and edge styles.
- * See ColorByType.ts for an example
+ * One entry inside a peeked source (a zip in v1). Mirrors the existing
+ * /list envelope so the same UI components can render it. `source_url` is the
+ * osfs:// URI for this entry — pass it back to peek deeper (for folders), or
+ * use it as `os_source_url` when exporting to the workspace (v2).
  */
-export declare type Styler = {
-    /**
-     * Use this function to modify style of a node from outside the graph.
-     * You can overwrite the style, but DO NOT merge currentStyle or originStyle when returning new styling (or rather styling patch).
-     * This can lead do recursive clone error later on.
-     * Merging with actual style will be handled automatically!
-     * Use them just as a reference:
-     * - @param originStyle for eg original node radius (if its a circural node), so you want to eg multiply it by amount of connections.
-     * - @param currentStyle for eg current node radius (if its a circural node), so you want to eg apply a holor like a heatmap by amount of connections.
-     * @param entity - The entity for which to get the node style.
-     * @param originStyle - The original style (the one passed to node during it's initialization). See '@antv/graphin' -> NodeStyle
-     * @param currentStyle - The current style. See '@antv/graphin' -> NodeStyle
-     * @returns A promise that resolves to the style patch. See '@antv/graphin' -> NodeStyle
-     */
-    getG6NodeStyle?: (entity: Entity, originStyle: TODO, currentStyle: TODO) => Promise<TODO>;
-    /**
-     * Use this function to modify style of a edge from outside the graph.
-     * You can overwrite the style, but DO NOT merge currentStyle or originStyle when returning new styling (or rather styling patch).
-     * This can lead do recursive clone error later on.
-     * Merging with actual style will be handled automatically!
-     * Use them just as a reference, eg edge width to multiply.
-     * @param edge - The edge specification for which to get the edge style.
-     * @param originStyle - The original style (the one passed to edge during it's initialization). See '@antv/graphin' -> EdgeStyle
-     * @param currentStyle - The current style. See '@antv/graphin' -> EdgeStyle
-     * @returns A promise that resolves to the style patch. See '@antv/graphin' -> EdgeStyle
-     */
-    getG6EdgeStyle?: (edge: EdgeSpec, originStyle: TODO, currentStyle: TODO) => Promise<TODO>;
-};
+export declare interface SourcePeekEntry {
+    entity_label: string;
+    is_folder: boolean;
+    is_source_entry?: boolean;
+    '#path': string;
+    source_url: string;
+    os_item_content_type?: string | null;
+    os_content_size?: number | null;
+}
 
 /**
- * @beta
- * Type representing the configuration for a styler.
+ * Response envelope from `GET /api/v1/files/source/list/...`. Lists one
+ * directory level inside a source (zip). `inner_path` is the path that was
+ * listed (`/` for the source root).
  */
-export declare type StylerConfig = StylerOption & {
-    /** The name of the styler configuration. */
-    name: string;
-    /** The description of the styler configuration. */
-    description: string;
-    /** The initialization function for the styler. */
-    init: StylerProducer;
-    /** The optional destroy function for the styler. */
-    destroy?: () => Promise<void>;
-};
+export declare interface SourcePeekResponse {
+    folders: SourcePeekEntry[];
+    files: SourcePeekEntry[];
+    total_folders: number;
+    total_files: number;
+    source_entity_id: string;
+    inner_path: string;
+}
 
 /**
  * @beta
- * Interface representing the context for a styler.
+ * Options for streaming JSON line data from an API.
  */
-export declare interface StylerContext {
-    /** The graph specification. */
-    graph: GraphSpec;
-    /** The selected graph specification. */
-    selected: GraphSpec;
-    /** The ontology API instance. */
-    OntologyAPI: Ontology;
-    /** The desktop API instance. */
-    DesktopAPI: Desktop;
-    /** The event emitter instance. */
-    ee: EventEmitterType;
-    /** The event topic prefix. */
-    eventTopicPrefix: string;
+export declare interface StreamJsonOptions<T> extends FetchOptions {
     /**
-     * @beta
-     * Callback function to be called when the task is complete.
-     * @param x - The styler instance.
+     * The asynchronous function to process each JSON object.
      */
-    onTaskComplete?: (x: Styler) => void;
-    /** Callback function to be called when the task is canceled. */
-    onTaskCanceled?: () => void;
-    /** The task ID associated with the styler. */
-    taskID?: string;
+    jsonHandler: (value: T) => Promise<void>;
 }
 
 /**
  * @beta
- * Type representing a styler definition, which can be one of several specific types.
- */
-export declare type StylerDefinition = JavascriptFileStylerDefinition | JavascriptInlineStylerDefinition;
-
-/**
- * @beta
- * Type representing a collection of styler definitions.
+ * Options for streaming text data from an API.
  */
-export declare type StylerDefinitions = Record<string, StylerDefinition>;
+export declare interface StreamTextOptions extends FetchOptions {
+    /**
+     * The asynchronous function to process each line of text.
+     */
+    handler: (line: string) => Promise<void>;
+}
 
-/**
- * @beta
- * Type representing an option for a styler.
- */
-export declare type StylerOption = {
-    /** The name of the styler option. */
-    name: string;
-    /** The description of the styler option. */
-    description: string;
-};
+export declare type SubscribeDragStartFn = (id: string, callback: Callback<unknown>) => void;
 
 /**
  * @beta
- * Type representing a function that produces a styler.
- * @param context - The context for the styler.
- * @returns A promise that resolves to the styler.
+ * Options for {@link Ontology.subscribe}.
  */
-export declare type StylerProducer = (context: StylerContext) => Promise<Styler>;
-
-export declare type SubscribeDragStartFn = (id: string, callback: Callback<unknown>) => void;
+export declare interface SubscribeOptions {
+    /** Skip notices that are not content changes: processing status, the `#active` flag and entity reads. */
+    contentOnly?: boolean;
+}
 
 export declare type SubscribeToContextFn = (id: string, callback: Callback<unknown>) => void;
 
@@ -4228,10 +5248,10 @@ export declare type TemplateMetadata = {
     style?: ReactCssProperties;
     /** Whether the template renders multiple records. */
     rendersMultipleRecords?: boolean;
-    /** Whether the template is an app. */
-    isApp?: boolean;
     /** details for semantic bindings. These can be app-specific */
     bindings?: SemanticBinding[];
+    /** Optional CSS injected when the template renders. */
+    css_content?: string;
 };
 
 /**
@@ -4246,7 +5266,30 @@ export declare type TemplateType = 'nunjucks' | 'javascript';
  */
 export declare type TemplateVariant = 'antd';
 
-declare type TODO = any;
+/**
+ * Test-connection body. All fields optional: an empty body tests the SAVED
+ * mount config. The override fields let an admin dry-run UNSAVED form edits
+ * before persisting them (octostar-api #785) — their shapes mirror the
+ * corresponding {@link MountCreate} / {@link MountUpdate} fields.
+ */
+export declare interface TestConnectionRequest {
+    credentials_override?: PerUserCredentialInput;
+    host?: string;
+    port?: number | null;
+    share?: string;
+    base_path?: string;
+    scheme?: MountScheme;
+    credential_mode?: CredentialMode;
+}
+
+export declare interface TestConnectionResponse {
+    outcome: TestOutcome;
+    latency_ms?: number | null;
+    details?: string | null;
+}
+
+/** Closed set of test-connection outcomes from the SMB handler. */
+export declare type TestOutcome = 'ok' | 'auth_failed' | 'network_error' | 'permission_denied' | 'not_found';
 
 /**
  * @beta
@@ -4323,6 +5366,41 @@ export declare interface UnzipOptions {
     extract_to_new_folder?: boolean;
 }
 
+/**
+ * Error thrown by `FilesAPIClient.uploadFromUrl` when the API returns a
+ * non-2xx response. Carries the parsed `{ detail.error_code, detail.message }`
+ * envelope (exposed on this object as `code`/`detailMessage`) so callers can
+ * render code-specific messages without re-parsing.
+ */
+export declare interface UploadFromUrlError extends Error {
+    status: number;
+    code?: UploadFromUrlErrorCode | string;
+    detailMessage?: string;
+}
+
+/**
+ * Structured error code returned by /api/v2/files/upload-from-url when the
+ * server-side fetch fails. The string is opaque to the API client; UI code is
+ * expected to map it to a user-friendly message.
+ */
+export declare type UploadFromUrlErrorCode = 'INVALID_URL' | 'SSRF_BLOCKED' | 'UPSTREAM_TIMEOUT' | 'BODY_TOO_LARGE' | 'UPSTREAM_ERROR' | 'NAME_CONFLICT';
+
+export declare interface UploadFromUrlRequest {
+    url: string;
+    filename?: string;
+    os_parent_folder: string;
+    content_type?: string;
+    overwrite?: boolean;
+}
+
+export declare interface UploadFromUrlResponse {
+    entity_id: string;
+    filename: string;
+    content_type: string;
+    byte_count: number;
+    os_parent_folder: string;
+}
+
 export declare interface UploadOptions {
     content_type: string;
     ttl_minutes?: number;
@@ -4349,6 +5427,13 @@ export declare type UserProfile = {
  */
 export declare type uuid = string;
 
+/**
+ * Entries of the general family that mark a kNN vector (one per detected face,
+ * one per image) rather than name what the image shows. The pipeline keeps
+ * them out of the label arrays; a reader of the legacy entries drops them too.
+ */
+export declare const VECTOR_SENTINEL_LABELS: readonly string[];
+
 declare type VectorKey = `vector_${string}_${number}_${string}`;
 
 /**
@@ -4359,49 +5444,6 @@ export declare type VirtualEntity = Entity & {
     '#virtual': true;
 };
 
-export declare type Watcher = {
-    /**
-     * Application ID.
-     */
-    app_id: string;
-    /**
-     * Application name.
-     */
-    app_name: string;
-    /**
-     * Watcher name.
-     */
-    watcher_name: string;
-    /**
-     * Constants for the watcher.
-     */
-    const: [key: string, value: any][];
-    /**
-     * Description of the watcher.
-     */
-    description: string;
-    /**
-     * File associated with the watcher.
-     */
-    file: string;
-    /**
-     * Interval for the watcher.
-     */
-    interval: string;
-    /**
-     * Name of the watcher.
-     */
-    name: string;
-    /**
-     * Parameters for the watcher.
-     */
-    params: [key: string, value: any][];
-    /**
-     * Semantically bound items.
-     */
-    semantically_bound: string[];
-};
-
 /**
  * Represents information about the current user.
  * @beta
@@ -4423,6 +5465,7 @@ export declare type Whoami = {
      * Username of the user.
      */
     username: string;
+    roles?: string[];
     /**
      * Roles of the user.
      */
@@ -4473,26 +5516,6 @@ export declare type WithProgressBarOptions = {
     persistUntilComplete?: boolean;
 };
 
-/**
- * @beta
- * Type representing a workspace.
- */
-export declare type Workspace = {
-    /** The workspace item. */
-    workspace: WorkspaceItem;
-    /** The items in the workspace. */
-    items: WorkspaceItems;
-    /** Optional records in the workspace. */
-    workspace_records?: WorkspaceRecords;
-    /** Optional tags in the workspace. */
-    tags?: TagInfo[];
-    /** Optional permission for the workspace. */
-    permission?: WorkspacePermission;
-    /** Whether the workspace is active. */
-    isActive?: boolean;
-    os_flags?: number;
-};
-
 /**
  * @beta
  * Interface representing a workspace change emitter.
@@ -4504,7 +5527,7 @@ export declare interface WorkspaceChangeEmitter {
      * @param callback - The callback to invoke on changes.
      * @returns A promise that resolves to an unsubscribe function.
      */
-    onWorkspaceChanged: (ws: WorkspaceIdentifier, callback: Callback<Workspace>) => Promise<Unsubscribe>;
+    onWorkspaceChanged: (ws: WorkspaceIdentifier, callback: Callback<WorkspaceItem>) => Promise<Unsubscribe>;
     /**
      * Subscribes to changes for a given workspace item.
      * @param item - The workspace item identifier.
@@ -4517,7 +5540,7 @@ export declare interface WorkspaceChangeEmitter {
      * @param callback - The callback to invoke with the current open workspaces.
      * @returns A promise that resolves to an unsubscribe function.
      */
-    onOpenWorkspacesChanged: AddListener<Workspace[]>;
+    onOpenWorkspacesChanged: AddListener<WorkspaceItem[]>;
 }
 
 /**
@@ -4538,9 +5561,14 @@ export declare type WorkspaceConfig = Partial<{
      */
     color: string;
     /**
-     * ID of the workspace.
+     * ID of the workspace. The server accepts only the caller's own personal
+     * workspace id; omit it and the server mints the id.
      */
     entity_id?: string;
+    /**
+     * Ontology concept to create. Defaults to 'os_workspace'.
+     */
+    entity_type?: string;
     /**
      * Whether to create the workspace quietly, without opening it.
      */
@@ -4599,6 +5627,41 @@ export declare type WorkspaceItem<T = any> = WorkspaceRecord & {
      * Whether the item has an attachment file content.
      */
     os_has_attachment?: boolean;
+    /**
+     * The source entity uid of the item.
+     */
+    source_entity_uid?: string;
+    /**
+     * The fragment keyframe number of the item.
+     */
+    fragment_keyframe_number?: number;
+    /**
+     * The source entity type of the item.
+     */
+    source_entity_type?: string;
+    /**
+     * The fragment page number of the item.
+     */
+    fragment_page_number?: number;
+    /**
+     * The fragment start: seconds for audio/video collections, a page for
+     * `document_*`, a row for `table_*`. Numbers from the pipeline, strings in
+     * older indexes — resolve through `resolveFragmentLocator`.
+     */
+    fragment_start?: string | number;
+    /**
+     * The fragment end, in the same unit as `fragment_start`.
+     */
+    fragment_end?: string | number;
+    /**
+     * Content type of the original file a fragment chain starts from, not of
+     * the direct parent. Missing on fragments indexed before the API wrote it.
+     */
+    parent_os_item_content_type?: string;
+    /**
+     * The fragment index of the item.
+     */
+    fragment_index?: number;
     /**
      * Optional path from the os_parent_folder or os_workspace to the item.
      * Does not include the item name.
@@ -4614,6 +5677,20 @@ export declare type WorkspaceItem<T = any> = WorkspaceRecord & {
      * Whether the item is readonly or not.
      */
     os_readonly?: boolean;
+    /**
+     * For source-backed files: the `osfs://` URI pointing INTO a parent source
+     * (e.g. a zip). When set, the file's bytes live inside another entity
+     * rather than directly in S3. Streaming GET on `/files/attachments` knows
+     * how to resolve this transparently.
+     */
+    os_source_url?: string;
+    /**
+     * Set by the backend stat path to indicate the file is a peekable source
+     * (zip, ufdr, jar, apk, ipa, epub, …). The UI uses this to decide whether
+     * to surface "Browse contents" and related affordances rather than
+     * re-deriving from content_type + filename extension.
+     */
+    is_peekable_source?: boolean;
 };
 
 /**
@@ -4699,25 +5776,6 @@ export declare type WorkspaceItemModel = {
          * Indicates if the item is in rename mode.
          */
         rename?: boolean;
-        /**
-         * A filter applied to concepts.
-         */
-        query?: ConceptFilter;
-        /**
-         * Function to get the count of entities.
-         * @returns A promise that resolves to the number of entities.
-         */
-        getEntitiesCount?: () => Promise<number>;
-        /**
-         * Function to get the entities.
-         * @param limit - The maximum number of entities to retrieve.
-         * @returns A promise that resolves to an array of entities.
-         */
-        getEntities?: (limit?: number) => Promise<Entity[]>;
-        /**
-         * Determines if the count is shown only when the item is closed.
-         */
-        showCountOnlyWhenClosed?: boolean;
         /**
          * The initial state of the item.
          */
@@ -4726,10 +5784,6 @@ export declare type WorkspaceItemModel = {
          * Indicates if the item should be highlighted.
          */
         highlight?: boolean;
-        /**
-         * Indicates if the item is in draft mode.
-         */
-        draft?: boolean;
         /**
          * Indicates if the item is auto open
          */
@@ -4753,12 +5807,6 @@ export declare type WorkspaceItemModel = {
     os_item_type: string;
 };
 
-/**
- * Represents an array of workspace items.
- * @beta
- */
-export declare type WorkspaceItems = WorkspaceItem[];
-
 /**
  * Properties for workspace item title.
  * @beta
@@ -4771,9 +5819,7 @@ export declare type WorkspaceItemTitleProps = DesktopActionContext & {
     /**
      * Menu options with extra action items.
      */
-    menuOptions?: ContextMenuOptions & {
-        extraActionItems?: DesktopActionMenuItem[];
-    };
+    menuOptions?: ContextMenuOptions;
     /**
      * Whether the item is expanded.
      */
@@ -4841,27 +5887,6 @@ export declare interface WorkspaceRecordIdentifier {
     os_workspace: string;
 }
 
-/**
- * @beta
- * Type representing information about records in a workspace.
- */
-export declare type WorkspaceRecordInfo = {
-    /** The concept associated with the records. */
-    concept: string;
-    /** The count of records. */
-    count: number;
-    /** The last updated timestamp for the records. */
-    max_last_updated: string;
-    /** The entities associated with the records. */
-    entities: Entity[];
-};
-
-/**
- * @beta
- * Type representing a collection of workspace records.
- */
-export declare type WorkspaceRecords = Record<string, WorkspaceRecordInfo>;
-
 /**
  * @beta
  * Type representing a workspace record with its relationships.
@@ -4879,7 +5904,7 @@ export declare type WorkspaceRecordWithRelationships = {
  * Represents a relationship between workspace items.
  * @beta
  */
-export declare type WorkspaceRelationship = WorkspaceItemBase & OsAuditFields & {
+export declare type WorkspaceRelationship = WorkspaceItemBase & Entity & OsAuditFields & {
     /**
      * Unique identifier for the source entity in the relationship.
      */
@@ -4900,6 +5925,10 @@ export declare type WorkspaceRelationship = WorkspaceItemBase & OsAuditFields &
      * Name of the relationship.
      */
     os_relationship_name: string;
+    /**
+     * Inverse name of the relationship.
+     */
+    os_relationship_inverse_name?: string;
 };
 
 /**