Command alignment

Tracking issue: #301. The CLI reference documents the implemented interface and the command conventions govern future changes. This page distinguishes implemented alignment from proposed follow-ups.

Implemented entry-point alignment (unreleased)

Command	Contract
kmx ctx [--check]	List named workspace destinations only; optional bounded local-context/anonymous registry checks. No selection or switching. targets remains runtime capabilities.
kmx context show	Read the effective context, selection source and posture.
kmx context use <context>	Remember KMX's access selection after the existing context guard; never change kubectl current-context.
kmx local up	Provision the local kind environment, model and Orka; no agent. The existing --step choices remain.
kmx local down	Delete the named local kind cluster, including its data, under the existing context/container-engine guard.
kmx aks up/down	Retain the guarded AKS provisioning/teardown operations and historical ownership records; hidden from root help and completion.

Bare context and local display help. Canonical commands use the existing operations, settings, saved-selection file and guards. Root up, down, the AKS lift alias and lift down are removed outright, with no compatibility aliases or retirement stubs. The old context-selecting ctx alias remains removed; the new ctx is a list-only named-destination view and refuses legacy switching syntax. Use context show/use, local up/down and aks up/down respectively. Tagged v0.4.1 used the old context/local spellings; the grouped commands require a newer build.

The redirected context report retains its source: kmx ctx provenance label for saved selections as a compatibility format. That label is not a next-step command. Generated selection and local teardown instructions use the canonical spellings. Invocation-specific confirmation preserves the caller's selectors and exact arguments.

Generated local commands preserve KIND_CLUSTER, CONTAINER_ENGINE and --context. AKS retry/teardown instructions use the common effective-option renderer, including --byo only for the existing ownership mode; Azure setup and cleanup diagnostics say AKS rather than agent Lift. The carried scripts use these native instructions when invoked by KMX. Standalone script use has no KMX ownership receipt, so its fallback names the actual script with quoted arguments instead of a deleted Make target or an invented BYO recovery route.

Implemented workflow command mapping (unreleased)

Previous route	Current route	Contract
agent create [name] / create --live	Removed	No live resource/bundle creation, previews or wizard. Root create NAME authors native workspace source offline.
agent chat <name> [message...]	chat <name> [message...]	Interactive Orka session, not workspace execution.
agent run [<bundle-dir>]	run --agent NAME	Bundle mode removed; independent live Orka Task/answer/result contracts retained. Suite-owned Agents refuse legacy invocation.
agent show <name> / agent list	orka show <name> / orka list	Live Orka detail/inventory, not workspace inspection. Show still requires namespace.
agent evaluate/lift/retire/status / bundle ...	Removed	Old commands/readers/writers/receipts removed outright, no stubs or migration. Suite status/retirement remain unavailable.
agent verify / bundle verify	Removed	Legacy replay/judges and RecordedExecution are removed without a native replacement.
agent eval diff <before.json> <after.json>	eval diff <before.json> <after.json>	Offline receipt comparison, not evaluation execution.
agent eval from-sessions <session-uid>...	eval from-sessions <session-uid>...	Private reference-case preparation, not execution.
suite push --workspace DIR REF / suite push REF	push [--workspace DIR] REF	Exact prepared workspace graph publication; discovers the nearest ancestor workspace.yaml, or selects an exact root without fallback with --workspace.

The entire kmx agent group is removed, including its hidden edit stub, with no aliases or retirement stubs. Use kubectl to edit live Orka resources. Root status and orka status retain the same table-only Orka runtime report; There is no suite status/retirement replacement. Root eval executes a full native workspace inventory with explicit target/output selection and exactly one runtime-derived model binding: Orka --inference or packaged kagent --bindings. Standalone packaged-reference evaluation remains unimplemented. Root digest lift deploys a packaged native suite with explicit private evidence, GET-only --plan, strict guarded apply and explicit source-only --promote; no model/runtime override, update or adoption. task result and suite push DIRECTORY REFERENCE, suite build/diff/pull/validate are unchanged. These spellings require a current development build; tagged v0.5.1 retains the agent routes. Workspace authoring/publication are unreleased. Existing operation handlers, arguments, applicable flags, stdout and exit contracts are preserved; this is not a receipt or bundle migration.

Independent evaluation helpers

Offline eval diff compares strict full-passing native Orka/kagent suite evidence only; old normalized Orka/kagent/AgentSessions bundle receipts are unreadable. Zero is comparison, not a new pass or promotion gate.

eval from-sessions UID... --sessions SOURCE --assertions CASE.yaml --out FILE remains private read-only reference extraction/export, not execution. Existing output appends atomically; duplicates refuse. No recorded payloads are persisted. RecordedExecution, legacy bundle Sessions evaluation/replay/judges and their consumers are removed. There is no native reference-manifest consumer; author native workspace cases. See reference extraction.

Named workspace destinations

Optional workspace-root kmx.yaml supplies selectors to existing eval/lift --to NAME. Individual eval may use its explicitly saved evalTarget; digest Lift has no implicit destination. Resolve once to concrete values, print their source, then pass those copies through the operation. Editing config during confirmation cannot redirect an invocation. Source, runtime, binding-byte and remote-object checks remain independent. Explicit invocation flags override corresponding saved fields, including an explicit false transport flag. Config is not packaged or included in source identity. Explicit digest Lift without --to never discovers a workspace. See configuration and checks.

No composed workspace Lift is enabled: a digest/private evidence, explicit push reference and eval output are still required. Kagent remains standalone; do not include it in composed Lift until candidate-scoped evaluation/cleanup is qualified.

Offline suite workspace

create <name> --model <model> --instructions <file> [--workspace <directory>] authors one tool-free native-Orka member offline by default. Model and an instructions file are required; description is optional. Create and push share nearest-ancestor workspace discovery. An exact --workspace override initializes a missing workspace without a prompt. Without a workspace, terminal create asks Start one here? [Y/n]; nonterminal or redirected use refuses with an explicit --workspace hint. Invalid nearest markers refuse without fallback; an existing one-member workspace refuses a second member without changing source.

Live create/previews/wizard and live-only flags are removed outright, unknown before config. No runtime/model bootstrap belongs in workspace create. Help/completion is inert; authoring needs no cluster, builder or model call.

push <reference> discovers the nearest ancestor workspace.yaml; --workspace <directory> instead selects that exact directory, without fallback. Missing, invalid or unreadable workspace selection refuses. The command prepares that member and its shareable authored cases as an ordinary AgentSuite, then copies the exact OCI manifest/blob graph. A single stderr line names the absolute workspace and prepared OCI manifest digest; result stdout is unchanged. Native member image requirements are empty. Registry auth, plain-HTTP and non-atomic tag replacement remain as documented. Old suite push <directory> <reference> retains extracted-artifact transfer behavior without workspace discovery; suite push no longer accepts --workspace or one positional reference. Root push refuses two positional arguments. Root eval --to-context CTX --out FILE performs offline workspace/inventory/ output preparation before configuration, then one guarded runtime-specific placement and one fresh Task per ordered case. Orka requires --inference provider:NAME; packaged exact-v0.10.3 Go kagent requires author-owned --bindings FILE, unsecure auth and no --result-port. Only full passing metadata is exported once to a private file outside workspace/cache; failure, unknown, drift, cancellation or output error stops later sends. No package reference, subset or content output is accepted. Authored llmJudge requires explicit --judge-base-url, optional --judge-key-env and authored model/version/threshold. Two independent samples must agree on the threshold side; errors/splits stay unknown. Judges use the fixed modern Chat Completions request shape: a 1024 max_completion_tokens budget, no temperature override and no error fallback. Evidence binds that style; old judge receipts require fresh evaluation. Judgment shares the case deadline and is followed by attribution rechecks. Passing rows bind judge identity, endpoint configuration hash and both scores without reasoning or raw judge URLs; recovery commands omit the endpoint. Text-only receipt encoding is unchanged. Development AgentSessions continues to refuse judges. push --evaluation FILE checks runtime-specific private receipt coherence and exact manifest S before publication; ordinary push is unevaluated. Receipts are unsigned observations, not policy gates. Dedicated shards qualify bounded Orka and kagent workspace scenarios; the native Orka inventory includes two text cases and one open-ended rubric case sharing the pinned AIKit workload, with no timeout increase. Kagent retains its two text cases. Hermetic runner tests are not live judge proof; this is not general runtime support. Root lift REF@sha256:DIGEST consumes that explicit private full-pass evidence for source-free, deploy-only packaged Orka or exact-kagent placement. Bounded qualification covers Orka exact reuse and kagent fresh-target creation, not every promotion, creation or partial-outcome path. See suite workspace.

Vocabulary

Decided: keep Create → Prove → Lift. Root digest Lift deploys an exact packaged native suite using private full-passing evidence, not old bundle state. Chat /lift and console Lift only print Lift moved: kmx lift <ref>@<digest> --to-context … --evidence …. No release GUI or live-copy fallback remains. Standalone AKS up/down and internal App.Lift cloud setup remain independent. Removal does not change AKS ownership, recovery or teardown behavior. Ready/answered/evaluated are distinct evidence.

• Context: a kubeconfig access selection; not a durable cluster identity.
• Target: selected runtime, cluster identity, namespace and deployment destination, following #238.
• Runtime adapter: KMX's integration with an execution platform.
• Inference provider/backend: an independent model-access route.
• Provision infrastructure; install runtime software; create source; eval full cases; push exact graph; lift an evaluated digest. Live Orka show/list and independent run/chat remain separate.
• Ready, answered and evaluated are different evidence. Unknown is not absent; retry resubmits; result only retrieves.
• Suite status/retirement remain unavailable. Lift does not transfer live state, sessions or memory, delete source, perform cutover or grant teardown authority.

Audit and existing work

The command inventory is pinned by the command-tree and entry-point tests in cmd/kmx. Context show/use split read and selection operations; local up/down scope the existing kind operations. Root discovery hides the AKS compatibility group, which remains directly callable. Removed root aliases are neither registered nor suggested by help or completion. Help and internal completion are not operational leaves.

Other implemented alignment in development builds includes quickstart --interactive (-i) and intrinsically interactive root chat. quickstart-wizard is a retirement stub, and chat no longer accepts --interactive; tagged v0.4.1 still uses those older forms. kmx targets is the read-only runtime capability view. Plane commands, administration, migration, model overlays and the hello-to-governed demo are removed, not candidates for regrouping. Current native setup does not deploy a model plane.

Sources: command constructors and completion in cmd/kmx, chat registry/dispatch in chat_slash.go and runtime_session.go, console actions in agent_tui.go, current guides, Make and embedded script recovery messages. This is a source/help audit, not a new live-cluster proof.

The review identified mixed singular/plural groups, noun-only mutations, inconsistent inspection verbs, local meaning cluster-configured inference, different prompt/file flags, different bundle/live target flags, and preview modes with different file/network/cluster effects. It also found stale status formats, namespace claims, governance wording and deleted Make recovery targets. These are tracked in #301 rather than silently treated as part of this slice.

Related work	Ownership retained there
#194, #248	Product story and lifecycle vocabulary.
#223	Cloud extraction, infrastructure ownership, recovery and teardown.
#224, draft #225	Target identity, runtime selection, lifecycle contracts and extensions.
#238, #294	Runtime qualification and supported operations.
#289	Read-only capability reporting, implemented as kmx targets.
#276, #286	Shared operations and authoring/execution/adapter/UI extraction.
#284	Historical model-plane work; the plane is now removed.
#292	Verbosity levels and redaction.
#299, #300	AgentSuite artifact and validation contracts; suite validate remains.

Merged #203 is the precedent for separating AKS provisioning from agent lift. #301 owns command consistency and compatibility over these operations, not parallel implementations.

Proposed follow-ups — not current syntax

Interactive controls should share resource/action names: /agent show, /agent chat, /agent use, /agent tools configure, /agent inference configure, and console /context use local|remote <context>. Interactive /lift and console Lift are retired move notices, not release workflows. Do not add a grouped release GUI or live-copy fallback. Use /inference use cluster|host-copilot|host-foundry to distinguish execution routes, /exit with /quit compatibility, and /verbose on|off coordinated with #292. Retain keyboard shortcuts and advertise only supported controls.

Proposed flag alignment: --prompt/--prompt-file instead of --task, --instructions-file instead of file-valued --instructions. Keep report --output separate from artifact --out; preserve raw and answer-only stdout.

Remaining decisions

1. Infrastructure hierarchy: #223 owns the long-term Azure interface; target aks is not the chosen final shape. aks up/down remain callable compatibility routes, hidden from root help and completion.
2. Runtime setup: retain orka install/status pending agreement on a generic runtime setup family; a name cannot imply installer support.
3. Capability view: kmx targets is implemented for #289; retain that spelling and its read-only/offline-default contract rather than adding synonyms.
4. Authoring/execution verbs: default create now authors offline; live create is removed. Reconcile evaluate with test and root run with canvas-service run start through #276 and its authoring/execution work. Their scopes differ.
5. Runtime selection: settle operator/saved configuration versus public selection through #224/#238; retain current capabilities in rename slices.
6. Target flags: decide --to-* versus --context/--namespace with runtime-specific bindings, multi-target status, namespace ambiguity and alias conflicts.
7. Preview terms: distinguish artifact rendering, no-write planning and server validation, including downloads/cache/local files and which resources admission actually checks. Do not mechanically alias --no-apply modes.
8. Remaining compatibility routes: follow the announced breaking-release policy for future removals. The root context/local/AKS aliases are already removed outright; no retirement stubs remain. The hidden AKS group is retained.

Keeping future work aligned

AGENTS.md records the contributor rules alongside the command conventions. For each implemented slice, update command registration, help, completion, interactive labels where applicable, generated next/recovery commands, primary docs, compatibility tests and CHANGELOG together. Use existing operation handlers. Keep historical records and deliberate compatibility fixtures distinct from current examples.

Tests must cover more than names: read-only behavior, saved selection and refusal, context/namespace/engine preservation, mode conflicts before operation loading, stdout versus stderr, and operation result/exit compatibility. Help/completion must not perform operational mutations. Doc-link/map and boundary checks should include newly added files.