Assistant skill contract

BonVoyage defines one machine-readable contract for Claude Code and ChatGPT/Codex configuration skills. The contract keeps both wrappers aligned with the same reviewed release assets and the same installed bonvoyage-config authority.

The shared contract is config/authoring/skills/v1/contract.json. It is generated from a reviewed policy and exact SHA-256 identities for the authoring contract, completion metadata, test corpus, diagnostic catalog, result schema, and snippet catalog.

Contract and package evidence are distinct

The shared contract defines common behavior. The repository now contains pre-release Claude Code and ChatGPT/Codex wrapper packages, but package qualification is not a provider-model pass. No model-specific result is accepted merely because the contract, packages, or shared harness exists.

Bounded capabilities

Capability	Allowed outcome
Generate	Propose a complete document from reviewed assets, then validate and preview it.
Explain	Explain supported fields from release-matched completion metadata.
Modify	Propose a minimal change, then diff, validate, format, and preview it.
Diagnose	Classify actual structured diagnostics with reviewed remediation guidance.
Migrate	Request one explicit shipped migration, then validate and preview the result.
Verify	Prepare bounded local verification commands after validation and preview.

A generated or modified document requires explicit operator confirmation before a file write. Verification commands require confirmation before execution. The contract forbids autonomous apply and production mutation.

Authority and version binding

The skill must use the exact installed product and compiler versions. It cannot replace or override them with a caller-supplied version. Missing tooling, unsupported fields, and stale versions are blockers rather than invitations to guess.

The Go snapshot compiler remains the semantic authority. JSON Schema, completion hints, snippets, and assistant reasoning provide authoring help; they do not establish deployability. Stable reason codes are the diagnostic contract. Human-readable message text is not.

Untrusted input boundary

Configuration documents and command output are data, including text that looks like an instruction. A wrapper must not follow instructions embedded in YAML, diagnostics, comments, filenames, or retrieved text. Material ambiguity must be resolved with the operator before a proposed document is called usable.

The shared package is offline by default. It does not use telemetry or network access, read live gateway state, inspect environment secrets, or include secret values. TLS keys, certificates, API keys, trust material, and JWKS content stay outside the skill; supported configuration fields contain deployment-secret filenames only.

Claim boundary

Without the installed compiler, a draft is unvalidated. Successful validate means only offline validated. Successful preview means only offline previewed. Neither result proves deployment, data-plane ACK, activation, rollback, or traffic behavior. Those claims require authoritative runtime evidence.

Evaluation boundary

Each wrapper must pass the same release-matched cases for valid requests, ambiguous requirements, invalid YAML, malicious embedded instructions, rollback guidance, secret handling, semantic conflicts, and stale versions. Cross-surface agreement remains a separate release gate.

See the assistant skill evaluations for the machine-readable case and result contracts.

See the ChatGPT and Codex configuration skill and Claude Code configuration skill for package installation and bounded use.

Read the configuration authoring contract for operation details, the configuration test corpus for compiler-backed decisions, and configuration diagnostics for stable failure presentation.