stagent 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (276) hide show
  1. package/README.md +67 -31
  2. package/dist/cli.js +151 -2
  3. package/docs/.coverage-gaps.json +21 -0
  4. package/docs/.last-generated +1 -1
  5. package/docs/features/agent-intelligence.md +36 -14
  6. package/docs/features/chat.md +53 -71
  7. package/docs/features/cost-usage.md +14 -10
  8. package/docs/features/dashboard-kanban.md +30 -13
  9. package/docs/features/delivery-channels.md +198 -0
  10. package/docs/features/design-system.md +10 -10
  11. package/docs/features/documents.md +8 -8
  12. package/docs/features/home-workspace.md +20 -15
  13. package/docs/features/inbox-notifications.md +22 -10
  14. package/docs/features/keyboard-navigation.md +11 -11
  15. package/docs/features/monitoring.md +1 -1
  16. package/docs/features/playbook.md +30 -32
  17. package/docs/features/profiles.md +33 -11
  18. package/docs/features/projects.md +2 -2
  19. package/docs/features/provider-runtimes.md +58 -14
  20. package/docs/features/schedules.md +77 -41
  21. package/docs/features/settings.md +134 -51
  22. package/docs/features/shared-components.md +7 -15
  23. package/docs/features/tool-permissions.md +9 -9
  24. package/docs/features/workflows.md +32 -21
  25. package/docs/getting-started.md +33 -9
  26. package/docs/index.md +25 -16
  27. package/docs/journeys/developer.md +124 -207
  28. package/docs/journeys/personal-use.md +70 -79
  29. package/docs/journeys/power-user.md +107 -151
  30. package/docs/journeys/work-use.md +81 -113
  31. package/docs/manifest.json +79 -47
  32. package/docs/superpowers/plans/2026-03-30-finish-in-progress-features.md +547 -0
  33. package/docs/superpowers/specs/2026-03-27-chat-screenshot-display-design.md +303 -0
  34. package/docs/use-cases/agency-operator.md +84 -0
  35. package/docs/use-cases/solo-founder.md +75 -0
  36. package/docs/why-stagent.md +59 -0
  37. package/package.json +12 -3
  38. package/src/app/api/channels/[id]/route.ts +103 -0
  39. package/src/app/api/channels/[id]/test/route.ts +52 -0
  40. package/src/app/api/channels/inbound/slack/route.ts +109 -0
  41. package/src/app/api/channels/inbound/telegram/poll/route.ts +128 -0
  42. package/src/app/api/channels/inbound/telegram/route.ts +76 -0
  43. package/src/app/api/channels/route.ts +71 -0
  44. package/src/app/api/chat/conversations/[id]/messages/route.ts +3 -2
  45. package/src/app/api/chat/conversations/route.ts +15 -0
  46. package/src/app/api/chat/entities/search/route.ts +112 -0
  47. package/src/app/api/documents/[id]/file/route.ts +4 -1
  48. package/src/app/api/environment/profiles/suggest/route.ts +19 -3
  49. package/src/app/api/environment/scan/route.ts +8 -1
  50. package/src/app/api/handoffs/[id]/route.ts +76 -0
  51. package/src/app/api/handoffs/route.ts +89 -0
  52. package/src/app/api/memory/route.ts +181 -0
  53. package/src/app/api/profiles/[id]/route.ts +16 -1
  54. package/src/app/api/profiles/[id]/test/route.ts +4 -0
  55. package/src/app/api/profiles/[id]/test-results/route.ts +22 -0
  56. package/src/app/api/profiles/[id]/test-single/route.ts +64 -0
  57. package/src/app/api/profiles/assist/route.ts +35 -0
  58. package/src/app/api/profiles/import-repo/apply-updates/route.ts +123 -0
  59. package/src/app/api/profiles/import-repo/check-updates/route.ts +163 -0
  60. package/src/app/api/profiles/import-repo/confirm/route.ts +118 -0
  61. package/src/app/api/profiles/import-repo/preview/route.ts +107 -0
  62. package/src/app/api/profiles/import-repo/route.ts +29 -0
  63. package/src/app/api/profiles/import-repo/scan/route.ts +25 -0
  64. package/src/app/api/profiles/route.ts +73 -22
  65. package/src/app/api/projects/[id]/route.ts +119 -9
  66. package/src/app/api/projects/__tests__/delete-project.test.ts +170 -0
  67. package/src/app/api/runtimes/ollama/route.ts +86 -0
  68. package/src/app/api/runtimes/suggest/route.ts +29 -0
  69. package/src/app/api/schedules/[id]/heartbeat-history/route.ts +77 -0
  70. package/src/app/api/schedules/[id]/route.ts +41 -3
  71. package/src/app/api/schedules/parse/route.ts +66 -0
  72. package/src/app/api/schedules/route.ts +71 -12
  73. package/src/app/api/settings/author-default/route.ts +7 -0
  74. package/src/app/api/settings/browser-tools/route.ts +68 -0
  75. package/src/app/api/settings/learning/route.ts +41 -0
  76. package/src/app/api/settings/ollama/route.ts +34 -0
  77. package/src/app/api/settings/providers/route.ts +57 -0
  78. package/src/app/api/settings/routing/route.ts +24 -0
  79. package/src/app/api/settings/web-search/route.ts +28 -0
  80. package/src/app/api/tasks/[id]/execute/route.ts +13 -1
  81. package/src/app/documents/page.tsx +3 -0
  82. package/src/app/environment/page.tsx +8 -1
  83. package/src/app/settings/page.tsx +12 -4
  84. package/src/app/workflows/[id]/edit/page.tsx +2 -0
  85. package/src/app/workflows/new/page.tsx +2 -0
  86. package/src/components/chat/chat-command-popover.tsx +280 -0
  87. package/src/components/chat/chat-input.tsx +90 -10
  88. package/src/components/chat/chat-message.tsx +9 -3
  89. package/src/components/chat/chat-model-selector.tsx +42 -1
  90. package/src/components/chat/chat-shell.tsx +31 -5
  91. package/src/components/chat/screenshot-gallery.tsx +96 -0
  92. package/src/components/dashboard/welcome-landing.tsx +9 -9
  93. package/src/components/environment/artifact-card.tsx +27 -1
  94. package/src/components/environment/environment-dashboard.tsx +50 -2
  95. package/src/components/environment/environment-summary-card.tsx +5 -2
  96. package/src/components/environment/suggested-profiles.tsx +117 -52
  97. package/src/components/handoffs/handoff-approval-card.tsx +159 -0
  98. package/src/components/memory/memory-browser.tsx +315 -0
  99. package/src/components/monitoring/log-entry.tsx +61 -27
  100. package/src/components/profiles/learned-context-panel.tsx +4 -4
  101. package/src/components/profiles/profile-assist-panel.tsx +512 -0
  102. package/src/components/profiles/profile-browser.tsx +109 -8
  103. package/src/components/profiles/profile-card.tsx +29 -1
  104. package/src/components/profiles/profile-detail-view.tsx +200 -28
  105. package/src/components/profiles/profile-form-view.tsx +220 -82
  106. package/src/components/profiles/repo-import-wizard.tsx +648 -0
  107. package/src/components/profiles/smoke-test-editor.tsx +106 -0
  108. package/src/components/projects/project-detail.tsx +15 -2
  109. package/src/components/schedules/schedule-create-sheet.tsx +32 -330
  110. package/src/components/schedules/schedule-detail-sheet.tsx +37 -21
  111. package/src/components/schedules/schedule-edit-sheet.tsx +159 -0
  112. package/src/components/schedules/schedule-form.tsx +749 -0
  113. package/src/components/schedules/schedule-list.tsx +31 -2
  114. package/src/components/settings/auth-method-selector.tsx +7 -1
  115. package/src/components/settings/browser-tools-section.tsx +247 -0
  116. package/src/components/settings/budget-guardrails-section.tsx +111 -48
  117. package/src/components/settings/channels-section.tsx +526 -0
  118. package/src/components/settings/chat-settings-section.tsx +27 -1
  119. package/src/components/settings/data-management-section.tsx +8 -6
  120. package/src/components/settings/learning-context-section.tsx +124 -0
  121. package/src/components/settings/ollama-section.tsx +270 -0
  122. package/src/components/settings/providers-runtimes-section.tsx +499 -0
  123. package/src/components/settings/runtime-timeout-section.tsx +4 -4
  124. package/src/components/settings/web-search-section.tsx +101 -0
  125. package/src/components/shared/command-palette.tsx +1 -30
  126. package/src/components/shared/screenshot-lightbox.tsx +151 -0
  127. package/src/components/shared/tag-input.tsx +156 -0
  128. package/src/components/tasks/kanban-board.tsx +32 -0
  129. package/src/components/tasks/kanban-column.tsx +4 -2
  130. package/src/components/tasks/task-card.tsx +1 -0
  131. package/src/components/tasks/task-chip-bar.tsx +6 -1
  132. package/src/components/tasks/task-create-panel.tsx +55 -5
  133. package/src/components/workflows/workflow-form-view.tsx +38 -3
  134. package/src/hooks/use-caret-position.ts +104 -0
  135. package/src/hooks/use-chat-autocomplete.ts +288 -0
  136. package/src/hooks/use-project-skills.ts +66 -0
  137. package/src/hooks/use-tag-suggestions.ts +31 -0
  138. package/src/instrumentation.ts +4 -1
  139. package/src/lib/agents/__tests__/browser-mcp.test.ts +175 -0
  140. package/src/lib/agents/__tests__/claude-agent.test.ts +6 -0
  141. package/src/lib/agents/__tests__/learned-context.test.ts +10 -0
  142. package/src/lib/agents/agentic-loop.ts +235 -0
  143. package/src/lib/agents/browser-mcp.ts +174 -0
  144. package/src/lib/agents/claude-agent.ts +83 -198
  145. package/src/lib/agents/handoff/bus.ts +164 -0
  146. package/src/lib/agents/handoff/governance.ts +47 -0
  147. package/src/lib/agents/handoff/types.ts +16 -0
  148. package/src/lib/agents/learned-context.ts +27 -7
  149. package/src/lib/agents/memory/decay.ts +61 -0
  150. package/src/lib/agents/memory/extractor.ts +181 -0
  151. package/src/lib/agents/memory/retrieval.ts +96 -0
  152. package/src/lib/agents/memory/types.ts +6 -0
  153. package/src/lib/agents/profiles/__tests__/project-profiles.test.ts +119 -0
  154. package/src/lib/agents/profiles/__tests__/registry.test.ts +11 -3
  155. package/src/lib/agents/profiles/builtins/code-reviewer/profile.yaml +2 -2
  156. package/src/lib/agents/profiles/builtins/content-creator/SKILL.md +19 -0
  157. package/src/lib/agents/profiles/builtins/content-creator/profile.yaml +27 -0
  158. package/src/lib/agents/profiles/builtins/customer-support-agent/SKILL.md +19 -0
  159. package/src/lib/agents/profiles/builtins/customer-support-agent/profile.yaml +26 -0
  160. package/src/lib/agents/profiles/builtins/data-analyst/profile.yaml +2 -2
  161. package/src/lib/agents/profiles/builtins/devops-engineer/profile.yaml +2 -2
  162. package/src/lib/agents/profiles/builtins/document-writer/profile.yaml +2 -2
  163. package/src/lib/agents/profiles/builtins/financial-analyst/SKILL.md +19 -0
  164. package/src/lib/agents/profiles/builtins/financial-analyst/profile.yaml +24 -0
  165. package/src/lib/agents/profiles/builtins/general/profile.yaml +2 -2
  166. package/src/lib/agents/profiles/builtins/health-fitness-coach/profile.yaml +2 -2
  167. package/src/lib/agents/profiles/builtins/learning-coach/profile.yaml +2 -2
  168. package/src/lib/agents/profiles/builtins/marketing-strategist/SKILL.md +19 -0
  169. package/src/lib/agents/profiles/builtins/marketing-strategist/profile.yaml +27 -0
  170. package/src/lib/agents/profiles/builtins/operations-coordinator/SKILL.md +19 -0
  171. package/src/lib/agents/profiles/builtins/operations-coordinator/profile.yaml +26 -0
  172. package/src/lib/agents/profiles/builtins/project-manager/profile.yaml +2 -2
  173. package/src/lib/agents/profiles/builtins/researcher/SKILL.md +1 -0
  174. package/src/lib/agents/profiles/builtins/researcher/profile.yaml +2 -2
  175. package/src/lib/agents/profiles/builtins/sales-researcher/SKILL.md +19 -0
  176. package/src/lib/agents/profiles/builtins/sales-researcher/profile.yaml +26 -0
  177. package/src/lib/agents/profiles/builtins/shopping-assistant/SKILL.md +1 -0
  178. package/src/lib/agents/profiles/builtins/shopping-assistant/profile.yaml +2 -2
  179. package/src/lib/agents/profiles/builtins/sweep/profile.yaml +1 -1
  180. package/src/lib/agents/profiles/builtins/technical-writer/profile.yaml +2 -2
  181. package/src/lib/agents/profiles/builtins/travel-planner/SKILL.md +2 -0
  182. package/src/lib/agents/profiles/builtins/travel-planner/profile.yaml +2 -2
  183. package/src/lib/agents/profiles/builtins/wealth-manager/SKILL.md +2 -0
  184. package/src/lib/agents/profiles/builtins/wealth-manager/profile.yaml +2 -2
  185. package/src/lib/agents/profiles/project-profiles.ts +193 -0
  186. package/src/lib/agents/profiles/registry.ts +130 -6
  187. package/src/lib/agents/profiles/types.ts +28 -0
  188. package/src/lib/agents/router.ts +174 -2
  189. package/src/lib/agents/runtime/__tests__/catalog.test.ts +15 -4
  190. package/src/lib/agents/runtime/anthropic-direct.ts +644 -0
  191. package/src/lib/agents/runtime/catalog.ts +57 -2
  192. package/src/lib/agents/runtime/claude.ts +205 -1
  193. package/src/lib/agents/runtime/index.ts +22 -0
  194. package/src/lib/agents/runtime/ollama-adapter.ts +409 -0
  195. package/src/lib/agents/runtime/openai-direct.ts +514 -0
  196. package/src/lib/agents/runtime/profile-assist-types.ts +30 -0
  197. package/src/lib/agents/runtime/types.ts +2 -0
  198. package/src/lib/agents/tool-permissions.ts +203 -0
  199. package/src/lib/channels/gateway.ts +321 -0
  200. package/src/lib/channels/poller.ts +268 -0
  201. package/src/lib/channels/registry.ts +90 -0
  202. package/src/lib/channels/slack-adapter.ts +188 -0
  203. package/src/lib/channels/telegram-adapter.ts +218 -0
  204. package/src/lib/channels/types.ts +43 -0
  205. package/src/lib/channels/webhook-adapter.ts +74 -0
  206. package/src/lib/chat/command-data.ts +50 -0
  207. package/src/lib/chat/context-builder.ts +147 -3
  208. package/src/lib/chat/engine.ts +182 -19
  209. package/src/lib/chat/ollama-engine.ts +198 -0
  210. package/src/lib/chat/slash-commands.ts +191 -0
  211. package/src/lib/chat/stagent-tools.ts +106 -20
  212. package/src/lib/chat/tool-catalog.ts +209 -0
  213. package/src/lib/chat/tool-registry.ts +90 -0
  214. package/src/lib/chat/tools/chat-history-tools.ts +4 -4
  215. package/src/lib/chat/tools/document-tools.ts +43 -6
  216. package/src/lib/chat/tools/handoff-tools.ts +70 -0
  217. package/src/lib/chat/tools/notification-tools.ts +4 -4
  218. package/src/lib/chat/tools/profile-tools.ts +3 -3
  219. package/src/lib/chat/tools/project-tools.ts +3 -3
  220. package/src/lib/chat/tools/schedule-tools.ts +29 -13
  221. package/src/lib/chat/tools/settings-tools.ts +2 -2
  222. package/src/lib/chat/tools/task-tools.ts +66 -11
  223. package/src/lib/chat/tools/usage-tools.ts +2 -2
  224. package/src/lib/chat/tools/workflow-tools.ts +8 -8
  225. package/src/lib/chat/types.ts +22 -6
  226. package/src/lib/constants/known-tools.ts +19 -0
  227. package/src/lib/constants/prose-styles.ts +1 -1
  228. package/src/lib/constants/settings.ts +11 -0
  229. package/src/lib/data/channel-bindings.ts +85 -0
  230. package/src/lib/data/clear.ts +38 -4
  231. package/src/lib/data/profile-test-results.ts +48 -0
  232. package/src/lib/data/seed-data/conversations.ts +196 -0
  233. package/src/lib/data/seed-data/learned-context.ts +99 -0
  234. package/src/lib/data/seed-data/notifications.ts +54 -1
  235. package/src/lib/data/seed-data/profile-test-results.ts +96 -0
  236. package/src/lib/data/seed-data/repo-imports.ts +51 -0
  237. package/src/lib/data/seed-data/views.ts +60 -0
  238. package/src/lib/data/seed.ts +51 -0
  239. package/src/lib/db/bootstrap.ts +167 -0
  240. package/src/lib/db/migrations/0012_add_screenshot_columns.sql +5 -0
  241. package/src/lib/db/migrations/0013_add_repo_imports.sql +15 -0
  242. package/src/lib/db/migrations/0014_add_linked_profile_id.sql +3 -0
  243. package/src/lib/db/migrations/0015_add_channel_bindings.sql +23 -0
  244. package/src/lib/db/schema.ts +192 -1
  245. package/src/lib/environment/__tests__/auto-scan.test.ts +86 -0
  246. package/src/lib/environment/__tests__/profile-linker.test.ts +187 -0
  247. package/src/lib/environment/auto-scan.ts +48 -0
  248. package/src/lib/environment/data.ts +25 -0
  249. package/src/lib/environment/profile-generator.ts +40 -10
  250. package/src/lib/environment/profile-linker.ts +143 -0
  251. package/src/lib/environment/profile-rules.ts +96 -0
  252. package/src/lib/import/dedup.ts +149 -0
  253. package/src/lib/import/format-adapter.ts +631 -0
  254. package/src/lib/import/github-api.ts +219 -0
  255. package/src/lib/import/repo-scanner.ts +251 -0
  256. package/src/lib/schedules/__tests__/nlp-parser.test.ts +330 -0
  257. package/src/lib/schedules/active-hours.ts +120 -0
  258. package/src/lib/schedules/heartbeat-parser.ts +224 -0
  259. package/src/lib/schedules/heartbeat-prompt.ts +153 -0
  260. package/src/lib/schedules/nlp-parser.ts +357 -0
  261. package/src/lib/schedules/scheduler.ts +218 -3
  262. package/src/lib/screenshots/__tests__/persist.test.ts +104 -0
  263. package/src/lib/screenshots/persist.ts +114 -0
  264. package/src/lib/settings/__tests__/budget-guardrails.test.ts +39 -1
  265. package/src/lib/settings/helpers.ts +6 -0
  266. package/src/lib/settings/routing.ts +24 -0
  267. package/src/lib/settings/runtime-setup.ts +28 -1
  268. package/src/lib/usage/ledger.ts +2 -1
  269. package/src/lib/utils/stagent-paths.ts +4 -0
  270. package/src/lib/validators/__tests__/settings.test.ts +9 -0
  271. package/src/lib/validators/profile.ts +39 -0
  272. package/src/lib/workflows/blueprints/builtins/business-daily-briefing.yaml +102 -0
  273. package/src/lib/workflows/blueprints/builtins/content-marketing-pipeline.yaml +90 -0
  274. package/src/lib/workflows/blueprints/builtins/customer-support-triage.yaml +107 -0
  275. package/src/lib/workflows/blueprints/builtins/financial-reporting.yaml +104 -0
  276. package/src/lib/workflows/blueprints/builtins/lead-research-pipeline.yaml +82 -0
