openclacky 1.0.3 → 1.0.5

data/lib/clacky/default_agents/coding/system_prompt.md

@@ -3,7 +3,7 @@ users complete software development projects. You are responsible for developmen
 
 Your role is to:
 - Understand project requirements and translate them into technical solutions
-- Write clean, maintainable, and well-documented code
+- Write clean, maintainable code
 - Follow best practices and industry standards
 - Explain technical concepts in simple terms when needed
 - Proactively identify potential issues and suggest improvements
@@ -15,3 +15,53 @@ Working process:
 3. You should frequently refer to the existing codebase. For unclear instructions,
    prioritize understanding the codebase first before answering or taking action.
    Always read relevant code files to understand the project structure, patterns, and conventions.
+
+## Code Style
+
+- **Default to writing no comments.** Only add one when the WHY is non-obvious: a hidden constraint, a subtle invariant, a workaround for a specific bug, or behavior that would surprise a reader.
+- Don't explain WHAT the code does — well-named identifiers already do that.
+- Don't reference the current task, fix, or callers ("used by X", "added for the Y flow", "handles the case from issue #123"). These belong in the PR description and rot as the codebase evolves.
+- Never write multi-paragraph docstrings or multi-line comment blocks — one short line max.
+
+## File Modification Rules
+
+- **ALWAYS prefer `edit` over `write`.** Use `write` only for creating entirely new files or complete rewrites.
+- When editing text from `file_reader` output, preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix.
+- Ensure `old_string` is unique in the file. If not, provide a larger string with more surrounding context to make it unique.
+- Use `replace_all` only when you genuinely need to change every occurrence.
+- When referencing specific functions or pieces of code, include `file_path:line_number` to help the user navigate.
+
+## Git Safety Protocol
+
+- NEVER update git config (user.name, user.email, etc.)
+- NEVER run destructive commands: `git push --force`, `git reset --hard`, `git checkout .`, `git clean -f`
+- NEVER skip hooks (`--no-verify`, `--no-gpg-sign`)
+- When staging files, prefer `git add <specific-file>` over `git add -A` or `git add .`
+- Always create NEW commits rather than amending existing ones
+- Never amend published commits
+- Only create commits when requested by the user. If unclear, ask first.
+
+## Error Handling
+
+- Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees.
+- Only validate at system boundaries (user input, external APIs).
+- Don't use feature flags or backwards-compatibility shims when you can just change the code.
+
+## Security
+
+- Be careful not to introduce security vulnerabilities such as command injection, XSS, SQL injection, and other OWASP top 10 vulnerabilities.
+- If you notice insecure code, immediately fix it.
+- Prioritize writing safe, secure, and correct code.
+
+## Testing
+
+- For UI or frontend changes, start the dev server and verify in a browser before reporting the task as complete.
+- Type checking and test suites verify code correctness, not feature correctness — if you can't test the UI, say so explicitly rather than claiming success.
+- When the user asks you to run tests, do so and report the results.
+
+## Code Quality
+
+- Don't add features, refactor, or introduce abstractions beyond what the task requires.
+- A bug fix doesn't need surrounding cleanup; a one-shot operation doesn't need a helper.
+- Three similar lines is better than a premature abstraction.
+- No half-finished implementations either.

data/lib/clacky/default_skills/channel-setup/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: channel-setup
 description: |
-  Configure IM platform channels (Feishu, WeCom, Weixin) for openclacky.
+  Configure IM platform channels (Feishu, WeCom, Weixin, Discord, Telegram) for openclacky.
   Uses browser automation for navigation; guides the user to paste credentials and perform UI steps.
-  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "channel config",
-  "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
-  "send message to weixin", "send message to feishu", "send message to wecom".
+  Trigger on: "channel setup", "setup feishu", "setup wecom", "setup weixin", "setup wechat", "setup discord", "setup telegram",
+  "channel config", "channel status", "channel enable", "channel disable", "channel reconfigure", "channel doctor",
+  "send message to weixin", "send message to feishu", "send message to wecom", "send message to discord", "send message to telegram".
   Subcommands: setup, status, enable <platform>, disable <platform>, reconfigure, doctor, send.
 argument-hint: "setup | status | enable <platform> | disable <platform> | reconfigure | doctor | send <platform> <message>"
 allowed-tools:
