anchi-toolkit 1.2.0 → 1.2.2

package/dist/.cursor/skills/mobile-development/references/mobile-mindset.md

@@ -0,0 +1,544 @@
+# Mobile Development Mindset & Thinking Patterns
+
+Essential thinking patterns and decision-making frameworks for successful mobile development.
+
+## The 10 Commandments of Mobile Development
+
+### 1. Performance is Foundation, Not Feature
+- **Reality**: 70% users abandon apps >3s load time
+- **Mindset**: Optimize from day one, not "later"
+- **Action**: Set performance budgets before writing code
+
+### 2. Every Kilobyte, Every Millisecond Matters
+- **Reality**: Mobile = constrained environment (battery, memory, network)
+- **Mindset**: Desktop assumptions don't apply
+- **Action**: Profile real devices, not simulators
+
+### 3. Offline-First by Default
+- **Reality**: Network is unreliable (elevators, tunnels, airplanes, poor signal)
+- **Mindset**: Design for offline, sync when online
+- **Action**: Local persistence first, cloud sync second
+
+### 4. User Context > Developer Environment
+- **Reality**: Users on trains, walking, one-handed, bright sunlight
+- **Mindset**: Test in real-world scenarios
+- **Action**: Real device testing mandatory
+
+### 5. Platform Awareness Without Platform Lock-In
+- **Reality**: iOS and Android users expect different patterns
+- **Mindset**: Respect conventions, but keep logic portable
+- **Action**: Platform-specific UI, shared business logic
+
+### 6. Iterate, Don't Perfect (2024-2025 Survival Strategy)
+- **Reality**: Mobile landscape changes rapidly
+- **Mindset**: Ship, measure, improve cycle
+- **Action**: MVP → User feedback → Iterate
+
+### 7. Security and Accessibility by Design
+- **Reality**: Not afterthoughts, but core requirements
+- **Mindset**: Build trust and inclusivity from start
+- **Action**: Security audit + accessibility testing in every sprint
+
+### 8. Test on Real Devices
+- **Reality**: Simulators lie about performance, battery, network
+- **Mindset**: Simulators for speed, devices for truth
+- **Action**: CI/CD with real device farms
+
+### 9. Architecture Scales with Complexity
+- **Reality**: Over-engineering kills simple apps
+- **Mindset**: Start simple, refactor when needed
+- **Action**: MVVM for small apps, Clean Architecture when complexity demands
+
+### 10. Continuous Learning is Survival
+- **Reality**: 85% developers use AI tools (2024), frameworks evolve constantly
+- **Mindset**: Embrace change, allocate learning time
+- **Action**: 1+ hour weekly for new tech/patterns
+
+## Mobile-Specific Constraints & Thinking
+
+### Small Screens (Constraint → Design Parameter)
+
+**Constraint:**
+- 5-7 inch screens, thumb-reach zones, fat finger problem
+
+**Thinking Shift:**
+- Embrace minimalism: "What can we remove?"
+- Priority-based hierarchy: Most important action front and center
+- Progressive disclosure: Hide complexity behind layers
+
+**Practical Targets:**
+- 44x44px minimum touch targets (iOS)
+- 48x48px minimum touch targets (Android)
+- Primary actions within thumb reach (bottom 1/3)
+- Maximum 3-4 items in bottom navigation
+
+**Example Decision:**
+```
+❌ Bad: 8-column data table on mobile
+✅ Good: Card view with 3 key metrics, "View more" for details
+```
+
+### Limited Resources (Every KB/ms Matters)
+
+**Constraint:**
+- Battery drain, memory pressure, thermal throttling
+
+**Thinking Shift:**
+- Resource consciousness in every decision
+- Measure before optimizing (don't guess)
+- Graceful degradation on low-end devices
+
+**Practical Targets:**
+- <100MB memory for typical screens
+- <5% battery drain per hour active use
+- <50MB initial download, <200MB total
+- 60 FPS (16.67ms per frame)
+
+**Example Decision:**
+```
+❌ Bad: Load all 1000 items in list
+✅ Good: Virtualized list (10 items visible + buffer)
+```
+
+### Intermittent Connectivity (Offline-First)
+
+**Constraint:**
+- Network unreliable: elevators, tunnels, poor signal, airplane mode
+
+**Thinking Shift:**
+- Local-first data architecture
+- Optimistic UI updates
+- Sync conflict resolution strategy
+
+**Practical Approaches:**
+- **Write-through cache**: Write local, sync background
+- **Hybrid sync**: Push (realtime) + Pull (periodic)
+- **Conflict resolution**: Last-write-wins with timestamps or CRDT
+
+**Example Decision:**
+```
+❌ Bad: Show spinner while posting comment
+✅ Good: Show comment immediately (optimistic), sync background, handle conflicts
+```
+
+## Platform-Specific Thinking
+
+### iOS Mental Model
+
+**Philosophy**: Consistent, polished, opinionated
+- Users expect iOS patterns (tab bar, navigation bar, swipe back)
+- Design reviews reject non-standard UIs
+- "It just works" expectation = zero tolerance for crashes
+
+**Fragmentation**: LOW
+- 90%+ on iOS 16+ (2024)
+- Only ~50 device models to test
+- Predictable hardware specs
+
+**Design Thinking**:
+- Follow Human Interface Guidelines religiously
+- Native navigation patterns non-negotiable
+- Haptic feedback for important actions
+- Respect safe areas (notch, Dynamic Island)
+
+**When to Go Native iOS:**
+- App Store is primary revenue channel
+- Need latest Apple features (WidgetKit, Live Activities)
+- Target affluent user base (iOS users spend 2.5x more)
+
+### Android Mental Model
+
+**Philosophy**: Flexible, customizable, democratic
+- Users expect Material Design but tolerate variations
+- Extreme fragmentation = defensive programming
+- "Back button" = fundamental navigation expectation
+
+**Fragmentation**: HIGH
+- 24,000+ device models
+- Android 6-14 in active use (8 years of OS versions)
+- Wide range of hardware specs (512MB to 12GB RAM)
+
+**Design Thinking**:
+- Material Design 3 as baseline
+- Test on low-end devices (1GB RAM minimum)
+- Respect system navigation (gesture vs 3-button)
+- Handle back button properly
+
+**When to Go Native Android:**
+- Global market focus (72% market share)
+- Emerging markets (Android dominates)
+- Enterprise/B2B (customization needs)
+
+## Performance Mindset (Every Millisecond Matters)
+
+### Critical Metrics (User Perception)
+
+| Metric | Threshold | User Perception |
+|--------|-----------|-----------------|
+| **Launch time** | <2s | Acceptable |
+| **Launch time** | 2-3s | Noticeable delay |
+| **Launch time** | >3s | 70% abandon |
+| **Screen load** | <1s | Instant (cached) |
+| **Screen load** | 1-3s | Acceptable (network) |
+| **Screen load** | >3s | Frustrating |
+| **Animation** | 60 FPS | Smooth |
+| **Animation** | 30-60 FPS | Noticeable jank |
+| **Animation** | <30 FPS | Unusable |
+
+### Performance Budget Example
+
+**Mobile App Performance Budget:**
+```
+Launch Time
+├─ Cold start: <2s (target 1.5s)
+├─ Warm start: <1s
+└─ Hot start: <0.5s
+
+Screen Load
+├─ Cached data: <500ms
+├─ Network data: <2s
+└─ Heavy computation: <3s
+
+Memory
+├─ Typical screen: <100MB
+├─ Heavy screen (images): <150MB
+└─ Peak usage: <200MB
+
+Network
+├─ Initial bundle: <2MB
+├─ Per screen: <500KB
+└─ Images: <200KB each
+
+Battery
+├─ Active use: <5% per hour
+├─ Background: <1% per hour
+└─ Idle: <0.1% per hour
+```
+
+### Optimization Decision Tree
+
+**Is it slow?**
+1. **Measure first** (Xcode Instruments, Android Profiler)
+2. **Find bottleneck** (CPU, memory, network, disk I/O)
+3. **Fix biggest impact** (80/20 rule)
+4. **Measure again** (verify improvement)
+
+**Common Culprits:**
+- Synchronous main thread operations
+- Unoptimized images (too large, wrong format)
+- N+1 query problem (fetch in loop)
+- Memory leaks (retain cycles, listeners)
+- Re-renders without memoization
+
+## Mobile Development Workflow
+
+### Iterative Development Cycle (Agile)
+
+**Sprint Structure (2 weeks):**
+```
+Week 1: Build + Test
+├─ Day 1-2: Design + plan
+├─ Day 3-4: Implement core
+└─ Day 5: Code review + tests
+
+Week 2: Polish + Ship
+├─ Day 6-7: Bug fixes + polish
+├─ Day 8: QA testing
+├─ Day 9: Staging deployment
+└─ Day 10: Production release (staged)
+```
+
+**Daily Workflow:**
+1. Pull latest code
+2. Run tests locally
+3. Develop feature/fix
+4. Write/update tests
+5. Local testing on device
+6. Code review
+7. CI/CD validation
+8. Merge to develop
+
+**CI/CD Impact:**
+- 20% reduction in development time
+- 50% fewer production bugs
+- 3x faster deployment
+
+### Common Pitfalls & Avoidance
+
+#### 1. Testing Only on Simulators
+**Problem**: Simulators don't show real performance (battery, memory, network)
+**Solution**: Real device testing mandatory before every release
+**Impact**: 40% of bugs only appear on real devices
+
+#### 2. Ignoring Platform Conventions
+**Problem**: Custom navigation confuses users
+**Solution**: Follow iOS HIG and Material Design
+**Impact**: 30% lower engagement with non-standard UIs
+
+#### 3. No Offline Handling
+**Problem**: Network failures = blank screens, errors
+**Solution**: Offline-first architecture, cached data
+**Impact**: 50% of users experience network issues daily
+
+#### 4. Poor Memory Management
+**Problem**: Memory leaks → crashes, poor performance
+**Solution**: ARC/GC understanding, profile regularly
+**Impact**: Memory issues = #1 crash cause (35%)
+
+#### 5. Hardcoded Credentials
+**Problem**: Security vulnerability, API key exposure
+**Solution**: Environment variables, secure storage
+**Impact**: 23% of apps leak sensitive data (OWASP)
+
+#### 6. No Accessibility
+**Problem**: Excludes 15%+ of users (disability, situational)
+**Solution**: VoiceOver/TalkBack testing, semantic labels
+**Impact**: Accessibility = 1.3B global market
+
+#### 7. Premature Optimization
+**Problem**: Wasted time optimizing non-bottlenecks
+**Solution**: Measure first, optimize biggest impact
+**Impact**: 80% of performance issues = 20% of code
+
+#### 8. Over-Engineering
+**Problem**: Complex architecture for simple apps
+**Solution**: Start simple, scale when needed
+**Impact**: 3x longer development for no user benefit
+
+#### 9. Skipping Real Device Testing
+**Problem**: Missed battery drain, thermal issues
+**Solution**: Device farm in CI/CD, manual testing
+**Impact**: 25% of performance issues device-specific
+
+#### 10. Not Respecting Battery
+**Problem**: Background processing drains battery
+**Solution**: Batch operations, respect Doze Mode
+**Impact**: Battery drain = #1 uninstall reason
+
+## Debugging Strategies & Tools (2024-2025)
+
+### iOS Debugging (Xcode 16)
+
+**Tools:**
+- **Instruments**: Profiling (Time, Allocations, Leaks, Network)
+- **Memory Graph**: Visual retain cycles
+- **View Hierarchy**: UI debugging
+- **Network Link Conditioner**: Simulate poor network
+- **Console**: System logs, os_log
+
+**AI-Driven:**
+- Xcode 16 AI crash analysis
+- Automatic memory leak detection
+- Performance suggestions
+
+**Process:**
+1. Reproduce bug on device
+2. Attach debugger / capture crash log
+3. Symbolicate crash report
+4. Fix root cause (not symptom)
+5. Add test to prevent regression
+
+### Android Debugging (Android Studio Giraffe+)
+
+**Tools:**
+- **Profiler**: CPU, Memory, Network, Energy
+- **Layout Inspector**: 3D view hierarchy
+- **Database Inspector**: SQLite/Room debugging
+- **Network Inspector**: API call monitoring
+- **Logcat**: System logs with filters
+
+**AI-Driven:**
+- Android Vitals: Crash clustering, ANR analysis
+- Firebase Crashlytics: AI-powered issue grouping
+- Play Console insights: User-reported bugs
+
+**Process:**
+1. Reproduce on emulator/device
+2. Check Logcat for stack traces
+3. Use Android Profiler for performance
+4. Fix and verify with instrumented tests
+5. Monitor Play Console vitals post-release
+
+### Cross-Platform Debugging
+
+**React Native:**
+- Chrome DevTools / Safari Web Inspector
+- Flipper (meta debugger: network, layout, logs)
+- Reactotron (state inspection)
+
+**Flutter:**
+- Flutter DevTools (Inspector, Timeline, Memory, Network)
+- Dart Observatory (VM debugging)
+- Widget Inspector (UI debugging)
+
+## Progressive Enhancement & Graceful Degradation
+
+### Progressive Enhancement (Build Up)
+
+**Strategy**: Start with baseline, enhance for capable devices
+
+**Example: Image Loading**
+```
+Baseline (all devices):
+├─ Show placeholder immediately
+├─ Load low-res image (10KB)
+└─ Display with smooth fade-in
+
+Enhancement (modern devices):
+├─ Check network (fast = high-res)
+├─ Check memory (ample = cache)
+└─ Progressive JPEG rendering
+```
+
+**Benefits:**
+- Works on all devices
+- Optimal experience on modern devices
+- No user left behind
+
+### Graceful Degradation (Strip Down)
+
+**Strategy**: Build for best, degrade for constraints
+
+**Example: Animation**
+```
+Best (flagship devices):
+├─ Complex particle effects
+├─ 120 FPS animations
+└─ Parallax scrolling
+
+Degraded (budget devices):
+├─ Simple fade transitions
+├─ 60 FPS target
+└─ Disable parallax (GPU load)
+```
+
+**Detection:**
+```javascript
+// React Native
+const isLowEndDevice =
+  DeviceInfo.getTotalMemory() < 2000000000; // <2GB
+
+if (isLowEndDevice) {
+  // Disable heavy animations
+  // Reduce concurrent operations
+  // Lower image quality
+}
+```
+
+**Benefits:**
+- Optimized for all hardware tiers
+- Prevents crashes on low-end devices
+- Better user experience across spectrum
+
+## Native vs Cross-Platform Decision Framework
+
+### Decision Tree
+
+**Q1: Do you need 100% native performance?**
+- **Yes** → Native (Swift/Kotlin)
+- **No** → Continue
+
+**Q2: Is team comfortable with JavaScript?**
+- **Yes** → React Native
+- **No** → Continue
+
+**Q3: Need desktop or web versions too?**
+- **Yes** → Flutter
+- **No** → Continue
+
+**Q4: Complex animations or custom UI?**
+- **Yes** → Flutter
+- **No** → React Native (easier for standard UIs)
+
+**Q5: Existing codebase to share?**
+- **React web app** → React Native
+- **No existing code** → Flutter (cleaner slate)
+
+### Hybrid Approach (Best of Both Worlds)
+
+**Strategy**: Cross-platform for most features, native for critical paths
+
+**Example Architecture:**
+```
+React Native / Flutter (90%)
+├─ UI and business logic
+├─ Standard features
+└─ API integration
+
+Native Modules (10%)
+├─ Performance-critical (video processing)
+├─ Platform-specific (HealthKit, Android Auto)
+└─ Third-party SDKs (payment, analytics)
+```
+
+**When to Use:**
+- Best: Leverage cross-platform speed + native power
+- Complexity: Maintain native module knowledge
+- Team: Need both cross-platform and native developers
+
+## Architecture Decision-Making
+
+### Complexity-Based Architecture Selection
+
+**Simple App (1-5 screens, basic CRUD)**
+- **Architecture**: MVVM (no Clean Architecture)
+- **State**: Local state (useState, setState)
+- **Reasoning**: Over-engineering adds complexity without benefit
+
+**Medium App (5-20 screens, moderate logic)**
+- **Architecture**: MVVM with clear separation
+- **State**: Global state management (Zustand, Riverpod)
+- **Reasoning**: Scalability without over-engineering
+
+**Complex App (20+ screens, enterprise logic)**
+- **Architecture**: Clean Architecture (domain, data, presentation)
+- **State**: Advanced state management + dependency injection
+- **Reasoning**: Maintainability and testability critical
+
+### Architecture Evolution
+
+**Start Simple:**
+```
+v1.0: MVVM, local state, single module
+└─ Focus: Ship fast, validate idea
+
+v2.0: Add global state when needed
+└─ Trigger: Props drilling becomes painful
+
+v3.0: Add Clean Architecture when scaling
+└─ Trigger: Team grows, features multiply
+
+v4.0: Extract microservices if justified
+└─ Trigger: Independent deployment needs
+```
+
+**Key Principle:** Refactor when pain > refactoring cost, not before
+
+## Resources & Continuous Learning
+
+**Weekly Learning Targets (2024-2025):**
+- 1 hour: New framework features
+- 30 min: Performance optimization techniques
+- 30 min: Security updates (CVEs, OWASP)
+- 30 min: Community articles/videos
+
+**Top Resources:**
+- iOS: Apple WWDC videos, Swift by Sundell
+- Android: Android Dev Summit, Medium Android Dev
+- React Native: React Native Blog, Expo Blog
+- Flutter: Flutter Engage, Medium Flutter
+- Mobile DevOps: Bitrise Blog, Fastlane guides
+
+**Communities:**
+- Stack Overflow (mobile tags)
+- Reddit (r/iOSProgramming, r/androiddev, r/reactnative, r/FlutterDev)
+- Discord (React Native, Flutter official)
+- Twitter: Follow framework creators and contributors
+
+**AI Tools (85% adoption in 2024):**
+- GitHub Copilot: Code completion, boilerplate
+- ChatGPT/Claude: Architecture questions, debugging
+- Tabnine: Context-aware suggestions
+- Average time saved: 1+ hour weekly
+
+**Key Mindset:** Continuous learning is not optional, it's survival in mobile development

package/dist/.cursor/skills/payment-integration/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: payment-integration
+description: Implement payment integrations with SePay (Vietnamese payment gateway with VietQR, bank transfers, cards) and Polar (global SaaS monetization platform with subscriptions, usage-based billing, automated benefits). Use when integrating payment processing, implementing checkout flows, managing subscriptions, handling webhooks, processing bank transfers, generating QR codes, automating benefit delivery, or building billing systems. Supports authentication (API keys, OAuth2), product management, customer portals, tax compliance (Polar as MoR), and comprehensive SDK integrations (Node.js, PHP, Python, Go, Laravel, Next.js).
+version: 1.0.0
+license: MIT
+---
+
+# Payment Integration
+
+Implement payment processing with SePay (Vietnamese payments) and Polar (global SaaS monetization).
+
+## When to Use
+
+Use when implementing:
+- Payment gateway integration (checkout, processing)
+- Subscription management (trials, upgrades, billing)
+- Webhook handling (payment notifications)
+- QR code payments (VietQR, NAPAS)
+- Usage-based billing (metering, credits)
+- Automated benefit delivery (licenses, GitHub access, Discord roles)
+- Customer portals (self-service management)
+- Bank transfer automation (Vietnamese banks)
+- Product catalogs with pricing
+
+## Platform Selection
+
+**Choose SePay for:**
+- Vietnamese market (VND currency)
+- Bank transfer automation
+- VietQR/NAPAS payments
+- Local payment methods
+- Direct bank account monitoring
+
+**Choose Polar for:**
+- Global SaaS products
+- Subscription management
+- Usage-based billing
+- Automated benefits (GitHub, Discord, licenses)
+- Merchant of Record (tax compliance)
+- Digital product sales
+
+## Quick Reference
+
+### SePay Integration
+- **Overview & Auth**: `references/sepay/overview.md` - Platform capabilities, API/OAuth2 auth, supported banks
+- **API Reference**: `references/sepay/api.md` - Endpoints, transactions, bank accounts, virtual accounts
+- **Webhooks**: `references/sepay/webhooks.md` - Setup, payload structure, verification, retry logic
+- **SDK Usage**: `references/sepay/sdk.md` - Node.js, PHP, Laravel implementations
+- **QR Codes**: `references/sepay/qr-codes.md` - VietQR generation, templates, integration
+- **Best Practices**: `references/sepay/best-practices.md` - Security, patterns, monitoring
+
+### Polar Integration
+- **Overview & Auth**: `references/polar/overview.md` - Platform capabilities, authentication methods, MoR concept
+- **Products & Pricing**: `references/polar/products.md` - Product types, pricing models, usage-based billing
+- **Checkouts**: `references/polar/checkouts.md` - Checkout flows, embedded checkout, links
+- **Subscriptions**: `references/polar/subscriptions.md` - Lifecycle, upgrades, downgrades, trials
+- **Webhooks**: `references/polar/webhooks.md` - Event types, signature verification, monitoring
+- **Benefits**: `references/polar/benefits.md` - Automated delivery (GitHub, Discord, licenses, files)
+- **SDK Usage**: `references/polar/sdk.md` - TypeScript, Python, PHP, Go, framework adapters
+- **Best Practices**: `references/polar/best-practices.md` - Security, patterns, monitoring
+
+### Integration Scripts
+- **SePay Webhook Verification**: `scripts/sepay-webhook-verify.js` - Verify SePay webhook authenticity
+- **Polar Webhook Verification**: `scripts/polar-webhook-verify.js` - Verify Polar webhook signatures
+- **Checkout Helper**: `scripts/checkout-helper.js` - Generate checkout sessions for both platforms
+
+## Implementation Workflow
+
+### SePay Implementation
+1. Load `references/sepay/overview.md` for auth setup
+2. Load `references/sepay/api.md` or `references/sepay/sdk.md` for integration
+3. Load `references/sepay/webhooks.md` for payment notifications
+4. Use `scripts/sepay-webhook-verify.js` for webhook verification
+5. Load `references/sepay/best-practices.md` for production readiness
+
+### Polar Implementation
+1. Load `references/polar/overview.md` for auth and concepts
+2. Load `references/polar/products.md` for product setup
+3. Load `references/polar/checkouts.md` for payment flows
+4. Load `references/polar/webhooks.md` for event handling
+5. Use `scripts/polar-webhook-verify.js` for webhook verification
+6. Load `references/polar/benefits.md` if automating delivery
+7. Load `references/polar/best-practices.md` for production readiness
+
+## Key Capabilities
+
+**SePay:**
+- Payment gateway (QR, bank transfer, cards)
+- Bank account monitoring with webhooks
+- Order-based virtual accounts
+- VietQR generation API
+- 44+ Vietnamese banks supported
+- Rate limit: 2 calls/second
+
+**Polar:**
+- Merchant of Record (global tax compliance)
+- Subscription lifecycle management
+- Usage-based billing (events, meters)
+- Automated benefits (GitHub, Discord, licenses)
+- Customer portal (self-service)
+- Multi-language SDKs
+- Rate limit: 300 req/min
+
+## Instructions
+
+When implementing payment integration:
+
+1. **Identify platform** based on requirements (Vietnamese vs global, payment types)
+2. **Load relevant references** progressively as needed
+3. **Implement authentication** using platform-specific methods
+4. **Set up products/pricing** according to business model
+5. **Implement checkout flow** (hosted, embedded, or API-driven)
+6. **Configure webhooks** with proper verification
+7. **Handle payment events** (success, failure, refund)
+8. **Test thoroughly** in sandbox before production
+9. **Monitor and optimize** using platform analytics
+
+Load only the references needed for current implementation step to maintain context efficiency.