docs: add workspaces page explaining project/workspace/session model

Adds a new conceptual Workspaces doc that explains how Paseo organizes work around projects, workspaces, and sessions. Reframed the existing Git worktrees page as the technical deep-dive it always was. Updated glossary with agent session and tab terminology. Reordered docs nav so workspaces and worktrees come before providers.

docs/glossary.md

@@ -5,7 +5,7 @@ Authoritative terminology. UI label wins. Don't invent synonyms; use what's here
 - **Project** — Logical grouping of workspaces sharing a git remote (or main repo root). UI: "Project" / "Add project". Code: `ProjectSummary` (`packages/app/src/utils/projects.ts:22`), `projectKey` (`packages/server/src/server/workspace-registry-model.ts:16`). Forbidden: "Repo", "Repository" as UI label.
 - **Workspace** — One concrete `cwd` on one daemon, with git state; belongs to exactly one project. UI: "Workspace". Code: `WorkspaceDescriptorPayload` (`packages/protocol/src/messages.ts:2178`). Don't confuse with: Branch (one branch can back many workspaces via worktrees). Forbidden: "Folder", "Directory" as UI label.
 - **Workspace kind** — `"directory" | "local_checkout" | "worktree"`. Code: `PersistedWorkspaceKind` (`packages/server/src/server/workspace-registry-model.ts:8`).
-- **Agent** — One AI coding agent run on a daemon (one provider, one model, one cwd, one timeline). UI: "Agent" / "New Agent". Code: `AgentSnapshotPayload` (`packages/protocol/src/messages.ts:608`). Forbidden: "Task", "Job", "Run".
+- **Agent** — See **Agent session**. UI still says "Agent" / "New Agent" in places, but moving toward **Agent session** as the canonical term. Code: `AgentSnapshotPayload` (`packages/protocol/src/messages.ts:608`). Forbidden: "Task", "Job", "Run".
 - **Daemon** — Local Paseo server process; identified by `serverId`. UI: "Daemon" (system contexts only). Code: `serverId` in `ServerInfoStatusPayloadSchema` (`packages/protocol/src/messages.ts:1936`), `DaemonClient` (`packages/client/src/daemon-client.ts`).
 - **Host** — Client-side connection profile pointing at a daemon; bundles one or more `HostConnection`s. UI: "Host" / "Add host" / "Switch host". Code: `HostProfile` (`packages/app/src/types/host-connection.ts:37`). Forbidden: "Connection" (means `HostConnection`, not host).
 - **Project host entry** — One row in a project for a single (project, daemon) pair, aggregating that daemon's workspaces in the project. Internal. Code: `ProjectHostEntry` (`packages/app/src/utils/projects.ts:11`). Don't introduce "Checkout" as a synonym.
@@ -13,10 +13,12 @@ Authoritative terminology. UI label wins. Don't invent synonyms; use what's here
 - **Branch** — Plain git branch. UI: "Switch branch". Code: `currentBranch` in `WorkspaceGitRuntimePayloadSchema` (`packages/protocol/src/messages.ts:2136`); `BranchSwitcher` (`packages/app/src/components/branch-switcher.tsx`).
 - **Worktree** — Paseo-managed git worktree (`~/.paseo/worktrees/{name}`); also a `workspaceKind` value. UI: CLI + `paseo.json` keys (`worktree.setup`, `worktree.teardown`) only. Code: `ProjectCheckoutLiteGitPaseoPayload` (`packages/protocol/src/messages.ts:2092`); CLI `paseo worktree` (`packages/cli/src/commands/worktree/index.ts:8`). Forbidden: "Checkout" as a synonym.
 - **Repository / Remote** — Internal git inputs (`remoteUrl`, `mainRepoRoot`) used to derive `projectKey`. No UI label.
