feat(toolbox-stack): add shared prompt and scaffolding template

ToolboxStack/collab/TSYSDevStack-toolbox-prompt.md

@@ -25,7 +25,7 @@ The TSYSDevStack consists of four categories:
 - mise
 - zsh / oh-my-zsh / completions /
 - 
+- See `output/PROMPT` for shared toolbox contributor guidance, `output/toolbox-base/PROMPT` for the image-specific snapshot, and `output/NewToolbox.sh` for bootstrapping new toolboxes from the template (edit each toolbox's `SEED` once to set goals, then load its PROMPT when starting work).
 
 ## toolbox-gis
 ## toolbox-weather
-

ToolboxStack/output/NewToolbox.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+    echo "Usage: $0 <toolbox-name>" >&2
+    exit 1
+fi
+
+RAW_NAME="$1"
+if [[ "${RAW_NAME}" == toolbox-* ]]; then
+    TOOLBOX_NAME="${RAW_NAME}"
+else
+    TOOLBOX_NAME="toolbox-${RAW_NAME}"
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE_DIR="${SCRIPT_DIR}/toolbox-template"
+TARGET_DIR="${SCRIPT_DIR}/${TOOLBOX_NAME}"
+
+if [[ ! -d "${TEMPLATE_DIR}" ]]; then
+    echo "Error: template directory not found at ${TEMPLATE_DIR}" >&2
+    exit 1
+fi
+
+if [[ -e "${TARGET_DIR}" ]]; then
+    echo "Error: ${TARGET_DIR} already exists" >&2
+    exit 1
+fi
+
+cp -R "${TEMPLATE_DIR}" "${TARGET_DIR}"
+
+python3 - "$TARGET_DIR" "$TOOLBOX_NAME" <<'PY'
+import sys
+from pathlib import Path
+
+base = Path(sys.argv[1])
+toolbox_name = sys.argv[2]
+
+for path in base.rglob("*"):
+    if not path.is_file():
+        continue
+    text = path.read_text()
+    updated = text.replace("{{toolbox_name}}", toolbox_name)
+    if updated != text:
+        path.write_text(updated)
+PY
+
+echo "Created ${TARGET_DIR} from template."
+echo "Next steps:"
+echo "  1) Edit ${TARGET_DIR}/SEED once to describe the toolbox goals."
+echo "  2) Load ${TARGET_DIR}/PROMPT in Codex; it will instruct you to read SEED and proceed."

ToolboxStack/output/PROMPT

@@ -0,0 +1,17 @@
+You are Codex helping with TSYSDevStack ToolboxStack deliverables.
+
+Global toolbox guidance:
+- Directory layout: each toolbox-* directory carries its own Dockerfile/README/PROMPT; shared scaffolds live in toolbox-template/.devcontainer and docker-compose.yml.
+- Use ./NewToolbox.sh <name> to scaffold a new toolbox-* directory from toolbox-template.
+- Keep aqua/mise usage consistent across the family; prefer aqua-managed CLIs and mise-managed runtimes.
+- Reference toolbox-template when bootstrapping a new toolbox. Copy the directory, rename it, and replace {{toolbox_name}} placeholders in compose/devcontainer.
+- Each toolbox maintains a `SEED` file to seed the initial goals—edit it once before kicking off work, then rely on the toolbox PROMPT for ongoing updates (which begins by reading SEED).
+
+Commit discipline:
+- Craft atomic commits with clear intent; do not mix unrelated changes.
+- Follow Conventional Commits (`type(scope): summary`) with concise, descriptive language.
+- Commit frequently as features evolve, keeping diffs reviewable.
+- After documentation/tooling changes, run ./build.sh to ensure the image builds, then push once the build succeeds.
+- Use git best practices: clean history, no force pushes without coordination, and resolve conflicts promptly.
+
+Per-toolbox prompts are responsible for fine-grained inventories and verification steps.

ToolboxStack/output/toolbox-base/Dockerfile

@@ -18,11 +18,14 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
         git \
         jq \
         bc \
+        htop \
+        btop \
         locales \
         openssh-client \
         ripgrep \
         tmux \
         screen \
+        entr \
         fd-find \
         bat \
         httpie \

ToolboxStack/output/toolbox-base/PROMPT

@@ -7,16 +7,16 @@ Context snapshot (toolbox-base):
 - Mounted workspace: current repo at /workspace (rw)
 
 Current state:
-- Dockerfile installs shell tooling (zsh/bash/fish with Starship & oh-my-zsh), core CLI utilities (curl, wget, git, tmux, screen, httpie, tea, bc, etc.), build-essential + headers, aqua, and mise. Aqua is pinned to specific versions for gh, lazygit, direnv, git-delta, zoxide, just, yq, xh, curlie, chezmoi, shfmt, shellcheck, hadolint; direnv/zoxide hooks are enabled for all shells (direnv logging muted).
+- Dockerfile installs shell tooling (zsh/bash/fish with Starship & oh-my-zsh), core CLI utilities (curl, wget, git, tmux, screen, htop, btop, entr, httpie, tea, bc, etc.), build-essential + headers, aqua, and mise. Aqua is pinned to specific versions for gh, lazygit, direnv, git-delta, zoxide, just, yq, xh, curlie, chezmoi, shfmt, shellcheck, hadolint, uv, watchexec; direnv/zoxide hooks are enabled for all shells (direnv logging muted).
 - aqua-managed CLI inventory lives in README.md alongside usage notes; tea installs via direct download with checksum verification (TEA_VERSION build arg).
 - mise handles language/tool runtimes; activation wired into zsh, bash, and fish.
 - docker-compose.yml runs container with host UID/GID, `sleep infinity`, and docker socket mount; run via run.sh/build.sh. Host directories `~/.local/share/mise` and `~/.cache/mise` are mounted for persistent runtimes.
 - Devcontainer config ( .devcontainer/devcontainer.json ) references the compose service.
-- Documentation: README.md (tooling inventory & workflow) and this PROMPT must stay current. README also notes that build.sh now uses docker buildx with a local cache directory.
+- Documentation: README.md (tooling inventory & workflow) and this PROMPT must stay current, and both should stay aligned with the shared guidance in ../PROMPT. README also notes that build.sh now uses docker buildx with a local cache directory.
 
 Collaboration guidelines:
 1. Default to non-destructive operations; respect existing scripts run.sh/build.sh.
-2. Any tooling changes require updating README.md (inventory) and this prompt summary.
+2. Any tooling changes require updating README.md (inventory) and this prompt summary, rebuilding via ./build.sh, then committing (Conventional Commits, atomic diffs) and pushing after a successful build per ../PROMPT.
 3. Keep configurations reproducible: prefer aqua/mise for new CLI/runtimes over apt unless prerequisites.
 4. Mention verification steps (build/test) after changes.
 5. Maintain UID/GID mapping and non-root execution.

ToolboxStack/output/toolbox-base/README.md

@@ -36,8 +36,8 @@ The compose service mounts the current repo to `/workspace` (read/write) and run
 |----------|---------|-------|
 | **Shells & Prompts** | 🐚 `zsh` • 🐟 `fish` • 🧑‍💻 `bash` • ⭐ `starship` • 💎 `oh-my-zsh` | Starship prompt enabled for all shells; oh-my-zsh configured with `git` + `fzf` plugins. |
 | **Runtime & CLI Managers** | 🪄 `mise` • 💧 `aqua` | `mise` handles language/tool runtimes (activation wired into zsh/bash/fish); `aqua` manages standalone CLIs with config at `~/.config/aquaproj-aqua/aqua.yaml`. |
-| **Core CLI Utilities** | 📦 `curl` • 📥 `wget` • 🔐 `ca-certificates` • 🧭 `git` • 🔧 `build-essential` + headers (`pkg-config`, `libssl-dev`, `zlib1g-dev`, `libffi-dev`, `libsqlite3-dev`, `libreadline-dev`, `make`) • 🔍 `ripgrep` • 🧭 `fzf` • 📁 `fd` • 📖 `bat` • 🔗 `openssh-client` • 🧵 `tmux` • 🖥️ `screen` • 📊 `jq` • 🌐 `httpie` • ☕ `tea` • 🧮 `bc` | Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs). |
+| **Core CLI Utilities** | 📦 `curl` • 📥 `wget` • 🔐 `ca-certificates` • 🧭 `git` • 🔧 `build-essential` + headers (`pkg-config`, `libssl-dev`, `zlib1g-dev`, `libffi-dev`, `libsqlite3-dev`, `libreadline-dev`, `make`) • 🔍 `ripgrep` • 🧭 `fzf` • 📁 `fd` • 📖 `bat` • 🔗 `openssh-client` • 🧵 `tmux` • 🖥️ `screen` • 📈 `htop` • 📉 `btop` • ♻️ `entr` • 📊 `jq` • 🌐 `httpie` • ☕ `tea` • 🧮 `bc` | Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs). |
-| **Aqua-Managed CLIs** | 🐙 `gh` • 🌀 `lazygit` • 🪄 `direnv` • 🎨 `git-delta` • 🧭 `zoxide` • 🧰 `just` • 🧾 `yq` • ⚡ `xh` • 🌍 `curlie` • 🏠 `chezmoi` • 🛠️ `shfmt` • ✅ `shellcheck` • 🐳 `hadolint` | Extend via `~/.config/aquaproj-aqua/aqua.yaml` and run `aqua install`. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish. |
+| **Aqua-Managed CLIs** | 🐙 `gh` • 🌀 `lazygit` • 🪄 `direnv` • 🎨 `git-delta` • 🧭 `zoxide` • 🧰 `just` • 🧾 `yq` • ⚡ `xh` • 🌍 `curlie` • 🏠 `chezmoi` • 🛠️ `shfmt` • ✅ `shellcheck` • 🐳 `hadolint` • 🐍 `uv` • 🔁 `watchexec` | Extend via `~/.config/aquaproj-aqua/aqua.yaml` and run `aqua install`. Direnv logging is muted and hooks for direnv/zoxide are pre-configured for zsh, bash, and fish. |
 | **Container Workflow** | 🐳 Docker socket mount (`/var/run/docker.sock`) | Enables Docker CLIs inside the container; host Docker daemon required. |
 | **Runtime Environment** | 👤 Non-root user `toolbox` (UID/GID mapped) • 🗂️ `/workspace` mount | Maintains host permissions and isolates artifacts under `artifacts/ToolboxStack/toolbox-base`. |
 

