# 🧰 TSYSDevStack Toolbox Template

Template for creating new toolboxes that extend from the `toolbox-base` image.

---

## 🚀 Quick Start

1. **Create a new toolbox**
   ```bash
   cp -r /path/to/toolbox-template /path/to/new-toolbox
   cd /path/to/new-toolbox
   ```
   
2. **Customize the toolbox**
   - Edit `Dockerfile` to add toolbox-specific tooling
   - Modify `docker-compose.yml` to adjust service configuration
   - Update `SEED` to define the toolbox's purpose and goals
   
3. **Build the toolbox**
   ```bash
   ./build.sh
   ```
   
4. **Start the toolbox**
   ```bash
   ./run.sh up
   ```
   
5. **Access the toolbox**
   ```bash
   docker exec -it tsysdevstack-toolboxstack-<toolbox-name> zsh
   ```
   
6. **Stop the toolbox**
   ```bash
   ./run.sh down
   ```

---

## 🧱 Architecture

- **Base Image**: Extends from `tsysdevstack-toolboxstack-toolbox-base:release-current`
- **User**: Runs as non-root `toolbox` user (UID/GID mapped to host)
- **Workspace**: Mounts current directory to `/workspace` (read/write)
- **Runtime**: Inherits all tooling from base plus toolbox-specific additions

---

## 🛠️ Customization

### Dockerfile
Extend the base image with toolbox-specific tooling:
```dockerfile
# Extend from the toolbox-base image
FROM tsysdevstack-toolboxstack-toolbox-base:release-current

# Add toolbox-specific packages or configurations
RUN apt-get update && apt-get install -y --no-install-recommends \
    specific-package \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*
```

### docker-compose.yml
Adjust service configuration for toolbox-specific needs:
```yaml
services:
  my-toolbox:
    # Inherits all base configuration
    # Add toolbox-specific volumes, ports, etc.
    volumes:
      - ./custom-config:/home/toolbox/.config/custom-tool
```

### SEED
Define the toolbox's purpose and goals:
```markdown
- Describe what this toolbox should provide (languages, CLIs, workflows)
- List required base image modifications or additional mounts
- Note verification or testing expectations specific to this toolbox
```

---

## 📂 Project Layout

| Path | Purpose |
|------|---------|
| `Dockerfile` | Extends base image with toolbox-specific tooling |
| `docker-compose.yml` | Service configuration for the toolbox |
| `build.sh` | Wrapper around `docker build` with host UID/GID mapping |
| `run.sh` | Helper to bring the service up/down |
| `.devcontainer/devcontainer.json` | VS Code remote container definition |
| `SEED` | Defines the toolbox's purpose and goals |
| `PROMPT` | LLM onboarding prompt for future contributors |

---

## 🤝 Collaboration Notes

- Inherits all collaboration policies from `toolbox-base`
- Document toolbox-specific additions in `README.md` and `PROMPT`
- Update `SEED` only when the high-level objectives change
- Prefer aqua/mise for new tooling to keep installations reproducible
- Keep documentation synchronized for future contributors