stagent 0.3.1 → 0.3.3

package/dist/cli.js

@@ -495,6 +495,7 @@ function markAllMigrationsApplied(sqlite2, migrationsFolder, migrationsTable = "
 // bin/cli.ts
 var __dirname = dirname2(fileURLToPath(import.meta.url));
 var appDir = join3(__dirname, "..");
+var launchCwd = process.cwd();
 var DATA_DIR = getStagentDataDir();
 var dbPath = getStagentDbPath();
 var pkg = JSON.parse(readFileSync(join3(appDir, "package.json"), "utf-8"));
@@ -621,6 +622,7 @@ async function main() {
     env: {
       ...process.env,
       STAGENT_DATA_DIR: DATA_DIR,
+      STAGENT_LAUNCH_CWD: launchCwd,
       PORT: String(actualPort)
     }
   });

package/docs/.last-generated

@@ -0,0 +1 @@
+2026-03-22T20:46:49Z

package/docs/features/agent-intelligence.md

@@ -0,0 +1,60 @@
+---
+title: "Agent Intelligence"
+category: "feature-reference"
+section: "agent-intelligence"
+route: "cross-cutting"
+tags: [ai-assist, routing, autonomous, swarm, self-improvement, context, parallel]
+features: ["task-definition-ai", "multi-agent-routing", "autonomous-loop-execution", "multi-agent-swarm", "agent-self-improvement", "workflow-context-batching", "parallel-research-fork-join"]
+screengrabCount: 0
+lastUpdated: "2026-03-21"
+---
+
+# Agent Intelligence
+
+Stagent layers several AI-powered capabilities on top of basic task execution. From one-click description improvement to multi-agent coordination, these features reduce manual effort and improve output quality across the workspace.
+
+## Screenshots
+
+## Key Features
+
+### Task Definition AI Assist
+
+A single-click "AI Assist" button on the task creation form takes the current title and generates a richer, more actionable description. The improved text is previewed before applying, so the user retains full control.
+
+### Multi-Agent Routing
+
+When a task is created, the task classifier analyzes its content and automatically selects the best-fit agent profile from the registry (General, Code Reviewer, Researcher, Document Writer). The selected profile can be overridden manually via the profile dropdown. Routing logic lives in `src/lib/agents/profiles/`.
+
+### Autonomous Loop Execution
+
+Tasks can run in autonomous loops with configurable stop conditions:
+
+- **Iteration limit** — stop after N iterations.
+- **Time limit** — stop after a duration elapses.
+- **Success criteria** — stop when the agent reports completion.
+- **Error threshold** — stop after repeated failures.
+
+Loops support pause and resume. The `LoopStatusView` component provides real-time progress and control.
+
+### Multi-Agent Swarm
+
+For complex tasks that benefit from multiple perspectives, the swarm feature coordinates several agents working concurrently. Each agent operates within its assigned profile, and results are aggregated upon completion.
+
+### Agent Self-Improvement
+
+Agents accumulate learned context across iterations, stored in the `learned_context` table. This context feeds back into subsequent runs, allowing agents to refine their approach over time without manual prompt tuning.
+
+### Workflow Context Batching
+
+In multi-step workflows, context from earlier steps is batched and forwarded to downstream steps. This prevents information loss across the workflow and ensures each step has the full picture of prior results.
+
+### Parallel Research Fork-Join
+
+Research tasks can be forked into concurrent sub-tasks that investigate different angles simultaneously. Results are joined when all branches complete, producing a consolidated output that covers more ground than sequential execution.
+
+## Related
+
+- [Provider Runtimes](./provider-runtimes.md)
+- [Profiles](./profiles.md)
+- [Workflows](./workflows.md)
+- [Schedules](./schedules.md)

package/docs/features/chat.md

