@anchrd/intel-ui 0.4.0 → 0.6.0

package/src/flows/flows.tsx

@@ -1,6 +1,6 @@
-import type { FlowGraph, FlowNode, KnowledgeNode, ResourceRole } from "@anchrd/intel-contract";
+import type { Flow, FlowGraph, FlowNode, KnowledgeNode } from "@anchrd/intel-contract";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { useRouterState } from "@tanstack/react-router";
+import { useNavigate, useRouterState } from "@tanstack/react-router";
 import {
   addEdge,
   applyEdgeChanges,
@@ -18,60 +18,82 @@ import {
   Position,
   ReactFlow,
 } from "@xyflow/react";
-import {
-  Bot,
-  CheckCircle2,
-  CirclePlay,
-  FileSearch,
-  GitBranch,
-  Save,
-  Send,
-  Share2,
-  ShieldCheck,
-  Sparkles,
-  Trash2,
-  Wrench,
-} from "lucide-react";
-import { useEffect, useMemo, useState } from "react";
-import { HeaderActions } from "@/app/header-actions/header-actions.tsx";
+import { FileSearch, Info, Send, Wrench } from "lucide-react";
+import { useEffect, useId, useMemo, useState } from "react";
+import { ActionSlot } from "@/app/action-slot/action-slot.tsx";
+import { ViewToggle } from "@/app/view-toggle/view-toggle.tsx";
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+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 { Modal } from "@/modal/modal.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
-import { selectedFrom } from "@/router/selection-search.ts";
+import { selectedFrom, viewFrom } from "@/router/selection-search.ts";
+import { SaveButton, UnsavedChangesGuard } from "@/save-button/save-button.tsx";
+import { useSystemTheme } from "@/theme/theme.ts";
+import { TitleRow } from "@/title-row/title-row.tsx";
 
 type CanvasNode = Node<{ node: FlowNode }, "intel">;
 type CanvasEdge = Edge;
 
-const nodeIcon = {
-  trigger: CirclePlay,
-  instruction: Sparkles,
-  knowledge: FileSearch,
-  tool: Wrench,
-  condition: GitBranch,
-  approval: ShieldCheck,
-  output: CheckCircle2,
-} as const;
+// 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";
+
+// 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",
+  "knowledge",
+  "tool",
+  "condition",
+  "approval",
+  "subflow",
+  "output",
+] as const;
 
 function FlowCard({ data, selected }: NodeProps<CanvasNode>) {
+  const { i18n } = useIntelRouterContext();
   const contract = data.node;
   const Icon = nodeIcon[contract.kind];
   const branching = contract.kind === "condition" || contract.kind === "approval";
+  // ⚠️ 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 rounded-xl border bg-card p-3 text-card-foreground shadow-sm ${selected ? "ring-2 ring-ring" : ""}`}
+      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 place-items-center rounded-lg bg-primary/10 text-primary">
+        <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>
-          <span className="block text-xs capitalize text-muted-foreground">{contract.kind}</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). */}
+          <span className="block text-xs text-muted-foreground">
+            {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.description && (
-        <p className="mt-2 line-clamp-2 text-xs text-muted-foreground">{contract.description}</p>
-      )}
       {contract.kind !== "output" && !branching && (
         <Handle type="source" position={Position.Right} />
       )}
@@ -91,6 +113,15 @@ function FlowCard({ data, selected }: NodeProps<CanvasNode>) {
           />
         </>
       )}
