@rsconcept/rstool 0.5.1 → 0.5.2

package/docs/CONCEPTUAL-SCHEMA.md

@@ -96,32 +96,3 @@ card(S1) = card(Pr1,2(S1))
 - `card(F[ξ]) = 1`.
 
 Перед `D{x∈… | ∃d1∈… ∃d2∈…}` проверь, нельзя ли взять `Pr` от уже введенного отношения.
-
-## Проверка на маленькой КМ
-
-Если семантика не очевидна, собери минимальную модель: значения для `X#`, `C#`, `S#`; затем вычисли целевые `D#`, `F#`, `P#`, `A#`.
-
-Особенно проверяй проекции, фильтры, `red`, `bool` / `debool`, аксиомы. Для важной проверки сделай скрипт-тест: сессия + значения неопределяемых конституент + проверка `success` и ожидаемого `value`.
-
-Цикл: `MODEL-TESTING.md`.
-
-## Быстрое ревью
-
-- Атрибутивная и родоструктурная экспликации не смешаны без запроса.
-- Нет проверки принадлежности к собственной типизации: `x∈X1` избыточно, если `x` уже объявлен в `X1`.
-- Покрыты главные сущности, роли, отношения, утверждения.
-- Повторяющиеся отборы вынесены в `F#`.
-- Каждая аксиома имеет понятную цель.
-- Сомнительная семантика проверена на маленькой КМ при наличии тестовых данных.
-
-## Рабочий порядок
-
-1. Собери словарь: базовые понятия, ключевые отношения, сценарий синтеза.
-2. Добавь `X#`, `C#` с конвенциями из источника.
-3. Добавь базовые `S#`: трансформация, перевод, допускание, выбор, цели, субъекты.
-4. Проверь, что базовые понятия независимы и не выводятся друг из друга.
-5. Добавь `A#` на структуры: `card`, покрытие `Pr1,2(S#)=…`, принадлежность выбора.
-6. Введи `F#` для типовых запросов.
-7. Производные понятия строй через `Pr*`, `Fi*`, `F#` от центрального `D#` и базовых `S#`.
-8. Перед каждым upsert запускай `analyzeExpression`.
-9. Для сомнительной семантики собери маленькую КМ (`MODEL-TESTING.md`).

package/docs/CONSTITUENTA.md

@@ -51,5 +51,3 @@
 3. Все глобальные ссылки уже есть в сессии.
 4. `axiom` и `statement` имеют типизацию `Logic`, иначе `expectedLogic`.
 5. Выводимая конституента с пустой формулой дает `cstEmptyDerived`.
-
-Цикл: `analyzeExpression` на черновике → исправить `diagnostics[].from/to` → `addOrUpdateConstituenta`.

package/docs/DIAGNOSTICS.md

@@ -78,8 +78,4 @@
 
 ## Цикл исправления
 
-1. Запусти `analyzeExpression`.
-2. Прочитай `code`, `from`, `to`, `params`.
-3. Исправь именно диапазон в `definitionFormal`.
-4. Не повторяй вызов без изменения ввода.
-5. После успеха вызывай `addOrUpdateConstituenta`.
+Пошаговый цикл — в `../skills/rstool-helper/GUIDE.md`, раздел «Цикл диагностик». Здесь — справочник кодов и типичных ошибок.

package/docs/MODEL-TESTING.md

@@ -11,15 +11,6 @@
 
 Для простой проверки типизации сначала используй `analyzeExpression`. КМ нужна, когда вопрос зависит от интерпретации данных и вычисленного значения.
 
-## Минимальный цикл
-
-1. Создай отдельную `createSession` или изолированную копию текущей сессии.
-2. Добавь только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
-3. Проверь формулы через `analyzeExpression` и `addOrUpdateConstituenta`.
-4. Задай значения базовых понятий через `setConstituentaValue` или `setConstituentaValues`.
-5. Вычисли проверяемую формулу через `evaluateExpression` или сохраненную конституенту через `evaluateConstituenta`.
-6. Сравни результат с ожидаемым значением; если есть несколько зависимых определений, запусти `recalculateModel`.
-
 ## Что задавать руками
 
 `basic`, `constant`, `structure` можно интерпретировать напрямую. `term`, `function`, `predicate`, `axiom`, `statement` должны вычисляться из формулы, поэтому их напрямую не задавай.

package/docs/README.md

@@ -1,6 +1,8 @@
 # Документация rstool
 
-Краткая русская справка для агентов.
+Краткая справка для агентов.
+
+**Воркфлоу и чеклисты** — в `../skills/rstool-helper/GUIDE.md` (начинай с него). Здесь — справочные правила языка и предметной области.
 
 ## Какой файл читать
 
@@ -14,4 +16,4 @@
 - **PORTAL-API.md** — объекты REST API Portal.
 - **GRAMMAR-REF.md** — краткая карта токенов и приоритетов.
 
-Контракт агента `rstool` см. в `../skills/rstool-helper/REFERENCE.md`.
+Контракт агента `rstool` и примеры — `../skills/rstool-helper/REFERENCE.md`, `EXAMPLES.md` (на русском, вместе с `GUIDE.md`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Agent-facing library for incremental RSForm construction, RSLang analysis, diagnostics, modeling, and evaluation. Wraps @rsconcept/domain with a deterministic session contract and stdio wrapper.",
   "license": "MIT",
   "author": "IRBorisov",

package/skills/README.md

@@ -6,9 +6,9 @@ Each skill lives in its own subdirectory: `skills/<skill-name>/SKILL.md` (plus r
 
 - `INSTALL.md`: agent procedure after `npm install`
 - `rstool-helper/SKILL.md`: thin entry skill — copy into the project’s agent skills folder (see `INSTALL.md`)
-- `rstool-helper/GUIDE.md`: canonical workflow and language primer
-- `rstool-helper/REFERENCE.md`: API, stdio, contract
-- `rstool-helper/EXAMPLES.md`: worked examples and pitfalls
+- `rstool-helper/GUIDE.md`: единая точка входа — воркфлоу, чеклисты, обзор языка (на русском)
+- `rstool-helper/REFERENCE.md`: API, stdio, контракт (на русском)
+- `rstool-helper/EXAMPLES.md`: примеры и типичные ошибки (на русском)
 - `../docs/*.md`: language reference (DOMAIN, SYNTAX, DIAGNOSTICS, …)
 
 ## npm workflow

package/skills/rstool-helper/EXAMPLES.md

@@ -1,8 +1,8 @@
-# rstool Examples
+# Примеры rstool
 
-Short examples for agents. For full scripts, see `../../examples/`.
+Короткие примеры для агентов. Полные скрипты — `../../examples/`. Воркфлоу — [GUIDE.md](GUIDE.md).
 
-## Minimal Session
+## Минимальная сессия
 
 ```ts
 import { CstType, RSToolAgent } from '@rsconcept/rstool';
@@ -20,7 +20,7 @@ tool.addOrUpdateConstituenta(sessionId, {
     alias: 'S1',
     cstType: CstType.STRUCTURED,
     definitionFormal: 'ℬ(X1×X1)',
-    convention: 'Elements are (parent, child) pairs with parent, child ∈ X1.'
+    convention: 'Элементы — пары (родитель, потомок); родитель, потомок ∈ X1.'
   }
 });
 
@@ -31,9 +31,9 @@ const { state, diagnostics } = tool.addOrUpdateConstituenta(sessionId, {
 console.log(state.analysis.success, diagnostics.length);
 ```
 
-## Analyze Before Upsert
+## Анализ перед upsert
 
-Use scratch analysis when syntax or `cstType` is uncertain.
+Черновой анализ, когда синтаксис или `cstType` под вопросом.
 
 ```ts
 const analysis = tool.analyzeExpression(sessionId, {
@@ -46,9 +46,9 @@ if (!analysis.success) {
 }
 ```
 
-Fix the reported `from` / `to` range, then re-run analysis. Maybe rethink the whole definition or split into multiple constituents
+Исправь диапазон `from` / `to` из отчёта и повтори анализ. При необходимости пересмотри определение целиком или разбей на несколько конституент.
 
-## Evaluation
+## Вычисление
 
 ```ts
 tool.setConstituentaValue(sessionId, {
@@ -64,11 +64,11 @@ const scratch = tool.evaluateExpression(sessionId, {
 console.log(scratch.success, scratch.value); // true, 3
 ```
 
-For stored definitions, set values for `basic`, `constant`, and `structure`, then call `evaluateConstituenta` or `recalculateModel`.
+Для сохранённых определений задай значения `basic`, `constant` и `structure`, затем вызови `evaluateConstituenta` или `recalculateModel`.
 
-## Semantic Smoke Test
+## Семантический smoke-тест
 
-When syntax is valid but meaning is uncertain, build a tiny model and assert the value.
+Синтаксис верен, но смысл неочевиден — собери маленькую модель и проверь значение.
 
 ```ts
 import { CstType, EvalStatus, RSToolAgent } from '@rsconcept/rstool';
@@ -103,15 +103,15 @@ tool.setConstituentaValues(sessionId, {
 const result = tool.evaluateConstituenta(sessionId, { constituentId: 3 });
 
 if (!result.success || result.status !== EvalStatus.HAS_DATA || JSON.stringify(result.value) !== '[0]') {
-  throw new Error(`Expected Pr1(S1) to select the first coordinate; got ${JSON.stringify(result)}`);
+  throw new Error(`Ожидалось Pr1(S1) = первая координата; получено ${JSON.stringify(result)}`);
 }
 ```
 
-Use this pattern for tests that protect important definitions. Full kinship model: `../../examples/build-kinship-rsmodel.ts`. More notes: `../../docs/MODEL-TESTING.md`.
+Подробнее: `../../docs/MODEL-TESTING.md`.
 
-## Wrapper Client
+## Клиент обёртки
 
-Use the wrapper when the agent talks to a separate `rstool-wrapper` process.
+Когда агент общается с отдельным процессом `rstool-wrapper`.
 
 ```ts
 import { CstType } from '@rsconcept/rstool';
@@ -135,36 +135,27 @@ console.log(diagnostics);
 await client.close();
 ```
 
-Manual stdio is one JSON request per line:
+Ручной stdio — один JSON-запрос на строку:
 
 ```jsonl
 { "id": "1", "method": "createSession", "params": {} }
 { "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
 ```
 
-## Export / Import
+## Экспорт / импорт
 
 ```ts
 const payload = tool.exportSession(sessionId);
 const restored = tool.importSession(payload);
 ```
 
-Export includes session state and model values.
+Экспорт включает состояние сессии и значения модели.
 
-To create files the user can upload to an existing Portal object:
+Файлы для загрузки пользователем в существующий объект Portal:
 
 ```ts
 const schemaJson = tool.exportPortalSchema(sessionId);
 const modelJson = tool.exportPortalModel(sessionId);
 ```
 
-Use `schemaJson` on a schema page and `modelJson` on a model page via **Load from JSON**.
-
-## Common mistakes
-
-- Wrong `cstType` in `analyzeExpression` → role-specific errors.
-- `term` with `X1×X1` for a relation → full Cartesian product, not relation typification.
-- `structure` with `Pr1(S1)` → wrong role; projections belong on `term` / `function`.
-- Same long `∃d1…∃dn` chain in many `D#` → define one central `D#` and use `Pr*` / `F#`.
-- `setConstituentaValue` on `term`, `axiom`, or `statement` → cannot set computed constituents directly.
-- Evaluation before base bindings → missing value, empty result, or evaluation failure.
+`schemaJson` — на странице схемы, `modelJson` — на странице модели, через **Load from JSON**.

package/skills/rstool-helper/GUIDE.md

@@ -1,68 +1,122 @@
-# RS Language & rstool
+# RSLang и rstool
 
-Compact entry guide for agents. Keep details in linked docs.
+Краткий входной гайд для агентов. Детали — в связанных документах.
 
-**RSLang** is a formal notation for conceptual schemas: concepts, relations, operations, assertions. Core ideas: membership `x∈y`, set-theoretic expressions, logical expressions, typification.
+**RSLang** — формальная нотация концептуальных схем: понятия, отношения, операции, утверждения. Основа: принадлежность `x∈y`, теоретико-множественные и логические выражения, типизация.
 
-**rstool** is the agent API for sessions, upserts, analysis, diagnostics, model values, evaluation, export/import.
+**rstool** — API агента для сессий, upsert, анализа, диагностик, значений модели, вычисления, экспорта/импорта.
 
-- Library: `@rsconcept/rstool`.
-- Analyzer: `@rsconcept/domain`.
-- Stdio wrapper: `npx rstool-wrapper`, JSON per line.
-- Node client: `RSToolWrapperClient`.
+- Библиотека: `@rsconcept/rstool`.
+- Анализатор: `@rsconcept/domain`.
+- Stdio-обёртка: `npx rstool-wrapper`, JSON построчно.
+- Node-клиент: `RSToolWrapperClient`.
 
-## What to Read
+## Что читать
 
-Paths are relative to this file.
+Пути — относительно этого файла.
 
-- API, methods, stdio, error codes: [REFERENCE.md](REFERENCE.md).
-- Worked examples and pitfalls: [EXAMPLES.md](EXAMPLES.md).
-- Domain terms: [../../docs/DOMAIN.md](../../docs/DOMAIN.md).
-- Schema design rules: [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
-- Constituents and validation: [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md).
-- Syntax: [../../docs/SYNTAX.md](../../docs/SYNTAX.md).
-- Typification: [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md).
-- Definition testing with small conceptual models: [../../docs/MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
-- Diagnostics: [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
-- Portal REST reads: [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md).
-- Grammar pointers: [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md).
+- API, методы, stdio, коды ошибок: [REFERENCE.md](REFERENCE.md).
+- Примеры: [EXAMPLES.md](EXAMPLES.md).
+- Термины предметной области: [../../docs/DOMAIN.md](../../docs/DOMAIN.md).
+- Концептуализация, создание схемы: [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
+- Конституенты и валидация: [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md).
+- Синтаксис: [../../docs/SYNTAX.md](../../docs/SYNTAX.md).
+- Типизация: [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md).
+- Проверка определений на КМ: [../../docs/MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
+- Диагностики: [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
+- Грамматика: [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md).
+- REST Portal: [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md).
 
-## Workflow
+## Воркфлоу
 
-Use this when editing or checking schemas and models.
+Все пошаговые сценарии собраны здесь. Справочные документы дают правила и детали.
 
-1. `createSession`.
-2. Develop schema - add constituents with proper type and attributes.
-3. Add dependencies before dependents.
-4. Use `analyzeExpression` before upsert when unsure.
-5. Fix diagnostics by `from` / `to` range in `definitionFormal`.
-6. When unsure about semantics, build a tiny conceptual model and evaluate test data.
+### Редактирование и проверка схемы
 
-- Set base/model values with `setConstituentaValue(s)`.
-- Evaluate with `evaluateExpression`, `evaluateConstituenta`, or `recalculateModel`.
+Когда схема уже есть и нужны точечные правки, новые конституенты или проверка формул.
 
-7. `commitStep` when the state is coherent.
-8. Persist with `exportSession` / `importSession`.
-9. For user-uploadable Portal files, use `exportPortalSchema` for schema JSON or `exportPortalModel` for model JSON.
+1. `createSession` (или продолжить существующую сессию).
+2. Развивай схему — добавляй конституенты с корректным `cstType` и атрибутами.
+3. Добавляй поставщиков раньше потребителей (см. [порядок объявления](#порядок-объявления-конституент)).
+4. Перед upsert при сомнении вызывай `analyzeExpression`.
+5. Исправляй диагностики по диапазону `from` / `to` в `definitionFormal` ([DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)).
+6. При сомнении в семантике собери маленькую КМ и проверь тестовые данные ([цикл КМ](#проверка-на-маленькой-км)).
+7. Задай базовые/модельные значения: `setConstituentaValue(s)`; вычисли: `evaluateExpression`, `evaluateConstituenta`, `recalculateModel`.
+8. `commitStep`, когда состояние согласовано.
+9. Сохрани: `exportSession` / `importSession`.
+10. Для загрузки в Portal: `exportPortalSchema` (схема) или `exportPortalModel` (модель).
 
-## Diagnostics Loop
+### Концептуализация (КС из содержания источника)
 
-1. Check `analysis.success`.
-2. If false, read `analysis.diagnostics` or `listDiagnostics`.
-3. Map `code` to a fix in `DIAGNOSTICS.md`.
-4. Patch the reported `from` / `to` range.
-5. Re-run only after changing input.
+Когда нужно построить или существенно развить КС по тексту ПО, требованиям или предметному описанию. Правила редукции, слоёв и паттернов — [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
 
-## Declaration Order
+1. Собери словарь: базовые понятия, ключевые отношения, сценарий синтеза.
+2. Добавь `X#`, `C#` с конвенциями из источника (не копируй дословно).
+3. Добавь базовые `S#`: трансформация, перевод, допускание, выбор, цели, субъекты.
+4. Проверь независимость базовых понятий — они не выводятся друг из друга.
+5. Добавь `A#` на структуры: `card`, покрытие `Pr1,2(S#)=…`, принадлежность выбора.
+6. Введи `F#` для типовых запросов.
+7. Производные понятия строй через `Pr*`, `Fi*`, `F#` от центрального `D#` и базовых `S#`.
+8. Перед каждым upsert — `analyzeExpression`; при ошибках — [цикл диагностик](#цикл-диагностик).
+9. Сомнительную семантику проверь на маленькой КМ ([цикл КМ](#проверка-на-маленькой-км), [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)).
+10. Перед показом результата пройди [чеклист ревью КС](#ревью-концептуальной-схемы).
+
+Дальше — обычное [редактирование и проверка](#редактирование-и-проверка-схемы): commit, export.
+
+### Цикл диагностик
+
+Когда `analysis.success === false` или `listDiagnostics` не пуст. Коды и типичные ошибки — [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
+
+1. Запусти `analyzeExpression` (черновик без сохранения).
+2. Прочитай `code`, `from`, `to`, `params` в `analysis.diagnostics` или через `listDiagnostics`.
+3. Сопоставь `code` с исправлением в [DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md).
+4. Исправь именно диапазон в `definitionFormal`.
+5. Не повторяй вызов без изменения ввода.
+6. После успеха — `addOrUpdateConstituenta`.
+
+### Проверка на маленькой КМ
+
+Когда синтаксис верен, но смысл формулы неочевиден. Подробности и форма данных — [MODEL-TESTING.md](../../docs/MODEL-TESTING.md).
+
+1. Отдельная `createSession` или изолированная копия текущей сессии.
+2. Только нужные поставщики: `X#`, `C#`, `S#` и проверяемые `D#` / `F#` / `P#` / `A#`.
+3. `analyzeExpression` и `addOrUpdateConstituenta`.
+4. Значения базовых понятий: `setConstituentaValue` / `setConstituentaValues`.
+5. `evaluateExpression` или `evaluateConstituenta`; сравни с ожидаемым `value`.
+6. При нескольких зависимых определениях — `recalculateModel`.
+
+Для регрессий вынеси проверку в скрипт или colocated `*.test.ts` (см. [MODEL-TESTING.md](../../docs/MODEL-TESTING.md)).
+
+### Порядок объявления конституент
 
 1. `basic`, `constant`.
-2. Core structures and key concepts.
-3. Derived constituents in topological order.
-4. Axioms and statements after their references.
+2. Базовые структуры и ключевые понятия.
+3. Производные конституенты в топологическом порядке.
+4. Аксиомы и утверждения после всех ссылок.
+
+Правила валидации по типам — [CONSTITUENTA.md](../../docs/CONSTITUENTA.md).
+
+## Чеклисты
+
+### Сессия и rstool
+
+- [ ] Отслеживается `sessionId`.
+- [ ] `cstType` соответствует роли конституенты.
+- [ ] Поставщики добавлены раньше потребителей.
+
+### Перед показом, commit и export
+
+- [ ] Схема проверена; ошибки исправлены.
+- [ ] Диагностики обработаны до `commitStep` и экспорта.
+
+### Ревью концептуальной схемы
 
-## Checklist
+Перед завершением концептуализации или крупного изменения. Правила — [CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.md).
 
-- [ ] `sessionId` tracked.
-- [ ] `cstType` matches the role.
-- [ ] Check schema and fix errors before showing result.
-- [ ] Diagnostics handled before commit/export.
+- [ ] Атрибутивная и родоструктурная экспликации не смешаны без явного запроса.
+- [ ] Нет избыточной проверки принадлежности к собственной типизации (`x∈X1`, если `x` уже в `X1`).
+- [ ] Базовые понятия независимы, введены необходимые по смысле аксиомы.
+- [ ] Покрыты главные сущности, роли, отношения, утверждения.
+- [ ] В текстовых определениях используются только понятия из схемы.
+- [ ] Повторяющиеся части формальных определений вынесены в производные понятия `D#` и `F#`.
+- [ ] Сомнительная семантика проверена на маленькой КМ при наличии тестовых данных.

package/skills/rstool-helper/REFERENCE.md

@@ -1,39 +1,39 @@
-# RS language and rstool — reference
-
-## rstool contract
-
-- Package: `@rsconcept/rstool`
-- Contract version: `1.4.0` (`CONTRACT_VERSION`)
-- Core class: `RSToolAgent`
-- Public imports: `@rsconcept/rstool` and `@rsconcept/rstool/wrapper`
-
-### Methods
-
-| Method                                                      | Purpose                                                            |
-| ----------------------------------------------------------- | ------------------------------------------------------------------ |
-| `createSession(initial?)`                                   | New in-memory session → `{ sessionId, contractVersion }`           |
-| `addOrUpdateConstituenta(sessionId, { draft })`             | Merge draft; analyze in session context → `{ state, diagnostics }` |
-| `analyzeExpression(sessionId, { expression, cstType })`     | Parse/typecheck snippet without persisting a constituent           |
-| `getFormState(sessionId)`                                   | Clone of full session state                                        |
-| `listDiagnostics(sessionId, filters?)`                      | Accumulated diagnostics; optional `constituentId` filter           |
-| `commitStep(sessionId, message?)`                           | Record revision checkpoint                                         |
-| `exportSession(sessionId)`                                  | JSON string `{ contractVersion, state, diagnostics }`              |
-| `exportPortalSchema(sessionId)`                             | Portal schema import JSON string using versioned schema shape      |
-| `exportPortalModel(sessionId)`                              | Portal model import JSON string using versioned model values shape |
-| `importSession(payload)`                                    | New session from export                                            |
-| `setConstituentaValue(sessionId, { target, type?, value })` | Set one base binding or structured value → `SessionModelState`     |
-| `setConstituentaValues(sessionId, { items })`               | Batch set values → `SessionModelState`                             |
-| `clearConstituentaValues(sessionId, { items })`             | Clear values by constituent id → `SessionModelState`               |
-| `getModelState(sessionId)`                                  | Clone of session interpretation state                              |
-| `evaluateExpression(sessionId, { expression, cstType })`    | Evaluate snippet in session context → `EvaluationResult`           |
-| `evaluateConstituenta(sessionId, { constituentId })`        | Evaluate stored definition → `EvaluationResult`                    |
-| `recalculateModel(sessionId)`                               | Recalculate all inferrable constituents → `{ items[] }`            |
+# RSLang и rstool — справочник
+
+## Контракт rstool
+
+- Пакет: `@rsconcept/rstool`
+- Версия контракта: `1.4.0` (`CONTRACT_VERSION`)
+- Основной класс: `RSToolAgent`
+- Публичные импорты: `@rsconcept/rstool` и `@rsconcept/rstool/wrapper`
+
+### Методы
+
+| Метод                                                       | Назначение                                                                    |
+| ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `createSession(initial?)`                                   | Новая in-memory сессия → `{ sessionId, contractVersion }`                     |
+| `addOrUpdateConstituenta(sessionId, { draft })`             | Слияние черновика; анализ в контексте сессии → `{ state, diagnostics }`       |
+| `analyzeExpression(sessionId, { expression, cstType })`     | Разбор/типизация фрагмента без сохранения конституенты                        |
+| `getFormState(sessionId)`                                   | Клон полного состояния сессии                                                 |
+| `listDiagnostics(sessionId, filters?)`                      | Накопленные диагностики; опциональный фильтр `constituentId`                  |
+| `commitStep(sessionId, message?)`                           | Зафиксировать контрольную точку ревизии                                       |
+| `exportSession(sessionId)`                                  | JSON-строка `{ contractVersion, state, diagnostics }`                         |
+| `exportPortalSchema(sessionId)`                             | JSON импорта схемы Portal                                                     |
+| `exportPortalModel(sessionId)`                              | JSON импорта модели Portal                                                    |
+| `importSession(payload)`                                    | Новая сессия из экспорта                                                      |
+| `setConstituentaValue(sessionId, { target, type?, value })` | Одна привязка базового понятия или структурное значение → `SessionModelState` |
+| `setConstituentaValues(sessionId, { items })`               | Пакетная установка значений → `SessionModelState`                             |
+| `clearConstituentaValues(sessionId, { items })`             | Очистка значений по id конституент → `SessionModelState`                      |
+| `getModelState(sessionId)`                                  | Клон состояния интерпретации сессии                                           |
+| `evaluateExpression(sessionId, { expression, cstType })`    | Вычисление фрагмента в контексте сессии → `EvaluationResult`                  |
+| `evaluateConstituenta(sessionId, { constituentId })`        | Вычисление сохранённого определения → `EvaluationResult`                      |
+| `recalculateModel(sessionId)`                               | Пересчёт всех выводимых конституент → `{ items[] }`                           |
 
 ### `ConstituentaDraft`
 
 ```ts
 {
-  id: number;           // stable id within session
+  id: number;           // стабильный id внутри сессии
   alias: string;
   cstType: CstType;
   definitionFormal: string;
@@ -43,27 +43,27 @@
 }
 ```
 
-Omitted text fields default to `''` in stored state.
+Пропущенные текстовые поля в сохранённом состоянии по умолчанию `''`.
 
-### `SessionState` metadata
+### Метаданные `SessionState`
 
-Set on `createSession(initial?)` or via `importSession`:
+Задаются в `createSession(initial?)` или через `importSession`:
 
 ```ts
 {
-  alias: string; // library item alias
-  title: string; // display title
-  comment: string; // developer notes
+  alias: string; // alias объекта библиотеки
+  title: string; // отображаемое название
+  comment: string; // заметки разработчика
 }
 ```
 
-All default to `''` when omitted.
+При опускании все поля по умолчанию `''`.
 
-### Model and evaluation types
+### Типы модели и вычисления
 
 ```ts
-type RSToolValue = number | RSToolValue[]; // runtime value
-type BasicBinding = Record<number, string>; // base-set element labels
+type RSToolValue = number | RSToolValue[]; // значение во время выполнения
+type BasicBinding = Record<number, string>; // подписи элементов базового множества
 
 interface SessionModelState {
   items: { id: number; type: string; value: RSToolValue | BasicBinding }[];
@@ -79,19 +79,19 @@ interface EvaluationResult {
 }
 ```
 
-Base/constant bindings use `type: "basic"` and `value: { "0": "label", … }`. Structured values use normalized typification as `type` and nested arrays for sets/tuples.
+Привязки `basic`/`constant` используют `type: "basic"` и `value: { "0": "label", … }`. Структурные значения — нормализованная типизация в `type` и вложенные массивы для множеств/кортежей.
 
-### Stdio protocol
+### Протокол stdio
 
-Process: `npx rstool-wrapper`
+Процесс: `npx rstool-wrapper`
 
-1. **Ready** (no request): `{"id":null,"ok":true,"result":{"ready":true,"wrapper":"rstool-stdio","contractVersion":"1.4.0"}}`
-2. **Request**: `{"id":"<unique>","method":"<name>","params":{...}}`
-3. **Response**: `{"id":"<same>","ok":true,"result":...}` or `{"id":"...","ok":false,"error":{"code":"...","message":"..."}}`
+1. **Ready** (без запроса): `{"id":null,"ok":true,"result":{"ready":true,"wrapper":"rstool-stdio","contractVersion":"1.4.0"}}`
+2. **Запрос**: `{"id":"<unique>","method":"<name>","params":{...}}`
+3. **Ответ**: `{"id":"<same>","ok":true,"result":...}` или `{"id":"...","ok":false,"error":{"code":"...","message":"..."}}`
 
-Extra methods: `ping`, `methods`.
+Дополнительные методы: `ping`, `methods`.
 
-Example chain:
+Пример цепочки:
 
 ```json
 {"id":"1","method":"createSession","params":{}}
@@ -108,9 +108,9 @@ Example chain:
 {"id":"9","method":"evaluateConstituenta","params":{"sessionId":"…","input":{"constituentId":3}}}
 ```
 
-`RSToolWrapperClient`: spawns `rstool-wrapper` by default and implements `waitUntilReady()`, `call(method, params)`, `close()`.
+`RSToolWrapperClient`: по умолчанию запускает `rstool-wrapper`; методы `waitUntilReady()`, `call(method, params)`, `close()`.
 
-### Analysis result
+### Результат анализа
 
 ```ts
 interface AnalysisResult {
@@ -121,79 +121,77 @@ interface AnalysisResult {
 }
 ```
 
-## RS language
+## RSLang
 
-Intro (help): language is FOL-based; set vs logic expression split; parameterized templates for term/predicate functions.
+Кратко: язык на базе логики первого порядка; разделение множественных и логических выражений; параметризованные шаблоны для функций и предикатов.
 
-- **Typification**: structure type of an expression; grades include elements (`Xi`, `Ci`), `Z`, tuples `(H1×…×Hn)`, sets `ℬ(H)`, logic `Logic`, parameterized `Hr 🠔 [H1,…,Hi]`. On `structure` (`S#`), `definitionFormal` **is** the typification. On `term` (`D#`), typification is **inferred from** the definition.
+- **Типизация**: структурный тип выражения; ступени включают элементы (`Xi`, `Ci`), `Z`, кортежи `(H1×…×Hn)`, множества `ℬ(H)`, логику `Logic`, параметризованные `Hr 🠔 [H1,…,Hi]`. У `structure` (`S#`) поле `definitionFormal` **задаёт** типизацию. У `term` (`D#`) типизация **выводится** из определения.
 
-## Grammar tokens
+## Токены грамматики
 
-From `rslang.grammar`:
+Из `rslang.grammar`:
 
-| Category               | Tokens / forms                                        |
-| ---------------------- | ----------------------------------------------------- |
-| Globals                | `X`, `C`, `S`, `D`, `A`, `T` + digits (`Global` rule) |
-| Functions / predicates | `F<n>`, `P<n>`                                        |
-| Radicals               | `R<n>`                                                |
-| Locals                 | `_a-zα-ω` + optional digits                           |
-| Logic                  | `¬` `∀` `∃` `⇔` `⇒` `∨` `&`                           |
-| Sets                   | `ℬ` `∪` `\` `∆` `∩` `×` `∈` `∉` `⊆` `⊂` …             |
-| Ops                    | `Pr`, `pr`, `Fi`, `card`, `bool`, `debool`, `red`     |
-| Literals               | digits, `Z`, `∅`                                      |
+| Категория           | Токены / формы                                          |
+| ------------------- | ------------------------------------------------------- |
+| Глобальные          | `X`, `C`, `S`, `D`, `A`, `T` + цифры (правило `Global`) |
+| Функции / предикаты | `F<n>`, `P<n>`                                          |
+| Радикалы            | `R<n>`                                                  |
+| Локальные           | `_a-zα-ω` + опциональные цифры                          |
+| Логика              | `¬` `∀` `∃` `⇔` `⇒` `∨` `&`                             |
+| Множества           | `ℬ` `∪` `\` `∆` `∩` `×` `∈` `∉` `⊆` `⊂` …               |
+| Операции            | `Pr`, `pr`, `Fi`, `card`, `bool`, `debool`, `red`       |
+| Литералы            | цифры, `Z`, `∅`                                         |
 
-Full grammar pointers and precedence notes: `docs/GRAMMAR-REF.md`.
+Полная грамматика и приоритеты: `docs/GRAMMAR-REF.md`.
 
-## Help topic map (companion docs)
+## Документация
 
-Standalone agents should consult the bundled distilled docs (`docs/*.md` inside `@rsconcept/rstool`):
+| Тема                                     | Документ                                                     |
+| ---------------------------------------- | ------------------------------------------------------------ |
+| Идентификаторы, литералы                 | `docs/SYNTAX.md` § «Имена и литералы»                        |
+| Ступени, `Logic`, параметризованные типы | `docs/TYPIFICATION.md` § «Ступени»                           |
+| Логические выражения                     | `docs/SYNTAX.md` § «Логические выражения (LE)»               |
+| Операторы над множествами                | `docs/SYNTAX.md` § «Теоретико-множественные выражения (STE)» |
+| Целочисленная арифметика                 | `docs/SYNTAX.md` § «Арифметика»                              |
+| Дополнительные и производные типизации   | `docs/TYPIFICATION.md` § «Дополнительные типизации»          |
+| Кванторы                                 | `docs/SYNTAX.md` § «Кванторы»                                |
+| Параметризованные функции, шаблоны       | `docs/SYNTAX.md` § «Параметризованные выражения»             |
+| Модель корректности / валидация          | `docs/SYNTAX.md` § «Корректность»                            |
+| Семантические тесты определений          | `docs/MODEL-TESTING.md`                                      |
+| Словарь предметной области               | `docs/DOMAIN.md`                                             |
+| Поля конституент и порядок               | `docs/CONSTITUENTA.md`                                       |
+| REST API Portal                          | `docs/PORTAL-API.md`                                         |
+| Токены грамматики / приоритеты           | `docs/GRAMMAR-REF.md`                                        |
 
-| Topic                                | Bundled doc                                |
-| ------------------------------------ | ------------------------------------------ |
-| Identifiers, literals                | `docs/SYNTAX.md` § _Identifier rules_      |
-| Grades, `Logic`, parameterized types | `docs/TYPIFICATION.md`                     |
-| Logical expressions                  | `docs/SYNTAX.md` § _Logical expressions_   |
-| Set operators                        | `docs/SYNTAX.md` § _Set-theoretic_         |
-| Integer arithmetic                   | `docs/SYNTAX.md` § _Arithmetic_            |
-| Structural / typification reshaping  | `docs/TYPIFICATION.md` § _Forming/derived_ |
-| Quantifiers                          | `docs/SYNTAX.md` § _Quantifiers_           |
-| Parameterized functions, templates   | `docs/SYNTAX.md` § _Parameterised_         |
-| Correctness / validation mindset     | `docs/SYNTAX.md` § _Correctness model_     |
-| Definition semantic tests            | `docs/MODEL-TESTING.md`                    |
-| Domain vocabulary                    | `docs/DOMAIN.md`                           |
-| Constituent fields and ordering      | `docs/CONSTITUENTA.md`                     |
-| Portal REST API                      | `docs/PORTAL-API.md`                       |
-| Grammar tokens / precedence          | `docs/GRAMMAR-REF.md`                      |
+Воркфлоу и чеклисты — `skills/rstool-helper/GUIDE.md`.
 
-## Error codes
+## Коды ошибок
 
-rstool re-exports `RSErrorCode.definitionNotAllowed` (`0x8862`) for base/constant violations.
+Категории и исправления по коду: `docs/DIAGNOSTICS.md`.
 
-Categories and per-code fix guidance: `docs/DIAGNOSTICS.md`.
+Категории:
 
-Categories:
+- `0x84xx` — синтаксис / разбор
+- `0x28xx` — предупреждения локальных объявлений
+- `0x88xx` — семантика / типы
+- `0x886x` — уровень конституент (пустая производная, запрещённое определение)
+- `0x81xx` — вычисление (runtime; из `evaluateExpression` / `evaluateConstituenta`)
 
-- `0x84xx` — syntax / parse
-- `0x28xx` — local declaration warnings
-- `0x88xx` — semantic / type
-- `0x886x` — constituent-level (empty derived, definition not allowed)
-- `0x81xx` — evaluation (runtime; returned by `evaluateExpression` / `evaluateConstituenta`)
+## Форма экспорта сессии
 
-## Exported session shape
+`exportSession(sessionId)` возвращает JSON-строку `{ contractVersion, state, diagnostics }`.
 
-`exportSession(sessionId)` returns a JSON string with `{ contractVersion, state, diagnostics }`.
+- `state.alias`, `state.title`, `state.comment` — метаданные объекта библиотеки для экспорта в Portal (`comment` → JSON `description`).
+- `state.items[]` — каждая конституента с `id`, `alias`, `cstType`, `definitionFormal`, опциональными текстовыми полями и вложенным результатом анализа.
+- `state.model.items[]` — присутствует, если заданы значения интерпретации.
+- `diagnostics[]` — накопленные диагностики со смещениями и кодами.
 
-- `state.alias`, `state.title`, `state.comment` — library-item metadata for Portal export (`comment` → JSON `description`).
-- `state.items[]` contains each constituent with `id`, `alias`, `cstType`, `definitionFormal`, optional text fields, and nested analysis output.
-- `state.model.items[]` is present when interpretation values have been set.
-- `diagnostics[]` contains accumulated diagnostics with offsets and codes.
+## JSON импорта Portal
 
-## Portal import JSON
+Для **Load from JSON** на существующей схеме или модели Portal:
 
-For **Load from JSON** on an existing Portal schema or model:
+- `exportPortalSchema(sessionId)` — файл схемы
+- `exportPortalModel(sessionId)` — файл модели
 
-- `exportPortalSchema(sessionId)` — schema file
-- `exportPortalModel(sessionId)` — model file
-
-- Schema `items[]`: versioned constituent fields (`cst_type`, `definition_formal`, `term_raw`, …).
-- Model `items[]`: `{ id, type, value }` per binding.
+- Схема `items[]`: поля конституент (`cst_type`, `definition_formal`, `term_raw`, …).
+- Модель `items[]`: `{ id, type, value }` на каждую привязку.

package/skills/rstool-helper/SKILL.md

@@ -18,9 +18,9 @@ Then continue with the canonical files below.
 
 ## Canonical files (read before rstool work)
 
-- **Start here** — workflow: `node_modules/@rsconcept/rstool/skills/rstool-helper/GUIDE.md`
-- API, stdio, contract: `node_modules/@rsconcept/rstool/skills/rstool-helper/REFERENCE.md`
-- Examples, pitfalls: `node_modules/@rsconcept/rstool/skills/rstool-helper/EXAMPLES.md`
+- **Start here** — воркфлоу и чеклисты: `node_modules/@rsconcept/rstool/skills/rstool-helper/GUIDE.md`
+- API, stdio, контракт: `node_modules/@rsconcept/rstool/skills/rstool-helper/REFERENCE.md`
+- Примеры, типичные ошибки: `node_modules/@rsconcept/rstool/skills/rstool-helper/EXAMPLES.md`
 - Language / domain docs: `node_modules/@rsconcept/rstool/docs/*.md`
 - Install procedure: `node_modules/@rsconcept/rstool/skills/INSTALL.md`