stagent 0.3.1 → 0.3.3

package/docs/features/keyboard-navigation.md

@@ -0,0 +1,62 @@
+---
+title: "Keyboard Navigation"
+category: "feature-reference"
+section: "keyboard-navigation"
+route: "cross-cutting"
+tags: [keyboard, command-palette, accessibility, aria, a11y, navigation]
+features: ["command-palette-enhancement", "accessibility"]
+screengrabCount: 2
+lastUpdated: "2026-03-21"
+---
+
+# Keyboard Navigation
+
+Stagent is designed for keyboard-first operation. The command palette provides instant access to any resource, and all interactive elements support full keyboard navigation with visible focus indicators.
+
+## Screenshots
+
+![Command palette in empty state](../screengrabs/command-palette-empty.png)
+*The command palette (Meta+K) showing recent items and navigation shortcuts.*
+
+![Command palette with search results](../screengrabs/command-palette-search.png)
+*Searching across projects, tasks, and workflows from the command palette.*
+
+## Key Features
+
+### Command Palette
+
+Activated with **Meta+K** (Cmd+K on macOS, Ctrl+K on other platforms), the command palette provides:
+
+- **Recent items** — quick access to recently viewed projects, tasks, and workflows.
+- **Cross-entity search** — type to search across projects, tasks, workflows, documents, and schedules in a single unified list.
+- **Keyboard navigation** — arrow keys to browse results, Enter to select, Escape to dismiss.
+- **Action shortcuts** — create new tasks, projects, or workflows directly from the palette.
+
+### Focus-Visible Rings
+
+All interactive cards, buttons, and links display a visible focus ring when navigated via keyboard (`:focus-visible`). The ring uses the accent color at reduced opacity to remain visible without being distracting.
+
+### Skip-to-Content Link
+
+A hidden skip link appears on Tab press, allowing keyboard users to bypass the sidebar and jump directly to the main content area.
+
+### ARIA Labels
+
+All interactive elements carry descriptive ARIA labels. Status badges include `aria-label` text that reads the status aloud (e.g., "Status: completed"). Icon-only buttons have accessible names.
+
+### Kanban Keyboard Drag-and-Drop
+
+Kanban board cards support full keyboard-driven reordering:
+
+1. **Space** — pick up the focused card.
+2. **Arrow keys** — move the card between columns or positions.
+3. **Space** — drop the card in its new position.
+4. **Escape** — cancel the drag and return the card to its original position.
+
+A live region announces the card's current position during the drag operation for screen reader users.
+
+## Related
+
+- [Design System](./design-system.md)
+- [Dashboard & Kanban](./dashboard-kanban.md)
+- [Shared Components](./shared-components.md)

package/docs/features/monitoring.md

@@ -0,0 +1,59 @@
+---
+title: "Monitoring"
+category: "feature-reference"
+section: "monitoring"
+route: "/monitor"
+tags: [monitoring, agent-logs, activity, real-time, execution]
+features: ["monitoring-dashboard"]
+screengrabCount: 1
+lastUpdated: "2026-03-21"
+---
+
+# Monitoring
+
+Real-time agent activity monitoring for all running tasks in your workspace. The monitoring dashboard provides a live view of agent logs with timestamps, task associations, and status indicators, giving you full visibility into what your agents are doing at any moment.
+
+## Screenshots
+
+![Monitoring dashboard showing agent activity logs](../screengrabs/monitor-list.png)
+*The monitoring dashboard displays a chronological feed of agent activity with status indicators and task associations.*
+
+## Key Features
+
+### Real-Time Activity Feed
+The monitoring dashboard streams agent log entries as they happen. Each log entry includes a timestamp, the associated task name, the agent profile performing the work, and a status indicator showing whether the operation succeeded, failed, or is still in progress.
+
+### Task Association Tracking
+Every log entry is linked to its parent task, making it easy to trace agent activity back to the work item that triggered it. Click any task reference to jump directly to the task detail view.
+
+### Status Indicators
+Visual status badges distinguish between different activity states: running operations appear with an active indicator, completed work shows a success badge, and errors are highlighted with a destructive badge for immediate visibility.
+
+### Execution Progress Monitoring
+Track the progress of long-running agent executions across all active tasks. The dashboard aggregates activity from every running agent, providing a single pane of glass for workspace-wide oversight.
+
+### Error Detection
+Failed operations and agent errors surface prominently in the activity feed. Error entries include the error message and context, enabling quick diagnosis without needing to dig into individual task logs.
+
+## How To
+
+### Monitor Active Agents
+1. Navigate to `/monitor` from the sidebar under the **Manage** group.
+2. The activity feed loads automatically with the most recent log entries.
+3. New entries appear at the top of the feed in real time as agents execute tasks.
+
+### Investigate an Error
+1. Look for log entries with a destructive (red) status badge in the activity feed.
+2. Read the error message displayed in the log entry detail.
+3. Click the associated task name to navigate to the full task detail view.
+4. Review the complete execution log for additional context.
+
+### Filter by Task
+1. Open the monitoring dashboard at `/monitor`.
+2. Use the task association links to identify activity related to a specific task.
+3. Click through to the task detail page for the complete execution history of that task.
+
+## Related
+- [Dashboard & Kanban](./dashboard-kanban.md)
+- [Cost & Usage](./cost-usage.md)
+- [Inbox & Notifications](./inbox-notifications.md)

