overthink-plugins

MUST be invoked before any work involving: the `charly migrate` command (the single idempotent migration that brings any opencharly config up to the latest schema CalVer), the CalVer schema-version stamp (`version: YYYY.DDD.HHMM`), the CUE-anchored HEAD/floor (`charly/schema/version.cue` → `#SchemaVersion`/`#SchemaFloor`), the declarative migration table (`charly/migrations.cue`, applied by the core op-walker in `charly/migrate_engine.go`), the `LatestSchemaVersion()` load-time gate, or adding a new schema cutover as a migration-table entry.

MUST be invoked before any work involving: charly secrets commands, Secret Service / config-file credential management, GPG-encrypted .secrets files, credential import/export, or secret administration.

Authoritative reference for the "Hard Cutover by Default" policy governing schema changes, API renames, and deprecations. Forbidden patterns, required deliverables, rationale, examples from this repo, and the no-exception enforcement: plans are authored as full-scope single-phase cutovers and executed end-to-end regardless of estimated time, context, or scope. MUST be invoked when planning or reviewing any breaking change to Go types, YAML field names, CLI flags, or OCI labels.

Use when committing, branching, pushing, merging, tagging, creating PRs, or approving/merging PRs with gh — the feat/-branch, R10-gated, never-force-push landing workflow across the main repo + the plugins submodule + box/<distro> submodules. Covers sync-to-upstream, branch/worktree pruning, the fork+PR path for contributors without write access, and cross-repo @github landing order.

Go CLI development: building the charly binary, running tests, understanding the source code structure. MUST be invoked before reading or modifying any Go source file in charly/.

the `libvirt:` libvirt-RPC check verb for VMs — domain info, framebuffer screenshots, send-key, passwd, QMP, qemu-guest-agent client, snapshots, events — served out-of-process by candy/plugin-vm.

MUST be invoked before any work involving: charly config commands, image deployment setup, quadlet generation, secrets provisioning, encrypted volumes, data seeding, or volume backing configuration. Named `charly-config` (not `config`) to disambiguate from Claude Code's built-in `/config` slash command.

MUST be invoked before any work involving: `charly bundle add`/`charly bundle del` commands, quadlet generation, volume backing, tunnels (Tailscale/Cloudflare), `add_candy:` overlay, or per-machine deploy overlays.

Generic SSH support for charly — `--host <alias>` re-execs any command on a remote machine; `charly ssh tunnel` exposes remote SPICE/VNC endpoints on the local host for external GUI apps.

Mounts a virtiofs share tagged `workspace` at /workspace inside a VM guest via a systemd .mount unit. Use when a kind:vm entity shares a host directory into the guest and you need it auto-mounted (and re-mounted at every boot).

versa — image bundling marimo reactive notebook environment with Apache Airflow + GPU-accelerated OSM/GTFS analytics + martin vector tiles + 3D terrain via MapLibre + Polars geospatial extensions (polars-st, geopolars) + GeoArrow + deck.gl rendering via lonboard. Composes a marimo + airflow + OSM/GTFS analytics stack (agent-forwarding, nvidia, cuda, marimo, airflow, osm-tools, maputnik, notebook-osm, notebook-graph, debug-tools, dbus, charly, plus the versatiles tile-serving layers) on a CachyOS / Arch base into a single pod that exposes 7 host ports and 1 MCP server. MUST be invoked before building, deploying, configuring, or troubleshooting the versa image.

First kind:vm entity with source.kind: cloud_image — fetches the Arch Linux cloud qcow2 from pkgbuild.com, applies cloud-init, boots under libvirt/QEMU via BIOS firmware + virtio-gpu. Documents the stale-BOOTX64.EFI RCA, the simpledrm→qxldrmfb takeover race, the adopt-user pattern, and resource sizing. MUST be invoked before editing arch in box/arch/charly.yml or authoring another cloud_image VM from a template.

`disposable: true` is the ONE and ONLY authorization for autonomous destroy + rebuild via `charly update`. MUST be invoked before any task involving `charly update`, live verification on rebuildable targets, or marking a VM / container deploy as safe-to-nuke. Explains why disposability is a DEPLOY property (not an image property), the separation between load-bearing `disposable:` and informational `lifecycle:`, why derivation is deliberately absent, and how the flag makes live verification fearless on shared hosts.

MUST be invoked before any work involving: virtual machines, charly vm commands, kind:vm entities in charly.yml, cloud_image vs bootc source types, libvirt/QEMU backends, BIOS vs UEFI firmware, virtio-gpu video, or VM lifecycle.

Host dependency checker and hardware detector for the `charly doctor` CLI verb. Use when diagnosing host setup, checking dependencies, or verifying GPU detection. Named `charly-doctor` (not `doctor`) to disambiguate from Claude Code's built-in `/doctor` slash command.

MUST be invoked before any work involving: charly shell command, interactive shells, command execution in containers, workspace mounts, TTY allocation, or port relay.

