flutter-pro-max-cli 1.0.2 → 2.1.0

package/README.md

@@ -47,31 +47,78 @@ For CI/CD or automated setups, you can specify the assistant type directly:
 # Install for a specific assistant
 flutter-pro-max init --ai claude
 flutter-pro-max init --ai cursor
+flutter-pro-max init --ai antigravity
 
 # Install for all supported assistants
 flutter-pro-max init --ai all
 ```
 
+### Other Commands
+
+```bash
+# List available versions from GitHub releases
+flutter-pro-max versions
+
+# Update to the latest version
+flutter-pro-max update
+flutter-pro-max update --ai claude
+```
+
 ---
 
 ## 🤖 Supported AI Assistants
 
 This CLI bridges the gap between the Flutter Pro Max knowledge base and your development tools:
 
-| Assistant | Type Flag | Installation Path |
-|-----------|-----------|-------------------|
-| **Claude Code** | `claude` | `.claude/skills/` |
-| **Cursor** | `cursor` | `.cursor/commands/` |
-| **Windsurf** | `windsurf` | `.windsurf/workflows/` |
-| **Antigravity** | `antigravity` | `.agent/workflows/` |
-| **Trae** | `trae` | `.trae/skills/` |
-| **Gemini CLI** | `gemini` | `.gemini/skills/` |
-| **GitHub Copilot** | `copilot` | `.github/prompts/` |
-| **RooCode** | `roocode` | `.roo/commands/` |
-| **Kiro** | `kiro` | `.kiro/steering/` |
-| **Qoder** | `qoder` | `.qoder/rules/` |
-| **CodeBuddy** | `codebuddy` | `.codebuddy/commands/` |
-| **Codex** | `codex` | `.codex/skills/` |
+| Assistant | Type Flag | Install Type | Structure |
+|-----------|-----------|--------------|-----------|
+| **Claude Code** | `claude` | Full | `.claude/skills/flutter-pro-max/` |
+| **Codex CLI** | `codex` | Full | `.codex/skills/flutter-pro-max/` |
+| **Continue** | `continue` | Full | `.continue/skills/flutter-pro-max/` |
+| **Antigravity** | `antigravity` | Full | `.agent/skills/flutter-pro-max/` |
+| **Cursor** | `cursor` | Reference | `.cursor/commands/` + `.shared/` |
+| **Windsurf** | `windsurf` | Reference | `.windsurf/workflows/` + `.shared/` |
+| **GitHub Copilot** | `copilot` | Reference | `.github/prompts/` + `.shared/` |
+| **Kiro** | `kiro` | Reference | `.kiro/skills/` + `.shared/` |
+| **RooCode** | `roocode` | Reference | `.roo/commands/` + `.shared/` |
+| **Qodo/Qoder** | `qoder` | Reference | `.qodo/skills/` + `.shared/` |
+| **Gemini CLI** | `gemini` | Reference | `.gemini/skills/` + `.shared/` |
+| **Trae** | `trae` | Reference | `.trae/skills/` + `.shared/` |
+| **CodeBuddy** | `codebuddy` | Reference | `.codebuddy/skills/` + `.shared/` |
+| **OpenCode** | `opencode` | Reference | `.opencode/skills/` + `.shared/` |
+
+**Install Types:**
+- **Full**: Data và scripts nằm trong skill folder (standalone, ~500KB)
+- **Reference**: Skill file trỏ đến `.shared/` folder chung (tiết kiệm dung lượng khi dùng nhiều assistants)
+
+---
+
+## 📊 What Gets Installed
+
+### Data Files (17 domains)
+| Domain | File | Description |
+|--------|------|-------------|
+| Widgets | `widget.csv` | 65+ Flutter widgets |
+| Packages | `package.csv` | 100+ packages với alternatives |
+| Patterns | `patterns.csv` | 110+ design patterns |
+| Architecture | `architect.csv` | Architecture layers |
+| Performance | `flutter-performance.csv` | 35 optimization patterns |
+| Accessibility | `mobile-accessibility.csv` | 35 accessibility patterns |
+| UI Reasoning | `ui-reasoning.csv` | 35 app category decisions |
+| Colors | `colors.csv` | 50+ color palettes |
+| Typography | `typography.csv` | 40+ font pairings |
+| Styles | `styles.csv` | 60+ UI styles |
+| UX | `ux-guidelines.csv` | 50+ UX rules |
+| Icons | `icons.csv` | 100+ icon recommendations |
+| Landing | `landing.csv` | 30+ landing patterns |
+| Products | `products.csv` | 40+ product recommendations |
+| Prompts | `prompts.csv` | 30+ AI prompts |
+| Charts | `charts.csv` | 20+ chart types |
+| Naming | `name_convention.csv` | Naming conventions |
+
+### Search Scripts
+- `search.py` - BM25 search CLI
+- `core.py` - Search engine core
 
 ---
 
@@ -88,8 +135,42 @@ npm install
 # Build the project
 npm run build
 
-# Run locally in development mode
-npm run dev
+# Run locally
+node dist/index.js init --ai claude
+
+# Test search
+node dist/index.js init --ai claude
+cd .claude/skills/flutter-pro-max
+python3 scripts/search.py "ListView" --domain widget --top 3
+```
+
+---
+
+## 📁 Project Structure
+
+```
+cli/
+├── src/
+│   ├── index.ts              # CLI entry point
+│   ├── commands/
+│   │   ├── init.ts           # Install command
+│   │   ├── versions.ts       # List versions
+│   │   └── update.ts         # Update command
+│   ├── types/
+│   │   └── index.ts          # TypeScript types
+│   └── utils/
+│       ├── detect.ts         # AI type detection
+│       ├── github.ts         # GitHub API client
+│       ├── logger.ts         # Console logger
+│       └── template.ts       # Template renderer
+├── assets/
+│   ├── data/                 # 17 CSV knowledge files
+│   ├── scripts/              # Python search scripts
+│   └── templates/
+│       ├── base/             # Markdown templates
+│       └── platforms/        # 14 platform JSON configs
+├── package.json
+└── tsconfig.json
 ```
 
 ---
@@ -99,6 +180,18 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
+## 📝 Changelog
+
+### v2.1.0 (2026-01-27)
+- **Type Safety**: Full Python type hints cho Pylance strict mode
+- **Python 3.10+**: Minimum Python version updated
+- **Code Quality**: Xóa unused imports, fix linter warnings
+
+### v2.0.0
+- Phiên bản đầu tiên với 14 AI assistant support
+
+---
+
 <div align="center">
 
 **Streamline your Flutter development with AI-powered architectural intelligence.**

