docs(agents): promote v1.0.8 release learnings

Record three confirmed v1.0.8 failure modes (expo prebuild native
regressions, npm 10/11 lockfile divergence, local EAS build
preconditions) and promote each into docs/releasing.md, a new
docs/development/dependencies.md, and the release-preflight script.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/development/dependencies.md

@@ -0,0 +1,76 @@
+# Dependency and lockfile discipline
+
+## Two npm realities
+
+CI runners and the API Docker image use the node version pinned in
+`.nvmrc` (node 20.19.4 with npm 10.8.2). A developer machine can run a newer
+npm (for example npm 11). npm 10 and npm 11 resolve wildcard or range
+dependencies differently at the same place in the dependency tree, and each
+npm's platform-optional binary selection is not portable to a lockfile
+regenerated by the other npm. A lockfile that passes `npm ci` under one npm
+major version can fail it under the other with either an "Invalid: lock
+file's ... does not satisfy" error or missing platform-optional binaries
+(for example `@next/swc-linux-x64-gnu` breaking `next build`,
+`@rollup/rollup-linux-x64-gnu` breaking the API Docker `tsup` build, or a
+missing `lightningcss` variant breaking local `npm ci`).
+
+## Pin wildcard-range dependencies with root overrides
+
+When a transitive dependency declares a wildcard or wide range (for example
+`react-native-worklets` depending on `@react-native/metro-config: "*"`), pin
+the exact version the app needs in the root `package.json` `overrides` block
+rather than leaving it to whichever npm resolved the lockfile last:
+
+```json
+"overrides": {
+  "rollup": "4.54.0",
+  "react-native": "0.85.3",
+  "expo": "~56.0.0",
+  "@react-native/metro-config": "0.85.3"
+}
+```
+
+## Pin platform-optional binaries that must travel with the framework version
+
+`apps/web/package.json` pins the `@next/swc` linux and darwin binaries as
+direct `optionalDependencies` so npm does not have to infer them per
+platform:
+
+```json
+"optionalDependencies": {
+  "@next/swc-linux-x64-gnu": "15.5.24",
+  "@next/swc-linux-x64-musl": "15.5.24",
+  "@next/swc-darwin-arm64": "15.5.24"
+}
+```
+
+These versions must be bumped together with any `next` version bump, or the
+pinned binaries will drift from the framework version and `npm ci` or
+`next build` can fail on the platform that needs the stale binary.
+
+## Validate a regenerated lockfile both ways
+
+After changing `overrides` or any dependency version, regenerate
+`package-lock.json` and validate it under both npm majors before committing:
+
+```bash
+# Local npm (matches this machine's npm major)
+npm ci
+npm run verify:fast
+
+# The CI/Docker npm major, emulated on Apple Silicon
+docker run --rm --platform linux/amd64 -v "$PWD:/repo" -w /repo node:20.19.4 npm ci
+```
+
+The `--platform linux/amd64` flag is mandatory on Apple Silicon: without it,
+Docker runs the arm64 image and the platform-binary check proves nothing.
+
+## After any bypassed push
+
+Pushes to `staging` bypass required status checks. After any such push, check
+`gh run list --branch staging` to confirm CI is actually green rather than
+assuming it ran and passed.
+
+Do not pipe `npm` commands through `tail` when diagnosing a lockfile or build
+failure; it can swallow the command's exit code and the detail needed to find
+the root cause.

docs/index.md

@@ -8,6 +8,7 @@ historical notes. Agents should load only the section relevant to their task.
 - [System architecture](architecture/system.md)
 - [Client data freshness](architecture/client-data-freshness.md)
 - [Local full-stack development](development/local-stack.md)
+- [Dependency and lockfile discipline](development/dependencies.md)
 - [Testing strategy](testing/strategy.md)
 - [Database migration safety](operations/database-migrations.md)
 - [Backend deployment and branching](operations/backend-deployments.md)

docs/releasing.md

@@ -249,6 +249,23 @@ and dependency installation failures occur before native compilation: fix and
 preflight those inputs without starting another build. Make one meaningful build
 per newly proven input state.
 
+Before starting: confirm `eas` is installed and on PATH (scripts call bare
+`eas`); explicitly export `ANDROID_HOME`, `ANDROID_SDK_ROOT`, and `JAVA_HOME`
+(JDK 17) rather than relying on a shell profile, because non-interactive shells
+used for automation do not load it ("SDK location not found" otherwise); ensure
+`EAS_LOCAL_BUILD_WORKINGDIR` does not exist or is empty ("Workingdir is not
+empty" otherwise); and run every command from `apps/mobile`. Capture the full
+build log to a file; do not pipe it through `tail`, which drops the detail
+needed to diagnose a failure.
+
+After a successful iOS build, EAS auto-increment updates both app and widget
+Info.plists but not the widget target's `CURRENT_PROJECT_VERSION` in the
+pbxproj, so `release:preflight` fails until it is synced to the new build
+number (for example `sed -i '' 's/CURRENT_PROJECT_VERSION = 46;/CURRENT_PROJECT_VERSION = 47;/' ios/Sauci.xcodeproj/project.pbxproj`
+for both Debug and Release). If native dependencies changed, also sync
+`ios/Podfile.lock` from the successful build's working directory: the archive's
+`pod install` resolution is authoritative when local CocoaPods is broken.
+
 Report provider progress by phase: packaging, native compilation, submission
 queue, or store processing. Do not describe every failure as a rebuild.
 
@@ -292,6 +309,24 @@ verify it, and commit it before starting the release from a clean worktree. Use
 5.x, a non-clean prebuild against an already-generated iOS project fails while
 updating the widget's Xcode target.
 
+**After native regeneration:** `expo prebuild --clean` can silently regress
+checked-in native invariants (confirmed during the SDK 54 to 56 upgrade). Before
+committing a regenerated project:
+
+- Diff pbxproj signing and identity keys (PRODUCT_BUNDLE_IDENTIFIER,
+  CODE_SIGN_ENTITLEMENTS) against the last release tag; apple-targets can derive
+  a widget's bundle identifier from its folder name instead of the pinned config.
+- Semantic-diff Info.plist and entitlements files against the last release tag;
+  prebuild can reintroduce dev-launcher-only keys (NSBonjourServices,
+  NSLocalNetworkUsageDescription, RCTMetroPort) and drop widget entitlements.
+- Check android/gradle.properties for a reset `org.gradle.jvmargs` (prebuild
+  resets it to the stock -Xmx2048m/512m, which OOMs release Kotlin/CMake tasks).
+- Run `npm run release:preflight`; it enforces the Android manifest media
+  permission removal and rejects the dev-launcher-only Info.plist keys.
+- Treat `expo-doctor` unmaintained-package warnings as release blockers on an
+  SDK upgrade: a package absent from the new SDK's bundledNativeModules can fail
+  the iOS archive with no compatible release available.
+
 **Out of memory:**
 ```bash
 # Increase Gradle memory