Portal — Settings — SideButton Marketing Website Knowledge Module

What This Is

Settings page for Fleet Control -- a multi-tab configuration interface for managing the fleet. Seven tabs: General (LLM provider, model, API key, effort level), Agents (per-agent config with roles, entry paths, env vars, RDP downloads, avatar picker, danger zone), Assistant (chat bot name, persona prompt, avatar URL), Issue Tracking (Jira credentials, webhook URL, deploy/test webhook), Slack (channel connections with bot token setup and live testing), Knowledge Packs (default pack status, ZIP upload, workflow list), and Logs (incoming webhook event history with MATCH/SKIP status, pagination, and matched-only filter). All tabs have editable forms with save feedback. Tabs are deep-linkable via URL query parameter.

URL Patterns

Pattern	Description
/portal/settings	Settings page (General tab default)
/portal/settings?tab=general	General tab (explicit)
/portal/settings?tab=agents	Agents tab
/portal/settings?tab=assistant	Assistant tab
/portal/settings?tab=integrations	Issue Tracking tab
/portal/settings?tab=slack	Slack tab
/portal/settings?tab=knowledge-packs	Knowledge Packs tab
/portal/settings?tab=logs	Logs tab (was ?tab=webhook-logs)

Page Structure

+--[Sidebar]--+--[Main Content]------------------------------------------------------------------+
|             |  H1: "Settings"                                                                   |
|  Settings   |                                                                                   |
|  (active)   |  [Tab Bar: General | Agents | Assistant | Issue Tracking | Slack | Knowledge Packs | Logs]        |
|             |  (horizontal scrollbar when narrow viewport)                                      |
|             |                                                                                   |
|             |  [Tab Content -- varies by active tab]                                            |
+-------------+-----------------------------------------------------------------------------------+

General Tab

|  LLM Provider [dropdown]    Model [text input]          |
|  API Key [password input]                               |
|  "API key is configured" (green) or "Platform key       |
|   active — add your own to override"                    |
|  Default Effort Level: [Max] [High] [Medium] toggles    |
|  "Max / High = Opus, Medium = Sonnet..."                |
|  [Save] button   [status: Saving.../Saved/error]        |

Agents Tab

|  "Manage agent roles, entry paths, environment config,  |
|   and download RDP shortcuts."                          |
|                                                         |
|  [Owned Agent Card]                                     |
|    [Set avatar] display-name [✏ Rename]                 |
|    hostname          ONLINE  [SE][QA][SD][PM]           |
|    Shared with N account(s)  [Default v]  [RDP]         |
|  [Expanded Config Panel]                                |
|    Entry Paths:                                         |
|      [x] ~/workspace  "Main"  [MCP JSON]  [Remove]     |
|      [+ Add Entry Path]                                 |
|    Environment Variables:                               |
|      [textarea: ~/.agent-env content]                   |
|    [Save] [Save & Apply]  [status text]                 |
|    Danger Zone:                                         |
|      [Reboot] [Delete]                                  |
|                                                         |
|  [Shared Agent Card]                                    |
|    [avatar] agent-name    ONLINE  "shared"  [roles]     |
|    agent-name.agents.sidebutton.com          [chevron v]|
|  [Shared Preferences Panel]                             |
|    Enabled Roles: [SE] [QA] [SD] [PM] checkboxes       |
|    Effort Level: [dropdown]                             |
|    Enabled Entry Paths: [checkboxes per path]           |
|    [Save Preferences] [Remove Shared Agent]             |
|                                                         |
|  -- or (empty state) --                                 |
|  "No agents registered yet"                             |

Assistant Tab

|  Name [text input]                                      |
|  "The name your team sees in Slack messages"            |
|  Persona [textarea]                                     |
|  "System prompt that shapes the assistant's voice       |
|   and behavior"                                         |
|  Avatar URL [text input]                                |
|  Active Role [dropdown]                                 |
|    "Skill pack role that shapes the assistant's         |
|     domain expertise"                                   |
|  [Save] button   [status: Saving.../Saved/error]        |
|                                                         |
|  ─────────────────────────────────────────────────      |
|                                                         |
|  H3: "MCP Connections"                                  |
|  "Tool sources available to the chat assistant..."      |
|                                                         |
|  [● green] SideButton Cloud          7 tools [toggle]   |
|    "Agent dispatch, workflow execution..."               |
|                                                         |
|  [● grey] Jira / Atlassian            [Configure]       |
|    "Search, create, edit, and transition..."             |

Issue Tracking Tab

|  H2: "Issue Tracking"                                   |
|  "Connect your issue tracker to enable automated        |
|   agent dispatching from ticket updates."               |
|                                                         |
|  [Jira Card]                                            |
|    [Jira icon] "Jira"                                   |
|    "Atlassian Jira Cloud"                               |
|                                                         |
|    CREDENTIALS                                          |
|    Jira URL [text input]                                |
|    Email [text input]                                   |
|    API Token [password input]                           |
|    "API token is configured" (green, when set)          |
|    [Test Connection] [Save]  [status text]              |
|                                                         |
|    WEBHOOK                                              |
|    "Configure this URL in your Jira webhook settings,   |
|     or click Deploy to register automatically."         |
|    Webhook URL [readonly input] [Copy]                  |
|    [Test Webhook] [Deploy Webhook]                      |
|    "View webhook logs >"  (link to Logs tab)            |

Slack Tab

