From d7be6d999afc48232a1108746ed7187f592e9bcb Mon Sep 17 00:00:00 2001
From: Jage9 <jj@bestmidi.com>
Date: Tue, 24 Feb 2026 22:14:23 -0500
Subject: [PATCH] Update docs to use default local run commands

---
 README.md     | 35 +++++++++++++++++++++++++++++------
 docs/local.md | 14 ++++++++++----
 2 files changed, 39 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 1cc8418..19ca1b6 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
-# Chat Grid
+#Chat Grid
+##A Mostly Vibed, Audio-first Interactive Playground
 
-Realtime spatial chat grid with:
-- `client/` TypeScript web app
-- `server/` Python websocket signaling server
+Chat Grid is one of those projects that started with a random idea, and then grew to be many things, but most with spacial audio as its core. Briefly put, Chat Grid allows users to move around a grid and interact with each other, or with items placed on the grid. Your voice, as well as items are shared as positional audio. Item types currently range from dice and a wheel to a fully-playable toy piano and media players with directional audio. New item types can be added as plugins.
+
+Chat Grid is designed to be run on a secure server with users connecting via a web client. The client works best currently with Windows browsers, with minimal testing on mobile/Mac. Ideally, client apps would be better in the long-run, especially for mobile.
 
 ## Local Run
 
@@ -10,18 +11,30 @@ Realtime spatial chat grid with:
 ```bash
 cd server
 cp config.example.toml config.toml
-uv run python main.py --config config.toml
+uv run python main.py
 ```
 
 2) Start client
 ```bash
 cd client
 npm install
-npm run dev -- --host 0.0.0.0 --port 5173
+npm run dev
 ```
 
 3) Open `http://localhost:5173`
 
+Notes:
+- Server defaults to `config.toml` when present.
+- Server bind/port defaults are `127.0.0.1:8765` unless changed in config or CLI flags.
+- Client dev defaults to Vite local host/port (`localhost:5173`) unless flags override.
+- Auth requires `CHGRID_AUTH_SECRET` in server environment; `deploy/scripts/install_server.sh` creates `server/.env` with this value automatically if missing.
+
+Common server overrides:
+- `uv run python main.py --config /path/to/config.toml`
+- `uv run python main.py --host 0.0.0.0 --port 9000`
+- `uv run python main.py --ssl-cert /path/fullchain.pem --ssl-key /path/privkey.pem`
+- `uv run python main.py --bootstrap-admin` (one-time admin creation)
+
 ## Production Deploy (quick path)
 
 Use `deploy/README.md`.
@@ -48,3 +61,13 @@ Summary:
 - Protocol behavior notes: `docs/protocol-notes.md`
 - Item schema reference: `docs/item-schema.md`
 - Local dev commands: `docs/local.md`
+
+##Contributing
+Contributions and ideas are welcome. The grid is already home to several rather absurd ideas, and yours may fit right in. Please look over the docs and other files for guidance, or ask for help.
+
+##Notes on AI Coding
+This project has been largely coded using AI tools, with a lot of human prompting and hand-holding to enforce best practices. All ideas for improving the project or its design are welcome.
+
+## License
+- MIT
+This project is licensed under the MIT License. See `LICENSE`.
diff --git a/docs/local.md b/docs/local.md
index 97c734b..a6480c4 100644
--- a/docs/local.md
+++ b/docs/local.md
@@ -4,30 +4,36 @@
 
 ```bash
 cd /home/jjm/code/chgrid/server
-.venv/bin/python main.py --config config.toml --port 8765
+.venv/bin/python main.py
 ```
 
 ## Start Client
 
 ```bash
 cd /home/jjm/code/chgrid/client
-npm run dev -- --host 0.0.0.0 --port 5173
+npm run dev
 ```
 
 Open: `http://localhost:5173`
 
+Defaults:
+- Server reads `config.toml` automatically when present.
+- Server default bind/port is `127.0.0.1:8765`.
+- Client dev default is `localhost:5173`.
+- Auth requires `CHGRID_AUTH_SECRET` in environment.
+
 ## Quick Restarts
 
 Server:
 ```bash
 lsof -tiTCP:8765 -sTCP:LISTEN | xargs -r kill
 cd /home/jjm/code/chgrid/server
-nohup .venv/bin/python main.py --config config.toml --port 8765 > /tmp/chgrid-server.log 2>&1 &
+nohup .venv/bin/python main.py > /tmp/chgrid-server.log 2>&1 &
 ```
 
 Client:
 ```bash
 lsof -tiTCP:5173 -sTCP:LISTEN | xargs -r kill
 cd /home/jjm/code/chgrid/client
-nohup npm run dev -- --host 0.0.0.0 --port 5173 > /tmp/chgrid-client.log 2>&1 &
+nohup npm run dev > /tmp/chgrid-client.log 2>&1 &
 ```