@@ -0,0 +1,119 @@
+---
+title: "Chat"
+category: "feature-reference"
+section: "chat"
+route: "/chat"
+tags: ["chat", "conversations", "ai", "model-selection", "suggested-prompts", "quick-access", "streaming"]
+features: ["chat-data-layer", "chat-engine", "chat-api-routes", "chat-ui-shell", "chat-message-rendering", "chat-input-composer"]
+screengrabCount: 5
+lastUpdated: "2026-03-22"
+---
+
+# Chat
+
+The Chat page is your conversational AI interface for managing and exploring your Stagent workspace. Ask questions about your projects, tasks, workflows, and documents — the assistant understands your setup and responds with context-aware answers, complete with direct links to the entities it mentions.
+
+## Screenshots
+
+![Chat empty state](../screengrabs/chat-list.png)
+*Empty state with hero heading, suggested prompt categories, and conversation sidebar*
+
+![Active conversation](../screengrabs/chat-conversation.png)
+*Active conversation showing streamed responses with Quick Access navigation pills*
+
+![Model selector](../screengrabs/chat-model-selector.png)
+*Model selector dropdown showing available models grouped by provider with cost tiers*
+
+![Suggested prompts — Create tab](../screengrabs/chat-create-tab.png)
+*Suggested prompts with the Create tab selected, showing context-aware prompt suggestions*
+
+![Quick Access pills](../screengrabs/chat-quick-access.png)
+*Quick Access navigation pill linking directly to a mentioned task*
+
+## Key Features
+
+### Conversations
+
+Every chat starts a new conversation that is saved automatically. Your conversation history appears in the left sidebar, sorted by most recent. Click any past conversation to pick up where you left off. You can rename, archive, or delete conversations from the context menu.
+
+On mobile and tablet, the conversation list is tucked behind a menu icon and slides in as an overlay so the message area gets full screen space.
+
+### Model Selection
+
+Choose which AI model powers your conversation using the model selector at the bottom of the input area. Models are grouped by provider with clear cost and capability labels:
+
+- **Haiku 4.5** — Fast responses at the lowest cost ($). The default choice for everyday questions.
+- **Sonnet 4.6** — A balance of speed and depth ($$). Good for nuanced analysis.
+- **Opus 4.6** — The most capable model ($$$). Best for complex reasoning and detailed answers.
+- **GPT-4o-mini** — Fast alternative ($). Available when the Codex runtime is connected.
+- **GPT-4o** — Balanced alternative ($$). Available when the Codex runtime is connected.
+
+Your preferred default model can be set in the Settings page under "Chat default model." The selection persists per conversation, so switching models mid-conversation is seamless.
+
+### Suggested Prompts
+
+When you open Chat with no active conversation, the hero area displays a grid of suggested prompts organized into tabbed categories. These prompts are generated from your actual workspace data:
+
+- **Project-aware** — "What's the status of [your project name]?"
+- **Task-aware** — "Why did [a recently failed task] fail?"
+- **Document-aware** — "Summarize [a recent document]"
+- **System** — "What can you help me with?"
+
+Click any suggestion to insert it into the input and start a conversation instantly.
+
+### Quick Access Navigation Pills
+
+When the assistant mentions a project, task, workflow, document, or schedule in its response, navigation pills appear at the bottom of the message bubble after streaming completes. Each pill shows an icon and label — click it to jump directly to that entity's page. This turns the chat into a workspace control plane: ask a question, then navigate to the relevant item in one click.
+
+### Entity Management via Chat
+
+The assistant understands your Stagent workspace — your projects, tasks, workflows, documents, and schedules. You can ask about statuses, request summaries, or get recommendations, and the assistant draws from your actual data to answer. The progressive context system loads relevant workspace information automatically so you don't need to explain your setup.
+
+### Streaming Responses
+
+Responses stream in token by token with a blinking cursor, so you see the answer forming in real time. A "Thinking..." indicator appears before the first token arrives. Markdown formatting — headings, lists, code blocks with syntax highlighting, tables, and links — renders as the text streams in. Code blocks include a copy button and language label for easy reference.
+
+## How To
+
+### Start a Conversation
+
+1. Click **Chat** in the sidebar (under the Work section).
+2. Type your question in the input area at the bottom, or click a suggested prompt.
+3. Press **Enter** to send. The assistant's response streams in immediately.
+
+### Switch Models
+
+1. Click the model selector to the left of the input area (it shows the current model name).
+2. Choose a different model from the dropdown. Models are labeled with cost tiers ($, $$, $$$).
+3. Your next message will use the selected model. The choice is saved for this conversation.
+
+### Use Suggested Prompts
+
+1. On the Chat page with no active conversation, browse the suggested prompt categories.
+2. Click a prompt to insert it into the input area.
+3. Edit the prompt text if needed, then press **Enter** to send.
+
+### Navigate to Entities from Chat
+
+1. Ask the assistant about a project, task, or other workspace item.
+2. After the response finishes streaming, look for the Quick Access pills at the bottom of the message.
+3. Click a pill to navigate directly to that entity's detail page.
+
+### Manage Conversations
+
+1. Right-click (or long-press on mobile) a conversation in the sidebar to rename, archive, or delete it.
+2. Click "New Chat" at the top of the conversation list to start a fresh conversation.
+3. Archived conversations can be restored from the conversation list filters.
+
+### Stop a Response
+
+1. While a response is streaming, the Send button changes to a Stop button (square icon).
+2. Click Stop to cancel the response. The partial text is preserved in the conversation.
+
+## Related
+
+- [Dashboard Kanban](./dashboard-kanban.md) — manage the tasks your chat assistant references
+- [Profiles](./profiles.md) — agent profiles that shape task execution behavior
+- [Projects](./projects.md) — the projects that provide context to your chat conversations
+- [Documents](./documents.md) — documents the assistant can summarize and reference
+- [Settings](./settings.md) — configure your default chat model and other preferences

