From be38ca61ed85e4493e645c97d69251cdcc02b80b Mon Sep 17 00:00:00 2001
From: Solstice <solstice@local>
Date: Wed, 10 Jun 2026 00:59:09 -0700
Subject: fix: bundle release audio and docs

---
 README.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 127 insertions(+), 4 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 102e366..b63df65 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,130 @@
-# Tauri + React + Typescript
+# Solstice
 
-This template should help get you started developing with Tauri, React and Typescript in Vite.
+Minimalist Pomodoro timer desktop app. Stack: Tauri 2 + React 19 + TypeScript + Rust.
 
-## Recommended IDE Setup
+## Prereqs
 
-- [VS Code](https://code.visualstudio.com/) + [Tauri](https://marketplace.visualstudio.com/items?itemName=tauri-apps.tauri-vscode) + [rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+- Node.js 20+
+- Rust toolchain
+- Tauri system deps for your OS
+
+Install Tauri OS deps first if `npm run tauri dev` or `npm run tauri build` fails:
+
+- https://v2.tauri.app/start/prerequisites/
+
+## Clone And Install
+
+```bash
+git clone ssh://git@tylerhoang.xyz:46701/srv/git/solstice.git
+cd solstice
+npm install
+```
+
+## Run In Dev
+
+Full desktop app with hot reload:
+
+```bash
+npm run tauri dev
+```
+
+What this does:
+
+- starts Vite dev server on `http://localhost:1420`
+- builds Rust side in dev mode
+- opens native Tauri window
+
+Frontend only in browser:
+
+```bash
+npm run dev
+```
+
+## Build
+
+Frontend build + TypeScript check only:
+
+```bash
+npm run build
+```
+
+This writes static frontend files to `dist/`. It does **not** create runnable desktop app by itself.
+
+Desktop app build:
+
+```bash
+npm run tauri build
+```
+
+This runs frontend build first, then builds packaged Tauri app.
+
+## Run Built App
+
+After `npm run tauri build`, look here:
+
+- packaged outputs: `src-tauri/target/release/bundle/`
+- raw release binary: `src-tauri/target/release/`
+
+Typical local run on Linux:
+
+```bash
+./src-tauri/target/release/solstice
+```
+
+If exact filename differs on your OS, use installer/package inside `src-tauri/target/release/bundle/`.
+
+## Audio Files
+
+Ambient audio is user-supplied. Expected filenames:
+
+- `rain.ogg`
+- `cafe.ogg`
+- `white_noise.ogg`
+
+Lookup order:
+
+1. app data audio dir
+2. bundled `audio/` dir
+
+### Easiest Dev Setup
+
+Place OGG files in:
+
+```text
+src-tauri/audio/
+```
+
+This directory is also release source for bundled default sounds. `npm run tauri build` packages any expected `.ogg` files found there, and built app uses them when app-data audio is absent.
+
+Example:
+
+```bash
+cp /path/to/rain.ogg src-tauri/audio/rain.ogg
+cp /path/to/cafe.ogg src-tauri/audio/cafe.ogg
+cp /path/to/white_noise.ogg src-tauri/audio/white_noise.ogg
+```
+
+Do not rename files. App looks for those exact names.
+
+### App Data Audio Dir
+
+On startup app creates `<app_data_dir>/audio` and prefers files there over bundled files.
+
+Use this when you want custom audio without touching repo files. App state also persists under same app data dir as `data.json`.
+
+## Useful Commands
+
+```bash
+npm run dev          # frontend only
+npm run build        # TS check + frontend build
+npm run tauri dev    # desktop app in dev mode
+npm run tauri build  # desktop app release build
+```
+
+Rust side only:
+
+```bash
+cd src-tauri
+cargo build
+cargo test
+```
-- 
cgit v1.3-2-g0d8e