-- **Session** — Per-client connection to a daemon. Internal. Code: `Session` (`packages/server/src/server/session.ts`). Don't confuse with: provider-side agent session log.
+- **Agent session** — One running instance of an agent inside a workspace (one provider, one model, one cwd, one timeline). The conceptual unit; in the UI this opens as a tab. Moving toward this as the canonical term over "Agent". Code: `AgentSnapshotPayload` (`packages/protocol/src/messages.ts:608`).
+- **Session** — Two senses: (a) per-client connection to a daemon, internal; (b) user-facing agent session, see **Agent session**. Code: `Session` (`packages/server/src/server/session.ts`) for (a). Don't confuse with: provider-side agent session log.
 - **Profile** — Internal name for the persisted shape of a host. Code: `HostProfile` (`packages/app/src/types/host-connection.ts:37`). Never user-facing.
 - **Provider** — Agent backend (Claude Code, Codex, Copilot, OpenCode, Pi, OMP). UI: "Provider". Code: `ProviderSnapshotEntry` (`packages/protocol/src/messages.ts:198`).
 - **Model** — A specific LLM offered by a provider. UI: "Model" / "Select model". Code: `AgentModelDefinition` (`packages/protocol/src/messages.ts:187`).
+- **Tab** — UI surface representing one session inside a workspace. Not a conceptual unit; use **Agent session** when talking about the model. Code: `WorkspaceTabDescriptor` (`packages/app/src/screens/workspace/workspace-tabs-types.ts`).
 - **Terminal** — Workspace-scoped PTY shell streamed over the binary mux channel. UI: "Terminal". Code: `TerminalStreamFrame` (`packages/protocol/src/terminal-stream-protocol.ts`).
 - **Schedule** — Cron-style trigger that creates new agents. UI: CLI/MCP (`paseo schedule`, `create_schedule`). Don't confuse with: Heartbeat (cron prompt back into the same agent) or Loop (iterative re-execution of one agent).
 - **Heartbeat** — Cron-style prompt sent back into the same agent/conversation. MCP: `create_heartbeat`. Use for reminders and babysitting where the status should return inline.

public-docs/best-practices.md

@@ -2,7 +2,7 @@
 title: Best practices
 description: Tips for getting the most out of Paseo and mobile-first agent workflows.
 nav: Best practices
-order: 13
+order: 17
 ---
 
 # Best practices

public-docs/cli.md

@@ -2,7 +2,7 @@
 title: CLI
 description: "Paseo CLI reference: manage agents, daemons, permissions, and worktrees from your terminal."
 nav: CLI
-order: 6
+order: 8
 ---
 
 # CLI

public-docs/configuration.md

@@ -2,7 +2,7 @@
 title: Configuration
 description: Configure Paseo via config.json, environment variables, and CLI overrides.
 nav: Configuration
-order: 10
+order: 14
 ---
 
 # Configuration

public-docs/custom-providers.md

@@ -2,7 +2,7 @@
 title: Custom providers
 description: Configure custom providers, alternative endpoints, profiles, custom binaries, and ACP agents in ~/.paseo/config.json.
 nav: Custom providers
-order: 5
+order: 7
 ---
 
 # Custom providers

public-docs/index.md

@@ -30,6 +30,7 @@ Configuration and local state live under `PASEO_HOME` (defaults to `~/.paseo`).
 
 ## Where next
 
