charly-internals

Multi-agent support in OpenCharly across agent harnesses (Claude Code, Codex, Kimi) — sub-agents, dynamic workflows, agent teams, fresh validator sessions, and how each drives the existing `charly check` disposable beds to test and verify. MUST be invoked before authoring or invoking an charly sub-agent / dynamic workflow / agent team / fresh validator session, wiring agent-lifecycle hooks, or asking "which primitive should drive the R10 beds?".

MUST be invoked before any work involving: OCI label contract, Capabilities / BoxMetadata struct, CapabilityLabelMap completeness check, LabelService structured round-trip, source-less deploy via `charly fleet from-box`, or adding a new OCI label. Developer-facing; users author via `/charly-image:layer` and `/charly-image:image`.

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: sdk/vmshared/cloud_init_render.go, sdk/vmshared/cloud_init_iso.go, spec/exec/charly_install.go. MUST be invoked before editing cloud-init emission paths.

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.

`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.

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 candy/plugin-fleet/egress.go, the vendored schemas under candy/plugin-egress/egress-schemas/vendor/, the ValidateEgress / registerVendoredEgressKind path, the offline CUE vendoring pipeline, or adding an egress schema for any written artifact (cloud-init, kubernetes manifests, traefik routes, runtime config, install ledger, systemd/quadlet units, ssh_config, libvirt XML).

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/.

Use when committing, branching, pushing, opening PRs, or landing a change with gh — the feat/-branch, R10-gated, PR-ONLY, org-workflow-validated, never-force-push landing across the main repo, its box submodules, the marketplace repo, and the proxy-resolved sdk contract module (no submodule — consumed at the pinned go.mod require). A direct push to main is FORBIDDEN and mechanically disabled; the org-wide `charly/pr-validator` GitHub Actions gate validates the PR and, on PASS, its `auto-merge` companion squash-merges and tags. Covers sync-to-upstream, branch/worktree pruning, the fork+PR path, cross-repo @github landing order, and the CalVer-generated-at-merge rule.

Go CLI development: building the charly binary, running tests, understanding the source code structure. Owns the Schema Driven Design (SDD) operationalization — the spec/schema/*.cue → `task cue:gen` generation pipeline and the generation-coverage current state. MUST be invoked before reading or modifying any Go source file in charly/ or any spec/schema/*.cue schema file.

How to check charly's Go source for CLAUDE.md compliance + code quality and fix what's found. Covers golangci-lint v2 (the deterministic backbone) + the charly/.golangci.yml linter set, gopls, go vet, gofmt; the .go compliance checklist (R3 duplication, R4 ad-hoc workarounds, R5 dead/stale paths, repo invariants); the legitimate-pattern allowlist that kills false positives; triage + adversarial verification; and how to fix findings as a handful of large thematic R10-gated cutovers. MUST be invoked before any Go code-quality audit, golangci-lint run, dupl/duplication check, or CLAUDE.md-compliance sweep of charly/.

InstallPlan is the shared deployment IR. Use for the external local, VM, pod, Kubernetes, and Android deploy targets; executor reverse-channel walking; host-engine steps; guest SSH execution; pod overlay builds; Kustomize generation; Containerfile emission; deploy wire types; or any new step, target, or reverse operation. MUST be invoked before changing the InstallPlan, build target, external deploy target, lifecycle preresolution, overlay, Kubernetes generation, or SDK deploy-wire implementation.

Translation facade from VmSpec + LibvirtDomain to libvirt domain XML (via the libvirtxml library) and QEMU argv. Covers RenderDomainXML, device emission (passt backend, portForward attribute order, virtio-gpu defaults), firmware plumbing, and LibvirtDomain schema shape. Source: sdk/vmshared/libvirt_yaml.go, candy/plugin-vm/libvirt_yaml_bridge.go, sdk/vmshared/libvirt_helpers.go, sdk/vmshared/qemu_render.go. MUST be invoked before editing libvirt XML emission.

Go file map for the host side of the `local:` (external deploy:local plugin) + VM deploy execution surface. Files: deploy_chain.go, sdk/kit/sshconfig.go, sdk/vmshared/hostdistro.go, install_ledger.go, builder_run.go, shell_profile.go, reverse_ops.go, candy/plugin-fleet/deploy_ref.go (the former `charly/deploy_ref.go` is DELETED, K-wave 2). 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).

UEFI firmware (OVMF_CODE + OVMF_VARS) path resolution for VMs. Covers the per-distro path table (Fedora vs Arch vs Debian/Ubuntu), per-VM NVRAM copies pattern, secure-boot variants, and the "empty strings = skip loader/nvram" contract for firmware: bios. Source: sdk/vmshared/ovmf_paths.go. MUST be invoked before editing UEFI firmware resolution.

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.

R1 mandatory failure analysis agent. MUST be invoked before any remediation when an unexpected error, warning, or anomaly occurs. Performs the 8-step root cause analysis process.

Skill maintenance guidelines: when and how to update skills, root rulebooks, and README.md. Use when updating documentation, feeding back operational insights, or auditing skill coverage.

Operationalization of CLAUDE.md R1-R5 plus the RDD and ADE pillars — the engineering-discipline rules that come BEFORE runtime verification. Covers: (R1) RCA on every failure via /charly-internals:root-cause-analyzer; (RDD) prove every HIGH-RISK assumption on a disposable bed BEFORE editing; (ADE) the spec-is-the-test `plan:` acceptance discipline; (R2) no "pre-existing" / "out of scope" / "follow-up PR" classifications; (R3) no code duplication, generic over ad-hoc; (R4) no ad-hoc workarounds; (R5) hard cutover deletes the deprecated path AND every stale reference in the same commit. MUST be invoked when a failure / warning / anomaly surfaces, when a plan rests on a high-risk unproven assumption, when a pattern is about to land in a second surface, when a sleep / retry / magic-number is tempting, or when a cutover commit is about to ship.

The external VM deploy substrate applies InstallPlan inside a guest through the reverse-channel SSH executor. Use for plugin-deploy-vm, VM boot and guest readiness, Charly delivery, nested pods, lifecycle preparation and teardown, VmDeployState persistence, DeployExecutor, or the generic pluginDeployTarget and UnifiedDeployTarget seams (S3b: candy/plugin-fleet's Invoke(OpDeployDispatch), replacing the deleted grpcSubstrateLifecycle/externalDeployTarget). SSHExecutor, VmDeployState persistence, and the host-side ledger. Source: candy/plugin-deploy-vm/lifecycle.go, charly/unified_targets.go, charly/deploy_target_dispatch.go, candy/plugin-fleet/deploy_target.go, spec/exec/deploy_executor*.go, sdk/deploykit/vm_deploy_state.go, candy/plugin-vm/vm_util_copies.go. (The former charly/fleet_add_cmd_vm.go is DELETED, K-wave 2.) MUST be invoked before editing VM-target deploy code.

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: spec/spec/cue_types_gen.go (generated), spec/schema/vm.cue, sdk/vmshared/. MUST be invoked before editing VmSpec Go code or authoring vm.yml entries.