Migrate Dataflow interface patterns

2026-08-03 14:19:42 +02:00
parent 3fa7a29f48
commit 109ddcd4fb
9 changed files with 995 additions and 103 deletions
@@ -0,0 +1,38 @@
+# Dataflow Interface Pattern Migration
+
+This migration applies the GovOPlaN interface pattern language to the pipeline
+library, graphical and constrained-SQL editors, node inspector, intermediate
+preview, automation triggers, and durable run/deployment surfaces.
+
+## Surface Inventory
+
+| Surface | Archetype | Consequence class | Contract |
+| --- | --- | --- | --- |
+| `/dataflow` library | Governed directory | Select, create, reuse, or retire a pipeline | Stable loading, empty, permission, read-only, disabled-reason, and help states |
+| Graph/SQL workspace | Consequential definition editor | Append immutable revision | One canonical graph, guarded draft, constrained SQL compilation, diagnostics, and explicit save/discard |
+| Node inspector | Typed configuration editor | Change transform semantics | Contextual node/expression help, typed validation, bounded intermediate preview, and read-only state |
+| Trigger editor | Governed automation editor | Create, enable, change, or delete trigger | Guarded nested draft, pinned revision/grant, authorization recheck, and destructive confirmation |
+| Preview/results | Bounded evidence preview | Read transient intermediate rows | Selected-node context, diagnostics, privacy boundary, row limit, and no retained preview contents |
+| Runs/deployments | Asynchronous command register | Queue, publish, cancel, reconcile, or promote | Explicit consequence confirmation, durable command identity, progress, recovery state, and retained evidence |
+
+## Consequence And Availability Rules
+
+- Saving appends an immutable definition revision. Derivation creates a
+  separately governed copy pinned to the source revision and content hash.
+- SQL is parsed and compiled into the canonical graph. It is never passed
+  directly to a database or execution provider.
+- Preview is bounded and transient. A saved run is revision-pinned and records
+  actor, authority, idempotency, progress, output, and recovery evidence.
+- Publishing appends a governed Datasource materialization. Unknown external
+  outcomes require reconciliation before retry.
+- Staging and production promotion require confirmation and never rewrite a
+  revision. Cancellation cannot promise reversal of acknowledged external
+  effects.
+- Missing optional Datasources or automation capabilities disable only their
+  associated actions; local graph, SQL, validation, and preview behavior stays
+  available where authorized.
+
+Backend and WebUI manifests publish matching surface identifiers. English and
+German catalogues cover module-owned navigation, states, and core commands.
+Contextual help resolves from manifest documentation, main and nested drafts
+are guarded, and unavailable actions carry stable reasons.
@@ -181,6 +181,113 @@ DOCUMENTATION = (
                "Output publication uses forward recovery and blocks blind retry "
                "when provider acknowledgement is uncertain."
            ),
+            "help_contexts": [
+                "dataflow.page",
+                "dataflow.library",
+                "dataflow.graph",
+                "dataflow.sql",
+                "dataflow.inspector",
+                "dataflow.results",
+                "dataflow.state.read-only",
+            ],
+        },
+    ),
+    DocumentationTopic(
+        id="dataflow.reference.nodes-and-expressions",
+        title="Dataflow nodes and expressions",
+        summary="Typed node inputs, expressions, schema propagation, and bounded intermediate previews.",
+        body=(
+            "Every graph node declares typed inputs, configuration, output schema, and validation rules. "
+            "Source nodes pin inline content or governed Datasource references; combine, filter, transform, "
+            "quality, reconciliation, reusable-subflow, and output nodes remain explicit in the canonical graph. "
+            "Expressions use the typed Dataflow expression language and never execute arbitrary host or database "
+            "code. Selecting a node may request a bounded intermediate preview; preview rows are transient, "
+            "privacy-filtered for the actor, and are not retained as run output. SQL editing compiles into the same "
+            "canonical graph, so unsupported statements are diagnostics rather than pass-through SQL."
+        ),
+        layer="available",
+        documentation_types=("admin", "user"),
+        audience=("operator", "module_admin", "power_user", "data_steward"),
+        order=76,
+        related_modules=("datasources", "connectors", "policy", "audit"),
+        metadata={
+            "help_contexts": [
+                "dataflow.field.node-name",
+                "dataflow.field.source",
+                "dataflow.field.expression",
+                "dataflow.field.schema",
+                "dataflow.action.preview-node",
+            ],
+        },
+    ),
+    DocumentationTopic(
+        id="dataflow.reference.fields-and-consequences",
+        title="Dataflow fields and lifecycle consequences",
+        summary="Definition scope, revision, reuse, automation, execution, publication, promotion, and deletion semantics.",
+        body=(
+            "Scope determines ownership and Policy inheritance. Templates can be derived but not run; complete "
+            "flows may be previewed, revisioned, automated, and executed when effective Policy allows it. Saving "
+            "appends an immutable revision. A scoped copy pins its source revision and content hash. Triggers pin "
+            "the revision and authorization grant, then re-evaluate authority for every delivery. Runs create "
+            "durable command and recovery evidence. Publishing creates a governed Datasource materialization, and "
+            "environment promotion changes which immutable revision is eligible for staging or production runs. "
+            "Deletion prevents future use while retained run, deployment, lineage, audit, and recovery evidence "
+            "continues under its retention policy."
+        ),
+        layer="available",
+        documentation_types=("admin", "user"),
+        audience=("operator", "module_admin", "power_user", "product_owner"),
+        order=77,
+        related_modules=("datasources", "workflow_engine", "notifications", "policy", "audit"),
+        metadata={
+            "help_contexts": [
+                "dataflow.field.scope",
+                "dataflow.field.definition-kind",
+                "dataflow.action.save",
+                "dataflow.action.derive",
+                "dataflow.action.trigger",
+                "dataflow.action.delete",
+            ],
+            "consequence_classes": {
+                "save_revision": "Appends an immutable pipeline definition revision.",
+                "derive_copy": "Creates a separately governed copy pinned to the source revision and hash.",
+                "configure_trigger": "Creates or changes an automation command with revision and authorization evidence.",
+                "delete_pipeline": "Prevents future use while retained evidence remains governed.",
+            },
+        },
+    ),
+    DocumentationTopic(
+        id="dataflow.execution-and-recovery",
+        title="Dataflow execution, publication, and recovery",
+        summary="Pinned runs, environment promotion, output publication, cancellation, reconciliation, and retained evidence.",
+        body=(
+            "Every run is pinned to an immutable revision and idempotency key. The queue records actor, authority, "
+            "environment, progress, cancellation, output, and recovery state. Database-only runs commit atomically. "
+            "Publication to a governed Datasource uses forward recovery: an unknown provider outcome is reconciled "
+            "before retry so output is not duplicated. Staging and production promotion is explicit and does not "
+            "rewrite a revision. Cancellation is best effort once external work has started; the final evidence "
+            "states whether work stopped, completed, failed, or requires operator reconciliation."
+        ),
+        layer="available",
+        documentation_types=("admin", "user"),
+        audience=("operator", "module_admin", "power_user", "security_admin"),
+        order=78,
+        related_modules=("datasources", "notifications", "policy", "audit", "ops"),
+        metadata={
+            "help_contexts": [
+                "dataflow.runs",
+                "dataflow.action.queue-run",
+                "dataflow.action.publish",
+                "dataflow.action.promote-staging",
+                "dataflow.action.promote-production",
+                "dataflow.state.recovery-attention",
+            ],
+            "consequence_classes": {
+                "queue_run": "Creates a durable asynchronous command and authorization evidence.",
+                "publish_output": "Creates or updates a governed Datasource and appends a materialization.",
+                "promote_revision": "Makes an immutable revision eligible in a higher execution environment.",
+                "cancel_run": "Requests cancellation; already acknowledged external effects may remain.",
+            },
        },
    ),
 )
