{ "markdown": "# Kudlit\n\n

\n \"Kudlit\n

\n\n

Learn, read, and translate Baybayin with a mobile-first Filipino learning companion.

\n\n

\n Download Android v1.0.0\n ·\n Design System\n ·\n System Audit\n

\n\n

\n \"Kudlit\n \"Butty\n

\n\nKudlit is a Flutter app for Baybayin discovery: scan glyphs, translate Filipino text, practice lessons, and get guidance from Butty, the app's learning companion. It combines a playful Filipino visual identity with practical mobile workflows for learners who want to recognize, write, and understand Baybayin without jumping between separate tools.\n\n## Why Kudlit\n\n- **Scan Baybayin glyphs** with a camera-first scanner on Android and a web preview path for browser testing.\n- **Translate in both directions** between Filipino text and Baybayin Unicode, with clearer input surfaces for longer writing.\n- **Learn by doing** through lessons, glyph references, quiz surfaces, and sketch-oriented practice flows.\n- **Ask Butty for help** through AI-assisted explanation surfaces designed to show user-facing answers, not raw prompt scaffolding.\n- **Built mobile first** with responsive auth, scan, translate, learn, profile, settings, and legal flows hardened across portrait and landscape checks.\n- **Brand-led interface** using the bundled Kudlit design system, Baybayin display font, and original Butty/learning artwork.\n\n## Release\n\nThe current public Android package is available from the GitHub Release:\n\n- **Version:** `v1.0.0`\n- **APK:** [`app-release.apk`](https://github.com/ACSADians/kudlit-app/releases/download/v1.0.0/app-release.apk)\n- **Verified device metadata:** `versionName=1.0.0`, `versionCode=2`\n\n## Screenshots\n\n

\n \"Kudlit\n \"Kudlit\n \"Kudlit\n \"Kudlit\n \"Kudlit\n

\n\n## 90-Second Demo Flow\n\n1. **Install:** Open the `v1.0.0` GitHub Release, download the Android APK, and install Kudlit.\n2. **Enter:** Start on the branded welcome screen and continue as a guest for the fastest demo path.\n3. **Scan:** Open Scan, show the camera/gallery controls, and explain that Kudlit is built for Baybayin recognition with clear fallback states.\n4. **Translate:** Switch to Translate, type a Filipino phrase, and show the Baybayin Unicode output flow.\n5. **Learn:** Open Learn to show lessons, glyph references, and quiz-oriented practice.\n6. **Ask Butty:** Switch to Butty and show the companion as the support layer for explanations and learning guidance.\n7. **Close:** Point back to the APK release and the bundled design system as proof that the app is packaged, branded, and ready for hands-on testing.\n\n## Product Surfaces\n\n| Surface | What it does |\n|---|---|\n| Scan | Camera and gallery-based Baybayin recognition with responsive scanner controls and clear fallback states. |\n| Translate | Filipino-to-Baybayin and Baybayin-to-Filipino translation surfaces with copy/share/explain affordances. |\n| Learn | Lessons, glyph references, quiz entry points, and mobile-friendly study cards. |\n| Butty | Companion guidance for explanations, learning support, and AI-assisted help surfaces. |\n| Auth/Profile/Settings | Branded account entry, legal pages, profile polish, and safer navigation patterns. |\n\n## Current Setup\n\n- App shell and auth flow use a shared Flutter design-system layer under `lib/core/design_system/`.\n- The bundled Baybayin display font and reference assets are copied into `assets/fonts/` and `assets/brand/` for normal Flutter usage.\n- The home shell, scanner, translator, learning, profile, and settings surfaces are active Flutter feature slices using the shared Kudlit visual system.\n- The original design-system source remains in [`Kudlit Design System/`]() for previews, reference JSX, and asset provenance.\n\n## Tech Stack\n\n| Layer | Technology |\n|---|---|\n| Framework | Flutter (Dart) |\n| State management | Riverpod (`riverpod_annotation`) |\n| Routing | `go_router` |\n| Backend auth | Supabase |\n| Character detection | YOLO → TFLite (`ultralytics_yolo`) |\n| Language understanding | Gemma 4 |\n| Error handling | `Either` via `fpdart` |\n\n## Getting Started\n\n```bash\nflutter doctor\nflutter pub get\nflutter run -d chrome\n```\n\nUseful commands:\n\n```bash\nflutter analyze\nflutter test\nflutter build web\ndart format lib/ test/\n```\n\n## Deployment\n\nThe repository includes two web deployment paths:\n\n- `build.sh` for Cloudflare Pages. Configure the build command as `bash build.sh` and the output directory as `build/web`.\n- `.github/workflows/deploy-pages.yml` for GitHub Pages. It runs on pushes to `main` and can also be started manually from GitHub Actions. A repository or organization administrator must first enable Pages with **GitHub Actions** as the source; the workflow token cannot enable Pages itself.\n\nBoth deployment paths expect these repository or platform secrets:\n\n- `SUPABASE_URL`\n- `SUPABASE_ANON_KEY`\n- `GEMINI_API_KEY`\n- `HUGGINGFACE_TOKEN` is optional.\n\nAfter a deployment is live, smoke-check the main web routes:\n\n```bash\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/prod-smoke.ps1 -BaseUrl \"https://acsadians.github.io/kudlit-app\"\n```\n\n### Translate Header UI verification\n\nFrom `kudlit-app/`, run:\n\n```bash\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/verify-translate-header-ui.ps1\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/verify-translate-header-ui.ps1 -Tabs \"scan,translate,learn,butty\" -Widths \"768,1024,1366,1920\" -SkipTests\n```\n\nThe script:\n\n- runs `test/features/home/presentation/widgets/translate_density_test.dart` unless `-SkipTests` is set,\n- captures screenshots under `test-results/ui-verify/` with names like `translate-header--.png`,\n- starts a local static preview only if the target URL is not already reachable.\n\n### Translate header UI hardening\n\n```bash\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/verify-translate-header-ui.ps1\n```\n\nCapture-only pass (skip `translate_density_test.dart`):\n\n```bash\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/verify-translate-header-ui.ps1 -SkipTests\n```\n\nCustom capture width set:\n\n```bash\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/verify-translate-header-ui.ps1 -Widths \"768,1024,1366,1920,1536\"\n```\n\n### Scan layout hardening\n\n```bash\npwsh -NoProfile -ExecutionPolicy Bypass -File scripts/scan-layout-overlap-pass.ps1\n```\n\nThis strict pass runs `test/features/scanner/presentation/widgets/scan_tab_responsive_matrix_test.dart`, captures matrix and transition screenshots, and writes:\n\n- `qa-artifact/scan-layout-strict-overlap/report.json`\n- `qa-artifact/scan-layout-strict-overlap/scan-layout-overlap-contact-sheet.html`\n- `qa-artifact/scan-layout-strict-overlap/matrix/`\n- `qa-artifact/scan-layout-strict-overlap/transitions/`\n\nLatest verified timestamp: `2026-05-10T18:08:55.7427350+08:00`.\n\nDefault matrix set in script:\n\n- `360x740`, `390x844`, `430x932`, `844x390`, `1024x768`\n- strict tiny stress widths: `340x260`, `320x240`\n\nTransition stress test uses:\n\n- URL query `qa_camera_status=unavail-ready`\n- phases: `early`, `mid`, `late`\n- waits: 300ms, 1200ms, 2100ms\n\n## Folder Structure\n\n```text\nlib/\n├── app/ App bootstrapping, router, app constants\n├── core/\n│ ├── config/ Environment and Supabase setup\n│ ├── design_system/ Flutter theme, color tokens, shared UI shells\n│ ├── error/ Shared failures and exceptions\n│ └── usecases/ Base use case abstractions\n├── features/\n│ ├── auth/ Auth feature slice\n│ ├── scanner/ Scanner detection, model, and camera logic\n│ ├── translator/ AI/chat translation and memory logic\n│ └── learning/ Lesson and reference logic\n└── main.dart\n\nassets/\n├── brand/ Copied Kudlit illustrations and reference art\n└── fonts/ Baybayin display font used in the UI\n\nKudlit Design System/ Reference docs, CSS tokens, previews, JSX UI kit\n```\n\n## Architecture\n\nThe app follows feature-first clean architecture:\n\n- `presentation -> domain <- data`\n- `domain` stays pure Dart\n- repositories are defined in `domain` and implemented in `data`\n- app-wide visual decisions live in `core/design_system/`, not inside feature widgets\n\nCurrent feature intent:\n\n- `auth`: implemented and now wrapped in the branded Kudlit auth shell\n- `scanner`: native live YOLO scanning plus web webcam preview with capture-based TFLite detection from the active vision model URL\n- `translator`: active Baybayin transliteration and Gemma-assisted interpretation surfaces\n- `learn`: active lessons, quizzes, and reference content\n\n## Design System Notes\n\n- Token source: [`Kudlit Design System/colors_and_type.css`]()\n- Brand guidance: [`Kudlit Design System/README.md`]()\n- Local repo workflow notes: [SKILL.md](SKILL.md)\n- Gemini CLI entrypoint: [GEMINI.md](GEMINI.md)\n- Repo-local Gemini frontend skill: [skills/flutter-frontend/SKILL.md](skills/flutter-frontend/SKILL.md)\n\nImportant limitation:\n\n- The design docs specify Geist for the UI font, but this repository currently only bundles the Baybayin display font. The shared Flutter theme already applies the Kudlit color, radius, and spacing language, and Baybayin headings use the bundled font directly.\n\n## Gemini CLI Setup\n\nInstall `obra/superpowers` in Gemini CLI:\n\n```bash\ngemini extensions install https://github.com/obra/superpowers\n```\n\nThis repository also includes a local Gemini extension:\n\n- [gemini-extension.json](gemini-extension.json)\n- [GEMINI.md](GEMINI.md)\n- [skills/flutter-frontend/SKILL.md](skills/flutter-frontend/SKILL.md)\n\nRecommended usage:\n\n- Use `obra/superpowers` for process skills such as brainstorming, planning, debugging, TDD, and review\n- Use the local `flutter-frontend` skill for Kudlit-specific Flutter UI and design-system implementation\n\n## Working Rules\n\n- Keep UI mobile-first even when using Chrome as the design target.\n- Do not bypass `core/design_system/` for shared colors, type, surfaces, or brand assets.\n- Keep widgets focused on display; move business logic into Riverpod notifiers and use cases.\n- Prefer relative imports within a feature and `package:kudlit_ph/...` across features.\n- Use single quotes and explicit types.\n\nFor repo-level coding rules and architecture constraints, read [CLAUDE.md](CLAUDE.md).\n", "bytes": 11295, "sha": "32c8d4d7f2d95ebcdebcfd6e5f902fb2872a0174981bca395c18c1d613143590", "repo_slug": "acsadians/kudlit-app", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_acsadians_kudlit_app_e14b1f51/readme" }