@@ -4,245 +4,201 @@ category: "user-journey"
4
4
  persona: "power-user"
5
5
  difficulty: "advanced"
6
6
  estimatedTime: "30 minutes"
7
- sections: ["dashboard-kanban", "profiles", "chat", "workflows", "schedules", "monitoring"]
8
- tags: ["advanced", "automation", "workflows", "profiles", "schedules", "monitoring", "bulk-operations"]
9
- lastUpdated: "2026-03-22"
7
+ sections: ["dashboard-kanban", "profiles", "chat", "workflows", "schedules", "monitoring", "settings"]
8
+ tags: ["advanced", "automation", "workflows", "profiles", "schedules", "monitoring", "bulk-operations", "ollama", "episodic-memory", "nlp-scheduling"]
9
+ lastUpdated: "2026-03-31"
10
10
  ---
11
11
 
12
12
  # Power User Guide
13
13
 
14
- Meet Sam, a DevOps engineer who automates everything that can be automated -- and most things that people assume cannot. Sam has already completed the Personal Use Guide and runs Stagent daily for task management. Now Sam is ready to go deeper: specialized agent profiles, multi-step workflow pipelines, scheduled autonomous loops, bulk operations, and real-time monitoring. This guide covers the advanced automation layer that transforms Stagent from a task manager into a hands-off operations engine.
14
+ Meet Sam, a DevOps engineer who automates everything that can be automated. Sam has already completed the Personal Use Guide and runs Stagent daily as an AI business operating system. Now Sam is ready to go deeper: specialized agent profiles, multi-step workflow pipelines, NLP-driven scheduling, Ollama local models, episodic memory, bulk operations, and real-time monitoring. This guide covers the advanced automation layer that puts entire business processes on autopilot.
15
15
 