@@ -374,6 +481,69 @@ manifest = ModuleManifest(
            ),
        ),
        view_surfaces=(
+            ViewSurface(
+                id="dataflow.page",
+                module_id=MODULE_ID,
+                kind="route",
+                label="Dataflow",
+                order=72,
+            ),
+            ViewSurface(
+                id="dataflow.library",
+                module_id=MODULE_ID,
+                kind="section",
+                label="Pipeline library",
+                parent_id="dataflow.page",
+                order=10,
+            ),
+            ViewSurface(
+                id="dataflow.graph",
+                module_id=MODULE_ID,
+                kind="section",
+                label="Graph editor",
+                parent_id="dataflow.page",
+                order=20,
+            ),
+            ViewSurface(
+                id="dataflow.sql",
+                module_id=MODULE_ID,
+                kind="section",
+                label="Constrained SQL editor",
+                parent_id="dataflow.page",
+                order=30,
+            ),
+            ViewSurface(
+                id="dataflow.inspector",
+                module_id=MODULE_ID,
+                kind="section",
+                label="Node inspector",
+                parent_id="dataflow.page",
+                order=40,
+            ),
+            ViewSurface(
+                id="dataflow.results",
+                module_id=MODULE_ID,
+                kind="section",
+                label="Preview and diagnostics",
+                parent_id="dataflow.page",
+                order=50,
+            ),
+            ViewSurface(
+                id="dataflow.triggers",
+                module_id=MODULE_ID,
+                kind="action",
+                label="Automation triggers",
+                parent_id="dataflow.page",
+                order=60,
+            ),
+            ViewSurface(
+                id="dataflow.runs",
+                module_id=MODULE_ID,
+                kind="action",
+                label="Runs and deployments",
+                parent_id="dataflow.page",
+                order=70,
+            ),
            ViewSurface(
                id="dataflow.widget.pipelines",
                module_id=MODULE_ID,
@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from pathlib import Path
+import unittest
+
+from govoplan_dataflow.backend.manifest import get_manifest
+
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+
+
+class DataflowInterfaceDocumentationContractTests(unittest.TestCase):
+    def test_backend_surfaces_and_hierarchy_remain_declared(self) -> None:
+        frontend = get_manifest().frontend
+        self.assertIsNotNone(frontend)
+        surfaces = {item.id: item for item in frontend.view_surfaces}  # type: ignore[union-attr]
+        self.assertEqual(
+            {
+                "dataflow.page",
+                "dataflow.library",
+                "dataflow.graph",
+                "dataflow.sql",
+                "dataflow.inspector",
+                "dataflow.results",
+                "dataflow.triggers",
+                "dataflow.runs",
+                "dataflow.widget.pipelines",
+            },
+            set(surfaces),
+        )
+        for surface_id in (
+            "dataflow.library",
+            "dataflow.graph",
+            "dataflow.sql",
+            "dataflow.inspector",
+            "dataflow.results",
+            "dataflow.triggers",
+            "dataflow.runs",
+        ):
+            self.assertEqual("dataflow.page", surfaces[surface_id].parent_id)
+
+    def test_help_and_consequence_metadata_remain_published(self) -> None:
+        topics = {topic.id: topic for topic in get_manifest().documentation}
+        boundary = topics["dataflow.module-boundary"]
+        fields = topics["dataflow.reference.fields-and-consequences"]
+        nodes = topics["dataflow.reference.nodes-and-expressions"]
+        execution = topics["dataflow.execution-and-recovery"]
+
+        self.assertIn("dataflow.state.read-only", boundary.metadata["help_contexts"])
+        self.assertIn("dataflow.field.expression", nodes.metadata["help_contexts"])
+        self.assertIn("save_revision", fields.metadata["consequence_classes"])
+        self.assertIn("delete_pipeline", fields.metadata["consequence_classes"])
+        self.assertIn("publish_output", execution.metadata["consequence_classes"])
+        self.assertIn("promote_revision", execution.metadata["consequence_classes"])
+
+    def test_webui_uses_shared_help_guard_and_consequence_components(self) -> None:
+        page = (REPO_ROOT / "webui/src/features/dataflow/DataflowPage.tsx").read_text(
+            encoding="utf-8"
+        )
+        inspector = (
+            REPO_ROOT / "webui/src/features/dataflow/NodeInspector.tsx"
+        ).read_text(encoding="utf-8")
+
+        for component in (
+            "ActionBlockerHint",
+            "DocumentationHelpLink",
+            "useUnsavedDraftGuard",
+            "ConfirmDialog",
+        ):
+            self.assertIn(component, page)
+        self.assertIn("DATAFLOW_NODE_DOCUMENTATION", inspector)
+
+
+if __name__ == "__main__":
+    unittest.main()
@@ -26,10 +26,12 @@ import {
  Upload
 } from "lucide-react";
 import {
+  ActionBlockerHint,
  Button,
  ConfirmDialog,
  Dialog,
  DismissibleAlert,
+  DocumentationHelpLink,
  FormField,
  IconButton,
  LoadingFrame,
@@ -97,6 +99,12 @@ import {
  type PipelineDraft
 } from "./model";
 import { dataflowNodeIcon } from "./nodeIcons";
+import {
+  DATAFLOW_DOCUMENTATION,
+  DATAFLOW_FIELDS_DOCUMENTATION,
+  DATAFLOW_I18N,
+  DATAFLOW_RUN_DOCUMENTATION
+} from "./interfacePatterns";

 type ResultTab = "preview" | "diagnostics";
 type SnapshotFormat = "json" | "csv";
@@ -145,6 +153,9 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
  const canEdit = canWrite && (
    !draft?.id || draft.governance?.actions.edit?.allowed !== false
  );
+  const editBlockedReason = !canWrite
+    ? DATAFLOW_I18N.writeReason
+    : draft?.governance?.actions.edit?.reason ?? DATAFLOW_I18N.writeReason;
  const canReuse = Boolean(
    draft?.id
    && canWrite
@@ -313,8 +324,8 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings

  useUnsavedDraftGuard({
    dirty,
-    title: "Unsaved pipeline",
-    message: "Save or discard the pipeline changes before leaving this workspace.",
+    title: "i18n:govoplan-dataflow.unsaved_title",
+    message: "i18n:govoplan-dataflow.unsaved_message",
    onSave: saveDraft,
    onDiscard: discardDraft
  });
@@ -577,6 +588,7 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                variant="ghost"
                onClick={() => requestNavigation(() => void loadPipelines(draft?.id))}
                disabled={loading}
+                disabledReason={loading ? DATAFLOW_I18N.loading : undefined}
              />
              <IconButton
                label="New pipeline"
@@ -584,6 +596,7 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                variant="primary"
                onClick={createNew}
                disabled={!canWrite}
+                disabledReason={!canWrite ? DATAFLOW_I18N.writeReason : undefined}
              />
            </span>
          </div>
@@ -658,6 +671,7 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                  </select>
                </div>
                <div className="dataflow-command-bar">
+                  <DocumentationHelpLink reference={DATAFLOW_DOCUMENTATION} />
                  <SegmentedControl<EditorMode>
                    ariaLabel="Pipeline editor mode"
                    options={[
@@ -676,7 +690,11 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                    onClick={() => void runPreview(selectedNodeId ?? undefined)}
                    disabled={working || !canPreview}
                    disabledReason={
-                      draft.governance?.actions.run?.reason ?? undefined
+                      working
+                        ? DATAFLOW_I18N.working
+                        : !canRun
+                          ? DATAFLOW_I18N.runReason
+                          : draft.governance?.actions.run?.reason ?? undefined
                    }
                  >
                    {preview ? <RefreshCw size={16} /> : <Play size={16} />}
@@ -695,7 +713,11 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                    disabled={working || !canRun || dirty || !canStartSavedRun || !draft.currentRevision}
                    disabledReason={
                      dirty
-                        ? "Save the pipeline before starting a pinned run."
+                        ? DATAFLOW_I18N.saveFirst
+                        : working
+                          ? DATAFLOW_I18N.working
+                          : !canRun
+                            ? DATAFLOW_I18N.runReason
                            : draft.governance?.actions.run?.reason ?? undefined
                    }
                  >
@@ -707,6 +729,7 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                    variant="ghost"
                    onClick={() => setDefinitionSettingsOpen(true)}
                    disabled={!draft}
+                    disabledReason={!draft ? DATAFLOW_I18N.noSelection : undefined}
                  />
                  {draft.id ? (
                    <IconButton
@@ -715,6 +738,11 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                      variant="ghost"
                      onClick={() => setDeriveOpen(true)}
                      disabled={!canReuse}
+                      disabledReason={
+                        !canReuse
+                          ? draft.governance?.actions.derive?.reason ?? editBlockedReason
+                          : undefined
+                      }
                    />
                  ) : null}
                  {draft.id ? (
@@ -724,6 +752,7 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                      variant="ghost"
                      onClick={() => setTriggersOpen(true)}
                      disabled={!canViewTriggers}
+                      disabledReason={!canViewTriggers ? DATAFLOW_I18N.writeReason : undefined}
                    />
                  ) : null}
                  <IconButton
@@ -732,6 +761,13 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                    variant="ghost"
                    onClick={() => requestDiscard(() => undefined)}
                    disabled={!dirty || saving}
+                    disabledReason={
+                      saving
+                        ? DATAFLOW_I18N.working
+                        : !dirty
+                          ? DATAFLOW_I18N.noChanges
+                          : undefined
+                    }
                  />
                  {draft.id ? (
                    <IconButton
@@ -740,12 +776,24 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
                      variant="danger"
                      onClick={() => setDeleteOpen(true)}
                      disabled={!canEdit || saving}
+                      disabledReason={
+                        saving ? DATAFLOW_I18N.working : !canEdit ? editBlockedReason : undefined
+                      }
                    />
                  ) : null}
                  <Button
                    variant="primary"
                    onClick={() => void saveDraft()}
                    disabled={saving || working || !dirty || !canEdit}
+                    disabledReason={
+                      saving || working
+                        ? DATAFLOW_I18N.working
+                        : !canEdit
+                          ? editBlockedReason
+                          : !dirty
+                            ? DATAFLOW_I18N.noChanges
+                            : undefined
+                    }
                  >
                    <Save size={16} /> {saving ? "Saving..." : "Save"}
                  </Button>
@@ -757,6 +805,26 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
              {success ? (
                <DismissibleAlert tone="success" resetKey={success} floating>{success}</DismissibleAlert>
              ) : null}
+              {!canEdit ? (
+                <div className="dataflow-action-guidance">
+                  <ActionBlockerHint
+                    tone="info"
+                    reason={{
+                      summary: "Pipeline definition is read-only",
+                      details: editBlockedReason,
+                      requiredAction: DATAFLOW_I18N.permissionAction,
+                      actor: DATAFLOW_I18N.permissionActor,
+                      target: DATAFLOW_I18N.permissionDestination
+                    }}
+                    labels={{
+                      requiredAction: DATAFLOW_I18N.requiredAction,
+                      actor: DATAFLOW_I18N.actor,
+                      target: DATAFLOW_I18N.destination
+                    }}
+                    documentation={DATAFLOW_DOCUMENTATION}
+                  />
+                </div>
+              ) : null}
              <div className={`dataflow-editor ${draft.editorMode === "sql" ? "is-sql" : ""}`}>
                {draft.editorMode === "graph" ? (
                  <aside className="dataflow-palette" aria-label="Transform palette">
@@ -872,7 +940,12 @@ export default function DataflowPage({ settings, auth }: { settings: ApiSettings
            <div className="dataflow-workspace-empty">
              <Network size={30} />
              <strong>No pipeline selected</strong>
-              <Button variant="primary" onClick={createNew} disabled={!canWrite}>
+              <Button
+                variant="primary"
+                onClick={createNew}
+                disabled={!canWrite}
+                disabledReason={!canWrite ? DATAFLOW_I18N.writeReason : undefined}
+              >
                <Plus size={16} /> New pipeline
              </Button>
            </div>
@@ -1038,6 +1111,7 @@ function DefinitionSettingsDialog({
          <FormField
            label="Scope"
            help="The scope determines ownership, visibility, and where Policy inheritance is resolved."
+            documentation={DATAFLOW_FIELDS_DOCUMENTATION}
          >
            <select
              value={draft.scopeType}
@@ -1061,6 +1135,7 @@ function DefinitionSettingsDialog({
                  ? "The stable account ID is stored; directory labels are presentation-only."
                  : "Only groups available in the active tenant can be selected."
              }
+              documentation={DATAFLOW_FIELDS_DOCUMENTATION}
            >
              <ReferenceSelect
                value={draft.scopeId}
@@ -1084,6 +1159,7 @@ function DefinitionSettingsDialog({
          <FormField
            label="Definition kind"
            help="Templates can be reused or derived, but cannot be run or automated directly."
+            documentation={DATAFLOW_FIELDS_DOCUMENTATION}
          >
            <select
              value={draft.definitionKind}
@@ -1166,12 +1242,23 @@ function DerivePipelineDialog({
  onClose: () => void;
  onDerived: (pipeline: Pipeline) => void;
 }) {
+  const { requestDiscard } = useUnsavedChanges();
  const [name, setName] = useState("");
  const [kind, setKind] = useState<"flow" | "template">("flow");
  const [scopeType, setScopeType] = useState<"tenant" | "group" | "user">("tenant");
  const [scopeId, setScopeId] = useState("");
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState("");
+  const defaultName = `${pipeline?.name ?? "Pipeline"} copy`;
+  const dirty = Boolean(
+    open
+    && (
+      name !== defaultName
+      || kind !== "flow"
+      || scopeType !== "tenant"
+      || scopeId !== ""
+    )
+  );
  const scopeProvider = useMemo(
    () =>
      dataflowScopeReferenceProvider(
@@ -1188,15 +1275,23 @@ function DerivePipelineDialog({

  useEffect(() => {
    if (!open) return;
-    setName(`${pipeline?.name ?? "Pipeline"} copy`);
+    setName(defaultName);
    setKind("flow");
    setScopeType("tenant");
    setScopeId("");
    setError("");
-  }, [open, pipeline?.id]);
+  }, [defaultName, open, pipeline?.id]);

-  const derive = async () => {
-    if (!pipeline || !name.trim()) return;
+  const resetDraft = () => {
+    setName(defaultName);
+    setKind("flow");
+    setScopeType("tenant");
+    setScopeId("");
+    setError("");
+  };
+
+  const derive = async (): Promise<boolean> => {
+    if (!pipeline || !name.trim()) return false;
    setBusy(true);
    setError("");
    try {
@@ -1211,23 +1306,39 @@ function DerivePipelineDialog({
        allow_reuse: false,
        allow_automation: false
      }));
+      return true;
    } catch (deriveError) {
      setError(apiErrorMessage(deriveError));
+      return false;
    } finally {
      setBusy(false);
    }
  };

+  useUnsavedDraftGuard({
+    dirty,
+    title: "i18n:govoplan-dataflow.unsaved_copy_title",
+    message: "i18n:govoplan-dataflow.unsaved_copy_message",
+    onSave: derive,
+    onDiscard: resetDraft
+  });
+
+  const close = () => {
+    if (busy) return;
+    if (dirty) requestDiscard(onClose);
+    else onClose();
+  };
+
  return (
    <Dialog
      open={open}
      title="Reuse as scoped copy"
      className="dataflow-definition-dialog"
      closeDisabled={busy}
-      onClose={onClose}
+      onClose={close}
      footer={(
        <>
-          <Button onClick={onClose} disabled={busy}>Cancel</Button>
+          <Button onClick={close} disabled={busy}>Cancel</Button>
          <Button
            variant="primary"
            onClick={() => void derive()}
@@ -1245,10 +1356,10 @@ function DerivePipelineDialog({
    >
      <div className="dataflow-definition-fields">
        {error ? <DismissibleAlert tone="danger" resetKey={error}>{error}</DismissibleAlert> : null}
-        <FormField label="Name">
+        <FormField label="Name" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
          <input value={name} onChange={(event) => setName(event.target.value)} />
        </FormField>
-        <FormField label="Target scope">
+        <FormField label="Target scope" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
          <select
            value={scopeType}
            onChange={(event) => {
@@ -1262,7 +1373,10 @@ function DerivePipelineDialog({
          </select>
        </FormField>
        {scopeType !== "tenant" ? (
-          <FormField label={scopeType === "user" ? "User" : "Group"}>
+          <FormField
+            label={scopeType === "user" ? "User" : "Group"}
+            documentation={DATAFLOW_FIELDS_DOCUMENTATION}
+          >
            <ReferenceSelect
              value={scopeId}
              onChange={(value) => setScopeId(value)}
@@ -1278,7 +1392,7 @@ function DerivePipelineDialog({
            />
          </FormField>
        ) : null}
-        <FormField label="Copy kind">
+        <FormField label="Copy kind" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
          <select value={kind} onChange={(event) => setKind(event.target.value as typeof kind)}>
            <option value="flow">Complete flow</option>
            <option value="template">Template</option>
@@ -1306,6 +1420,7 @@ function DataflowTriggersDialog({
  editable: boolean;
  onClose: () => void;
 }) {
+  const { requestNavigation, requestDiscard } = useUnsavedChanges();
  const [triggers, setTriggers] = useState<DataflowTrigger[]>([]);
  const [selectedId, setSelectedId] = useState<string | null>(null);
  const [name, setName] = useState("");
@@ -1320,7 +1435,22 @@ function DataflowTriggersDialog({
  const [eventFilters, setEventFilters] = useState("{}");
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState("");
+  const [savedFingerprint, setSavedFingerprint] = useState("");
+  const [deleteCandidate, setDeleteCandidate] = useState<DataflowTrigger | null>(null);
  const selected = triggers.find((item) => item.id === selectedId) ?? null;
+  const currentFingerprint = JSON.stringify([
+    name,
+    kind,
+    enabled,
+    runAt,
+    intervalMinutes,
+    catchUpPolicy,
+    maxConcurrentRuns,
+    eventType,
+    eventModule,
+    eventFilters
+  ]);
+  const dirty = Boolean(open && savedFingerprint && currentFingerprint !== savedFingerprint);

  const load = useCallback(async () => {
    if (!pipeline) return;
@@ -1348,27 +1478,58 @@ function DataflowTriggersDialog({
    setEventType("");
    setEventModule("");
    setEventFilters("{}");
+    setSavedFingerprint(JSON.stringify([
+      `${pipeline.name} schedule`,
+      "interval",
+      false,
+      "",
+      60,
+      "coalesce",
+      1,
+      "",
+      "",
+      "{}"
+    ]));
+    setDeleteCandidate(null);
    void load();
  }, [open, pipeline?.id, load]);

  const edit = (trigger: DataflowTrigger) => {
+    const nextRunAt = toLocalDateTime(trigger.schedule?.run_at ?? "");
+    const nextInterval = Math.max(1, Math.round((trigger.schedule?.interval_seconds ?? 3600) / 60));
+    const nextEventType = trigger.event?.event_type ?? "";
+    const nextEventModule = trigger.event?.module_id ?? "";
+    const nextFilters = JSON.stringify(trigger.event?.filters ?? {}, null, 2);
    setSelectedId(trigger.id);
    setName(trigger.name);
    setKind(trigger.kind);
    setEnabled(trigger.status === "enabled");
-    setRunAt(toLocalDateTime(trigger.schedule?.run_at ?? ""));
-    setIntervalMinutes(Math.max(1, Math.round((trigger.schedule?.interval_seconds ?? 3600) / 60)));
+    setRunAt(nextRunAt);
+    setIntervalMinutes(nextInterval);
    setCatchUpPolicy(trigger.catch_up_policy);
    setMaxConcurrentRuns(trigger.max_concurrent_runs);
-    setEventType(trigger.event?.event_type ?? "");
-    setEventModule(trigger.event?.module_id ?? "");
-    setEventFilters(JSON.stringify(trigger.event?.filters ?? {}, null, 2));
+    setEventType(nextEventType);
+    setEventModule(nextEventModule);
+    setEventFilters(nextFilters);
+    setSavedFingerprint(JSON.stringify([
+      trigger.name,
+      trigger.kind,
+      trigger.status === "enabled",
+      nextRunAt,
+      nextInterval,
+      trigger.catch_up_policy,
+      trigger.max_concurrent_runs,
+      nextEventType,
+      nextEventModule,
+      nextFilters
+    ]));
    setError("");
  };

  const reset = () => {
+    const defaultName = `${pipeline?.name ?? "Pipeline"} schedule`;
    setSelectedId(null);
-    setName(`${pipeline?.name ?? "Pipeline"} schedule`);
+    setName(defaultName);
    setKind("interval");
    setEnabled(false);
    setRunAt("");
@@ -1378,11 +1539,23 @@ function DataflowTriggersDialog({
    setEventType("");
    setEventModule("");
    setEventFilters("{}");
+    setSavedFingerprint(JSON.stringify([
+      defaultName,
+      "interval",
+      false,
+      "",
+      60,
+      "coalesce",
+      1,
+      "",
+      "",
+      "{}"
+    ]));
    setError("");
  };

-  const save = async () => {
-    if (!pipeline || !name.trim()) return;
+  const save = async (): Promise<boolean> => {
+    if (!pipeline || !name.trim()) return false;
    setBusy(true);
    setError("");
    try {
@@ -1420,12 +1593,14 @@ function DataflowTriggersDialog({
        ...current.filter((item) => item.id !== saved.id)
      ]);
      edit(saved);
+      return true;
    } catch (saveError) {
      setError(
        saveError instanceof SyntaxError
          ? "Event filters must be a JSON object with scalar values."
          : apiErrorMessage(saveError)
      );
+      return false;
    } finally {
      setBusy(false);
    }
@@ -1437,6 +1612,7 @@ function DataflowTriggersDialog({
    try {
      await deleteDataflowTrigger(settings, trigger.id);
      setTriggers((current) => current.filter((item) => item.id !== trigger.id));
+      setDeleteCandidate(null);
      reset();
    } catch (deleteError) {
      setError(apiErrorMessage(deleteError));
@@ -1451,18 +1627,57 @@ function DataflowTriggersDialog({
    && (kind !== "event" || eventType.trim())
  );

+  useUnsavedDraftGuard({
+    dirty,
+    title: "i18n:govoplan-dataflow.unsaved_trigger_title",
+    message: "i18n:govoplan-dataflow.unsaved_trigger_message",
+    onSave: save,
+    onDiscard: () => {
+      if (selected) edit(selected);
+      else reset();
+    }
+  });
+
+  const close = () => {
+    if (busy) return;
+    if (dirty) requestDiscard(onClose);
+    else onClose();
+  };
+
  return (
+    <>
      <Dialog
        open={open}
        title={`Automation · ${pipeline?.name ?? "pipeline"}`}
        className="dataflow-triggers-dialog"
        closeDisabled={busy}
-      onClose={onClose}
+        onClose={close}
        footer={(
          <>
-          <Button onClick={onClose} disabled={busy}>Close</Button>
-          <Button onClick={reset} disabled={busy || !editable}>New trigger</Button>
-          <Button variant="primary" onClick={() => void save()} disabled={busy || !editable || !complete}>
+            <Button onClick={close} disabled={busy}>Close</Button>
+            <Button
+              onClick={() => requestNavigation(reset)}
+              disabled={busy || !editable}
+              disabledReason={busy ? DATAFLOW_I18N.working : !editable ? DATAFLOW_I18N.writeReason : undefined}
+            >
+              New trigger
+            </Button>
+            <Button
+              variant="primary"
+              onClick={() => void save()}
+              disabled={busy || !editable || !complete || (Boolean(selected) && !dirty)}
+              disabledReason={
+                busy
+                  ? DATAFLOW_I18N.working
+                  : !editable
+                    ? DATAFLOW_I18N.writeReason
+                    : !complete
+                      ? "Complete the trigger fields first."
+                    : selected && !dirty
+                        ? DATAFLOW_I18N.noChanges
+                        : undefined
+              }
+            >
              <Save size={16} /> Save trigger
            </Button>
          </>
@@ -1475,7 +1690,7 @@ function DataflowTriggersDialog({
              key={trigger.id}
              type="button"
              className={trigger.id === selectedId ? "is-selected" : ""}
-              onClick={() => edit(trigger)}
+              onClick={() => requestNavigation(() => edit(trigger))}
            >
              <span>
                <strong>{trigger.name}</strong>
@@ -1490,11 +1705,12 @@ function DataflowTriggersDialog({
          {!busy && !triggers.length ? <small>No triggers configured</small> : null}
        </div>
        <div className="dataflow-trigger-form">
+          <DocumentationHelpLink reference={DATAFLOW_FIELDS_DOCUMENTATION} />
          {error ? <DismissibleAlert tone="danger" resetKey={error}>{error}</DismissibleAlert> : null}
-          <FormField label="Name">
+          <FormField label="Name" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
            <input disabled={!editable} value={name} onChange={(event) => setName(event.target.value)} />
          </FormField>
-          <FormField label="Trigger">
+          <FormField label="Trigger" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
            <select disabled={!editable} value={kind} onChange={(event) => setKind(event.target.value as DataflowTriggerKind)}>
              <option value="once">Given time</option>
              <option value="interval">Interval</option>
@@ -1502,13 +1718,13 @@ function DataflowTriggersDialog({
            </select>
          </FormField>
          {kind === "once" ? (
-            <FormField label="Run at">
+            <FormField label="Run at" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
              <input disabled={!editable} type="datetime-local" value={runAt} onChange={(event) => setRunAt(event.target.value)} />
            </FormField>
          ) : null}
          {kind === "interval" ? (
            <>
-              <FormField label="Interval (minutes)">
+              <FormField label="Interval (minutes)" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
                <input
                  type="number"
                  min={1}
@@ -1517,7 +1733,7 @@ function DataflowTriggersDialog({
                  onChange={(event) => setIntervalMinutes(Math.max(1, Number(event.target.value)))}
                />
              </FormField>
-              <FormField label="Missed runs">
+              <FormField label="Missed runs" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
                <select
                  disabled={!editable}
                  value={catchUpPolicy}
@@ -1531,15 +1747,16 @@ function DataflowTriggersDialog({
          ) : null}
          {kind === "event" ? (
            <>
-              <FormField label="Event type">
+              <FormField label="Event type" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
                <input disabled={!editable} value={eventType} onChange={(event) => setEventType(event.target.value)} />
              </FormField>
-              <FormField label="Source module">
+              <FormField label="Source module" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
                <input disabled={!editable} value={eventModule} onChange={(event) => setEventModule(event.target.value)} />
              </FormField>
              <FormField
                label="Exact payload filters"
                help="Only direct scalar payload fields are matched. No expressions are executed."
+                documentation={DATAFLOW_FIELDS_DOCUMENTATION}
              >
                <textarea disabled={!editable} value={eventFilters} onChange={(event) => setEventFilters(event.target.value)} />
              </FormField>
@@ -1551,7 +1768,7 @@ function DataflowTriggersDialog({
            disabled={busy || !editable}
            onChange={setEnabled}
          />
-          <FormField label="Concurrent runs">
+          <FormField label="Concurrent runs" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
            <input
              type="number"
              min={1}
@@ -1570,7 +1787,12 @@ function DataflowTriggersDialog({
              {selected.grant_scopes.map((scope) => <code key={scope}>{scope}</code>)}
              <small>Authorization is resolved again for every delivery.</small>
              {selected.last_error ? <small className="is-error">{selected.last_error}</small> : null}
-              <Button variant="danger" onClick={() => void remove(selected)} disabled={busy || !editable}>
+              <Button
+                variant="danger"
+                onClick={() => requestNavigation(() => setDeleteCandidate(selected))}
+                disabled={busy || !editable}
+                disabledReason={busy ? DATAFLOW_I18N.working : !editable ? DATAFLOW_I18N.writeReason : undefined}
+              >
                <Trash2 size={16} /> Delete trigger
              </Button>
            </section>
@@ -1578,6 +1800,19 @@ function DataflowTriggersDialog({
        </div>
        </div>
      </Dialog>
+      <ConfirmDialog
+        open={deleteCandidate !== null}
+        title="Delete automation trigger"
+        message={`Delete ${deleteCandidate?.name ?? "this trigger"}? Future automatic runs will stop; retained run and audit evidence is not removed.`}
+        confirmLabel="Delete trigger"
+        tone="danger"
+        busy={busy}
+        onCancel={() => setDeleteCandidate(null)}
+        onConfirm={() => {
+          if (deleteCandidate) void remove(deleteCandidate);
+        }}
+      />
+    </>
  );
 }

@@ -1589,6 +1824,7 @@ function toLocalDateTime(value: string): string {
 }

 type RunMode = "run" | "publish";
+type RunConfirmation = RunMode | "staging" | "production";

 function RunPipelineDialog({
  open,
@@ -1621,6 +1857,7 @@ function RunPipelineDialog({
  const [loadingRuns, setLoadingRuns] = useState(false);
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState("");
+  const [confirmation, setConfirmation] = useState<RunConfirmation | null>(null);
  const publicationTargets = sources.filter((source) =>
    source.mode !== "live" && source.capabilities.includes("read")
  );
@@ -1637,6 +1874,7 @@ function RunPipelineDialog({
    setIdempotencyKey(crypto.randomUUID());
    setEnvironment("development");
    setError("");
+    setConfirmation(null);
    setLoadingRuns(true);
    void Promise.all([
      listDataflowPipelineRuns(settings, pipeline.id),
@@ -1738,22 +1976,60 @@ function RunPipelineDialog({
  const targetComplete = mode === "run"
    || targetRef !== "new"
    || Boolean(name.trim() && sourceName.trim());
+  const confirmationTitle = confirmation === "production"
+    ? "i18n:govoplan-dataflow.promote_production_title"
+    : confirmation === "staging"
+      ? "i18n:govoplan-dataflow.promote_staging_title"
+      : confirmation === "publish"
+        ? "i18n:govoplan-dataflow.publish_title"
+        : "i18n:govoplan-dataflow.queue_title";
+  const confirmationMessage = confirmation === "production"
+    ? "i18n:govoplan-dataflow.promote_production_message"
+    : confirmation === "staging"
+      ? "i18n:govoplan-dataflow.promote_staging_message"
+      : confirmation === "publish"
+        ? "i18n:govoplan-dataflow.publish_message"
+        : "i18n:govoplan-dataflow.queue_message";
+
+  const confirmAction = async () => {
+    const action = confirmation;
+    if (!action) return;
+    if (action === "staging" || action === "production") {
+      await promote(action);
+    } else {
+      await start();
+    }
+    setConfirmation(null);
+  };

  return (
+    <>
      <Dialog
        open={open}
        title={`Run ${pipeline?.name ?? "pipeline"}`}
        className="dataflow-run-dialog"
        onClose={() => {
-        if (!busy) onClose();
+          if (!busy) {
+            setConfirmation(null);
+            onClose();
+          }
        }}
        footer={(
          <>
            <Button onClick={onClose} disabled={busy}>Close</Button>
            <Button
              variant="primary"
-            onClick={() => void start()}
+              onClick={() => setConfirmation(mode)}
              disabled={busy || !pipeline || !targetComplete}
+              disabledReason={
+                busy
+                  ? DATAFLOW_I18N.working
+                  : !pipeline
+                    ? DATAFLOW_I18N.noSelection
+                    : !targetComplete
+                      ? "Complete the publication target fields first."
+                      : undefined
+              }
            >
              <Play size={16} /> {busy ? "Queueing..." : "Queue run"}
            </Button>
@@ -1767,6 +2043,7 @@ function RunPipelineDialog({
          </DismissibleAlert>
        ) : null}
        <div className="dataflow-run-controls">
+          <DocumentationHelpLink reference={DATAFLOW_RUN_DOCUMENTATION} />
          <SegmentedControl<RunMode>
            ariaLabel="Run output"
            options={[
@@ -1781,7 +2058,7 @@ function RunPipelineDialog({
          </span>
        </div>
        <div className="dataflow-run-publication-fields">
-          <FormField label="Environment">
+          <FormField label="Environment" documentation={DATAFLOW_RUN_DOCUMENTATION}>
            <select
              value={environment}
              onChange={(event) => setEnvironment(
@@ -1796,7 +2073,7 @@ function RunPipelineDialog({
          {canPromote ? (
            <>
              <Button
-                onClick={() => void promote("staging")}
+                onClick={() => setConfirmation("staging")}
                disabled={busy || deployments.some((item) =>
                  item.environment === "staging" && item.revision === pipeline?.revision
                )}
@@ -1804,7 +2081,7 @@ function RunPipelineDialog({
                <Rocket size={16} /> Promote to staging
              </Button>
              <Button
-                onClick={() => void promote("production")}
+                onClick={() => setConfirmation("production")}
                disabled={busy
                  || !deployments.some((item) =>
                    item.environment === "staging" && item.revision === pipeline?.revision
@@ -1820,7 +2097,7 @@ function RunPipelineDialog({
        </div>
        {mode === "publish" ? (
          <div className="dataflow-run-publication-fields">
-            <FormField label="Target">
+            <FormField label="Target" documentation={DATAFLOW_RUN_DOCUMENTATION}>
              <select
                value={targetRef}
                onChange={(event) => setTargetRef(event.target.value)}
@@ -1835,20 +2112,20 @@ function RunPipelineDialog({
            </FormField>
            {targetRef === "new" ? (
              <>
-                <FormField label="Name">
+                <FormField label="Name" documentation={DATAFLOW_RUN_DOCUMENTATION}>
                  <input
                    value={name}
                    onChange={(event) => setName(event.target.value)}
                  />
                </FormField>
-                <FormField label="Logical source name">
+                <FormField label="Logical source name" documentation={DATAFLOW_RUN_DOCUMENTATION}>
                  <input
                    value={sourceName}
                    onChange={(event) => setSourceName(event.target.value)}
                    pattern="[A-Za-z_][A-Za-z0-9_]*"
                  />
                </FormField>
-                <FormField label="Description">
+                <FormField label="Description" documentation={DATAFLOW_RUN_DOCUMENTATION}>
                  <input
                    value={description}
                    onChange={(event) => setDescription(event.target.value)}
@@ -1864,7 +2141,7 @@ function RunPipelineDialog({
              />
            </div>
            {freeze ? (
-              <FormField label="Frozen-state label">
+              <FormField label="Frozen-state label" documentation={DATAFLOW_RUN_DOCUMENTATION}>
                <input
                  value={frozenLabel}
                  onChange={(event) => setFrozenLabel(event.target.value)}
@@ -1948,6 +2225,19 @@ function RunPipelineDialog({
        </section>
        </div>
      </Dialog>
+      <ConfirmDialog
+        open={confirmation !== null}
+        title={confirmationTitle}
+        message={confirmationMessage}
+        confirmLabel={confirmation === "production" ? "Promote to production" : confirmation === "staging" ? "Promote to staging" : "Queue run"}
+        tone={confirmation === "production" ? "danger" : "default"}
+        busy={busy}
+        onCancel={() => {
+          if (!busy) setConfirmation(null);
+        }}
+        onConfirm={() => void confirmAction()}
+      />
+    </>
  );
 }

@@ -1962,6 +2252,7 @@ function SourceSnapshotDialog({
  onClose: () => void;
  onCreated: (source: TabularSource) => void;
 }) {
+  const { requestDiscard } = useUnsavedChanges();
  const [name, setName] = useState("");
  const [sourceName, setSourceName] = useState("");
  const [description, setDescription] = useState("");
@@ -1972,9 +2263,20 @@ function SourceSnapshotDialog({
  const [fileInputKey, setFileInputKey] = useState(0);
  const [busy, setBusy] = useState(false);
  const [error, setError] = useState("");
+  const dirty = Boolean(
+    open
+    && (
+      name !== ""
+      || sourceName !== ""
+      || description !== ""
+      || format !== "json"
+      || rowsText !== "[]"
+      || csvText !== ""
+      || delimiter !== ","
+    )
+  );

-  useEffect(() => {
-    if (!open) return;
+  const resetDraft = () => {
    setName("");
    setSourceName("");
    setDescription("");
@@ -1984,9 +2286,14 @@ function SourceSnapshotDialog({
    setDelimiter(",");
    setFileInputKey((current) => current + 1);
    setError("");
+  };
+
+  useEffect(() => {
+    if (!open) return;
+    resetDraft();
  }, [open]);

-  const create = async () => {
+  const create = async (): Promise<boolean> => {
    setError("");
    let rows: Record<string, unknown>[] = [];
    if (format === "json") {
@@ -1998,11 +2305,11 @@ function SourceSnapshotDialog({
        rows = parsed;
      } catch (parseError) {
        setError(parseError instanceof Error ? parseError.message : "Rows could not be parsed.");
-        return;
+        return false;
      }
    } else if (!csvText.trim()) {
      setError("Choose a CSV file or paste CSV data.");
-      return;
+      return false;
    }
    setBusy(true);
    try {
@@ -2015,13 +2322,29 @@ function SourceSnapshotDialog({
          : { format, csv_text: csvText, delimiter })
      });
      onCreated(source);
+      return true;
    } catch (createError) {
      setError(apiErrorMessage(createError));
+      return false;
    } finally {
      setBusy(false);
    }
  };

+  useUnsavedDraftGuard({
+    dirty,
+    title: "i18n:govoplan-dataflow.unsaved_source_title",
+    message: "i18n:govoplan-dataflow.unsaved_source_message",
+    onSave: create,
+    onDiscard: resetDraft
+  });
+
+  const close = () => {
+    if (busy) return;
+    if (dirty) requestDiscard(onClose);
+    else onClose();
+  };
+
  const loadCsvFile = async (file: File | undefined) => {
    if (!file) return;
    setError("");
@@ -2040,12 +2363,10 @@ function SourceSnapshotDialog({
      open={open}
      title="Stage datasource"
      className="dataflow-source-dialog"
-      onClose={() => {
-        if (!busy) onClose();
-      }}
+      onClose={close}
      footer={(
        <>
-          <Button onClick={onClose} disabled={busy}>Cancel</Button>
+          <Button onClick={close} disabled={busy}>Cancel</Button>
          <Button
            variant="primary"
            onClick={() => void create()}
@@ -2071,10 +2392,10 @@ function SourceSnapshotDialog({
            onChange={setFormat}
          />
        </div>
-        <FormField label="Name">
+        <FormField label="Name" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
          <input value={name} onChange={(event) => setName(event.target.value)} />
        </FormField>
-        <FormField label="Logical source name">
+        <FormField label="Logical source name" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
          <input
            value={sourceName}
            onChange={(event) => setSourceName(event.target.value)}
@@ -2082,12 +2403,12 @@ function SourceSnapshotDialog({
            placeholder="monthly_input"
          />
        </FormField>
-        <FormField label="Description">
+        <FormField label="Description" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
          <input value={description} onChange={(event) => setDescription(event.target.value)} />
        </FormField>
        {format === "csv" ? (
          <>
-            <FormField label="CSV file">
+            <FormField label="CSV file" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
              <input
                key={fileInputKey}
                type="file"
@@ -2095,7 +2416,7 @@ function SourceSnapshotDialog({
                onChange={(event) => void loadCsvFile(event.target.files?.[0])}
              />
            </FormField>
-            <FormField label="Delimiter">
+            <FormField label="Delimiter" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
              <select value={delimiter} onChange={(event) => setDelimiter(event.target.value)}>
                <option value=",">Comma</option>
                <option value=";">Semicolon</option>
@@ -2103,7 +2424,7 @@ function SourceSnapshotDialog({
                <option value="|">Pipe</option>
              </select>
            </FormField>
-            <FormField label="CSV data">
+            <FormField label="CSV data" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
              <textarea
                className="dataflow-json-editor"
                value={csvText}
@@ -2113,7 +2434,7 @@ function SourceSnapshotDialog({
            </FormField>
          </>
        ) : (
-          <FormField label="Rows">
+          <FormField label="Rows" documentation={DATAFLOW_FIELDS_DOCUMENTATION}>
            <textarea
              className="dataflow-json-editor"
              value={rowsText}
@@ -1,8 +1,8 @@
-import { useEffect, useState } from "react";
+import { useEffect, useState, type ComponentProps } from "react";
 import { Play, Trash2 } from "lucide-react";
 import {
  DismissibleAlert,
-  FormField,
+  FormField as CoreFormField,
  IconButton
 } from "@govoplan/core-webui";
 import type {
@@ -10,6 +10,18 @@ import type {
  PipelineGraphNode,
  TabularSource
 } from "../../api/dataflow";
+import { DATAFLOW_NODE_DOCUMENTATION } from "./interfacePatterns";
+
+type NodeFormFieldProps = ComponentProps<typeof CoreFormField>;
+
+function FormField({ documentation, ...props }: NodeFormFieldProps) {
+  return (
+    <CoreFormField
+      {...props}
+      documentation={documentation ?? DATAFLOW_NODE_DOCUMENTATION}
+    />
+  );
+}

 type NodeInspectorProps = {
  node: PipelineGraphNode | null;
@@ -0,0 +1,37 @@
+import type { DocumentationHelpReference } from "@govoplan/core-webui";
+
+export const DATAFLOW_DOCUMENTATION = {
+  topicId: "dataflow.module-boundary",
+  documentationType: "user"
+} satisfies DocumentationHelpReference;
+
+export const DATAFLOW_FIELDS_DOCUMENTATION = {
+  topicId: "dataflow.reference.fields-and-consequences",
+  documentationType: "admin"
+} satisfies DocumentationHelpReference;
+
+export const DATAFLOW_NODE_DOCUMENTATION = {
+  topicId: "dataflow.reference.nodes-and-expressions",
+  documentationType: "user"
+} satisfies DocumentationHelpReference;
+
+export const DATAFLOW_RUN_DOCUMENTATION = {
+  topicId: "dataflow.execution-and-recovery",
+  documentationType: "admin"
+} satisfies DocumentationHelpReference;
+
+export const DATAFLOW_I18N = {
+  loading: "i18n:govoplan-dataflow.loading_reason",
+  working: "i18n:govoplan-dataflow.working_reason",
+  writeReason: "i18n:govoplan-dataflow.write_reason",
+  runReason: "i18n:govoplan-dataflow.run_reason",
+  noSelection: "i18n:govoplan-dataflow.no_selection_reason",
+  noChanges: "i18n:govoplan-dataflow.no_changes_reason",
+  saveFirst: "i18n:govoplan-dataflow.save_first_reason",
+  requiredAction: "i18n:govoplan-dataflow.required_action",
+  actor: "i18n:govoplan-dataflow.actor",
+  destination: "i18n:govoplan-dataflow.destination",
+  permissionAction: "i18n:govoplan-dataflow.permission_action",
+  permissionActor: "i18n:govoplan-dataflow.permission_actor",
+  permissionDestination: "i18n:govoplan-dataflow.permission_destination"
+} as const;
@@ -0,0 +1,163 @@
+import type { PlatformTranslations } from "@govoplan/core-webui";
+
+const en = {
+  "i18n:govoplan-dataflow.dataflow": "Dataflow",
+  "i18n:govoplan-dataflow.library": "Pipeline library",
+  "i18n:govoplan-dataflow.graph": "Graph editor",
+  "i18n:govoplan-dataflow.sql": "Constrained SQL editor",
+  "i18n:govoplan-dataflow.inspector": "Node inspector",
+  "i18n:govoplan-dataflow.results": "Preview and diagnostics",
+  "i18n:govoplan-dataflow.triggers": "Automation triggers",
+  "i18n:govoplan-dataflow.runs": "Runs and deployments",
+  "i18n:govoplan-dataflow.widget": "Dataflows widget",
+  "i18n:govoplan-dataflow.loading_reason": "The pipeline library is still loading.",
+  "i18n:govoplan-dataflow.working_reason": "Another Dataflow operation is still running.",
+  "i18n:govoplan-dataflow.write_reason": "Your account may not create or change pipeline definitions.",
+  "i18n:govoplan-dataflow.run_reason": "Your account may not preview or run pipelines.",
+  "i18n:govoplan-dataflow.no_selection_reason": "Select or create a pipeline first.",
+  "i18n:govoplan-dataflow.no_changes_reason": "There are no unsaved pipeline changes.",
+  "i18n:govoplan-dataflow.save_first_reason": "Save the pipeline before starting a revision-pinned run.",
+  "i18n:govoplan-dataflow.required_action": "Required action",
+  "i18n:govoplan-dataflow.actor": "Responsible actor",
+  "i18n:govoplan-dataflow.destination": "Where to continue",
+  "i18n:govoplan-dataflow.permission_action": "Ask for Dataflow definition or run permission for the intended operation.",
+  "i18n:govoplan-dataflow.permission_actor": "A tenant administrator or Dataflow manager",
+  "i18n:govoplan-dataflow.permission_destination": "Access administration for Dataflow",
+  "i18n:govoplan-dataflow.unsaved_title": "Unsaved pipeline",
+  "i18n:govoplan-dataflow.unsaved_message": "Save or discard the pipeline changes before leaving this workspace.",
+  "i18n:govoplan-dataflow.unsaved_copy_title": "Uncreated pipeline copy",
+  "i18n:govoplan-dataflow.unsaved_copy_message": "Create the scoped copy or discard its changed settings before leaving.",
+  "i18n:govoplan-dataflow.unsaved_source_title": "Unstaged datasource",
+  "i18n:govoplan-dataflow.unsaved_source_message": "Import the datasource snapshot or discard its staged content before leaving.",
+  "i18n:govoplan-dataflow.unsaved_trigger_title": "Unsaved automation trigger",
+  "i18n:govoplan-dataflow.unsaved_trigger_message": "Save or discard the trigger changes before leaving this editor.",
+  "i18n:govoplan-dataflow.queue_title": "Queue pipeline run",
+  "i18n:govoplan-dataflow.queue_message": "Queue this pinned pipeline revision? The run and its authorization evidence will be retained.",
+  "i18n:govoplan-dataflow.publish_title": "Queue and publish pipeline output",
+  "i18n:govoplan-dataflow.publish_message": "Queue this pinned revision and publish its output to the selected governed Datasource target?",
+  "i18n:govoplan-dataflow.promote_staging_title": "Promote revision to staging",
+  "i18n:govoplan-dataflow.promote_staging_message": "Promote this immutable pipeline revision to the staging execution environment?",
+  "i18n:govoplan-dataflow.promote_production_title": "Promote revision to production",
+  "i18n:govoplan-dataflow.promote_production_message": "Promote this immutable pipeline revision to production? Future production runs may use it.",
+  "Pipelines": "Pipelines",
+  "Search pipelines": "Search pipelines",
+  "No matching pipelines": "No matching pipelines",
+  "No pipelines yet": "No pipelines yet",
+  "Graph": "Graph",
+  "SQL": "SQL",
+  "Validate": "Validate",
+  "Preview": "Preview",
+  "Refresh": "Refresh",
+  "Run": "Run",
+  "Save": "Save",
+  "Saving...": "Saving...",
+  "Nodes": "Nodes",
+  "No pipeline selected": "No pipeline selected",
+  "New pipeline": "New pipeline",
+  "Definition settings": "Definition settings",
+  "Reuse as scoped copy": "Reuse as scoped copy",
+  "Automation triggers": "Automation triggers",
+  "Discard changes": "Discard changes",
+  "Delete pipeline": "Delete pipeline",
+  "Constrained Dataflow SQL": "Constrained Dataflow SQL",
+  "Apply SQL": "Apply SQL",
+  "Stage datasource": "Stage datasource",
+  "Run only": "Run only",
+  "Publish result": "Publish result",
+  "Environment": "Environment",
+  "Development": "Development",
+  "Staging": "Staging",
+  "Production": "Production",
+  "Promote to staging": "Promote to staging",
+  "Promote to production": "Promote to production",
+  "Recent runs": "Recent runs",
+  "Queue run": "Queue run",
+  "New trigger": "New trigger",
+  "Save trigger": "Save trigger",
+  "Delete trigger": "Delete trigger",
+  "Delete automation trigger": "Delete automation trigger",
+  "Pipeline definition is read-only": "Pipeline definition is read-only",
+  "Working...": "Working..."
+} as const;
+
+const de: Record<keyof typeof en, string> = {
+  "i18n:govoplan-dataflow.dataflow": "Datenfluss",
+  "i18n:govoplan-dataflow.library": "Datenflussbibliothek",
+  "i18n:govoplan-dataflow.graph": "Graph-Editor",
+  "i18n:govoplan-dataflow.sql": "Eingeschränkter SQL-Editor",
+  "i18n:govoplan-dataflow.inspector": "Knoteninspektor",
+  "i18n:govoplan-dataflow.results": "Vorschau und Diagnosen",
+  "i18n:govoplan-dataflow.triggers": "Automatisierungsauslöser",
+  "i18n:govoplan-dataflow.runs": "Ausführungen und Bereitstellungen",
+  "i18n:govoplan-dataflow.widget": "Datenfluss-Widget",
+  "i18n:govoplan-dataflow.loading_reason": "Die Datenflussbibliothek wird noch geladen.",
+  "i18n:govoplan-dataflow.working_reason": "Eine andere Datenflussoperation läuft noch.",
+  "i18n:govoplan-dataflow.write_reason": "Ihr Konto darf keine Datenflussdefinitionen erstellen oder ändern.",
+  "i18n:govoplan-dataflow.run_reason": "Ihr Konto darf Datenflüsse nicht prüfen oder ausführen.",
+  "i18n:govoplan-dataflow.no_selection_reason": "Wählen oder erstellen Sie zuerst einen Datenfluss.",
+  "i18n:govoplan-dataflow.no_changes_reason": "Es gibt keine ungespeicherten Datenflussänderungen.",
+  "i18n:govoplan-dataflow.save_first_reason": "Speichern Sie den Datenfluss vor einer revisionsgebundenen Ausführung.",
+  "i18n:govoplan-dataflow.required_action": "Erforderliche Aktion",
+  "i18n:govoplan-dataflow.actor": "Verantwortliche Stelle",
+  "i18n:govoplan-dataflow.destination": "Fortsetzung",
+  "i18n:govoplan-dataflow.permission_action": "Fordern Sie die für den Vorgang erforderliche Datenfluss- oder Ausführungsberechtigung an.",
+  "i18n:govoplan-dataflow.permission_actor": "Mandantenadministration oder Datenflussverwaltung",
+  "i18n:govoplan-dataflow.permission_destination": "Zugriffsverwaltung für Datenflüsse",
+  "i18n:govoplan-dataflow.unsaved_title": "Ungespeicherter Datenfluss",
+  "i18n:govoplan-dataflow.unsaved_message": "Speichern oder verwerfen Sie die Datenflussänderungen, bevor Sie diesen Arbeitsbereich verlassen.",
+  "i18n:govoplan-dataflow.unsaved_copy_title": "Nicht erstellte Datenflusskopie",
+  "i18n:govoplan-dataflow.unsaved_copy_message": "Erstellen Sie die eingegrenzte Kopie oder verwerfen Sie ihre geänderten Einstellungen.",
+  "i18n:govoplan-dataflow.unsaved_source_title": "Nicht bereitgestellte Datenquelle",
+  "i18n:govoplan-dataflow.unsaved_source_message": "Importieren Sie den Datenquellenstand oder verwerfen Sie dessen bereitgestellten Inhalt.",
+  "i18n:govoplan-dataflow.unsaved_trigger_title": "Ungespeicherter Automatisierungsauslöser",
+  "i18n:govoplan-dataflow.unsaved_trigger_message": "Speichern oder verwerfen Sie die Änderungen am Auslöser, bevor Sie diesen Editor verlassen.",
+  "i18n:govoplan-dataflow.queue_title": "Datenflussausführung einreihen",
+  "i18n:govoplan-dataflow.queue_message": "Diese gebundene Datenflussrevision einreihen? Ausführung und Berechtigungsnachweis werden aufbewahrt.",
+  "i18n:govoplan-dataflow.publish_title": "Datenflussausgabe einreihen und veröffentlichen",
+  "i18n:govoplan-dataflow.publish_message": "Diese gebundene Revision einreihen und ihre Ausgabe in der ausgewählten verwalteten Datenquelle veröffentlichen?",
+  "i18n:govoplan-dataflow.promote_staging_title": "Revision nach Staging übernehmen",
+  "i18n:govoplan-dataflow.promote_staging_message": "Diese unveränderliche Datenflussrevision in die Staging-Ausführungsumgebung übernehmen?",
+  "i18n:govoplan-dataflow.promote_production_title": "Revision in Produktion übernehmen",
+  "i18n:govoplan-dataflow.promote_production_message": "Diese unveränderliche Datenflussrevision in Produktion übernehmen? Künftige Produktionsausführungen können sie verwenden.",
+  "Pipelines": "Datenflüsse",
+  "Search pipelines": "Datenflüsse suchen",
+  "No matching pipelines": "Keine passenden Datenflüsse",
+  "No pipelines yet": "Noch keine Datenflüsse",
+  "Graph": "Graph",
+  "SQL": "SQL",
+  "Validate": "Validieren",
+  "Preview": "Vorschau",
+  "Refresh": "Aktualisieren",
+  "Run": "Ausführen",
+  "Save": "Speichern",
+  "Saving...": "Speichert...",
+  "Nodes": "Knoten",
+  "No pipeline selected": "Kein Datenfluss ausgewählt",
+  "New pipeline": "Neuer Datenfluss",
+  "Definition settings": "Definitionseinstellungen",
+  "Reuse as scoped copy": "Als eingegrenzte Kopie verwenden",
+  "Automation triggers": "Automatisierungsauslöser",
+  "Discard changes": "Änderungen verwerfen",
+  "Delete pipeline": "Datenfluss löschen",
+  "Constrained Dataflow SQL": "Eingeschränktes Datenfluss-SQL",
+  "Apply SQL": "SQL anwenden",
+  "Stage datasource": "Datenquelle bereitstellen",
+  "Run only": "Nur ausführen",
+  "Publish result": "Ergebnis veröffentlichen",
+  "Environment": "Umgebung",
+  "Development": "Entwicklung",
+  "Staging": "Staging",
+  "Production": "Produktion",
+  "Promote to staging": "Nach Staging übernehmen",
+  "Promote to production": "In Produktion übernehmen",
+  "Recent runs": "Letzte Ausführungen",
+  "Queue run": "Ausführung einreihen",
+  "New trigger": "Neuer Auslöser",
+  "Save trigger": "Auslöser speichern",
+  "Delete trigger": "Auslöser löschen",
+  "Delete automation trigger": "Automatisierungsauslöser löschen",
+  "Pipeline definition is read-only": "Datenflussdefinition ist schreibgeschützt",
+  "Working...": "Vorgang läuft..."
+};
+
+export const generatedTranslations: PlatformTranslations = { en, de };
@@ -4,6 +4,7 @@ import type {
  PlatformWebModule
 } from "@govoplan/core-webui";
 import DataflowPipelinesWidget from "./features/dataflow/DataflowPipelinesWidget";
+import { generatedTranslations } from "./i18n/generatedTranslations";
 import "@xyflow/react/dist/style.css";
 import "./styles/dataflow.css";

@@ -57,7 +58,7 @@ const dataflowDashboardWidgets: DashboardWidgetsUiCapability = {

 export const dataflowModule: PlatformWebModule = {
  id: "dataflow",
-  label: "Dataflow",
+  label: "i18n:govoplan-dataflow.dataflow",
  version: "0.1.14",
  optionalDependencies: [
    "access",
@@ -70,23 +71,94 @@ export const dataflowModule: PlatformWebModule = {
    "risk_compliance",
    "workflow"
  ],
+  translations: generatedTranslations,
  viewSurfaces: [
+    {
+      id: "dataflow.page",
+      moduleId: "dataflow",
+      kind: "route",
+      label: "i18n:govoplan-dataflow.dataflow",
+      order: 72
+    },
+    {
+      id: "dataflow.library",
+      moduleId: "dataflow",
+      kind: "section",
+      label: "i18n:govoplan-dataflow.library",
+      parentId: "dataflow.page",
+      order: 10
+    },
+    {
+      id: "dataflow.graph",
+      moduleId: "dataflow",
+      kind: "section",
+      label: "i18n:govoplan-dataflow.graph",
+      parentId: "dataflow.page",
+      order: 20
+    },
+    {
+      id: "dataflow.sql",
+      moduleId: "dataflow",
+      kind: "section",
+      label: "i18n:govoplan-dataflow.sql",
+      parentId: "dataflow.page",
+      order: 30
+    },
+    {
+      id: "dataflow.inspector",
+      moduleId: "dataflow",
+      kind: "section",
+      label: "i18n:govoplan-dataflow.inspector",
+      parentId: "dataflow.page",
+      order: 40
+    },
+    {
+      id: "dataflow.results",
+      moduleId: "dataflow",
+      kind: "section",
+      label: "i18n:govoplan-dataflow.results",
+      parentId: "dataflow.page",
+      order: 50
+    },
+    {
+      id: "dataflow.triggers",
+      moduleId: "dataflow",
+      kind: "action",
+      label: "i18n:govoplan-dataflow.triggers",
+      parentId: "dataflow.page",
+      order: 60
+    },
+    {
+      id: "dataflow.runs",
+      moduleId: "dataflow",
+      kind: "action",
+      label: "i18n:govoplan-dataflow.runs",
+      parentId: "dataflow.page",
+      order: 70
+    },
    {
      id: "dataflow.widget.pipelines",
      moduleId: "dataflow",
      kind: "section",
-      label: "Dataflows widget",
+      label: "i18n:govoplan-dataflow.widget",
      order: 70
    }
  ],
  navItems: [
-    { to: "/dataflow", label: "Dataflow", iconName: "waypoints", anyOf: readScopes, order: 72 }
+    {
+      to: "/dataflow",
+      label: "i18n:govoplan-dataflow.dataflow",
+      iconName: "waypoints",
+      anyOf: readScopes,
+      order: 72
+    }
  ],
  routes: [
    {
      path: "/dataflow",
      anyOf: readScopes,
      order: 72,
+      surfaceId: "dataflow.page",
      render: ({ settings, auth }) => createElement(DataflowPage, { settings, auth })
    }
  ],
@@ -290,6 +290,10 @@
  background: var(--bg);
 }

+.dataflow-action-guidance {
+  padding: 0 10px 8px;
+}
+
 .dataflow-workspace-toolbar {
  min-height: 58px;
  padding: 8px 10px;