stagent 0.4.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.
 
 ---
 
@@ -58,7 +58,7 @@ Stagent ships a shared runtime registry that routes tasks, schedules, and workfl
 | ⏰ | **[Schedules](#schedules)** | Recurring and one-shot automations with cadence, expiry, and firing controls |
 | 📄 | **[Documents](#document-management)** | Upload, preprocess, inspect, and link files to tasks and projects |
 | 📥 | **[Human-in-the-Loop Inbox](#inbox--human-in-the-loop)** | Approve tool use, answer questions, and review results from one queue |
-| 💬 | **[Chat](#chat)** | Conversational AI with model selection, suggested prompts, and entity-aware responses |
+| 💬 | **[Chat](#chat)** | Tool catalog with model selection, @ mentions, slash commands, and browser automation |
 | 👀 | **[Monitoring](#monitoring)** | Live runtime visibility with log streaming, filters, and health signals |
 | 🔁 | **[Provider Runtimes](#provider-runtimes)** | Shared runtime layer with Claude Code and OpenAI Codex App Server adapters |
 | 🧪 | **[Parallel + Swarm Workflows](#parallel--swarm-workflows)** | Bounded fork/join and swarm orchestration without a free-form graph editor |
@@ -74,6 +74,8 @@ Stagent ships a shared runtime registry that routes tasks, schedules, and workfl
 | ⌨️ | **[Command Palette](#command-palette)** | Global `⌘K` search for fast navigation across tasks, projects, workflows, and settings |
 | 📖 | **[Playbook](#playbook)** | Built-in documentation with usage-stage awareness, adoption heatmap, and guided learning journeys |
 | 📚 | **[Living Book](#living-book)** | AI-native book reader with 9 chapters, agent-powered regeneration, staleness detection, and reading paths |
+| 🌐 | **[Environment](#environment)** | Control plane for Claude Code and Codex CLI environments with scanning, caching, sync, and templates |
+| 🔧 | **[Browser Tools](#browser-tools)** | Chrome DevTools and Playwright MCP integration for browser automation in chat and task execution |
 
 ---
 
@@ -218,6 +220,28 @@ AI-native book reader at `/book` with 9 chapters across 3 parts (Foundation, Int
 - **Try It Now** — each chapter links to related Playbook feature docs and user journeys
 - **Author's Notes** — collapsible callout blocks with behind-the-scenes commentary
 
+### Environment
+
+#### Environment
+Stagent doubles as a **control plane for AI coding environments** — scanning, caching, and syncing configuration for Claude Code and Codex CLI across projects. The environment dashboard surfaces detected tools, active configurations, git checkpoint status, and health scores.
+
+- **Environment Scanner** — detects Claude Code and Codex CLI configurations, MCP servers, skills, and project settings
+- **Environment Cache** — persists scanned state for fast dashboard rendering without re-scanning
+- **Environment Dashboard** — unified view of all detected environments with health indicators
+- **Git Checkpoint Manager** — tracks environment state via git commits for rollback and comparison
+- **Environment Sync Engine** — bidirectional sync between local config and cached state
+- **Project Onboarding** — guided flow for setting up new projects with environment-aware defaults
+- **Environment Templates** — reusable environment configurations for common project types
+- **Cross-Project Comparison** — compare environment settings across projects
+- **Skill Portfolio** — aggregate view of skills across all detected environments
+- **Environment Health Scoring** — composite health score based on configuration completeness and freshness
+- **Agent Profile from Environment** — auto-generate agent profiles from detected environment capabilities
+
+<img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/environment-list.png" alt="Stagent environment dashboard" width="1200" />
+
+#### Browser Tools
+Enable browser automation in chat and task execution through two MCP integrations: **Chrome DevTools MCP** (29 tools for connecting to a running Chrome instance via CDP) and **Playwright MCP** (50+ tools for headless browser automation). Configure both from Settings with independent toggles and permission tiering — read-only operations auto-approve while mutations are gated through the inbox approval flow.
+
 ### Platform
 
 #### Tool Permission Persistence
@@ -254,13 +278,13 @@ When an agent needs approval or input, a notification appears in your inbox. Rev
 | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/inbox-expanded.png" alt="Inbox notification expanded" width="580" /> |
 
 #### Chat
-Conversational control plane for all workspace primitives — projects, tasks, workflows, documents, and profiles are all reachable from the chat surface. Progressive 5-tier context injection (~53K token budget) builds workspace awareness from lightweight summaries up to full document content. Multi-provider model selection with cost tiers ($, $$, $$$) spans Claude Haiku through Opus and GPT-5.x models, with a Settings-level default preference. Claude.ai-style tabbed suggested prompts (Explore, Create, Analyze) with hover preview help new users discover workspace capabilities. Quick Access navigation pills in responses provide entity deep-linking — click a mentioned project or task to jump directly to its detail view. Stagent CRUD tools let you create, update, and delete projects, tasks, and workflows through natural language. Streaming responses render in real time with full markdown support.
+Conversational control plane for all workspace primitives — projects, tasks, workflows, documents, and profiles are all reachable from the chat surface. The chat interface is organized as a **tool catalog** with five categories (Explore, Create, Debug, Automate, Smart Picks) that help discover workspace capabilities. Progressive 5-tier context injection (~53K token budget) builds workspace awareness from lightweight summaries up to full document content. **@ mentions** let you reference documents and entities directly in prompts with fuzzy search autocomplete, injecting their content as context. **Slash commands** (`/`) provide quick access to tools and actions. Multi-provider model selection with cost tiers ($, $$, $$$) spans Claude Haiku through Opus and GPT-5.x models. Browser automation via Chrome DevTools and Playwright MCP enables screenshot capture and web interaction from chat. Quick Access navigation pills in responses provide entity deep-linking. Stagent CRUD tools let you create, update, and delete workspace entities through natural language.
 
-<img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-conversation.png" alt="Stagent chat conversation with Quick Access navigation pills" width="1200" />
+<img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-conversation.png" alt="Stagent chat conversation with @ document context" width="1200" />
 
-| Empty State & Suggested Prompts | Model Selector | Quick Access Pills |
+| Tool Catalog | Model Selector | Create Tab |
 |:-:|:-:|:-:|
-| <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-list.png" alt="Chat empty state with suggested prompts" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-model-selector.png" alt="Chat model selector with cost tiers" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-quick-access.png" alt="Chat Quick Access navigation pills" width="380" /> |
+| <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-list.png" alt="Chat tool catalog with category tabs" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-model-selector.png" alt="Chat model selector with cost tiers" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/chat-create-tab.png" alt="Chat Create category prompts" width="380" /> |
 
 #### Monitoring
 Real-time agent log streaming via Server-Sent Events. Filter by task or event type, click entries to jump to task details, and auto-pause polling when the tab is hidden (Page Visibility API).
@@ -271,19 +295,19 @@ Real-time agent log streaming via Server-Sent Events. Filter by task or event ty
 File upload with drag-and-drop in task creation. Type-aware content preview for text, markdown (via react-markdown), code, and JSON. Copy-to-clipboard and download-as-file for task outputs.
 
 #### Settings
-Configuration hub with provider-aware sections: Claude authentication (API key or OAuth), OpenAI Codex runtime API-key management, tool permissions (saved "Always Allow" patterns with revoke), permission presets, budget configuration, and data management.
+Configuration hub with provider-aware sections: Claude authentication (API key or OAuth), OpenAI Codex runtime API-key management, chat defaults (model selection), **browser tools** (Chrome DevTools and Playwright MCP toggles), runtime configuration (SDK timeout and max turns), tool permissions (saved "Always Allow" patterns with revoke), permission presets, budget guardrails, and data management.
 
 <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-list.png" alt="Stagent settings" width="1200" />
 
-| Permission Presets | Budget Configuration | Data Management |
+| Browser Tools | Permission Presets | Budget Configuration |
 |:-:|:-:|:-:|
-| <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-presets.png" alt="Tool permission presets" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-budget.png" alt="Budget configuration" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-data.png" alt="Data management" width="380" /> |
+| <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-browser-tools.png" alt="Browser tools MCP toggles" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-presets.png" alt="Tool permission presets" width="380" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/settings-budget.png" alt="Budget configuration" width="380" /> |
 
 #### CLI
 The `npx stagent` entry point boots a Next.js server from the published npm package. It is built from `bin/cli.ts` into `dist/cli.js` using tsup, and serves as the primary distribution channel — no clone required.
 
 #### Database
-SQLite with WAL mode via better-sqlite3 + Drizzle ORM. Twelve tables: `projects`, `tasks`, `workflows`, `agent_logs`, `notifications`, `documents`, `schedules`, `settings`, `learned_context`, `usage_ledger`, `conversations`, `chat_messages`. Self-healing bootstrap — tables are created on startup if missing.
+SQLite with WAL mode via better-sqlite3 + Drizzle ORM. Fourteen tables: `projects`, `tasks`, `workflows`, `agent_logs`, `notifications`, `documents`, `schedules`, `settings`, `learned_context`, `usage_ledger`, `conversations`, `chat_messages`, `environments`, `environment_configs`. Self-healing bootstrap — tables are created on startup if missing.
 
 #### Command Palette
 Global `⌘K` command palette for fast navigation and search across tasks, projects, workflows, and settings. Recent items, fuzzy search, and keyboard-driven navigation.
@@ -293,7 +317,7 @@ Global `⌘K` command palette for fast navigation and search across tasks, proje
 | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/command-palette-empty.png" alt="Command palette empty state" width="580" /> | <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/command-palette-search.png" alt="Command palette search results" width="580" /> |
 
 #### App Shell
-Responsive sidebar with collapsible icon-only mode, custom Stagent logo, tooltip navigation, dark/light/system theme, and OKLCH hue 250 blue-indigo color palette. Built on shadcn/ui (New York style) with PWA manifest and app icons. Routes: Home, Dashboard, Inbox, Chat, Monitor, Projects, Workflows, Documents, Profiles, Schedules, Cost & Usage, Playbook, Settings.
+Responsive sidebar with collapsible icon-only mode, custom Stagent logo, tooltip navigation, dark/light/system theme, and OKLCH hue 250 blue-indigo color palette. Built on shadcn/ui (New York style) with PWA manifest and app icons. Routes: Home, Dashboard, Inbox, Chat, Projects, Workflows, Documents, Monitor, Profiles, Schedules, Cost & Usage, AI Native Book, User Guide, Environment, Settings.
 
 #### E2E Test Automation
 API-level end-to-end test suite built on Vitest with 120-second timeouts and sequential execution. Five test files cover single-task execution, sequence workflows, parallel workflows, blueprints, and cross-runtime scenarios across both Claude and Codex backends. Tests skip gracefully when runtimes are not configured, preventing CI failures. Run with `npm run test:e2e`.
@@ -343,7 +367,9 @@ src/
 │   ├── schedules/        # Schedule management
 │   ├── costs/            # Cost & usage dashboard
 │   ├── playbook/         # Documentation & learning journeys
-│   ├── chat/             # Conversational AI
+│   ├── chat/             # Conversational AI (tool catalog)
+│   ├── book/             # AI Native Book reader
+│   ├── environment/      # Environment control plane
 │   ├── inbox/            # Notifications
 │   ├── monitor/          # Log streaming
 │   └── settings/         # Configuration
@@ -357,9 +383,11 @@ src/
 │   ├── playbook/         # Playbook docs + journeys + adoption
 │   ├── schedules/        # Schedule management
 │   ├── monitoring/       # Log viewer
-│   ├── chat/             # Chat shell, messages, input composer
+│   ├── chat/             # Chat shell, messages, input composer, tool catalog
+│   ├── book/             # Book reader, chapters, reading paths
+│   ├── environment/      # Environment dashboard, scanner, templates
 │   ├── notifications/    # Inbox + permission actions
-│   ├── settings/         # Auth, permissions, budgets, data mgmt
+│   ├── settings/         # Auth, permissions, budgets, browser tools, data mgmt
 │   ├── shared/           # App shell, sidebar
 │   └── ui/               # shadcn/ui primitives
 └── lib/
@@ -454,24 +482,32 @@ All 14 features shipped across three layers:
 | **Core** | Project management, task board, agent integration, inbox notifications, monitoring dashboard |
 | **Polish** | Homepage dashboard, UX fixes, workflow engine, AI task assist, content handling, session management |
 
-### Post-MVP — 37 features shipped
+### Post-MVP — 52 features shipped
 
 | Category | Features |
 |----------|---------|
 | **Documents** (5) | File attachments, preprocessing (5 formats), agent context injection, document browser, output generation |
 | **Agent Intelligence** (6) | Multi-agent routing, autonomous loops, multi-agent swarm, AI assist→workflows, agent self-improvement, workflow context batching |
-| **Agent Profiles** (2) | Agent profile catalog (13+ profiles), workflow blueprints (8 templates) |
-| **UI Enhancement** (13) | Ambient approvals, learned context UX, micro-visualizations, command palette, operational surface, profile surface, accessibility, UI density, kanban operations, board persistence, detail view redesign, playbook documentation, workflow UX overhaul (in-progress) |
+| **Agent Profiles** (2) | Agent profile catalog (21 profiles), workflow blueprints (8 templates) |
+| **UI Enhancement** (13) | Ambient approvals, learned context UX, micro-visualizations, command palette, operational surface, profile surface, accessibility, UI density, kanban operations, board persistence, detail view redesign, playbook documentation, workflow UX overhaul |
 | **Platform** (8) | Scheduled prompt loops, tool permissions, provider runtimes, OpenAI Codex runtime, cross-provider profiles, parallel fork/join, tool permission presets, npm publish (deferred) |
 | **Runtime Quality** (2) | SDK runtime hardening, E2E test automation |
 | **Governance** (3) | Usage metering ledger, spend budget guardrails, cost & usage dashboard |
-| **Chat** (6) | Chat data layer, chat engine (5-tier context, CRUD tools), API routes (SSE streaming), UI shell, message rendering (Quick Access pills), input composer (model selector, suggested prompts) |
-
-### In Progress
-
-| Feature | Description |
-|---------|-------------|
-| Workflow UX Overhaul | Document context propagation, output readability, dashboard visibility, AI assist guidance |
+| **Chat** (6) | Chat data layer, chat engine (5-tier context, CRUD tools), API routes (SSE streaming), UI shell, message rendering (Quick Access pills), input composer (tool catalog, model selector) |
+| **Environment** (11) | Environment scanner, cache, dashboard, git checkpoint manager, sync engine, project onboarding, templates, cross-project comparison, skill portfolio, health scoring, agent profile from environment |
+| **Living Book** (5) | Content merge (chapters → playbook), author's notes, reading paths, markdown pipeline, self-updating chapters |
+
+### Planned
+
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| Browser Use | P1 | Chrome DevTools + Playwright MCP integration for browser automation |
+| Workspace Context Awareness | P1 | Surface cwd, git branch, worktree status to chat agents |
+| Chat Command Mentions | P1 | Slash commands for tools/actions + @ entity mentions |
+| Task Hierarchy Clarity | P1 | Distinguish standalone vs workflow-bound tasks |
+| Chat Conversation Persistence | P1 | URL/localStorage persistence for active conversations |
+| Settings Interactive Controls | P2 | Slider upgrades for SDK Timeout and Max Turns |
+| Agent Document API Access | P2 | MCP-based document tools for agent consumption |
 
 ---
 

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,7 +336,23 @@ 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);`);
+  addColumnIfMissing(`ALTER TABLE documents ADD COLUMN message_id TEXT;`);
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_documents_source ON documents(source);`);
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_documents_conversation_id ON documents(conversation_id);`);
   sqlite2.exec(`
     CREATE TABLE IF NOT EXISTS environment_scans (
       id TEXT PRIMARY KEY NOT NULL,
@@ -353,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
     );
@@ -410,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();
@@ -470,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(", ");
@@ -539,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-22T20:46:49Z
+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)