diff --git a/.forge/specs/readme-quickstart/decomposition.md b/.forge/specs/readme-quickstart/decomposition.md new file mode 100644 index 0000000..10ed930 --- /dev/null +++ b/.forge/specs/readme-quickstart/decomposition.md @@ -0,0 +1,22 @@ +# README Quick Start corrections + +> Feature **readme-quickstart** — base branch `main`, +> branch prefix `forge`. + +## Pieces + + +1. **p1: Correct and tighten the README Quick Start** + + Fix the Scala version and verify the README Quick Start steps so a new user can get running first try. + + `pending` + + + +--- + +*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.* diff --git a/.forge/specs/readme-quickstart/design.md b/.forge/specs/readme-quickstart/design.md new file mode 100644 index 0000000..db4fa8e --- /dev/null +++ b/.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. diff --git a/.forge/specs/readme-quickstart/manifest.json b/.forge/specs/readme-quickstart/manifest.json new file mode 100644 index 0000000..03d68e2 --- /dev/null +++ b/.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 + } + ] +} diff --git a/.forge/specs/readme-quickstart/pieces/p1.md b/.forge/specs/readme-quickstart/pieces/p1.md new file mode 100644 index 0000000..e844fe0 --- /dev/null +++ b/.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).