16
16
  ## Prerequisites
17
17
 
18
18
  - Stagent installed and running locally (`npm run dev`)
19
19
  - An Anthropic API key configured in `.env.local`
20
- - Familiarity with basic Stagent concepts (projects, tasks, inbox) -- see [Personal Use Guide](./personal-use.md)
20
+ - Familiarity with basic Stagent concepts (see [Personal Use Guide](./personal-use.md))
21
21
  - At least one project with several completed tasks (agents learn from past context)
22
22
 
23
23
  ## Journey Steps
24
24
 
25
25
  ### Step 1: Master Keyboard Navigation
26
26
 
27
- Sam refuses to reach for the mouse when a keystroke will do. The Command Palette is the nerve center of keyboard-driven navigation -- it searches across every entity in the workspace and launches actions instantly.
27
+ Sam refuses to reach for the mouse when a keystroke will do. The Command Palette is the nerve center of keyboard-driven navigation.
28
28
 
29
29
  ![Command palette overlay showing available commands and navigation](../screengrabs/command-palette-empty.png)
30
30
 
31
- 1. Press **Cmd+K** (Mac) or **Ctrl+K** (Windows/Linux) to open the Command Palette
32
- 2. Without typing anything, scan the **recent items** and **suggested actions** that appear by default
33
- 3. Type a partial name -- "deploy," "nightly," "code review" -- to filter across projects, tasks, workflows, schedules, and pages
34
- 4. Use **arrow keys** to highlight an item and press **Enter** to navigate or execute immediately
35
- 5. Press **Escape** to dismiss the palette and return focus to the current page
31
+ 1. Press **Cmd+K** to open the Command Palette
32
+ 2. Without typing anything, scan the **recent items** and **suggested actions**
33
+ 3. Type a partial name to filter across projects, tasks, workflows, schedules, and pages
34
+ 4. Use **arrow keys** to highlight an item and press **Enter** to navigate or execute
36
35
 
