@eubound/ax

Local-first EUBound AX harness for external customer-controlled coding agents.

The harness does not upload repository source code. It scans locally, sends only a synthetic smoke prompt when smoke is run, verifies receipts, audits obvious logging/fallback risks, and writes eubound-proof.json.

npx @eubound/ax init
npx @eubound/ax doctor --json
npx @eubound/ax contract --json
npx @eubound/ax scan --json
npx @eubound/ax fetch-jwks --json
npx @eubound/ax validate --json
npx @eubound/ax smoke --json
npx @eubound/ax verify --json --jwks .eubound/jwks.json
npx @eubound/ax audit-logs --json
npx @eubound/ax proof --json

Offline verification requires trusted EUBound JWKS. --allow-embedded-key is a development-only escape hatch for local fixtures and is not production proof. doctor --json lists every AX networked command and explicitly declares source, repository-metadata, customer-prompt, customer-completion, API-key, and prompt/completion-storage behavior for that command. proof requires the signed receipt artifact from smoke or --receipt and recomputes verification against trusted JWKS instead of trusting .eubound/verify.json. Generated proof packs include sha256: hashes for the local AX evidence artifacts they were built from, without embedding source code, prompts, or completions. validate --json recomputes those non-null evidence hashes and blocks proof if local AX evidence drifted after proof generation.

Required runtime variables for smoke tests:

export EUBOUND_API_BASE_URL=https://api.eubound.eu/v1
export EUBOUND_API_KEY=...
export EUBOUND_MODEL=mistral-small-alpha
export EUBOUND_POLICY=EU_HARD_BOUNDARY

Release is intentionally guarded from the repository root:

EUBOUND_API_KEY=... just ax-publish-dry-run
npm login --registry https://registry.npmjs.org/
EUBOUND_API_KEY=... just ax-publish

The publish script forces the npmjs registry, checks package contents, installs and smoke-tests the packed tarball, runs authenticated production readiness before publish, and reruns full readiness after publish. The current Forgejo release path uses AX_NPM_PROVENANCE=off because npm provenance requires supported cloud-hosted CI/CD. Use AX_NPM_PROVENANCE=required only from a future supported npm OIDC publisher.

The repository just ax-check gate also installs the packed tarball into a temporary consumer project and runs the installed eubound-ax binary, so package file selection, package metadata, and bin wiring are tested before publication. After publication, just ax-production-readiness installs @eubound/ax@<version> from npm and runs the same binary smoke so public metadata alone cannot count as release readiness. The same readiness gate also validates linked schema, recipe, and error catalog shapes, then compares manifest-embedded error_codes with the linked error catalog so failure semantics cannot drift across AX contract surfaces. The live gate also requires the full AX error-code vocabulary.

CI release uses .forgejo/workflows/ax-publish.yaml with NPM_TOKEN and EUBOUND_API_KEY secrets on the EU runner.

Documentation Map

• Map key: packages-ax-cli
• Documentation map: ../../docs/documentation-map.md
• Scope: Local-first AX CLI command behavior and safety boundaries.
• Audience: External coding agents, customer developers, and CLI maintainers
• Recommended related docs:
  • AX documentation
  • LLMS.txt
• Update rule: Review this README whenever CLI commands, output files, proof semantics, or network behavior changes.
• Last map sync date: 2026-05-15
• Update attempt log:
  • What was attempted: Add documentation for the initial dependency-light AX CLI package.
  • What failed: Nothing known in this update.
  • What worked: The README documents local-first behavior, commands, and required smoke-test environment variables.