stagent 0.9.6 → 0.11.0

package/docs/features/inbox-notifications.md

@@ -4,9 +4,9 @@ category: "feature-reference"
 section: "inbox-notifications"
 route: "/inbox"
 tags: [inbox, notifications, permissions, approval, human-in-the-loop, toast, handoffs, agent-messages]
-features: ["inbox-notifications", "ambient-approval-toast", "content-handling", "agent-async-handoffs"]
+features: ["inbox-notifications", "ambient-approval-toast", "content-handling", "agent-async-handoffs", "upgrade-detection", "upgrade-session"]
 screengrabCount: 2
-lastUpdated: "2026-03-31"
+lastUpdated: "2026-04-15"
 ---
 
 # Inbox & Notifications
@@ -41,6 +41,14 @@ When an agent requests permission to use a tool, a "Permission Required" notific
 ### Agent Handoff Approvals
 When one agent hands off work to another via the async message bus, a handoff notification appears in the inbox. You can approve the handoff to let the receiving agent proceed, or deny it to stop the chain. Governance gates enforce chain depth limits and prevent self-handoffs.
 
+### Agent Questions (AskUserQuestion)
+
+When an agent needs a direct answer from you — for example, to disambiguate between two valid paths during an upgrade merge — it uses the **AskUserQuestion** tool. These surface in the inbox as question notifications with a typed reply box (rendered by the `QuestionReplyActions` branch of the permission-response view). Submit a short answer inline and the agent resumes from where it paused. Questions are distinct from permission requests: there is no "Approve / Deny," only the reply field.
+
+### Upgrade Failure Notifications
+
+If the hourly upgrade-detection poller fails three consecutive times (network error, unreachable remote, etc.), a persistent notification is posted to the inbox so the issue does not go silent. The three-strike dedup prevents a flood — only the first sustained failure raises a notification, and it clears automatically once the poller succeeds again.
+
 ### Ambient Approval Toasts
 For quick permission grants, ambient toasts appear at the edge of the screen. You can approve or deny without navigating to the inbox, keeping your workflow uninterrupted.
 

package/docs/features/keyboard-navigation.md

@@ -3,10 +3,10 @@ title: "Keyboard Navigation"
 category: "feature-reference"
 section: "keyboard-navigation"
 route: "cross-cutting"
-tags: [keyboard, command-palette, accessibility, aria, a11y, navigation]
-features: ["command-palette-enhancement", "accessibility", "keyboard-shortcut-system"]
+tags: [keyboard, command-palette, accessibility, aria, a11y, navigation, templates, saved-searches, slash-commands]
+features: ["command-palette-enhancement", "accessibility", "keyboard-shortcut-system", "chat-conversation-templates", "chat-pinned-saved-searches", "saved-search-polish-v1"]
 screengrabCount: 2
-lastUpdated: "2026-03-31"
+lastUpdated: "2026-04-15"
 ---
 
 # Keyboard Navigation
@@ -31,6 +31,15 @@ Activated with **Meta+K** (Cmd+K on macOS, Ctrl+K on other platforms), the comma
 - **Cross-entity search** -- type to search across projects, tasks, workflows, documents, and schedules in a single unified list.
 - **Keyboard navigation** -- arrow keys to browse results, Enter to select, Escape to dismiss.
 - **Action shortcuts** -- create new tasks, projects, or workflows directly from the palette.
+- **Templates group** -- browse conversation templates generated from workflow blueprints; pick one to open a pre-primed chat.
+- **Saved group** -- recall pinned search + filter combinations across Chat, Documents, and Tables. Saved searches round-trip through a settings endpoint and refetch automatically when new ones are added.
+
+### Slash Commands
+
+In addition to the palette, the Chat composer recognizes slash commands for fast actions:
+
+- `/new-from-template` -- open the conversation template picker inline without leaving the composer.
+- Additional slash commands live alongside the `/` popover tabs (Actions, Skills, Tools, Entities).
 
 ### Focus-Visible Rings
 

package/docs/features/provider-runtimes.md

@@ -4,9 +4,9 @@ category: "feature-reference"
 section: "provider-runtimes"
 route: "cross-cutting"
 tags: [claude, codex, runtime, oauth, websocket, mcp, providers, ollama, anthropic-direct, openai-direct, smart-router]
-features: ["provider-runtime-abstraction", "openai-codex-app-server", "cross-provider-profile-compatibility", "ollama-runtime-provider", "anthropic-direct-runtime", "openai-direct-runtime", "smart-runtime-router"]
+features: ["provider-runtime-abstraction", "openai-codex-app-server", "cross-provider-profile-compatibility", "ollama-runtime-provider", "anthropic-direct-runtime", "openai-direct-runtime", "smart-runtime-router", "runtime-validation-hardening", "runtime-capability-matrix"]
 screengrabCount: 2
-lastUpdated: "2026-03-31"
+lastUpdated: "2026-04-15"
 ---
 
 # Provider Runtimes
@@ -51,6 +51,10 @@ The Codex runtime connects to the OpenAI Codex App Server over WebSocket using J
 
 - Resumable threads with persistent state across reconnections.
 - WebSocket transport for low-latency bidirectional communication.
+- Two auth modes for Codex App Server:
+  - **ChatGPT** -- browser sign-in tied to your ChatGPT plan, with cached session reuse in Stagent's isolated Codex home
+  - **API Key** -- direct API-key auth using `OPENAI_API_KEY`
+- OpenAI Direct remains a separate API-key-backed runtime even when Codex App Server uses ChatGPT auth.
 
 ### OpenAI Direct API Runtime
 
@@ -82,6 +86,20 @@ The smart router automatically selects the best runtime for each task based on m
 
 The default selection is "Auto (recommended)" which lets the router decide. You can always override with a specific runtime in task, schedule, or workflow forms.
 
+### Runtime Capability Matrix
+
+Each runtime advertises its capabilities through a central matrix used by the rest of the app to decide whether to show a feature, gate it, or substitute a fallback. The most visible flags today:
+
+- **`supportsSkillComposition`** — whether the runtime accepts multiple concurrent skills on a single conversation. Gates the Chat Skills tab multi-activation behavior.
+- **`maxActiveSkills`** — hard cap on the active skill stack. The Chat composer shows "N of M active" against this value.
+- **`hasNativeSkills`** / **`stagentInjectsSkills`** / **`autoLoadsInstructions`** — decide whether Stagent should inject SKILL.md or trust the runtime's native loader, preventing duplicated context on Codex and Claude.
+
+Reading this matrix before wiring a feature is the canonical way to answer "should Stagent do X, or trust the runtime to do X."
+
+### Runtime Validation Hardening
+
+The MCP task-tools surface now validates every incoming `runtimeId` before dispatching work — unknown IDs are rejected at the boundary rather than crashing downstream. This protects the runtime registry from malformed chat-tool calls and surfaces bad configurations with a clean error message instead of a stack trace.
+
 ### Cross-Provider Profile Compatibility
 
 Agent profiles are defined independently of the provider runtime. A profile specifies behavioral traits -- system prompt, tool preferences, stop conditions -- that translate cleanly to any of the five runtimes. Switching the runtime dropdown on a task preserves the selected profile and its configuration.

package/docs/features/schedules.md

@@ -3,10 +3,10 @@ title: "Schedules"
 category: "feature-reference"
 section: "schedules"
 route: "/schedules"
-tags: ["schedules", "automation", "recurring", "prompts", "heartbeat", "natural-language", "proactive"]
-features: ["scheduled-prompt-loops", "heartbeat-scheduler", "natural-language-scheduling"]
-screengrabCount: 2
-lastUpdated: "2026-03-31"
+tags: ["schedules", "automation", "recurring", "prompts", "heartbeat", "natural-language", "proactive", "orchestration", "concurrency"]
+features: ["scheduled-prompt-loops", "heartbeat-scheduler", "natural-language-scheduling", "schedule-orchestration-v2"]
+screengrabCount: 4
+lastUpdated: "2026-04-08"
 ---
 
 # Schedules
@@ -21,6 +21,12 @@ Automate recurring AI prompts on configurable intervals with two distinct schedu
 ![Schedule detail sheet showing configuration and firing history](../screengrabs/schedules-detail.png)
 *The schedule detail sheet shows full configuration, checklist items (for heartbeats), execution statistics, and chronological firing history.*
 
+![Schedule creation form with max agent steps and budget controls](../screengrabs/schedules-create-form-empty.png)
+*The Create Schedule sheet exposes the new per-schedule turn-budget field. Max agent steps per run caps how many actions the agent takes in a single firing before the runtime aborts.*
+
+![Schedule creation form filled with realistic data](../screengrabs/schedules-create-form-filled.png)
+*Filled schedule form showing a weekday 9am security audit with a 250-step budget. Writing "MAX N turns" in your prompt is a hint to the model — the Max agent steps field is the enforced runtime limit.*
+
 ## Key Features
 
 ### Two Schedule Types
@@ -66,6 +72,28 @@ Every schedule firing creates a tracked child task. The detail view shows a chro
 ### Pause and Resume
 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.
 
