# codespaces_mgr: branches, releases, and prebuilds

## The branches

- **`dev`** — where all edits land. Val never opens VS Code on `cs-mgr` directly; Claude
  drives `dev` via `create_codespaces_mgr.py` (see below) and direct git commands.
- **`main`** — the public/stable branch. Only ever updated by a release (merge from `dev`).
  This is what visitors get when they click "Open in GitHub Codespaces" from the homepage
  or `https://github.com/codespaces/new/ApiLogicServer/codespaces_mgr` — both default to `main`.

## The script: `.devcontainer-codespaces/create_codespaces_mgr.py`

```bash
python3 .devcontainer-codespaces/create_codespaces_mgr.py /path/to/org_git/codespaces_mgr [--dry-run|--push|--release]
```

- **(no flag)** — sync files into target, leave staged for manual review. Doesn't commit/push.
- **`--dry-run`** — show what would be copied, no changes.
- **`--push`** — sync, commit, push to `dev`. The normal day-to-day command after any edit
  (README wording, sample fix, CE update). Always runs the full sync (copies `samples/`,
  `system/`, etc. — ~100MB, but this is local disk copy + git diff-based push, so it's a few
  seconds, not the multi-minute operation it might look like from the verbose output).
- **`--release`** — does everything `--push` does, then: merges `dev` → `main`, tags `main`
  with the current gold-source product version, bumps `.devcontainer/devcontainer.json`
  (triggers the prebuild refresh — see below), pushes `main` + the tag, and leaves the repo
  checked out on `dev`. Refuses to run if the gold version hasn't changed since the last
  release tag (that means you forgot to bump it upstream).

The version `--release` tags with always comes from gold source:
`org_git/ApiLogicServer-src/api_logic_server_cli/api_logic_server.py` (`__version__ = "..."`)
— never from README front matter. Val controls that version directly; `cs-mgr` never bumps it.

## ⚠️ README.md provenance — don't edit it as if it's the source

`genai-logic/README.md` (what `create_codespaces_mgr.py` copies into `cs-mgr`) is **not**
hand-authored — it's generated by `copy_md()` from the real gold source:

```
org_git/Docs/docs/Manager-readme.md  (mkdocs format)
        │  copy_md() — strips front matter, converts mkdocs → plain markdown,
        │  rewrites relative image paths to GitHub raw URLs
        ▼
genai-logic/README.md  (this workspace — what gets synced to cs-mgr)
        │  create_codespaces_mgr.py — strips front matter again, injects
        │  Codespaces/browser note, samples/ links → Docs site URLs
        ▼
codespaces_mgr/README.md
```

Editing `genai-logic/README.md` directly works for **this session only** — the next BLT run
or fresh project creation re-runs `copy_md()` from `org_git/Docs/docs/Manager-readme.md` and
silently overwrites it. **Permanent README changes go in the Docs gold source, in mkdocs
format**, not in either copy downstream of it.

## Why prebuilds, and why "Every push" as the trigger

Prebuilds cache the devcontainer image so a new codespace starts fast. They cost storage +
GitHub Actions minutes on every rebuild. There's no API/CLI for managing prebuilds — GitHub
web UI only (Settings → Codespaces → Prebuilds).

Trigger options are **Every push**, **Configuration change**, or **Scheduled** — no
"manual-only" mode. The risk we were originally guarding against — a rebuild firing on a
casual, possibly-mid-edit push to `main` — doesn't apply once `dev` exists: `main` *only*
ever changes via a deliberate `--release`, never a casual edit. Given that, **Every push**
and **Configuration change** trigger on the same events in practice (since `--release`
always bumps `.devcontainer/devcontainer.json` as part of the merge) — but **Every push**
is the more robust choice: it doesn't depend on that bump as the trigger mechanism, so it
still rebuilds correctly even if a future change to the release flow ever merges into `main`
without touching `devcontainer.json`. Configuration change would silently miss that case.

(Configured: `main` branch, trigger = Every push, region US East.)

## Manual prebuild refresh (rarely needed)

The prebuild's "⋯" menu in Settings → Codespaces → Prebuilds has a "Manually trigger" action
that works regardless of trigger type — use it if you need a refresh without a `--release`.
