# Codex Script Notes

This file is a fast-reference companion for the large local helper scripts.

## `.maintain-custom-release.sh`

Purpose:
- maintain a custom stable branch such as `release/v1.26-custom`
- start from `BASE_TAG`
- fetch and sync upstream compare / release-target refs explicitly
- cherry-pick selected custom work from a local source branch

Current interaction model:
- interactive menu with submenus:
  - `Manual Backups >`
  - `Fetch upstreams >`
  - `Sync >`
  - `Rollback >`
  - `Restore >`
- submenu navigation:
  - `Enter` or `b` / `B` => Back
  - `0` => Exit

Persistent runtime state:
- runtime copy: `/tmp/.maintain-custom-release.sh`
- persisted settings: `/tmp/.maintain-custom-release.env`
- restore points: `.git/.maintain-custom-release-restore-points/`
- snapshots: `.git/.maintain-custom-release-snapshots/`
- active state file: `.git/.maintain-custom-release-state`

Recommended order:
1. `Bootstrap maintenance branch`
2. `Fetch upstream/main compare ref`
3. `Fetch upstream release target ref`
4. `Show import plan`
5. `Sync` actions as needed

Important behavior:
- `bootstrap` should only create/switch the maintenance branch from `BASE_TAG`; it should not fetch automatically
- `rollback` should remove bootstrap-created maintenance branches and clean script-managed refs/artifacts
- deleting a saved exact snapshot should also remove its paired `backup/maint-*` Git Graph marker

## `.update-gitea.sh`

Purpose:
- safe upstream sync helper for the working tree
- create safety backups before real sync actions
- provide `dry-run`, `rollback`, `restore-stash`, and `restore-snapshot`

Key safety expectations:
- `dry-run` must not modify the real repository
- real sync actions must preserve enough state for exact rollback

## `.import-upstream-cherry-pick.sh`

Purpose:
- import upstream commits through `git cherry-pick -x`
- support commit-by-commit or range-based import

Key safety expectations:
- save backup branch, snapshot, and stash before real import actions
- support `continue`, `rollback`, `restore-stash`, and `restore-snapshot`