Require release versions for script uploads

docs/guides/beta-test-plans.md

@@ -429,7 +429,13 @@ recent evidence under `test`.
 copied into a beta; later edits do not change an active plan.
 
 `POST /api/betas/:id/revisions` accepts multipart `expectedRevision`, optional
-`notes`, and replacement uploads named `file:<scriptId>`. A stale revision is
+`notes`, and replacement uploads named `file:<scriptId>`. Each script replacement
+also requires `release:<scriptId>` in `MAJOR.MINOR.PATCH` form. The update dialog
+accepts manual versions or `versions.json` to fill empty fields by exact filename.
+A changed script cannot reuse a previous release version. Missing or invalid
+versions reject the entire update without modifying beta history or deployments.
+Plugin release tags remain optional. See [script release versions](getting-started.md#script-release-versions).
+A stale revision is
 rejected. `GET /api/betas/:id` includes the current `revision` and `revisions`
 history; `GET /api/betas/:id/revisions/:revision/files/:scriptId` downloads an
 archived file (or the original pinned file before its first update).

docs/guides/getting-started.md

@@ -108,6 +108,35 @@ servers. Disruptive operations normally wait for a fresh empty lobby or a
 verified stopped container. A rebuild removes the instance's writable files.
 See [Provisioning](provisioning.md) and [Collections](collections.md) for details.
 
+## Script release versions
+
+Every new script upload needs a release version in `MAJOR.MINOR.PATCH` form,
+for example `1.2.0`. Enter a version for each file in the upload drawer, script
+page, or beta replacement dialog. Versions belong to individual scripts; a batch
+can contain different versions.
+
+To fill empty fields automatically, choose `versions.json` from the same source
+checkout as your scripts. Cherry matches exact, case-sensitive filenames (such as
+`tws_t5_hud.gsc`) and leaves entered values intact. Review the values before
+uploading. A manifest identifies source releases; it does not verify file contents.
+
+Changing a script requires a new release version. Reuploading identical bytes with
+the same version reuses the saved release; different bytes with that version are
+rejected. Older release versions can be imported. Cherry keeps its upload number
+separately, displaying labels such as `1.2.0 (upload 7)`.
+
+Historical scripts without a release label display `Unversioned (upload N)` and
+remain available for testing, promotion, and rollback. Cherry does not infer old
+versions from today's manifest or rewrite historical records. Uploading the same
+bytes with an explicit version creates a separate labeled record when needed.
+Plugins retain optional publisher tags; configurations retain automatic upload
+numbers.
+
+API clients must include multipart `releaseVersion` when creating a script with
+`POST /api/scripts` or uploading with `POST /api/scripts/:id/versions`. Missing or
+invalid versions return HTTP 400; conflicting contents return HTTP 409. The
+version upload response reports `reused: true` for an existing identical release.
+
 ## Connect game telemetry
 
 Configure your game reporter or plugin to send `EC_TELEMETRY_TOKEN` in an