stagent 0.3.6 → 0.5.0

package/README.md

@@ -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 |
@@ -73,6 +73,9 @@ Stagent ships a shared runtime registry that routes tasks, schedules, and workfl
 | 🧪 | **[E2E Test Automation](#e2e-test-automation)** | API-level end-to-end test suite covering both runtimes, 4 profiles, and 4 workflow patterns |
 | ⌨️ | **[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 |
 
 ---
 
@@ -207,6 +210,38 @@ Built-in documentation system at `/playbook` with usage-stage awareness that ada
 
 <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/playbook-list.png" alt="Stagent playbook documentation" width="1200" />
 
+#### Living Book
+AI-native book reader at `/book` with 9 chapters across 3 parts (Foundation, Intelligence, Autonomy). Each chapter is generated from Stagent's own source code and feature docs by the document-writer agent — making this a book that writes itself.
+
+- **Chapter regeneration** — one-click regeneration via the document-writer agent profile with fire-and-forget task execution
+- **Staleness detection** — git-based change tracking compares source file timestamps against `lastGeneratedBy` frontmatter to show when chapters need updating
+- **Live progress streaming** — SSE subscription shows real-time agent steps during generation (Reading files → Planning → Composing → Writing) with fade-in animation
+- **Reading paths** — 4 persona-based paths (Getting Started, Team Lead, Power User, Developer) filter chapter navigation
+- **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
@@ -243,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).
@@ -260,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.
@@ -282,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`.
@@ -332,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
@@ -346,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/
@@ -443,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

@@ -104,7 +104,9 @@ var STAGENT_TABLES = [
   "environment_sync_ops",
   "environment_templates",
   "conversations",
-  "chat_messages"
+  "chat_messages",
+  "reading_progress",
+  "bookmarks"
 ];
 function bootstrapStagentDatabase(sqlite2) {
   sqlite2.exec(`
@@ -319,6 +321,11 @@ function bootstrapStagentDatabase(sqlite2) {
   addColumnIfMissing(`ALTER TABLE projects ADD COLUMN working_directory TEXT;`);
   addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN assigned_agent 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,
@@ -448,6 +455,26 @@ function bootstrapStagentDatabase(sqlite2) {
     CREATE INDEX IF NOT EXISTS idx_chat_messages_conversation_id ON chat_messages(conversation_id);
     CREATE INDEX IF NOT EXISTS idx_chat_messages_conversation_created ON chat_messages(conversation_id, created_at);
   `);
+  sqlite2.exec(`
+    CREATE TABLE IF NOT EXISTS reading_progress (
+      chapter_id TEXT PRIMARY KEY NOT NULL,
+      progress INTEGER DEFAULT 0 NOT NULL,
+      scroll_position INTEGER DEFAULT 0 NOT NULL,
+      last_read_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS bookmarks (
+      id TEXT PRIMARY KEY NOT NULL,
+      chapter_id TEXT NOT NULL,
+      section_id TEXT,
+      scroll_position INTEGER DEFAULT 0 NOT NULL,
+      label TEXT NOT NULL,
+      created_at INTEGER NOT NULL
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_bookmarks_chapter_id ON bookmarks(chapter_id);
+  `);
 }
 function hasLegacyStagentTables(sqlite2) {
   const placeholders = STAGENT_TABLES.map(() => "?").join(", ");
@@ -496,15 +523,16 @@ function markAllMigrationsApplied(sqlite2, migrationsFolder, migrationsTable = "
 var __dirname = dirname2(fileURLToPath(import.meta.url));
 var appDir = join3(__dirname, "..");
 var launchCwd = process.cwd();
-var DATA_DIR = getStagentDataDir();
-var dbPath = getStagentDbPath();
 var pkg = JSON.parse(readFileSync(join3(appDir, "package.json"), "utf-8"));
-var HELP_TEXT = `
+function getHelpText() {
+  const dir = getStagentDataDir();
+  const db2 = getStagentDbPath();
+  return `
 Data:
-  Directory        ${DATA_DIR}
-  Database         ${dbPath}
-  Sessions         ${join3(DATA_DIR, "sessions")}
-  Logs             ${join3(DATA_DIR, "logs")}
+  Directory        ${dir}
+  Database         ${db2}
+  Sessions         ${join3(dir, "sessions")}
+  Logs             ${join3(dir, "logs")}
 
 Environment variables:
   STAGENT_DATA_DIR Custom data directory for the web app
@@ -513,10 +541,16 @@ Environment variables:
 
 Examples:
   node dist/cli.js --port 3210 --no-open
-  STAGENT_DATA_DIR=/tmp/stagent node dist/cli.js --reset
+  node dist/cli.js --data-dir ~/.stagent-dogfood --port 3100
 `;
-program.name("stagent").description("Governed AI agent workspace").version(pkg.version).addHelpText("after", HELP_TEXT).option("-p, --port <number>", "port to start on", "3000").option("--reset", "delete the local database before starting").option("--no-open", "don't auto-open browser").parse();
+}
+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();
 var opts = program.opts();
+if (opts.dataDir) {
+  process.env.STAGENT_DATA_DIR = opts.dataDir;
+}
+var DATA_DIR = getStagentDataDir();
+var dbPath = getStagentDbPath();
 var requestedPort = Number.parseInt(opts.port, 10);
 if (Number.isNaN(requestedPort) || requestedPort <= 0) {
   program.error(`Invalid port: ${opts.port}`);

package/docs/.last-generated

@@ -1 +1 @@
-2026-03-22T20:46:49Z
+2026-03-28T00:33:25Z

package/docs/features/chat.md

@@ -3,100 +3,105 @@ title: "Chat"
 category: "feature-reference"
 section: "chat"
 route: "/chat"
-tags: ["chat", "conversations", "ai", "model-selection", "suggested-prompts", "quick-access", "streaming"]
+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-22"
+lastUpdated: "2026-03-27"
 ---
 
 # 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.
 
 ## 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*
+
+![Quick Access navigation](../screengrabs/chat-quick-access.png)
+*Response content with Quick Access navigation pills linking directly to mentioned entities*
 
 ## 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. 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.
 
 ### 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:
+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.
+- **Haiku 4.5** -- Fast responses at the lowest cost ($). The default choice for everyday questions.
+- **Sonnet 4.6** -- A balance of speed and depth ($$). Good for nuanced analysis.
+- **Opus 4.6** -- The most capable model ($$$). Best for complex reasoning and detailed answers.
+- **GPT-4o-mini** -- Fast alternative ($). Available when the Codex runtime is connected.
+- **GPT-4o** -- Balanced alternative ($$). Available when the Codex runtime is connected.
 
 Your preferred default model can be set in the Settings page under "Chat default model." The selection persists per conversation, so switching models mid-conversation is seamless.
 
-### Suggested Prompts
+### @ Mentions and Context
 
-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:
+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.
 
-- **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?"
+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.
 
-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. Click any past conversation to pick up where you left off. You can rename, archive, or delete conversations from the context menu.
 
-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.
+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.
 
-### Entity Management via Chat
+### Quick Access Navigation
 
-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 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.
 
 ### 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, so you see the answer forming in real time. A "Thinking..." indicator appears before the first token arrives. Markdown formatting -- headings, lists, code blocks with syntax highlighting, tables, and links -- renders as the text streams in. Code blocks include a copy button and language label for easy reference.
 
 ## How To
 
-### Start a Conversation
+### 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.
+2. Browse the tool catalog categories or type your question in the input area at the bottom.
+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.
 
-### Switch Models
+### Switch AI Models
 
-1. Click the model selector to the left of the input area (it shows the current model name).
+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.
 
-### Use Suggested Prompts
+### Reference Documents in Chat
 
-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.
+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 streaming, look for the Quick Access pills at the bottom of the message.
+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.
 
 ### Manage Conversations
@@ -112,8 +117,8 @@ Responses stream in token by token with a blinking cursor, so you see the answer
 
 ## 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 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
+- [Profiles](./profiles.md) -- Agent profiles that shape how the assistant responds
+- [Dashboard Kanban](./dashboard-kanban.md) -- Manage the tasks your chat assistant references

package/docs/features/schedules.md

@@ -3,66 +3,72 @@ title: "Schedules"
 category: "feature-reference"
 section: "schedules"
 route: "/schedules"
-tags: [schedules, automation, loops, recurring, intervals, autonomous]
-features: ["scheduled-prompt-loops", "autonomous-loop-execution"]
-screengrabCount: 1
-lastUpdated: "2026-03-21"
+tags: ["schedules", "automation", "recurring", "prompts"]
+features: ["scheduled-prompt-loops"]
+screengrabCount: 3
+lastUpdated: "2026-03-27"
 ---
 
 # Schedules
 
-Schedule recurring agent tasks with configurable intervals and autonomous loop execution. The scheduler engine manages the full execution lifecycle, running prompts on a cadence you define with preset intervals or custom timing. Autonomous loops add intelligent stop conditions so agents can iterate toward a goal and stop when done.
+Automate recurring AI prompts on configurable intervals. Define what you want an agent to do, set a schedule, and let it run unattended. Each firing creates a tracked task with full execution history, so you always know what ran, when it ran, and what it produced. Pause, resume, or edit schedules at any time without losing history.
 
 ## Screenshots
 
-![Schedules list showing active and paused schedules](../screengrabs/schedules-list.png)
-*The schedules list displays all configured schedules with their status, interval, next run time, and associated project.*
+![Schedules list showing active and paused schedules with status, frequency, and next firing time](../screengrabs/schedules-list.png)
+*The schedules list displays all configured schedules with their current status, interval, next run time, and associated project.*
+
+![Schedule detail sheet showing configuration and firing history](../screengrabs/schedules-detail.png)
+*The schedule detail sheet shows the full configuration, execution statistics, and a chronological firing history with results from each run.*
+
+![Schedule edit dialog with name, prompt, interval, runtime, and profile fields](../screengrabs/schedules-edit-form.png)
+*The edit dialog lets you modify a schedule's name, prompt, interval, runtime provider, and agent profile without recreating it.*
 
 ## Key Features
 
-### Preset Intervals
-Choose from six built-in interval presets for common scheduling patterns: every 5 minutes, 15 minutes, 30 minutes, hourly, every 2 hours, or daily at 9 AM. Presets cover the most common automation cadences without requiring manual configuration.
+### Schedule Management
+Create, edit, pause, resume, and delete schedules from a single list view. Each schedule captures a complete execution context: a descriptive name, the prompt to send to the agent, the execution interval, a project for scoping, the provider runtime, and the agent profile that governs behavior. Schedules persist in the database and survive server restarts.
 
-### Custom Intervals
-Define custom intervals beyond the presets using the interval parser. Specify any duration to match your exact automation needs, from rapid polling to weekly recurring tasks.
+### Schedule Editing
+Edit any schedule after creation using the edit dialog. Update the schedule name, prompt text, execution interval, runtime provider (Claude or Codex), and agent profile without deleting and recreating the schedule. All changes take effect on the next firing.
 
-### Schedule Configuration
-Each schedule captures a complete execution context: a descriptive name, the execution interval, the prompt to send to the agent, the project context for scoping, the provider runtime (Claude or Codex), and the agent profile that governs behavior.
+### Firing History
+Every schedule firing creates a tracked child task. The detail view shows a chronological history of all past executions with their results, making it easy to audit what the agent did on each run and spot patterns over time.
 
-### Scheduler Engine
-The scheduler engine runs as a background process initialized via the Next.js instrumentation hook. It tracks all active schedules, calculates next run times, triggers executions on cadence, and manages the lifecycle of each schedule through active, paused, and completed states.
+### Flexible Intervals
+Choose from six built-in presets (every 5 minutes, 15 minutes, 30 minutes, hourly, every 2 hours, or daily at 9 AM) or define a custom interval. Advanced users can enter standard 5-field cron expressions for precise control. Human-friendly shorthand like `5m`, `2h`, or `1d` is also accepted.
 
-### Autonomous Loop Execution
-Autonomous loops extend scheduled execution with intelligent stop conditions. Four stop condition types are available: max iterations (stop after N runs), time limit (stop after a duration), goal achieved (agent determines the objective is met), and error threshold (stop after too many failures). The loop executor passes iteration context between runs so the agent can build on previous results.
+### Runtime and Profile Selection
+Choose which AI provider runtime (Claude or Codex) and which agent profile each schedule uses. This lets you match the right model and behavioral profile to each automation task, whether it needs a code reviewer, researcher, or general assistant.
 
 ### Pause and Resume
-Schedules can be paused and resumed without losing their configuration or execution history. Pausing a schedule suspends future runs while preserving the next-run calculation, so resuming picks up right where it left off.
+Suspend a schedule without losing its configuration or execution history. Pausing stops future runs while preserving the next-run calculation, so resuming picks up right where it left off.
 
 ## How To
 
-### Create a Recurring Schedule
-1. Navigate to `/schedules` from the sidebar under the **Manage** group.
+### Create a New Schedule
+1. Navigate to **Schedules** from the sidebar under the Manage group.
 2. Click the **Create Schedule** button to open the creation form.
 3. Enter a descriptive name for the schedule.
-4. Select an interval from the presets (5min, 15min, 30min, hourly, 2h, daily 9AM) or define a custom interval.
+4. Select an interval from the presets or define a custom interval.
 5. Write the prompt that the agent will execute on each run.
 6. Optionally select a project for context scoping.
 7. Choose the provider runtime and agent profile.
 8. Save the schedule. It begins executing on the configured cadence.
 
-### Set Up an Autonomous Loop
-1. Create a schedule with your desired prompt and interval.
-2. Configure one or more stop conditions: set a max iteration count, a time limit, a goal description, or an error threshold.
-3. Start the schedule. The loop executor passes context from each iteration to the next.
-4. The loop automatically stops when any stop condition is met.
+### Edit an Existing Schedule
+1. Open the schedules list at **Schedules**.
+2. Select a schedule to open its detail view.
+3. Click the **Edit** button to open the edit dialog.
+4. Modify any combination of name, prompt, interval, runtime, or agent profile.
+5. Save your changes. They take effect on the next scheduled firing.
 
-### Pause or Resume a Schedule
-1. Open the schedules list at `/schedules`.
+### Pause and Resume a Schedule
+1. Open the schedules list at **Schedules**.
 2. Locate the schedule you want to control.
 3. Click the pause button to suspend future executions, or the resume button to reactivate a paused schedule.
-4. The schedule status updates to reflect the current state.
+4. The schedule status updates immediately and the list reflects the new state.
 
 ## Related
-- [Monitoring](./monitoring.md)
-- [Profiles](./profiles.md)
-- [Cost & Usage](./cost-usage.md)
+- [Profiles](./profiles.md) — Agent profiles used by schedule firings
+- [Monitor](./monitoring.md) — View execution logs from schedule firings