From 65609665a289dea6b49c4c885d4262d86f7018ab Mon Sep 17 00:00:00 2001
From: Albrecht Degering <albrecht@degering.name>
Date: Mon, 24 Aug 2026 11:36:36 +0200
Subject: [PATCH] feat(connectors): document consequential governance actions

---
 pyproject.toml                                 | 2 +-
 src/govoplan_connectors/backend/manifest.py    | 6 +++++-
 webui/package.json                             | 2 +-
 webui/src/features/ConnectorGovernancePage.tsx | 8 ++++----
 webui/src/features/ExternalKnowledgePage.tsx   | 4 ++--
 5 files changed, 13 insertions(+), 9 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 88e532b..8c4e549 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-connectors"
-version = "0.1.24"
+version = "0.1.25"
 description = "Governed connector catalogue and tabular source capabilities for GovOPlaN."
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/src/govoplan_connectors/backend/manifest.py b/src/govoplan_connectors/backend/manifest.py
index 7e19e02..14d73f2 100644
--- a/src/govoplan_connectors/backend/manifest.py
+++ b/src/govoplan_connectors/backend/manifest.py
@@ -126,7 +126,7 @@ from govoplan_connectors.backend.german_documentation import (
 
 
 MODULE_ID = "connectors"
-MODULE_VERSION = "0.1.24"
+MODULE_VERSION = "0.1.25"
 TABULAR_SOURCE_INTERFACE_VERSION = "0.1.0"
 DATASOURCE_ORIGIN_INTERFACE_VERSION = "0.1.0"
 SANCTIONS_SNAPSHOT_INTERFACE_VERSION = "1.0.0"
@@ -1053,6 +1053,10 @@ manifest = ModuleManifest(
             order=39,
             metadata={
                 "kind": "reference",
+                "help_contexts": [
+                    "connectors.action.reject-ambiguous-result",
+                    "connectors.action.approve-ambiguous-result",
+                ],
                 "fields": [
                     "Direction and technical maturity",
                     "Configured source authority",
diff --git a/webui/package.json b/webui/package.json
index 8f675e7..475110b 100644
--- a/webui/package.json
+++ b/webui/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/connectors-webui",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "private": true,
   "type": "module",
   "main": "src/index.ts",
diff --git a/webui/src/features/ConnectorGovernancePage.tsx b/webui/src/features/ConnectorGovernancePage.tsx
index c4427c2..a7b626f 100644
--- a/webui/src/features/ConnectorGovernancePage.tsx
+++ b/webui/src/features/ConnectorGovernancePage.tsx
@@ -483,7 +483,7 @@ export default function ConnectorGovernancePage({ settings, auth }: Props) {
             <FormField label="Endpoint URL" hint="Credentials are rejected in URLs.">
               <input value={draft.endpoint_url} disabled={!canAdmin || busy} placeholder="https://provider.example/api" onChange={(event) => setDraft({ ...draft, endpoint_url: event.target.value })} />
             </FormField>
-            <FormField label="Credential reference" hint="Reference an approved secret; do not paste a secret.">
+            <FormField label="Credential reference" hint="Reference an approved secret; do not paste a secret." helpContextId="connectors.admin.governed-configurations" helpModuleId="connectors">
               <input value={draft.credential_ref} disabled={!canAdmin || busy} placeholder="vault://connectors/provider" onChange={(event) => setDraft({ ...draft, credential_ref: event.target.value })} />
             </FormField>
             <FormField label="Ambiguous-result policy">
@@ -574,7 +574,7 @@ export default function ConnectorGovernancePage({ settings, auth }: Props) {
         <FormField label="Endpoint URL">
           <input value={newDraft.endpoint_url} disabled={busy} onChange={(event) => setNewDraft({ ...newDraft, endpoint_url: event.target.value })} />
         </FormField>
-        <FormField label="Credential reference">
+        <FormField label="Credential reference" helpContextId="connectors.admin.governed-configurations" helpModuleId="connectors">
           <input value={newDraft.credential_ref} disabled={busy} onChange={(event) => setNewDraft({ ...newDraft, credential_ref: event.target.value })} />
         </FormField>
         <FormField label="Ambiguous-result policy">
@@ -597,8 +597,8 @@ export default function ConnectorGovernancePage({ settings, auth }: Props) {
       closeDisabled={busy}
       footer={<>
         <Button onClick={() => setReviewRun(null)} disabled={busy}>Cancel</Button>
-        <Button variant="danger" onClick={() => void decideReview("rejected")} disabled={busy || reviewReason.trim().length < 5}>Reject</Button>
-        <Button variant="primary" onClick={() => void decideReview("approved")} disabled={busy || reviewReason.trim().length < 5}>Approve</Button>
+        <Button variant="danger" helpContextId="connectors.action.reject-ambiguous-result" helpModuleId="connectors" onClick={() => void decideReview("rejected")} disabled={busy || reviewReason.trim().length < 5}>Reject</Button>
+        <Button variant="primary" helpContextId="connectors.action.approve-ambiguous-result" helpModuleId="connectors" onClick={() => void decideReview("approved")} disabled={busy || reviewReason.trim().length < 5}>Approve</Button>
       </>}
     >
       <p>Review {reviewRun?.summary.ambiguous ?? 0} ambiguous effects against the retained input and configuration hashes before deciding.</p>
diff --git a/webui/src/features/ExternalKnowledgePage.tsx b/webui/src/features/ExternalKnowledgePage.tsx
index 3c10ada..4d772fc 100644
--- a/webui/src/features/ExternalKnowledgePage.tsx
+++ b/webui/src/features/ExternalKnowledgePage.tsx
@@ -326,7 +326,7 @@ export default function ExternalKnowledgePage({ settings, auth }: Props) {
       <Button variant="secondary" onClick={() => void sync(false)} disabled={!selected || !canSync || busy || dirty}>Run delta</Button>
       <Button variant="secondary" onClick={() => void sync(true)} disabled={!selected || !canSync || busy || dirty}>Run full backfill</Button>
       <Button variant="secondary" onClick={() => setMigrationOpen(true)} disabled={!selected || !canMigrate || busy || dirty}>Preview migration</Button>
-      <Button variant="primary" onClick={() => setPublishOpen(true)} disabled={!selected || !canPublish || busy || dirty}>Publish page</Button>
+      <Button variant="primary" helpContextId="connectors.admin.external-knowledge" helpModuleId="connectors" onClick={() => setPublishOpen(true)} disabled={!selected || !canPublish || busy || dirty}>Publish page</Button>
     </>}
     discardAction={{
       label: "Discard changes",
@@ -501,7 +501,7 @@ export default function ExternalKnowledgePage({ settings, auth }: Props) {
 
     <Dialog open={publishOpen} title="Publish provider page revision" onClose={() => !busy && setPublishOpen(false)} closeDisabled={busy} footer={<>
       <Button onClick={() => setPublishOpen(false)} disabled={busy}>Cancel</Button>
-      <Button variant="primary" onClick={() => void publish()} disabled={busy || !externalPageId.trim() || !publishTitle.trim()}>Publish revision</Button>
+      <Button variant="primary" helpContextId="connectors.admin.external-knowledge" helpModuleId="connectors" onClick={() => void publish()} disabled={busy || !externalPageId.trim() || !publishTitle.trim()}>Publish revision</Button>
     </>}>
       <p className="muted">Publication is an external effect. Supply the current provider revision where possible; an unknown outcome blocks blind retry.</p>
       <FormGrid columns={2} collapseAt="standard" className="">