feat(chart,docs): unified image tag format openab:<tag>-<agent>

[chaodu-agent]

Summary

Migrate Helm chart and documentation to use the unified Docker image tag format from #1175.

Changes

Helm chart (_helpers.tpl)

• agentImage helper now produces openab:<tag>-<agent> for non-kiro agents
• kiro (default) stays as openab:<tag> with no suffix
• Per-agent image string override still works for backward compat

values.yaml

• Removed old openab-<agent> repo references from commented examples
• Per-agent image field defaults to empty (chart auto-resolves)

docs/image-tags.md

• Rewrote with unified tag convention + old→new migration table
• Updated release flow diagram

Agent docs (12 files)

• Removed --set agents.xxx.image=... from helm install examples (chart auto-resolves)
• Updated docker pull examples to openab:beta-<agent> format
• Left openab-gateway references untouched (separate image)

Verified

helm template test charts/openab → openab:0.9.0-beta.1 (kiro)
helm template test charts/openab --set agents.claude.command=... → openab:0.9.0-beta.1-claude

What's next (PR B)

• Update build-operator.yml to use Dockerfile.unified + new tag format

Closes follow-up from #1175

[chaodu-agent]

CHANGES REQUESTED ⚠️ — The unified openab:<tag>-<agent> images this PR points to are not published in the registry yet, so the new chart default and migrated docs would cause ImagePullBackOff for every non-kiro agent.

What This PR Does

Migrates the Helm chart default image resolution and all docs from the per-repo image scheme (ghcr.io/openabdev/openab-<agent>:<tag>) to a unified single-repo, tag-suffix scheme (ghcr.io/openabdev/openab:<tag>-<agent>), with kiro as the default agent (no suffix).

How It Works

openab.agentImage in _helpers.tpl now branches on the agent name: kiro → repository:<tag>, any other agent → repository:<tag>-<agent>. Explicit per-agent image: string overrides are still honored verbatim (with :) or get appVersion appended (without :), preserving backward compatibility. Docs drop the now-redundant --set agents.<x>.image=... flags and rely on auto-resolution.

Findings

#	Severity	Finding	Location
1	🔴	Unified openab:<tag>-<agent> images are not published — chart default & docs resolve to non-existent images (verified 404 against ghcr)	_helpers.tpl:74-78, docs/*
2	🔴	openab:beta-native-sandbox does not exist and native-sandbox is not a buildable variant in the unified builder	docs/openshell.md:78
3	🟡	mybot example (runs opencode) now auto-resolves to non-existent openab:<tag>-mybot after the image override was removed	docs/refarch/sidecar-proxy.md:66
4	🟡	No helm-unittest coverage for the new agent-suffix resolution logic	charts/openab/tests/
5	🟢	Backward-compat for explicit overrides preserved; helper doc comment clear; chart kiro-default matches the unified builder convention	_helpers.tpl

Finding Details

🔴 F1: Unified images are not published yet — default install breaks for non-kiro agents

The active release workflow (build-operator.yml, triggered on push: tags: v*) still publishes the legacy per-repo images (openab-claude, openab-codex, … via Dockerfile.<agent>). The unified builder (build-images.yml) that emits openab:<tag>-<agent> is workflow_dispatch-only and is not invoked by any other workflow, so it has not published these tags.

Verified directly against the registry (anonymous pull-token, current appVersion = 0.9.0-beta.1):

openab:0.9.0-beta.1          -> 200   (kiro default — OK)
openab:0.9.0-beta.1-claude   -> 404   (chart default for claude — MISSING)
openab:beta-claude           -> 404
openab:beta-codex            -> 404
openab:stable-claude         -> 404
openab:latest-claude         -> 404
openab-claude:beta           -> 200   (legacy per-repo — still the real image)
openab-codex:beta            -> 200

Consequence: after this merges, helm install for any non-kiro agent with default values renders ghcr.io/openabdev/openab:<appVersion>-<agent>, which 404s → ImagePullBackOff. The docs that removed the working --set agents.<x>.image=... overrides make this worse, since those flags previously pointed at images that exist.

Suggested sequencing: first wire the unified builder into the release pipeline (or update build-operator.yml) so openab:<tag>-<agent> is published — and backfill the tags for already-released versions — then flip the chart default and docs. Alternatively, gate the new default behind a values flag until the images exist.

🔴 F2: openab:beta-native-sandbox is not a real image

docs/openshell.md now uses --from ghcr.io/openabdev/openab:beta-native-sandbox. native-sandbox is not in the unified builder's allowed-variants list (kiro,claude,…,native,agentcore in build-images.yml), and openab:beta-native-sandbox returns 404. The real image is the legacy ghcr.io/openabdev/openab-native-sandbox (built from openshell/Dockerfile, returns 200). This reference should stay on the per-repo image (or the unified build must add a native-sandbox variant first).

🟡 F3: mybot sidecar example resolves to a non-existent image

In docs/refarch/sidecar-proxy.md the agent is named mybot but runs command: opencode. The PR removed --set agents.mybot.image=ghcr.io/openabdev/openab-opencode. With the new logic the name (not the command) drives resolution, producing openab:<tag>-mybot — confirmed via helm template:

image: "ghcr.io/openabdev/openab:0.9.0-beta.1-mybot"

Keep an explicit image override here (e.g. point it at the opencode variant), since the agent name does not match a published variant.

🟡 F4: Missing test coverage for the core behavior change

No file under charts/openab/tests/ asserts the new resolution. helm-unittest passing is not evidence the suffix logic works. Please add a case asserting kiro → ghcr.io/openabdev/openab:<tag> and a non-default agent → ghcr.io/openabdev/openab:<tag>-<agent>, plus the explicit-override passthrough.

🟢 F5: What's good

• Explicit image: overrides remain backward compatible (verbatim when containing :, else appVersion appended).
• The helper comment clearly documents the new behavior and call signature.
• The chart's kiro-as-default (no suffix) convention matches build-images.yml exactly, so the two won't drift once images are published.

Baseline Check

• PR opened: 2026-06-23, label pending-maintainer, CI (check, helm-unittest) green.
• Main already has: openab.agentImage with per-repo override support; legacy per-repo images published by build-operator.yml; a manual-only unified builder (build-images.yml).
• Net-new value: switches the default and docs to the unified tag scheme. The scheme itself is sound — the blocker is that the images it targets are not yet published on the release path.

[chaodu-agent]

法師團隊 Review — LGTM ✅

5/5 reviewers approve (X渡 did not respond)

Reviewer	Angle	Verdict
普渡 (Claude)	Correctness	✅ LGTM
覺渡 (Gemini)	Docs/UX	✅ LGTM
擺渡 (Codex)	Architecture	✅ LGTM
口渡 (Copilot)	Security/CI	✅ LGTM
Z渡 (Codex)	Tests/Perf	✅ LGTM

Summary of changes (post-review fixes included)

• _helpers.tpl: All agents (including kiro) use <tag>-<agent> format — no default, no bare tags
• values.yaml: Per-agent image examples removed (chart auto-resolves)
• docs/image-tags.md: Full rewrite — no latest, no default agent, explicit <version>-<agent> everywhere
• Agent docs: Removed --set image lines (chart auto-resolves)
• docs/antigravity.md: Fixed broken repository object format
• docs/openshell.md: Reverted (native-sandbox stays on separate Dockerfile)
• Added charts/openab/tests/agent-image_test.yaml with 6 test cases

Verified

helm template test charts/openab
  → image: ghcr.io/openabdev/openab:0.9.0-beta.1-kiro ✅

helm template test charts/openab --set agents.claude.command=claude-agent-acp
  → image: ghcr.io/openabdev/openab:0.9.0-beta.1-claude ✅

helm-unittest: ✅

Options for maintainer

1️⃣ Approve & merge
2️⃣ Request further changes
3️⃣ Close PR