Kitchen-sink development box on Debian 13 trixie: coding + AI-coding CLIs + DevOps tooling in one container. Debian base, 30+ direct candies mirroring fedora-coder's stack but with deb: sections. Runs as uid 1000 (`user`) with passwordless sudo. 143/0 tests pass. Use when working with the debian-coder box — or when comparing cross-distro parity across the four coder-family boxes.

MUST be invoked before any work involving: candy authoring, charly.yml, plan steps, pixi.toml, package.json, Cargo.toml, or any file under candy/. This skill is the authoritative reference for the plan-step verb catalog (`run:`/`check:` steps), `var:` substitution, execution order, and per-verb validation. Every other skill defers here for install-schema questions.

QEMU/KVM/libvirt stack — works identically under supervisord (containers/ pods, custom `exec:` form) AND under systemd (host installs / bootc / VMs, use_packaged: socket form). The daemon set is DISTRO-DIVERGENT: Fedora/Arch ship the modular virtqemud + virtnetworkd, Debian/Ubuntu ship only the monolithic libvirtd — selected by a per-entry `service: distro:` filter. Uses the mixed-entry `service:` schema (CLAUDE.md "Init-system polymorphism") — same name appears twice, init system at deploy time picks the matching form. Canonical worked example of the polymorphism pattern.

Use when authoring or modifying a charly PLUGIN — a candy with a `plugin:` block that contributes Providers (verbs/kinds/deploy-targets/steps/builders/commands), its own CUE schema, builtin (compiled-in) or external (out-of-tree git repo). Covers the unified Provider model, the per-plugin CUE-schema contract (single source → Go params for dev + schema-over-Describe RPC for runtime), the SDK, and the loader.

The InstallPlan IR — the shared intermediate representation consumed by the DEPLOY targets. ALL FIVE deploy substrates (local/vm/pod/k8s/android) are EXTERNAL out-of-process deploys via externalDeployTarget over the executor reverse channel. The local AND vm substrates DO consume the IR — the plugin walks the InstallPlan over the shared out-of-process walk (charly/plugin/kit.WalkPlans), driving the host for host-engine step kinds via the RunHostStep reverse-channel RPC; for vm the served executor is the guest SSHExecutor, so the SAME walk runs INSIDE the guest. pod's plugin walks NOTHING — pod bakes its steps INTO the image, so its substrateLifecycle hook builds the overlay container image HOST-SIDE via the retained PodDeployTarget (OCITarget add_candy: synthesis). The k8s substrate is EXTERNAL (deploy:k8s, served out-of-process by candy/plugin-kube): it does NOT consume the IR — the host preresolver GENERATES a Kustomize tree (the GenerateK8sKustomize shim → compiled-in candy/plugin-k8sgen) and the plugin ru

Go file map for the host side of the `local:` (external deploy:local plugin) + VM deploy execution surface. Files: local_spec.go, deploy_chain.go, ssh_managed_config.go, vmshared/hostdistro.go, install_ledger.go, builder_run.go, shell_profile.go, reverse_ops.go, service_render.go, deploy_ref.go. MUST be invoked before reading or modifying any of those files, or when debugging `local:` / VM deploy behaviour (ledger state, sudo batching, managed-block insertion, glibc preflight, ssh-config fragment, ref resolution).

Containerfile generation from charly.yml and layers. MUST be invoked before any work involving: charly box generate command, Containerfile generation, .build/ directory contents, the task-verb emission pipeline, or understanding generated output.

Containerfile generation: understanding charly box generate output, multi-stage builds, intermediate images, and the .build/ directory. Use when debugging or understanding generated Containerfiles. MUST be invoked before reading or modifying any Go source file in charly/.

MUST be invoked before any work involving: building container images, charly box build command, pushing to registries, merging layers, build caches, or Containerfile generation.

Topic skill (no dedicated `charly enc` command — the surface is flags + subcommands on `charly config`). MUST be invoked before any work involving: encrypted storage, gocryptfs, or the `--encrypt` / `-v <name>:encrypted` backing flags on `charly config`, the `charly config mount` / `unmount` / `status` / `passwd` subcommands, or `charly-enc-<image>-<volume>.scope` systemd units.

Runtime configuration management for the charly CLI. MUST be invoked before any work involving: charly settings commands, runtime configuration, engine selection, bind address, storage paths, or secret backend configuration.

Prune reusable build artifacts to defaults: retention (images, check runs) and sweep one-time makepkg leftovers. MUST be invoked before any work involving: charly clean, build-artifact retention, keep_images / keep_check_runs, image-tag pruning, or .check run cleanup.

MUST be invoked before any work involving: `charly bundle add --target kubernetes`, `charly bundle from-box`, Kustomize manifest generation, cluster profiles, K8s deployments, `kubernetes:` block in deploy spec, or OCI-label capabilities.

CUE EGRESS validation — validating (and, where it adds value, generating) the config files charly WRITES to a system BEFORE the bytes hit disk. MUST be invoked before working on charly/egress.go, the vendored schemas under candy/plugin-egress/egress-schemas/vendor/, the ValidateEgress / registerVendoredEgressKind path, the offline `task cue:vendor` pipeline, or adding an egress schema for any written artifact (cloud-init, k8s manifests, traefik routes, runtime config, install ledger, systemd/quadlet units, ssh_config, libvirt XML).