+      {/* 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>
   );
 }
@@ -104,7 +135,6 @@ function defaultGraph(): FlowGraph {
         id: "trigger",
         kind: "trigger",
         label: "Manual start",
-        description: null,
         position: { x: 80, y: 180 },
         configuration: { mode: "manual" },
       },
@@ -112,7 +142,6 @@ function defaultGraph(): FlowGraph {
         id: "output",
         kind: "output",
         label: "Result",
-        description: null,
         position: { x: 520, y: 180 },
         configuration: { template: "" },
       },
@@ -122,6 +151,7 @@ function defaultGraph(): FlowGraph {
         id: "trigger-output",
         source: "trigger",
         target: "output",
+        kind: "flow",
         label: null,
         sourceHandle: null,
       },
@@ -137,13 +167,31 @@ function canvas(graph: FlowGraph) {
       position: node.position,
       data: { node },
     })),
-    edges: graph.edges.map((edge) => ({
-      id: edge.id,
-      source: edge.source,
-      target: edge.target,
-      sourceHandle: edge.sourceHandle,
-      label: edge.label ?? undefined,
-    })),
+    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,
   };
 }
 
@@ -153,31 +201,58 @@ function graph(nodes: CanvasNode[], edges: CanvasEdge[]): FlowGraph {
       ...node.data.node,
       position: node.position,
     })),
-    edges: edges.map((edge) => ({
-      id: edge.id,
-      source: edge.source,
-      target: edge.target,
-      label: typeof edge.label === "string" && edge.label ? edge.label : null,
-      sourceHandle: edge.sourceHandle ?? null,
-    })),
+    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",
+  );
+}
+
 function newNode(
-  kind: Exclude<FlowNode["kind"], "trigger">,
+  kind: FlowNode["kind"],
   index: number,
   firstKnowledgeId?: string,
+  firstFlowId?: string,
 ): FlowNode {
   const common = {
     id: `${kind}-${crypto.randomUUID()}`,
     label: kind[0]?.toUpperCase() + kind.slice(1),
-    description: null,
     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,
@@ -222,6 +297,14 @@ function newNode(
           timeout: "7 days",
         },
       };
+    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: { template: "" } };
   }
@@ -229,7 +312,9 @@ function newNode(
 
 export function Flows() {
   const { data, i18n } = useIntelRouterContext();
+  const theme = useSystemTheme();
   const queryClient = useQueryClient();
+  const navigate = useNavigate();
   const tools = useQuery({
     queryKey: ["tools"],
     queryFn: () => data.listTools(),
@@ -240,12 +325,36 @@ export function Flows() {
     queryKey: ["knowledge-graph"],
     queryFn: () => data.getKnowledgeGraph(),
   });
-  // The tree in the sidebar and the header search both name the flow to open through `?select=`.
-  const selectedFlowId = useRouterState({
-    select: (state) => selectedFrom(state.location.search),
+  // 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 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 [sharing, setSharing] = useState(false);
+  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();
+  // A flow is shared through the folder it is filed in, on the Knowledge screen (ADR-0004 §2). It
+  // has no share action of its own — a narrower grant beside the folder's would break the guarantee
+  // that a flow only reaches flows in its own subtree.
   const document = useQuery({
     queryKey: ["flow", selectedFlowId],
     queryFn: () => data.getFlow(selectedFlowId ?? ""),
@@ -254,6 +363,7 @@ export function Flows() {
   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;
@@ -264,6 +374,7 @@ export function Flows() {
     setNodes(next.nodes);
     setEdges(next.edges);
     setSelectedNodeId(null);
+    setDirty(false);
   }, [document.data, selectedFlowId]);
   const selectedNode = nodes.find((node) => node.id === selectedNodeId) ?? null;
 
@@ -275,19 +386,16 @@ export function Flows() {
         graph: graph(nodes, edges),
         idempotencyKey: crypto.randomUUID(),
       }),
-    onSuccess: (saved) => {
+    onSuccess: async (saved) => {
+      setDirty(false);
       queryClient.setQueryData(["flow", saved.flow.id], saved);
-    },
-  });
-  const publish = useMutation({
-    mutationFn: () =>
-      data.publishFlow({
-        flowId: selectedFlowId ?? "",
-        versionId: document.data?.flow.currentVersionId ?? "",
-        idempotencyKey: crypto.randomUUID(),
-      }),
-    onSuccess: async () => {
-      await queryClient.invalidateQueries({ queryKey: ["flow", selectedFlowId] });
+      // 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] }),
+      ]);
     },
   });
   const run = useMutation({
@@ -295,11 +403,13 @@ export function Flows() {
       data.startFlow({
         flowId: selectedFlowId ?? "",
         input: {},
+        parent: null,
         idempotencyKey: crypto.randomUUID(),
       }),
   });
 
   function updateNode(update: (node: FlowNode) => FlowNode) {
+    setDirty(true);
     setNodes((current) =>
       current.map((node) =>
         node.id === selectedNodeId ? { ...node, data: { node: update(node.data.node) } } : node,
@@ -309,45 +419,43 @@ export function Flows() {
 
   return (
     <div className="flex h-full min-h-0 flex-col">
-      {/* A flow's own actions, in the shell's action bar. Creating a flow is not among them: that
-          belongs to the tree, at the folder the flow is meant to live in. */}
+      {/* Only the view switch belongs to the area: it says how the thing the breadcrumb names is
+          being shown, and it is mounted only where there is a flow to draw — a switch with nothing
+          to point at is what #19 rules out for the header. A flow is the one level that has runs,
+          so it is the one that offers the third view (#35). Everything that acts on the flow itself
+          left this bar for the flow's own title line below (#24). */}
       {selectedFlowId ? (
-        <HeaderActions>
-          <button
-            type="button"
-            onClick={() => setSharing(true)}
-            className="inline-flex h-8 items-center gap-2 rounded-md border bg-background px-2.5 text-sm outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring"
-          >
-            <Share2 aria-hidden="true" className="size-4" /> {i18n.t("flows.share")}
-          </button>
-          <button
-            type="button"
-            onClick={() => save.mutate()}
-            disabled={!canMutate || save.isPending}
-            className="inline-flex h-8 items-center gap-2 rounded-md border bg-background px-2.5 text-sm outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
-          >
-            <Save aria-hidden="true" className="size-4" /> {i18n.t("common.save")}
-          </button>
-          <button
-            type="button"
-            onClick={() => publish.mutate()}
-            disabled={!canMutate || !document.data?.flow.currentVersionId || publish.isPending}
-            className="inline-flex h-8 items-center gap-2 rounded-md border bg-background px-2.5 text-sm outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
-          >
-            <Send aria-hidden="true" className="size-4" /> {i18n.t("flows.publish")}
-          </button>
-          <button
-            type="button"
-            onClick={() => run.mutate()}
-            disabled={!canMutate || !document.data?.flow.publishedVersionId || run.isPending}
-            className="inline-flex h-8 items-center gap-2 rounded-md bg-primary px-2.5 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
-          >
-            <Bot aria-hidden="true" className="size-4" /> {i18n.t("flows.run")}
-          </button>
-        </HeaderActions>
+        <ActionSlot>
+          <ViewToggle views={["editor", "graph", "runs"]} />
+        </ActionSlot>
       ) : null}
