charly-build

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

MUST be invoked for either Model Context Protocol direction: the declarative out-of-process `mcp:` check verb that probes advertised servers, or `charly mcp serve`, which exposes the reflected Charly CLI over Streamable HTTP or stdio. Covers URL rewriting, host-networked and published ports, tool annotations, read-only filtering, project fallback, authoring tools, and the `charly-mcp` deployment layer. The name avoids collision with harness slash commands and the `/charly-coder:charly-mcp` image skill.

The `charly docs generate` verb — the generator that renders the reference half of the opencharly.ai documentation site from this repo's canonical sources. The site lives in the standalone opencharly/docs repo: its deploy workflow runs this verb against the charly commit its .gitmodules pins, and regeneration is a docs PR that bumps that pin. MUST be invoked before any work involving the `charly docs` command, the opencharly.ai site's generated trees, the candy/plugin-docs runtime plugin, or the cross-reference rewriting that turns `/charly-<plugin>:<skill>` into site links.

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.

Image inspection showing resolved configuration as JSON. MUST be invoked before any work involving: charly box inspect command, viewing image configuration, or querying image metadata.

List components from charly.yml and filesystem. MUST be invoked before any work involving: charly box list commands, enumerating images, layers, build targets, services, routes, volumes, or aliases.

Use when a locally-built image has to reach the NESTED podman store inside a running pod — a candybox that runs its own containers. `charly box load` is the container twin of `charly vm cp-box`. Invoked as `charly box load <target> <image>`.

Post-build layer optimization via merging consecutive small layers. MUST be invoked before any work involving: charly box merge command, image layer reduction, merge configuration, or post-build optimization.

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 (`spec/schema/version.cue` → `#SchemaVersion`/`#SchemaFloor`), the declarative migration table (`candy/plugin-migrate/migrations.cue`, applied by the op-walker in `candy/plugin-migrate/engine.go`), the `LatestSchemaVersion()` load-time gate, or adding a new schema cutover as a migration-table entry.

Scaffold new candies, boxes, and whole projects with template files. MUST be invoked before any work involving: charly box new {project, box, candy} commands, creating new projects/boxes/candies, or scaffolding directories.

Fetch an image from its registry into local container storage so deploy-mode commands can read its OCI labels. MUST be invoked before any work involving: charly box pull command, the ErrImageNotLocal error, fetching images by short name / fully-qualified ref / @github.com/... remote ref, or recovering deploy-mode commands that fail with "image X is not available locally".

Use when @github layer/namespace pins drift across repos and the resolver emits "referenced at multiple versions" warnings — `charly box reconcile` aligns every pin of a repo to one version (clearing the warnings). Invoked as `charly box reconcile`.

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.

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.

MUST be invoked before any work involving: charly box validate command, validation rules, common validation errors, or checking charly.yml and layer definitions.