stagent 0.4.0 → 0.6.0

package/docs/features/chat.md

@@ -3,117 +3,99 @@ 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"
+tags: ["chat", "conversation", "ai", "tool-catalog", "mentions", "channels", "bidirectional"]
+features: ["chat-data-layer", "chat-engine", "chat-api-routes", "chat-ui-shell", "chat-message-rendering", "chat-input-composer", "bidirectional-channel-chat"]
+screengrabCount: 4
+lastUpdated: "2026-03-31"
 ---
 
 # 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.
+The Chat page is your AI-powered command center for everything in your workspace. Instead of a blank prompt, you land on a **Tool Catalog** that organizes suggested prompts into four action-oriented categories -- Explore, Create, Debug, and Automate -- plus a Smart Picks row of personalized suggestions drawn from your actual projects, tasks, and documents. Pick a model, choose a prompt (or type your own), and get context-aware answers with direct links to the items the assistant mentions. Conversations can also originate from Slack and Telegram via bidirectional delivery channels.
 
 ## 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*
+![Chat tool catalog](../screengrabs/chat-list.png)
+*Tool catalog with hero heading, category tabs (Explore / Create / Debug / Automate), Smart Picks row, and conversation sidebar*
 
 ![Model selector](../screengrabs/chat-model-selector.png)
-*Model selector dropdown showing available models grouped by provider with cost tiers*
+*Model selector dropdown showing Claude and Codex models organized 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*
+![Create category tab](../screengrabs/chat-create-tab.png)
+*Create category selected, showing prompts for spinning up tasks, workflows, and projects*
 
-![Quick Access pills](../screengrabs/chat-quick-access.png)
-*Quick Access navigation pill linking directly to a mentioned task*
+![Active conversation](../screengrabs/chat-conversation.png)
+*Active conversation with @ document context injected and streamed response with formatted markdown*
 
 ## Key Features
 
-### Conversations
+### Tool Catalog
 
-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.
+When no conversation is active, the chat page displays a curated grid of suggested prompts organized into tabbed categories:
 
-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.
+- **Explore** -- Questions about your workspace: project statuses, task summaries, schedule overviews.
+- **Create** -- Prompts that help you spin up new tasks, workflows, projects, and schedules.
+- **Debug** -- Investigate failed tasks, review agent logs, and diagnose workflow issues.
+- **Automate** -- Set up scheduled loops, bulk operations, and repeating workflows.
+- **Smart Picks** -- A personalized row of suggestions generated from your actual workspace data.
 
 ### 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.
+Choose which AI model powers your conversation using the model selector at the bottom-left of the input area. Models are grouped by provider with clear cost and capability labels:
 
-### Suggested Prompts
+- **Haiku 4.5** -- Fast responses at the lowest cost ($).
+- **Sonnet 4.6** -- A balance of speed and depth ($$).
+- **Opus 4.6** -- The most capable model ($$$).
+- **GPT-4o-mini** / **GPT-4o** -- Available when the Codex runtime is connected.
+- **Ollama models** -- Available when a local Ollama instance is connected ($0).
 
-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:
+### @ Mentions and Context
 
-- **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?"
+Type **@** in the chat input to reference a specific project, task, workflow, document, profile, or schedule by name. An autocomplete popover appears with fuzzy-searchable results. When you select a mention, the assistant receives the full details of that entity as part of the conversation context.
 
-Click any suggestion to insert it into the input and start a conversation instantly.
+### Conversation Management
 
-### Quick Access Navigation Pills
+Every chat starts a new conversation that is saved automatically. Your conversation history appears in the left sidebar, sorted by most recent. Channel conversations from Slack and Telegram also appear here, titled "Channel: [channel name]," so you can continue them from the web UI.
 
-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.
+### Channel Conversations
 
-### 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.
+When bidirectional chat is enabled on a Slack or Telegram delivery channel, messages sent to Stagent from those platforms create conversations visible in the Chat sidebar. The same chat engine handles both web and channel conversations, including tool access, permission handling, and multi-turn context.
 
 ### 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.
+Responses stream in token by token with a blinking cursor. 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.
 
 ## How To
 
-### Start a Conversation
+### Start a New 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.
+2. Browse the tool catalog categories or type your question in the input area.
+3. Click a suggested prompt to insert it, or type your own message.
+4. Press **Enter** to send. The response streams in immediately.
 