+## Orchestration & Safety
+
+Schedule orchestration v2 adds four orchestration primitives that keep concurrent schedules, long-running firings, and noisy prompts from destabilising the workspace.
+
+### Global Concurrency Cap
+A configurable ceiling on how many scheduled runs can execute simultaneously. When the cap is reached, new firings are queued rather than launched in parallel. The atomic slot-claim primitive ensures that two schedules firing at the exact same tick cannot both slip past the limit — at most one claims each available slot. The cap adapts to chat pressure: active streaming chat sessions count against the ceiling so scheduled runs do not contend with interactive work.
+
+### Lease Reaper
+Each running firing holds a lease recorded in the slot registry. A background reaper periodically checks for stale leases — firings whose host process died or whose runtime never responded — and reclaims their slots via `AbortController`. This is the safety net that prevents hung runs from permanently occupying capacity.
+
+### Pre-Flight Cron Collision Warning
+When you save a schedule whose cron expression overlaps with an existing schedule (both would fire in the same minute on the same day), the form shows a warning banner at save time listing the conflicting schedules. You can still save — collisions are not blocked — but you see the conflict before committing so you can spread the load if desired.
+
+### Per-Schedule Turn Budget
+The **Max agent steps per run** field caps the number of agent actions (messages, tool calls, sub-responses) allowed in a single firing. The runtime enforces this as a hard limit — not a prompt hint — and emits an explicit `failure_reason` if the budget is exceeded. Most schedules run comfortably in the 50–500 step range; heavy research runs sometimes need 2,000+. A separate streak counter grants one grace breach before the schedule is auto-paused, so a single over-budget run does not kill a stable schedule.
+
+### Manual Execute with Force-Bypass
+The schedule detail view exposes a manual execute action that runs the schedule once, immediately, without waiting for the next scheduled tick. Manual runs still honour the concurrency cap by default; power users can force-bypass the cap for urgent one-off runs, with the bypass recorded in the audit ledger as a `manual_force_bypass` usage event.
+
+### Firing Metrics for Tuning
+Every firing writes a row into `schedule_firing_metrics` capturing start time, end time, steps consumed, tool calls made, and terminal reason. This is the forensic trail you use to tune `Max agent steps`, detect runaway prompts, and spot schedules that routinely run close to their budget.
+
 ## How To
 
 ### Create a Clock-Driven Schedule

package/docs/features/settings.md

@@ -3,10 +3,10 @@ title: "Settings"
 category: "feature-reference"
 section: "settings"
 route: "/settings"
-tags: ["settings", "configuration", "auth", "runtime", "browser-tools", "permissions", "budget", "ollama", "channels"]
-features: ["session-management", "tool-permission-persistence", "tool-permission-presets", "browser-use", "spend-budget-guardrails", "settings-interactive-controls", "ollama-runtime-provider", "multi-channel-delivery", "bidirectional-channel-chat", "database-snapshot-backup"]
-screengrabCount: 10
-lastUpdated: "2026-04-03"
+tags: ["settings", "configuration", "auth", "runtime", "browser-tools", "permissions", "budget", "ollama", "channels", "instance", "upgrade"]
+features: ["session-management", "tool-permission-persistence", "tool-permission-presets", "browser-use", "spend-budget-guardrails", "settings-interactive-controls", "ollama-runtime-provider", "multi-channel-delivery", "bidirectional-channel-chat", "database-snapshot-backup", "instance-bootstrap", "upgrade-detection", "upgrade-session", "instance-license-metering"]
+screengrabCount: 11
+lastUpdated: "2026-04-15"
 ---
 
 # Settings
@@ -49,7 +49,7 @@ The Settings page is the central configuration hub for Stagent. From a single sc
 
 ### Authentication
 
-Choose how Stagent connects to Claude. **OAuth** uses your existing Max subscription at no additional API cost. **API Key** uses the Anthropic key stored in your environment. A **Test Connection** button validates whichever method you select. A separate section configures the Codex App Server endpoint for tasks that run through the Codex runtime.
+Choose how Stagent connects to each provider runtime. For **Anthropic**, **OAuth** uses your existing Max subscription at no additional API cost, while **API Key** uses the Anthropic key stored in your environment. For **OpenAI**, Codex App Server can use either an **OpenAI API key** or **ChatGPT** browser sign-in, while OpenAI Direct continues to use an API key. Connection tests validate the currently selected runtime mode and the OpenAI section shows active ChatGPT account and Codex rate-limit state when available.
 
 ### Ollama Runtime (Local Models)
 
@@ -172,6 +172,29 @@ Protect your workspace with automatic and manual database backups:
 2. Toggle on the preset that matches your comfort level.
 3. The preset's tools are added to your approved list immediately.
 
