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>

DEVELOPER_SETUP.md

@@ -0,0 +1,68 @@
+# Developer setup — org `ac`
+
+**Clean machine?** Start with [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) and run `ac-scripts/fresh-clone-dev-env.sh`.
+
+Canonical entry point: **`ac-workspace`** (submodule manifest).
+
+```bash
+git clone git://f0xx.org/ac/ac-workspace
+cd ac-workspace
+git checkout next
+git submodule update --init --recursive
+```
+
+## Which repo for what
+
+| Area | Repo(s) |
+|------|---------|
+| Android app | `ac-mobile-android` |
+| Issues / crash console PHP | `ac-ms-issues`, `ac-be-issues`, `ac-platform-php`, `ac-platform-web` |
+| Auth / 2FA UI | `ac-be-auth`, `ac-ms-identity` |
+| Graphs | `ac-ms-graphs`, `ac-be-graphs` |
+| Tickets, RBAC, devices, remote access | `ac-ms-tickets`, `ac-ms-rbac`, `ac-ms-devices`, `ac-ms-remote-access`, matching `ac-be-*` |
+| URL shortener | `ac-ms-url-shortener` (submodule in workspace) |
+| Hub / builder | `ac-be-hub`, `ac-be-builder` |
+| Nginx FE/BE snippets | `ac-platform-edge` (`fe/ac-fe.conf` for Gentoo FE) |
+| DB schema / migrations | `ac-platform-db` |
+| Lab deploy scripts | `ac-deploy` (`sim/cluster0/`) |
+| Docs | `ac-docs` |
+
+Legacy monolith `git://f0xx.org/android_cast` is **frozen read-only** — do not commit there.
+
+## Local PHP (optional)
+
+1. Clone workspace as above.
+2. Copy `ac-deploy/sim/cluster0/lab-seeds/backend/config/config.example.php` → `config/config.php` and set SQLite or local MariaDB.
+3. Point a local vhost at `public/` with `base_path` `/app/androidcast_project/issues` (see `ac-platform-edge` fragments).
+
+## Lab cluster (cast01–03)
+
+Deployed tree on nodes:
+
+| Path | Content |
+|------|---------|
+| `/var/www/ac/workspace/` | `ac-workspace` + submodules |
+| `/var/www/ac/composed/backend/` | overlay from `compose-lab-backend.sh` |
+| `/var/www/ac/platform/` | shared session / footer helpers |
+| cast01 `:3000` | Gitea browse UI (org **ac**, pull mirrors) |
+
+Scripts: `ac-deploy/sim/cluster0/scripts/` — run on cast01 as `ai` after NFS sync.
+
+**Secrets / recovery:** [docs/SECRETS_AND_RECOVERY.md](docs/SECRETS_AND_RECOVERY.md) — passwords, tokens, WireGuard, RSSH.  
+Lab shared files: `cluster/credentials.txt`, `cluster/secrets.lab.env` (from `secrets.lab.env.example`).
+
+**Public lab URL (after FE install):** `https://acl0.f0xx.org/app/androidcast_project/issues/`  
+**Gitea (lab):** `https://acl0.f0xx.org/app/androidcast_project/git/ac/` — `[gitea_admin]` in `credentials.txt`  
+FE config: `ac-platform-edge/fe/INSTALL.md` → `/etc/nginx/ac-fe.conf` on monstro (PO applies).
+
+## Mobile defaults
+
+Production REST base: `https://apps.f0xx.org/app/androidcast_project/issues/`  
+(`ac-mobile-android` → `BackendEndpoints.ISSUES_BASE`). For lab QA, override upload URL in app settings or build flavor.
+
+After migration, **minor app/BE version will bump**; unreleased older mobile builds may be rejected by lab/prod — always build from current `next`.
+
+## Tests
+
+- Android unit: `./gradlew :app:testDebugUnitTest` (from `ac-mobile-android` checkout).
+- Cluster verify: `ac-deploy/sim/cluster0/scripts/verify_lab_setup.sh --local` / `--cluster`.

README.md

@@ -5,3 +5,11 @@ AndroidCast documentation (extracted from monolith `docs/`).
 - **Remote:** `git://f0xx.org/ac/ac-docs`
 - **Build PDFs:** `./build-pdf.sh` (requires pandoc/xelatex per `_pdf_build/`)
 - **SPEC:** [specs/20260618_repos_reorganizing.md](specs/20260618_repos_reorganizing.md) Step 2
+
+## Developer onboarding
+
+| Doc | Purpose |
+|-----|---------|
+| [DEVELOPER_SETUP.md](DEVELOPER_SETUP.md) | Repo map, lab paths |
+| [docs/FRESH_ENV_CLONE.md](docs/FRESH_ENV_CLONE.md) | Clean laptop — clone all `ac/*` repos |
+| [docs/SECRETS_AND_RECOVERY.md](docs/SECRETS_AND_RECOVERY.md) | Passwords, tokens, VPN/RSSH recovery |

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 |

docs/SECRETS_AND_RECOVERY.md