ToolboxStack/output/toolbox-base/aqua.yaml

@@ -1,7 +1,7 @@
 version: 1.0.0
 registries:
   - type: standard
-    ref: v4.200.0
+    ref: v4.431.0
 packages:
   - name: cli/cli@v2.82.1
   - name: jesseduffield/lazygit@v0.55.1
@@ -16,3 +16,5 @@ packages:
   - name: mvdan/sh@v3.12.0
   - name: koalaman/shellcheck@v0.11.0
   - name: hadolint/hadolint@v2.14.0
+  - name: astral-sh/uv@v0.9.5
+  - name: watchexec/watchexec@v2.3.2

ToolboxStack/output/toolbox-template/.devcontainer/devcontainer.json

@@ -0,0 +1,14 @@
+{
+  "name": "TSYSDevStack {{toolbox_name}}",
+  "dockerComposeFile": [
+    "../docker-compose.yml"
+  ],
+  "service": "{{toolbox_name}}",
+  "workspaceFolder": "/workspace",
+  "remoteUser": "toolbox",
+  "runServices": [
+    "{{toolbox_name}}"
+  ],
+  "overrideCommand": false,
+  "postCreateCommand": "zsh -lc 'starship --version >/dev/null'"
+}

ToolboxStack/output/toolbox-template/PROMPT