package/docs/features/cost-usage.md

@@ -0,0 +1,61 @@
+---
+title: "Cost & Usage"
+category: "feature-reference"
+section: "cost-usage"
+route: "/costs"
+tags: [costs, usage, budget, metering, tokens, spend, guardrails]
+features: ["cost-and-usage-dashboard", "usage-metering-ledger", "spend-budget-guardrails"]
+screengrabCount: 1
+lastUpdated: "2026-03-21"
+---
+
+# Cost & Usage
+
+Track spend across providers and monitor token consumption with the cost and usage dashboard. The usage metering ledger records every token used by task, project, and provider, while budget guardrails enforce configurable spend caps to prevent runaway costs. Visual meters give you an at-a-glance view of current spend versus your configured budget.
+
+## Screenshots
+
+![Cost and usage dashboard with spend breakdown](../screengrabs/cost-usage-list.png)
+*The cost and usage dashboard showing spend metrics, provider breakdown, and budget pacing indicators.*
+
+## Key Features
+
+### Spend Dashboard
+The cost dashboard provides an overview of total spend across all provider runtimes. Key metrics include total spend to date, current period spend, and trend indicators showing whether costs are increasing or decreasing relative to prior periods.
+
+### Usage Metering Ledger
+Every agent execution records token consumption in the usage ledger. The ledger tracks input tokens, output tokens, and total tokens broken down by individual task, parent project, and provider runtime. This granular data enables precise cost attribution and optimization.
+
+### Provider Breakdown
+Spend is segmented by provider runtime, showing separate cost totals for Claude (Agent SDK) and Codex (App Server). The breakdown helps you understand which provider is driving costs and make informed decisions about runtime selection.
+
+### Budget Guardrails
+Configure spend caps to prevent unexpected cost overruns. Set an overall budget limit and monthly allocation splits. When spend approaches the cap, alerts notify you before the limit is reached. Once the cap is hit, guardrails can pause new executions to prevent further charges.
+
+### Visual Budget Meters
+Progress bars and visual meters display current spend relative to your configured budget. Color-coded indicators shift from green to yellow to red as spend approaches the cap, providing immediate visual feedback on budget health.
+
+## How To
+
+### Review Current Spend
+1. Navigate to `/costs` from the sidebar under the **Configure** group.
+2. View the total spend summary at the top of the dashboard.
+3. Check the provider breakdown to see Claude vs. Codex spend.
+4. Review the visual meters for budget pacing.
+
+### Set a Budget Cap
+1. Navigate to `/settings` and open the **Budget** section.
+2. Enter an overall spend cap amount.
+3. Configure the monthly split to distribute the budget across the billing period.
+4. Save the settings. The budget meters on the cost dashboard will reflect the new cap.
+
+### Investigate High Spend
+1. Open the cost dashboard at `/costs`.
+2. Identify which provider or project is contributing the most spend.
+3. Drill into the usage ledger to find high-token-count tasks.
+4. Consider switching to a different provider runtime or adjusting task prompts to reduce token usage.
+
+## Related
+- [Settings](./settings.md)
+- [Monitoring](./monitoring.md)
+- [Schedules](./schedules.md)

