.

artifacts/ToolboxStack/toolbox-base/PROMPT

@@ -12,15 +12,15 @@ Current state:
 - 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.
 - Devcontainer config ( .devcontainer/devcontainer.json ) references the compose service.
-- Documentation: docs/TOOLS.md tracks tooling inventory and must stay current.
+- Documentation: README.md (tooling inventory & workflow) and this PROMPT must stay current.
 
 Collaboration guidelines:
 1. Default to non-destructive operations; respect existing scripts run.sh/build.sh.
-2. Any tooling changes require updating docs/TOOLS.md (inventory) and this prompt summary.
+2. Any tooling changes require updating README.md (inventory) and this prompt summary.
 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.
 
 Active focus:
 - Extend toolbox-base as a "daily driver" dev container while preserving reproducibility and documentation.
-- Next contributor should review docs/TOOLS.md before modifying tooling and ensure both docs and this prompt reflect new state.
+- Next contributor should review README.md before modifying tooling and ensure both README and this prompt reflect new state.

artifacts/ToolboxStack/toolbox-base/README.md

@@ -0,0 +1,81 @@
+# 🧰 TSYSDevStack Toolbox Base
+
+Daily-driver development container for ToolboxStack work. It provides a reproducible Ubuntu 24.04 environment with curated shell tooling, package managers, and helper scripts.
+
+---
+
+## 🚀 Quick Start
+
+1. **Build the image**
+   ```bash
+   ./build.sh
+   ```
+2. **Start the container**
+   ```bash
+   ./run.sh up
+   ```
+3. **Attach to a shell**
+   ```bash
+   docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh
+   # or: bash / fish
+   ```
+4. **Stop the container**
+   ```bash
+   ./run.sh down
+   ```
+
+The compose service mounts the current repo to `/workspace` (read/write) and runs as the mapped host user (`toolbox`).
+
+---
+
+## 🧩 Tooling Inventory
+
+| Category | Tooling | Notes |
+|----------|---------|-------|
+| **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`) • 🔍 `ripgrep` • 🧭 `fzf` • 📁 `fd` • 📖 `bat` • 🔗 `openssh-client` • 🧵 `tmux` • 🖥️ `screen` • 📊 `jq` | Provides ergonomic defaults plus toolchain deps for compiling runtimes (no global language installs). |
+| **Aqua-Managed CLIs** | 🐙 `gh` • 🫖 `tea` • 🌀 `lazygit` | Extend via `~/.config/aquaproj-aqua/aqua.yaml` and run `aqua install`. |
+| **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`. |
+
+---
+
+## 🛠️ Extending the Sandbox
+
+- **Add a runtime**: `mise use python@3.12` (per project). Run inside `/workspace` to persist `.mise.toml`.
+- **Add a CLI tool**: update `~/.config/aquaproj-aqua/aqua.yaml`, then run `aqua install`.
+- **Adjust base image**: modify `Dockerfile`, run `./build.sh`, and keep this README & `PROMPT` in sync.
+
+> 🔁 **Documentation policy:** Whenever you add/remove tooling or change the developer experience, update both this README and the `PROMPT` file so the next collaborator has an accurate snapshot.
+
+---
+
+## 📂 Project Layout
+
+| Path | Purpose |
+|------|---------|
+| `Dockerfile` | Defines the toolbox-base image. |
+| `docker-compose.yml` | Compose service providing the container runtime. |
+| `build.sh` | Wrapper around `docker build` with host UID/GID mapping. |
+| `run.sh` | Helper to bring the compose service up/down (exports UID/GID env vars). |
+| `.devcontainer/devcontainer.json` | VS Code remote container definition. |
+| `aqua.yaml` | Default aqua configuration (gh, tea, lazygit). |
+| `PROMPT` | LLM onboarding prompt for future contributors (must remain current). |
+
+---
+
+## ✅ Verification Checklist
+
+After any image changes:
+1. Run `./build.sh` and ensure it succeeds.
+2. Optionally `./run.sh up` and sanity-check key tooling (e.g., `mise --version`, `gh --version`).
+3. Update this README and the `PROMPT` with any new or removed tooling.
+
+---
+
+## 🤝 Collaboration Notes
+
+- Container always runs as the mapped non-root user; avoid adding steps that require root login.
+- Prefer `mise`/`aqua` for new tooling to keep installations reproducible.
+- Keep documentation synchronized (README + PROMPT) so future contributors can resume quickly.

artifacts/ToolboxStack/toolbox-base/aqua.yaml

@@ -6,3 +6,6 @@ packages:
   - name: cli/cli@latest
   - name: go-gitea/tea@latest
   - name: jesseduffield/lazygit@latest
+  - name: direnv/direnv@latest
+  - name: dandavison/delta@latest
+  - name: ajeetdsouza/zoxide@latest

artifacts/ToolboxStack/toolbox-base/docs/TOOLS.md

@@ -1,20 +0,0 @@
-# 🧰 TSYSDevStack Toolbox Base – Installed Tooling
-
-| Category | Tooling | Notes |
-|----------|---------|-------|
-| Shells & Prompts | 🐚 `zsh` • 🐟 `fish` • 🧑‍💻 `bash` • ⭐ `starship` • 💎 `oh-my-zsh` | Shell choice is flexible; Starship prompt configured for all three; oh-my-zsh with `git` + `fzf` plugins. |
-| Runtime & CLI Managers | 🪄 `mise` • 💧 `aqua` | `mise` manages language/tool runtimes (activated for zsh/bash/fish); `aqua` manages standalone CLIs (global config under `~/.config/aquaproj-aqua/aqua.yaml`). |
-| Core CLI Utilities | 📦 `curl` • 📥 `wget` • 🔐 `ca-certificates` • 🧭 `git` • 🔧 `build-essential` + headers • 🔍 `ripgrep` • 🧭 `fzf` • 📁 `fd` • 📖 `bat` • 🔗 `openssh-client` • 🧵 `tmux` • 🖥️ `screen` • 📊 `jq` | Provides day-to-day development ergonomics and compile toolchain requirements (openssl/zlib/sqlite/readline/ffi headers, pkg-config). |
-| Aqua-Managed CLIs | 🐙 `gh` • 🫖 `tea` • 🌀 `lazygit` | Installed via aqua; extendable by editing `~/.config/aquaproj-aqua/aqua.yaml`. |
-| Container Workflow | 🐳 Docker integration via host Docker socket | Compose file binds `/var/run/docker.sock` read-only; `docker` CLI expected on host. |
-| Misc | 🗂️ `/workspace` mount (rw) • 👤 Non-root user `toolbox` mapped to host UID/GID | Container runs as the mapped host user; current repo mounted to `/workspace`. |
-
-## Usage Highlights
-
-1. Build the image: `./build.sh`  
-2. Start the dev environment: `./run.sh up`  
-3. Attach a shell: `docker exec -it tsysdevstack-toolboxstack-toolbox-base zsh` (or `bash` / `fish`)  
-4. Manage runtimes: `mise use python@3.12` (per project)  
-5. Install extra CLIs: add entries to `~/.config/aquaproj-aqua/aqua.yaml` then run `aqua install`  
-
-> ℹ️ **Documentation policy:** Update this file whenever tooling changes (new utilities, removals, or configuration shifts) so contributors always have an accurate inventory.