+## Instance & Upgrades
+
+![Settings page scrolled to the Instance section](../screengrabs/settings-instance.png)
+*The Instance section shows the installation metadata and the upgrade flow entry point.*
+
+### Instance Section
+The **Instance** card surfaces metadata about this installation: the stable `instanceId`, the current instance branch (e.g., `local` for single-clone users, `wealth-mgr` for private instances), the upstream remote it tracks, and whether the first-boot bootstrap has completed. Power users also see the guardrail state — whether a pre-push hook is installed and whether `pushRemote=no_push` is set on the instance branch.
+
+### Dev Mode Gate
+When `STAGENT_DEV_MODE=true` is set in `.env.local` or the `.git/stagent-dev-mode` sentinel file is present, the Instance section displays a "Dev mode" banner and the upgrade machinery is intentionally bypassed. This is the gate that protects the main dev repo from having a pre-push hook installed by the instance-bootstrap flow — contributors working on Stagent itself must not have their own push workflow broken.
+
+### Upgrade Detection
+An hourly scheduled poll runs `git fetch` against the upstream remote and compares `HEAD` to `origin/main`. When upstream is ahead, the sidebar shows a small **Upgrade available** badge next to Settings and the Instance card surfaces a "New version available" card with the number of commits behind. Detection is `git`-based rather than GitHub REST to avoid rate limits. Three consecutive poll failures escalate to a persistent notification.
+
+### Upgrade Session
+Clicking **Start upgrade** opens the upgrade session as a right-side sheet — not a full-page navigation, so you can glance back at your workspace while the upgrade runs. The session is backed by a task row with the `upgrade-assistant` profile, so it reuses all the existing execution infrastructure: fire-and-forget launch, canUseTool approval caching, SSE log streaming, and conflict resolution via the pending-approval host. If merge conflicts occur, a 3-card cluster (Keep mine / Take theirs / Show diff) appears inline and you resolve them without leaving the sheet. When the assistant needs a direct answer (e.g., to disambiguate a conflict), it now calls **AskUserQuestion**, which renders a typed reply field via the inbox's `QuestionReplyActions` branch — you answer in-place and the assistant resumes. The `upgrade-assistant` profile explicitly allowlists AskUserQuestion so it is not gated behind a generic permission prompt.
+
+### Footer Upgrade Button
+A subtle **Upgrade** button appears in the sidebar footer once an upgrade is available — the same surface that shows trust tier and the command palette shortcut. Clicking it opens the same upgrade session sheet from any page without navigating to Settings first.
+
+### Hybrid Licensing
+Local-only features (task execution, workflows, schedules, tables) remain unlimited regardless of license state. Cloud features (sync, marketplace, team sharing) are metered via a `(email, machineFingerprint, instanceId)` tuple so the same user on the same machine counts as one seat across multiple instance branches. Seat state is refreshed on each boot via the LicenseManager.
+
 ## Related
 
 - [Cost & Usage](./cost-usage.md)

package/docs/features/shared-components.md

@@ -3,10 +3,10 @@ title: "Shared Components"
 category: "feature-reference"
 section: "shared-components"
 route: "cross-cutting"
-tags: [components, page-shell, detail-pane, status-chip, filter-bar, data-table, reusable]
-features: ["shared-component-library", "page-shell", "detail-pane", "status-chip", "filter-bar", "view-switcher"]
+tags: [components, page-shell, detail-pane, status-chip, filter-bar, filter-input, data-table, reusable]
+features: ["shared-component-library", "page-shell", "detail-pane", "status-chip", "filter-bar", "view-switcher", "chat-filter-namespace"]
 screengrabCount: 0
-lastUpdated: "2026-03-31"
+lastUpdated: "2026-04-15"
 ---
 
 # Shared Components
@@ -31,6 +31,10 @@ Five status chip families that map to entity lifecycle states. Each chip renders
 
 Horizontal filter strip placed below page headers. Supports multiple filter types (select, search, date range) and displays an active filter count badge. Filters persist in URL search params for shareable filtered views.
 
+### FilterInput
+
+Typed input used for namespace-aware filtering (`#scope:`, `#type:`, and similar qualifiers). Supports double-quoted values so phrases with spaces parse correctly — e.g. `#scope:"customer support"`. Used by Chat search, the `@` / `/` popovers, the `/documents` list page, and the `⌘K` palette, giving every surface the same filter syntax. Paired with the `cleanFilterInput()` helper, which strips mention-trigger residue (`@`, `#`, `/`) when a pinned saved search is reapplied.
+
 ### ViewSwitcher
 
 Toggle between saved view modes on a per-surface basis. Common modes include table view and grid/card view. The active view preference persists in local storage.

package/docs/features/tables.md

@@ -4,9 +4,9 @@ category: "feature-reference"
 section: "tables"
 route: "/tables"
 tags: [tables, structured-data, spreadsheet, charts, triggers, templates, import, export, formulas]
