Simplify Slack workspace installation UX for non-technical users

[zenotcx]

Requested by: Preet preet@textcortex.com

Problem

Non-technical users do not understand how to add an agent to Slack. The current process involves too many steps and concepts that are confusing to non-technical users.

Current Flow (as implemented)

Based on the TextCortex deployment, the current process requires:

1. Account Setup

• User must have a TextCortex account
• User must sign up/login at app.textcortex.com

2. Slack Identity Linking

• Navigate to Settings > Permissions
• Click "Connect Slack" button
• Authorize Slack workspace access
• Wait for callback/confirmation

3. Workspace Installation (Conceptual)

• Understand the concept of "Slack gateway" and "concierge instance"
• The installation happens through the Slack gateway service
• Backend tracks installations via spritz_channel_installation table

4. Agent/Concierge Understanding

• Understand what a "concierge instance" is
• Understand that one Slack workspace = one concierge
• Understand the relationship between TextCortex account and Slack workspace

Why This Is Confusing

1. Multiple systems: TextCortex web app → Settings → Permissions → Slack linking → workspace installation
2. Technical concepts: "Principal", "provider", "external tenant", "concierge instance" - these are implementation details exposed to users
3. No clear entry point: Non-technical users don't know where to start - do they go to Slack first? TextCortex app first?
4. Unclear status: After linking, users don't understand if their agent is "ready" or what happens next
5. Too many clicks: Each step requires navigation and authorization, with no guided flow

Desired State

A non-technical user should be able to:

1. Start from Slack (where they already are)
2. Click a single button to add the agent to their workspace
3. Get immediate feedback that it's working
4. Start using the agent right away

Target: 3 clicks or less from "I want this agent" to "I'm using it"

Suggested Improvements

Slack-First Flow

• Slack app manifest with "Add to Slack" button
• One-click installation that handles:
  • TextCortex account creation (if needed)
  • Slack identity linking
  • Workspace installation
  • Concierge instance creation

Guided Onboarding

• In-Slack welcome message with clear next steps
• No technical jargon - just "Your AI assistant is ready"
• Clear indication of what the agent can do

Status Visibility

• Simple Slack command (e.g., /zeno status) showing connection state
• Clear messaging when something needs attention
• No need to visit TextCortex app for status checks

Admin vs User Experience

• Workspace admins can install for everyone
• Regular users can start using immediately after admin install
• Clear messaging about who can do what

Related Architecture

Current implementation files:

• docs/spritz/2026-03-23-channel-gateway-concierge-platform-implementation.md
• docs/spritz/2026-03-24-slack-channel-gateway-textcortex-plan.md
• docs/integrations/2026-03-17-slack-account-linking-implementation-plan.md
• Backend: core/services/spritz_channel_provider_auth.py
• Slack gateway: deploy/spritz/integrations/slack-gateway/

Acceptance Criteria

• Non-technical user can install agent from Slack directly
• Total clicks ≤ 3 from intent to active agent
• No technical jargon exposed to end users
• Clear success/error messaging at each step
• Works for both new and existing TextCortex users
• Admin install flow vs user usage flow clearly separated
• Status visible from Slack without visiting web app

Priority

P1 - Critical for adoption by non-technical enterprise users