SnapOtter/docs/superpowers/specs/2026-03-25-settings-phase1-design.md

# Settings Phase 1 — Admin Control Panel

Inspired by Stirling-PDF's settings system, this phase adds five features to the existing settings dialog to make Stirling-Image feel like a serious self-hosted product.

## Decisions

- Extend existing settings dialog (no separate admin panel route)
- Teams are organizational labels only — no per-team permissions
- Tool disabling and feature flags require server restart
- Temp file management is minimal (max age + startup cleanup)
- Custom branding is app name + logo (no favicon, no custom theme colors)

## 1. Teams Management

**New "Teams" tab in settings dialog.**

Simple CRUD for teams. Users are assigned to teams from the existing People section.

### Database

New `teams` table:

| Column | Type | Notes |
|---|---|---|
| id | text | Primary key (UUID) |
| name | text | Unique, not null |
| createdAt | integer (timestamp) | Auto-set |

Migration steps (single Drizzle migration file):
1. Create `teams` table
2. Insert a "Default" team with a known UUID
3. Collect all distinct `users.team` string values; for each non-"Default" value, insert a new team row
4. Update `users.team` from the string value to the corresponding team UUID
5. Keep `users.team` as a plain `text` column (no DB-level FK — SQLite doesn't support adding FK constraints via ALTER TABLE). Enforce the relationship at the application level.

Note: The existing `0003_add_team_to_users.sql` migration added the `team` column as free text. This new migration extends that by creating the `teams` table and converting values.

### Team Name Validation

- 1-50 characters
- Trimmed (no leading/trailing whitespace)
- Unique (case-insensitive)
- The "Default" team cannot be deleted (it's the fallback for new users)

### API Routes

| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/teams | auth | List all teams with member count |
| POST | /api/v1/teams | admin | Create team (body: `{ name }`) |
| PUT | /api/v1/teams/:id | admin | Rename team (body: `{ name }`) |
| DELETE | /api/v1/teams/:id | admin | Delete team (fails if team has members or is "Default") |

### UI

- Table with columns: Team Name, Total Members, actions (three-dot menu: Rename, Delete)
- "+ Create New Team" button
- Delete blocked with message if team has assigned members or is the Default team
- People section's team assignment dropdown pulls from teams table

## 2. Tool Disabling

**New "Tools" tab in settings dialog.**

Admin can globally disable specific tools. Disabled tools are hidden from all users.

### Settings Key

`disabledTools` — JSON array of tool IDs. Default: `"[]"`

### Behavior

- On save, shows "Restart required for changes to take effect" banner
- On API startup, server reads `disabledTools` and skips registering those tool routes (server-side enforcement)
- Frontend also filters disabled tools from the tool panel for immediate visual feedback after save, but API routes remain active until restart
- Pipelines containing disabled tools: step renders but shows "tool unavailable" badge

### UI

- Searchable list of all registered tools
- Each tool has a toggle (on = enabled, off = disabled)
- Search/filter bar at top
- Tools grouped by category for easier scanning
- "Restart required" banner appears after any change is saved

## 3. Feature Flags

**Added to existing "System Settings" section.**

Single toggle controlling visibility of experimental tools.

### Settings Key

`enableExperimentalTools` — `"true"` or `"false"`. Default: `"false"`

### Tool Registry Change

Reuse the existing `alpha?: boolean` field on the `Tool` type in `packages/shared/src/types.ts`. Rename it to `experimental?: boolean` for clarity (update all references). Tools marked experimental are hidden unless the flag is enabled.

### Behavior

- Works independently of tool disabling (a tool can be both experimental AND manually disabled)
- On save, shows "Restart required" banner
- When flag is off, experimental tools are excluded from: tool panel, fullscreen grid, pipeline step picker

### UI

- Single toggle row in System Settings: "Enable Experimental Tools" with description "Show tools that are still in development. These may be unstable."

## 4. Temp File Management

**Added to existing "System Settings" section under "File Management" sub-heading.**

Admin controls how long processed files persist and whether to clean on startup.

### Settings Keys

| Key | Default | Description |
|---|---|---|
| tempFileMaxAgeHours | "24" | Hours before temp files are eligible for cleanup |
| startupCleanup | "true" | Whether to run cleanup on server boot |

### Behavior

- The cleanup function re-reads `tempFileMaxAgeHours` from the settings DB on every cycle (not cached at startup). If the setting is not set, falls back to the `FILE_MAX_AGE_HOURS` env var (default 24). DB setting takes precedence over env var.
- On startup, if `startupCleanup` is true, cleanup runs asynchronously (does not block server startup — matches current behavior where `startCleanupCron()` is non-blocking)
- Changes take effect on next cleanup cycle (no restart required)

### UI

- Number input: "Max File Age (hours)" with description "How long processed files are kept before automatic cleanup"
- Toggle: "Startup Cleanup" with description "Clean up old temporary files when the server starts"

## 5. Custom Branding — Logo Upload

**Added to existing "System Settings" section, below App Name.**

Admin uploads a custom logo displayed in the sidebar/navbar.

### API Routes

| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/v1/settings/logo | admin | Upload logo (PNG/SVG/JPEG, max 500KB) |
| GET | /api/v1/settings/logo | public | Serve custom logo (404 if none) |
| DELETE | /api/v1/settings/logo | admin | Remove custom logo |

### Settings Key

`customLogo` — `"true"` or `"false"`. Default: `"false"`

### Behavior

- All uploaded logos are converted to PNG and stored to `data/branding/logo.png` (SVGs are rasterized, JPEGs are re-encoded)
- Server resizes to max 128x128 via Sharp on upload
- `GET /api/v1/settings/logo` serves with `Content-Type: image/png`. This route must be added to `PUBLIC_PATHS` in `auth.ts` so the logo is accessible on the login page.
- Sidebar/navbar checks `customLogo` on mount — if true, loads from logo endpoint; otherwise uses built-in SVG
- No restart required — logo change is immediate

### UI

- Logo upload area with drag-and-drop, preview thumbnail
- "Remove" button to revert to default logo
- Accepts PNG, SVG, JPEG. Max 500KB.
- Shows current logo preview if one is set

## 6. Settings Dialog Navigation

### Current Sections
General, System Settings, Security, People, API Keys, About

### New Sections
General, System Settings, Security, People, **Teams**, API Keys, **Tools**, About

### Section Contents

| Section | What's new |
|---|---|
| System Settings | Feature flags toggle, temp file management controls, logo upload area (all added to existing section) |
| Teams | Entirely new — team CRUD table |
| Tools | Entirely new — tool enable/disable list |

### Frontend Type Changes

- Add `"teams" | "tools"` to the `Section` type union in `settings-dialog.tsx`
- Add corresponding entries to `NAV_ITEMS` array

### i18n

Add translation keys to `packages/shared/src/i18n/en.ts` under `settings` for the new sections (teams, tools) and their UI strings.

## Summary

| Feature | UI Location | New DB/API | Restart Required |
|---|---|---|---|
| Teams CRUD | New "Teams" tab | `teams` table, 4 CRUD routes | No |
| Tool disabling | New "Tools" tab | `disabledTools` setting key | Yes |
| Feature flags | System Settings | `enableExperimentalTools` setting key | Yes |
| Temp file management | System Settings | 2 setting keys | No |
| Logo upload | System Settings | 3 routes, `customLogo` key, `data/branding/` | No |