From 95defaf9d7ebd980705d62983987b1316d7382cb Mon Sep 17 00:00:00 2001
From: Joshua Temple <joshua.temple@stablekernel.com>
Date: Fri, 12 Jun 2026 20:58:42 -0400
Subject: [PATCH] docs: add cross-repo external artifact tracking diagram

Signed-off-by: Joshua Temple <joshua.temple@stablekernel.com>
---
 README.md                             | 35 +++++++++++++++++++++++++++
 docs/src/content/docs/architecture.md | 27 +++++++++++++++++++++
 2 files changed, 62 insertions(+)

diff --git a/README.md b/README.md
index 3bc04e5d..95a817e7 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,41 @@ flowchart TD
 
 ---
 
+## Cross-repo artifact tracking
+
+A primary repo can own the environment chain for artifacts that are built and versioned in other repos. Each external repo dispatches the primary's generated `external-update.yaml`, which writes `{sha, version}` into `state.<env>.external.<name>` of the one shared manifest; concurrent updates serialize on that manifest, then the primary cascades every source through its own environments. A callback can also pull in an external repo's workflow synchronously via `uses:` during the primary's run.
+
+```mermaid
+%%{init: {'theme':'base','themeVariables':{'fontFamily':'ui-sans-serif, system-ui, sans-serif','primaryColor':'#0E8B82','primaryBorderColor':'#36D0C4','primaryTextColor':'#F4FBFA','lineColor':'#1F9B92','clusterBkg':'transparent','clusterBorder':'#36D0C4','tertiaryColor':'#B87333'}}}%%
+flowchart TD
+    subgraph EXT["External artifact repos"]
+        direction LR
+        A["<b>artifact-a</b><br/>builds its own artifact"]
+        B["<b>artifact-b</b><br/>builds its own artifact"]
+    end
+
+    A -- "workflow_dispatch<br/>source_repo · deploy_name · environment<br/>sha · version · artifacts" --> EU
+    B -- "workflow_dispatch<br/>source_repo · deploy_name · environment<br/>sha · version · artifacts" --> EU
+
+    subgraph PRIMARY["Primary repo"]
+        direction TB
+        EU["<b>external-update.yaml</b><br/>cascade external update"]
+        EU -- "writes {sha, version}" --> ST["<b>.github/manifest.yaml</b><br/>state.&lt;env&gt;.external.&lt;name&gt;<br/>concurrent updates serialize"]
+        ST --> PR
+        subgraph PR["Promote (cascade through environments)"]
+            direction LR
+            dev["dev"] --> test["test"] --> staging["staging"] --> prod["prod"]
+        end
+    end
+
+    CB["Primary build / deploy callback"] -. "sync uses:<br/>org/artifact-repo/.github/workflows/&lt;name&gt;.yaml@ref" .-> SYNC["External workflow<br/>invoked inline"]
+
+    classDef accent fill:#B87333,stroke:#E8702A,color:#FFF7F0;
+    class ST accent;
+```
+
+---
+
 ## Quick start
 
 ### 1. Install the CLI
diff --git a/docs/src/content/docs/architecture.md b/docs/src/content/docs/architecture.md
index 16e7c19a..f37beeae 100644
--- a/docs/src/content/docs/architecture.md
+++ b/docs/src/content/docs/architecture.md
@@ -493,6 +493,33 @@ flowchart BT
 3. **Primary updates state**: Records external deploy SHA/version in manifest
 4. **Promotion includes all**: When promoting, primary triggers all deploys (local + external)
 
+The topology above shows which repos talk to which. The flow below shows what actually moves between them: each external repo dispatches the primary's `external-update.yaml` with a payload, the primary serializes those writes into the one shared manifest, then cascades every source through its environments.
+
+```mermaid
+flowchart TD
+    subgraph EXT["External artifact repos"]
+        direction LR
+        A["<b>artifact-a</b><br/>builds its own artifact"]
+        B["<b>artifact-b</b><br/>builds its own artifact"]
+    end
+
+    A -- "workflow_dispatch<br/>source_repo · deploy_name · environment<br/>sha · version · artifacts" --> EU
+    B -- "workflow_dispatch<br/>source_repo · deploy_name · environment<br/>sha · version · artifacts" --> EU
+
+    subgraph PRIMARY["Primary repo"]
+        direction TB
+        EU["<b>external-update.yaml</b><br/>cascade external update"]
+        EU -- "writes {sha, version}" --> ST["<b>.github/manifest.yaml</b><br/>state.&lt;env&gt;.external.&lt;name&gt;<br/>concurrent updates serialize"]
+        ST --> PR
+        subgraph PR["Promote (cascade through environments)"]
+            direction LR
+            dev["dev"] --> test["test"] --> staging["staging"] --> prod["prod"]
+        end
+    end
+
+    CB["Primary build / deploy callback"] -. "sync uses:<br/>org/artifact-repo/.github/workflows/&lt;name&gt;.yaml@ref" .-> SYNC["External workflow<br/>invoked inline"]
+```
+
 ### State Tracking
 
 Primary manifest tracks external deploys alongside local deploys: