From 648b1c6643a79cb9485c1cac6b2c1c69b196557c Mon Sep 17 00:00:00 2001
From: Aaron <aaron@pikit.local>
Date: Wed, 10 Dec 2025 19:40:45 -0500
Subject: [PATCH] Update plan and add release README

---
 PLAN.md                 | 22 ++++++++++++---------
 tools/release/README.md | 42 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 55 insertions(+), 9 deletions(-)
 create mode 100644 tools/release/README.md

diff --git a/PLAN.md b/PLAN.md
index 9c751d6..5dcceb4 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -61,17 +61,21 @@
 - If apply fails, auto rollback.
 - Skip overwriting user-edited config? For v1 assume assets/api are managed; nginx site left unchanged.
 
-## Implementation steps
-1) Add current version markers (maybe file in repo, read by UI).
-2) Implement updater helper script with check/apply/rollback + state.
-3) Add systemd service/timer units template (install script TBD, for now keep files in repo).
-4) Extend `pikit-api.py` with new endpoints calling updater functions.
-5) Extend UI (status chip + modal) and wire to API.
-6) Add mock responses for dev (mock-update-status.json).
-7) Test locally (mock) and on device (manual apply pointing to a dummy URL or skip download logic for now).
+## Current status (2025-12-11)
+- Version markers and mock update status in place.
+- UI has release chip + modal; buttons call real `/api/update/*`.
+- API implements check/apply/rollback with staging, SHA256 verify, backup, deploy, restart, rollback.
+- Release tooling: `tools/release/make-release.sh` + README; SHA256 baked into manifest.
+- Missing: auto-check timer, lockfile, backup pruning, real release publishing.
+
+## Remaining work
+- Publish real release bundles + manifest to Gitea.
+- Add lock around apply/check to prevent overlap.
+- Add backup pruning (keep last N).
+- Add systemd timer/service to run check daily and surface status.
+- Optional: protect nginx/site overrides; add disk-space preflight.
 
 ## Open questions / assumptions
 - Release hosting: use Gitea releases at `https://git.44r0n.cc/44r0n7/pi-kit/releases/latest` (JSON API? or static URLs). For v1, hardcode base URL env var or config.
 - Services to restart: assume `dietpi-dashboard-frontend` and `pikit-api` (if we add a service file). Need to verify actual service names on device.
 - Device perms: updater runs as root (via sudo from API). Ensure API endpoint requires auth (existing login).
-
diff --git a/tools/release/README.md b/tools/release/README.md
new file mode 100644
index 0000000..b478e27
--- /dev/null
+++ b/tools/release/README.md
@@ -0,0 +1,42 @@
+# Release packaging quickstart
+
+## Prereqs
+- Node build already run (pikit-web built) if you want production assets. Dev assets also work but will be larger.
+- `tar`, `sha256sum`, `rsync` available (default on DietPi/Debian).
+
+## Build a release bundle
+
+```bash
+./tools/release/make-release.sh <version> <base_download_url>
+# example
+./tools/release/make-release.sh 0.1.0 https://git.44r0n.cc/44r0n7/pi-kit/releases/download/v0.1.0
+```
+
+Outputs (in `out/releases/`):
+- `pikit-<version>.tar.gz`
+- `manifest.json` with the SHA256 of the bundle and the download URL.
+
+## Publish
+1) Create a release in Gitea for tag `v<version>`.
+2) Upload both `pikit-<version>.tar.gz` and `manifest.json` as release assets.
+3) Ensure the base download URL in the manifest matches where the bundle is hosted.
+
+## Device configuration (optional override)
+The API uses `PIKIT_MANIFEST_URL` to fetch `manifest.json`. Default:
+```
+https://git.44r0n.cc/44r0n7/pi-kit/releases/latest/download/manifest.json
+```
+Set an override in the environment or a systemd drop-in for `pikit-api.service`:
+```
+[Service]
+Environment=PIKIT_MANIFEST_URL=https://git.44r0n.cc/44r0n7/pi-kit/releases/download/v0.1.0/manifest.json
+```
+
+## What’s inside the bundle
+- `pikit-web/` (built static assets)
+- `pikit-api.py`
+- optional helper scripts (e.g., `set_ready.sh`, `start-codex.sh`, `pikit-services.json` if present)
+
+## Notes
+- The updater verifies the bundle SHA256 from `manifest.json` before installing.
+- Backups of current web/api are stored in `/var/backups/pikit/<timestamp>/` before deployment.