+- [Workspaces](/docs/workspaces), the project, workspace, and session model Paseo is built around.
 - [Providers](/docs/providers), what a provider is and how Paseo wraps existing CLIs.
 - [CLI reference](/docs/cli), every command.
 - [GitHub repo](https://github.com/getpaseo/paseo)

public-docs/mcp.md

@@ -2,7 +2,7 @@
 title: Paseo MCP
 description: Paseo MCP tools injected into agents.
 nav: Paseo MCP
-order: 7
+order: 9
 ---
 
 # Paseo MCP

public-docs/metadata-generation.md

@@ -2,7 +2,7 @@
 title: Metadata generation
 description: How Paseo uses providers to generate agent titles, branch names, commit messages, and pull request text, and how to configure them.
 nav: Metadata generation
-order: 11
+order: 15
 ---
 
 # Metadata generation

public-docs/providers.md

@@ -2,7 +2,7 @@
 title: Providers
 description: How Paseo thinks about coding agents, wrapping existing CLIs, native vs ACP support, and where to go next.
 nav: Providers
-order: 3
+order: 5
 ---
 
 # Providers

public-docs/schedules.md

@@ -2,7 +2,7 @@
 title: Schedules
 description: Run Paseo agents on intervals or cron.
 nav: Schedules
-order: 8
+order: 11
 ---
 
 # Schedules

public-docs/security.md

@@ -2,7 +2,7 @@
 title: Security
 description: "Security model for Paseo: architecture overview, connection methods, relay encryption, and best practices."
 nav: Security
-order: 12
+order: 16
 ---
 
 # Security

public-docs/skills.md

@@ -2,7 +2,7 @@
 title: Orchestration skills
 description: "Paseo orchestration skills: teach coding agents to spawn, coordinate, and manage other agents using slash commands."
 nav: Skills
-order: 8
+order: 12
 ---
 
 # Orchestration skills

public-docs/supported-providers.md

@@ -2,7 +2,7 @@
 title: Supported providers
 description: Every coding agent Paseo can launch, natively supported providers and the ACP catalog.
 nav: Supported providers
-order: 4
+order: 6
 ---
 
 # Supported providers

public-docs/voice.md

@@ -2,7 +2,7 @@
 title: Voice
 description: Paseo voice architecture, local-first model execution, and provider configuration.
 nav: Voice
-order: 9
+order: 13
 ---
 
 # Voice

public-docs/workspaces.md

@@ -0,0 +1,49 @@
+---
+title: Workspaces
+description: Understand Paseo's project, workspace, and session model before setting up agents or git worktrees.
+nav: Workspaces
+order: 3
+---
+
+# Workspaces
+
+Paseo is organized around workspaces, not chats.
+
+A workspace is the place where a task happens. It has a working directory and can contain multiple sessions running at the same time. In the app, each session opens as a tab.
+
+## Projects contain workspaces
+
+The sidebar starts with projects. A project can be a git repository, a GitHub project, or any directory on a machine running the Paseo daemon.
+
+Inside each project are workspaces. For example:
+
+```
+my-app
+├── main
+├── fix-login-flow
+└── redesign-settings
+```
+
+Each workspace is a separate place to work. You can keep one for your main checkout, create another for a feature, or open a GitHub PR as another workspace.
+
+## Workspaces contain sessions
+
+Agents run inside a workspace as sessions. A workspace can have one agent session, several agent sessions, terminals, browsers, and diffs open at the same time.
+
+That matters because real development rarely fits into one long chat. You might ask one agent to implement a feature, open a terminal to run a service, start another agent to review the diff, and keep the browser open next to both. Those belong together because they are all part of the same task.
+
+In Paseo, the workspace is the stable container. The sessions are what you run inside it.
+
+## Creating a workspace
+
+When you create a new workspace, Paseo creates a working directory for it. If you are using git, this is an isolated git worktree on its own branch, so agents can work in parallel without touching your main checkout. Paseo names the branch from your first prompt.
+
+You can also create a workspace without starting an agent right away. The workspace is still there with its working directory ready; you can open terminals, run services, or browse files, then start an agent later.
+
+Either way, once the workspace exists you can add more sessions to it. Open a terminal alongside an agent, start a second agent to review changes, or open a browser tab to check a local service. Every session lives as a tab inside the same workspace.
+
+## Worktrees
+
+Every workspace in Paseo is backed by a working directory. When that directory is a git worktree, you get a separate branch and isolated environment for each task.
+
+If you want the details on configuring setup hooks, scripts, and services, continue to [Git worktrees](/docs/worktrees).

public-docs/worktrees.md

@@ -2,12 +2,16 @@
 title: Git worktrees
 description: Run agents in isolated git worktrees with setup hooks, scripts, and long-running services.
 nav: Git worktrees
-order: 7
+order: 4
 ---
 
 # Git worktrees
 
-Each agent runs in its own git worktree, a separate directory on a separate branch, so parallel agents never step on each other. You configure setup, scripts, and long-running services through a `paseo.json` file at your repo root.
+Git worktrees are one kind of workspace.
+
+A [workspace](/docs/workspaces) is the place where a task happens. When that workspace is backed by a git worktree, Paseo creates a separate directory on a separate branch so parallel agents never step on each other.
+
+This page covers the git-specific details: where worktrees live, how branches are chosen, and how to configure setup hooks, scripts, terminals, and long-running services through `paseo.json`.
 
 ## Layout and workflow