|  H2: "Connected Channels"                              |
|  [status dot] #channel-name  Team: T0123  [Remove]     |
|  -- or --                                               |
|  "No channels connected yet."                           |
|                                                         |
|  H2: "Add Channel"                                      |
|  Team ID [text]  Channel ID [text]                      |
|  Channel Name [text]                                    |
|  Bot Token [password]                                   |
|  Signing Secret [password]                              |
|  Bot User ID [text]                                     |
|  [Add Channel] [Test Connection]                        |
|  [test status: "Connected: {team} ({user})"]            |
|                                                         |
|  > Slack App Setup Guide (expandable)                   |

Knowledge Packs Tab

|  H3: "Knowledge Pack"                                   |
|  [Status Card]                                          |
|    "Using SideButton Default Pack"                      |
|    "Default workflows are available to all accounts.    |
|     Upload a custom pack below to add account-specific  |
|     workflows."                                         |
|    [Sync Now]  [Remove]                                 |
|                                                         |
|  H3: "Upload Knowledge Pack"                            |
|    Knowledge Pack ZIP [drag-drop zone]                  |
|      "Drop a .zip file here or click to browse"         |
|      "Max 10MB. Must contain index.json at root."       |
|    Display Name [text input]                            |
|    [Upload & Sync] (disabled until file selected)       |
|                                                         |
|  H3: "Loaded Workflows"                                 |
|    "Default workflows are available on the              |
|     Workflows page."  (link)                            |
|  -- or (when custom pack uploaded) --                   |
|    workflow-name  [override|skill-pack badge]  domain   |

Logs Tab

|  H2: "Webhooks"                                        |
|  "Incoming webhook events across all automations."     |
|                                                         |
|  [x] Matched only  (checkbox filter)                   |
|                                                         |
|  Time        Status  Event                Automation  Job |
|  4/2/2026    [SKIP]  jira:issue_updated   Auto Name   —   |
|  4/2/2026    [MATCH] jira:issue_updated   Auto Name   #2959 |
|  ...                                                    |
|                                                         |
|  1–30 of 3769              [Prev] [Next]               |
|                                                         |
|  -- or (empty state) --                                 |
|  "No webhook events recorded yet"                      |

Key Elements

Tab Bar

Element	Selector / Ref	Notes
General tab	link "General"	Active by default, dark background when selected; URL adds ?tab=general
Agents tab	link "Agents"	URL adds ?tab=agents
Assistant tab	link "Assistant"	URL adds ?tab=assistant
Issue Tracking tab	link "Issue Tracking"	URL adds ?tab=integrations
Slack tab	link "Slack"	URL adds ?tab=slack
Knowledge Packs tab	link "Knowledge Packs"	URL adds ?tab=knowledge-packs
Logs tab	link "Logs"	7th tab; URL adds ?tab=logs; was previously labeled "Webhook Logs" with ?tab=webhook-logs

General Tab

Element	Selector / Ref	Notes
LLM Provider dropdown	combobox labeled "LLM Provider"	Options: OpenAI (openai), Anthropic (anthropic), OpenRouter (openrouter)
Model input	textbox labeled "Model"	Text input, e.g. "gpt-5.4"
API Key input	textbox labeled "API Key"	Password field; placeholder varies by state
API key status (configured)	.text-emerald-400	"API key is configured"
API key status (platform)	Text below input	"Platform key active — add your own to override"
Effort: Max button	button "Max"	Toggle; orange border/text when selected
Effort: High button	button "High"	Toggle; orange border/text when selected
Effort: Medium button	button "Medium"	Toggle; orange border/text when selected
Effort hint	Below buttons	"Max / High = Opus, Medium = Sonnet. Applied to all agent jobs unless overridden per agent."
Save button	button "Save"	Orange button
Save status	.text-slate-500 / .text-emerald-400 / .text-red-400	"Saving..." then "Saved" or error message

Issue Tracking Tab — Jira Credentials

Element	Selector / Ref	Notes
Page heading	heading "Issue Tracking"	H2
Subheading	heading "Jira"	With Jira icon and "Atlassian Jira Cloud" subtitle
Credentials heading	heading "Credentials"	Section label
Jira URL input	textbox labeled "Jira URL"	Placeholder "https://yourcompany.atlassian.net"
Email input	textbox labeled "Email"	Placeholder "[email protected]"
API Token input	textbox labeled "API Token"	Password field; placeholder "(configured — enter new to change)" when set, "ATATT3x..." otherwise
API token status	.text-emerald-400	"API token is configured" (shown when token exists)
Test Connection button	button "Test Connection"	Outlined button; tests Jira API connectivity
Save button	button "Save"	Orange button; saves credentials
Status text	Below buttons	"Saving..." then "Saved" or error

Issue Tracking Tab — Webhook

Element	Selector / Ref	Notes
Webhook heading	heading "Webhook"	Section label
Webhook description	Text below heading	"Configure this URL in your Jira webhook settings, or click Deploy to register automatically."
Webhook URL input	textbox labeled "Webhook URL"	Readonly; value: https://sidebutton.com/api/webhooks/jira
Copy button	button "Copy"	Copies webhook URL to clipboard
Test Webhook button	button "Test Webhook"	Outlined button; sends test webhook
Deploy Webhook button	button "Deploy Webhook"	Orange button; auto-registers webhook in Jira (requires saved credentials)
View webhook logs link	link "View webhook logs"	Navigates to Logs tab

Agents Tab — Card Header (per agent)