package/docs/features/playbook.md

@@ -0,0 +1,57 @@
+---
+title: "Playbook"
+category: "feature-reference"
+section: "playbook"
+route: "/playbook"
+tags: [playbook, documentation, guides, reference, articles]
+features: ["playbook-documentation"]
+screengrabCount: 1
+lastUpdated: "2026-03-21"
+---
+
+# Playbook
+
+Built-in documentation system that surfaces product guides and feature reference articles directly within the Stagent workspace. Playbook articles are generated from feature specs and screengrabs, giving users browsable, searchable documentation without leaving the app. Articles are organized by section for easy discovery.
+
+## Screenshots
+
+![Playbook article list with sections](../screengrabs/playbook-list.png)
+*The playbook page displaying a list of documentation articles organized by section with search capability.*
+
+## Key Features
+
+### In-App Documentation
+The playbook embeds product documentation directly into the Stagent interface. Users can read feature guides, reference articles, and how-to instructions without switching to an external docs site or wiki.
+
+### Feature Reference Articles
+Each article covers a specific feature area with an overview, screenshots, key features, step-by-step instructions, and links to related articles. Articles are generated from structured feature specs and include annotated screengrabs for visual context.
+
+### Section Organization
+Articles are grouped into logical sections that mirror the application's navigation structure. Sections such as workspace, tasks, workflows, documents, agents, automation, and configuration make it easy to find documentation relevant to the feature you are using.
+
+### Search Capability
+A search function lets you find articles by keyword across all playbook content. Search matches against article titles, tags, and body text to surface relevant documentation quickly.
+
+## How To
+
+### Browse Documentation
+1. Navigate to `/playbook` from the sidebar.
+2. Scroll through the article list to see all available documentation.
+3. Articles are organized by section for logical grouping.
+4. Click any article title to open the full article view.
+
+### Search for a Topic
+1. Open the playbook at `/playbook`.
+2. Use the search field to enter keywords related to your question.
+3. Results filter in real time as you type.
+4. Click a matching article to read the full documentation.
+
+### Find Related Features
+1. Open any playbook article.
+2. Scroll to the **Related** section at the bottom.
+3. Click related article links to navigate to documentation for connected features.
+
+## Related
+- [Home & Workspace](./home-workspace.md)
+- [Dashboard & Kanban](./dashboard-kanban.md)
+- [Settings](./settings.md)

package/docs/features/profiles.md

