Keep a site's own files when its container is replaced

`db_data` was a volume and the instance directory was not, so the documented
update path - `docker compose build api && up -d api` - recreated the container
and discarded everything the site had written. `plugins.json` is only the loud
part: maps, branding, model and application images, employee photos, warranty
proofs, slides, printed-part files and the Dell OAuth token all live under
instance_path too. MySQL rows survive and point at files that are gone, so the
second symptom is images 404ing rather than an error anybody sees.

Reported by an adopting site, which read it as having updated too fast. It had
not; nothing it could have done differently would have kept those files.

DEPLOY.md had been telling sites to back up `instance/` since it was written.
The template never gave them anything to back up.

The air-gap `migrate` service mounts the volume too, because
`flask plugin upgrade-all` rewrites plugins.json and that service exits
immediately after.

The image now creates instance/ ITSELF, owned by the app user. Docker seeds an
empty named volume from image content at the mountpoint, ownership included;
with no such directory in the image the mountpoint is created root-owned 0755
and the container, which runs as shopdb, cannot write into its own instance
directory. Caught by running the built image rather than by reading it: the
volume mounted clean and `touch` came back Permission denied. Verified fixed the
same way.

A stack that predates the volume needs its files moved across ONCE, while the
old container still exists - the volume is seeded from image content, and the
image ships instance/ empty, so it comes up empty rather than inheriting the old
container's writable layer. DEPLOY.md carries the procedure, including the chown
after `docker compose cp`, which writes files under the copying user's numeric
uid rather than the app user's.

Also here, found while checking what an upgrade actually runs: the connected
update steps ran `flask db upgrade` and stopped. Per-plugin Alembic chains
(ADR-008) are not part of that, so a connected site taking an image with a
bumped plugin migration ran the core chain and silently skipped every plugin
chain. The air-gap stack had it right all along. Both commands are in Step 9
now, plus a `db current` check against `db heads`.

docs/DEPLOY.md

@@ -187,7 +187,13 @@ docker compose exec -T db mysqldump -u root -p"${MYSQL_ROOT_PASSWORD}" shopdb_fl
 
 Verify a restore quarterly. Back up the `instance/` directory alongside the DB;
 it holds uploaded floor plans, branding, `plugins.json`, and tokens that are not
-in MySQL. See [docs/BACKUP-RESTORE.md](BACKUP-RESTORE.md) for the full backup and
+in MySQL. Under compose it is the `instance_data` named volume:
+
+```bash
+docker compose run --rm -v "$PWD:/backup" api tar czf /backup/instance-$(date +%F).tar.gz -C /app/instance .
+```
+
+See [docs/BACKUP-RESTORE.md](BACKUP-RESTORE.md) for the full backup and
 restore procedure.
 
 ## Step 9: Updates
@@ -197,8 +203,53 @@ git pull origin main
 docker compose build api
 docker compose up -d api
 docker compose exec api flask db upgrade
+docker compose exec api flask plugin upgrade-all
+docker compose exec api flask db current   # must match `flask db heads`
 ```
 
+`plugin upgrade-all` runs the per-plugin Alembic chains (ADR-008), which
+`db upgrade` does NOT touch. The air-gap stack runs both in its one-shot
+`migrate` service; a connected stack has to ask.
+
+`up -d api` REPLACES the container. Everything the site has written lives in the
+`instance_data` volume for exactly this reason: the enabled-plugin list
+(`plugins.json`), uploaded floor plans and branding, model and application
+images, employee photos, warranty proofs, slides, printed-part files, and the
+Dell OAuth token. If your stack predates that volume, those files are in the old
+container's writable layer and an update discards them. Move them across ONCE,
+before the next rebuild:
+
+```bash
+docker compose cp api:/app/instance ./instance-rescued   # BEFORE pulling new code
+docker compose up -d api                                 # creates the volume
+docker compose cp ./instance-rescued/. api:/app/instance
+docker compose exec -u root api chown -R shopdb:shopdb /app/instance
+docker compose restart api
+```
+
+The `chown` is not optional. `docker compose cp` writes the files with the
+copying user's numeric uid, which is only `shopdb` by coincidence if your host
+account happens to be uid 1000. Get it wrong and the site reads its restored
+files fine and cannot write new ones.
+
+Then run the migrations and confirm the plugins came back:
+
+```bash
+docker compose exec api flask db upgrade
+docker compose exec api flask plugin upgrade-all
+docker compose exec api flask db current   # must match `flask db heads`
+docker compose exec api flask plugin list  # the site's plugins, enabled
+```
+
+Restore `instance/` BEFORE `plugin upgrade-all`: that command works from
+`plugins.json`, so running it against an empty instance directory upgrades
+nothing and reports success.
+
+The symptom of having missed this is a site that comes back with its plugins
+disabled and image URLs that 404: the MySQL rows survived, the files did not.
+Re-enabling by hand works, but `flask plugin apply-profile <profile.json>` puts
+the same list back in one command and is the thing to keep in version control.
+
 The framework's `__contract_version__` may have moved. Check `docs/adr/` for any new ADRs since the last update. If an ADR introduces a breaking change, the upgrade may require coordinated work; the ADR's "Consequences" section documents it. See [docs/UPGRADE.md](UPGRADE.md) for the full upgrade procedure, including re-seeding and the v0.5+ floor-plan note.
 
 ## Common issues