@anchrd/intel 0.59.0

package/ui/src/flows/flows.tsx

@@ -0,0 +1,1646 @@
+import type { Flow, FlowGraph, FlowNode } from "@contract/flow.ts";
+import { flowNodeLayer } from "@contract/flow.ts";
+import type { Node } from "@contract/node.ts";
+import { serverOf } from "@contract/tool.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useNavigate, useRouterState } from "@tanstack/react-router";
+import {
+  addEdge,
+  applyEdgeChanges,
+  applyNodeChanges,
+  Background,
+  type Connection,
+  Controls,
+  type Edge,
+  type EdgeChange,
+  Handle,
+  MiniMap,
+  type NodeChange,
+  type NodeProps,
+  Position,
+  ReactFlow,
+  type Node as ReactFlowNode,
+  ReactFlowProvider,
+  useReactFlow,
+} from "@xyflow/react";
+import { FileSearch, Info, Send, Wrench } from "lucide-react";
+import { createContext, useContext, useEffect, useId, useMemo, useState } from "react";
+import { TreeEntryMediaType } from "@/app/app-tree/app-tree.tsx";
+import { ViewMenu } from "@/app/view-menu/view-menu.tsx";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+import { IntelRequestError } from "@/data/intel-data-provider/intel-data-provider.ts";
+import { RefusalNotice } from "@/data/request-refusal/refusal-notice.tsx";
+import { refusalOf } from "@/data/request-refusal/request-refusal.ts";
+import { EntryPicker } from "@/entry-picker/entry-picker.tsx";
+import { FlowRuns } from "@/flow-runs/flow-runs.tsx";
+import { nodeIcon } from "@/flows/node-icon/node-icon.ts";
+import { NodePalette, usePaletteOpen } from "@/flows/node-palette/node-palette.tsx";
+import { GraphPane } from "@/graph-pane/graph-pane.tsx";
+import type { I18n } from "@/i18n/i18n.types.ts";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { Modal } from "@/modal/modal.tsx";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+import { selectedFrom, viewFrom } from "@/router/selection-search.ts";
+import { SaveButton, UnsavedChangesGuard } from "@/save-button/save-button.tsx";
+import { useResolvedTheme } from "@/theme/theme-context.tsx";
+import { TitleRow, TitleRowFrame, TitleRowScrollArea } from "@/title-row/title-row.tsx";
+
+type CanvasNode = ReactFlowNode<{ node: FlowNode; branches?: readonly string[] }, "intel">;
+type CanvasEdge = Edge;
+
+// One handle id at both ends of a context edge. React Flow reports the handles a connection was
+// drawn between, and that is the only place the two meanings can still be told apart — the contract
+// stores the meaning itself, not which dot it was dragged from.
+const ContextHandle = "context";
+
+// What a condition drawn on this canvas calls its branches. A DEFAULT for a new one, not a
+// vocabulary: `sourceHandle` is any non-empty string in the contract, and `compileFlow` asks only
+// that a condition's branches are unique and not null. A graph arrives over MCP as readily as from
+// here, and one whose branches are called something else is as valid as this one.
+const DefaultBranches = ["yes", "no"] as const;
+
+/**
+ * The branch names of one condition, as the loaded graph spells them.
+ *
+ * ⚠️ Read from the edges, never imposed on them. Rendering a fixed `yes`/`no` pair left every edge
+ * saved with other names unattached to any handle — the author redrew it, the redrawn edge took
+ * this canvas's name, and the old edge stayed in the state until its target had two incoming edges
+ * and `compileFlow` refused the save (#627). The names are taken once, when the version is loaded,
+ * so deleting an edge does not take its branch off the card: the handle stays, and drawing the edge
+ * again lands on the same name it had.
+ *
+ * Filled up to two from the defaults only where the graph is short of them — a condition needs two
+ * branches to be worth drawing, and one with none at all would offer nowhere to start.
+ */
+function branchesOf(graph: FlowGraph, nodeId: string): string[] {
+  const named = graph.edges
+    .filter((edge) => edge.kind === "flow" && edge.source === nodeId)
+    .map((edge) => edge.sourceHandle)
+    .filter((handle): handle is string => handle !== null);
+  const branches = [...new Set(named)];
+  for (const fallback of DefaultBranches) {
+    if (branches.length >= DefaultBranches.length) break;
+    if (!branches.includes(fallback)) branches.push(fallback);
+  }
+  return branches;
+}
+
+// The order the bar offers them in: roughly the order a flow is built, from the start to the result.
+// ⚠️ The start is in the bar even though every graph opens with one, because it can be deleted —
+// without an entry there would be no way back to a flow that has a beginning.
+const paletteKinds = [
+  "trigger",
+  "instruction",
+  "condition",
+  "subflow",
+  "folder",
+  "document",
+  "upload",
+  "table",
+  "tool",
+  "output",
+] as const;
+
+// What the tree hands over, read back defensively: the payload crosses a browser API, so it is
+// parsed rather than trusted. A drop that does not carry what we put there is simply ignored.
+function droppedEntry(payload: string): { id: string; kind: string; title: string } | null {
+  try {
+    const parsed: unknown = JSON.parse(payload);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const { id, kind, title } = parsed as Record<string, unknown>;
+    if (typeof id !== "string" || typeof kind !== "string" || typeof title !== "string")
+      return null;
+    return { id, kind, title };
+  } catch {
+    return null;
+  }
+}
+
+// A row's kind decides what dropping it makes, so nothing has to be asked. A folder becomes a
+// Folder link, a flow becomes the Flow step that calls it (D25).
+const flowKindOfEntry: Record<string, FlowNode["kind"] | undefined> = {
+  folder: "folder",
+  document: "document",
+  attachment: "upload",
+  table: "table",
+  flow: "subflow",
+};
+
+/**
+ * The tree links of this flow that name nothing any more, by resource id (#509).
+ *
+ * ⚠️ A context rather than a field on the node's `data`, because the canvas nodes are React state
+ * that the loaded version owns: writing the answer of a query into them would put a second writer
+ * on that state and let a background refetch land in the middle of an edit. The set is read where
+ * it is drawn and nowhere else.
+ */
+const InvalidLinks = createContext<ReadonlySet<string>>(new Set());
+
+function FlowCard({ data, selected }: NodeProps<CanvasNode>) {
+  const i18n = useI18n();
+  const contract = data.node;
+  const invalidLinks = useContext(InvalidLinks);
+  // ⚠️ Said in a WORD, not by colour alone. A card that only turned red would say nothing to a
+  // colour-blind reader and nothing at all to a screen reader — and this is the one state on the
+  // canvas that stops the flow from running (#509).
+  const broken = isLinkNode(contract) && invalidLinks.has(contract.configuration.resourceId);
+  const Icon = nodeIcon[contract.kind];
+  const branching = contract.kind === "condition";
+  const branches = data.branches ?? DefaultBranches;
+  // ⚠️ The start is told apart by silhouette first (#39): a pill among rectangles, in the primary
+  // token. Shape survives zooming out past the point where the label is legible, and it is the only
+  // one of the three that also carries into the overview map, where nothing is written at all.
+  const start = contract.kind === "trigger";
+  // ⚠️ A call that rides along says so on the call itself (ADR-0004 §5). A version choice that only
+  // showed up in the inspector would be invisible on exactly the screen people read a flow from,
+  // and "why did this flow change" would have no answer on the canvas.
+  const riding = contract.kind === "subflow" ? contract.configuration.version.mode : null;
+  return (
+    <div
+      className={`min-w-48 border bg-card p-3 text-card-foreground shadow-sm ${start ? "rounded-full border-primary bg-primary/5 px-4" : "rounded-xl"} ${selected ? "ring-2 ring-ring" : ""}`}
+    >
+      {contract.kind !== "trigger" && <Handle type="target" position={Position.Left} />}
+      <div className="flex items-center gap-2">
+        <span
+          className={`grid size-8 shrink-0 place-items-center bg-primary/10 text-primary ${start ? "rounded-full bg-primary text-primary-foreground" : "rounded-lg"}`}
+        >
+          <Icon aria-hidden="true" className="size-4" />
+        </span>
+        <span className="min-w-0">
+          <span className="block truncate text-sm font-medium">{contract.label}</span>
+          {/* The kind through the catalog, not the raw key: the start node is called Start on the
+              canvas as well, and `trigger` would name an event that no longer exists (#39).
+              ⚠️ A broken link says so INSTEAD of naming its kind, because "Document" beside a
+              reference that names nothing is the sentence #509 is about: the card looked like every
+              valid link on the canvas. */}
+          <span
+            className={`block text-xs ${broken ? "text-destructive" : "text-muted-foreground"}`}
+          >
+            {broken ? i18n.t("flows.nodeInvalid") : i18n.t(`flows.node.${contract.kind}`)}
+          </span>
+        </span>
+        {riding === "follows" || riding === "pinned" ? (
+          <span className="ml-auto shrink-0 rounded-full border px-2 py-0.5 text-[0.625rem] uppercase tracking-wide text-muted-foreground">
+            {i18n.t(`flows.subflowBadge.${riding}`)}
+          </span>
+        ) : null}
+      </div>
+      {contract.kind !== "output" && !branching && (
+        <Handle type="source" position={Position.Right} />
+      )}
+      {branching &&
+        branches.map((branch, index) => (
+          <Handle
+            key={branch}
+            id={branch}
+            type="source"
+            position={Position.Right}
+            // Spread over the right edge rather than pinned: a condition may carry more than the two
+            // this canvas offers, and three branches stacked on two fixed points would hide one.
+            style={{ top: `${(100 * (index + 1)) / (branches.length + 1)}%` }}
+          />
+        ))}
+      {/* The context point (#37). Sideways is the order of work, downwards is what a step works
+          with — including at the output, where the same edge reads as where the result goes. Both
+          ends sit on the vertical axis so an attachment hangs under its step and the two meanings
+          are told apart by direction as well as by the dashed line. The start has no top point:
+          the beginning of a flow is not material another step works with. */}
+      <Handle id={ContextHandle} type="source" position={Position.Bottom} />
+      {contract.kind !== "trigger" && (
+        <Handle id={ContextHandle} type="target" position={Position.Top} />
+      )}
+    </div>
+  );
+}
+
+const nodeTypes = { intel: FlowCard };
+
+function defaultGraph(): FlowGraph {
+  return {
+    nodes: [
+      {
+        id: "trigger",
+        kind: "trigger",
+        label: "Manual start",
+        position: { x: 80, y: 180 },
+        configuration: { mode: "manual" },
+      },
+      {
+        id: "output",
+        kind: "output",
+        label: "Result",
+        position: { x: 520, y: 180 },
+        configuration: {},
+      },
+    ],
+    edges: [
+      {
+        id: "trigger-output",
+        source: "trigger",
+        target: "output",
+        kind: "flow",
+        label: null,
+        sourceHandle: null,
+      },
+    ],
+  };
+}
+
+/**
+ * The edges left over once `connection` is drawn.
+ *
+ * ⚠️ A point in the order of work leads to ONE place, and drawing from it again means "there
+ * instead". `compileFlow` says so twice — a step has exactly one outgoing edge, and a condition's
+ * branches are unique — so a second line from the same point can only ever be a graph that will not
+ * save. Dropping the old one here is what #627 cost when nothing did: the author redrew a branch,
+ * both lines stayed, and the refusal that followed named a node they had not touched.
+ *
+ * The context point is the exception it has always been: a step works with as much material as it
+ * needs, and those edges leave from the same handle by design.
+ */
+export function clearedFor(edges: CanvasEdge[], connection: Connection): CanvasEdge[] {
+  if (connection.sourceHandle === ContextHandle) return edges;
+  return edges.filter(
+    (edge) =>
+      edge.source !== connection.source ||
+      (edge.sourceHandle ?? null) !== (connection.sourceHandle ?? null),
+  );
+}
+
+function canvas(graph: FlowGraph) {
+  return {
+    nodes: graph.nodes.map((node) => ({
+      id: node.id,
+      type: "intel" as const,
+      position: node.position,
+      data: node.kind === "condition" ? { node, branches: branchesOf(graph, node.id) } : { node },
+    })),
+    edges: graph.edges.map((edge) => {
+      const context = edge.kind === "context";
+      return {
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        // The handle ids are put back from the stored meaning, so a context edge lands on the
+        // vertical pair again and a flow edge keeps the branch handle it was saved with.
+        sourceHandle: context ? ContextHandle : edge.sourceHandle,
+        targetHandle: context ? ContextHandle : null,
+        label: edge.label ?? undefined,
+        ...contextEdgeStyle(context),
+      };
+    }),
+  };
+}
+
+// Dashed and unarrowed, in the muted token rather than the colour of a flow edge: the reader has to
+// be able to separate the procedure from the material without being told which is which.
+function contextEdgeStyle(context: boolean): Partial<CanvasEdge> {
+  if (!context) return {};
+  return {
+    className: "intel-context-edge",
+    style: { strokeDasharray: "6 4" },
+    animated: false,
+  };
+}
+
+function graph(nodes: CanvasNode[], edges: CanvasEdge[]): FlowGraph {
+  return {
+    nodes: nodes.map((node) => ({
+      ...node.data.node,
+      position: node.position,
+    })),
+    edges: edges.map((edge) => {
+      const context = edge.sourceHandle === ContextHandle;
+      return {
+        id: edge.id,
+        source: edge.source,
+        target: edge.target,
+        kind: context ? ("context" as const) : ("flow" as const),
+        label: typeof edge.label === "string" && edge.label ? edge.label : null,
+        // A context edge carries no branch: the handle it was drawn from is a fact about the canvas,
+        // and storing it would make `compileFlow` read a branch where there is none.
+        sourceHandle: context ? null : (edge.sourceHandle ?? null),
+      };
+    }),
+  };
+}
+
+// ⚠️ Not every change React Flow reports is an edit. It also announces selection and the sizes it
+// has just measured, and both arrive unasked on the first paint — a flow would be "unsaved" the
+// moment it was opened, and the one signal that means something would mean nothing.
+function editsNodes(changes: NodeChange<CanvasNode>[]): boolean {
+  return changes.some(
+    (change) =>
+      change.type === "add" ||
+      change.type === "remove" ||
+      change.type === "replace" ||
+      (change.type === "position" && change.dragging === true),
+  );
+}
+
+function editsEdges(changes: EdgeChange<CanvasEdge>[]): boolean {
+  return changes.some(
+    (change) => change.type === "add" || change.type === "remove" || change.type === "replace",
+  );
+}
+
+// ⚠️ `upload` is what the flow calls an attachment. The two names are deliberately not unified:
+// in the tree it is a file somebody uploaded, in a flow it is material a step reads, and renaming
+// either one to match the other would make the other read wrong.
+//
+// The reverse map is DERIVED rather than written a second time — two hand-kept tables of the same
+// correspondence are two tables that eventually disagree, and the disagreement would show up as a
+// picker offering the wrong kind.
+const nodeKindOfLink = Object.fromEntries(
+  Object.entries(flowKindOfEntry)
+    .filter(([, kind]) => kind !== undefined && kind !== "subflow")
+    .map(([nodeKind, kind]) => [kind, nodeKind]),
+) as Partial<Record<FlowNode["kind"], Node["kind"]>>;
+
+type LinkNode = Extract<FlowNode, { configuration: { resourceId: string } }>;
+
+// A predicate rather than a boolean, so the update below can build the one configuration a link
+// has without widening every other node's to match.
+function isLinkNode(node: FlowNode): node is LinkNode {
+  return flowNodeLayer[node.kind] === "link" && "resourceId" in node.configuration;
+}
+
+function newNode(
+  kind: FlowNode["kind"],
+  index: number,
+  firstNodeId?: string,
+  firstFlowId?: string,
+  firstServer?: string,
+): FlowNode {
+  const common = {
+    id: `${kind}-${crypto.randomUUID()}`,
+    label: kind[0]?.toUpperCase() + kind.slice(1),
+    position: {
+      x: 260 + (index % 3) * 240,
+      y: 80 + Math.floor(index / 3) * 180,
+    },
+  };
+  switch (kind) {
+    case "trigger":
+      return { ...common, kind, label: "Manual start", configuration: { mode: "manual" } };
+    case "instruction":
+      return {
+        ...common,
+        kind,
+        configuration: { prompt: "Describe what the AI should do." },
+      };
+    // The four link kinds differ only in what the picker offers, so they are one branch. A link
+    // starts out naming nothing: it is filled in from the inspector, and `compileFlow` refuses to
+    // publish a graph whose reference is empty.
+    case "folder":
+    case "document":
+    case "upload":
+    case "table":
+      return { ...common, kind, configuration: { resourceId: firstNodeId ?? "" } };
+    case "tool":
+      return {
+        ...common,
+        kind,
+        // ⚠️ A server, not an empty string. `ToolServerHandle` has a minimum length, so a draft
+        // with `""` cannot be saved at all — the author would build a step and lose it at the next
+        // save with a raw field-path error. The tree link one line up takes the same way out.
+        configuration: {
+          server: firstServer ?? "",
+          allow: null,
+          fingerprint: null,
+        },
+      };
+    case "condition":
+      return {
+        ...common,
+        kind,
+        configuration: {
+          mode: "semantic",
+          instruction: "Describe how to choose yes or no.",
+        },
+      };
+    case "subflow":
+      // `latest` while drafting: nobody should have to version things while building, and
+      // publishing turns it into the concrete version (ADR-0004 §5).
+      return {
+        ...common,
+        kind,
+        configuration: { flowId: firstFlowId ?? "", version: { mode: "latest" } },
+      };
+    case "output":
+      return { ...common, kind, configuration: {} };
+  }
+}
+
+/**
+ * Which sentence a refused SAVE is told with.
+ *
+ * ⚠️ `400 flow_graph_invalid` and `409` are two different answers, and until #508 they shared one
+ * sentence — the conflict one. For a rejected graph that advice is not merely useless but
+ * destructive: reloading discards the unsaved canvas, and the next attempt is refused for exactly
+ * the same reason, so following it costs the work and changes nothing.
+ *
+ * The graph rule therefore shows the API's OWN sentence: only the server knows which step broke
+ * which rule, and it names that step by its label since #508. A conflict keeps the reload sentence,
+ * because there reloading IS the way out. Everything else gets neither — a timeout or a `502` is
+ * worth repeating, and nothing about it says the loaded version is stale.
+ *
+ * ⚠️ Not `resourceErrorKey`: that maps a code onto a catalog key, and this case has no key to map
+ * onto — its whole content is the server's sentence.
+ */
+function saveRefusalText(error: unknown, i18n: I18n): string {
+  const refusal = error instanceof IntelRequestError ? error : null;
+  if (refusal?.status === 400 && refusal.code === "flow_graph_invalid") {
+    return i18n.t("flows.saveInvalid", { detail: refusal.message });
+  }
+  if (refusal?.status === 409) return i18n.t("flows.saveConflict");
+  return i18n.t("flows.saveFailed");
+}
+
+/**
+ * Which sentence a refused PUBLISH is told with — #508 one surface further (#551).
+ *
+ * Publishing answers with at least eight different refusals: the compile rules of the save path,
+ * a link whose document is out of reach, a tool server that is gone, a frozen schema that moved,
+ * three rules about calling another flow — and all of them read
+ * "Publishing failed. Reload the latest version and try again." Reloading is the way out of exactly
+ * one of them, and for the rest it is the advice that costs the canvas and changes nothing.
+ *
+ * The split is therefore by what the answer IS, not by which code it carries:
+ *
+ * - **A refusal** (`4xx`) always shows the server's own sentence. It is the only party that knows
+ *   which step broke which rule, and since #508 it names that step by its label rather than by an
+ *   id — which is why #551 rewrote `flow_node_unavailable`, the one that still named a resource id.
+ * - **Two of them add the way out**, because the server's sentence identifies the step and stops
+ *   there: a document out of reach is answered by asking for access, and a tool server that is
+ *   gone by looking in the portal. Neither is something the API should prescribe per surface.
+ * - **A conflict** keeps the reload sentence, because there reloading IS the way out.
+ * - **Everything else** — a timeout, a `502`, a network that came back — says nothing about the
+ *   loaded version and is worth repeating, so it gets neither.
+ */
+function publishRefusalText(error: unknown, i18n: I18n): string {
+  const refusal = error instanceof IntelRequestError ? error : null;
+  // ⚠️ A `5xx` carries a sentence too, and showing it would dress a broken deployment up as a
+  // decision about this flow. Only the deliberate range speaks for itself.
+  if (refusal === null || refusal.status < 400 || refusal.status >= 500) {
+    return i18n.t("flows.publishFailed");
+  }
+  const detail = { detail: refusal.message };
+  switch (refusal.code) {
+    case "flow_node_unavailable":
+      return i18n.t("flows.publishNodeUnavailable", detail);
+    case "flow_tool_unavailable":
+      return i18n.t("flows.publishToolUnavailable", detail);
+    // The two ways the version being published stopped being the one to publish. Both are races
+    // against another editor, and the loaded version is genuinely stale afterwards.
+    case "flow_version_conflict":
+    case "flow_publish_conflict":
+      return i18n.t("flows.publishConflict");
+    default:
+      return i18n.t("flows.publishRefused", detail);
+  }
+}
+
+// ⚠️ The provider wraps the editor rather than sitting inside it: `useReactFlow` — which is how the
+// drop turns a screen point into a graph point — has to be called from a component UNDER it, and
+// the hook lives in the same component that renders the canvas.
+export function Flows() {
+  return (
+    <ReactFlowProvider>
+      <FlowsEditor />
+    </ReactFlowProvider>
+  );
+}
+
+function FlowsEditor() {
+  const { data } = useIntelRouterContext();
+  const i18n = useI18n();
+  const flow = useReactFlow();
+  const theme = useResolvedTheme();
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  // The servers a tool step can name (#489). The flat function list the picker used to show is
+  // what that ticket set out to remove; which function runs is decided while the flow runs.
+  // ⚠️ The flat function list is NOT what a step is chosen from any more (#489) — it is only what
+  // an author narrows a chosen server WITH. It is asked for regardless of whether a tool step is
+  // selected, because a query that starts when a panel opens shows a spinner inside the panel.
+  const tools = useQuery({
+    queryKey: ["tools"],
+    queryFn: () => data.listTools(),
+    // ⚠️ No retry. This query only ENRICHES the panel — the server is already chosen without it —
+    // and a retry is paused while the tab is unfocused, so a deterministic failure would leave the
+    // function list empty for as long as the reader looks away, with nothing saying why (#212).
+    retry: false,
+  });
+  const toolServers = useQuery({
+    queryKey: ["tool-servers"],
+    queryFn: () => data.listToolServers(),
+    // ⚠️ No retry here either, and for a sharper reason than the list above: the panel shows
+    // NOTHING while this is pending. A deterministic 502 with an unfocused tab pauses the retry,
+    // and the author then sits in front of an empty server field with no sentence saying why —
+    // which is #212 exactly. `error` is a state this panel can speak; `pending` is not.
+    retry: false,
+  });
+  // A tree link points at a node, so the editor needs candidates. The graph is the authorized
+  // flat list of them; walking the folder tree for a picker would be the N+1 all over again.
+  const nodeGraph = useQuery({
+    queryKey: ["node-graph"],
+    queryFn: () => data.getNodeGraph(),
+  });
+  // The candidates for a subflow step. Which of them a flow may actually call is answered when it is
+  // published (ADR-0004 §3) — the picker offers what the user may see, and the refusal names the
+  // reason rather than hiding the option.
+  const callable = useQuery({
+    queryKey: ["flows"],
+    queryFn: () => data.listFlows(),
+  });
+  /**
+   * The refusal of the top level, read off the query the picker already holds.
+   *
+   * ⚠️ No second query, and that is the whole difference to #445 next door: `["flows"]` is asked
+   * with or without a selection, so the answer for the empty screen is already in the cache. What
+   * the screen did was throw it away — `listTreeChildren` fails whole once `flows/read` is missing,
+   * the sidebar has said so since #430, and the main area beside it went on inviting the reader to
+   * pick a flow they cannot see (#557).
+   *
+   * ⚠️ Off the ERROR rather than off a missing answer. A sentence about a permission, shown while
+   * the request is still travelling, claims a refusal nobody has spoken yet — the mistake from #350,
+   * and `packages/intel/ui/CLAUDE.md` has the rule: a missing answer is a reason to say less, never to
+   * refuse more. Until a refusal arrives, what stands is the invitation, which claims nothing.
+   */
+  const rootRefusal = refusalOf(callable.error);
+  // The tree in the sidebar and the header search both name the flow to open through `?select=`;
+  // `?view=` says how it is shown — the editor, the relation graph (#19) or the runs (#35).
+  const selection = useRouterState({
+    select: (state) => ({
+      id: selectedFrom(state.location.search),
+      view: viewFrom(state.location.search),
+    }),
+  });
+  const selectedFlowId = selection.id;
+  // A single flow answers the relation question for itself: what it reads and what it calls.
+  const relations = useQuery({
+    queryKey: ["relation-graph", "flow", selectedFlowId],
+    queryFn: () => data.getRelationGraph({ of: "flow", flowId: selectedFlowId ?? "" }),
+    enabled: Boolean(selectedFlowId) && selection.view === "graph",
+  });
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+  const [publishing, setPublishing] = useState(false);
+  // Lifted out of the bar because the canvas dismisses it too — a click on the pane is the third way
+  // out, next to the trigger and Escape.
+  const [paletteOpen, setPaletteOpen] = usePaletteOpen();
+  const document = useQuery({
+    queryKey: ["flow", selectedFlowId],
+    queryFn: () => data.getFlow(selectedFlowId ?? ""),
+    enabled: Boolean(selectedFlowId),
+  });
+  // ⚠️ A refusal is not a failure. "Reload the latest version and try again." is advice for a
+  // network that came back; against a `403` or a `404` it sends somebody to reload a screen that
+  // will answer the same thing forever, and it hides that the answer was final (#430).
+  const documentRefusal = refusalOf(document.error);
+  const initial = useMemo(() => canvas(defaultGraph()), []);
+  const [nodes, setNodes] = useState<CanvasNode[]>(initial.nodes);
+  const [edges, setEdges] = useState<CanvasEdge[]>(initial.edges);
+  const [dirty, setDirty] = useState(false);
+  // The canvas stays visible during a background refetch; only a mutation needs the stricter
+  // guarantee that the loaded document is both the selected flow and settled.
+  const documentReady = selectedFlowId !== null && document.data?.flow.id === selectedFlowId;
+  const canMutate = documentReady && !document.isFetching;
+  // ⚠️ A tool step without a server cannot be saved at all — `ToolServerHandle` has a minimum
+  // length. Letting the request go out anyway answers with a generic failure that names no step, so
+  // the author learns "something is wrong" instead of "this one needs a server". The refusal
+  // belongs here, before the write (#517).
+  const stepsMissingServer = nodes.filter(
+    (node) => node.data.node.kind === "tool" && node.data.node.configuration.server === "",
+  );
+  useEffect(() => {
+    if (!document.data || document.data.flow.id !== selectedFlowId) return;
+    const next = canvas(document.data.version?.graph ?? defaultGraph());
+    setNodes(next.nodes);
+    setEdges(next.edges);
+    setSelectedNodeId(null);
+    setDirty(false);
+  }, [document.data, selectedFlowId]);
+  const selectedNode = nodes.find((node) => node.id === selectedNodeId) ?? null;
+  // ⚠️ The same query `FlowNeeds` asks, under the same key: TanStack answers both from one cache
+  // entry, so the canvas and the panel cannot end up disagreeing about which link is dead. A second
+  // key would be a second answer to one question, and the one people would trust is the one they
+  // happen to be looking at (#509).
+  const needs = useQuery({
+    queryKey: ["flow-requirements", selectedFlowId],
+    queryFn: () => data.getFlowRequirements(selectedFlowId ?? ""),
+    enabled: Boolean(selectedFlowId),
+  });
+  const invalidLinks = useMemo(
+    () => new Set(needs.data?.invalidNodes ?? []),
+    [needs.data?.invalidNodes],
+  );
+
+  const save = useMutation({
+    mutationFn: () =>
+      data.saveFlow({
+        flowId: selectedFlowId ?? "",
+        baseVersionId: document.data?.flow.currentVersionId ?? null,
+        graph: graph(nodes, edges),
+        idempotencyKey: crypto.randomUUID(),
+      }),
+    onSuccess: async (saved) => {
+      setDirty(false);
+      queryClient.setQueryData(["flow", saved.flow.id], saved);
+      // Saving is the whole of what changes here: the graph is both what this flow reads and calls
+      // — so the relation view of it and of its folder move with it — and the whole of what it
+      // needs.
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
+        queryClient.invalidateQueries({ queryKey: ["flow-requirements", saved.flow.id] }),
+      ]);
+    },
+  });
+
+  function updateNode(update: (node: FlowNode) => FlowNode) {
+    setDirty(true);
+    setNodes((current) =>
+      current.map((node) =>
+        node.id === selectedNodeId ? { ...node, data: { node: update(node.data.node) } } : node,
+      ),
+    );
+  }
+
+  return (
+    <TitleRowFrame className="flex h-full min-h-0 flex-col">
+      {selectedFlowId && document.data ? (
+        <FlowTitle
+          flow={document.data.flow}
+          dirty={dirty}
+          saving={save.isPending}
+          canMutate={canMutate}
+          incomplete={stepsMissingServer.map((node) => ({ label: node.data.node.label }))}
+          scrollingView={selection.view === "runs"}
+          onSave={() => save.mutate()}
+          onPublish={() => setPublishing(true)}
+        />
+      ) : null}
+      <UnsavedChangesGuard dirty={dirty} />
+      <div className="flex min-h-0 flex-1">
+        {!selectedFlowId ? (
+          rootRefusal ? (
+            <RefusalNotice refusal={rootRefusal} />
+          ) : (
+            <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
+              {i18n.t("flows.select")}
+            </div>
+          )
+        ) : /* ⚠️ The refusal comes BEFORE the view switch, and that placement is the whole of #568.
+               `?view=graph` and `?view=runs` used to be read first, so a flow the reader may not
+               open still rendered its two side views — each with a failure sentence and a "Try
+               again" button on an answer that will not change (#430). Whether the reader may see
+               this flow at all is answered by `getFlow`, once, for every view of it; asking it
+               after the switch means asking it three times and getting two of them wrong. */
+        documentRefusal ? (
+          <RefusalNotice refusal={documentRefusal} />
+        ) : selection.view === "runs" ? (
+          <FlowRuns flowId={selectedFlowId} />
+        ) : selection.view === "graph" ? (
+          <GraphPane
+            query={relations}
+            select={(node) =>
+              void navigate({
+                to: node.kind === "flow" ? "/flows" : "/nodes",
+                search: { select: node.id },
+              })
+            }
+          />
+        ) : document.isError ? (
+          <div
+            role="alert"
+            className="grid flex-1 place-items-center p-8 text-center text-sm text-destructive"
+          >
+            {i18n.t("flows.operationFailed")}
+          </div>
+        ) : !documentReady ? (
+          <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
+            {i18n.t("common.loading")}
+          </div>
+        ) : (
+          <>
+            <section className="relative min-w-0 flex-1">
+              {/* Adding is not what one does most of the time — reading the graph is. The bar stays
+                  open once opened, so three steps in a row cost one click, not three. */}
+              <NodePalette
+                kinds={paletteKinds}
+                open={paletteOpen}
+                setOpen={setPaletteOpen}
+                // ⚠️ Only the bar is closed off here. `compileFlow` keeps insisting on exactly one
+                // start, because a graph can also arrive over MCP or an import, where no bar was
+                // involved — this is the earlier answer, not the only one.
+                disabledReason={(kind) =>
+                  kind === "trigger" && nodes.some((node) => node.data.node.kind === "trigger")
+                    ? i18n.t("flows.startExists")
+                    : null
+                }
+                add={(kind) => {
+                  setDirty(true);
+                  const item = newNode(
+                    kind,
+                    nodes.length,
+                    nodeGraph.data?.nodes[0]?.id,
+                    callable.data?.items.find((entry) => entry.id !== selectedFlowId)?.id,
+                    toolServers.data?.items[0]?.handle,
+                  );
+                  setNodes((current) => [
+                    ...current,
+                    {
+                      id: item.id,
+                      type: "intel",
+                      position: item.position,
+                      data: { node: item },
+                    },
+                  ]);
+                }}
+              />
+              {/* ⚠️ React Flow knows nothing about the `.dark` class our tokens hang off; without
+                  `colorMode` it paints its controls and its minimap from its own light palette and
+                  leaves two glaring white surfaces on a black canvas. The value comes from the same
+                  media query that sets the class, so both turn together and mid-session. What the
+                  surfaces are actually coloured with is in `styles.css`, through the library's own
+                  theming variables. */}
+              <InvalidLinks.Provider value={invalidLinks}>
+                <ReactFlow<CanvasNode, CanvasEdge>
+                  colorMode={theme}
+                  nodes={nodes}
+                  edges={edges}
+                  nodeTypes={nodeTypes}
+                  fitView
+                  onNodesChange={(changes: NodeChange<CanvasNode>[]) => {
+                    if (editsNodes(changes)) setDirty(true);
+                    setNodes((current) => applyNodeChanges(changes, current));
+                  }}
+                  onEdgesChange={(changes: EdgeChange<CanvasEdge>[]) => {
+                    if (editsEdges(changes)) setDirty(true);
+                    setEdges((current) => applyEdgeChanges(changes, current));
+                  }}
+                  // ⚠️ The two meanings cannot be mixed on one edge: a line from a context point into
+                  // a flow input would be stored as context and drawn as an attachment, while the
+                  // author meant "and then". Refused at the point where it is still visible.
+                  isValidConnection={(connection) =>
+                    (connection.sourceHandle === ContextHandle) ===
+                    (connection.targetHandle === ContextHandle)
+                  }
+                  onConnect={(connection: Connection) => {
+                    setDirty(true);
+                    setEdges((current) =>
+                      addEdge(
+                        {
+                          ...connection,
+                          id: crypto.randomUUID(),
+                          ...contextEdgeStyle(connection.sourceHandle === ContextHandle),
+                        },
+                        clearedFor(current, connection),
+                      ),
+                    );
+                  }}
+                  onNodeClick={(_event, node) => setSelectedNodeId(node.id)}
+                  onPaneClick={() => {
+                    setSelectedNodeId(null);
+                    setPaletteOpen(false);
+                  }}
+                  // ⚠️ `copy`, not `move` (#75). The tree's own drop targets say `move`, and the two
+                  // have to feel different while the pointer is still travelling: dropping here makes
+                  // a node that POINTS at the row, it does not take the row out of its folder.
+                  onDragOver={(event) => {
+                    if (!event.dataTransfer.types.includes(TreeEntryMediaType)) return;
+                    event.preventDefault();
+                    event.dataTransfer.dropEffect = "copy";
+                  }}
+                  onDrop={(event) => {
+                    const payload = event.dataTransfer.getData(TreeEntryMediaType);
+                    if (!payload) return;
+                    event.preventDefault();
+                    const dropped = droppedEntry(payload);
+                    if (!dropped) return;
+                    const kind = flowKindOfEntry[dropped.kind];
+                    if (!kind) return;
+                    // Where the pointer let go, in the graph's own coordinates — not the screen's, or
+                    // the node would land somewhere else at every zoom level.
+                    const position = flow.screenToFlowPosition({
+                      x: event.clientX,
+                      y: event.clientY,
+                    });
+                    setDirty(true);
+                    setNodes((current) => [
+                      ...current,
+                      {
+                        id: `${kind}-${crypto.randomUUID()}`,
+                        type: "intel" as const,
+                        position,
+                        data: {
+                          node: {
+                            id: `${kind}-${crypto.randomUUID()}`,
+                            kind,
+                            label: dropped.title,
+                            position,
+                            configuration:
+                              kind === "subflow"
+                                ? { flowId: dropped.id, version: { mode: "latest" as const } }
+                                : { resourceId: dropped.id },
+                          } as FlowNode,
+                        },
+                      },
+                    ]);
+                  }}
+                >
+                  <Background />
+                  {/* The overview map has no room for a label, so the start is marked there the only
+                    way that is left: its own colour, from the tokens rather than a fixed value. */}
+                  <MiniMap
+                    pannable
+                    zoomable
+                    nodeClassName={(node) =>
+                      (node as CanvasNode).data.node.kind === "trigger" ? "intel-minimap-start" : ""
+                    }
+                  />
+                  <Controls />
+                </ReactFlow>
+              </InvalidLinks.Provider>
+            </section>
+            <aside className="flex w-80 shrink-0 flex-col border-l bg-card">
+              <TitleRowScrollArea className="min-h-0 flex-1 overflow-y-auto">
+                <NodeInspector
+                  node={selectedNode}
+                  update={updateNode}
+                  toolServers={toolServers.data?.items ?? []}
+                  toolServersState={
+                    toolServers.isPending
+                      ? "pending"
+                      : toolServers.isError
+                        ? "error"
+                        : toolServers.data?.portalConnected === false
+                          ? "disconnected"
+                          : "ready"
+                  }
+                  toolNames={(tools.data?.items ?? []).map((entry) => entry.name)}
+                  toolNamesFailed={tools.isError}
+                  toolNamesPending={tools.isPending}
+                  flows={(callable.data?.items ?? []).filter(
+                    (entry) => entry.id !== selectedFlowId,
+                  )}
+                />
+                <FlowNeeds flowId={selectedFlowId} />
+              </TitleRowScrollArea>
+            </aside>
+          </>
+        )}
+      </div>
+      {save.isError && (
+        <p
+          role="alert"
+          className="fixed bottom-5 left-[18rem] z-20 rounded-lg border border-destructive/30 bg-card px-4 py-3 text-sm text-destructive shadow-xl"
+        >
+          {saveRefusalText(save.error, i18n)}
+        </p>
+      )}
+      {publishing && selectedFlowId && document.data?.flow.currentVersionId ? (
+        <PublishPreview
+          flowId={selectedFlowId}
+          versionId={document.data.flow.currentVersionId}
+          close={() => setPublishing(false)}
+          onPublished={async () => {
+            setPublishing(false);
+            // Publishing appends the frozen version, so more than the flow row moves: the canvas
+            // reloads from the new current version, the preview cached under the old version id
+            // would still claim there is something left to freeze, and the relation view reads the
+            // graph that just changed.
+            await Promise.all([
+              queryClient.invalidateQueries({ queryKey: ["flow", selectedFlowId] }),
+              queryClient.invalidateQueries({
+                queryKey: ["flow-publish-preview", selectedFlowId],
+              }),
+              queryClient.invalidateQueries({ queryKey: ["relation-graph"] }),
+            ]);
+          }}
+        />
+      ) : null}
+    </TitleRowFrame>
+  );
+}
+
+/**
+ * The flow's title line — the same one a document has (#24).
+ *
+ * Before this, a flow wore four spelled-out buttons in the shell's header while a document wore
+ * icons in its own title line: two screens of one application, built two ways, and a reader who has
+ * to learn where actions live twice.
+ *
+ * ⚠️ `Publish` and `Run` stay visible buttons rather than menu entries, and they are deliberately
+ * *not* the same shape as each other. Both reach outside the editor — publishing freezes the version
+ * every later run hangs on, and a run keeps going after the tab is closed (Cloudflare Workflows,
+ * binding `FLOWS`) — so neither belongs behind three dots. But `Run` is the only one that starts
+ * work, so it is the only button in the line that carries a word instead of a picture: the
+ * difference in form *is* the warning against hitting it by accident.
+ */
+function FlowTitle({
+  flow,
+  dirty,
+  saving,
+  canMutate,
+  incomplete,
+  scrollingView,
+  onSave,
+  onPublish,
+}: {
+  flow: Flow;
+  dirty: boolean;
+  saving: boolean;
+  canMutate: boolean;
+  // Whether what stands below this line can scroll under it. The runs list can and earns its edge
+  // the usual way; the canvas and the graph pan instead, and would never get one (#634).
+  scrollingView: boolean;
+  // Tool steps that name no server yet. They cannot be saved, so the refusal is shown here rather
+  // than fetched from the server as a message that names no step.
+  incomplete: Array<{ label: string }>;
+  onSave(): void;
+  onPublish(): void;
+}) {
+  const i18n = useI18n();
+  // A draft that is already the published one freezes nothing, so publishing it would be a no-op
+  // with a dialog in front of it.
+  const publishable =
+    canMutate &&
+    Boolean(flow.currentVersionId) &&
+    flow.currentVersionId !== flow.publishedVersionId;
+  // ⚠️ Nothing published means `Start run` answers 409 `flow_not_published` (`flows.ts:541`), and
+  // until now that was only readable by clicking it. The button that fixes it says so instead.
+  const unpublished = flow.publishedVersionId === null;
+  const publishLabel = i18n.t(
+    !publishable ? "flows.publishNothing" : unpublished ? "flows.publishNeeded" : "flows.publish",
+  );
+  return (
+    // ⚠️ The menu stands to the RIGHT of the run button, not before it (#53, deliberate). Run is the
+    // loudest thing in this line and used to hold the edge; the menu takes it, because a menu one can
+    // hit without looking is worth more than the primary button being outermost. `TitleRow` is what
+    // enforces that — nothing passed in here can get past the menu.
+    <TitleRow title={flow.title} target={{ type: "flow", flow }} separated={!scrollingView}>
+      {/* ⚠️ #454: the view switch used to stand in the global header, beside the search — where what
+          applies EVERYWHERE stands. But it says how THIS flow is shown, and so belongs in the line
+          that names this flow. A flow is the only level with runs, and therefore the only one with
+          three views (#35) — behind one symbol since #818, like every other surface. */}
+      {incomplete.length > 0 && (
+        <p className="mr-2 text-xs text-destructive">
+          {i18n.t("flows.toolStepNeedsServer", { label: incomplete[0]?.label ?? "" })}
+        </p>
+      )}
+      <SaveButton
+        dirty={dirty && canMutate && incomplete.length === 0}
+        saving={saving}
+        onSave={onSave}
+      />
+      <TooltipProvider delayDuration={300}>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <span className="inline-flex">
+              {/* Publishing goes through the preview, always. ADR-0004 §5 asks the author to see
+                    the freeze before it happens, and a second, quieter path around the dialog would
+                    be the one everybody ends up using. */}
+              <button
+                type="button"
+                onClick={onPublish}
+                disabled={!publishable}
+                aria-label={publishLabel}
+                className={`inline-flex size-8 items-center justify-center rounded-md outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 ${
+                  publishable && unpublished ? "bg-primary/10 text-primary" : ""
+                }`}
+              >
+                <Send aria-hidden="true" className="size-4" />
+              </button>
+            </span>
+          </TooltipTrigger>
+          <TooltipContent>{publishLabel}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+      <ViewMenu views={["editor", "graph", "runs"]} />
+    </TitleRow>
+  );
+}
+
+// ⚠️ The list is the server's, not this component's. Publishing computes the same freeze from the
+// same code, so what the author agrees to here is what happens — a version resolved in the browser
+// would be a second opinion, and the two would part ways the moment someone else publishes.
+function PublishPreview({
+  flowId,
+  versionId,
+  close,
+  onPublished,
+}: {
+  flowId: string;
+  versionId: string;
+  close(): void;
+  onPublished(): Promise<void>;
+}) {
+  const { data } = useIntelRouterContext();
+  const i18n = useI18n();
+  const preview = useQuery({
+    queryKey: ["flow-publish-preview", flowId, versionId],
+    queryFn: () => data.previewFlowPublish({ flowId, versionId }),
+  });
+  const publish = useMutation({
+    mutationFn: () => data.publishFlow({ flowId, versionId, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: onPublished,
+  });
+  return (
+    <Modal title={i18n.t("flows.publishPreview")} close={close}>
+      {preview.isPending ? (
+        <p className="text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+      ) : preview.isError ? (
+        <p role="alert" className="text-sm text-destructive">
+          {i18n.t("flows.operationFailed")}
+        </p>
+      ) : (
+        <>
+          <p className="text-sm text-muted-foreground">
+            {preview.data.calls.length === 0 && preview.data.tools.length === 0
+              ? i18n.t("flows.publishPreviewEmpty")
+              : i18n.t("flows.publishPreviewIntro")}
+          </p>
+          {/* ⚠️ The tool surface belongs in the preview because publishing FREEZES it: after this
+              confirmation the step is pinned to these functions and inherits nothing the provider
+              adds later. An author who is not shown it is asked to freeze something unseen (#517). */}
+          {preview.data.tools.length > 0 && (
+            <ul className="mt-4 space-y-2">
+              {preview.data.tools.map((tool) => (
+                <li key={tool.nodeId} className="rounded-md border p-3 text-sm">
+                  <span className="block font-medium">{tool.nodeLabel}</span>
+                  <span className="block text-xs text-muted-foreground">{tool.server}</span>
+                  <span
+                    className={`mt-1 block text-xs ${tool.available ? "text-muted-foreground" : "text-destructive"}`}
+                  >
+                    {!tool.available
+                      ? i18n.t("flows.publishPreviewToolUnavailable")
+                      : tool.allow === null
+                        ? i18n.t("flows.toolAllowAll")
+                        : i18n.t("flows.publishPreviewToolAllow", {
+                            functions: tool.allow.join(", "),
+                          })}
+                  </span>
+                </li>
+              ))}
+            </ul>
+          )}
+          <ul className="mt-4 space-y-2">
+            {preview.data.calls.map((call) => {
+              // ⚠️ One condition for the sentence and its colour. They were two, so a call that
+              // rides along into a callee with nothing published read "runs along" in the colour of
+              // a failure — the reader would have gone looking for a problem that is not there.
+              const blocked = !call.available && call.mode !== "follows";
+              return (
+                <li key={call.nodeId} className="rounded-md border p-3 text-sm">
+                  <span className="block font-medium">{call.nodeLabel}</span>
+                  <span className="block text-xs text-muted-foreground">{call.calleeTitle}</span>
+                  <span
+                    className={`mt-1 block text-xs ${blocked ? "text-destructive" : "text-muted-foreground"}`}
+                  >
+                    {blocked
+                      ? i18n.t("flows.publishPreviewUnavailable")
+                      : call.freezes
+                        ? i18n.t("flows.publishPreviewFreeze", {
+                            sequence: call.versionSequence ?? 0,
+                          })
+                        : call.mode === "pinned"
+                          ? i18n.t("flows.publishPreviewPinned", {
+                              sequence: call.versionSequence ?? 0,
+                            })
+                          : i18n.t("flows.publishPreviewFollows")}
+                  </span>
+                </li>
+              );
+            })}
+          </ul>
+          {publish.isError && (
+            <p role="alert" className="mt-4 text-sm text-destructive">
+              {publishRefusalText(publish.error, i18n)}
+            </p>
+          )}
+          <button
+            type="button"
+            onClick={() => publish.mutate()}
+            disabled={publish.isPending}
+            className="mt-5 w-full rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+          >
+            {publish.isPending ? i18n.t("common.saving") : i18n.t("flows.publishConfirm")}
+          </button>
+        </>
+      )}
+    </Modal>
+  );
+}
+
+function NodeInspector({
+  node,
+  update,
+  toolServers,
+  toolServersState,
+  toolNames,
+  toolNamesFailed,
+  toolNamesPending,
+  flows,
+}: {
+  node: CanvasNode | null;
+  update(fn: (node: FlowNode) => FlowNode): void;
+  toolServers: Array<{ handle: string; name: string; toolCount: number }>;
+  // ⚠️ FOUR answers, not two. A list that is still loading is not one that came back empty; a
+  // failure is neither; and a portal this user never connected is not a portal that reaches
+  // nothing. Drawing them all as "no servers" is the mistake #350 records for the tools screen —
+  // and the fourth one is the worst of them: it answers a SIGN-IN problem with a sentence about
+  // reach, in a place that offers no way to sign in.
+  toolServersState: "pending" | "error" | "disconnected" | "ready";
+  toolNames: string[];
+  // Told apart from "this server offers nothing": a function list that could not be loaded must not
+  // read as a narrowing that lost its functions.
+  toolNamesFailed: boolean;
+  // ⚠️ A query that has not answered is not one that answered "nothing". Without this a step opened
+  // while the catalog is still loading shows its allowed functions as missing — the panel accusing
+  // the author of a narrowing that broke, moments before the list arrives.
+  toolNamesPending: boolean;
+  flows: Flow[];
+}) {
+  const i18n = useI18n();
+  if (!node) return <p className="p-5 text-sm text-muted-foreground">{i18n.t("flows.inspect")}</p>;
+  const contract = node.data.node;
+  return (
+    <div className="p-5">
+      <h2 className="font-semibold">{i18n.t(`flows.node.${contract.kind}`)}</h2>
+      {/* ⚠️ A marker has no name to give (D25). Start and End are the same two points in every
+          flow, and a start renamed "Rechnung holen" reads on the canvas as a step that does
+          something — which is exactly the confusion the layer split is meant to end. */}
+      {flowNodeLayer[contract.kind] !== "marker" && (
+        <Field
+          label={i18n.t("common.title")}
+          value={contract.label}
+          setValue={(label) => update((value) => ({ ...value, label }))}
+        />
+      )}
+      {(contract.kind === "instruction" || contract.kind === "condition") && (
+        <TextArea
+          label={i18n.t("flows.instruction")}
+          hint={i18n.t("flows.instructionHint")}
+          value={
+            contract.kind === "instruction"
+              ? contract.configuration.prompt
+              : contract.configuration.instruction
+          }
+          setValue={(text) =>
+            update((value) =>
+              value.kind === "instruction"
+                ? { ...value, configuration: { prompt: text } }
+                : value.kind === "condition"
+                  ? {
+                      ...value,
+                      configuration: { mode: "semantic", instruction: text },
+                    }
+                  : value,
+            )
+          }
+        />
+      )}
+      {/* ⚠️ One reference, chosen — not a list, ticked. What replaces this properly is the picker
+          in #75 (search, the tree, dropping from the sidebar); until then a select does the one
+          thing the layer rule needs it to do, which is make "exactly one" the only sayable state.
+          The list is filtered to the kind of the node, so a Table node cannot name a folder. */}
+      {isLinkNode(contract) && (
+        <EntryPicker
+          kind={nodeKindOfLink[contract.kind] ?? null}
+          value={contract.configuration.resourceId}
+          label={i18n.t(`flows.node.${contract.kind}`)}
+          onSelect={(resourceId) =>
+            update((value) =>
+              isLinkNode(value) ? { ...value, configuration: { resourceId } } : value,
+            )
+          }
+        />
+      )}
+      {contract.kind === "subflow" && (
+        <div className="mt-4">
+          <label className="block text-sm font-medium">
+            {i18n.t("flows.subflowTarget")}
+            <select
+              value={contract.configuration.flowId}
+              onChange={(event) => {
+                const flowId = event.target.value;
+                update((value) =>
+                  value.kind === "subflow"
+                    ? { ...value, configuration: { ...value.configuration, flowId } }
+                    : value,
+                );
+              }}
+              className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <option value="">{i18n.t("flows.selectSubflow")}</option>
+              {flows.map((entry) => (
+                <option key={entry.id} value={entry.id}>
+                  {entry.title}
+                </option>
+              ))}
+            </select>
+          </label>
+          {/* The call rule is a folder question, so it cannot be answered while typing. Publishing
+              answers it and names the reason. */}
+          <p className="mt-2 text-xs text-muted-foreground">{i18n.t("flows.subflowRule")}</p>
+          <SubflowVersionField configuration={contract.configuration} update={update} />
+        </div>
+      )}
+      {contract.kind === "tool" && (
+        <ToolStepFields
+          configuration={contract.configuration}
+          servers={toolServers}
+          state={toolServersState}
+          toolNames={toolNames}
+          toolNamesFailed={toolNamesFailed}
+          toolNamesPending={toolNamesPending}
+          update={update}
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * What a tool step may reach: one server, and optionally only some of its functions.
+ *
+ * ⚠️ The server comes first and the functions are a NARROWING, not the other way round (#489). The
+ * old field offered every function of every server in one flat list — 85 entries here, portal
+ * management tools among them — and asked the author to pick the one call they wanted before they
+ * knew what the step would say. Which function runs is a run-time answer; which server may be
+ * reached is an authoring decision, and that is the one this asks for.
+ */
+export function ToolStepFields({
+  configuration,
+  servers,
+  state,
+  toolNames,
+  toolNamesFailed,
+  toolNamesPending,
+  update,
+}: {
+  configuration: { server: string; allow: string[] | null; fingerprint: string | null };
+  servers: Array<{ handle: string; name: string; toolCount: number }>;
+  state: "pending" | "error" | "disconnected" | "ready";
+  toolNames: string[];
+  toolNamesFailed: boolean;
+  toolNamesPending: boolean;
+  update(fn: (node: FlowNode) => FlowNode): void;
+}) {
+  const i18n = useI18n();
+  // ⚠️ The group's identity, not its data. Two steps on one screen with the same server would
+  // otherwise share one radio group and unset each other — and the component is exported now, so
+  // that invariant no longer lives in the file that guarantees it.
+  const groupId = useId();
+  const hintId = `${groupId}-hint`;
+  // The one sentence this field has to say, or none. Derived once so the control and the paragraph
+  // cannot disagree about whether there is something to point at.
+  const hint =
+    state === "error"
+      ? ({ key: "flows.toolServersFailed", tone: "bad" } as const)
+      : state === "disconnected"
+        ? ({ key: "flows.toolServersDisconnected", tone: "bad" } as const)
+        : state === "ready" && servers.length === 0
+          ? ({ key: "flows.toolServersEmpty", tone: "plain" } as const)
+          : null;
+  const ownFunctions = toolNames.filter(
+    (name) => configuration.server !== "" && serverOf(name, [configuration.server]) !== null,
+  );
+  // ⚠️ An allowed function the catalog does not carry is DRAWN, not dropped. Rendering only what
+  // the catalog knows would let the panel and the saved graph disagree in silence: the author reads
+  // "narrowed to nothing" while the step still names something. The API treats the same condition
+  // as serious enough to refuse a publish, so the editor may not swallow it.
+  // Nothing is "missing" until the catalog has actually answered.
+  const missing = toolNamesPending
+    ? []
+    : (configuration.allow ?? []).filter((name) => !ownFunctions.includes(name));
+  const functions = [...ownFunctions, ...missing];
+
+  function setTool(
+    change: (current: { server: string; allow: string[] | null; fingerprint: string | null }) => {
+      server: string;
+      allow: string[] | null;
+      fingerprint: string | null;
+    },
+  ) {
+    update((value) =>
+      value.kind === "tool" ? { ...value, configuration: change(value.configuration) } : value,
+    );
+  }
+
+  return (
+    <div className="mt-4 space-y-3">
+      <label className="block text-sm font-medium">
+        {i18n.t("flows.tool")}
+        <select
+          value={configuration.server}
+          // ⚠️ A disabled control drops out of the tab order, so the reason has to be ANNOUNCED
+          // rather than merely printed beside it. It points at the hint only when the hint is
+          // actually rendered — `pending` prints nothing on purpose, and a reference to an id that
+          // does not exist is worse than none: a screen reader reads it as a broken relation.
+          aria-describedby={hint === null ? undefined : hintId}
+          disabled={state !== "ready" || servers.length === 0}
+          onChange={(event) => {
+            // ⚠️ Read out of the event NOW, not inside the updater. The updater runs later, and by
+            // then this controlled select has been set back to the state's value — the change would
+            // apply to itself and nothing would move.
+            const server = event.target.value;
+            // Changing the server drops the narrowing AND the frozen surface. Keeping `allow` would
+            // leave functions of the old server behind — the contract refuses that outright — and
+            // keeping the fingerprint would claim a surface nobody has confirmed.
+            setTool(() => ({ server, allow: null, fingerprint: null }));
+          }}
+          className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+        >
+          <option value="">{i18n.t("flows.selectTool")}</option>
+          {servers.map((entry) => (
+            <option key={entry.handle} value={entry.handle}>
+              {entry.name}
+            </option>
+          ))}
+        </select>
+      </label>
+      {/* The three states of the list, told apart. Silence while loading; a reason when it failed;
+          and "you reach none" only once that is actually known. */}
+      {hint !== null && (
+        <p
+          id={hintId}
+          className={`text-xs ${hint.tone === "bad" ? "text-destructive" : "text-muted-foreground"}`}
+        >
+          {i18n.t(hint.key)}
+        </p>
+      )}
+      {configuration.server !== "" && (
+        <fieldset className="space-y-2">
+          <legend className="text-sm font-medium">{i18n.t("flows.toolFunctions")}</legend>
+          <label className="flex items-center gap-2 text-sm">
+            <input
+              type="radio"
+              name={groupId}
+              checked={configuration.allow === null}
+              onChange={() =>
+                setTool((current) => ({ ...current, allow: null, fingerprint: null }))
+              }
+              className="size-4"
+            />
+            {i18n.t("flows.toolAllowAll")}
+          </label>
+          <label className="flex items-center gap-2 text-sm">
+            <input
+              type="radio"
+              name={groupId}
+              checked={configuration.allow !== null}
+              onChange={() => setTool((current) => ({ ...current, allow: [], fingerprint: null }))}
+              className="size-4"
+            />
+            {i18n.t("flows.toolAllowSome")}
+          </label>
+          {configuration.allow !== null && (
+            <ul className="max-h-48 space-y-1 overflow-y-auto pl-6">
+              {functions.map((name) => (
+                <li key={name}>
+                  <label className="flex items-center gap-2 text-sm">
+                    <input
+                      type="checkbox"
+                      checked={configuration.allow?.includes(name) ?? false}
+                      onChange={(event) => {
+                        // Same reason as the select above: the checked flag is read now, the
+                        // updater runs later.
+                        const add = event.target.checked;
+                        setTool((current) => ({
+                          ...current,
+                          allow: add
+                            ? [...(current.allow ?? []), name]
+                            : (current.allow ?? []).filter((entry) => entry !== name),
+                          fingerprint: null,
+                        }));
+                      }}
+                      className="size-4"
+                    />
+                    <span className="min-w-0 truncate">{name}</span>
+                  </label>
+                </li>
+              ))}
+            </ul>
+          )}
+          {/* Two sentences that only appear when they are true, and neither is the generic hint:
+              a narrowing to nothing cannot be published, and a name the catalog does not carry is
+              something the author has to see rather than lose. */}
+          {configuration.allow?.length === 0 && (
+            <p className="text-xs text-destructive">{i18n.t("flows.toolAllowNone")}</p>
+          )}
+          {toolNamesFailed && (
+            <p className="text-xs text-destructive">{i18n.t("flows.toolFunctionsFailed")}</p>
+          )}
+          {!toolNamesFailed && missing.length > 0 && (
+            <p className="text-xs text-destructive">
+              {i18n.t("flows.toolAllowUnknown", { count: missing.length })}
+            </p>
+          )}
+          <p className="text-xs text-muted-foreground">{i18n.t("flows.toolAllowHint")}</p>
+        </fieldset>
+      )}
+    </div>
+  );
+}
+
+// "What this flow needs": the documents and tools the graph names, and nothing about who may reach
+// them. A standing "this flow has conflicts" badge is not offered on purpose — for tools it could
+// never be true, because the catalog is a live query with each user's own portal token (ADR-0003).
+function FlowNeeds({ flowId }: { flowId: string }) {
+  const { data } = useIntelRouterContext();
+  const i18n = useI18n();
+  const needs = useQuery({
+    queryKey: ["flow-requirements", flowId],
+    queryFn: () => data.getFlowRequirements(flowId),
+  });
+  // ⚠️ A flow that touches nothing and a flow whose every reference is hidden or dead are three
+  // different answers, so neither the counted nor the broken ones may fall out of this condition —
+  // otherwise the panel claims the first when it means one of the others.
+  const empty =
+    needs.data !== undefined &&
+    needs.data.nodes.length === 0 &&
+    needs.data.invalidNodes.length === 0 &&
+    needs.data.hiddenNodes === 0 &&
+    needs.data.servers.length === 0;
+  return (
+    <section aria-label={i18n.t("flows.needs")} className="mt-auto border-t p-5">
+      <h2 className="font-semibold">{i18n.t("flows.needs")}</h2>
+      {needs.isPending && (
+        <p className="mt-2 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>
+      )}
+      {needs.isError && (
+        <p role="alert" className="mt-2 text-sm text-destructive">
+          {i18n.t("flows.needsFailed")}
+        </p>
+      )}
+      {empty && <p className="mt-2 text-sm text-muted-foreground">{i18n.t("flows.needsEmpty")}</p>}
+      {needs.data && !empty && (
+        <>
+          {(needs.data.nodes.length > 0 ||
+            needs.data.invalidNodes.length > 0 ||
+            needs.data.hiddenNodes > 0) && (
+            <>
+              <h3 className="mt-4 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                {i18n.t("flows.needsNodes")}
+              </h3>
+              <ul className="mt-2 space-y-1 text-sm">
+                {needs.data.nodes.map((reference) => (
+                  <li key={reference.id} className="flex items-center gap-2">
+                    <FileSearch aria-hidden="true" className="size-3.5 shrink-0" />
+                    <span className="min-w-0 truncate">{reference.title}</span>
+                  </li>
+                ))}
+                {/* ⚠️ A dead reference and an unreachable one are two entries, not one (#509).
+                    They used to share the counted line, which said "you cannot see it" about a
+                    document that is gone — a sentence about a permission, in front of something no
+                    permission can fix. This one says what to do instead, because there is exactly
+                    one thing to do: replace the step or take it out. */}
+                {needs.data.invalidNodes.length > 0 && (
+                  <li className="text-destructive">
+                    {i18n.t("flows.needsInvalid", { count: needs.data.invalidNodes.length })}
+                  </li>
+                )}
+                {/* ⚠️ Counted, never named. A title is exactly what someone without access to the
+                    document may not learn from a list about it. */}
+                {needs.data.hiddenNodes > 0 && (
+                  <li className="text-muted-foreground">
+                    {i18n.t("flows.needsHidden", { count: needs.data.hiddenNodes })}
+                  </li>
+                )}
+              </ul>
+            </>
+          )}
+          {needs.data.servers.length > 0 && (
+            <>
+              <h3 className="mt-4 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                {i18n.t("flows.needsTools")}
+              </h3>
+              <ul className="mt-2 space-y-1 text-sm">
+                {needs.data.servers.map((name) => (
+                  <li key={name} className="flex items-center gap-2">
+                    <Wrench aria-hidden="true" className="size-3.5 shrink-0" />
+                    <span className="min-w-0 truncate">{name}</span>
+                  </li>
+                ))}
+              </ul>
+            </>
+          )}
+        </>
+      )}
+    </section>
+  );
+}
+
+// The version choice of one call (ADR-0004 §5). Two of the three modes are chosen here; the third,
+// `pinned`, is what publishing writes, so it is offered as the current value and can be given up
+// again — but no arbitrary version is picked by hand. Which version a pin points at is a fact of the
+// published graph, not something to browse for while drafting.
+function SubflowVersionField({
+  configuration,
+  update,
+}: {
+  configuration: Extract<FlowNode, { kind: "subflow" }>["configuration"];
+  update(fn: (node: FlowNode) => FlowNode): void;
+}) {
+  const i18n = useI18n();
+  const mode = configuration.version.mode;
+  return (
+    <div className="mt-4">
+      <label className="block text-sm font-medium">
+        {i18n.t("flows.subflowVersion")}
+        <select
+          value={mode}
+          onChange={(event) => {
+            const next = event.target.value;
+            if (next !== "latest" && next !== "follows") return;
+            update((value) =>
+              value.kind === "subflow"
+                ? { ...value, configuration: { ...value.configuration, version: { mode: next } } }
+                : value,
+            );
+          }}
+          className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <option value="latest">{i18n.t("flows.subflowVersion.latest")}</option>
+          <option value="follows">{i18n.t("flows.subflowVersion.follows")}</option>
+          {mode === "pinned" && (
+            <option value="pinned">{i18n.t("flows.subflowVersion.pinned")}</option>
+          )}
+        </select>
+      </label>
+      <p className="mt-2 text-xs text-muted-foreground">
+        {i18n.t(`flows.subflowVersionHint.${mode}`)}
+      </p>
+    </div>
+  );
+}
+
+function Field({
+  label,
+  value,
+  setValue,
+}: {
+  label: string;
+  value: string;
+  setValue(value: string): void;
+}) {
+  return (
+    <label className="mt-4 block text-sm font-medium">
+      {label}
+      <input
+        value={value}
+        onChange={(event) => setValue(event.target.value)}
+        className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      />
+    </label>
+  );
+}
+function TextArea({
+  label,
+  value,
+  setValue,
+  hint,
+}: {
+  label: string;
+  value: string;
+  setValue(value: string): void;
+  hint?: string;
+}) {
+  const hintId = useId();
+  return (
+    <label className="mt-4 block text-sm font-medium">
+      <span className="flex items-center gap-1.5">
+        {label}
+        {/* The note that keeps the box of parts small (#39): a condition, a check or a branch can be
+            said in words inside the instruction, so `condition` can stay a node without everyone
+            having to drag one for every small decision. A button, not a bare icon — a hint reachable
+            only by hovering is not reachable at all. */}
+        {hint && (
+          <button
+            type="button"
+            aria-label={hint}
+            aria-describedby={hintId}
+            title={hint}
+            className="inline-flex size-4 shrink-0 items-center justify-center rounded-full text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            <Info aria-hidden="true" className="size-3.5" />
+          </button>
+        )}
+      </span>
+      <textarea
+        rows={6}
+        value={value}
+        aria-describedby={hint ? hintId : undefined}
+        onChange={(event) => setValue(event.target.value)}
+        className="mt-2 w-full resize-y rounded-md border bg-background px-3 py-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      />
+      {hint && (
+        <span id={hintId} className="mt-1 block text-xs font-normal text-muted-foreground">
+          {hint}
+        </span>
+      )}
+    </label>
+  );
+}