@anchrd/intel-ui 0.4.0 → 0.6.0

package/src/branding/favicon.default.svg

@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
   <title>Intel</title>
-  <rect width="32" height="32" rx="8" fill="oklch(0.45 0.17 265)"/>
-  <path d="M10 10h12v12H10zM7 14h3m12 0h3M14 7v3m4-3v3M14 22v3m4-3v3" fill="none" stroke="oklch(0.98 0.01 265)" stroke-width="2" stroke-linecap="round"/>
+  <rect width="32" height="32" rx="8" fill="oklch(0.205 0 0)"/>
+  <path d="M10 10h12v12H10zM7 14h3m12 0h3M14 7v3m4-3v3M14 22v3m4-3v3" fill="none" stroke="oklch(0.985 0 0)" stroke-width="2" stroke-linecap="round"/>
 </svg>

package/src/branding/favicon.svg

@@ -1,5 +1,5 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
   <title>Intel</title>
-  <rect width="32" height="32" rx="8" fill="oklch(0.45 0.17 265)"/>
-  <path d="M10 10h12v12H10zM7 14h3m12 0h3M14 7v3m4-3v3M14 22v3m4-3v3" fill="none" stroke="oklch(0.98 0.01 265)" stroke-width="2" stroke-linecap="round"/>
+  <rect width="32" height="32" rx="8" fill="oklch(0.205 0 0)"/>
+  <path d="M10 10h12v12H10zM7 14h3m12 0h3M14 7v3m4-3v3M14 22v3m4-3v3" fill="none" stroke="oklch(0.985 0 0)" stroke-width="2" stroke-linecap="round"/>
 </svg>

package/src/components/ui/dropdown-menu.tsx

@@ -1,3 +1,4 @@
+import { Check, ChevronRight } from "lucide-react";
 import { DropdownMenu as DropdownMenuPrimitive } from "radix-ui";
 import type * as React from "react";
 import { cn } from "@/lib/utils";
@@ -61,6 +62,78 @@ function DropdownMenuItem({
   );
 }
 
