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

AGENTS.md

@@ -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
 

Dockerfile

@@ -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"

rootfs/home/developer/.bash_aliases

@@ -16,12 +16,11 @@ export HISTCONTROL=ignoreboth:erasedups
 export HISTTIMEFORMAT='%F %T  '
 shopt -s histappend 2>/dev/null
 shopt -s cmdhist 2>/dev/null
-# Flush every command to disk immediately so reboots don't lose recent work.
+# Note: PROMPT_COMMAND="history -a" is installed LATER in this file,
-# Guarded so repeated sourcing (e.g. `exec bash`) doesn't stack duplicates.
+# after zoxide's init runs. Installing it here would create a
-if [ -z "${DEVBOX_HIST_SET:-}" ]; then
+# "history -a;;__zoxide_hook" chain because zoxide's init uses ';'
-  PROMPT_COMMAND="history -a; ${PROMPT_COMMAND:-}"
+# as its separator and prepends itself; two adjacent ';' breaks the
-  export DEVBOX_HIST_SET=1
+# parser. See https://github.com/ajeetdsouza/zoxide/issues/722.
-fi
 
 # ── Common aliases ───────────────────────────────────────────────────
 # Prefer eza (modern ls) when available
@@ -65,9 +64,22 @@ if command -v fzf >/dev/null 2>&1; then
   eval "$(fzf --bash)" 2>/dev/null || true
 fi
 
+# ── PROMPT_COMMAND: flush history every prompt ───────────────────────
+# Installed AFTER zoxide init so zoxide's hook is already in place;
+# we append with a newline separator to avoid the ';;' parse error
+# described at the top of this file. Guarded so repeated sourcing
+# (e.g. `exec bash`) doesn't stack duplicates.
+if [ -z "${DEVBOX_HIST_SET:-}" ]; then
+  PROMPT_COMMAND="${PROMPT_COMMAND:+$PROMPT_COMMAND$'\n'}history -a"
+  export DEVBOX_HIST_SET=1
+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