kiku-agent 1.2.0 → 1.3.0

package/server/agent/tools.js

@@ -7,12 +7,20 @@ import { socialUpdatesData } from '../../src/data/socialUpdatesData.js';
 import { galleryData } from '../../src/data/galleryData.js';
 import { awardsData } from '../../src/data/awardsData.js';
 import { timelineData } from '../../src/data/timelineData.js';
-import { searchWeb, fetchWebpage, fetchJson, screenshotWebpage, webExtract } from './webSearch.js';
-import { readFile, readdir, stat, realpath } from 'node:fs/promises';
+import { getDynamicEntries, addDynamicEntry } from './dynamicCatalog.js';
+import { industryIndexData, platformsCatalog, artistIndustryMetrics, categoryDefinitions } from '../../src/data/industryIndexData.js';
+import {
+  searchWeb, fetchWebpage, fetchJson, screenshotWebpage, webExtract,
+  searchNews, fetchRssFeed, searchEncyclopedia, searchMusicPlatforms,
+  searchChineseWeb, searchBilibili, searchWebImages, detectLanguage
+} from './webSearch.js';
+import { readFile, readdir, stat, realpath } from 'node:fs/promises';
 import { join, relative, extname, resolve } from 'node:path';
 import { audioPlayer } from './audioPlayer.js';
+import { fetchYoutubeTranscript } from './youtubeTranscript.js';
 import { sanitizeToolArgs, sanitizeUrl } from './sanitizer.js';
 import { getGpuMetrics } from './gpuMetrics.js';
