feat: bot alias reservation + BOT_API.md documentation

- Aliases ending with Bot/bot/_bot reserved for registered bots only
- Non-bot users get clear error directing to /v1/bot/register
- Bot registration auto-creates alias (@name_bot suffix)
- BOT_API.md: full developer guide with endpoints, examples, echo bot
- LLM_HELP.md: expanded bot section with update types + Python example

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

warzone/crates/warzone-server/src/routes/aliases.rs

@@ -123,6 +123,18 @@ async fn register_alias(
         return Ok(Json(serde_json::json!({ "error": "alias must be 1-32 alphanumeric chars" })));
     }
 
+    // Reserve *Bot and *_bot suffixes for bots only
+    let is_bot_name = alias.ends_with("bot") || alias.ends_with("_bot");
+    if is_bot_name {
+        // Check if this fingerprint is registered as a bot
+        let bot_key = format!("bot_fp:{}", fp);
+        let is_registered_bot = state.db.tokens.get(bot_key.as_bytes())
+            .ok().flatten().is_some();
+        if !is_registered_bot {
+            return Ok(Json(serde_json::json!({ "error": "aliases ending with 'Bot' or '_bot' are reserved for bots — register via /v1/bot/register first" })));
+        }
+    }
+
     // Check existing record for this alias
     if let Some(existing) = load_alias_record(&state.db.aliases, &alias) {
         if existing.fingerprint == fp {

warzone/crates/warzone-server/src/routes/bot.rs

@@ -100,12 +100,25 @@ async fn register_bot(
         &token[..token.len().min(20)]
     );
 
+    // Auto-register bot alias (name must end with Bot or _bot)
+    let bot_alias = if req.name.ends_with("Bot") || req.name.ends_with("_bot") || req.name.ends_with("bot") {
+        req.name.to_lowercase()
+    } else {
+        format!("{}_bot", req.name.to_lowercase())
+    };
+    let alias_key = format!("a:{}", bot_alias);
+    let _ = state.db.aliases.insert(alias_key.as_bytes(), fp.as_bytes());
+    let fp_key = format!("fp:{}", fp);
+    let _ = state.db.aliases.insert(fp_key.as_bytes(), bot_alias.as_bytes());
+    tracing::info!("Bot alias @{} registered for {}", bot_alias, fp);
+
     Ok(Json(serde_json::json!({
         "ok": true,
         "result": {
             "token": token,
             "name": req.name,
             "fingerprint": fp,
+            "alias": format!("@{}", bot_alias),
         }
     })))
 }