# Capability: Tool Workshop

## Overview

The Tool Workshop is the unified interface for defining, configuring, and managing development tools. It consolidates tool type management, tool configuration, and config folder management into a single powerful interface.

## Functional Requirements

### FR-1: Tool Type Definition
- Users can create new tool types with either Docker Compose or Dockerfile
- Tool types specify: name, display name, description, category, interfaces, port, definition type, template
- Built-in tool types can be viewed but not edited
- Tool types can be deleted (with cascade deletion of associated configs)

### FR-2: Tool Configuration
- Users can create tool configurations per tool type
- Configs can be global (all projects) or project-scoped
- Configs support: key-value pairs (env/file), port override, start command, working directory, environment variables, volumes
- Configs are mounted into containers when instances are created

### FR-3: Config Folder Management
- Users can create named collections of configuration files
- Each folder has a default mount path in containers
- Folders can be activated/deactivated
- Folders support per-project overrides
- Active folders are automatically mounted into new instances

### FR-4: Readiness Probes
- Tool types can define a readiness probe command
- Instance creation waits for the probe to succeed
- Probes have configurable timeout and check interval
- Failed probes mark instances as "failed" with logs

### FR-5: Instance Integration
- Instance creation uses tool type definition (compose or dockerfile)
- Instance creation applies tool configs (env vars, files, volumes)
- Instance creation mounts active config folders
- Instance creation executes readiness probe
- Instance status reflects probe result

## Non-Functional Requirements

### NFR-1: Performance
- Tool Workshop page loads in < 2 seconds
- Config folder operations complete in < 500ms
- Instance creation with dockerfile build completes in < 5 minutes

### NFR-2: Usability
- UI is intuitive for both technical and non-technical users
- Clear validation messages for all fields
- Progressive disclosure of advanced options
- Responsive design for mobile devices

### NFR-3: Security
- Users can only access their own tool types, configs, and folders
- File paths in config folders are sanitized (no path traversal)
- Dockerfile builds run in isolated context
- Config values are never logged or exposed

## State Diagram

```
┌─────────────┐
│   DRAFT     │
└──────┬──────┘
       │ Create
       ▼
┌─────────────┐     Edit     ┌─────────────┐
│   ACTIVE    │◀────────────▶│   UPDATED   │
└──────┬──────┘              └─────────────┘
       │
       │ Delete
       ▼
┌─────────────┐
│  DELETED    │
└─────────────┘
```

## API Specification

See `design.md` for complete endpoint list.

## UI Specification

See `design.md` for complete UI mockups.

## Acceptance Criteria

- [ ] User can create a tool type with dockerfile and start an instance
- [ ] User can create a tool type with compose and start an instance
- [ ] User can create config folders and mount them into instances
- [ ] User can set project overrides on config folders
- [ ] Readiness probes wait for tools to be ready before marking running
- [ ] Failed readiness probes show clear error messages
- [ ] All new fields are persisted and retrieved correctly
- [ ] UI is responsive and intuitive