From 2f75b8980d3600b671077641696e93609aa3b60e Mon Sep 17 00:00:00 2001
From: josh <josh@thewrightserver.net>
Date: Fri, 27 Mar 2026 23:15:26 -0400
Subject: [PATCH] readme

---
 README.md | 117 +++++++++++++++++++++++++++++++++++++-----------------
 1 file changed, 81 insertions(+), 36 deletions(-)

diff --git a/README.md b/README.md
index 0199f78..4f1660c 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,100 @@
 # Catalyst
 
-Instance registry for tracking infrastructure. Built as a single-page app — no backend, no framework.
-
-## Stack
-
-- **sql.js** — SQLite compiled to WebAssembly, runs entirely in the browser
-- **localStorage** — persists the database between sessions
-- **nginx** — serves the static files (via Docker)
+A lightweight instance registry for tracking self-hosted infrastructure. No backend, no framework — just a browser, a SQLite database compiled to WebAssembly, and a static file server.
 
 ## Structure
 
 ```
-index.html          Entry point
-css/app.css         All styles
+index.html        Entry point
+css/app.css       Styles
 js/
-  config.js         Service definitions and seed data
-  db.js             Database layer (init, queries, mutations, persistence)
-  ui.js             Rendering, modals, toast notifications
-  app.js            Router and bootstrap
-Dockerfile          nginx:alpine image
-nginx.conf          SPA routing config (used by Dockerfile)
+  config.js       Service definitions and seed data
+  db.js           Data layer
+  ui.js           Rendering, modals, notifications
+  app.js          Router
 ```
 
-## Running locally
+## Data layer
 
-Requires a local HTTP server — `history.pushState` routing won't work over `file://`.
+All reads and writes go through five functions in `js/db.js`. This is the boundary that would be replaced when wiring Catalyst to a real backend — nothing else in the codebase touches data directly.
 
-```bash
-npx serve . --single
+### `getInstances(filters?)`
+
+Returns an array of instances, sorted by name. All filters are optional.
+
+```js
+getInstances()
+getInstances({ search: 'plex' })
+getInstances({ state: 'degraded' })
+getInstances({ stack: 'production' })
+getInstances({ search: 'home', state: 'deployed', stack: 'production' })
 ```
 
-Then open `http://localhost:3000`.
+`search` matches against `name`, `vmid`, and `stack`.
 
-## Building
+### `getInstance(vmid)`
 
-Push to `main`. Gitea Actions builds and pushes two image tags to your registry:
+Returns a single instance by VMID, or `null` if not found.
 
-| Tag | Use |
-|---|---|
-| `:latest` | Always the current main |
-| `:<sha>` | Pinned to a specific commit (use for rollbacks) |
+```js
+getInstance(137) // → { id, name, vmid, state, stack, ...services, createdAt, updatedAt }
+```
 
-Requires two things set in Gitea repository settings:
+### `getDistinctStacks()`
 
-| Key | Type | Value |
+Returns a sorted array of unique stack names present in the registry. Used to populate the stack filter dynamically.
+
+```js
+getDistinctStacks() // → ['development', 'production']
+```
+
+### `createInstance(data)`
+
+Inserts a new instance. Returns `{ ok: true }` on success or `{ ok: false, error }` on failure (e.g. duplicate VMID).
+
+```js
+createInstance({
+  name: 'plex',
+  vmid: 117,
+  state: 'deployed',        // 'deployed' | 'testing' | 'degraded'
+  stack: 'production',
+  tailscale_ip: '100.64.0.1',
+  atlas: 1,
+  argus: 1,
+  semaphore: 0,
+  patchmon: 1,
+  tailscale: 1,
+  andromeda: 0,
+  hardware_acceleration: 1,
+})
+```
+
+### `updateInstance(id, data)`
+
+Updates an existing instance by internal `id`. Accepts the same shape as `createInstance`. Returns `{ ok: true }` or `{ ok: false, error }`.
+
+### `deleteInstance(id)`
+
+Deletes an instance by internal `id`. Only instances on the `development` stack can be deleted — this is enforced in the UI before `deleteInstance` is ever called.
+
+---
+
+## Instance shape
+
+| Field | Type | Notes |
 |---|---|---|
-| `REGISTRY_HOST` | Variable | your Gitea hostname |
-| `GITEA_TOKEN` | Secret | token with `package:write` scope |
-
-## Running the container
-
-```bash
-docker run -d -p 3000:80 <registry>/catalyst:latest
-```
+| `id` | integer | Internal autoincrement ID |
+| `vmid` | integer | Unique. Used as the public identifier and in URLs (`/instance/137`) |
+| `name` | string | Display name |
+| `state` | string | `deployed`, `testing`, or `degraded` |
+| `stack` | string | `production` or `development` |
+| `tailscale_ip` | string | Optional |
+| `atlas` | 0 \| 1 | |
+| `argus` | 0 \| 1 | |
+| `semaphore` | 0 \| 1 | |
+| `patchmon` | 0 \| 1 | |
+| `tailscale` | 0 \| 1 | |
+| `andromeda` | 0 \| 1 | |
+| `hardware_acceleration` | 0 \| 1 | |
+| `createdAt` | ISO string | Set on insert |
+| `updatedAt` | ISO string | Updated on every write |