Releasing Mino

This page covers application releases. For the book website, see writing and updating the book.

All ten chapter releases, chapter-01 through chapter-10, were published on 2026-10-21 with macOS packages for Apple Silicon and Intel; chapter-10 was republished on 2026-10-26, Chapters 11 and 12 were published on 2026-10-26 as chapter-11 and chapter-12, Chapter 13 on 2026-10-27 as chapter-13, Chapter 14 on 2026-10-28 as chapter-14, and Chapter 15 on 2026-10-29 as chapter-15. The latest chapter release is chapter-15, application version 0.15.0; each lesson uses its matching source tag. Building the working tree does not create a release or change published tags.

Republished releases

On 2026-10-21 the tutorial was restructured from nine chapters into ten, and every chapter tag and release was republished. The former Chapter 03 became Chapter 03 (the Agent loop) and Chapter 04 (recovering interrupted tool turns), and later chapters moved up by one, so a tag such as chapter-05 now names a different lesson than before. Releases published before that date used the old numbering and are superseded. Replacing published tags was a one-time exception authorized by the owner; future fixes receive new patch tags.

An executable installed before 2026-10-21 still reports its old version number; run mino update to switch to a republished release. Sessions that earlier releases wrote under ~/.mino/sessions/ remain readable, but a legacy ~/.mino/history.jsonl is not imported. Keep it as a private backup.

On 2026-10-26, again at the owner's request, Chapter 10 was rewritten in place and chapter-10 (0.10.0) was republished. The optional ~/.mino/policy.json was replaced by three permission modes selected with /mode; see Chapter 10 permission modes. Earlier chapters and their releases are unchanged. Both packages report 0.10.0; an executable from the first package prints a Policy: line at startup, so run mino update chapter-10 to replace it. The republished release ignores a leftover ~/.mino/policy.json.

Session compatibility

Each release reads the session records written by earlier chapters, but an older release may refuse a session once a newer one has written records it does not know. Before switching versions, close Mino and keep private copies of your session files.

Chapter 03 writes version 2 session records and reads versions 1–2; chapter-02 cannot read a session after version 2 records are appended. See Chapter 03 setup.

Chapter 04 keeps version 2, but chapter-03 cannot open a session after Chapter 04 saves a recovery_ack record; see Chapter 04 setup.

Chapter 05 also keeps version 2 and adds multiple sessions. Once /new has created a second session, Chapters 02–04 stop at startup; see Chapter 05 session storage.

Chapter 06 writes version 3 session records and reads versions 1–3. Before trying it or rolling back, follow the history compatibility notes.

Chapter 07 writes version 4 records and reads versions 1–4; see Chapter 07 compatibility before using existing sessions or rolling back.

Chapter 08 keeps record version 4, but chapter-07 cannot load a session that started a file-tool call; see Chapter 08 compatibility before rolling back.

Chapter 09 also keeps record version 4, but chapter-08 cannot load a session that started an MCP call; see Chapter 09 compatibility before rolling back.

Chapter 10 keeps record version 4 and chapter-09 can still open its sessions; see Chapter 10 compatibility.

Chapter 11 keeps record version 4 and adds no record kinds; chapter-10 can still open its sessions but does not include mino eval. See Chapter 11 compatibility.

Chapter 12 keeps record version 4 and adds no record kinds; chapter-11 can still open its sessions but runs Bash unconfined, and it refuses a session that recorded an approved sandbox: false opt-out. See Chapter 12 compatibility.

Chapter 13 keeps record version 4 and adds no record kinds; chapter-12 can still open its sessions unless a memory_view or memory_save call started in them, or the saved skill catalog holds a description longer than 1,024 bytes. Older releases ignore ~/.mino/memory/. See Chapter 13 compatibility.

Chapter 14 keeps record version 4 and adds no record kinds; chapter-13 can still open its sessions unless a spawn_agent call started in them. Older releases ignore the .agents directories that hold subagent logs, and their /clear leaves them in place. See Chapter 14 compatibility.