@@ -0,0 +1,57 @@
+---
+title: "Profiles"
+category: "feature-reference"
+section: "profiles"
+route: "/profiles"
+tags: [profiles, agents, routing, multi-agent, catalog, cross-provider]
+features: ["agent-profile-catalog", "multi-agent-routing", "cross-provider-profile-compatibility"]
+screengrabCount: 1
+lastUpdated: "2026-03-21"
+---
+
+# Profiles
+
+Browse and manage 21 specialized agent profiles that define how agents behave when executing tasks. Each profile encapsulates a distinct persona with tailored capabilities, system prompts, and behavioral constraints. Profiles work across providers (Claude and Codex), and the auto-detect router can automatically select the best-fit profile for any given task.
+
+## Screenshots
+
+![Agent profiles catalog showing profile cards](../screengrabs/profiles-list.png)
+*The profiles catalog displays all 21 agent profiles as cards with name, description, and capability indicators.*
+
+## Key Features
+
+### Agent Profile Catalog
+The catalog presents 21 specialized profiles organized as browsable cards: General, Code Reviewer, Data Analyst, DevOps Engineer, Document Writer, Researcher, Project Manager, QA Tester, Technical Writer, Wealth Manager, Health & Fitness Coach, Learning Coach, Travel Planner, Shopping Assistant, API Tester, Launch Copy Chief, Portfolio Review Coach, Pricing QA Analyst, Revenue Operations Analyst, and Sweep. Each card shows the profile name, a description of its specialization, and its core capabilities.
+
+### Multi-Agent Routing
+The task classifier analyzes incoming tasks and routes them to the most appropriate agent profile based on the task description, project context, and required capabilities. Auto-detect mode selects the best-fit profile automatically, while manual mode lets you choose a specific profile for any task.
+
+### Cross-Provider Compatibility
+Profiles are provider-agnostic and work with both Claude (via Agent SDK) and Codex (via App Server). The same profile definition produces consistent behavior regardless of which provider runtime executes the task, ensuring predictable results across your workspace.
+
+### Profile Cards
+Each profile card displays the agent's name, a concise description of its specialization, and the capabilities it brings to task execution. Cards are interactive with keyboard navigation and focus-visible rings following the Calm Ops design system.
+
+## How To
+
+### Browse Available Profiles
+1. Navigate to `/profiles` from the sidebar under the **Manage** group.
+2. Scroll through the catalog to see all 21 available agent profiles.
+3. Read each card's description to understand what the profile specializes in.
+
+### Assign a Profile to a Task
+1. Open a task in the task detail or create a new task.
+2. Locate the **Agent Profile** selector in the task form.
+3. Choose a specific profile from the dropdown, or select **Auto-detect** to let the router choose.
+4. Execute the task. The selected profile's system prompt and behavioral constraints will govern the agent's behavior.
+
+### Use Auto-Detect Routing
+1. When creating or editing a task, set the agent profile to **Auto-detect**.
+2. The task classifier analyzes the task description and project context.
+3. The best-fit profile is selected automatically when the task executes.
+4. Check the agent logs to see which profile was selected and why.
+
+## Related
+- [Agent Intelligence](./agent-intelligence.md)
+- [Settings](./settings.md)
+- [Provider Runtimes](./provider-runtimes.md)

package/docs/features/projects.md

@@ -0,0 +1,67 @@
+---
+title: "Projects"
+category: "feature-reference"
+section: "projects"
+route: "/projects"
+tags: [projects, workspaces, tasks, working-directory, organization]
+features: ["project-management", "detail-view-redesign"]
+screengrabCount: 2
+lastUpdated: "2026-03-21"
+---
+
+# Projects
+
+Projects are workspaces that group related tasks, workflows, and documents under a shared context. Each project can specify a working directory, enabling agents to execute file-system-aware tasks within the correct folder on your machine.
+
+## Screenshots
+
+![Projects list view](../screengrabs/projects-list.png)
+*Project cards showing name, status, and description for each workspace*
+
+![Project detail view](../screengrabs/projects-detail.png)
+*Project detail page with associated tasks, workflows, and documents*
+
+## Key Features
+
+### Project Workspaces
+Each project acts as a container for related work. Tasks, workflows, and documents associated with a project share context, making it easy to organize complex initiatives with multiple agent activities.
+
+### Project Cards
+The project list displays cards with the project name, current status, and a brief description. Cards are interactive — click to navigate to the project detail page.
+
+### Project Detail Page
+The detail page shows everything associated with a project: its tasks (with status), linked workflows, and attached documents. This is your single-pane view of all activity within a project.
+
+### Working Directory
+Each project can specify a local file-system path as its working directory. When agents execute tasks for this project, they resolve file operations relative to this directory. This enables safe, scoped file access without giving agents free rein over your machine.
+
+### Create Project Dialog
+The creation dialog collects a project name, description, and optional working directory. Projects can be created empty and populated with tasks and documents later.
+
+## How To
+
+### Create a New Project
+1. Navigate to `/projects` and click "New Project."
+2. Enter a name and description for the project.
+3. Optionally set a working directory (e.g., `/Users/you/code/my-repo`).
+4. Click "Create" to add the project.
+
+### View Project Details
+1. Click any project card on the projects list page.
+2. The detail page shows all associated tasks, workflows, and documents.
+3. Click any linked item to navigate directly to its detail view.
+
+### Associate Tasks with a Project
+1. When creating or editing a task, select a project from the project dropdown.
+2. The task will appear in the project's detail page under associated tasks.
+3. The agent executing the task will use the project's working directory as its base path.
+
+### Manage Project Status
+1. Open the project detail page.
+2. Update the project status as work progresses (e.g., Active, Completed, Archived).
+3. Status changes are reflected on the project card in the list view.
+
+## Related
+- [Dashboard Kanban](./dashboard-kanban.md)
+- [Workflows](./workflows.md)
+- [Documents](./documents.md)