package/assets/data/flutter-performance.csv

@@ -0,0 +1,36 @@
+No,Category,Issue,Keywords,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
+1,Build Optimization,Const Constructors,const widget rebuild optimization,Sử dụng const constructor để tránh rebuild widget không cần thiết,"Thêm const cho widget tĩnh","Tạo widget mới mỗi lần build","const SizedBox(height: 16)","SizedBox(height: 16)",High
+2,Build Optimization,Widget Extraction,extract widget method rebuild,Tách widget thành StatelessWidget riêng thay vì dùng method để tối ưu rebuild,"Tách thành widget class riêng","Dùng method trả về widget","class MyButton extends StatelessWidget { ... }","Widget _buildButton() { return Container(...); }",Critical
+3,Build Optimization,RepaintBoundary,repaint boundary canvas custom,Bọc widget có animation phức tạp trong RepaintBoundary để isolate vùng repaint,"Dùng RepaintBoundary cho animation phức tạp","Để toàn bộ subtree repaint cùng nhau","RepaintBoundary(child: AnimatedWidget())","AnimatedWidget() // không có boundary",High
+4,Build Optimization,Builder Pattern,builder lazy build,Sử dụng Builder widgets (ListView.builder) để lazy-load thay vì tạo tất cả widget cùng lúc,"Dùng .builder constructors","Truyền list children trực tiếp","ListView.builder(itemBuilder: (_, i) => Item(i))","ListView(children: items.map((i) => Item(i)).toList())",Critical
+5,State Management,Selective Listening,select watch notifier rebuild,Chỉ watch những phần state cần thiết thay vì toàn bộ object,"Dùng select() để lọc state","Watch toàn bộ object","ref.watch(userProvider.select((u) => u.name))","ref.watch(userProvider)",High
+6,State Management,Late Provider Init,lazy init provider notifier,Không khởi tạo provider/state nặng ngay từ đầu,"Dùng autoDispose và lazy init","Khởi tạo tất cả state khi app start","@riverpod class Heavy extends _$Heavy { late final _data; }","final heavy = StateProvider((_) => expensiveInit())",Medium
+7,State Management,Avoid Unnecessary Notify,notify state equal check,Kiểm tra giá trị mới khác giá trị cũ trước khi notify listeners,"So sánh trước khi update","Notify mỗi lần set value","if (state != newValue) state = newValue","state = newValue // luôn notify",Medium
+8,Image & Asset,Image Caching,cache image memory network,Sử dụng cached_network_image thay vì Image.network cho danh sách,"Dùng CachedNetworkImage","Dùng Image.network trong list","CachedNetworkImage(imageUrl: url)","Image.network(url)",Critical
+9,Image & Asset,Image Resolution,resolution precache asset,Precache và sử dụng đúng resolution cho asset images,"Dùng ResolutionAwareAssetBundle","Load ảnh resolution cao không cần thiết","precacheImage(AssetImage('img.png'), context)","Image.asset('high_res.png') // 4K cho thumbnail",Medium
+10,Image & Asset,Memory Image Dispose,dispose controller animation,Dispose ImageProvider và AnimationController đúng cách để tránh memory leak,"Dispose trong dispose()","Quên dispose controllers","@override void dispose() { _controller.dispose(); super.dispose(); }","// Không có dispose()",Critical
+11,List & Scroll,Virtualization,lazy load list viewport,Sử dụng ListView.builder để chỉ render items trong viewport,"Dùng builder cho list > 20 items","Render tất cả items cùng lúc","ListView.builder(itemCount: 1000, ...)","ListView(children: List.generate(1000, ...))",Critical
+12,List & Scroll,ShrinkWrap Avoid,shrinkwrap scroll nested,Tránh sử dụng shrinkWrap: true cho list dài vì tắt lazy loading,"Dùng Expanded hoặc Flexible","Dùng shrinkWrap: true","Expanded(child: ListView.builder(...))","ListView(shrinkWrap: true, children: longList)",Critical
+13,List & Scroll,Item Extent,itemextent cacheextent scroll,Cung cấp itemExtent khi items có cùng chiều cao để tối ưu scroll performance,"Set itemExtent cho uniform height","Để Flutter tính toán mỗi item","ListView.builder(itemExtent: 72, ...)","ListView.builder(...) // không có itemExtent",Medium
+14,List & Scroll,Keep Alive Careful,keepalive memory tab,Cân nhắc khi dùng AutomaticKeepAliveClientMixin vì giữ widget trong bộ nhớ,"Chỉ dùng cho tabs quan trọng","Keep alive tất cả tabs","// Chỉ keep alive tab có data quan trọng","// Keep alive tất cả tabs trong TabBarView",Medium
+15,Animation,Animation Controller Dispose,dispose animation leak,Luôn dispose AnimationController để tránh memory leak và ticker leak,"Dispose trong dispose() method","Quên dispose controller","@override void dispose() { _animController.dispose(); super.dispose(); }","// Không dispose AnimationController",Critical
+16,Animation,Implicit Over Explicit,implicit animated simple,Ưu tiên implicit animations (AnimatedContainer) cho hiệu ứng đơn giản,"Dùng AnimatedFoo widgets","Dùng AnimationController cho mọi thứ","AnimatedContainer(duration: Duration(milliseconds: 300), ...)","AnimationController + AnimatedBuilder cho color change",Medium
+17,Animation,TweenAnimationBuilder,tween animation builder stateless,Dùng TweenAnimationBuilder cho animation không cần control manual,"Dùng TweenAnimationBuilder","Tạo StatefulWidget chỉ cho animation đơn giản","TweenAnimationBuilder<double>(tween: Tween(begin: 0, end: 1), ...)","StatefulWidget + AnimationController cho fade in",Medium
+18,Animation,Animation Curve,curve ease animation timing,Sử dụng Curves phù hợp thay vì linear để animation tự nhiên hơn,"Dùng Curves.easeOutCubic","Dùng Curves.linear cho mọi thứ","curve: Curves.easeOutCubic","curve: Curves.linear",Low
+19,Async & Network,Isolate Heavy Work,isolate compute background,Chạy JSON parsing lớn và tính toán nặng trong Isolate/compute(),"Dùng compute() cho work > 16ms","Parse JSON lớn trên main thread","final data = await compute(parseJson, response)","final data = jsonDecode(response) // 100MB JSON",High
+20,Async & Network,Cancel Async Operations,cancel async dispose,Hủy Future/Stream subscriptions khi widget dispose,"Cancel trong dispose()","Để async operations chạy tiếp sau dispose","subscription?.cancel(); // trong dispose","// Không cancel, gây setState after dispose",High
+21,Async & Network,Debounce Search,debounce timer search input,Debounce search input để tránh gọi API quá nhiều,"Timer 300-500ms trước khi search","Gọi API mỗi keystroke","Timer(Duration(milliseconds: 500), () => search(query))","onChanged: (q) => search(q) // gọi mỗi keystroke",High
+22,Async & Network,Connection Check,connectivity network offline,Check kết nối mạng trước khi gọi API heavy,"Check connectivity trước","Luôn gọi API rồi xử lý lỗi sau","if (await Connectivity().checkConnectivity() != none) { ... }","try { await api.call() } catch (e) { // network error }",Medium
+23,Layout,Avoid Nested Layouts,nested row column layout,Tránh nested Row/Column quá sâu, sử dụng CustomMultiChildLayout nếu cần,"Flatten layout structure","Nested 5+ level Row/Column","Wrap, Table, CustomMultiChildLayout","Row(Column(Row(Column(Row(...))))))",Medium
+24,Layout,Intrinsic Dimension Avoid,intrinsic width height expensive,Tránh IntrinsicHeight/IntrinsicWidth vì gây double layout pass,"Dùng constraints hoặc fixed size","Dùng IntrinsicHeight cho list items","ConstrainedBox hoặc AspectRatio","IntrinsicHeight(child: Row(...))",High
+25,Layout,Clip Behavior,clip antiAlias expensive,Sử dụng Clip.hardEdge thay vì antiAlias nếu không cần smooth edges,"Clip.hardEdge hoặc Clip.none","Clip.antiAlias everywhere","clipBehavior: Clip.hardEdge","clipBehavior: Clip.antiAlias // mọi Container",Low
+26,Text & Font,Font Preload,font precache asset,Preload custom fonts khi app start để tránh flash of unstyled text,"Preload fonts trong main()","Để font load lazy","await FontLoader('MyFont').load()","// Font load khi widget đầu tiên dùng nó",Medium
+27,Text & Font,Text Scale Factor,textscale accessibility responsive,Hỗ trợ textScaleFactor cho accessibility thay vì hardcode font size,"Dùng Theme.of(context).textTheme","Hardcode fontSize everywhere","Text('Hi', style: Theme.of(context).textTheme.bodyLarge)","Text('Hi', style: TextStyle(fontSize: 14))",Medium
+28,Platform,Platform Channel Batch,platform channel native batch,Batch nhiều platform channel calls thành một để giảm overhead,"Batch calls thành single method","Gọi nhiều method channel riêng lẻ","channel.invokeMethod('batchOperation', [data1, data2])","channel.invokeMethod('op1'); channel.invokeMethod('op2');",Medium
+29,Platform,Profile vs Debug,profile mode release debug,Test performance trong Profile mode, không phải Debug mode,"Flutter run --profile","Đánh giá perf trong debug mode","flutter run --profile --target=lib/main.dart","flutter run // debug mode chậm hơn nhiều",Critical
+30,Platform,Skia vs Impeller,impeller ios android render,Sử dụng Impeller trên iOS (default) và test trên Android cho performance tốt hơn,"Enable Impeller nếu chưa","Disable Impeller không lý do","flutter run --enable-impeller","--no-enable-impeller // fallback Skia",Medium
+31,Startup,Deferred Loading,deferred loading split,Sử dụng deferred loading để giảm initial bundle size,"Deferred import cho features phụ","Load tất cả code lúc startup","import 'heavy.dart' deferred as heavy; await heavy.loadLibrary()","import 'heavy.dart' // load lúc app start",High
+32,Startup,Lazy Initialization,lazy init singleton service,Khởi tạo services lazy thay vì tất cả trong main(),"Lazy init với getter","Init tất cả trong main()","static final instance = Lazy(() => HeavyService())","void main() { HeavyService.init(); ... }",High
+33,DevTools,Timeline Profiling,devtools timeline frame,Sử dụng Flutter DevTools Timeline để phát hiện jank frames,"Profile với DevTools Timeline","Đoán nguyên nhân jank","flutter pub global run devtools","// Không dùng profiling tools",Medium
+34,DevTools,Widget Inspector,inspector rebuild debug,Dùng Widget Inspector để detect unnecessary rebuilds,"Check rebuild indicators","Đoán widget nào rebuild","DevTools > Flutter Inspector > Track widget rebuilds","// Không biết widget nào rebuild nhiều",Medium
+35,Memory,Dispose Pattern,dispose stream subscription,Implement dispose pattern đúng cách cho tất cả resources,"Dispose tất cả controllers, subscriptions","Quên dispose một số resources","streams.forEach((s) => s.cancel()); controllers.forEach((c) => c.dispose());","// Dispose một số, quên một số",Critical

