@anchrd/intel-ui 0.6.0 → 0.7.0

package/package.json

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

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

@@ -82,6 +82,11 @@ function levelKey(level: Level): readonly unknown[] {
   return level.type === "flow" ? ["flow-calls", level.id] : treeLevelKey(level.id);
 }
 
+// What a row puts on the clipboard for anybody outside the tree. Its own media type rather than
+// `text/plain`, so a drop target that means "move this row" and one that means "make a node for
+// this" cannot be confused by the same payload.
+export const TreeEntryMediaType = "application/x-intel-tree-entry";
+
 export function AppTree() {
   const { data, i18n } = useIntelRouterContext();
   const queryClient = useQueryClient();
@@ -176,7 +181,6 @@ export function AppTree() {
         kind,
         title,
         description: null,
-        contextPolicy: "relevant",
         idempotencyKey: crypto.randomUUID(),
       });
       // ⚠️ Two calls, because they are two things: the node is a row in the tree, the header is the
@@ -212,7 +216,6 @@ export function AppTree() {
         kind: "attachment",
         title: file.name,
         description: null,
-        contextPolicy: "relevant",
         idempotencyKey: crypto.randomUUID(),
       });
       try {
@@ -445,8 +448,17 @@ export function AppTree() {
             isActive={isActive}
             draggable={!derived}
             onDragStart={(event) => {
-              event.dataTransfer.effectAllowed = "move";
+              // ⚠️ Two formats, one gesture. `text/plain` is what a drop inside the tree reads —
+              // that is a MOVE, and it only ever needed the id. The flow canvas needs the kind as
+              // well, to know which node to make, and resolving an id there would mean a second
+              // read of something the drag already knows. `effectAllowed` says both are allowed;
+              // each drop target picks the one it means (#75).
+              event.dataTransfer.effectAllowed = "copyMove";
               event.dataTransfer.setData("text/plain", entry.id);
+              event.dataTransfer.setData(
+                TreeEntryMediaType,
+                JSON.stringify({ id: entry.id, kind: entry.kind, title: entry.title }),
+              );
               draggedRef.current = entry;
               setDragged(entry);
             }}

package/src/components/ui/table.tsx

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

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

@@ -14,6 +14,7 @@ import {
   FlowRunHistory,
   FlowRunList,
   FlowRunStep,
+  FlowValidation,
   KnowledgeDocument,
   KnowledgeGraph,
   KnowledgeLinkList,
@@ -316,6 +317,9 @@ export function createIntelDataProvider(
     async getFlow(flowId) {
       return await request(`/flows/${encodeURIComponent(flowId)}`, FlowDocument);
     },
+    async validateFlow(flowId) {
+      return await request(`/flows/${encodeURIComponent(flowId)}/validation`, FlowValidation);
+    },
     async listFlowCalls(flowId) {
       return await request(`/flows/${encodeURIComponent(flowId)}/calls`, FlowList);
     },

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

@@ -14,6 +14,7 @@ import type {
   FlowRunHistory,
   FlowRunList,
   FlowRunStep,
+  FlowValidation,
   KnowledgeDocument,
   KnowledgeGraph,
   KnowledgeLinkList,
@@ -95,6 +96,8 @@ export interface IntelDataProvider {
   // What a flow calls, read out of its graph. It answers a different question from `listTreeChildren`
   // and deliberately gives a different answer: a shared sub-flow is listed under every caller.
   listFlowCalls(flowId: string): Promise<FlowList>;
+  // Would this flow start for me, right now. A question, not an action: nothing is created (#72).
+  validateFlow(flowId: string): Promise<FlowValidation>;
   // What accesses what, for one level of the shared tree: a folder for its contents, a flow for
   // itself. ⚠️ Only nodes the signed-in user may see come back, and one they may not is absent
   // altogether — never a placeholder, because the edge into one would already say that it exists.

package/src/entry-picker/entry-picker.tsx

@@ -0,0 +1,166 @@
+import type { KnowledgeNode, KnowledgeNodeKind } from "@anchrd/intel-contract";
+import { useQuery } from "@tanstack/react-query";
+import { ChevronRight, Folder, Search } from "lucide-react";
+import { useMemo, useState } from "react";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+/**
+ * One picker for everything a node can name: search by name, or click down through the tree from
+ * the top-level folders.
+ *
+ * ⚠️ Both halves read ONE source — the authorized flat graph the editor already loads. Not because
+ * a search endpoint would be hard, but because `searchKnowledge` answers a different question: it
+ * searches PASSAGES and hands back citations. Someone looking for a document by name would get
+ * results ranked by what is written inside it, which is the wrong list in a picker. Filtering names
+ * here is also instant, and it cannot disagree with the tree about what exists.
+ *
+ * ⚠️ What the caller may not see is absent from the graph, so it is absent here — and an empty
+ * result never says which of the two it is (#17, #19).
+ */
+export function EntryPicker({
+  kind,
+  value,
+  onSelect,
+  label,
+}: {
+  // Which kind of node may be chosen. `null` offers every kind — what the Flow step uses.
+  kind: KnowledgeNodeKind | null;
+  value: string;
+  onSelect(nodeId: string): void;
+  label: string;
+}) {
+  const { data, i18n } = useIntelRouterContext();
+  const [query, setQuery] = useState("");
+  const [openFolder, setOpenFolder] = useState<string | null>(null);
+  const graph = useQuery({
+    queryKey: ["knowledge-graph"],
+    queryFn: () => data.getKnowledgeGraph(),
+  });
+
+  const nodes = useMemo(() => graph.data?.nodes ?? [], [graph.data]);
+  const eligible = useMemo(
+    () => nodes.filter((node) => kind === null || node.kind === kind),
+    [nodes, kind],
+  );
+
+  // Searching looks at every eligible node wherever it sits; browsing looks at one level. The two
+  // are the same list seen two ways, which is why a result can be picked from either.
+  const searching = query.trim().length > 0;
+  const shown = useMemo(() => {
+    if (searching) {
+      const needle = query.trim().toLowerCase();
+      return eligible.filter((node) => node.title.toLowerCase().includes(needle)).slice(0, 50);
+    }
+    return nodes.filter((node) => node.parentId === openFolder);
+  }, [searching, query, eligible, nodes, openFolder]);
+
+  // The way back up, as the chain of folders that leads to the open one.
+  const trail = useMemo(() => {
+    const chain: KnowledgeNode[] = [];
+    let current = openFolder;
+    while (current !== null) {
+      const folder = nodes.find((node) => node.id === current);
+      if (!folder) break;
+      chain.unshift(folder);
+      current = folder.parentId;
+    }
+    return chain;
+  }, [openFolder, nodes]);
+
+  const chosen = nodes.find((node) => node.id === value) ?? null;
+
+  return (
+    <div className="mt-4">
+      <span className="block text-sm font-medium">{label}</span>
+      {chosen ? (
+        <p className="mt-1 truncate text-sm text-muted-foreground">{chosen.title}</p>
+      ) : (
+        <p className="mt-1 text-sm text-muted-foreground">{i18n.t("flows.linkEmpty")}</p>
+      )}
+
+      <div className="mt-2 rounded-lg border">
+        <label className="flex items-center gap-2 border-b px-2 py-1.5">
+          <Search aria-hidden="true" className="size-4 shrink-0 text-muted-foreground" />
+          <span className="sr-only">{i18n.t("picker.search")}</span>
+          <input
+            type="search"
+            value={query}
+            onChange={(event) => setQuery(event.target.value)}
+            placeholder={i18n.t("picker.search")}
+            className="w-full bg-transparent text-sm outline-none"
+          />
+        </label>
+
+        {/* The trail is hidden while searching: a result can come from anywhere, so "where you are"
+            would be a claim about a place the list is no longer showing. */}
+        {!searching && trail.length > 0 ? (
+          <div className="flex flex-wrap items-center gap-1 border-b px-2 py-1 text-xs">
+            <button
+              type="button"
+              onClick={() => setOpenFolder(null)}
+              className="rounded px-1 outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {i18n.t("picker.top")}
+            </button>
+            {trail.map((folder) => (
+              <span key={folder.id} className="flex items-center gap-1">
+                <ChevronRight aria-hidden="true" className="size-3 text-muted-foreground" />
+                <button
+                  type="button"
+                  onClick={() => setOpenFolder(folder.id)}
+                  className="rounded px-1 outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  {folder.title}
+                </button>
+              </span>
+            ))}
+          </div>
+        ) : null}
+
+        <ul className="max-h-56 overflow-y-auto py-1">
+          {shown.map((node) => {
+            // A folder is two things while browsing: somewhere to go, and — when folders are what
+            // is being picked — something to choose. It gets both, side by side, rather than one
+            // control that has to guess which was meant.
+            const canOpen = node.kind === "folder" && !searching;
+            const canPick = kind === null || node.kind === kind;
+            return (
+              <li key={node.id} className="flex items-center gap-1 px-1">
+                {canPick ? (
+                  <button
+                    type="button"
+                    onClick={() => onSelect(node.id)}
+                    aria-current={node.id === value}
+                    className={`min-w-0 flex-1 truncate rounded px-2 py-1.5 text-left text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring ${
+                      node.id === value ? "bg-muted font-medium" : ""
+                    }`}
+                  >
+                    {node.title}
+                    <span className="sr-only"> — {i18n.t(`knowledge.kind.${node.kind}`)}</span>
+                  </button>
+                ) : (
+                  <span className="min-w-0 flex-1 truncate px-2 py-1.5 text-sm text-muted-foreground">
+                    {node.title}
+                  </span>
+                )}
+                {canOpen ? (
+                  <button
+                    type="button"
+                    onClick={() => setOpenFolder(node.id)}
+                    aria-label={i18n.t("picker.open", { title: node.title })}
+                    className="inline-flex size-7 shrink-0 items-center justify-center rounded outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    <Folder aria-hidden="true" className="size-4" />
+                  </button>
+                ) : null}
+              </li>
+            );
+          })}
+          {shown.length === 0 ? (
+            <li className="px-3 py-2 text-sm text-muted-foreground">{i18n.t("picker.nothing")}</li>
+          ) : null}
+        </ul>
+      </div>
+    </div>
+  );
+}

package/src/flows/flows.tsx

@@ -1,4 +1,5 @@
 import type { Flow, FlowGraph, FlowNode, KnowledgeNode } from "@anchrd/intel-contract";
+import { flowNodeLayer } from "@anchrd/intel-contract";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
 import {
@@ -17,12 +18,16 @@ import {
   type NodeProps,
   Position,
   ReactFlow,
+  ReactFlowProvider,
+  useReactFlow,
 } from "@xyflow/react";
 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 { TreeEntryMediaType } from "@/app/app-tree/app-tree.tsx";
 import { ViewToggle } from "@/app/view-toggle/view-toggle.tsx";
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "@/components/ui/tooltip";
+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";
@@ -48,19 +53,46 @@ const ContextHandle = "context";
 const paletteKinds = [
   "trigger",
   "instruction",
-  "knowledge",
-  "tool",
   "condition",
-  "approval",
   "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",
+};
+
 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";
+  const branching = contract.kind === "condition";
   // ⚠️ 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.
@@ -99,18 +131,8 @@ function FlowCard({ data, selected }: NodeProps<CanvasNode>) {
       )}
       {branching && (
         <>
-          <Handle
-            id={contract.kind === "approval" ? "approved" : "yes"}
-            type="source"
-            position={Position.Right}
-            style={{ top: "35%" }}
-          />
-          <Handle
-            id={contract.kind === "approval" ? "rejected" : "no"}
-            type="source"
-            position={Position.Right}
-            style={{ top: "70%" }}
-          />
+          <Handle id="yes" type="source" position={Position.Right} style={{ top: "35%" }} />
+          <Handle id="no" type="source" position={Position.Right} style={{ top: "70%" }} />
         </>
       )}
       {/* The context point (#37). Sideways is the order of work, downwards is what a step works
@@ -143,7 +165,7 @@ function defaultGraph(): FlowGraph {
         kind: "output",
         label: "Result",
         position: { x: 520, y: 180 },
-        configuration: { template: "" },
+        configuration: {},
       },
     ],
     edges: [
@@ -236,6 +258,27 @@ function editsEdges(changes: EdgeChange<CanvasEdge>[]): boolean {
   );
 }
 
+// ⚠️ `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"], KnowledgeNode["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,
@@ -259,16 +302,14 @@ function newNode(
         kind,
         configuration: { prompt: "Describe what the AI should do." },
       };
-    case "knowledge":
-      return {
-        ...common,
-        kind,
-        configuration: {
-          resourceIds: firstKnowledgeId ? [firstKnowledgeId] : [],
-          mode: "relevant",
-          query: null,
-        },
-      };
+    // 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: firstKnowledgeId ?? "" } };
     case "tool":
       return {
         ...common,
@@ -288,15 +329,6 @@ function newNode(
           instruction: "Describe how to choose yes or no.",
         },
       };
-    case "approval":
-      return {
-        ...common,
-        kind,
-        configuration: {
-          prompt: "Describe what must be approved.",
-          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).
@@ -306,12 +338,24 @@ function newNode(
         configuration: { flowId: firstFlowId ?? "", version: { mode: "latest" } },
       };
     case "output":
-      return { ...common, kind, configuration: { template: "" } };
+      return { ...common, kind, configuration: {} };
   }
 }
 
+// ⚠️ 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, i18n } = useIntelRouterContext();
+  const flow = useReactFlow();
   const theme = useSystemTheme();
   const queryClient = useQueryClient();
   const navigate = useNavigate();
@@ -398,15 +442,6 @@ export function Flows() {
       ]);
     },
   });
-  const run = useMutation({
-    mutationFn: () =>
-      data.startFlow({
-        flowId: selectedFlowId ?? "",
-        input: {},
-        parent: null,
-        idempotencyKey: crypto.randomUUID(),
-      }),
-  });
 
   function updateNode(update: (node: FlowNode) => FlowNode) {
     setDirty(true);
@@ -435,10 +470,8 @@ export function Flows() {
           dirty={dirty}
           saving={save.isPending}
           canMutate={canMutate}
-          running={run.isPending}
           onSave={() => save.mutate()}
           onPublish={() => setPublishing(true)}
-          onRun={() => run.mutate()}
         />
       ) : null}
       <UnsavedChangesGuard dirty={dirty} />
@@ -551,6 +584,50 @@ export function Flows() {
                   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
@@ -570,7 +647,6 @@ export function Flows() {
                 node={selectedNode}
                 update={updateNode}
                 tools={tools.data?.items ?? []}
-                knowledge={knowledge.data?.nodes ?? []}
                 flows={(callable.data?.items ?? []).filter((entry) => entry.id !== selectedFlowId)}
               />
               <FlowNeeds flowId={selectedFlowId} />
@@ -578,15 +654,7 @@ export function Flows() {
           </>
         )}
       </div>
-      {run.data && (
-        <div className="fixed bottom-5 right-5 z-20 max-w-sm rounded-xl border bg-card p-4 text-sm shadow-xl">
-          <p className="font-medium">{i18n.t("flows.runStarted")}</p>
-          <p className="mt-1 text-xs text-muted-foreground">
-            {run.data.node?.label ?? run.data.run.status} · {run.data.run.id}
-          </p>
-        </div>
-      )}
-      {(save.isError || run.isError) && (
+      {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"
@@ -636,19 +704,15 @@ function FlowTitle({
   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
@@ -693,14 +757,6 @@ function FlowTitle({
         </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>
   );
 }
@@ -795,13 +851,11 @@ function NodeInspector({
   node,
   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();
@@ -810,23 +864,24 @@ function NodeInspector({
   return (
     <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 }))}
-      />
-      {(contract.kind === "instruction" ||
-        contract.kind === "condition" ||
-        contract.kind === "approval") && (
+      {/* ⚠️ 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.kind === "condition"
-                ? contract.configuration.instruction
-                : contract.configuration.prompt
+              : contract.configuration.instruction
           }
           setValue={(text) =>
             update((value) =>
@@ -837,76 +892,26 @@ function NodeInspector({
                       ...value,
                       configuration: { mode: "semantic", instruction: text },
                     }
-                  : value.kind === "approval"
-                    ? {
-                        ...value,
-                        configuration: { ...value.configuration, prompt: text },
-                      }
-                    : value,
+                  : value,
             )
           }
         />
       )}
-      {contract.kind === "knowledge" && (
-        <>
-          <fieldset className="mt-4 rounded-lg border p-3">
-            <legend className="px-1 text-sm font-medium">{i18n.t("flows.knowledgeIds")}</legend>
-            {knowledge.map((item) => (
-              <label
-                key={item.id}
-                className="flex cursor-pointer items-start gap-2 rounded-md px-2 py-1.5 text-sm hover:bg-muted"
-              >
-                <input
-                  type="checkbox"
-                  checked={contract.configuration.resourceIds.includes(item.id)}
-                  disabled={
-                    contract.configuration.resourceIds.length === 1 &&
-                    contract.configuration.resourceIds[0] === item.id
-                  }
-                  onChange={(event) =>
-                    update((value) => {
-                      if (value.kind !== "knowledge") return value;
-                      const selected = new Set(value.configuration.resourceIds);
-                      if (event.target.checked) selected.add(item.id);
-                      else selected.delete(item.id);
-                      return {
-                        ...value,
-                        configuration: {
-                          ...value.configuration,
-                          resourceIds: [...selected],
-                        },
-                      };
-                    })
-                  }
-                  className="mt-0.5 size-4 accent-primary disabled:cursor-not-allowed disabled:opacity-50"
-                />
-                <span className="min-w-0 truncate">{item.title}</span>
-              </label>
-            ))}
-            {knowledge.length === 0 && (
-              <p className="px-2 py-1 text-sm text-muted-foreground">
-                {i18n.t("flows.knowledgeEmpty")}
-              </p>
-            )}
-          </fieldset>
-          <TextArea
-            label={i18n.t("flows.knowledgeQuery")}
-            value={contract.configuration.query ?? ""}
-            setValue={(query) =>
-              update((value) =>
-                value.kind === "knowledge"
-                  ? {
-                      ...value,
-                      configuration: {
-                        ...value.configuration,
-                        query: query || null,
-                      },
-                    }
-                  : 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">

package/src/flows/node-icon/node-icon.ts

@@ -1,11 +1,13 @@
 import type { FlowNode } from "@anchrd/intel-contract";
 import {
-  CheckCircle2,
+  CircleDot,
   CirclePlay,
-  FileSearch,
+  FileText,
+  Folder,
   GitBranch,
-  ShieldCheck,
+  Paperclip,
   Sparkles,
+  Table,
   Workflow,
   Wrench,
 } from "lucide-react";
@@ -19,10 +21,14 @@ export type NodeIcon = ComponentType<SVGProps<SVGSVGElement>>;
 export const nodeIcon: Record<FlowNode["kind"], NodeIcon> = {
   trigger: CirclePlay,
   instruction: Sparkles,
-  knowledge: FileSearch,
-  tool: Wrench,
   condition: GitBranch,
-  approval: ShieldCheck,
   subflow: Workflow,
-  output: CheckCircle2,
+  // The four links wear the symbol their kind wears in the tree, so a document is the same shape
+  // wherever it is seen — the sidebar, the picker and the canvas do not each teach their own.
+  folder: Folder,
+  document: FileText,
+  upload: Paperclip,
+  table: Table,
+  tool: Wrench,
+  output: CircleDot,
 };

package/src/flows/node-palette/node-palette.tsx

@@ -1,5 +1,6 @@
+import { flowNodeLayer } from "@anchrd/intel-contract";
 import { Plus, X } from "lucide-react";
-import { useId, useRef, useState } from "react";
+import { Fragment, useId, useRef, useState } from "react";
 import { type NodeIcon, nodeIcon } from "@/flows/node-icon/node-icon.ts";
 import { cn } from "@/lib/utils.ts";
 import { useIntelRouterContext } from "@/router/router-context.ts";
@@ -172,25 +173,38 @@ export function NodePalette<K extends PaletteKind>({
           {kinds.map((kind, index) => {
             const Icon: NodeIcon = nodeIcon[kind];
             const reason = disabledReason?.(kind) ?? null;
+            // ⚠️ A separator before the first entry of each layer after the first (D25). It is
+            // decoration, not structure: the toolbar's keyboard walks `[data-palette-item]`, so a
+            // divider in between must not be one — otherwise the arrows would stop on a line.
+            const opensLayer =
+              index > 0 && flowNodeLayer[kind] !== flowNodeLayer[kinds[index - 1] ?? kind];
             return (
-              <button
-                key={kind}
-                type="button"
-                data-palette-item=""
-                disabled={reason !== null}
-                title={reason ?? undefined}
-                tabIndex={index === active ? 0 : -1}
-                onClick={() => {
-                  setActive(index);
-                  add(kind);
-                }}
-                // `h-9` is the trigger's height: sharing one row only reads as one row if the entries
-                // start on the trigger's top edge instead of floating in the middle of it.
-                className="inline-flex h-9 items-center gap-1.5 rounded-md px-2 text-xs outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent"
-              >
-                <Icon aria-hidden="true" className="size-3.5" />
-                {i18n.t(`flows.node.${kind}`)}
-              </button>
+              <Fragment key={kind}>
+                {opensLayer ? (
+                  <span
+                    aria-hidden="true"
+                    className="mx-1 my-1.5 w-px self-stretch bg-border"
+                    title={i18n.t(`flows.layer.${flowNodeLayer[kind]}`)}
+                  />
+                ) : null}
+                <button
+                  type="button"
+                  data-palette-item=""
+                  disabled={reason !== null}
+                  title={reason ?? undefined}
+                  tabIndex={index === active ? 0 : -1}
+                  onClick={() => {
+                    setActive(index);
+                    add(kind);
+                  }}
+                  // `h-9` is the trigger's height: sharing one row only reads as one row if the entries
+                  // start on the trigger's top edge instead of floating in the middle of it.
+                  className="inline-flex h-9 items-center gap-1.5 rounded-md px-2 text-xs outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-transparent"
+                >
+                  <Icon aria-hidden="true" className="size-3.5" />
+                  {i18n.t(`flows.node.${kind}`)}
+                </button>
+              </Fragment>
             );
           })}
         </div>

package/src/folder-contents/folder-contents.tsx

@@ -0,0 +1,106 @@
+import { useQuery } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { treeLevelKey } from "@/app/tree-move/tree-move.tsx";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table.tsx";
+import type { TreeEntry } from "@/data/intel-data-provider/intel-data-provider.types.ts";
+import { useIntelRouterContext } from "@/router/router-context.ts";
+
+const icons: Record<TreeEntry["kind"], string> = {
+  folder: "knowledge.kind.folder",
+  document: "knowledge.kind.document",
+  attachment: "knowledge.kind.attachment",
+  table: "knowledge.kind.table",
+  flow: "knowledge.kind.flow",
+};
+
+/**
+ * A folder's own screen: what lies directly in it, as a table.
+ *
+ * ⚠️ It reads the SAME query the sidebar reads for the same folder — `treeLevelKey`, filled by
+ * `listTreeChildren`. Not a second call and not a second cache entry: two readers of one folder that
+ * fetch separately show it differently the moment one of them is stale, and that is the kind of
+ * difference a customer finds before anybody here does. The other half of the bargain is free —
+ * every invalidation the tree already does after a create, a move or an archive lands here too.
+ */
+export function FolderContents({ folderId }: { folderId: string }) {
+  const { data, i18n } = useIntelRouterContext();
+  const navigate = useNavigate();
+  const level = useQuery({
+    queryKey: treeLevelKey(folderId),
+    queryFn: () => data.listTreeChildren(folderId),
+  });
+
+  if (level.isPending) {
+    return <p className="p-6 text-sm text-muted-foreground">{i18n.t("common.loading")}</p>;
+  }
+  if (level.isError) {
+    return (
+      <p role="alert" className="p-6 text-sm text-destructive">
+        {i18n.t("knowledge.folderFailed")}
+      </p>
+    );
+  }
+
+  const entries = level.data ?? [];
+  // ⚠️ An empty folder keeps a sentence, unlike an empty row in the tree (#59). A folder IS this
+  // screen: a blank rectangle leaves someone who just created it with nowhere to go, which is the
+  // same reason `tree.empty` survives at the root.
+  if (entries.length === 0) {
+    return (
+      <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
+        {i18n.t("knowledge.folderEmpty")}
+      </div>
+    );
+  }
+
+  return (
+    <div className="min-h-0 flex-1 overflow-y-auto p-4">
+      <Table>
+        <TableHeader>
+          <TableRow>
+            <TableHead>{i18n.t("common.title")}</TableHead>
+            <TableHead>{i18n.t("knowledge.kind")}</TableHead>
+            <TableHead>{i18n.t("knowledge.changed")}</TableHead>
+          </TableRow>
+        </TableHeader>
+        <TableBody>
+          {entries.map((entry) => {
+            const changed = entry.type === "flow" ? entry.flow.updatedAt : entry.node.updatedAt;
+            return (
+              <TableRow key={entry.id}>
+                {/* ⚠️ The button carries the whole cell rather than the cell carrying an onClick.
+                    A row that only reacts to a mouse is a row nobody can reach with a keyboard, and
+                    a `<tr onClick>` has no name to read out either. */}
+                <TableCell className="p-0">
+                  <button
+                    type="button"
+                    onClick={() =>
+                      void navigate({
+                        to: entry.type === "flow" ? "/flows" : "/knowledge",
+                        search: { select: entry.id },
+                      })
+                    }
+                    className="w-full px-2 py-2 text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    {entry.title}
+                  </button>
+                </TableCell>
+                <TableCell className="text-muted-foreground">{i18n.t(icons[entry.kind])}</TableCell>
+                <TableCell className="text-muted-foreground">
+                  {new Date(changed).toLocaleDateString()}
+                </TableCell>
+              </TableRow>
+            );
+          })}
+        </TableBody>
+      </Table>
+    </div>
+  );
+}

package/src/i18n/en.json

@@ -84,11 +84,15 @@
   "knowledge.table.empty": "No rows yet. Rows are appended by flows and agents.",
   "knowledge.table.undefined": "This table has no columns yet.",
   "knowledge.select": "Select a document or folder to work with it.",
-  "knowledge.folderHelp": "Select a child document, or create something inside this folder.",
-  "knowledge.contextPolicy": "AI context policy",
-  "knowledge.context.pinned": "Pinned in scope",
-  "knowledge.context.relevant": "Load when relevant",
-  "knowledge.context.explicit": "Only when referenced",
+  "knowledge.folderEmpty": "Nothing in this folder yet. Create something with the plus in the sidebar.",
+  "knowledge.folderFailed": "This folder could not be read.",
+  "knowledge.kind": "Kind",
+  "knowledge.changed": "Changed",
+  "knowledge.kind.folder": "Folder",
+  "knowledge.kind.document": "Document",
+  "knowledge.kind.attachment": "Upload",
+  "knowledge.kind.table": "Table",
+  "knowledge.kind.flow": "Flow",
   "knowledge.share": "Share",
   "knowledge.shareAction": "Grant access",
   "knowledge.email": "Email address",
@@ -158,25 +162,40 @@
   "flows.publish": "Publish",
   "flows.publishNothing": "Nothing new to publish",
   "flows.publishNeeded": "Publish — no run can start until you do",
-  "flows.run": "Start run",
-  "flows.runStarted": "Durable run started",
+  "flows.validate": "Check whether it would run",
+  "flows.validateReady": "This flow would start now.",
+  "flows.validateWhen": "Checked {when}. Tool access is asked with your own token each time, so this answer is a snapshot.",
+  "flows.problem.flow_execute_forbidden": "You may not run this flow",
+  "flows.problem.flow_not_published": "The flow is not published",
+  "flows.problem.flow_graph_invalid": "The graph cannot be run",
+  "flows.problem.flow_tools_unavailable": "A tool is out of reach",
+  "flows.problem.flow_knowledge_forbidden": "Material a step reads is out of reach",
+  "flows.problem.flow_subflow_unavailable": "A called flow is unavailable",
+  "flows.problem.flow_subflow_not_published": "A called flow is not published",
   "flows.addNode": "Add a step",
   "flows.closePalette": "Close the step bar",
   "flows.nodePalette": "Step types",
   "flows.node.trigger": "Start",
   "flows.startExists": "A flow has exactly one start, and this one already has it.",
   "flows.node.instruction": "Instruction",
-  "flows.node.knowledge": "Knowledge",
+  "flows.node.folder": "Folder",
+  "flows.node.document": "Document",
+  "flows.node.upload": "Upload",
+  "flows.node.table": "Table",
   "flows.node.tool": "Tool",
   "flows.node.condition": "Condition",
-  "flows.node.approval": "Approval",
-  "flows.node.subflow": "Sub-flow",
-  "flows.node.output": "Output",
+  "flows.node.subflow": "Flow",
+  "flows.node.output": "End",
   "flows.instruction": "Instruction for the AI or person",
   "flows.instructionHint": "Conditions, checks and branches can be described here in words. You do not need a separate node for every small decision.",
-  "flows.knowledgeIds": "Knowledge references",
-  "flows.knowledgeEmpty": "Create a knowledge item before adding this step.",
-  "flows.knowledgeQuery": "Semantic retrieval hint",
+  "flows.linkEmpty": "Nothing chosen yet",
+  "picker.search": "Search by name",
+  "picker.top": "All folders",
+  "picker.open": "Open {title}",
+  "picker.nothing": "Nothing here",
+  "flows.layer.marker": "Markers",
+  "flows.layer.step": "Steps",
+  "flows.layer.link": "Links",
   "flows.subflowTarget": "Flow to call",
   "flows.selectSubflow": "Select a flow to call",
   "flows.subflowRule": "A flow may call a flow in its own folder or below it, or one in a folder every user may run. Publishing names the reason if it may not.",

package/src/knowledge/knowledge.tsx

@@ -6,6 +6,7 @@ import { lazy, Suspense, 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 { FolderContents } from "@/folder-contents/folder-contents.tsx";
 import { GraphPane } from "@/graph-pane/graph-pane.tsx";
 import { KnowledgeTablePanel } from "@/knowledge-table/knowledge-table.tsx";
 import { useIntelRouterContext } from "@/router/router-context.ts";
@@ -135,9 +136,7 @@ export function Knowledge() {
                 }
               />
             ) : selected.kind === "folder" ? (
-              <div className="grid flex-1 place-items-center p-8 text-sm text-muted-foreground">
-                {i18n.t("knowledge.folderHelp")}
-              </div>
+              <FolderContents folderId={selected.id} />
             ) : selected.kind === "attachment" ? (
               <AttachmentPanel node={selected} />
             ) : selected.kind === "table" ? (

package/src/resource-menu/resource-menu.tsx

@@ -1,13 +1,22 @@
 import type {
-  ContextPolicy,
   Flow,
+  FlowValidation,
   KnowledgeNode,
   ResourceVerb,
   UnreadableKnowledge,
 } from "@anchrd/intel-contract";
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useNavigate, useRouterState } from "@tanstack/react-router";
-import { Archive, CornerLeftUp, Ellipsis, Link2, Pencil, Share2, Trash2 } from "lucide-react";
+import {
+  Archive,
+  CornerLeftUp,
+  Ellipsis,
+  Link2,
+  Pencil,
+  Share2,
+  ShieldCheck,
+  Trash2,
+} from "lucide-react";
 import type * as React from "react";
 import { useState } from "react";
 import { moveErrorKey, useTreeMove } from "@/app/tree-move/tree-move.tsx";
@@ -15,12 +24,7 @@ import {
   DropdownMenu,
   DropdownMenuContent,
   DropdownMenuItem,
-  DropdownMenuRadioGroup,
-  DropdownMenuRadioItem,
   DropdownMenuSeparator,
-  DropdownMenuSub,
-  DropdownMenuSubContent,
-  DropdownMenuSubTrigger,
   DropdownMenuTrigger,
 } from "@/components/ui/dropdown-menu";
 import { flowEntry } from "@/data/intel-data-provider/intel-data-provider.ts";
@@ -93,8 +97,6 @@ export function resourceErrorKey(error: unknown): string {
   }
 }
 
-const contextPolicies: readonly ContextPolicy[] = ["pinned", "relevant", "explicit"];
-
 /**
  * The three-dot menu.
  *
@@ -122,6 +124,14 @@ export function ResourceMenu({
   // the name. #27 gave moving a second, equal route through a folder picker, and that route lived in
   // the tree row's menu. With the row menu gone (#58) it lives here, or it does not exist.
   const move = useTreeMove();
+  // ⚠️ Not a query. A validation is a snapshot taken when somebody asks (#72, ADR-0003): cached
+  // under a key it would be re-served later as if it still held, and the one thing it must never
+  // claim is that a moment which has passed is still true.
+  const [validation, setValidation] = useState<FlowValidation | null>(null);
+  const validate = useMutation({
+    mutationFn: () => data.validateFlow(id),
+    onSuccess: setValidation,
+  });
 
   const id = idOf(target);
   const title = titleOf(target);
@@ -192,26 +202,11 @@ export function ResourceMenu({
     },
   });
 
-  const setContextPolicy = useMutation({
-    mutationFn: async (contextPolicy: ContextPolicy) => {
-      if (target.type === "flow") throw new Error("A flow has no retrieval mode");
-      await data.updateKnowledge({
-        nodeId: target.node.id,
-        baseUpdatedAt: target.node.updatedAt,
-        contextPolicy,
-        idempotencyKey: crypto.randomUUID(),
-      });
-    },
-    onSuccess: refresh,
-  });
-
   const failure = rename.isError
     ? null // the rename dialog words its own refusal, beside the field that caused it
     : archive.isError
       ? archive.error
-      : setContextPolicy.isError
-        ? setContextPolicy.error
-        : undefined;
+      : undefined;
 
   return (
     <>
@@ -236,27 +231,15 @@ export function ResourceMenu({
             <CornerLeftUp aria-hidden="true" />
             {i18n.t("tree.move.action")}
           </DropdownMenuItem>
-          {retrievable || linkable || node ? <DropdownMenuSeparator /> : null}
-          {/* ⚠️ A submenu with a checked value, not an embedded `select`. A form control inside a
-              menu takes the keyboard away from the menu that contains it, and the current value is
-              then only readable by opening a second widget. */}
-          {retrievable && node ? (
-            <DropdownMenuSub>
-              <DropdownMenuSubTrigger>{i18n.t("knowledge.contextPolicy")}</DropdownMenuSubTrigger>
-              <DropdownMenuSubContent>
-                <DropdownMenuRadioGroup
-                  value={node.contextPolicy}
-                  onValueChange={(value) => setContextPolicy.mutate(value as ContextPolicy)}
-                >
-                  {contextPolicies.map((policy) => (
-                    <DropdownMenuRadioItem key={policy} value={policy}>
-                      {i18n.t(`knowledge.context.${policy}`)}
-                    </DropdownMenuRadioItem>
-                  ))}
-                </DropdownMenuRadioGroup>
-              </DropdownMenuSubContent>
-            </DropdownMenuSub>
+          {/* Only a flow can be run, so only a flow can be asked whether it would. Rarely needed —
+              which is why it is in the menu and not in the title line (#72). */}
+          {node === null ? (
+            <DropdownMenuItem onSelect={() => validate.mutate()}>
+              <ShieldCheck aria-hidden="true" />
+              {i18n.t("flows.validate")}
+            </DropdownMenuItem>
           ) : null}
+          {retrievable || linkable || node ? <DropdownMenuSeparator /> : null}
           {linkable ? (
             <DropdownMenuItem onSelect={() => setLinksOpen(true)}>
               <Link2 aria-hidden="true" />
@@ -295,6 +278,33 @@ export function ResourceMenu({
           `resourceErrorKey`: "that is not a folder" and "that would be a loop" have no equivalent
           among the changes above, and one shared sentence would leave the reader guessing. */}
       {move.error ? <MenuFailure>{i18n.t(moveErrorKey(move.error))}</MenuFailure> : null}
+      {/* ⚠️ Every reason at once, not the first one. Somebody with two missing tools should not have
+          to ask twice — and a success says so out loud, because an empty menu after a click reads
+          as "nothing happened" rather than "nothing is in the way". */}
+      {validation ? (
+        <Modal title={i18n.t("flows.validate")} close={() => setValidation(null)}>
+          {validation.problems.length === 0 ? (
+            <p className="text-sm">{i18n.t("flows.validateReady")}</p>
+          ) : (
+            <ul className="space-y-2">
+              {validation.problems.map((problem) => (
+                <li key={problem.code} className="rounded-md border p-3 text-sm">
+                  <span className="block font-medium">
+                    {i18n.t(`flows.problem.${problem.code}`)}
+                  </span>
+                  <span className="mt-1 block text-xs text-muted-foreground">{problem.detail}</span>
+                </li>
+              ))}
+            </ul>
+          )}
+          {/* A snapshot says when it was taken, or it will be read as a standing verdict. */}
+          <p className="mt-4 text-xs text-muted-foreground">
+            {i18n.t("flows.validateWhen", {
+              when: new Date(validation.checkedAt).toLocaleString(),
+            })}
+          </p>
+        </Modal>
+      ) : null}
       {move.dialog}
       {renaming ? (
         <RenameDialog