Element	Selector / Ref	Notes
Description text	Below tab bar	"Manage agent roles, entry paths, environment config, and download RDP shortcuts."
Avatar button	button "Set avatar" (w-9 h-9, first in card)	Click opens avatar picker modal
Agent display name	Bold text in card	Editable display name, e.g. "dev-agent-1"
Rename agent button	button "Rename agent" (.agent-rename-btn)	Hover-to-reveal pencil icon; click makes name editable inline
Rename save button	.agent-rename-save	Emerald checkmark; saves new name
Rename cancel button	.agent-rename-cancel	Slate X; cancels rename
Agent hostname	Grey text below name	e.g. "venmate-agent-1"
Status badge	Badge in card	ONLINE (green) / BUSY (amber) / ERROR (red) / OFFLINE (gray)
Shared with text	span on owned agents	"Shared with N account(s)" — shows how many accounts share this agent
Shared badge	Light blue badge	"shared" — shown for non-owned agents
Role checkboxes (owned)	input[type="checkbox"] per role	SE, QA, SD, PM — toggles agent capabilities
Effort dropdown (owned)	select	Default (empty) / Max / High / Medium — direct PUT on change
RDP button	button "RDP" (.rdp-download-btn)	Opens RDP configuration modal
Expand chevron	button (chevron icon)	Toggles config panel open/closed
No agents text	"No agents registered yet"	Empty state when no agents exist

Agents Tab — Owned Agent Config Panel (expanded)

Element	Selector / Ref	Notes
Entry path active checkbox	input[type="checkbox"] per path	Toggle path active/inactive
Entry path input	input per path	Path value, e.g. "~/workspace"
Entry path label input	input per path	Label, e.g. "Main"
Entry path MCP JSON textarea	textarea per path (3 rows)	JSON config for MCP servers on this path
Remove entry path button	button per path	Removes this entry path
Add Entry Path button	button "+ Add Entry Path"	Appends new empty entry path
Environment variables textarea	textarea (4 rows)	~/.agent-env content; supports ANTHROPIC_API_KEY, GH_TOKEN, etc.
Save button	button "Save"	Slate button — saves config to DB only
Save & Apply button	button "Save & Apply"	Orange button — saves + pushes config to agent VM
Config status text	Below buttons	Shows result of last save/apply operation
Applied timestamp	Below status	"Applied at: {ISO timestamp}"
Reboot button	button "Reboot" (amber)	Danger zone — shows confirmation alert, POST to reboot
Delete button	button "Delete" (red)	Danger zone — shows confirmation alert, deletes agent

Agents Tab — Shared Agent Preferences Panel (expanded)

Element	Selector / Ref	Notes
Enabled Roles checkboxes	input[type="checkbox"] per capability	Select which roles your account can use; unchecking all = enable all
Effort Level dropdown	select	Default / Max / High / Medium; shows agent's default in label
Enabled Entry Paths checkboxes	input[type="checkbox"] per active path	Select which entry paths your account can use
Save Preferences button	button "Save Preferences"	Sky-blue (sky-500) button
Remove Shared Agent button	button (red)	Removes shared agent from your account

Avatar Picker Modal (heading: "Set Agent Avatar")

Element	Selector / Ref	Notes
Modal heading	heading "Set Agent Avatar"	H3
Preset avatar grid	10 avatar buttons in grid	Click to select preset (supportbot, bot-blue, opshub, bot-orange, sidebutton, bot-teal, aictpo, bot-red, talentflow, bot-cyan)
Upload file input	input[type="file"]	Max 1 MB; accepts JPEG, PNG, GIF, WebP, SVG
Remove Avatar button	button "Remove avatar (use default)"	Sets avatar to null (default SVG)
Cancel button	button "Cancel"	Closes modal without changes
Modal status text	Below grid	"Saving..." then "Saved" or error (e.g. "File too large")

RDP Download Modal (heading: "Download RDP Shortcut")

Element	Selector / Ref	Notes
Modal heading	heading "Download RDP Shortcut"	H3
Display Mode: Fullscreen	radio	Disables resolution options when selected
Display Mode: Windowed	radio	Enables resolution options
Resolution: 1280x800	radio	Disabled if fullscreen
Resolution: 1440x900	radio	Default selection
Resolution: 1920x1080	radio	Disabled if fullscreen
Save Credentials checkbox	checkbox#rdp-save-password	"Save credentials Embed password in RDP file"
Platform: Windows	radio	Default; generates standard .rdp
Platform: macOS	radio	Hint: "Requires Microsoft Remote Desktop from App Store"
Platform: Linux	radio	Hint: "Open with Remmina, xfreerdp..."
Cancel button	button "Cancel"	Closes modal
Copy password button	button "Copy password"	Copies agent RDP password to clipboard
Download button	button "Download"	Generates and downloads {agentName}.rdp file

Assistant Tab

Element	Selector / Ref	Notes
Name input	textbox labeled "Name"	Placeholder "e.g. Atlas", max 100 chars
Name hint	Below input	"The name your team sees in Slack messages"
Persona textarea	textbox labeled "Persona" (4 rows)	System prompt text, placeholder "You are Atlas, a concise and helpful engineering assistant...", max 5000 chars
Persona hint	Below textarea	"System prompt that shapes the assistant's voice and behavior"
Avatar URL input	textbox labeled "Avatar URL"	Placeholder "https://...", max 500 chars
Active Role dropdown	select#active-role-select (name="active_role")	Options: No role (default), QA Engineer, Skill Discovery, Software Engineer, Product Manager, Social Media Manager, sales
Active Role hint	Below dropdown	"Skill pack role that shapes the assistant's domain expertise"
Save button	button "Save"	Orange button
Save status	.text-emerald-400 / .text-red-400	"Saving..." then "Saved" or error