package/docs/features/provider-runtimes.md

@@ -0,0 +1,49 @@
+---
+title: "Provider Runtimes"
+category: "feature-reference"
+section: "provider-runtimes"
+route: "cross-cutting"
+tags: [claude, codex, runtime, oauth, websocket, mcp, providers]
+features: ["provider-runtime-abstraction", "openai-codex-app-server", "cross-provider-profile-compatibility"]
+screengrabCount: 0
+lastUpdated: "2026-03-21"
+---
+
+# Provider Runtimes
+
+Stagent supports two provider runtimes, allowing tasks and workflows to target either Claude or Codex depending on the use case. Profiles are compatible across providers, so switching runtimes does not require redefining agent behavior. Runtime selection is exposed via dropdown in task and workflow creation forms.
+
+## Key Features
+
+### Provider Runtime Abstraction
+
+A unified interface sits between the task execution layer and the underlying provider. Both runtimes expose the same lifecycle hooks — start, poll, resume, cancel — so the execution manager and workflow engine operate identically regardless of which provider is active.
+
+### Claude Runtime (Agent SDK)
+
+The Claude runtime uses the Anthropic Agent SDK with two authentication modes:
+
+- **OAuth** — uses Max subscription tokens via the OAuth flow (default, no credit burn).
+- **API Key** — uses `ANTHROPIC_API_KEY` from `.env.local` for direct API access.
+
+Capabilities include resumable conversations, human-in-the-loop approvals via the `canUseTool` polling pattern, and MCP (Model Context Protocol) server integration for extended tool use.
+
+### Codex Runtime (App Server)
+
+The Codex runtime connects to the OpenAI Codex App Server over WebSocket using JSON-RPC. Key characteristics:
+
+- **Resumable threads** — long-running tasks persist across reconnections.
+- **WebSocket transport** — low-latency bidirectional communication.
+- **Integration point** — `src/lib/agents/runtime/codex-app-server-client.ts`.
+
+Codex SDK reference documentation is captured at `.claude/reference/developers-openai-com-codex-sdk/`.
+
+### Cross-Provider Profile Compatibility
+
+Agent profiles (General, Code Reviewer, Researcher, Document Writer) are defined independently of the provider runtime. A profile specifies behavioral traits — system prompt, tool preferences, stop conditions — that translate cleanly to either Claude or Codex. Switching the runtime dropdown on a task preserves the selected profile and its configuration.
+
+## Related
+
+- [Agent Intelligence](./agent-intelligence.md)
+- [Profiles](./profiles.md)
+- [Settings](./settings.md)

package/docs/features/schedules.md

