Imported from Maruti05/caply-ai-cap-gen (AGENTS.md). Install upstream with npx skills add Maruti05/caply-ai-cap-gen. Copyright stays with the author.

Caply – Agent Guide

What this is

AI-powered social media caption/bio/quote generator. No backend, no auth, no database — all state is local via SharedPreferences. Groq API (llama-3.1-8b-instant) via REST.

Key structure

lib/
  main.dart                 # Entrypoint: dotenv → prefs → consent → AdMob → run
  core/
    theme/app_theme.dart    # Material 3 light + dark, Google Fonts (Plus Jakarta Sans, Manrope)
    utils/ai_service.dart   # Groq API client, retry logic, JSON + fallback parsing
    services/
      admob_service.dart    # Singleton, auto test IDs in debug, production IDs in release
      consent_manager.dart  # GDPR consent form
    providers/theme_provider.dart  # ChangeNotifier, persisted to SharedPreferences
    widgets/ad_banner_widget.dart  # Adaptive anchored banner with retry
  features/
    navigation/main_screen.dart    # 4-tab bottom nav (Captions/Bios/Quotes/Saved)
    tabs/caption_tab.dart          # PlatformContentTab for captions
    tabs/bio_tab.dart              # PlatformContentTab for bios
    tabs/quote_tab.dart            # Custom tab with quote categories
    tabs/platform_content_tab.dart # Shared platform-selector widget
    input/input_screen.dart        # Prompt + style/emoji/hashtag toggles → AiService
    result/result_screen.dart      # Copy / share / ❤️-save results
    saved/saved_screen.dart        # TabBarView of grouped saved items, swipe-to-delete
    settings/settings_screen.dart  # Theme mode picker, share, rate, privacy policy

Commands

State management

• Provider (ChangeNotifierProvider) — only for ThemeProvider (theme mode persisted in SharedPreferences)
• flutter_hooks (useState, useMemoized) — for ephemeral local state in widgets (selected tab, selected platform, etc.)
• Everything else is stateless or local StatefulWidget state

Dev quirks

• .env required at project root with GROQ_API_KEY and GROQ_API_URL. Already tracked — do not commit real keys.
• AdMob production IDs are in lib/core/services/admob_service.dart:10-13. Debug builds auto-use Google test IDs.
• The stock widget test (test/widget_test.dart) is stale — it tests a counter app that doesn't exist. Don't rely on it.
• lib/core/theme/app_theme.dart uses google_fonts (requires internet on first run or cached fonts).
• Empty directories: lib/features/home/ — intentionally unused.

Lint & conventions

Enforced via analysis_options.yaml:

• prefer_const_constructors, prefer_const_declarations
• prefer_final_locals
• curly_braces_in_flow_control_structures

Run dart format . after writing Dart code.

Tests

One meaningful test: test/core/utils/ai_service_test.dart — live integration test that calls the real Groq API. Requires .env file at project root. Run with flutter test.