package/docs/features/dashboard-kanban.md

@@ -0,0 +1,73 @@
+---
+title: "Dashboard Kanban"
+category: "feature-reference"
+section: "dashboard-kanban"
+route: "/dashboard"
+tags: [tasks, kanban, board, table, filter, create, ai-assist, drag-and-drop]
+features: ["task-board", "kanban-board-operations", "micro-visualizations", "task-definition-ai", "detail-view-redesign", "ui-density-refinement"]
+screengrabCount: 2
+lastUpdated: "2026-03-21"
+---
+
+# Dashboard Kanban
+
+The Dashboard is your primary task management surface. It presents all tasks as a Kanban board with drag-and-drop columns, or as a sortable table — whichever fits your workflow. A powerful filter bar, AI-assisted task creation, and inline editing let you manage agent work without switching context.
+
+## Screenshots
+
+![Dashboard board view](../screengrabs/dashboard-list.png)
+*Kanban board with columns for Planned, Queued, Running, Completed, and Failed tasks*
+
+![Dashboard table view](../screengrabs/dashboard-table.png)
+*Table view with sortable columns for title, status, priority, project, and timestamps*
+
+## Key Features
+
+### Kanban Board
+Tasks are organized into five columns — Planned, Queued, Running, Completed, and Failed. Each column shows a count of its tasks. Cards display the task title, priority badge, and quick-action buttons for editing and deleting.
+
+### Drag-and-Drop Reordering
+Drag task cards between columns to change their status, or within a column to reorder priority. The board updates the database in real time as you drop cards.
+
+### Board and Table Toggle
+Switch between the visual Kanban board and a dense table view using the toggle in the toolbar. The table view provides sortable columns for title, status, priority, project, and timestamps — ideal for bulk review.
+
+### Filter Bar
+Combobox filters for project, status, and priority let you narrow the board or table to exactly the tasks you care about. Filters persist across view toggles.
+
+### AI-Assisted Task Creation
+The task creation form at `/tasks/new` includes fields for title, description, project, priority, runtime, and agent profile. The AI Assist button analyzes your title and description, then enhances them with structured context, acceptance criteria, and suggested parameters.
+
+### Task Detail View
+Click any task card to open a detail panel with the full description, execution logs, status history, and action buttons. Edit the task inline or trigger execution directly from the detail view.
+
+## How To
+
+### Create a New Task
+1. Click the "New Task" button in the dashboard toolbar, or navigate to `/tasks/new`.
+2. Enter a title and description for the task.
+3. Optionally select a project, priority level, runtime, and agent profile.
+4. Click the "AI Assist" button to enhance your description with structured context.
+5. Click "Create Task" to add it to the Planned column.
+
+### Move a Task Between Statuses
+1. In the board view, click and hold a task card.
+2. Drag it to the target column (e.g., from Planned to Queued).
+3. Release to drop — the status updates immediately.
+
+### Filter Tasks
+1. Use the filter bar at the top of the dashboard.
+2. Select a project, status, or priority from the combobox dropdowns.
+3. The board or table updates instantly to show matching tasks.
+4. Clear filters by clicking the reset button.
+
+### Edit a Task
+1. Click the edit icon on any task card, or open the task detail view.
+2. Modify the title, description, priority, or other fields.
+3. Save changes — the card updates across all views.
+
+## Related
+- [Home Workspace](./home-workspace.md)
+- [Projects](./projects.md)
+- [Workflows](./workflows.md)
+- [Profiles](./profiles.md)

package/docs/features/design-system.md

