anil.recoil.org / slop
My agentic slop goes here. Not intended for anyone else!
fork atom
slop / stack / vicuna / USAGE.md
at 2e57b99c7facfca67595741b51d79f40df77fa2b 4.9 kB view raw view code

Vicuna Bot - Quick Usage Guide#

The Email Problem#

When you authenticate to Zulip using OAuth, SSO, or other third-party authentication methods, Zulip often assigns you an auto-generated email address like:

  • user123@zulipchat.com
  • person456@zulip.example.com

This isn't your actual email address - it's just an internal identifier.

The Smart Solution#

Good news! Vicuna now automatically detects your real email address from your Zulip profile!

Most users can simply type register and the bot will try multiple sources:

  1. Your delivery_email from Zulip profile (the real email associated with your account)
  2. Your user.email from Zulip profile API (may be your real email depending on server config)
  3. Your Zulip message sender email as a fallback

No need to manually provide your email in most cases!

Registration Options#

Option 1: Smart Auto-Detection (RECOMMENDED - Just type register)#

> register

The bot will automatically fetch your real email from your Zulip profile!

Response (when delivery_email is available):

✅ Successfully registered!
• Email: `alice@mycompany.com`
• Zulip ID: `12345`
• Full Name: `Alice Smith`

💡 Your Zulip email is: `user123@zulipchat.com`
📧 Using your delivery email from your profile
You can now be @mentioned by your email or Zulip ID!

The bot automatically found alice@mycompany.com from your profile!

Response (when delivery_email is NOT available):

✅ Successfully registered!
• Email: `user123@zulipchat.com`
• Zulip ID: `12345`
• Full Name: `Alice Smith`

💡 Your Zulip email is: `user123@zulipchat.com`
You can now be @mentioned by your email or Zulip ID!

Falls back to Zulip email if delivery_email isn't available.

Option 2: Manual Email Override#

> register alice@mycompany.com

Manually specify a custom email (overrides auto-detection).

Response:

✅ Successfully registered!
• Email: `alice@mycompany.com`
• Zulip ID: `12345`
• Full Name: `Alice Smith`

💡 Your Zulip email is: `user123@zulipchat.com`
📝 Using the custom email you provided
You can now be @mentioned by your email or Zulip ID!

Lookup Examples#

Find Someone by Email#

> whois alice@mycompany.com

👤 User found:
• Email: `alice@mycompany.com`
• Zulip ID: `12345`
• Full Name: `Alice Smith`
• Registered: 2025-01-15 10:30:45

Find Someone by Zulip ID#

> whois 12345

👤 User found:
• Email: `alice@mycompany.com`
• Zulip ID: `12345`
• Full Name: `Alice Smith`
• Registered: 2025-01-15 10:30:45

Check Your Status#

> whoami

📋 Your registration info:
• Email: `alice@mycompany.com`
• Zulip ID: `12345`
• Full Name: `Alice Smith`
• Registered: 2025-01-15 10:30:45

List All Users#

> list

📋 Registered users (3):
• **Alice Smith** (`alice@mycompany.com`) - ID: 12345
• **Bob Jones** (`bob@company.org`) - ID: 67890
• **Carol White** (`carol@example.com`) - ID: 54321

Get Help#

> help

Shows all available commands and examples.

Pro Tips#

  1. Just type register - In most cases, the bot will automatically find your real email from your profile!
  2. Check if it worked - Use whoami after registering to see which email was used
  3. Manual override if needed - If the auto-detection didn't work, use register your-email@example.com
  4. Encourage your team to register - The more people registered, the more useful the directory
  5. Update your registration - If your email changes, just register again with the new one
  6. The bot stores both emails - It knows your registered email AND your Zulip internal email

How Smart Detection Works#

The bot uses this priority order:

  1. Custom email (if you provide one): register alice@company.com - Highest priority
  2. delivery_email (from Zulip profile API): Your real email address associated with the account
  3. user.email (from Zulip profile API): Email from profile (if different from message sender)
  4. Message sender email (fallback): The internal user@zulipchat.com style email

This means the bot will use the best available email automatically!

Why Multiple Sources?#

  • delivery_email: The most reliable source for real email, but may be null depending on permissions
  • user.email: Another source from the API that may contain the real email depending on server configuration
  • Message sender email: Always available but often an auto-generated internal identifier

The bot tries each in order until it finds a usable email address.

Admin Considerations#

  • No admin permissions needed - Users can register themselves
  • Server-side storage - All data is stored using Zulip's bot storage API
  • No custom profile fields required - Works out of the box on any Zulip instance
  • Privacy - Only registered users appear in the directory (opt-in)