Assistant Tab — MCP Connections

Below the persona form, separated by a divider line.

Element	Selector / Ref	Notes
MCP Connections heading	heading "MCP Connections"	H3 (not H2), below divider
MCP description	Text below heading	"Tool sources available to the chat assistant, Slack bot, and MCP clients. Each connection provides tools the assistant can use."
SideButton Cloud card	Connection card	Green dot (active), "SideButton Cloud" title, "Agent dispatch, workflow execution, and fleet monitoring" description
SideButton Cloud tool count	Badge text	"7 tools"
SideButton Cloud toggle	checkbox	Orange toggle switch when enabled; controls whether chat assistant can use SideButton Cloud tools
Jira / Atlassian card	Connection card	Green dot when configured (grey when unconfigured), "Jira / Atlassian" title, "Search, create, edit, and transition Jira issues and Confluence pages" description
Jira tool count	Badge text	"60 tools" (when configured)
Jira toggle	checkbox (data-mcp-id="jira")	Orange toggle when enabled; only shown when Jira credentials are configured (otherwise shows "Configure" link to Issue Tracking tab)

Slack Tab

Element	Selector / Ref	Notes
Connected Channels heading	heading "Connected Channels"	H2
Channel status dot	Emerald (active) or Gray (inactive)	Per connected channel
Channel name	#channel-name text	Falls back to channel ID if no name
Channel team ID	Small text	Shown per channel
Channel remove button	button per channel	DELETE endpoint; removes channel binding
No channels text	"No channels connected yet."	Empty state
Add Channel heading	heading "Add Channel"	H2
Team ID input	textbox labeled "Team ID"	Placeholder "T0123ABC"
Channel ID input	textbox labeled "Channel ID"	Placeholder "C0123ABC"
Channel Name input	textbox labeled "Channel Name"	Placeholder "#engineering-agents" (optional)
Bot Token input	textbox labeled "Bot Token"	Password field; placeholder "xoxb-..." (required)
Signing Secret input	textbox labeled "Signing Secret"	Password field; placeholder "From Slack App settings" (required)
Bot User ID input	textbox labeled "Bot User ID"	Placeholder "U0123ABC (from auth.test)" (optional, auto-filled by Test)
Add Channel button	button "Add Channel"	Orange button
Test Connection button	button "Test Connection"	Outlined button; calls Slack auth.test API directly
Test status text	Below buttons	"Testing..." then "Connected: {team} ({user})" or "Slack error: {error}"
Setup Guide	details > summary "Slack App Setup Guide"	Expandable 7-step guide

Slack App Setup Guide (expanded content)

1. Go to api.slack.com/apps and create a new app
2. Under OAuth & Permissions, add bot scopes: chat:write, reactions:write, users:read
3. Install the app to workspace, copy Bot User OAuth Token (starts with xoxb-)
4. Under Basic Information, copy the Signing Secret
5. Under Event Subscriptions, enable events, set Request URL to: https://sidebutton.com/api/slack/events
6. Subscribe to bot events: message.channels, message.groups
7. Invite the bot to your channel, then add channel details in the form above

Knowledge Packs Tab — Default Pack Status

Element	Selector / Ref	Notes
Knowledge Pack heading	heading "Knowledge Pack"	H3
Default pack label	"Using SideButton Default Pack"	Status card with icon
Default pack description	Below label	"Default workflows are available to all accounts. Upload a custom pack below to add account-specific workflows."
Sync Now button	button "Sync Now"	Refreshes pack workflows from upstream (was "Pull Updates")
Remove button	button "Remove"	Removes the knowledge pack; shows confirmation dialog

Knowledge Packs Tab — Upload Form

Element	Selector / Ref	Notes
Upload heading	heading "Upload Knowledge Pack"	H3
ZIP file drop zone	textbox labeled "Knowledge Pack ZIP"	Drag-and-drop area: "Drop a .zip file here or click to browse"; max 10MB; must contain index.json at root
Display Name input	textbox labeled "Display Name"	Placeholder "My Knowledge Pack"
Upload & Sync button	button "Upload & Sync"	Orange; disabled until file selected; uploads ZIP and syncs workflows

Knowledge Packs Tab — Loaded Workflows

Element	Selector / Ref	Notes
Loaded Workflows heading	heading "Loaded Workflows"	H3
Default workflows text	"Default workflows are available on the Workflows page."	Shown when using default pack only
Workflows page link	link "Workflows page"	Links to /portal/workflows
Workflow card	Per workflow (when custom pack uploaded)	Name (monospace, truncated), source badge, domain text
Source badge: override	Orange badge	override — account-level override workflow
Source badge: skill-pack	Gray badge	skill-pack — from uploaded pack

Logs Tab

