---
name: bonesaw-ship
description: Ship accumulated Bonesaw work to the live realm and to players - build, warn, save, replace worldserver, import SQL, publish the client, tag, and post Discord notes. Only ever invoked by the user typing /bonesaw-ship.
disable-model-invocation: true
---

# Ship Bonesaw

## Stop unless the user asked for this

This is the only skill allowed to touch the live realm.

`disable-model-invocation: true` in the frontmatter enforces that under Claude
Code, but **it is not honoured by every runtime** - Pi, for one, reads the same
SKILL.md and ignores that key, which means the model can reach this file on its
own. So the guarantee has to live in the instructions too:

**Before Phase 0, confirm the user actually asked to ship in their most recent
message** - `/bonesaw-ship`, "ship it", "deploy", "push it live". If they did
not, say so and stop. Do not ship because the work looks finished, because the
status output says there are unshipped commits, or because a previous message
said to ship something earlier in the session. Authorisation is per-ship and
does not carry forward.

Work through the phases in order and **stop at the first failure** - do not
carry on to a later phase to "get most of it out".

Announce which phase you are entering as you go, so an interrupted ship can be
resumed from a known point.

## Phase 0 - preflight

```
python tools/bonesaw_status.py
```

- Working tree must be clean. If it is not, commit first (do not stash - the
  stash stack is shared with other worktrees).
- Show the user the unshipped commit list. That list *is* the patch notes
  source; do not invent items that are not in it.
- If `UNSHIPPED` is empty and the server is not behind, there is nothing to
  ship. Say so and stop.

### Glance at the disk (not every ship - roughly monthly)

Phase 1 builds an image every single ship, and WSL2 virtual disks only ever
grow. Nothing shrinks `docker_data.vhdx` on its own, so it creeps until C: is
full and a build fails for reasons that look nothing like disk space.

```
powershell -NoProfile -Command "'{0:N1} GB free on C:' -f ((Get-PSDrive C).Free/1GB); '{0:N1} GB vhdx' -f ((Get-Item $env:LOCALAPPDATA'\Docker\wsl\disk\docker_data.vhdx').Length/1GB)"
```

This is a look, not a gate - **never block a ship on it**, and do not compact
mid-ship. If C: is under ~40 GB free, or the vhdx is far larger than
`docker system df` says Docker is actually holding, mention it to the user and
move on. It is its own maintenance job, done between ships.

When they want it done, the sequence is a realm restart plus a compaction, so
it follows the same warn/save rules as Phase 2:

```
docker builder prune -f                      # build cache; check `docker system df` first
tools/save_world.ps1                          # or restart_worldserver.ps1 if humans are on
docker compose down                           # NEVER with -v: that deletes wow-bonesaw_ac-database
wsl --shutdown                                # quit Docker Desktop first or it restarts WSL
# then, elevated: diskpart /s <script> with
#   select vdisk file="...\docker_data.vhdx" / attach vdisk readonly / compact vdisk / detach vdisk
docker compose up -d
```

On 2026-09-01 that vhdx had reached 171 GB while holding ~35 GB of data;
compaction returned 133 GB. Also worth a glance:
`%LOCALAPPDATA%\Temp\wsl-crashes` had 43 GB of worldserver dumps, nine of them
in three days - they accumulate on their own after every crash and nothing
cleans them up.

Decide the version: bump the patch number in `tools/client-update/Bonesaw.version`.
**Never skip a number**, including for server-only ships - the launcher and the
Discord thread both key off it.

## Phase 1 - build before anything live moves

```
docker compose build ac-worldserver ac-db-import
```

**Both images. This is not optional and it is the bug that keeps recurring.**
`ac-db-import` bakes `data/sql/updates/pending_db_*` *into the image* - there is
no bind mount. Rebuilding only `ac-worldserver` means every new migration is
silently skipped forever: on 2026-08-22 `rev_living_gear_account_keys.sql` had
been sitting unapplied since 08-21 because of exactly this, so the account key
ring was dead while its code read perfectly.

If the build fails, **stop here**. Nothing live has been touched yet, which is
the entire reason the build comes first. Fix the compile error and restart the
ship.

## Phase 2 - warn and save

Skip entirely if `ac-worldserver` is not running.

**First, count REAL players online.** The countdown exists to stop players
taking a rollback; with nobody to roll back, five minutes of announcements to an
empty realm is just five minutes. Playerbots do not count - they have no
progress a restart can cost them.

```
docker compose exec -T ac-database mysql -uroot -ppassword -N -e "SELECT COUNT(*) FROM acore_characters.characters c JOIN acore_auth.account a ON a.id = c.account WHERE c.online = 1 AND a.username NOT LIKE 'RNDBOT%';"
```

Bot accounts are all named `RNDBOT*` (144 of 147 accounts at the time of
writing), so excluding them is what makes this count mean "humans". Do NOT use
the worldserver console's `server info` for this - its "Connected players"
includes bots, so it reads non-zero on an empty realm.

**If that count is 0:** save and restart immediately, no announcements.