-### Navigate to Entities from Chat
+### Switch AI Models
 
-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.
+1. Click the model selector to the left of the input area.
+2. Choose a different model from the dropdown. Models are labeled with cost tiers.
+3. Your next message will use the selected model.
 
-### Manage Conversations
+### Reference Entities in Chat
 
-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.
+1. Type **@** followed by the name of a document, project, task, or other entity.
+2. An autocomplete popover appears -- use arrow keys or click to select.
+3. The assistant receives the full context of the mentioned entity.
 
-### Stop a Response
+### Chat from Slack or Telegram
 
-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.
+1. Configure a delivery channel with Chat mode enabled (see [Settings](./settings.md)).
+2. Send a message to Stagent from Slack or Telegram.
+3. The conversation appears in the Chat sidebar and can be continued from either platform.
 
 ## 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
+- [Settings](./settings.md) -- Configure default chat model, Ollama, and delivery channels
+- [Documents](./documents.md) -- Documents the assistant can reference via @ mentions
+- [Projects](./projects.md) -- Projects that provide context to conversations
+- [Profiles](./profiles.md) -- Agent profiles that shape how the assistant responds
+- [Delivery Channels](./delivery-channels.md) -- Bidirectional Slack and Telegram integration

package/docs/features/cost-usage.md

@@ -3,21 +3,24 @@ title: "Cost & Usage"
 category: "feature-reference"
 section: "cost-usage"
 route: "/costs"
-tags: [costs, usage, budget, metering, tokens, spend, guardrails]
+tags: [costs, usage, budget, metering, tokens, spend, guardrails, ollama]
 features: ["cost-and-usage-dashboard", "usage-metering-ledger", "spend-budget-guardrails"]
-screengrabCount: 1
-lastUpdated: "2026-03-21"
+screengrabCount: 2
+lastUpdated: "2026-03-31"
 ---
 
 # 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.
+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. Tasks executed via Ollama (local models) are tracked at $0.
 
 ## 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.*
 
+![Cost and usage below fold](../screengrabs/cost-usage-below-fold.png)
+*Detailed usage table and cost trends below the summary cards.*
+
 ## Key Features
 
 ### Spend Dashboard
@@ -27,10 +30,10 @@ The cost dashboard provides an overview of total spend across all provider runti
 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.
+Spend is segmented by provider runtime, showing separate cost totals for Claude (Agent SDK and Direct API), Codex (App Server and Direct API), and Ollama ($0 local). 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.
+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 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.
@@ -38,9 +41,9 @@ Progress bars and visual meters display current spend relative to your configure
 ## How To
 
 ### Review Current Spend
-1. Navigate to `/costs` from the sidebar under the **Configure** group.
+1. Navigate to `/costs` from the sidebar under the **Manage** group.
 2. View the total spend summary at the top of the dashboard.
-3. Check the provider breakdown to see Claude vs. Codex spend.
+3. Check the provider breakdown to see spend by runtime.
 4. Review the visual meters for budget pacing.
 
 ### Set a Budget Cap
@@ -52,10 +55,11 @@ Progress bars and visual meters display current spend relative to your configure
 ### 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.
+3. Scroll down to the usage breakdown table for granular task-level data.
+4. Consider switching to Ollama (local models) for tasks that do not require cloud-level capability, or adjust task prompts to reduce token usage.
 
 ## Related
 - [Settings](./settings.md)
 - [Monitoring](./monitoring.md)
 - [Schedules](./schedules.md)
+- [Provider Runtimes](./provider-runtimes.md)

package/docs/features/dashboard-kanban.md

@@ -3,15 +3,15 @@ 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"
+tags: [tasks, kanban, board, table, filter, create, ai-assist, drag-and-drop, bulk-operations, heartbeat]
+features: ["task-board", "kanban-board-operations", "micro-visualizations", "task-definition-ai", "detail-view-redesign", "ui-density-refinement", "heartbeat-scheduler"]
+screengrabCount: 5
+lastUpdated: "2026-03-31"
 ---
 
 # 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.
+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, bulk operations, and inline editing let you manage agent work without switching context.
 
 ## Screenshots
 
