feat: crucible wrapper sync (#3)

Reviewed-on: #3
Co-authored-by: vickydotbat <vickydotbat@tutamail.com>
Co-committed-by: vickydotbat <vickydotbat@tutamail.com>

.gitea/workflows/sync-wrappers.yml

@@ -0,0 +1,50 @@
+# Auto-PR canonical wrapper updates to consumer repos when wrappers/ changes on
+# main. Maintenance automation (not artifact publishing), so it is allowed on a
+# main push under the D7 trigger standard. Requires WRAPPER_SYNC_TOKEN: a bot
+# user's token with content+PR write to the consumer repos (never committed).
+name: sync-wrappers
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'wrappers/crucible.sh'
+      - 'wrappers/crucible.ps1'
+
+jobs:
+  sync:
+    runs-on: nix-docker
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Open sync PRs to consumers
+        env:
+          TOKEN: ${{ secrets.WRAPPER_SYNC_TOKEN }}
+          SERVER: ${{ github.server_url }}
+          SRC_SHA: ${{ github.sha }}
+        run: |
+          nix develop --command bash -c '
+            set -euo pipefail
+            host="$(echo "$SERVER" | sed -E "s#https?://##")"
+            branch="chore/sync-wrappers-$(echo "$SRC_SHA" | cut -c1-12)"
+            grep -vE "^\s*#|^\s*$" wrappers/consumers.txt | while read -r target; do
+              echo "== syncing $target =="
+              work="$(mktemp -d)"
+              git clone "https://oauth2:${TOKEN}@${host}/${target}.git" "$work"
+              cp wrappers/crucible.sh wrappers/crucible.ps1 "$work"/
+              ( cd "$work"
+                git config user.name  "crucible-sync-bot"
+                git config user.email "bot@westgate.pw"
+                if git diff --quiet; then echo "no changes for $target"; exit 0; fi
+                git checkout -b "$branch"
+                git add crucible.sh crucible.ps1
+                git commit -m "chore: sync crucible wrappers from sow-tools@${SRC_SHA}"
+                git push -f origin "$branch"
+                curl -fsS -X POST \
+                  -H "Authorization: token ${TOKEN}" -H "Content-Type: application/json" \
+                  "${SERVER}/api/v1/repos/${target}/pulls" \
+                  -d "{\"head\":\"${branch}\",\"base\":\"main\",\"title\":\"chore: sync crucible wrappers from sow-tools\"}" || true
+              )
+              rm -rf "$work"
+            done
+          '

README.md

@@ -41,6 +41,30 @@ See [`docs/migration-from-nwn-tool.md`](docs/migration-from-nwn-tool.md) for wha
 was done and what remains (the consumer `--manifest/--source/--out` flag contract
 is the open Phase-6 item).
 
+## Quick start (no Nix)
+
+Teammates without Nix don't build anything — they run the bootstrap wrapper,
+which downloads the latest released `crucible` for your OS and runs it:
+
+```bash
+./crucible            # interactive menu (pick a command)
+./crucible module build
+./crucible topdata validate-topdata
+```
+
+Windows (PowerShell):
+
+```powershell
+.\crucible.ps1 module build
+```
+
+The binary is cached under `~/.cache/crucible/<version>/` (`%LOCALAPPDATA%\crucible`
+on Windows); `--repo-local` caches inside the repo instead. Private releases:
+set `CRUCIBLE_TOKEN` or write the token to `~/.config/crucible/token`.
+
+Only the **music** builder needs `ffmpeg`; everything else has zero dependencies.
+If you run a music command without it, Crucible prints a per-OS install hint.
+
 ## Develop
 
 Self-contained (D8) — a host with only Nix can run everything:
@@ -58,12 +82,18 @@ This retires the old habit of checking in `nwn-tool` / `sow-toolkit`.
 
 ## CI
 
-PR-first (D7): every check runs on pull requests and on push to `main`.
+PR-first (D7): checks run on pull requests and on push to `main`; the only
+publish event is a `v*` tag (see `sow-docs/runbooks/ci-trigger-standard.md`).
 
-- `test.yml` — vet, test, shellcheck, yamllint, binary smoke.
+- `test.yml` — vet, test, shellcheck, yamllint, binary smoke (PR + main).
-- `build-image.yml` — build `registry.westgate.pw/deployment/crucible:<sha>`; publish
+- `test-image.yml` — build the OCI image to prove it compiles (PR + main, no push).
-  only on `main`. PRs build but never push. No mutable tags.
+- `build-binaries.yml` — cross-build all targets (PR + main); on a `v*` tag, upload
-- `release.yml` — tag-gated binary bundles; image re-tag is wired in Phase 6.
+  the binaries, `SHA256SUMS`, and the wrappers to the Gitea release.
+- `build-image.yml` — on a `v*` tag, build and publish
+  `registry.westgate.pw/deployment/crucible:<sha>`.
+- `publish-image.yml` — manual `workflow_dispatch` break-glass republish.
+- `sync-wrappers.yml` — on a `main` push that touches `wrappers/`, auto-PR the
+  canonical wrappers to the consumer repos in `wrappers/consumers.txt`.
 
 ## Consumers
 

wrappers/consumers.txt

@@ -0,0 +1,5 @@
+# Repos that carry copies of the canonical Crucible wrappers.
+# One "owner/repo" per line. sync-wrappers.yml opens an update PR to each when
+# wrappers/ changes. Add a repo here AND grant the sync bot write access to it.
+ShadowsOverWestgate/sow-module
+ShadowsOverWestgate/sow-topdata