paseo/docs/glossary.md

Paseo Glossary

Authoritative terminology. UI label wins. Don't invent synonyms; use what's here.

• Project — A stable, exact selected-root record. Its host-local projectId is an opaque prj_<16 hex> value. Its persisted projectKey is an opaque equivalence key that may group the logical project across hosts. A normalized Git remote is the current key producer, but consumers must not parse or rederive it. Git facts can update mutable kind and grouping metadata but never the ID, root, or default display name. UI: "Project" / "Add project". 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.
• Archive workspace — Removes one workspace from active use and archives everything it owns. UI, CLI, and MCP always say "Archive workspace", regardless of backing. The daemon leaves ordinary directories intact and removes a Paseo-owned worktree only when no active workspace still references it.
• 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 by deriveWorkspaceKind in workspace-registry-model.ts, not stored from a user choice. 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 — 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 HostConnections. UI: "Host" / "Add host" / "Switch host". Code: HostProfile (packages/app/src/types/host-connection.ts:37). Forbidden: "Connection" (means HostConnection, not host).
• Host badge — The item on a sidebar workspace row's meta row naming which host that workspace lives on. Three things gate it, and they compose as a lattice rather than competing: the sidebar must span more than one host (automatic), Show → Host in the sidebar's display preferences must be on (global, all hosts at once), and then that host's own display mode decides how it draws — Name / Icon only / Hidden. Name, color, and display mode are per-host, per-device, and live client-side on HostProfile.appearance; nothing about it reaches the daemon. Never add a fourth way to hide it. UI: the "Appearance" group on a host's settings page, and the "Show" submenu in the sidebar's display preferences. Code: selectHostBadges (packages/app/src/hosts/appearance.ts) takes the first two as its enabled input; WorkspaceMetaRow (packages/app/src/components/sidebar/workspace-meta-row/index.tsx) draws it. Don't confuse with Status pill, which reports state rather than identity.
• 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 stable foreign-key relationship to its project plus its git checkout snapshot. Internal. An explicit creation projectId is authoritative when active.
• 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).
• Forge — Git hosting service behind Paseo's change-request features: GitHub, GitLab, Gitea, Forgejo, or a future registered adapter. Code: ForgeService, forge-registry, forge-resolver. Use forge for internal abstraction and registry IDs; use concrete forge names only when a behavior or RPC is forge-specific.
• Change request — Forge-neutral term for a proposed branch-to-branch code change. UI normally renders the forge noun instead: GitHub/Gitea/Forgejo "PR", GitLab "MR". Code: forge_change_request attachments, checkoutSource: { kind: "change_request" }, and PR/MR status payloads.
• MR — GitLab merge request. UI label for GitLab change requests only; do not use MR for GitHub/Gitea/Forgejo.
• Worktree — Paseo-managed git worktree (~/.paseo/worktrees/{name}); also a workspaceKind value. User-facing creation treats it as the worktree workspace isolation choice. Code and paseo.json retain worktree terminology for git lifecycle implementation. Forbidden: "Checkout" as a product synonym.
• Repository / Remote — Internal Git observations. They may produce mutable kind, branch, and project-grouping metadata but never the host-local project ID, root, display name, or workspace membership. No UI label.
• Sidebar items — The configurable entries of the app sidebar, in two sections. Header: the rows at the head of the sidebar — New workspace, History, Search, Schedules, and plugin header items. Footer: the full-width rows between Add project and the footer icon row — Usage and plugin footer items. Add project and the icon row (Hosts, Import session, Help and support, Settings) are fixed and are not sidebar items. A plugin item may render several rows, such as one per bot; it is still one item that moves and hides as a block. Each section's order and visibility is one per-device preference (AppSettings.sidebarNavItems, AppSettings.sidebarFooterItems); every item may be off. UI: the Header and Footer cards on the Sidebar settings page. Code: packages/app/src/sidebar-nav/model.ts resolves a section, and the sidebar (components/sidebar/sidebar-nav-rows.tsx, the footer in components/left-sidebar.tsx) and the settings page (screens/settings/sidebar/sidebar-nav-section.tsx) read it through useSidebarNavItems(section). Never hardcode one of these entries or add a second place that decides which ones show. Don't confuse with Explorer sidebar.
• Explorer sidebar — The dedicated navigation dock containing the Files and Changes trees. UI: "Explorer sidebar". Code: packages/app/src/workspace-tabs/explorer-sidebar.ts; persisted pane identifiers retain the explorer spelling. See explorer-sidebar.md.
• Side pane — An ordinary right-side workspace pane used for content opened beside the user's work. It closes and participates in workspace splits like every other main-host pane. See explorer-sidebar.md. Forbidden: "Side panel".
• 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, forge change-request 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 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. Three other things are called "profile" in this codebase, so always qualify: Agent profile, Terminal profile, and the provider aliases in custom-providers.md. Bare "profile" is forbidden in UI copy.
• Agent profile — A named launch bundle: provider, model, mode, thinking option, feature values, and free-text notes. Applying one writes those values into the Agent controls and is then forgotten — there is no selected profile, no default profile, and no drift tracking. The notes are written for orchestrating agents and are what the list_profiles MCP tool surfaces. Stored host-wide in daemon config as agentProfiles. UI: "Agent profiles". Code: AgentProfile (packages/protocol/src/messages.ts:161). Carries no system prompt, because a per-agent system prompt can only be set at creation. Forbidden: "Favourite", which this replaced.
• Terminal profile — A named shell command a terminal can launch. Stored host-wide in daemon config as terminalProfiles. UI: "Terminal profiles". Code: TerminalProfile (packages/protocol/src/messages.ts:135), resolveTerminalProfiles (packages/protocol/src/terminal-profiles.ts). Also selectable as a New Workspace launch target, where the alternative is the chat agent.
• Provider — Agent backend (Claude Code, Codex, Copilot, OpenCode, Pi, Oh My Pi). UI: "Provider". Code: ProviderSnapshotEntry (packages/protocol/src/messages.ts:198).
• Usage source — Plugin registration that discovers accounts and fetches plan usage. Code: UsageSourceRegistration (packages/plugin/src/server/usage.ts).
• Report ID — Stable daemon-composed identity for one source account: <sourceId>:<accountKey>. The source owns the account key; clients treat the whole ID as opaque. Code: UsageReportEntry.id (packages/protocol/src/messages.ts).
• Usage report — A source's normalized usage for one account, including status and optional windows, balances, and details. Its entry carries the Report ID, account label, and fetch time. Code: UsageReport (packages/plugin/src/server/usage.ts).
• Usage (sidebar item) — The sidebar footer item showing each pinned window's source icon and percent, or a plain "Usage" row while no pinned window has data; pressing it opens the Usage screen (a bottom sheet on phones). A pin is { sourceId, windowId } and shows once per account of that source. Pins and the used/remaining choice are one per-device preference (AppSettings.usage) that every usage surface follows. It reads the active workspace's host, else the first connected host with usage sources. Code: packages/app/src/usage/sidebar-item.tsx, usage/pinned.ts, usage/preferences.ts.
• 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).
• Workspace script — A named command a workspace can run, declared in paseo.json. Two types: service and script (a command that runs and finishes). UI: "Scripts" for the panel and the menu, both of which list either type. Code: WorkspaceScriptPayload (packages/protocol/src/messages.ts:3126). Don't confuse with Service, which is one of the two types rather than a synonym for the pair.
• Service — A workspace script of type service: long-running, may bind a port, and carries health of healthy | unhealthy | null once the daemon has observed it. The only type a sidebar workspace row reports, because a running plain script says nothing about whether the workspace is up; the row names the service and turns danger when its health fails, and where several run the failing one takes the row's single slot. UI: "Services" in the sidebar's display preferences (Show → Services). Code: selectWorkspaceServiceSummary (packages/app/src/components/sidebar/workspace-meta-row/service-summary.ts), WorkspaceScriptHealthSchema (packages/protocol/src/messages.ts:3124). Forbidden: "Service" as a label for the Scripts panel, which lists both types.
• 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).
• Heartbeat — Ephemeral cron prompt sent back into the same agent/conversation. Agent surfaces expose create, update cron, and delete only. Use for reminders and babysitting where 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 — External or local context bound to an agent prompt: forge issue/change request, review context, uploaded file, text, or image. UI: "Attach issue or PR/MR". 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 at the foot of a pane, by the composer input. Specific tracks use the <thing> track form: Queue track, Subagents track, Tasks track. The subagents and tasks tracks are pills floating over the transcript, each opening a panel with its rows; the queue track is a lane inside the composer itself. Code: queue track inside Composer (packages/app/src/composer/index.tsx), pill and panel frame in packages/app/src/composer/tracks.tsx, SubagentsTrack (packages/app/src/subagents/track.tsx), AgentTaskList (packages/app/src/composer/task-list/index.tsx).
• Steer — A follow-up admitted into an agent's already-running turn instead of interrupting it. Interrupting the turn discards steers the provider has not read yet; there is no take-back short of that, and no provider offers one. The stop button and Escape both interrupt. A steer the provider never read keeps its transcript row, matching Codex. Sending while the agent waits on a permission denies that request first, so the message reaches the same turn instead of stalling behind it. UI: "Send and steer". Code: steerActiveTurn (packages/server/src/server/agent/agent-sdk-types.ts). Don't confuse with Queue track, which holds messages client-side until the turn ends and never enters the running turn. Forbidden: "Delivery", "Queued prompt".
• Subagent — User-facing term for an agent session related to a parent agent session. Use subagents in UI copy and docs. Internal daemon/provider plumbing may say "child agent" or child_session, especially for provider-managed imports; do not surface "child agent" as a product term.
• 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".
• Fork — Starting a NEW agent session seeded with a copy of another session's curated chat history. The history rides along as a chat_history composer attachment on a draft; the fork does not resume or branch the provider-side session, and the source session keeps running untouched. Two targets, one surface, one RPC (agent.fork_context, gated on the agentForkContext host feature). UI: the fork menu lives in the assistant turn footer and offers "Fork in a new tab" / "Fork in a new workspace". On a completed turn it sits beside the copy button and pins a boundary to that turn, so the fork stops where the turn ended. On the in-flight turn it sits beside the progress loader and elapsed timer, and omits the boundary entirely — selectForkContextRows projects the whole timeline when no boundary is given, so the fork captures everything up to now, including the response still streaming. That omission is what makes mid-run forking work; pinning a boundary there would silently drop the live response. Forbidden on provider-subagent (read-only) panes. Code: useForkAgent (packages/app/src/hooks/use-fork-agent.ts), selectForkContextRows (packages/server/src/server/agent/activity-curator.ts). Don't confuse with: git fork (unrelated; Paseo has no such concept), Worktree (filesystem isolation, not history copying).
• 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).
• Product discussion — Where non-bug product talk goes: GitHub Discussions and #product in Discord. Covers workflows, features, and product direction. The container term; the ask inside it is always a workflow — what you're doing, how you do it today, where Paseo gets in the way. Issues are bugs only. Forbidden: "Feature request" as a Paseo surface, label, or invitation; the phrase is only used when answering someone who arrived with it. Don't invent "feature discussion", "idea", or "workflow thread" as synonyms. See CONTRIBUTING.md.

Inconsistencies (documented, not papered over)

• 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).