Chapter 15 writes record version 5 and adds the session_agents record. chapter-14 and earlier cannot open a session after Chapter 15 has opened, resumed, or cleared it, even before a new question. Older releases ignore .agents/agents/ and do not have the built-in create-subagent skill. See Chapter 15 compatibility.

Version policy

Release tags identify chapters; executables and archive filenames retain numeric versions:

Release tag	Application version
chapter-01	0.1.0
chapter-02	0.2.0
chapter-03	0.3.0
chapter-04	0.4.0
chapter-05	0.5.0
chapter-06	0.6.0
chapter-07	0.7.0
chapter-08	0.8.0
chapter-09	0.9.0
chapter-10	0.10.0
chapter-11	0.11.0
chapter-12	0.12.0
chapter-13	0.13.0
chapter-14	0.14.0
chapter-15	0.15.0

An initial chapter release uses chapter-NN. A later fix uses chapter-NN.PATCH: for example, chapter-05.1 produces version 0.5.1. Future fixes receive new tags; do not move published tags or replace their assets. The 2026-10-21 and 2026-10-26 republications were exceptions authorized by the owner. Prefer one complete commit per chapter, including code, tests, and both book languages.

Packaging derives 0.<chapter>.<patch> from the tag and supplies it through Go linker flags. Source builds display dev. The changelog heading stays numeric, such as ## [0.5.1].

Migrate an existing installation

An updater installed before the chapter-tag migration cannot resolve chapter-* tags. Rerun the current installation command once, even if the displayed numeric version is unchanged. This fetches the new installer and replaces the executable while preserving settings, custom ~/.mino/SOUL.md, and any history. Updating a tag or the script on main does not change an installed binary.

After that installation, mino update selects the latest release and mino update chapter-15 selects this chapter. The installer also accepts 0.15.0 or v0.15.0 as aliases for chapter-15; these are version selectors, not additional Git tags.

Publish a version

1. Finish the change, add the numeric version entry to CHANGELOG.md, and commit it.

2. Run bash scripts/check.sh, review the code and bilingual book, then push the reviewed change to main.

3. Create and push a new chapter or patch tag. For example, a future Chapter 15 patch:

   git tag -a chapter-15.1 -m 'Mino chapter-15.1'
   git push origin chapter-15.1

The Release workflow runs for chapter-* tags. It reruns checks and builds darwin/arm64 and darwin/amd64 with CGO disabled. On macOS, packaging also runs the host-architecture executable to verify its numeric version.

Each archive contains mino, LICENSE, and THIRD_PARTY_NOTICES.txt. The example patch would provide:

mino_0.15.1_darwin_arm64.tar.gz
mino_0.15.1_darwin_amd64.tar.gz
checksums.txt

The workflow uploads to a draft release, then publishes after all uploads succeed. The matching numeric changelog entry supplies the notes; packaging fails if it is missing. Normal branch pushes run CI without publishing an application release. The publishing job uses GitHub's built-in GITHUB_TOKEN with contents: write; it needs no model API key.

Local packaging and recovery

From the repository root at chapter-15, inspect this chapter's packages:

bash scripts/package.sh chapter-15

Packaging accepts the canonical chapter tag and builds the current working tree; it does not check out the tag. Output goes to the ignored dist/ directory without creating a Git tag or release. If publishing fails, inspect the logs and any incomplete draft before rerunning the job.

Public downloads and the embedded updater

The installer uses curl, without GitHub CLI or a GitHub login. It resolves the latest tag once unless you specify a release, then downloads the package and checksums.txt from that same tag. It verifies SHA-256 and the executable's numeric version before replacing ~/.mino/bin/mino; download or verification failures preserve the existing executable.

Each chapter release embeds the installer used by mino update. Installation configures PATH through .zshrc (respecting ZDOTDIR) or .bash_profile without overwriting the profile. For a symlink or unwritable profile, it prints the line to add manually. First launch creates the model configuration only after you complete setup.