pneumo

M5: Document deployment and add screenshots (ENG-273) #38

Open

demi.dev 1w ago

targeting main from stoopkidddd/eng-273-m5-one-click-railway-template-and-the-readme

Open opened by and assigned to

demi.dev 1w ago targeting main from stoopkidddd/eng-273-m5-one-click-railway-template-and-the-readme

Linear: https://linear.app/engineereddev/issue/ENG-273

README part of ENG-273, by omp (commit 57a4341). The Railway template part is the lead's and is in progress.

README.md:
- Hero (lockup and og-image), features, and web and Android screenshots in light and dark.
- Deploy on Railway (3-step setup) and "Run anywhere" (docker run), with the §12.3 env table and S3 provider notes.
- Android install (APK, fingerprint, pairing, why the permanent notification and battery exemption exist), the §6.11 security model in plain words, and reset.
- Development, and a note that Tangled is the source and GitHub a read-only mirror.
CONTRIBUTING.md: short.
docs/screenshots/: 8 PNGs, 444 KB. The Android ones are copies of the committed Roborazzi baselines, not re-recorded.

Known pending: README.md:47 links https://railway.com/deploy/TEMPLATE_CODE. The lead replaces it in a later round, once the template exists and its throwaway test deploy passes. This PR merges only after that.

Verify (lead, in the worktree): mise run check:infra exit 0 (hadolint, shellcheck, compose, all 4 workflow files valid).

Verify (omp):

The documented docker run against local MinIO: /api/health returned {"ok":true,"version":"0.1.0","initialized":false}.
Browser setup, a note and Devices worked. The documented reset deleted 4 objects.
mise run e2e:web: 42 passed.

🤖 Generated with Claude Code

Commits 2

M5: Fix README hero themes and local deployment (ENG-273)

+26 -14

M5: Document deployment and add screenshots (ENG-273)

+353 -9

Comments

v0 1w ago

demi.dev 1w ago

Review round 1 (pneumo-reviewer): REQUEST_CHANGES #

Summary: The README half of ENG-273 is accurate. Every env var name and default matches apps/server/src/config.ts and SPEC §12.3. The documented docker run and CLI reset work on a locally built image. The fingerprint matches docs/RELEASING.md. The Android screenshots are byte-identical to the Roborazzi baselines. Two cheap FIX items remain. TEMPLATE_CODE was not reviewed; the lead fills it in later.

FIX (score ≥ 5):

README.md:2, often 6 × bad 1 = 6. The hero brand/lockup.svg uses fill="currentColor". As an <img> that resolves to black, so on GitHub's or Tangled's dark theme the lockup is black on near-black and almost invisible. Fix: use <picture> with a dark-scheme source and a fixed-colour variant, or drop the separate lockup.
README.md:196, often 2 × bad 3 = 6. On Linux, --add-host=host.docker.internal:host-gateway cannot reach the dev MinIO, because Compose publishes it only on 127.0.0.1:9000. The server fails with only "Server failed to start" and keeps restarting. Fix: --network host with S3_ENDPOINT=http://127.0.0.1:9000, or join the Compose network with S3_ENDPOINT=http://minio:9000, or point to docker compose --profile server up --build.

FILE (score < 5, tracked in Linear, code left alone): 3. Reset is documented only for Docker. There is no Railway route (railway ssh / one-off command, §12.5) and no "stop first" step there (2 × 2 = 4). 4. "Release tags omit the leading v" should say image tags (2 × 1 = 2). 5. The image tag 0.1.0-rc.1 is pinned in two places, and nothing in the release process bumps it (3 × 1 = 3). 6. docker logs shows setup links from earlier boots. Only the newest works (2 × 1 = 2). 7. apksigner prints the fingerprint as lowercase without colons, while the README shows uppercase with colons (1 × 1 = 1). 8. The security model doesn't advise a strong passphrase, although meta/owner.json allows offline guessing (1 × 3 = 3).

Spec check: §16.6, §16.7, §6.11, §12.3 OK. §12.5 OK for Docker; the Railway route is FILE 3.

DoD check:

hadolint, shellcheck and the 4 workflow files: clean and valid.
docker build: succeeds.
Prod health checks: they belong to the template half (lead).
No secrets. Only placeholders and the documented fake dev values.

Tests run by the reviewer:

check:infra and docker build: pass.
README rehearsal on OrbStack: /api/health 200, then dev-client smoke all PASS (auth, pair/claim, note, link, 2 MB file, push_deleted, revoke 4401).
Reset: refuses without --yes; with --yes it deleted 3 objects and the instance returned to uninitialized.

v1 1w ago

demi.dev 1w ago

Review round 2 (pneumo-reviewer): APPROVE (README half) #

Summary: Round v1 (f4abb34) fixes both FIX findings and changes nothing else. brand/ and the contract are untouched. The README's TEMPLATE_CODE placeholder is still the lead's open item.

Earlier FIX findings:

Hero lockup invisible on dark themes: RESOLVED. README.md:1-6 is a <picture> with docs/images/lockup-dark.svg (#F4F6FA) and lockup-light.svg (#151922). Both use the brand text tokens and the same geometry as brand/lockup.svg. Rendered in both schemes, both read clearly.
Linux host-gateway rehearsal: RESOLVED. The rehearsal now uses the Compose server profile, which reaches minio:9000 by service name on any platform. The README's description matches docker-compose.yml.

New findings: none. The FILE items (ENG-501..506) are unchanged in the code, as required.

Spec check: §16.6 OK (except the placeholder). §16.7, §6.11, §12.3 OK. §12.5 OK for Docker.

DoD check: check:infra exit 0, 4/4 workflows valid. The Compose --build built the Dockerfile. No secrets.

Tests run by the reviewer:

docker compose --profile server up --build -d --wait: exit 0, server Healthy. /api/health returned {"ok":true,"version":"0.1.0","initialized":false}.
down/up/curl repeated 3 times: no startup race.
dev-client smoke against the Compose rehearsal: all PASS (auth, pair/claim, note, link, 2 MB file, push_deleted, revoke 4401).

Versions

Review round 1 (pneumo-reviewer): REQUEST_CHANGES #

Review round 2 (pneumo-reviewer): APPROVE (README half) #