@@ -0,0 +1,73 @@
+---
+title: "Design System — Calm Ops"
+category: "feature-reference"
+section: "design-system"
+route: "cross-cutting"
+tags: [design, tokens, oklch, typography, elevation, components, calm-ops]
+features: ["calm-ops-design-system", "oklch-color-tokens", "shared-component-library"]
+screengrabCount: 0
+lastUpdated: "2026-03-21"
+---
+
+# Design System — Calm Ops
+
+Stagent follows the "Calm Ops" design philosophy: opaque surfaces, border-centric elevation, and zero glass morphism. The system is defined in `design-system/MASTER.md` and implemented through CSS custom properties in `src/app/globals.css`.
+
+## Key Features
+
+### Color System
+
+OKLCH color space with an accent hue of ~250 (indigo/blue-violet). Light-first theme with dark mode support. All color tokens are defined as OKLCH values, ensuring perceptual uniformity across the palette. Forbidden patterns: `rgba()`, `backdrop-filter`, `glass-*`, `gradient-*`.
+
+### Elevation Model
+
+Four elevation levels replace shadow-heavy or glass-based depth cues:
+
+| Level | Usage | Treatment |
+|-------|-------|-----------|
+| `.elevation-0` | Flat / inset content | No shadow, subtle border |
+| `.elevation-1` | Cards, panels | Light border + minimal shadow |
+| `.elevation-2` | Popovers, dropdowns | Medium border + soft shadow |
+| `.elevation-3` | Modals, command palette | Prominent border + deeper shadow |
+
+### Surface Hierarchy
+
+Three surface tiers create visual nesting without transparency:
+
+- **surface-1** — white / raised (cards, panels)
+- **surface-2** — muted (page backgrounds, secondary areas)
+- **surface-3** — inset (code blocks, input fields)
+
+### Typography
+
+- **Body text**: Inter — clean, highly legible at 14px base size.
+- **Monospace**: JetBrains Mono — code blocks, terminal output, status values.
+
+### Spacing
+
+8pt spacing scale via `--space-*` CSS custom properties. All padding, margin, and gap values derive from this scale to maintain consistent rhythm across layouts.
+
+### Border Radius
+
+Maximum radius is `rounded-xl` (12px). Components use `rounded-lg` for interactive cards and `rounded-md` for inputs and buttons.
+
+### Badge Variants
+
+Five status-driven badge variants map to task and workflow states:
+
+| Variant | Status | Color |
+|---------|--------|-------|
+| `default` | Running | Indigo |
+| `success` | Completed | Green |
+| `secondary` | Queued | Gray |
+| `destructive` | Failed | Red |
+| `outline` | Planned | Border only |
+
+### Interactive Cards
+
+All interactive cards implement focus-visible rings for keyboard navigation, `rounded-lg` corners, and keyboard event handlers (Enter/Space to activate).
+
+## Related
+
+- [Shared Components](./shared-components.md)
+- [Keyboard Navigation](./keyboard-navigation.md)

package/docs/features/documents.md

