Add a handoff document with status and next steps

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

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 `<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](../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.