# Proposal: Workspace-First UI Refresh

## Status

| Field | Value |
|---|---|
| Phase | **Proposal** |
| Based on | [Working Copies Spec](../working-copies/spec.md) |
| Next | Spec |

## Problem

The current UI has two competing "workspace" concepts:

1. **Old "Repository Workspace"** (`repo-workspace.tsx`): A file browser + editor + git toolbar view tied to a repository. This was the default view when opening a project. It reads files from the repo path directly and offers quick editing.
2. **New "Workspace"** (`workspaces.tsx`): A list of persistent writable clones that tool instances mount. These are first-class entities with their own lifecycle.

These two concepts confuse users. The old workspace is redundant now that workspaces are persistent clones — users should work inside a workspace, not directly on the repo.

Additionally:
- The Projects page only shows a list of projects with "Open Workspace" links — no visibility into repos or workspaces
- Tool instances are spawned from the repo-workspace view, not from the workspace view
- Mobile layout of the old workspace is cramped and not well-suited for the new paradigm

## Solution

Replace the old "Repository Workspace" with a **Workspace-First** navigation model:

### New Information Architecture

```
Projects
  └── Project Card (inline repos + workspaces)
        └── Repo: "my-app"
              ├── Workspace: "main" → /workspaces/{id}
              ├── Workspace: "feature-auth" → /workspaces/{id}
              └── [+ New Workspace]
Workspaces
  └── All Workspaces (grid/list)
        └── Workspace Card → /workspaces/{id}
```

### Workspace Detail Page (`/workspaces/:workspaceId`)

The workspace detail page is the primary work surface. It replaces the old repo-workspace:

```
┌──────────────────────────────────────────────────────────────┐
│  {project} / {repo} / {workspace-name}     [Start Tool ▼]   │
├──────────────┬───────────────────────────────────────────────┤
│              │  Tabs: [Files] [Git] [Tools]                  │
│  File Tree   ├───────────────────────────────────────────────┤
│  (workspace  │                                               │
│   clone)     │  {active tab content}                         │
│              │                                               │
│  📁 src/     │                                               │
│  📄 README   │                                               │
│              │                                               │
├──────────────┤                                               │
│  Git Status  │                                               │
│  (compact)   │                                               │
└──────────────┴───────────────────────────────────────────────┘
```

**Panels (collapsible, IDE-style):**
- **Files**: File tree from workspace clone path + file viewer/editor
- **Git**: Commit panel, branch selector, push/pull/fetch actions (operating on workspace clone)
- **Tools**: List of active tool instances on this workspace + spawn new tool

**Start Tool**: Inline modal (not page navigation) to spawn a tool instance on this workspace.

### Projects Page Refresh

Project cards now show:
- Project name + description
- Repositories (accordion/list)
- For each repo: its workspaces as clickable chips/cards
- "New Workspace" button per repo

```
┌─────────────────────────────────────────────┐
│ My Project                                  │
│ A web application                            │
├─────────────────────────────────────────────┤
│ Repositories:                               │
│                                             │
│ ▼ my-app (git@github.com:...)               │
│   ┌─────────┐ ┌─────────────┐ [+ New]      │
│   │ main    │ │ feature-auth│               │
│   │ ● 2     │ │ ● 0         │               │
│   └─────────┘ └─────────────┘               │
│                                             │
│ ▶ api-service                               │
│   ┌─────────┐ [+ New]                      │
│   │ main    │                               │
│   └─────────┘                               │
└─────────────────────────────────────────────┘
```

### Mobile Layout

Bottom tab bar (4 tabs):
- **Files**: Full-screen file tree + viewer
- **Git**: Compact commit panel + action buttons
- **Tools**: Instance list + spawn button
- **Menu**: Workspace switcher, settings

Swipe between tabs. File tree is always accessible.

### Deleted

- `pages/repo-workspace.tsx` — old repository workspace (file browser + editor on repo path)
- Route `/projects/:projectId` → now shows project detail, not file browser
- Old workspace header component
- Git toolbar component (replaced by panel in workspace detail)

## Scope

### In Scope

- [ ] New workspace detail page (`/workspaces/:workspaceId`)
- [ ] File browser reading from workspace clone path
- [ ] File viewer/editor for workspace files
- [ ] Git operations on workspace clone (status, commit, push, pull, fetch, branch)
- [ ] Tool instance list per workspace
- [ ] Inline tool spawn modal
- [ ] Collapsible IDE-style panels (desktop)
- [ ] Bottom tab bar layout (mobile)
- [ ] Projects page refresh (inline repos + workspaces)
- [ ] Workspace list page improvements (link to detail page)
- [ ] Backend: file endpoints for workspace path
- [ ] Backend: git endpoints for workspace path
- [ ] Delete old `repo-workspace.tsx` and related components
- [ ] Update routing

### Out of Scope

- Git history / diff view (deferred, can reuse existing page)
- Workspace sharing between users
- Advanced IDE features (search, multi-file edit)
- Auto-sync on schedule
- Terminal integration inside workspace page

## Decisions

| # | Question | Answer |
|---|---|---|
| 1 | Projects page → what happens on "Open"? | **A** — Show project detail with repos + workspaces inline |
| 2 | Workspace page layout? | **C** — Collapsible panels, IDE-style |
| 3 | File browser source? | Workspace clone path (`/data/working-copies/{repo-id}/{name}/`) |
| 4 | Git actions scope? | Workspace clone |
| 5 | Tool spawning? | Inline modal on workspace page |
| 6 | Mobile layout? | Bottom tab bar (Files / Git / Tools / Menu), swipeable |
| 7 | Old workspace fallback? | **No fallback** — delete immediately |
| 8 | Projects page detail level? | Inline workspace cards on project page |

## Open Questions for Spec

1. Should the workspace detail page URL be `/workspaces/:id` or nested under project/repo?
2. Should we keep the sidebar Workspaces nav entry, or rely on Projects → Workspace flow?
3. How does "New Workspace" flow work from Projects page — inline form or navigate to create page?
4. Should workspace detail show repo remote URL and allow switching branches?
5. What happens when a workspace has no tool instances yet — show empty state or prompt to spawn?

## Risks

| Risk | Mitigation |
|---|---|
| Users confused by navigation change | Keep "Workspaces" in sidebar, add breadcrumbs |
| Large frontend refactor | Break into 3 PRs: backend endpoints, workspace detail page, projects refresh |
| Mobile layout complexity | Prototype with CSS grid first, test on actual device |
| Git operations on workspace path | Reuse existing git service, just change the path argument |

## Success Criteria

- [ ] Old `repo-workspace.tsx` is deleted
- [ ] `/projects/:id` shows project detail with repos and workspaces
- [ ] `/workspaces/:id` shows workspace detail with Files, Git, Tools panels
- [ ] File browser reads from workspace clone path
- [ ] Git commit/push/pull work on workspace clone
- [ ] Tool spawn modal creates instance with workspace mounted
- [ ] Mobile layout uses bottom tabs
- [ ] All existing tests pass (or updated)
- [ ] ruff clean, TypeScript clean, eslint clean