package/assets/data/mobile-accessibility.csv

@@ -0,0 +1,36 @@
+No,Category,Issue,Keywords,Platform,Description,Do,Don't,Code Example Good,Code Example Bad,Severity
+1,Semantics,Screen Reader Labels,semantics label button accessibility,Flutter,Tất cả interactive widgets cần Semantics label cho screen reader,"Thêm Semantics hoặc semanticLabel","Button không có label","Semantics(label: 'Đóng', child: IconButton(...))","IconButton(icon: Icon(Icons.close), onPressed: ...)",Critical
+2,Semantics,Exclude Decorative,excludesemantics decorative icon,Flutter,Ẩn decorative icons khỏi screen reader,"Dùng excludeFromSemantics: true","Decorative icon được đọc lên","Icon(Icons.star, semanticLabel: null) // hoặc ExcludeSemantics","Icon(Icons.star) // đọc là 'star'",Medium
+3,Semantics,Image Descriptions,image semantic description alt,Flutter,Mô tả ảnh cho người dùng khiếm thị,"Thêm semanticLabel cho Image","Image không có description","Image.asset('logo.png', semanticLabel: 'Logo công ty ABC')","Image.asset('logo.png')",High
+4,Touch Target,Minimum Size,touch target 48 44 size,Flutter,Touch target tối thiểu 48x48 dp (Material) hoặc 44x44 pt (iOS),"Set minimum size 48x48","Nút quá nhỏ","SizedBox(width: 48, height: 48, child: IconButton(...))","IconButton(...) // 24x24 mặc định",Critical
+5,Touch Target,Hit Test Extension,gesture hitslop padding,Flutter,Mở rộng vùng tap không ảnh hưởng visual size,"Dùng padding hoặc MaterialTapTargetSize","Chỉ dựa vào icon size","GestureDetector(behavior: HitTestBehavior.opaque, child: Padding(...))","Icon(size: 16) // quá nhỏ để tap",High
+6,Touch Target,Spacing Between Targets,spacing touch targets,Flutter,Khoảng cách tối thiểu 8dp giữa các touch targets,"Thêm spacing >= 8dp","Các button sát nhau","Row(children: [btn1, SizedBox(width: 8), btn2])","Row(children: [btn1, btn2]) // sát nhau",Medium
+7,Color Contrast,Text Contrast Ratio,contrast ratio wcag text,Flutter,Tỉ lệ contrast tối thiểu 4.5:1 cho text thường và 3:1 cho large text,"Check contrast ratio trước khi chọn màu","Text nhạt trên nền sáng","Text(style: TextStyle(color: Color(0xFF1A1A1A))) // trên nền trắng","Text(style: TextStyle(color: Colors.grey[400])) // trên nền trắng",Critical
+8,Color Contrast,Non-Text Contrast,contrast icon button visual,Flutter,UI elements (icons buttons borders) cần contrast tối thiểu 3:1,"Đảm bảo icon/border đủ contrast","Icon quá nhạt","Icon(Icons.add, color: Color(0xFF333333))","Icon(Icons.add, color: Colors.grey[300])",High
+9,Color Contrast,Dark Mode Support,dark mode theme contrast,Flutter,Đảm bảo contrast đạt chuẩn cho cả light và dark mode,"Test cả 2 theme modes","Chỉ test light mode","Theme.of(context).colorScheme.onSurface","Color(0xFF333333) // hardcode không đổi theo theme",High
+10,Color,Not Only Color,color blind indicator shape,Flutter,Không dùng màu là chỉ báo duy nhất cho thông tin quan trọng,"Kết hợp icon/shape với color","Chỉ dùng màu để phân biệt","Row(children: [Icon(Icons.error), Text('Lỗi', style: TextStyle(color: Colors.red))])","Text('Lỗi', style: TextStyle(color: Colors.red))",High
+11,Text,Scalable Text,textscaler font size accessibility,Flutter,Hỗ trợ textScaler để người dùng có thể phóng to text,"Dùng Theme.textTheme","Hardcode fontSize","Text('Hi', style: Theme.of(context).textTheme.bodyLarge)","Text('Hi', style: TextStyle(fontSize: 14))",High
+12,Text,Text Truncation,overflow ellipsis truncate,Flutter,Xử lý text overflow đúng cách với ellipsis hoặc fade,"Set overflow và maxLines","Text tràn ra ngoài","Text('Long...', overflow: TextOverflow.ellipsis, maxLines: 2)","Text('Long text...') // tràn container",Medium
+13,Text,Dynamic Type,font accessibility large small,Flutter,Test với font size từ nhỏ nhất đến lớn nhất trong settings,"Test với tất cả font scales","Chỉ test với font mặc định","MediaQuery.textScalerOf(context).scale(14)","// Không test với accessibility settings",Medium
+14,Focus,Focus Management,focus traversal keyboard,Flutter,Quản lý focus order hợp lý cho keyboard navigation,"Set FocusTraversalOrder khi cần","Focus order không logic","FocusTraversalGroup(policy: OrderedTraversalPolicy(...))","// Để Flutter tự quyết định khi order phức tạp",Medium
+15,Focus,Focus Visibility,focus indicator ring border,Flutter,Hiển thị focus indicator rõ ràng khi navigate bằng keyboard,"Custom focusColor hoặc FocusNode","Focus không hiển thị","Focus(onFocusChange: (f) => setState(() => hasFocus = f))","// Không có visual feedback khi focus",High
+16,Focus,Restore Focus,autofocus restore modal,Flutter,Restore focus về element trước khi mở modal/dialog,"FocusScope.of(context).previousFocus()","Focus bị mất sau khi đóng modal","Navigator.pop(context); FocusScope.of(context).previousFocus()","Navigator.pop(context) // focus bị mất",Medium
+17,Navigation,Back Button Handle,popscope android back,Flutter,Xử lý nút Back Android đúng cách với PopScope,"Dùng PopScope","WillPopScope (deprecated)","PopScope(canPop: false, onPopInvokedWithResult: ...)","WillPopScope(onWillPop: ...) // deprecated",High
+18,Navigation,Screen Reader Announce,announce route semantics,Flutter,Thông báo cho screen reader khi chuyển màn hình,"SemanticsService.announce()","Chuyển màn hình im lặng","SemanticsService.announce('Đã mở trang Cài đặt', TextDirection.ltr)","Navigator.push(...) // không thông báo",Medium
+19,Navigation,Skip Navigation,skip link content main,Flutter,Cung cấp cách bỏ qua navigation để đến nội dung chính,"Focus node cho main content","Phải tab qua toàn bộ nav","ElevatedButton(onPressed: () => mainContentFocus.requestFocus(), child: Text('Bỏ qua'))","// Không có skip link",Medium
+20,Forms,Error Messages,form error inline accessible,Flutter,Hiển thị lỗi inline gần field và thông báo cho screen reader,"errorText trong InputDecoration","Lỗi ở xa field","TextFormField(decoration: InputDecoration(errorText: error))","// Hiển thị lỗi ở cuối form",High
+21,Forms,Form Labels,label hint form input,Flutter,Mỗi form field cần label rõ ràng (không chỉ hint),"labelText trong InputDecoration","Chỉ dùng hintText","TextFormField(decoration: InputDecoration(labelText: 'Email', hintText: 'example@mail.com'))","TextFormField(decoration: InputDecoration(hintText: 'Email'))",High
+22,Forms,Required Indicator,required asterisk field,Flutter,Đánh dấu rõ ràng các field bắt buộc,"Thêm * hoặc (required) vào label","Không đánh dấu required","InputDecoration(labelText: 'Email *')","InputDecoration(labelText: 'Email') // required nhưng không hiển thị",Medium
+23,Motion,Reduced Motion,reduce motion animation accessibility,Flutter,Tôn trọng cài đặt Reduce Motion của hệ thống,"Check MediaQuery.disableAnimations","Animation luôn chạy","if (!MediaQuery.disableAnimationsOf(context)) animate()","// Animation luôn chạy bất kể settings",High
+24,Motion,Auto-play Content,autoplay video audio control,Flutter,Không auto-play video/audio hoặc cho phép tắt,"Cung cấp play button","Auto-play media","VideoPlayer(autoPlay: false)","VideoPlayer(autoPlay: true) // làm phiền user",Medium
+25,Motion,Animation Duration,animation duration time,Flutter,Animation không nên quá nhanh (< 100ms) hoặc quá chậm (> 500ms),"Duration 150-300ms cho micro-interactions","Animation quá nhanh hoặc quá chậm","Duration(milliseconds: 200)","Duration(milliseconds: 50) // quá nhanh để nhận ra",Low
+26,Feedback,Loading States,loading indicator progress,Flutter,Hiển thị loading state rõ ràng cho async operations,"CircularProgressIndicator hoặc Skeleton","Không có loading feedback","if (isLoading) CircularProgressIndicator() else Content()","// Blank screen khi loading",High
+27,Feedback,Error States,error message retry action,Flutter,Hiển thị thông báo lỗi rõ ràng với action để retry,"Error message + Retry button","Im lặng khi lỗi","Column([Text('Có lỗi xảy ra'), ElevatedButton('Thử lại')])","// Blank screen hoặc chỉ có icon lỗi",High
+28,Feedback,Success Confirmation,success toast snackbar confirmation,Flutter,Xác nhận hành động thành công cho người dùng,"SnackBar hoặc Dialog","Không có feedback","ScaffoldMessenger.of(context).showSnackBar(SnackBar(content: Text('Đã lưu!')))","// Không thông báo gì sau khi save",Medium
+29,Feedback,Haptic Feedback,haptic vibration touch,Flutter,Sử dụng haptic feedback cho các action quan trọng,"HapticFeedback.lightImpact()","Không có haptic","HapticFeedback.mediumImpact(); // sau khi tap important button","// Không có tactile feedback",Low
+30,Platform,iOS Guidelines,cupertino ios human interface,Flutter,Tuân thủ Human Interface Guidelines trên iOS,"Dùng Cupertino widgets hoặc adaptive","Material widgets trên iOS","CupertinoPageRoute, CupertinoSwitch khi cần","MaterialPageRoute trên iOS với animation lạ",Medium
+31,Platform,Android Guidelines,material android guidelines,Flutter,Tuân thủ Material Design guidelines trên Android,"Dùng Material 3 widgets","UI không theo platform conventions","MaterialApp, NavigationBar, FloatingActionButton","Custom navigation không theo Material",Medium
+32,Platform,Gesture Conventions,gesture swipe back platform,Flutter,Tôn trọng gesture conventions của từng platform,"iOS: swipe right to back","Block platform gestures","Scaffold với Navigator tự động handle","PopScope block iOS swipe back gesture",Medium
+33,Orientation,Rotation Support,rotation orientation landscape,Flutter,Hỗ trợ rotation nếu phù hợp với app type,"Test cả portrait và landscape","Lock orientation không cần thiết","LayoutBuilder để responsive","SystemChrome.setPreferredOrientations([portrait]) // không cần",Low
+34,Orientation,Keyboard Overlap,keyboard resize insets,Flutter,Xử lý keyboard hiển thị không che form fields,"resizeToAvoidBottomInset hoặc scroll","Keyboard che input field","Scaffold(resizeToAvoidBottomInset: true)","Scaffold(resizeToAvoidBottomInset: false) // keyboard che field",High
+35,Testing,Accessibility Audit,accessibility audit testing,Flutter,Chạy accessibility audit trong development,"Dùng flutter accessibility tools","Không test accessibility","debugCheckIntrinsicSizes: true, semanticsDumpEnabled: true","// Không test với TalkBack/VoiceOver",High