```
powershell -NoProfile -ExecutionPolicy Bypass -File tools/save_world.ps1
```

**On the Linux host, use `python3 tools/save_world.py` instead.** There is no
PowerShell there, and the `.ps1`'s documented fallback `tools/worldserver_cli.py`
is Windows-only too (it opens the Docker named pipe through `ctypes.WinDLL`), so
with SOAP disabled the entire warn/save path is unavailable and the ship silently
has no way to save at all. `save_world.py` attaches to the console on a pty and
leaves with ctrl-p ctrl-q. Do not replace it with a pipe into `docker attach`:
stdin goes straight to the worldserver console and EOF halts the server.

Note that port 7878 answering a TCP connect does NOT mean SOAP is up -- docker
proxy binds the host side regardless. Check `SOAP.Enabled` in
`env/dist/etc/worldserver.conf`.

The save still runs. It costs about three seconds and it is not a warning - it
protects world and bot state, and a stale `online` flag left by an earlier crash
is the one case where this count could be wrong in the dangerous direction. If
it is wrong the other way (a human logs in during the restart) they get a clean
reconnect, not a rollback.

**If that count is greater than 0:** the full countdown, no shortcuts.

```
powershell -NoProfile -ExecutionPolicy Bypass -File tools/restart_worldserver.ps1
```

**There is no Linux port of the countdown.** If humans are on and you are on the
Linux host, drive it by hand with the same helper -- `python3 tools/save_world.py
--command "announce <text>" --expect ""` for each step of the 5/2/1/0:30/0:10
ladder, then a final plain `python3 tools/save_world.py` for the saveall. Do not
skip the ladder because the tool is missing.

Announces in game on a staged countdown (5 minutes, then 2, 1, 30s, 10s), then
`saveall`. **Wait for its final line**, `OK: players warned ... and saved;
restart is allowed`. An exit code of 0 is not the same thing: on 2026-08-23 that
script was killed partway, exited 0, and had never reached the saveall - the
missing final line was the only evidence. Never use AzerothCore
`server shutdown` for a docker replace - it races `saveall` on its own timer.

Run it in the background rather than in the foreground, or a tool timeout will
kill it mid-countdown, which is exactly how that happened.

## Phase 3 - replace the server

```
docker compose up -d ac-db-import
docker compose up -d ac-worldserver
```

db-import first and let it complete; worldserver depends on it. Then confirm
the module actually loaded and no migration errored:

```
docker logs --tail 200 ac-worldserver | grep -iE "living gear|error|Applying"
```

Re-run `python tools/bonesaw_status.py` - `pending SQL` must now read
`all imported`. If it does not, the db-import image did not pick the file up;
go back to Phase 1.

## Phases 4-6, automated

The bookkeeping after the container replace (client publish, manifest, patch
notes, Discord, release notes, tag, push) is mechanical and was the recurring
source of forgotten steps - 0.1.79/0.1.80 shipped with no Discord post, and the
live manifest went stale twice in the 0.1.105/0.1.106 era. One command runs
the whole tail in the right order, refuses to continue on any failed step, and
tags LAST so `git log --first-parent ship/<latest>..HEAD` is empty when it exits:

```
python tools/ship_bookkeeping.py --version X.Y.Z --notes-only           # then --post
python tools/ship_bookkeeping.py --version X.Y.Z --no-client --notes-only
python tools/ship_bookkeeping.py --version X.Y.Z --no-client --post
```

