diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md new file mode 100644 index 0000000..5ae902e --- /dev/null +++ b/docs/HANDOFF.md @@ -0,0 +1,97 @@ +# Handoff: where Nanga Kathai stands and what comes next + +Last updated: 2026-11-03. Start the next session with: *"Read docs/HANDOFF.md and continue from Next steps."* + +## Where things stand + +| What | Status | Link | +|------|--------|------| +| Android app 1.0.0 | Live on Google Play (177 countries) | https://play.google.com/store/apps/details?id=com.metatroncubesolutions.nanga_kathai | +| iPhone app 1.0.0 (build 10) | Live on the App Store (175 regions) | https://apps.apple.com/app/id6829229617 | +| Website | Live, both store badges linked | https://nkbmusic.com | +| Backend | Self-hosted Supabase, running | https://app.nkbmusic.com | + +- **Play Console:** org account 7638421478373330730, app 4976442413590577476. +- **App Store Connect:** app ID 6829229617. +- **Support tips** ("Support Nanga Kathai", consumable in-app purchases): + - **Android:** the screen shows, but says "not available" because no products exist yet. + - **iOS:** the screen is hidden ([settings_screen.dart](../lib/features/settings/settings_screen.dart), the `TargetPlatform.iOS` check). +- **External payment links** (PayPal or Stripe) inside the app are not allowed for India, and only partly allowed in the US, UK and EEA. We decided against them. + - A support link on the **website only** is fine. + - The app must never mention or link to it. + +## Next steps (in order) + +### 1. Set up store payments: the owner does these, in the browser (no build needed) + +**Google Play.** The owner sets up a Google Payments merchant account: Play Console → Monetize → Payments profile. +- Then create the 3 one-time products from [support-payments.md](support-payments.md): `nk_support_small`, `nk_support_medium`, `nk_support_large`, using the prices in that file. +- After this, tips work on Android at once. No new build is needed. + +**Apple.** The owner (the Account Holder) does these in App Store Connect: +- Business → sign the **Paid Apps Agreement**. +- Add the bank account and complete the tax forms. +- Complete the **EU Digital Services Act trader status**. + +Then create the same 3 consumable in-app purchases. Apple only reviews a developer's first in-app purchases together with a new build, so they ship with 1.0.1. + +Claude can fill in the product names, prices and descriptions in the consoles. Bank, tax and legal agreements must be done by the owner. + +### 2. iOS and Android 1.0.1 build: Claude can do this + +- **Re-enable Support on iOS.** Better still, show the Support entry on every platform **only when the store returns products**, instead of hiding it by platform. +- **Add an App Store / Play rating prompt** using the `in_app_review` package. + - Show it after real use, for example 10 songs played over at least 3 different days. + - Show it at most once per version, and never right after an error. +- **Bump the version** to `1.0.1+N` in [pubspec.yaml](../pubspec.yaml), and change the hard-coded "1.0.0" text in settings_screen.dart. +- **Release:** + - Push a `v1.0.1` tag; Codemagic builds iOS to TestFlight and Android to Play internal testing. + - In App Store Connect, attach the 3 in-app purchases to version 1.0.1 and submit for review. + - Promote the Android build to production. +- **Restore the store text.** Once tips are live, put the gift line back in [appstore-description.txt](store/appstore-description.txt) and in App Store Connect. + +### 3. Grow reviews and the audience (ongoing) + +- Share the store links in the Badaga WhatsApp and community groups. Ask for **honest** reviews and offer nothing in return. +- Anyone connected to Metatroncube must not post reviews (Apple guideline 5.6.3). +- Reply to reviews in App Store Connect → Ratings and Reviews, and in Play Console → Reviews. +- Optional: improve the store subtitle, keywords and screenshot captions. + +### 4. Next major release: creator platform + +From the earlier product decisions: +- Verified creator accounts: application, admin check, uploads and claims on older songs. +- Listener donations to verified creators, with a 10% platform fee. +- Play counting for stats only, not payouts. + +Plan this after 1.0.1. See [NK_IMPLEMENTATION_PLAN.md](NK_IMPLEMENTATION_PLAN.md). + +## How to + +- **Release builds:** see [app-store-release.md](app-store-release.md). Codemagic workflows `ios-release` and `android-release` run on `v*` tags. +- **Push code:** `git push` on `main` goes to both Gitea (the server pulls from it) and GitHub (Codemagic builds from it). +- **Update the backend:** `ssh dev@72.62.169.43`, then `sh ~/APPS/nanga_kathai/server/update.sh`. +- **Update the website:** + 1. Run `python tools/build_site.py`. The store links are now its defaults. + 2. Upload `site/` to `~/nk-site` on the server. + 3. The owner runs `ssh -t dev@72.62.169.43 "sudo sh ~/APPS/nanga_kathai/server/deploy-site.sh"`, which needs the sudo password. + + Claude can do steps 1 and 2. +- **Store text:** kept in [docs/store/](store/), so keep it in step with the consoles. + +## Where the secrets are (never commit them) + +- `C:\Users\manes\nk-keys\`: + - Android upload keystore and its password backup; + - iOS distribution key; + - App Review demo account (`app-review-account.txt`). +- `android/key.properties` and `env.json` are git-ignored. +- Backend secrets: `.env` in `~/APPS/nk-backend/supabase-project` on the server. + +## Known gotchas + +- **Play Console's default language is en-IN**, so release notes need `` tags. +- **Privacy and deletion URLs** use the `.html` form (`https://nkbmusic.com/privacy.html`, `/delete-account.html`). Play's checker rejected the URLs without `.html`. +- **iOS audio:** the Android-only audio effects must stay Android-only (`soundEffectsSupported` in [nk_audio_handler.dart](../lib/audio/nk_audio_handler.dart)), or iOS playback breaks. +- **Phone recording:** for adb screen recording from Git Bash, run `export MSYS_NO_PATHCONV=1` first. +- **The `dev` user has no passwordless sudo,** so the website publish step always needs the owner.