Clarify tag-letter convention: suffix is build ordinal, 'a' is never used

Previous phrasing treated the letter suffix as a plain alphabetical sequence, which led to confusion about whether the first rebuild should be 'a' or 'b'. Spell out the intent: the suffix is the build ordinal, and the letter 'a' is reserved to mean '1st build' — which always uses the bare tag (no letter). So letters start at 'b' for the 2nd build, 'c' for the 3rd, and so on. Examples for opencode version 1.14.20: 1st build: v1.14.20 2nd build: v1.14.20b 3rd build: v1.14.20c
Fix [devbox] prompt marker disappearing after 'exec bash'
2026-04-21 23:58:12 +02:00 · 2026-04-21 23:52:03 +02:00 · 2026-04-21 21:16:47 +02:00
3 changed files with 16 additions and 4 deletions
@@ -15,7 +15,16 @@ Docker image packaging [opencode](https://opencode.ai) into a production-ready d

 ## Versioning scheme

-Tags follow `v{opencode_version}{letter}` — e.g. `v1.4.3k`. The number matches the opencode npm version. The letter suffix increments for container-level changes (tooling, docs, CVE fixes) on the same opencode version. CI produces four Docker Hub tags per release: `vX.Y.Zn`, `latest`, `vX.Y.Zn-omos`, `latest-omos`.
+Tags follow `v{opencode_version}[letter]` — e.g. `v1.14.20` for the first build on a new opencode release, and `v1.14.20b`, `v1.14.20c`, … for subsequent rebuilds on the same opencode version.
+
+- The number tracks the opencode npm version (see `OPENCODE_VERSION` ARG in `Dockerfile`).
+- **No letter suffix** on the first build of a new opencode version — the bare `v{opencode_version}` tag is the canonical release.
+- **Letter suffix is the build ordinal**, starting at `b` for the second build. The letter `a` is **never used** — think of the suffix as counting rebuilds: `b = 2nd, c = 3rd, d = 4th, …`. For opencode version `1.14.20`: first build `v1.14.20`, second `v1.14.20b`, third `v1.14.20c`, and so on.
+- A letter suffix is only used for container-level rebuilds — tooling changes, CVE fixes, doc-driven rebuilds, entrypoint bugfixes — that don't change the underlying opencode version.
+
+CI produces four Docker Hub tags per release: `vX.Y.Z[n]`, `latest`, `vX.Y.Z[n]-omos`, `latest-omos`.
+
+When bumping the opencode version, also bump `OPENCODE_VERSION` in `Dockerfile` and update the comment in `.env.example` if it names a specific model/version for context.

 ## Critical conventions

@@ -5,7 +5,7 @@ ARG DEBIAN_VERSION=trixie-slim
 FROM debian:${DEBIAN_VERSION} AS base

 ARG TARGETARCH
-ARG OPENCODE_VERSION=1.14.19
+ARG OPENCODE_VERSION=1.14.20

 LABEL maintainer="joakimp"
 LABEL description="Portable opencode developer container"
@@ -76,7 +76,10 @@ fi

 # ── Prompt: show [opencode-devbox] tag so it's obvious you're in the container
 # Preserves the default Debian PS1 logic but prefixes with a container marker.
-if [ -n "${PS1:-}" ] && [ -z "${DEVBOX_PS1_SET:-}" ]; then
+# We check for the literal '[devbox]' substring in PS1 rather than relying on
+# an exported guard variable — otherwise `exec bash` inherits the guard but
+# gets a fresh (prefix-less) PS1 from .bashrc, and the prefix would never be
+# re-added in the new shell.
+if [ -n "${PS1:-}" ] && [[ "$PS1" != *"[devbox]"* ]]; then
  PS1='\[\e[38;5;39m\][devbox]\[\e[0m\] '"${PS1}"
-  export DEVBOX_PS1_SET=1
 fi