chore: sync website translation parent

docs/design.md

@@ -20,7 +20,7 @@ A semantic element used in three or more places is a primitive. One of a kind is
 
 Primitives live in `packages/app/src/components/ui/` and `packages/app/src/components/headers/`. Card and row layout live in `packages/app/src/styles/settings.ts`. Section structure lives in `packages/app/src/screens/settings/settings-section.tsx`.
 
-A pressable styled to look like a button is wrong; the button is `<Button>` (`packages/app/src/components/ui/button.tsx`). A bare `<Text>` styled to look like a section header is wrong; the section header is `<SettingsSection>` (`packages/app/src/screens/settings/settings-section.tsx`). A custom `Modal` for a confirmation is wrong; the confirmation is `confirmDialog` (`packages/app/src/utils/confirm-dialog.ts`). A hand-rolled overflow menu is wrong; the menu is `<DropdownMenu>` (`packages/app/src/components/ui/dropdown-menu.tsx`). A hand-rolled status pill is wrong; the pill is `<StatusBadge>` (`packages/app/src/components/ui/status-badge.tsx`). A circle pinned over a scrolling surface is wrong; the floating action is `<FloatingActionButton>` (`packages/app/src/components/ui/floating-action-button.tsx`), one per surface, and the surface reserves `FLOATING_ACTION_BUTTON_CLEARANCE` below its content so the button never traps the last row.
+A pressable styled to look like a button is wrong; the button is `<Button>` (`packages/app/src/components/ui/button.tsx`). A pressable wrapping an icon is wrong; the icon action is `<ToolbarButton>` (`packages/app/src/components/ui/pane-content-toolbar.tsx`), which owns the hitbox, the rounded `interactionHighlight` fill on hover and press, the compact size, and the tooltip. Rows on a menu surface are `<MenuItem>`, or `<ComposerTrackRow>` in a track panel; other rows are `<PressHighlight>` (`packages/app/src/components/ui/press-highlight.tsx`), which flashes on native the moment a finger lands. A bare `<Text>` styled to look like a section header is wrong; the section header is `<SettingsSection>` (`packages/app/src/screens/settings/settings-section.tsx`). A custom `Modal` for a confirmation is wrong; the confirmation is `confirmDialog` (`packages/app/src/utils/confirm-dialog.ts`). A hand-rolled overflow menu is wrong; the menu is `<DropdownMenu>` (`packages/app/src/components/ui/dropdown-menu.tsx`). A hand-rolled status pill is wrong; the pill is `<StatusBadge>` (`packages/app/src/components/ui/status-badge.tsx`). A circle pinned over a scrolling surface is wrong; the floating action is `<FloatingActionButton>` (`packages/app/src/components/ui/floating-action-button.tsx`), one per surface, and the surface reserves `FLOATING_ACTION_BUTTON_CLEARANCE` below its content so the button never traps the last row.
 
 Before adding a new component, read `components/ui/`. The primitive usually exists.
 
@@ -249,6 +249,7 @@ New status pills use `<StatusBadge>`. Identity, shortcut, and interactive link b
 
 - `fontWeight.medium` on row titles, body text, button labels, badge text, or `<SidebarCallout>` titles. Medium is reserved for the structural-label tier described in §3 — section labels, modal/sheet titles, dense metadata emphasis, and tight action labels. Anything else is `normal`. `<ScreenTitle>` is responsive `400/300` and is never overridden.
 - `<Pressable>` wrapping `<Text>` to make a button. `<Button>` exists.
+- Importing `Pressable` or a `Touchable*` outside `components/ui/`. A raw pressable has no standard press or hover feedback, so every one drifts. `paseo/no-raw-pressable` reports it; the files on its burn-down list in `.oxlintrc.json` may only leave it.
 - Bare `<Text>` for a section header inside settings. `<SettingsSection>` exists.
 - A muted paragraph between a section header and its card. Section-level explanation is the header's `info` tooltip (§7).
 - A "Settings" CTA on a detail page. Detail pages are settings; settings is reached from the sidebar, the host entry, or a row's kebab menu.

