# Tool Workshop User Guide

## Overview

The Tool Workshop lets you define and manage tool types — the blueprints for
containers that run inside Headquarter. Each tool type specifies how to build
and start a container (Docker image, Compose file, or a declarative manifest).

## Definition Types

### 1. Compose (Legacy)
Write a raw Docker Compose template. Variable substitution is supported:
- `${REPO_PATH}` — path to the mounted repository
- `${TOOL_PORT}` — dynamically assigned free port
- `${INSTANCE_NAME}` — generated instance name
- `${USER_ID}`, `${PROJECT_ID}` — IDs for reference

Best for: simple web services, databases, or anything that already has a
Docker image.

### 2. Dockerfile (Legacy)
Write a raw Dockerfile. Headquarter builds the image and generates a minimal
Compose file automatically.

Best for: custom environments where you need full control over the image build.

### 3. Manifest (Declarative) — **Recommended**
Define your tool with structured JSON instead of raw Docker files:
- **Base image** — pick a base definition (e.g. `ubuntu-24.04-dev`)
- **Packages** — declare apt, npm global, pip, and Node.js version
- **Scripts** — build scripts (run at image build time) and startup scripts
  (run when container starts)
- **Mounts** — workspace, SSH keys, instance state, git-mounted dotfiles
- **Runtime** — command, working directory, stdin/tty settings
- **Live preview** — see generated Dockerfile and Compose as you edit

Best for: reproducible, versioned, self-documenting tool definitions.

## Creating a Manifest-Based Tool

1. Go to **Settings → Tool Workshop**
2. Click **New Tool Type**
3. Select **Manifest (Declarative)** as the definition type
4. Choose a **Base Image** (e.g. `ubuntu-24.04-dev v1`)
5. Add packages:
   - Apt: `neovim`, `tmux`, `git`
   - NPM global: `@earendil-works/pi-coding-agent`
   - Node.js version: `20`
6. Add build scripts (e.g. configure git defaults)
7. Add startup scripts (e.g. fix workspace permissions)
8. Configure mounts:
   - Workspace → `/workspace` (writable)
   - SSH keys → `/home/user/.ssh` (readonly, mode 0700)
9. Set runtime: command `/bin/bash`, working dir `/workspace`
10. Click **Preview** to verify generated Dockerfile and Compose
11. Save

## Base Definitions

Base definitions are versioned manifest templates that other tools extend.
They are marked with the **Base** badge in the list.

The default base `ubuntu-24.04-dev` provides:
- Ubuntu 24.04 base image
- Common build tools (curl, wget, git, build-essential)
- A non-root `user` account (uid 1000)

## Migration from Legacy

Existing tool types using Compose or Dockerfile continue to work unchanged.
You can migrate a tool type to Manifest by:
1. Editing the tool type
2. Switching definition type to **Manifest**
3. Re-creating the configuration in the manifest editor
4. Saving (the old template is cleared automatically)

## Permissions

For manifest-based tools, mount permissions are fixed automatically after the
container starts. The system runs `chown` and `chmod` via `docker exec` as
root, then drops back to the configured runtime user.