+      {selectedFlowId && document.data ? (
+        <FlowTitle
+          flow={document.data.flow}
+          dirty={dirty}
+          saving={save.isPending}
+          canMutate={canMutate}
+          running={run.isPending}
+          onSave={() => save.mutate()}
+          onPublish={() => setPublishing(true)}
+          onRun={() => run.mutate()}
+        />
+      ) : null}
+      <UnsavedChangesGuard dirty={dirty} />
       <div className="flex min-h-0 flex-1">
-        {!selectedFlowId ? (
+        {selectedFlowId && selection.view === "runs" ? (
+          <FlowRuns flowId={selectedFlowId} />
+        ) : selectedFlowId && selection.view === "graph" ? (
+          <GraphPane
+            query={relations}
+            select={(node) =>
+              void navigate({
+                to: node.kind === "flow" ? "/flows" : "/knowledge",
+                search: { select: node.id },
+              })
+            }
+          />
+        ) : !selectedFlowId ? (
           <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
             {i18n.t("flows.select")}
           </div>
@@ -365,65 +473,108 @@ export function Flows() {
         ) : (
           <>
             <section className="relative min-w-0 flex-1">
-              <div className="absolute left-4 top-4 z-10 flex max-w-[calc(100%-2rem)] flex-wrap gap-1 rounded-lg border bg-card/95 p-2 shadow-sm backdrop-blur">
-                {(
-                  ["instruction", "knowledge", "tool", "condition", "approval", "output"] as const
-                ).map((kind) => {
-                  const Icon = nodeIcon[kind];
-                  return (
-                    <button
-                      key={kind}
-                      type="button"
-                      onClick={() => {
-                        const item = newNode(kind, nodes.length, knowledge.data?.nodes[0]?.id);
-                        setNodes((current) => [
-                          ...current,
-                          {
-                            id: item.id,
-                            type: "intel",
-                            position: item.position,
-                            data: { node: item },
-                          },
-                        ]);
-                      }}
-                      className="inline-flex items-center gap-1.5 rounded-md px-2 py-1.5 text-xs outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
-                    >
-                      <Icon aria-hidden="true" className="size-3.5" />
-                      {i18n.t(`flows.node.${kind}`)}
-                    </button>
+              {/* 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,
+                    knowledge.data?.nodes[0]?.id,
+                    callable.data?.items.find((entry) => entry.id !== selectedFlowId)?.id,
                   );
-                })}
-              </div>
+                  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 — for the same reason `.react-sigma` is there. */}
               <ReactFlow<CanvasNode, CanvasEdge>
+                colorMode={theme}
                 nodes={nodes}
                 edges={edges}
                 nodeTypes={nodeTypes}
                 fitView
-                onNodesChange={(changes: NodeChange<CanvasNode>[]) =>
-                  setNodes((current) => applyNodeChanges(changes, current))
-                }
-                onEdgesChange={(changes: EdgeChange<CanvasEdge>[]) =>
-                  setEdges((current) => applyEdgeChanges(changes, current))
+                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) =>
+                onConnect={(connection: Connection) => {
+                  setDirty(true);
                   setEdges((current) =>
-                    addEdge({ ...connection, id: crypto.randomUUID() }, current),
-                  )
-                }
+                    addEdge(
+                      {
+                        ...connection,
+                        id: crypto.randomUUID(),
+                        ...contextEdgeStyle(connection.sourceHandle === ContextHandle),
+                      },
+                      current,
+                    ),
+                  );
+                }}
                 onNodeClick={(_event, node) => setSelectedNodeId(node.id)}
-                onPaneClick={() => setSelectedNodeId(null)}
+                onPaneClick={() => {
+                  setSelectedNodeId(null);
+                  setPaletteOpen(false);
+                }}
               >
                 <Background />
-                <MiniMap pannable zoomable />
+                {/* 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>
             </section>
-            <NodeInspector
-              node={selectedNode}
-              update={updateNode}
-              tools={tools.data?.items ?? []}
-              knowledge={knowledge.data?.nodes ?? []}
-            />
+            <aside className="flex w-80 shrink-0 flex-col overflow-y-auto border-l bg-card">
+              <NodeInspector
+                node={selectedNode}
+                update={updateNode}
+                tools={tools.data?.items ?? []}
+                knowledge={knowledge.data?.nodes ?? []}
+                flows={(callable.data?.items ?? []).filter((entry) => entry.id !== selectedFlowId)}
+              />
+              <FlowNeeds flowId={selectedFlowId} />
+            </aside>
           </>
         )}
       </div>
@@ -435,7 +586,7 @@ export function Flows() {
           </p>
         </div>
       )}
-      {(save.isError || publish.isError || run.isError) && (
+      {(save.isError || run.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"
@@ -443,121 +594,199 @@ export function Flows() {
           {i18n.t("flows.operationFailed")}
         </p>
       )}
-      {sharing && selectedFlowId && (
-        <ShareFlow flowId={selectedFlowId} close={() => setSharing(false)} />
-      )}
+      {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}
     </div>
   );
 }
 
-function ShareFlow({ flowId, close }: { flowId: string; close(): void }) {
+/**
+ * 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,
+  running,
+  onSave,
+  onPublish,
+  onRun,
+}: {
+  flow: Flow;
+  dirty: boolean;
+  saving: boolean;
+  canMutate: boolean;
+  running: boolean;
+  onSave(): void;
+  onPublish(): void;
+  onRun(): void;
+}) {
+  const { i18n } = useIntelRouterContext();
+  // 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} description={flow.description} target={{ type: "flow", flow }}>
+      <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 border bg-background outline-none hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50 ${
+                  publishable && unpublished ? "border-primary text-primary" : ""
+                }`}
+              >
+                <Send aria-hidden="true" className="size-4" />
+              </button>
+            </span>
+          </TooltipTrigger>
+          <TooltipContent>{publishLabel}</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+      <SaveButton dirty={dirty && canMutate} saving={saving} onSave={onSave} />
+      <button
+        type="button"
+        onClick={onRun}
+        disabled={!canMutate || unpublished || running}
+        className="inline-flex h-8 items-center rounded-md bg-primary px-3 text-sm font-medium text-primary-foreground outline-none hover:bg-primary/90 focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
+      >
+        {i18n.t("flows.run")}
+      </button>
+    </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, i18n } = useIntelRouterContext();
-  const queryClient = useQueryClient();
-  const [email, setEmail] = useState("");
-  const [role, setRole] = useState<ResourceRole>("viewer");
-  const grants = useQuery({
-    queryKey: ["flow-grants", flowId],
-    queryFn: () => data.listFlowGrants(flowId),
+  const preview = useQuery({
+    queryKey: ["flow-publish-preview", flowId, versionId],
+    queryFn: () => data.previewFlowPublish({ flowId, versionId }),
   });
-  const share = useMutation({
-    mutationFn: () =>
-      data.shareFlow({
-        resourceId: flowId,
-        principal: { type: "email", email },
-        role,
-        expiresAt: null,
-        idempotencyKey: crypto.randomUUID(),
-      }),
-    onSuccess: async () => {
-      setEmail("");
-      await queryClient.invalidateQueries({
-        queryKey: ["flow-grants", flowId],
-      });
-    },
-  });
-  const revoke = useMutation({
-    mutationFn: (grantId: string) =>
-      data.revokeFlowGrant({
-        resourceId: flowId,
-        grantId,
-        idempotencyKey: crypto.randomUUID(),
-      }),
-    onSuccess: async () => {
-      await queryClient.invalidateQueries({
-        queryKey: ["flow-grants", flowId],
-      });
-    },
+  const publish = useMutation({
+    mutationFn: () => data.publishFlow({ flowId, versionId, idempotencyKey: crypto.randomUUID() }),
+    onSuccess: onPublished,
   });
-
   return (
-    <Modal title={i18n.t("flows.share")} close={close}>
-      {(share.isError || revoke.isError) && (
-        <p role="alert" className="mb-4 text-sm text-destructive">
-          {i18n.t("flows.shareFailed")}
+    <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>
-      )}
-      <ul className="mb-5 max-h-44 space-y-2 overflow-y-auto">
-        {grants.data?.items.map((grant) => (
-          <li
-            key={grant.id}
-            className="flex items-center justify-between gap-3 rounded-md border p-3 text-sm"
-          >
-            <span className="min-w-0 truncate">
-              {grant.principal.type === "email"
-                ? grant.principal.email
-                : grant.principal.type === "user"
-                  ? grant.principal.id
-                  : i18n.t("flows.organization")}
-              <span className="ml-2 text-xs text-muted-foreground">{grant.role}</span>
-            </span>
-            <button
-              type="button"
-              onClick={() => revoke.mutate(grant.id)}
-              aria-label={i18n.t("flows.revokeShare")}
-              className="rounded-md p-2 text-destructive outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
-            >
-              <Trash2 aria-hidden="true" className="size-4" />
-            </button>
-          </li>
-        ))}
-      </ul>
-      <form
-        className="space-y-4 border-t pt-5"
-        onSubmit={(event) => {
-          event.preventDefault();
-          share.mutate();
-        }}
-      >
-        <label className="block text-sm font-medium">
-          {i18n.t("knowledge.email")}
-          <input
-            type="email"
-            required
-            value={email}
-            onChange={(event) => setEmail(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>
-        <label className="block text-sm font-medium">
-          {i18n.t("knowledge.role")}
-          <select
-            value={role}
-            onChange={(event) => setRole(event.target.value as ResourceRole)}
-            className="mt-2 w-full rounded-md border bg-background px-3 py-2 outline-none focus-visible:ring-2 focus-visible:ring-ring"
+      ) : (
+        <>
+          <p className="text-sm text-muted-foreground">
+            {preview.data.calls.length === 0
+              ? i18n.t("flows.publishPreviewEmpty")
+              : i18n.t("flows.publishPreviewIntro")}
+          </p>
+          <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">
+              {i18n.t("flows.publishFailed")}
+            </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"
           >
-            <option value="viewer">{i18n.t("knowledge.viewer")}</option>
-            <option value="editor">{i18n.t("knowledge.editor")}</option>
-            <option value="manager">{i18n.t("knowledge.manager")}</option>
-          </select>
-        </label>
-        <button
-          type="submit"
-          disabled={share.isPending}
-          className="w-full rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
-        >
-          {i18n.t("knowledge.shareAction")}
-        </button>
-      </form>
+            {publish.isPending ? i18n.t("common.saving") : i18n.t("flows.publishConfirm")}
+          </button>
+        </>
+      )}
     </Modal>
   );
 }
@@ -567,40 +796,31 @@ function NodeInspector({
   update,
   tools,
   knowledge,
+  flows,
 }: {
   node: CanvasNode | null;
   update(fn: (node: FlowNode) => FlowNode): void;
   tools: Array<{ name: string; title: string | null; fingerprint: string }>;
   knowledge: KnowledgeNode[];
+  flows: Flow[];
 }) {
   const { i18n } = useIntelRouterContext();
-  if (!node)
-    return (
-      <aside className="w-80 shrink-0 border-l bg-card p-5 text-sm text-muted-foreground">
-        {i18n.t("flows.inspect")}
-      </aside>
-    );
+  if (!node) return <p className="p-5 text-sm text-muted-foreground">{i18n.t("flows.inspect")}</p>;
   const contract = node.data.node;
   return (
-    <aside className="w-80 shrink-0 overflow-y-auto border-l bg-card p-5">
+    <div className="p-5">
       <h2 className="font-semibold">{i18n.t(`flows.node.${contract.kind}`)}</h2>
       <Field
         label={i18n.t("common.title")}
         value={contract.label}
         setValue={(label) => update((value) => ({ ...value, label }))}
       />
-      <Field
-        label={i18n.t("flows.nodeDescription")}
-        value={contract.description ?? ""}
-        setValue={(description) =>
-          update((value) => ({ ...value, description: description || null }))
-        }
-      />
       {(contract.kind === "instruction" ||
         contract.kind === "condition" ||
         contract.kind === "approval") && (
         <TextArea
           label={i18n.t("flows.instruction")}
+          hint={i18n.t("flows.instructionHint")}
           value={
             contract.kind === "instruction"
               ? contract.configuration.prompt
@@ -688,6 +908,36 @@ function NodeInspector({
           />
         </>
       )}
+      {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" && (
         <div className="mt-4">
           <label className="block text-sm font-medium">
@@ -738,7 +988,125 @@ function NodeInspector({
           />
         </div>
       )}
-    </aside>
+    </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, i18n } = useIntelRouterContext();
+  const needs = useQuery({
+    queryKey: ["flow-requirements", flowId],
+    queryFn: () => data.getFlowRequirements(flowId),
+  });
+  // ⚠️ A flow that touches nothing and a flow whose every reference is hidden are two different
+  // answers, so the counted ones keep the panel from claiming the first when it means the second.
+  const empty =
+    needs.data !== undefined &&
+    needs.data.knowledge.length === 0 &&
+    needs.data.hiddenKnowledge === 0 &&
+    needs.data.tools.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.knowledge.length > 0 || needs.data.hiddenKnowledge > 0) && (
+            <>
+              <h3 className="mt-4 text-xs font-medium uppercase tracking-wide text-muted-foreground">
+                {i18n.t("flows.needsKnowledge")}
+              </h3>
+              <ul className="mt-2 space-y-1 text-sm">
+                {needs.data.knowledge.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>
+                ))}
+                {/* ⚠️ Counted, never named. A title is exactly what someone without access to the
+                    document may not learn from a list about it. */}
+                {needs.data.hiddenKnowledge > 0 && (
+                  <li className="text-muted-foreground">
+                    {i18n.t("flows.needsHidden", { count: needs.data.hiddenKnowledge })}
+                  </li>
+                )}
+              </ul>
+            </>
+          )}
+          {needs.data.tools.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.tools.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>
+            </>
+          )}
+          <p className="mt-4 text-xs text-muted-foreground">{i18n.t("flows.needsHint")}</p>
+        </>
+      )}
+    </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 } = useIntelRouterContext();
+  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>
   );
 }
 
@@ -807,20 +1175,46 @@ 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">
-      {label}
+      <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>
   );
 }