@anchrd/intel-ui 0.5.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-ui",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -28,7 +28,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@anchrd/intel-contract": "^0.2.0",
+    "@anchrd/intel-contract": "^0.3.0",
     "@blocknote/core": "^0.52.1",
     "@blocknote/react": "^0.52.1",
     "@blocknote/shadcn": "^0.52.1",

package/src/app/action-slot/action-slot.tsx

@@ -10,6 +10,10 @@ import { createPortal } from "react-dom";
 // ⚠️ The slot lives above the component that fills it, so it is not in the document while that
 // component first renders. Looking it up in an effect costs one extra render and is the only order
 // that works; reading it during render finds nothing on the first paint.
+//
+// ⚠️ A portal only ever appends, so the slot decides where its content sits and mount order decides
+// nothing. That is why the shell gives the screens a box of their own next to the search rather
+// than one shared list (see `app.tsx`, #56).
 export function ActionSlot({
   name = "header-actions",
   children,

package/src/app/app-tree/app-tree.tsx

@@ -15,10 +15,11 @@ import {
 import { useRef, useState } from "react";
 import {
   type MoveDestination,
-  MoveDialog,
   moveErrorKey,
   moveVerdict,
   parentOf,
+  treeLevelKey,
+  useTreeMove,
 } from "@/app/tree-move/tree-move.tsx";
 import {
   DropdownMenu,
@@ -36,7 +37,6 @@ import {
 import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
 import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
 import { Modal } from "@/modal/modal.tsx";
-import { ResourceMenu } from "@/resource-menu/resource-menu.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
 import { selectedFrom } from "@/router/selection-search.ts";
 
@@ -79,16 +79,13 @@ type Level = { id: string | null; type: "folder" | "flow" };
 // One key per level. `null` is the root; every expanded row adds one of its own, and nothing else is
 // ever asked for.
 function levelKey(level: Level): readonly unknown[] {
-  return level.type === "flow" ? ["flow-calls", level.id] : ["tree", level.id];
+  return level.type === "flow" ? ["flow-calls", level.id] : treeLevelKey(level.id);
 }
 
-// The optimistic row, filed where it is about to land. Its own parent has to travel with it, or the
-// plus on the moved row would still file into the folder it just left.
-function withParent(entry: TreeEntry, parentId: string | null): TreeEntry {
-  return entry.type === "knowledge"
-    ? { ...entry, node: { ...entry.node, parentId } }
-    : { ...entry, flow: { ...entry.flow, parentId } };
-}
+// What a row puts on the clipboard for anybody outside the tree. Its own media type rather than
+// `text/plain`, so a drop target that means "move this row" and one that means "make a node for
+// this" cannot be confused by the same payload.
+export const TreeEntryMediaType = "application/x-intel-tree-entry";
 
 export function AppTree() {
   const { data, i18n } = useIntelRouterContext();
@@ -103,10 +100,14 @@ export function AppTree() {
   // Which target the pointer is over: `undefined` for none, `null` for the root strip, an id for a
   // folder row. Three answers, because "the root" and "nothing" are not the same drop.
   const [over, setOver] = useState<string | null | undefined>(undefined);
-  const [moving, setMoving] = useState<{
-    entry: TreeEntry;
-    initial: MoveDestination | null;
-  } | null>(null);
+  // The drop's half of the move. The other half is the folder picker in the title line's menu, and
+  // both go through the same mutation (#58, `useTreeMove`) — the tree only adds what a tree can add,
+  // which is opening the folder the row just landed in.
+  const move = useTreeMove({
+    onMoved: (destination) => {
+      if (destination.id !== null) toggle({ id: destination.id, type: "folder" }, true);
+    },
+  });
 
   const location = useRouterState({
     select: (state) => ({
@@ -180,7 +181,6 @@ export function AppTree() {
         kind,
         title,
         description: null,
-        contextPolicy: "relevant",
         idempotencyKey: crypto.randomUUID(),
       });
       // ⚠️ Two calls, because they are two things: the node is a row in the tree, the header is the
@@ -216,7 +216,6 @@ export function AppTree() {
         kind: "attachment",
         title: file.name,
         description: null,
-        contextPolicy: "relevant",
         idempotencyKey: crypto.randomUUID(),
       });
       try {
@@ -251,86 +250,6 @@ export function AppTree() {
     },
   });
 
-  // ⚠️ Optimistic, never authoritative. The row is lifted out of one level and dropped into the
-  // other before the server answers, and every refusal — 403, `parent_not_folder`, `move_cycle`,
-  // `update_conflict` — puts both levels back exactly as they were and then re-reads them, so a
-  // rejected move cannot leave a row standing twice or nowhere at all.
-  const move = useMutation({
-    mutationFn: async ({
-      entry,
-      destination,
-    }: {
-      entry: TreeEntry;
-      destination: MoveDestination;
-    }) => {
-      // `baseUpdatedAt` travels with the move: it is what turns a concurrent edit into a 409 the
-      // view can act on instead of an overwrite nobody notices.
-      if (entry.type === "flow") {
-        await data.updateFlow({
-          flowId: entry.id,
-          baseUpdatedAt: entry.flow.updatedAt,
-          parentId: destination.id,
-          idempotencyKey: crypto.randomUUID(),
-        });
-      } else {
-        await data.updateKnowledge({
-          nodeId: entry.id,
-          baseUpdatedAt: entry.node.updatedAt,
-          parentId: destination.id,
-          idempotencyKey: crypto.randomUUID(),
-        });
-      }
-    },
-    onMutate: async ({ entry, destination }) => {
-      const fromKey = levelKey({ id: parentOf(entry), type: "folder" });
-      const toKey = levelKey({ id: destination.id, type: "folder" });
-      await Promise.all([
-        queryClient.cancelQueries({ queryKey: fromKey }),
-        queryClient.cancelQueries({ queryKey: toKey }),
-      ]);
-      const snapshot = [
-        [fromKey, queryClient.getQueryData<TreeEntry[]>(fromKey)],
-        [toKey, queryClient.getQueryData<TreeEntry[]>(toKey)],
-      ] as const;
-      queryClient.setQueryData<TreeEntry[]>(fromKey, (current) =>
-        current?.filter((row) => row.id !== entry.id),
-      );
-      // A level nobody has opened stays unloaded: writing one here would show a folder's contents
-      // that were never read.
-      queryClient.setQueryData<TreeEntry[]>(toKey, (current) =>
-        current === undefined
-          ? current
-          : [...current.filter((row) => row.id !== entry.id), withParent(entry, destination.id)],
-      );
-      return { snapshot };
-    },
-    onError: (_error, _variables, context) => {
-      for (const [key, value] of context?.snapshot ?? []) queryClient.setQueryData(key, value);
-    },
-    onSuccess: (_result, { destination }) => {
-      if (destination.id !== null) toggle({ id: destination.id, type: "folder" }, true);
-    },
-    onSettled: async (_result, _error, { entry, destination }) => {
-      await Promise.all([
-        queryClient.invalidateQueries({
-          queryKey: levelKey({ id: parentOf(entry), type: "folder" }),
-        }),
-        queryClient.invalidateQueries({
-          queryKey: levelKey({ id: destination.id, type: "folder" }),
-        }),
-        queryClient.invalidateQueries({
-          queryKey: [entry.type === "flow" ? "flows" : "knowledge-graph"],
-        }),
-        queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
-      ]);
-    },
-  });
-
-  function startMove(entry: TreeEntry, destination: MoveDestination | null) {
-    move.reset();
-    setMoving({ entry, initial: destination });
-  }
-
   // What a drop on this target would do. `undefined` means nothing is being dragged, so the target
   // is not a target at all.
   function verdictFor(
@@ -374,7 +293,7 @@ export function AppTree() {
           setDragged(null);
           draggedRef.current = null;
           if (carried && verdictFor(carried, target.id, ancestors) === "ok") {
-            startMove(carried, target);
+            move.start(carried, target);
           }
         },
       },
@@ -529,8 +448,17 @@ export function AppTree() {
             isActive={isActive}
             draggable={!derived}
             onDragStart={(event) => {
-              event.dataTransfer.effectAllowed = "move";
+              // ⚠️ Two formats, one gesture. `text/plain` is what a drop inside the tree reads —
+              // that is a MOVE, and it only ever needed the id. The flow canvas needs the kind as
+              // well, to know which node to make, and resolving an id there would mean a second
+              // read of something the drag already knows. `effectAllowed` says both are allowed;
+              // each drop target picks the one it means (#75).
+              event.dataTransfer.effectAllowed = "copyMove";
               event.dataTransfer.setData("text/plain", entry.id);
+              event.dataTransfer.setData(
+                TreeEntryMediaType,
+                JSON.stringify({ id: entry.id, kind: entry.kind, title: entry.title }),
+              );
               draggedRef.current = entry;
               setDragged(entry);
             }}
@@ -559,17 +487,12 @@ export function AppTree() {
               else setCreating({ parentId: target, kind });
             }}
           />
-          {/* ⚠️ Dragging is a pointer gesture and nothing else: no keyboard, no screen reader, no
-              touch worth the name. A capability that exists only for a mouse is missing for
-              everyone else, so moving has a second, equal route — this menu's folder picker. #27
-              opened the menu with that one item; the rest of the row's actions moved in here from
-              the header, which is what #24 is. A row under a flow is what that flow calls, read out
-              of its graph rather than from `parent_id` (ADR-0004 §3): it has no place of its own to
-              be moved from, so it gets no move — and no menu, since renaming the shared flow from
-              under one of its callers would rename it for all of them without saying so. */}
-          {derived ? null : (
-            <ResourceMenu target={entry} variant="row" onMove={() => startMove(entry, null)} />
-          )}
+          {/* ⚠️ Nothing else. The three-dot menu stood here until #58 and does not any more: two
+              buttons per row put ten of them into a 240px column, and one then reads buttons instead
+              of titles — the tree is for reading. Every action it held is in the title line of the
+              thing itself, which every row opens by being clicked, including a folder, whose screen
+              is nothing but that line. Do not put a second one back here: the point of the menu is
+              that it is always in the same place, and two places are not one. */}
         </div>
         {/* The same rows one indent deeper: one row component for every depth, so the plus on the
             fourth level is the same plus as on the first. The list is named after the row it hangs
@@ -598,7 +521,7 @@ export function AppTree() {
         <button
           type="button"
           {...rootDrop.props}
-          onClick={() => startMove(dragged, { id: null, title: i18n.t("tree.move.root") })}
+          onClick={() => move.start(dragged, { id: null, title: i18n.t("tree.move.root") })}
           data-drop={rootDrop.verdict}
           className={`mb-1 flex w-full items-center gap-1 rounded-md border border-dashed px-2 py-1.5 text-left text-sm outline-none focus-visible:ring-2 focus-visible:ring-sidebar-ring ${
             rootDrop.verdict === "ok"
@@ -622,7 +545,7 @@ export function AppTree() {
       ) : null}
       {/* Four refusals, four sentences — and by the time one is read the row is already back where
           it started, because the rollback happens in `onError` rather than here. */}
-      {move.isError ? (
+      {move.error ? (
         <p role="alert" className="px-2 py-1.5 text-sm text-destructive">
           {i18n.t(moveErrorKey(move.error))}
         </p>
@@ -666,17 +589,7 @@ export function AppTree() {
           />
         </Modal>
       ) : null}
-      {moving ? (
-        <MoveDialog
-          entry={moving.entry}
-          initial={moving.initial}
-          close={() => setMoving(null)}
-          submit={(destination) => {
-            setMoving(null);
-            move.mutate({ entry: moving.entry, destination });
-          }}
-        />
-      ) : null}
+      {move.dialog}
     </SidebarGroup>
   );
 }

package/src/app/app.tsx

@@ -91,10 +91,21 @@ export function App() {
               ) : null}
             </BreadcrumbList>
           </Breadcrumb>
-          {/* The bar for area-owned actions. A screen renders into it through `ActionSlot`;
-              search is the shell's own, because it has to open from every screen alike and belongs
-              to none of them. It stays first, so a screen's actions line up to its right. */}
-          <div data-slot="header-actions" className="ml-auto flex items-center gap-2">
+          {/* The bar for area-owned actions. A screen renders into the inner box through
+              `ActionSlot`; search is the shell's own, because it has to open from every screen
+              alike and belongs to none of them. It stays last, against the right edge, and a
+              screen's actions line up to its left: the search is the one thing in this bar that is
+              on every screen, so it is the one whose place must not depend on what a screen happens
+              to bring. Pinned the other way round it was the constant that moved (#56).
+
+              ⚠️ Two boxes rather than one list, and that is the whole of the mechanism: a portal
+              only ever appends to its container, so with the search a sibling of the portalled
+              actions a screen that mounts them later — Flows does, once a flow is selected — would
+              land to its right. Giving the screens a container of their own takes mount order out
+              of the question entirely. `data-slot="header-actions"` therefore names the inner box:
+              it is the name every `ActionSlot` looks up. */}
+          <div data-slot="header-bar" className="ml-auto flex items-center gap-2">
+            <div data-slot="header-actions" className="flex items-center gap-2" />
             <HeaderSearch />
           </div>
         </header>

package/src/app/tree-move/tree-move.tsx

@@ -1,5 +1,6 @@
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { ChevronLeft, Folder } from "lucide-react";
+import type * as React from "react";
 import { useState } from "react";
 import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
 import { Modal } from "@/modal/modal.tsx";
@@ -17,6 +18,20 @@ export function parentOf(entry: TreeEntry): string | null {
   return entry.type === "knowledge" ? entry.node.parentId : entry.flow.parentId;
 }
 
+// One level of the shared tree, as a query key. The move writes into two of them and the picker
+// reads a third, so the shape is stated once rather than spelled out at each of those places.
+export function treeLevelKey(parentId: string | null): readonly unknown[] {
+  return ["tree", parentId];
+}
+
+// The optimistic row, filed where it is about to land. Its own parent has to travel with it, or the
+// plus on the moved row would still file into the folder it just left.
+function withParent(entry: TreeEntry, parentId: string | null): TreeEntry {
+  return entry.type === "knowledge"
+    ? { ...entry, node: { ...entry.node, parentId } }
+    : { ...entry, flow: { ...entry.flow, parentId } };
+}
+
 /**
  * ⚠️ The trap this ticket is built around: a node must not travel into its own descendants. The
  * service refuses it (`move_cycle`, `knowledge.ts:421`), but a refusal that only arrives once the
@@ -195,3 +210,122 @@ export function MoveDialog({
     </Modal>
   );
 }
+
+/**
+ * Moving a row, wherever it is asked for.
+ *
+ * ⚠️ It is asked for from two places now (#58): a drop on a folder in the tree, and the menu in the
+ * title line — the keyboard route, which since #58 is the only one the menu still has anywhere. Both
+ * are the same move, so both take it from here rather than each carrying its own mutation. Two
+ * copies of an optimistic update that rewrites two cached levels is how a rejected move ends up
+ * leaving a row standing twice.
+ *
+ * ⚠️ Optimistic, never authoritative. The row is lifted out of one level and dropped into the other
+ * before the server answers, and every refusal — 403, `parent_not_folder`, `move_cycle`,
+ * `update_conflict` — puts both levels back exactly as they were and then re-reads them.
+ *
+ * The caller renders `dialog` where it likes and words `error` itself with `moveErrorKey`: the tree
+ * says it in the sidebar, the menu over the screen, and neither position belongs to the move.
+ */
+export function useTreeMove({
+  onMoved,
+}: {
+  // What the caller wants to do with the destination once the move is through — the tree opens that
+  // folder so the row is where the eye follows it. Nobody else has a tree to open.
+  onMoved?: ((destination: MoveDestination) => void) | undefined;
+} = {}): {
+  start(entry: TreeEntry, destination: MoveDestination | null): void;
+  error: unknown;
+  dialog: React.ReactNode;
+} {
+  const { data } = useIntelRouterContext();
+  const queryClient = useQueryClient();
+  const [moving, setMoving] = useState<{
+    entry: TreeEntry;
+    initial: MoveDestination | null;
+  } | null>(null);
+
+  const move = useMutation({
+    mutationFn: async ({
+      entry,
+      destination,
+    }: {
+      entry: TreeEntry;
+      destination: MoveDestination;
+    }) => {
+      // `baseUpdatedAt` travels with the move: it is what turns a concurrent edit into a 409 the
+      // view can act on instead of an overwrite nobody notices.
+      if (entry.type === "flow") {
+        await data.updateFlow({
+          flowId: entry.id,
+          baseUpdatedAt: entry.flow.updatedAt,
+          parentId: destination.id,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      } else {
+        await data.updateKnowledge({
+          nodeId: entry.id,
+          baseUpdatedAt: entry.node.updatedAt,
+          parentId: destination.id,
+          idempotencyKey: crypto.randomUUID(),
+        });
+      }
+    },
+    onMutate: async ({ entry, destination }) => {
+      const fromKey = treeLevelKey(parentOf(entry));
+      const toKey = treeLevelKey(destination.id);
+      await Promise.all([
+        queryClient.cancelQueries({ queryKey: fromKey }),
+        queryClient.cancelQueries({ queryKey: toKey }),
+      ]);
+      const snapshot = [
+        [fromKey, queryClient.getQueryData<TreeEntry[]>(fromKey)],
+        [toKey, queryClient.getQueryData<TreeEntry[]>(toKey)],
+      ] as const;
+      queryClient.setQueryData<TreeEntry[]>(fromKey, (current) =>
+        current?.filter((row) => row.id !== entry.id),
+      );
+      // A level nobody has opened stays unloaded: writing one here would show a folder's contents
+      // that were never read.
+      queryClient.setQueryData<TreeEntry[]>(toKey, (current) =>
+        current === undefined
+          ? current
+          : [...current.filter((row) => row.id !== entry.id), withParent(entry, destination.id)],
+      );
+      return { snapshot };
+    },
+    onError: (_error, _variables, context) => {
+      for (const [key, value] of context?.snapshot ?? []) queryClient.setQueryData(key, value);
+    },
+    onSuccess: (_result, { destination }) => onMoved?.(destination),
+    onSettled: async (_result, _error, { entry, destination }) => {
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: treeLevelKey(parentOf(entry)) }),
+        queryClient.invalidateQueries({ queryKey: treeLevelKey(destination.id) }),
+        queryClient.invalidateQueries({
+          queryKey: [entry.type === "flow" ? "flows" : "knowledge-graph"],
+        }),
+        queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
+      ]);
+    },
+  });
+
+  return {
+    start(entry, destination) {
+      move.reset();
+      setMoving({ entry, initial: destination });
+    },
+    error: move.isError ? move.error : null,
+    dialog: moving ? (
+      <MoveDialog
+        entry={moving.entry}
+        initial={moving.initial}
+        close={() => setMoving(null)}
+        submit={(destination) => {
+          setMoving(null);
+          move.mutate({ entry: moving.entry, destination });
+        }}
+      />
+    ) : null,
+  };
+}

package/src/components/ui/table.tsx

@@ -0,0 +1,82 @@
+import type * as React from "react";
+import { cn } from "@/lib/utils.ts";
+
+// The shadcn table primitive. A real `<table>` and not a grid of divs: the row and column
+// relationships are what a screen reader reads out, and no `role` patch on a div reproduces them
+// as reliably as the element that means it.
+//
+// ⚠️ The horizontal scroll lives on the wrapper, not on the page. A wide table has to be able to
+// scroll inside its own box, or the whole layout scrolls sideways with it.
+function Table({ className, ...props }: React.ComponentProps<"table">) {
+  return (
+    <div data-slot="table-container" className="relative w-full overflow-x-auto">
+      <table
+        data-slot="table"
+        className={cn("w-full caption-bottom text-sm", className)}
+        {...props}
+      />
+    </div>
+  );
+}
+
+function TableHeader({ className, ...props }: React.ComponentProps<"thead">) {
+  return <thead data-slot="table-header" className={cn("[&_tr]:border-b", className)} {...props} />;
+}
+
+function TableBody({ className, ...props }: React.ComponentProps<"tbody">) {
+  return (
+    <tbody
+      data-slot="table-body"
+      className={cn("[&_tr:last-child]:border-0", className)}
+      {...props}
+    />
+  );
+}
+
+function TableRow({ className, ...props }: React.ComponentProps<"tr">) {
+  return (
+    <tr
+      data-slot="table-row"
+      className={cn(
+        "border-b transition-colors hover:bg-muted/50 data-[state=selected]:bg-muted",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function TableHead({ className, ...props }: React.ComponentProps<"th">) {
+  return (
+    <th
+      data-slot="table-head"
+      className={cn(
+        "h-10 px-2 text-left align-middle font-medium text-muted-foreground whitespace-nowrap",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+function TableCell({ className, ...props }: React.ComponentProps<"td">) {
+  return (
+    <td
+      data-slot="table-cell"
+      className={cn("p-2 align-middle whitespace-nowrap", className)}
+      {...props}
+    />
+  );
+}
+
+function TableCaption({ className, ...props }: React.ComponentProps<"caption">) {
+  return (
+    <caption
+      data-slot="table-caption"
+      className={cn("mt-4 text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  );
+}
+
+export { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow };

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

@@ -14,6 +14,7 @@ import {
   FlowRunHistory,
   FlowRunList,
   FlowRunStep,
+  FlowValidation,
   KnowledgeDocument,
   KnowledgeGraph,
   KnowledgeLinkList,
@@ -84,10 +85,20 @@ export function flowEntry(flow: Flow): TreeEntry {
 }
 
 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 ??
     (() => {
@@ -306,6 +317,9 @@ export function createIntelDataProvider(
     async getFlow(flowId) {
       return await request(`/flows/${encodeURIComponent(flowId)}`, FlowDocument);
     },
+    async validateFlow(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/validation`, FlowValidation);
+    },
     async listFlowCalls(flowId) {
       return await request(`/flows/${encodeURIComponent(flowId)}/calls`, FlowList);
     },
@@ -400,8 +414,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

@@ -14,6 +14,7 @@ import type {
   FlowRunHistory,
   FlowRunList,
   FlowRunStep,
+  FlowValidation,
   KnowledgeDocument,
   KnowledgeGraph,
   KnowledgeLinkList,
@@ -77,7 +78,10 @@ export interface IntelDataProvider {
   appendKnowledgeTableRows(
     input: AppendKnowledgeTableRowsInput,
   ): Promise<AppendKnowledgeTableRowsResult>;
-  portalConnectUrl(returnTo?: string): string;
+  // 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>;
@@ -92,6 +96,8 @@ export interface IntelDataProvider {
   // 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>;
+  // Would this flow start for me, right now. A question, not an action: nothing is created (#72).
+  validateFlow(flowId: string): Promise<FlowValidation>;
   // 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.