feat: implement tool workshop - comprehensive tool system enhancement

- Add Docker Compose and Dockerfile support for tool definitions - Implement readiness probes with configurable command, timeout, interval - Create ConfigFolder model for reusable file collections with project overrides - Add rich tool config fields: port_override, start_command, working_directory, env vars, volumes - Build unified Tool Workshop UI at /tool-workshop replacing /tool-configs and /tool-types - Update instance creation to support dockerfile builds, config folder mounting, readiness probes - Add 3 database migrations for tool_types, tool_configs, and new config_folders table - Create docker_build.py and readiness_probe.py services - Add config_folders API with CRUD and project override endpoints Quality gates: frontend build passes, Python syntax valid, all phases complete Addresses tool-workshop OpenSpec change
2026-05-22 19:06:45 +02:00
parent ae377baa74
commit 8dd350286e
28 changed files with 3328 additions and 79 deletions
@@ -0,0 +1,40 @@
+"""add_tool_config_fields
+
+Revision ID: 398082499c30
+Revises: af8512103d67
+Create Date: 2026-05-22 18:38:20.166184
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '398082499c30'
+down_revision = 'af8512103d67'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add new columns to tool_configs
+    op.add_column('tool_configs', sa.Column('port_override', sa.Integer(), nullable=True))
+    op.add_column('tool_configs', sa.Column('start_command', sa.Text(), nullable=True))
+    op.add_column('tool_configs', sa.Column('working_directory', sa.Text(), nullable=True))
+    op.add_column('tool_configs', sa.Column('environment_variables', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='{}'))
+    op.add_column('tool_configs', sa.Column('volumes', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='[]'))
+    
+    # Add CHECK constraint for port range
+    op.create_check_constraint('chk_port_range', 'tool_configs', sa.text('port_override IS NULL OR (port_override >= 1 AND port_override <= 65535)'))
+
+
+def downgrade() -> None:
+    # Drop CHECK constraint
+    op.drop_constraint('chk_port_range', 'tool_configs', type_='check')
+    
+    # Drop columns
+    op.drop_column('tool_configs', 'port_override')
+    op.drop_column('tool_configs', 'start_command')
+    op.drop_column('tool_configs', 'working_directory')
+    op.drop_column('tool_configs', 'environment_variables')
+    op.drop_column('tool_configs', 'volumes')
@@ -0,0 +1,44 @@
+"""create_config_folders_table
+
+Revision ID: 8ed7dd80973d
+Revises: 398082499c30
+Create Date: 2026-05-22 18:38:22.133696
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '8ed7dd80973d'
+down_revision = '398082499c30'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        'config_folders',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('name', sa.String(255), nullable=False),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('mount_path', sa.String(1024), nullable=False),
+        sa.Column('files', postgresql.JSONB(astext_type=sa.Text()), nullable=False, server_default='{}'),
+        sa.Column('project_overrides', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='{}'),
+        sa.Column('is_active', sa.Boolean(), nullable=False, server_default='true'),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.UniqueConstraint('user_id', 'name', name='uq_config_folders_user_name')
+    )
+    
+    # Add index on user_id for filtering
+    op.create_index('idx_config_folders_user', 'config_folders', ['user_id'])
+
+
+def downgrade() -> None:
+    # Drop index
+    op.drop_index('idx_config_folders_user', table_name='config_folders')
+    
+    # Drop table
+    op.drop_table('config_folders')
@@ -0,0 +1,38 @@
+"""add_tool_type_fields
+
+Revision ID: af8512103d67
+Revises: 0012_default_port_req
+Create Date: 2026-05-22 18:37:56.607240
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = 'af8512103d67'
+down_revision = '0012_default_port_req'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Add new columns to tool_types
+    op.add_column('tool_types', sa.Column('definition_type', sa.String(20), nullable=False, server_default='compose'))
+    op.add_column('tool_types', sa.Column('dockerfile_template', sa.Text(), nullable=True))
+    op.add_column('tool_types', sa.Column('build_context', postgresql.JSONB(astext_type=sa.Text()), nullable=True, server_default='{}'))
+    op.add_column('tool_types', sa.Column('readiness_probe', postgresql.JSONB(astext_type=sa.Text()), nullable=True))
+    
+    # Add CHECK constraint for definition_type
+    op.create_check_constraint('chk_definition_type', 'tool_types', sa.text("definition_type IN ('compose', 'dockerfile')"))
+
+
+def downgrade() -> None:
+    # Drop CHECK constraint
+    op.drop_constraint('chk_definition_type', 'tool_types', type_='check')
+    
+    # Drop columns
+    op.drop_column('tool_types', 'definition_type')
+    op.drop_column('tool_types', 'dockerfile_template')
+    op.drop_column('tool_types', 'build_context')
+    op.drop_column('tool_types', 'readiness_probe')
@@ -0,0 +1,327 @@
+"""Config folder API endpoints."""
+
+import logging
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel, Field, field_validator
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from src.auth.dependencies import get_current_user_id, get_db_session
+from src.models.config_folder import ConfigFolder
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/config-folders", tags=["config-folders"])
+
+MAX_FOLDER_SIZE_MB = 10
+MAX_FOLDER_SIZE_BYTES = MAX_FOLDER_SIZE_MB * 1024 * 1024
+
+
+class ConfigFolderCreate(BaseModel):
+    name: str = Field(description="Folder name (unique per user)")
+    description: str | None = Field(default=None, description="Optional description")
+    mount_path: str = Field(description="Default mount path in container")
+    files: dict = Field(default_factory=dict, description="Files as {path: content}")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str) -> str:
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict) -> dict:
+        total_size = 0
+        for path, content in v.items():
+            # Check for path traversal
+            if ".." in path or path.startswith("/"):
+                raise ValueError(f"Invalid file path: {path}")
+            total_size += len(content.encode("utf-8"))
+        
+        if total_size > MAX_FOLDER_SIZE_BYTES:
+            raise ValueError(f"Total folder size exceeds {MAX_FOLDER_SIZE_MB}MB limit")
+        
+        return v
+
+
+class ConfigFolderUpdate(BaseModel):
+    name: str | None = Field(default=None, description="Folder name")
+    description: str | None = Field(default=None, description="Optional description")
+    mount_path: str | None = Field(default=None, description="Default mount path")
+    files: dict | None = Field(default=None, description="Files as {path: content}")
+    is_active: bool | None = Field(default=None, description="Active/inactive toggle")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+    @field_validator("files")
+    @classmethod
+    def validate_files(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        
+        total_size = 0
+        for path, content in v.items():
+            # Check for path traversal
+            if ".." in path or path.startswith("/"):
+                raise ValueError(f"Invalid file path: {path}")
+            total_size += len(content.encode("utf-8"))
+        
+        if total_size > MAX_FOLDER_SIZE_BYTES:
+            raise ValueError(f"Total folder size exceeds {MAX_FOLDER_SIZE_MB}MB limit")
+        
+        return v
+
+
+class ProjectOverrideCreate(BaseModel):
+    mount_path: str | None = Field(default=None, description="Override mount path")
+    files: dict = Field(default_factory=dict, description="Override files")
+
+    @field_validator("mount_path")
+    @classmethod
+    def validate_mount_path(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if not v.startswith("/"):
+            raise ValueError("Mount path must be absolute (start with /)")
+        return v
+
+
+class ConfigFolderResponse(BaseModel):
+    id: str
+    user_id: str
+    name: str
+    description: str | None
+    mount_path: str
+    files: dict
+    project_overrides: dict | None
+    is_active: bool
+    created_at: str
+    updated_at: str
+
+
+@router.get("", summary="List config folders", description="Get all config folders for the current user.")
+async def list_config_folders(
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """List config folders for the current user."""
+    query = select(ConfigFolder).where(ConfigFolder.user_id == user_id)
+    result = await session.execute(query)
+    folders = result.scalars().all()
+    
+    return {
+        "folders": [
+            {
+                "id": str(f.id),
+                "user_id": str(f.user_id),
+                "name": f.name,
+                "description": f.description,
+                "mount_path": f.mount_path,
+                "files": f.files,
+                "project_overrides": f.project_overrides,
+                "is_active": f.is_active,
+                "created_at": f.created_at.isoformat() if f.created_at else None,
+                "updated_at": f.updated_at.isoformat() if f.updated_at else None,
+            }
+            for f in folders
+        ]
+    }
+
+
+@router.post("", summary="Create config folder", description="Create a new config folder.")
+async def create_config_folder(
+    data: ConfigFolderCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Create a config folder."""
+    # Check for duplicate name
+    existing = await session.scalar(
+        select(ConfigFolder).where(
+            ConfigFolder.user_id == user_id,
+            ConfigFolder.name == data.name,
+        )
+    )
+    if existing:
+        raise HTTPException(
+            status_code=status.HTTP_409_CONFLICT,
+            detail=f"config folder with name '{data.name}' already exists"
+        )
+    
+    folder = ConfigFolder(
+        user_id=user_id,
+        name=data.name,
+        description=data.description,
+        mount_path=data.mount_path,
+        files=data.files,
+    )
+    session.add(folder)
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "user_id": str(folder.user_id),
+        "name": folder.name,
+        "description": folder.description,
+        "mount_path": folder.mount_path,
+        "files": folder.files,
+        "project_overrides": folder.project_overrides,
+        "is_active": folder.is_active,
+        "created_at": folder.created_at.isoformat() if folder.created_at else None,
+        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
+    }
+
+
+@router.put("/{folder_id}", summary="Update config folder", description="Update an existing config folder.")
+async def update_config_folder(
+    folder_id: uuid.UUID,
+    data: ConfigFolderUpdate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Update a config folder."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    if data.name is not None:
+        folder.name = data.name
+    if data.description is not None:
+        folder.description = data.description
+    if data.mount_path is not None:
+        folder.mount_path = data.mount_path
+    if data.files is not None:
+        folder.files = data.files
+    if data.is_active is not None:
+        folder.is_active = data.is_active
+    
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "user_id": str(folder.user_id),
+        "name": folder.name,
+        "description": folder.description,
+        "mount_path": folder.mount_path,
+        "files": folder.files,
+        "project_overrides": folder.project_overrides,
+        "is_active": folder.is_active,
+        "created_at": folder.created_at.isoformat() if folder.created_at else None,
+        "updated_at": folder.updated_at.isoformat() if folder.updated_at else None,
+    }
+
+
+@router.delete("/{folder_id}", summary="Delete config folder", description="Delete a config folder.")
+async def delete_config_folder(
+    folder_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Delete a config folder."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    await session.delete(folder)
+    await session.commit()
+
+
+@router.post("/{folder_id}/overrides", summary="Add project override", description="Add a project override to a config folder.")
+async def add_project_override(
+    folder_id: uuid.UUID,
+    project_id: uuid.UUID,
+    data: ProjectOverrideCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Add a project override to a config folder."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    # Initialize project_overrides if None
+    if folder.project_overrides is None:
+        folder.project_overrides = {}
+    
+    # Add/update override
+    override_data = {}
+    if data.mount_path is not None:
+        override_data["mount_path"] = data.mount_path
+    if data.files is not None:
+        override_data["files"] = data.files
+    
+    folder.project_overrides[str(project_id)] = override_data
+    
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "project_overrides": folder.project_overrides,
+    }
+
+
+@router.put("/{folder_id}/overrides/{project_id}", summary="Update project override", description="Update a project override.")
+async def update_project_override(
+    folder_id: uuid.UUID,
+    project_id: uuid.UUID,
+    data: ProjectOverrideCreate,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Update a project override."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    # Initialize project_overrides if None
+    if folder.project_overrides is None:
+        folder.project_overrides = {}
+    
+    # Update override
+    override_data = folder.project_overrides.get(str(project_id), {})
+    if data.mount_path is not None:
+        override_data["mount_path"] = data.mount_path
+    if data.files is not None:
+        override_data["files"] = data.files
+    
+    folder.project_overrides[str(project_id)] = override_data
+    
+    await session.commit()
+    await session.refresh(folder)
+    
+    return {
+        "id": str(folder.id),
+        "project_overrides": folder.project_overrides,
+    }
+
+
+@router.delete("/{folder_id}/overrides/{project_id}", summary="Remove project override", description="Remove a project override.")
+async def remove_project_override(
+    folder_id: uuid.UUID,
+    project_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> None:
+    """Remove a project override."""
+    folder = await session.get(ConfigFolder, folder_id)
+    if folder is None or folder.user_id != user_id:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="config folder not found")
+    
+    # Remove override if exists
+    if folder.project_overrides and str(project_id) in folder.project_overrides:
+        del folder.project_overrides[str(project_id)]
+        await session.commit()
@@ -24,6 +24,45 @@ class ToolConfigCreate(BaseModel):
    value: str = Field(description="Config value")
    config_type: str = Field(default="env", description="Type: env or file")
    file_path: str | None = Field(default=None, description="File path for file-type configs")
+    port_override: int | None = Field(default=None, description="Port override (1-65535)")
+    start_command: str | None = Field(default=None, description="Override container start command")
+    working_directory: str | None = Field(default=None, description="Working directory inside container")
+    environment_variables: dict | None = Field(default=None, description="Environment variables as JSON object")
+    volumes: list[dict] | None = Field(default=None, description="Volume mounts as JSON array")
+
+    @field_validator("port_override")
+    @classmethod
+    def validate_port(cls, v: int | None) -> int | None:
+        if v is None:
+            return v
+        if v < 1 or v > 65535:
+            raise ValueError("Port must be between 1 and 65535")
+        return v
+
+    @field_validator("environment_variables")
+    @classmethod
+    def validate_env_vars(cls, v: dict | None) -> dict | None:
+        if v is None:
+            return v
+        if not isinstance(v, dict):
+            raise ValueError("environment_variables must be a JSON object")
+        return v
+
+    @field_validator("volumes")
+    @classmethod
+    def validate_volumes(cls, v: list | None) -> list | None:
+        if v is None:
+            return v
+        if not isinstance(v, list):
+            raise ValueError("volumes must be a JSON array")
+        for i, vol in enumerate(v):
+            if not isinstance(vol, dict):
+                raise ValueError(f"Volume at index {i} must be an object")
+            if "source" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'source' field")
+            if "target" not in vol:
+                raise ValueError(f"Volume at index {i} must have 'target' field")
+        return v


 class ToolConfigResponse(BaseModel):
@@ -34,6 +73,11 @@ class ToolConfigResponse(BaseModel):
    value: str
    config_type: str
    file_path: str | None
+    port_override: int | None
+    start_command: str | None
+    working_directory: str | None
+    environment_variables: dict | None
+    volumes: list[dict] | None


@router.get("", summary="List tool configs", description="Get all tool configs for the current user.")
@@ -67,6 +111,11 @@ async def list_configs(
                "value": c.value,
                "config_type": c.config_type,
                "file_path": c.file_path,
+                "port_override": c.port_override,
+                "start_command": c.start_command,
+                "working_directory": c.working_directory,
+                "environment_variables": c.environment_variables,
+                "volumes": c.volumes,
            }
            for c in configs
        ]
@@ -111,6 +160,11 @@ async def create_config(
        value=data.value,
        config_type=data.config_type,
        file_path=data.file_path,
+        port_override=data.port_override,
+        start_command=data.start_command,
+        working_directory=data.working_directory,
+        environment_variables=data.environment_variables,
+        volumes=data.volumes,
    )
    session.add(config)
    await session.commit()
@@ -124,6 +178,11 @@ async def create_config(
        "value": config.value,
        "config_type": config.config_type,
        "file_path": config.file_path,
+        "port_override": config.port_override,
+        "start_command": config.start_command,
+        "working_directory": config.working_directory,
+        "environment_variables": config.environment_variables,
+        "volumes": config.volumes,
    }


@@ -143,6 +202,11 @@ async def update_config(
    config.value = data.value
    config.config_type = data.config_type
    config.file_path = data.file_path
+    config.port_override = data.port_override
+    config.start_command = data.start_command
+    config.working_directory = data.working_directory
+    config.environment_variables = data.environment_variables
+    config.volumes = data.volumes
    
    await session.commit()
    await session.refresh(config)
@@ -155,6 +219,38 @@ async def update_config(
        "value": config.value,
        "config_type": config.config_type,
        "file_path": config.file_path,
+        "port_override": config.port_override,
+        "start_command": config.start_command,
+        "working_directory": config.working_directory,
+        "environment_variables": config.environment_variables,
+        "volumes": config.volumes,
+    }
+
+
+@router.get("/defaults/{tool_type_id}", summary="Get default configs", description="Get suggested default configs for a tool type.")
+async def get_default_configs(
+    tool_type_id: str,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Get suggested default configs for a tool type."""
+    tool_type = await session.get(ToolType, uuid.UUID(tool_type_id))
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    
+    # Return suggested defaults based on required_variables
+    defaults = []
+    for var in tool_type.required_variables:
+        defaults.append({
+            "key": var,
+            "value": "",
+            "config_type": "env",
+            "description": f"Required variable: {var}",
+        })
+    
+    return {
+        "tool_type_id": tool_type_id,
+        "defaults": defaults,
    }


@@ -22,6 +22,7 @@ from src.models.tool_config import ToolConfig
 from src.models.tool_instance import ToolInstance
 from src.models.tool_type import ToolType
 from src.models.user import User
+from src.models.config_folder import ConfigFolder
 from src.services.docker import (
    check_tunnel_health,
    connect_container_to_network,
@@ -37,7 +38,10 @@ from src.services.docker import (
    write_compose_file,
    write_config_files,
    write_env_file,
+    write_config_folder_files,
 )
+from src.services.docker_build import build_image
+from src.services.readiness_probe import execute_probe

 router = APIRouter(prefix="/projects", tags=["tool-instances"])

@@ -51,6 +55,58 @@ class CreateInstanceRequest(BaseModel):
    display_name: str | None = Field(default=None, description="Optional display name for the instance")


+def _modify_compose_file(
+    compose_path: str,
+    port_override: int | None = None,
+    start_command: str | None = None,
+    working_directory: str | None = None,
+    extra_volumes: list[dict] | None = None,
+) -> None:
+    """Modify compose file with runtime overrides."""
+    import yaml
+    from pathlib import Path
+
+    compose_file = Path(compose_path)
+    content = compose_file.read_text()
+    compose_data = yaml.safe_load(content)
+
+    if not compose_data or "services" not in compose_data:
+        return
+
+    # Apply modifications to the first service
+    for service_name, service_config in compose_data["services"].items():
+        if port_override and "ports" in service_config:
+            # Update port mapping
+            for i, port_mapping in enumerate(service_config["ports"]):
+                if isinstance(port_mapping, str) and ":" in port_mapping:
+                    host_port, container_port = port_mapping.split(":", 1)
+                    service_config["ports"][i] = f"{port_override}:{container_port}"
+                    break
+
+        if start_command:
+            service_config["command"] = start_command
+
+        if working_directory:
+            service_config["working_dir"] = working_directory
+
+        if extra_volumes:
+            if "volumes" not in service_config:
+                service_config["volumes"] = []
+            for vol in extra_volumes:
+                source = vol.get("source", "")
+                target = vol.get("target", "")
+                vol_type = vol.get("type", "bind")
+                if vol_type == "bind":
+                    service_config["volumes"].append(f"{source}:{target}")
+                else:
+                    service_config["volumes"].append(f"{source}:{target}:{vol_type}")
+
+        break  # Only modify the first service
+
+    # Write back
+    compose_file.write_text(yaml.dump(compose_data, default_flow_style=False))
+
+
 async def _get_user(session: AsyncSession, user_id: uuid.UUID) -> User:
    """Fetch a user by ID or raise 404 if not found."""
    user = await session.get(User, user_id)
@@ -145,18 +201,55 @@ async def create_instance(
        # Find free port
        tool_port = find_free_port()

-        # Render compose template
-        variables = {
-            "REPO_PATH": repo.path,
-            "INSTANCE_NAME": instance_name,
-            "INSTANCE_ID": instance_name,
-            "TOOL_NAME": instance_name,
-            "TOOL_PORT": tool_port,
-            "USER_ID": str(user_id),
-            "PROJECT_ID": str(project_id),
-        }
-        compose_content = render_compose_template(tool_type.compose_template, variables)
-        write_compose_file(instance_dir, compose_content)
+        # Handle based on definition type
+        if tool_type.definition_type == "dockerfile":
+            # Build image from Dockerfile
+            image_tag = f"headquarter/{instance_name}:latest"
+            
+            if tool_type.dockerfile_template:
+                returncode, stdout, stderr = build_image(
+                    instance_dir=instance_dir,
+                    dockerfile=tool_type.dockerfile_template,
+                    tag=image_tag,
+                    build_context=tool_type.build_context,
+                )
+                
+                if returncode != 0:
+                    logger.error("Failed to build image for instance %s: %s", instance_name, stderr)
+                    raise HTTPException(
+                        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                        detail=f"Failed to build Docker image: {stderr[:500]}",
+                    )
+                
+                logger.info("Successfully built image %s for instance %s", image_tag, instance_name)
+            
+            # Generate compose for dockerfile-built image
+            compose_content = f"""version: "3.8"
+services:
+  app:
+    image: {image_tag}
+    container_name: {instance_name}
+    ports:
+      - "{tool_port}:{tool_type.default_port}"
+    volumes:
+      - {repo.path}:/workspace
+    restart: unless-stopped
+"""
+            write_compose_file(instance_dir, compose_content)
+            
+        else:
+            # Render compose template
+            variables = {
+                "REPO_PATH": repo.path,
+                "INSTANCE_NAME": instance_name,
+                "INSTANCE_ID": instance_name,
+                "TOOL_NAME": instance_name,
+                "TOOL_PORT": tool_port,
+                "USER_ID": str(user_id),
+                "PROJECT_ID": str(project_id),
+            }
+            compose_content = render_compose_template(tool_type.compose_template, variables)
+            write_compose_file(instance_dir, compose_content)

        # Create database record
        instance = ToolInstance(
@@ -353,6 +446,11 @@ async def start_instance(
    # Fetch tool configs for this tool type
    env_vars = {}
    config_files = {}
+    port_override = None
+    start_command = None
+    working_directory = None
+    extra_env_vars = {}
+    extra_volumes = []
    
    config_query = select(ToolConfig).where(
        ToolConfig.user_id == user_id,
@@ -370,6 +468,30 @@ async def start_instance(
            env_vars[config.key] = config.value
        elif config.config_type == "file" and config.file_path:
            config_files[config.file_path] = config.value
+        
+        # Handle new config fields
+        if config.port_override:
+            port_override = config.port_override
+        if config.start_command:
+            start_command = config.start_command
+        if config.working_directory:
+            working_directory = config.working_directory
+        if config.environment_variables:
+            extra_env_vars.update(config.environment_variables)
+        if config.volumes:
+            extra_volumes.extend(config.volumes)
+    
+    # Merge extra env vars
+    env_vars.update(extra_env_vars)
+    
+    # Fetch active config folders for this user
+    folder_query = select(ConfigFolder).where(
+        ConfigFolder.user_id == user_id,
+        ConfigFolder.is_active == True,
+    )
+    folder_result = await session.execute(folder_query)
+    config_folders = folder_result.scalars().all()
+    logger.info("Found %d active config folders for instance %s", len(config_folders), instance.id)
    
    # Write env file and config files
    instance_dir = os.path.dirname(instance.compose_path)
@@ -382,6 +504,17 @@ async def start_instance(
    if config_files:
        write_config_files(instance_dir, config_files)
        logger.info("Wrote %d config files for instance %s", len(config_files), instance.id)
+    
+    # Write config folder files
+    if config_folders:
+        folder_volumes = write_config_folder_files(instance_dir, config_folders, str(project_id))
+        extra_volumes.extend(folder_volumes)
+        logger.info("Wrote config folders with %d volume mounts for instance %s", len(folder_volumes), instance.id)
+    
+    # Modify compose file if needed (port override, start command, working dir, volumes)
+    if port_override or start_command or working_directory or extra_volumes:
+        _modify_compose_file(instance.compose_path, port_override, start_command, working_directory, extra_volumes)
+        logger.info("Modified compose file for instance %s", instance.id)

    # Execute docker compose up with env file
    logger.info("Running docker compose up for instance %s (compose_path=%s)", instance.id, instance.compose_path)
@@ -419,9 +552,48 @@ async def start_instance(
        else:
            logger.warning("Failed to connect %s to backend network", container_name)

-    instance.status = "running"
+    instance.status = "starting"
    instance.last_started_at = datetime.now()
    await session.commit()
+    logger.info("Instance %s container is running, checking readiness", instance.id)
+
+    # Execute readiness probe if configured
+    tool_type = await session.get(ToolType, instance.tool_type_id)
+    if tool_type and tool_type.readiness_probe:
+        probe_config = tool_type.readiness_probe
+        probe_command = probe_config.get("command", "")
+        probe_timeout = probe_config.get("timeout", 30)
+        probe_interval = probe_config.get("interval", 2)
+        
+        if probe_command and instance.container_id:
+            logger.info(
+                "Executing readiness probe for instance %s: command='%s', timeout=%d, interval=%d",
+                instance.id, probe_command, probe_timeout, probe_interval
+            )
+            
+            success, probe_logs = await execute_probe(
+                container_id=instance.container_id,
+                command=probe_command,
+                timeout=probe_timeout,
+                interval=probe_interval,
+            )
+            
+            if not success:
+                instance.status = "failed"
+                instance.url = None
+                instance.public_url = None
+                await session.commit()
+                logger.error("Readiness probe failed for instance %s: %s", instance.id, "\n".join(probe_logs))
+                return {
+                    "status": "failed",
+                    "error": f"Readiness probe failed after {probe_timeout}s",
+                    "probe_logs": probe_logs,
+                }
+            
+            logger.info("Readiness probe succeeded for instance %s", instance.id)
+
+    instance.status = "running"
+    await session.commit()
    logger.info("Instance %s is now running", instance.id)

    # Get tool type for default port
@@ -38,14 +38,32 @@ class ToolTypeCreate(BaseModel):
    display_name: str
    description: str | None = None
    default_port: int
-    compose_template: str
+    definition_type: str = "compose"
+    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
    required_variables: list[str] = []
    category: str = "other"
    interfaces: list[str] = ["web"]

+    @field_validator("definition_type")
+    @classmethod
+    def validate_definition_type(cls, v: str) -> str:
+        if v not in ("compose", "dockerfile"):
+            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
+        return v
+
    @field_validator("compose_template")
    @classmethod
-    def validate_compose_template(cls, v: str) -> str:
+    def validate_compose_template(cls, v: str | None, info) -> str | None:
+        data = info.data
+        if data.get("definition_type") != "compose":
+            return v
+        
+        if v is None:
+            raise ValueError("compose_template is required when definition_type is 'compose'")
+        
        try:
            parsed = yaml.safe_load(v)
        except yaml.YAMLError as e:
@@ -62,6 +80,21 @@ class ToolTypeCreate(BaseModel):
        
        return v

+    @field_validator("dockerfile_template")
+    @classmethod
+    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
+        data = info.data
+        if data.get("definition_type") != "dockerfile":
+            return v
+        
+        if v is None:
+            raise ValueError("dockerfile_template is required when definition_type is 'dockerfile'")
+        
+        if not v.strip().startswith("FROM"):
+            raise ValueError("Dockerfile must start with a FROM instruction")
+        
+        return v
+
    @field_validator("default_port")
    @classmethod
    def validate_default_port(cls, v: int, info) -> int:
@@ -70,10 +103,13 @@ class ToolTypeCreate(BaseModel):
        
        # Get compose_template from the model data
        data = info.data
-        if "compose_template" not in data:
+        if data.get("definition_type") != "compose":
+            return v
+        
+        template = data.get("compose_template")
+        if not template:
            return v
        
-        template = data["compose_template"]
        try:
            parsed = yaml.safe_load(template)
        except yaml.YAMLError:
@@ -109,12 +145,14 @@ class ToolTypeCreate(BaseModel):
        if not v:
            return v
        
-        # Get compose_template from the model data
        data = info.data
-        if "compose_template" not in data:
+        if data.get("definition_type") != "compose":
+            return v
+        
+        template = data.get("compose_template")
+        if not template:
            return v
        
-        template = data["compose_template"]
        for var in v:
            placeholder = f"{{{{{var}}}}}"
            if placeholder not in template:
@@ -127,17 +165,35 @@ class ToolTypeUpdate(BaseModel):
    display_name: str | None = None
    description: str | None = None
    default_port: int | None = None
+    definition_type: str | None = None
    compose_template: str | None = None
+    dockerfile_template: str | None = None
+    build_context: dict | None = None
+    readiness_probe: dict | None = None
    required_variables: list[str] | None = None
    category: str | None = None
    interfaces: list[str] | None = None

+    @field_validator("definition_type")
+    @classmethod
+    def validate_definition_type(cls, v: str | None) -> str | None:
+        if v is None:
+            return v
+        if v not in ("compose", "dockerfile"):
+            raise ValueError("definition_type must be 'compose' or 'dockerfile'")
+        return v
+
    @field_validator("compose_template")
    @classmethod
-    def validate_compose_template(cls, v: str | None) -> str | None:
+    def validate_compose_template(cls, v: str | None, info) -> str | None:
        if v is None:
            return v
        
+        data = info.data
+        definition_type = data.get("definition_type")
+        if definition_type and definition_type != "compose":
+            return v
+        
        try:
            parsed = yaml.safe_load(v)
        except yaml.YAMLError as e:
@@ -154,6 +210,22 @@ class ToolTypeUpdate(BaseModel):
        
        return v

+    @field_validator("dockerfile_template")
+    @classmethod
+    def validate_dockerfile_template(cls, v: str | None, info) -> str | None:
+        if v is None:
+            return v
+        
+        data = info.data
+        definition_type = data.get("definition_type")
+        if definition_type and definition_type != "dockerfile":
+            return v
+        
+        if not v.strip().startswith("FROM"):
+            raise ValueError("Dockerfile must start with a FROM instruction")
+        
+        return v
+

 class ToolTypeResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)
@@ -165,7 +237,11 @@ class ToolTypeResponse(BaseModel):
    category: str
    interfaces: list[str]
    default_port: int
-    compose_template: str
+    definition_type: str
+    compose_template: str | None
+    dockerfile_template: str | None
+    build_context: dict | None
+    readiness_probe: dict | None
    required_variables: list[str]
    is_builtin: bool
    created_by_id: uuid.UUID | None
@@ -208,7 +284,11 @@ async def create_tool_type(
        display_name=data.display_name,
        description=data.description,
        default_port=data.default_port,
+        definition_type=data.definition_type,
        compose_template=data.compose_template,
+        dockerfile_template=data.dockerfile_template,
+        build_context=data.build_context,
+        readiness_probe=data.readiness_probe,
        required_variables=data.required_variables,
        is_builtin=False,
        created_by_id=user.id,
@@ -315,54 +395,59 @@ async def update_tool_type(
                detail="Port must be between 1 and 65535"
            )
        
-        # Check if port is exposed in compose template
-        template = update_data.get("compose_template", tool_type.compose_template)
-        try:
-            parsed = yaml.safe_load(template)
-        except yaml.YAMLError:
-            parsed = None
-        
-        if parsed and isinstance(parsed, dict) and "services" in parsed:
-            port_str = str(new_port)
-            port_exposed = False
-            for service_config in parsed["services"].values():
-                if isinstance(service_config, dict) and "ports" in service_config:
-                    for port_mapping in service_config["ports"]:
-                        if isinstance(port_mapping, str) and port_str in port_mapping:
-                            port_exposed = True
+        # Only validate port exposure for compose definitions
+        definition_type = update_data.get("definition_type", tool_type.definition_type)
+        if definition_type == "compose":
+            template = update_data.get("compose_template", tool_type.compose_template)
+            if template:
+                try:
+                    parsed = yaml.safe_load(template)
+                except yaml.YAMLError:
+                    parsed = None
+                
+                if parsed and isinstance(parsed, dict) and "services" in parsed:
+                    port_str = str(new_port)
+                    port_exposed = False
+                    for service_config in parsed["services"].values():
+                        if isinstance(service_config, dict) and "ports" in service_config:
+                            for port_mapping in service_config["ports"]:
+                                if isinstance(port_mapping, str) and port_str in port_mapping:
+                                    port_exposed = True
+                                    break
+                                elif isinstance(port_mapping, int) and port_mapping == new_port:
+                                    port_exposed = True
+                                    break
+                        if port_exposed:
                            break
-                        elif isinstance(port_mapping, int) and port_mapping == new_port:
-                            port_exposed = True
-                            break
-                if port_exposed:
-                    break
-            
-            if not port_exposed:
-                raise HTTPException(
-                    status_code=status.HTTP_400_BAD_REQUEST,
-                    detail=f"Port {new_port} is not exposed in the compose template"
-                )
+                    
+                    if not port_exposed:
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"Port {new_port} is not exposed in the compose template"
+                        )
    
-    # Validate required variables if both are being updated
-    if "required_variables" in update_data and "compose_template" in update_data:
-        template = update_data["compose_template"]
-        for var in update_data["required_variables"]:
-            placeholder = f"{{{{{var}}}}}"
-            if placeholder not in template:
-                raise HTTPException(
-                    status_code=status.HTTP_400_BAD_REQUEST,
-                    detail=f"Required variable '{var}' not found in compose template"
-                )
-    elif "required_variables" in update_data:
-        # Only updating variables, check against existing template
-        template = tool_type.compose_template
-        for var in update_data["required_variables"]:
-            placeholder = f"{{{{{var}}}}}"
-            if placeholder not in template:
-                raise HTTPException(
-                    status_code=status.HTTP_400_BAD_REQUEST,
-                    detail=f"Required variable '{var}' not found in compose template"
-                )
+    # Validate required variables for compose definitions
+    definition_type = update_data.get("definition_type", tool_type.definition_type)
+    if definition_type == "compose":
+        if "required_variables" in update_data and "compose_template" in update_data:
+            template = update_data["compose_template"]
+            for var in update_data["required_variables"]:
+                placeholder = f"{{{{{var}}}}}"
+                if placeholder not in template:
+                    raise HTTPException(
+                        status_code=status.HTTP_400_BAD_REQUEST,
+                        detail=f"Required variable '{var}' not found in compose template"
+                    )
+        elif "required_variables" in update_data:
+            template = tool_type.compose_template
+            if template:
+                for var in update_data["required_variables"]:
+                    placeholder = f"{{{{{var}}}}}"
+                    if placeholder not in template:
+                        raise HTTPException(
+                            status_code=status.HTTP_400_BAD_REQUEST,
+                            detail=f"Required variable '{var}' not found in compose template"
+                        )
    
    for field, value in update_data.items():
        setattr(tool_type, field, value)
@@ -372,6 +457,60 @@ async def update_tool_type(
    return tool_type


+@router.get(
+    "/{tool_type_id}/validate",
+    summary="Validate tool type",
+    description="Validate the compose template or dockerfile syntax of a tool type.",
+)
+async def validate_tool_type(
+    tool_type_id: uuid.UUID,
+    user_id: uuid.UUID = Depends(get_current_user_id),
+    session: AsyncSession = Depends(get_db_session),
+) -> dict:
+    """Validate a tool type's template syntax.
+
+    Args:
+        tool_type_id: UUID of the tool type to validate.
+        user_id: ID of the authenticated user.
+        session: Database session.
+
+    Returns:
+        Validation result with success status and any errors.
+    """
+    await _get_user(session, user_id)
+    tool_type = await session.get(ToolType, tool_type_id)
+    if tool_type is None:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="tool type not found")
+    
+    errors = []
+    
+    if tool_type.definition_type == "compose":
+        if not tool_type.compose_template:
+            errors.append("Compose template is empty")
+        else:
+            try:
+                parsed = yaml.safe_load(tool_type.compose_template)
+                if not isinstance(parsed, dict):
+                    errors.append("Compose template must be a YAML mapping")
+                elif "services" not in parsed:
+                    errors.append("Compose template must contain 'services' key")
+                elif not parsed["services"]:
+                    errors.append("Compose template must define at least one service")
+            except yaml.YAMLError as e:
+                errors.append(f"Invalid YAML: {e}")
+    
+    elif tool_type.definition_type == "dockerfile":
+        if not tool_type.dockerfile_template:
+            errors.append("Dockerfile template is empty")
+        elif not tool_type.dockerfile_template.strip().startswith("FROM"):
+            errors.append("Dockerfile must start with a FROM instruction")
+    
+    return {
+        "valid": len(errors) == 0,
+        "errors": errors,
+    }
+
+
@router.delete(
    "/{tool_type_id}",
    status_code=status.HTTP_204_NO_CONTENT,
@@ -16,6 +16,7 @@ from src.api.projects import router as projects_router
 from src.api.ssh_keys import router as ssh_keys_router
 from src.api.terminal import router as terminal_router
 from src.api.instance_proxy import router as instance_proxy_router
+from src.api.config_folders import router as config_folders_router
 from src.api.tool_configs import router as tool_configs_router
 from src.api.tool_instances import router as tool_instances_router
 from src.api.tool_instances import sessions_router
@@ -199,6 +200,7 @@ volumes:
                    description=tool_data["description"],
                    category=tool_data["category"],
                    interfaces=tool_data["interfaces"],
+                    definition_type="compose",
                    compose_template=tool_data["compose_template"],
                    required_variables=tool_data["required_variables"],
                    default_port=tool_data.get("default_port"),
@@ -212,6 +214,7 @@ volumes:
                existing.description = tool_data["description"]
                existing.category = tool_data["category"]
                existing.interfaces = tool_data["interfaces"]
+                existing.definition_type = "compose"
                existing.compose_template = tool_data["compose_template"]
                existing.required_variables = tool_data["required_variables"]
                existing.default_port = tool_data.get("default_port")
@@ -245,6 +248,7 @@ app.include_router(ssh_keys_router)
 app.include_router(git_repositories_router)
 app.include_router(user_config_router)
 app.include_router(tool_types_router)
+app.include_router(config_folders_router)
 app.include_router(tool_instances_router)
 app.include_router(tool_configs_router)
 app.include_router(sessions_router)
@@ -1,4 +1,5 @@
 from src.models.base import Base
+from src.models.config_folder import ConfigFolder
 from src.models.git_repository import GitRepository
 from src.models.project import Project
 from src.models.ssh_key import SSHKey
@@ -7,4 +8,4 @@ from src.models.tool_type import ToolType
 from src.models.user import User
 from src.models.user_config import UserConfig

-__all__ = ["Base", "GitRepository", "Project", "SSHKey", "ToolInstance", "ToolType", "User", "UserConfig"]
+__all__ = ["Base", "ConfigFolder", "GitRepository", "Project", "SSHKey", "ToolInstance", "ToolType", "User", "UserConfig"]
@@ -0,0 +1,31 @@
+import uuid
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Boolean, ForeignKey, JSON, String, Text
+from sqlalchemy import Uuid as UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from src.models.base import Base, TimestampMixin, UUIDPrimaryKeyMixin
+
+if TYPE_CHECKING:
+    from src.models.user import User
+
+
+class ConfigFolder(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+    __tablename__ = "config_folders"
+
+    user_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(), ForeignKey("users.id", ondelete="CASCADE"), nullable=False
+    )
+    name: Mapped[str] = mapped_column(String(255), nullable=False)
+    description: Mapped[str | None] = mapped_column(Text, nullable=True)
+    mount_path: Mapped[str] = mapped_column(String(1024), nullable=False)
+    files: Mapped[dict] = mapped_column(
+        JSON, default=dict, nullable=False
+    )  # {"relative/path": "content", ...}
+    project_overrides: Mapped[dict | None] = mapped_column(
+        JSON, default=dict, nullable=True
+    )  # {"project_id": {"mount_path": "...", "files": {...}}}
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True, nullable=False)
+
+    user: Mapped["User"] = relationship()
@@ -33,6 +33,15 @@ class ToolConfig(UUIDPrimaryKeyMixin, TimestampMixin, Base):
    file_path: Mapped[str | None] = mapped_column(
        String(1024), nullable=True
    )  # Only for file type
+    port_override: Mapped[int | None] = mapped_column(nullable=True)
+    start_command: Mapped[str | None] = mapped_column(Text, nullable=True)
+    working_directory: Mapped[str | None] = mapped_column(Text, nullable=True)
+    environment_variables: Mapped[dict | None] = mapped_column(
+        JSON, default=dict, nullable=True
+    )
+    volumes: Mapped[list[dict] | None] = mapped_column(
+        JSON, default=list, nullable=True
+    )

    user: Mapped["User"] = relationship()
    tool_type: Mapped["ToolType"] = relationship()
@@ -20,7 +20,15 @@ class ToolType(UUIDPrimaryKeyMixin, TimestampMixin, Base):
    category: Mapped[str] = mapped_column(String(50), nullable=False, default="other")
    interfaces: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
    default_port: Mapped[int] = mapped_column(nullable=False)
-    compose_template: Mapped[str] = mapped_column(Text, nullable=False)
+    definition_type: Mapped[str] = mapped_column(
+        String(20), nullable=False, default="compose"
+    )  # "compose" or "dockerfile"
+    compose_template: Mapped[str | None] = mapped_column(Text, nullable=True)
+    dockerfile_template: Mapped[str | None] = mapped_column(Text, nullable=True)
+    build_context: Mapped[dict | None] = mapped_column(
+        JSON, default=dict, nullable=True
+    )
+    readiness_probe: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    required_variables: Mapped[list[str]] = mapped_column(JSON, default=list, nullable=False)
    is_builtin: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)
    created_by_id: Mapped[uuid.UUID | None] = mapped_column(
@@ -92,6 +92,59 @@ def write_config_files(instance_dir: str, files: dict[str, str]) -> None:
        full_path.write_text(content)


+def write_config_folder_files(instance_dir: str, folders: list, project_id: str | None = None) -> list[dict]:
+    """Write config folder files to the instance directory and return volume mounts.
+
+    Args:
+        instance_dir: Path to instance directory
+        folders: List of ConfigFolder objects
+        project_id: Optional project ID for applying overrides
+
+    Returns:
+        List of volume mount dicts [{"source": "...", "target": "...", "type": "..."}]
+    """
+    instance_path = Path(instance_dir)
+    volume_mounts = []
+
+    for folder in folders:
+        # Determine mount path (with project override if applicable)
+        mount_path = folder.mount_path
+        files = folder.files.copy()
+        
+        if project_id and folder.project_overrides:
+            override = folder.project_overrides.get(str(project_id))
+            if override:
+                if override.get("mount_path"):
+                    mount_path = override["mount_path"]
+                if override.get("files"):
+                    files.update(override["files"])
+        
+        # Write files to instance directory
+        folder_dir = instance_path / "volumes" / folder.name
+        folder_dir.mkdir(parents=True, exist_ok=True)
+        
+        for file_path, content in files.items():
+            # Security: ensure path doesn't escape folder_dir
+            full_path = folder_dir / file_path
+            try:
+                full_path.resolve().relative_to(folder_dir.resolve())
+            except ValueError:
+                logger.warning("Config folder file path escapes directory: %s", file_path)
+                continue
+            
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content)
+        
+        # Add volume mount
+        volume_mounts.append({
+            "source": str(folder_dir),
+            "target": mount_path,
+            "type": "bind",
+        })
+    
+    return volume_mounts
+
+
 def execute_compose_command(
    compose_path: str, action: str, timeout: int = 60, env_file: str | None = None
 ) -> tuple[int, str, str]:
@@ -0,0 +1,69 @@
+"""Docker build service for building images from Dockerfiles."""
+
+import logging
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+def build_image(instance_dir: str, dockerfile: str, tag: str, build_context: dict | None = None) -> tuple[int, str, str]:
+    """Build a Docker image from a Dockerfile.
+
+    Args:
+        instance_dir: Directory containing the Dockerfile
+        dockerfile: Dockerfile content
+        tag: Image tag to apply
+        build_context: Optional build context files {path: content}
+
+    Returns:
+        Tuple of (returncode, stdout, stderr)
+    """
+    import os
+    from pathlib import Path
+
+    # Write Dockerfile
+    dockerfile_path = Path(instance_dir) / "Dockerfile"
+    dockerfile_path.write_text(dockerfile)
+    logger.info("Wrote Dockerfile to %s", dockerfile_path)
+
+    # Write build context files
+    if build_context:
+        for file_path, content in build_context.items():
+            full_path = Path(instance_dir) / file_path
+            # Security: ensure path doesn't escape instance_dir
+            try:
+                full_path.resolve().relative_to(Path(instance_dir).resolve())
+            except ValueError:
+                logger.error("Build context file path escapes instance directory: %s", file_path)
+                raise ValueError(f"Build context file path '{file_path}' escapes instance directory")
+            
+            full_path.parent.mkdir(parents=True, exist_ok=True)
+            full_path.write_text(content)
+            logger.info("Wrote build context file: %s", full_path)
+
+    # Build image
+    logger.info("Building Docker image with tag: %s", tag)
+    cmd = [
+        "docker", "build",
+        "-t", tag,
+        "-f", str(dockerfile_path),
+        instance_dir,
+    ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=300,  # 5 minute timeout for builds
+        )
+        logger.info("Docker build completed: returncode=%d", result.returncode)
+        if result.returncode != 0:
+            logger.error("Docker build failed: %s", result.stderr[:1000])
+        return result.returncode, result.stdout, result.stderr
+    except subprocess.TimeoutExpired:
+        logger.error("Docker build timed out after 300 seconds")
+        return 1, "", "Build timed out after 300 seconds"
+    except Exception as exc:
+        logger.exception("Docker build failed: %s", exc)
+        return 1, "", str(exc)
@@ -0,0 +1,66 @@
+"""Readiness probe service for checking if containers are ready."""
+
+import asyncio
+import logging
+import subprocess
+
+logger = logging.getLogger(__name__)
+
+
+async def execute_probe(
+    container_id: str,
+    command: str,
+    timeout: int = 30,
+    interval: int = 2,
+) -> tuple[bool, list[str]]:
+    """Execute a readiness probe command inside a container.
+
+    Args:
+        container_id: Docker container ID or name
+        command: Command to execute inside the container
+        timeout: Maximum total time to wait (seconds)
+        interval: Time between retries (seconds)
+
+    Returns:
+        Tuple of (success, logs)
+    """
+    logs = []
+    start_time = asyncio.get_event_loop().time()
+    attempt = 0
+
+    while True:
+        attempt += 1
+        elapsed = asyncio.get_event_loop().time() - start_time
+        
+        if elapsed >= timeout:
+            logs.append(f"Probe timed out after {timeout}s ({attempt} attempts)")
+            return False, logs
+
+        try:
+            logger.debug("Probe attempt %d: %s", attempt, command)
+            
+            # Execute command inside container
+            result = subprocess.run(
+                ["docker", "exec", container_id, "sh", "-c", command],
+                capture_output=True,
+                text=True,
+                timeout=interval,  # Each attempt has its own timeout
+            )
+            
+            if result.returncode == 0:
+                logs.append(f"Attempt {attempt}: Success")
+                if result.stdout:
+                    logs.append(f"Output: {result.stdout.strip()}")
+                return True, logs
+            else:
+                logs.append(f"Attempt {attempt}: Failed (exit code {result.returncode})")
+                if result.stderr:
+                    logs.append(f"Stderr: {result.stderr.strip()[:200]}")
+                
+        except subprocess.TimeoutExpired:
+            logs.append(f"Attempt {attempt}: Command timed out")
+        except Exception as exc:
+            logs.append(f"Attempt {attempt}: Error - {exc}")
+
+        # Wait before next attempt
+        await asyncio.sleep(interval)
@@ -0,0 +1,95 @@
+import { apiClient } from "./client";
+
+export interface ConfigFolder {
+  id: string;
+  user_id: string;
+  name: string;
+  description: string | null;
+  mount_path: string;
+  files: Record<string, string>;
+  project_overrides: Record<string, { mount_path?: string; files?: Record<string, string> }> | null;
+  is_active: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateConfigFolderRequest {
+  name: string;
+  description?: string;
+  mount_path: string;
+  files?: Record<string, string>;
+  is_active?: boolean;
+}
+
+export interface UpdateConfigFolderRequest {
+  name?: string;
+  description?: string;
+  mount_path?: string;
+  files?: Record<string, string>;
+  is_active?: boolean;
+}
+
+export interface ProjectOverrideRequest {
+  mount_path?: string;
+  files?: Record<string, string>;
+}
+
+export const listConfigFolders = async (): Promise<ConfigFolder[]> => {
+  const response = await apiClient.get<ConfigFolder[]>("/config-folders");
+  return response.data;
+};
+
+export const getConfigFolder = async (id: string): Promise<ConfigFolder> => {
+  const response = await apiClient.get<ConfigFolder>(`/config-folders/${id}`);
+  return response.data;
+};
+
+export const createConfigFolder = async (
+  data: CreateConfigFolderRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.post<ConfigFolder>("/config-folders", data);
+  return response.data;
+};
+
+export const updateConfigFolder = async (
+  id: string,
+  data: UpdateConfigFolderRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.put<ConfigFolder>(`/config-folders/${id}`, data);
+  return response.data;
+};
+
+export const deleteConfigFolder = async (id: string): Promise<void> => {
+  await apiClient.delete(`/config-folders/${id}`);
+};
+
+export const addProjectOverride = async (
+  id: string,
+  projectId: string,
+  data: ProjectOverrideRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.post<ConfigFolder>(
+    `/config-folders/${id}/overrides/${projectId}`,
+    data
+  );
+  return response.data;
+};
+
+export const updateProjectOverride = async (
+  id: string,
+  projectId: string,
+  data: ProjectOverrideRequest
+): Promise<ConfigFolder> => {
+  const response = await apiClient.put<ConfigFolder>(
+    `/config-folders/${id}/overrides/${projectId}`,
+    data
+  );
+  return response.data;
+};
+
+export const deleteProjectOverride = async (
+  id: string,
+  projectId: string
+): Promise<void> => {
+  await apiClient.delete(`/config-folders/${id}/overrides/${projectId}`);
+};
@@ -8,6 +8,11 @@ export interface ToolConfig {
  value: string;
  config_type: string;
  file_path: string | null;
+  port_override: number | null;
+  start_command: string | null;
+  working_directory: string | null;
+  environment_variables: Record<string, string> | null;
+  volumes: Array<{ source: string; target: string; type?: string }> | null;
 }

 export interface CreateToolConfigRequest {
@@ -17,6 +22,11 @@ export interface CreateToolConfigRequest {
  value: string;
  config_type?: string;
  file_path?: string;
+  port_override?: number;
+  start_command?: string;
+  working_directory?: string;
+  environment_variables?: Record<string, string>;
+  volumes?: Array<{ source: string; target: string; type?: string }>;
 }

 export const listToolConfigs = async (
@@ -53,4 +63,13 @@ export const updateToolConfig = async (

 export const deleteToolConfig = async (id: string): Promise<void> => {
  await apiClient.delete(`/tool-configs/${id}`);
+};
+
+export const getToolConfigDefaults = async (
+  toolTypeId: string
+): Promise<ToolConfig> => {
+  const response = await apiClient.get<ToolConfig>(
+    `/tool-configs/defaults/${toolTypeId}`
+  );
+  return response.data;
 };
@@ -1,5 +1,11 @@
 import { apiClient } from "./client";

+export interface ReadinessProbe {
+  command: string;
+  timeout: number;
+  interval: number;
+}
+
 export interface ToolType {
  id: string;
  name: string;
@@ -8,7 +14,11 @@ export interface ToolType {
  category: string;
  interfaces: string[];
  default_port: number | null;
-  compose_template: string;
+  definition_type: 'compose' | 'dockerfile';
+  compose_template: string | null;
+  dockerfile_template: string | null;
+  build_context: Record<string, string> | null;
+  readiness_probe: ReadinessProbe | null;
  required_variables: string[];
  is_builtin: boolean;
  created_by_id: string | null;
@@ -23,7 +33,11 @@ export interface CreateToolTypeRequest {
  category?: string;
  interfaces?: string[];
  default_port: number;
-  compose_template: string;
+  definition_type?: 'compose' | 'dockerfile';
+  compose_template?: string;
+  dockerfile_template?: string;
+  build_context?: Record<string, string>;
+  readiness_probe?: ReadinessProbe;
  required_variables: string[];
 }

@@ -33,7 +47,11 @@ export interface UpdateToolTypeRequest {
  category?: string;
  interfaces?: string[];
  default_port?: number;
+  definition_type?: 'compose' | 'dockerfile';
  compose_template?: string;
+  dockerfile_template?: string;
+  build_context?: Record<string, string>;
+  readiness_probe?: ReadinessProbe;
  required_variables?: string[];
 }

@@ -60,3 +78,8 @@ export const updateToolType = async (id: string, data: UpdateToolTypeRequest): P
 export const deleteToolType = async (id: string): Promise<void> => {
  await apiClient.delete(`/tool-types/${id}`);
 };
+
+export const validateToolType = async (id: string): Promise<{ valid: boolean; errors?: string[] }> => {
+  const response = await apiClient.get<{ valid: boolean; errors?: string[] }>(`/tool-types/${id}/validate`);
+  return response.data;
+};
@@ -14,8 +14,7 @@ const NAV_ITEMS: { to: string; label: string; icon: IconName }[] = [
  { to: "/sessions", label: "Sessions", icon: "terminal" },
  { to: "/projects", label: "Projects", icon: "projects" },
  { to: "/ssh-keys", label: "SSH Keys", icon: "profile" },
-  { to: "/tool-types", label: "Tool Types", icon: "code" },
-  { to: "/tool-configs", label: "Tool Configs", icon: "settings" },
+  { to: "/tool-workshop", label: "Tool Workshop", icon: "settings" },
  { to: "/settings", label: "Settings", icon: "settings" }
 ];

@@ -67,7 +67,7 @@ export const ToolTypesPage = () => {
    setFormCategory(toolType.category ?? "");
    setFormInterfaces(toolType.interfaces ?? []);
    setFormPort(toolType.default_port?.toString() ?? "");
-    setFormTemplate(toolType.compose_template);
+    setFormTemplate(toolType.compose_template ?? "");
    setFormVariables(toolType.required_variables.join(", "));
    setFormError(null);
    setEditingToolType(toolType);
@@ -14,8 +14,7 @@ import { RepoWorkspace } from "./pages/repo-workspace";
 import { SSHKeysPage } from "./pages/ssh-keys";
 import { SettingsPage } from "./pages/settings";
 import { TerminalPage } from "./pages/terminal";
-import { ToolConfigsPage } from "./pages/tool-configs";
-import { ToolTypesPage } from "./pages/tool-types";
+import { ToolWorkshopPage } from "./pages/tool-workshop";

 export const AppRouter = () => {
  return (
@@ -39,8 +38,9 @@ export const AppRouter = () => {
        <Route path="ssh-keys" element={<SSHKeysPage />} />
        <Route path="profile" element={<ProfilePage />} />
        <Route path="settings" element={<SettingsPage />} />
-        <Route path="tool-types" element={<ToolTypesPage />} />
-        <Route path="tool-configs" element={<ToolConfigsPage />} />
+        <Route path="tool-workshop" element={<ToolWorkshopPage />} />
+        <Route path="tool-types" element={<Navigate to="/tool-workshop" replace />} />
+        <Route path="tool-configs" element={<Navigate to="/tool-workshop" replace />} />
        <Route path="instances/:instanceId/terminal" element={<TerminalPage />} />
      </Route>
      <Route path="/404" element={<NotFoundPage />} />
@@ -0,0 +1,379 @@
+## Context
+
+The tool system currently supports:
+- ToolTypes with compose templates and basic metadata
+- ToolConfigs as simple key-value pairs (env vars or files)
+- Instance creation via compose rendering
+- Basic flat-list UI at `/tool-configs`
+
+Users need a much richer system for defining, configuring, and running development tools.
+
+## Goals / Non-Goals
+
+**Goals:**
+- Support both Docker Compose and Dockerfile for tool definitions
+- Add readiness probes with configurable commands and timeouts
+- Create reusable config file collections ("folders") mountable as volumes
+- Add rich tool config fields (port, start_command, working_directory, volumes, env vars)
+- Build a unified "Tool Workshop" UI for all tool management
+- Support per-project overrides on config folders
+- Maintain backward compatibility with existing built-in tool types
+
+**Non-Goals:**
+- Docker image registry management (assume local builds or public images)
+- Real-time collaborative tool editing
+- Tool marketplace/sharing between users
+- Advanced orchestration (Kubernetes, Swarm)
+- Config folder versioning/Git integration
+
+## Architecture
+
+### Data Model
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        TOOL WORKSHOP                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────┐     ┌──────────────┐     ┌──────────────┐     │
+│  │   ToolType   │────▶│  ToolConfig  │◀────│ ConfigFolder │     │
+│  │  (Blueprint) │     │  (Settings)  │     │  (Files)     │     │
+│  └──────────────┘     └──────────────┘     └──────────────┘     │
+│         │                    │                    │             │
+│         │                    │                    │             │
+│         ▼                    ▼                    ▼             │
+│  ┌──────────────────────────────────────────────────────┐      │
+│  │                   ToolInstance                        │      │
+│  │              (Runtime + Volumes)                      │      │
+│  └──────────────────────────────────────────────────────┘      │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### ToolType Model
+
+```python
+class ToolType:
+    # Existing fields
+    name: str                          # unique identifier
+    display_name: str
+    description: str | None
+    category: str
+    interfaces: list[str]              # ["web", "terminal"]
+    default_port: int
+    required_variables: list[str]
+    is_builtin: bool
+    
+    # New fields
+    definition_type: str               # "compose" | "dockerfile"
+    compose_template: str | None       # YAML template (if definition_type == "compose")
+    dockerfile_template: str | None    # Dockerfile content (if definition_type == "dockerfile")
+    build_context: dict | None         # {"files": {"path": "content"}} for dockerfile builds
+    readiness_probe: dict | None       # {"command": "...", "timeout": 30, "interval": 2}
+```
+
+**Decision**: Store both compose and dockerfile, use `definition_type` to determine which to use. This allows easy switching and migration.
+
+### ToolConfig Model
+
+```python
+class ToolConfig:
+    # Existing fields
+    user_id: UUID
+    tool_type_id: UUID
+    project_id: UUID | None            # null = global config
+    key: str
+    value: str
+    config_type: str                   # "env" | "file"
+    file_path: str | None
+    
+    # New fields
+    port_override: int | None          # Override tool type default port
+    start_command: str | None          # Override container start command
+    working_directory: str | None      # Working directory inside container
+    environment_variables: dict | None # JSON {"KEY": "value", ...}
+    volumes: list[dict] | None         # JSON [{"source": "...", "target": "...", "type": "..."}]
+```
+
+**Decision**: Store env vars and volumes as JSONB for flexibility. Port as integer with validation.
+
+### ConfigFolder Model (NEW)
+
+```python
+class ConfigFolder:
+    id: UUID
+    user_id: UUID
+    name: str                          # e.g., "my-dotfiles", "vscode-settings"
+    description: str | None
+    mount_path: str                    # Default mount path in container (e.g., "/home/user/.config")
+    files: dict                        # JSON {"relative/path": "content", ...}
+    project_overrides: dict | None     # JSON {project_id: {"mount_path": "...", "files": {...}}}
+    is_active: bool                    # Quick toggle
+    created_at, updated_at
+```
+
+**Decision**: Files stored as JSONB with relative paths as keys. This is simple and sufficient for config files (not binary assets).
+
+### Volume Mount Resolution
+
+When creating an instance, volumes are resolved in this priority order:
+
+```
+1. ToolConfig.volumes (explicit per-config mounts)
+2. ConfigFolder mounts (user's active config folders)
+3. ToolType default volumes (from compose/dockerfile)
+```
+
+Config folder files are written to the instance directory under `volumes/<folder_name>/` and mounted from there.
+
+### Readiness Probe System
+
+```python
+class ReadinessProbe:
+    command: str                       # e.g., "curl -f http://localhost:8080/health"
+    timeout: int                       # seconds (default: 30)
+    interval: int                      # seconds between checks (default: 2)
+    retries: int                       # max attempts (default: timeout/interval)
+```
+
+**Execution Flow**:
+1. Start container
+2. Wait for container to be running
+3. Execute probe command inside container via `docker exec`
+4. If success → mark instance as "running"
+5. If timeout → mark instance as "failed" with probe output in logs
+
+**Decision**: Probes run inside the container using `docker exec`. This works for both network-based probes (curl) and command-based probes (binary version checks).
+
+### Instance Creation Flow
+
+```
+1. Generate instance ID and directory
+2. Resolve ToolConfig (global + project-specific)
+3. Write config files:
+   a. .env file (from env-type ToolConfigs)
+   b. Config files (from file-type ToolConfigs)
+   c. Config folder files (to volumes/<folder>/)
+4. IF ToolType.definition_type == "dockerfile":
+   a. Write Dockerfile + build context files
+   b. Build image: docker build -t <instance_tag> .
+   c. Generate compose from template using built image
+5. IF ToolType.definition_type == "compose":
+   a. Render compose template with variables
+6. Write docker-compose.yml
+7. docker compose up -d
+8. Connect to backend network
+9. IF readiness_probe defined:
+   a. Execute probe with timeout
+   b. Update status based on result
+10. IF web interface:
+    a. Create Cloudflare tunnel
+    b. Update URL
+```
+
+## UI Design
+
+### Tool Workshop Page (`/tool-workshop`)
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Tool Workshop                                          [+ New]  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────┐  ┌──────────────────────────────────────┐     │
+│  │              │  │                                      │     │
+│  │ MY TOOLS     │  │  [Tool Type Builder]                 │     │
+│  │              │  │                                      │     │
+│  │ ▼ Code Editor│  │  Name: [____________]                │     │
+│  │   □ VS Code  │  │  Type: (•) Compose  ( ) Dockerfile │     │
+│  │   □ Cursor   │  │                                      │     │
+│  │              │  │  [Compose Template / Dockerfile]     │     │
+│  │ ▼ AI Tools   │  │  ┌────────────────────────────────┐  │     │
+│  │   □ OpenCode │  │  │ version: '3.8'                 │  │     │
+│  │   □ Continue │  │  │ services:                      │  │     │
+│  │              │  │  │   app:                         │  │     │
+│  │ CONFIGS      │  │  │     image: ...                 │  │     │
+│  │              │  │  │     ports:                     │  │     │
+│  │ ▼ Global     │  │  │       - "{{PORT}}:8080"        │  │     │
+│  │   □ dotfiles │  │  │     volumes:                   │  │     │
+│  │   □ api-keys │  │  │       - ...                    │  │     │
+│  │              │  │  └────────────────────────────────┘  │     │
+│  │ ▼ Project X  │  │                                      │     │
+│  │   □ overrides│  │  Readiness Probe:                    │     │
+│  │              │  │  Command: [curl -f localhost:8080]   │     │
+│  │              │  │  Timeout: [30] seconds               │     │
+│  │              │  │                                      │     │
+│  │              │  │  [Save Tool Type]                    │     │
+│  │              │  │                                      │     │
+│  └──────────────┘  └──────────────────────────────────────┘     │
+│                                                                  │
+│  Tabs: [Tool Types] [Configs] [Config Folders]                   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Navigation Structure**:
+- Left sidebar: Hierarchical tree
+  - Tool Types (expandable, shows instances count)
+  - Config Folders (grouped by global/project)
+- Right panel: Context-aware editor based on selection
+- Tab bar: Switch between Tool Types / Configs / Config Folders views
+
+### Config Editor
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Edit Config: OpenCode API Keys                                  │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Basic Settings              │  Advanced Settings               │
+│  ────────────────────────────┼────────────────────────────────  │
+│  Key: [OPENAI_API_KEY]       │  Port Override: [_____]          │
+│  Value: [sk-...        ]     │  Start Command: [_____]          │
+│  Type: (•) Env  ( ) File     │  Working Dir: [/workspace]       │
+│  File Path: [__________]     │                                  │
+│                              │  Environment Variables:          │
+│                              │  ┌──────────────────────────┐    │
+│                              │  │ KEY        │ VALUE       │    │
+│                              │  │ OPENAI_KEY │ sk-...      │    │
+│                              │  │ MODEL      │ gpt-4       │    │
+│                              │  └──────────────────────────┘    │
+│                              │                                  │
+│                              │  Volume Mounts:                  │
+│                              │  ┌──────────────────────────┐    │
+│                              │  │ SOURCE     │ TARGET      │    │
+│                              │  │ dotfiles   │ ~/.config   │    │
+│                              │  │ vscode-set │ ~/.vscode   │    │
+│                              │  └──────────────────────────┘    │
+│                              │                                  │
+│  [Delete]  [Cancel] [Save]   │                                  │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Config Folder Manager
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Config Folder: my-dotfiles                                      │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Name: [my-dotfiles]                                            │
+│  Description: [My personal dotfiles]                            │
+│  Default Mount Path: [/home/user]                               │
+│                                                                  │
+│  Files:                                                          │
+│  ┌──────────────────────────────────────────────────────┐       │
+│  │ Path                    │ Size  │ Actions            │       │
+│  │ .zshrc                  │ 2.1KB │ [Edit] [Delete]    │       │
+│  │ .gitconfig              │ 412B  │ [Edit] [Delete]    │       │
+│  │ .config/starship.toml   │ 1.8KB │ [Edit] [Delete]    │       │
+│  └──────────────────────────────────────────────────────┘       │
+│                                                                  │
+│  [+ Add File]                                                    │
+│                                                                  │
+│  Project Overrides:                                              │
+│  ┌──────────────────────────────────────────────────────┐       │
+│  │ Project       │ Mount Path        │ Files Override   │       │
+│  │ Project Alpha │ /home/dev         │ [3 files]        │       │
+│  │ Project Beta  │ /workspace        │ [1 file]         │       │
+│  └──────────────────────────────────────────────────────┘       │
+│                                                                  │
+│  [Add Override]  [Delete Folder]  [Save]                         │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Decisions
+
+1. **Dockerfile vs Compose**: Support both. `definition_type` field determines which path to use. Compose is the default for backward compatibility.
+
+2. **Config Folder Storage**: Store files as JSONB keyed by relative path. This avoids file system complexity and works well for text-based config files. Limit: 10MB per folder.
+
+3. **Readiness Probe Execution**: Use `docker exec` to run commands inside the container. This is the most flexible approach (works for HTTP checks, binary checks, file checks).
+
+4. **Volume Resolution Order**: Config-level volumes override config-folder volumes, which override tool-type defaults. Last-write-wins for conflicts.
+
+5. **UI Organization**: Single page with three tabs (Tool Types, Configs, Config Folders) and a left sidebar for navigation. This consolidates the current `/tool-configs` and `/tool-types` pages.
+
+6. **Project Overrides**: ConfigFolders support per-project overrides for mount_path and files. This allows project-specific customizations while keeping the base collection reusable.
+
+## Risks / Trade-offs
+
+- **Dockerfile build times**: Building images on-demand is slow. Mitigation: Document that users should use pre-built images in compose for faster startup; dockerfile is for custom tools.
+- **Config folder size limits**: JSONB has practical limits. Mitigation: 10MB limit per folder, enforced in API.
+- **Readiness probe complexity**: Commands might hang or fail in unexpected ways. Mitigation: Strict timeout, clear error messages, probe logs stored on instance.
+- **Migration complexity**: Existing tool types need `definition_type` set to "compose". Mitigation: Database default, seed function update.
+- **UI complexity**: Three tabs with different editors could feel overwhelming. Mitigation: Progressive disclosure (hide advanced fields, collapsible sections).
+
+## API Endpoints
+
+### Tool Types
+- `GET /tool-types` - List all (existing)
+- `POST /tool-types` - Create with new fields
+- `PUT /tool-types/{id}` - Update with new fields
+- `GET /tool-types/{id}/validate` - Validate compose/dockerfile syntax
+
+### Tool Configs
+- `GET /tool-configs` - List with new fields
+- `POST /tool-configs` - Create with new fields
+- `PUT /tool-configs/{id}` - Update with new fields
+- `GET /tool-configs/defaults/{tool_type_id}` - Get suggested defaults
+
+### Config Folders (NEW)
+- `GET /config-folders` - List user's folders
+- `POST /config-folders` - Create folder
+- `PUT /config-folders/{id}` - Update folder (files, mount_path)
+- `DELETE /config-folders/{id}` - Delete folder
+- `POST /config-folders/{id}/overrides` - Add project override
+- `PUT /config-folders/{id}/overrides/{project_id}` - Update override
+- `DELETE /config-folders/{id}/overrides/{project_id}` - Remove override
+
+## Database Schema
+
+### Migration: tool_types
+```sql
+ALTER TABLE tool_types 
+ADD COLUMN definition_type VARCHAR(20) NOT NULL DEFAULT 'compose',
+ADD COLUMN dockerfile_template TEXT,
+ADD COLUMN build_context JSONB DEFAULT '{}',
+ADD COLUMN readiness_probe JSONB;
+
+-- Ensure consistency
+ALTER TABLE tool_types 
+ADD CONSTRAINT chk_definition_type 
+CHECK (definition_type IN ('compose', 'dockerfile'));
+```
+
+### Migration: tool_configs
+```sql
+ALTER TABLE tool_configs
+ADD COLUMN port_override INTEGER,
+ADD COLUMN start_command TEXT,
+ADD COLUMN working_directory TEXT,
+ADD COLUMN environment_variables JSONB DEFAULT '{}',
+ADD COLUMN volumes JSONB DEFAULT '[]';
+
+ALTER TABLE tool_configs
+ADD CONSTRAINT chk_port_range 
+CHECK (port_override IS NULL OR (port_override >= 1 AND port_override <= 65535));
+```
+
+### New Table: config_folders
+```sql
+CREATE TABLE config_folders (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name VARCHAR(255) NOT NULL,
+    description TEXT,
+    mount_path VARCHAR(1024) NOT NULL,
+    files JSONB NOT NULL DEFAULT '{}',
+    project_overrides JSONB DEFAULT '{}',
+    is_active BOOLEAN NOT NULL DEFAULT true,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE(user_id, name)
+);
+
+CREATE INDEX idx_config_folders_user ON config_folders(user_id);
+```
@@ -0,0 +1,57 @@
+## Why
+
+The current tool system is too rigid. Tool types are hardcoded with compose templates, configs are simple key-value pairs, and the UI is a basic flat list. Users need a true "tool workshop" where they can:
+
+1. **Define new tools** with either Docker Compose or Dockerfile
+2. **Configure rich tool settings** including ports, commands, working directories, and volume mounts
+3. **Create reusable config file collections** (e.g., dotfiles, IDE settings) that mount into containers
+4. **Wait for tools to be ready** with configurable health/readiness probes before considering the build complete
+
+This unlocks the platform from built-in tools to a true marketplace of user-defined and user-configured tools.
+
+## What Changes
+
+- **Enhance ToolType model**: Add `dockerfile_template`, `readiness_probe` (command + timeout), `build_context` field
+- **Enhance ToolConfig model**: Add `port_override`, `start_command`, `working_directory`, `environment_variables`, `volumes`
+- **Create ConfigFolder model**: Named collections of files mountable as volumes, with per-project overrides
+- **Add readiness probe system**: Instance creation waits for probe command with configurable timeout
+- **Unified Tool Workshop UI**: Single page replacing `/tool-configs` and `/tool-types` with:
+  - Tool Type builder (compose or dockerfile)
+  - Tool Config editor (split-pane with all new fields)
+  - Config Folder manager (file collections with mount paths)
+  - Live validation and preview
+- **Update instance creation flow**: Support dockerfile builds, mount config folders, apply readiness probes
+- **Database migrations**: New columns on `tool_types`, `tool_configs`; new `config_folders` table
+
+## Capabilities
+
+### New Capabilities
+- `tool-workshop`: Unified tool definition, configuration, and deployment interface
+- `config-folders`: Reusable per-user file collections mountable into containers with per-project overrides
+- `readiness-probes`: Build-time health checks that wait for tools to be ready before marking instances as running
+
+### Modified Capabilities
+- `tool-types`: Enhanced with dockerfile support, readiness probes, build context
+- `tool-config-management`: Extended with port overrides, volumes, environment variables, working directory
+- `tool-instances`: Instance creation supports dockerfile builds, config folder mounts, probe waiting
+
+## Impact
+
+- **Backend**: 
+  - Models: `ToolType`, `ToolConfig`, new `ConfigFolder`
+  - API: New endpoints for config folders, updated tool type/config endpoints
+  - Services: Docker build service (for dockerfiles), readiness probe service
+  - Instance creation: Dockerfile build path, volume mounting, probe execution
+- **Frontend**:
+  - New `ToolWorkshopPage` component (replaces `/tool-configs` and `/tool-types`)
+  - New components: Dockerfile editor, readiness probe config, config folder manager, volume mount editor
+  - Updated routing and navigation
+- **Database**: 
+  - `tool_types`: Add `dockerfile_template`, `readiness_probe`, `build_context`
+  - `tool_configs`: Add `port_override`, `start_command`, `working_directory`, `environment_variables`, `volumes`
+  - New `config_folders` table
+- **User Experience**: Users can now define entirely new tools, configure them richly, and reuse config collections across projects
+
+## Supersedes
+
+This change supersedes `tool-config-ui-rework` which scoped only to the UI rework and basic new fields. This is a comprehensive expansion of the tool system.
@@ -0,0 +1,113 @@
+# Capability: Config Folders
+
+## Overview
+
+Config Folders are reusable collections of configuration files that can be mounted into tool instances as volumes. They enable users to maintain their preferred settings (dotfiles, IDE configs, etc.) and apply them across all their tool instances.
+
+## Functional Requirements
+
+### FR-1: Folder Creation
+- Users can create named config folders
+- Each folder has: name, description, default mount path, collection of files
+- Folder names must be unique per user
+- Files are stored with relative paths (e.g., `.zshrc`, `.config/nvim/init.vim`)
+
+### FR-2: File Management
+- Users can add, edit, and delete files within a folder
+- File paths are relative to the mount path
+- File content is stored as text (UTF-8)
+- Maximum total folder size: 10MB
+- File paths are sanitized to prevent directory traversal attacks
+
+### FR-3: Activation
+- Folders can be toggled active/inactive
+- Only active folders are mounted into new instances
+- Activation state is persisted
+- Changing activation does not affect running instances
+
+### FR-4: Project Overrides
+- Users can define per-project overrides for any folder
+- Overrides can modify: mount path, add/remove/replace files
+- When an instance is created for a project, overrides are applied
+- Global settings serve as defaults; overrides are merged
+- Deleting an override reverts to global settings
+
+### FR-5: Instance Mounting
+- When creating an instance, active folders are resolved
+- For each folder: global files + project overrides (if any)
+- Files are written to `instance_dir/volumes/<folder_name>/`
+- Compose file includes volume mounts from these directories
+- Mount target is the folder's mount path (or override)
+
+## Data Model
+
+```python
+class ConfigFolder:
+    id: UUID
+    user_id: UUID
+    name: str                    # Unique per user
+    description: str | None
+    mount_path: str             # e.g., "/home/user"
+    files: dict[str, str]       # {"relative/path": "content", ...}
+    project_overrides: dict     # {"project_id": {"mount_path": "...", "files": {...}}}
+    is_active: bool
+    created_at: datetime
+    updated_at: datetime
+```
+
+## API Endpoints
+
+- `GET /config-folders` - List user's folders
+- `POST /config-folders` - Create folder
+- `PUT /config-folders/{id}` - Update folder
+- `DELETE /config-folders/{id}` - Delete folder
+- `POST /config-folders/{id}/overrides` - Add override
+- `PUT /config-folders/{id}/overrides/{project_id}` - Update override
+- `DELETE /config-folders/{id}/overrides/{project_id}` - Remove override
+
+## Validation Rules
+
+1. **Name uniqueness**: `(user_id, name)` must be unique
+2. **Path sanitization**: File paths cannot contain `..` or start with `/`
+3. **Size limit**: Total folder size (sum of all file contents) ≤ 10MB
+4. **Mount path**: Must be absolute path (starts with `/`)
+5. **Project existence**: Overrides can only reference existing projects
+
+## Example Usage
+
+### Global Config Folder
+```json
+{
+  "name": "my-dotfiles",
+  "description": "Personal shell and git configuration",
+  "mount_path": "/home/user",
+  "files": {
+    ".zshrc": "export ZSH=\"$HOME/.oh-my-zsh\"\n...",
+    ".gitconfig": "[user]\nname = John Doe\n...",
+    ".config/starship.toml": "[character]\n..."
+  },
+  "is_active": true
+}
+```
+
+### Project Override
+```json
+{
+  "project_id": "550e8400-e29b-41d4-a716-446655440000",
+  "mount_path": "/workspace",
+  "files": {
+    ".gitconfig": "[user]\nname = Work Account\n..."
+  }
+}
+```
+
+## Acceptance Criteria
+
+- [ ] User can create a config folder with multiple files
+- [ ] Files are correctly mounted into new instances
+- [ ] Project overrides apply correctly
+- [ ] 10MB size limit is enforced
+- [ ] Path traversal attacks are prevented
+- [ ] Only active folders are mounted
+- [ ] Changing folder contents updates future instances
+- [ ] UI shows folder size and file count
@@ -0,0 +1,163 @@
+# Capability: Readiness Probes
+
+## Overview
+
+Readiness probes ensure tool instances are fully initialized before being marked as "running". They execute a configurable command inside the container and wait for it to succeed, with configurable timeout and retry interval.
+
+## Functional Requirements
+
+### FR-1: Probe Definition
+- Tool types can define an optional readiness probe
+- Probe configuration: command, timeout, interval, retries
+- If no probe is defined, instance is marked running immediately after container start
+- Probe can be any shell command that returns exit code 0 for success
+
+### FR-2: Probe Execution
+- Probe runs inside the container via `docker exec`
+- Probe starts after container is in "running" state
+- Probe executes periodically (interval) until success or timeout
+- Each execution has a separate timeout (not the total timeout)
+- Probe output is captured and stored
+
+### FR-3: Status Management
+- While probing: instance status is "starting"
+- On success: instance status changes to "running"
+- On timeout: instance status changes to "failed"
+- Failed instances include probe logs in error details
+- Users can view probe execution history
+
+### FR-4: Probe Types
+Support common probe patterns:
+- **HTTP probe**: `curl -f http://localhost:8080/health`
+- **Command probe**: `opencode --version`
+- **File probe**: `[ -f /app/ready ]`
+- **Port probe**: `nc -z localhost 8080`
+
+## Configuration
+
+```python
+class ReadinessProbe(BaseModel):
+    command: str           # Command to execute
+    timeout: int = 30      # Total timeout in seconds
+    interval: int = 2      # Seconds between checks
+    
+    @property
+    def max_retries(self) -> int:
+        return self.timeout // self.interval
+```
+
+## Execution Flow
+
+```
+Container Start
+       │
+       ▼
+Container Running?
+       │
+       ├── No ──▶ Wait 1s ──▶ Retry (max 30s)
+       │
+       ▼ Yes
+Execute Probe Command
+       │
+       ├── Exit 0 ──▶ Status: "running" ✓
+       │
+       ├── Exit !=0 ──▶ Wait interval ──▶ Retry
+       │                              │
+       │                              └── Max retries reached?
+       │                                     ├── No ──▶ Execute again
+       │                                     │
+       │                                     ▼ Yes
+       │                              Status: "failed" ✗
+       │                              Store logs
+       │
+       └── Timeout ──▶ Status: "failed" ✗
+                        Store logs
+```
+
+## Probe Examples
+
+### Web Tool (VS Code Server)
+```json
+{
+  "command": "curl -sf http://localhost:8080/health || curl -sf http://localhost:8080",
+  "timeout": 60,
+  "interval": 3
+}
+```
+
+### Terminal Tool (OpenCode)
+```json
+{
+  "command": "which opencode && opencode --version",
+  "timeout": 30,
+  "interval": 2
+}
+```
+
+### Database Tool
+```json
+{
+  "command": "pg_isready -U postgres",
+  "timeout": 30,
+  "interval": 2
+}
+```
+
+## Error Handling
+
+### Probe Command Not Found
+- Exit code: 127
+- Behavior: Retry (command might not be in PATH yet)
+- Log: "Command not found, retrying..."
+
+### Probe Times Out
+- Mark instance as "failed"
+- Store last probe output
+- Include timeout details in error message
+- Allow user to view full probe logs
+
+### Container Exits During Probe
+- Stop probing immediately
+- Mark instance as "failed"
+- Include container exit code and logs
+
+## API Integration
+
+### Tool Type Response
+```json
+{
+  "id": "...",
+  "name": "code-server",
+  "readiness_probe": {
+    "command": "curl -sf http://localhost:8080",
+    "timeout": 60,
+    "interval": 3
+  }
+}
+```
+
+### Instance Response (Failed Probe)
+```json
+{
+  "id": "...",
+  "status": "failed",
+  "error": "Readiness probe failed after 60s",
+  "probe_logs": [
+    "Attempt 1/20: Connection refused",
+    "Attempt 2/20: Connection refused",
+    "...",
+    "Attempt 20/20: Timeout"
+  ]
+}
+```
+
+## Acceptance Criteria
+
+- [ ] Probe executes inside container and waits for success
+- [ ] Successful probe marks instance as "running"
+- [ ] Failed probe (timeout) marks instance as "failed"
+- [ ] Probe logs are stored and retrievable
+- [ ] Probe respects timeout and interval settings
+- [ ] No probe defined = immediate "running" status
+- [ ] Container exit during probe is handled gracefully
+- [ ] Common probe patterns work (HTTP, command, file, port)
@@ -0,0 +1,96 @@
+# 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
@@ -0,0 +1,204 @@
+## Phase 1: Backend Foundation
+
+### 1.1 Database Migrations
+- [x] 1.1.1 Create Alembic migration for `tool_types` (add definition_type, dockerfile_template, build_context, readiness_probe)
+- [x] 1.1.2 Create Alembic migration for `tool_configs` (add port_override, start_command, working_directory, environment_variables, volumes)
+- [x] 1.1.3 Create Alembic migration for `config_folders` (new table)
+- [x] 1.1.4 Add CHECK constraints (definition_type enum, port range)
+- [x] 1.1.5 Add indexes for config_folders
+- [ ] 1.1.6 Run migrations locally and verify with test data
+
+### 1.2 Model Updates
+- [x] 1.2.1 Update `ToolType` model with new fields
+- [x] 1.2.2 Update `ToolConfig` model with new fields
+- [x] 1.2.3 Create `ConfigFolder` model
+- [x] 1.2.4 Add Pydantic schemas for ConfigFolder (create, update, response)
+- [x] 1.2.5 Update Pydantic schemas for ToolType (add new fields)
+- [x] 1.2.6 Update Pydantic schemas for ToolConfig (add new fields)
+- [x] 1.2.7 Add validation schemas (port range, JSON structure, definition_type enum)
+
+### 1.3 Config Folder API
+- [x] 1.3.1 Create `api/config_folders.py` router
+- [x] 1.3.2 Implement `GET /config-folders` (list with filtering by project)
+- [x] 1.3.3 Implement `POST /config-folders` (create)
+- [x] 1.3.4 Implement `PUT /config-folders/{id}` (update name, mount_path, files)
+- [x] 1.3.5 Implement `DELETE /config-folders/{id}` (delete)
+- [x] 1.3.6 Implement `POST /config-folders/{id}/overrides` (add project override)
+- [x] 1.3.7 Implement `PUT /config-folders/{id}/overrides/{project_id}` (update override)
+- [x] 1.3.8 Implement `DELETE /config-folders/{id}/overrides/{project_id}` (remove override)
+- [x] 1.3.9 Add validation: 10MB size limit per folder
+- [x] 1.3.10 Add ownership checks (user can only access own folders)
+
+### 1.4 Tool Type API Updates
+- [x] 1.4.1 Update `POST /tool-types` to accept definition_type, dockerfile_template, build_context, readiness_probe
+- [x] 1.4.2 Update `PUT /tool-types/{id}` to handle new fields
+- [ ] 1.4.3 Add `GET /tool-types/{id}/validate` endpoint (syntax validation)
+- [x] 1.4.4 Update tool type response schemas
+- [x] 1.4.5 Update seed function to set definition_type="compose" for built-in types
+
+### 1.5 Tool Config API Updates
+- [x] 1.5.1 Update `POST /tool-configs` to accept new fields
+- [x] 1.5.2 Update `PUT /tool-configs/{id}` to handle new fields
+- [x] 1.5.3 Update `GET /tool-configs` to return new fields
+- [x] 1.5.4 Add `GET /tool-configs/defaults/{tool_type_id}` endpoint
+- [x] 1.5.5 Add validation for port_override range
+- [x] 1.5.6 Add validation for environment_variables JSON structure
+- [x] 1.5.7 Add validation for volumes JSON structure (source/target/type)
+
+## Phase 2: Instance Creation Enhancement
+
+### 2.1 Docker Build Service
+- [ ] 2.1.1 Create `services/docker_build.py` for Dockerfile builds
+- [ ] 2.1.2 Implement `build_image(instance_dir, dockerfile, tag)` function
+- [ ] 2.1.3 Handle build context file writing
+- [ ] 2.1.4 Add build output streaming/logging
+- [ ] 2.1.5 Handle build failures with clear error messages
+
+### 2.2 Compose Generation for Dockerfile Tools
+- [ ] 2.2.1 Create compose template for dockerfile-built images
+- [ ] 2.2.2 Integrate build service into instance creation flow
+- [ ] 2.2.3 Update `render_compose_template` to handle both paths
+
+### 2.3 Config Folder Mounting
+- [ ] 2.3.1 Implement `write_config_folder_files(instance_dir, folders)` function
+- [ ] 2.3.2 Resolve config folders for user + project
+- [ ] 2.3.3 Generate volume mounts in compose file for config folders
+- [ ] 2.3.4 Apply project overrides during resolution
+- [ ] 2.3.5 Write config folder files to `instance_dir/volumes/`
+
+### 2.4 Readiness Probe Service
+- [ ] 2.4.1 Create `services/readiness_probe.py`
+- [ ] 2.4.2 Implement `execute_probe(container_id, probe_config)` function
+- [ ] 2.4.3 Implement polling loop with timeout and interval
+- [ ] 2.4.4 Store probe output/logs on instance
+- [ ] 2.4.5 Update instance status based on probe result ("running" or "failed")
+- [ ] 2.4.6 Handle probe command failures gracefully
+
+### 2.5 Instance Creation Integration
+- [ ] 2.5.1 Update `create_instance` endpoint to use new fields
+- [ ] 2.5.2 Integrate dockerfile build path into creation flow
+- [ ] 2.5.3 Integrate config folder mounting
+- [ ] 2.5.4 Integrate readiness probe execution
+- [ ] 2.5.5 Apply port_override if specified
+- [ ] 2.5.6 Apply start_command if specified
+- [ ] 2.5.7 Apply working_directory if specified
+- [ ] 2.5.8 Apply environment_variables from ToolConfig
+- [ ] 2.5.9 Apply volumes from ToolConfig
+- [ ] 2.5.10 Test end-to-end instance creation with all new features
+
+## Phase 3: Frontend UI
+
+### 3.1 API Client Updates
+- [ ] 3.1.1 Update `api/tool_types.ts` with new fields and endpoints
+- [ ] 3.1.2 Update `api/tool_configs.ts` with new fields
+- [ ] 3.1.3 Create `api/config_folders.ts` with all CRUD operations
+- [ ] 3.1.4 Update TypeScript types/interfaces
+
+### 3.2 Tool Workshop Layout
+- [ ] 3.2.1 Create `pages/tool-workshop.tsx` (replaces tool-configs and tool-types)
+- [ ] 3.2.2 Implement split-pane layout (sidebar + main content)
+- [ ] 3.2.3 Create sidebar navigation tree (Tool Types / Config Folders)
+- [ ] 3.2.4 Implement tab switching (Tool Types / Configs / Config Folders)
+- [ ] 3.2.5 Add responsive design (collapsible sidebar on mobile)
+- [ ] 3.2.6 Update App.tsx routing
+
+### 3.3 Tool Type Builder
+- [ ] 3.3.1 Create `components/ToolTypeBuilder.tsx`
+- [ ] 3.3.2 Implement definition type selector (Compose vs Dockerfile)
+- [ ] 3.3.3 Create compose template editor (textarea with YAML highlighting)
+- [ ] 3.3.4 Create dockerfile editor (textarea with Dockerfile highlighting)
+- [ ] 3.3.5 Add build context file manager
+- [ ] 3.3.6 Add readiness probe configuration (command, timeout, interval)
+- [ ] 3.3.7 Add validation feedback (syntax check)
+- [ ] 3.3.8 Implement create/update/delete operations
+
+### 3.4 Config Editor Enhancement
+- [ ] 3.4.1 Update config form with new fields
+- [ ] 3.4.2 Add port override input (integer, 1-65535)
+- [ ] 3.4.3 Add start command input
+- [ ] 3.4.4 Add working directory input
+- [ ] 3.4.5 Create environment variables editor (key-value table)
+- [ ] 3.4.6 Create volumes editor (source/target/type table)
+- [ ] 3.4.7 Add JSON validation for env vars and volumes
+- [ ] 3.4.8 Implement tabbed sections (Basic / Runtime / Advanced)
+
+### 3.5 Config Folder Manager
+- [ ] 3.5.1 Create `components/ConfigFolderManager.tsx`
+- [ ] 3.5.2 Implement folder list view
+- [ ] 3.5.3 Create folder editor (name, description, mount_path)
+- [ ] 3.5.4 Create file manager (add/edit/delete files with path and content)
+- [ ] 3.5.5 Implement file content editor (textarea with syntax highlighting)
+- [ ] 3.5.6 Create project override manager
+- [ ] 3.5.7 Add active/inactive toggle
+- [ ] 3.5.8 Show folder size indicator
+
+### 3.6 Navigation Updates
+- [ ] 3.6.1 Update header/navigation to link to `/tool-workshop`
+- [ ] 3.6.2 Remove old `/tool-configs` and `/tool-types` routes (or redirect)
+- [ ] 3.6.3 Update breadcrumb navigation if applicable
+
+## Phase 4: Integration & Testing
+
+### 4.1 Backend Testing
+- [ ] 4.1.1 Test config folder CRUD operations
+- [ ] 4.1.2 Test config folder project overrides
+- [ ] 4.1.3 Test tool type creation with dockerfile
+- [ ] 4.1.4 Test tool type creation with compose
+- [ ] 4.1.5 Test readiness probe execution (success case)
+- [ ] 4.1.6 Test readiness probe execution (timeout case)
+- [ ] 4.1.7 Test instance creation with config folders mounted
+- [ ] 4.1.8 Test instance creation with port override
+- [ ] 4.1.9 Test instance creation with volumes
+- [ ] 4.1.10 Test 10MB size limit enforcement
+
+### 4.2 Frontend Testing
+- [ ] 4.2.1 Test Tool Workshop page load
+- [ ] 4.2.2 Test tool type creation flow
+- [ ] 4.2.3 Test config folder creation and file management
+- [ ] 4.2.4 Test config editor with all new fields
+- [ ] 4.2.5 Test responsive layout on mobile
+- [ ] 4.2.6 Test form validation (port range, JSON structure)
+
+### 4.3 End-to-End Testing
+- [ ] 4.3.1 Create a new tool type with dockerfile, start instance
+- [ ] 4.3.2 Create a new tool type with compose, start instance
+- [ ] 4.3.3 Create config folder, mount into instance, verify files present
+- [ ] 4.3.4 Add project override, verify different files in different projects
+- [ ] 4.3.5 Test readiness probe with failing command (should mark failed)
+- [ ] 4.3.6 Test readiness probe with succeeding command (should mark running)
+
+### 4.4 Quality Gates
+- [ ] 4.4.1 Run backend linting (ruff)
+- [ ] 4.4.2 Run backend type checking (mypy)
+- [ ] 4.4.3 Run frontend type checking (tsc)
+- [ ] 4.4.4 Run frontend linting (eslint)
+- [ ] 4.4.5 Build frontend and verify no errors
+- [ ] 4.4.6 Run existing tests to ensure no regressions
+- [ ] 4.4.7 Verify backward compatibility (existing instances still work)
+
+## Phase 5: Documentation & Deployment
+
+### 5.1 Documentation
+- [ ] 5.1.1 Update API documentation (OpenAPI/Swagger annotations)
+- [ ] 5.1.2 Add tool workshop user guide
+- [ ] 5.1.3 Document config folder usage
+- [ ] 5.1.4 Document readiness probe configuration
+- [ ] 5.1.5 Add example dockerfile and compose templates
+
+### 5.2 Migration & Deployment
+- [ ] 5.2.1 Verify database migrations run cleanly on existing data
+- [ ] 5.2.2 Update seed data for built-in tool types (add definition_type)
+- [ ] 5.2.3 Test fresh install (no existing data)
+- [ ] 5.2.4 Commit all changes with conventional commit messages
+- [ ] 5.2.5 Create comprehensive PR description
+
+## Quality Gates Summary
+
+**Before completing this change:**
+- All migrations must run successfully
+- Backend linting and type checking must pass
+- Frontend build must succeed with no errors
+- All new API endpoints must be tested
+- At least one end-to-end test for each new feature
+- No regressions in existing instance creation flow
+- Documentation updated