From 30852a81122bd1c29b5fbf0a99d1b95b31a5660a Mon Sep 17 00:00:00 2001
From: pdmarf <135653545+pdmarf@users.noreply.github.com>
Date: Sat, 11 Apr 2026 11:17:09 +0100
Subject: [PATCH] Add README

---
 README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1871336
--- /dev/null
+++ b/README.md
@@ -0,0 +1,86 @@
+# Notion Timer — Stream Deck Plugin
+
+A Stream Deck plugin that toggles time tracking in Notion. Press a button to start a timer against a project, press again to stop. Only one timer can run at a time.
+
+---
+
+## Staff Installation
+
+Requires [Stream Deck](https://www.elgato.com/downloads) installed and up to date.
+
+Open Terminal and run:
+
+```bash
+curl -s https://gitea.pdmarf.co.uk/pdm/stream_deck_notion_timer/raw/branch/master/install.sh | bash
+```
+
+Stream Deck will open and install the plugin automatically.
+
+**First-time setup:**
+1. Drag a **Toggle Timer** button onto a key in Stream Deck
+2. Click the button — a settings panel appears at the bottom
+3. Expand **Notion Credentials** and fill in your API token, then select your name from the dropdown
+4. Select your project from the Project dropdown
+
+---
+
+## Auto-Updates
+
+Updates are automatic — no action needed from staff.
+
+The flow:
+1. Plugin starts and connects to Stream Deck
+2. After 10 seconds it checks `version.json` on Gitea
+3. If a newer version is available, it downloads `plugin.js` and `plugin.js.sig`
+4. The Ed25519 signature is verified against the public key embedded in the plugin
+5. If the signature is valid, the plugin overwrites itself and restarts
+6. Stream Deck relaunches the plugin on the new version
+
+If the update server is unreachable or the signature fails, the plugin continues running on the current version unchanged.
+
+---
+
+## Developer Workflow
+
+### Build & deploy locally
+
+```bash
+npm run build       # compile + sign
+```
+
+Then copy to Stream Deck:
+```bash
+cp com.pdma.notion-timer.sdPlugin/bin/plugin.js "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/com.pdma.notion-timer.sdPlugin/bin/plugin.js"
+cp com.pdma.notion-timer.sdPlugin/bin/plugin.js.sig "$HOME/Library/Application Support/com.elgato.StreamDeck/Plugins/com.pdma.notion-timer.sdPlugin/bin/plugin.js.sig"
+pkill -f "notion-timer"
+```
+
+### Release an update to staff
+
+1. Make your changes
+2. Bump `CURRENT_VERSION` in `src/plugin.ts` and `version.json`
+3. Run:
+
+```bash
+npm run package
+git add .
+git commit -m "v1.x.x: description"
+git push
+```
+
+Staff machines will pick up the update within 10 seconds of their next Stream Deck start.
+
+### Signing key
+
+The Ed25519 private key lives at `~/.notion-timer-signing-key.pem` — keep this backed up. If lost, a new key pair must be generated and the plugin redistributed manually to all staff.
+
+---
+
+## Architecture
+
+| Component | Location | Runtime |
+|---|---|---|
+| Plugin logic | `src/plugin.ts` | Node.js 20 (under Stream Deck) |
+| Notion API | `src/notion.ts` | Node.js 20 |
+| Settings UI | `ui/property-inspector.html` | Browser (in Stream Deck app) |
+| PI library | `ui/libs/` | Browser — from [elgatosf/streamdeck-javascript-sdk](https://github.com/elgatosf/streamdeck-javascript-sdk) |