From 586f3e1c88051d00ac95bd26acd8ba955e02b864 Mon Sep 17 00:00:00 2001 From: thedancingdeveloper <306930456+thedancingdeveloper@users.noreply.github.com> Date: Tue, 1 Sep 2026 21:42:36 +0000 Subject: [PATCH] =?UTF-8?q?docs(deploy):=20document=20the=20vogt-stack=20t?= =?UTF-8?q?ag=20taxonomy=20=E2=80=94=20lean=20releases=20vs=20full=20branc?= =?UTF-8?q?h=20builds?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The registry interleaves two deliberately different vogt-stack builds under one name: semver/`latest` (release.yml, lean pod base, CLI-free by policy) and dev-/prod- (build.yml, full pod base, agent CLIs present). Nothing at the point of consumption distinguishes them, and pinning the natural-looking release tag in a deployment that runs agent sessions comes up with no CLIs — templates register but cannot start. State the taxonomy in the deployment guide, next to the existing CLI-free-release policy. Refs #502 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01RzFCTnWGff1k4FyX1HQCYM --- docs/DEPLOYMENT.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index 1a3b0ee..4e714af 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -388,6 +388,25 @@ production is one such private deployment, layering a private overlay on the public base; it is not a supported drop-in scenario reproducible from this repository alone. +**Read the `vogt-stack` tags carefully — two different builds share the +repository.** The registry interleaves both families under one name, and +pinning by the natural-looking tag is exactly the mistake this table exists +to prevent: + +| Tag family | Built by | Pod base | Agent CLIs | Meant for | +|---|---|---|---|---| +| `X.Y.Z`, `X.Y`, `sha-`, `latest` | `release.yml` (version tag) | lean | **none** — CLI-free by policy | the signed public release artifact | +| `dev`, `dev-`, `prod-` | `build.yml` (branch push) | full | present | the maintainer's own dev/prod pods, which run coding sessions | + +A deployment that runs agent sessions and pins a semver or `latest` +`vogt-stack` digest comes up with **no agent CLIs**: the engine registers its +session templates but none of them can start. Nothing warns at pull time — +the image runs and passes a liveness probe. If your deployment runs agents, +pin a `full`-variant digest (a branch build, or your own image built with +`VOGT_INSTALL_AI_CLIENTS=true`), never the release stack tag. See issue +[#502](https://github.com/TheDancingDeveloper-org/vogt/issues/502) for making +the variants distinguishable in the registry itself. + ### 7.1 Promote `dev` to production Promotion is two explicit, fast-forward-only pull requests. First deploy the