@@ -0,0 +1,68 @@
+---
+title: "Schedules"
+category: "feature-reference"
+section: "schedules"
+route: "/schedules"
+tags: [schedules, automation, loops, recurring, intervals, autonomous]
+features: ["scheduled-prompt-loops", "autonomous-loop-execution"]
+screengrabCount: 1
+lastUpdated: "2026-03-21"
+---
+
+# Schedules
+
+Schedule recurring agent tasks with configurable intervals and autonomous loop execution. The scheduler engine manages the full execution lifecycle, running prompts on a cadence you define with preset intervals or custom timing. Autonomous loops add intelligent stop conditions so agents can iterate toward a goal and stop when done.
+
+## Screenshots
+
+![Schedules list showing active and paused schedules](../screengrabs/schedules-list.png)
+*The schedules list displays all configured schedules with their status, interval, next run time, and associated project.*
+
+## Key Features
+
+### Preset Intervals
+Choose from six built-in interval presets for common scheduling patterns: every 5 minutes, 15 minutes, 30 minutes, hourly, every 2 hours, or daily at 9 AM. Presets cover the most common automation cadences without requiring manual configuration.
+
+### Custom Intervals
+Define custom intervals beyond the presets using the interval parser. Specify any duration to match your exact automation needs, from rapid polling to weekly recurring tasks.
+
+### Schedule Configuration
+Each schedule captures a complete execution context: a descriptive name, the execution interval, the prompt to send to the agent, the project context for scoping, the provider runtime (Claude or Codex), and the agent profile that governs behavior.
+
+### Scheduler Engine
+The scheduler engine runs as a background process initialized via the Next.js instrumentation hook. It tracks all active schedules, calculates next run times, triggers executions on cadence, and manages the lifecycle of each schedule through active, paused, and completed states.
+
+### Autonomous Loop Execution
+Autonomous loops extend scheduled execution with intelligent stop conditions. Four stop condition types are available: max iterations (stop after N runs), time limit (stop after a duration), goal achieved (agent determines the objective is met), and error threshold (stop after too many failures). The loop executor passes iteration context between runs so the agent can build on previous results.
+
+### Pause and Resume
+Schedules can be paused and resumed without losing their configuration or execution history. Pausing a schedule suspends future runs while preserving the next-run calculation, so resuming picks up right where it left off.
+
+## How To
+
+### Create a Recurring Schedule
+1. Navigate to `/schedules` from the sidebar under the **Manage** group.
+2. Click the **Create Schedule** button to open the creation form.
+3. Enter a descriptive name for the schedule.
+4. Select an interval from the presets (5min, 15min, 30min, hourly, 2h, daily 9AM) or define a custom interval.
+5. Write the prompt that the agent will execute on each run.
+6. Optionally select a project for context scoping.
+7. Choose the provider runtime and agent profile.
+8. Save the schedule. It begins executing on the configured cadence.
+
+### Set Up an Autonomous Loop
+1. Create a schedule with your desired prompt and interval.
+2. Configure one or more stop conditions: set a max iteration count, a time limit, a goal description, or an error threshold.
+3. Start the schedule. The loop executor passes context from each iteration to the next.
+4. The loop automatically stops when any stop condition is met.
+
+### Pause or Resume a Schedule
+1. Open the schedules list at `/schedules`.
+2. Locate the schedule you want to control.
+3. Click the pause button to suspend future executions, or the resume button to reactivate a paused schedule.
+4. The schedule status updates to reflect the current state.
+
+## Related
+- [Monitoring](./monitoring.md)
+- [Profiles](./profiles.md)
+- [Cost & Usage](./cost-usage.md)

package/docs/features/settings.md

