Incident-level internals of cwcli's apps command group (list/install/uninstall/update/checkout) and the update state machine - multi-site fan-out by default, --json stdout purity, post-mutation recache, git-URL app-name derivation, the deprecated `cwcli update` alias and its frappe special-case, list/install/uninstall on the logic core (core/apps.py: the untangled uninstall consent/auto_start, report.ok-driven exit codes, `cwcli axi apps list` and `axi apps checkout` shipping while install/uninstall stay deferred, and how checkout's absence assertion was reversed), and core/update.py's control flow plus maintenance-mode safety (why it is NOT a generator, why a lost stream is unknown-not-failed, per-site enable/disable, honest partial-failure exit codes, shlex-quoted interpolation). Use this whenever you edit or debug commands/apps.py, core/apps.py, commands/update.py, core/update.py, or `axi apps list`/`axi apps update`, or touch app install/uninstall/update/checkout or bench migration behavior. Each note gua
The UI-pure logic core boundary and the cwcli axi agent-facing frontend - core purity (core/*.py imports NO rich/questionary/typer, returns a typed Result envelope or raises CwcliError, never prompts or exits), no live Docker object crossing a core.<verb> return boundary, the thin CLI wrappers over core resolvers, the backup pre-resolve-then-spinner pattern, axi's TOON-only structured output and exit-code mapping, the migrated read-only ls/list + where slices, and the AXI cross-cutting shell (the `cwcli axi setup` SessionStart-hook installer and the generated installable skill). Use this whenever you edit or debug src/caffeinated_whale_cli/core/, commands/axi.py, utils/toon.py, commands/list.py, commands/where.py, utils/agent_hooks.py, scripts/build_skill.py, skills/cwcli/SKILL.md, or migrate another command onto the logic core. Each note guards a locked design decision or a real shipped bug - do not silently re-break it.
Manage local Frappe/ERPNext Docker instances through the cwcli CLI - list instances, start/stop/restart them, check per-process health, back up and unlock sites, manage bench apps, and search cached apps and sites. Use whenever a task touches a local Frappe or ERPNext development instance, bench, or site: checking whether an instance is running, starting or restarting one, backing up or restoring a site, installing or updating bench apps, or finding which bench holds an app or site.
Incident-level root-cause internals of cwcli's lifecycle and destructive commands - init (Frappe/bench version gating, admin/db-root secret env-transport, existing-bench reuse flow), rm (what deletion actually removes, conf/-only archive, recache-under-spinner deadlock, the C1/H5/M11 backup+name+exit-code data-safety gates, multi-bench per-bench backup, the start-back-up-delete transient-start flow for a stopped project), and restore (receive-mode and normal-path data-safety, non-interactive selectors, secrets off the argv, streamed copies, shared site detection, default-site resolution, post-restore migrate+restart), and start/status/logs/restart (the supervisord per-process supervision substrate: PID-keyed idempotency, config/launcher generation, per-process logs, the stdout-token-only status contract, single-program restart + auto-heal). Use this whenever you edit or debug core/init.py, commands/init.py, core/rm.py, commands/rm.py, core/restore.py, commands/restore.py, commands/start.py, commands/status.py
End-to-end testing protocol for cwcli against real Frappe/ERPNext Docker instances - the isolation recipe (CWCLI_HOME or a temp HOME, the cwe2e- project prefix, dedicated volumes/network), building genuine v14/v15/v16 benches instead of fixtures, driving interactive prompts through a real pty (the ESC[?2004h raw-mode marker), driving non-interactive paths with flags, teardown, and the tests/e2e/harness.py contract. Use this whenever you write, run, or extend E2E tests (anything under tests/e2e/), touch tests/e2e/harness.py, or hand-validate a cwcli behavior change on a real instance - even if the task just says "test it on a real instance" without naming E2E.
Incident-level internals of cwcli's inspect / cache / multi-bench layer - inspect's 3-tier freshness model (T1 serve-cache / T2 read-only partial drift-check / T3 full re-cache), the multi-bench addressing model (numeric vs durable user labels, the --bench selector, marker-file recovery), the shared --yes / auto-start / honest-exit-code contract, the cache secret-redaction whitelist that keeps secrets out of the SQLite cache, and the CWCLI_HOME on-disk footprint override. Use this whenever you edit or debug core/inspect.py, commands/inspect.py, commands/label.py, utils/bench_labels.py, utils/db_utils.py, utils/config_utils.py, the SQLite cache, or anything touching multi-bench selection / labels. Each note guards a real shipped bug - keep the root-cause "why".
How to cut a cwcli (caffeinated-whale-cli) release - the exactly-four version-bump files (pyproject.toml, __init__.py, uv.lock, CHANGELOG.md), the CHANGELOG Keep-a-Changelog format, the semver convention this repo practices, the develop -> vX.Y.Z tag publish path, the uv trusted-publishing PyPI flow in release.yml (OIDC, --check-url non-reproducible-build gotcha, why the old pypa action was replaced), and the one-time PyPI trusted-publisher prerequisite. Use this whenever you bump the cwcli version, edit CHANGELOG.md for a release, publish to PyPI, or touch .github/workflows/release.yml or build.yml.