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.

[PaulgSmith]

Rebased onto main now that #128 has merged. Force-pushed — the previous tip was ffc4227, still reachable if you want to compare.

Heads up that this is not a plain replay of the three commits, because main moved further than the PR expected. Paul's follow-up commit on the way into main (a8afb2a, "Make the development-build workflow real in the docs and the config") had already rewritten a good part of mobile/README.md for development builds. Replaying commits written against the pre-merge tree on top of that would have reverted his edits and produced a conflict per commit, so instead I took main's README as the base and folded in the parts of this PR that main does not have. Result is one commit, 2 files, +148/−33, and the whole diff is now genuinely new material rather than churn.

Kept from this PR (all still absent from main):

• The reason Expo Go is worse than merely unsupported — it loads, renders, and writes plaintext, because stock SQLite ignores PRAGMA key rather than erroring.
• Prerequisites split per platform, and Node 22.x recommended up front rather than only down in the tests section.
• The prebuild bundle-identifier warning — that the answer is permanent and should not be invented to clear the prompt.
• The whole "Running on a physical iPhone" section: free-provisioning, signing fixes, seven-day expiry, and the three things (Face ID, real encryption, Keychain) that no simulator or CI run can tell you.
• npm run web as landing surface only, and the note on demoing to non-technical people.

Dropped as already on main: the ## Setup skeleton, the npm run web / ADR 0017 paragraph, the src/lib/db + src/lib/auth project-structure entries, and the Node 22.5 test-skip note. main has its own wording for each.

One change is not docs. npm start is now expo start --dev-client. Without the flag expo start picks its target by whether expo-dev-client is a dependency — it is not — so a bare npm start installs and opens Expo Go, which is exactly the build that writes the journal in cleartext. run:ios / run:android pass the flag themselves, which is why the first day works and the morning after does not. main's README currently says npm start "picks it up, the same as it always did", which was the one line describing the daily loop and was wrong. Flagging it because it takes this PR slightly outside "docs only" — happy to split it out if you would rather it landed on its own.

Two forward references from the original description are now resolved: #133 is fixed on main, so the tests section no longer needs the "they error rather than skip" caveat, and main's own wording already says they skip.

Verified locally on Node 22.14: npm test → 14 suites, 152 tests, all pass. npx tsc --noEmit and npm run lint both clean. Also checked that every remaining mention of Expo Go is a warning rather than an instruction, that all five ../docs/decisions/*.md links resolve, that code fences balance, and that the #running-on-a-physical-iphone anchor has a target.

Still unverified, and still the acceptance criterion that matters most: that someone with a clean checkout can follow this start to finish and reach a running app. That needs macOS + Xcode and an Android Studio machine. #129's QA checklist covers it and someone should walk it before this merges.