readme: add build & deploy section (server docker, android APK, gitea release)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitignore

@@ -23,6 +23,7 @@ android/captures/
 .vscode/
 *.iml
 
-# os
+# os and emacs
 .DS_Store
 Thumbs.db
+/archive

README.md

@@ -2,10 +2,9 @@
 
 open app. 
 type, optionally mark as todo, optionally add tags, save. 
-if home server accessible, post unsynced captures to lan-only service and appended to `phone.org`.
+if home server accessible, post unsynced captures to lan-only service and appended to `synq.org`.
 
 ## non-goals
-
 - no org parser on android
 - no agenda on android
 - no sync provider dependency
@@ -157,6 +156,83 @@ synq/
 5. add history screen and resend handling.
 6. polish launch speed and widget/share-target only after core path works.
 
+## build & deploy
+
+### server (docker)
+
+```bash
+# build
+docker build -t synq-server ./server
+
+# run (replace paths and token as needed)
+docker run -d --name synq --restart=unless-stopped \
+  -p 8765:8765 \
+  -v /mnt/user/synq/data:/data \
+  synq-server
+```
+
+the server generates a random token on first start and logs it prominently. copy it into the android app settings. to use a fixed token instead, pass `-e PHONE_CAPTURE_TOKEN=yourtoken`.
+
+to rebuild after a `git pull`:
+
+```bash
+git pull
+docker build -t synq-server ./server
+docker stop synq && docker rm synq
+# re-run the docker run command above
+```
+
+### android
+
+open `android/` in Android Studio and hit **Sync**. then either:
+
+- **run on device/emulator directly** from Android Studio (▶), or
+- **build a release APK** from the terminal:
+
+```bash
+cd android
+./gradlew assembleRelease
+# output: app/build/outputs/apk/release/app-release-unsigned.apk
+```
+
+sideload to a connected device:
+
+```bash
+adb install app/build/outputs/apk/release/app-release-unsigned.apk
+```
+
+### releasing on gitea
+
+tag the commit and push the tag:
+
+```bash
+git tag v1.0.0
+git push gitea v1.0.0
+```
+
+then go to **Releases → New Release** in the Gitea UI, pick the tag, and drag the APK into the assets box. anyone on the LAN can download it from there.
+
+## backup
+
+### what to back up
+
+the server writes to one directory (the `/data` volume). back up the whole thing:
+
+```text
+/data/synq.org        ← the canonical org capture file
+/data/capture.sqlite3 ← idempotency store (dedup ids)
+/data/token.txt       ← auto-generated token (if not using PHONE_CAPTURE_TOKEN env var)
+```
+
+on unraid the host path is whatever you mapped in compose, e.g. `/mnt/user/ben/synq/phone-capture`.
+
+### restore behavior
+
+- restore the `/data` volume to a new container and start it. the server will pick up where it left off.
+- `synq.org` is append-only plain text — it is human-readable and recoverable even without the sqlite db.
+- if `capture.sqlite3` is lost but `synq.org` is intact, the server will accept re-posted captures that were already in the org file (no dedup). the android app marks them synced either way (`already_seen` or `accepted`), so the only side effect is duplicate org entries for anything re-synced. restore the db from backup to avoid this.
+- if `token.txt` is lost, delete it and let the server generate a new one on next start, then update the app settings.
+
 ## v2 parking lot
 
 - android share target

android/app/src/main/AndroidManifest.xml

@@ -8,7 +8,8 @@
         android:label="@string/app_name"
         android:theme="@style/Theme.Synq"
         android:allowBackup="true"
-        android:supportsRtl="true">
+        android:supportsRtl="true"
+        android:usesCleartextTraffic="true">
 
         <activity
             android:name=".MainActivity"
@@ -18,6 +19,11 @@
                 <action android:name="android.intent.action.MAIN" />
                 <category android:name="android.intent.category.LAUNCHER" />
             </intent-filter>
+            <intent-filter>
+                <action android:name="android.intent.action.SEND" />
+                <category android:name="android.intent.category.DEFAULT" />
+                <data android:mimeType="text/plain" />
+            </intent-filter>
         </activity>
 
     </application>

android/app/src/main/kotlin/me/hgsky/synq/MainActivity.kt

@@ -1,33 +1,56 @@
 package me.hgsky.synq
 
+import android.content.Intent
 import android.os.Bundle
 import androidx.activity.ComponentActivity
 import androidx.activity.compose.setContent
 import androidx.activity.enableEdgeToEdge
 import androidx.compose.runtime.Composable
+import androidx.navigation.NavType
 import androidx.navigation.compose.NavHost
 import androidx.navigation.compose.composable
 import androidx.navigation.compose.rememberNavController
+import androidx.navigation.navArgument
 import me.hgsky.synq.ui.capture.CaptureScreen
 import me.hgsky.synq.ui.history.HistoryScreen
 import me.hgsky.synq.ui.settings.SettingsScreen
 import me.hgsky.synq.ui.theme.SynqTheme
