From 68738e486dd03a6bef7eb467792126368ab42594 Mon Sep 17 00:00:00 2001
From: Assistant builder <meelstorm@gmail.com>
Date: Thu, 11 Jun 2026 20:11:39 +0000
Subject: [PATCH] Add README with repo layout, local dev, smoke test, deploy
 commands

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

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..624df62
--- /dev/null
+++ b/README.md
@@ -0,0 +1,94 @@
+# Smart Assistant
+
+Voice assistant on a Raspberry Pi talking to the OpenAI Realtime API via an
+ASP.NET backend deployed on Coolify.
+
+See `docs/superpowers/specs/2026-06-11-smart-assistant-design.md` for the full
+design and `docs/superpowers/plans/2026-06-11-smart-assistant-backend-foundation.md`
+for the Plan 1 implementation steps that produced this code.
+
+## Repo layout
+
+- `backend/` — ASP.NET 9 backend (Identity, Devices, Pairing, Install).
+- `backend.tests/` — xUnit integration + unit tests via `WebApplicationFactory`.
+- `client/` — Python client. **Plan 1 ships placeholders only**; the full
+  wakeword + Realtime client lands in Plan 3.
+- `Dockerfile` + `docker-compose.yml` — multi-stage build; produces one image
+  with the published ASP.NET app + a bundled `client.tar.gz` in
+  `wwwroot/client.tar.gz`.
+- `deploy.json` — Coolify config (gitignored; contains the OpenAI key).
+- `docs/superpowers/` — specs and plans.
+
+## Local development
+
+```sh
+dotnet test                              # all backend tests
+dotnet run --project backend             # starts on http://localhost:5000
+```
+
+Hit `http://localhost:5000/health` to verify it's up.
+
+## Smoke test against a live deploy
+
+The full pairing flow can be exercised with `curl` — no UI needed yet.
+
+```sh
+DOMAIN="https://assistant.volcanic.tes.gd"          # or your domain
+COOKIE=$(mktemp)
+
+# Register the first user (becomes Admin automatically) and sign in
+curl -sf -c "$COOKIE" -X POST "$DOMAIN/api/auth/register" \
+  -H 'content-type: application/json' \
+  -d '{"email":"you@example.com","password":"Passw0rd!"}'
+curl -sf -c "$COOKIE" -b "$COOKIE" -X POST "$DOMAIN/api/auth/login" \
+  -H 'content-type: application/json' \
+  -d '{"email":"you@example.com","password":"Passw0rd!"}'
+
+# Generate a pairing code (auth required)
+CODE=$(curl -sf -c "$COOKIE" -b "$COOKIE" -X POST "$DOMAIN/api/pair-code" \
+  -H 'content-type: application/json' \
+  -d '{"name":"kitchen"}' \
+  | python3 -c 'import sys,json; print(json.load(sys.stdin)["code"])')
+echo "code=$CODE"
+
+# Pair as a device (public endpoint) and capture the token
+curl -sf -X POST "$DOMAIN/api/pair" \
+  -H 'content-type: application/json' \
+  -d "{\"code\":\"$CODE\",\"hostname\":\"smoke\",\"client_version\":\"0.1\"}" \
+  | python3 -m json.tool
+
+# Verify the install script and client bundle are served
+curl -sf "$DOMAIN/install.sh" | head -5
+curl -sIf "$DOMAIN/client.tar.gz"
+```
+
+Expected: `{"ok":true}` on `/health`, JSON with `device_id`/`device_token`/`backend_ws`
+from `/api/pair`, the bash shebang from `/install.sh`, and a `200 OK` with
+`Content-Type: application/gzip` for the bundle.
+
+> **Plan 1 ships a placeholder Python bundle** — running the bundled
+> `client.main` will exit with the placeholder message. Plan 3 replaces it
+> with the real wakeword + Realtime client.
+
+## Deploying
+
+Use the Coolify v4 API. The `deploy.json` file (gitignored) carries the
+project + server UUIDs and the OpenAI key.
+
+```sh
+APP=$(python3 -c "import json; print(json.load(open('deploy.json'))['app']['uuid'])")
+curl -sf -X POST "$COOLIFY_URL/api/v1/deploy?uuid=$APP" \
+  -H "Authorization: Bearer $COOLIFY_KEY"
+```
+
+Fire-and-forget; the API returns a `deployment_uuid` immediately. Don't poll
+(per the global Coolify rule in `CLAUDE.md`).
+
+## What's next
+
+- **Plan 2** — backend device hub + OpenAI Realtime relay + tools registry
+  (the `end_session`, `get_current_time`, `set_volume` tools the spec describes).
+- **Plan 3** — full Python client on the Pi (wakeword, VAD, audio plumbing,
+  state machine, install + pair CLIs).
+- **Plan 4** — React management UI for the admin dashboard and conversation
+  history viewer.