-features: ["tables-data-layer", "tables-list-page", "tables-spreadsheet-editor", "tables-document-import", "tables-template-gallery", "tables-agent-integration", "tables-chat-queries", "tables-computed-columns", "tables-cross-joins", "tables-agent-charts", "tables-workflow-triggers", "tables-nl-creation", "tables-export", "tables-versioning"]
+features: ["tables-data-layer", "tables-list-page", "tables-spreadsheet-editor", "tables-document-import", "tables-template-gallery", "tables-agent-integration", "tables-chat-queries", "tables-computed-columns", "tables-cross-joins", "tables-agent-charts", "tables-workflow-triggers", "tables-nl-creation", "tables-export", "tables-versioning", "bulk-row-enrichment"]
 screengrabCount: 8
-lastUpdated: "2026-04-03"
+lastUpdated: "2026-04-15"
 ---
 
 # Tables
@@ -38,6 +38,8 @@ Tables is Stagent's structured data system -- a built-in spreadsheet-meets-datab
 ### Table and Grid Views
 Browse all your tables from the `/tables` list page. Toggle between a compact table view and a visual grid view. Use the filter bar to narrow by category or search by name. Click any table to open it.
 
+The filter bar uses the shared **FilterInput** component and the `#namespace:value` syntax (double-quote values that contain spaces, e.g. `#type:"customer list"`). Saved filter + query combinations can be pinned as **saved searches** and recalled from the `⌘K` palette under the **Saved** group — useful for recurring table views like "open orders" or "stale leads." See the [Documents](./documents.md) page for a cross-surface reference implementation.
+
 ### Create Tables
 Open the create dialog to define a new table with a name, description, and columns. The inline column builder lets you set each column's name, type, and whether it is required -- all before the table is saved. Supported column types include text, number, date, boolean, select (dropdown), URL, email, and computed.
 
@@ -114,6 +116,13 @@ Every row edit is tracked. The History tab shows a timeline of changes, and you
 2. The agent will use its table tools to read, filter, aggregate, or update the data as needed.
 3. Results appear in the task output, and any row changes are reflected in the table immediately.
 
+### Bulk Row Enrichment
+Enrich every matching row in a table by generating a loop workflow that iterates over the rows and writes results back via a `postAction`. Trigger it two ways:
+- **From chat:** ask "enrich the Leads table with a one-line company summary for each row" — the `enrich_table` chat tool plans a loop workflow scoped to the matching rows.
+- **From the Tables API:** `POST /api/tables/:id/enrich` with a prompt, target column, and optional row filter.
+
+Each iteration binds the current row's fields as `{{row.field}}` in the prompt template, so the agent sees only that row's context. Execution is sequential (not parallel) to keep the spend budget predictable, and the loop is idempotent — already-populated cells are skipped on re-run so you can safely resume an interrupted enrichment. The generated workflow appears in the Workflows list so you can watch progress, pause, or inspect per-row results.
+
 ## Related
 
 - [Documents](./documents.md) -- Upload files and attach them to tasks for agent context.

package/docs/features/tool-permissions.md

@@ -4,9 +4,9 @@ category: "feature-reference"
 section: "tool-permissions"
 route: "cross-cutting"
 tags: [permissions, trust, safety, approval, human-in-the-loop, presets]
-features: ["tool-permission-persistence", "tool-permission-presets", "ambient-approval-toast"]
+features: ["tool-permission-persistence", "tool-permission-presets", "ambient-approval-toast", "upgrade-session"]
 screengrabCount: 1
-lastUpdated: "2026-03-31"
+lastUpdated: "2026-04-15"
 ---
 
 # Tool Permissions
@@ -46,6 +46,10 @@ Before executing a task, the runtime performs a permission pre-check against the
 
 When a tool request exceeds the current trust tier and has not been persisted, a notification is created in the inbox. You can approve or deny from the Inbox or from the task detail view, keeping the agent paused until a decision is made.
 
+### AskUserQuestion Tool
+
+A special tool — `AskUserQuestion` — lets agents ask you for direct input rather than request permission. Instead of an Approve / Deny pair, the inbox notification renders a typed reply box (the `QuestionReplyActions` branch of the permission response view). This is the primitive behind the upgrade assistant's conflict resolution flow: when the merge hits an ambiguous decision, the upgrade profile asks a targeted question and waits for your reply before proceeding. `AskUserQuestion` is never auto-approved and is explicitly allowlisted on the `upgrade-assistant` profile.
+
 ### Ambient Approval Toast
 
 For quick permission grants without navigating away from the current context, ambient toast notifications appear when an agent requests a tool. You can approve directly from the toast, maintaining workflow continuity.

