Promote assembly content hub synchronization

.github/assembly-sync.json

@@ -0,0 +1,9 @@
+{
+  "version": 1,
+  "hubRepository": "researchanddesire/rad-app",
+  "hubPath": "apps/docs-ohai/content",
+  "spokeRepository": "researchanddesire/assembly-docs",
+  "spokePath": "content",
+  "product": null,
+  "hubCommit": "1b2e12f7bdef4b8d276ca5f5a015a55d3f347ee2"
+}

.github/workflows/sync-docs-ohai-content.yml

@@ -1,54 +1,51 @@
-name: Request RadApp Ohai Import
+name: Notify Assembly Content Hub
 
 on:
   push:
-    branches:
-      - main
-      - staging
+    branches: [staging, main]
     paths:
-      - "content/**"
-      - ".github/workflows/sync-docs-ohai-content.yml"
+      - content/**
+      - .github/assembly-sync.json
+      - .github/workflows/sync-docs-ohai-content.yml
   workflow_dispatch:
     inputs:
       branch:
-        description: Branch to synchronize
-        required: true
-        default: staging
+        description: Matching hub release track
         type: choice
-        options:
-          - staging
-          - main
+        options: [staging, main]
+        default: staging
 
 permissions:
   contents: read
 
 concurrency:
-  group: request-rad-app-ohai-import-${{ github.event_name == 'push' && github.ref_name || inputs.branch }}
+  group: assembly-hub-notification-${{ github.event_name == 'push' && github.ref_name || inputs.branch }}
   cancel-in-progress: false
 
 jobs:
-  request-import:
-    if: ${{ github.event_name == 'workflow_dispatch' || !contains(github.event.head_commit.message, '[docs-sync]') }}
+  notify:
     runs-on: ubuntu-latest
     timeout-minutes: 5
-    env:
-      SYNC_BRANCH: ${{ github.event_name == 'push' && github.ref_name || inputs.branch }}
     steps:
-      - name: Create documentation sync token
-        id: app-token
+      - name: Create token scoped to the hub
+        id: token
         uses: actions/create-github-app-token@v2
         with:
           app-id: ${{ vars.RAD_VERSION_CONTROL_APP_ID }}
           private-key: ${{ secrets.RAD_VERSION_CONTROL_PRIVATE_KEY }}
           owner: researchanddesire
           repositories: rad-app
-
-      - name: Request matching RadApp import
+      - name: Wake hub reconciliation
+        uses: actions/github-script@v7
         env:
-          GH_TOKEN: ${{ steps.app-token.outputs.token }}
-        run: |
-          gh workflow run import-docs-content.yml \
-            --repo researchanddesire/rad-app \
-            --ref "$SYNC_BRANCH" \
-            --field site=assembly \
-            --field branch="$SYNC_BRANCH"
+          SYNC_BRANCH: ${{ github.event_name == 'push' && github.ref_name || inputs.branch }}
+        with:
+          github-token: ${{ steps.token.outputs.token }}
+          script: |
+            const branch = process.env.SYNC_BRANCH;
+            if (!['staging', 'main'].includes(branch)) throw new Error('Invalid release track');
+            await github.rest.repos.createDispatchEvent({
+              owner: 'researchanddesire', repo: 'rad-app',
+              event_type: 'assembly-content-changed',
+              client_payload: { repository: `${context.repo.owner}/${context.repo.repo}`, branch }
+            });

AGENTS.md

@@ -1,5 +1,25 @@
 # AGENTS.md
 
+## Current Fumadocs synchronization contract
+
+`rad-app` is the hub. This repository's `content/**` is the complete, bidirectional
+mirror of `rad-app/apps/docs-ohai/content/**`, including all locales and assets.
+English product pages use `.en.mdx` and English product metadata `meta.en.json`.
+Edit content here and open a PR into `staging`; the notifier wakes the hub after
+merge. The hub reconciles changes and opens reviewed sync PRs before propagating
+to the four English-only hardware spokes. Never sync directly to hardware repos.
+
+`.github/assembly-sync.json` is the hub-managed baseline, outside mirrored
+content. Do not hand-edit it. Preserve `_bom/` CSV, provenance and generated JSON
+together. Workflow authentication uses `RAD_VERSION_CONTROL_APP_ID` and
+`RAD_VERSION_CONTROL_PRIVATE_KEY`, scoped to rad-app for notifications.
+
+Both persistent branches must exist. Normal edits synchronize staging to staging;
+main is audited and updated through reviewed staging-to-main promotion. No
+direct writes or automatic merges into release branches. The legacy MkDocs
+instructions below describe historical tooling only and do not govern the
+active Fumadocs content tree. Do not regenerate content from that tooling.
+
 Guidance for future agents working in the `assembly-docs` aggregator repo,
 especially on BOM rendering.
 

README.md

@@ -2,7 +2,27 @@
 
 This repository is the public, editable content mirror for [R+D Assembly](https://ohai.researchanddesire.com). Rendered page titles and section headings link to their exact source lines under `content/docs/`.
 
-Public contributions should target `main`. The dedicated synchronization app mirrors approved content into the private Fumadocs renderer; legacy MkDocs assembly tooling remains below for migration and product-source workflows.
+Public contributions should target `staging`. `rad-app` is the synchronization
+hub: this repository's entire `content/` tree mirrors
+`rad-app/apps/docs-ohai/content/`, including every language and asset. English
+product pages use `.en.mdx`; navigation uses `meta.en.json`. The hub strips `.en`
+only when exporting to the four English-only hardware repositories.
+
+Merging content changes sends an `assembly-content-changed` notification to
+rad-app. The hub detects concurrent edits against `.github/assembly-sync.json`,
+opens a draft import PR, and propagates to affected hardware spokes after that
+PR merges. Do not hand-edit the checkpoint. Routine sync targets staging;
+main follows reviewed staging-to-main releases. No direct spoke-to-spoke writes.
+
+The notifier needs the organization's existing `RAD_VERSION_CONTROL_APP_ID`
+variable and `RAD_VERSION_CONTROL_PRIVATE_KEY` secret with access to rad-app.
+Initial seeding is a separate reviewed action in the hub; it does not overwrite
+content merely because this notifier is installed.
+
+## Historical MkDocs tooling (not the active synchronization pipeline)
+
+The remaining sections document legacy tooling retained for reference. Do not
+use it to regenerate the active `content/` tree or dispatch directly to hardware.
 
 Aggregates each hardware product's `assembly-docs/` folder into a single
 MkDocs Material site, following the same architecture as

content/docs/dtt/_bom/bom.csv

@@ -0,0 +1,10 @@
+#,Part Name,Category,Description,Qty,UOM,Manufacturer,MFG PN,Vendor,Vendor PN,Source,Notes
+1,DTT PCB assembly,PCA,Rev4 printed circuit board assembly,1,each,–,–,–,–,pcb/diptrace-rev4/pcb-bom-full.csv,PCB child BOM is maintained separately
+2,DTT loop velcro,FBO,Loop-side hook-and-loop strip used on the PCB,1,each,–,–,–,–,–,Used on the PCB during assembly
+3,3D printed DTT housing,FDM,Printed trainer housing,1,each,–,–,–,–,cad/README.md,Clean interior filament strands before assembly
+4,OLED screen,ASM,Display module,1,each,–,–,–,–,–,Remove film before installation
+5,Sensor,IC,Position sensor module,1,each,–,–,–,–,–,Install flush with casing
+6,Battery,BTY,Lithium battery,1,each,–,–,–,–,–,Install writing-side down
+7,Cable harness,CHA,Screen sensor battery and PCB cable harness,1,each,–,–,–,–,–,Connects screen sensor battery and PCB
+8,0408LTFB screws,FST,PCB mounting screws,4,each,–,0408LTFB,–,–,–,Used to fasten the PCB to the trainer case
+9,Hot glue,ADH,Assembly adhesive,1,application,–,–,–,–,–,Used to secure screen sensor and battery

content/docs/dtt/_bom/bom.json

@@ -0,0 +1,146 @@
+{
+  "repo": "DT_Trainer-OSS",
+  "commit": "f3233e34e4ebc4cc4b50b1d2d63acc2dd4fd6df9",
+  "columns": [
+    "#",
+    "Part Name",
+    "Category",
+    "Description",
+    "Qty",
+    "UOM",
+    "Manufacturer",
+    "MFG PN",
+    "Vendor",
+    "Vendor PN",
+    "Source",
+    "Notes"
+  ],
+  "rows": [
+    [
+      "1",
+      "DTT PCB assembly",
+      "PCA",
+      "Rev4 printed circuit board assembly",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "pcb/diptrace-rev4/pcb-bom-full.csv",
+      "PCB child BOM is maintained separately"
+    ],
+    [
+      "2",
+      "DTT loop velcro",
+      "FBO",
+      "Loop-side hook-and-loop strip used on the PCB",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "–",
+      "Used on the PCB during assembly"
+    ],
+    [
+      "3",
+      "3D printed DTT housing",
+      "FDM",
+      "Printed trainer housing",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "cad/README.md",
+      "Clean interior filament strands before assembly"
+    ],
+    [
+      "4",
+      "OLED screen",
+      "ASM",
+      "Display module",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "–",
+      "Remove film before installation"
+    ],
+    [
+      "5",
+      "Sensor",
+      "IC",
+      "Position sensor module",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "–",
+      "Install flush with casing"
+    ],
+    [
+      "6",
+      "Battery",
+      "BTY",
+      "Lithium battery",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "–",
+      "Install writing-side down"
+    ],
+    [
+      "7",
+      "Cable harness",
+      "CHA",
+      "Screen sensor battery and PCB cable harness",
+      "1",
+      "each",
+      "–",
+      "–",
+      "–",
+      "–",
+      "–",
+      "Connects screen sensor battery and PCB"
+    ],
+    [
+      "8",
+      "0408LTFB screws",
+      "FST",
+      "PCB mounting screws",
+      "4",
+      "each",
+      "–",
+      "0408LTFB",
+      "–",
+      "–",
+      "–",
+      "Used to fasten the PCB to the trainer case"
+    ],
+    [
+      "9",
+      "Hot glue",
+      "ADH",
+      "Assembly adhesive",
+      "1",
+      "application",
+      "–",
+      "–",
+      "–",
+      "–",
+      "–",
+      "Used to secure screen sensor and battery"
+    ]
+  ]
+}

content/docs/dtt/_bom/source.json

@@ -0,0 +1,4 @@
+{
+  "repo": "DT_Trainer-OSS",
+  "commit": "f3233e34e4ebc4cc4b50b1d2d63acc2dd4fd6df9"
+}