@@ -0,0 +1,108 @@
+# Secrets, tokens, and recovery (lab cluster + dev)
+
+**Rule:** whenever you create a password, API token, or VPN key, **record it in the shared lab store** so the next deploy or developer can recover without guesswork.
+
+## Shared store (lab cluster)
+
+| File | Location | In git? |
+|------|----------|---------|
+| `credentials.txt` | `ac-deploy/sim/cluster0/` → NFS `/shared/cluster/` | **Yes** (lab-only values) |
+| `secrets.lab.env` | same NFS tree | **No** — copy from `secrets.lab.env.example`, fill on cluster |
+| Gitea install secrets | `/var/lib/gitea/.lab-secrets.env` on cast01 | **No** (generated by `deploy-gitea.sh`) |
+| Gitea mirror API token | `/var/lib/gitea/.mirror-admin-token` on cast01 | **No** (regenerable — see below) |
+
+Production (`artc0` / `monstro`) keeps its own stores; lab cluster is **cast01–03**.
+
+## Recovery priority
+
+1. **Preferred:** user self-service via **email** (2FA, password reset) once cluster mail is configured and verified on `acl0`.
+2. **Lab fallback:** admin CLI / config rewrite from values in `credentials.txt` + `secrets.lab.env`.
+3. **VPN (WireGuard + RSSH):** re-provision from cluster scripts — never copy prod keys to lab.
+
+---
+
+## Gitea (cast01)
+
+| Secret | Recover |
+|--------|---------|
+| Admin password `[gitea_admin]` | `credentials.txt` → or `gitea admin user change-password --username admin --password '…'` |
+| Mirror API token | `sudo -u gitea gitea -c /etc/gitea/app.ini admin user generate-access-token --username admin --token-name mirror-ac --scopes all --raw` → save to `/var/lib/gitea/.mirror-admin-token` |
+| `INTERNAL_TOKEN`, JWT | `/var/lib/gitea/.lab-secrets.env` — if lost: stop gitea, delete file, `FORCE_GITEA_CONFIG=1 deploy-gitea.sh` (rewrites `app.ini`; **DB preserved**) |
+
+Browse: `https://acl0.f0xx.org/app/androidcast_project/git/` (org **`ac`**).
+
+---
+
+## MariaDB (cluster)
+
+| Item | Recover |
+|------|---------|
+| App user/password | `[mariadb_app]` in `credentials.txt` |
+| Replication | `[mariadb_replication]` in `credentials.txt` |
+| Root | Alpine socket auth as root on cast01 — no password by default |
+
+Re-apply schemas: `sudo sh /shared/cluster/scripts/load-schemas.sh` on cast01 (destructive to empty DB only — read script first).
+
+---
+
+## PHP / issues backend (`config.php`)
+
+Lab composed tree: `/var/www/ac/composed/backend/config/config.php` (generated by `compose-lab-backend.sh`).
+
+| Key | Source |
+|-----|--------|
+| DB password | `credentials.txt` `[mariadb_app]` |
+| `auth.encryption_key` | `secrets.lab.env` → `AUTH_ENCRYPTION_KEY` or regenerate (invalidates sessions) |
+
+Template: `ac-deploy/sim/cluster0/lab-seeds/backend/config/config.example.php`.
+
+**Email / 2FA:** when SMTP is live on lab, verify with `diag.php` and registration flow; then prefer **email recovery** over static passwords.
+
+---
+
+## WireGuard (remote access)
+
+| Item | Store / recover |
+|------|-----------------|
+| Server keys | `secrets.lab.env` → `WG_SERVER_*` or BE `config.php` `remote_access` |
+| Peer keys | DB `remote_access` tables + `WireGuardPeerProvisioner` |
+| Re-provision | `ac-deploy/sim/cluster0/lab-seeds/backend/scripts/sync_wg_peers.php` (on cluster, from composed backend) |
+
+Do **not** reuse production WG keys on lab. Generate new lab keys and document in `secrets.lab.env`.
+
+---
+
+## RSSH (bastion / reverse SSH)
+
+| Item | Store / recover |
+|------|-----------------|
+| Bastion host keys | server `sshd` host keys (standard OS path) |
+| Ephemeral `ra-*` users | `scripts/rssh_bastion_user.sh` on composed backend |
+| Client keys | issued per session in DB — no static shared password |
+
+Recovery: run bastion provisioner from lab backend; see `REMOTE_ACCESS_IMPL.md` and `REMOTE_ACCESS_VALIDATION.md`.
+
+---
+
+## Git HTTPS read tokens (future)
+
+Per SPEC: tokens live under **`/etc/git-ro/`** on FE — **outside** app repos.  
+AndroidCast code does not read those paths; CI holds tokens in its own secret store.
+
+---
+
+## Checklist after creating any secret
+
+- [ ] Added to `credentials.txt` (if safe for git — lab only) **or** `secrets.lab.env` on NFS (not committed).
+- [ ] Noted in this doc if recovery command is non-obvious.
+- [ ] If user-facing: email path tested on lab when mail is up.
+- [ ] VPN: lab keys distinct from prod.
+
+---
+
+## Related
+
+- [FRESH_ENV_CLONE.md](FRESH_ENV_CLONE.md) — clean laptop clone
+- [DEVELOPER_SETUP.md](../DEVELOPER_SETUP.md) — repo map
+- `ac-deploy/sim/cluster0/gitea/README.md` — Gitea deploy
+- `20260607-2FA-email-mobile-auth-flow.md` — auth / email flows