@@ -0,0 +1,25 @@
+You are Codex, collaborating with a human on the TSYSDevStack ToolboxStack project.
+
+- Seed context:
+  - `SEED` captures the initial scope. Edit it once to define goals, then treat it as read-only unless the high-level objectives change.
+  - Start each session by reading it (`cat SEED`) and summarize progress or adjustments here in PROMPT.
+
+Context snapshot ({{toolbox_name}}):
+- Working directory: artifacts/ToolboxStack/{{toolbox_name}}
+- Image: tsysdevstack-toolboxstack-{{toolbox_name}} (Ubuntu 24.04)
+- Container user: toolbox (non-root, UID/GID mapped to host)
+- Mounted workspace: current repo at /workspace (rw)
+
+Current state:
+- Seed items above still need to be translated into Dockerfile/tooling work.
+- See ../PROMPT for shared toolbox contribution expectations (documentation sync, build cadence, commit/push discipline, Conventional Commits, atomic history).
+
+Collaboration checklist:
+1. Translate SEED goals into concrete tooling decisions; mirror outcomes in README.md and this PROMPT (do not rewrite SEED unless the scope resets).
+2. Prefer aqua-managed CLIs and mise-managed runtimes for reproducibility.
+3. After each tooling change, update README/PROMPT, run ./build.sh, commit (Conventional Commit message, focused diff), and push only once the build succeeds per ../PROMPT.
+4. Record verification steps (build/test commands) as they are performed.
+5. Maintain UID/GID mapping and non-root execution.
+
+Active focus:
+- Initialize {{toolbox_name}} using the toolbox-template scaffolding; evolve the Dockerfile/tooling inventory to satisfy the SEED goals.

