Docs update

Author: CrushBy

docs/brief/en/Brief.md

@@ -30,15 +30,20 @@ Which branch: `language` — statement / operator syntax; `paradigm` — concept
 - A project is composed of **modules**; how data is stored and made fast is the
   physical model, and exchange with anything outside is integration.
 
-Two misreadings worth pre-empting, because everything downstream depends on
-them:
+Three misreadings worth pre-empting, because everything downstream depends
+on them:
 
 - A class does not map to a table. A table holds property values; its key
   fields hold object ids and are typed by the parameter classes of those
   properties.
 - The system modules are a library of ordinary properties and actions, not
   built-in language operators. Only `System` is implicit; the rest need
   `REQUIRE` before their declarations are reachable.
+- `.lsf` is not a shell around code in another language. The application —
+  its model, computations, checks, reactions to changes, forms and access
+  rights — is written in these elements; Java and JavaScript enter it only
+  where the platform itself admits them (`INTERNAL`, `EXTERNAL`, `FORMULA`,
+  `CUSTOM`) and for what those operators are for.
 
 ## The brief articles — which one to open
 

docs/brief/ru/Brief.md

@@ -29,7 +29,7 @@ slug: "/Brief"
 - Проект собирается из **модулей**; как данные хранятся и за счёт чего работают
   быстро — это физическая модель, а обмен с чем угодно снаружи — интеграция.
 
-Два непонимания, которые стоит снять заранее, потому что от них зависит всё
+Три непонимания, которые стоит снять заранее, потому что от них зависит всё
 дальнейшее:
 
 - Класс не отображается в таблицу. Таблица хранит значения свойств; её
@@ -38,6 +38,11 @@ slug: "/Brief"
 - Системные модули — это библиотека обычных свойств и действий, а не
   встроенные операторы языка. Неявно подключается только `System`, остальным
   нужен `REQUIRE`, чтобы их объявления стали доступны.
+- `.lsf` — не оболочка над кодом на другом языке. Приложение — его модель,
+  вычисления, проверки, реакции на изменения, формы и права доступа —
+  пишется этими элементами; Java и JavaScript попадают в него только там,
+  где их допускает сама платформа (`INTERNAL`, `EXTERNAL`, `FORMULA`,
+  `CUSTOM`), и по назначению этих операторов.
 
 ## Статьи brief — какую открыть
 

docs/rules/en/Rules.md

@@ -59,6 +59,43 @@ the name in the first column.
    the user which area went unread, and MUST NOT present the result as
    rule-checked.
 
+## Choice of mechanism (MANDATORY)
+
+1. PLATFORM MECHANISMS FIRST. An application on lsFusion is
+   written in `.lsf`. Wherever the platform provides a
+   mechanism — the data model, computations, constraints,
+   events, actions, session control, forms, access rights —
+   the assistant MUST implement it with that mechanism:
+   classes, properties, actions, `CONSTRAINT`, `WHEN`,
+   `NEWSESSION` / `APPLY`, `FORM`, the security policy.
+   The assistant MUST NOT use `.lsf` as a shell over its own
+   implementation of these mechanisms in Java, JavaScript or
+   another language: a separate server part, a separate
+   interface with its own data operations, a computation or
+   a check duplicated outside the platform.
+
+2. WHAT IS NOT APPLICATION CODE. The rule concerns the
+   application's own code. It does not concern the platform's
+   own Java implementation (the server and the clients),
+   auxiliary development tooling (build, test and verification
+   scripts), or the operators through which the platform itself
+   admits code in another language, used for what they are for:
+   `EXTERNAL` and `INTERNAL` for reaching a system outside the
+   platform or a component of its own deployment, `FORMULA` for
+   an SQL expression, `CUSTOM` and a custom view on a React
+   component for rendering that the standard views do not
+   provide. Java or JavaScript present in the project is not a
+   violation in itself; business logic moved out of `.lsf` is.
+
+3. WHEN CODE OUTSIDE `.lsf` IS ALLOWED. Only at an established
+   limitation of the platform or an explicit requirement of the
+   user, and only for the part that limitation or requirement
+   covers. A documentation search with no suitable result does
+   not establish a limitation: before deciding on such code the
+   assistant MUST read the area's brief
+   (`lsfusion_get_guidance(brief='<name>')`) and search
+   `paradigm` and `how-to`.
+
 ## Mandatory workflow
 
 1. ELEMENT IDENTIFICATION ORDER (MANDATORY)

docs/rules/ru/Rules.md

@@ -61,6 +61,44 @@ slug: "/Rules"
    ОБЯЗАН сказать пользователю, какая область осталась непрочитанной, и
    НЕ ДОЛЖЕН выдавать результат за проверенный на соответствие правилам.
 
+## Выбор механизма (ОБЯЗАТЕЛЬНО)
+
+1. СНАЧАЛА МЕХАНИЗМЫ ПЛАТФОРМЫ. Приложение на lsFusion пишется
+   на `.lsf`. Везде, где платформа предоставляет механизм —
+   модель данных, вычисления, ограничения, события, действия,
+   управление сессиями, формы, права доступа, — ассистент
+   ОБЯЗАН пользоваться этим механизмом: классами,
+   свойствами, действиями, `CONSTRAINT`, `WHEN`,
+   `NEWSESSION` / `APPLY`, `FORM`, политикой безопасности.
+   Ассистент НЕ ДОЛЖЕН использовать `.lsf` как оболочку над
+   собственной реализацией этих механизмов на Java, JavaScript
+   или другом языке: отдельной серверной частью, отдельным
+   интерфейсом со своими операциями над данными, вычислением
+   или проверкой, продублированными вне платформы.
+
+2. ЧТО НЕ ЯВЛЯЕТСЯ ПРИКЛАДНЫМ КОДОМ. Правило касается
+   собственного кода приложения. Оно не касается штатной
+   Java-реализации самой платформы (сервера и клиентов),
+   вспомогательных инструментов разработки (сценариев сборки,
+   тестирования и проверки) и операторов, которыми сама
+   платформа допускает код на другом языке, при использовании
+   по назначению: `EXTERNAL` и `INTERNAL` — для обращения к
+   системе вне платформы или к компоненту её собственной
+   поставки, `FORMULA` — для выражения на SQL, `CUSTOM` и
+   пользовательское представление на компоненте React — для
+   отрисовки, которой не дают стандартные представления.
+   Наличие Java или JavaScript в проекте само по себе не
+   нарушение; нарушение — бизнес-логика, вынесенная из `.lsf`.
+
+3. КОГДА КОД ВНЕ `.lsf` ДОПУСТИМ. Только при установленном
+   ограничении платформы или явном требовании пользователя и
+   только в объёме этого ограничения или требования. Поиск по
+   документации без подходящего результата ограничения не
+   устанавливает: прежде чем решить в пользу такого кода,
+   ассистент ОБЯЗАН прочитать brief области
+   (`lsfusion_get_guidance(brief='<имя>')`) и выполнить поиск
+   по `paradigm` и `how-to`.
+
 ## Обязательный порядок работы
 
 1. ПОРЯДОК ИДЕНТИФИКАЦИИ ЭЛЕМЕНТОВ (ОБЯЗАТЕЛЬНО)