antenna-openclaw-plugin 1.3.0 → 1.3.2

package/index.ts

@@ -268,7 +268,7 @@ export default function register(api: any) {
         channel: { type: "string", description: "The channel name" },
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
       },
-      required: ["sender_id", "channel"],
+      required: ["sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -277,7 +277,7 @@ export default function register(api: any) {
       const radius = params.radius_m ?? cfg.defaultRadiusM ?? 500;
 
       if (isRateLimited(deviceId)) {
-        return ok({ nearby: [], message: "刚刚才扫描过，稍等一会儿再试。", rate_limited: true });
+        return ok({ profiles: [], message: "刚刚才扫描过，稍等一会儿再试。", rate_limited: true });
       }
 
       let lat = params.lat;
@@ -290,7 +290,7 @@ export default function register(api: any) {
           lat = loc.lat;
           lng = loc.lng;
         } else {
-          return ok({ nearby: [], message: "还没有位置信息。请先通过链接分享位置，或者发送位置消息。" });
+          return ok({ profiles: [], message: "还没有位置信息。请先通过链接分享位置，或者发送位置消息。" });
         }
       }
 
@@ -323,11 +323,11 @@ export default function register(api: any) {
             try { await supabase.rpc("log_recommendation", { p_device_id: deviceId, p_recommended_id: p.device_id }); } catch {}
           }
           return ok({
-            nearby: gProfiles, total: gProfiles.length, radius_m: radius, global: true,
+            profiles: gProfiles, count: gProfiles.length, radius_m: radius, global: true,
             message: `附近 ${radius}m 暂时没人。今天的全球推荐——这个人跟你可能聊得来。（每天 1 次）`,
           });
         }
-        return ok({ nearby: [], message: `附近暂时没人，今天的全球推荐已经用完了。明天再来！` });
+        return ok({ profiles: [], message: `附近暂时没人，今天的全球推荐已经用完了。明天再来！` });
       }
 
       // Build ref mapping — never expose device_id
@@ -353,8 +353,8 @@ export default function register(api: any) {
       } catch { /* best effort */ }
 
       return ok({
-        nearby: profiles,
-        total: others.length,
+        profiles: profiles,
+        count: others.length,
         radius_m: radius,
         instruction: "根据你对用户的了解，判断哪些人值得推荐，用 ref 编号引用。不要显示 device_id。",
       });
@@ -381,8 +381,9 @@ export default function register(api: any) {
         line2: { type: "string", description: "Second line (what you're into)" },
         line3: { type: "string", description: "Third line (what you're looking for)" },
         visible: { type: "boolean", description: "Whether to be visible to others" },
+        matching_context: { type: "string", description: "Free-form context for AI matching (interests, goals, etc.)" },
       },
-      required: ["action", "sender_id", "channel"],
+      required: ["action", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -406,6 +407,7 @@ export default function register(api: any) {
         p_display_name: params.display_name ?? null, p_emoji: params.emoji ?? null,
         p_line1: params.line1 ?? null, p_line2: params.line2 ?? null,
         p_line3: params.line3 ?? null, p_visible: params.visible ?? true,
+        ...(params.matching_context != null ? { p_matching_context: params.matching_context } : {}),
       });
 
       if (error) return ok({ error: error.message });
@@ -436,7 +438,7 @@ export default function register(api: any) {
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
         place_name: { type: "string", description: "Optional: name of the place (for confirmation message)" },
       },
