# Workspace This spec defines the behavior of the core workspace — what things do, not how they look. For visual specs (tokens, typography, component CSS), see `design.md`. The thinking block is the exception: its product intent and high-level behavior live in `product-spec/thinking-block.md`, while the concrete implementation lives in `reference/workspace.html`. --- ## Key Concepts ### Workspace Each user has a single workspace — "[Name]'s Workspace." The workspace contains all of the user's agents and opened artifacts in a single list. There is no multi-workspace model; the workspace is a fixed container, not something users create or manage. ### Agents An agent is a conversation thread. It contains user messages, agent responses, execution updates, and result cards. Each agent appears in the sidebar. ### Artifacts Artifacts are outputs the agent produces — dashboards, reports, documents, links. When a user opens an artifact (from a result card), it appears in the sidebar alongside agents. Agents and artifacts share the same list, sorted by recent interaction. --- ## Core User Flow 1. User lands in their workspace 2. User starts an agent describing what they want 3. Agent works and posts execution updates inline 4. Agent returns a result card 5. User opens the result in artifact mode (it appears in the sidebar) 6. User continues iterating --- ## Left Sidebar Width is user-adjustable via a drag handle on the right edge (200–480px, default 280px). The header shows the workspace name (static, not editable) and the user's profile avatar on the right. A thin bottom border anchors the header above the scrollable content. At the top of the scrollable area, a "New agent" button with a "+" icon creates a new conversation. It is styled as a full-width action, clearly labeled, sitting above the item list. Below the button, a single unified list holds both agent conversations and opened artifacts, sorted by recent interaction (most recent at top). Items only move to the top when interacted with (e.g., typing in the chat, clicking inside the workspace, or staying on the item for more than 5 seconds), rather than moving simply by clicking the item in the sidebar. Agents and artifacts are visually distinct. Every item has a type icon on the left: agents show a robot icon, while artifacts show their content type (app, doc, link). The icon makes both types instantly identifiable at a glance. Agent items with active work display a spinner after the name; when work completes and the user hasn't viewed the conversation, a small unread dot replaces the spinner. The dot clears when the user opens the conversation. Artifacts appear in the sidebar when the user opens them from a result card. Clicking an artifact item reopens it in artifact mode. All interactive items display a clear hover state. Spacing is generous to keep the list calm and scannable. --- ## Chat Mode The active conversation with a sticky composer at the bottom. The conversation content area is centered at max-width 720px with equal padding on both sides. Messages anchor to the bottom of the view — when history is short, content sits near the composer with no excessive whitespace above. The composer sits at the bottom as a rounded bordered container. It auto-grows with content up to roughly seven lines, then becomes scrollable. Switching to any chat autofocuses the composer so the user can start typing immediately. User messages are right-aligned with a subtle light grey background and rounded corners. Agent messages are left-aligned with no background. Neither side needs a label — alignment and styling are sufficient to distinguish speakers. All message text auto-wraps to fit the conversation width, including long unbroken strings. The conversation timeline also contains execution updates and result cards. --- ## Artifact Mode A focused view of a selected output (app, link, doc, file, report, or workflow). Always includes a clear back action. The artifact header shows a chevron-left back button and the artifact title. No divider, no label text — the icon is universally understood. --- ## Execution Updates A transient thinking block appears inline while the agent works. Its product intent and high-level behavior are defined in `product-spec/thinking-block.md`. Concrete implementation details live in `reference/workspace.html`. This file should only describe how the thinking block fits into the workspace. Within the workspace, it appears when the agent begins working, exits when the agent's text response begins rendering, and leaves no persistent execution history in the conversation after completion. --- ## Result Cards Richer than execution updates but still visually restrained. Inline summaries of completed outputs, visually distinct from both execution updates and agent responses. Result cards contain a title and description. Clicking the card opens it in artifact mode and adds the artifact to the sidebar list (sorted by recent interaction alongside agents). --- ## User Profile The profile avatar in the sidebar header toggles the profile panel. Clicking it once opens the profile as an overlay in the workspace panel; clicking it again closes it. The sidebar stays visible, keeping the user grounded in the workspace. The profile is a single scrollable page. Sections in order: 1. **Header** — Avatar with initials, user name, email. 2. **Credits** — Two large numbers side by side: remaining and spent. 3. **Recent Activity** — Compact transaction list. Each row shows date, description, and amount. Credits (purchases) use primary text; debits use tertiary. 4. **Subscription** — Current plan name, price, next billing date, and a "Manage subscription" action that navigates to the subscription page. 5. **Log out** — Text button at the bottom, separated by a divider. Switching chats, opening an artifact, or pressing Escape automatically closes the profile. --- ## Empty State New users land in their workspace ("[Name]'s Workspace") with the empty chat view, ready to start their first conversation. No onboarding steps required — they can begin immediately. The placeholder text in the input is enough to invite action. --- ## Text Input Behavior The chat composer and the new chat input share the same pattern: a rounded bordered container with an auto-growing textarea and a small bottom toolbar. The textarea autofocuses with a blinking cursor. It grows with content up to roughly seven lines, then becomes scrollable. Enter creates new lines. ⌘Enter sends. The toolbar sits below the textarea. An attach button (+ icon) sits on the left. A circular action button sits on the right and is always visible. It serves two roles: send (up-arrow icon) by default, and stop (square icon) during agent execution. Clicking stop restores the last sent message to the composer for editing. Both states use the same dark filled circle so the action is always unmistakable. Attached files appear as compact chips above the textarea. Each chip shows the filename and a remove (×) button. There is no file preview. --- ## Keyboard Shortcuts | Shortcut | Action | |----------|--------| | ⌘K | Open command palette (search/jump to chats, run actions) | | ⌘Enter | Send message (in composer or new chat input) | | Escape | Close the topmost overlay (command palette, artifact, profile, menus) | The command palette is a centered modal with a search input. It lists available actions (New chat, Profile) and all existing chats. Results filter as the user types. Arrow keys navigate the list, Enter selects. --- ## Discoverability Hidden interactions are surfaced through progressive affordances: - **Timestamps**: The most recent message shows its timestamp inline. --- ## Error States Errors are communicated directly and without alarm. The interface uses clear copy, distinct icons, and actionable next steps to convey failure. Every error state offers a path forward. ### Execution Failure The thinking block exits according to `product-spec/thinking-block.md`. The agent posts a response acknowledging the failure in plain language: what happened, why, and what the user can do about it. There is no retry button. The conversation is the recovery mechanism — the user tells the agent what to do next. ### Message Send Failure If a user message fails to send (network issue, server error): - The message remains visible at reduced opacity. - A small hint appears below: "Couldn't send · Retry". - Clicking "Retry" re-sends the message. On success, the message returns to full opacity and the agent begins processing. Failed messages do not trigger thinking blocks or agent responses until successfully sent. ### Connection Loss When the connection to the server drops: - A thin banner appears at the top of the workspace: "Connection lost. Reconnecting..." with a pulsing indicator. - The composer remains active — the user can keep typing. - When the connection returns, the banner briefly shows "Reconnected" then fades out. - If reconnection takes more than 30 seconds, the banner updates to: "Still trying to reconnect..." The connection banner never blocks interaction. The workspace stays usable in a degraded state.