Run stage 1 (`--notes-only`) **after Phase 3's `bonesaw_status` says
`pending SQL: all imported`**. It bumps the version (exactly one patch),
builds the client if any, writes `tools/patch-notes/X.Y.Z.md` and **stops -
nothing has been posted**. The script's bullets are raw commit subjects and
only a human pass makes them read as notes, so the pass is now mandatory and
happens between the stages: edit the notes file (player-facing bullets, retest
asks for THIS ship's own changes first, no code names or file paths), then run
stage 2 (`--post`), which re-runs the retest check, prints the notes it is
about to publish, and only then posts to Discord, updates the GitHub release,
commits the notes, tags LAST and pushes. One set of notes goes out - the
reviewed one. The phases below document what the script does; use them as the
manual fallback when the script cannot run.

Push **only** to origin `Raajik/wotlk-bonesaw`, never to the `playerbots`
remote. Never force-push `main`.

## Phase 4 - client, if client files changed (manual fallback)

Needed when anything under `modules/mod-living-gear/client_addon/`,
`tools/client-patch/` or `tools/launcher/` changed since the last ship:

```
git diff --stat ship/<previous>..HEAD -- modules/mod-living-gear/client_addon tools/client-patch tools/launcher
```

If it is empty, skip to Phase 5 - a server-only ship still bumps the version
and still gets Discord notes.

Otherwise follow `tools/client-update/README.md` under "Ship to all players".
That file is the source of truth for these steps; do not reproduce them from
memory. The order that matters: build the launcher, create the GitHub release,
then `--verify`, then push the manifest. The exe is not byte-reproducible, so
rebuilding between hashing and uploading strands every player.

Push **only** to origin `Raajik/wotlk-bonesaw`, never to the `playerbots`
remote. Never force-push `main`.

## Phase 5 - record the ship (tag LAST)

```
git commit -am "Ship Bonesaw X.Y.Z: <one line>"
git tag ship/X.Y.Z
```

The tag is what makes the next `/bonesaw-status` able to say what players have.
Without it the whole thing goes blind again. **Tag after the notes commit, not
before** - a tag chased by manifest/notes commits leaves `--first-parent ship/<latest>..HEAD`
non-empty forever and every later status reads "N commits not shipped"
(0.1.104/0.1.105/0.1.106 all needed a tag re-point for exactly this).

## Phase 6 - tell people

This phase used to read "Post to Discord" with nothing to run, so it was done by
hand or not at all - **0.1.79 and 0.1.80 both shipped without the notes ever
reaching players**, and the GitHub releases carried the placeholder "Run
Bonesaw.exe." instead of a changelog. Writing notes into the chat reply is not
the same as posting them. Do all three steps below.

### 1. Write the notes to a file

```
tools/patch-notes/X.Y.Z.md
```

Built from the Phase 0 commit list, following
`.cursor/rules/discord-patch-notes.mdc`: player-facing only, ASCII, plain `-`
bullets, grouped by theme, no file paths or spell IDs, only what actually
shipped. Extra jump is disabled - do not advertise it. Title line is
`**Bonesaw X.Y.Z - patch notes**`. If the client changed, end with *Close Wow
and run Bonesaw.exe to update.*

**Every notes file ends with a "Please test these things" section**, placed
just before the update line. Fixes that shipped but were never confirmed
otherwise silently age out on the tracker, and players are the only test
environment that counts. Source it live at notes-writing time, never from a
stale list. GitHub is the canonical tracker and `status:awaiting-retest` is
its queue of shipped-but-unconfirmed work (in-game `lg_bug_report` rows reach
that label via `tools/bug-reports/bug_resolve.py` after the sweep):

```
python tools/retest_list.py --raw
```

- First 1-4 asks about THIS ship's own changes that only a player can verify
  ("craft something that needs banked materials - does anything land in your
  bags?"). Pass them as `-a "..."` to `tools/retest_list.py` for a paste-ready
  section, then rephrase anything that still reads like a bug title.
- Then the longest-waiting open `status:awaiting-retest` issues, so stale items
  get the spotlight instead of aging out. Drop the `[Report #N]` prefix -
  players cannot see the tracker, so issue numbers never appear in notes.
- One short ask per item ("Try X, tell us if Y still happens"). Roughly 8
  bullets max so the notes stay one Discord message where possible.
- If nothing is genuinely awaiting retest, omit the section. Never re-list an
  issue that already got a confirmed retest and was closed - the tool only
  lists open ones, but check before hand-adding anything.
- `python tools/retest_list.py --check tools/patch-notes/X.Y.Z.md` fails the
  ship if the section is missing or a `[Report #N]` leaked through.

The file is the record: it is what gets posted, what the GitHub release shows,
and what the next person reads to see what a version contained. Commit it.

### 2. Post to Discord

```
python tools/post_patch_notes.py tools/patch-notes/X.Y.Z.md --dry-run
python tools/post_patch_notes.py tools/patch-notes/X.Y.Z.md
```

Dry-run first - it checks the notes are ASCII and previews the title-line body
plus the attachment before contacting anyone. Posting is attachment-only: the
body is just the title line and the full notes ride as a .txt attachment, so
the 2000-character message limit never splits or truncates anything. The
webhook lives in
`tools/client-update/discord.webhook`, which is gitignored because it is a
credential; never echo it into a log or a commit.

The script exits non-zero if Discord rejects anything, so a failed post stops
the ship rather than being reported as done.

### 3. Put the same notes on the GitHub release

```
gh release edit vX.Y.Z --repo Raajik/wotlk-bonesaw --notes-file tools/patch-notes/X.Y.Z.md
```

Phase 4 creates the release with a placeholder because the notes may not exist
yet at that point. This is where it gets the real changelog, so the release list
is a readable history rather than a wall of identical one-liners.

### 4. Record the learnings

Append durable learnings to `A:\obsidian\jeremy\wiki\Bonesaw.md` - crashes, UI
rules, deploy gotchas, spell IDs, do-not-repeat mistakes. Part of shipping, not
after it.

Same file from the Linux host: `/run/media/muckfup/aba/obsidian/jeremy/wiki/Bonesaw.md`.
It is CRLF -- write it back as CRLF or the whole page shows as modified.

## Finally

Re-run `python tools/bonesaw_status.py`. It should exit 0 with
"Everything committed, built, imported and published." If it does not, say
exactly what is still outstanding rather than calling the ship done.

Also confirm the notes end with the test section:
`python tools/retest_list.py --check tools/patch-notes/X.Y.Z.md`