From 8e6455f1d60ea6112ee733cb6391bdfc55437207 Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Wed, 10 Jun 2026 15:49:51 +0700 Subject: [PATCH] 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 | 6 ++-- public-docs/best-practices.md | 2 +- public-docs/cli.md | 2 +- public-docs/configuration.md | 2 +- public-docs/custom-providers.md | 2 +- public-docs/index.md | 1 + public-docs/mcp.md | 2 +- public-docs/metadata-generation.md | 2 +- public-docs/providers.md | 2 +- public-docs/schedules.md | 2 +- public-docs/security.md | 2 +- public-docs/skills.md | 2 +- public-docs/supported-providers.md | 2 +- public-docs/voice.md | 2 +- public-docs/workspaces.md | 49 ++++++++++++++++++++++++++++++ public-docs/worktrees.md | 8 +++-- 16 files changed, 72 insertions(+), 16 deletions(-) create mode 100644 public-docs/workspaces.md diff --git a/docs/glossary.md b/docs/glossary.md index 37780bb53..08778e432 100644 --- a/docs/glossary.md +++ b/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. diff --git a/public-docs/best-practices.md b/public-docs/best-practices.md index 4ed412df2..88505fc79 100644 --- a/public-docs/best-practices.md +++ b/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 diff --git a/public-docs/cli.md b/public-docs/cli.md index 2f60e6362..6af28b531 100644 --- a/public-docs/cli.md +++ b/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 diff --git a/public-docs/configuration.md b/public-docs/configuration.md index 9fedebca7..7f07342dd 100644 --- a/public-docs/configuration.md +++ b/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 diff --git a/public-docs/custom-providers.md b/public-docs/custom-providers.md index 14b5e6399..6e2706925 100644 --- a/public-docs/custom-providers.md +++ b/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 diff --git a/public-docs/index.md b/public-docs/index.md index 91aaeb1c1..1c2deba50 100644 --- a/public-docs/index.md +++ b/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) diff --git a/public-docs/mcp.md b/public-docs/mcp.md index 54f000800..a16826a9c 100644 --- a/public-docs/mcp.md +++ b/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 diff --git a/public-docs/metadata-generation.md b/public-docs/metadata-generation.md index a3ad02000..2c22ec069 100644 --- a/public-docs/metadata-generation.md +++ b/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 diff --git a/public-docs/providers.md b/public-docs/providers.md index ae97166ca..3b75d14ff 100644 --- a/public-docs/providers.md +++ b/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 diff --git a/public-docs/schedules.md b/public-docs/schedules.md index 68d85a115..8e6e7bed1 100644 --- a/public-docs/schedules.md +++ b/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 diff --git a/public-docs/security.md b/public-docs/security.md index 88c373667..9f98a17a0 100644 --- a/public-docs/security.md +++ b/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 diff --git a/public-docs/skills.md b/public-docs/skills.md index a71173622..1ef6630b8 100644 --- a/public-docs/skills.md +++ b/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 diff --git a/public-docs/supported-providers.md b/public-docs/supported-providers.md index b209cc314..f64a5f410 100644 --- a/public-docs/supported-providers.md +++ b/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 diff --git a/public-docs/voice.md b/public-docs/voice.md index 1fa77256b..2045e5218 100644 --- a/public-docs/voice.md +++ b/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 diff --git a/public-docs/workspaces.md b/public-docs/workspaces.md new file mode 100644 index 000000000..6aa4af945 --- /dev/null +++ b/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). diff --git a/public-docs/worktrees.md b/public-docs/worktrees.md index 0eb7e44d5..81dd66a03 100644 --- a/public-docs/worktrees.md +++ b/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