# 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 |