The CUE data-validation / configuration CLI (cue), pinned to v0.16.1. Use when working with the cue candy, installing the cue binary into a box or onto a target:local dev host, or running the offline schema-vendoring pipeline that feeds charly's egress validation.

The `vm` deploy substrate applies an InstallPlan INSIDE a running VM over SSH. `vm` is an EXTERNAL out-of-process deploy substrate (like local/android/k8s): the plan WALK runs in candy/plugin-deploy-vm via the shared charly/plugin/kit.WalkPlans over the GUEST SSHExecutor the executor reverse channel serves, and the host-side VM venue lifecycle (boot the domain, build the guest SSH executor, nested-pod-in-guest, teardown, the `charly vm` lifecycle) lives in the registered vmSubstrateLifecycle hook. The bare DeployTarget (Name+Emit) interface has two in-proc BUILD-ENGINE implementers (OCITarget, PodDeployTarget, invoked host-side from a lifecycle hook); the deploy lifecycle is the UnifiedDeployTarget interface, and ALL FIVE external substrates (local/vm/pod/k8s/android) route through the generic externalDeployTarget. Covers the DeployExecutor interface, SSHExecutor, VmDeployState persistence, and the host-side ledger. Source: charly/vm_deploy_lifecycle.go, charly/deploy_substrate_lifecycle.go, charly/deploy_tar

Pure renderer from VmSpec + VmCloudInit to NoCloud seed ISO (user-data + meta-data + network-config). Covers composeUsers adopt-merge, SMBIOS vs cloud_init additive channels, xorriso ISO emission, and charly_install.strategy state machine. Source: charly/cloud_init_render.go, charly/cloud_init_iso.go, charly/charly_install.go. MUST be invoked before editing cloud-init emission paths.

Go type reference for VmSpec and the discriminated-union source types (VmSource cloud_image | bootc | clone | imported | bootstrap). Documents every field, validation rules, and the adopt-user decision. Source files: charly/spec/cue_types_gen.go (generated), charly/schema/vm.cue, charly/vmshared/. MUST be invoked before editing VmSpec Go code or authoring vm.yml entries.

Schema reference for `kind: pod` and deploy entities — charly.yml entry shape, tree-position nesting, sidecars, pod networking. For verb-level operations see /charly-core:deploy.

Authoring reference for kind:vm entities in vm.yml. Parallel to /charly-image:layer and /charly-image:image. Covers the VmSpec schema, source.kind discriminator (cloud_image vs bootc), base_user adopt pattern, and step-by-step recipes for both source kinds. MUST be invoked before authoring or editing vm.yml entries.

MUST be invoked before any work involving: the `kind: android` schema kind, a `target: android` deploy (the external `deploy:android` substrate), the `apk:` layer package format (installing Android apps declaratively), the android deploy preresolver, an in-pod emulator OR a remote/physical adb-endpoint device, or nested `pod → android` deployment. The first-class Android device + app surface that sits above the `adb:`/`appium:` check verbs.

MUST be invoked before any work involving: `charly check` (image / live / run), the plan steps / `description:` field in a candy/box `charly.yml`, the disposable test-bed deploys in a project's `charly.yml`, the `ai.opencharly.description` OCI label (where the baked plan travels), the AI iteration harness loop, `kind: agent` (the agent grader) and the disposable R10 deploys (`disposable: true`, run via `charly check run <bed>`), or any plan step / Op authoring. Covers the unified `charly check` surface: three primary modes (image / live / run), ZERO in-core live-container probe verbs — every live-container check verb (cdp/wl/vnc/dbus/mcp/record/kube/adb/appium/spice/libvirt) is served out-of-process by its plugin candy, verb catalog (file/port/command/http/package/service/process/dns/user/ unix_group/interface/kernel-param/mount/addr/matching), runtime variable resolution (`${HOST_PORT:N}`, `${VOLUME_PATH:name}`, `${CONTAINER_IP}`, `${ENV_*}`), charly.yml overlay rules, authoring gotchas learned the hard way

CachyOS bootstrap VM (kind:vm cachyos-vm) — source.kind: bootstrap via cachyos-pacstrap-builder + pacstrap, btrfs rootfs, uefi-insecure. Plus the disposable check-cachyos-vm deploy. Lives in the overthinkos/cachyos submodule. MUST be invoked before editing cachyos-vm or its check bed.

Tailscale runtime wiring for target:local hosts. Sets `--operator=$account` + `--hostname=$(hostname -s)` so user-systemd ExecStartPost can run `tailscale serve` without sudo, and the tailnet device name stays in sync with the system hostname. Depends on /charly-infrastructure:tailscale (which installs the daemon). Self-gates on `systemctl is-active tailscaled` so it's a no-op in image-build / pre-auth contexts. Use when adding deploy-runtime tailscale wiring to a target:local host (canonical consumer: local.charly-cachyos) — distinct from the tailscale candy which only installs + enables the daemon.