nkbmusic/docs/HANDOFF.md

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, 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: 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, 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 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.

How to

• Release builds: see 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/, 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 <en-IN> 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), 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.