docs: developer onboarding, fresh clone guide, secrets recovery

Add DEVELOPER_SETUP, FRESH_ENV_CLONE, and SECRETS_AND_RECOVERY for the ac/*
workspace; link from README for clean-laptop and lab credential procedures.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/FRESH_ENV_CLONE.md

@@ -0,0 +1,90 @@
+# Fresh developer machine — clone guide
+
+Use this on a **clean laptop** (no legacy `android_cast` monolith checkout).  
+Canonical layout: org **`ac`** on `git://f0xx.org/ac/*`, branch **`next`**.
+
+## One command (recommended)
+
+From any empty directory (requires `git` and reachability to `git://f0xx.org`):
+
+```bash
+# Bootstrap: shallow clone ac-scripts only, then run the full workspace clone
+git clone --branch next --single-branch --depth 1 \
+  git://f0xx.org/ac/ac-scripts /tmp/ac-scripts-bootstrap
+sh /tmp/ac-scripts-bootstrap/fresh-clone-dev-env.sh
+```
+
+Default target: `~/src/androidcast-ac/` (override with `-d /path`).
+
+The script:
+
+1. Clones **`ac-workspace`** (submodule manifest).
+2. Runs `git submodule update --init --recursive` on **`next`**.
+3. Verifies every submodule path exists and prints a SHA summary.
+4. Exits non-zero if any submodule is missing or unreachable.
+
+## Manual steps (review / teach)
+
+```bash
+export AC_GIT_BASE=git://f0xx.org/ac
+export AC_BRANCH=next
+export TARGET=~/src/androidcast-ac
+
+mkdir -p "$(dirname "$TARGET")"
+git clone --branch "$AC_BRANCH" --single-branch \
+  "${AC_GIT_BASE}/ac-workspace" "$TARGET"
+cd "$TARGET"
+git submodule sync --recursive
+git submodule update --init --recursive
+
+# Sanity: expect 32 submodule directories + ac-workspace root
+find . -maxdepth 1 -type d -name 'ac-*' | wc -l
+
+# Spot-check remotes (each submodule should be git://f0xx.org/ac/<name>)
+git submodule foreach --quiet 'echo $name $(git rev-parse --short HEAD) $(git remote get-url origin)'
+```
+
+## What you get
+
+| Path under workspace | Role |
+|----------------------|------|
+| `ac-mobile-android/` | Android app |
+| `ac-deploy/` | Lab cluster (`sim/cluster0/`), compose scripts |
+| `ac-docs/` | Documentation (this file) |
+| `ac-scripts/` | `fresh-clone-dev-env.sh`, CI helpers |
+| `ac-platform-*` | DB, PHP, web, edge nginx snippets |
+| `ac-ms-*`, `ac-be-*` | Backend microservices and consoles |
+
+**Do not** clone legacy `git://f0xx.org/android_cast` for new work — it is frozen read-only.
+
+## After clone
+
+| Task | Where |
+|------|--------|
+| Repo map, lab URLs | [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md) |
+| Passwords / tokens / VPN recovery | [SECRETS_AND_RECOVERY.md](SECRETS_AND_RECOVERY.md) |
+| Android build | `cd ac-mobile-android && ./gradlew :app:assembleDebug` |
+| Unit tests | `./gradlew :app:testDebugUnitTest` |
+| Lab cluster (optional) | `ac-deploy/sim/cluster0/DEPLOY.md` |
+
+## Lab vs production URLs
+
+| Environment | Issues API | Gitea browse |
+|-------------|------------|--------------|
+| Production (current) | `https://apps.f0xx.org/app/androidcast_project/issues/` | prod BE Gitea |
+| Lab cluster (cast01) | `https://acl0.f0xx.org/...` (after FE `ac-fe.conf`) | `.../git/ac/` |
+
+Mobile defaults target **production** until you point a debug build at lab (`BackendEndpoints` / settings).
+
+## Version note (post-migration)
+
+After migration completes, **app and backend minor versions will bump**. Older mobile builds were not publicly released; lab/prod may **reject** clients below the new minimum. Rebuild from `ac-mobile-android` on `next` after pulling.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| `git://f0xx.org` unreachable | VPN/LAN to git host; try from cluster or PO network |
+| Submodule empty dir | `git submodule update --init --recursive` in workspace root |
+| Wrong branch | `git checkout next && git submodule foreach git checkout next` |
+| SSH instead of git | Not required for read-only clone; push uses `git://` on FE |