My agentic slop goes here. Not intended for anyone else!
anil.recoil.org
1# Vicuna Bot - Quick Usage Guide
2
3## The Email Problem
4
5When you authenticate to Zulip using OAuth, SSO, or other third-party authentication methods, Zulip often assigns you an auto-generated email address like:
6
7- `user123@zulipchat.com`
8- `person456@zulip.example.com`
9
10This isn't your actual email address - it's just an internal identifier.
11
12## The Smart Solution
13
14**Good news!** Vicuna now automatically detects your real email address from your Zulip profile!
15
16Most users can simply type `register` and the bot will try multiple sources:
171. Your `delivery_email` from Zulip profile (the real email associated with your account)
182. Your `user.email` from Zulip profile API (may be your real email depending on server config)
193. Your Zulip message sender email as a fallback
20
21**No need to manually provide your email in most cases!**
22
23## Registration Options
24
25### Option 1: Smart Auto-Detection (RECOMMENDED - Just type `register`)
26
27```
28> register
29```
30
31The bot will automatically fetch your real email from your Zulip profile!
32
33**Response (when delivery_email is available):**
34```
35✅ Successfully registered!
36• Email: `alice@mycompany.com`
37• Zulip ID: `12345`
38• Full Name: `Alice Smith`
39
40💡 Your Zulip email is: `user123@zulipchat.com`
41📧 Using your delivery email from your profile
42You can now be @mentioned by your email or Zulip ID!
43```
44
45The bot automatically found `alice@mycompany.com` from your profile!
46
47**Response (when delivery_email is NOT available):**
48```
49✅ Successfully registered!
50• Email: `user123@zulipchat.com`
51• Zulip ID: `12345`
52• Full Name: `Alice Smith`
53
54💡 Your Zulip email is: `user123@zulipchat.com`
55You can now be @mentioned by your email or Zulip ID!
56```
57
58Falls back to Zulip email if delivery_email isn't available.
59
60### Option 2: Manual Email Override
61
62```
63> register alice@mycompany.com
64```
65
66Manually specify a custom email (overrides auto-detection).
67
68**Response:**
69```
70✅ Successfully registered!
71• Email: `alice@mycompany.com`
72• Zulip ID: `12345`
73• Full Name: `Alice Smith`
74
75💡 Your Zulip email is: `user123@zulipchat.com`
76📝 Using the custom email you provided
77You can now be @mentioned by your email or Zulip ID!
78```
79
80## Lookup Examples
81
82### Find Someone by Email
83
84```
85> whois alice@mycompany.com
86
87👤 User found:
88• Email: `alice@mycompany.com`
89• Zulip ID: `12345`
90• Full Name: `Alice Smith`
91• Registered: 2025-01-15 10:30:45
92```
93
94### Find Someone by Zulip ID
95
96```
97> whois 12345
98
99👤 User found:
100• Email: `alice@mycompany.com`
101• Zulip ID: `12345`
102• Full Name: `Alice Smith`
103• Registered: 2025-01-15 10:30:45
104```
105
106## Check Your Status
107
108```
109> whoami
110
111📋 Your registration info:
112• Email: `alice@mycompany.com`
113• Zulip ID: `12345`
114• Full Name: `Alice Smith`
115• Registered: 2025-01-15 10:30:45
116```
117
118## List All Users
119
120```
121> list
122
123📋 Registered users (3):
124• **Alice Smith** (`alice@mycompany.com`) - ID: 12345
125• **Bob Jones** (`bob@company.org`) - ID: 67890
126• **Carol White** (`carol@example.com`) - ID: 54321
127```
128
129## Get Help
130
131```
132> help
133```
134
135Shows all available commands and examples.
136
137## Pro Tips
138
1391. **Just type `register`** - In most cases, the bot will automatically find your real email from your profile!
1402. **Check if it worked** - Use `whoami` after registering to see which email was used
1413. **Manual override if needed** - If the auto-detection didn't work, use `register your-email@example.com`
1424. **Encourage your team to register** - The more people registered, the more useful the directory
1435. **Update your registration** - If your email changes, just register again with the new one
1446. **The bot stores both emails** - It knows your registered email AND your Zulip internal email
145
146## How Smart Detection Works
147
148The bot uses this priority order:
149
1501. **Custom email** (if you provide one): `register alice@company.com` - Highest priority
1512. **delivery_email** (from Zulip profile API): Your real email address associated with the account
1523. **user.email** (from Zulip profile API): Email from profile (if different from message sender)
1534. **Message sender email** (fallback): The internal `user@zulipchat.com` style email
154
155This means the bot will use the best available email automatically!
156
157### Why Multiple Sources?
158
159- **delivery_email**: The most reliable source for real email, but may be `null` depending on permissions
160- **user.email**: Another source from the API that may contain the real email depending on server configuration
161- **Message sender email**: Always available but often an auto-generated internal identifier
162
163The bot tries each in order until it finds a usable email address.
164
165## Admin Considerations
166
167- **No admin permissions needed** - Users can register themselves
168- **Server-side storage** - All data is stored using Zulip's bot storage API
169- **No custom profile fields required** - Works out of the box on any Zulip instance
170- **Privacy** - Only registered users appear in the directory (opt-in)