package/docs/features/workflows.md

@@ -3,10 +3,10 @@ title: "Workflows"
 category: "feature-reference"
 section: "workflows"
 route: "/workflows"
-tags: [workflows, patterns, sequence, parallel, swarm, autonomous, templates, multi-step, blueprints]
-features: ["workflow-engine", "workflow-blueprints", "ai-assist-workflow-creation", "workflow-context-batching", "business-function-profiles"]
-screengrabCount: 3
-lastUpdated: "2026-03-31"
+tags: [workflows, patterns, sequence, parallel, swarm, autonomous, templates, multi-step, blueprints, delays, drip]
+features: ["workflow-engine", "workflow-blueprints", "ai-assist-workflow-creation", "workflow-context-batching", "business-function-profiles", "workflow-step-delays", "chat-conversation-templates", "workflow-run-history"]
+screengrabCount: 4
+lastUpdated: "2026-04-15"
 ---
 
 # Workflows
@@ -24,6 +24,9 @@ Workflows let you orchestrate multi-step agent operations using six built-in pat
 ![Workflow blueprints gallery](../screengrabs/workflows-blueprints.png)
 *Workflow blueprints gallery with pre-built workflow templates*
 
+![Workflow create form with a delay step inserted between sequence steps](../screengrabs/workflows-create-form-delay.png)
+*The workflow create form exposes an "Add Delay" button alongside "Add Step". Delay steps pause execution for a schedule-based duration (30m, 2h, 3d, 1w) before the next step runs — ideal for drip sequences and cooldown windows.*
+
 ## Key Features
 
 ### Six Pattern Types
@@ -35,6 +38,9 @@ Workflows support six orchestration patterns:
 - **Parallel Research** -- Fans out multiple steps to run concurrently, then merges results.
 - **Multi-Agent Swarm** -- Multiple agent profiles collaborate on a shared objective with dynamic handoffs.
 
+### Step Delays (Drip Sequences & Cooldowns)
+Insert pure time-delay steps between agent steps using the **Add Delay** button in the create form. Delays accept compact durations like `30m`, `2h`, `3d`, or `1w`. Execution model is schedule-based, not sleep-based: the delay is persisted in `workflows.resume_at` and the scheduler resumes the workflow when the time is up. This means delays survive process restarts — a 3-day cooldown will resume correctly even if the dev server is stopped and restarted in between. Resume is atomic and idempotent: the scheduler and a manual "Resume Now" click cannot double-fire the same delay. Delay steps are the primitive behind drip email campaigns, staggered onboarding sequences, and cooldown windows between automated actions.
+
 ### Workflow Blueprints
 The blueprint gallery offers pre-built workflow templates for common patterns:
 - **Technical blueprints** -- code review pipelines, deploy-and-verify, research synthesis, documentation generation
@@ -42,6 +48,10 @@ The blueprint gallery offers pre-built workflow templates for common patterns:
 
 Click any blueprint to preview its steps, then create a workflow pre-populated with the template configuration. Customize steps, profiles, and runtimes to match your specific process.
 
+### Blueprints as Chat Templates
+
+Blueprints also double as **conversation templates** for the Chat surface. A blueprint can declare an optional `chatPrompt` field that provides a purpose-built opening prompt for chat use; if it is not set, the chat launcher falls back to `steps[0].promptTemplate`. This means the same blueprint asset powers three entry points — the Workflows gallery, the Chat empty-state picker, and the `/new-from-template` slash command — without requiring parallel definitions. See the [Chat](./chat.md) feature doc for the conversation-side flow.
+
 ### Tabs: All, Templates, Runs
 The workflow page organizes content into three tabs. "All" shows every workflow. "Templates" shows reusable patterns you can instantiate. "Runs" shows active and historical executions with their current status.
 

package/docs/index.md

@@ -1,7 +1,7 @@
 ---
 title: "Stagent Documentation"
 category: "index"
-lastUpdated: "2026-04-03"
+lastUpdated: "2026-04-15"
 ---
 
 # Stagent Documentation

package/docs/journeys/developer.md

@@ -6,7 +6,7 @@ difficulty: "advanced"
 estimatedTime: "30 minutes"
 sections: ["settings", "environment", "chat", "monitoring", "profiles", "workflows", "tables", "schedules", "delivery-channels"]
 tags: ["advanced", "developer", "settings", "environment", "cli", "api", "monitoring", "profiles", "ollama", "channels", "handoffs", "memory", "tables"]
-lastUpdated: "2026-04-03"
+lastUpdated: "2026-04-16"
 ---
 
 # Developer Guide