Element	Selector / Ref	Notes
Section heading	heading "Webhooks"	H2
Section description	Text below heading	"Incoming webhook events across all automations."
Matched only checkbox	checkbox / #wh-logs-matched-only	Filters to show only matched (dispatched) events
Log table	table in .bg-slate-900/60 container	5-column table with border and rounded corners
Column: Time	th "Time"	Timestamp in locale format (e.g. "4/2/2026, 2:13:05 PM")
Column: Status	th "Status"	MATCH or SKIP badge
Column: Event	th "Event"	Formatted event summary (truncated at 280px)
Column: Automation	th "Automation"	Automation name that evaluated this event
Column: Job	th "Job"	Job link #N or "—" dash
MATCH badge	span.text-emerald-400	Green badge: "MATCH" — event matched automation criteria and dispatched a job
SKIP badge	span.text-slate-500	Grey badge: "SKIP" — event was evaluated but did not match
Job link	a (sky-400 text)	Links to /portal/jobs/{id} for matched events
Pagination container	#wh-logs-pagination	Shows when total > 30 items; hidden otherwise
Pagination info	#wh-logs-info	"N–M of Total" (e.g. "1–30 of 3769")
Prev button	button "Prev" / #wh-logs-prev	Disabled on first page (opacity-30)
Next button	button "Next" / #wh-logs-next	Disabled on last page
Loading state	td (colspan=5)	"Loading..." centered text
Empty state	td (colspan=5)	"No webhook events recorded yet" centered text
Error state	td (colspan=5)	"Failed to load logs ({error})" in red-400 text

Data Model

General Settings

Field	Type	Description
llm_provider	string	LLM provider: "openai", "anthropic", or "openrouter"
model	string	Model identifier (e.g. "gpt-5.4")
api_key	string	API key (masked in UI, transmitted only when changed)
has_api_key	boolean	Read-only; true when key configured
default_effort	string	"max" / "high" / "medium"

Jira Integration (Issue Tracking)

Field	Type	Description
jira_url	string	Atlassian instance URL (e.g. "https://yourcompany.atlassian.net")
jira_email	string	Jira account email for API access
jira_api_token	string	Jira API token (masked in UI, transmitted only when changed)
has_jira_token	boolean	Read-only; true when token configured
webhook_url	string	Read-only; webhook endpoint: https://sidebutton.com/api/webhooks/jira

Agent

Field	Type	Description
display_name	string	Editable display name shown on card (e.g. "dev-agent-1")
name	string	Agent hostname/identifier
ip	string	Agent IP or DNS address
status	string	"online" / "busy" / "error" / "offline"
capabilities	string[]	Array of roles: ["se", "qa", "sd", "pm"]
effort_level	string?	Per-agent effort override: "max" / "high" / "medium" / null
agent_env	string	Environment variable content (~/.agent-env)
avatar_url	string?	Custom avatar URL or null for default
entry_paths	object[]	Array of {path, label, mcp_json, active} objects
is_shared	boolean	Whether agent is shared from another account

Entry Path

Field	Type	Description
path	string	Filesystem path (e.g. "~/workspace")
label	string	Display label
mcp_json	string	JSON config for MCP servers on this path
active	boolean	Whether this path is enabled

Assistant Settings

Field	Type	Description
name	string	Bot display name (max 100 chars)
persona	string	System prompt text (max 5000 chars)
avatar_url	string	Avatar image URL (max 500 chars)
active_role	string	Skill pack role: "" (No role), "qa", "sd", "se", "pm", "software-engineer", "product-manager", "sales", "smm"

Slack Channel

Field	Type	Description
team_id	string	Slack team/workspace ID (required)
channel_id	string	Slack channel ID (required)
channel_name	string	Channel display name (optional)
bot_token	string	Slack bot token xoxb-... (required, masked in responses)
signing_secret	string	Slack signing secret (required, masked in responses)
bot_user_id	string	Bot user ID (optional, auto-filled by Test Connection)
is_active	boolean	Whether channel is active

MCP Connection

Field	Type	Description
name	string	Connection display name (e.g. "SideButton Cloud", "Jira / Atlassian")
description	string	What tools the connection provides
tool_count	number	Number of tools available (e.g. 7)
enabled	boolean	Whether connection is active (toggle state)
status	string	"active" (green dot) / "inactive" (grey dot)
configure_url	string	Tab to navigate to for setup (e.g. Issue Tracking for Jira)

Knowledge Pack

Field	Type	Description
name	string	Display name for the pack
type	string	"default" (SideButton built-in) or "custom" (uploaded ZIP)
zip_file	file	ZIP archive; max 10MB; must contain index.json at root

Webhook Log Entry

Field	Type	Description
id	number	Log entry ID
automation_id	number	ID of the automation that evaluated this event
automation_name	string	Display name of the automation
trigger_event	object	JSON event payload (webhookEvent, issueKey, projectKey, issueType, assignee, status for Jira; eventType, workflowSlug, agentName for SideButton; type, schedule for cron)
matched	boolean	Whether the event matched the automation criteria
dispatched_job_id	number?	Job ID if a job was dispatched (null for SKIP events)
created_at	string (datetime)	When the event was received

States & Variations

