Document development builds; Expo Go no longer runs this app

[Jberma23]

What this does

Rewrites mobile/README.md for development builds. The README still described the old workflow — install Expo Go, npm start, scan a QR code — which with useSQLCipher set is instructions for something that cannot work, aimed at exactly the newcomers 0008 designed a gentle first ticket for.

The constraint now leads rather than being buried, because it decides whether someone can work on this at all: a new "This app does not run in Expo Go" section up front, saying that SQLCipher is compiled in at build time, that the first build is slow, and that Xcode or Android Studio is now a prerequisite rather than an optional extra. Setup is npm install → npx expo prebuild → npx expo run:ios / run:android, with the day-to-day loop after that separated out so nobody thinks they rebuild every morning. Prerequisites say which toolchain each platform needs and that iOS has no path without a Mac.

Two other things the encrypted database made untrue:

• npm run web is documented as the landing surface only. Per 0017 the journal refuses to open in a browser rather than quietly writing an unencrypted medical journal into browser storage, so any screen reading the journal throws there by design. Someone who runs it and sees the landing page render would reasonably conclude the opposite.
• Demoing to non-technical people no longer works through Expo Go. 0016 flagged it and nothing in the docs said so; there is now a short section giving the two remaining options.

Smaller corrections while in there: src/lib/db/ and src/lib/auth/ added to the project structure, which was silently missing the largest new directory; and the tests section now says that tests need no native build, that two suites want Node 22.5, and that a green suite does not prove the file is encrypted.

Issue

Closes #129

Testing

• Covered by tests — n/a, docs only

No code changed, so nothing to unit test. What I did check:

• Every remaining mention of Expo Go is either the heading saying it does not work or an explanation of why — no instruction anywhere still tells you to use it, and the QR-code step is gone.
• All four ../docs/decisions/*.md links resolve against the files on this branch.
• Code fences balance (16).
• The commands are accurate for this branch: expo-dev-client is not a dependency, so npx expo run:ios / run:android is the correct path rather than anything requiring it, and /ios + /android are gitignored, matching 0016's "generated rather than committed".

The acceptance criterion I cannot verify is the one that matters most: that a contributor with a clean checkout can follow this start to finish and reach a running app. That needs macOS + Xcode and an Android Studio machine, neither of which I have. #129's QA checklist covers it and someone should walk it before this merges.

Notes for review

• Targeted at feature/encrypted-storage-unlock-foundation, not main. 0016 asks for this to land with or close behind Add encrypted storage and biometric unlock foundation #128, and on main today useSQLCipher is not set — so merged to main first, this README would describe a requirement that does not exist yet. Targeting Paul's branch keeps Add encrypted storage and biometric unlock foundation #128 self-consistent: the PR that breaks Expo Go also fixes the docs describing Expo Go.
• One forward reference. The tests section says the two node:sqlite suites currently error rather than skip on Node below 22.5, and links jest node:sqlite guard never runs — two suites fail instead of skipping on Node < 22.5 #133. That is true on this branch; jest node:sqlite guard never runs — two suites fail instead of skipping on Node < 22.5 #133 is fixed in Address #128 review: unopenable journals, repository binding, and the node:sqlite guard #138, and the sentence should be trimmed to "they skip" whenever that lands. Flagging it rather than pre-writing a claim that is not true yet.
• The first-build time estimate ("often ten to twenty minutes") is a guess from typical RN + SQLCipher builds. Worth someone replacing it with a real number once they have run it.

[Jberma23]

Added a second commit: Running on a physical iPhone, plus a warning about the prebuild bundle-identifier prompt.

The README got someone as far as a simulator and stopped, which for this app is not far enough. The 0015 unlock path cannot be checked in a simulator at all — simulators do not enforce biometric authentication when retrieving a stored secret, which expo-secure-store documents — and nothing in the test suite shows the database is encrypted, since node:sqlite is stock SQLite. A green simulator run and a green test run together still leave both of the things this foundation exists for unverified. The new section says which those are.

It also states plainly that a free Apple ID is enough — no push, no app groups, no associated domains, so nothing here needs a paid account. Worth writing down, because assuming otherwise is what quietly stops a volunteer from testing on the phone already in their pocket. Then signing, trusting the certificate, going wireless after the first cable build, the seven-day expiry, and expo-dev-client for when the Mac keeps changing address.

One thing that belongs in #128, not here

app.json sets neither ios.bundleIdentifier nor android.package, so npx expo prebuild stops and prompts for them — and writes whatever you answer into app.json as the app's permanent App Store identity.

That is a decision, not a prompt to click through at the end of a long setup. I have documented it defensively ("do not invent one, ask first"), but the real fix is setting it deliberately — something like org.rubyforgood.alongwithyou — in app.json on #128, at which point the warning here can come out. Flagging rather than doing it, since it is the kind of value that is annoying to change later.

Checked again after the edit: 18 code fences balanced, all five ADR links resolve, dash style normalised to match the rest of the file.

[PaulgSmith]

npx expo start picks its launch target from that dependency too, so plain npm start targets Expo Go and pressing i/a opens Expo Go, not the build you installed. run:ios forces --dev-client itself, so the first build is fine; it's the next morning that misfires.

Intentional, or worth changing the daily loop to npx expo start --dev-client? Same question for npm run ios / npm run android under Other command.

[Jberma23]

npx expo start picks its launch target from that dependency too, so plain npm start targets Expo Go and pressing i/a opens Expo Go, not the build you installed. run:ios forces --dev-client itself, so the first build is fine; it's the next morning that misfires.

Intentional, or worth changing the daily loop to npx expo start --dev-client? Same question for npm run ios / npm run android under Other command.

Not intentional — good catch. start now passes --dev-client, ios/android are now run:ios/run:android, and the READMEs explain the flag. Worth knowing the misfire was silent: Expo Go loads this app fine and stock SQLite ignores PRAGMA key, so it'd write the journal unencrypted with no error.