[busbyk]

I ran into issues following the current docs to run the app locally. Very much open to critique about the layout of docs that I chose here.

Summary

Avy can't run in Expo Go because @rnmapbox/maps is a native module, but yarn start forced Expo Go (--go) and the docs never explained development builds.

This PR adds a local development guide (getting started first, then an optional deeper dive) and a debugging guide, keeps CONTRIBUTING about contributing, and fixes the instructions that were wrong.

 README.md
+  # Docs                         # links to every doc in docs/
 CONTRIBUTING.md
-  # Developer Environment       # setup, npm 8 pins, Expo Go claim, stale env list
-  ## Local Secrets / ## Logging
+  # Development                  # links to the local development and debugging docs
+  # Working from a fork          # volunteers work in forks
   # Checking in code
 docs/
+├── local-development.md        # getting started → how dev builds work → when to rebuild
+└── debugging.md                # DevTools, dev menus, LOG_LEVEL, gotchas
 .github/
+└── pull_request_template.md    # what/why, screenshots, testing, native-build checkbox
 package.json
-  "start": "... expo start --go"
+  "start": "... expo start --dev-client"
 CLAUDE.md / .env.sample         # drop Expo Go + LOG_NETWORK, document LOG_LEVEL

Corrections to the old docs:

• Expo Go: the old claim "Expo Go works with an empty .env" is false. The app crashes on Mapbox.setAccessToken at startup.
• LOG_NETWORK: no code reads it anymore. Network logging comes from LOG_LEVEL=debug, and trace adds request and response bodies.
• Secrets: the list named Google Maps keys and omitted MAPBOX_API_KEY, the only key needed locally. Mapbox no longer requires a secret download token.
• Android JDK: the build fails on JDK 25 because CMake treats the "restricted method" warning as an error. JDK 17 and 21 work; Android Studio's bundled JDK is 21.

Evidence

• Before: yarn start → i opens Expo Go → the app fails at startup because the native Mapbox module is missing.
  After: from a clean npx expo prebuild --clean, both platforms reach the onboarding screen:
  • iOS: npx expo run:ios builds, installs on the iPhone 17 simulator and loads the app with Metro (Build Succeeded, 0 errors).
  • Android: npx expo run:android installs on a Pixel emulator and loads the app.
• Android before: JDK 25: configureCMakeDebug[arm64-v8a] > WARNING: A restricted method in java.lang.System has been called, BUILD FAILED.
  Android after: JDK 21 (Android Studio's): BUILD SUCCESSFUL.

Follow-ups

• Android URI scheme missing: the generated Android manifest has no exp+avalanche-forecast scheme (iOS has it). Metro warns "Could not find a shared URI scheme", and Android opens to the dev launcher instead of auto-loading the app. The local development doc notes the workaround: tap the running server.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[yuliadub]

thank for running through it and updating 🙏 layout looks good to me!

[kevinherdez]

Thanks for this! I think it looks good. There's a couple things that I'm going to tweak when I get the PR out for Expo 58 since some of the commands will change slightly, but other than that this is great

[busbyk]

Thanks for this! I think it looks good. There's a couple things that I'm going to tweak when I get the PR out for Expo 58 since some of the commands will change slightly, but other than that this is great

Perfect. I'll just leave this open and let you update once you get that merged if that sounds good to you?

[kevinherdez]

Thanks for this! I think it looks good. There's a couple things that I'm going to tweak when I get the PR out for Expo 58 since some of the commands will change slightly, but other than that this is great

Perfect. I'll just leave this open and let you update once you get that merged if that sounds good to you?

Yeah sounds good!