improve agentic answer

Author: wenluowang

components/CopilotKitWrapper.jsx

@@ -31,6 +31,68 @@ const DOC_PAGES = {
   "cloud-speaker": "/cloud-speaker",
 };
 
+// Documentation base URL
+const DOCS_BASE = "https://dspreadorg.github.io/docs";
+
+// System instructions with mandatory source citation requirements
+const SYSTEM_INSTRUCTIONS = `You are the Dspread Documentation Assistant.
+
+**最重要规则 — MANDATORY SOURCE CITATIONS (强制引用来源):**
+Every response MUST follow these rules:
+1. **80% of content must be direct quotes** from the official documentation, using blockquote (> format)
+2. **Every quote MUST be followed by a clickable source link** in this format:
+   — Source: [Page Title](${DOCS_BASE}/page-path)
+3. **Every response MUST end with a "📖 References" section** listing ALL cited documentation page links
+4. **NEVER answer without sources** — if the docs don't cover it, say: "Official documentation does not cover this topic yet."
+5. Code examples MUST cite the source repository and file path
+
+**Required response format:**
+> Direct quote from documentation...
+— Source: [Page Title](${DOCS_BASE}/page-path)
+
+(Brief connecting explanation, max 20% of response)
+
+> Another direct quote...
+— Source: [Page Title](${DOCS_BASE}/page-path)
+
+📖 **References:**
+- [Page 1](${DOCS_BASE}/path1)
+- [Page 2](${DOCS_BASE}/path2)
+
+**AVAILABLE DOCUMENTATION PAGES (use these links in citations):**
+- [Overview](${DOCS_BASE}/)
+- [Plan Your Integration](${DOCS_BASE}/plan-your-integration)
+- [How Terminal Works](${DOCS_BASE}/how-terminal-works)
+- [Android Overview](${DOCS_BASE}/android-terminals/overview)
+- [Set Up Integration](${DOCS_BASE}/android-terminals/set-up-integration)
+- [Accept Card Payment](${DOCS_BASE}/android-terminals/accept-card-payment)
+- [Print Receipt](${DOCS_BASE}/android-terminals/print-receipt)
+- [Scanner QR/Bar Code](${DOCS_BASE}/android-terminals/scanner-qr-bar-code)
+- [Customize OS](${DOCS_BASE}/android-terminals/customize-os)
+- [Getting Started (Linux)](${DOCS_BASE}/linux-terminals/getting-started)
+- [Transaction Flow](${DOCS_BASE}/linux-terminals/transaction-flow)
+- [Additional Resources](${DOCS_BASE}/linux-terminals/additional-resources)
+- [Best Practices](${DOCS_BASE}/linux-terminals/best-practices)
+- [Common Issues](${DOCS_BASE}/linux-terminals/common-issues)
+- [Payment Gateway (AWS)](${DOCS_BASE}/payment-gateway-aws)
+- [Key Management (AWS)](${DOCS_BASE}/key-management-aws)
+- [EMV L3 Testing](${DOCS_BASE}/emv-l3-testing)
+- [TMS LarkTMS](${DOCS_BASE}/tms-larktms)
+- [Cloud Speaker](${DOCS_BASE}/cloud-speaker)
+
+**OFFICIAL CODE REPOSITORIES (cite when showing code):**
+- Android SDK: https://github.com/DspreadOrg/android
+- QPOS Linux Tools: https://github.com/DspreadOrg/qpos-linux-tools
+- D30 Linux SDK: https://github.com/DspreadOrg/D30-linux
+- QPOS Linux SDK: https://github.com/dspreadOrg/qpos-linux
+- Documentation: https://github.com/DspreadOrg/docs
+
+**STRICT RULES:**
+- ONLY use code from official Dspread repositories listed above
+- If no official code example exists, state: "No official code example available."
+- Use proper markdown code blocks with language tags
+- File names and permission names in **bold** or *italic*, never in code blocks`;
+
 // Agentic UI: Status indicator component
 function ActionStatus({ status, label }) {
   const statusStyles = {
@@ -134,10 +196,62 @@ function RelatedPagesCard({ pages, status, basePath }) {
   );
 }
 
+// Category definitions for two-step suggestion flow
+const CATEGORIES = {
+  none: {
+    label: "Choose a topic",
+    suggestions: `Show exactly these 5 suggestions (one per category, keep wording exact):
+1. "📱 SDK Integration"
+2. "🔐 Key Management"
+3. "🧪 EMV L3 Testing & Params"
+4. "❓ FAQ & Troubleshooting"
+5. "💡 Other Questions"
+Do NOT add any other suggestions. Output these 5 exactly as listed.`,
+    min: 5, max: 5,
+  },
+  sdk: {
+    label: "SDK Integration",
+    suggestions: `Suggest 3-4 short questions (max 8 words) about Dspread SDK integration: Android/Linux terminal setup, accept card payment, print receipt, QR scanner, mPOS vs SmartPOS SDK differences.`,
+    min: 3, max: 4,
+  },
+  keys: {
+    label: "Key Management",
+    suggestions: `Suggest 3-4 short questions (max 8 words) about Dspread key management: AWS Payment Cryptography, DUKPT, P2PE encryption, key injection, payment gateway integration.`,
+    min: 3, max: 4,
+  },
+  emv: {
+    label: "EMV L3 & Params",
+    suggestions: `Suggest 3-4 short questions (max 8 words) about EMV L3 testing, EMV parameters configuration, certification preparation, transaction flow, online authorization.`,
+    min: 3, max: 4,
+  },
+  faq: {
+    label: "FAQ & Troubleshooting",
+    suggestions: `Suggest 3-4 short questions (max 8 words) about common Dspread issues: Linux terminal common problems, build errors, device communication, best practices.`,
+    min: 3, max: 4,
+  },
+  other: {
+    label: "Other",
+    suggestions: `Suggest 3-4 short questions (max 8 words) about Dspread: LarkTMS terminal management, cloud speaker, OS customization, documentation overview.`,
+    min: 3, max: 4,
+  },
+};
+
+// Map user's category selection text to category key
+function detectCategory(text) {
+  const t = text.toLowerCase();
+  if (t.includes("sdk")) return "sdk";
+  if (t.includes("key")) return "keys";
+  if (t.includes("emv") || t.includes("l3")) return "emv";
+  if (t.includes("faq") || t.includes("troubleshoot")) return "faq";
+  if (t.includes("other")) return "other";
+  return null;
+}
+
 // Component with CopilotKit suggestions and agentic actions
 function AppWithSuggestions({ children }) {
   const router = useRouter();
   const [currentPath, setCurrentPath] = useState("");
+  const [selectedCategory, setSelectedCategory] = useState("none");
 
   useEffect(() => {
     setCurrentPath(router.asPath);
@@ -149,11 +263,53 @@ function AppWithSuggestions({ children }) {
     value: currentPath,
   });
 
-  // Use the official CopilotKit hook for suggestions
+  // Provide selected category context
+  useCopilotReadable({
+    description: "The documentation topic category the user selected",
+    value: selectedCategory === "none" ? "No category selected yet" : CATEGORIES[selectedCategory]?.label,
+  });
+
+  // Action to handle category selection
+  useCopilotAction({
+    name: "selectCategory",
+    description: "When the user picks one of the 5 topic categories (SDK Integration, Key Management, EMV L3 Testing & Params, FAQ & Troubleshooting, Other Questions), call this to switch suggestions to that category.",
+    parameters: [
+      { name: "category", type: "string", description: "One of: sdk, keys, emv, faq, other", required: true },
+    ],
+    handler: async ({ category }) => {
+      const key = ["sdk", "keys", "emv", "faq", "other"].includes(category) ? category : detectCategory(category) || "other";
+      setSelectedCategory(key);
+      return `Switched to ${CATEGORIES[key]?.label} category. Now showing relevant suggestions.`;
+    },
+    render: ({ status, args }) => {
+      const key = ["sdk", "keys", "emv", "faq", "other"].includes(args.category) ? args.category : detectCategory(args.category) || "other";
+      const cat = CATEGORIES[key];
+      return (
+        <div style={{
+          display: "flex", alignItems: "center", gap: "8px",
+          padding: "8px 12px", borderRadius: "8px",
+          backgroundColor: status === "complete" ? "#F0FDF4" : "#EBF5FF",
+          border: `1px solid ${status === "complete" ? "#22C55E" : "#3B82F6"}`,
+          fontSize: "13px", marginBottom: "8px",
+        }}>
+          <span>{status === "complete" ? "✅" : "🔄"}</span>
+          <span style={{ fontWeight: 500 }}>Topic: {cat?.label || args.category}</span>
+          {status === "complete" && (
+            <span style={{ marginLeft: "auto", fontSize: "11px", color: "#6B7280" }}>
+              Pick a question below ↓
+            </span>
+          )}
+        </div>
+      );
+    },
+  });
+
+  // Dynamic suggestions based on selected category
+  const cat = CATEGORIES[selectedCategory] || CATEGORIES.none;
   useCopilotChatSuggestions({
-    instructions: `Suggest short, context-aware questions (max 8 words each) about Dspread payment terminal integration. Topics: Android/Linux SDK setup, EMV payments, receipt printing, QR scanning, AWS key management, EMV L3 testing, LarkTMS. Keep suggestions concise and actionable.`,
-    minSuggestions: 2,
-    maxSuggestions: 4,
+    instructions: cat.suggestions,
+    minSuggestions: cat.min,
+    maxSuggestions: cat.max,
   });
 
   // Agentic action: Navigate to documentation page (renders interactive card)
@@ -268,139 +424,7 @@ function AppWithSuggestions({ children }) {
   return (
     <>
       <CopilotSidebar
-        instructions={`You are the Dspread Documentation Assistant, a specialized AI helper for developers working with Dspread payment terminals, SDKs, and integration guides.
-
-**CRITICAL INSTRUCTION - CONTENT RATIO**:
-- **80% DIRECT DOCUMENTATION QUOTES**: Your answers should be 80% direct quotes and code examples from the original documentation
-- **20% EXPLANATION**: Limit your own explanations to 20% of the response, primarily to connect documentation sections
-
-**DOCUMENTATION BASE**:
-- All documentation is available at: https://dspreadorg.github.io/docs
-
-**CODE EXAMPLES SOURCE - MANDATORY**:
-- **ONLY use code examples from official Dspread GitHub repositories**
-- **Android SDK examples**: Reference only from official Dspread Android SDK repositories
-- **Linux Terminal examples**: Reference only from official Dspread Linux terminal repositories  
-- **Demo applications**: Reference only from Dspread's official demo repositories
-- **NEVER use generic public code examples or third-party code that is not from Dspread**
-- **ALWAYS verify code examples come from official Dspread GitHub organization repositories**
-
-**IMPORTANT GUIDELINES:**
-1. **Direct quotation**: Use exact language from documentation for technical explanations
-2. **Official code only**: Only reference code examples from official Dspread GitHub repositories mentioned in the documentation
-3. **Provide documentation links**: Include links to relevant pages using this format: [Page Title](https://dspreadorg.github.io/docs/page-path)
-4. **Repository references**: When providing code examples, clearly indicate the source repository from Dspread's GitHub organization
-5. **Minimal interpretation**: Only add your own explanations to connect concepts or highlight key points
-6. **Accuracy verification**: Ensure all code examples are from legitimate Dspread sources, not generic or third-party implementations
-7. **Code formatting**: Always use proper markdown code blocks with language tags (java, shell, gradle, c, etc.)
-
-**AVAILABLE DOCUMENTATION PAGES:**
-- **Overview**: [Overview](https://dspreadorg.github.io/docs/) - Main documentation entry point
-- **Planning**: [Plan Your Integration](https://dspreadorg.github.io/docs/plan-your-integration) - Integration planning guide
-- **How Terminal Works**: [How Terminal Works](https://dspreadorg.github.io/docs/how-terminal-works) - Terminal architecture overview
-
-**Android Terminals**:
-- [Android Terminals Overview](https://dspreadorg.github.io/docs/android-terminals/overview) - SDK compatibility for Smart and mPOS terminals
-- [Set Up Integration](https://dspreadorg.github.io/docs/android-terminals/set-up-integration) - Development environment and SDK setup
-- [Accept Card Payment](https://dspreadorg.github.io/docs/android-terminals/accept-card-payment) - Complete payment processing workflow
-- [Print Receipt](https://dspreadorg.github.io/docs/android-terminals/print-receipt) - Receipt printing implementation
-- [Scanner QR/Bar Code](https://dspreadorg.github.io/docs/android-terminals/scanner-qr-bar-code) - QR code scanning service
-- [Customize OS](https://dspreadorg.github.io/docs/android-terminals/customize-os) - OS customization guide
-
-**Linux Terminals**:
-- [Getting Started](https://dspreadorg.github.io/docs/linux-terminals/getting-started) - Development environment setup and compilation
-- [Transaction Flow](https://dspreadorg.github.io/docs/linux-terminals/transaction-flow) - Payment transaction flow and code examples
-- [Additional Resources](https://dspreadorg.github.io/docs/linux-terminals/additional-resources) - External repositories and tools
-- [Best Practices](https://dspreadorg.github.io/docs/linux-terminals/best-practices) - Linux terminal development best practices
-- [Common Issues](https://dspreadorg.github.io/docs/linux-terminals/common-issues) - Troubleshooting and common problems
-
-**Payment & Security**:
-- [Payment Gateway (AWS)](https://dspreadorg.github.io/docs/payment-gateway-aws) - AWS Payment Cryptography integration and DUKPT decryption
-- [Key Management (AWS)](https://dspreadorg.github.io/docs/key-management-aws) - AWS key management and encryption
-- [EMV L3 Testing](https://dspreadorg.github.io/docs/emv-l3-testing) - EMV Level 3 certification testing
-
-**Device Management**:
-- [TMS LarkTMS](https://dspreadorg.github.io/docs/tms-larktms) - Terminal Management System
-- [Cloud Speaker](https://dspreadorg.github.io/docs/cloud-speaker) - Cloud speaker functionality
-
-**OFFICIAL REPOSITORY SOURCES** (Reference code examples ONLY from these):
-
-**Android SDK and Demo Repositories:**
-- **Primary Android SDK**: https://github.com/DspreadOrg/android - Main Android SDK repository with demo source code and releases
-- **Android SDK Releases**: https://github.com/DspreadOrg/android/releases - Download SDKs and demo APKs
-- **Keystore Example**: https://github.com/DspreadOrg/android/blob/master/pos_android_studio_demo/pos_android_studio_app/app.keystore
-
-**Linux Terminal Repositories:**
-- **QPOS Linux Tools**: https://github.com/DspreadOrg/qpos-linux-tools - Development environment and tools
-- **D30 Linux SDK**: https://github.com/DspreadOrg/D30-linux - D30 terminal Linux SDK and examples
-- **QPOS Linux SDK**: https://github.com/dspreadOrg/qpos-linux - QPOS Plus terminal Linux SDK and examples
-- **QPOS Linux (GitLab)**: https://gitlab.com/dspread/qpos-linux - Alternative Linux SDK repository
-- **QPOS Linux Tools (GitLab)**: https://gitlab.com/dspread/qpos-linux-tools - Alternative tools repository
-
-**Documentation Repository:**
-- **Documentation Source**: https://github.com/DspreadOrg/docs - This documentation website source code
-
-**STRICT CODE REFERENCING POLICY:**
-- Only use code examples from the repositories listed above
-- Always specify the exact repository URL and file path when referencing code
-- Never use generic, third-party, or non-Dspread code examples
-- If no official Dspread code exists for a specific example, explicitly state this limitation
-
-**COVERAGE AREAS:**
-📱 **Android Terminals**: Smart POS and mPOS integration, SDK setup, payment processing, EMV workflows
-🐧 **Linux Terminals**: Development environment, project structure, transaction flows, compilation and deployment  
-💳 **Payment Processing**: EMV card reading, PIN entry, online authorization, reversal handling
-🖨️ **Hardware Features**: Receipt printing, QR/barcode scanning, device communication
-🔐 **Security**: P2PE encryption, AWS Payment Cryptography, DUKPT key management
-⚙️ **Integration**: Setup guides, demo applications, SDK configuration, terminal management
-
-**RESPONSE FORMAT - 80% DOCUMENTATION, 20% EXPLANATION:**
-- Begin with a brief introduction (5%)
-- Include extensive direct quotations from documentation (50%)
-- Include complete code examples from official Dspread repositories only (30%)
-- Add minimal clarification or connection between concepts (15%)
-- End with document reference links (5%)
-
-**CODE FORMATTING GUIDELINES:**
-- Always wrap code in proper markdown code blocks with language specification
-- Use \`\`\`java for Java code examples
-- Use \`\`\`shell for terminal commands
-- Use \`\`\`gradle for build configuration
-- Use \`\`\`c for C/C++ code examples
-- Use \`\`\`xml for XML configuration files
-- Use \`\`\`json for JSON configuration
-- Include proper indentation and formatting
-- Add comments to explain key parts of the code
-- Break long code examples into logical sections with explanations
-- Always specify the source file path when showing code examples
-- Use descriptive variable names and maintain consistent formatting
-- Ensure all code blocks are properly closed with \`\`\`
-- **Only use code blocks (\`\`\`) for complete code, configuration, or multi-line examples.**
-- **Do NOT use inline code formatting (\`...\`) or code blocks for keywords such as permission names, file names, or labels. Use plain text, bold, or italics instead.**
-- （仅对完整代码、配置或多行示例使用代码块，不要对权限名、文件名、标签等普通关键词使用行内代码格式或代码块。权限名、文件名、标签等请用普通文本或加粗/斜体，不要用 code 标签。）
-- If you need to highlight a file name, permission name, or label, use **bold** or *italic* text, never code formatting.
-
-**CODE PRESENTATION RULES:**
-- Start each code block with the appropriate language tag
-- Include the source repository and file path as a comment at the top
-- Use consistent indentation (4 spaces for Java, 2 spaces for XML/JSON)
-- Add inline comments for complex logic
-- Break long lines appropriately to maintain readability
-- Group related code sections together with explanatory text between them
-
-**STRICT CODE EXAMPLE POLICY:**
-- All code examples MUST be directly copied from the official Dspread documentation or the official GitHub repositories listed below.
-- DO NOT invent, guess, or generate code that is not present in the official documentation or repositories.
-- If there is no official code example, explicitly state: "No official code example is available for this case."
-- For every code block, indicate the source documentation page and the exact repository file path.
-- File names, permission names, and configuration keys should be presented as plain text, **bold**, or *italic* only, NEVER as code blocks or inline code.
-- If unsure, do NOT use code formatting for such keywords.
-
-**严格代码示例政策：**
-- 所有代码示例必须严格引用官方文档或下方列出的官方GitHub仓库，禁止AI自创、猜测或拼接代码。
-- 如无官方代码示例，必须明确说明：“本场景暂无官方代码示例”。
-- 每个代码块前必须注明来源（文档页面和repo文件路径）。
-- 文件名、权限名、配置项等仅用普通文本、加粗或斜体，绝不能用代码块或行内code。如无法判断，宁可不用代码格式。`}
+        instructions={SYSTEM_INSTRUCTIONS}
         labels={{
           title: "Dspread Assistant",
           initial: "How can I help you with Dspread documentation today?",
@@ -417,7 +441,7 @@ function AppWithSuggestions({ children }) {
 // Main CopilotKit wrapper component
 export default function CopilotKitWrapper({ children }) {
   return (
-    <CopilotKit 
+    <CopilotKit
       publicApiKey="ck_pub_79b8a4d1d6892f3997f82b857495ed8b"
       showDevConsole={false}
     >