docs: add local orbstack setup

docs/LOCAL_ORBSTACK.md

@@ -0,0 +1,102 @@
+# Local Development with OrbStack
+
+Yes — this backend can run locally in OrbStack.
+
+This repo includes `compose.yaml` with:
+
+- `db`: PostgreSQL 16
+- `api`: the Go backend built from the local `Dockerfile`
+
+## Quick start
+
+From `Arkie-Library-Backend`:
+
+```bash
+docker compose up --build
+```
+
+Then test:
+
+```bash
+curl http://localhost:8080/healthz
+```
+
+Expected output:
+
+```text
+ok
+```
+
+## Local URLs
+
+| Service | URL |
+| --- | --- |
+| Backend API | `http://localhost:8080` |
+| Health check | `http://localhost:8080/healthz` |
+| PostgreSQL from Mac host | `localhost:5433` |
+| PostgreSQL from API container | `db:5432` |
+
+The DB host port is `5433` to avoid conflicts with any local PostgreSQL already using `5432`.
+
+## Default local admin
+
+When the DB is empty, compose seeds an admin because `SEED_ADMIN=true` by default:
+
+```text
+email: admin@ark.local
+password: admin123
+```
+
+Override if needed:
+
+```bash
+ADMIN_EMAIL=you@example.com ADMIN_PASSWORD='your-password' docker compose up --build
+```
+
+## Frontend connecting to local backend
+
+In `Arkie-Library-Frontend`, use:
+
+```bash
+VITE_API_URL=http://localhost:8080
+```
+
+Then run your frontend dev server normally.
+
+## Running Go locally but DB in OrbStack
+
+For faster backend development, you can run only PostgreSQL in OrbStack and run Go directly on your Mac.
+
+Start DB only:
+
+```bash
+docker compose up db
+```
+
+In another terminal:
+
+```bash
+export DATABASE_URL='postgres://ark:ark@localhost:5433/arkdb?sslmode=disable'
+export HTTP_ADDR=':8080'
+export JWT_SECRET='local-dev-change-me'
+export CORS_ORIGINS='http://localhost:5173,http://localhost:3000'
+export SEED_ADMIN=true
+
+go run ./cmd/server
+```
+
+## Reset local database
+
+This deletes local development data and reruns migrations on next start:
+
+```bash
+docker compose down -v
+docker compose up --build
+```
+
+## Important notes
+
+- This is local-only and does not touch the production server.
+- `migrations/001_init.sql` runs only when the PostgreSQL volume is first created.
+- If you change migrations and want them reapplied, reset with `docker compose down -v`.
+- Do not use production `DATABASE_URL` for local development unless you intentionally want to modify production data.