ToolboxStack/output/toolbox-template/SEED

@@ -0,0 +1,3 @@
+- TODO: describe what this toolbox should provide (languages, CLIs, workflows).
+- TODO: list required base image modifications or additional mounts.
+- TODO: note verification or testing expectations specific to this toolbox.

ToolboxStack/output/toolbox-template/build.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+IMAGE_NAME="tsysdevstack-toolboxstack-{{toolbox_name}}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+USER_ID="${USER_ID_OVERRIDE:-$(id -u)}"
+GROUP_ID="${GROUP_ID_OVERRIDE:-$(id -g)}"
+USERNAME="${USERNAME_OVERRIDE:-toolbox}"
+TEA_VERSION="${TEA_VERSION_OVERRIDE:-0.11.1}"
+BUILDER_NAME="${BUILDER_NAME:-tsysdevstack-toolboxstack-builder}"
+CACHE_DIR="${SCRIPT_DIR}/.build-cache"
+
+echo "Building ${IMAGE_NAME} with UID=${USER_ID} GID=${GROUP_ID} USERNAME=${USERNAME}"
+
+if ! docker buildx inspect "${BUILDER_NAME}" >/dev/null 2>&1; then
+    docker buildx create --driver docker-container --name "${BUILDER_NAME}" --use >/dev/null
+else
+    docker buildx use "${BUILDER_NAME}" >/dev/null
+fi
+
+mkdir -p "${CACHE_DIR}"
+
+docker buildx build \
+    --builder "${BUILDER_NAME}" \
+    --load \
+    --progress=plain \
+    --build-arg USER_ID="${USER_ID}" \
+    --build-arg GROUP_ID="${GROUP_ID}" \
+    --build-arg USERNAME="${USERNAME}" \
+    --build-arg TEA_VERSION="${TEA_VERSION}" \
+    --cache-from "type=local,src=${CACHE_DIR}" \
+    --cache-to "type=local,dest=${CACHE_DIR},mode=max" \
+    --tag "${IMAGE_NAME}" \
+    "${SCRIPT_DIR}"

ToolboxStack/output/toolbox-template/docker-compose.yml

@@ -0,0 +1,20 @@
+services:
+  {{toolbox_name}}:
+    container_name: tsysdevstack-toolboxstack-{{toolbox_name}}
+    image: tsysdevstack-toolboxstack-{{toolbox_name}}
+    build:
+      context: .
+      args:
+        USER_ID: ${LOCAL_UID:-1000}
+        GROUP_ID: ${LOCAL_GID:-1000}
+        USERNAME: ${LOCAL_USERNAME:-toolbox}
+    user: "${LOCAL_UID:-1000}:${LOCAL_GID:-1000}"
+    working_dir: /workspace
+    command: ["sleep", "infinity"]
+    init: true
+    tty: true
+    stdin_open: true
+    volumes:
+      - .:/workspace:rw
+      - ${HOME}/.local/share/mise:/home/toolbox/.local/share/mise:rw
+      - ${HOME}/.cache/mise:/home/toolbox/.cache/mise:rw

ToolboxStack/output/toolbox-template/run.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+COMPOSE_FILE="${SCRIPT_DIR}/docker-compose.yml"
+
+export LOCAL_UID="${USER_ID_OVERRIDE:-$(id -u)}"
+export LOCAL_GID="${GROUP_ID_OVERRIDE:-$(id -g)}"
+export LOCAL_USERNAME="${USERNAME_OVERRIDE:-toolbox}"
+
+if [[ ! -f "${COMPOSE_FILE}" ]]; then
+    echo "Error: docker-compose.yml not found at ${COMPOSE_FILE}" >&2
+    exit 1
+fi
+
+ACTION="${1:-up}"
+shift || true
+
+if [[ "${ACTION}" == "up" ]]; then
+    mkdir -p "${HOME}/.local/share/mise" "${HOME}/.cache/mise"
+fi
+
+case "${ACTION}" in
+    up)
+        docker compose -f "${COMPOSE_FILE}" up --build --detach "$@"
+        ;;
+    down)
+        docker compose -f "${COMPOSE_FILE}" down "$@"
+        ;;
+    *)
+        echo "Usage: $0 [up|down] [additional docker compose args]" >&2
+        exit 1
+        ;;
+esac