Merge branch 'develop' into publish/2.1.0

# Conflicts:
#	Jenkinsfile
#	install/release-notes.md

Author: EvilBeaver

.cursor/rules/langversion.mdc

@@ -2,4 +2,5 @@
 alwaysApply: true
 ---
 
-Проект использует .net 8.0 и LangVersion 8, поэтому при генерации кода не используй языковые фичи C#, которые отсутствуют в C# 8.
+Проект VSCode.DebugAdapter использует net framework 4.8, поэтому при генерации кода для  него не используй языковые фичи C#, которые отсутствуют в C# 7.3.
+Остальные проекты используют .net 8, можно применять C# 12.

.cursor/skills/release-notes/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: release-notes
+description: This skill creates release notes for new release by reading git commit log. Use it only when explicitly specified
+---
+
+# Release notes
+
+Когда нужно выпустить новый релиз, в репозитории нужно изменить файл install/release-notes.md (путь относительно корня репозитория)
+
+Для того, чтобы собрать данные, нужно использовать git log и вызвать команду
+
+```bat
+set LC_ALL=C.UTF-8
+set TAGNAME=%1
+
+git --no-pager log --pretty="* %%s" --no-merges %TAGNAME%..HEAD
+```
+
+где переменная TAGNAME должна быть git-тэгом предыдущего релиза. Результатом выполнения команды будут тексты коммитов, между TAGNAME и текущим состоянием ветки.
+
+Ты должен запросить у пользователя тег предыдущей версии, либо пользователь тебе сообщит его в промпте сразу.
+
+Далее, ты должен прочитать тексты коммитов, в них могут встречаться ссылки на github issues в виде указания номера задачи через решетку, например вот так:
+
+`fixes #1234 bla-bla-bla`
+
+Текст коммита также может не содержать упоминания задачи, или быть вовсе техническим/промежуточным коммитом, который в release notes попадать не должен, т.к. не описывает конечное изменение.
+
+Твоя задача и цель - взять тексты коммитов и вывести из них изменения в версии, которые будут включены в файл install/release-notes.md.
+
+Те коммиты, которые содержат ссылки на github - пойти на github в соответствующую задачу в репозитории https://github.com/EvilBeaver/OneScript/issues/<НомерЗадачи> и прочитать ее суть.
+
+Те коммиты, которые ссылок на гитхаб не содержат, ты должен просто прочитать и решить - стоит их включать в release-notes или нет, содержат ли они описание конкретной сделанной функциональности, или это промежуточный, технический и не требующий публикации коммит.
+
+Далее, ты должен сделать итоговый дайджест того, что было сделано в версии и записать это в файл install/release-notes.md. Каждая задача это отдельный bullet-point, причем ссылки на github должны быть сделаны в markdown реальными кликабельными ссылками.
+
+## Формат файла release-notes
+
+В начале записывается заголовок "Версия <НомерВерсии>. Какая сейчас конкретно версия ты должен посмотреть в файле Jenkinsfile в параметре VersionPrefix и взять его.
+
+Далее идет перечень сделанных задач, как описано выше.
+Задачи разбиваются на две группы: исправление ошибок и новые возможности. Соответственно в release notes добавляются два раздела уровня "заголовок 2" для "Новые возможности" и "Исправление ошибок". Если задач по какой-то категории нет (например, были только исправления, а новых фич не было), то соответствующий раздел не добавляется в файл совсем.
+
+## Instructions
+
+1. Определи текущую выпускаемую версию, прочитав файл Jenkinsfile и его параметр VersionPrefix в самом начале
+2. Определи тег предыдущей версии. Для этого запроси его у пользователя, если тег не был сразу задан в промпте
+3. Выполни команду gitlog, как показано выше, для получения истории коммитов между версиями
+4. Составь дайджест изменений и запиши их в install/release-notes.md

Jenkinsfile

@@ -4,7 +4,7 @@ pipeline {
     agent none
 
     environment {
-        VersionPrefix = '2.0.2'
+        VersionPrefix = '2.1.0'
         outputEnc = '65001'
     }
 

README-EN.md

@@ -34,13 +34,31 @@ The OneScript distribution already includes a set of the most commonly used pack
 
 ### Linux ###
 
+#### v2.x (current branch) — .NET 8.0 based ####
+
+Two ZIP archive variants are available:
+
+| Variant                       | Description                                | External dependencies                                                              |
+|-------------------------------|--------------------------------------------|------------------------------------------------------------------------------------|
+| **SCD** (self-contained)      | .NET Runtime is bundled inside the archive | None                                                                               |
+| **FDD** (framework-dependent) | Smaller archive                            | Requires [.NET Runtime 8.0](https://learn.microsoft.com/dotnet/core/install/linux) |
+
+Installation steps:
 - Download the ZIP archive for Linux from the [Releases](https://github.com/EvilBeaver/OneScript/releases) section or from the [official website](https://oscript.io).
 - Extract the archive to a convenient directory.
 - Set executable permissions:
   ```bash
-  chmod +x oscript
+  chmod +x ./oscript
   ```
 
+The FDD variant requires .NET Runtime 8.0 — see installation instructions for your distribution at [learn.microsoft.com/dotnet/core/install/linux](https://learn.microsoft.com/dotnet/core/install/linux).
+
+#### v1.x LTS — deb package (Mono) ####
+
+The LTS branch is distributed as a `.deb` package and runs on Mono. The package automatically installs the minimum required Mono components; however, **the debugger requires `mono-complete`**.
+
+> **Important for debugging on Ubuntu/Debian:** if breakpoints are not being hit, install `mono-complete` from the **official Mono Project repository** (not from the distribution's default repositories). For instructions specific to your system, see the [Mono Project website](https://www.mono-project.com/download/stable/#download-lin).
+
 ### MacOS ###
 
 - Download the ZIP archive for macOS (x64 or arm64) from the [Releases](https://github.com/EvilBeaver/OneScript/releases) section or from the [official website](https://oscript.io).
@@ -57,50 +75,97 @@ The OneScript distribution already includes a set of the most commonly used pack
 
 ## Preparation
 
-Links to distributions are provided below, however, please note that links may change over time and their relevance is not guaranteed. You need dotnet SDK and C++ compiler, which can be downloaded from anywhere you can find.
+To build the project you need:
+
+* [.NET SDK 8.0](https://dotnet.microsoft.com/download/dotnet/8.0) (the project's target framework is `net8.0`).
+* A C++ compiler — only required to build the native bridge `ScriptEngine.NativeApi` (support for native add-ins compatible with the 1C NativeApi). On Windows the easiest way to get one is to install [MS Build Tools](https://visualstudio.microsoft.com/visual-studio-build-tools/) or Visual Studio with the "Desktop development with C++" workload. If a C++ compiler is not available, see the `NoCppCompiler` parameter below.
 
-* Install [MS BuildTools](https://visualstudio.microsoft.com/ru/thank-you-downloading-visual-studio/?sku=buildtools&rel=16), when installing enable targeting for .net6, .net4.8, install C++ compiler.
+> Distribution links may change over time, their relevance is not guaranteed.
 
 ## Build
 
-Launch Developer Command Prompt (will appear in the Start menu after installing MSBuildTools or Visual Studio). Navigate to the OneScript repository directory. The following are commands in the Developer Command Prompt console.
-Build is performed using msbuild. Targets:
+The build is driven by MSBuild via the `Build.csproj` script in the repository root. Commands can be run with `msbuild` (Developer Command Prompt installed together with MS Build Tools/Visual Studio) or with `dotnet msbuild` (cross-platform).
 
-* CleanAll - clean previous build results
-* BuildAll - prepare files for distribution
-* MakeCPP;MakeFDD;MakeSCD;BuildDebugger - separate build targets for preparing different types of distributions
-* PrepareDistributionFiles - build full distribution packages (including libraries)
-* PackDistributions - prepare ZIP archives for distribution
-* CreateNuget - create packages for publishing to NuGet
+Main targets:
+
+* `CleanAll` — clean previous build results;
+* `BuildAll` — build binary files for distribution (FDD, SCD, debugger; native components are also built when a C++ compiler is available);
+* `MakeCPP`, `MakeFDD`, `MakeSCD`, `BuildDebugger` — individual targets that build specific parts of the distribution;
+* `GatherLibrary` — download and stage the base set of libraries (`opm`, `asserts`, `logos`, `fs`, `tempfiles`, `cli`);
+* `PrepareDistributionFiles` — build full distribution contents (including libraries and documentation);
+* `PackDistributions` — pack the distribution contents into ZIP archives for all supported platforms;
+* `BuildDocumentation` — generate the platform reference (markdown + json);
+* `CreateNuget` / `PublishNuget` — build and publish NuGet packages;
+* `Test` (`UnitTests`, `ScriptedTests`) — run unit and acceptance (BSL) tests.
 
 **Build parameters**
 
-* VersionPrefix - release number prefix, its main part, for example, 2.0.0
-* VersionSuffix - version suffix, which usually acts as an arbitrary versioning suffix according to semver, for example, beta-786 (optional)
-* NoCppCompiler - if True - C++ compiler is not installed, C++ components (NativeApi support) will not be added to the build
+* `VersionPrefix` — main part of the release number, for example `2.0.0` (defaults to `2.0.0`);
+* `VersionSuffix` — optional SemVer suffix, for example `beta-786`;
+* `NoCppCompiler` — when set to `True`, native C++ components (NativeApi) are not built and not included in the distribution (use it when no C++ compiler is installed);
+* `Configuration` — build configuration, defaults to `Release`. For a debug build on Linux use `LinuxDebug`.
 
-All distribution files will be placed in the `built` directory at the root of the 1Script repository
+All build artifacts are placed in the `built` directory at the repository root.
 
 ### Building distribution contents in a separate directory
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles
 ```
 
 ### Building with manual version specification
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:VersionPrefix=2.0.0
 ```
 
 ### Building ZIP distributions
 
 ```bat
-msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles;PackDistributions /p:VersionPrefix=2.0.0 /p:VersionSuffix=preview223
+```
+
+### Building without C++ components (no NativeApi)
+
+```bat
+dotnet msbuild Build.csproj /t:CleanAll;PrepareDistributionFiles /p:NoCppCompiler=True
 ```
 
 ### Documentation generation
 
 ```bat
-msbuild Build.csproj /t:BuildDocumentation
+dotnet msbuild Build.csproj /t:BuildDocumentation
 ```
+
+# Testing
+
+The project has two layers of tests:
+
+* **C# unit tests** — located in `src/Tests/*` (xUnit/NUnit). Run them via `dotnet test` in the corresponding test project directory or all at once:
+  ```bat
+  dotnet msbuild Build.csproj /t:UnitTests
+  ```
+* **BSL acceptance tests** — located in the `tests/` directory and executed by `testrunner.os` against a freshly built `oscript`. The repository includes wrapper scripts:
+  ```bat
+  rem Windows
+  tests\run-bsl-tests.cmd src\oscript\bin\Debug\net8.0\oscript.exe
+  ```
+
+  ```bash
+  # Linux/macOS
+  tests/run-bsl-tests.sh src/oscript/bin/Debug/net8.0/oscript
+  ```
+
+  Before running the acceptance tests, build `oscript`:
+  ```bat
+  dotnet build src/oscript/oscript.csproj
+  ```
+
+# Developer documentation
+
+If you want to contribute to the project, take a look at the additional documents in the [`docs/`](docs/) directory:
+
+* [`docs/developer_docs.md`](docs/developer_docs.md) — project architecture, solution layout and guided tour of the source code.
+* [`docs/contexts.md`](docs/contexts.md) — a practical guide to adding BSL contexts, methods, properties and global functions.
+* [`CODESTYLE.md`](CODESTYLE.md) — C# code style requirements.
+