package/assets/data/ui-reasoning.csv

@@ -0,0 +1,36 @@
+No,App_Category,Recommended_Pattern,Style_Priority,Color_Mood,Typography_Mood,Key_Effects,Decision_Rules,Anti_Patterns,Severity
+1,E-commerce App,Hero + Grid + Cart,Material 3 + Vibrant,Brand primary + Success green + Trust,Clear + Engaging,Card elevation + Add to cart animation + Price highlight,"{""if_luxury"": ""use-premium-colors"", ""must_have"": ""quick-add-to-cart""}",Tiny tap targets + Hidden cart + Cluttered product grid,HIGH
+2,Social Media App,Feed + Stories + Profile,Vibrant + Motion-driven,Engagement colors + Notification red,Modern + Bold,Pull to refresh + Like animation + Story progress,"{""must_have"": ""infinite-scroll"", ""must_have"": ""engagement-feedback""}",No loading states + Static content + Poor image loading,HIGH
+3,Banking/Fintech App,Dashboard + Cards + Transactions,Material 3 + Trust,Navy + Trust Blue + Security green,Professional + Clear,Balance animation + Transaction list + Security indicators,"{""must_have"": ""biometric-auth"", ""must_have"": ""transaction-security""}",Insecure storage + No encryption + Hidden fees,CRITICAL
+4,Healthcare App,Appointments + Records + Chat,Accessible + Calm,Calm blue + Health green + White,Readable (16px+) + Clear,Appointment reminders + Health charts + Doctor availability,"{""must_have"": ""hipaa-compliance"", ""must_have"": ""accessibility""}",Small text + Complex navigation + No offline access,HIGH
+5,Fitness/Workout App,Progress + Workouts + Stats,Vibrant + Energetic,Energetic orange + Progress green,Bold + Motivational,Progress rings + Achievement unlocks + Workout timer,"{""must_have"": ""progress-tracking"", ""if_gamification"": ""add-achievements""}",No visual feedback + Static progress + Poor timer UX,HIGH
+6,Food Delivery App,Search + Menu + Tracking,Appetizing + Fast,Warm (Orange Red) + Success green,Clear + Appetizing,Real-time tracking + Order status + Cart animation,"{""must_have"": ""real-time-tracking"", ""must_have"": ""easy-reorder""}",No tracking + Hidden delivery time + Complex checkout,HIGH
+7,Travel/Booking App,Search + Listings + Booking,Inspiring + Trust,Sky blue + Destination colors + Trust,Inspirational + Clear,Search animation + Map integration + Price comparison,"{""must_have"": ""search-filters"", ""must_have"": ""booking-confirmation""}",Complex booking flow + No price transparency + Poor photos,HIGH
+8,Education/Learning App,Courses + Progress + Quiz,Friendly + Engaging,Learning blue + Progress green + Playful,Friendly + Readable,Progress bars + Quiz feedback + Certificate animation,"{""must_have"": ""progress-saving"", ""must_have"": ""offline-mode""}",No progress indication + Lost progress + Boring design,HIGH
+9,Productivity/Todo App,Lists + Calendar + Reminders,Minimal + Clean,Neutral + Priority colors (Red Yellow Green),Clean + Efficient,Task completion animation + Calendar sync + Quick actions,"{""must_have"": ""quick-add"", ""must_have"": ""reminders""}",Complex task creation + No sync + Hidden features,MEDIUM
+10,Messaging/Chat App,Conversations + Messages + Media,Clean + Personal,Brand + Read indicators + Online status,Modern + Readable,Typing indicator + Message status + Media preview,"{""must_have"": ""message-status"", ""must_have"": ""media-support""}",No read receipts + Poor media handling + Slow loading,HIGH
+11,Music/Audio App,Library + Player + Playlists,Immersive + Dark,Album art colors + Control accents,Modern + Bold,Waveform visualization + Now playing animation + Playlist shuffle,"{""must_have"": ""background-playback"", ""must_have"": ""audio-controls""}",Poor audio player UX + No background play + No offline,HIGH
+12,News/Media App,Feed + Articles + Categories,Clean + Readable,Neutral + Category accents,Editorial + Clear,Pull to refresh + Reading progress + Share animation,"{""must_have"": ""offline-reading"", ""must_have"": ""category-filtering""}",Cluttered layout + Slow loading + No offline cache,MEDIUM
+13,Dating App,Profiles + Matching + Chat,Personal + Warm,Warm (Pink Red) + Match success,Friendly + Personal,Swipe animation + Match celebration + Profile reveal,"{""must_have"": ""privacy-controls"", ""must_have"": ""report-system""}",No privacy + Poor profile display + Generic design,HIGH
+14,Real Estate App,Listings + Search + Favorites,Professional + Trust,Trust blue + Premium gold + Clean white,Professional + Clear,Property gallery + Map markers + Price comparison,"{""must_have"": ""map-view"", ""must_have"": ""save-favorites""}",Poor photos + Complex search + No saved properties,HIGH
+15,Ride-sharing App,Booking + Tracking + Payment,Fast + Trust,Brand + Live tracking + Safety indicators,Clear + Functional,Real-time map + Driver tracking + Fare estimation,"{""must_have"": ""real-time-tracking"", ""must_have"": ""safety-features""}",No live tracking + Hidden pricing + Poor driver info,CRITICAL
+16,Wallet/Payment App,Balance + Send + History,Secure + Trust,Trust blue + Money green + Security,Professional + Clear,Balance animation + Transaction confirmation + QR scanner,"{""must_have"": ""biometric-auth"", ""must_have"": ""transaction-receipts""}",Insecure + No confirmation + Hidden fees,CRITICAL
+17,Weather App,Current + Forecast + Alerts,Atmospheric + Dynamic,Sky gradients + Weather-based colors,Clear + Large,Weather animation + Location-based + Push alerts,"{""must_have"": ""location-accuracy"", ""must_have"": ""severe-alerts""}",Inaccurate data + No alerts + Static design,MEDIUM
+18,Gaming App,Game + Leaderboard + Store,Immersive + Engaging,Vibrant + Achievement gold,Bold + Impactful,Game animations + Achievement unlock + Score celebration,"{""must_have"": ""save-progress"", ""must_have"": ""leaderboards""}",Lost progress + Poor performance + No haptics,HIGH
+19,Event/Ticketing App,Events + Tickets + QR,Exciting + Trust,Event colors + Ticket accents,Engaging + Clear,Event discovery + QR ticket + Calendar add,"{""must_have"": ""qr-ticket"", ""must_have"": ""calendar-integration""}",No offline ticket + Complex purchase + Hidden fees,HIGH
+20,Grocery/Shopping App,Categories + Cart + Delivery,Fresh + Fast,Fresh green + Category colors + CTA,Clear + Appetizing,Product search + Quick add + Delivery slots,"{""must_have"": ""search-autocomplete"", ""must_have"": ""delivery-scheduling""}",Poor product images + Complex checkout + No reorder,HIGH
+21,Photography/Camera App,Camera + Gallery + Edit,Creative + Minimal,Neutral + Creative accents,Minimal + Clean,Camera controls + Filter preview + Edit tools,"{""must_have"": ""fast-capture"", ""must_have"": ""non-destructive-editing""}",Slow capture + Poor gallery + Complex editing,MEDIUM
+22,Podcast/Audio App,Shows + Episodes + Player,Content-focused + Dark,Dark + Audio waveform accents,Modern + Clear,Audio player + Episode progress + Download indicator,"{""must_have"": ""background-audio"", ""must_have"": ""download-offline""}",Poor player controls + No downloads + No playback speed,HIGH
+23,Job Search App,Search + Applications + Profile,Professional + Trust,Professional blue + Success green,Clear + Professional,Job match + Application tracker + Interview reminders,"{""must_have"": ""application-tracking"", ""must_have"": ""profile-completion""}",Complex application + No tracking + Hidden salary,HIGH
+24,Pet Care App,Pets + Health + Reminders,Friendly + Warm,Playful + Pet category colors,Friendly + Clear,Pet profiles + Health tracking + Vet reminders,"{""must_have"": ""vaccination-tracking"", ""must_have"": ""vet-locator""}",Generic design + No reminders + Poor pet profiles,MEDIUM
+25,Home Automation App,Devices + Scenes + Schedules,Smart + Dark,Dark + Device status colors + Accent,Clear + Functional,Device control + Scene activation + Real-time status,"{""must_have"": ""real-time-control"", ""must_have"": ""automation""}",Slow response + No offline control + Complex setup,HIGH
+26,Meditation/Wellness App,Sessions + Progress + Sounds,Calm + Minimal,Calm pastels + Nature colors,Calming + Readable,Breathing animation + Timer + Progress tracking,"{""must_have"": ""offline-audio"", ""must_have"": ""reminders""}",Harsh colors + Distracting UI + No offline,HIGH
+27,Parking App,Find + Pay + Navigate,Fast + Trust,Location blue + Payment green,Clear + Functional,Map markers + Payment flow + Timer notification,"{""must_have"": ""map-accuracy"", ""must_have"": ""payment-receipts""}",Inaccurate locations + Complex payment + No timer,HIGH
+28,Restaurant/Menu App,Menu + Order + Reservation,Appetizing + Brand,Brand + Food colors + CTA,Appetizing + Clear,Menu browsing + Table booking + Order tracking,"{""must_have"": ""menu-photos"", ""must_have"": ""reservation-system""}",Poor food photos + Complex ordering + No confirmation,HIGH
+29,Rental/Sharing App,Browse + Book + Return,Trust + Efficient,Trust blue + Status colors,Clear + Efficient,Availability calendar + Booking confirmation + Return reminder,"{""must_have"": ""availability-check"", ""must_have"": ""damage-reporting""}",No availability + Complex booking + Poor damage flow,HIGH
+30,Language Learning App,Lessons + Practice + Progress,Engaging + Playful,Learning colors + Progress indicators,Friendly + Clear,Lesson progress + Quiz feedback + Streak animation,"{""must_have"": ""progress-sync"", ""must_have"": ""gamification""}",Boring design + No motivation + Lost progress,HIGH
+31,Pharmacy/Medicine App,Prescriptions + Orders + Reminders,Trust + Healthcare,Medical blue + Trust + Alert colors,Clear + Accessible,Prescription scanner + Refill reminders + Drug info,"{""must_have"": ""reminder-system"", ""must_have"": ""drug-interactions""}",Complex refill + No reminders + Poor drug info,HIGH
+32,Insurance App,Policies + Claims + Support,Trust + Professional,Trust blue + Success green + Alert,Professional + Clear,Policy overview + Claim status + Document upload,"{""must_have"": ""claim-tracking"", ""must_have"": ""document-management""}",Hidden policy details + Complex claims + No tracking,HIGH
+33,Donation/Charity App,Causes + Donate + Impact,Heartfelt + Trust,Warm + Impact colors + Trust,Heartfelt + Clear,Impact visualization + Donation confirmation + Recurring setup,"{""must_have"": ""impact-transparency"", ""must_have"": ""easy-recurring""}",Hidden impact + Complex donation + No receipts,HIGH
+34,Survey/Form App,Questions + Progress + Submit,Clean + Efficient,Brand + Progress + Completion,Clear + Readable,Progress indicator + Skip logic + Submit confirmation,"{""must_have"": ""save-progress"", ""must_have"": ""clear-navigation""}",Lost progress + Complex questions + No feedback,MEDIUM
+35,Kids/Family App,Content + Controls + Profiles,Safe + Playful,Playful + Safe colors,Large + Friendly,Parental controls + Age-appropriate content + Usage stats,"{""must_have"": ""parental-controls"", ""must_have"": ""content-filtering""}",No controls + Inappropriate content + Small targets,CRITICAL