@@ -55,7 +55,7 @@ Riley sets up Ollama as the fifth runtime adapter for private, zero-cost executi
 
 Riley sets up Slack and Telegram as delivery channels for schedule notifications and bidirectional chat.
 
-![Settings data management section](../screengrabs/settings-data.png)
+![Settings Delivery Channels section](../screengrabs/settings-channels.png)
 
 1. Scroll to **Delivery Channels** in Settings
 2. Click **+ Add Channel** and select **Slack**
@@ -98,6 +98,20 @@ Riley sets up Slack and Telegram as delivery channels for schedule notifications
 3. Use **Clear Data** cautiously -- it removes all workspace content while preserving settings
 4. Use **Populate Sample Data** for demos or testing
 
+### Step 6a: Take a Database Snapshot Backup
+
+Riley wants a point-in-time backup before running a risky migration or a destructive clear.
+
+![Settings snapshots card with create/restore/download controls](../screengrabs/settings-snapshots.png)
+
+1. Scroll to the **Snapshots** card inside **Data Management**
+2. Click **Create Snapshot** — Stagent copies the SQLite database (with WAL checkpoint) into a named, timestamped snapshot file stored alongside the live DB
+3. Give the snapshot a descriptive label ("before-v2-migration", "post-sample-seed") so future-you can find it
+4. To restore, pick a snapshot from the list and click **Restore** — the live DB is atomically swapped with the snapshot contents
+5. To archive off-host, click **Download** to get a `.sqlite` file you can stash in your backup system
+
+> **Tip:** Snapshots are the fastest safety net for experiments that touch tables, workflows, or schedules. Always take one before clearing data or trying an unfamiliar migration path.
+
 ### Step 7: Explore the Environment Dashboard
 
 Riley switches to the Environment page to understand the control plane.
@@ -204,6 +218,29 @@ Riley builds the CLI for scripted operations and CI/CD integration.
 3. Test CRUD operations: `node dist/cli.js projects list`, `node dist/cli.js tasks create --title "CLI test"`
 4. Verify CLI-created entities appear in the web UI (shared SQLite database)
 
+### Step 14a: Understand the Runtime Capability Matrix
+
+Riley wants to know why some features show up on one runtime but not another. The answer lives in the runtime capability matrix.
+
+1. Open `src/lib/agents/runtime/catalog.ts` — each runtime adapter declares flags like `supportsSkillComposition`, `maxActiveSkills`, `hasNativeSkills`, `stagentInjectsSkills`, and `autoLoadsInstructions`
+2. The Chat Skills tab reads `supportsSkillComposition` to decide whether to enable multi-skill activation and "N of M active" reporting
+3. The SKILL.md injector reads `stagentInjectsSkills` to avoid duplicating context on runtimes (like Codex App Server and Claude Agent SDK) that load instructions natively
+4. When you wire a new feature that touches system prompts or skills, consult the matrix before deciding whether Stagent should inject something or trust the runtime to do so
+
+> **Tip:** The MCP task-tools boundary also validates the runtime ID now (runtime-validation-hardening). Malformed `runtimeId` values are rejected at the boundary with a clean error, rather than crashing the dispatcher.
+
+### Step 14b: Observe the Upgrade Detection Poller
+
+![Instance section showing dev mode status and upgrade detection gate](../screengrabs/settings-instance.png)
+
+1. Scroll to the **Instance** section in Settings to see the dev mode status and upgrade detection gate
+2. The hourly scheduler runs `git fetch` against the upstream remote and compares `HEAD` to `origin/main`
+3. When upstream is ahead, the sidebar shows an **Upgrade available** badge and the Instance card reports the commits-behind count
+4. Three consecutive poll failures escalate to a persistent inbox notification (three-strike dedup prevents notification floods)
+5. The upgrade session uses the `upgrade-assistant` profile, which allowlists **AskUserQuestion** — the assistant can ask direct questions mid-merge without hitting a generic permission prompt
+
+> **Tip:** The Instance card also shows bootstrap status. In dev mode (indicated by `STAGENT_DEV_MODE=true` or the `.git/stagent-dev-mode` sentinel), auto-upgrade machinery is skipped to avoid interfering with contributor workflows.
+
 ### Step 15: Verify Platform Health
 
 Riley performs a final platform health check.

package/docs/journeys/personal-use.md

@@ -4,9 +4,9 @@ category: "user-journey"
 persona: "personal"
 difficulty: "beginner"
 estimatedTime: "30 minutes"
-sections: ["home-workspace", "dashboard-kanban", "projects", "chat", "tables", "schedules", "user-guide"]
-tags: ["beginner", "solo", "tasks", "kanban", "chat", "tables", "schedules", "delivery-channels"]
-lastUpdated: "2026-04-03"
+sections: ["home-workspace", "dashboard-kanban", "projects", "chat", "tables", "schedules", "user-guide", "book"]
+tags: ["beginner", "solo", "tasks", "kanban", "chat", "tables", "schedules", "delivery-channels", "book"]
+lastUpdated: "2026-04-16"
 ---
 
 # Personal Use Guide