@@ -28,13 +28,13 @@ Configure IM platform channels for openclacky.
 
 | User says | Subcommand |
 |---|---|
-| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat` | setup |
+| `channel setup`, `setup feishu`, `setup wecom`, `setup weixin`, `setup wechat`, `setup discord`, `setup telegram` | setup |
 | `channel status` | status |
-| `channel enable feishu/wecom/weixin` | enable |
-| `channel disable feishu/wecom/weixin` | disable |
+| `channel enable feishu/wecom/weixin/discord/telegram` | enable |
+| `channel disable feishu/wecom/weixin/discord/telegram` | disable |
 | `channel reconfigure` | reconfigure |
 | `channel doctor` | doctor |
-| `send <message> to weixin/feishu/wecom` | send |
+| `send <message> to weixin/feishu/wecom/discord/telegram` | send |
 
 ---
 
@@ -51,7 +51,9 @@ Response shape (example):
 {"channels":[
   {"platform":"feishu","enabled":true,"running":true,"has_config":true,"app_id":"cli_xxx","domain":"https://open.feishu.cn","allowed_users":[]},
   {"platform":"wecom","enabled":false,"running":false,"has_config":false,"bot_id":""},
-  {"platform":"weixin","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://ilinkai.weixin.qq.com","allowed_users":[]}
+  {"platform":"weixin","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://ilinkai.weixin.qq.com","allowed_users":[]},
+  {"platform":"discord","enabled":true,"running":true,"has_config":true,"has_token":true,"allowed_users":[]}
+  {"platform":"telegram","enabled":true,"running":true,"has_config":true,"has_token":true,"base_url":"https://api.telegram.org","parse_mode":"Markdown","allowed_users":[]}
 ]}
 ```
 
@@ -64,12 +66,16 @@ Platform   Enabled   Running   Details
 feishu     ✅ yes    ✅ yes    app_id: cli_xxx...
 wecom      ❌ no     ❌ no     (not configured)
 weixin     ✅ yes    ✅ yes    has_token: true
+discord    ✅ yes    ✅ yes    has_token: true
+telegram   ✅ yes    ✅ yes    has_token: true
 ─────────────────────────────────────────────────────
 ```
 
 - Feishu: show `app_id` (truncated to 12 chars)
 - WeCom: show `bot_id` if present
 - Weixin: show `has_token: true/false` (token value is never displayed)
+- Discord: show `has_token: true/false` (token value is never displayed)
+- Telegram: show `has_token: true/false` (bot token is never displayed)
 
 If the API is unreachable or returns an empty list: "No channels configured yet. Run `/channel-setup setup` to get started."
 
@@ -83,6 +89,8 @@ Ask:
 > 1. Feishu
 > 2. WeCom (Enterprise WeChat)
 > 3. Weixin (Personal WeChat via iLink QR login)
+> 4. Discord
+> 5. Telegram (Bot API)
 
 ---
 
@@ -100,7 +108,7 @@ ruby "SKILL_DIR/feishu_setup.rb"
 - The script completed successfully.
 - Config is already written to `~/.clacky/channels.yml`.
 - Tell the user: "✅ Feishu channel configured automatically! The channel is ready."
-- **Stop here — do not proceed to manual steps.**
+- **Skip Step 2 (manual fallback) and continue to Step 3.**
 
 **If exit code is non-0:**
 - Check stdout for the error message.
@@ -199,7 +207,61 @@ curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/in
   -d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}'
 ```
 