37
- > **Tip:** The Command Palette is contextual. It surfaces results from every section of Stagent, so you never need to remember which sidebar group a feature lives under. Power users open the palette dozens of times per session -- muscle memory for Cmd+K pays for itself on day one.
36
+ > **Tip:** Power users open the palette dozens of times per session -- muscle memory for Cmd+K pays for itself on day one.
38
37
 
39
38
  ### Step 2: Explore Agent Profiles
40
39
 
41
- Before building any automation, Sam reviews the available agent profiles. Each profile shapes an agent's personality, system prompt, and tool permissions for a specific role -- assigning the right profile to the right task is the single biggest lever for output quality.
40
+ Before building any automation, Sam reviews the available agent profiles. The catalog now includes business-function profiles alongside technical ones.
42
41
 
43
- ![Agent profiles grid showing available behavioral profiles with work and personal tabs](../screengrabs/profiles-list.png)
42
+ ![Agent profiles grid showing available behavioral profiles](../screengrabs/profiles-list.png)
44
43
 
45
- 1. Open the Command Palette and type **"Profiles"**, or click **Profiles** in the sidebar under the **Manage** group
46
- 2. Browse the **profile cards** in the grid -- each displays the profile name, a short description, and a capability summary
47
- 3. Switch between the **Work** and **Personal** tabs to see profiles organized by context
48
- 4. Note the built-in profiles:
49
- - **General** -- balanced, all-purpose agent behavior
50
- - **Code Reviewer** -- focused on code quality, security, and best practices
51
- - **Researcher** -- optimized for information gathering and synthesis
52
- - **Document Writer** -- tuned for long-form content generation
44
+ 1. Click **Profiles** in the sidebar under the **Manage** group
45
+ 2. Browse profile cards -- each displays the name, description, runtime badges, and capabilities
46
+ 3. Switch between **Work** and **Personal** tabs
47
+ 4. Note the business-function profiles: Marketing Strategist, Sales Researcher, Customer Support Agent, Financial Analyst, Content Creator, and Operations Coordinator
53
48
  5. Click any profile card to open its full detail page