@@ -69,9 +69,13 @@ Before setting up a formal project, Alex tries the Chat feature to brainstorm id
 2. Notice the **Tool Catalog** with a welcoming hero heading and suggested prompt categories (Explore, Create, Debug, Automate)
 3. Browse the **Smart Picks** row for personalized suggestions
 4. Type a question like "What pages should a developer portfolio website include?" and press Enter
-5. Review the AI response
+5. Review the AI response -- notice how Chat keeps a clean conversation thread, deduplicating similar messages so the history stays readable
+6. Try typing **@** in the composer to open the mentions popover -- you can reference tasks, projects, documents, profiles, and workflows inline to give the AI richer context
+7. Next time, try **Start from template** on the empty-state hero (or type `/new-from-template` in the composer) to open a conversation pre-primed with a blueprint like "Research a topic" or "Draft a plan"
 
-> **Tip:** Chat is perfect for quick brainstorming sessions. You do not need to create a project first -- just ask a question. The conversation history stays in the sidebar so you can return to it later.
+![@ mentions popover showing pinned entities, tasks, projects, and documents](../screengrabs/chat-mentions-popover.png)
+
+> **Tip:** Chat is perfect for quick brainstorming sessions. You do not need to create a project first -- just ask a question. The conversation history stays in the sidebar so you can return to it later. Pin useful filter + search combinations as **saved searches** (available from the `⌘K` palette under the **Saved** group) so you can jump back to them later.
 
 ### Step 5: Create a New Project
 
@@ -122,7 +126,10 @@ Alex creates the first task for the portfolio project.
 3. Write a **Description** with detail about requirements
 4. Assign the task to the **Portfolio Website** project
 5. Set **Priority** to High and leave **Status** as Planned
-6. Click **Create** to add the task to the board
+6. Open the **/** popover in the composer to browse available tools (create_task, execute_task, read_file) and entities -- these are the same capabilities the AI uses when running tasks
+7. Click **Create** to add the task to the board
+
+![/ popover Tools tab showing available runtime tools](../screengrabs/chat-tools-tab.png)
 
 > **Tip:** Write task descriptions as if you are briefing a colleague. The more specific you are, the better the AI agent results will be.
 
@@ -181,7 +188,7 @@ Alex wants Stagent to proactively check on the portfolio project every morning.
 
 Alex wants to receive schedule results on the go. Setting up a Telegram delivery channel takes less than two minutes.
 
-![Settings page showing provider and runtime configuration](../screengrabs/settings-auth.png)
+![Settings page showing Delivery Channels configuration](../screengrabs/settings-channels.png)
 
 1. Open **Settings** from the sidebar under **Configure**
 2. Scroll to the **Delivery Channels** section
@@ -205,7 +212,24 @@ Alex discovers the built-in documentation hub.
 3. Check the **guided journeys** for your current skill level
 4. Use the feature grid to discover areas you have not tried yet
 
-### Step 15: What's Next
+### Step 15: Read the AI Native Book
+
+Alex wants deeper context on how Stagent fits into the broader shift to AI-native work. The Living Book is built into the sidebar under the **Learn** group.
+
+![AI Native Book — chapter list with reading progress](../screengrabs/book-list.png)
+
+1. Click **AI Native Book** in the sidebar under the **Learn** group to open the chapter list
+2. Scan the table of contents — chapters are organised from foundational concepts (From Hierarchy to Intelligence) through advanced topics (Autonomous Organization, The Road Ahead)
+3. Pick a reading path that matches your current focus:
+   - **Newcomer path** — start with the intro chapters on the AI-native blueprint and refinery
+   - **Practitioner path** — jump straight to the chapters on workflow orchestration, scheduled intelligence, and human-in-the-loop
+   - **Visionary path** — skip ahead to agent self-improvement, multi-agent swarms, and the governance layer
+4. As you read, the book merges content updates on each upgrade — new chapters and revisions appear automatically when you pull the latest release, so the book stays in sync with the product
+5. Reading progress persists per chapter, so you can dip in and out without losing your place
+
+> **Tip:** The book treats every example project as a case study — when you see a workflow or schedule described in a chapter, try building the same thing in your own workspace to anchor the idea in muscle memory.
+
+### Step 16: What's Next
 
 Alex now has a solid foundation: a project, organized tasks on a kanban board, a heartbeat schedule for proactive monitoring, and Telegram notifications for staying connected on the go. Here is where to go from here: