[design] README Quick Start corrections

.forge/specs/readme-quickstart/decomposition.md

@@ -0,0 +1,22 @@
+# README Quick Start corrections
+
+> Feature **readme-quickstart** — base branch `main`,
+> branch prefix `forge`.
+
+## Pieces
+
+<!-- forge:order-start -->
+1. <!-- forge:piece p1 -->**p1: Correct and tighten the README Quick Start**<!-- /forge:piece -->
+   <!-- forge:editable-summary p1 -->
+   Fix the Scala version and verify the README Quick Start steps so a new user can get running first try.
+   <!-- /forge:editable-summary -->
+   <!-- forge:status p1 -->`pending`<!-- /forge:status -->
+
+<!-- forge:order-end -->
+
+---
+
+*Rendered by [Forge](https://github.com/anthropics/forge) from
+`manifest.json`. Edit a piece summary or reorder the list between the
+`forge:order-start` / `forge:order-end` markers above, then run
+`forge reconcile readme-quickstart` to import the change.*

.forge/specs/readme-quickstart/design.md

@@ -0,0 +1,68 @@
+# README Quick Start corrections
+
+## Problem
+
+The root `README.md` has a "🚀 Quick Start" section that looks complete but
+misleads a first-time contributor:
+
+- It lists **Scala 2.13** in the Quick Start prerequisites and again in
+  **Architecture → Technology Stack**, but the build is **Scala 3.7.1**
+  (`build.sbt: ThisBuild / scalaVersion := "3.7.1"`).
+- The rest of the Quick Start (prerequisites, `.env` setup, backend/frontend
+  run steps, ports) is spread across the file and has not been verified to be
+  internally consistent and correct against the repo.
+
+Net effect: a new user following the steps top-to-bottom can hit an incorrect
+fact and stall before getting a server running.
+
+## Approach
+
+A documentation-only revision of `README.md`. No source, build, or
+`.env.example` changes.
+
+1. **Correct the Scala version everywhere it appears.** Replace "Scala 2.13"
+   with "Scala 3" in both the Quick Start prerequisites and the
+   Architecture → Technology Stack section. Plain "Scala 3" is preferred over
+   pinning "3.7.1" in prose so the README does not drift on the next bump; the
+   exact version stays in `build.sbt`.
+
+2. **Verify and correct the remaining Quick Start facts** against the repo, and
+   leave correct ones unchanged. Verified during design:
+   - Toolchain in use: Java 21 (`java -version`), sbt 1.11.3
+     (`project/build.properties`). The README's "Java 17+" / "sbt 1.8+" are
+     stated as minimums — keep unless shown to be wrong; do not regress them.
+   - Node.js prerequisite for the frontend.
+   - `.env` setup: `.env.example` exists in the repo root; `cp .env.example .env`
+     is correct.
+   - Backend start: `sbt szorkStart` and `sbt "~szorkStart"`.
+   - Frontend: `cd frontend`, `npm install`, `npm run dev`; dev server is Vite
+     on **port 3090** (`frontend/vite.config.mts`), URL `http://localhost:3090`.
+   - Ports: HTTP **8090** (`SzorkConfig.scala`) and WebSocket **9002**
+     (`SzorkServer.scala`) — already correct in the README.
+
+3. **Keep the section tight and linear** — a single clone → configure → run
+   path, ordered so the steps work in sequence.
+
+## Decisions
+
+- The human dismissed the clarifying questions, so defaults were taken:
+  - Interpretation: **improve the existing README Quick Start**, not create a
+    new file.
+  - **Factual accuracy is in scope** — the Scala version mismatch is fixed as
+    part of this work.
+- Version is written as "Scala 3" (not "3.7.1") in prose to avoid future drift;
+  `build.sbt` remains the single source of truth for the exact version.
+
+## Scope: single piece
+
+This is one small, internally-consistent edit to a single file, comfortably
+reviewable in one sitting. The feature is therefore a single piece (`p1`).
+Splitting it into setup/edit/cleanup stages would add overhead without value.
+
+## Non-goals
+
+- No new standalone `QUICKSTART.md` — the README section is the home for this.
+- No rewrite of unrelated README sections (Features, How It Works, About,
+  Contributors, License) beyond the version corrections noted above.
+- No changes to source code, build files, or `.env.example`.
+- No expansion into troubleshooting, Docker, or deployment docs.

.forge/specs/readme-quickstart/manifest.json

@@ -0,0 +1,25 @@
+{
+  "schemaVersion": 1,
+  "featureId": "readme-quickstart",
+  "title": "README Quick Start corrections",
+  "baseBranch": "main",
+  "branchPrefix": "forge",
+  "mode": "claude-driver",
+  "designPr": null,
+  "pieces": [
+    {
+      "id": "p1",
+      "order": 1,
+      "title": "Correct and tighten the README Quick Start",
+      "summary": "Fix the Scala version and verify the README Quick Start steps so a new user can get running first try.",
+      "specPath": "pieces/p1.md",
+      "acceptanceHash": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
+      "status": "pending",
+      "baseSha": null,
+      "prNumber": null,
+      "mergeCommit": null,
+      "mergedAt": null,
+      "attempts": 0
+    }
+  ]
+}

.forge/specs/readme-quickstart/pieces/p1.md

@@ -0,0 +1,55 @@
+# p1 — Correct and tighten the README Quick Start
+
+## Goal
+
+Revise the "🚀 Quick Start" section of the root `README.md` (and the directly
+related Scala version mention in Architecture → Technology Stack) so a brand-new
+user can go from clone to a running server by following the steps top-to-bottom
+with no incorrect facts. Documentation-only.
+
+## Scope
+
+- Edit `README.md` only. No source, build, or `.env.example` changes.
+
+## Changes
+
+1. Replace **"Scala 2.13"** with **"Scala 3"** everywhere it appears in
+   `README.md`:
+   - Quick Start → Prerequisites.
+   - Architecture → Technology Stack ("Backend: Scala 2.13 …").
+   Use plain "Scala 3" (do not pin "3.7.1" in prose).
+2. Verify each remaining Quick Start fact against the repo and correct any that
+   are wrong; leave correct ones unchanged:
+   - Prerequisites: Java, sbt, Node.js (repo toolchain is Java 21 / sbt 1.11.3;
+     keep the README's stated minimums unless shown wrong).
+   - `.env` setup: `.env.example` exists and `cp .env.example .env` is accurate.
+   - Backend start: `sbt szorkStart` and `sbt "~szorkStart"`.
+   - Frontend: `cd frontend`, `npm install`, `npm run dev`, dev URL
+     `http://localhost:3090`.
+   - Ports: HTTP 8090, WebSocket 9002.
+3. Keep the Quick Start ordered as a single linear clone → configure → run path;
+   do not add new top-level sections.
+
+## Acceptance criteria
+
+- [ ] `README.md` contains **no occurrence of "2.13"** (case-insensitive;
+      `grep -ci "2\.13" README.md` returns 0).
+- [ ] `README.md` refers to **Scala 3** in both the Quick Start prerequisites and
+      the Architecture → Technology Stack section.
+- [ ] The Scala version stated for the backend is consistent with `build.sbt`
+      (`scalaVersion := "3.7.1"`, i.e. Scala 3); no other Scala major version is
+      stated.
+- [ ] The `.env` setup step references `.env.example` (which exists in the repo
+      root) with a correct `cp .env.example .env` command.
+- [ ] Backend start instructions show `sbt szorkStart` and the hot-reload
+      variant `sbt "~szorkStart"`.
+- [ ] Frontend instructions show `cd frontend`, `npm install`, `npm run dev`,
+      and the dev URL `http://localhost:3090`.
+- [ ] Ports referenced match the code: HTTP **8090** and WebSocket **9002**.
+- [ ] The Quick Start reads as a single top-to-bottom path (Prerequisites →
+      Environment Setup → Backend → Frontend) with no out-of-order steps.
+- [ ] Only `README.md` is modified — no changes to source code, build files, or
+      `.env.example`.
+- [ ] Unrelated README sections (Features, How It Works, About, Contributors,
+      License) are unchanged except for the Scala version corrections.
+- [ ] Documentation-only change with no build impact (`sbt compile` unaffected).