+function DropdownMenuSub({ ...props }: React.ComponentProps<typeof DropdownMenuPrimitive.Sub>) {
+  return <DropdownMenuPrimitive.Sub data-slot="dropdown-menu-sub" {...props} />;
+}
+
+function DropdownMenuSubTrigger({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubTrigger>) {
+  return (
+    <DropdownMenuPrimitive.SubTrigger
+      data-slot="dropdown-menu-sub-trigger"
+      className={cn(
+        "flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-hidden focus:bg-accent focus:text-accent-foreground data-[state=open]:bg-accent data-[state=open]:text-accent-foreground [&_svg]:size-4 [&_svg]:shrink-0",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronRight aria-hidden="true" className="ml-auto" />
+    </DropdownMenuPrimitive.SubTrigger>
+  );
+}
+
+function DropdownMenuSubContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.SubContent>) {
+  return (
+    <DropdownMenuPrimitive.Portal>
+      <DropdownMenuPrimitive.SubContent
+        data-slot="dropdown-menu-sub-content"
+        className={cn(
+          "z-50 min-w-32 origin-(--radix-dropdown-menu-content-transform-origin) overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0",
+          className,
+        )}
+        {...props}
+      />
+    </DropdownMenuPrimitive.Portal>
+  );
+}
+
+function DropdownMenuRadioGroup({
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioGroup>) {
+  return <DropdownMenuPrimitive.RadioGroup data-slot="dropdown-menu-radio-group" {...props} />;
+}
+
+function DropdownMenuRadioItem({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<typeof DropdownMenuPrimitive.RadioItem>) {
+  return (
+    <DropdownMenuPrimitive.RadioItem
+      data-slot="dropdown-menu-radio-item"
+      className={cn(
+        "relative flex cursor-default select-none items-center gap-2 rounded-sm py-1.5 pr-2 pl-8 text-sm outline-hidden focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4 [&_svg]:shrink-0",
+        className,
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-3.5 items-center justify-center">
+        <DropdownMenuPrimitive.ItemIndicator>
+          <Check aria-hidden="true" />
+        </DropdownMenuPrimitive.ItemIndicator>
+      </span>
+      {children}
+    </DropdownMenuPrimitive.RadioItem>
+  );
+}
+
 function DropdownMenuSeparator({
   className,
   ...props
@@ -79,6 +152,11 @@ export {
   DropdownMenuContent,
   DropdownMenuItem,
   DropdownMenuLabel,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
   DropdownMenuSeparator,
+  DropdownMenuSub,
+  DropdownMenuSubContent,
+  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 };

package/src/data/intel-data-provider/intel-data-provider.ts

@@ -1,28 +1,37 @@
 import {
+  AppendKnowledgeTableRowsInput,
+  AppendKnowledgeTableRowsResult,
   ArchiveKnowledgeNodeInput,
   CompleteFlowRunStepInput,
   CreateFlowInput,
-  CreateKnowledgeLinkInput,
   CreateKnowledgeNodeInput,
-  DeleteKnowledgeLinkInput,
+  DefineKnowledgeTableInput,
   Flow,
   FlowDocument,
   FlowList,
+  FlowPublishPreview,
+  FlowRequirements,
+  FlowRunHistory,
+  FlowRunList,
   FlowRunStep,
   KnowledgeDocument,
   KnowledgeGraph,
-  KnowledgeLink,
   KnowledgeLinkList,
   KnowledgeNode,
   KnowledgeNodeList,
+  KnowledgeTable,
   KnowledgeVersionList,
+  ListFlowRunsInput,
   ListFlowsInput,
   ListKnowledgeNodesInput,
+  PreviewFlowPublishInput,
   ProblemDetails,
   PublishFlowInput,
-  ResourceGrant,
+  RelationGraph,
+  RelationGraphInput,
+  ResolveKnowledgeLinksInput,
+  ResolveKnowledgeLinksResult,
   ResourceGrantList,
-  RevokeFlowGrantInput,
   RevokeGrantResult,
   RevokeKnowledgeGrantInput,
   SaveFlowVersionInput,
@@ -31,17 +40,30 @@ import {
   SearchKnowledgeInput,
   SearchKnowledgeResult,
   SessionUser,
-  ShareFlowInput,
   ShareKnowledgeInput,
+  ShareKnowledgeResult,
   StartFlowRunInput,
   ToolCatalog,
   UpdateFlowInput,
   UpdateKnowledgeNodeInput,
 } from "@anchrd/intel-contract";
-import { z } from "zod";
+import type { z } from "zod";
 import type { IntelDataProvider, TreeEntry } from "./intel-data-provider.types.ts";
 
-const DeleteResult = z.strictObject({ deleted: z.boolean() });
+// ⚠️ The refusal's `code`, not only its prose. A view that has to tell four different refusals
+// apart — "you may not write there", "that is not a folder", "that would be a cycle", "someone
+// else changed it" — cannot do so from `detail`, which is a sentence the server is free to
+// reword. The code is the contract (`ProblemDetails.code`); the message stays what it was.
+export class IntelRequestError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly code: string | null,
+    message: string,
+  ) {
+    super(message);
+    this.name = "IntelRequestError";
+  }
+}
 
 // Attachment uploads and downloads share this budget, so it is generous rather than snappy.
 const RequestTimeoutMs = 60_000;
@@ -51,11 +73,31 @@ export function loginPath(returnTo?: string): string {
   return returnTo ? `/auth/login?returnTo=${encodeURIComponent(returnTo)}` : "/auth/login";
 }
 
+/**
+ * One flow as one row of the tree. Two levels show flows — the contents of a folder, and what an
+ * expanded flow calls — and they are two lists of the same rows, so they are built here once. Two
+ * copies of this would keep returning something plausible and slowly stop agreeing on what a flow
+ * row is (#30).
+ */
+export function flowEntry(flow: Flow): TreeEntry {
+  return { type: "flow", id: flow.id, title: flow.title, kind: "flow", flow };
+}
+
 export function createIntelDataProvider(
-  deps: { fetch?: typeof fetch; baseUrl?: string; onUnauthorized?(): void } = {},
+  deps: {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    onUnauthorized?(): void;
+    navigate?(url: string): void;
+  } = {},
 ): IntelDataProvider {
   const doFetch = deps.fetch ?? fetch;
   const baseUrl = deps.baseUrl?.replace(/\/$/, "") ?? "";
+  const navigate =
+    deps.navigate ??
+    ((url: string) => {
+      if (typeof window !== "undefined") window.location.assign(url);
+    });
   const unauthorized =
     deps.onUnauthorized ??
     (() => {
@@ -86,7 +128,9 @@ export function createIntelDataProvider(
           .json()
           .catch(() => null),
       );
-      throw new Error(
+      throw new IntelRequestError(
+        result.status,
+        parsed.success ? (parsed.data.code ?? null) : null,
         parsed.success
           ? (parsed.data.detail ?? parsed.data.title)
           : `Intel responded with ${result.status}`,
@@ -144,13 +188,7 @@ export function createIntelDataProvider(
           kind: node.kind,
           node,
         })),
-        ...flows.items.map((flow) => ({
-          type: "flow" as const,
-          id: flow.id,
-          title: flow.title,
-          kind: "flow" as const,
-          flow,
-        })),
+        ...flows.items.map(flowEntry),
       ];
       // Folders first, then everything else by title: a document and a flow sit side by side, and
       // the icon is what tells them apart.
@@ -176,21 +214,13 @@ export function createIntelDataProvider(
     async listKnowledgeLinks(nodeId) {
       return await request(`/knowledge/${encodeURIComponent(nodeId)}/links`, KnowledgeLinkList);
     },
-    async createKnowledgeLink(input) {
-      const parsed = CreateKnowledgeLinkInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.sourceNodeId)}/links`,
-        KnowledgeLink,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
-    },
-    async deleteKnowledgeLink(input) {
-      const parsed = DeleteKnowledgeLinkInput.parse(input);
-      return await request(
-        `/knowledge/${encodeURIComponent(parsed.sourceNodeId)}/links/${encodeURIComponent(parsed.linkId)}/revoke`,
-        DeleteResult,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
+    // ⚠️ POST, not GET. The identifiers of the documents a text links to belong in a body: a
+    // query string of them would end up in logs and referrers.
+    async resolveKnowledgeLinks(input) {
+      return await request("/knowledge/links/resolve", ResolveKnowledgeLinksResult, {
+        method: "POST",
+        body: JSON.stringify(ResolveKnowledgeLinksInput.parse(input)),
+      });
     },
     async saveKnowledge(input) {
       const parsed = SaveKnowledgeVersionInput.parse(input);
@@ -211,6 +241,28 @@ export function createIntelDataProvider(
     async getKnowledgeAttachment(nodeId) {
       return await (await response(`/knowledge/${encodeURIComponent(nodeId)}/attachment`)).blob();
     },
+    async getKnowledgeTable(nodeId) {
+      return await request(`/knowledge/${encodeURIComponent(nodeId)}/table`, KnowledgeTable);
+    },
+    async defineKnowledgeTable(input) {
+      const parsed = DefineKnowledgeTableInput.parse(input);
+      return await request(
+        `/knowledge/${encodeURIComponent(parsed.nodeId)}/table`,
+        KnowledgeTable,
+        {
+          method: "POST",
+          body: JSON.stringify(parsed),
+        },
+      );
+    },
+    async appendKnowledgeTableRows(input) {
+      const parsed = AppendKnowledgeTableRowsInput.parse(input);
+      return await request(
+        `/knowledge/${encodeURIComponent(parsed.nodeId)}/table/rows`,
+        AppendKnowledgeTableRowsResult,
+        { method: "POST", body: JSON.stringify(parsed) },
+      );
+    },
     async listKnowledgeVersions(nodeId) {
       return await request(
         `/knowledge/${encodeURIComponent(nodeId)}/versions`,
@@ -248,7 +300,7 @@ export function createIntelDataProvider(
       const parsed = ShareKnowledgeInput.parse(input);
       return await request(
         `/knowledge/${encodeURIComponent(parsed.resourceId)}/grants`,
-        ResourceGrant,
+        ShareKnowledgeResult,
         { method: "POST", body: JSON.stringify(parsed) },
       );
     },
@@ -264,6 +316,30 @@ export function createIntelDataProvider(
     async getFlow(flowId) {
       return await request(`/flows/${encodeURIComponent(flowId)}`, FlowDocument);
     },
+    async listFlowCalls(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/calls`, FlowList);
+    },
+    async getRelationGraph(scope, limit) {
+      const parsed = RelationGraphInput.parse({
+        scope,
+        ...(limit === undefined ? {} : { limit }),
+      });
+      const params = new URLSearchParams({
+        of: parsed.scope.of,
+        limit: String(parsed.limit),
+        // A folder scope without an ID is the root of the shared tree, and an absent parameter is
+        // how that is said — the same distinction `/flows?parentId=` makes.
+        ...(parsed.scope.of === "flow"
+          ? { flowId: parsed.scope.flowId }
+          : parsed.scope.folderId
+            ? { folderId: parsed.scope.folderId }
+            : {}),
+      });
+      return await request(`/flows/graph?${params}`, RelationGraph);
+    },
+    async getFlowRequirements(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/requirements`, FlowRequirements);
+    },
     async createFlow(input) {
       return await request("/flows", Flow, {
         method: "POST",
@@ -277,28 +353,6 @@ export function createIntelDataProvider(
         body: JSON.stringify(parsed),
       });
     },
-    async listFlowGrants(flowId) {
-      return await request(`/flows/${encodeURIComponent(flowId)}/grants`, ResourceGrantList);
-    },
-    async shareFlow(input) {
-      const parsed = ShareFlowInput.parse(input);
-      return await request(
-        `/flows/${encodeURIComponent(parsed.resourceId)}/grants`,
-        ResourceGrant,
-        {
-          method: "POST",
-          body: JSON.stringify(parsed),
-        },
-      );
-    },
-    async revokeFlowGrant(input) {
-      const parsed = RevokeFlowGrantInput.parse(input);
-      return await request(
-        `/flows/${encodeURIComponent(parsed.resourceId)}/grants/${encodeURIComponent(parsed.grantId)}/revoke`,
-        RevokeGrantResult,
-        { method: "POST", body: JSON.stringify(parsed) },
-      );
-    },
     async saveFlow(input) {
       const parsed = SaveFlowVersionInput.parse(input);
       return await request(`/flows/${encodeURIComponent(parsed.flowId)}/versions`, FlowDocument, {
@@ -306,6 +360,13 @@ export function createIntelDataProvider(
         body: JSON.stringify(parsed),
       });
     },
+    async previewFlowPublish(input) {
+      const parsed = PreviewFlowPublishInput.parse(input);
+      return await request(
+        `/flows/${encodeURIComponent(parsed.flowId)}/versions/${encodeURIComponent(parsed.versionId)}/publish-preview`,
+        FlowPublishPreview,
+      );
+    },
     async publishFlow(input) {
       const parsed = PublishFlowInput.parse(input);
       return await request(`/flows/${encodeURIComponent(parsed.flowId)}/publish`, Flow, {
@@ -320,9 +381,24 @@ export function createIntelDataProvider(
         body: JSON.stringify(parsed),
       });
     },
+    async listFlowRuns(input) {
+      const parsed = ListFlowRunsInput.parse(input);
+      // Only what was actually asked for travels. `failedOnly` is the parameter's presence rather
+      // than a value, which is the same shape the server reads it back with.
+      const params = new URLSearchParams({ limit: String(parsed.limit) });
+      if (parsed.failedOnly) params.set("failedOnly", "");
+      if (parsed.cursor) params.set("cursor", parsed.cursor);
+      return await request(
+        `/flows/${encodeURIComponent(parsed.flowId)}/runs?${params}`,
+        FlowRunList,
+      );
+    },
     async getFlowRun(runId) {
       return await request(`/flow-runs/${encodeURIComponent(runId)}`, FlowRunStep);
     },
+    async getFlowRunSteps(runId) {
+      return await request(`/flow-runs/${encodeURIComponent(runId)}/steps`, FlowRunHistory);
+    },
     async completeFlowStep(input) {
       const parsed = CompleteFlowRunStepInput.parse(input);
       return await request(`/flow-runs/${encodeURIComponent(parsed.runId)}/complete`, FlowRunStep, {
@@ -334,8 +410,10 @@ export function createIntelDataProvider(
       return await request("/tools", ToolCatalog);
     },
 
-    portalConnectUrl(returnTo = "/tools") {
-      return `${baseUrl}/auth/connect?returnTo=${encodeURIComponent(returnTo)}`;
+    // The Worker serves the connect route, so this navigation belongs to the data layer for the
+    // same reason `loginPath` does. `silent=1` is what makes it a redirect nobody has to watch.
+    startPortalSignIn(returnTo = "/tools") {
+      navigate(`${baseUrl}/auth/connect?returnTo=${encodeURIComponent(returnTo)}&silent=1`);
     },
     async logout() {
       const response = await doFetch(`${baseUrl}/auth/logout`, {

package/src/data/intel-data-provider/intel-data-provider.types.ts

@@ -1,28 +1,37 @@
 import type {
+  AppendKnowledgeTableRowsInput,
+  AppendKnowledgeTableRowsResult,
   ArchiveKnowledgeNodeInput,
   CompleteFlowRunStepInput,
   CreateFlowInput,
-  CreateKnowledgeLinkInput,
   CreateKnowledgeNodeInput,
-  DeleteKnowledgeLinkInput,
+  DefineKnowledgeTableInput,
   Flow,
   FlowDocument,
   FlowList,
+  FlowPublishPreview,
+  FlowRequirements,
+  FlowRunHistory,
+  FlowRunList,
   FlowRunStep,
   KnowledgeDocument,
   KnowledgeGraph,
-  KnowledgeLink,
   KnowledgeLinkList,
   KnowledgeNode,
   KnowledgeNodeKind,
   KnowledgeNodeList,
+  KnowledgeTable,
   KnowledgeVersionList,
+  ListFlowRunsInput,
   ListFlowsInput,
   ListKnowledgeNodesInput,
+  PreviewFlowPublishInput,
   PublishFlowInput,
-  ResourceGrant,
+  RelationGraph,
+  RelationGraphScope,
+  ResolveKnowledgeLinksInput,
+  ResolveKnowledgeLinksResult,
   ResourceGrantList,
-  RevokeFlowGrantInput,
   RevokeGrantResult,
   RevokeKnowledgeGrantInput,
   SaveFlowVersionInput,
@@ -31,8 +40,8 @@ import type {
   SearchKnowledgeInput,
   SearchKnowledgeResult,
   SessionUser,
-  ShareFlowInput,
   ShareKnowledgeInput,
+  ShareKnowledgeResult,
   StartFlowRunInput,
   ToolCatalog,
   UpdateFlowInput,
@@ -55,30 +64,59 @@ export interface IntelDataProvider {
   createKnowledge(input: CreateKnowledgeNodeInput): Promise<KnowledgeNode>;
   getKnowledgeGraph(limit?: number): Promise<KnowledgeGraph>;
   listKnowledgeLinks(nodeId: string): Promise<KnowledgeLinkList>;
-  createKnowledgeLink(input: CreateKnowledgeLinkInput): Promise<KnowledgeLink>;
-  deleteKnowledgeLink(input: DeleteKnowledgeLinkInput): Promise<{ deleted: boolean }>;
+  // The titles of the documents a text links to, for the reader. A target they may not see, or one
+  // that is gone, is absent from the answer — the two look the same on purpose (#41).
+  resolveKnowledgeLinks(input: ResolveKnowledgeLinksInput): Promise<ResolveKnowledgeLinksResult>;
   saveKnowledge(input: SaveKnowledgeVersionInput): Promise<KnowledgeDocument>;
   saveKnowledgeAttachment(input: SaveKnowledgeAttachmentInput): Promise<KnowledgeDocument>;
   getKnowledgeAttachment(nodeId: string): Promise<Blob>;
-  portalConnectUrl(returnTo?: string): string;
+  // A table as columns and rows. The CSV stays canonical — `getKnowledge` still answers with it,
+  // which is what the download uses — and this is the same bytes read by the server's one reader.
+  getKnowledgeTable(nodeId: string): Promise<KnowledgeTable>;
+  defineKnowledgeTable(input: DefineKnowledgeTableInput): Promise<KnowledgeTable>;
+  appendKnowledgeTableRows(
+    input: AppendKnowledgeTableRowsInput,
+  ): Promise<AppendKnowledgeTableRowsResult>;
+  // Walks the browser through the portal's OAuth flow without asking anybody anything: Gate is the
+  // identity provider Cloudflare Access consumes, so a signed-in person is already known there
+  // (#60). It navigates away — the caller renders no button for it and gets no answer back.
+  startPortalSignIn(returnTo?: string): void;
   listKnowledgeVersions(nodeId: string): Promise<KnowledgeVersionList>;
   updateKnowledge(input: UpdateKnowledgeNodeInput): Promise<KnowledgeNode>;
   archiveKnowledge(input: ArchiveKnowledgeNodeInput): Promise<KnowledgeNode>;
   searchKnowledge(input: SearchKnowledgeInput): Promise<SearchKnowledgeResult>;
   listKnowledgeGrants(resourceId: string): Promise<ResourceGrantList>;
-  shareKnowledge(input: ShareKnowledgeInput): Promise<ResourceGrant>;
+  // The grant, and what the grant does not cover: the documents the flows in this folder read that
+  // the new principal still cannot. A warning, never a refusal (ADR-0004 §4).
+  shareKnowledge(input: ShareKnowledgeInput): Promise<ShareKnowledgeResult>;
   revokeKnowledgeGrant(input: RevokeKnowledgeGrantInput): Promise<RevokeGrantResult>;
   listFlows(input?: ListFlowsInput): Promise<FlowList>;
   getFlow(flowId: string): Promise<FlowDocument>;
+  // What a flow calls, read out of its graph. It answers a different question from `listTreeChildren`
+  // and deliberately gives a different answer: a shared sub-flow is listed under every caller.
+  listFlowCalls(flowId: string): Promise<FlowList>;
+  // What accesses what, for one level of the shared tree: a folder for its contents, a flow for
+  // itself. ⚠️ Only nodes the signed-in user may see come back, and one they may not is absent
+  // altogether — never a placeholder, because the edge into one would already say that it exists.
+  getRelationGraph(scope: RelationGraphScope, limit?: number): Promise<RelationGraph>;
+  // What a flow touches: the documents and tools its graph names. Documents the signed-in user may
+  // not see are counted rather than named, and nothing here claims anybody may reach them.
+  getFlowRequirements(flowId: string): Promise<FlowRequirements>;
   createFlow(input: CreateFlowInput): Promise<Flow>;
   updateFlow(input: UpdateFlowInput): Promise<Flow>;
-  listFlowGrants(flowId: string): Promise<ResourceGrantList>;
-  shareFlow(input: ShareFlowInput): Promise<ResourceGrant>;
-  revokeFlowGrant(input: RevokeFlowGrantInput): Promise<RevokeGrantResult>;
   saveFlow(input: SaveFlowVersionInput): Promise<FlowDocument>;
+  // Which version each sub-flow call will take once published, and which of them publishing
+  // freezes. Read before publishing, so the author agrees to the pins rather than discovering them.
+  previewFlowPublish(input: PreviewFlowPublishInput): Promise<FlowPublishPreview>;
   publishFlow(input: PublishFlowInput): Promise<Flow>;
   startFlow(input: StartFlowRunInput): Promise<FlowRunStep>;
+  // What this flow has done, newest first, one page at a time. ⚠️ It carries what a run did and
+  // never what it produced: a run reads Knowledge with the rights of whoever started it, so its
+  // result is not automatically readable for everyone who may read the flow.
+  listFlowRuns(input: ListFlowRunsInput): Promise<FlowRunList>;
   getFlowRun(runId: string): Promise<FlowRunStep>;
+  // The drill-down behind one run: every step it took, and the call chain it belongs to.
+  getFlowRunSteps(runId: string): Promise<FlowRunHistory>;
   completeFlowStep(input: CompleteFlowRunStepInput): Promise<FlowRunStep>;
   // Reading the catalog is the whole of the tool surface here: calling a tool belongs to a flow
   // or to the Intel MCP surface, not to the screen that shows what the portal offers.

package/src/document-link/document-link.tsx

@@ -0,0 +1,132 @@
+import { DocumentLinkInlineType } from "@anchrd/intel-contract";
+import { BlockNoteSchema } from "@blocknote/core";
+import { createReactInlineContentSpec } from "@blocknote/react";
+import { FileText, Link2Off } from "lucide-react";
+import { createContext, useContext } from "react";
+
+/**
+ * What a document link resolves to for the person reading it.
+ *
+ * ⚠️ `titles` holds only the documents this reader may see. A missing entry is the whole answer for
+ * both of the reasons an entry can be missing — the target is gone, or it is not theirs to reach —
+ * and nothing here may ever be given a way to tell those apart. `pending` exists so the editor can
+ * hold back the difference between "not resolved yet" and "does not resolve", which would otherwise
+ * flash a broken link at every reader for one render.
+ */
+export interface DocumentLinkResolution {
+  titles: ReadonlyMap<string, string>;
+  pending: boolean;
+  // The one word an unresolved link says. It travels in the context because a BlockNote inline
+  // element is rendered by the editor rather than by a view that could reach the i18n catalog.
+  unresolvedLabel: string;
+}
+
+const DocumentLinkContext = createContext<DocumentLinkResolution>({
+  titles: new Map(),
+  pending: false,
+  unresolvedLabel: "Unavailable document",
+});
+
+export const DocumentLinkProvider = DocumentLinkContext.Provider;
+
+export function useDocumentLinkResolution(): DocumentLinkResolution {
+  return useContext(DocumentLinkContext);
+}
+
+/**
+ * One document link inside the text (#41).
+ *
+ * ⚠️ The element stores the target's ID and nothing else. A stored title would be wrong the moment
+ * the target is renamed and a stored path the moment it is moved — and both would put a name into a
+ * document that any reader of it could then read, whether or not they may reach the target.
+ *
+ * ⚠️ An unresolved link says that it does not resolve and nothing more: no title, no path, no ID on
+ * screen, no hint of which of the two reasons applies. That is the whole of the leak this feature
+ * could have introduced, and the reason the broken form carries no data at all.
+ */
+export function DocumentLinkText({ nodeId }: { nodeId: string }) {
+  const { titles, pending, unresolvedLabel } = useDocumentLinkResolution();
+  const title = titles.get(nodeId);
+  if (title === undefined) {
+    return (
+      <span
+        data-document-link={pending ? "pending" : "unresolved"}
+        className={
+          pending
+            ? "inline-flex items-center gap-1 rounded-sm px-1 text-muted-foreground"
+            : "inline-flex items-center gap-1 rounded-sm bg-destructive/10 px-1 text-destructive line-through"
+        }
+      >
+        {pending ? null : <Link2Off aria-hidden="true" className="size-3.5" />}
+        {pending ? "…" : unresolvedLabel}
+      </span>
+    );
+  }
+  return (
+    <span
+      data-document-link="resolved"
+      data-node-id={nodeId}
+      className="inline-flex items-center gap-1 rounded-sm bg-muted px-1 text-foreground"
+    >
+      <FileText aria-hidden="true" className="size-3.5" />
+      {title}
+    </span>
+  );
+}
+
+export const documentLinkSpec = createReactInlineContentSpec(
+  {
+    type: DocumentLinkInlineType,
+    propSchema: { nodeId: { default: "" } },
+    // The link has no editable text of its own: what it reads is the target's title, and a title
+    // somebody could type over would stop following the target the first time they did (#41).
+    content: "none",
+  },
+  {
+    render: (props) => <DocumentLinkText nodeId={String(props.inlineContent.props.nodeId)} />,
+  },
+);
+
+// One schema for the editor and for everything that reads its documents back: BlockNote's defaults
+// plus the one inline element #41 adds.
+//
+// ⚠️ `extend` rather than `create({ inlineContentSpecs: { ...defaults, documentLink } })`. Both
+// build the same schema at run time, but only `extend` keeps the added type in the schema's own
+// generics under this repo's `exactOptionalPropertyTypes` — with the spread form the editor infers
+// BlockNote's default schema, typechecks, and then refuses to insert a document link.
+export const intelEditorSchema = BlockNoteSchema.create().extend({
+  inlineContentSpecs: { documentLink: documentLinkSpec },
+});
+
+// The schema carries its own editor and block types as declaration-only properties, which is the
+// only way to name them here: writing `BlockNoteEditor<typeof schema.blockSchema, ...>` by hand
+// fails BlockNote's own constraint under `exactOptionalPropertyTypes`.
+export type IntelEditor = (typeof intelEditorSchema)["BlockNoteEditor"];
+export type IntelEditorPartialBlock = (typeof intelEditorSchema)["PartialBlock"];
+
+/**
+ * The IDs a stored BlockNote document links to.
+ *
+ * The server reads the same thing out of the same content when the document is saved; this side
+ * needs it too, to ask which of them it may show a title for.
+ */
+export function documentLinkIds(blocks: unknown): string[] {
+  const found = new Set<string>();
+  const walk = (value: unknown): void => {
+    if (Array.isArray(value)) {
+      for (const entry of value) walk(entry);
+      return;
+    }
+    if (typeof value !== "object" || value === null) return;
+    const record = value as Record<string, unknown>;
+    if (record.type === DocumentLinkInlineType) {
+      const props = record.props as Record<string, unknown> | undefined;
+      const nodeId = props?.nodeId;
+      if (typeof nodeId === "string" && nodeId.length > 0) found.add(nodeId);
+    }
+    walk(record.content);
+    walk(record.children);
+  };
+  walk(blocks);
+  return [...found];
+}