+import java.net.URLDecoder
+import java.net.URLEncoder
 
 class MainActivity : ComponentActivity() {
     override fun onCreate(savedInstanceState: Bundle?) {
         super.onCreate(savedInstanceState)
         enableEdgeToEdge()
+
+        val sharedText = if (intent.action == Intent.ACTION_SEND)
+            intent.getStringExtra(Intent.EXTRA_TEXT) else null
+
         setContent {
-            SynqTheme { SynqNav() }
+            SynqTheme { SynqNav(sharedText = sharedText) }
         }
     }
 }
 
 @Composable
-private fun SynqNav() {
+private fun SynqNav(sharedText: String? = null) {
     val nav = rememberNavController()
-    NavHost(navController = nav, startDestination = "capture") {
+    val startRoute = if (sharedText != null) {
+        "capture/${URLEncoder.encode(sharedText, "UTF-8")}"
+    } else {
+        "capture"
+    }
+
+    NavHost(navController = nav, startDestination = startRoute) {
         composable("capture") { CaptureScreen(nav) }
+        composable(
+            route = "capture/{prefill}",
+            arguments = listOf(navArgument("prefill") { type = NavType.StringType }),
+        ) { back ->
+            val prefill = back.arguments?.getString("prefill")
+                ?.let { URLDecoder.decode(it, "UTF-8") }
+            CaptureScreen(nav, prefill = prefill)
+        }
         composable("history") { HistoryScreen(nav) }
         composable("settings") { SettingsScreen(nav) }
     }

android/app/src/main/kotlin/me/hgsky/synq/data/SettingsRepository.kt

@@ -2,6 +2,7 @@ package me.hgsky.synq.data
 
 import android.content.Context
 import androidx.datastore.preferences.core.edit
+import androidx.datastore.preferences.core.intPreferencesKey
 import androidx.datastore.preferences.core.stringPreferencesKey
 import androidx.datastore.preferences.preferencesDataStore
 import kotlinx.coroutines.flow.Flow
@@ -13,6 +14,7 @@ data class SynqSettings(
     val serverUrl: String = "http://jeeves.mother:8765",
     val token: String = "",
     val deviceLabel: String = "android",
+    val syncIntervalMinutes: Int = 15,
 )
 
 class SettingsRepository(private val context: Context) {
@@ -20,12 +22,14 @@ class SettingsRepository(private val context: Context) {
     private val KEY_URL = stringPreferencesKey("server_url")
     private val KEY_TOKEN = stringPreferencesKey("token")
     private val KEY_DEVICE = stringPreferencesKey("device_label")
+    private val KEY_INTERVAL = intPreferencesKey("sync_interval_minutes")
 
     val settings: Flow<SynqSettings> = context.dataStore.data.map { prefs ->
         SynqSettings(
             serverUrl = prefs[KEY_URL] ?: "http://jeeves.mother:8765",
             token = prefs[KEY_TOKEN] ?: "",
             deviceLabel = prefs[KEY_DEVICE] ?: "android",
+            syncIntervalMinutes = prefs[KEY_INTERVAL] ?: 15,
         )
     }
 
@@ -34,6 +38,7 @@ class SettingsRepository(private val context: Context) {
             prefs[KEY_URL] = settings.serverUrl
             prefs[KEY_TOKEN] = settings.token
             prefs[KEY_DEVICE] = settings.deviceLabel
+            prefs[KEY_INTERVAL] = settings.syncIntervalMinutes
         }
     }
 }

android/app/src/main/kotlin/me/hgsky/synq/data/db/CaptureDao.kt

@@ -27,4 +27,13 @@ interface CaptureDao {
 
     @Query("UPDATE captures SET status = 'synced', syncedAt = :syncedAt, lastError = NULL WHERE id = :id")
     suspend fun markSynced(id: String, syncedAt: String)
+
+    @Query("SELECT MAX(syncedAt) FROM captures WHERE syncedAt IS NOT NULL")
+    fun getLastSyncedAt(): Flow<String?>
+
+    @Query("SELECT tagsJson FROM captures WHERE tagsJson != '[]' AND tagsJson != '' ORDER BY createdAt DESC LIMIT 100")
+    fun getRecentTagsJson(): Flow<List<String>>
+
+    @Query("UPDATE captures SET body = :body WHERE id = :id")
+    suspend fun updateBody(id: String, body: String)
 }

android/app/src/main/kotlin/me/hgsky/synq/data/sync/SyncWorker.kt

@@ -29,18 +29,20 @@ class SyncWorker(ctx: Context, params: WorkerParameters) : CoroutineWorker(ctx,
     companion object {
         private const val WORK_NAME = "synq_periodic_sync"
 
-        fun schedule(context: Context) {
+        fun schedule(context: Context, intervalMinutes: Int = 15) {
             val constraints = Constraints.Builder()
                 .setRequiredNetworkType(NetworkType.CONNECTED)
                 .build()
 
-            val request = PeriodicWorkRequestBuilder<SyncWorker>(15, TimeUnit.MINUTES)
+            val request = PeriodicWorkRequestBuilder<SyncWorker>(
+                intervalMinutes.toLong().coerceAtLeast(15), TimeUnit.MINUTES,
+            )
                 .setConstraints(constraints)
                 .build()
 
             WorkManager.getInstance(context).enqueueUniquePeriodicWork(
                 WORK_NAME,
-                ExistingPeriodicWorkPolicy.KEEP,
+                ExistingPeriodicWorkPolicy.REPLACE,
                 request,
             )
         }

android/app/src/main/kotlin/me/hgsky/synq/ui/capture/CaptureScreen.kt

@@ -1,8 +1,11 @@
 package me.hgsky.synq.ui.capture
 
 import androidx.activity.ComponentActivity
+import androidx.compose.foundation.horizontalScroll
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ExperimentalLayoutApi
+import androidx.compose.foundation.layout.FlowRow
 import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.Spacer
 import androidx.compose.foundation.layout.fillMaxSize
@@ -10,6 +13,7 @@ import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.rememberScrollState
 import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.History
@@ -18,6 +22,7 @@ import androidx.compose.material.icons.filled.Sync
 import androidx.compose.material3.Button
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.ExperimentalMaterial3Api
+import androidx.compose.material3.FilterChip
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
@@ -41,15 +46,40 @@ import androidx.compose.ui.text.input.KeyboardCapitalization
 import androidx.compose.ui.unit.dp
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.navigation.NavController
+import java.time.OffsetDateTime
+import java.time.format.DateTimeFormatter
+import java.time.format.FormatStyle
 
-@OptIn(ExperimentalMaterial3Api::class)
+@OptIn(ExperimentalMaterial3Api::class, ExperimentalLayoutApi::class)
 @Composable
-fun CaptureScreen(nav: NavController, vm: CaptureViewModel = viewModel()) {
+fun CaptureScreen(
+    nav: NavController,
+    prefill: String? = null,
+    vm: CaptureViewModel = viewModel(),
+) {
     val state by vm.state.collectAsState()
+    val recentTags by vm.recentTags.collectAsState()
+    val lastSyncedAt by vm.lastSyncedAt.collectAsState()
     val focusRequester = remember { FocusRequester() }
     val context = LocalContext.current
 
     LaunchedEffect(Unit) { focusRequester.requestFocus() }
+    LaunchedEffect(prefill) {
+        if (!prefill.isNullOrEmpty()) vm.setBody(prefill)
+    }
+
+    val activeTags = remember(state.tags) {
+        state.tags.split(Regex("[,\\s]+")).filter { it.isNotEmpty() }.toSet()
+    }
+
+    val lastSyncedText = remember(lastSyncedAt) {
+        lastSyncedAt?.let { iso ->
+            runCatching {
+                val dt = OffsetDateTime.parse(iso)
+                "synced " + dt.format(DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT))
+            }.getOrNull()
+        }
+    }
 
     Scaffold(
         topBar = {
@@ -120,6 +150,29 @@ fun CaptureScreen(nav: NavController, vm: CaptureViewModel = viewModel()) {
                 singleLine = true,
             )
 
+            if (recentTags.isNotEmpty()) {
+                FlowRow(
+                    modifier = Modifier.fillMaxWidth(),
+                    horizontalArrangement = Arrangement.spacedBy(6.dp),
+                ) {
+                    recentTags.forEach { tag ->
+                        FilterChip(
+                            selected = tag in activeTags,
+                            onClick = { vm.toggleTag(tag) },
+                            label = { Text(tag, style = MaterialTheme.typography.labelSmall) },
+                        )
+                    }
+                }
+            }
+
+            if (lastSyncedText != null) {
+                Text(
+                    lastSyncedText,
+                    style = MaterialTheme.typography.labelSmall,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                )
+            }
+
             Row(
                 modifier = Modifier.fillMaxWidth(),
                 horizontalArrangement = Arrangement.spacedBy(8.dp),

android/app/src/main/kotlin/me/hgsky/synq/ui/capture/CaptureViewModel.kt

@@ -5,9 +5,12 @@ import androidx.lifecycle.AndroidViewModel
 import androidx.lifecycle.viewModelScope
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.first
+import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
 import kotlinx.serialization.encodeToString
 import kotlinx.serialization.json.Json
@@ -34,10 +37,31 @@ class CaptureViewModel(app: Application) : AndroidViewModel(app) {
     private val _state = MutableStateFlow(CaptureUiState())
     val state: StateFlow<CaptureUiState> = _state.asStateFlow()
 
+    val recentTags: StateFlow<List<String>> = dao.getRecentTagsJson()
+        .map { jsonList ->
+            val seen = LinkedHashSet<String>()
+            for (json in jsonList) {
+                runCatching { Json.decodeFromString<List<String>>(json) }
+                    .getOrElse { emptyList() }
+                    .forEach { seen.add(it) }
+            }
+            seen.take(20).toList()
+        }
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), emptyList())
+
+    val lastSyncedAt: StateFlow<String?> = dao.getLastSyncedAt()
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+
     fun setBody(v: String) { _state.value = _state.value.copy(body = v) }
     fun setTodo(v: Boolean) { _state.value = _state.value.copy(isTodo = v) }
     fun setTags(v: String) { _state.value = _state.value.copy(tags = v) }
 
+    fun toggleTag(tag: String) {
+        val current = parseTags(_state.value.tags).toMutableList()
+        if (current.contains(tag)) current.remove(tag) else current.add(tag)
+        _state.value = _state.value.copy(tags = current.joinToString(" "))
+    }
+
     fun save(onDone: () -> Unit = {}) {
         val s = _state.value
         val body = s.body.trim()

android/app/src/main/kotlin/me/hgsky/synq/ui/history/HistoryScreen.kt

@@ -1,5 +1,6 @@
 package me.hgsky.synq.ui.history
 
+import androidx.compose.foundation.clickable
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.Column
@@ -12,18 +13,26 @@ import androidx.compose.foundation.lazy.LazyColumn
 import androidx.compose.foundation.lazy.items
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.automirrored.filled.ArrowBack
+import androidx.compose.material3.AlertDialog
 import androidx.compose.material3.Button
 import androidx.compose.material3.Card
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
 import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
+import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
 import androidx.compose.material3.TopAppBar
 import androidx.compose.runtime.Composable
 import androidx.compose.runtime.collectAsState
 import androidx.compose.runtime.getValue
+import androidx.compose.runtime.mutableStateOf
+import androidx.compose.runtime.remember
+import androidx.compose.runtime.saveable.rememberSaveable
+import androidx.compose.runtime.setValue
 import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
 import androidx.compose.ui.graphics.Color
@@ -32,16 +41,40 @@ import androidx.compose.ui.unit.dp
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.navigation.NavController
 import me.hgsky.synq.data.db.CaptureEntity
+import java.time.OffsetDateTime
+import java.time.format.DateTimeFormatter
+import java.time.format.FormatStyle
 
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 fun HistoryScreen(nav: NavController, vm: HistoryViewModel = viewModel()) {
     val captures by vm.captures.collectAsState(initial = emptyList())
+    val lastSyncedAt by vm.lastSyncedAt.collectAsState()
+
+    val lastSyncedText = remember(lastSyncedAt) {
+        lastSyncedAt?.let { iso ->
+            runCatching {
+                val dt = OffsetDateTime.parse(iso)
+                "last synced " + dt.format(DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT))
+            }.getOrNull()
+        }
+    }
 
     Scaffold(
         topBar = {
             TopAppBar(
-                title = { Text("history") },
+                title = {
+                    Column {
+                        Text("history")
+                        if (lastSyncedText != null) {
+                            Text(
+                                lastSyncedText,
+                                style = MaterialTheme.typography.labelSmall,
+                                color = MaterialTheme.colorScheme.onSurfaceVariant,
+                            )
+                        }
+                    }
+                },
                 navigationIcon = {
                     IconButton(onClick = { nav.navigateUp() }) {
                         Icon(Icons.AutoMirrored.Filled.ArrowBack, contentDescription = "back")
@@ -62,7 +95,11 @@ fun HistoryScreen(nav: NavController, vm: HistoryViewModel = viewModel()) {
                 verticalArrangement = Arrangement.spacedBy(8.dp),
             ) {
                 items(captures, key = { it.id }) { capture ->
-                    CaptureRow(capture, onRetry = { vm.retryCapture(capture) })
+                    CaptureRow(
+                        capture = capture,
+                        onRetry = { vm.retryCapture(capture) },
+                        onEditConfirm = { newBody -> vm.updateBody(capture, newBody) },
+                    )
                 }
             }
         }
@@ -70,14 +107,56 @@ fun HistoryScreen(nav: NavController, vm: HistoryViewModel = viewModel()) {
 }
 
 @Composable
-private fun CaptureRow(capture: CaptureEntity, onRetry: () -> Unit) {
+private fun CaptureRow(
+    capture: CaptureEntity,
+    onRetry: () -> Unit,
+    onEditConfirm: (String) -> Unit,
+) {
+    var expanded by rememberSaveable(capture.id) { mutableStateOf(false) }
+    var showEdit by remember { mutableStateOf(false) }
+    var editBody by remember(capture.body) { mutableStateOf(capture.body) }
+
     val statusColor = when (capture.status) {
         "synced" -> Color(0xFF2E7D32)
         "failed" -> MaterialTheme.colorScheme.error
         else -> MaterialTheme.colorScheme.onSurfaceVariant
     }
 
-    Card(modifier = Modifier.fillMaxWidth()) {
+    val editable = capture.status == "pending" || capture.status == "failed"
+
+    if (showEdit) {
+        AlertDialog(
+            onDismissRequest = { showEdit = false },
+            title = { Text("edit capture") },
+            text = {
+                OutlinedTextField(
+                    value = editBody,
+                    onValueChange = { editBody = it },
+                    modifier = Modifier.fillMaxWidth(),
+                    label = { Text("body") },
+                    minLines = 3,
+                )
+            },
+            confirmButton = {
+                Button(
+                    onClick = {
+                        onEditConfirm(editBody)
+                        showEdit = false
+                    },
+                    enabled = editBody.isNotBlank(),
+                ) { Text("save") }
+            },
+            dismissButton = {
+                TextButton(onClick = { showEdit = false }) { Text("cancel") }
+            },
+        )
+    }
+
+    Card(
+        modifier = Modifier
+            .fillMaxWidth()
+            .clickable { expanded = !expanded },
+    ) {
         Column(
             modifier = Modifier.padding(12.dp),
             verticalArrangement = Arrangement.spacedBy(4.dp),
@@ -96,18 +175,29 @@ private fun CaptureRow(capture: CaptureEntity, onRetry: () -> Unit) {
                     style = MaterialTheme.typography.labelSmall,
                     color = statusColor,
                 )
-                if (capture.status == "pending" || capture.status == "failed") {
+                if (editable) {
-                    Button(onClick = onRetry, contentPadding = PaddingValues(horizontal = 8.dp)) {
+                    OutlinedButton(
+                        onClick = onRetry,
+                        contentPadding = PaddingValues(horizontal = 8.dp),
+                    ) {
                         Text("retry", style = MaterialTheme.typography.labelSmall)
                     }
                 }
+                if (editable && expanded) {
+                    OutlinedButton(
+                        onClick = { showEdit = true },
+                        contentPadding = PaddingValues(horizontal = 8.dp),
+                    ) {
+                        Text("edit", style = MaterialTheme.typography.labelSmall)
+                    }
+                }
             }
 
             Text(
                 capture.body,
                 style = MaterialTheme.typography.bodyMedium,
-                maxLines = 2,
+                maxLines = if (expanded) Int.MAX_VALUE else 2,
-                overflow = TextOverflow.Ellipsis,
+                overflow = if (expanded) TextOverflow.Clip else TextOverflow.Ellipsis,
             )
 
             Text(

android/app/src/main/kotlin/me/hgsky/synq/ui/history/HistoryViewModel.kt

@@ -4,6 +4,9 @@ import android.app.Application
 import androidx.lifecycle.AndroidViewModel
 import androidx.lifecycle.viewModelScope
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
 import me.hgsky.synq.SynqApp
 import me.hgsky.synq.data.db.CaptureEntity
@@ -14,9 +17,18 @@ class HistoryViewModel(app: Application) : AndroidViewModel(app) {
 
     val captures: Flow<List<CaptureEntity>> = dao.observeAll()
 
+    val lastSyncedAt: StateFlow<String?> = dao.getLastSyncedAt()
+        .stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), null)
+
     fun retryCapture(capture: CaptureEntity) {
         viewModelScope.launch {
             dao.updateStatus(capture.id, "pending", null)
         }
     }
+
+    fun updateBody(capture: CaptureEntity, newBody: String) {
+        val trimmed = newBody.trim()
+        if (trimmed.isEmpty()) return
+        viewModelScope.launch { dao.updateBody(capture.id, trimmed) }
+    }
 }

android/app/src/main/kotlin/me/hgsky/synq/ui/settings/SettingsScreen.kt

@@ -2,15 +2,21 @@ package me.hgsky.synq.ui.settings
 
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
 import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.fillMaxWidth
 import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.text.KeyboardOptions
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.automirrored.filled.ArrowBack
 import androidx.compose.material3.Button
+import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.ExperimentalMaterial3Api
 import androidx.compose.material3.Icon
 import androidx.compose.material3.IconButton
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.OutlinedButton
 import androidx.compose.material3.OutlinedTextField
 import androidx.compose.material3.Scaffold
 import androidx.compose.material3.Text
@@ -21,7 +27,10 @@ import androidx.compose.runtime.getValue
 import androidx.compose.runtime.mutableStateOf
 import androidx.compose.runtime.remember
 import androidx.compose.runtime.setValue
+import androidx.compose.ui.Alignment
 import androidx.compose.ui.Modifier
+import androidx.compose.ui.graphics.Color
+import androidx.compose.ui.text.input.KeyboardType
 import androidx.compose.ui.unit.dp
 import androidx.lifecycle.viewmodel.compose.viewModel
 import androidx.navigation.NavController
@@ -31,13 +40,22 @@ import me.hgsky.synq.data.SynqSettings
 @Composable
 fun SettingsScreen(nav: NavController, vm: SettingsViewModel = viewModel()) {
     val saved by vm.settings.collectAsState()
+    val ping by vm.ping.collectAsState()
 
     var url by remember(saved.serverUrl) { mutableStateOf(saved.serverUrl) }
     var token by remember(saved.token) { mutableStateOf(saved.token) }
     var device by remember(saved.deviceLabel) { mutableStateOf(saved.deviceLabel) }
+    var interval by remember(saved.syncIntervalMinutes) { mutableStateOf(saved.syncIntervalMinutes.toString()) }
+
+    fun buildSettings() = SynqSettings(
+        serverUrl = url.trim(),
+        token = token.trim(),
+        deviceLabel = device.trim().ifEmpty { "android" },
+        syncIntervalMinutes = interval.toIntOrNull()?.coerceAtLeast(15) ?: 15,
+    )
 
     fun saveAndBack() {
-        vm.save(SynqSettings(url.trim(), token.trim(), device.trim().ifEmpty { "android" }))
+        vm.save(buildSettings())
         nav.navigateUp()
     }
 
@@ -81,10 +99,55 @@ fun SettingsScreen(nav: NavController, vm: SettingsViewModel = viewModel()) {
                 label = { Text("device label") },
                 singleLine = true,
             )
+            OutlinedTextField(
+                value = interval,
+                onValueChange = { v -> if (v.length <= 4 && v.all { it.isDigit() }) interval = v },
+                modifier = Modifier.fillMaxWidth(),
+                label = { Text("sync interval (minutes, min 15)") },
+                singleLine = true,
+                keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Number),
+                supportingText = { Text("WorkManager minimum is 15 min") },
+            )
+
+            Row(
+                modifier = Modifier.fillMaxWidth(),
+                horizontalArrangement = Arrangement.spacedBy(8.dp),
+                verticalAlignment = Alignment.CenterVertically,
+            ) {
+                OutlinedButton(
+                    onClick = {
+                        vm.save(buildSettings())
+                        vm.checkConnection(url.trim())
+                    },
+                    modifier = Modifier.weight(1f),
+                    enabled = ping !is PingState.Checking,
+                ) {
+                    if (ping is PingState.Checking) {
+                        CircularProgressIndicator(modifier = Modifier.size(16.dp), strokeWidth = 2.dp)
+                    } else {
+                        Text("check connection")
+                    }
+                }
+
                 Button(
                     onClick = ::saveAndBack,
-                modifier = Modifier.fillMaxWidth(),
+                    modifier = Modifier.weight(1f),
                 ) { Text("save") }
             }
+
+            when (val p = ping) {
+                is PingState.Ok -> Text(
+                    "✓ reachable",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = Color(0xFF2E7D32),
+                )
+                is PingState.Failed -> Text(
+                    "✗ unreachable — check URL and that server is running",
+                    style = MaterialTheme.typography.bodySmall,
+                    color = MaterialTheme.colorScheme.error,
+                )
+                else -> {}
+            }
+        }
     }
 }

android/app/src/main/kotlin/me/hgsky/synq/ui/settings/SettingsViewModel.kt

@@ -3,15 +3,29 @@ package me.hgsky.synq.ui.settings
 import android.app.Application
 import androidx.lifecycle.AndroidViewModel
 import androidx.lifecycle.viewModelScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.flow.MutableStateFlow
 import kotlinx.coroutines.flow.SharingStarted
+import kotlinx.coroutines.flow.StateFlow
+import kotlinx.coroutines.flow.asStateFlow
 import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.launch
 import me.hgsky.synq.SynqApp
 import me.hgsky.synq.data.SynqSettings
+import me.hgsky.synq.data.api.SynqApiClient
+import me.hgsky.synq.data.sync.SyncWorker
+
+sealed class PingState {
+    object Idle : PingState()
+    object Checking : PingState()
+    data class Ok(val url: String) : PingState()
+    data class Failed(val url: String) : PingState()
+}
 
 class SettingsViewModel(app: Application) : AndroidViewModel(app) {
 
-    private val repo = (app as SynqApp).settings
+    private val synqApp = app as SynqApp
+    private val repo = synqApp.settings
 
     val settings = repo.settings.stateIn(
         viewModelScope,
@@ -19,7 +33,22 @@ class SettingsViewModel(app: Application) : AndroidViewModel(app) {
         SynqSettings(),
     )
 
+    private val _ping = MutableStateFlow<PingState>(PingState.Idle)
+    val ping: StateFlow<PingState> = _ping.asStateFlow()
+
     fun save(settings: SynqSettings) {
-        viewModelScope.launch { repo.save(settings) }
+        viewModelScope.launch {
+            repo.save(settings)
+            SyncWorker.schedule(synqApp, settings.syncIntervalMinutes)
+        }
+    }
+
+    fun checkConnection(url: String) {
+        if (_ping.value is PingState.Checking) return
+        viewModelScope.launch(Dispatchers.IO) {
+            _ping.value = PingState.Checking
+            val ok = SynqApiClient().checkHealth(url.trim())
+            _ping.value = if (ok) PingState.Ok(url) else PingState.Failed(url)
+        }
     }
 }

server/app/main.py

@@ -1,7 +1,9 @@
 import logging
 import os
+import secrets
 from pathlib import Path
 
+from contextlib import asynccontextmanager
 from fastapi import Depends, FastAPI, HTTPException, Request
 from fastapi.exceptions import RequestValidationError
 from fastapi.responses import JSONResponse
@@ -10,11 +12,51 @@ from .models import CaptureRequest, CaptureResponse, HealthResponse
 from .org_writer import format_capture
 from .store import IdempotencyStore, get_file_lock
 
+logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger("synq")
 
-app = FastAPI(title="synq", version="0.1.0")
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    _load_token()
+    yield
+
+
+app = FastAPI(title="synq", version="0.1.0", lifespan=lifespan)
 
 _store: IdempotencyStore | None = None
+_token_cache: str | None = None
+
+
+def _load_token() -> str:
+    global _token_cache
+    if _token_cache:
+        return _token_cache
+
+    env_token = os.environ.get("PHONE_CAPTURE_TOKEN", "").strip()
+    if env_token and env_token != "change-me" and env_token != "change-me-long-random-token":
+        _token_cache = env_token
+        return _token_cache
+
+    token_file = Path(os.environ.get("PHONE_CAPTURE_DB_PATH", "/data/capture.sqlite3")).parent / "token.txt"
+    if token_file.exists():
+        stored = token_file.read_text().strip()
+        if stored:
+            _token_cache = stored
+            logger.info("synq token loaded from %s", token_file)
+            return _token_cache
+
+    generated = secrets.token_hex(32)
+    token_file.parent.mkdir(parents=True, exist_ok=True)
+    token_file.write_text(generated)
+    logger.info("")
+    logger.info("=" * 60)
+    logger.info("  SYNQ TOKEN (paste into app settings):")
+    logger.info("  %s", generated)
+    logger.info("=" * 60)
+    logger.info("")
+    _token_cache = generated
+    return _token_cache
+
 
 
 def get_store() -> IdempotencyStore:
@@ -30,7 +72,7 @@ def _org_path() -> str:
 
 
 def _token() -> str:
-    return os.environ.get("PHONE_CAPTURE_TOKEN", "")
+    return _load_token()
 
 
 async def check_token(request: Request) -> None:
@@ -40,6 +82,7 @@ async def check_token(request: Request) -> None:
     auth = request.headers.get("authorization", "")
     scheme, _, provided = auth.partition(" ")
     if scheme.lower() != "bearer" or provided != expected:
+        logger.warning("rejected request: invalid token from %s", request.client.host if request.client else "unknown")
         raise HTTPException(status_code=401, detail="unauthorized")
 
 
@@ -59,7 +102,10 @@ async def capture(payload: CaptureRequest, store: IdempotencyStore = Depends(get
 
     lock = get_file_lock()
     with lock:
-        Path(org_path).parent.mkdir(parents=True, exist_ok=True)
+        org_file = Path(org_path)
+        org_file.parent.mkdir(parents=True, exist_ok=True)
+        if not org_file.exists():
+            org_file.write_text("#+title: synq captures\n#+startup: overview\n\n", encoding="utf-8")
         with open(org_path, "a", encoding="utf-8") as f:
             f.write(entry)
         store.mark_seen(payload.id, payload.created_at)
@@ -71,6 +117,8 @@ async def capture(payload: CaptureRequest, store: IdempotencyStore = Depends(get
 @app.exception_handler(RequestValidationError)
 async def validation_exception_handler(request: Request, exc: RequestValidationError) -> JSONResponse:
     errors = exc.errors()
+    fields = [str(e.get("loc", "")) for e in errors]
+    logger.warning("rejected payload: validation failed fields=%s from=%s", fields, request.client.host if request.client else "unknown")
     for err in errors:
         if "body" in err.get("loc", ()):
             return JSONResponse(status_code=400, content={"detail": "body must not be empty"})

tasks.org

@@ -43,8 +43,10 @@ the app must be instant-feeling, capture-only, and boring. the phone stores note
 *** acceptance
 - `android/`, `server/`, and `docs/` directories exist.
 - root `README.md`, `tasks.org`, `.env.example`, and `docker-compose.example.yml` exist.
+
 *** notes
 Skeleton committed in initial commit. android/ dir will be created in milestone 2.
+
 *** evidence
 - commit: c08b3fe
 - tests: n/a (directory structure)
@@ -328,48 +330,146 @@ SettingsScreen + SettingsViewModel from milestone 2. DataStore-backed. Default s
 - datetime: [2026-05-18 Sun 18:00]
 
 * milestone 4: polish and hardening
-** TODO make launch path fast
+** DONE make launch path fast
 *** acceptance
 - app opens directly to capture field.
 - no network call blocks launch.
 - no history loading blocks text entry.
-** TODO normalize tags
+*** notes
+LaunchedEffect(Unit) { focusRequester.requestFocus() } fires immediately on composition. No network calls in MainActivity or CaptureScreen init path. History loads via Room Flow on a background coroutine — never blocks text entry.
+*** evidence
+- commit: 19b05a8
+- tests: manual — cold launch, keyboard appears without any loading state
+- datetime: [2026-05-18 Sun 19:00]
+
+** DONE normalize tags
 *** acceptance
 - whitespace-separated and comma-separated tags both work.
 - invalid org tag chars are stripped or replaced.
 - duplicate tags collapse.
-** TODO handle multiline notes well
+*** notes
+Two-layer normalization: parseTags() in CaptureViewModel splits on [,\s]+ before storing to Room. normalize_tags() in server/app/org_writer.py lowercases, strips #, replaces spaces with _, removes non-[a-z0-9_] chars, deduplicates. 7 unit tests cover all cases.
+*** evidence
+- commit: e873a00 (server), 19b05a8 (android)
+- tests: pytest tests/test_org_writer.py::TestNormalizeTags — 7 passed
+- datetime: [2026-05-18 Sun 19:00]
+
+** DONE fix org formatting
+*** acceptance
+- add `#+startup: overview` to synq.org
+*** notes
+Append writer in main.py checks if org file exists before first write. If missing, creates it with #+title and #+startup: overview header. Existing files are never modified.
+*** evidence
+- commit: fd28a45
+- tests: manual — delete synq.org, post a capture, verify header present
+- datetime: [2026-05-18 Sun 19:00]
+
+** DONE handle multiline notes well
 *** acceptance
 - first line can become note heading if body is multiline.
 - full body is preserved under heading.
 - todo body remains usable as a single todo heading, with extra lines under it if present.
-** TODO add basic logs
+*** notes
+format_capture() in org_writer.py: multiline note uses first line as heading suffix ("* note: <first line>"), full body preserved below drawer. Single-line note uses "* note" heading, body below. Covered by test_note_multiline.
+*** evidence
+- commit: e873a00
+- tests: pytest tests/test_org_writer.py::TestFormatCapture::test_note_multiline — passed
+- datetime: [2026-05-17 Sat 17:00]
+
+** DONE add basic logs
 *** acceptance
 - server logs accepted capture id.
 - server logs duplicate capture id.
 - server logs rejected payload without dumping secrets.
-** TODO create backup note
+*** notes
+logger.info for accepted and duplicate (id only, no body). logger.warning for invalid token (client IP only, no token value logged). logger.warning for validation errors (field names only, no body content).
+*** evidence
+- commit: fd28a45
+- tests: manual — send bad token, send empty body, check uvicorn stdout
+- datetime: [2026-05-18 Sun 19:00]
+
+** DONE create backup note
 *** acceptance
 - readme documents which paths need backup.
 - readme documents restore behavior.
+*** notes
+Added "backup" section to README.md covering synq.org, capture.sqlite3, token.txt. Restore section documents behavior when each file is lost individually.
+*** evidence
+- commit: 66155f6
+- tests: n/a
+- datetime: [2026-05-18 Sun 19:00]
 
-* milestone 5: optional v1.5
+* milestone 5: optional v1.5 improvements
-** TODO add android share target
+** DONE add android share target
 *** acceptance
 - sharing text to app opens prefilled capture.
 - user can save as note or todo.
+*** notes
+ACTION_SEND text/plain intent-filter added to MainActivity in manifest. MainActivity.onCreate extracts EXTRA_TEXT and passes it as a URL-encoded nav argument to the capture/{prefill} route. CaptureScreen applies it via LaunchedEffect on first composition.
+*** evidence
+- commit: 66155f6
+- tests: manual — share any text from browser/notes to synq, verify it pre-fills capture body
+- datetime: [2026-05-18 Sun 20:00]
+
 ** TODO add home screen quick capture widget
 *** acceptance
 - widget opens capture screen quickly.
 - does not require sync to work.
-** TODO add recent tag chips
+
+** DONE add recent tag chips
 *** acceptance
 - app shows recent tags.
 - tapping chip adds/removes tag.
-** TODO add edit-before-sync
+*** notes
+CaptureViewModel.recentTags collects the last 100 capture tagsJson rows, decodes each JSON array, flattens and deduplicates (LinkedHashSet order), limits to 20. CaptureScreen shows a FlowRow of FilterChip below the tags text field. Tapping a chip calls toggleTag() which adds/removes it from the tags string. Active chips are highlighted via FilterChip selected=true.
+*** evidence
+- commit: 66155f6
+- tests: manual — save a few captures with tags, open capture screen, verify chips appear and toggle
+- datetime: [2026-05-18 Sun 20:00]
+
+** DONE add edit-before-sync
 *** acceptance
 - pending/failed captures can be edited.
 - synced captures are read-only unless explicitly duplicated.
+*** notes
+CaptureDao.updateBody() new query. HistoryViewModel.updateBody() calls it. HistoryScreen CaptureRow shows "edit" OutlinedButton only when expanded AND status is pending/failed. Tapping edit opens an AlertDialog with an OutlinedTextField pre-filled with current body. Save calls updateBody; cancel dismisses.
+*** evidence
+- commit: 66155f6
+- tests: manual — save a capture, open history, expand row, tap edit, change body, save, verify updated
+- datetime: [2026-05-18 Sun 20:00]
+
+** DONE tap to expand history item
+*** acceptance
+- tapping a history row expands/collapses it.
+- expanded row shows full body.
+- edit button is only visible when expanded.
+*** notes
+CaptureRow uses rememberSaveable expanded: Boolean keyed on capture.id. Card has clickable { expanded = !expanded }. maxLines switches between 2 and Int.MAX_VALUE. Edit button only renders when expanded && editable.
+*** evidence
+- commit: 66155f6
+- tests: manual — tap history rows to expand/collapse, verify full body visible when expanded
+- datetime: [2026-05-18 Sun 20:00]
+
+** DONE add "Last synced" display
+*** acceptance
+- "last synced at" visible in history top bar and capture screen.
+*** notes
+CaptureDao.getLastSyncedAt() returns Flow<String?> of MAX(syncedAt). HistoryViewModel and CaptureViewModel both stateIn this flow. HistoryScreen shows it as a subtitle under "history" in the TopAppBar. CaptureScreen shows it as a small label above the save buttons. Both parse the ISO string via OffsetDateTime and format with DateTimeFormatter.ofLocalizedDateTime(SHORT).
+*** evidence
+- commit: 66155f6
+- tests: manual — sync a capture, verify timestamp appears in history header and capture screen
+- datetime: [2026-05-18 Sun 20:00]
+
+** DONE add settings for sync frequency
+*** acceptance
+- user-specified poll rate in minutes (min 15).
+- changing interval reschedules WorkManager immediately.
+*** notes
+SynqSettings gained syncIntervalMinutes: Int = 15 field with DataStore key sync_interval_minutes. SettingsScreen added OutlinedTextField with number keyboard for interval, shows supporting text "WorkManager minimum is 15 min". buildSettings() coerces to max(value, 15). SettingsViewModel.save() now also calls SyncWorker.schedule(app, settings.syncIntervalMinutes). SyncWorker.schedule() uses REPLACE policy so new interval takes effect immediately.
+*** evidence
+- commit: 66155f6
+- tests: manual — change interval to 30, save, verify WorkManager re-queues (check adb shell dumpsys jobscheduler)
+- datetime: [2026-05-18 Sun 20:00]
 
 * implementation notes for coding agents
 - keep the server small and testable.