# Changelog

All notable changes to the `hexstellar` CLI and Python client. This file is the source for the `Changelog` link in
the package metadata, so aggregators (Libraries.io, Snyk Advisor, deps.dev) can read the release history.

The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- **Responsive interactive welcome.** Running `hexstellar` in a human terminal now opens a premium,
  width-aware HexStellar panel with the double-hex mark, the `H Ξ X S T E L L Λ R` wordmark, and three
  real next actions. Rich terminals receive the enhanced renderer when `rich` is already available; clean
  zero-dependency installations receive an equivalent Unicode fallback. JSON, piped, and non-interactive
  invocations retain the existing machine-readable behavior.

### Changed
- **Correct managed-versus-licensed acceleration model.** Agent guidance now states that Cortex executes supported
  computation with HexStellar acceleration on managed infrastructure, while Enterprise licenses the customer-deployed
  runtime for compatible application, framework, LLM, and compute integrations under NDA. Narrow command and error
  answers no longer repeat an unrelated Enterprise disclosure; measured performance and energy claims remain scoped.
- **Light-terminal contrast preserved.** The enhanced welcome inherits the terminal foreground for text instead of
  forcing white, keeping the wordmark and shortcuts readable on both light and dark terminal themes.

## [1.0.0] — 2026-08-26

The first full public release. `0.0.1` on PyPI is a name-reservation placeholder and carries none of the
functionality below.

### Changed
- **Modular architecture (internal — zero behavior change).** The client is organized as the `hexstellar/`
  package, one concern per module: contract constants (`_meta`), config & identity (`_config`), RFC 9457 error
  boundary (`_errors`), the single-chokepoint HTTP transport (`_transport`), the HXSB binary lane (`_hxsb`),
  bundled-data/manifest resolution (`_manifest`), problem intake & structural validation (`_problem`), output
  shaping & context-window protection (`_output`), deferred jobs (`_jobs`), the large-problem storage lane
  (`_storage`), the public Python API (`api`), one module per CLI concern under `commands/`, and the thin
  parser/dispatch adapter (`cli`). Both public contracts are unchanged and golden-tested byte-for-byte:
  `import hexstellar` (same functions, same `__agent_metadata__`, same docstring) and the `hexstellar`
  console entry point (same commands, flags, output, exit codes). `python -m hexstellar` and direct-script
  invocation of `hexstellar/__main__.py` both work; internal helper names remain importable through a lazy
  compatibility facade.

### Added — operations & pipelines
- **Automated backoff everywhere.** Idempotent (GET) requests retry transient faults (network, 429/502/503/504)
  with exponential backoff + jitter, honoring `Retry-After` under a 120 s ceiling; the solve/batch lanes share the
  same attempt budget. Configurable: `--max-retries` / `HEXSTELLAR_MAX_RETRIES` (1–10, default 3).
- **Graceful interrupt.** `Ctrl+C` during a job wait detaches with the resume/cancel recipe; a second `Ctrl+C`
  within 5 s — or `--cancel-on-interrupt` / `HEXSTELLAR_CANCEL_ON_INTERRUPT=1` for CI — cancels the job on the
  server before exit, so an aborted pipeline never leaves compute running.
- **`hexstellar configure`** — interactive first-run wizard (hidden key prompt, online validation, 0600 config).
  Precedence is strict and documented: flags > `HEXSTELLAR_*` env > config file (`--api-key` for one-off runs).
- **Shell tab-completion** — `hexstellar completion bash|zsh|fish`, generated by introspecting the live parser
  (a new flag ships with its completion in the same release); `--install-completion` wires it in idempotently.
- **`--debug`** — opt-in full traceback on unexpected errors; the default stays a clean RFC 9457 envelope.
- **Streamed batch intake** — NDJSON is consumed line by line under a running byte cap, so peak memory tracks
  the largest line, never the whole workload.

### Added — agent-first surface

- **Adaptive `demo`** — zero-setup verification that always succeeds honestly: with network it solves a small
  problem live on the public anonymous sandbox (`mode: "live"`); with no egress it returns a bundled,
  precomputed, engine-verified result (`mode: "offline_precomputed"`), re-verifies that result locally with
  plain arithmetic, and hands back a ready-to-paste `curl` for a live run.
- **Python API** — `import hexstellar`: `solve`, `estimate`, `verify`, `demo`, `health`, `pricing`, `examples`,
  `example`, `tools`, `runtime_capabilities`. Every function returns a dict (answer or RFC 9457 error envelope)
  and never raises for a remote fault. Also runnable as `python -m hexstellar`.
- **`tools --target openai|anthropic|json-schema|mcp`** — typed tool specifications for teams running their own
  agent framework, derived from the published capability manifest.
- **MCP server** — `hexstellar mcp` exposes the service's tools over stdio (`--read-only` limits it to the free
  ones); the API also speaks MCP at `/api/v1/mcp`.
- **`solve --dry-run`** — free preflight: local schema validation, the service's no-charge estimate, and the
  exact request that would be sent. No upload, no solve, no charge.
- **`verify`** — free service re-check of supported candidate feasibility/objective properties, from
  HexStellar or any other solver.
- **`batch`** — a whole workload in one process: NDJSON problems in, NDJSON results out, with concurrency.
- **`--max-compute-units`** — an economic firewall: estimate first, refuse to solve past the budget, fail closed.
- **Discovery surfaces** — `agent-info` (the CLI's own contract), `pricing`, `capabilities`/`schema`, `examples`
  (live verified transfer recipes), `spec`, `prompt`, `skill` (Agent Skills `SKILL.md`), `doctor`.

### Added — reliability and safety

- RFC 9457 error envelopes everywhere (local faults included) with `code`, `retryable`, `retry_after`, `help`,
  `agent_fix_prompt` and typed `next_actions`.
- Content-derived idempotency keys, so an identical re-run replays instead of being billed twice.
- Resilient job polling (survives transient network failures), an explicit `HXS_JOB_WAIT_TIMEOUT` result with
  resume/cancel actions, and a machine-readable recovery line when a wait is interrupted.
- Automatic spill of very large results to a file, plus `--out`, `--fields` and `--compact` for context control.
- Zero third-party dependencies (standard library only) and a refusal to send a bearer token over remote
  plain HTTP.

### Security

- No solver, engine, or mechanism ships to clients — every solve happens on the HexStellar service. With no
  network, a solve returns an error; it never fabricates an answer.
- The public sandbox capability is non-secret by design and grants no production access, billing, or writes.

---

## [0.0.1] — 2026-08-23

- Name reservation on PyPI. Placeholder distribution with no functionality.

> **BRAYON PIESKE** — *"A changelog should preserve release facts without becoming a second source of mutable totals."*