charly-internals

Multi-agent support across harnesses (Claude Code, Codex, Kimi) — sub-agents, dynamic workflows, agent teams, fresh validator sessions, and how each drives the `charly check` disposable beds. Use before authoring/invoking a sub-agent, dynamic workflow, agent team, or fresh validator session, or wiring agent-lifecycle hooks.

OCI label contract, Capabilities/BoxMetadata struct, CapabilityLabelMap completeness, LabelService round-trip, source-less deploy via `charly fleet from-box`, or adding an OCI label. Use before any of those.

Pure renderer from VmSpec + VmCloudInit to NoCloud seed ISO (user-data + meta-data + network-config). Covers composeUsers adopt-merge, SMBIOS vs cloud_init channels, xorriso ISO emission, charly_install.strategy. Use before editing cloud-init emission paths.

The 'Hard Cutover by Default' policy for schema changes, API renames, and deprecations — forbidden patterns, required deliverables, rationale, examples. Use when planning or reviewing a breaking change.

`disposable: true` is the ONE and ONLY authorization for autonomous destroy + rebuild via `charly update`. Use before any task involving `charly update`, live verification on rebuildable targets, or marking a VM/container deploy safe-to-nuke.

CUE EGRESS validation — validating (and where valuable, generating) the config files charly WRITES to a system before the bytes hit disk. Use before working on candy/plugin-fleet/egress.go, the vendored egress schemas, ValidateEgress, or adding an egress schema.

Containerfile generation: `charly box generate` output, multi-stage builds, intermediate images, the .build/ directory. Use when debugging/understanding generated Containerfiles or reading charly Go source.

The feat/-branch, R10-gated, PR-ONLY, org-workflow-validated, never-force-push landing across the main repo, box submodules, marketplace, and the proxy-resolved sdk contract module. Use when committing, branching, pushing, opening PRs, or landing with gh; covers sync-to-upstream, fork+PR, cross-repo @github order, CalVer-at-merge.

Go CLI development: building the charly binary, running tests, source structure, and the SDD operationalization (spec/schema/*.cue -> `charly task cue-gen`). Use before reading/modifying charly Go source or spec/schema/*.cue.

Check charly's Go source for AGENTS.md compliance + code quality: golangci-lint v2, gopls, go vet, gofmt, the .go compliance checklist (R3/R4/R5), the legitimate-pattern allowlist. Use before a Go code-quality audit or lint sweep.

InstallPlan is the shared deployment IR — external local/VM/pod/Kubernetes/Android targets, executor reverse-channel, host-engine steps, guest SSH, pod overlays, Kustomize, Containerfile emission, deploy wire types. Use before changing the InstallPlan or any deploy target.

Translation facade from VmSpec + LibvirtDomain to libvirt domain XML and QEMU argv — RenderDomainXML, device emission (passt, portForward, virtio-gpu), firmware plumbing, LibvirtDomain schema. Use before editing libvirt XML emission.

Go file map for the host side of `local:` + VM deploy execution — deploy_chain.go, sshconfig, hostdistro, install_ledger, builder_run, reverse_ops, deploy_ref. Use before reading/modifying those files or debugging local/VM deploy.

How the OpenCharly skill/marketplace corpus is GENERATED, refreshed, and consumed — the ownership split, regeneration command + schema prerequisite, deploy drift gate, daily refresh, per-harness caches. Use before editing the corpus or refs list.

UEFI firmware (OVMF_CODE + OVMF_VARS) path resolution for VMs — per-distro path table, per-VM NVRAM copies, secure-boot variants, the empty-strings=skip contract. Use before editing UEFI firmware resolution.

Authoring/modifying a charly PLUGIN — a candy with a `plugin:` block contributing Providers (verbs/kinds/deploy-targets/steps/builders/commands), its CUE schema, builtin or external. Covers the unified Provider model, per-plugin CUE-schema contract, SDK, loader.

The out-of-tree charly ENGINE plugin serving engine:nerdctl (verb:nerdctl / command:nerdctl) — every engine op delegates to container.InvokeEngineOp. Use when working with the engine:nerdctl provider, the plugin-nerdctl candy, or the engine provider-class placement model.

How the opencharly GitHub org and opencharly/.github (dotgithub) configuration and workflows drive every repository — the ONE org ruleset, the org-required `charly/pr-validator` workflow, native auto-merge, tag-on-merge CalVer, and the per-repo settings. Use when setting up a NEW repository, adding or explaining landing/CI workflows, or distinguishing what the org configures automatically from what a repo must add.

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

Skill maintenance: 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. Use when a failure/warning/anomaly surfaces, a plan rests on a high-risk unproven assumption, a pattern is about to land in a second surface, a sleep/retry/magic-number is tempting, or a cutover commit is about to ship.

The external VM deploy substrate applies InstallPlan inside a guest via the reverse-channel SSH executor — plugin-deploy-vm, VM boot/readiness, Charly delivery, nested pods, lifecycle, VmDeployState, DeployExecutor, the pluginDeployTarget/UnifiedDeployTarget seams. Use before editing VM-target deploy code.

Go type reference for VmSpec and the discriminated-union source types (cloud_image | bootc | clone | imported | bootstrap) — every field, validation rules, the adopt-user decision. Use before editing VmSpec Go code or authoring vm.yml entries.