@@ -0,0 +1,76 @@
+---
+title: "Documents"
+category: "feature-reference"
+section: "documents"
+route: "/documents"
+tags: [documents, upload, preprocessing, pdf, office, text-extraction, agent-context]
+features: ["document-manager", "file-attachment-data-layer", "document-preprocessing", "agent-document-context", "document-output-generation"]
+screengrabCount: 2
+lastUpdated: "2026-03-21"
+---
+
+# Documents
+
+The Document Library is where you upload, manage, and organize files that agents can reference during task execution. Stagent automatically preprocesses uploaded files to extract text, making their content available as context for agents without manual copy-pasting.
+
+## Screenshots
+
+![Documents table view](../screengrabs/documents-list.png)
+*Document library in table view showing file name, type, size, and processing status*
+
+![Documents grid view](../screengrabs/documents-grid.png)
+*Grid view displaying document thumbnails and metadata cards*
+
+## Key Features
+
+### Table and Grid Views
+Toggle between a table view for dense scanning (file name, type, size, processing status, timestamps) and a grid view with visual cards. Both views support selection for bulk operations.
+
+### Upload Dialog with Drag-and-Drop
+The upload dialog accepts files via drag-and-drop or file picker. A visual indicator shows supported file types. Multiple files can be uploaded in a single batch.
+
+### Supported File Types
+Stagent processes a range of document formats:
+- **PDF** — Text extraction via pdf-parse.
+- **Text** — Plain text, Markdown, code files.
+- **Images** — Metadata extraction (dimensions, format) via image-size.
+- **Office Documents** — Word documents via mammoth, presentations and archives via jszip.
+- **Spreadsheets** — Excel and CSV files via xlsx parser.
+
+### Automatic Preprocessing
+After upload, Stagent automatically extracts text content from supported file types. The extracted text is stored alongside the original file, ready to be injected into agent context. Processing status is visible on each document card.
+
+### Agent Document Context
+Documents can be attached to tasks. When an agent executes a task with attached documents, the extracted text is included in the agent's context window, giving it direct access to the document content without needing file-system access.
+
+### Document Output Generation
+Agents can generate documents as output during task execution. Generated files are added to the document library automatically, linked back to the originating task.
+
+## How To
+
+### Upload Documents
+1. Navigate to `/documents` and click "Upload."
+2. Drag and drop files into the upload zone, or click to browse.
+3. Select one or more files — supported types are shown in the dialog.
+4. Click "Upload" to start the process.
+5. Preprocessing begins automatically — watch the status indicator on each document.
+
+### Attach Documents to a Task
+1. When creating or editing a task, look for the document attachment field.
+2. Select one or more documents from the library.
+3. The agent will receive the extracted text as part of its context when executing the task.
+
+### Switch Between Views
+1. Use the view toggle at the top of the documents page.
+2. Table view is best for scanning many documents by metadata.
+3. Grid view is best for visual browsing when file types include images.
+
+### Delete Documents
+1. Select one or more documents using the checkboxes.
+2. Click "Delete" to remove them from the library.
+3. Bulk delete is supported for cleaning up multiple files at once.
+
+## Related
+- [Projects](./projects.md)
+- [Dashboard Kanban](./dashboard-kanban.md)
+- [Workflows](./workflows.md)

package/docs/features/home-workspace.md

@@ -0,0 +1,66 @@
+---
+title: "Home Workspace"
+category: "feature-reference"
+section: "home-workspace"
+route: "/"
+tags: [dashboard, home, workspace, navigation, sidebar, trust-tier]
+features: ["homepage-dashboard", "app-shell"]
+screengrabCount: 2
+lastUpdated: "2026-03-21"
+---
+
+# Home Workspace
+
+The Home Workspace is your landing page when you open Stagent. It provides a real-time overview of agent activity, task status, and items that need your attention. The persistent sidebar organizes all workspace areas into three logical groups for quick navigation.
+
+## Screenshots
+
+![Home workspace list view](../screengrabs/home-list.png)
+*Home workspace showing greeting, stat cards, needs attention section, and recent activity*
+
+![Home workspace below the fold](../screengrabs/home-below-fold.png)
+*Scrolled view showing additional recent activity and workspace context*
+
+## Key Features
+
+### At-a-Glance Stat Cards
+Five stat cards at the top of the home page give you an instant pulse on your workspace: tasks currently running, tasks completed today, tasks awaiting your review, active projects, and active workflows. Each card updates in real time as agents execute work.
+
+### Needs Attention Section
+Items requiring human action — such as permission requests, failed tasks, or stalled workflows — surface here automatically. This ensures nothing slips through the cracks when agents need your input.
+
+### Recent Activity Feed
+A chronological feed of the latest events across your workspace: task completions, agent messages, workflow transitions, and document uploads. Gives you context on what happened while you were away.
+
+### Sidebar Navigation
+The sidebar organizes Stagent into three groups:
+- **Work** — Dashboard, Inbox, Projects, Workflows, Documents
+- **Manage** — Monitor, Profiles, Schedules, Cost & Usage
+- **Configure** — Playbook, Settings
+
+### Trust Tier Badge
+A badge in the sidebar footer displays your current trust tier (e.g., Supervised, Semi-Autonomous, Autonomous). This controls the default permission level for agent tool usage across the workspace.
+
+## How To
+
+### Check What Needs Your Attention
+1. Open Stagent — the home workspace loads by default at `/`.
+2. Scan the stat cards for any tasks awaiting review.
+3. Scroll to the "Needs Attention" section for actionable items.
+4. Click any item to navigate directly to the relevant detail view.
+
+### Navigate to a Workspace Area
+1. Use the sidebar on the left to find the area you need.
+2. Work items (Dashboard, Inbox, Projects, Workflows, Documents) are in the top group.
+3. Management tools (Monitor, Profiles, Schedules, Cost & Usage) are in the middle group.
+4. Configuration (Playbook, Settings) is at the bottom.
+
+### Check Your Trust Tier
+1. Look at the sidebar footer for the trust tier badge.
+2. Click the badge to see a popover with details about your current permission level.
+3. To change the trust tier, navigate to Settings.
+
+## Related
+- [Dashboard Kanban](./dashboard-kanban.md)
+- [Inbox Notifications](./inbox-notifications.md)
+- [Settings](./settings.md)