-Check for `"code":0`. On success: "✅ Feishu channel configured."
+Check for `"code":0`. On success: continue to Step 3 (below).
+
+##### Phase 9 — done
+
+Step 2 ends here. **Continue to Step 3.**
+
+---
+
+#### Step 3 — Optional: install Feishu CLI
+
+Reach here from either Step 1 success or end of Step 2. Read `app_id` and `app_secret` from `~/.clacky/channels.yml` (under `channels.feishu`) for the install commands below.
+
+Call `request_user_feedback`:
+
+zh:
+```json
+{
+  "question": "是否要安装「飞书 CLI」？装好之后 AI 可以帮你操作飞书云文档、电子表格、多维表格、知识库、日历、任务等几乎全部飞书能力，不只是聊天，而是能\"做事\"。不装也 OK。",
+  "options": ["启用", "跳过"]
+}
+```
+
+en:
+```json
+{
+  "question": "Install Feishu CLI? With it, the AI can operate Feishu Docs, Sheets, Bitable, Wiki, Calendar, Tasks and almost every Feishu capability — not just chat, but actually get things done. Skipping is fine.",
+  "options": ["Enable", "Skip"]
+}
+```
+
+If the user picks Skip, stop — setup is complete.
+
+If the user picks Enable, run:
+
+```bash
+lark-cli --version > /dev/null 2>&1 || npm install -g @larksuite/cli
+echo -n "<APP_SECRET>" | lark-cli config init --app-id <APP_ID> --app-secret-stdin --brand feishu
+npx -y skills add larksuite/cli -y -g
+ruby "SKILL_DIR/import_lark_skills.rb"
+lark-cli auth login --recommend
+```
+
+The last command blocks up to 10 minutes waiting for browser authorization — make sure the runner's timeout is ≥ 600s.
+
+Once you see the authorization URL in the command's stdout, tell the user (do **not** wait for a reply — the CLI's blocking poll will return on its own when authorization completes):
+- zh: "请在浏览器中打开下方链接完成授权：\n<URL>"
+- en: "Open this URL in your browser to authorize:\n<URL>"
+
+**Do not kill and restart this command** — restarting invalidates the device code and breaks the link the user already opened. The "hang" is just polling; wait it out.
+
+When `lark-cli auth login` returns successfully, tell the user:
+- zh: "✅ 飞书 CLI 已就绪。"
+- en: "✅ Feishu CLI is ready."
+
+**Stop — setup is fully complete.**
 
 ---
 
@@ -290,6 +352,105 @@ Tell the user while waiting:
 
 ---
 