State	Trigger	Visual Indicator
General tab active	Default or click General	Dark tab background; URL ?tab=general
Agents tab active	Click Agents	Dark tab background; URL ?tab=agents
Assistant tab active	Click Assistant	Dark tab background; URL ?tab=assistant
Issue Tracking tab active	Click Issue Tracking	Dark tab background; URL ?tab=integrations
Slack tab active	Click Slack	Dark tab background; URL ?tab=slack
Knowledge Packs tab active	Click Knowledge Packs	Dark tab background; URL ?tab=knowledge-packs
Logs tab active	Click Logs	Dark tab background; URL ?tab=logs
API key configured	Key exists	Green "API key is configured" text
API key missing (platform)	No user key, platform key active	"Platform key active — add your own to override"
Effort: selected	Click effort button	Selected button has orange border/text (orange-500/20 bg, orange-400 text, orange-500/50 border)
Effort: unselected	Other buttons	Dark background (slate-800), slate-400 text
Save: Saving	Click Save	"Saving..." in slate-500 text
Save: Success	API returns OK	"Saved" in emerald-400 text
Save: Error	API returns error	Error message in red-400 text
Jira token configured	Token exists	Green "API token is configured" text below API Token field
Jira test: success	Valid credentials	Success message with connection details
Jira test: error	Invalid credentials	Error message in red
Webhook deploy: success	Click Deploy Webhook	Success status after auto-registering webhook in Jira
Agent online	Agent connected	Green "ONLINE" badge
Agent busy	Agent running job	Amber "BUSY" badge
Agent error	Agent in error state	Red "ERROR" badge
Agent offline	Agent disconnected	Gray "OFFLINE" badge
No agents	No agents registered	"No agents registered yet" text
Agent card collapsed	Default	Only header row visible
Agent card expanded	Click chevron	Config panel visible below card
Agent effort changed	Change dropdown	Border flash green (success) or red (error)
Agent role toggled	Click role checkbox	Label style updates, outline flash
Agent rename active	Hover → click Rename	Name field becomes editable inline; save/cancel buttons appear
Avatar modal open	Click "Set avatar"	Modal overlay with heading "Set Agent Avatar", preset grid + upload
RDP modal open	Click "RDP"	Modal with heading "Download RDP Shortcut", display/resolution/platform options, Copy password/Cancel/Download buttons
Shared agent card	Non-owned agent	Sky-blue accents, "shared" badge, preferences panel instead of config
No Slack channels	No channels configured	"No channels connected yet." text
Channels connected	Channels exist	Channel list with status dots above "Add Channel" form
Slack test: testing	Click "Test Connection"	"Testing..." text
Slack test: success	Valid token	"Connected: {team} ({user})" — auto-fills bot_user_id
Slack test: error	Invalid token	"Slack error: {message}"
Slack duplicate channel	Add existing channel	Error 409: "This Slack channel is already connected"
MCP: SideButton Cloud enabled	Toggle on	Green dot, orange toggle, "7 tools" badge
MCP: SideButton Cloud disabled	Toggle off	Grey dot, slate toggle
MCP: Jira unconfigured	No Jira credentials	Grey dot, "Configure" link (goes to Issue Tracking tab); no toggle or tool count shown
MCP: Jira configured	Jira credentials saved	Green dot, "60 tools" badge, orange toggle switch
Default pack active	No custom pack uploaded	Status card: "Using SideButton Default Pack" with Sync Now and Remove buttons
Upload & Sync disabled	No file selected	Button grayed out
Upload & Sync enabled	ZIP file selected	Button becomes orange/clickable
Workflows: default only	Default pack	"Default workflows are available on the Workflows page." with link
Workflows: custom loaded	Custom pack synced	Workflow list with name/source/domain per item
Logs: loading	Tab first opened	"Loading..." in table (client-side fetch)
Logs: with data	Webhook events exist	Table rows with Time/Status/Event/Automation/Job columns
Logs: empty	No webhook events	"No webhook events recorded yet" centered in table
Logs: error	API fetch fails	"Failed to load logs ({error})" in red text
Logs: matched filter	"Matched only" checked	Only MATCH rows shown; resets pagination to page 1
Logs: pagination	Total > 30 events	Pagination bar visible with "N–M of Total" + Prev/Next buttons
Logs: first page	Offset = 0	Prev button disabled (opacity-30)
Logs: last page	Offset + 30 >= total	Next button disabled

Common Tasks

1. Configure LLM provider

1. Go to Settings > General tab
2. Select LLM Provider from dropdown
3. Enter Model name
4. Enter API Key (or leave blank to keep existing)
5. Click Save
6. Verify "Saved" status text appears in green

2. Set default effort level

1. Go to Settings > General tab
2. Click Max, High, or Medium button
3. Click Save
4. Verify button styling updates and "Saved" appears

3. Configure Jira integration

1. Go to Settings > Issue Tracking tab
2. Enter Jira URL (e.g. "https://yourcompany.atlassian.net")
3. Enter Email (your Jira account email)
4. Enter API Token (from Jira account settings)
5. Click "Test Connection" to verify credentials
6. Click Save
7. Verify "Saved" and "API token is configured" text

4. Deploy Jira webhook

1. Go to Settings > Issue Tracking tab (requires saved Jira credentials)
2. In the Webhook section, click "Deploy Webhook"
3. Webhook auto-registers in Jira pointing to https://sidebutton.com/api/webhooks/jira
4. Alternatively, copy the URL and configure manually in Jira

5. Rename an agent

1. Go to Settings > Agents tab
2. Hover over the agent card to reveal the pencil icon (Rename button)
3. Click the Rename button — the name becomes an editable text field
4. Type the new display name
5. Click the emerald checkmark to save, or the slate X to cancel
6. Name updates immediately on the card

6. Change agent avatar

1. Go to Settings > Agents tab
2. Click the "Set avatar" button (small square) on the agent card
3. In the modal ("Set Agent Avatar"), either click a preset avatar or upload a file (max 1 MB)
4. Verify "Saved" status; click "Cancel" or click outside to close

7. Configure agent roles

1. Go to Settings > Agents tab
2. Click role checkboxes (SE/QA/SD/PM) on the agent card header
3. Changes save immediately via PUT on each toggle (outline flash confirms)

8. Configure agent entry paths