docs/explorer-sidebar.md

@@ -11,7 +11,7 @@ contracts.
 
 ## Panel host contract
 
-Every desktop panel registers its supported `PaneHost` values and presentation. Launchers derive
+Every panel registers its supported `PaneHost` values and presentation. Launchers derive
 fixed-target labels and icons from that registration, filter by host, and never substitute one
 panel type for another. Tab moves reject unsupported destinations, and placement resolves only to
 a compatible pane.
@@ -21,7 +21,10 @@ so a pane’s + menu omits each while that pane already contains it. Closing one
 item available again. Other compatible tabs, including agents, terminals, files, and diffs,
 can move between Explorer and main panes.
 Keep panel implementations independent of either shell. `WorkspacePanelHost` owns mounting and
-retention, while each shell owns its tabs, focus, dragging, resizing, and shortcuts.
+retention. The shared Explorer owns its tab rail; its shared frame owns visibility, activity and
+close-gesture lifetime. Platform adapters own resizing and inset geometry.
+The host keeps three recently used tabs plus modified tabs; unmodified tabs beyond that budget
+can remount. Native retained content stays live, while web chat uses its existing deferred Freeze.
 
 ## Sheets
 
@@ -40,11 +43,11 @@ remounts its panel. Revealing a target that already has a sheet uncovers that sh
 ones above it, except ones holding unsaved work, which stay where they are. Opening a sheet as a tab
 dismisses the sheets above it, since the tab would sit under them. The stack is not persisted.
 
-Sheets are modal and cover the whole compact column, header included. A sheet's header is its drag
+Sheets are modal and cover the whole compact workspace, including the header and Explorer. A sheet's header is its drag
 handle, because the panel scrolls on its own and content panning would fight it. Its trailing rail
 holds icon buttons only (`SheetHeaderIconButton`): Open as tab is the full-screen glyph beside
 Close, so the title keeps its width. The sheets present