@@ -0,0 +1,85 @@
+---
+title: "Settings"
+category: "feature-reference"
+section: "settings"
+route: "/settings"
+tags: [settings, authentication, budget, permissions, data, providers, oauth, api-key, codex]
+features: ["tool-permission-persistence", "provider-runtime-abstraction", "spend-budget-guardrails", "tool-permission-presets", "openai-codex-app-server"]
+screengrabCount: 4
+lastUpdated: "2026-03-21"
+---
+
+# Settings
+
+Configure authentication, budgets, tool permissions, and data management from a single settings page. Settings supports two provider runtimes -- Claude (Agent SDK with OAuth or API key) and Codex (App Server with WebSocket JSON-RPC) -- along with budget guardrails, permission presets with risk-level badges, and data management tools for clearing or exporting workspace data.
+
+## Screenshots
+
+![Settings page overview with authentication section](../screengrabs/settings-list.png)
+*The settings page showing the authentication section with provider configuration, OAuth vs API key selection, and connection test.*
+
+![Budget settings section](../screengrabs/settings-budget.png)
+*Budget configuration with overall spend cap, monthly split, OAuth billing indicator, and current pacing meter.*
+
+![Permission presets section](../screengrabs/settings-presets.png)
+*Tool permission presets showing Read Only, Git Safe, and Full Auto tiers with risk-level badges.*
+
+![Data management section](../screengrabs/settings-data.png)
+*Data management section with clear data and export options.*
+
+## Key Features
+
+### Authentication
+Configure how Stagent authenticates with provider runtimes. For Claude, choose between OAuth (uses your Max subscription with no additional API charges) and API Key (uses your Anthropic API key from `.env.local`). For Codex, configure the App Server connection endpoint. A connection test button validates that your credentials and endpoints are working.
+
+### Provider Runtime Abstraction
+Two provider runtimes are supported out of the box. Claude uses the Anthropic Agent SDK and supports both OAuth and API key authentication modes. Codex connects via the App Server using WebSocket JSON-RPC for real-time communication. The runtime abstraction means tasks and profiles work identically regardless of which provider executes them.
+
+### Budget Configuration
+Set an overall spend cap to limit total workspace costs. Configure monthly splits to distribute the budget across billing periods. The OAuth billing indicator shows whether the current authentication method incurs API charges. A pacing meter visualizes current spend against the budget, with color-coded status for healthy, warning, and critical spend levels.
+
+### Permission Presets
+Three permission tiers control what tools agents are allowed to use. **Read Only** grants access to file reading and search tools with no write permissions -- the lowest risk tier. **Git Safe** adds version-controlled write operations (file edits, git commits) with moderate risk. **Full Auto** enables all tools including shell commands, network access, and file system writes -- the highest risk tier. Each tier displays a risk badge for clear visibility.
+
+### Tool Permission Persistence
+The "Always Allow" feature remembers tool permission decisions across sessions. When you approve a tool for a given permission tier, the decision is stored in the settings table so agents do not prompt for the same permission again.
+
+### Data Management
+Clear workspace data or export it for backup. The clear data function removes tasks, logs, documents, and other workspace content while preserving settings. Export creates a snapshot of your workspace data for external storage or migration.
+
+## How To
+
+### Configure Claude Authentication
+1. Navigate to `/settings` from the sidebar under the **Configure** group.
+2. In the **Authentication** section, select either **OAuth** or **API Key** for the Claude runtime.
+3. For OAuth, ensure you have an active Claude Max subscription. For API Key, verify that `ANTHROPIC_API_KEY` is set in `.env.local`.
+4. Click **Test Connection** to validate the configuration.
+
+### Set Up Codex Runtime
+1. Open the **Authentication** section in settings.
+2. Locate the Codex App Server configuration.
+3. Enter the WebSocket endpoint for the Codex App Server.
+4. Test the connection to verify connectivity.
+
+### Configure Budget Guardrails
+1. Navigate to the **Budget** section in settings.
+2. Enter the overall spend cap amount.
+3. Set the monthly split to distribute the budget.
+4. Monitor the pacing meter to track spend against the cap.
+5. Alerts will notify you when spend approaches the limit.
+
+### Choose a Permission Preset
+1. Open the **Permission Presets** section in settings.
+2. Review the three tiers: Read Only, Git Safe, and Full Auto.
+3. Note the risk badge on each tier to understand the permission scope.
+4. Select the tier that matches your risk tolerance for agent operations.
+
+### Clear Workspace Data
+1. Scroll to the **Data Management** section in settings.
+2. Click **Clear Data** to remove workspace content (tasks, logs, documents).
+3. Confirm the action. Settings are preserved; only workspace data is cleared.
+
+## Related
+- [Cost & Usage](./cost-usage.md)
+- [Tool Permissions](./tool-permissions.md)
+- [Provider Runtimes](./provider-runtimes.md)

package/docs/features/shared-components.md

