From a51901e54c05da482b899b5105485c8144b0d633 Mon Sep 17 00:00:00 2001
From: "shakespeare.diy" <assistant@shakespeare.diy>
Date: Sat, 25 Jul 2026 13:26:41 +0700
Subject: [PATCH] Document recurring Zapstore release flow in ZAPSTORE.md

Add a prominent "Releasing a new version" runbook (bump both package.json
and build.gradle, git pull, npm run android:build, SIGN_WITH=... zsp publish
zapstore.yaml) with troubleshooting table. Keeps first-time keystore/setup
steps below for new machines.

Co-authored-by: shakespeare.diy <assistant@shakespeare.diy>
---
 ZAPSTORE.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/ZAPSTORE.md b/ZAPSTORE.md
index 25caa5c..892f0df 100644
--- a/ZAPSTORE.md
+++ b/ZAPSTORE.md
@@ -2,6 +2,101 @@
 
 Get SkateSpots on [Zapstore](https://zapstore.dev) as a native Android APK.
 
+---
+
+## 🚀 Releasing a new version (the recurring flow)
+
+> This is the process to follow **every time** you ship an update. For a
+> brand-new machine setup (keystore, `android:init`, etc.) see
+> **First-time setup** further down.
+
+### Prerequisites
+- `zsp` installed at `~/go/bin/zsp`
+- `SIGN_WITH` env var with your nsec
+- Android SDK + Gradle installed
+
+### Step 1 — Bump versions (BOTH files)
+
+Bump the web version in `package.json`:
+
+```
+"version": "1.0.XX"  →  "1.0.<XX+1>"
+```
+
+Bump the Android version in `android/app/build.gradle`:
+
+```bash
+# Check current version first
+grep -n "versionCode\|versionName" android/app/build.gradle
+
+# Bump it (replace OLD/NEW with actual numbers)
+sed -i 's/versionCode OLD/versionCode NEW/' android/app/build.gradle
+sed -i 's/versionName "1.0.OLD"/versionName "1.0.NEW"/' android/app/build.gradle
+
+# Verify
+grep -n "versionCode\|versionName" android/app/build.gradle
+```
+
+> ⚠️ **Both numbers must be bumped** — `package.json` for the web app,
+> `build.gradle` for the APK. **Zapstore reads the version from the APK
+> (`build.gradle`)**, so if you forget that one you'll get `Asset already exists`.
+
+### Step 2 — Pull latest from git
+
+```bash
+git pull
+```
+
+### Step 3 — Build the APK
+
+```bash
+npm run android:build
+```
+
+This runs: (1) Vite build → (2) Capacitor sync → (3) Gradle `assembleRelease`.
+✅ Look for **BUILD SUCCESSFUL** at the end.
+
+### Step 4 — Publish to Zapstore
+
+```bash
+SIGN_WITH=nsec1... ~/go/bin/zsp publish zapstore.yaml
+```
+
+The wizard will: parse & verify the APK → fetch Play Store metadata → sign with
+your nsec → publish to `wss://relay.zapstore.dev` → upload the APK to
+`cdn.zapstore.dev`.
+
+- When prompted **"Preview release in browser?"** → select **No, skip**
+- When prompted **"Choose an option"** → select **Publish now**
+
+### Full one-liner (once versions are bumped)
+
+```bash
+git pull && npm run android:build && SIGN_WITH=nsec1... ~/go/bin/zsp publish zapstore.yaml
+```
+
+### Verify it's live
+
+https://zapstore.dev/apps/org.skatespots.app
+
+### Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `zapstore: command not found` | Use `~/go/bin/zsp` instead |
+| `zsp: command not found` | Run `go install github.com/zapstore/zsp@latest` |
+| `Asset already exists` | Version not bumped — check `build.gradle` |
+| Vite build fails | Run `git pull` first to get latest fixes |
+| Merge conflict on `package-lock.json` | `git checkout --theirs package-lock.json && git add package-lock.json && git commit` |
+
+---
+
+## First-time setup
+
+The sections below are only needed the **first time** you set up a machine
+(installing tooling, creating the signing keystore, initializing the Android
+project). For normal releases, use the flow above.
+
 ## Prerequisites (install on your machine)
 
 1. **Node.js 18+** — https://nodejs.org