Install from release zip; fix Passport migration collision

Two root causes made the composer-based update produce a broken install:

- composer create-project ships source only, without the compiled frontend
  bundles (public/v1/js/app.js etc.), leaving the UI broken (no graphs, 404s).
  Switch to downloading and extracting the official GitHub release zip, which
  is prebuilt. Normalize the version so both "6.6.5" and "v6.6.5" resolve to
  the correct v-prefixed release asset.

- Laravel Passport renames its migration files between versions, so a
  carried-over DB has the oauth_* tables while the new filenames look pending,
  and migrate aborts trying to recreate existing tables. Reconcile the
  migrations ledger before migrate: record already-present tables, let missing
  ones be created.

Also add an ERR trap so a failed run names the failing line and cannot
masquerade as success (a silent mid-run failure left a half-built dir that
looked done), a dependency check (curl/unzip/php), and mkdir guards for the
storage carry-over. Document all of it in README.md and CLAUDE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

1 files changed, 24 insertions, 9 deletions

diff --git a/README.md b/README.md
index 49ab6ef..caf5f8f 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,17 @@
 
 Update a [Firefly III](https://www.firefly-iii.org/) instance on Debian.
 
-Installs the latest (or a pinned) release via Composer, carries over your
-`.env`, uploads, exports, and SQLite database, runs the migrations and
-upgrade steps, then swaps the new version in and restarts Apache. A
-timestamped database backup is taken before anything is touched, and
-`--restore` rolls back to the previous version.
+Downloads the latest (or a pinned) release, carries over your `.env`, uploads,
+exports, and SQLite database, runs the migrations and upgrade steps, then swaps
+the new version in and restarts Apache. A timestamped database backup is taken
+before anything is touched, and `--restore` rolls back to the previous version.
+
+Installs from the **official GitHub release zip**, not `composer
+create-project`. The composer/Packagist dist ships source only and lacks the
+compiled frontend bundles, which leaves the UI broken (no graphs, 404s on
+`/v1/js/app.js`). The release zip is prebuilt.
+
+Requires `curl`, `unzip`, `php`, and `sqlite3` on the host.
 
 ## Usage
 
@@ -14,7 +20,7 @@ Run as root (it chowns files and restarts Apache):
 
 ```bash
 sudo ./firefly-update              # update to latest release
-sudo ./firefly-update -v 6.1.0     # update to a specific tag
+sudo ./firefly-update -v 6.6.5     # update to a specific tag (v-prefix optional)
 sudo ./firefly-update --restore    # roll back to the previous version
 sudo ./firefly-update --help
 ```
@@ -36,9 +42,18 @@ WORKDIR=/srv INSTANCE=ff sudo -E ./firefly-update
 ## Notes
 
 - Assumes an SQLite database at `storage/database/database.sqlite`.
-- `set -euo pipefail`: any failed step aborts before the live instance is
-  swapped, so a broken build never replaces a working one.
-- The previous version is kept at `$INSTANCE-old` until the next run.
+- `set -euo pipefail` plus an `ERR` trap: any failed step aborts before the
+  live instance is swapped (a broken build never replaces a working one) and
+  prints the failing line, so a partial run cannot masquerade as success.
+- Before migrating, the script reconciles Laravel Passport's OAuth migrations:
+  Passport renames its migration files between versions, so a carried-over DB
+  has the `oauth_*` tables while the new filenames look pending, and a naive
+  `migrate` would fail trying to recreate existing tables. The script records
+  those already-present tables as migrated and lets genuinely-missing ones be
+  created.
+- The previous version is kept at `$INSTANCE-old` until the next run;
+  `--restore` swaps it back and overlays the newest DB backup. A failed restore
+  leaves the broken version at `$INSTANCE-broken`.
 
 ## License