@@ -21,26 +21,41 @@ The Dashboard is your primary task management surface. It presents all tasks as
 ![Dashboard table view](../screengrabs/dashboard-table.png)
 *Table view with sortable columns for title, status, priority, project, and timestamps*
 
+![Task detail sheet](../screengrabs/dashboard-card-detail.png)
+*Task detail sheet showing task properties, description, and execution history*
+
+![Task edit dialog](../screengrabs/dashboard-card-edit.png)
+*Task edit dialog for updating task details from the kanban board*
+
+![Bulk select mode](../screengrabs/dashboard-bulk-select.png)
+*Kanban board in select mode with checked cards and bulk action toolbar*
+
 ## 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.
+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, agent profile, and quick-action buttons for editing and deleting. Heartbeat-generated tasks show a heartbeat badge to distinguish them from manually created work.
 
 ### 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.
+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.
+The task creation form 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.
 
+### Bulk Select Mode
+Enter select mode to check multiple task cards across any column. A toolbar appears with bulk actions: queue selected tasks for execution, move them to a different status, or delete tasks that are no longer needed. This is essential when autonomous workflows or heartbeat schedules generate many tasks overnight.
+
+### Heartbeat Badges
+Tasks created by heartbeat schedules display a heartbeat badge on their kanban card. This visual indicator distinguishes proactively generated work from tasks you created manually, making it easy to audit what your scheduled agents produced.
+
 ## How To
 
 ### Create a New Task
@@ -53,7 +68,7 @@ Click any task card to open a detail panel with the full description, execution
 ### 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.
+3. Release to drop -- the status updates immediately.
 
 ### Filter Tasks
 1. Use the filter bar at the top of the dashboard.
@@ -61,13 +76,15 @@ Click any task card to open a detail panel with the full description, execution
 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.
+### Bulk-Manage Tasks
+1. Click the "Select" button in the toolbar to enter bulk select mode.
+2. Check the boxes on multiple task cards.
+3. Use the bulk action toolbar to queue, move, or delete selected tasks.
+4. Confirm the action and exit select mode.
 
 ## Related
 - [Home Workspace](./home-workspace.md)
 - [Projects](./projects.md)
 - [Workflows](./workflows.md)
 - [Profiles](./profiles.md)
+- [Schedules](./schedules.md)

package/docs/features/delivery-channels.md

