docs: update README and docs for v2.28.0 release (#1054)

* docs: add Node LTS pinning guide for macOS Homebrew users

New doc (docs/node-lts-macos.md) explains how to pin Node 24 LTS
via Homebrew to avoid running on odd-numbered development releases.
Covers brew install/link/pin, version managers as alternatives,
and verification steps.

Added notice banner in README linking to the guide.

* docs: update README and docs for v2.28.0 release

- README: add 'What's New in v2.28' section with key features
- commands.md: add /gsd update, /gsd export --html --all, and
  Export section with usage examples
- auto-mode.md: add --all flag to export, add Failure Recovery
  (v2.28) section documenting reliability hardening
- getting-started.md: mention /gsd update as in-session option

README.md

@@ -24,6 +24,19 @@ One command. Walk away. Come back to a built project with clean git history.
 
 ---
 
+## What's New in v2.28
+
+- **`gsd headless query`** — instant JSON snapshot of project state (~50ms, no LLM session)
+- **`/gsd update`** — update GSD to the latest version without leaving your session
+- **`/gsd export --html --all`** — generate retrospective HTML reports for all milestones at once
+- **Reliability hardening** — atomic file writes, OAuth fetch timeouts, RPC exit detection, blob GC, LSP init retry with backoff
+- **RPC utilities** now part of the public API for headless/scripted integrations
+- **npm** established as the canonical package manager
+
+See the full [Changelog](./CHANGELOG.md) for details.
+
+---
+
 ## Documentation
 
 Full documentation is available in the [`docs/`](./docs/) directory:

docs/auto-mode.md

@@ -157,7 +157,11 @@ After a milestone completes, GSD auto-generates a self-contained HTML report in
 auto_report: true    # enabled by default
 ```
 
-Generate manually anytime with `/gsd export --html`.
+Generate manually anytime with `/gsd export --html`, or generate reports for all milestones at once with `/gsd export --html --all` (v2.28).
+
+### Failure Recovery (v2.28)
+
+v2.28 hardens auto-mode reliability with multiple safeguards: atomic file writes prevent corruption on crash, OAuth fetch timeouts (30s) prevent indefinite hangs, RPC subprocess exit is detected and reported, and blob garbage collection prevents unbounded disk growth. Combined with the existing crash recovery and headless auto-restart, auto-mode is designed for true "fire and forget" overnight execution.
 
 ## Controlling Auto Mode
 

docs/commands.md

@@ -19,6 +19,8 @@
 | `/gsd cleanup` | Clean up GSD state files and stale worktrees |
 | `/gsd visualize` | Open workflow visualizer (progress, deps, metrics, timeline) |
 | `/gsd export --html` | Generate self-contained HTML report for current or completed milestone |
+| `/gsd export --html --all` | Generate retrospective reports for all milestones at once |
+| `/gsd update` | Update GSD to the latest version in-session |
 | `/gsd knowledge` | Add persistent project knowledge (rule, pattern, or lesson) |
 | `/gsd help` | Categorized command reference with descriptions for all GSD subcommands |
 
@@ -192,3 +194,30 @@ gsd --mode mcp
 ```
 
 The server registers all tools from the agent session and maps MCP `tools/list` and `tools/call` requests to GSD tool definitions. It runs until the transport closes.
+
+## In-Session Update
+
+`/gsd update` checks npm for a newer version of GSD and installs it without leaving the session.
+
+```bash
+/gsd update
+# Current version: v2.28.0
+# Checking npm registry...
+# Updated to v2.29.0. Restart GSD to use the new version.
+```
+
+If already up to date, it reports so and takes no action.
+
+## Export
+
+`/gsd export` generates reports of milestone work.
+
+```bash
+# Generate HTML report for the active milestone
+/gsd export --html
+
+# Generate retrospective reports for ALL milestones at once
+/gsd export --html --all
+```
+
+Reports are saved to `.gsd/reports/` with a browseable `index.html` that links to all generated snapshots.

docs/getting-started.md

@@ -8,7 +8,7 @@ npm install -g gsd-pi
 
 Requires Node.js ≥ 20.6.0 (22+ recommended) and Git.
 
-GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip.
+GSD checks for updates once every 24 hours. When a new version is available, you'll see an interactive prompt at startup with the option to update immediately or skip. You can also update from within a session with `/gsd update`.
 
 ### VS Code Extension