54
49
 
55
- > **Tip:** Think of profiles the way you think of IAM roles -- least privilege, purpose-fit. A task assigned to the Code Reviewer profile will produce actionable review comments with line references. The same task on the General profile will produce a softer, less specific summary.
50
+ > **Tip:** Think of profiles as IAM roles -- purpose-fit and least privilege. A Financial Analyst profile produces structured reports with proper methodology; the General profile produces softer summaries.
56
51
 
57
52
  ### Step 3: Deep-Dive into Profile Configuration
58
53
 
59
- Sam opens a profile detail page to understand exactly what an agent will do when assigned this profile. The detail view exposes the system prompt, tool permissions, and capability badges that govern agent behavior.
60
-
61
54
  ![Profile detail page showing capabilities, tools, and full configuration](../screengrabs/profiles-detail.png)
62
55
 
63
- 1. From the profiles grid, click a profile card (e.g., **Code Reviewer**) to open the detail page
64
- 2. Read the **system prompt** section -- this is the instruction set the agent receives before every task
65
- 3. Review the **capabilities** list to see which tools and actions the profile permits
66
- 4. Check the **tool permissions** section for any tools that are explicitly allowed or denied
67
- 5. Use the back button or Command Palette to return to the profiles grid
68
-
69
- > **Tip:** When a workflow step produces unexpected output, the profile detail page is the first place to investigate. Nine times out of ten, the system prompt or tool permissions explain the behavior. Small prompt refinements compound across every execution.
56
+ 1. Click a profile card to open the detail page
57
+ 2. Read the **system prompt** section
58
+ 3. Review the **capabilities** list and **tool permissions**
59
+ 4. Check runtime compatibility badges to see which providers the profile supports
60
+ 5. Note that profiles work across all five runtimes (Claude SDK, Codex, Anthropic Direct, OpenAI Direct, Ollama)
70
61
 
71
- ### Step 4: Optimize Chat with Model Selection
62
+ ### Step 4: Connect Ollama for Local Models
72
63
 
73
- Sam uses Chat strategically, switching between models based on query complexity. Model selection is the primary cost optimization lever -- the right model for the right question can cut chat costs dramatically.
74
-
75
- ![Chat model selector dropdown showing available models with cost tier indicators](../screengrabs/chat-model-selector.png)
64
+ Sam wants to run privacy-sensitive tasks on local models with zero API cost.
76
65
 
77
- 1. Navigate to **Chat** in the sidebar under the **Work** group
78
- 2. Click the **model selector** in the input composer area to reveal the dropdown
79
- 3. Review the available models -- each displays a **cost tier indicator** ($ to $$$) alongside the model name
80
- 4. Select **Haiku ($)** for quick factual queries like "list my active schedules" or "how many tasks failed this week"
81
- 5. Switch to **Opus ($$$)** for multi-step reasoning like "analyze the error patterns across my last 10 workflow runs and suggest architectural fixes"
82
- 6. Notice the cost tier badge update as you switch between models
66
+ ![Ollama connected with local models](../screengrabs/settings-ollama-connected.png)
83
67
 
