# PRD prd-new: Modernize built-in agent images

- **Status:** Draft
- **Author:** Codex
- **Created:** 2026-07-21
- **Issue:** #451

## Summary

Keep every built-in agent provider on Debian's current stable release and make
Podman available inside each image. This gives agents a consistent, modern
userspace and an OCI container tool without requiring per-project setup.

## Problem

The Claude, Codex, and Pi images inherited the generic `node:22-slim` tag. That
tag did not make Debian the explicit supported base and left the images on the
older Bookworm release. None of the built-in images installed Podman, so tasks
that need to inspect or build OCI images first had to modify the bottle or
could not run at all.

## Goals / success criteria

- Every Dockerfile under `bot_bottle/contrib/*/Dockerfile` explicitly inherits
  `debian:trixie-slim`, Debian 13 (the current stable release).
- Every image explicitly creates the non-root `node` runtime user with UID and
  GID 1000 instead of relying on a language image to provide it.
- Every built-in agent image installs Podman from Debian stable.
- Every built-in agent image retains an SSH client for Git-over-SSH workflows.
- The non-root agent user owns a traversable XDG Git configuration directory,
  so Git can load bot-bottle's global git-gate rewrites without permission
  errors.
- A shared test enforces both requirements for current and future built-in
  providers.

## Non-goals

- Configuring privileged or nested-container execution for bottles.
- Pinning Podman outside Debian's stable package repository.
- Changing the Node.js or agent CLI release policy.

## Design

Use the explicit `debian:trixie-slim` base. Install Node.js and npm from Debian
stable where a provider needs them, and create the common `node` runtime user
explicitly. Install the `podman` package with each image's existing `apt-get`
dependency layer, so package metadata and caches are still removed in the same
layer. Treat Debian stable as the Node.js and Podman stability and update
channel; this keeps the images distribution-first and avoids adding a
third-party package repository.