stagent 0.9.5 → 0.10.0

package/README.md

@@ -39,47 +39,6 @@ The AI agent stack is broken for business operators. You can spin up an agent in
 
 ---
 
-## Community & Premium Editions
-
-Stagent is **free and fully functional** as a local-first tool. The Community Edition (Apache 2.0) includes everything you need to run AI agents, workflows, and schedules on your machine. Premium tiers add cloud sync, expanded limits, marketplace access, and analytics for power users and teams.
-
-### Feature Comparison
-
-| Capability | Community (Free) | Premium |
-|---|---|---|
-| Local tasks & workflows | Unlimited | Unlimited |
-| Agent profiles | All built-in | All built-in |
-| Human-in-the-loop approval | Full | Full |
-| Agent memories per profile | 50 | 200 - Unlimited |
-| Learned context versions | 10 | 50 - Unlimited |
-| Active schedules | 5 | 20 - Unlimited |
-| History retention | 30 days | 180 days - Unlimited |
-| Cloud sync & backup | — | Solo and above |
-| Marketplace blueprints | Browse only | Import & Publish |
-| Outcome analytics | — | Operator and above |
-
-### Soft Limits
-
-| Resource | Community Limit | At Limit |
-|---|---|---|
-| Agent memories | 50 per profile | New writes blocked, existing preserved |
-| Context versions | 10 per profile | New proposals blocked |
-| Active schedules | 5 | New schedule creation returns 402 |
-| Task history | 30 days | Older entries pruned daily |
-
-### Pricing
-
-| Tier | Price | Best For |
-|---|---|---|
-| Community | Free forever | Individual developers, evaluation |
-| Solo | $19/mo | Power users, expanded limits |
-| Operator | $49/mo | Professionals, analytics, cloud sync |
-| Scale | $99/mo | Teams, marketplace publishing, unlimited |
-
-[Get Premium →](https://stagent.io/pricing)
-
----
-
 ## Runtime Bridge
 
 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.
@@ -123,7 +82,11 @@ Run the same business process on different AI providers without changing a line
 
 ## Architecture
 
-<img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/architecture.svg" alt="Stagent architecture diagram" width="900" />
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/architecture-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/architecture-light.svg">
+  <img src="https://raw.githubusercontent.com/navam-io/stagent/main/public/readme/architecture-light.svg" alt="Stagent architecture diagram" width="900" />
+</picture>
 
 **Key design decisions:**
 

package/dist/cli.js

@@ -130,8 +130,8 @@ var STAGENT_TABLES = [
   "user_table_triggers",
   "user_table_row_history",
   "snapshots",
-  "license",
-  "workflow_execution_stats"
+  "workflow_execution_stats",
+  "schedule_firing_metrics"
 ];
 function bootstrapStagentDatabase(sqlite2) {
   sqlite2.exec(`
@@ -175,6 +175,7 @@ function bootstrapStagentDatabase(sqlite2) {
       status TEXT DEFAULT 'draft' NOT NULL,
       run_number INTEGER DEFAULT 0 NOT NULL,
       runtime_id TEXT,
+      resume_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
@@ -276,6 +277,32 @@ function bootstrapStagentDatabase(sqlite2) {
     CREATE INDEX IF NOT EXISTS idx_schedules_next_fire_at ON schedules(next_fire_at);
     CREATE INDEX IF NOT EXISTS idx_schedules_project_id ON schedules(project_id);
 
+    -- schedule_firing_metrics is placed here (between schedules indexes and
+    -- notifications indexes) to satisfy its foreign-key dependency on schedules.
+    -- Future tables with FK dependencies should follow the same "place after
+    -- parent table" discipline rather than batching all CREATE TABLE at the top.
+    CREATE TABLE IF NOT EXISTS schedule_firing_metrics (
+      id TEXT PRIMARY KEY NOT NULL,
+      schedule_id TEXT NOT NULL,
+      task_id TEXT,
+      fired_at INTEGER NOT NULL,
+      slot_claimed_at INTEGER,
+      completed_at INTEGER,
+      slot_wait_ms INTEGER,
+      duration_ms INTEGER,
+      turn_count INTEGER,
+      max_turns_at_firing INTEGER,
+      event_loop_lag_ms REAL,
+      peak_rss_mb INTEGER,
+      chat_streams_active INTEGER,
+      concurrent_schedules INTEGER,
+      failure_reason TEXT,
+      FOREIGN KEY (schedule_id) REFERENCES schedules(id) ON UPDATE NO ACTION ON DELETE NO ACTION,
+      FOREIGN KEY (task_id) REFERENCES tasks(id) ON UPDATE NO ACTION ON DELETE NO ACTION
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_sfm_schedule_time ON schedule_firing_metrics(schedule_id, fired_at);
+
     CREATE INDEX IF NOT EXISTS idx_notifications_task_id ON notifications(task_id);
     CREATE INDEX IF NOT EXISTS idx_notifications_read ON notifications(read);
     CREATE INDEX IF NOT EXISTS idx_documents_task_id ON documents(task_id);
@@ -344,6 +371,7 @@ function bootstrapStagentDatabase(sqlite2) {
 
     CREATE INDEX IF NOT EXISTS idx_views_surface ON views(surface);
     CREATE INDEX IF NOT EXISTS idx_views_surface_default ON views(surface, is_default);
+
   `);
   const addColumnIfMissing = (ddl) => {
     try {
@@ -380,6 +408,7 @@ function bootstrapStagentDatabase(sqlite2) {
   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;`);
+  addColumnIfMissing(`ALTER TABLE workflows ADD COLUMN resume_at INTEGER;`);
   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(`
@@ -605,6 +634,15 @@ function bootstrapStagentDatabase(sqlite2) {
   addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN failure_streak INTEGER DEFAULT 0 NOT NULL;`);
   addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN last_failure_reason TEXT;`);
   addColumnIfMissing(`ALTER TABLE channel_configs ADD COLUMN direction TEXT DEFAULT 'outbound' NOT NULL;`);
+  addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN slot_claimed_at INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN lease_expires_at INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN failure_reason TEXT;`);
+  addColumnIfMissing(`ALTER TABLE tasks ADD COLUMN max_turns INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN max_turns INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN max_turns_set_at INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN max_run_duration_sec INTEGER;`);
+  addColumnIfMissing(`ALTER TABLE schedules ADD COLUMN turn_budget_breach_streak INTEGER DEFAULT 0 NOT NULL;`);
+  sqlite2.exec(`CREATE INDEX IF NOT EXISTS idx_tasks_running_scheduled ON tasks(status, source_type, lease_expires_at);`);
   sqlite2.exec(`
     CREATE TABLE IF NOT EXISTS channel_bindings (
       id TEXT PRIMARY KEY NOT NULL,
@@ -902,21 +940,6 @@ function bootstrapStagentDatabase(sqlite2) {
     CREATE INDEX IF NOT EXISTS idx_snapshots_type ON snapshots(type);
     CREATE INDEX IF NOT EXISTS idx_snapshots_created_at ON snapshots(created_at);
 
-    CREATE TABLE IF NOT EXISTS license (
-      id TEXT PRIMARY KEY NOT NULL,
-      supabase_user_id TEXT,
-      tier TEXT DEFAULT 'community' NOT NULL,
-      status TEXT DEFAULT 'inactive' NOT NULL,
-      email TEXT,
-      activated_at INTEGER,
-      expires_at INTEGER,
-      last_validated_at INTEGER,
-      grace_period_expires_at INTEGER,
-      encrypted_token TEXT,
-      created_at INTEGER NOT NULL,
-      updated_at INTEGER NOT NULL
-    );
-
     CREATE TABLE IF NOT EXISTS workflow_execution_stats (
       id TEXT PRIMARY KEY,
       pattern TEXT NOT NULL,
@@ -1010,7 +1033,8 @@ Examples:
   node dist/cli.js --data-dir ~/.stagent-dogfood --port 3100
 `;
 }
-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();
+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");
+program.parse();
 var opts = program.opts();
 if (opts.dataDir) {
   process.env.STAGENT_DATA_DIR = opts.dataDir;

package/docs/.coverage-gaps.json

@@ -1,71 +1,29 @@
 {
-  "generated": "2026-04-03T23:30:00Z",
+  "generated": "2026-04-08T20:00:00Z",
   "summary": {
-    "totalFeatures": 82,
-    "coveredFeatures": 78,
-    "gapCount": 4,
+    "totalFeatures": 86,
+    "coveredFeatures": 85,
+    "gapCount": 1,
     "unusedScreenshotCount": 0,
     "brokenReferences": 0,
-    "orphanedImages": 14
+    "orphanedImages": 0
   },
   "gaps": [
-    {
-      "feature": "book-content-merge",
-      "category": "Living Book",
-      "screenshots": ["book-list.png"],
-      "journeyCoverage": [],
-      "suggestedPersona": "personal",
-      "note": "Book reader captured but not referenced in any journey"
-    },
-    {
-      "feature": "book-reading-paths",
-      "category": "Living Book",
-      "screenshots": ["book-list.png"],
-      "journeyCoverage": [],
-      "suggestedPersona": "personal",
-      "note": "Book navigation not in any journey"
-    },
     {
       "feature": "tables-document-import",
       "category": "Structured Data",
       "screenshots": [],
       "journeyCoverage": ["work-use"],
       "suggestedPersona": "work",
-      "note": "Import wizard not captured (no dedicated screenshot) but tables mentioned in Work journey"
-    },
-    {
-      "feature": "database-snapshot-backup",
-      "category": "Platform",
-      "screenshots": ["settings-snapshots.png"],
-      "journeyCoverage": [],
-      "suggestedPersona": "developer",
-      "note": "New feature - settings snapshot card captured, not yet in any journey"
+      "note": "Import wizard has no dedicated screenshot. The feature is referenced narratively in the Work journey at Step 7, but a dedicated capture is blocked by the Tables list being empty (no seed data). Residual gap — revisit after seeding sample tables."
     }
   ],
-  "brokenReferences": [
-    { "file": "developer.md", "screenshot": "settings-ollama-connected.png", "status": "STALE", "note": "Old screenshot in public/readme/, not in current screengrabs/" },
-    { "file": "developer.md", "screenshot": "settings-channels-add-form.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "developer.md", "screenshot": "settings-channels-telegram-form.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "developer.md", "screenshot": "settings-channels-webhook-form.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "developer.md", "screenshot": "chat-conversation.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "developer.md", "screenshot": "schedules-detail.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "personal-use.md", "screenshot": "dashboard-card-detail.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "personal-use.md", "screenshot": "settings-channels.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "power-user.md", "screenshot": "settings-ollama-connected.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "power-user.md", "screenshot": "chat-model-selector.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "power-user.md", "screenshot": "schedules-detail.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "power-user.md", "screenshot": "chat-create-tab.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "work-use.md", "screenshot": "chat-conversation.png", "status": "STALE", "note": "Old screenshot in public/readme/" },
-    { "file": "work-use.md", "screenshot": "settings-channels.png", "status": "STALE", "note": "Old screenshot in public/readme/" }
-  ],
-  "orphanedImages": [
-    "book-chapter-header.png", "book-chapter-nav.png", "book-reader.png",
-    "book-settings.png", "book-toc.png", "book-try-it-now.png",
-    "chat-conversation.png", "chat-create-tab.png", "chat-model-selector.png",
-    "chat-quick-access.png", "dashboard-card-detail.png", "playbook-list.png",
-    "schedules-detail.png", "schedules-edit-form.png", "settings-browser-tools.png",
-    "settings-channels-add-form.png", "settings-channels-telegram-form.png",
-    "settings-channels-webhook-form.png", "settings-channels.png",
-    "settings-ollama-connected.png"
+  "brokenReferences": [],
+  "orphanedImages": [],
+  "notes": [
+    "Closed 3 of 4 prior gaps: book-content-merge, book-reading-paths, database-snapshot-backup.",
+    "Closed 14 prior broken references — journey docs now reference only fixtures that exist in public/readme/.",
+    "Cleared 20 orphaned images by overwriting public/readme/ with the fresh screengrab set.",
+    "Added 4 new feature entries to reflect schedule-orchestration-v2, workflow-step-delays, bulk-row-enrichment, instance-bootstrap/upgrade-session/license-metering."
   ]
 }

package/docs/.last-generated

@@ -1 +1 @@
-2026-04-03T23:43:05Z
+2026-04-08T20:00:00Z

package/docs/features/provider-runtimes.md

@@ -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
 

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-08"
 ---
 
 # 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.
+
+### 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/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-08"
 ---
 
 # Tables
@@ -114,6 +114,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/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"]
+screengrabCount: 4
+lastUpdated: "2026-04-08"
 ---
 
 # 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

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-08"
 ---
 
 # Developer Guide
@@ -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.

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-08"
 ---
 
 # Personal Use Guide
@@ -205,7 +205,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: