# 25. Hex package scope is CLI/ACP-only until public Elixir APIs are explicit
Date: 2026-06-19
Status: Accepted
Implementation status: Accepted package scope for the first Hex release. This ADR
defines the distribution contract before and after initial publication.
## Context
ADR 0016 intentionally deferred Hex publication. Pixir's source-install beta is now
usable for a local operator through the CLI and ACP, but publishing to Hex would create
a public distribution contract. That contract is easy to overstate: a Hex package can
look like a stable Elixir library even when the intended product surface is an escript
and an ACP server.
Pixir already has much of the mechanical Hex metadata in `mix.exs`: `app`, `version`,
`description`, `package`, `licenses`, `links`, `docs`, dependencies from Hex, and an
escript configuration. A local package build also succeeds. The remaining question is
not "can Hex build a tarball?" but "what public contract does that tarball imply?"
## Decision
**1. First Hex scope is CLI/ACP-only.** The first Hex package, if published, is a
distribution path for installing and running Pixir as a local tool:
```bash
mix escript.install hex pixir
pixir doctor --json
pixir acp
```
It does not promise a stable public Elixir library API.
**2. Public API promise stays narrow.** The stable surface for a first Hex release is:
- CLI behavior documented in README and quickstart docs;
- ACP over stdio;
- local diagnostics such as `pixir doctor --json`;
- documented local file/log behavior and security boundaries.
Internal modules under `Pixir.*` may be documented for transparency, but are not stable
extension points until a later ADR explicitly marks them public.
**3. Hex owner is explicit and separate from GitHub.** The package owner must be a
Hex.pm user or Hex.pm organization, not implicitly a GitHub account. The initial owner
is **TBD**. If the owner starts as an individual Hex user, transfer or additional owner
policy must be recorded before a broader release.
**4. Package contents must be curated before publishing.** The first publication should
not rely only on Hex defaults. The package should explicitly include runtime and public
documentation files and exclude local agent instructions, scratch artifacts, benchmark
state, generated docs, and local runtime state.
**5. A GitHub Release binary may still precede Hex.** Hex is useful for Elixir-native
installation, but it is not the only way to improve operator ergonomics. A prebuilt
binary release can remain the lower-API-commitment path if package API boundaries are
not ready.
## Consequences
- Hex is no longer blocked on the idea that every `Pixir.*` module must be stable.
- The first package can be judged as a CLI/ACP install surface rather than as a library.
- Docs and ExDoc must clearly say which surfaces are stable and which are internal.
- `mix.exs` should get explicit package file curation before publication.
- Ownership is a release decision, not an accident of whoever runs `mix hex.publish`.
## Non-goals
- Do not publish in this ADR.
- Do not claim a stable public Elixir API.
- Do not imply packaged T3Code integration or an upstream T3 provider.
- Do not add telemetry, self-update, MCP, web UI, multi-provider support, or SLA promises.
- Do not treat a successful `mix hex.build` as sufficient for publication readiness.
## Verification Direction
Before any Hex publication, the release candidate should pass:
```bash
mix check
mix docs --warnings-as-errors
mix hex.publish --dry-run
mix hex.build --unpack
mix escript.build
./pixir doctor --json
```
The unpacked package must be inspected for:
- no local runtime state (`.pixir`, `_build`, `deps`, `tmp`, generated `doc`);
- no local/private agent scaffolding;
- no secrets or machine-specific paths;
- expected README, LICENSE, `mix.exs`, runtime `lib`, and public docs;
- install instructions for `mix escript.install hex pixir`;
- clear CLI/ACP-only API stability wording.
After publication, test installation in a fresh project/shell:
```bash
mix escript.install hex pixir
pixir --version
pixir doctor --json
pixir acp
```
## References
- ADR 0016: open beta scope is source-install developer preview.
- ADR 0017: minimal Harness core and Presenter boundary.
- Hex publishing guide: https://hex.pm/docs/publish
- `mix hex.publish`: https://hex.hexdocs.pm/Mix.Tasks.Hex.Publish.html
- `mix escript.install`: https://mix.hexdocs.pm/main/Mix.Tasks.Escript.Install.html