docs(release): document nightly downloads and build workflow

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

4 files changed, 31 insertions, 2 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index ccbd9bf..0e5d2e9 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -180,6 +180,29 @@ on Linux. LLVM 23 uses `CreateGlobalString` for opaque string pointers,
 `hasTerminator()` for block termination checks (its `getTerminator()` requires an
 existing terminator), and an explicit `llvm::Triple` for the embedded target.
 
+## Nightly builds
+
+`.github/workflows/nightly-build.yml` runs on every push to `main`, without path
+filters. A shared concurrency group cancels superseded runs. The cleanup job
+requires the existing `nightly-build` release and deletes all uploaded assets,
+including paginated results, before either build starts. It never creates or
+deletes the release and preserves its tag, title and notes. GitHub's generated
+source downloads remain available.
+
+Compiler and plugin jobs run independently on Ubuntu 24.04 x86_64, checking out
+the push SHA. The compiler uses LLVM/Clang 23 from apt.llvm.org, Release and
+EMBEDDED settings, Pandoc, and the existing `release` target. It extracts and
+checks the archive, then runs a small OUTPUT program with the packaged binary.
+The plugin uses Node.js 22, `npm ci --ignore-scripts` and `npm run package`, then
+checks VSIX contents. Each job uploads directly after its own checks pass;
+failure in one does not block the other. No Actions artifacts are uploaded.
+Cleanup and uploads check main's current SHA to avoid modifying nightly for a
+superseded push. The workflow uses `GITHUB_TOKEN` with `contents: write`.
+Compiler package names retain the existing commit-based version; the VSIX uses
+`plugin/package.json`'s version. Before committing workflow changes, run
+actionlint, simulate release API calls, and smoke-test the packages locally;
+do not modify the real release for local verification.
+
 ## Layout
 
 | Path | Contents |
diff --git a/AGENTS/PITFALLS.md b/AGENTS/PITFALLS.md
index abea2fa..47910ce 100644
--- a/AGENTS/PITFALLS.md
+++ b/AGENTS/PITFALLS.md
@@ -103,5 +103,7 @@ random files (OPENFILE...FOR RANDOM/SEEK/GETRECORD/PUTRECORD — TYPE is done, s
 are unblocked now; the RANDOM keyword is reserved and gives a dedicated parse error),
 DATE, INPUT into array elements, string escape sequences,
 array-typed record fields, whole-array RETURN, class methods/constructors/destructors,
-NEW and class inheritance. No compiler tests or CI exist; verify
-changes by compiling sample programs end-to-end (command sequence in `ARCH.md`).
+NEW and class inheritance. There is no dedicated compiler test suite; nightly CI
+smoke-tests the packaged EMBEDDED compiler and runs the existing plugin tests.
+Verify compiler changes by compiling sample programs end-to-end (command
+sequence in `ARCH.md`).
diff --git a/README.md b/README.md
index 5895679..8a9ccc8 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,8 @@ A compiler for CIE Pseudocode (A Level 9618 Computer Science)
 
 [Usage quick reference](doc/cpsc.1.md) · [Build guide](doc/build.md) · [Installation and releases](doc/install.md)
 
+Download the Linux x86_64 compiler package and VS Code extension from [Nightly Build](https://github.com/ovfor4/cie-pseudocode-compiler/releases/tag/nightly-build). The compiler uses EMBEDDED mode and needs no LLVM installation. Each push to `main` removes the previous attachments before rebuilding both packages; each package appears when its build and checks finish.
+
 Details can be found here: [Pseudocode Guide for Teachers](https://www.cambridgeinternational.org/Images/697401-2026-pseudocode-guide-for-teachers.pdf)
 
 ## Features
diff --git a/plugin/README.md b/plugin/README.md
index 37eb0a6..1718945 100644
--- a/plugin/README.md
+++ b/plugin/README.md
@@ -6,6 +6,8 @@ VS Code support for this project's `.cps` files. Requires VS Code 1.85 or newer
 
 ## Install
 
+Download the VSIX from [Nightly Build](https://github.com/ovfor4/cie-pseudocode-compiler/releases/tag/nightly-build). The same release provides the Linux x86_64 compiler with execution support.
+
 In the Extensions panel, choose **... > Install from VSIX...** and select `cie-pseudocode-0.1.0.vsix`, or run:
 
 ```sh