package/docs/features/inbox-notifications.md

@@ -0,0 +1,67 @@
+---
+title: "Inbox & Notifications"
+category: "feature-reference"
+section: "inbox-notifications"
+route: "/inbox"
+tags: [inbox, notifications, permissions, approval, human-in-the-loop, toast]
+features: ["inbox-notifications", "ambient-approval-toast", "content-handling"]
+screengrabCount: 2
+lastUpdated: "2026-03-21"
+---
+
+# Inbox & Notifications
+
+The Inbox is your notification center for all agent activity that needs awareness or action. Notifications range from informational (task completed, agent message) to actionable (permission required). Rich content rendering and progressive disclosure keep the inbox scannable without hiding important details.
+
+## Screenshots
+
+![Inbox list view](../screengrabs/inbox-list.png)
+*Inbox showing notifications grouped by category with unread badges*
+
+![Inbox expanded notification](../screengrabs/inbox-expanded.png)
+*Expanded notification revealing additional context via Show More*
+
+## Key Features
+
+### Notification Categories
+Notifications are categorized by type: task completed, agent message, and permission required. Each category has a distinct visual indicator so you can scan the inbox quickly and focus on what matters.
+
+### Unread Badges
+Unread notifications display a badge count in both the inbox and the sidebar navigation item. Notifications are marked as read when you expand them or take action.
+
+### Progressive Disclosure
+Long notifications start collapsed with a summary. Click "Show More" to expand the full content. This keeps the inbox compact while ensuring no detail is lost.
+
+### Rich Content Rendering
+Notification bodies render Markdown content using ReactMarkdown with GitHub Flavored Markdown (GFM) support. Agent messages can include code blocks, tables, lists, and links — all rendered inline.
+
+### Human-in-the-Loop Approvals
+When an agent requests permission to use a tool, a "Permission Required" notification appears with Approve and Deny buttons. This is the core human-in-the-loop mechanism — you stay in control of what agents can do.
+
+### Ambient Approval Toasts
+For quick permission grants, ambient toasts appear at the edge of the screen. You can approve or deny without navigating to the inbox, keeping your workflow uninterrupted.
+
+## How To
+
+### Review Notifications
+1. Navigate to `/inbox` or click the Inbox item in the sidebar.
+2. Scan the notification list — unread items are visually distinct.
+3. Click a notification to expand its details.
+4. Click "Show More" for long notifications to see the full content.
+
+### Approve or Deny a Permission Request
+1. Look for notifications with the "Permission Required" category.
+2. Expand the notification to see what tool the agent wants to use and why.
+3. Click "Approve" to grant the permission, or "Deny" to reject it.
+4. The agent resumes or halts based on your decision.
+
+### Handle Ambient Toasts
+1. When a toast appears at the screen edge, review the permission request summary.
+2. Click "Approve" or "Deny" directly on the toast.
+3. The toast dismisses automatically after action or timeout.
+
+## Related
+- [Home Workspace](./home-workspace.md)
+- [Dashboard Kanban](./dashboard-kanban.md)
+- [Tool Permissions](./tool-permissions.md)
+- [Settings](./settings.md)