84
- > **Tip:** Haiku is 10-20x cheaper per token than Opus. Sam's rule of thumb: if the answer requires recalling a fact, use Haiku. If the answer requires *thinking*, use Opus. This habit alone can reduce monthly chat spend by 80% without sacrificing quality where it matters.
68
+ 1. Install Ollama from [ollama.com](https://ollama.com) and pull a model: `ollama pull llama3`
69
+ 2. Open **Settings** and scroll to the **Ollama** section
70
+ 3. Click **Test Connection** -- the status shows "Connected" with a list of available models
71
+ 4. Once connected, Ollama models appear in runtime selectors across the workspace
85
72
 
86
- ### Step 5: Use Chat for Complex Queries
73
+ > **Tip:** Ollama executions are tracked at $0 in the cost dashboard. Sam uses Ollama for routine tasks (code formatting, simple summaries) and reserves Claude or GPT for complex reasoning. This habit cuts monthly spend significantly.
87
74
 
88
- Sam sends a query and discovers that Chat responses include Quick Access pills -- interactive links that connect chat answers directly to the entities they reference. No more copy-pasting IDs to look up a task.
75
+ ### Step 5: Optimize Chat with Model Selection
89
76
 
90
- ![Chat message with Quick Access entity navigation pills linking to tasks and projects](../screengrabs/chat-quick-access.png)
77
+ ![Chat model selector dropdown showing available models with cost tier indicators](../screengrabs/chat-model-selector.png)
91
78
 
92
- 1. Type a complex query such as **"Which tasks in the Infrastructure project are blocked, and what's blocking them?"**
93
- 2. Read the agent's response -- it synthesizes information from across your workspace
94
- 3. Notice the **Quick Access pills** embedded in the response -- colored badges that link to specific tasks, projects, or workflows
95
- 4. Click a Quick Access pill to navigate directly to that entity's detail page
96
- 5. Use the browser back button or Command Palette to return to the chat conversation
79
+ 1. Navigate to **Chat** and click the **model selector** in the input area
80
+ 2. Review models with cost tier indicators ($ to $$$)
81
+ 3. Select **Haiku ($)** for quick factual queries
82
+ 4. Switch to **Opus ($$$)** for complex reasoning
83
+ 5. If Ollama is connected, local models appear at $0
97
84
 
98
- > **Tip:** Quick Access pills turn Chat into a navigation hub. Instead of manually browsing the sidebar to find a specific task the agent mentioned, click the pill. Sam often starts a session by asking Chat "what needs my attention today?" and then clicking through the linked entities.
85
+ > **Tip:** Sam's rule of thumb: factual recall = Haiku, thinking = Opus, privacy-sensitive = Ollama. This habit reduces monthly chat spend by 80%.
99
86
 
100
- ### Step 6: Browse Workflow Blueprints
87
+ ### Step 6: Use NLP Scheduling
101
88
 
102
- Sam wants to build a multi-step automation pipeline but does not want to start from scratch. The Blueprint Gallery offers pre-built workflow templates designed for common DevOps patterns.
89
+ Sam creates schedules by describing them in plain English instead of writing cron expressions.
103
90
 
104
- ![Workflow blueprint gallery showing pre-built templates for common automation patterns](../screengrabs/workflows-blueprints.png)
91
+ ![Schedules list with active and heartbeat schedules](../screengrabs/schedules-list.png)
105
92
 
106
- 1. Navigate to **Workflows** in the sidebar under the **Work** group
107
- 2. Click the **Blueprints** tab (or navigate directly to the blueprint gallery)
108
- 3. Browse the available templates -- each blueprint includes a name, description, step count, and recommended profile assignments
109
- 4. Look for templates that match your use case: deploy pipelines, code review chains, research synthesis, documentation generation
110
- 5. Click a blueprint to preview its step configuration before creating a workflow from it
111
- 6. Click **Use Blueprint** to create a new workflow pre-populated with the template's steps
93
+ 1. Navigate to **Schedules** and click **Create Schedule**
94
+ 2. In the interval field, type natural language: "every weekday at 10pm," "every 6 hours during business hours," or "twice daily at 9am and 5pm"
95
+ 3. A **preview** appears showing exactly how the system parsed the input
96
+ 4. Select **Heartbeat** type to add intelligence -- the agent evaluates a checklist before acting
97
+ 5. Add checklist items specific to your automation needs
98
+ 6. Save the schedule
112
99
 
113
- > **Tip:** Blueprints encode best practices. Even if you plan to customize heavily, starting from a blueprint ensures you get the step ordering, dependency chains, and profile assignments right. Sam always starts from a blueprint and then adjusts -- it is faster than building from zero.
100
+ > **Tip:** NLP scheduling removes the friction of cron syntax. If the preview does not match your intent, rephrase and it re-parses instantly.
114
101
 
115
102
  ### Step 7: Build a Multi-Step Workflow
116
103
 
117
- Sam customizes a workflow for a "Deploy & Verify" pipeline -- three steps, each depending on the previous one succeeding, each assigned to the right agent profile.
118
-
119
- ![Workflows list showing existing workflow definitions with tabs for All, Templates, and Runs](../screengrabs/workflows-list.png)
104
+ Sam customizes a workflow for a "Deploy & Verify" pipeline with specialized profiles at each step.
120
105
 
121
- 1. From the Workflows page, click **Create Workflow** (or customize a blueprint from Step 6)
122
- 2. Enter a **Workflow Name** such as "Nightly Deploy & Verify"
123
- 3. Add a description explaining the pipeline's purpose
124
- 4. Configure **Step 1 -- Run Tests**: assign the **Code Reviewer** profile, set the prompt to "Run the full test suite and report failures with root cause analysis"
125
- 5. Configure **Step 2 -- Deploy to Staging**: assign the **General** profile, set dependency on Step 1
126
- 6. Configure **Step 3 -- Verify Deployment**: assign the **Researcher** profile, set dependency on Step 2, prompt it to "Check all critical endpoints and report status"
127
- 7. Save the workflow
106
+ ![Workflows list showing existing workflow definitions](../screengrabs/workflows-list.png)
128
107
 
129
- > **Tip:** Each step in a workflow can use a different agent profile. This is the key insight: match the profile to the step's purpose. Code Reviewer for testing, General for execution, Researcher for verification. Profile specialization across steps is what makes workflows more reliable than running a single general-purpose agent.
108
+ 1. From the Workflows page, click **Create Workflow** (or customize a blueprint)
109
+ 2. Configure steps with different agent profiles at each stage
110
+ 3. Use the business-function profiles for non-technical steps (e.g., Content Creator for documentation, Operations Coordinator for runbook updates)
111
+ 4. Save the workflow
130
112
 
131
113
  ### Step 8: Inspect Workflow Execution
132
114
 
133
- After triggering a run, Sam opens the workflow detail view to track step-by-step progress, inspect outputs, and diagnose any failures in the pipeline.
134
-
135
115
  ![Workflow detail page showing steps, dependency graph, and execution status](../screengrabs/workflows-detail.png)
136
116
 
137
- 1. Click on a workflow (e.g., "Nightly Deploy & Verify") to open the detail view
138
- 2. Review the **step sequence** and dependency chain displayed visually
139
- 3. Check each step's **status indicator** -- queued, running, completed, or failed
140
- 4. Click on a completed step to read its full output and see which tools the agent used
141
- 5. If a step failed, expand its error output to diagnose the issue
142
- 6. Use the **Run Workflow** button to trigger a new execution
143
-
144
- > **Tip:** Independent steps (those without dependencies between them) execute concurrently. Sam designs workflows to maximize parallelism -- if two verification checks do not depend on each other, they run simultaneously and the pipeline finishes faster.
117
+ 1. Click on a workflow to open the detail view
118
+ 2. Review the **step sequence** and dependency chain
119
+ 3. Check each step's **status indicator**
120
+ 4. Click completed steps to read their full output
121
+ 5. Use the **Run Workflow** button to trigger a new execution
145
122
 
146
123
  ### Step 9: Batch-Manage Tasks on the Kanban
147
124
 
148
- Sam switches to the Dashboard to clean up the task board. Bulk select mode lets you queue, reassign, or delete multiple tasks in a single action -- essential when autonomous workflows generate dozens of tasks overnight.
125
+ Sam cleans up the task board using bulk select mode.
149
126
 
150
127
  ![Kanban board in bulk select mode with checkboxes and bulk action toolbar](../screengrabs/dashboard-bulk-select.png)
151
128
 
152
- 1. Navigate to the **Dashboard** (kanban board view)
153
- 2. Click the **Select** button in the toolbar to enter bulk select mode
154
- 3. Check the boxes on multiple task cards across any status column
155
- 4. Use the **bulk action toolbar** that appears at the top to:
156
- - **Queue** selected tasks for agent execution
157
- - **Move** selected tasks to a different status column
158
- - **Delete** selected tasks that are no longer needed
159
- 5. Confirm the bulk action and exit select mode
129
+ 1. Navigate to the **Dashboard** kanban board
130
+ 2. Click **Select** to enter bulk select mode
131
+ 3. Check boxes on multiple task cards across columns
132
+ 4. Use the bulk action toolbar to queue, move, or delete selected tasks
133
+ 5. Confirm and exit select mode
160
134
 
161
- > **Tip:** After a weekend of autonomous loop runs, Sam's first Monday task is always a bulk cleanup. Enter select mode, check all the "completed" tasks that need archiving, and clear the board in one action. Keeping the kanban clean prevents cognitive overload as automation scales.
135
+ > **Tip:** After a weekend of autonomous heartbeat runs, Sam's first Monday task is always a bulk cleanup.
162
136
 
163
137
  ### Step 10: Schedule Automated Prompt Loops
164
138
 
165
- Sam sets up a recurring schedule so the Deploy & Verify workflow runs every evening without manual intervention. Combining workflows with schedules creates fully autonomous operation loops.
166
-
167
- ![Schedules list showing configured recurring jobs with status, frequency, and next firing time](../screengrabs/schedules-list.png)
168
-
169
- 1. Navigate to **Schedules** in the sidebar under the **Manage** group
170
- 2. Click **Create Schedule**
171
- 3. Enter a **Name** such as "Nightly Deploy Pipeline"
172
- 4. Set the **Interval** using natural language: "every day at 10pm" or "every 6 hours"
173
- 5. Link the schedule to the **Nightly Deploy & Verify** workflow
174
- 6. Configure **stop conditions** to prevent runaway execution:
175
- - **Max iterations**: 1 per trigger (each night = one full pipeline run)
176
- - **Timeout**: 30 minutes per iteration
177
- - **Failure threshold**: 1 (pause after first failure for investigation)
178
- 7. Enable the schedule and click **Create**
139
+ ![Schedule detail sheet showing configuration and firing history](../screengrabs/schedules-detail.png)
179
140
 
180
- > **Tip:** Always set at least one stop condition. Sam's rule: max iterations prevents infinite loops, timeout prevents hung agents, and failure threshold prevents burning tokens on a broken pipeline. All three together form a safety net for unattended operation.
141
+ 1. Click on a schedule to open its detail sheet
142
+ 2. Review the **firing history** with timestamps and outcomes (including suppressed heartbeat runs)
143
+ 3. Check the **next firing time**
144
+ 4. Verify stop conditions and delivery channels
145
+ 5. Toggle **Pause/Resume** as needed
181
146
 
182
- ### Step 11: Monitor Schedule Execution
147
+ ### Step 11: Leverage Episodic Memory
183
148
 
184
- Sam checks in on the nightly schedule to verify it fired correctly, review its execution history, and confirm the next scheduled run.
149
+ Sam notices agents are re-researching the same topics. Episodic memory lets agents retain factual knowledge across executions.
185
150
 
186
- ![Schedule detail sheet showing configuration, stop conditions, and firing history](../screengrabs/schedules-detail.png)
151
+ ![Agent monitoring dashboard with execution logs](../screengrabs/monitor-list.png)
187
152
 
188
- 1. From the Schedules list, click on **Nightly Deploy Pipeline** to open the detail sheet
189
- 2. Review the **firing history** -- a list of past executions with timestamps and outcomes
190
- 3. Check the **next firing time** to confirm the schedule is correctly queued
191
- 4. Verify the **stop conditions** are configured as intended
192
- 5. Toggle **Pause/Resume** if you need to temporarily disable the schedule (e.g., during a maintenance window)
193
- 6. Close the detail sheet to return to the schedules list
153
+ 1. Run several tasks with the same profile on related topics
154
+ 2. Open **Monitor** to observe that the agent extracted memory entries during execution
155
+ 3. Memory entries persist -- the agent recalls facts from previous tasks in future executions
156
+ 4. Memories have confidence scores that decay over time, keeping the context window focused on current knowledge
157
+ 5. Visit the memory browser (accessible from the profile detail page) to inspect, edit, or delete stored memories
194
158
 
195
- > **Tip:** Iteration context is a powerful feature for improvement loops. When enabled, each run can reference the previous run's output. For deploy pipelines, this means a failed verification can inform the next deployment attempt -- agents learn from their own history.
159
+ > **Tip:** Episodic memory means a Financial Analyst profile that researches a company once can recall that research in future tasks without re-doing the work. It builds institutional knowledge automatically.
196
160
 
197
161
  ### Step 12: Watch Agent Execution in Real-Time
198
162
 
199
- Sam opens the Monitor section for a unified view of all agent activity across the workspace -- every task execution, workflow step, and scheduled run appears here with full trace logs.
163
+ ![Agent monitoring dashboard showing real-time execution logs](../screengrabs/monitor-list.png)
200
164
 
201
- ![Agent monitoring dashboard showing real-time execution logs and activity feed](../screengrabs/monitor-list.png)
165
+ 1. Click **Monitor** in the sidebar
166
+ 2. Review the execution log showing all recent agent activity
167
+ 3. Filter by project, workflow, or agent profile
168
+ 4. Click entries to expand full execution traces -- tool calls, outputs, token counts, timing
169
+ 5. Watch for error patterns
202
170
 
203
- 1. Click **Monitor** in the sidebar under the **Manage** group
204
- 2. Review the **execution log** showing all recent agent activity in reverse chronological order
205
- 3. Filter by **project**, **workflow**, or **agent profile** to focus on specific activity streams
206
- 4. Click on any log entry to expand the full execution trace -- tool calls, outputs, token counts, and timing
207
- 5. Watch for **error patterns** such as repeated failures on the same tool or profile
208
- 6. Use the monitor to verify that scheduled runs are completing within expected time bounds
209
-
210
- > **Tip:** The Monitor is Sam's operational dashboard. When something goes wrong in an autonomous loop at 3am, the monitor's execution traces are the fastest path to diagnosis. Sam bookmarks this page and checks it first thing every morning.
171
+ > **Tip:** The Monitor is Sam's operational dashboard. When something goes wrong in an autonomous loop at 3am, the execution traces are the fastest path to diagnosis.
211
172
 
212
173
  ### Step 13: Use Chat Suggested Prompts
213
174
 
214
- Sam returns to Chat and discovers the suggested prompts feature -- tabbed categories of pre-written prompts that cover common operations. Instead of typing from scratch, Sam picks a prompt and edits it.
215
-
216
- ![Chat suggested prompts with Create tab selected showing categorized prompt templates](../screengrabs/chat-create-tab.png)
217
-
218
- 1. Navigate to **Chat** (or open a new conversation)
219
- 2. Below the input composer, notice the **suggested prompt tabs** -- categories like Create, Analyze, Manage, and more
220
- 3. Click the **Create** tab to see prompts related to creating new entities (tasks, workflows, schedules)
221
- 4. Click a suggested prompt to populate the input composer with pre-written text
222
- 5. Edit the prompt to match your specific needs, then send it
223
- 6. Try other tabs to discover prompts for analysis, troubleshooting, and status checks
175
+ ![Chat suggested prompts with Create tab selected](../screengrabs/chat-create-tab.png)
224
176
 
225
- > **Tip:** Suggested prompts are not just shortcuts -- they are examples of how to phrase requests for the best agent response. Sam reads through them to learn the phrasing patterns that produce the most useful output, then adapts those patterns for custom queries.
177
+ 1. Navigate to **Chat** and notice the **suggested prompt tabs** (Explore, Create, Debug, Automate)
178
+ 2. Click the **Create** tab to see prompts for creating tasks, workflows, and schedules
179
+ 3. Click a suggested prompt to populate the input
180
+ 4. Edit and send -- these prompts are optimized for the best agent responses
226
181
 
227
- ### Step 14: Chain Workflows and Schedules
182
+ ### Step 14: Chain Everything Together
228
183
 
229
- Sam connects the dots: workflows define *what* to automate, schedules define *when* to automate, and profiles define *how* each step behaves. Chaining all three creates autonomous loops that run, learn, and improve without human intervention.
184
+ Sam connects the dots: profiles define *how*, workflows define *what*, schedules define *when*, Ollama handles the *cheap stuff*, episodic memory provides the *knowledge*, and delivery channels deliver the *results*.
230
185
 
231
186
  ![Workflows list showing automation pipelines ready for scheduling](../screengrabs/workflows-list.png)
232
187
 
233
- 1. Review your existing workflows and identify which ones should run on a schedule
234
- 2. For each workflow, create a corresponding schedule with appropriate intervals and stop conditions
235
- 3. Assign specialized profiles to each workflow step for maximum output quality
236
- 4. Enable **iteration context** on schedules where the agent should learn from previous runs
237
- 5. Set up the Monitor as your oversight layer -- check it daily to catch issues early
238
- 6. Gradually increase automation scope: start with one nightly workflow, then add weekly research sweeps, then continuous monitoring loops
188
+ 1. Review workflows and identify which should run on a schedule
189
+ 2. Create heartbeat schedules with appropriate checklists
190
+ 3. Assign business-function profiles to each step
191
+ 4. Route privacy-sensitive steps to Ollama, complex reasoning to Claude
192
+ 5. Attach Slack or Telegram channels for delivery
193
+ 6. Enable episodic memory for profiles that handle recurring topics
194
+ 7. Set up the Monitor as your oversight layer
239
195
 
240
- > **Tip:** Sam's automation philosophy: start small, observe, then expand. Run a workflow manually three times before scheduling it. Confirm the schedule fires correctly for a week before enabling iteration context. Trust builds incrementally -- and so should autonomy.
196
+ > **Tip:** Sam's automation philosophy: start small, observe, then expand. Run a workflow manually three times before scheduling it. Trust builds incrementally -- and so should autonomy.
241
197
 
242
198
  ### Step 15: What's Next
243
199
 
244
- Sam's Stagent workspace is now a fully autonomous operations engine -- specialized agent profiles handling different task types, multi-step workflows executing complex pipelines, schedules firing on cadence, and the Monitor providing real-time oversight. The next step is going deeper into the platform layer.
200
+ Sam's workspace is a fully autonomous operations engine. The next step is going deeper into the platform layer.
245
201
 
246
- - [Developer Guide](./developer.md) -- Configure authentication methods, runtime settings, CLI tooling, and permission presets
202
+ - [Developer Guide](./developer.md) -- Configure authentication, runtime settings, channel gateway architecture, and CLI tooling
247
203
  - [Work Use Guide](./work-use.md) -- Explore team collaboration features, document management, and cost governance
248
- - [Personal Use Guide](./personal-use.md) -- Review the basics if you need a refresher on projects, tasks, and the inbox
204
+ - [Personal Use Guide](./personal-use.md) -- Review the basics if you need a refresher