+import { levenshteinDistance, levenshteinSimilarity, levenshteinScore, CATEGORY_ALIASES } from './catalogEntityResolver.js';
 
 export function buildYouTubeSearchUrl(query) {
   return `https://www.youtube.com/results?search_query=${encodeURIComponent(query)}`;
@@ -41,25 +49,46 @@ export function formatCatalogTitle(primary, secondary) {
   return `${first} (${second})`;
 }
 
+export const CATALOG_STOP_WORDS = new Set([
+  'the', 'from', 'what', 'are', 'is', 'about', 'drama', 'series', 'ost', 'song', 'songs', 'soundtrack', 'music', 'single', 'album', 'stage',
+  'brand', 'brands', 'ambassador', 'endorsement', 'commercial', 'role', 'roles', 'character', 'characters', 'award', 'awards', 'category', 'video', 'mv', 'clip',
+  'ju', 'jingyi', 'jujingyi', 'kiku', 'kikuuu', 'จวีจิ้งอี', 'จวี', 'จิ้งอี', 'เสี่ยวจวี', 'เสี่ยว', '鞠婧祎', '小鞠', '鞠',
+  'เพลง', 'เพลงของ', 'ซีรีส์', 'ซีรีส์ของ', 'ละคร', 'เรื่อง', 'ผลงาน', 'อัลบั้ม', 'คอนเสิร์ต', 'บทบาท', 'ตัวละคร', 'แบรนด์', 'รางวัล', 'ผลงานล่าสุด', 'พรีเซนเตอร์',
+  'ค้นหา', 'หา', 'ดู', 'เปิด', 'ฟัง', 'โปรโมท', 'โปรโมต', 'การโปรโมท', 'การโปรโมต', 'โฆษณา', 'แคมเปญ', 'ข้อมูล', 'รายละเอียด', 'บน', 'ใน', 'ที่', 'กับ', 'ช่วย', 'อยาก', 'ให้', 'หน่อย', 'คือ', 'อะไร', 'บ้าง', 'ไหม', 'มั้ย', 'มี',
+  'search', 'find', 'show', 'look', 'promo', 'promote', 'promoted', 'campaign', 'for', 'with', 'tell', 'me', 'please', 'can', 'you', 'info', 'details',
+  '搜索', '查找', '看看', '播放', '在', '上的', '关于', '有什么', '吗', '呢',
+  'bilibili', 'b站', 'youtube', 'weibo', 'douyin', 'spotify', 'qqmusic', 'iqiyi', 'youku', 'tencent'
+]);
+
+const PERSONAL_FACT_KEYWORDS = Object.freeze([
+  'birthplace', 'born', 'birthday', 'education', 'instrument', 'violin', 'blood', 'height', 'hometown', 'cat', 'cats', 'pet', 'pets', 'fandom', 'slogan', 'motto', 'กำเนิด', 'เกิด', 'บ้านเกิด', 'ไวโอลิน', 'เครื่องดนตรี', 'การศึกษา', 'กรุ๊ปเลือด', 'ส่วนสูง', 'แมว', '出生', '籍贯', '血型', '身高', '毕业'
+]);
+
+function normalizeWorkId(value) {
+  return String(value || '').toLowerCase().trim().replace(/[_\s]+/g, '-');
+}
+
+const WORKS_BY_NORM_ID = new Map();
+for (const w of worksData) {
+  const id = normalizeWorkId(w.id);
+  if (id && !WORKS_BY_NORM_ID.has(id)) WORKS_BY_NORM_ID.set(id, w);
+}
+
 export function createCatalogMatcher(query) {
   if (!query) return () => true;
   const raw = String(query).toLowerCase().trim();
   if (!raw) return () => true;
 
-  const stopWords = new Set([
-    'the', 'from', 'what', 'are', 'is', 'about', 'drama', 'series', 'ost', 'song', 'songs', 'soundtrack', 'music', 'single', 'album', 'stage',
-    'brand', 'brands', 'ambassador', 'endorsement', 'commercial', 'role', 'roles', 'character', 'characters', 'award', 'awards', 'category', 'video', 'mv', 'clip',
-    'ju', 'jingyi', 'jujingyi', 'kiku', 'kikuuu', 'จวีจิ้งอี', 'จวี', 'จิ้งอี', 'เสี่ยวจวี', 'เสี่ยว', '鞠婧祎', '小鞠', '鞠',
-    'เพลง', 'เพลงของ', 'ซีรีส์', 'ซีรีส์ของ', 'ละคร', 'เรื่อง', 'ผลงาน', 'อัลบั้ม', 'คอนเสิร์ต', 'บทบาท', 'ตัวละคร', 'แบรนด์', 'รางวัล', 'ผลงานล่าสุด', 'พรีเซนเตอร์'
-  ]);
-
   const allTokens = raw.split(/[^\p{L}\p{M}\p{N}]+/u).filter(t => t.length >= 2);
- 
   const deDated = raw.replace(/ใหม่ล่าสุด|ล่าสุด|最新|latest|newest|recent/gi, ' ');
   const datedTokens = deDated.split(/[^\p{L}\p{M}\p{N}]+/u).filter(t => t.length >= 2);
-  const coreTokens = datedTokens.filter(t => !stopWords.has(t));
- 
-  if (coreTokens.length === 0) return () => true;
+  const coreTokens = datedTokens.filter(t => !CATALOG_STOP_WORDS.has(t));
+
+  if (coreTokens.length === 0) {
+    const broadMatcher = () => true;
+    broadMatcher.broad = true;
+    return broadMatcher;
+  }
   const effectiveTokens = coreTokens;
 
   return (...fields) => {
@@ -67,7 +96,27 @@ export function createCatalogMatcher(query) {
     if (haystack.includes(raw)) return true;
     if (effectiveTokens.length > 0) {
       const matchCount = effectiveTokens.filter(term => haystack.includes(term)).length;
-      return matchCount > 0 && (matchCount / effectiveTokens.length >= 0.5);
+      if (matchCount > 0 && (matchCount / effectiveTokens.length >= 0.5)) return true;
+    }
+
+    if (raw.length >= 4) {
+      for (const field of fields) {
+        if (!field) continue;
+        const fStr = String(field).toLowerCase();
+        if (fStr.includes(raw) || raw.includes(fStr)) return true;
+        const words = fStr.split(/\s+/);
+        for (let i = 0; i < words.length; i++) {
+          for (let len = 1; len <= Math.min(5, words.length - i); len++) {
+            const sub = words.slice(i, i + len).join(' ');
+            if (sub.length >= 4 && Math.abs(sub.length - raw.length) <= 3) {
+              const { dist, sim } = levenshteinScore(raw, sub);
+              if (dist <= 2 || sim >= 0.75) {
+                return true;
+              }
+            }
+          }
+        }
+      }
     }
     return false;
   };
@@ -114,15 +163,17 @@ const STATIC_CATALOG_TOOLS = new Set([
   'get_profile_and_fandom',
   'get_quotes',
   'get_awards',
-  'get_timeline',
+  'get_career_timeline',
   'get_brand_endorsements',
-  'get_gallery',
+  'get_gallery_photos',
   'get_music_videos',
   'search_works',
   'search_discography',
   'get_work_detail',
-  'get_social_updates',
   'get_media_links',
+  'get_entertainment_metrics',
+  'get_industry_index',
+  'global_search',
 ]);
 
 const WEB_CACHE_TOOLS = new Set([
@@ -130,17 +181,19 @@ const WEB_CACHE_TOOLS = new Set([
   'web_extract',
   'fetch_webpage',
   'fetch_json',
+  'search_news',
+  'fetch_rss',
+  'search_encyclopedia',
+  'search_music_platforms',
+  'search_chinese_web',
+  'search_bilibili',
+  'search_web_images',
 ]);
 
 
+
 const LIVE_DATA_TOOLS = new Set([
   'get_social_feed',
-  'get_gallery_photos',
-  'get_awards',
-  'get_career_timeline',
-  'get_brand_endorsements',
-  'get_music_videos',
-  'get_media_links',
 ]);
 
 const CACHED_DISCOGRAPHY = (() => {
@@ -163,6 +216,11 @@ const CACHED_DISCOGRAPHY = (() => {
         titleEn: track.titleEn || '',
         year: track.year,
         work: track.work || "Solo Single",
+        category: track.category || 'single',
+        categoryName: track.categoryName || '',
+        role: track.role || '',
+        description: track.description || '',
+        badge: track.badge || '',
         duration: track.duration || track.trackDuration || '',
         theme: track.theme || "Pop / Ballad",
         youtubeId: ytId,
@@ -171,6 +229,12 @@ const CACHED_DISCOGRAPHY = (() => {
         qqMusicSearchUrl: buildQqMusicSearchUrl(`鞠婧祎 ${track.titleCn || track.titleTh}`),
         bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${track.titleCn || track.titleTh}`)
       });
+    } else {
+      const existing = map.get(key);
+      if (!existing.role && track.role) existing.role = track.role;
+      if (!existing.description && track.description) existing.description = track.description;
+      if (!existing.categoryName && track.categoryName) existing.categoryName = track.categoryName;
+      if (!existing.work && track.work) existing.work = track.work;
     }
   }
 
@@ -195,12 +259,33 @@ function getAllMusicVideos() {
   return CACHED_MUSIC_VIDEOS;
 }
 
+
+const WORK_CATEGORY_VALUES = ['historical-drama', 'modern-drama', 'movie'];
+const WORK_CATEGORY_SYNONYMS = {
+  series: ['historical-drama', 'modern-drama'],
+  drama: ['historical-drama', 'modern-drama'],
+  tv: ['historical-drama', 'modern-drama'],
+  television: ['historical-drama', 'modern-drama'],
+  film: ['movie'],
+  cinema: ['movie'],
+};
+
+export function normalizeWorkCategoryFilter(category) {
+  const raw = String(category || '').toLowerCase().trim();
+  if (!raw || raw === 'all') return null;
+  const compact = raw.replace(/[\s_]+/g, '-');
+  if (WORK_CATEGORY_VALUES.includes(compact)) return [compact];
+  if (WORK_CATEGORY_SYNONYMS[compact]) return WORK_CATEGORY_SYNONYMS[compact];
+  const partial = WORK_CATEGORY_VALUES.filter(k => k.includes(compact) || compact.includes(k));
+  return partial.length ? partial : [compact];
+}
+
 export const toolsSchema = [
   {
     type: "function",
     function: {
-      name: "get_profile_and_fandom",
-      description: "Get Ju Jingyi's biographical profile, Chinese/English/Thai names, birthday, birthplace, Miju (蜜橘) fan community, official slogan, and socials.",
+      name: "get_current_datetime",
+      description: "Get the current local date and time (ISO 8601, timezone, weekday, and current year). Call this whenever 'today', 'now', or the current year matters — NEVER guess or rely on training data for dates.",
       parameters: {
         type: "object",
         properties: {},
@@ -208,15 +293,60 @@ export const toolsSchema = [
       }
     }
   },
+  {
+    type: "function",
+    function: {
+      name: "get_youtube_transcript",
+      description: "Fetch the caption/transcript text of a YouTube video (manual or auto captions). Use it to verify lyrics, quotes, or statements from interviews instead of guessing their content.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full YouTube video URL (watch, youtu.be, shorts, embed, or live)" },
+          videoId: { type: "string", description: "11-character YouTube video ID — alternative to url" },
+          lang: { type: "string", enum: ["th", "en", "zh"], description: "Preferred caption language" },
+          maxChars: { type: "number", description: "Maximum transcript characters to return (default 6000, cap 20000)" }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_profile_and_fandom",
+      description: "Get Ju Jingyi's biographical profile — the authoritative source for ALL personal facts: Chinese/English/Thai names, birthday, birthplace, height, blood type, education, musical instruments (classical violin), debut date, SNH48 graduation date, current status, Miju (蜜橘) fan community, official slogan, pets, and socials. For exact personal dates and biographical facts use this instead of get_career_timeline. Optional sections expose talents, career stats, Forbes-level honors, and official social links.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Optional fact keyword to inspect (e.g. 'birthplace', 'education', 'instrument', 'violin', 'blood type', 'height', 'birthday', 'hometown', 'cats')"
+          },
+          section: {
+            type: "string",
+            enum: ["all", "talents", "stats", "honors", "social"],
+            description: "Optional extra profile section to include (default: all = core profile)"
+          }
+        },
+        required: []
+      }
+    }
+  },
   {
     type: "function",
     function: {
       name: "get_quotes",
-      description: "Retrieve inspiring quotes and famous statements made by Ju Jingyi (with Thai translation and Chinese text).",
+      description: `Retrieve official quotes, mottoes, interview philosophies, mindsets, and life credos (e.g., "保持热爱，奔赴山海", "往前看").
+[CRITICAL]: Use this tool when the user asks for her motto (座右铭), personal quotes, or philosophical sayings. DO NOT use get_profile_and_fandom for mindset/quotes.`,
       parameters: {
         type: "object",
         properties: {
-          tag: { type: "string", description: "Optional tag (mindset, growth, acting, fandom)" }
+          tag: {
+            type: "string",
+            enum: ["mindset", "career", "fans", "all", "growth", "acting"],
+            description: "Theme tag of the quote"
+          },
+          query: { type: "string", description: "Specific keyword in Thai, Chinese, or English" }
         },
         required: []
       }
@@ -226,14 +356,14 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "search_works",
-      description: "Search Ju Jingyi's filmography (TV dramas, web series, movies, and upcoming projects). Returns grounded role context, synopsis, highlights, catalog platform, and trailer search links; use these fields instead of inferring plot or acting claims.",
+      description: `Search filmography, drama series, movies, and character costume details (e.g., Sword and Fairy 4 / 仙剑四, In Blossom, Han Lingsha red costume).
+[CRITICAL]: Use this tool for drama episode counts, platforms, character visual traits, and plot synopses. DO NOT use global_search.`,
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Search keyword for drama title or character name." },
-          year: { type: "number", description: "Specific release year (e.g. 2026, 2025, 2024, 2023). Leave empty to get newest." },
-          category: { type: "string", description: "Category filter (e.g. 'series', 'movie', 'upcoming')." },
-          featuredOnly: { type: "boolean", description: "Filter only featured major hit dramas." }
+          query: { type: "string", description: "Drama/Movie title or character name" },
+          year: { type: "number", description: "Release year" },
+          category: { type: "string", description: "Drama or movie category filter ('historical-drama', 'modern-drama', 'movie', 'series', 'drama', 'film', or 'all')" }
         },
         required: []
       }
@@ -257,11 +387,11 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_character_roles",
-      description: "List and search famous fictional character roles portrayed by Ju Jingyi in dramas and movies (e.g. Yang Caiwei, Lu Wuyi, Bai Suzhen, Han Yunxi).",
+      description: "Authoritative role catalog for FICTIONAL drama and movie characters Ju Jingyi portrays (e.g. Yang Caiwei, Lu Wuyi, Bai Suzhen, Han Yunxi). NEVER call this for Ju Jingyi's real-life personal facts, birthplace, birthday, education, or blood type — use get_profile_and_fandom instead.",
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Optional role name or drama title keyword" }
+          query: { type: "string", description: "Optional fictional role name or drama title keyword" }
         },
         required: []
       }
@@ -271,7 +401,8 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "search_discography",
-      description: "Search Ju Jingyi's songs, singles, and OST drama soundtracks. Returns verified direct YouTube watch links (https://www.youtube.com/watch?v=...), real YouTube search queries (https://www.youtube.com/results?search_query=...), and music streaming links.",
+      description: `Search songs, solo singles, drama OSTs, and album tracks by Chinese title, English title, or Thai transliteration (e.g., View From The Wall / 壁上观, FIND THE WAY, 如纱, 不苦).
+[CRITICAL]: Use this tool to find translations of song titles (Chinese <-> English). DO NOT use global_search for song queries.`,
       parameters: {
         type: "object",
         properties: {
@@ -287,7 +418,7 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_music_videos",
-      description: "Retrieve music videos (MV), stage performances, and dance practices with verified direct YouTube links and YouTube search query URLs.",
+      description: "Use for official music videos, dance practices, video release years, and video durations. Titles may include alphanumeric codes or short tokens like '0.2s' or 'Everyday' or catalog video IDs. If a query asks for the stored releaseYear of a video entry (e.g. Dewdrops video ID), retrieve it here.",
       parameters: {
         type: "object",
         properties: {
@@ -302,7 +433,7 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_media_links",
-      description: "Get direct YouTube video watch links (watch?v=...), official YouTube search queries (results?search_query=...), Bilibili links, and streaming URLs for any Ju Jingyi song, MV, live stage, or drama trailer.",
+      description: "LINKS ONLY: get direct YouTube video watch links (watch?v=...), official YouTube search queries (results?search_query=...), Bilibili links, and streaming URLs for a given Ju Jingyi song, MV, live stage, or drama trailer. It returns media URLs and basic metadata but NO character roles, song credits, or duet artists — for role facts use search_works/get_character_roles, for song facts use search_discography. Use this tool only when the user asks for URLs/links themselves.",
       parameters: {
         type: "object",
         properties: {
@@ -317,7 +448,8 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_brand_endorsements",
-      description: "Retrieve brand endorsements, commercial ambassadorships, luxury fashion, and beauty partnerships of Ju Jingyi.",
+      description: `Authoritative source for all commercial brand contracts, spokesperson titles, global ambassadors, and commercial sales records/statistics (e.g., FRED Paris high jewelry, PRSR Milan, Lafang 30-year ambassador, TuTuCare 20,000 gift boxes 1-second sellout, DAFUYAN).
+[CRITICAL]: If query mentions a commercial brand, ambassador title, or sales record/statistics, ALWAYS call this tool. Do NOT answer from memory or claim lack of records without querying.`,
       parameters: {
         type: "object",
         properties: {
@@ -334,12 +466,14 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_career_timeline",
-      description: "Explore Ju Jingyi's career milestones and chronological eras (SNH48 Era, Solo Studio, Breakthrough Dramas, Present).",
+      description: `Use for historical chronology, career milestones, debut dates, annual awards, election rankings, and chronological milestones across 2013-2026.
+[CRITICAL]: Whenever the user query asks 'from timeline', 'according to timeline' ('ตามไทม์ไลน์', '按时间线', 'in the timeline') or asks for chronological events in a specific year (e.g. 2015 Seine River/Running Man China, 2016 election champion & center song Princess's Cloak, 2017 May 4th Medal & Studio graduation, 2018 co-star with Mike in Mr. Swimmer, 2019 Forbes 30 Under 30 Asia, 2024 Beauty Ambassador), you MUST invoke get_career_timeline. Do NOT substitute with search_works or get_media_links.`,
       parameters: {
         type: "object",
         properties: {
           year: { type: "number", description: "Year filter (2013-2026)" },
-          era: { type: "string", description: "Era keyword" }
+          era: { type: "string", description: "Era keyword (e.g. SNH48 Era, Solo Studio, Breakthrough Dramas, Present)" },
+          limit: { type: "number", description: "Maximum milestones to return (1-20)" }
         },
         required: []
       }
@@ -349,13 +483,18 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_awards",
-      description: "Query awards and honors received by Ju Jingyi across music, television, and cultural influence.",
+      description: `Retrieve official acting and music awards, nominations, rankings, and festival honors (e.g., ERC Chinese Top Ten Awards / 东方风云榜, Weibo TV & Video Summit, Scream Night, Weibo Night).
+[CRITICAL]: Use this tool for ANY question asking which song, role, or album WON an award or was honored at a music chart ceremony. DO NOT use get_media_links or search_discography for award verification.`,
       parameters: {
         type: "object",
         properties: {
-          category: { type: "string", description: "Category (Acting, Music, Honor)" },
-          year: { type: "number", description: "Year filter" },
-          query: { type: "string", description: "Award title, ceremony, or category keyword" },
+          category: {
+            type: "string",
+            enum: ["Music", "Acting", "Breakthrough", "Fashion", "All"],
+            description: "Category of the award"
+          },
+          year: { type: "number", description: "Year of the award ceremony" },
+          query: { type: "string", description: "Ceremony name, song title, or drama title (e.g., 东方风云榜, 恋爱告急, In Blossom)" },
           limit: { type: "number", description: "Maximum results from 1 to 20" }
         },
         required: []
@@ -381,12 +520,13 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_gallery_photos",
-      description: "Search visual photo gallery of Ju Jingyi (red carpet, photoshoot, drama stills).",
+      description: `Retrieve magazine editorial photoshoots, fashion pictorials, desert/studio spreads, and runway styling (e.g., PORT Magazine / 《PORT》九月刊, Harper's BAZAAR, Milan Fashion Week outfits).
+[CRITICAL]: Use this tool when queries ask about clothing, colors, jewelry (e.g., FRED Force 10 in PORT photoshoot), or visual styling featured IN A MAGAZINE OR PHOTO SET. DO NOT call get_brand_endorsements unless the query specifically asks for commercial brand ambassadorship contracts.`,
       parameters: {
         type: "object",
         properties: {
           category: { type: "string", description: "Category (fashion-magazine, red-carpet, drama-stills)" },
-          query: { type: "string", description: "Photo title or category keyword" },
+          query: { type: "string", description: "Magazine name, theme, jewelry collection, or outfit color (e.g., PORT, FRED, Milan, pink)" },
           year: { type: "number", description: "Year filter" },
           limit: { type: "number", description: "Number of photos from 1 to 20" }
         },
@@ -398,11 +538,14 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "global_search",
-      description: "Universal search across ALL Ju Jingyi entities (works, songs, roles, brands, awards, videos) with YouTube and media links.",
+      description: `STRICT FALLBACK TOOL ONLY.
+[NEGATIVE CONSTRAINT]: FORBIDDEN to use on the first turn or for specific entity queries (songs, works, awards, photos, endorsements).
+[PERMITTED ONLY WHEN]: Domain-specific tools (search_works, search_discography, get_awards, etc.) return 0 results or count == 0.
+Searches raw text catalog across all unindexed cross-domain documents.`,
       parameters: {
         type: "object",
         properties: {
-          query: { type: "string", description: "Search term to match across all collections" }
+          query: { type: "string", description: "The exact fallback search string" }
         },
         required: ["query"]
       }
@@ -531,6 +674,113 @@ export const toolsSchema = [
       }
     }
   },
+  {
+    type: "function",
+    function: {
+      name: "search_news",
+      description: "Search live news via Google News RSS + Bing News RSS (supports Thai, Chinese, English automatically). PREFERRED over web_search whenever the user asks about news, latest updates, recent events, or what is new - results include publish dates. Append 'when:7d' to the query to narrow to the last N days.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "News search query, e.g. '鞠婧祎 最新' or 'Ju Jingyi news'" },
+          maxResults: { type: "number", description: "Max results (default 8, max 15)" }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "fetch_rss",
+      description: "Fetch and parse any public RSS/Atom feed URL (news sites, blogs, Sina/Weibo feeds, etc). Returns feed items with title, link, publish date and snippet.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full HTTP/HTTPS URL of the RSS/Atom feed" },
+          maxItems: { type: "number", description: "Max items to return (default 10, max 30)" }
+        },
+        required: ["url"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_encyclopedia",
+      description: "Look up encyclopedia entries: Baidu Baike (百度百科) for Chinese terms, Wikipedia for Thai/English. Returns a structured summary with title, text, thumbnail and page URL. Use for background/biography/profile depth beyond the local catalog.",
+      parameters: {
+        type: "object",
+        properties: {
+          term: { type: "string", description: "Encyclopedia term to look up, e.g. '鞠婧祎', 'Ju Jingyi', 'SNH48'" },
+          language: { type: "string", enum: ["zh", "th", "en"], description: "Optional: force language. Defaults to auto-detect from the term." },
+          maxEntries: { type: "number", description: "Max encyclopedia entries to return (default 2, max 3)" }
+        },
+        required: ["term"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_music_platforms",
+      description: "Search international music platforms (iTunes Search API + MusicBrainz, no API key needed) for songs/albums. Complements the local discography catalog with global platform data, previews and release metadata.",
+      parameters: {
+        type: "object",
+        properties: {
+          term: { type: "string", description: "Song/album/artist search term, e.g. 'Ju Jingyi' or '叹云兮'" },
+          maxResults: { type: "number", description: "Max results (default 8, max 20)" }
+        },
+        required: ["term"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_chinese_web",
+      description: "Search Chinese websites (Baidu first, then site-filtered DuckDuckGo across sina/sohu/weibo/bilibili/iqiyi/mgtv etc). Use for Chinese entertainment news, Weibo topics, and anything on Chinese portals. Requires KIKU_ENABLE_CN_WEB_TOOLS=true.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Chinese search query, e.g. '鞠婧祎 微博'" },
+          maxResults: { type: "number", description: "Max results (default 8, max 15)" },
+          site: { type: "string", description: "Optional domain hint to restrict fallback search, e.g. 'sina.com.cn'" }
+        },
+        required: ["query"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_bilibili",
+      description: "Search Bilibili videos via its public API (stage performances, MVs, fancams, interviews). Returns title, author, duration, play count, publish date and video URL. Requires KIKU_ENABLE_CN_WEB_TOOLS=true.",
+      parameters: {
+        type: "object",
+        properties: {
+          keyword: { type: "string", description: "Bilibili search keyword, e.g. '鞠婧祎 舞台'" },
+          maxResults: { type: "number", description: "Max results (default 8, max 20)" }
+        },
+        required: ["keyword"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_web_images",
+      description: "Search the web (Baidu Images & Chinese entertainment media portals) for photos, on-set stills (路透), red carpet appearances, and press images of Ju Jingyi. Returns direct image URLs, thumbnails, dimensions, and source article links. Requires KIKU_ENABLE_CN_WEB_TOOLS=true.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Image search keyword or topic, e.g. '鞠婧祎 路透', '万花世界 剧照', 'Ju Jingyi red carpet'" },
+          maxResults: { type: "number", description: "Max images to return (default 8, max 20)" }
+        },
+        required: ["query"]
+      }
+    }
+  },
   {
     type: "function",
     function: {
@@ -687,7 +937,7 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_current_track",
-      description: "Get information about the currently playing or paused track.",
+      description: "Get information about the currently playing or paused track only. For the full player state (queue, volume, mute) use get_music_status instead.",
       parameters: { type: "object", properties: {} }
     }
   },
@@ -695,7 +945,7 @@ export const toolsSchema = [
     type: "function",
     function: {
       name: "get_music_status",
-      description: "Get full music player status including playing state, current track, and queue info.",
+      description: "Get FULL music player status in one call: playing/paused state, current track, queue contents, volume, and mute state. Prefer this over get_current_track.",
       parameters: { type: "object", properties: {} }
     }
   },
@@ -805,6 +1055,139 @@ export const toolsSchema = [
         properties: {}
       }
     }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_entertainment_metrics",
+      description: "Query professional Chinese entertainment industry big data platforms (Vlinkage, DataWin, Guduo, Yunhe, Maoyan Pro, Dengta, Weibo, Douban, Xiaohongshu), popularity index, effective streaming views, and Ju Jingyi commercial benchmarks.",
+      parameters: {
+        type: "object",
+        properties: {
+          platform: {
+            type: "string",
+            enum: ["all", "vlinkage", "datawin", "guduo", "yunhe", "maoyan", "dengta", "weibo", "douban", "xiaohongshu"],
+            description: "Specific platform ID or 'all'."
+          },
+          category: {
+            type: "string",
+            enum: ["all", "actor_drama_index", "streaming_boxoffice", "social_commercial"],
+            description: "Category pillar filter."
+          },
+          query: {
+            type: "string",
+            description: "Optional search query to match platform name, metrics, or drama title (e.g. 'In Blossom', 'Yunhe', 'Vlinkage', 'Commercial')."
+          }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "get_industry_index",
+      description: "DEPRECATED ALIAS — identical to get_entertainment_metrics. Call get_entertainment_metrics instead; kept only for backward compatibility.",
+      parameters: {
+        type: "object",
+        properties: {
+          platform: {
+            type: "string",
+            enum: ["all", "vlinkage", "datawin", "guduo", "yunhe", "maoyan", "dengta", "weibo", "douban", "xiaohongshu"],
+            description: "Specific platform ID or 'all'."
+          },
+          category: {
+            type: "string",
+            enum: ["all", "actor_drama_index", "streaming_boxoffice", "social_commercial"],
+            description: "Category pillar filter."
+          },
+          query: {
+            type: "string",
+            description: "Optional search query to match platform name, metrics, or drama title."
+          }
+        },
+        required: []
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "checkpoint_step",
+      description: "Record immediate progress and state checkpoint for an active run. Updates kiku/runs/{run_id}/state and plan checklist.",
+      parameters: {
+        type: "object",
+        properties: {
+          run_id: { type: "string", description: "The active run identifier (e.g. run_123)." },
+          step_name: { type: "string", description: "Name of the subtask or step being executed." },
+          status: { type: "string", enum: ["pending", "in_progress", "completed", "failed", "paused", "waiting_user"], description: "Current execution status of the step." },
+          summary: { type: "string", description: "Concise summary of step execution or outcome." }
+        },
+        required: ["run_id", "step_name", "status", "summary"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "record_failure",
+      description: "Record an error trace and tactical recovery action during task execution for episodic reflection.",
+      parameters: {
+        type: "object",
+        properties: {
+          run_id: { type: "string", description: "The active run identifier." },
+          error_trace: { type: "string", description: "Error message or stack trace describing what failed." },
+          recovery_action: { type: "string", description: "Tactical recovery action or workaround taken." },
+          tool_name: { type: "string", description: "Optional name of the tool that encountered the failure." }
+        },
+        required: ["run_id", "error_trace", "recovery_action"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "load_active_run",
+      description: "Load active run state, execution plan, and checkpoint history for task hydration and resuming.",
+      parameters: {
+        type: "object",
+        properties: {
+          run_id: { type: "string", description: "The run identifier to load." }
+        },
+        required: ["run_id"]
+      }
+    }
+  },
+  {
+    type: "function",
+    function: {
+      name: "record_dynamic_event",
+      description: "Record a newly verified live event, brand activity, appearance, or work into the local dynamic catalog overlay. Persists immediately across restarts without modifying static source files.",
+      parameters: {
+        type: "object",
+        properties: {
+          category: {
+            type: "string",
+            enum: ["brands", "timeline", "gallery", "works", "events"],
+            description: "Catalog category to record this event into."
+          },
+          entry: {
+            type: "object",
+            description: "The structured catalog entry to record (must match category schema, e.g. year, title/brand, etc.)."
+          },
+          source: {
+            type: "string",
+            description: "Origin source URL or platform (e.g. Douyin, Weibo, Official Press)."
+          },
+          trustTier: {
+            type: "number",
+            enum: [1, 2, 3],
+            description: "Trust tier of the information source (1=Official, 2=Press, 3=Community/Other)."
+          }
+        },
+        required: ["category", "entry"]
+      }
+    }
   }
 ];
 
@@ -816,10 +1199,22 @@ const TOOL_DEFAULT_TIMEOUTS = {
   suggest_topics: 120_000,
   web_extract: 90_000,
   screenshot_webpage: 90_000,
+  get_youtube_transcript: 90_000,
   search_youtube: 60_000,
   play_music: 60_000,
+  search_news: 45_000,
+  fetch_rss: 30_000,
+  search_encyclopedia: 45_000,
+  search_music_platforms: 45_000,
+  search_chinese_web: 60_000,
+  search_bilibili: 45_000,
+  search_web_images: 60_000,
 };
 
+const isCnWebEnabled = () => process.env.KIKU_ENABLE_CN_WEB_TOOLS === 'true';
+const cnWebDisabledMessage = (toolName) =>
+  `"${toolName}" is disabled. Set KIKU_ENABLE_CN_WEB_TOOLS=true to enable Chinese web tools (Baidu/Baike/Bilibili scraping — these sites use anti-bot protection and may be unreliable). Meanwhile use web_search, search_news, or search_encyclopedia.`;
+
 async function ensureLlmAvailable(client) {
   if (!client || typeof client.checkConnection !== 'function') return null;
   try {
@@ -837,26 +1232,56 @@ async function ensureLlmAvailable(client) {
   return null;
 }
 
-export const RUMORED_OR_EXTERNAL_PROJECTS = [
-  {
-    keywords: ['七星彩', 'qi xiang cai', 'qi xing cai', 'ชีซิงไฉ่', 'seven star color'],
-    titleCn: '七星彩',
-    titleEn: 'Qi Xing Cai (Seven Star Color)',
-    status: 'rumored_casting',
-    producer: 'Youku (优酷) x Stellar Media (恒星引力传媒)',
-    originalNovel: '《七星彩》 by 明月珰 (Mingyue Dang)',
-    leads: '纪澄 (Ji Cheng) & 沈彻 (Shen Che)',
-    details: 'โปรเจกต์ซีรีส์จีนโบราณฟอร์มยักษ์ของ Youku ร่วมกับค่ายเหิงซิงอิ่นลี่ (ผู้สร้างของรักของข้า Love Between Fairy and Devil) ดัดแปลงจากนิยายของหมิงเยว่ตัง เล่าเรื่องราวของจี้เฉิง บุตรสาวตระกูลพ่อค้าที่ใช้ปฏิภาณไหวพริบเอาตัวรอดจนได้พบกับแม่ทัพเสิ่นเช่อ',
-    buzzReason: 'เหตุผลที่ชาวเน็ตให้ความสนใจอย่างมากคือ กระแสข่าวลือแคสติ้งนักแสดงนำ (Casting Rumors / 选角瓜) โดยมีการลือชื่อนักแสดงหญิงแถวหน้าหลายคนรวมถึง จวีจิ้งอี, หลูอวี้เสี่ยว ฯลฯ แต่ปัจจุบันยังไม่มีการประกาศยืนยันนักแสดงทางการจากทางค่ายหรือสตูดิโอ',
-    disambiguation: 'คนละผลงานกับซีรีส์ 《千香》 (The Eternal Fragrance / พันกลิ่นบุปผา) ที่จวีจิ้งอีนำแสดงร่วมกับ ซ่งเวยหลง'
-  }
-];
+import { RUMORED_OR_EXTERNAL_PROJECTS } from './rumoredProjects.js';
+
+export { RUMORED_OR_EXTERNAL_PROJECTS };
 
 export const toolHandlers = {
-  get_profile_and_fandom: async () => {
-    const d = profileData.details || {};
+  get_current_datetime: async () => {
+    const now = new Date();
+    const offsetMinutes = -now.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const absOffset = Math.abs(offsetMinutes);
+    const timezoneOffset = `${sign}${String(Math.floor(absOffset / 60)).padStart(2, '0')}:${String(absOffset % 60).padStart(2, '0')}`;
+    let timezoneName = null;
+    try {
+      timezoneName = Intl.DateTimeFormat().resolvedOptions().timeZone || null;
+    } catch { }
     return {
       status: "success",
+      iso: now.toISOString(),
+      local: now.toLocaleString('en-GB', { hour12: false }),
+      timezoneOffset,
+      timezoneName,
+      weekday: now.toLocaleDateString('en-US', { weekday: 'long' }),
+      year: now.getFullYear(),
+      month: now.getMonth() + 1,
+      day: now.getDate(),
+      timestampMs: now.getTime()
+    };
+  },
+
+  get_youtube_transcript: async (args = {}) => fetchYoutubeTranscript(args),
+
+  get_profile_and_fandom: async ({ section, query } = {}) => {
+    const d = profileData.details || {};
+    const qStr = String(query || '').toLowerCase().trim();
+    const isCatQuery = /(cat|cats|แมว|สัตว์เลี้ยง|pet|pets|miaomiao)/i.test(qStr);
+
+    if (isCatQuery) {
+      return {
+        status: "success",
+        query: query || "cats",
+        nameTh: profileData.nameTh,
+        nameCn: profileData.nameCn,
+        petsSummary: d.petsSummary || "แมว 3 ตัว: ฮวาฮวา (Huahua), เมี่ยวเมี่ยว (Miaomiao), เลิฟเวอร์ (Lover)",
+        cats: profileData.cats || []
+      };
+    }
+
+    const result = {
+      status: "success",
+      query: query || undefined,
       profile: {
         nameTh: profileData.nameTh,
         nameCn: profileData.nameCn,
@@ -878,10 +1303,28 @@ export const toolHandlers = {
         cats: profileData.cats || [],
         fandomName: d.fandomName || "มี่จวี (Miju / 蜜橘)",
         fandomColor: d.fandomColorName || "ฟ้าคริสตัล & ชมพูซากุระ",
-        slogan: profileData.motto || "保持热爱，奔赴山海",
-        youtubeSearchUrl: buildYouTubeSearchUrl("Ju Jingyi 鞠婧祎")
+        slogan: profileData.motto || "保持热爱，奔赴山海"
       }
     };
+
+    const requested = String(section || 'all').toLowerCase();
+    if (requested === 'talents' || requested === 'all') {
+      result.talents = (profileData.talents || []).map(t => ({
+        id: t.id, title: t.title, titleCn: t.titleCn, level: t.level, description: t.description
+      }));
+    }
+    if (requested === 'stats' || requested === 'all') {
+      result.stats = profileData.stats || [];
+    }
+    if (requested === 'honors' || requested === 'all') {
+      result.honors = profileData.forbesHonors || [];
+    }
+    if (requested === 'social' || requested === 'all') {
+      result.socialLinks = (profileData.socialLinks || []).map(s => ({
+        name: s.name, url: s.url, username: s.username, type: s.type, badge: s.badge
+      }));
+    }
+    return result;
   },
 
   get_quotes: async ({ tag } = {}) => {
@@ -907,20 +1350,44 @@ export const toolHandlers = {
   },
 
   search_works: async ({ query, year, category, featuredOnly } = {}) => {
-    let results = [...worksData];
+    const dynamicWorks = getDynamicEntries('works');
+    const baseWorks = dynamicWorks && dynamicWorks.length > 0 ? [...dynamicWorks, ...worksData] : [...worksData];
+    let results = [...baseWorks];
 
     if (year) results = results.filter(w => w.year === Number(year));
-    if (category && category !== 'all') results = results.filter(w => w.category === category);
+    const categoryFilter = normalizeWorkCategoryFilter(category);
+    if (categoryFilter) results = results.filter(w => categoryFilter.includes(w.category));
 
+    let broadMatch = false;
+    let matcher = null;
     if (query) {
-      const matcher = createCatalogMatcher(query);
-      results = results.filter(w => matcher(w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis));
+      matcher = createCatalogMatcher(query);
+      if (matcher.broad) {
+        broadMatch = true;
+      } else {
+        results = results.filter(w => matcher(
+          w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis,
+          ...(w.aliases || []), ...(w.keywords || [])
+        ));
+      }
     }
 
     if (featuredOnly && results.some(w => !!w.featured)) {
       results = results.filter(w => !!w.featured);
     }
 
+    if (results.length === 0 && query && (categoryFilter || year)) {
+      let relaxed = [...baseWorks];
+      const fallbackMatcher = matcher || createCatalogMatcher(query);
+      relaxed = relaxed.filter(w => fallbackMatcher(
+        w.titleTh, w.titleEn, w.titleCn, w.role, w.roleCn, w.synopsis,
+        ...(w.aliases || []), ...(w.keywords || [])
+      ));
+      if (relaxed.length > 0) {
+        results = relaxed;
+      }
+    }
+
     if (results.length === 0 && query) {
       const qLower = String(query).toLowerCase().trim();
       const rumored = RUMORED_OR_EXTERNAL_PROJECTS.find(p => p.keywords.some(k => qLower.includes(k)));
@@ -937,7 +1404,7 @@ export const toolHandlers = {
 
     results.sort((a, b) => (b.year || 0) - (a.year || 0));
 
-    return {
+    const result = {
       status: "success",
       count: results.length,
       works: results.slice(0, 6).map(w => {
@@ -950,14 +1417,15 @@ export const toolHandlers = {
           titleEn: w.titleEn,
           year: w.year,
           category: w.category,
-          role: w.role,
-          roleCn: w.roleCn,
-          synopsis: w.synopsis || null,
-          highlights: (w.highlights || []).slice(0, 3),
+          role: w.role,
+          roleCn: w.roleCn,
+          synopsis: w.synopsis || null,
+          highlights: (w.highlights || []).slice(0, 3),
           episodes: w.episodes,
           rating: w.rating,
           platform: w.streamPlatform,
           streamUrl: w.streamUrl || null,
+          poster: w.poster || null,
           youtubeTrailerSearch: buildYouTubeSearchUrl(`${titleSearch} Trailer Official`),
           youtubeTrailerIsDirectLink: false,
           youkuSearchUrl: buildYoukuSearchUrl(w.titleCn || w.titleEn),
@@ -968,22 +1436,33 @@ export const toolHandlers = {
             youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.themeSong.titleCn || w.themeSong.titleTh} OST`)
           } : null
         };
-      })
+      }),
+      images: results.slice(0, 6).map(w => ({
+        title: `${w.titleTh || w.titleCn} (${w.year})`,
+        imageUrl: w.poster || null,
+        thumbUrl: w.poster || null,
+        source: 'Series Poster'
+      })).filter(img => img.imageUrl)
     };
+    if (broadMatch) {
+      result.message = `Broad query "${query}": every search term was generic, so no title/character filter was applied. The works below are the newest catalog entries, not an exact match for "${query}" — say so explicitly if you use them.`;
+    }
+    return result;
   },
 
   get_work_detail: async ({ workIdOrTitle }) => {
     if (!workIdOrTitle) return { status: "error", message: "workIdOrTitle parameter is required." };
     const q = workIdOrTitle.toLowerCase().trim();
    
-    const normId = (value) => String(value || '').toLowerCase().trim().replace(/[_\s]+/g, '-');
-    const qId = normId(workIdOrTitle);
-    let work = worksData.find(w =>
-      normId(w.id) === qId ||
-      w.titleTh.toLowerCase().includes(q) ||
-      (w.titleEn && w.titleEn.toLowerCase().includes(q)) ||
-      (w.titleCn && w.titleCn.includes(workIdOrTitle))
-    );
+    const qId = normalizeWorkId(workIdOrTitle);
+    let work = WORKS_BY_NORM_ID.get(qId) || null;
+    if (!work) {
+      work = worksData.find(w =>
+        w.titleTh.toLowerCase().includes(q) ||
+        (w.titleEn && w.titleEn.toLowerCase().includes(q)) ||
+        (w.titleCn && w.titleCn.includes(workIdOrTitle))
+      );
+    }
     if (!work) {
 
       const matcher = createCatalogMatcher(workIdOrTitle);
@@ -1006,8 +1485,8 @@ export const toolHandlers = {
         titleEn: work.titleEn,
         year: work.year,
         category: work.category,
-        role: work.role,
-        roleCn: work.roleCn,
+        role: work.role,
+        roleCn: work.roleCn,
         episodes: work.episodes,
         rating: work.rating,
         platform: work.streamPlatform,
@@ -1016,7 +1495,7 @@ export const toolHandlers = {
         youtubeTrailerIsDirectLink: false,
         youkuSearchUrl: buildYoukuSearchUrl(work.titleCn || work.titleEn),
         bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${work.titleCn}`),
-        synopsis: work.synopsis || null,
+        synopsis: work.synopsis || null,
         highlights: (work.highlights || []).slice(0, 3),
         themeSong: work.themeSong ? {
           title: formatCatalogTitle(work.themeSong.titleTh, work.themeSong.titleCn),
@@ -1029,7 +1508,26 @@ export const toolHandlers = {
   },
 
   get_character_roles: async ({ query } = {}) => {
-    const roles = worksData.map(w => ({
+    if (query) {
+      const qLower = String(query).toLowerCase();
+      const isPersonal = PERSONAL_FACT_KEYWORDS.some(k => qLower.includes(k));
+      if (isPersonal) {
+        return {
+          status: "misdirected",
+          count: 0,
+          roles: [],
+          message: "get_character_roles contains fictional drama and movie characters only. For Ju Jingyi's personal facts, birthplace, education, musical instruments, blood type, or biography, call get_profile_and_fandom."
+        };
+      }
+    }
+
+    let matchedWorks = worksData;
+    if (query) {
+      const matcher = createCatalogMatcher(query);
+      matchedWorks = worksData.filter(w => matcher(w.role, w.roleCn, formatCatalogTitle(w.titleTh, w.titleCn), w.titleTh, w.titleCn));
+    }
+
+    const filtered = matchedWorks.map(w => ({
       workTitle: formatCatalogTitle(w.titleTh, w.titleCn),
       year: w.year,
       role: w.role,
@@ -1037,12 +1535,6 @@ export const toolHandlers = {
       youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.roleCn || w.role} ${w.titleCn}`)
     }));
 
-    let filtered = roles;
-    if (query) {
-      const matcher = createCatalogMatcher(query);
-      filtered = roles.filter(r => matcher(r.role, r.roleCn, r.workTitle));
-    }
-
     filtered.sort((a, b) => (b.year || 0) - (a.year || 0));
 
     return {
@@ -1053,7 +1545,9 @@ export const toolHandlers = {
   },
 
   search_discography: async ({ query, year, type } = {}) => {
-    let list = getCleanDiscography();
+    let rawList = getCleanDiscography();
+    let list = [...rawList];
+    let broadMatch = false;
 
     if (year) list = list.filter(s => s.year === Number(year));
     if (type === 'ost') list = list.filter(s => s.work && s.work !== "Solo Single");
@@ -1071,20 +1565,99 @@ export const toolHandlers = {
         };
       }
       const matcher = createCatalogMatcher(query);
-      list = list.filter(s => matcher(s.titleTh, s.titleCn, s.titleEn, s.work, s.role, s.description));
+      if (matcher.broad) {
+        broadMatch = true;
+      } else {
+        list = list.filter(s => matcher(
+          s.titleTh, s.titleCn, s.titleEn, s.work, s.role, s.description,
+          ...(s.aliases || []), ...(s.keywords || [])
+        ));
+      }
+
+      if (list.length === 0 && (type || year)) {
+        let relaxed = [...rawList];
+        relaxed = relaxed.filter(s => matcher(
+          s.titleTh, s.titleCn, s.titleEn, s.work, s.role, s.description,
+          ...(s.aliases || []), ...(s.keywords || [])
+        ));
+        if (relaxed.length > 0) {
+          list = relaxed;
+        }
+      }
+
+      const qClean = qLower;
+      const scoredList = list.map(item => {
+        const titles = [item.titleEn, item.titleCn, item.titleTh, ...(item.aliases || [])];
+        let score = 0;
+        for (const t of titles) {
+          if (!t) continue;
+          const lower = String(t).toLowerCase().trim();
+          if (lower === qClean) {
+            score = 2;
+            break;
+          }
+          if (score < 1 && lower.includes(qClean)) {
+            score = 1;
+          }
+        }
+        return { item, score };
+      });
+      scoredList.sort((a, b) => b.score - a.score);
+      list = scoredList.map(s => s.item);
+    }
+
+    if (list.length === 0 && query) {
+      const allMVs = getAllMusicVideos();
+      const mvMatcher = createCatalogMatcher(query);
+      const mvMatches = allMVs.filter(m => mvMatcher(
+        m.titleTh, m.titleCn, m.titlePinyin, m.dramaName, m.description,
+        ...(m.aliases || []), ...(m.keywords || [])
+      ));
+      if (mvMatches.length > 0) {
+        return {
+          status: "success",
+          source: "musicVideoData",
+          cascadeMatched: true,
+          count: mvMatches.length,
+          message: `Cascade retrieval: Matched in music videos catalog (musicVideoData) for "${query}".`,
+          songs: mvMatches.slice(0, 5).map(m => ({
+            id: m.id,
+            title: formatCatalogTitle(m.titleTh, m.titleCn),
+            titleEn: m.titleCn,
+            titleCn: m.titleCn,
+            year: m.releaseYear || m.year,
+            type: m.category || "Single",
+            work: m.dramaName || "Music Video",
+            category: m.category,
+            duration: m.duration,
+            youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
+            isDirectLink: Boolean(m.youtubeId),
+            youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh}`),
+            bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${m.titleCn || m.titleTh}`)
+          }))
+        };
+      }
     }
 
     return {
       status: list.length > 0 ? "success" : "not_found",
-      message: list.length > 0 ? undefined : `No matching discography entries for "${query || 'this filter'}".`,
+      message: list.length > 0
+        ? (broadMatch ? `Broad query "${query}": every search term was generic, so no title filter was applied. The songs below are the newest catalog entries, not an exact match for "${query}" — say so explicitly if you use them.` : undefined)
+        : `No matching discography entries for "${query || 'this filter'}".`,
       count: list.length,
       songs: list.slice(0, 8).map(s => ({
         id: s.id,
         title: formatCatalogTitle(s.titleTh, s.titleCn),
         titleEn: s.titleEn,
+        titleCn: s.titleCn,
         year: s.year,
         type: s.work,
-        duration: s.duration,
+        work: s.work,
+        category: s.category,
+        categoryName: s.categoryName,
+        role: s.role,
+        description: s.description,
+        duration: s.duration || s.trackDuration,
         youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
         isDirectLink: Boolean(s.youtubeUrl || s.youtubeId),
         youtubeSearchUrl: s.youtubeSearchUrl || buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${s.titleCn || s.titleTh}`),
@@ -1098,7 +1671,7 @@ export const toolHandlers = {
     const allMVs = getAllMusicVideos();
 
     let results = allMVs;
-    if (category) {
+    if (category && category.toLowerCase() !== 'all') {
       const catLower = category.toLowerCase();
       results = results.filter(m => {
         const mCat = (m.category || '').toLowerCase();
@@ -1112,7 +1685,10 @@ export const toolHandlers = {
     
     if (query) {
       const matcher = createCatalogMatcher(query);
-      results = results.filter(m => matcher(m.titleTh, m.titleCn, m.titlePinyin, m.dramaName, m.description));
+      results = results.filter(m => matcher(
+        m.titleTh, m.titleCn, m.titlePinyin, m.dramaName, m.description,
+        ...(m.aliases || []), ...(m.keywords || [])
+      ));
     }
 
     return {
@@ -1124,12 +1700,14 @@ export const toolHandlers = {
         return {
           id: m.id,
           title: formatCatalogTitle(m.titleTh, m.titleCn),
+          titleCn: m.titleCn || null,
           category: m.category,
           year: m.releaseYear || m.year,
           drama: m.dramaName || null,
           duration: m.duration || null,
           description: m.description || null,
           isFeatured: !!m.isFeatured,
+          youtubeId: ytId,
           youtubeUrl: ytId ? buildYouTubeWatchUrl(ytId) : null,
           isDirectLink: Boolean(ytId),
           youtubeSearchUrl: buildYouTubeSearchUrl(searchTitle),
@@ -1157,6 +1735,8 @@ export const toolHandlers = {
       title: formatCatalogTitle(m.titleTh, m.titleCn),
       year: m.releaseYear || m.year,
       duration: m.duration,
+      drama: m.dramaName || null,
+      description: m.description || null,
       youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
       youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh} ${m.category === 'Stage-Performance' ? 'Stage' : 'Official MV'}`),
       bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${m.titleCn || m.titleTh}`)
@@ -1170,8 +1750,12 @@ export const toolHandlers = {
     ).map(s => ({
       type: s.work || 'Song',
       title: formatCatalogTitle(s.titleTh, s.titleCn),
+      titleEn: s.titleEn || null,
       year: s.year,
       duration: s.duration,
+      work: s.work || null,
+      role: s.role || null,
+      description: s.description || null,
       youtubeUrl: s.youtubeUrl || (s.youtubeId ? buildYouTubeWatchUrl(s.youtubeId) : null),
       youtubeSearchUrl: s.youtubeSearchUrl || buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${s.titleCn || s.titleTh}`),
       qqMusicSearchUrl: s.qqMusicSearchUrl || buildQqMusicSearchUrl(`鞠婧祎 ${s.titleCn || s.titleTh}`),
@@ -1186,6 +1770,9 @@ export const toolHandlers = {
       type: 'Drama / Series',
       title: formatCatalogTitle(w.titleTh, w.titleCn),
       year: w.year,
+      role: w.role,
+      roleCn: w.roleCn,
+      synopsis: w.synopsis || null,
       platform: w.streamPlatform,
       streamUrl: w.streamUrl || null,
       youtubeTrailerSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${w.titleCn || w.titleEn} Trailer Official`),
@@ -1200,6 +1787,21 @@ export const toolHandlers = {
     const generalYouTubeSearch = buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`);
     const generalBilibiliSearch = buildBilibiliSearchUrl(`鞠婧祎 ${query}`);
 
+    const brandItems = Array.isArray(brandsData) ? brandsData : (brandsData.brandList || brandsData.brands || []);
+    const matchedBrands = brandItems.filter(b => {
+      const bEn = String(b.brandNameEn || b.brand || b.name || '').toLowerCase();
+      const bCn = String(b.brandNameCn || '');
+      return bEn.includes(q) || (bCn && query.includes(bCn)) || (bCn && bCn.includes(query)) || (b.id && b.id.toLowerCase().includes(q));
+    }).map(b => ({
+      type: 'Brand / Commercial',
+      brand: `${b.brandNameEn || b.brand || b.name} (${b.brandNameCn || ''})`,
+      year: b.year,
+      title: b.title,
+      category: b.category,
+      youtubeCommercialSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${b.brandNameEn || b.brandNameCn} Commercial`),
+      bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${b.brandNameCn || b.brandNameEn}`)
+    }));
+
     return {
       status: "success",
       query,
@@ -1208,57 +1810,164 @@ export const toolHandlers = {
       results: {
         musicVideos: matchedVideos.slice(0, 5),
         songs: matchedSongs.slice(0, 5),
-        works: matchedWorks.slice(0, 3)
+        works: matchedWorks.slice(0, 3),
+        brands: matchedBrands.slice(0, 3)
       }
     };
   },
 
   get_brand_endorsements: async ({ isGlobal, category, year, query } = {}) => {
-    let list = Array.isArray(brandsData) ? [...brandsData] : [...(brandsData.brandList || brandsData.brands || [])];
+    const dynamicBrands = getDynamicEntries('brands');
+    let rawList = Array.isArray(brandsData) ? [...brandsData] : [...(brandsData.brandList || brandsData.brands || [])];
+    if (dynamicBrands && dynamicBrands.length > 0) {
+      rawList = [...dynamicBrands, ...rawList];
+    }
+    let list = [...rawList];
 
     if (typeof isGlobal === 'boolean') list = list.filter(b => !!b.isGlobal === isGlobal);
     if (year) list = list.filter(b => b.year === Number(year));
-    if (category) list = list.filter(b => (b.category && b.category.toLowerCase().includes(category.toLowerCase())) || (b.tier && b.tier.toLowerCase().includes(category.toLowerCase())));
 
+    const matchesCategory = (b, cat) => {
+      const cLower = String(cat).toLowerCase().trim();
+      if ((b.category && b.category.toLowerCase().includes(cLower)) || (b.tier && b.tier.toLowerCase().includes(cLower))) return true;
+      if (CATEGORY_ALIASES) {
+        for (const [canonical, aliases] of Object.entries(CATEGORY_ALIASES)) {
+          if (cLower.includes(canonical) || aliases.some(a => cLower.includes(a.toLowerCase()))) {
+            const bText = `${b.category || ''} ${b.tier || ''} ${(b.keywords || []).join(' ')} ${(b.aliases || []).join(' ')}`.toLowerCase();
+            if (aliases.some(a => bText.includes(a.toLowerCase()))) return true;
+          }
+        }
+      }
+      return false;
+    };
+
+    if (category) list = list.filter(b => matchesCategory(b, category));
+
+    let activeMatcher = null;
     if (query) {
       const numYear = Number(String(query).trim());
       if (!isNaN(numYear) && numYear >= 2013 && numYear <= 2030) {
         list = list.filter(b => b.year === numYear);
       } else {
-        const matcher = createCatalogMatcher(query);
-        list = list.filter(b => matcher(b.brandNameEn, b.brandNameCn, b.name, b.title, b.category, b.highlight, b.tier));
+        activeMatcher = createCatalogMatcher(query);
+        list = list.filter(b => activeMatcher(
+          b.brandNameEn, b.brandNameCn, b.brand, b.name, b.title, b.category, b.highlight, b.tier,
+          ...(b.aliases || []), ...(b.keywords || [])
+        ));
+      }
+    }
+
+    if (list.length === 0 && (category || query)) {
+      let relaxed = [...rawList];
+      if (typeof isGlobal === 'boolean') relaxed = relaxed.filter(b => !!b.isGlobal === isGlobal);
+      if (year) relaxed = relaxed.filter(b => b.year === Number(year));
+      const targetQuery = query || category;
+      if (targetQuery) {
+        const matcher = (targetQuery === query && activeMatcher) ? activeMatcher : createCatalogMatcher(targetQuery);
+        relaxed = relaxed.filter(b => matcher(
+          b.brandNameEn, b.brandNameCn, b.brand, b.name, b.title, b.category, b.highlight, b.tier,
+          ...(b.aliases || []), ...(b.keywords || [])
+        ));
+        if (relaxed.length > 0) {
+          list = relaxed;
+        }
       }
     }
 
     list.sort((a, b) => (b.year || 0) - (a.year || 0));
 
+    if (list.length === 0 && query) {
+      const qLower = String(query).toLowerCase().trim();
+      const isMedia = /poi|song|single|video|mv|ost|เพลง|ละคร|ซีรีส์|บทบาท/i.test(qLower);
+      return {
+        status: "not_found",
+        count: 0,
+        brands: [],
+        message: isMedia
+          ? `No brand endorsement matching "${query}". "${query}" appears to be a song, music video, or drama work. Please call search_discography, get_music_videos, or search_works instead.`
+          : `No brand endorsements found for query "${query}".`
+      };
+    }
+
+    const dynamicSales = dynamicBrands ? dynamicBrands.filter(b => b.salesHighlights || b.stat).flatMap(b => b.salesHighlights || [{ brand: b.brandNameEn || b.brand, detail: b.highlight || '', stat: b.stat || '' }]) : [];
+    const allSales = [...dynamicSales, ...(Array.isArray(brandsData?.salesHighlights) ? brandsData.salesHighlights : [])];
+    let relevantSales = allSales;
+    if (query) {
+      const qLower = String(query).toLowerCase().trim();
+      const filtered = allSales.filter(s =>
+        (s.brand && s.brand.toLowerCase().includes(qLower)) ||
+        (s.brandId && s.brandId.toLowerCase().includes(qLower)) ||
+        (s.detail && s.detail.toLowerCase().includes(qLower)) ||
+        (s.stat && s.stat.toLowerCase().includes(qLower))
+      );
+      if (filtered.length > 0) relevantSales = filtered;
+    }
+
     return {
       status: "success",
       count: list.length,
-      brands: list.slice(0, 8).map(b => ({
-        brand: `${b.brandNameEn || b.brand || b.name} (${b.brandNameCn || ''})`,
-        year: b.year,
-        title: b.title || (b.isGlobal ? 'Global Brand Ambassador' : 'Brand Ambassador'),
-        category: b.category,
-        isGlobal: !!b.isGlobal,
-        highlight: b.highlight || '',
-        youtubeCommercialSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${b.brandNameEn || b.brandNameCn} CF Commercial`)
-      }))
+      brands: list.slice(0, 8).map(b => {
+        const brandName = b.brandNameEn || b.brand || b.name || '';
+        const brandCn = b.brandNameCn || '';
+        return {
+          brand: `${brandName} (${brandCn})`.trim(),
+          brandNameEn: brandName,
+          brandNameCn: brandCn,
+          year: b.year,
+          title: b.title || (b.isGlobal ? 'Global Brand Ambassador' : 'Brand Ambassador'),
+          category: b.category,
+          isGlobal: !!b.isGlobal,
+          highlight: b.highlight || '',
+          youtubeCommercialSearch: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${brandName || brandCn} CF Commercial`),
+          bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${brandCn || brandName}`)
+        };
+      }),
+      salesHighlights: relevantSales
     };
   },
 
-  get_career_timeline: async ({ year, era } = {}) => {
-    let eras = Array.isArray(timelineData) ? timelineData : (timelineData.eras || []);
-    if (year) eras = eras.filter(e => e.year == year || (e.period && e.period.includes(String(year))));
-    if (era) eras = eras.filter(e => e.title?.toLowerCase().includes(era.toLowerCase()) || e.era?.includes(era));
+  get_career_timeline: async ({ year, era, limit = 10 } = {}) => {
+    const dynamicTimeline = [...getDynamicEntries('timeline'), ...getDynamicEntries('events')];
+    let eras = Array.isArray(timelineData) ? [...timelineData] : [...(timelineData.eras || [])];
+    if (dynamicTimeline && dynamicTimeline.length > 0) {
+      eras = [...dynamicTimeline, ...eras];
+    }
+    if (year) eras = eras.filter(e => e.year == year || (e.period && String(e.period).includes(String(year))) || (e.date && String(e.date).includes(String(year))));
+    if (era) {
+      const q = String(era).toLowerCase().trim();
+      const qNorm = q.replace(/\s*era\s*/gi, '').trim();
+      eras = eras.filter(e => {
+        const eEra = String(e.era || '').toLowerCase().trim();
+        const eEraNorm = eEra.replace(/\s*era\s*/gi, '').trim();
+        const eTitle = String(e.title || '').toLowerCase();
+        const eTitleCn = String(e.titleCn || '');
+        const eCategory = String(e.category || '').toLowerCase();
+        const eSummary = String(e.summary || '').toLowerCase();
+        return (
+          (eEra && (eEra.includes(q) || (qNorm && eEraNorm.includes(qNorm)) || (qNorm && qNorm.includes(eEraNorm)))) ||
+          eTitle.includes(q) || (qNorm && eTitle.includes(qNorm)) ||
+          eTitleCn.includes(era) ||
+          eCategory.includes(q) || (qNorm && eCategory.includes(qNorm)) ||
+          eSummary.includes(q) || (qNorm && eSummary.includes(qNorm))
+        );
+      });
+    }
 
+    const safeLimit = Math.min(Math.max(Number(limit) || 10, 1), 30);
     return {
-      status: "success",
+      status: eras.length > 0 ? "success" : "not_found",
       count: eras.length,
-      milestones: eras.slice(0, 6).map(e => ({
+      milestones: eras.slice(0, safeLimit).map(e => ({
+        id: e.id,
+        year: e.year,
+        date: e.date || e.period || String(e.year || ''),
         period: e.period || e.year,
         title: formatCatalogTitle(e.title, e.titleCn),
-        summary: e.summary?.slice(0, 150),
+        titleCn: e.titleCn,
+        era: e.era,
+        category: e.category,
+        summary: e.summary,
+        highlights: e.highlights || [],
         youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${e.titleCn || e.title}`)
       }))
     };
@@ -1272,15 +1981,27 @@ export const toolHandlers = {
     let usedQueryFilter = false;
     if (query) {
       const q = String(query).toLowerCase().trim();
-    
+
       const generic = /(ju jingyi|jujingyi|จวีจิ้งอี|จิ้งอี|จวี|鞠婧祎|小鞠|kiku|kikuuu|ju jing yi|蜜橘)/i.test(q);
       if (!generic) {
-        const filtered = list.filter(a => [a.titleTh, a.titleCn, a.titleEn, a.ceremony, a.category, a.work].filter(Boolean).join(' ').toLowerCase().includes(q));
-        if (filtered.length > 0) {
-          list = filtered;
-          usedQueryFilter = true;
+        const matcher = createCatalogMatcher(q);
+        if (matcher.broad) {
+
+        } else {
+          const filtered = list.filter(a => matcher(a.titleTh, a.titleCn, a.titleEn, a.ceremony, a.category, a.work));
+          if (filtered.length > 0) {
+            list = filtered;
+            usedQueryFilter = true;
+          } else {
+            return {
+              status: "not_found",
+              count: 0,
+              awards: [],
+              query,
+              message: `No awards match the query "${query}" in the local catalog. Do NOT present other awards as an answer to this query. Use web_search or web_extract for external information, or call get_awards without a query to list all awards.`
+            };
+          }
         }
-       
       }
     }
 
@@ -1327,20 +2048,36 @@ export const toolHandlers = {
   },
 
   get_gallery_photos: async ({ category, query, year, limit = 4 } = {}) => {
-    let photos = Array.isArray(galleryData) ? galleryData : (galleryData.photos || []);
+    const dynamicPhotos = getDynamicEntries('gallery');
+    let photos = Array.isArray(galleryData) ? [...galleryData] : [...(galleryData.photos || [])];
+    if (dynamicPhotos && dynamicPhotos.length > 0) {
+      photos = [...dynamicPhotos, ...photos];
+    }
     if (category && category !== 'all') photos = photos.filter(p => p.category?.toLowerCase().includes(category.toLowerCase()));
     let usedQueryFilter = false;
     if (query) {
       const q = String(query).toLowerCase().trim();
-    
+
       const generic = /(ju jingyi|jujingyi|จวีจิ้งอี|จิ้งอี|จวี|鞠婧祎|小鞠|kiku|kikuuu|ju jing yi|蜜橘)/i.test(q);
       if (!generic) {
-        const filtered = photos.filter(p => [p.titleTh, p.titleCn, p.titleEn, p.category, p.description].filter(Boolean).join(' ').toLowerCase().includes(q));
-        if (filtered.length > 0) {
-          photos = filtered;
-          usedQueryFilter = true;
+        const matcher = createCatalogMatcher(q);
+        if (matcher.broad) {
+        
+        } else {
+          const filtered = photos.filter(p => matcher(p.titleTh, p.titleCn, p.titleEn, p.category, p.description));
+          if (filtered.length > 0) {
+            photos = filtered;
+            usedQueryFilter = true;
+          } else {
+            return {
+              status: "not_found",
+              count: 0,
+              photos: [],
+              query,
+              message: `No photos match the query "${query}" in the local catalog. Do NOT present other photos as an answer to this query. Use web_search or web_extract for external information, or call get_gallery_photos without a query to browse all photos.`
+            };
+          }
         }
-       
       }
     }
     if (year) photos = photos.filter(p => Number(p.era || p.year) === Number(year));
@@ -1354,8 +2091,15 @@ export const toolHandlers = {
         id: p.id || `photo-${p.era || p.year || 'unknown'}-${index + 1}`,
         title: p.titleTh || p.titleCn,
         category: p.category,
-        year: p.era || p.year
-      }))
+        year: p.era || p.year,
+        imageUrl: p.image || p.imageUrl || p.url || null
+      })),
+      images: shown.map(p => ({
+        title: p.titleTh || p.titleCn || 'Gallery Photo',
+        imageUrl: p.image || p.imageUrl || p.url,
+        thumbUrl: p.image || p.imageUrl || p.url,
+        source: 'Official Gallery'
+      })).filter(img => img.imageUrl)
     };
     if (usedQueryFilter === false && query) {
       result.message = `Showing all ${result.count} photos (broad query "${query}" applied to full list).`;
@@ -1379,6 +2123,12 @@ export const toolHandlers = {
       matcher(s.titleTh, s.titleEn, s.titleCn, s.work, s.role, s.description)
     ).slice(0, 4).map(s => ({
       title: `${s.titleTh} (${s.year})`,
+      titleEn: s.titleEn || null,
+      titleCn: s.titleCn || null,
+      year: s.year,
+      work: s.work || null,
+      role: s.role || null,
+      description: s.description || null,
       youtubeUrl: s.youtubeUrl || null,
       isDirectLink: Boolean(s.youtubeUrl),
       youtubeSearchUrl: s.youtubeSearchUrl
@@ -1388,6 +2138,8 @@ export const toolHandlers = {
       matcher(m.titleTh, m.titleCn, m.titlePinyin, m.dramaName, m.description)
     ).slice(0, 4).map(m => ({
       title: `${formatCatalogTitle(m.titleTh, m.titleCn)} [${m.category}]`,
+      drama: m.dramaName || null,
+      description: m.description || null,
       youtubeUrl: m.youtubeId ? buildYouTubeWatchUrl(m.youtubeId) : null,
       isDirectLink: Boolean(m.youtubeId),
       youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${m.titleCn || m.titleTh}`)
@@ -1409,7 +2161,8 @@ export const toolHandlers = {
         works: matchedWorks,
         songs: matchedSongs,
         brands: matchedBrands,
-        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`)
+        youtubeSearchUrl: buildYouTubeSearchUrl(`Ju Jingyi 鞠婧祎 ${query}`),
+        bilibiliSearchUrl: buildBilibiliSearchUrl(`鞠婧祎 ${query}`)
       }
     };
   },
@@ -1422,35 +2175,35 @@ export const toolHandlers = {
     return await fetchWebpage(url);
   },
 
-  fetch_api: async ({ endpoint, query, baseUrl } = {}) => {
-    if (!endpoint) return { status: "error", message: "endpoint parameter is required (e.g. 'profile', 'works', 'search')" };
-    const base = (baseUrl || 'https://jujingyi-kikuuu.vercel.app/api/v1').replace(/\/$/, '');
-    const originCheck = sanitizeUrl(base);
+  fetch_api: async ({ endpoint, query, baseUrl } = {}) => {
+    if (!endpoint) return { status: "error", message: "endpoint parameter is required (e.g. 'profile', 'works', 'search')" };
+    const base = (baseUrl || 'https://jujingyi-kikuuu.vercel.app/api/v1').replace(/\/$/, '');
+    const originCheck = sanitizeUrl(base);
     if (!originCheck.safe) {
       return { status: "error", message: `Unsafe API base URL: ${originCheck.reason}` };
     }
-    const allowedOrigins = new Set([
-      'https://jujingyi-kikuuu.vercel.app',
-      ...(process.env.KIKU_API_ALLOWED_ORIGINS || '').split(',').map(value => value.trim()).filter(Boolean)
-    ]);
-    if (!originCheck.url || !allowedOrigins.has(originCheck.url.origin)) {
-      return { status: 'error', message: 'API base origin is not allowlisted.' };
-    }
-    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
-    const target = new URL(`${base}/${endpoint.replace(/^\/+/, '')}`);
-    if (target.origin !== originCheck.url.origin || !target.pathname.startsWith('/api/v1/')) {
-      return { status: 'error', message: 'API endpoint must remain under /api/v1/.' };
-    }
-    if (query) target.searchParams.set('q', query);
-
-    try {
-      const result = await fetchJson(target.href, { timeoutMs: 10000, maxResponseLength: 100000 });
-      if (result.status !== 'success') return result;
-      const json = result.data;
-      const data = json?.data || json;
-      return {
-        status: "success",
-        endpoint: path,
+    const allowedOrigins = new Set([
+      'https://jujingyi-kikuuu.vercel.app',
+      ...(process.env.KIKU_API_ALLOWED_ORIGINS || '').split(',').map(value => value.trim()).filter(Boolean)
+    ]);
+    if (!originCheck.url || !allowedOrigins.has(originCheck.url.origin)) {
+      return { status: 'error', message: 'API base origin is not allowlisted.' };
+    }
+    const path = endpoint.startsWith('/') ? endpoint : `/${endpoint}`;
+    const target = new URL(`${base}/${endpoint.replace(/^\/+/, '')}`);
+    if (target.origin !== originCheck.url.origin || !target.pathname.startsWith('/api/v1/')) {
+      return { status: 'error', message: 'API endpoint must remain under /api/v1/.' };
+    }
+    if (query) target.searchParams.set('q', query);
+
+    try {
+      const result = await fetchJson(target.href, { timeoutMs: 10000, maxResponseLength: 100000 });
+      if (result.status !== 'success') return result;
+      const json = result.data;
+      const data = json?.data || json;
+      return {
+        status: "success",
+        endpoint: path,
         count: Array.isArray(data) ? data.length : undefined,
         data
       };
@@ -1458,7 +2211,7 @@ export const toolHandlers = {
       return {
         status: "error",
         endpoint: path,
-        message: err.name === 'AbortError' ? 'API request timed out' : err.message
+        message: err.name === 'AbortError' ? 'API request timed out' : err.message
       };
     }
   },
@@ -1467,24 +2220,62 @@ export const toolHandlers = {
     return await fetchJson(url, { method, headers, body });
   },
 
+  search_news: async ({ query, maxResults } = {}) => {
+    if (!query) return { status: 'error', message: 'query parameter is required.' };
+    return await searchNews(query, maxResults);
+  },
+
+  fetch_rss: async ({ url, maxItems } = {}) => {
+    return await fetchRssFeed(url, maxItems);
+  },
+
+  search_encyclopedia: async ({ term, language, maxEntries } = {}) => {
+    if (!term) return { status: 'error', message: 'term parameter is required.' };
+    const lang = ['zh', 'th', 'en'].includes(language) ? language : detectLanguage(term);
+    return await searchEncyclopedia(term, lang, maxEntries);
+  },
+
+  search_music_platforms: async ({ term, maxResults } = {}) => {
+    if (!term) return { status: 'error', message: 'term parameter is required.' };
+    return await searchMusicPlatforms(term, maxResults);
+  },
+
+  search_chinese_web: async ({ query, maxResults, site } = {}) => {
+    if (!isCnWebEnabled()) return { status: 'error', gated: true, message: cnWebDisabledMessage('search_chinese_web') };
+    if (!query) return { status: 'error', message: 'query parameter is required.' };
+    return await searchChineseWeb(query, maxResults, { site });
+  },
+
+  search_bilibili: async ({ keyword, maxResults } = {}) => {
+    if (!isCnWebEnabled()) return { status: 'error', gated: true, message: cnWebDisabledMessage('search_bilibili') };
+    if (!keyword) return { status: 'error', message: 'keyword parameter is required.' };
+    return await searchBilibili(keyword, maxResults);
+  },
+
+  search_web_images: async ({ query, maxResults } = {}) => {
+    if (!isCnWebEnabled()) return { status: 'error', gated: true, message: cnWebDisabledMessage('search_web_images') };
+    if (!query) return { status: 'error', message: 'query parameter is required.' };
+    return await searchWebImages(query, maxResults);
+  },
+
   read_local_file: async ({ path: filePath, maxLines = 200 } = {}) => {
     if (!filePath) return { status: 'error', message: 'path parameter is required.' };
     try {
-      const projectRoot = await realpath(process.cwd());
-      const resolved = resolve(projectRoot, filePath);
-      const realResolved = await realpath(resolved);
-      const relativePath = relative(projectRoot, realResolved);
-
-      if (relativePath === '..' || relativePath.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
-        return { status: 'error', message: 'Path must be within the project directory.' };
-      }
-
-      if (/(^|[\\/])\.env(?:\.|$)/i.test(relativePath) || /(^|[\\/])cookies\.txt$/i.test(relativePath) ||
-          /\.(pem|key|p12|pfx)$/i.test(relativePath) || /(^|[\\/])\.(git|npmrc|netrc|ssh)([\\/]|$)/i.test(relativePath)) {
-        return { status: 'error', message: 'Reading this file is not permitted (sensitive file).' };
-      }
-
-      const fileStat = await stat(realResolved);
+      const projectRoot = await realpath(process.cwd());
+      const resolved = resolve(projectRoot, filePath);
+      const realResolved = await realpath(resolved);
+      const relativePath = relative(projectRoot, realResolved);
+
+      if (relativePath === '..' || relativePath.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
+        return { status: 'error', message: 'Path must be within the project directory.' };
+      }
+
+      if (/(^|[\\/])\.env(?:\.|$)/i.test(relativePath) || /(^|[\\/])cookies\.txt$/i.test(relativePath) ||
+          /\.(pem|key|p12|pfx)$/i.test(relativePath) || /(^|[\\/])\.(git|npmrc|netrc|ssh)([\\/]|$)/i.test(relativePath)) {
+        return { status: 'error', message: 'Reading this file is not permitted (sensitive file).' };
+      }
+
+      const fileStat = await stat(realResolved);
       if (!fileStat.isFile()) {
         return { status: 'error', message: `"${filePath}" is not a file.` };
       }
@@ -1493,7 +2284,7 @@ export const toolHandlers = {
         return { status: 'error', message: `File too large (${Math.round(fileStat.size / 1024)}KB). Use maxLines to read a portion.` };
       }
 
-      const content = await readFile(realResolved, 'utf-8');
+      const content = await readFile(realResolved, 'utf-8');
       const lines = content.split('\n');
       const totalLines = lines.length;
       const truncated = totalLines > maxLines;
@@ -1518,14 +2309,14 @@ export const toolHandlers = {
 
   list_directory: async ({ path: dirPath = '.', recursive = false } = {}) => {
     try {
-      const projectRoot = await realpath(process.cwd());
-      const resolved = resolve(projectRoot, dirPath);
-      const realResolved = await realpath(resolved);
-      const relativePath = relative(projectRoot, realResolved);
-
-      if (relativePath === '..' || relativePath.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
-        return { status: 'error', message: 'Path must be within the project directory.' };
-      }
+      const projectRoot = await realpath(process.cwd());
+      const resolved = resolve(projectRoot, dirPath);
+      const realResolved = await realpath(resolved);
+      const relativePath = relative(projectRoot, realResolved);
+
+      if (relativePath === '..' || relativePath.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)) {
+        return { status: 'error', message: 'Path must be within the project directory.' };
+      }
 
       async function listDir(dir, depth = 0) {
         if (depth > (recursive ? 3 : 0)) return [];
@@ -1565,7 +2356,7 @@ export const toolHandlers = {
         return items;
       }
 
-      const items = await listDir(realResolved);
+      const items = await listDir(realResolved);
       return {
         status: 'success',
         path: relativePath || '.',
@@ -1594,7 +2385,7 @@ export const toolHandlers = {
     const awards = Array.isArray(awardsData) ? awardsData : (awardsData?.awards || []);
     const timeline = Array.isArray(timelineData) ? timelineData : (timelineData?.eras || []);
     const mvs = getAllMusicVideos();
-    const gpu = await getGpuMetrics().catch(() => ({ available: false }));
+    const gpu = await getGpuMetrics({ includeShared: false }).catch(() => ({ available: false }));
 
     const debutMatch = profileData.details?.debutDate?.match(/\b(19\d\d|20\d\d)\b/);
     const debutYear = debutMatch ? Number(debutMatch[1]) : 2013;
@@ -1920,6 +2711,127 @@ export const toolHandlers = {
       apiKey: null
     };
   },
+
+  get_entertainment_metrics: async ({ platform, category, query } = {}) => {
+    let platforms = [...platformsCatalog];
+    let benchmarks = [...(artistIndustryMetrics.dramaBenchmarks || [])];
+
+    if (platform && platform !== 'all') {
+      const pId = String(platform).toLowerCase().trim();
+      platforms = platforms.filter(p => p.id.toLowerCase() === pId);
+    }
+
+    if (category && category !== 'all') {
+      const cat = String(category).toLowerCase().trim();
+      platforms = platforms.filter(p => p.category.toLowerCase() === cat);
+    }
+
+    if (query) {
+      const qLower = String(query).toLowerCase().trim();
+      platforms = platforms.filter(p =>
+        p.nameEn.toLowerCase().includes(qLower) ||
+        p.nameCn.includes(qLower) ||
+        (p.nameTh && p.nameTh.toLowerCase().includes(qLower)) ||
+        (p.industryRoleTh && p.industryRoleTh.toLowerCase().includes(qLower)) ||
+        (p.coreMetricsTh && p.coreMetricsTh.some(m => m.toLowerCase().includes(qLower))) ||
+        (p.kikuHighlightsTh && p.kikuHighlightsTh.some(h => h.toLowerCase().includes(qLower)))
+      );
+      benchmarks = benchmarks.filter(b =>
+        b.titleCn.includes(qLower) ||
+        b.titleEn.toLowerCase().includes(qLower) ||
+        (b.titleTh && b.titleTh.toLowerCase().includes(qLower)) ||
+        (b.platform && b.platform.toLowerCase().includes(qLower)) ||
+        (b.significanceTh && b.significanceTh.toLowerCase().includes(qLower))
+      );
+    }
+
+    return {
+      status: "success",
+      totalPlatforms: platforms.length,
+      categoryFilter: category || 'all',
+      platformFilter: platform || 'all',
+      platforms,
+      dramaBenchmarks: benchmarks,
+      artistOverview: artistIndustryMetrics.artist,
+      socialBuzzOverview: artistIndustryMetrics.socialBuzzOverview,
+      message: `Found ${platforms.length} big data platforms across Chinese entertainment analytics.`
+    };
+  },
+
+  get_industry_index: async (args = {}, options = {}) => {
+    return toolHandlers.get_entertainment_metrics(args, options);
+  },
+
+  checkpoint_step: async ({ run_id, step_name, status, summary } = {}, options = {}) => {
+    let memory = options?.agent?.memory || options?.memory;
+    if (!memory) {
+      const { AgentMemory } = await import('./memory.js');
+      memory = new AgentMemory();
+      await memory.load();
+    }
+    const result = await memory.checkpointStep({ runId: run_id, stepName: step_name, status, summary });
+    return {
+      status: "success",
+      message: `Checkpoint recorded for run ${run_id}: step "${step_name}" is ${status}.`,
+      checkpoint: result
+    };
+  },
+
+  record_failure: async ({ run_id, error_trace, recovery_action, tool_name } = {}, options = {}) => {
+    let memory = options?.agent?.memory || options?.memory;
+    if (!memory) {
+      const { AgentMemory } = await import('./memory.js');
+      memory = new AgentMemory();
+      await memory.load();
+    }
+    const result = await memory.recordFailure({ runId: run_id, errorTrace: error_trace, recoveryAction: recovery_action, toolName: tool_name });
+    return {
+      status: "success",
+      message: `Failure recorded for run ${run_id}.`,
+      failure: result
+    };
+  },
+
+  load_active_run: async ({ run_id } = {}, options = {}) => {
+    let memory = options?.agent?.memory || options?.memory;
+    if (!memory) {
+      const { AgentMemory } = await import('./memory.js');
+      memory = new AgentMemory();
+      await memory.load();
+    }
+    const result = await memory.loadActiveRun(run_id);
+    if (!result || !result.exists) {
+      return {
+        status: "not_found",
+        message: `Run "${run_id}" not found in active memory.`
+      };
+    }
+    return {
+      status: "success",
+      run: result
+    };
+  },
+
+  record_dynamic_event: async ({ category, entry, source, trustTier } = {}) => {
+    try {
+      const added = addDynamicEntry(category, {
+        ...(entry || {}),
+        source: source || entry?.source || 'agent_inference',
+        trustTier: trustTier || entry?.trustTier || 2,
+      });
+      globalToolCache.clear();
+      return {
+        status: "success",
+        message: `Successfully recorded dynamic event in category "${category}".`,
+        entry: added
+      };
+    } catch (err) {
+      return {
+        status: "error",
+        message: `Failed to record dynamic event: ${err.message}`
+      };
+    }
+  },
 };
 
 const toolSchemaByName = new Map(
@@ -2002,8 +2914,14 @@ export function prepareToolArguments(toolName, rawArgs = {}) {
     if (!checked.ok) {
       return { safe: false, args: {}, warnings, error: `Argument "${name}" must be ${propertySchema.type || 'valid'}.` };
     }
-    if (propertySchema.enum && !propertySchema.enum.includes(checked.value)) {
-      return { safe: false, args: {}, warnings, error: `Argument "${name}" must be one of: ${propertySchema.enum.join(', ')}.` };
+    if (propertySchema.enum) {
+      const target = String(checked.value).toLowerCase().trim();
+      const matched = propertySchema.enum.find(e => String(e).toLowerCase() === target);
+      if (matched !== undefined) {
+        checked.value = matched;
+      } else {
+        return { safe: false, args: {}, warnings, error: `Argument "${name}" must be one of: ${propertySchema.enum.join(', ')}.` };
+      }
     }
     if (checked.coerced) warnings.push(`Argument "${name}" was converted to ${propertySchema.type}`);
     validated[name] = checked.value;
@@ -2097,3 +3015,46 @@ export async function executeTool(toolName, args = {}, options = {}) {
     };
   }
 }
+
+/**
+ * Authoritative registry of primary tools with domain categorizations and schemas.
+ */
+export const toolsRegistry = {
+  global_search: {
+    domain: 'core',
+    isCore: true,
+    schema: toolsSchema.find(t => t.function?.name === 'global_search')?.function,
+    handler: toolHandlers.global_search,
+  },
+  get_awards: {
+    domain: 'awards',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'get_awards')?.function,
+    handler: toolHandlers.get_awards,
+  },
+  get_gallery_photos: {
+    domain: 'gallery',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'get_gallery_photos')?.function,
+    handler: toolHandlers.get_gallery_photos,
+  },
+  get_quotes: {
+    domain: 'quotes',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'get_quotes')?.function,
+    handler: toolHandlers.get_quotes,
+  },
+  search_discography: {
+    domain: 'discography',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'search_discography')?.function,
+    handler: toolHandlers.search_discography,
+  },
+  search_works: {
+    domain: 'works',
+    isCore: false,
+    schema: toolsSchema.find(t => t.function?.name === 'search_works')?.function,
+    handler: toolHandlers.search_works,
+  },
+};
+