From 27e133f69286ad3860f9d91a6677d40de5eb4cfc Mon Sep 17 00:00:00 2001 From: Copilot Date: Wed, 3 Jun 2026 12:02:03 -0500 Subject: [PATCH] docs(scrape): sync KotOR wrapper across GUI bridge docs (plan 084) GUI bridge and troubleshooting lead with run-kotor-yes-general-catchup.sh; merge-readiness HEAD updated; bridge sync smoke asserts wrapper and 24/24 gate. --- .docs/Recurring-Scrape-Troubleshooting.md | 13 ++--- docs/gui-zip-recurring-scrape-bridge.md | 18 ++++--- ...04-084-docs-kotor-wrapper-doc-sync-plan.md | 51 +++++++++++++++++++ docs/recurring-scrape-merge-readiness.md | 4 +- scripts/tests/sync-gui-bridge-doc-smoke.sh | 2 + 5 files changed, 71 insertions(+), 17 deletions(-) create mode 100644 docs/plans/2026-06-04-084-docs-kotor-wrapper-doc-sync-plan.md diff --git a/.docs/Recurring-Scrape-Troubleshooting.md b/.docs/Recurring-Scrape-Troubleshooting.md index 63b97865..48b20639 100644 --- a/.docs/Recurring-Scrape-Troubleshooting.md +++ b/.docs/Recurring-Scrape-Troubleshooting.md @@ -324,18 +324,15 @@ Not this: ./scripts/operator-handoff.sh --salvage-only --target KotOR_discord_msgs --channel 221726893064454144 ``` -2. **Raise container memory** in `scrape.env` (default `0` = no compose cap): +2. **Raise container memory** in `scrape.env` if needed (default `0` = no compose cap; `KotOR_discord_msgs` already sets `container_memory: "8g"` for single-target runs): ```bash - # scrape.env + # scrape.env — optional global override DCE_CONTAINER_MEMORY=8g ``` - Then run a channel-scoped catch-up: + Then run the one-command catch-up: ```bash - DCE_MIN_FREE_MB=0 ./scripts/run-operator-validation.sh \ - --salvage-before-scrape \ - --target KotOR_discord_msgs \ - --channel 221726893064454144 \ - --log-file logs/kotor-yes-general.log + ./scripts/run-kotor-yes-general-catchup.sh + # Inspect totals: ./scripts/print-scrape-summary.sh logs/kotor-yes-general.summary.json ``` 3. **Ensure only one scrape** holds `{archive_root}/.dce-scrape.lock` (see next section). diff --git a/docs/gui-zip-recurring-scrape-bridge.md b/docs/gui-zip-recurring-scrape-bridge.md index dd6a0a8a..fc482964 100644 --- a/docs/gui-zip-recurring-scrape-bridge.md +++ b/docs/gui-zip-recurring-scrape-bridge.md @@ -43,13 +43,15 @@ After stopping a long run, merge quiescent partial exports before re-downloading # Merge partial temps only (no Discord) ./scripts/operator-handoff.sh --salvage-only --target KotOR_discord_msgs --channel 221726893064454144 -# Salvage then incremental catch-up (with audit + log) -# For large yes_general catch-up, set DCE_CONTAINER_MEMORY=8g in scrape.env first. -DCE_MIN_FREE_MB=0 ./scripts/run-operator-validation.sh \ - --salvage-before-scrape \ - --target KotOR_discord_msgs \ - --channel 221726893064454144 \ - --log-file logs/kotor-yes-general-$(date -u +%Y%m%d-%H%M%S).log +# Salvage then incremental catch-up (one command; 8g cap via scrape-targets.json for KotOR) +./scripts/run-kotor-yes-general-catchup.sh +# Or: --dry-run | --salvage-only | --validation | --prove +# Inspect: ./scripts/print-scrape-summary.sh logs/kotor-yes-general.summary.json + +# Manual equivalent (validation with audit): +# DCE_MIN_FREE_MB=0 ./scripts/run-operator-validation.sh \ +# --salvage-before-scrape --target KotOR_discord_msgs \ +# --channel 221726893064454144 --log-file logs/kotor-yes-general.log ``` Or direct documents scrape: @@ -67,7 +69,7 @@ Archives: `config/scrape-targets.json` (typically `~/Documents/*` per target `ou **Disk:** Free several GiB on `/home` and archive roots before large scrapes (`DCE_MIN_FREE_MB`, default 1024). -**Validate scripts:** `DCE_MIN_FREE_MB=0 ./scripts/run-all-smokes.sh` (21 offline smokes) +**Validate scripts:** `DCE_MIN_FREE_MB=0 ./scripts/run-all-smokes.sh` (**24/24** offline smokes; `--include-container` optional) **Podman (Fedora):** install `podman-compose` when `docker compose` cannot reach the socket; scripts auto-prefer it. diff --git a/docs/plans/2026-06-04-084-docs-kotor-wrapper-doc-sync-plan.md b/docs/plans/2026-06-04-084-docs-kotor-wrapper-doc-sync-plan.md new file mode 100644 index 00000000..1a4cb77a --- /dev/null +++ b/docs/plans/2026-06-04-084-docs-kotor-wrapper-doc-sync-plan.md @@ -0,0 +1,51 @@ +--- +title: "docs: sync KotOR wrapper across GUI bridge and merge-readiness" +type: docs +status: complete +date: 2026-06-04 +origin: /lfg — plan 083 landed wrapper; GUI bridge and merge-readiness header still stale +--- + +# docs: sync KotOR wrapper across GUI bridge and merge-readiness + +## Summary + +Update `docs/gui-zip-recurring-scrape-bridge.md`, `.docs/Recurring-Scrape-Troubleshooting.md`, and `docs/recurring-scrape-merge-readiness.md` so operators and GUI-zip users see `run-kotor-yes-general-catchup.sh` as the primary yes_general path and **24/24** smoke gate everywhere. + +## Problem Frame + +Plan 083 added the KotOR catch-up wrapper and updated setup/checklist docs. The GUI bridge doc still documents long manual validation commands and claims **21** offline smokes. Merge-readiness branch HEAD stamp still references `18a22a6` instead of current `7171d7b`. + +## Requirements + +| ID | Requirement | +|----|-------------| +| R1 | GUI bridge yes_general section leads with `./scripts/run-kotor-yes-general-catchup.sh` | +| R2 | GUI bridge smoke line reads **24/24** (optional `--include-container`) | +| R3 | Troubleshooting OOM section cites wrapper + `print-scrape-summary.sh` | +| R4 | Merge-readiness table HEAD → `7171d7b` (or post-commit SHA) | +| R5 | `sync-gui-bridge-doc-smoke.sh` asserts dest mentions wrapper | +| R6 | `DCE_MIN_FREE_MB=0 ./scripts/run-all-smokes.sh` → 24/24 | + +## Implementation Units + +### U1. Doc updates + +**Files:** `docs/gui-zip-recurring-scrape-bridge.md`, `.docs/Recurring-Scrape-Troubleshooting.md`, `docs/recurring-scrape-merge-readiness.md` + +### U2. Bridge sync smoke + +**Files:** `scripts/tests/sync-gui-bridge-doc-smoke.sh` + +## Verification + +```bash +DCE_MIN_FREE_MB=0 ./scripts/run-all-smokes.sh +``` + +## Scope Boundaries + +### Deferred + +- Live KotOR catch-up on operator host +- PR #1538 body refresh (already at plans 070–083) diff --git a/docs/recurring-scrape-merge-readiness.md b/docs/recurring-scrape-merge-readiness.md index bd2d92e9..49f3c382 100644 --- a/docs/recurring-scrape-merge-readiness.md +++ b/docs/recurring-scrape-merge-readiness.md @@ -5,7 +5,7 @@ | Gate | Status | |------|--------| | Offline smokes (`run-all-smokes.sh`) | 24/24 pass | -| Branch HEAD (fork) | `18a22a6` — PR #1538 pruned stale Latest blocks (plan 082) | +| Branch HEAD (fork) | `7171d7b` — KotOR yes_general catch-up wrapper (plan 083) | | Live proof (`run-operator-proof.sh --sync-gui --target eod_discord`) | Passed on maintainer host | | Monthly cron (`setup-cron.sh`) | Installed (`00 04 1 * *`); dry-run preflight OK for all enabled targets | | Upstream CI (fork PR) | `action_required` until Tyrrrz approves workflow runs | @@ -204,6 +204,8 @@ DCE_MIN_FREE_MB=0 ./scripts/run-operator-validation.sh \ **Plan 083 (2026-06-04):** `run-kotor-yes-general-catchup.sh` — one-command yes_general path (salvage-before, log, summary hint). +**Plan 084 (2026-06-04):** GUI bridge + troubleshooting cite KotOR wrapper; merge-readiness HEAD synced; bridge sync smoke asserts wrapper + 24/24. + **Disk:** ~65 GiB free on `/home` (2026-05-30); large channel merges still need headroom. ## CI note (fork PRs) diff --git a/scripts/tests/sync-gui-bridge-doc-smoke.sh b/scripts/tests/sync-gui-bridge-doc-smoke.sh index ed7d702a..2743e142 100755 --- a/scripts/tests/sync-gui-bridge-doc-smoke.sh +++ b/scripts/tests/sync-gui-bridge-doc-smoke.sh @@ -17,5 +17,7 @@ mkdir -p "$TMP_DIR/gui-zip" "$SYNC" --dest "$DEST" [[ -f "$DEST" ]] || { printf 'ERROR: dest missing\n' >&2; exit 1; } grep -q 'operator-handoff' "$DEST" || { printf 'ERROR: dest content unexpected\n' >&2; exit 1; } +grep -q 'run-kotor-yes-general-catchup' "$DEST" || { printf 'ERROR: dest missing KotOR wrapper\n' >&2; exit 1; } +grep -q '24/24' "$DEST" || { printf 'ERROR: dest missing 24/24 smoke count\n' >&2; exit 1; } printf 'sync-gui-bridge-doc-smoke: ok\n'