@@ -0,0 +1,78 @@
+---
+title: "Shared Components"
+category: "feature-reference"
+section: "shared-components"
+route: "cross-cutting"
+tags: [components, page-shell, detail-pane, status-chip, filter-bar, data-table, reusable]
+features: ["shared-component-library", "page-shell", "detail-pane", "status-chip", "filter-bar", "view-switcher"]
+screengrabCount: 0
+lastUpdated: "2026-03-21"
+---
+
+# Shared Components
+
+Stagent maintains a library of reusable components that enforce layout consistency and reduce duplication across all surfaces. These components implement the Calm Ops design tokens and are used throughout the application.
+
+## Key Features
+
+### PageShell
+
+Unified page layout wrapper used by all detail, create, and edit pages. Provides consistent max-width, padding, and spacing. Accepts a header slot and body content.
+
+**Location**: `src/components/shared/`
+
+### DetailPane
+
+A 420px right-rail panel for viewing and editing entity details without leaving the list view. Slides in from the right with a semi-opaque backdrop. Used on projects, tasks, workflows, and documents surfaces.
+
+### StatusChip
+
+Five status chip families that map to entity lifecycle states. Each chip renders a colored dot indicator alongside the status label. Variants follow the badge color system (indigo/running, green/completed, gray/queued, red/failed, outline/planned).
+
+### FilterBar
+
+Horizontal filter strip placed below page headers. Supports multiple filter types (select, search, date range) and displays an active filter count badge. Filters persist in URL search params for shareable filtered views.
+
+### ViewSwitcher
+
+Toggle between saved view modes on a per-surface basis. Common modes include table view and grid/card view. The active view preference persists in local storage.
+
+### TrustTierBadge
+
+Displayed in the sidebar footer, this badge shows the current tool permission tier (Read Only, Git Safe, Full Auto). Clicking opens a popover with tier details and a link to Settings.
+
+### DataTable
+
+A sortable, paginated table component built on top of shadcn's Table primitives. Supports row selection, bulk actions, and column visibility toggles. Used on documents, schedules, and workflow steps surfaces.
+
+### PageHeader
+
+Renders the page title, optional subtitle, and action buttons (e.g., "New Task", "Upload Document") in a consistent layout across all top-level pages.
+
+### EmptyState
+
+A centered illustration + message component shown when a list or table has no data. Includes a primary action button to help users get started (e.g., "Create your first project").
+
+**Location**: `src/components/shared/empty-state.tsx`
+
+### ErrorState
+
+Displays error messages with a retry action. Used as an error boundary fallback and in API error scenarios.
+
+**Location**: `src/components/shared/error-state.tsx`
+
+### SectionHeading
+
+A styled heading component used to separate logical sections within a page or form. Renders an h2 with consistent font size, weight, and bottom margin.
+
+**Location**: `src/components/shared/section-heading.tsx`
+
+### FormSectionCard
+
+Groups related form fields inside an elevation-1 card with a section title. Used in create and edit forms to visually organize field groups (e.g., "Basic Info", "Configuration", "Schedule").
+
+## Related
+
+- [Design System](./design-system.md)
+- [Keyboard Navigation](./keyboard-navigation.md)
+- [Dashboard & Kanban](./dashboard-kanban.md)

package/docs/features/tool-permissions.md

@@ -0,0 +1,57 @@
+---
+title: "Tool Permissions"
+category: "feature-reference"
+section: "tool-permissions"
+route: "cross-cutting"
+tags: [permissions, trust, safety, approval, human-in-the-loop, presets]
+features: ["tool-permission-persistence", "tool-permission-presets", "ambient-approval-toast"]
+screengrabCount: 1
+lastUpdated: "2026-03-21"
+---
+
+# Tool Permissions
+
+Stagent provides a layered permission system that balances agent autonomy with human oversight. Trust tiers control what tools an agent can invoke, while persistence and ambient approval mechanisms reduce friction for trusted operations.
+
+## Screenshots
+
+![Permission presets in settings](../screengrabs/settings-presets.png)
+*Settings page showing the three trust tier presets — Read Only, Git Safe, and Full Auto.*
+
+## Key Features
+
+### Trust Tier Presets
+
+Three built-in permission tiers provide progressively broader agent access:
+
+- **Read Only** — safe browsing and file reading. No writes, no shell commands.
+- **Git Safe** — read operations plus git commands (status, diff, log, commit). No arbitrary shell execution.
+- **Full Auto** — all tools available, including shell commands and file writes.
+
+Presets are configured in the Settings page and apply globally to all agent executions.
+
+### Trust Tier Badge
+
+The sidebar footer displays a `TrustTierBadge` showing the current permission level at a glance. Clicking the badge opens a popover with details about what the active tier permits.
+
+### Tool Permission Persistence ("Always Allow")
+
+When an agent requests a tool that requires approval, the user can click "Always Allow" to persist that permission. On subsequent runs, the tool is pre-approved without prompting. Persisted permissions are stored in the `settings` table and can be revoked in Settings.
+
+### Permission Pre-Check
+
+Before executing a task, the runtime performs a permission pre-check against the current trust tier and any persisted "Always Allow" entries. Tools that fall within scope proceed automatically; tools outside scope trigger the approval flow.
+
+### Human-in-the-Loop Approval
+
+When a tool request exceeds the current trust tier and has not been persisted, a notification is created in the `notifications` table. The user can approve or deny from the Inbox or from the task detail view, keeping the agent paused until a decision is made.
+
+### Ambient Approval Toast
+
+For quick permission grants without navigating away from the current context, ambient toast notifications appear when an agent requests a tool. The user can approve directly from the toast, maintaining workflow continuity.
+
+## Related
+
+- [Settings](./settings.md)
+- [Inbox & Notifications](./inbox-notifications.md)
+- [Provider Runtimes](./provider-runtimes.md)