fix: docker-app check, error messages, and docs that did not work as written

[dabelle]

The rest of the pre-launch sweep: the docker-app check, the error messages a new user actually hits, and every documented command that did not work as written.

docker-app has never worked

Two stacked bugs, in v0.1.0 and v0.1.1 both.

nat.NewPort takes the protocol first, then the port. The call passed them the other way round, so "tcp" was parsed as a port number and the check died before the container was created. git log -S shows the line unchanged since the original docker sandbox commit.

With that fixed, a second bug surfaced: MappedPort inspected once immediately after start, but the daemon fills NetworkSettings.Ports asynchronously, so the binding is reliably absent for the first few hundred milliseconds. It now polls to a deadline, and reports a container that exited before publishing as exactly that, instead of "port is not published" sending people to look at networking when the real problem was an app dying on the restored data.

This shipped because dockerapp_test.go asserts against a fake ContainerRunner, verifying the spec the check builds while never executing the code that consumes it, and no e2e covered docker-app at all. run-docker.sh now boots a real nginx against restored data and asserts both a pass and a readiness failure, and asserts the failure is never "not published" so the race cannot come back silently. Confirmed non-vacuous: with the pre-fix docker.go restored, case 3 fails and the suite never reaches case 4.

Error messages

The human result went to stderr, so restorable test > result.txt captured nothing while --json captured everything. docs/commands.md promises the opposite.

Database failures discarded the reason. psql prints the cause first then echoes the statement with a caret under it, so keeping the last two lines kept the caret and dropped the explanation:

before: count rows in "assets": LINE 1: SELECT count(*) FROM "assets" / ^
after:  count rows in "assets": ERROR:  relation "assets" does not exist /
        LINE 1: SELECT count(*) FROM "assets"

The redaction added in #4 still strips the LINE segment before transport, so the reason travels and the row data does not.

A wrong password is the most common first-run mistake and it printed restic's raw JSON with the one useful sentence buried inside. It now reads Fatal: wrong password or no key found. A missing agent.yaml now names restorable init instead of only reporting that a file is absent.

Documentation that did not work

Every command in the quickstart is now runnable verbatim. Three were not.

The cron line used RESTIC_PASSWORD_FILE, which the agent has never supported, so step 4 failed every time, into a log file nobody reads. That is the silent-watcher failure this product exists to announce. It also used 2>&1 alongside --json, so the results file was never parseable; the streams are now separated.

restic ls latest was offered as the way to discover paths to assert, at the moment a user is least sure what to write, but nothing in the quickstart sets RESTIC_REPOSITORY. Step 5 said to register against https://<dashboard> without the URL appearing anywhere in the repo.

recipes/immich.yaml could not pass for anyone. Immich names dumps immich-db-backup-20250729T114018-v1.136.0-pg14.17.sql.gz, so the literal immich-db-backup-latest.sql.gz can never exist, and the asserted tables were renamed to singular upstream. Verified against Immich's source: the schema declares @Table('user') and @Table('asset'). Since recipes take literal paths with no globbing, the postgres check is commented out with the shell line that gives the dump a stable name.

README and agent-configuration.md listed six read-only subcommands; the closed type has seven. SECURITY.md already said seven, so the repo contradicted itself on the one claim a security-minded reader will diff against the source.

alerts.md attributed the hourly cron to vercel.json, which schedules the daily backstop. Billing docs advertised enforced limits while the live site gives everything away during the beta, so repo readers were seeing the worse offer.

Verification

Full Go suite, -race, golangci-lint clean. run.sh, run-docker.sh (now four cases) and run-s3.sh all pass. The corrected cron line and restic ls were run verbatim.