@@ -0,0 +1,198 @@
+---
+title: "Delivery Channels"
+category: "feature-reference"
+section: "delivery-channels"
+route: "/settings"
+tags: ["delivery-channels", "slack", "telegram", "webhook", "notifications", "integrations", "bidirectional", "chat"]
+features: ["delivery-channels", "bidirectional-channel-chat"]
+manual: true
+screengrabCount: 0
+lastUpdated: "2026-04-01"
+---
+
+# Delivery Channels
+
+Delivery Channels connect Stagent to external messaging services. Channels support two modes:
+
+- **Outbound** -- Stagent pushes notifications when scheduled tasks fire, complete, or need attention
+- **Bidirectional (Chat)** -- Users can chat with Stagent agents directly from Slack or Telegram, and receive responses in the same conversation
+
+Channels are configured in Settings and can be toggled between outbound-only and bidirectional mode at any time.
+
+## Key Features
+
+### Channel Types
+
+Three adapter types are supported, each requiring different configuration:
+
+| Type | Outbound Config | Bidirectional Config | Best For |
+|------|----------------|---------------------|----------|
+| **Slack** | Incoming Webhook URL | + Bot Token, Signing Secret, Channel ID | Team chat and notifications |
+| **Telegram** | Bot Token + Chat ID | Same (no extra config needed) | Personal AI assistant via messaging |
+| **Webhook** | URL + optional headers | N/A (outbound only) | Custom integrations, Zapier, n8n |
+
+### Bidirectional Chat
+
+When Chat mode is enabled on a Slack or Telegram channel, you can message Stagent directly from your messaging app. Stagent processes your message through the same chat engine used in the web UI, including:
+
+- **Multi-turn conversations** -- context is maintained across messages
+- **Tool access** -- the agent can query projects, tasks, documents, schedules, and more
+- **Permission handling** -- if a tool requires approval, Stagent asks in the channel and you reply with "approve" or "deny"
+- **Turn locking** -- if you send a message while the agent is still processing, you get a "Still processing, please wait..." reply
+
+Channel conversations also appear in the Stagent Chat sidebar, so you can continue them from the web UI.
+
+### Connection Testing
+
+Every channel has a test status indicator:
+
+| Status | Meaning |
+|--------|---------|
+| **untested** | Channel created but never tested |
+| **ok** | Last test message was delivered successfully |
+| **failed** | Last test or delivery failed -- check configuration |
+
+Click **Test** next to any channel to send a probe message and update the status.
+
+### Channel Controls
+
+Each channel card in Settings has:
+
+- **Chat** toggle -- enable/disable bidirectional chat mode (Slack and Telegram only)
+- **Active** toggle -- enable/disable the channel entirely (preserves configuration)
+- **Test** button -- send a test message to verify connectivity
+- **Delete** button -- remove the channel
+
+When Chat is enabled, a webhook URL is displayed below the channel card for reference.
+
+### Schedule Integration
+
+When a schedule fires, Stagent checks if it has delivery channels assigned. If so, a notification is posted to each active channel containing:
+
+- The schedule name and firing number
+- The task prompt (truncated)
+- A link back to the task
+
+Delivery failures are logged but never block task execution -- the agent work completes even if the notification fails to send.
+
+### Auto-Polling (Local Development)
+
+For local development, Stagent includes a built-in poller that checks Telegram and Slack for new messages every 5 seconds. This runs automatically when the dev server starts -- no public URL or webhook registration needed. The poller only polls channels that have both Chat enabled and Active status on.
+
+## How To
+
+### Connect Slack to Stagent
+
+This walkthrough creates a Slack App and connects it to Stagent for both outbound notifications and bidirectional chat.
+
+**Part 1 -- Create the Slack App**
+
+1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App**
+2. Choose **From scratch**
+3. Enter an App Name (e.g., "Stagent") and select the workspace you want to post to
+4. Click **Create App**
+
+**Part 2 -- Enable Incoming Webhooks (for outbound notifications)**
+
+5. In the app settings sidebar, click **Incoming Webhooks**
+6. Toggle **Activate Incoming Webhooks** to **On**
+7. Scroll down and click **Add New Webhook to Workspace**
+8. Select the Slack channel where you want notifications (e.g., `#all-stagent`)
+9. Click **Allow** to authorize the webhook
+10. Copy the generated **Webhook URL** (starts with `https://hooks.slack.com/services/...`)
+
+**Part 3 -- Add Bot Scopes (for bidirectional chat)**
+
+11. In the app settings sidebar, click **OAuth & Permissions**
+12. Scroll down to **Bot Token Scopes**
+13. Click **Add an OAuth Scope** and add these scopes:
+    - `channels:history` -- read messages from public channels
+    - `chat:write` -- send messages as the bot
+14. Scroll up and click **Reinstall to Stagent** to apply the new scopes
+15. Copy the **Bot User OAuth Token** (starts with `xoxb-...`)
+
+**Part 4 -- Get the Channel ID**
+
+16. Open Slack in a browser and navigate to the target channel
+17. The Channel ID is in the URL: `app.slack.com/client/WORKSPACE_ID/CHANNEL_ID` -- copy the `CHANNEL_ID` (starts with `C`)
+
+**Part 5 -- Add the Channel in Stagent**
+
+18. Open **Settings** in Stagent (sidebar → Configure → Settings)
+19. Scroll down to the **Delivery Channels** section
+20. Click **+ Add Channel**
+21. Set Channel Type to **Slack**
+22. Enter a descriptive name (e.g., "Stagent #all-stagent")
+23. Paste the **Webhook URL** from step 10
+24. Paste the **Bot Token** from step 15
+25. Optionally paste the **Signing Secret** (from Basic Information → App Credentials)
+26. Paste the **Channel ID** from step 17
+27. Click **Create Channel**
+28. Click **Test** -- verify the status changes to green **ok**
+29. Toggle **Chat** on to enable bidirectional mode
+30. Send a message in the Slack channel mentioning @Stagent -- you should receive a response within seconds
+
+### Add a Telegram Channel
+
+**Part 1 -- Create the Bot**
+
+1. Open Telegram and message [@BotFather](https://t.me/BotFather)
+2. Send `/newbot`, follow the prompts, and copy the **Bot Token** (format: `123456:ABC-DEF...`)
+3. Search for your bot by its username and **send it any message** (e.g., "hello") -- this is required before you can retrieve your Chat ID
+4. Get your **Chat ID** by visiting `https://api.telegram.org/bot<TOKEN>/getUpdates` in your browser -- the `chat.id` field in the JSON response contains the value you need (negative for groups). If the result array is empty, send another message to the bot first, then reload the URL
+
+**Part 2 -- Add the Channel in Stagent**
+
+5. In Stagent Settings → Delivery Channels → **+ Add Channel**
+6. Set Channel Type to **Telegram**
+7. Enter the Bot Token and Chat ID
+8. Click **Create Channel**
+9. Click **Test** -- verify the status changes to green **ok**
+10. Open the bot conversation in Telegram and confirm the test message was delivered
+11. Toggle **Chat** on to enable bidirectional mode
+12. Send a message to your bot in Telegram -- you should receive a response within seconds
+
+### Add a Generic Webhook
+
+1. In Stagent Settings → Delivery Channels → **+ Add Channel**
+2. Set Channel Type to **Webhook**
+3. Enter the destination **URL** (any HTTP endpoint that accepts POST requests)
+4. Optionally enter **Custom Headers** as JSON (e.g., `{"Authorization": "Bearer your-token"}`)
+5. Click **Create Channel** → **Test** → verify green **ok**
+
+Webhooks are outbound-only. The webhook receives a JSON POST body with this structure:
+
+```json
+{
+  "subject": "Schedule fired: Daily Report (#5)",
+  "body": "Task prompt text...",
+  "format": "markdown",
+  "metadata": {
+    "scheduleId": "...",
+    "taskId": "...",
+    "firingNumber": 5
+  },
+  "timestamp": "2026-03-31T10:00:00Z",
+  "source": "stagent"
+}
+```
+
+### Enable or Disable Bidirectional Chat
+
+To toggle Chat mode on an existing channel:
+
+1. Go to Settings → Delivery Channels
+2. Find the channel card for Slack or Telegram
+3. Toggle the **Chat** switch on or off
+4. When Chat is on, the channel shows a blue "Chat" badge and displays the webhook URL
+5. The auto-poller starts/stops polling that channel within 5 seconds
+
+### Conversations from Channels
+
+Channel conversations appear in the **Chat** sidebar alongside regular conversations. They are titled "Channel: [channel name]" and use the Sonnet model by default. You can view and continue these conversations from the web UI as well.
+
+## Related
+
+- [Settings](./settings.md) -- Delivery Channels live in the Settings page
+- [Schedules](./schedules.md) -- Attach channels to schedules for automated notifications
+- [Chat](./chat.md) -- Channel conversations appear in the Chat sidebar

package/docs/features/design-system.md

@@ -1,23 +1,23 @@
 ---
-title: "Design System — Calm Ops"
+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"
+lastUpdated: "2026-03-31"
 ---
 
-# Design System — Calm Ops
+# 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`.
+Stagent follows the "Calm Ops" design philosophy: opaque surfaces, border-centric elevation, and zero glass morphism. The system prioritizes readability and scan speed on operational screens.
 
 ## 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-*`.
+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.
 
 ### Elevation Model
 
@@ -34,14 +34,14 @@ Four elevation levels replace shadow-heavy or glass-based depth cues:
 
 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)
+- **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.
+- **Body text**: Inter -- clean, highly legible at 14px base size.
+- **Monospace**: JetBrains Mono -- code blocks, terminal output, status values.
 
 ### Spacing
 

package/docs/features/documents.md

@@ -6,7 +6,7 @@ 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"
+lastUpdated: "2026-03-31"
 ---
 
 # Documents
@@ -31,11 +31,11 @@ The upload dialog accepts files via drag-and-drop or file picker. A visual indic
 
 ### 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.
+- **PDF** -- Text extraction via pdf-parse.
+- **Text** -- Plain text, Markdown, code files.
+- **Images** -- Metadata extraction (dimensions, format).
+- **Office Documents** -- Word documents, presentations, and archives.
+- **Spreadsheets** -- Excel and CSV files.
 
 ### 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.
@@ -51,9 +51,9 @@ Agents can generate documents as output during task execution. Generated files a
 ### 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.
+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.
+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.