+### Discord setup
+
+Discord requires manual portal interaction (hCaptcha gates Application creation). The browser just navigates the user to the portal; the user clicks through and pastes the bot token + app id back.
+
+#### Step 1 — Open the developer portal
+
+Get the portal URL from the script and open it in the browser:
+
+```bash
+PORTAL_URL=$(ruby "SKILL_DIR/discord_setup.rb" --portal-url)
+```
+
+Open it: `browser(action="navigate", url="<PORTAL_URL>")`. If the browser tool is not configured, invoke `browser-setup` first, then retry.
+
+#### Step 2 — Guide the user through the portal (one round-trip)
+
+Tell the user **all** of the following in a single message, then call `request_user_feedback` to collect the values in one reply:
+
+> In the Discord Developer Portal I just opened:
+>
+> 1. Click **New Application** (top-right). Name it whatever you like (e.g. "Open Clacky"), check the ToS box, click **Create**.
+> 2. In the left nav click **Bot**.
+> 3. Scroll down to **Privileged Gateway Intents** and turn on **MESSAGE CONTENT INTENT**, then click **Save Changes**.
+> 4. Scroll up, click **Reset Token** → **Yes, do it!**. Click **Copy** to copy the bot token. (This is the only time the token is shown — don't navigate away before copying.)
+> 5. In the left nav click **General Information**. Copy the **Application ID**.
+>
+> Paste both values back here in this format (one line):
+>
+> `token=YOUR_BOT_TOKEN app_id=YOUR_APPLICATION_ID`
+
+If the user is chatting in a non-English language, append the localized label in parens after each bolded English button name (e.g. `**Bot**（机器人）`). The English label stays primary — it's what they physically click in the portal.
+
+Use `request_user_feedback` to collect the reply. Parse with tolerant regex (`token=\S+`, `app_id=\d+`).
+
+If the reply is malformed (missing either field), apologise briefly and ask again with the exact same format reminder. Up to 3 retries; after that, surface the original message and stop.
+
+#### Step 3 — Validate, save, invite, wait
+
+1. Validate the token and save credentials:
+   ```bash
+   ruby "SKILL_DIR/discord_setup.rb" --validate "<BOT_TOKEN>"
+   ```
+   On success the script prints `{"bot_id":"...","username":"..."}` and the adapter starts.
+
+2. Generate the invite URL using the application id from Step 2:
+   ```bash
+   ruby "SKILL_DIR/discord_setup.rb" --invite-url "<APP_ID>"
+   ```
+   Open it: `browser(action="navigate", url="<INVITE_URL>")`. Tell the user:
+   > Pick your server from the dropdown → **Continue** → **Authorize**. I'll detect when the bot joins.
+   >
+   > If the dropdown is empty, you don't have a server yet — open <https://discord.com/channels/@me>, click **Add a Server** (the **+** button on the left sidebar) → **Create My Own** → **For me and my friends** → name it → **Create**, then re-open the invite link.
+
+3. Wait for the bot to join a guild (long-poll, 10 min timeout). Run with `timeout: 620`:
+   ```bash
+   ruby "SKILL_DIR/discord_setup.rb" --watch-guild
+   ```
+   On exit 0: "✅ Discord channel configured! Bot is in `<guild_name>`. Mention it or DM it from any channel."
+   On timeout: offer to re-open the invite URL — the bot token stays valid.
+
+### Telegram setup (Bot API)
+
+Telegram setup is by far the simplest — no browser automation, no QR. The user creates a bot via @BotFather and pastes the token here.
+
+#### Step 1 — Create a bot via @BotFather
+
+Tell the user:
+
+> Open Telegram and start a chat with **@BotFather** (https://t.me/BotFather). Send `/newbot`, choose a display name and a username ending in `bot`. BotFather will reply with an HTTP API token that looks like `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`. Paste the token here.
+>
+> Optional: if your network blocks `api.telegram.org`, also tell me the base URL of your self-hosted Bot API server (e.g. `https://my-tg-proxy.example.com`). Otherwise leave it blank.
+
+Wait for the user's reply. Parse the token (matches `^\d+:[\w-]{30,}$`).
+
+#### Step 2 — Save credentials and validate
+
+Call the server API. It calls `getMe` against the Bot API to validate the token before persisting:
+
+```bash
+curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/telegram \
+  -H "Content-Type: application/json" \
+  -d '{"bot_token":"<TOKEN>","base_url":"<BASE_URL_OR_OMIT>"}'
+```
+
+- `200 { "ok": true }` — token validated and saved. The adapter starts long-polling immediately.
+- `422 { "ok": false, "error": "..." }` — show the error (commonly "Unauthorized" → wrong token) and offer to retry.
+
+On success:
+
+> ✅ Telegram channel configured. Open your bot in Telegram and send any message to start chatting. In group chats, the bot only replies when you @-mention it.
+
+#### Notes
+
+- **Group chats**: Telegram bots respond only when @-mentioned or directly replied to (matches Feishu behaviour). For unrestricted reading in groups, the bot owner must disable "Group Privacy" in @BotFather (`/mybots → Bot Settings → Group Privacy → Turn off`), but `@-mention only` is recommended to avoid spam.
+- **Self-hosted Bot API**: set `base_url` when `api.telegram.org` is unreachable. See https://github.com/tdlib/telegram-bot-api for the official self-hosted server.
+- **`allowed_users`**: restrict which Telegram user IDs the bot will respond to. Find a user's numeric ID by messaging @userinfobot.
+
+---
+
 ## `enable`
 
 Call the server API to re-enable the platform (this reads from disk, sets enabled, saves, and hot-reloads):
@@ -337,15 +498,30 @@ Check each item, report ✅ / ❌ with remediation:
    - Feishu: `app_id`, `app_secret` present and non-empty
    - WeCom: `bot_id`, `secret` present and non-empty
    - Weixin: `token` present and non-empty in `channels.yml`
+   - Discord: `bot_token` present and non-empty in `channels.yml`
+   - Telegram: `bot_token` present and non-empty
 3. **Feishu credentials** (if enabled) — run the token API call, check `code=0`.
 4. **Weixin token** (if enabled) — call `GET /api/channels` and check `has_token: true` for the weixin entry.
-5. **WeCom credentials** (if enabled) — search today's log:
+5. **Telegram credentials** (if enabled) — call `getMe` against the Bot API:
+   ```bash
+   BOT_TOKEN=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["bot_token"] rescue "")')
+   BASE_URL=$(ruby -ryaml -e 'puts (YAML.load_file(File.expand_path("~/.clacky/channels.yml"))["channels"]["telegram"]["base_url"] || "https://api.telegram.org" rescue "https://api.telegram.org")')
+   curl -s "$BASE_URL/bot$BOT_TOKEN/getMe" | grep -q '"ok":true' && echo "✅ Telegram OK" || echo "❌ Telegram credentials rejected by getMe"
+   ```
+6. **WeCom credentials** (if enabled) — search today's log:
    ```bash
    grep -iE "wecom adapter loop started|WeCom authentication failed|WeCom WS error response|WecomAdapter" \
      ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
    ```
    - `WeCom authentication failed` or non-zero errcode → ❌ "WeCom credentials incorrect"
    - `adapter loop started` with no auth error → ✅
+6. **Discord credentials** (if enabled) — call `GET /api/channels` and check `has_token: true`. Search today's log:
+   ```bash
+   grep -iE "DiscordAdapter|discord-gateway|/users/@me failed" \
+     ~/.clacky/logger/clacky-$(date +%Y-%m-%d).log
+   ```
+   - `/users/@me failed` → ❌ "Discord token invalid or revoked — re-run setup"
+   - `authenticated as` with no error → ✅
 
 ---
 
@@ -356,7 +532,7 @@ Proactively send a message to a user via an IM channel adapter.
 ### Parse the request
 
 Extract two things from the user's instruction:
-- **platform** — one of `weixin`, `feishu`, `wecom`
+- **platform** — one of `weixin`, `feishu`, `wecom`, `discord`, `telegram`
 - **message** — the text content to send
 
 If the platform cannot be inferred, ask the user to clarify.
@@ -396,7 +572,7 @@ curl -s -X POST http://${CLACKY_SERVER_HOST}:${CLACKY_SERVER_PORT}/api/channels/
 ### Constraints & notes
 
 - **Weixin (iLink protocol)**: Every outbound message requires a `context_token` that is obtained from the most recent inbound message from that user. The token is cached in memory and reset on server restart. If the server was restarted since the user last wrote, the token is gone and the send will fail — the user must message the bot again.
-- **Feishu / WeCom**: No token required. As long as the adapter is running and the `user_id` / `chat_id` is valid, the message will be delivered.
+- **Feishu / WeCom / Discord / Telegram**: No per-message token required. As long as the adapter is running and the `user_id` / `chat_id` (or Discord channel/user id) is valid, the message will be delivered. For Telegram specifically, the `user_id` must be a Telegram chat_id that the bot can write to — the user must have sent at least one message to the bot first.
 - This feature is intended for **proactive notifications** (e.g. task completion, reminders). It is not a replacement for the normal reply flow triggered by inbound messages.
 
 ---

data/lib/clacky/default_skills/channel-setup/discord_setup.rb

@@ -0,0 +1,199 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# discord_setup.rb — Discord channel setup helper.
+#
+# Discord's developer portal requires manual interaction (hCaptcha + private API), so the
+# Agent uses the browser only as a container — it navigates to the portal and the user
+# creates the App manually, then pastes back the bot token and application id. This
+# script handles everything a shell can do: emit the portal URL, validate the token
+# against /users/@me, save to the clacky server, generate the OAuth2 invite URL, and
+# poll until the bot is in at least one guild.
+#
+# Modes:
+#   --portal-url                Print the Discord developer portal URL (stdout, single line)
+#   --validate <token>          Validate bot_token via /users/@me, then POST to server
+#   --invite-url <client_id>    Print the OAuth2 invite URL (stdout, single line)
+#   --watch-guild               Long-poll /users/@me/guilds via the saved token
+#                               until at least one guild appears (or timeout)
+#   --bot-info <token>          Print {id, username} JSON for an unsaved token
+#
+# Environment:
+#   CLACKY_SERVER_HOST  default 127.0.0.1
+#   CLACKY_SERVER_PORT  default 7070
+
+require "json"
+require "net/http"
+require "net/https"
+require "uri"
+require "openssl"
+require "cgi"
+require "yaml"
+
+DISCORD_API_BASE      = "https://discord.com/api/v10"
+DISCORD_OAUTH_BASE    = "https://discord.com/oauth2/authorize"
+DISCORD_PORTAL_URL    = "https://discord.com/developers/applications"
+DEFAULT_BOT_PERMS     = "274877990912"
+DEFAULT_BOT_SCOPES    = "bot applications.commands"
+WATCH_GUILD_DEADLINE  = 10 * 60
+WATCH_GUILD_INTERVAL  = 3
+USER_AGENT            = "DiscordBot (https://github.com/clackyai/openclacky, 1.0)"
+
+CLACKY_SERVER_URL = begin
+  host = ENV.fetch("CLACKY_SERVER_HOST", "127.0.0.1")
+  port = ENV.fetch("CLACKY_SERVER_PORT", "7070")
+  "http://#{host}:#{port}"
+end
+
+def step(msg);  $stderr.puts("[discord-setup] #{msg}"); end
+def ok(msg);    $stderr.puts("[discord-setup] #{msg}"); end
+def warn!(msg); $stderr.puts("[discord-setup] #{msg}"); end
+
+def fail!(msg, json: false)
+  if json
+    $stdout.puts(JSON.generate({ error: msg }))
+  else
+    $stderr.puts("[discord-setup] #{msg}")
+  end
+  exit 1
+end
+
+def discord_get(path, bot_token:, timeout: 15)
+  uri  = URI("#{DISCORD_API_BASE}#{path}")
+  http = Net::HTTP.new(uri.host, uri.port)
+  http.use_ssl      = true
+  http.verify_mode  = OpenSSL::SSL::VERIFY_PEER
+  http.read_timeout = timeout
+  http.open_timeout = 10
+
+  req = Net::HTTP::Get.new(uri.request_uri)
+  req["Authorization"] = "Bot #{bot_token}"
+  req["User-Agent"]    = USER_AGENT
+  req["Accept"]        = "application/json"
+
+  res    = http.request(req)
+  body   = res.body.to_s
+  parsed = (JSON.parse(body) rescue nil)
+
+  unless res.is_a?(Net::HTTPSuccess)
+    msg = parsed.is_a?(Hash) ? (parsed["message"] || body.slice(0, 200)) : body.slice(0, 200)
+    raise "Discord HTTP #{res.code} #{path}: #{msg}"
+  end
+  parsed
+end
+
+def saved_bot_token
+  yml_path = File.expand_path("~/.clacky/channels.yml")
+  return nil unless File.exist?(yml_path)
+  data = YAML.safe_load_file(yml_path, permitted_classes: [Symbol], aliases: true) rescue nil
+  data&.dig("channels", "discord", "bot_token") || data&.dig(:channels, :discord, :bot_token)
+end
+
+def save_to_server(bot_token:)
+  uri  = URI("#{CLACKY_SERVER_URL}/api/channels/discord")
+  body = JSON.generate({ bot_token: bot_token })
+
+  http = Net::HTTP.new(uri.host, uri.port)
+  http.read_timeout = 30
+  http.open_timeout = 5
+
+  req = Net::HTTP::Post.new(uri.path, "Content-Type" => "application/json")
+  req.body = body
+
+  res  = http.request(req)
+  data = JSON.parse(res.body) rescue {}
+
+  unless res.is_a?(Net::HTTPSuccess) && data["ok"]
+    fail!("Failed to save Discord config: #{data["error"] || res.body.slice(0, 200)}")
+  end
+end
+
+mode_idx = ARGV.index { |a| a.start_with?("--") }
+mode     = mode_idx ? ARGV[mode_idx] : nil
+arg      = mode_idx ? ARGV[mode_idx + 1] : nil
+
+case mode
+when "--portal-url"
+  $stdout.puts(DISCORD_PORTAL_URL)
+  exit 0
+
+when "--validate"
+  fail!("--validate requires <bot_token>") if arg.to_s.strip.empty?
+  bot_token = arg.strip
+  step("Validating bot token against Discord API...")
+  begin
+    me = discord_get("/users/@me", bot_token: bot_token)
+  rescue => e
+    fail!("Token validation failed: #{e.message}")
+  end
+
+  bot_id   = me["id"].to_s
+  username = me["username"].to_s
+  fail!("Empty bot id from /users/@me") if bot_id.empty?
+
+  ok("Authenticated as #{username} (id=#{bot_id})")
+  step("Saving credentials via clacky server...")
+  save_to_server(bot_token: bot_token)
+  ok("Discord channel configured")
+
+  $stdout.puts(JSON.generate({ bot_id: bot_id, username: username }))
+  exit 0
+
+when "--bot-info"
+  fail!("--bot-info requires <bot_token>", json: true) if arg.to_s.strip.empty?
+  begin
+    me = discord_get("/users/@me", bot_token: arg.strip)
+  rescue => e
+    fail!(e.message, json: true)
+  end
+  $stdout.puts(JSON.generate({ bot_id: me["id"], username: me["username"] }))
+  exit 0
+
+when "--invite-url"
+  fail!("--invite-url requires <client_id>") if arg.to_s.strip.empty?
+  client_id = arg.strip
+  url = "#{DISCORD_OAUTH_BASE}?client_id=#{CGI.escape(client_id)}" \
+        "&permissions=#{DEFAULT_BOT_PERMS}" \
+        "&scope=#{CGI.escape(DEFAULT_BOT_SCOPES)}"
+  $stdout.puts(url)
+  exit 0
+
+when "--watch-guild"
+  bot_token = saved_bot_token
+  fail!("No saved bot_token in ~/.clacky/channels.yml — run --validate first") if bot_token.to_s.empty?
+
+  step("Waiting for the bot to be added to a guild (timeout: #{WATCH_GUILD_DEADLINE / 60} min)...")
+  deadline = Time.now + WATCH_GUILD_DEADLINE
+
+  loop do
+    fail!("Timed out waiting for the bot to join a guild. Open the invite URL again to retry.") if Time.now > deadline
+
+    begin
+      guilds = discord_get("/users/@me/guilds", bot_token: bot_token)
+    rescue => e
+      warn!("Poll error (will retry): #{e.message}")
+      sleep WATCH_GUILD_INTERVAL
+      next
+    end
+
+    if guilds.is_a?(Array) && !guilds.empty?
+      g = guilds.first
+      ok("Bot added to guild: #{g["name"]} (id=#{g["id"]})")
+      $stdout.puts(JSON.generate({ guild_id: g["id"], guild_name: g["name"], total: guilds.length }))
+      exit 0
+    end
+
+    sleep WATCH_GUILD_INTERVAL
+  end
+
+else
+  $stderr.puts(<<~USAGE)
+    Usage:
+      ruby discord_setup.rb --portal-url
+      ruby discord_setup.rb --validate <bot_token>
+      ruby discord_setup.rb --bot-info <bot_token>
+      ruby discord_setup.rb --invite-url <client_id>
+      ruby discord_setup.rb --watch-guild
+  USAGE
+  exit 1
+end

data/lib/clacky/default_skills/channel-setup/import_lark_skills.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'pathname'
+
+# Import lark-cli's official Skills from ~/.agents/skills/lark-* into
+# ~/.clacky/skills/lark-imports/<name>/.
+#
+# Background:
+#   lark-cli ships ~24 SKILL.md files (lark-doc, lark-sheets, lark-base, ...)
+#   that teach the agent how to use `lark-cli`. They are normally installed
+#   under ~/.agents/skills/lark-*, which openclacky's SkillLoader does NOT
+#   scan. This importer copies them into ~/.clacky/skills/lark-imports/ so
+#   they become discoverable via the standard skill description-matching
+#   mechanism.
+#
+# This is intentionally a small, dedicated importer (not a generic external
+# skills tool) — it only handles the lark-cli case for the feishu channel
+# setup flow. Failures are non-fatal: the bot itself remains functional even
+# if Skills cannot be exposed.
+#
+# Usage:
+#   importer = Clacky::ChannelSetup::LarkSkillsImporter.new
+#   result = importer.run
+#   # result => { copied: 24, skipped: 0, errors: [] }
+
+module Clacky
+  module ChannelSetup
+    class LarkSkillsImporter
+      DEFAULT_SOURCE_DIR = File.join(Dir.home, '.agents', 'skills')
+      DEFAULT_TARGET_DIR = File.join(Dir.home, '.clacky', 'skills', 'lark-imports')
+      SKILL_PREFIX       = 'lark-'
+
+      # @param source_dir [String] directory containing lark-cli installed skills
+      # @param target_dir [String] destination under ~/.clacky/skills/
+      def initialize(source_dir: DEFAULT_SOURCE_DIR, target_dir: DEFAULT_TARGET_DIR)
+        @source_dir = Pathname.new(source_dir).expand_path
+        @target_dir = Pathname.new(target_dir).expand_path
+      end
+
+      # Run the import. Returns a result hash; never raises on per-skill errors.
+      # @return [Hash] { copied: Integer, skipped: Integer, errors: Array<String> }
+      def run
+        return { copied: 0, skipped: 0, errors: ["source not found: #{@source_dir}"] } unless @source_dir.directory?
+
+        skill_dirs = discover_lark_skills
+        return { copied: 0, skipped: 0, errors: [] } if skill_dirs.empty?
+
+        FileUtils.mkdir_p(@target_dir)
+
+        copied = 0
+        errors = []
+        skill_dirs.each do |src|
+          begin
+            copy_skill(src)
+            copied += 1
+          rescue StandardError => e
+            errors << "#{src.basename}: #{e.message}"
+          end
+        end
+
+        { copied: copied, skipped: 0, errors: errors }
+      end
+
+      # Discover candidate lark-* skill directories under @source_dir.
+      # A directory qualifies when it (a) starts with "lark-" and (b) contains a SKILL.md.
+      # @return [Array<Pathname>]
+      private def discover_lark_skills
+        @source_dir.children
+                   .select { |p| p.directory? && p.basename.to_s.start_with?(SKILL_PREFIX) }
+                   .select { |p| p.join('SKILL.md').exist? }
+                   .sort_by { |p| p.basename.to_s }
+      end
+
+      # Copy a single skill directory into @target_dir, replacing any existing copy
+      # so re-runs always reflect the latest version.
+      # @param src [Pathname]
+      private def copy_skill(src)
+        dst = @target_dir.join(src.basename.to_s)
+        FileUtils.rm_rf(dst) if dst.exist?
+        FileUtils.mkdir_p(dst)
+        src.children.each { |child| FileUtils.cp_r(child, dst) }
+      end
+    end
+  end
+end
+
+# CLI entry point — invoked by SKILL.md after the user opts in to lark-cli.
+# Usage:
+#   ruby import_lark_skills.rb
+# Prints a one-line summary; exits 0 even when nothing to copy (treat empty
+# source as a soft skip — the script may run before `npx skills add`).
+if $PROGRAM_NAME == __FILE__
+  result = Clacky::ChannelSetup::LarkSkillsImporter.new.run
+  puts "[lark-import] copied=#{result[:copied]} errors=#{result[:errors].size}"
+  result[:errors].each { |e| warn "[lark-import] #{e}" }
+end

data/lib/clacky/default_skills/onboard/SKILL.md

@@ -55,7 +55,7 @@ Example (English):
 > Let's take 30 seconds to personalize your experience — I'll ask just a couple of quick things.
 
 Example (Chinese):
-> 嗨！我是你的专属小龙虾一号
+> 嗨！我是你的专属员工一号
 > 只需 30 秒完成个性化设置，我会问你两个简单问题。
 
 ### A.3. Ask the user to name the AI (card)