Skip to content

AGENTS.md never documents the container image: "release.yml then does everything" omits ghcr.io #172

Description

@plusky

AGENTS.md's Releases section says:

.github/workflows/release.yml then does everything: hermetic builds for
x86_64-unknown-linux-gnu and aarch64-apple-darwin, an x86_64 .deb and
.rpm, a GitHub release with all of those and their .sha256 files, and
finally the crates.io publish

"does everything" followed by an exhaustive-sounding list, which omits the
container and container-manifest jobs — the multi-arch image published to
ghcr.io.

grep -i 'ghcr\|container\|image' AGENTS.md returns nothing. The contract
file that agents are told to follow does not mention the container artifact at
all, anywhere.

Why it matters

  • The image is a shipped, publicly consumable artifact, and a pushed manifest
    cannot be cleanly unshipped — the exact irreversibility that motivated toolchain-drift is not a required status check, so a failing guard does not block a merge #138.
  • An agent reading only AGENTS.md would not know the image exists, so it would
    not know to keep the Dockerfile's toolchain, the packaging paths, or the
    release surface consistent with it.
  • The Dockerfile and its toolchain-drift guard are described in the repo,
    but nothing connects them to a published artifact.

Scope: a brief mention, nothing more

Narrowed 2026-08-30. The fix is a short mention in AGENTS.md's Releases
section
so the contract stops implying the enumerated list is exhaustive —
name the container image and where it is published. That is all.

Explicitly NOT in scope: tag semantics, the multi-arch manifest mechanics, a
container section of its own, or duplicating what release.yml's own comments
already say. AGENTS.md is a contract, not a manual; the detail belongs in the
workflow where it already lives.

One dense line or two, house style. Worth keeping (it is the non-obvious part
and release.yml already encodes it): container is a sibling of publish, not
upstream of it, so a broken image build must not hold back the crates.io release
of a tag whose binaries already shipped.

Found during the adversarial review of #170.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    ai-assistedAuthored or substantially written with an AI coding agentdockerPull requests that update docker codedocumentationImprovements or additions to documentation

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions