stagent 0.5.0 → 0.6.0

package/README.md

@@ -1,8 +1,8 @@
 # Stagent
 
-> Governed AI Agent Workspace — Supervised Local Execution, Workflows, Documents, and Provider Runtimes.
+> AI Business Operating System — Run your business with AI agents. Local-first, multi-provider, governed.
 
-[![npm](https://img.shields.io/npm/v/stagent)](https://www.npmjs.com/package/stagent) [![Next.js 16](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org/) [![React 19](https://img.shields.io/badge/React-19-61DAFB)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6)](https://www.typescriptlang.org/) [![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent_SDK-D97706)](https://docs.anthropic.com/) [![OpenAI Codex App Server](https://img.shields.io/badge/OpenAI-Codex_App_Server-10A37F)](https://developers.openai.com/codex/app-server) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+[![AI Business Operating System](https://img.shields.io/badge/AI_Business-Operating_System-6366F1)](https://stagent.io) [![npm](https://img.shields.io/npm/v/stagent)](https://www.npmjs.com/package/stagent) [![Next.js 16](https://img.shields.io/badge/Next.js-16-black)](https://nextjs.org/) [![React 19](https://img.shields.io/badge/React-19-61DAFB)](https://react.dev/) [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6)](https://www.typescriptlang.org/) [![Claude Agent SDK](https://img.shields.io/badge/Claude-Agent_SDK-D97706)](https://docs.anthropic.com/) [![OpenAI Codex App Server](https://img.shields.io/badge/OpenAI-Codex_App_Server-10A37F)](https://developers.openai.com/codex/app-server) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
 **[stagent.io](https://stagent.io)** · **[GitHub](https://github.com/navam-io/stagent)**
 
@@ -28,20 +28,20 @@ Open [localhost:3000](http://localhost:3000). That's it — zero config, local S
 
 ## Why Stagent
 
-AI agents are powerful — but production use breaks down when teams cannot see what the agent is doing, which rules it follows, or intervene before an unsafe action lands. Stagent gives you a **governed operations workspace** where every run is visible, every profile is reusable, and every approval is auditable.
+The AI agent stack is broken for business operators. You can spin up an agent in minutes — but running it reliably for real work means stitching together orchestration, governance, cost controls, and team coordination yourself. Stagent closes that gap with a single local-first platform where agents do the work and you stay in control.
 
 - **Local-first** — SQLite database, no cloud dependency, `npx stagent` and go
 - **Multi-provider** — Claude Code + OpenAI Codex App Server behind one runtime registry
-- **Human-in-the-loop** — Inbox approvals, ambient toasts, tool permission policies
-- **Reusable profiles** — 21 agent profiles with instructions, tool policies, and runtime tuning
-- **Workflow orchestration** — 6 patterns (sequence, planner-executor, checkpoint, parallel, loop, swarm)
-- **Cost governance** — Usage metering, budgets, and spend visibility per provider and model
+- **Your rules, enforced** — Tool permissions, inbox approvals, and audit trails for every agent action
+- **Your AI team** — 21 specialist profiles ready to deploy, each with instructions, tool policies, and runtime tuning
+- **Business processes, automated** — 6 workflow patterns (sequence, planner-executor, checkpoint, parallel, loop, swarm)
+- **Know what you spend** — Usage metering, budgets, and spend visibility per provider and model
 
 ---
 
 ## Runtime Bridge
 
-Stagent ships a shared runtime registry that routes tasks, schedules, and workflow steps through two governed execution backends: **Claude Code** (Anthropic Claude Agent SDK) and **OpenAI Codex App Server**. Both land in the same inbox, monitoring, and task-state surfaces — switching providers is a config change, not a rewrite.
+Run the same business process on different AI providers without changing a line of configuration. Stagent's shared runtime registry routes tasks, schedules, and workflow steps through **Claude Code** (Anthropic Claude Agent SDK) and **OpenAI Codex App Server**, landing everything in the same inbox, monitoring, and cost surfaces. Switching providers is a settings change, not a rewrite.
 
 ---
 

package/dist/cli.js

@@ -106,7 +106,13 @@ var STAGENT_TABLES = [
   "conversations",
   "chat_messages",
   "reading_progress",
-  "bookmarks"
+  "bookmarks",
+  "profile_test_results",
+  "repo_imports",
+  "agent_memory",
+  "channel_configs",
+  "channel_bindings",
+  "agent_messages"
 ];
 function bootstrapStagentDatabase(sqlite2) {
   sqlite2.exec(`
@@ -224,6 +230,16 @@ function bootstrapStagentDatabase(sqlite2) {
       expires_at INTEGER,
       last_fired_at INTEGER,
       next_fire_at INTEGER,
+      type TEXT DEFAULT 'scheduled' NOT NULL,
+      heartbeat_checklist TEXT,
+      active_hours_start INTEGER,
+      active_hours_end INTEGER,
+      active_timezone TEXT DEFAULT 'UTC',
+      suppression_count INTEGER DEFAULT 0 NOT NULL,
+      last_action_at INTEGER,
+      heartbeat_budget_per_day INTEGER,
+      heartbeat_spent_today INTEGER DEFAULT 0 NOT NULL,
+      heartbeat_budget_reset_at INTEGER,
       created_at INTEGER NOT NULL,
       updated_at INTEGER NOT NULL,
       FOREIGN KEY (project_id) REFERENCES projects(id) ON UPDATE NO ACTION ON DELETE NO ACTION
@@ -320,6 +336,17 @@ function bootstrapStagentDatabase(sqlite2) {
   sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_schedule_id ON tasks(schedule_id);`);
   addColumnIfMissing(`ALTER TABLE projects ADD COLUMN working_directory TEXT;`);
   addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN assigned_agent TEXT;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN type TEXT DEFAULT 'scheduled' NOT NULL;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN heartbeat_checklist TEXT;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN active_hours_start INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN active_hours_end INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN active_timezone TEXT DEFAULT 'UTC';`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN suppression_count INTEGER DEFAULT 0 NOT NULL;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN last_action_at INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN heartbeat_budget_per_day INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN heartbeat_spent_today INTEGER DEFAULT 0 NOT NULL;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN heartbeat_budget_reset_at INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN source_type TEXT;`);
   addColumnIfMissing(`ALTER TABLE documents ADD COLUMN version INTEGER NOT NULL DEFAULT 1;`);
   addColumnIfMissing(`ALTER TABLE documents ADD COLUMN source TEXT DEFAULT 'upload';`);
   addColumnIfMissing(`ALTER TABLE documents ADD COLUMN conversation_id TEXT REFERENCES conversations(id);`);
@@ -358,6 +385,7 @@ function bootstrapStagentDatabase(sqlite2) {
       metadata TEXT,
       size_bytes INTEGER DEFAULT 0 NOT NULL,
       modified_at INTEGER NOT NULL,
+      linked_profile_id TEXT,
       created_at INTEGER NOT NULL,
       FOREIGN KEY (scan_id) REFERENCES environment_scans(id) ON UPDATE NO ACTION ON DELETE NO ACTION
     );
@@ -415,6 +443,8 @@ function bootstrapStagentDatabase(sqlite2) {
 
     CREATE INDEX IF NOT EXISTS idx_env_templates_scope ON environment_templates(scope);
   `);
+  addColumnIfMissing(`ALTER TABLE environment_artifacts ADD COLUMN linked_profile_id TEXT;`);
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_env_artifacts_linked_profile ON environment_artifacts(linked_profile_id);`);
   const legacyConv = sqlite2.prepare(
     `SELECT sql FROM sqlite_master WHERE type='table' AND name='conversations'`
   ).get();
@@ -475,6 +505,120 @@ function bootstrapStagentDatabase(sqlite2) {
 
     CREATE INDEX IF NOT EXISTS idx_bookmarks_chapter_id ON bookmarks(chapter_id);
   `);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS repo_imports (
+      id TEXT PRIMARY KEY NOT NULL,
+      repo_url TEXT NOT NULL,
+      repo_owner TEXT NOT NULL,
+      repo_name TEXT NOT NULL,
+      branch TEXT NOT NULL,
+      commit_sha TEXT NOT NULL,
+      profile_ids TEXT NOT NULL,
+      skill_count INTEGER NOT NULL,
+      last_checked_at INTEGER,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_repo_imports_repo_url ON repo_imports(repo_url);
+    CREATE INDEX IF NOT EXISTS idx_repo_imports_owner_name ON repo_imports(repo_owner, repo_name);
+  `);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS agent_memory (
+      id TEXT PRIMARY KEY NOT NULL,
+      profile_id TEXT NOT NULL,
+      category TEXT NOT NULL,
+      content TEXT NOT NULL,
+      confidence INTEGER DEFAULT 700 NOT NULL,
+      source_task_id TEXT,
+      tags TEXT,
+      last_accessed_at INTEGER,
+      access_count INTEGER DEFAULT 0 NOT NULL,
+      decay_rate INTEGER DEFAULT 10 NOT NULL,
+      status TEXT DEFAULT 'active' NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (source_task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_agent_memory_profile_status ON agent_memory(profile_id, status);
+    CREATE INDEX IF NOT EXISTS idx_agent_memory_confidence ON agent_memory(confidence);
+  `);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS profile_test_results (
+      id TEXT PRIMARY KEY NOT NULL,
+      profile_id TEXT NOT NULL,
+      runtime_id TEXT NOT NULL,
+      report_json TEXT NOT NULL,
+      total_passed INTEGER DEFAULT 0 NOT NULL,
+      total_failed INTEGER DEFAULT 0 NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_profile_test_results_profile_runtime ON profile_test_results(profile_id, runtime_id);
+  `);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS channel_configs (
+      id TEXT PRIMARY KEY NOT NULL,
+      channel_type TEXT NOT NULL,
+      name TEXT NOT NULL,
+      config TEXT NOT NULL,
+      status TEXT DEFAULT 'active' NOT NULL,
+      test_status TEXT DEFAULT 'untested' NOT NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_channel_configs_type ON channel_configs(channel_type);
+  `);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN delivery_channels TEXT;`);
+  addColumnIfMissing(`ALTER TABLE channel_configs ADD COLUMN direction TEXT DEFAULT 'outbound' NOT NULL;`);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS channel_bindings (
+      id TEXT PRIMARY KEY NOT NULL,
+      channel_config_id TEXT NOT NULL,
+      conversation_id TEXT NOT NULL,
+      external_thread_id TEXT,
+      runtime_id TEXT NOT NULL,
+      model_id TEXT,
+      profile_id TEXT,
+      status TEXT DEFAULT 'active' NOT NULL,
+      pending_request_id TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL,
+      FOREIGN KEY (channel_config_id) REFERENCES channel_configs(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_channel_bindings_config ON channel_bindings(channel_config_id);
+    CREATE INDEX IF NOT EXISTS idx_channel_bindings_conversation ON channel_bindings(conversation_id);
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_channel_bindings_config_thread ON channel_bindings(channel_config_id, external_thread_id);
+  `);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS agent_messages (
+      id TEXT PRIMARY KEY NOT NULL,
+      from_profile_id TEXT NOT NULL,
+      to_profile_id TEXT NOT NULL,
+      task_id TEXT,
+      target_task_id TEXT,
+      subject TEXT NOT NULL,
+      body TEXT NOT NULL,
+      attachments TEXT,
+      priority INTEGER DEFAULT 2 NOT NULL,
+      status TEXT DEFAULT 'pending' NOT NULL,
+      requires_approval INTEGER DEFAULT 0 NOT NULL,
+      approved_by TEXT,
+      parent_message_id TEXT,
+      chain_depth INTEGER DEFAULT 0 NOT NULL,
+      created_at INTEGER NOT NULL,
+      responded_at INTEGER,
+      expires_at INTEGER,
+      FOREIGN KEY (task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (target_task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_agent_messages_to_status ON agent_messages(to_profile_id, status);
+    CREATE INDEX IF NOT EXISTS idx_agent_messages_task ON agent_messages(task_id);
+  `);
 }
 function hasLegacyStagentTables(sqlite2) {
   const placeholders = STAGENT_TABLES.map(() => "?").join(", ");
@@ -544,7 +688,7 @@ Examples:
   node dist/cli.js --data-dir ~/.stagent-dogfood --port 3100
 `;
 }
-program.name("stagent").description("Governed AI agent workspace").version(pkg.version).addHelpText("after", getHelpText).option("-p, --port <number>", "port to start on", "3000").option("--data-dir <path>", "custom data directory (overrides STAGENT_DATA_DIR)").option("--reset", "delete the local database before starting").option("--no-open", "don't auto-open browser").parse();
+program.name("stagent").description("AI Business Operating System").version(pkg.version).addHelpText("after", getHelpText).option("-p, --port <number>", "port to start on", "3000").option("--data-dir <path>", "custom data directory (overrides STAGENT_DATA_DIR)").option("--reset", "delete the local database before starting").option("--no-open", "don't auto-open browser").parse();
 var opts = program.opts();
 if (opts.dataDir) {
   process.env.STAGENT_DATA_DIR = opts.dataDir;

package/docs/.coverage-gaps.json

@@ -0,0 +1,21 @@
+{
+  "generated": "2026-03-31T21:00:00Z",
+  "totalFeatures": 31,
+  "coveredFeatures": 28,
+  "uncoveredFeatures": 3,
+  "coveragePercent": 90.3,
+  "gaps": {
+    "book-content-merge": {
+      "availableScreenshots": ["book-reader.png"],
+      "note": "Book reader screenshot exists but not referenced in any journey doc"
+    },
+    "book-reading-paths": {
+      "availableScreenshots": ["book-reader.png", "book-chapter-nav.png"],
+      "note": "Book navigation screenshots exist but not referenced in any journey doc"
+    },
+    "browser-tool-orchestration": {
+      "availableScreenshots": ["settings-browser-tools.png"],
+      "note": "Browser tools settings screenshot exists but not referenced in any journey doc"
+    }
+  }
+}

package/docs/.last-generated

@@ -1 +1 @@
-2026-03-28T00:33:25Z
+2026-04-01T05:15:01Z

package/docs/features/agent-intelligence.md

@@ -3,38 +3,36 @@ 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"]
+tags: [ai-assist, routing, autonomous, swarm, self-improvement, context, parallel, episodic-memory, handoffs]
+features: ["task-definition-ai", "multi-agent-routing", "autonomous-loop-execution", "multi-agent-swarm", "agent-self-improvement", "workflow-context-batching", "parallel-research-fork-join", "agent-episodic-memory", "agent-async-handoffs"]
 screengrabCount: 0
-lastUpdated: "2026-03-21"
+lastUpdated: "2026-03-31"
 ---
 
 # 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
+Stagent layers several AI-powered capabilities on top of basic task execution. From one-click description improvement to multi-agent coordination, episodic memory, and async handoffs, these features reduce manual effort and improve output quality across the workspace.
 
 ## 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.
+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 you retain 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/`.
+When a task is created, the task classifier analyzes its content and automatically selects the best-fit agent profile from the registry. The selected profile can be overridden manually via the profile dropdown. The router considers task content, project context, profile capabilities, and runtime availability.
 
 ### 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.
+- **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.
+Loops support pause and resume. The loop status view provides real-time progress and control.
 
 ### Multi-Agent Swarm
 
@@ -42,7 +40,30 @@ For complex tasks that benefit from multiple perspectives, the swarm feature coo
 
 ### 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.
+Agents accumulate learned context across iterations, stored in the database. This behavioral context feeds back into subsequent runs, allowing agents to refine their approach over time without manual prompt tuning. Context proposals require human approval before being applied.
+
+### Agent Episodic Memory
+
+Distinct from behavioral learned context, episodic memory captures factual knowledge the agent discovers during task execution. Key characteristics:
+
+- **Memory extraction** -- agents identify and store important facts, decisions, and discoveries as discrete memory entries
+- **Confidence scoring** -- each memory has a confidence level based on source reliability
+- **Time-based decay** -- older memories gradually lose relevance weight, keeping the context window focused on current knowledge
+- **Relevance-filtered retrieval** -- when executing a new task, the agent retrieves only memories relevant to the current context
+- **Operator review** -- a memory browser UI lets you inspect, edit, and delete stored memories
+
+Episodic memory means agents build institutional knowledge over time. A financial analyst profile that researches a company once can recall that research in future tasks without re-doing the work.
+
+### Agent Async Handoffs
+
+Agents can hand off work to other agents asynchronously through a message bus:
+
+- **send_handoff tool** -- agents use this tool to delegate work to another profile
+- **Governance gates** -- chain depth limits prevent infinite handoff loops, and self-handoff is blocked
+- **Inbox approvals** -- handoff requests surface in the inbox for human approval before the receiving agent begins work
+- **Handoff policies** -- configure which profiles can hand off to which, and under what conditions
+
+This enables multi-agent workflows where a researcher discovers a code issue and hands it off to the code reviewer without requiring a pre-built workflow definition.
 
 ### Workflow Context Batching
 
@@ -58,3 +79,4 @@ Research tasks can be forked into concurrent sub-tasks that investigate differen
 - [Profiles](./profiles.md)
 - [Workflows](./workflows.md)
 - [Schedules](./schedules.md)
+- [Inbox & Notifications](./inbox-notifications.md)

package/docs/features/chat.md

@@ -3,15 +3,15 @@ title: "Chat"
 category: "feature-reference"
 section: "chat"
 route: "/chat"
-tags: ["chat", "conversation", "ai", "tool-catalog", "mentions"]
-features: ["chat-data-layer", "chat-engine", "chat-api-routes", "chat-ui-shell", "chat-message-rendering", "chat-input-composer"]
-screengrabCount: 5
-lastUpdated: "2026-03-27"
+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 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.
+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
 
@@ -27,9 +27,6 @@ The Chat page is your AI-powered command center for everything in your workspace
 ![Active conversation](../screengrabs/chat-conversation.png)
 *Active conversation with @ document context injected and streamed response with formatted markdown*
 
-![Quick Access navigation](../screengrabs/chat-quick-access.png)
-*Response content with Quick Access navigation pills linking directly to mentioned entities*
-
 ## Key Features
 
 ### Tool Catalog
@@ -40,85 +37,65 @@ When no conversation is active, the chat page displays a curated grid of suggest
 - **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. If you have a recently failed task, a prompt like "Why did [task name] fail?" appears automatically.
-
-Click any suggestion to insert it into the input and start a conversation instantly.
+- **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-left 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.
+- **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).
 
 ### @ Mentions and Context
 
-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 grouped by entity type. When you select a mention, the assistant receives the full details of that entity as part of the conversation context -- so it can give precise, informed answers without you having to copy-paste information.
-
-The assistant also loads workspace context automatically in the background. Your active project, recent tasks, running workflows, and linked documents are all available to the model without any extra effort on your part.
+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.
 
 ### Conversation Management
 
-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 smaller screens, the conversation list is tucked behind a menu icon and slides in as an overlay so the message area gets full screen space.
+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.
 
-### Quick Access Navigation
+### Channel Conversations
 
-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 the response 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.
+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 New Conversation
 
 1. Click **Chat** in the sidebar (under the Work section).
-2. Browse the tool catalog categories or type your question in the input area at the bottom.
+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 assistant's response streams in immediately.
+4. Press **Enter** to send. The response streams in immediately.
 
 ### Switch AI Models
 
-1. Click the model selector to the left of the input area (it shows the current model name and cost tier).
-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.
-
-### Reference Documents in Chat
-
-1. In the chat input, 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 the entity you want.
-3. The selected mention appears as a highlighted reference in your message.
-4. When you send the message, the assistant receives the full context of the mentioned entity and can answer questions about it in detail.
-
-### Navigate to Entities from Chat
-
-1. Ask the assistant about a project, task, or other workspace item.
-2. After the response finishes, 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
 
-- [Settings](./settings.md) -- Configure default chat model and browser tools
-- [Documents](./documents.md) -- Documents the assistant can summarize and reference via @ mentions
-- [Projects](./projects.md) -- Projects that provide context to your chat conversations
+- [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
-- [Dashboard Kanban](./dashboard-kanban.md) -- Manage the tasks your chat assistant references
+- [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)