Skip to content

docs: plain English README and AGENTS.md - #75

Merged
rubas merged 2 commits into
mainfrom
docs/plain-english
Sep 26, 2026
Merged

rubas merged 2 commits into
mainfrom
docs/plain-english

Conversation

@rubas

@rubas rubas commented Sep 26, 2026

Copy link
Copy Markdown
Owner

Before

CPU is available in every build except coreml (see below). Pick one accelerator per build; the precompiled Hex package ships CPU plus cuda / hipblas variants for Linux and Metal on Apple Silicon, selected via WHISPER_CPP_VARIANT:

Problem

  • The README did not say which Linux targets have which GPU variant; only AGENTS.md did.
  • AGENTS.md opened with a "Goal" that repeated the README, and its release steps packed several rules into one step.
  • One pitfall described the release guard wrongly (see below).

After

  • The README goes from what the library is, to install, usage, backends, development, and license. A small table shows the precompiled variants per target. task check and task test:integration replace the bare mix test lines.
  • AGENTS.md holds the checks, rules, pitfalls, and release steps, in short sentences. The dispatch rules are their own step.
  • Words: README 511 to 537, AGENTS.md 782 to 649.
Fact fixes
  • AGENTS.md said the release job fails "when the ggml CPU flags contain native". release.yml checks that CMakeCache.txt has GGML_NATIVE:BOOL=OFF; the text now says that.
  • The README testing section listed mix test commands; the repo gate is task check (format check, compile, lint, Elixir and Rust tests, zizmor), and task test:integration for real inference.
  • Checked against the code: version 0.5.0, elixir: "~> 1.19", rust-version = "1.98", the @variants map, the six-entry release matrix, armv8.2-a+dotprod+fp16, the gfx1200 and gfx1201 arch list, the .hip_fatbin check, overwrite_files: false, the nif_versions sed, the weekly integration.yml, the [patch.crates-io] rev on vendor/whisper-rs-0.16.0-patched, issue Track upstream whisper-rs fixes; drop the vendor patches when released #26 (open), the Credo Specs and ModuleDoc settings, and the silero model file name.

@rubas
rubas merged commit 4af3c14 into main Sep 26, 2026
1 check passed
@rubas
rubas deleted the docs/plain-english branch September 26, 2026 21:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant