Document container tag provenance and enhance container-list

- Add "Squash-merge and container tags" section to build-container-image docs
  explaining the orphan SHA problem and post-merge C0 workflow
- Add post-merge container step to C1 process in agent-change-process
- Rewrite container-list as uv run --script with typer and rich
- Add optional container name filter argument (shows more tags when filtered)
- Annotate tags with [main]/[branch] based on commit ancestry

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/changelog.d/feature-container-tag-provenance.doc.md

@@ -0,0 +1 @@
+Document squash-merge container tag provenance issue and post-merge workflow for updating manifests to main-SHA tags.

docs/how-to/agent-change-process.md

@@ -1,6 +1,6 @@
 ---
 title: Agent Change Process
-modified: 2026-02-23
+modified: 2026-02-24
 last-reviewed: 2026-02-23
 tags:
   - how-to
@@ -52,6 +52,7 @@ A change with enough complexity or risk that a human should review it, but not s
    - **Workflows:** point workflow triggers at the branch if needed
 7. After user review and successful deployment, the user merges the PR
 8. **After merge:** reset ArgoCD revisions back to main, re-sync
+9. **If the PR changed `containers/`:** the merge triggers a rebuild from main automatically. Once it completes, commit a C0 updating the manifest to the new `[main]`-tagged image (see [[build-container-image#Squash-merge and container tags]])
 
 ### Upgrading to C2
 
@@ -227,6 +228,7 @@ When starting a new session to continue C2 work:
 Mikado resets apply to branch code, not build artifacts. Container images in the registry are independent of branch lifecycle:
 
 - **Registry images** are build outputs cached in zot — tagged with commit SHAs, so each build is unique and traceable
+- **Squash-merge orphans:** Images built during PR development reference branch SHAs that won't exist on main after merge. After merge, a rebuild triggers automatically; commit a C0 to update manifests to the new `[main]`-tagged image. Use `mise run container-list <name>` to find it
 - **Automatic builds** trigger when container changes merge to main. Use `mise run container-build-and-release` for manual dispatch
 - **If a build succeeds but deployment fails**, the image is fine; the problem is elsewhere. Document what you learned and try again
 - **If a build fails in CI**, no image is pushed. Fix the nix/dockerfile and re-merge or re-dispatch

docs/how-to/deployment/build-container-image.md

@@ -1,6 +1,6 @@
 ---
 title: Build Container Image
-modified: 2026-02-20
+modified: 2026-02-24
 last-reviewed: 2026-02-15
 tags:
   - how-to
@@ -86,6 +86,26 @@ image: registry.ops.eblu.me/blumeops/<name>:vX.Y.Z-abc1234
 
 Then deploy per [[deploy-k8s-service]].
 
+### Squash-merge and container tags
+
+Container image tags include the git commit SHA they were built from (e.g. `v3.9.1-74029e1`). When a PR is squash-merged, the original branch commits are replaced by a single new commit on main — the SHA in the image tag no longer exists on main. After branch cleanup (30 days), the SHA becomes unreachable and the container loses source traceability.
+
+**The rule:** Production manifests must reference images built from a commit on main. After merging a PR that changed `containers/<name>/`:
+
+1. The merge to main automatically triggers a rebuild (the `build-container.yaml` / `build-container-nix.yaml` workflows fire on pushes to `main` that touch `containers/**`)
+2. Wait for the workflow to complete — check at `https://forge.ops.eblu.me/eblume/blumeops/actions`
+3. Find the new main-SHA tag:
+   ```bash
+   mise run container-list <name>
+   ```
+   Tags marked `[main]` were built from a commit on main; tags marked `[branch]` are from PR branches
+4. Commit a C0 follow-up updating the manifest to use the `[main]` tag:
+   ```yaml
+   image: registry.ops.eblu.me/blumeops/<name>:vX.Y.Z-<main-sha>
+   ```
+
+This follow-up C0 is expected and routine — it's the cost of squash-merge + SHA-tagged containers.
+
 ## Common Patterns
 
 Existing containers demonstrate several build approaches: