suve

Use when restructuring the README or the GitHub Pages site generated from it — the left-nav/left-pane, section reorg, or per-provider command docs. Covers the build-docs-site.py split + literate-nav SUMMARY pipeline, its HTML-comment directives and site-only transforms (nav-group, site:skip, hero <h1>, asset ../ prefix, DOC_NAV grouping), the python-markdown gotchas GitHub hides, and the `mise docs-build` strict gate.

Use when authoring or backfilling the "## Highlights" section of a GitHub release — the human-written summary that prepends the auto-generated notes. Covers when a release earns highlights, the fixed format (bold lead + breaking-change note, `###` subsections, PR-referenced bullets), and the prepend-in-place mechanics.

Use when re-recording the CLI, TUI, or GUI demo GIFs after a UI change or a user-visible output change. Covers the record scripts, robust Playwright selectors, output-drift triggers, frame verification, and Git LFS.

Load when writing or reviewing Go that builds or transforms slices/maps. Prefer samber/lo, samber/lo/it, and stdlib slices/maps callback & iterator utilities over hand-rolled make + range + append; keep an explicit loop only where side effects or control flow are genuinely complex.

Load when you need the per-provider capability, versioning, and alias matrix for suve's CLI without reading the full docs/{aws,azure,gcloud}.md option tables. A one-page orientation; link out for per-command detail.

Load when adding or modifying a provider adapter, or when touching internal/provider/** or internal/domain/**. Captures the invariants that keep the provider-neutral seam honest: the neutral domain model, opaque version refs, the typed write/delete option pattern, interface segregation, and SDK confinement.

Load when wiring a top-level command group, adding a cloud, or touching internal/provider/registry.go, internal/provider/detect/, or internal/cli/commands/internal/client.go. Explains how a provider is selected (explicit groups plus env-detected flat aliases), how the registry composes backends, how each provider's scope is built, and the SDK-confinement boundary.

Load when changing the staging reducers or executor (internal/staging/transition/), or when reasoning about add/edit/delete/tag transitions, auto-skip/auto-unstage, the tag cascade, or conflict detection. Points to the authoritative state-machine reference.

Use when running a codebase-wide or subsystem bug audit — fan out orthogonal parallel investigators, adversarially verify every Medium+ finding before filing, write bug issues in the standard body, and file a severity-grouped [Epic] with linked sub-issues and an "Areas verified clean" section.

Use when turning one filed bug issue into a fix PR — reproduce from the issue's Failure-scenario section, fix at the cited site, add a regression test at every layer the three-layer rule names, run the gates, and write a PR whose Verification section shows real command output.

Use when keeping docs in sync with the implementation — sweep command tables/env-vars/paths against the real CLI, keep reference docs current-state-only (migrations go to release notes), enforce identical terminology across CLI help / README / GUI, and track the README install/aqua section against the external aqua-registry.

Use when planning a multi-PR feature or cross-cutting refactor as an epic — write a design-complete epic body, slice into layer-ordered sub-issues that each restate their slice standalone with DELETE/ADD/MODIFY tasks and dependencies, use an integration branch when the change must land coherently, and require a context-isolated review before every PR.

Use when adding emulator-backed e2e coverage for a provider — wiring an env-gated emulator seam, a compose.test.yaml service, a mise e2e-<provider> task, and a closed-network CI job. Covers emulator-vs-SDK divergences and coverage upload.

Use when adding a new cloud provider adapter, or extending an existing one with a new service, in internal/provider/<name>/. Covers the Store interface, SDK confinement, error mapping, version-spec parsing, CLI/registry wiring, and staging support.

Use when changing the Wails/Svelte GUI in internal/gui/ — backend bindings, capability-driven UI, provider/scope switching, or async loads. Covers the bindings-regenerate-then-rebuild rule, server-side guards, and the recurring async-bug checklist.