package/assets/{.claude/skills/flutter-pro-max/scripts → scripts}/core.py

@@ -10,19 +10,22 @@ import re
 from pathlib import Path
 from math import log
 from collections import defaultdict
+from typing import Any
 
 # ============ CONFIGURATION ============
-def _get_data_dir():
+def _get_data_dir() -> Path:
     """Auto-detect data directory based on script location"""
     script_dir = Path(__file__).parent
     possible_paths = [
+        # Full install: .claude/skills/flutter-pro-max/scripts/ -> data/ (sibling)
+        script_dir.parent / "data",
+        # Reference install: .shared/flutter-pro-max/scripts/ -> ../data
+        script_dir.parent.parent / "data",
         # When running from root/scripts/
         script_dir.parent / ".shared" / "data",
-        # When running from .shared/flutter-pro-max/scripts/
-        script_dir.parent.parent / "data",
         # When running from .agent/workflows/scripts/ (nested 3 levels deep)
         script_dir.parent.parent.parent / ".shared" / "data",
-        # When running from .claude/skills/flutter-pro-max/scripts/ (nested 4 levels deep)
+        # When running from .claude/skills/flutter-pro-max/scripts/ (reference mode)
         script_dir.parent.parent.parent.parent / ".shared" / "data",
         # Fallback: cwd
         Path.cwd() / ".shared" / "data",
@@ -36,7 +39,7 @@ DATA_DIR = _get_data_dir()
 MAX_RESULTS = 5
 
 # Domain configuration: file, search columns, output columns
-CSV_CONFIG = {
+CSV_CONFIG: dict[str, dict[str, str | list[str]]] = {
     "widget": {
         "file": "widget.csv",
         "search_cols": ["Widget Name", "Category", "Description", "Key Properties", "Usage Context & Pro-Tips"],
@@ -106,6 +109,21 @@ CSV_CONFIG = {
         "file": "prompts.csv",
         "search_cols": ["Style Category", "AI Prompt Keywords (Copy-Paste Ready)", "CSS/Technical Keywords"],
         "output_cols": ["Style Category", "AI Prompt Keywords (Copy-Paste Ready)", "CSS/Technical Keywords", "Implementation Checklist"]
+    },
+    "performance": {
+        "file": "flutter-performance.csv",
+        "search_cols": ["Category", "Issue", "Keywords", "Description", "Do", "Don't"],
+        "output_cols": ["Category", "Issue", "Keywords", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
+    },
+    "ui-reasoning": {
+        "file": "ui-reasoning.csv",
+        "search_cols": ["App_Category", "Recommended_Pattern", "Style_Priority", "Color_Mood", "Key_Effects", "Decision_Rules"],
+        "output_cols": ["App_Category", "Recommended_Pattern", "Style_Priority", "Color_Mood", "Typography_Mood", "Key_Effects", "Decision_Rules", "Anti_Patterns", "Severity"]
+    },
+    "accessibility": {
+        "file": "mobile-accessibility.csv",
+        "search_cols": ["Category", "Issue", "Keywords", "Platform", "Description", "Do", "Don't"],
+        "output_cols": ["Category", "Issue", "Keywords", "Platform", "Description", "Do", "Don't", "Code Example Good", "Code Example Bad", "Severity"]
     }
 }
 
@@ -124,49 +142,49 @@ AVAILABLE_STACKS = list(STACK_EXCLUSIONS.keys())
 class BM25:
     """BM25 ranking algorithm for text search - zero dependencies"""
 
-    def __init__(self, k1=1.5, b=0.75):
+    def __init__(self, k1: float = 1.5, b: float = 0.75) -> None:
         self.k1 = k1
         self.b = b
-        self.corpus = []
-        self.doc_lengths = []
-        self.avgdl = 0
-        self.idf = {}
-        self.doc_freqs = defaultdict(int)
-        self.N = 0
-
-    def tokenize(self, text):
+        self.corpus: list[list[str]] = []
+        self.doc_lengths: list[int] = []
+        self.avgdl: float = 0
+        self.idf: dict[str, float] = {}
+        self.doc_freqs: defaultdict[str, int] = defaultdict(int)
+        self.n: int = 0
+
+    def tokenize(self, text: str) -> list[str]:
         """Lowercase, split, remove punctuation, filter short words"""
         text = re.sub(r'[^\w\s]', ' ', str(text).lower())
         return [w for w in text.split() if len(w) > 1]
 
-    def fit(self, documents):
+    def fit(self, documents: list[str]) -> None:
         """Build BM25 index from documents"""
         self.corpus = [self.tokenize(doc) for doc in documents]
-        self.N = len(self.corpus)
-        if self.N == 0:
+        self.n = len(self.corpus)
+        if self.n == 0:
             return
         self.doc_lengths = [len(doc) for doc in self.corpus]
-        self.avgdl = sum(self.doc_lengths) / self.N
+        self.avgdl = sum(self.doc_lengths) / self.n
 
         for doc in self.corpus:
-            seen = set()
+            seen: set[str] = set()
             for word in doc:
                 if word not in seen:
                     self.doc_freqs[word] += 1
                     seen.add(word)
 
         for word, freq in self.doc_freqs.items():
-            self.idf[word] = log((self.N - freq + 0.5) / (freq + 0.5) + 1)
+            self.idf[word] = log((self.n - freq + 0.5) / (freq + 0.5) + 1)
 
-    def score(self, query):
+    def score(self, query: str) -> list[tuple[int, float]]:
         """Score all documents against query"""
         query_tokens = self.tokenize(query)
-        scores = []
+        scores: list[tuple[int, float]] = []
 
         for idx, doc in enumerate(self.corpus):
-            score = 0
+            score: float = 0.0
             doc_len = self.doc_lengths[idx]
-            term_freqs = defaultdict(int)
+            term_freqs: defaultdict[str, int] = defaultdict(int)
             for word in doc:
                 term_freqs[word] += 1
 
@@ -184,13 +202,13 @@ class BM25:
 
 
 # ============ HELPER FUNCTIONS ============
-def _load_csv(filepath):
+def _load_csv(filepath: Path) -> list[dict[str, str]]:
     """Load CSV and return list of dicts"""
     with open(filepath, 'r', encoding='utf-8') as f:
         return list(csv.DictReader(f))
 
 
-def _search_csv(filepath, search_cols, output_cols, query, max_results, boost_col=None, boost_query=None):
+def _search_csv(filepath: Path, search_cols: list[str], output_cols: list[str], query: str, max_results: int, boost_col: str | None = None, boost_query: str | None = None) -> list[dict[str, Any]]:
     """Core search function using BM25 with optional boosting"""
     if not filepath.exists():
         return []
@@ -208,28 +226,29 @@ def _search_csv(filepath, search_cols, output_cols, query, max_results, boost_co
     # Apply boosting if specified (widget name match, etc.)
     if boost_col and boost_query:
         boost_query_lower = boost_query.lower()
-        boosted = []
+        boosted: list[tuple[int, float]] = []
         for idx, score in ranked:
+            boosted_score = score
             if score > 0:
                 boost_value = str(data[idx].get(boost_col, "")).lower()
                 if boost_value in boost_query_lower or boost_query_lower in boost_value:
-                    score *= 2.0  # Double score for exact/partial match
-            boosted.append((idx, score))
+                    boosted_score = score * 2.0  # Double score for exact/partial match
+            boosted.append((idx, boosted_score))
         ranked = sorted(boosted, key=lambda x: x[1], reverse=True)
 
     # Get top results with score > 0
-    results = []
+    results: list[dict[str, Any]] = []
     for idx, score in ranked[:max_results]:
         if score > 0:
             row = data[idx]
-            result = {col: row.get(col, "") for col in output_cols if col in row}
+            result: dict[str, Any] = {col: row.get(col, "") for col in output_cols if col in row}
             result["_score"] = round(score, 4)
             results.append(result)
 
     return results
 
 
-def detect_domain(query):
+def detect_domain(query: str) -> str:
     """Auto-detect the most relevant domain from query keywords"""
     query_lower = query.lower()
 
@@ -250,13 +269,13 @@ def detect_domain(query):
         "prompt": ["prompt", "ai", "css", "tailwind", "implementation"],
     }
 
-    scores = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
-    best = max(scores, key=scores.get)
+    scores: dict[str, int] = {domain: sum(1 for kw in keywords if kw in query_lower) for domain, keywords in domain_keywords.items()}
+    best = max(scores, key=lambda k: scores[k])
     return best if scores[best] > 0 else "widget"
 
 
 # ============ MAIN SEARCH FUNCTIONS ============
-def search(query, domain=None, max_results=MAX_RESULTS):
+def search(query: str, domain: str | None = None, max_results: int = MAX_RESULTS) -> dict[str, Any]:
     """
     Main search function with auto-domain detection
     
@@ -275,7 +294,7 @@ def search(query, domain=None, max_results=MAX_RESULTS):
         return {"error": f"Unknown domain: {domain}. Available: {', '.join(AVAILABLE_DOMAINS)}"}
 
     config = CSV_CONFIG[domain]
-    filepath = DATA_DIR / config["file"]
+    filepath = DATA_DIR / str(config["file"])
 
     if not filepath.exists():
         return {"error": f"File not found: {filepath}", "domain": domain}
@@ -284,15 +303,20 @@ def search(query, domain=None, max_results=MAX_RESULTS):
     boost_col = "Widget Name" if domain == "widget" else None
     boost_query = query if domain == "widget" else None
 
-    results = _search_csv(
-        filepath, 
-        config["search_cols"], 
-        config["output_cols"], 
-        query, 
-        max_results,
-        boost_col=boost_col,
-        boost_query=boost_query
-    )
+    search_cols = config["search_cols"]
+    output_cols = config["output_cols"]
+    if isinstance(search_cols, list) and isinstance(output_cols, list):
+        results = _search_csv(
+            filepath, 
+            search_cols, 
+            output_cols, 
+            query, 
+            max_results,
+            boost_col=boost_col,
+            boost_query=boost_query
+        )
+    else:
+        results = []
 
     return {
         "domain": domain,
@@ -303,7 +327,7 @@ def search(query, domain=None, max_results=MAX_RESULTS):
     }
 
 
-def search_with_stack(query, stack, domain=None, max_results=MAX_RESULTS):
+def search_with_stack(query: str, stack: str, domain: str | None = None, max_results: int = MAX_RESULTS) -> dict[str, Any]:
     """
     Search with stack-specific filtering (excludes conflicting packages)
     
@@ -326,11 +350,11 @@ def search_with_stack(query, stack, domain=None, max_results=MAX_RESULTS):
 
     # Filter out conflicting packages
     excluded = STACK_EXCLUSIONS[stack]
-    filtered_results = []
+    filtered_results: list[dict[str, Any]] = []
     
     for item in result["results"]:
         # Check package name field
-        pkg_name = item.get("pkg_name", "").lower()
+        pkg_name = str(item.get("pkg_name", "")).lower()
         if pkg_name not in excluded:
             filtered_results.append(item)