1. Go to Settings > Agents tab
2. Click chevron to expand agent card
3. Click "+ Add Entry Path" to add a new path
4. Fill in Path (e.g. "~/workspace"), Label (e.g. "Main"), optionally MCP JSON
5. Toggle active checkbox per path
6. Click "Save" (DB only) or "Save & Apply" (DB + push to agent VM)

9. Set agent environment variables

1. Go to Settings > Agents tab
2. Click chevron to expand agent card
3. Edit the environment variables textarea
4. Click "Save & Apply" to push to agent

10. Download RDP connection

1. Go to Settings > Agents tab
2. Click "RDP" button for desired agent
3. In the modal ("Download RDP Shortcut"), choose Display Mode (Fullscreen/Windowed), Resolution, Platform
4. Optionally check "Save credentials" to embed password in RDP file
5. Use "Copy password" to copy the RDP password to clipboard
6. Click "Download" — browser downloads {agentName}.rdp file; or "Cancel" to close

11. Reboot an agent

1. Go to Settings > Agents tab
2. Click chevron to expand agent card
3. In the Danger Zone, click "Reboot"
4. Confirm in the alert dialog
5. Agent status changes to offline; agent reboots on its side

12. Delete an agent

1. Go to Settings > Agents tab
2. Click chevron to expand agent card
3. In the Danger Zone, click "Delete"
4. Confirm in the alert dialog

13. Configure shared agent preferences

1. Go to Settings > Agents tab
2. Find a shared agent (sky-blue accent, "shared" badge)
3. Click chevron to expand preferences panel
4. Toggle Enabled Roles (unchecking all = enable all)
5. Set Effort Level override
6. Toggle Enabled Entry Paths
7. Click "Save Preferences"

14. Configure assistant persona

1. Go to Settings > Assistant tab
2. Set Name (max 100 chars), Persona prompt (max 5000 chars), Avatar URL, and Active Role
3. Click Save
4. Verify "Saved" status appears

15. Set assistant active role

1. Go to Settings > Assistant tab
2. Select a role from the "Active Role" dropdown (No role, QA Engineer, Skill Discovery, Software Engineer, etc.)
3. Click Save
4. The selected role shapes the assistant's domain expertise in chat and Slack

16. Add Slack channel

1. Go to Settings > Slack tab
2. Fill in Team ID, Channel ID, Channel Name, Bot Token, Signing Secret
3. Click "Test Connection" — verify "Connected: {team} ({user})" appears
4. Bot User ID auto-fills if empty
5. Click "Add Channel" to save
6. Verify channel appears in Connected Channels list

17. Remove Slack channel

1. Go to Settings > Slack tab
2. Find the channel in Connected Channels list
3. Click the Remove button next to the channel

18. Upload a knowledge pack

1. Go to Settings > Knowledge Packs tab
2. Drop or click to browse for a ZIP file (max 10MB, must contain index.json at root)
3. Enter Display Name
4. Click "Upload & Sync"
5. Workflows from the pack appear in Loaded Workflows section

19. Sync knowledge pack

1. Go to Settings > Knowledge Packs tab
2. Click "Sync Now" on the pack card
3. Workflows refresh from upstream

20. View webhook logs

1. Go to Settings > Logs tab (or click "View webhook logs" link in Issue Tracking tab)
2. Table loads automatically via client-side fetch (shows "Loading..." then data)
3. View incoming webhook events with Time, Status (MATCH/SKIP), Event summary, Automation name, and linked Job
4. Use "Matched only" checkbox to filter to events that dispatched jobs
5. Use Prev/Next buttons to paginate (30 per page)

Tips

• The General tab effort level maps to Claude models: Max/High = Opus, Medium = Sonnet
• The Assistant persona is the system prompt used when the bot responds in Slack
• Jira configuration (URL, email, API token) is on the Issue Tracking tab, not General
• Agent display names are editable via the hover-to-reveal Rename button; the hostname below the name is the permanent identifier
• RDP files allow direct desktop access to agent VMs; the modal lets you customize resolution and platform; use "Copy password" to get the RDP password
• Tabs are deep-linkable via ?tab= query parameter — the URL updates when switching tabs
• "Save" persists config to the database; "Save & Apply" also pushes the config to the agent VM — use Apply when you need the agent to pick up changes immediately
• Agent role checkboxes and effort dropdown save immediately on change — no explicit Save needed
• Shared agents show sky-blue accents; you can only change preferences (roles, effort, paths), not the agent config itself
• Test Connection on the Slack tab calls the Slack API directly from the browser and auto-fills the Bot User ID
• Deploy Webhook on the Issue Tracking tab auto-registers a Jira webhook — no manual Jira admin needed
• MCP Connections on the Assistant tab control which tool sources the chat assistant, Slack bot, and MCP clients can use
• SideButton Cloud connection provides 7 tools for agent dispatch, workflow execution, and fleet monitoring
• Jira / Atlassian connection requires Jira credentials from the Issue Tracking tab before it can be enabled
• Active Role on the Assistant tab sets the assistant's domain expertise; options are populated from installed knowledge pack roles
• Knowledge Packs now use ZIP upload instead of local path attachment; "Sync Now" (was "Pull Updates") refreshes workflows

Gotchas

