Merge pull request #39 from markrai/refinements_and_docs

multiple UX refinements, PWA enablement, and docs

Author: markrai

CHANGELOG.md

@@ -3,6 +3,28 @@
 > **Upgrades:** No breaking changes in **3.7.x** / **3.8.x** / **3.9.x** / **3.10.x** / **3.11.x** unless noted below.
 
 
+## [3.11.3] - 2026-04-05
+
+### Features
+
+- **Board (mobile)** — When a todo drag starts, lane tabs briefly flash (**300ms**) so it is obvious they accept drops; tab labels stay readable above the drop overlays.
+- **Web Push (PWA)** — After sign-in, the client auto-subscribes when **both** VAPID keys are set on the server; **`SCRUMBOY_PUSH_BY_DEFAULT_IF_VAPID`** removed (VAPID presence is the operator signal). Per-user autosub progress in **localStorage** with resilient retry when the permission prompt is dismissed vs blocked.
+
+### Fixes
+
+- **Board (drag-and-drop)** — Success toast **“Todo moved to …”** only when the todo changes **lane**; same-lane reorder no longer shows a redundant toast (lane titles still come from the board workflow, not hardcoded names).
+
+### Improvements
+
+- **Settings → Customization** — **Background notifications (PWA)** is grayed out with a one-line notice when Web Push is unavailable (no VAPID on the server, or anonymous board mode).
+
+### Documentation
+
+- **`docs/mcp.md`** — MCP documentation added/expanded.
+- **`docs/pwa.md`** — Push flow and env vars aligned with streamlined enablement; key generation note includes **[VapidKeys.com](https://vapidkeys.com/)**.
+
+---
+
 ## [3.11.2] - 2026-04-04
 
 ### Fixes

README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <img width="372" src="internal/httpapi/web/githublogo.png" alt="scrumboy logo" />
   <br />
-  <img src="https://img.shields.io/badge/version-v3.11.2-blue" alt="version" />
+  <img src="https://img.shields.io/badge/version-v3.11.3-blue" alt="version" />
   <a href="LICENSE">
     <img src="https://img.shields.io/badge/license-AGPL--v3-orange" alt="license" />
   </a>
@@ -22,6 +22,7 @@
   - [Encryption key (optional)](#encryption-key-optional)
   - [OIDC / SSO login (optional)](#oidc--sso-login-optional)
   - [TLS / HTTPS (optional)](#tls--https-optional)
+  - [PWA / Web Push (optional)](#pwa--web-push-optional)
   - [Frontend build note](#frontend-build-note)
 - [Why Scrumboy?](#why-scrumboy)
 - [Who is this for?](#who-is-this-for)
@@ -109,6 +110,10 @@ See [`docs/oidc.md`](docs/oidc.md) for full setup details, constraints, and trou
 - HTTPS is enabled only when both `SCRUMBOY_TLS_CERT` and `SCRUMBOY_TLS_KEY` files exist.
 - Otherwise, the server runs on HTTP by default.
 
+### PWA / Web Push (optional)
+
+Install the app from the browser for a standalone window and better mobile UX. **Background assignment alerts** use the **Web Push API** with **VAPID** keys on the server. When both keys are set, signed-in clients attempt to subscribe automatically (browser permission may be prompted). Details and subscriber contact semantics: **[`docs/pwa.md`](docs/pwa.md)**.
+
 ### Frontend build note
 
 The Docker image and `go run` embed prebuilt assets under `internal/httpapi/web/dist`. If they are missing, build them:
@@ -167,7 +172,7 @@ Simplicity of a light Kanban, with the power of structured systems: Roles, sprin
 
 ## Integrations & API Access
 
-Scrumboy supports API access tokens for automation, integrations, and programmatic MCP access (legacy HTTP and JSON-RPC — see below).
+Scrumboy supports API access tokens for automation, integrations, and programmatic MCP access (legacy HTTP and JSON-RPC — see below). Full MCP guide for developers and agents: [`docs/mcp.md`](docs/mcp.md).
 
 You can create a token from the API and use it to call MCP endpoints directly — no browser session or cookies required.
 
@@ -197,7 +202,7 @@ Scrumboy exposes a **Model Context Protocol (MCP) compatible JSON-RPC endpoint**
 
 **Endpoint:** `POST /mcp/rpc`
 
-This is separate from the `/mcp` HTTP endpoint above and follows **JSON-RPC 2.0** (`initialize`, `tools/list`, `tools/call`, etc.). See [`API.md`](API.md) for full detail.
+This is separate from the `/mcp` HTTP endpoint above and follows **JSON-RPC 2.0** (`initialize`, `tools/list`, `tools/call`, etc.). See **[`docs/mcp.md`](docs/mcp.md)** for tools, auth, response shapes, and examples; **[`API.md`](API.md)** for the full HTTP/MCP behavior reference.
 
 #### Example: `initialize`
 
@@ -288,9 +293,9 @@ None of these are required for basic startup.
 | `SCRUMBOY_TLS_CERT` | `./cert.pem` - TLS cert for HTTPS |
 | `SCRUMBOY_TLS_KEY` | `./key.pem` - TLS key for HTTPS |
 | `SCRUMBOY_INTRANET_IP` | `192.168.1.250` - LAN IP to log for intranet access |
-| `SCRUMBOY_VAPID_PUBLIC_KEY` | (empty) - **Web Push.** VAPID public key (URL-safe base64). Required together with private key for PWA background assignment notifications. |
+| `SCRUMBOY_VAPID_PUBLIC_KEY` | (empty) - **Web Push.** VAPID public key (URL-safe base64). Required together with private key for PWA background assignment notifications and for post-login auto-subscribe in the SPA. |
 | `SCRUMBOY_VAPID_PRIVATE_KEY` | (empty) - VAPID private key (URL-safe base64). |
-| `SCRUMBOY_VAPID_SUBSCRIBER` | (empty) - Contact URL for VAPID `sub` claim (e.g. `mailto:ops@example.com`). Defaults to `mailto:scrumboy@localhost` if unset. |
+| `SCRUMBOY_VAPID_SUBSCRIBER` | (empty) - Contact for VAPID JWT `sub` (not tied to IdP). Use a **plain email** (e.g. `ops@example.com`); the server adds `mailto:`. Or set a full `mailto:...` or `https://...` URL explicitly. If unset, a built-in default is used. |
 | `SCRUMBOY_DEBUG_PUSH` | (empty) - Set to `1` to log push send/prune on the server. |
 
 `docker-compose.yml` overrides some of these (e.g. `SQLITE_BUSY_TIMEOUT_MS=5000`).
@@ -369,6 +374,8 @@ Invariants (e.g. canonical URL `/{slug}`, no UI links to `/p/{id}`) are enforced
 
 # Documentation
 
+- **MCP (HTTP tools + JSON-RPC):** [`docs/mcp.md`](docs/mcp.md) — tool catalog, auth, legacy vs `/mcp/rpc`, examples (agents & automation). See also [`API.md`](API.md) for exhaustive MCP HTTP detail.
+- **PWA / Web Push (VAPID):** [`docs/pwa.md`](docs/pwa.md) - keys, subscriber contact, post-login auto-subscribe when VAPID is configured, Settings opt-out, tradeoffs.
 - **Roles and permissions:** `docs/ROLES_AND_PERMISSIONS.md` - project roles, backend authorization, anonymous boards.
 - **Audit trail:** `docs/AUDIT_TRAIL.md` - action vocabulary, event model, integration points.
 

cmd/scrumboy/main.go

@@ -89,16 +89,16 @@ func main() {
 	}
 
 	srv := httpapi.NewServer(st, httpapi.Options{
-		Logger:         logger,
-		MaxRequestBody: cfg.MaxRequestBodyBytes,
-		ScrumboyMode:   cfg.ScrumboyMode,
-		MCPHandler:     mcp.New(st, mcp.Options{Mode: cfg.ScrumboyMode}),
-		EncryptionKey:  encKey,
-		OIDCService:    oidcSvc,
-		VAPIDPublicKey:   cfg.VAPIDPublicKey,
-		VAPIDPrivateKey:  cfg.VAPIDPrivateKey,
-		VAPIDSubscriber:  cfg.VAPIDSubscriber,
-		PushDebug:        cfg.PushDebug,
+		Logger:               logger,
+		MaxRequestBody:       cfg.MaxRequestBodyBytes,
+		ScrumboyMode:         cfg.ScrumboyMode,
+		MCPHandler:           mcp.New(st, mcp.Options{Mode: cfg.ScrumboyMode}),
+		EncryptionKey:        encKey,
+		OIDCService:          oidcSvc,
+		VAPIDPublicKey:       cfg.VAPIDPublicKey,
+		VAPIDPrivateKey:      cfg.VAPIDPrivateKey,
+		VAPIDSubscriber:      cfg.VAPIDSubscriber,
+		PushDebug: cfg.PushDebug,
 	})
 	st.SetTodoAssignedPublisher(srv.PublishTodoAssigned)