paseo/docs/glossary.md

Paseo Glossary

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. Its id is opaque workspace identity; its cwd is the filesystem directory. 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". The git-derived, persisted property of a workspace, used across its lifetime (archive safety, sidebar, grouping). Derived from the cwd's git reality (deriveWorkspaceKind, packages/server/src/server/workspace-registry-model.ts:158), not stored from a user choice. Code: PersistedWorkspaceKind (packages/server/src/server/workspace-registry-model.ts:8). Don't confuse with Isolation (the create-time intent).
• Isolation — Create-time choice for a new workspace: reuse the existing checkout (Local) or cut a dedicated git worktree (New worktree). A transient setup input, also remembered as a create-form preference; it is not a workspace property. UI: "Isolation" control on the New Workspace screen. Code: isolation ("local" | "worktree"), useWorkspaceIsolation (packages/app/src/screens/new-workspace-screen.tsx); persisted as FormPreferences.isolation (packages/app/src/create-agent-preferences/preferences.ts). Distinct from Workspace kind, which is the git-derived property the intent produces (Local → local_checkout or directory by git-ness; New worktree → worktree). On the wire it is the create request's source.kind (directory | worktree, packages/protocol/src/messages.ts:1693).
• Agent — A runnable identity the user picks to start work: today that is an Agent provider (Claude Code, Codex, Paseo Agent); direction: also a named Agent definition (reviewer) that pins provider, model, prompt, and tools. One CLI namespace: paseo run --agent <id> resolves agent provider ids first, then agent definition ids. The running instance is an Agent session — "New Agent" starts a new agent session. 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 HostConnections. 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.
• Placement — One workspace's relationship to its project (projectKey, projectName, git checkout snapshot). Internal. Code: ProjectPlacementPayload (packages/protocol/src/messages.ts:2113).
• 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.
• Directory-backed surface — A right-sidebar surface whose content is determined by the workspace's cwd, so two workspaces on the same directory see identical content: git diff/status, GitHub PR info, file preview/explorer contents. Keyed by (serverId, cwd), never workspaceId. See architecture.md.
• Workspace-owned state — Per-workspace state that never leaks to a same-cwd sibling: tabs, agents, terminals, panes, title, plus review drafts, diff-mode overrides, composer attachments, and file-explorer open/expand state. Keyed by workspaceId (cwd only as a fallback for old payloads). See architecture.md.
• Workspace status bucket — Aggregate activity signal for a workspace row. Same-cwd workspaces intentionally share agent and terminal status buckets, while tab, agent, and terminal visibility remains scoped by workspaceId.
• Agent session — One running instance of an agent inside a workspace (one agent provider, one model, one cwd, one timeline). The conceptual unit; in the UI this opens as a tab. Canonical term for the running instance (bare "Agent" is the identity being run, see Agent). Code: AgentSnapshotPayload (packages/protocol/src/messages.ts:608).
• Agent definition — A Paseo-owned markdown persona in $PASEO_HOME/agents/*.md: frontmatter name, prompt, model, tools, permissions; body is the prompt. Selected via agents.paseo.defaultAgent (defaultProfile is a legacy alias). Direction: definitions join the --agent namespace (paseo run --agent reviewer), so a definition id must not shadow an agent provider id. Code: loadAgentDefinition (packages/server/src/server/agent/providers/paseo-agent/prompt-profiles.ts:62), config keys (packages/server/src/server/agent/providers/paseo-agent/config.ts:174). Forbidden: "Profile", "Prompt profile" as synonyms.
• 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.
• Agent provider — The harness/backend that runs agents (Claude Code, Codex, Copilot, OpenCode, Pi, OMP, Paseo Agent with id paseo). UI: "Agent provider" (target label; surfaces still saying bare "Provider" migrate as touched). Wire and config keep provider — labels move, the protocol does not. Code: AgentProvider (packages/protocol/src/agent-types.ts:3), ProviderSnapshotEntrySchema (packages/protocol/src/messages.ts:262). Don't confuse with: Model provider. Forbidden: bare "Provider" as a new UI label — always qualify which layer.
• Model provider — A model API attached to the Paseo Agent provider: a type (openrouter, openai, anthropic, openai-codex, …) plus key/OAuth and models, keyed by instance name (openrouter-main, chatgpt). UI: "Model providers" (Paseo Agent settings). CLI: paseo provider add — the CLI provider noun means model provider. Config: agents.paseo.providers (packages/server/src/server/agent/providers/paseo-agent/config.ts:169); wire: PaseoAgentProviderTypeSchema (packages/protocol/src/messages.ts:1924). Don't confuse with: Agent provider. Forbidden: "Inference provider" (old docs term), bare "Provider" as a new UI label.
• Model — A specific LLM offered by a provider; for the Paseo Agent provider, addressed as <modelProviderName>/<modelId>. 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.
• Mode — Provider-specific operational mode (plan, default, full-access, …). UI: icon-only. Code: modeId in AgentSessionConfig (packages/protocol/src/messages.ts:257).
• Attachment — GitHub PR or Issue bound to an agent prompt. UI: "Attach issue or PR". Code: AgentAttachment (packages/protocol/src/messages.ts:782).
• Composer — The whole prompt surface for sending work to an agent. Code: Composer (packages/app/src/composer/index.tsx). Don't call this "message input" except for the text-entry subcomponent.
• Composer input — The text-entry surface inside the composer. Code: MessageInput (packages/app/src/composer/input/input.tsx).
• Composer toolbar — The bottom control row inside the composer input. Contains agent controls, attachment button, voice controls, and stop/send controls. Code: leftContent, beforeVoiceContent, and rightContent slots in MessageInput (packages/app/src/composer/input/input.tsx). Forbidden: "Status bar".
• Agent controls — Provider, model, mode, thinking, and provider-feature controls for an agent or draft agent. Code: AgentControls / DraftAgentControls (packages/app/src/composer/agent-controls/index.tsx). Forbidden: "Agent status bar".
• Composer footer — Optional area rendered below the composer input but still inside the keyboard-shifted composer layout. Code: Composer.footer (packages/app/src/composer/index.tsx).
• Composer track — A contextual lane above the composer input. Specific tracks use the <thing> track form: Queue track, Subagents track. Code: queue track inside Composer (packages/app/src/composer/index.tsx), SubagentsTrack (packages/app/src/subagents/track.tsx).
• Attachment tray — The selected-attachments row inside the composer input, above the text input. Code: renderAttachmentTray (packages/app/src/composer/index.tsx). Forbidden: "Attachment bar".
• Conflict — Two distinct senses; do NOT use the bare word in UI copy without qualifying which: (a) stale-write conflict on paseo.json ("Config changed on disk", code stale_project_config, packages/app/src/screens/project-settings-screen.tsx:593); (b) git merge conflict (no current UI string).

Inconsistencies (documented, not papered over)

• Bare "Provider" survives as a UI label in the provider picker and settings; target is "Agent provider" / "Model providers" per the entries above. Migrate labels as surfaces are touched — no big-bang rename.
• CLI paseo provider describes itself as "Manage agent providers" (packages/cli/src/commands/provider/index.ts:11) but manages model providers. Fix the description; keep the noun.
• CLI paseo run --provider <id> selects an agent provider. Direction: add --agent <id> as the canonical flag resolving one namespace (agent provider ids, then agent definition ids), keep --provider as a COMPAT alias.
• CLI --host <host> description "Daemon host target" (packages/cli/src/utils/command-options.ts:5) blurs daemon/host; the app keeps them distinct.
• WorkspaceDescriptorPayloadSchema.workspaceKind accepts legacy "checkout" on the wire (packages/protocol/src/messages.ts:2187) while PersistedWorkspaceKind does not (packages/server/src/server/workspace-registry-model.ts:8).