-      required: ["lat", "lng", "sender_id", "channel"],
+      required: ["lat", "lng", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -484,7 +486,7 @@ export default function register(api: any) {
         target_device_id: { type: "string", description: "Device ID (use ref instead when possible)" },
         contact_info: { type: "string", description: "Optional contact info to share" },
       },
-      required: ["sender_id", "channel"],
+      required: ["sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -560,7 +562,7 @@ export default function register(api: any) {
         purpose: { type: "string", description: "'profile' (default) or 'event'" },
         event_code: { type: "string", description: "Event code (required when purpose=event)" },
       },
-      required: ["sender_id", "channel"],
+      required: ["sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -601,7 +603,7 @@ export default function register(api: any) {
         channel: { type: "string", description: "The channel name" },
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
       },
-      required: ["sender_id", "channel"],
+      required: ["sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -690,7 +692,7 @@ export default function register(api: any) {
         requires_approval: { type: "boolean", description: "Require host approval to join (default false)" },
         screening_questions: { type: "array", items: { type: "string" }, description: "Screening questions for applicants" },
       },
-      required: ["name", "sender_id", "channel", "starts_at", "ends_at"],
+      required: ["name", "sender_id", "channel", "starts_at", "ends_at", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -727,7 +729,7 @@ export default function register(api: any) {
         channel: { type: "string" },
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
       },
-      required: ["code", "sender_id", "channel"],
+      required: ["code", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -759,7 +761,7 @@ export default function register(api: any) {
         lng: { type: "number", description: "Longitude (optional, for auto-checkin)" },
         application_context: { type: "string", description: "Application context from screening conversation" },
       },
-      required: ["code", "sender_id", "channel"],
+      required: ["code", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -783,7 +785,7 @@ export default function register(api: any) {
         } catch {}
       }
 
-      const { data, error } = await supabase.rpc("join_event", { p_code: params.code, p_device_id: deviceId, p_application_context: params.application_context || null });
+      const { data, error } = await supabase.rpc("join_event", { p_code: params.code, p_device_id: deviceId, p_lat: lat || null, p_lng: lng || null, p_application_context: params.application_context || null });
       if (error) return ok({ error: error.message });
       if (!data?.joined) return ok(data);
 
@@ -841,7 +843,7 @@ export default function register(api: any) {
         channel: { type: "string" },
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
       },
-      required: ["code", "sender_id", "channel"],
+      required: ["code", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -881,7 +883,7 @@ export default function register(api: any) {
         ref: { type: "string", description: "Ref number from scan/discover results" },
         target_device_id: { type: "string", description: "Device ID (use ref instead when possible)" },
       },
-      required: ["sender_id", "channel"],
+      required: ["sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -918,7 +920,7 @@ export default function register(api: any) {
         lat: { type: "number", description: "Latitude (optional)" },
         lng: { type: "number", description: "Longitude (optional)" },
       },
-      required: ["code", "sender_id", "channel"],
+      required: ["code", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -977,60 +979,44 @@ export default function register(api: any) {
         channel: { type: "string" },
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
       },
-      required: ["sender_id", "channel"],
+      required: ["sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
       const supabase = getSupabase(cfg);
       const deviceId = deriveDeviceId(params.sender_id, params.channel, params.chat_id);
 
-      const { data: allMatches } = await supabase.rpc("get_my_matches", { p_device_id: deviceId });
+      const { data: result } = await supabase.rpc("get_my_matches_with_profiles", { p_device_id: deviceId });
 
-      if (!allMatches?.length) {
-        return ok({ mutual_matches: [], incoming_accepts: [], message: "目前没有进行中的匹配。" });
-      }
+      const rawMutual = result?.mutual_matches || [];
+      const rawIncoming = result?.incoming_accepts || [];
 
-      // Matches I initiated
-      const myMatches = allMatches.filter((m: any) => m.device_id_a === deviceId);
-      // Matches where someone else accepted me
-      const incomingMatches = allMatches.filter((m: any) => m.device_id_b === deviceId);
-
-      // --- Mutual matches (both sides accepted) ---
-      const mutualMatches = [];
-      for (const match of myMatches) {
-        const reverse = incomingMatches.find(
-          (m: any) => m.device_id_a === match.device_id_b
-        );
-        if (reverse) {
-          // Clean up follow-up crons for this mutual pair
-          stopFollowUpCron(deviceId, match.device_id_b, logger);
-          stopFollowUpCron(match.device_id_b, deviceId, logger);
-
-          const { data: profile } = await supabase.rpc("get_profile", { p_device_id: match.device_id_b });
-          mutualMatches.push({
-            device_id: match.device_id_b,
-            name: profile?.display_name || "匿名", emoji: profile?.emoji || "👤",
-            line1: profile?.line1, line2: profile?.line2, line3: profile?.line3,
-            their_contact: reverse.contact_info_a || null, you_shared: match.contact_info_a || null,
-          });
-        }
+      if (!rawMutual.length && !rawIncoming.length) {
+        return ok({ mutual_matches: [], incoming_accepts: [], message: "目前没有进行中的匹配。" });
       }
 
-      // --- Incoming accepts (someone accepted me but I haven't accepted them yet) ---
-      const incomingAccepts = [];
-      for (const match of incomingMatches) {
-        const iAccepted = myMatches.find(
-          (m: any) => m.device_id_b === match.device_id_a
-        );
-        if (!iAccepted) {
-          // They accepted me but I haven't responded
-          const { data: profile } = await supabase.rpc("get_profile", { p_device_id: match.device_id_a });
-          incomingAccepts.push({
-            device_id: match.device_id_a,
-            name: profile?.display_name || "匿名", emoji: profile?.emoji || "👤",
-            line1: profile?.line1, line2: profile?.line2, line3: profile?.line3,
-          });
-        }
+      const mutualMatches = rawMutual.map((m: any, i: number) => ({
+        ref: String(i + 1),
+        _device_id: m.target_id,
+        name: m.name || "匿名",
+        emoji: m.emoji || "👤",
+        line1: m.line1, line2: m.line2, line3: m.line3,
+        their_contact: m.their_contact || null,
+        you_shared: m.you_shared || null,
+      }));
+
+      const incomingAccepts = rawIncoming.map((m: any, i: number) => ({
+        ref: String(i + 1),
+        _device_id: m.target_id,
+        name: m.name || "匿名",
+        emoji: m.emoji || "👤",
+        line1: m.line1, line2: m.line2, line3: m.line3,
+      }));
+
+      // Clean up follow-up crons for mutual matches
+      for (const m of mutualMatches) {
+        stopFollowUpCron(deviceId, m._device_id, logger);
+        stopFollowUpCron(m._device_id, deviceId, logger);
       }
 
       const messages = [];
@@ -1067,7 +1053,7 @@ export default function register(api: any) {
         starts_at: { type: "string", description: "New start time ISO" },
         ends_at: { type: "string", description: "New end time ISO" },
       },
-      required: ["code", "sender_id", "channel"],
+      required: ["code", "sender_id", "channel", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -1099,7 +1085,7 @@ export default function register(api: any) {
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
         ref: { type: "string", description: "Ref number of the participant to approve" },
       },
-      required: ["code", "sender_id", "channel", "ref"],
+      required: ["code", "sender_id", "channel", "ref", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -1128,7 +1114,7 @@ export default function register(api: any) {
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
         ref: { type: "string", description: "Ref number of the participant to reject" },
       },
-      required: ["code", "sender_id", "channel", "ref"],
+      required: ["code", "sender_id", "channel", "ref", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);
@@ -1157,7 +1143,7 @@ export default function register(api: any) {
         chat_id: { type: "string", description: "REQUIRED for notifications. Pass the chat/channel ID from your message context so Antenna can send you match and event notifications." },
         ref: { type: "string", description: "Ref number of the participant to make co-host" },
       },
-      required: ["code", "sender_id", "channel", "ref"],
+      required: ["code", "sender_id", "channel", "ref", "chat_id"],
     },
     async execute(_id: string, params: any) {
       const cfg = getConfig(api);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antenna-openclaw-plugin",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Antenna — agent-mediated nearby people discovery for OpenClaw",
   "openclaw": {
     "extensions": ["./index.ts"]

package/skills/antenna/SKILL.md

@@ -10,7 +10,7 @@ You have access to Antenna for location-based social discovery.
 
 **How to call Antenna:**
 - If you have Antenna plugin tools registered (antenna_scan, antenna_profile, etc.) — use them directly.
-- If not, use CLI: `antenna <command> [flags]`. Example: `antenna scan --id telegram:123`. The CLI supports all the same features.
+- If not, use CLI: `antenna <command> [flags]`. Example: `antenna scan --id <platform>:<user_id>`. The CLI supports all the same features.
 - All tool names map to CLI commands: `antenna_scan` → `antenna scan`, `antenna_event_create` → `antenna event --create`, etc.
 - **Always pass `chat_id`** when calling any Antenna tool. This is the chat/channel ID from your message context (e.g. Discord channel ID, Telegram chat ID). Antenna uses it to send you notifications about matches and event approvals.
 
@@ -62,15 +62,24 @@ cron 设完后，问用户一句：
 
 **第六步：启动实时通知**
 
-onboarding 完成后，启动 `antenna watch` 后台进程，实时接收匹配通知和活动审批通知：
+onboarding 完成后，启动 `antenna watch` 后台进程，实时接收匹配通知和活动审批通知。
+
+**判断方法（不要猜）：**
+1. 先试 `antenna status --id <device_id>` — 如果输出 "Watch: ✅ running"，已经在跑，不需要再启动
+2. 如果不在跑，试 `antenna watch --id <device_id> --push hermes,openclaw &` 启动后台进程
+3. 如果 exec 报错（不支持后台进程），用 cron 替代：
+
+Hermes cron:
 ```
-antenna watch --id <device_id> &
+hermes cron add --every 1h --message "Check antenna matches: call antenna_check_matches. If there are new mutual matches or incoming accepts, tell the user. If nothing new, reply HEARTBEAT_OK."
 ```
-这会保持一个 WebSocket 连接，有新匹配或活动审批变更时立即通知。比 cron 更实时。
 
-**Health check:** 每次对话开始时，跑 `antenna status --id <device_id>` 检查 watch 是否在跑。如果显示 "Watch: ❌ not running"，重新启动 `antenna watch --id <device_id> &`。
+OpenClaw cron:
+```
+openclaw cron add --every 1h --message "Check antenna matches: call antenna_check_matches. If there are new mutual matches or incoming accepts, tell the user. If nothing new, reply HEARTBEAT_OK."
+```
 
-如果 exec 不支持后台进程，cron 是 fallback。
+**优先级：** watch > cron。watch 是 2 分钟延迟，cron 是 1 小时。
 
 ## When to use
 
@@ -85,10 +94,11 @@ antenna watch --id <device_id> &
 
 ### `antenna_scan`
 Scan for nearby people **and events**. Returns raw profile cards + active events within 5km.
+**Read-only — does NOT update your location.** To update location, use `antenna_checkin` or `antenna_bind`.
 - `lat`, `lng`: coordinates (from `LocationLat`/`LocationLon` context, or geocoded from user input)
 - `radius_m`: search radius in meters (default 500, max 1000) for people; events search uses 5km
 - `sender_id`: the user's id from message context
-- `channel`: the channel name (telegram, whatsapp, discord, etc.)
+- `channel`: the platform/channel name (any platform works: telegram, discord, whatsapp, webchat, signal, slack, matrix, clawx, etc.)
 - Returns `profiles` (nearby people) + `nearby_events` (active events with name, participants count, code)
 
 **Location staleness:** Before scanning, check if the user's GPS is recent. If `last_seen_at` is older than 2 hours, prompt the user to update their location (`antenna_bind` or `antenna_checkin`). Stale GPS = wrong results.
@@ -132,8 +142,6 @@ The name card has:
 
 **After saving the profile, generate `matching_context` automatically** based on your knowledge of the user (memory, conversations, context). Don't ask the user to write it — you write it. Example:
 > "Product designer at a tech company in Beijing, focusing on AI search experience. Interested in music (Sakamoto), swimming, cooking, language learning. Recently exploring AI agent ecosystems and social discovery. Looking to connect with AI builders, indie hackers, and creative technologists."
-- **line2**: what they're into
-- **line3**: what they're looking for right now
 
 ### `antenna_accept`
 Accept a match after the user sees results. Can optionally include contact info to share.
@@ -222,7 +230,7 @@ Source code is open: https://github.com/H1an1/Antenna
 > "最后——你想被叫什么？再选个 emoji 代表你自己。"
 
 **第六步：确认**
-把名片组装好，展示给用户确认：
+把名片组装好，**确认三行都有内容后**展示给用户确认：
 > 你的名片：
 >
 > 🎸 **小林**
@@ -232,7 +240,8 @@ Source code is open: https://github.com/H1an1/Antenna
 >
 > 看看有没有要改的？OK 的话我就存了。
 
-用户说 OK → `antenna_profile` action="set" 保存。
+用户说 OK → **检查 line1、line2、line3 都不为空后** 调 `antenna_profile` action="set" 保存。
+如果某一行为空，先问用户补完再保存。后端会拒绝没有 line1 的新 profile，并对缺失的 line2/line3 返回 warning。
 用户说要改 → 改完再确认。
 
 **关键原则：**
@@ -245,6 +254,10 @@ Source code is open: https://github.com/H1an1/Antenna
 
 ### Showing results — 你来判断，不是服务器
 
+**第一次 scan 的新用户：** 简短一句解释："这是附近的人。Antenna 基于 AI 匹配，看到感兴趣的人 accept，双向匹配后交换联系方式。"
+
+**Profile 不完整时：** 如果用户的 profile 只有 1 行，提示："你的名片只填了一行，补完后匹配质量会更好。要现在补吗？"
+
 `antenna_scan` 返回的是附近所有人的名片，**没有打分、没有预匹配**。你需要：
 
 **全球推荐 fallback：** 如果 scan 结果里有 `global: true`，说明附近没人，这些是全球推荐。告诉用户“附近暂时没人，但全球有这几个有意思的人”，然后正常推荐。用户仍然可以 accept。
@@ -253,7 +266,7 @@ Source code is open: https://github.com/H1an1/Antenna
 2. 结合你对用户的全部了解，判断谁值得推荐
 3. 为每个推荐的人写一句**个性化的理由**——不是"你们都提到了 X"，而是真正有洞察的话
 
-**⚠️ 隐私规则：展示结果时绝对不要显示 device_id。** `device_id`（如 `telegram:koji1986`）是内部标识符，包含用户的平台和 ID，属于隐私信息。只显示 emoji + 名字 + 三句话 + 你写的匹配理由。`device_id` 只在内部调 `antenna_accept` 时用，不要展示给用户。
+**⚠️ 隐私规则：展示结果时绝对不要显示 device_id。** `device_id`（如 `platform:user123`）是内部标识符，包含用户的平台和 ID，属于隐私信息。只显示 emoji + 名字 + 三句话 + 你写的匹配理由。`device_id` 只在内部调 `antenna_accept` 时用，不要展示给用户。
 
 比如你知道用户最近在学吉他，看到附近有人写"组乐队找吉他手"：
 > 🎸 **小林** — 在组后摇乐队，找吉他手
@@ -288,7 +301,7 @@ Use `antenna_check_matches` when:
 
 ### Privacy
 - Never reveal exact coordinates to other users
-- **Never show device_id to users** (e.g. `telegram:123`, `wechat:xxx`) — this is internal only
+- **Never show device_id to users** (e.g. `telegram:12345`, `discord:67890`) — this is internal only
 - Never share someone's platform or username with another user
 - Only show the profile info (name, emoji, three lines)
 - Contact info is only shared when the user explicitly agrees
@@ -314,10 +327,11 @@ Plugin 自带后台服务，每 10 分钟轮询一次 Supabase 查新的 mutual
 
 ### `antenna_event_create`
 Create an event. Returns a shareable link (antenna.fyi/events/CODE).
-- `name`: event name
-- `sender_id`, `channel`: from context
-- `lat`, `lng`: optional event location
-- `starts_at`, `ends_at`: optional time range (default: now to +12h)
+- `name`: event name (required)
+- `sender_id`, `channel`: from context (required)
+- `chat_id`: REQUIRED for notifications
+- `starts_at`, `ends_at`: ISO time strings (required — no default, must be provided)
+- `lat`, `lng`: optional event location (needed for GPS check-in)
 - `description`: optional event description
 - `og_image`: optional OG image URL for social sharing preview
 - `requires_approval`: boolean, default false. If true, participants need organizer approval.
@@ -331,23 +345,30 @@ Create an event. Returns a shareable link (antenna.fyi/events/CODE).
 End an event. Only the creator can end it.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 
 ### `antenna_event_join`
 Join an event by code.
 - `code`: from the event URL (antenna.fyi/events/CODE)
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 
 ### `antenna_event_scan`
 Scan people in an event. No distance limit — returns all participants.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - Returns profiles with `source: "event"` tag
 
 ### `antenna_event_checkin`
 Check in at an event — marks you as present at the event location. Optionally updates GPS.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `lat`, `lng`: optional GPS coordinates
+- **Event must have started** (`starts_at <= now`). Cannot check in before start time.
+- **Must be within 1km** of event location.
+- **Must have `status: active`** (approved participants only, not pending).
 
 ### `antenna_event_upload_image`
 Upload an image for an event OG preview. Returns a public URL.
@@ -359,35 +380,41 @@ Upload an image for an event OG preview. Returns a public URL.
 Update event info. Only creator or co-host can update.
 - `code`: event code
 - `sender_id`, `channel`: from context
-- `name`, `description`, `og_image`, `lat`, `lng`, `starts_at`, `ends_at`: all optional, only provided fields are updated
+- `chat_id`: REQUIRED for notifications
+- `name`, `description`, `og_image`, `lat`, `lng`, `starts_at`, `ends_at`: all optional for update (only provided fields change, others stay as-is)
 
 ### `antenna_event_approve`
 Approve a pending participant. Only creator or co-host.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `ref`: participant ref number from scan
 
 ### `antenna_event_reject`
 Reject a pending participant. Only creator or co-host.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `ref`: participant ref number from scan
 
 ### `antenna_event_add_host`
 Add a co-host to the event. Only creator can add.
 - `code`: event code
 - `sender_id`, `channel`: from context
+- `chat_id`: REQUIRED for notifications
 - `ref`: participant ref number to promote to co-host
 
 ---
 
-## Part 2: Event Behavior Guide
+## Event Behavior Guide
+
+> This section is the single source of truth for event behavior. Tool descriptions above define parameters; this section defines agent behavior.
 
 ### Creating an event
 Collect info through conversation (ask one by one, don't dump all at once):
 1. **Event name** (required) — "活动叫什么名字？"
 2. **Description** — "简单描述一下这个活动？"
-3. **Time** — "什么时候开始？大概多长？" (convert to starts_at / ends_at ISO strings)
+3. **Time** (required) — "什么时候开始？大概多长？" (convert to `starts_at` / `ends_at` ISO strings. **Must provide both — no defaults.**)
 4. **Location** — "活动在哪里？" If user gives an address, geocode it. If vague, generate a bind link after creation.
 5. **Approval** — "需要审批参与者吗？" If yes:
 6. **Screening questions** — "你想问报名者什么问题？" Collect as a list.
@@ -416,3 +443,9 @@ Only creator or co-host can approve/reject:
 - `antenna_event_approve(code, ref)` → participant becomes active
 - `antenna_event_reject(code, ref)` → participant is rejected
 - Notifications are sent automatically to the applicant
+
+### Key differences from regular scan
+- `antenna_scan` = nearby discovery, read-only, does NOT write location
+- `antenna_event_scan` = event participants, no distance limit
+- `antenna_checkin` = update YOUR location (not event-related)
+- `antenna_event_checkin` = mark presence at an EVENT (GPS verified, event must have started)

package/skills/antenna/EVENTS.md

@@ -1,112 +0,0 @@
----
-name: antenna-events
-description: "Antenna Event Mode — create events, manage participants, GPS check-in. Use when a user wants to create an event, join an event, check in, scan event participants, or manage event settings."
-tools:
-  - antenna_event_create
-  - antenna_event_join
-  - antenna_event_scan
-  - antenna_event_end
-  - antenna_event_checkin
-  - antenna_event_upload_image
-  - antenna_bind
----
-
-# Antenna Event Mode
-
-Create real-world events where everyone's AI agent handles the networking.
-
-## Quick Start
-
-1. **Create**: `antenna_event_create(name, description)` → get shareable link
-2. **Share**: Send `antenna.fyi/events/CODE` to attendees
-3. **Join**: Attendees' agents call `antenna_event_join(code)`
-4. **Check in**: At the venue, `antenna_event_checkin(code)` — GPS verified ≤1km
-5. **Discover**: `antenna_event_scan(code)` — no distance limit inside events
-
-## Tools
-
-### `antenna_event_create`
-Create an event. Returns a shareable link (antenna.fyi/events/CODE).
-- `name`: event name
-- `sender_id`, `channel`: from context
-- `lat`, `lng`: optional event location
-- `starts_at`, `ends_at`: optional time range (default: now to +12h)
-- `description`: optional event description
-- `og_image`: optional OG image URL for social sharing preview
-- `requires_approval`: boolean, default false. If true, participants must be approved by the organizer before they become visible.
-- `screening_questions`: string array. Questions to ask applicants. Agent should collect answers via conversation and submit as `application_context` when joining.
-
-**When the user says anything about "审批" / "approval" / "筛选" / "报名表"**, set `requires_approval: true` and ask what screening questions they want.
-
-**GPS flow for events:** If the user doesn't provide coordinates, generate a bind link (`antenna_bind` with `purpose="event"` and `event_code`) and ask them to open it at the event location. The GPS will update the event's coordinates, NOT the user's profile.
-
-### `antenna_event_join`
-Join an event by code. Auto-checks in if event already started and user GPS is within 1km.
-- `code`: from the event URL (antenna.fyi/events/CODE)
-- `sender_id`, `channel`: from context
-- **Requires profile** — user must have a profile before joining
-- If event has started + user has GPS + within 1km → auto check-in
-
-### `antenna_event_scan`
-Scan people in an event. No distance limit — returns all participants.
-- `code`: event code
-- `sender_id`, `channel`: from context
-- Returns profiles with `checked_in` status and `role` (creator/participant)
-- Header shows "X joined, Y checked in"
-
-### `antenna_event_end`
-End an event. Only the creator can end it.
-- `code`: event code
-- `sender_id`, `channel`: from context
-
-### `antenna_event_checkin`
-Check in at an event — marks you as present at the event location.
-- `code`: event code
-- `sender_id`, `channel`: from context
-- `lat`, `lng`: optional GPS (auto-reads profile location if not provided)
-- GPS verified: must be within 1km of event location
-- Event must have GPS set for check-in to work
-
-### `antenna_event_upload_image`
-Upload an image for an event OG preview. Returns a public URL.
-- `image_base64`: base64-encoded image data
-- `content_type`: MIME type (default image/png)
-- `event_code`: event code
-
-### `antenna_bind` (for events)
-Generate a GPS link for setting event location.
-- `purpose`: set to `"event"`
-- `event_code`: the event code
-- GPS from this link writes to the event, not the user's profile
-
-## Agent Behavior
-
-### When someone says "create an event"
-Collect the following info through conversation (ask one by one, don't dump all at once):
-1. **Event name** (required) — "活动叫什么名字？"
-2. **Description** — "简单描述一下这个活动？"
-3. **Time** — "什么时候开始？大概多长？" (convert to starts_at / ends_at ISO strings)
-4. **Location** — "活动在哪里？" If user gives an address, geocode it. If vague, generate a bind link after creation.
-5. **Approval** — "需要审批参与者吗？" If yes:
-6. **Screening questions** — "你想问报名者什么问题？" Collect as a list.
-
-Then call `antenna_event_create` with all collected info.
-If no GPS, call `antenna_bind(purpose="event", event_code=CODE)` and send the link.
-Share the event URL with the user.
-
-### When someone shares an event link
-1. Extract the code from `antenna.fyi/events/CODE`
-2. Call `antenna_event_join(code)` — this checks everything:
-   - If no profile → "Create a profile first"
-   - If event requires approval and no `application_context` provided → returns `needs_screening: true` + `screening_questions` array
-   - If screening questions returned: **ask the user each question**, collect answers, then call `antenna_event_join(code, application_context="collected answers")` again
-   - If join succeeds with `status: pending` → tell user "waiting for organizer approval"
-   - If join succeeds with `status: active` → user is in!
-3. Auto check-in happens automatically if event has started + GPS within 1km
-
-### When someone says "who's here" at an event
-1. Call `antenna_event_scan(code)`
-2. Analyze profiles against what you know about the user
-3. Recommend who they should meet and why
-4. Creator appears with organizer badge
-