• Seven tabs: General, Agents, Assistant, Issue Tracking, Slack, Knowledge Packs, Logs; tab bar may scroll horizontally in narrow viewports
• Tab label renamed: The 7th tab is now "Logs" (was "Webhook Logs"); URL param is ?tab=logs (was ?tab=webhook-logs)
• Tab URL param: Issue Tracking tab uses ?tab=integrations (not ?tab=issue-tracking) — the param name doesn't match the visible label
• Jira moved out of General: Jira URL, email, and API token are now on the Issue Tracking tab, not the General tab — old references to "General > Jira URL" are outdated
• API key masking: The API Key field shows "(configured — enter new to change)" as placeholder when a key exists — entering a new value overwrites it
• Platform key fallback: When no user API key is set, shows "(optional — platform key active)" as placeholder and "Platform key active — add your own to override" as hint text
• Effort is global default: The effort level set in General applies to all jobs unless overridden per-agent or per-dispatch
• Effort button styling changed: Selected effort button now uses orange border/text accent (orange-500/20 bg) instead of dark/orange solid background
• Save vs Save & Apply: Agent config has two save actions — "Save" only writes to DB, "Save & Apply" also pushes to the agent VM. Forgetting to Apply means the agent doesn't see changes
• Role/effort saves immediately: Agent role checkboxes and effort dropdown fire PUT requests on every change — no Save button needed; visual feedback is a border flash
• Rename agent is hover-reveal: The pencil icon button appears only on hover over the agent card (opacity-0 group-hover/card:opacity-100); clicking it turns the name into an editable inline text field with save/cancel buttons
• Agent display name vs hostname: Cards show an editable display name (top) and a fixed hostname (below); the hostname is the permanent identifier used for DNS
• "Shared with N account(s)": Owned agents show a span indicating how many other accounts the agent is shared with
• Avatar modal heading: Modal heading is "Set Agent Avatar"; remove button text is "Remove avatar (use default)"; modal has a Cancel button
• Avatar upload limits: Max 1 MB, JPEG/PNG/GIF/WebP/SVG only. Oversized files show error and clear the input
• RDP modal heading: Modal heading is "Download RDP Shortcut"; includes "Copy password" button to copy RDP credentials and "Cancel" button to close without downloading
• RDP button text changed: The button on agent cards now shows as "RDP" (was "Download RDP")
• RDP Save Credentials: Checkbox id is rdp-save-password, label is "Save credentials Embed password in RDP file"
• RDP modal platform hints: macOS shows "Requires Microsoft Remote Desktop from App Store"; Linux shows "Open with Remmina, xfreerdp..."
• Shared agent read-only config: Non-owners see a Preferences panel (roles/effort/paths) instead of the full config panel — they cannot edit entry paths, env vars, or use danger zone
• Slack setup complexity: Adding a Slack channel requires multiple fields from the Slack App configuration — the expandable Setup Guide provides 7-step instructions
• Slack events URL: Event subscriptions must point to https://sidebutton.com/api/slack/events
• Slack duplicate channel: Adding a channel that's already connected returns error 409 — "This Slack channel is already connected"
• Slack Test Connection: Calls Slack auth.test API directly from browser — requires valid bot token
• No delete for settings: There's no reset/delete for General or Assistant settings — only overwrite via Save
• Knowledge pack is now ZIP upload: The old "Attach Skill Pack" flow with local path is replaced by ZIP file upload (max 10MB, must contain index.json at root)
• Sync Now replaced Pull Updates: The button to refresh knowledge pack workflows is now "Sync Now" (was "Pull Updates")
• Knowledge Pack Remove button: A "Remove" button is now visible on the pack card for removing the knowledge pack (shows confirmation dialog)
• Knowledge Pack heading level: The "Knowledge Pack" heading is now H3 (was H2)
• Active Role dropdown: New field on Assistant tab — select#active-role-select with name="active_role" — options are populated from installed skill pack roles
• Logs table headers: Column headers are now Title Case ("Time", "Status", "Event", "Automation", "Job") — previously documented as UPPERCASE
• Upload & Sync disabled by default: The button is disabled until a ZIP file is selected
• Deploy Webhook requires saved credentials: The Deploy Webhook button on the Issue Tracking tab only works after Jira credentials (URL, email, token) are saved
• Logs tab is client-side rendered: The table fetches data via /api/webhooks/logs on tab open — shows "Loading..." then populates; snapshot may not capture table rows since they're injected via JS
• Logs empty state: Shows "No webhook events recorded yet" (not a blank area) when no events exist
• Logs pagination: 30 items per page; Prev/Next buttons appear only when total > 30; "N–M of Total" info text (e.g. "1–30 of 3769")
• MATCH vs SKIP badges: MATCH (emerald/green) = event triggered a job dispatch; SKIP (slate/grey) = event was evaluated but didn't match automation criteria
• Logs event summary format: Jira events show "webhookEvent — issueKey (status)"; SideButton events show "eventType — workflowSlug on agentName"; cron events show "cron — schedule"; manual shows "manual trigger"
• Auth is now Auth0: Portal authentication uses Auth0 (email + password) instead of the old email-only flow; legacy /api/auth/login still works for programmatic access
• MCP Connections is on Assistant tab: The MCP Connections section is below the persona form on the Assistant tab, under an H3 heading (not H2), separated by a divider line
• Jira MCP state depends on credentials: When unconfigured, shows grey dot + "Configure" link to Issue Tracking tab; when configured, shows green dot + "60 tools" badge + orange toggle switch
• SideButton Cloud always available: SideButton Cloud connection is pre-configured and shows green dot; Jira shows grey dot until credentials are configured
• Confirmation dialogs on destructive actions: Reboot, Delete agent, and Remove pack all show browser confirm() dialogs