-from inside the compact column's `SheetHostScope`, so their panels read the navigator and every
+from the shared workspace's `SheetHostScope`, so their panels read the navigator and every
 workspace provider an ordinary pane has without a context bridge
 ([floating-panels.md Gotcha 6](floating-panels.md#gotcha-6--bottom-sheet-refs-are-not-lifecycle-truth)).
 
@@ -56,12 +59,16 @@ the sheet's tab into a pane, and edits the autosave has not started writing are
 ## Explorer sidebar
 
 `packages/app/src/workspace-tabs/explorer-sidebar.ts` owns show, hide, toggle, and view selection.
-On desktop, the shell is rendered outside the workspace split canvas so it divides the full
-workspace, including the header. It has its own persisted width and resize handle. Main-pane splits
+One Explorer host stays beside the center column across compact overlays and docks. Keep its
+providers and gesture roots at the same React position when width or appearance changes. The
+workspace route preserves panel ancestry during appearance updates. Appearance-dependent leaves
+subscribe to theme changes; the file editor reconfigures its existing editor theme compartment.
+Ordinary leaf routes retain the stack appearance policy.
+The shell is outside the workspace split canvas so it divides the full workspace, including the header. It has its own persisted width and resize handle. Main-pane splits
 never read or modify that width.
 
 `packages/app/src/workspace-tabs/open-supporting-view.ts` owns semantic Changes and pull-request
-opens. Compact and wide native layouts select the matching Explorer tab. Desktop Changes opens
+opens. Compact and wide native layouts select the matching workspace tab in Explorer. Desktop Changes opens
 follow the shared diff preference. Desktop pull requests use their Main panel, On the side, or
 Explorer sidebar setting. Automatic PR discovery follows that preference once per workspace without
 interrupting the user's work. Closing the tab opts that workspace out of future automatic opens,
@@ -76,18 +83,37 @@ literal `"explorer"` pane id and `explorerPaneIdByWorkspace` key for compatibili
 
 Explorer uses the shared workspace tab row and ordinary tab context menus. Files and Changes
 hide their close buttons through the panel manifest; close them from the tab context menu.
-Other tabs reveal the close control on hover. The + menu opens compatible panels in the dock and
-omits Agent and terminal profiles. Agents and terminals can still be dragged into Explorer.
+Other tabs reveal the close control on hover. The + menu opens compatible panels in the dock, including Agent and terminal profiles.
+Web also supports dragging agents and terminals into Explorer.
 Bulk-close actions apply only to the dock's tabs. Explorer tabs can be reordered and dragged
 between compatible panes, but the dock cannot be split or maximized. Selecting an Explorer tab
-does not change workspace focus.
+does not change workspace focus. Web dragging shares the workspace drag scope; compact layouts
+accept only reordering inside the source pane.
 
-Cmd+E shows or hides Explorer without changing its selected view. Compact layouts use the combined
-full-screen Explorer overlay for Changes, Files, and pull requests, and close it after a file opens. Compact Changes has no tree rail; its overview is the Jump to file action (`packages/app/src/git/jump-to-file/`), a sheet over the same changed-files tree the desktop rail renders.
-Wide native layouts without pane splits use the same combined content in a resizable inline dock;
-opening a file leaves that dock visible. Both presentations keep their selection in the panel store
-and reuse the layout store's per-workspace Explorer width. They do not create a second Explorer
-lifecycle.
+Cmd+E shows or hides Explorer without changing its selected view. All layouts use the same
+workspace tabs, launcher, and panel host. Below 600 points the shell is the swipeable Explorer
+overlay; at 600 points and above it reserves width beside the workspace. Native docking keeps its
+touch resize handle. Full workspace splits remain a separate web-only capability.
+
+The dock reserves at least 240 points and the workspace 360. App navigation yields when it cannot
+share the remaining width with both. This keeps a portrait tablet from rendering three unusably
+narrow columns; widening restores navigation without changing its saved open state.
+
+Compact panel gestures own overlay visibility; the workspace layout owns its tab selection and
+contents on every platform. Explicit pane destinations bypass compact sheet placement, so choosing
+a panel in Explorer's + menu keeps it there. Ordinary compact file and subagent look-ups still use
+the sheet policy. Resolving an existing main tab reveals center immediately; a new file sheet
+keeps Explorer underneath and closing the sheet uncovers it. Semantic navigation resolves the
+actual destination before revealing it, including deduplicated targets.
+
+Compact overlay selection and saved dock visibility are independent. Folding changes geometry,
+not either mode’s visibility intent. Native workspace retention remains one workspace; web retains
+up to ten with its existing inactive TTL.
+
+PR discovery belongs to the active workspace: split layouts discover while active, and other
+layouts discover while Explorer is active. The rail requests summary status; selected visible PR
+content also requests timeline data. Inactive consumers read cached data without request demand.
+Discovery uses ordinary PR tabs and their existing once-per-workspace close opt-out.
 
 ## Side pane
 

docs/expo-router.md

@@ -157,7 +157,9 @@ a small `withUnistyles` boundary without subscribing the route tree itself to
 every Unistyles runtime update.
 
 Navigators keep their identity across appearance changes. `ThemedStack` remounts
-each screen's content below the native stack when appearance tokens change; a
+each ordinary screen's content below the native stack when appearance tokens change.
+Workspace screens own retained panel lifetimes and update appearance at their
+leaves through `screenOwnedAppearance` ([Explorer](explorer-sidebar.md)). A
 keyed wrapper above a stack remounts the stack itself, and Android crashes when
 that happens while a FragmentManager transaction is running, which settings
 hydration at startup makes likely. A screen that mounts a nested navigator (the

docs/mobile-panels.md

@@ -32,7 +32,9 @@ The UI worklet owns transient motion:
 
 React publishes the active panel only when the canonical target and the UI-thread position agree at
 the final anchor. Retained content never observes gesture previews, progress, or an unsettled target.
-The gesture hosts stay mounted. Native worklets own overlay opacity and pointer events while
+The gesture hosts stay mounted. The Gesture Handler web patch keeps initially disabled hosts
+from capturing paragraph pointers; that capture confines browser selection to its starting paragraph.
+Native worklets own overlay opacity and pointer events while
 React owns settled panel activity and accessibility. Keep hidden native overlays laid out: collapsing
 their scroll ranges makes Android spring retained offsets back to zero during touch cancellation or
 release. Native panel hosts and their dependent draggable lists

docs/plugins.md

@@ -246,8 +246,9 @@ Do not put any other code modules in the plugin root.
 
 Shared files import contract helpers and types from `@getpaseo/plugin`. Server handler files import
 `PluginHandlerContext` from `@getpaseo/plugin/server`. Client files import Paseo UI from
-`@getpaseo/plugin/client/react-native`. Its `Icon` resolves a Lucide name using the client's installed icon
-set; an unknown name renders nothing so it cannot break the plugin surface.
+`@getpaseo/plugin/client/react-native`. Its `Icon` draws a Lucide name from the client's installed
+icon set, or any `PluginIcon` through its `icon` prop; an unknown name or unsafe SVG renders nothing
+so it cannot break the plugin surface.
 Its controlled modal keeps presentation metadata on `<Modal title="…" icon={…}>` and body UI in
 `<Modal.Content>`. Body layout, sheet-aware scrolling, and clipboard actions follow the
 [host UI contract](../public-docs/plugins/reference.md#host-ui).
@@ -338,7 +339,7 @@ created by plugin code. Paseo removes registered contributions, unmounts surface
 state, rejects pending RPCs, closes the plugin's daemon session, and stops the subprocess. Cleanup
 errors are logged and do not interrupt host teardown.
 
-Paseo owns the route, screen header, Lucide icon validation, close action, theme DTO, layout facts,
+Paseo owns the route, screen header, icon validation, close action, theme DTO, layout facts,
 and render error boundary. The contributed component owns the complete body below the header.
 The plugin owns the header's text through the screen's `title` (`resolvePluginScreenTitle` in
 `plugins/surface-contribution.ts`). A legacy `addSidebarItem` route (`/sidebar/<id>`) shows the
@@ -406,6 +407,25 @@ See the public [navigation fields](../public-docs/plugins/reference.md#screens-a
 and [external links and workspace browsers](../public-docs/plugins/reference.md#external-links-and-workspace-browsers)
 for the author-facing contract.
 
+### Plugin icons
+
+The [public reference](../public-docs/plugins/reference.md#icons) owns the author API: a contribution
+`icon` is a Lucide name, `{ svg }`, or a component.
+
+- `findSvgIconProblem` in the SDK root (`packages/plugin/src/icons.ts`) is the only SVG rule set.
+  The daemon applies it to provider and usage-source icon files; the app applies it to inline
+  icons. Change the rules there, never at a call site.
+- The app validates each icon once, at registration, through `parsePluginIcon` in
+  `packages/app/src/plugins/icons.ts`. Rendering trusts the stored icon.
+- That module is the only code that branches on the icon form. Surfaces draw with
+  `PluginIconView`, or take a stable component from `pluginIconComponent` when their slot expects
+  one. Lucide and SVG icons receive only size and color, so the host props a button passes to its
+  component icon never reach an SVG element.
+- Attachment sources take `PluginSerializableIcon`: composer drafts persist the source's icon with
+  each attachment, and a component cannot be stored.
+- The plugin compiler loads `.svg` imports as text, so `import icon from "./client/icon.svg"` is the
+  markup string.
+
 ## Lifecycle hooks
 
 Server entries register lifecycle observers with `server.on()` and request transforms with
@@ -497,15 +517,13 @@ provider implementation. The public [provider plugin guide](../public-docs/plugi
 owns author workflow, lifecycle, testing, and distribution guidance.
 
 `ProviderRegistration.icon` is a file path relative to the plugin directory, such as `icon.svg`.
-It must resolve inside that directory to a regular SVG file no larger than 64 KiB. The SVG must be
-self-contained: scripts, styles, `foreignObject`, event-handler attributes, JavaScript URLs, and
-external `href` or `xlink:href` references are rejected. Fragment references such as `#mark` are
-allowed. Paseo reads and sanitizes the file when the plugin starts; the string is never an inline
-SVG or URL.
+It must resolve inside that directory to a regular file that passes the shared SVG icon rules
+(see [Plugin icons](#plugin-icons)). Paseo reads and validates the file when the plugin starts; the
+string is never inline SVG or a URL.
 
 ## Usage sources
 
-Register a usage source from `index.server.ts` with `server.registerUsageSource()`. Import `UsageSourceRegistration` and normalization helpers from `@getpaseo/plugin/server/usage`. The plugin owns account discovery, harness labels, and credential-store reads; the daemon owns account grouping and the fetch cache. Agent popovers use only the agent's own login. The host-wide Usage modal falls back across an account's logins; any success shows usage only, and all failures show every login's labeled error and remedy. Follow the [usage source discovery contract](../public-docs/plugins/reference.md#usage-sources). The resolved launch environment crosses into the trusted, unsandboxed plugin subprocess for session discovery. Usage queries never run lifecycle hooks. Inputs are validated in the plugin process and remain daemon-side. `icon` uses the same sanitized SVG file rules as provider icons.
+Register a usage source from `index.server.ts` with `server.registerUsageSource()`. Import `UsageSourceRegistration` and normalization helpers from `@getpaseo/plugin/server/usage`. The plugin owns account discovery, harness labels, and credential-store reads; the daemon owns account grouping and the fetch cache. Agent popovers use only the agent's own login. The host-wide Usage modal falls back across an account's logins; any success shows usage only, and all failures show every login's labeled error and remedy. Follow the [usage source discovery contract](../public-docs/plugins/reference.md#usage-sources). The resolved launch environment crosses into the trusted, unsandboxed plugin subprocess for session discovery. Usage queries never run lifecycle hooks. Inputs are validated in the plugin process and remain daemon-side. `icon` uses the same SVG file rules as provider icons.
 
 The daemon calls discovery for `usage.list_reports`; the client gates this RPC on `server_info.features.usageSources`. The old `provider.usage.list` RPC maps discovered reports for older clients.
 

docs/protocol-compatibility.md

@@ -74,6 +74,14 @@ The adapter keys legacy slots by physical socket, so an old connection cannot re
 sibling's observation even when both use the same logical client ID. Optional wire IDs stay accepted
 for parsing compatibility; modern requests cannot select their subscription ID.
 
+Workspace setup details negotiate `workspace_setup_observation` with
+`server_info.features.workspaceSetupObservation`. Capable clients cannot request details through
+the legacy session event category. The setup panel owns a workspace-scoped observation while
+active and visible; directory metadata signals failures without requesting output. Older clients
+retain their legacy event delivery. A new app makes no setup event demand on older hosts and
+requires a host update to view details. Subscription-capable older hosts honor that absence of
+demand; broadcast-era hosts require an update before wire silence is guaranteed.
+
 ## Every shim is tagged and dated
 
 A shim that exists for old-app or old-daemon support carries a comment naming it, the version it arrived in, and when it can go:

docs/providers.md

@@ -95,7 +95,7 @@ Use OpenCode v2 execution events to trigger turn completion, with active-state a
 
 V2.0.4 also removed the activation endpoint that gated a cold location, and a cold location registers its config-derived commands, skills, and providers asynchronously. Wait until `plugin.list` returns a populated inventory before reading the catalog or commands; an empty inventory means the location is still warming. Fail when the readiness deadline expires, including when an inventory request stalls.
 
-Paseo installs its OpenCode tool bridge through `OPENCODE_CONFIG_CONTENT`. V1 accepts a plugin file; v2 silently skips configured files and requires a package directory with a server entry point. Both versions use the daemon's private loopback bridge for caller-scoped tools. Bridge context lives only in daemon memory and is removed when the Paseo session closes. The content-addressed plugin artifacts contain no session data or secrets. V2 also needs this plugin when native Paseo tools are disabled: its prompt API has no structured-output format, so the plugin supplies a schema-validated final-answer tool.
+Paseo installs its OpenCode tool bridge through `OPENCODE_CONFIG_CONTENT`. V1 accepts a plugin file; v2 silently skips configured files and requires a package directory with a server entry point. Both versions use the daemon's private loopback bridge for caller-scoped tools. The global manifest must use agent-scoped schemas before a session is bound, because every bridge call executes in an agent session. Bridge context lives only in daemon memory and is removed when the Paseo session closes. The content-addressed plugin artifacts contain no session data or secrets. V2 also needs this plugin when native Paseo tools are disabled: its prompt API has no structured-output format, so the plugin supplies a schema-validated final-answer tool.
 
 An agent with custom environment variables or user-configured MCP servers gets a dedicated OpenCode server. V2 supports session environment, but its MCP configuration remains location-scoped, so separate servers still prevent one agent from changing another agent's MCP setup. Configure custom MCP with `mcp.add`; do not follow it with `mcp.connect`, which only toggles config-backed servers.
 

docs/testing.md

@@ -193,7 +193,7 @@ Test suites in this repo are heavy. Running them in bulk freezes the machine, es
 - Playwright specs that exercise only the daemon import `daemonTest` from the shared fixtures so they do not create a browser context or page.
 - Helpers that create projects or workspaces own those records until cleanup. Their clients remove the daemon project on close, and an automatic fixture fails any test that still leaks a project record. Deleting only the temporary directory is not cleanup. Agent helpers pass the intended `workspaceId` through to agent creation; they never infer ownership from `cwd`.
 - Tests whose subject is daemon-global state, such as an empty history or daemon restart, start a dedicated host explicitly. Filenames and directories describe product behavior, never execution order or isolation mechanics.
-- Global setup accepts Metro as ready only when `/status` returns `packager-status:running`, then fetches the document's scripts so the cold bundle compilation finishes before Playwright's per-test timeout starts. A generic TCP listener is not sufficient readiness evidence. The browser suite uses direct local daemon connections and does not start a relay.
+- Global setup accepts Metro as ready only when `/status` returns `packager-status:running`, then fetches the document's scripts so the cold bundle compilation finishes before Playwright's per-test timeout starts. A generic TCP listener is not sufficient readiness evidence. The browser suite uses direct local daemon connections and does not start a relay. Automated Metro launches set `EXPO_UNSTABLE_HEADLESS=1` so Expo does not download the native DevTools shell into temporary test homes; its read-only cache breaks teardown. Browser fixtures and the standalone Electron browser runner share the developer-toast dismissal helper while retaining console logs. A pointer click moves hover away from the tested control and stalls behind app modal backdrops.
 - The app Playwright harness boots on Windows as well as POSIX. Spawn Node entrypoints through `process.execPath`, not `npx` or `node_modules/.bin` shims: Node refuses to spawn `.cmd` or `.bat` without `shell: true`, and shell mode concatenates argv without escaping and sends kill signals to `cmd.exe` instead of the real child.
 - Teardown kills the process tree, because a Windows signal reaches only the direct child and leaves forked workers holding the listening port.
 - The `asdf`-backed local Elixir relay stays POSIX-only, so the `relay-deployment` Playwright project is unavailable on Windows.