docs: expand README with spec links and dev workflow

README.md

@@ -1,3 +1,27 @@
-# minstrel
+# Minstrel
 
-Self-hosted music server with OpenSubsonic compatibility, server-side smart shuffle, dual-like model, session-aware radio, and Lidarr integration. Go + Postgres.
+Self-hosted music server with OpenSubsonic compatibility plus an extended API for server-side smart shuffle, a dual-like model (general + contextual), session-aware radio, ListenBrainz scrobble/similarity, and Lidarr integration. Go + Postgres, packaged as a Docker container.
+
+> State and intelligence belong on the server, not the client.
+
+## Specs
+
+Authoritative v1 scope lives under [`docs/`](./docs):
+
+- [Server spec](./docs/smart-music-server-spec.md) — current implementation focus.
+- [Client spec](./docs/smart-music-client-spec.md) — Flutter companion app; work starts once the server reaches its Subsonic-compatible baseline.
+
+## Development workflow
+
+- Day-to-day work happens on the `dev` branch (or feature branches merged into `dev`).
+- `main` is **protected** — changes land only via pull request from `dev`.
+- Production builds are cut by tagging a release (`v*`) off `main`.
+
+## CI / container image
+
+Forgejo Actions handles:
+
+- Tests on push to `dev` and on PRs into `main`.
+- Container image build + push to the Forgejo registry on merge to `main` (`:main`) and on `v*` tags (`:<version>`).
+
+Task and milestone tracking: Fable (`Minstrel` project, id 12).