@rsconcept/rstool 0.1.0

package/docs/SYNTAX.md

@@ -0,0 +1,139 @@
+# RSLang syntax reference
+
+Distilled from the Portal help topics under `help-rslang-*`. Use this when constructing or repairing RSLang expressions. For full grammar tokens see `GRAMMAR-REF.md`. For typification rules see `TYPIFICATION.md`.
+
+## Identifier rules
+
+- **Globals** (concept aliases): uppercase Latin letter + digits — `X1`, `C2`, `S3`, `D11`, `F7`, `P4`, `A6`, `T9`, `N12`. The leading letter must match the constituent's role.
+- **Radicals**: identifiers starting with `R` — used inside template parameterised expressions to denote arbitrary typifications (`R1`, `R2`).
+- **Locals** (bound variables): lowercase Latin or Greek letter, optionally with digits — `x`, `ξ`, `μ2`, `y1`.
+- **Special identifiers** — reserved tokens (`Z`, `∅`, operators).
+
+## Literals
+
+- **Integers**: digit sequence, no negative literal: `0`, `42`. Negation is a binary subtraction `0 - n`.
+- **Integer set**: `Z`.
+- **Empty set**: `∅` (typification `ℬ(R0)` — set of arbitrary element structure).
+
+## Set-theoretic expressions
+
+| Construct | Syntax | Notes |
+|-----------|--------|-------|
+| Union | `D1 ∪ D2` | |
+| Intersection | `D1 ∩ D2` | |
+| Difference | `D1 \ D2` | |
+| Symmetric difference | `D1 ∆ D2` | |
+| Cartesian product | `X1 × X2` | typification: tuple |
+| Boolean / power set | `ℬ(X1)` | set of all subsets |
+| Tuple | `(a, b, c)` | ordered, n ≥ 2 |
+| Enumeration | `{a, b, c}` | unordered, n ≥ 1 |
+| Singleton | `bool(a)` ≡ `{a}` | |
+| Desingleton | `debool({a})` ≡ `a` | only for one-element sets |
+| Sum set | `red(S1)` | union of inner sets; `S1` must be a set of sets |
+| Small projection | `pr1((a1, …, an))` | returns `a1` |
+| Large projection | `Pr1(S1)` | set of first components of tuples in `S1` |
+| Filter | `Fi1[D1](S1)` | subset of `S1` whose first projection ∈ `D1` |
+
+Indices `1` may be any natural number or comma-separated multi-index (`pr1,3((a1, a2, a3, a4)) = (a1, a3)`, `Fi1,2[D1](S1)`).
+
+## Logical expressions
+
+### Set-theoretic predicates
+
+| Predicate | Syntax |
+|-----------|--------|
+| Membership | `ξ ∈ S` |
+| Non-membership | `ξ ∉ S` |
+| Set equality | `S1 = S2` |
+| Set inequality | `S1 ≠ S2` |
+| Inclusion | `S1 ⊆ S2` |
+| Strict inclusion | `S1 ⊂ S2` |
+| Non-inclusion | `S1 ⊄ S2` |
+
+### Arithmetic predicates (typification `Logic`)
+
+`a = b`, `a ≠ b`, `a < b`, `a ≤ b`, `a > b`, `a ≥ b`.
+
+### Connectives
+
+| Connective | Syntax |
+|------------|--------|
+| Negation | `¬A` |
+| Conjunction | `A & B` |
+| Disjunction | `A ∨ B` |
+| Implication | `A ⇒ B` |
+| Equivalence | `A ⇔ B` |
+
+The constants `TRUE` and `FALSE` are **not** used inside schema explications.
+
+## Quantifiers
+
+| Form | Syntax |
+|------|--------|
+| Universal | `∀ξ∈STE (LE(ξ))` |
+| Existential | `∃ξ∈STE (LE(ξ))` |
+| Tuple binding | `∀(ξ1, ξ2)∈STE (LE(ξ1, ξ2))` |
+| Variable list | `∀ξ1, ξ2 ∈ STE (LE(ξ1, ξ2))` |
+
+Parentheses around `LE` may be omitted for atomic logical expressions.
+
+## Arithmetic
+
+Operations `a + b`, `a - b`, `a * b` form set-theoretic expressions with typification `Z`. Negative numbers are computed, never literal.
+
+`card(S)` returns the integer cardinality of `S` (always finite in practice).
+
+## Parameterised expressions
+
+### Term-function declaration
+
+```
+F1 ::= [α1∈STE1, α2∈STE2(α1)] STE(α1, α2)
+```
+
+- Inside `[]` is an ordered list of parameter declarations separated by commas.
+- A parameter is declared with `∈`: `local_var ∈ domain`.
+- A declared variable can appear in subsequent parameter domains and in the result STE.
+
+### Predicate-function declaration
+
+```
+P1 ::= [α1∈STE1, α2∈STE2(α1)] LE(α1, α2)
+```
+
+The only difference from a term-function is that the body is a logical expression.
+
+### Calling parameterised functions
+
+`F1[ξ1, S1]`, `P1[ξ1\ξ2, ξ3]` — arguments are positional and listed in square brackets after the function name. Argument typifications are checked against parameter typifications. Result is an STE (term-function) or LE (predicate-function).
+
+### Template expressions
+
+Functions that use radicals as parameter typifications are templates:
+
+```
+F2 ::= [α1∈R1×R2, α2∈R1] α2 = pr1(α1)
+```
+
+- Radical values are **inferred** from the call-site argument typifications. All inferred values for the same radical index must agree.
+- Different radical indices are independent.
+- Radicals may only appear in parameter domains — never in the result expression.
+
+## Examples
+
+- `¬α ∈ S1`
+- `D1 ∈ S1 ⇒ 2 + 2 = 5`
+- `D1 ⊆ D2 ⇔ ∀x∈D1 x∈D2`
+- `∀x∈D1 ∃y∈D2 (x, y)∈S1 & (x, x)∈S1`
+- `(4 + 5) * 3`, `card(X1) > 5`
+- `ℬ(2) = {{}, {1}, {2}, {1, 2}}`
+- `pr2((5, 4, 3, 2, 1)) = 4`
+- `red({{1, 2, 3}, {3, 4}}) = {1, 2, 3, 4}`
+- `Fi2[{2, 4}]({((1, 2), (3, 4), (5, 6))}) = {((1, 2), (3, 4))}`
+
+## Correctness model
+
+- Expression checking happens in the **global context**: known typifications and bijective portability of every referenced identifier. Unknown identifiers are errors.
+- Set-theoretic rules follow from bijective portability of the membership predicate — an element must match the typification of the set it is tested against.
+- Logical consistency cannot generally be checked automatically. The existence of an interpretation example in a conceptual model is a basis for accepting consistency.
+- All formal definitions must be **bijectively portable**: values are independent of any bijective replacement of undefined-concept interpretations.

package/docs/TYPIFICATION.md

@@ -0,0 +1,79 @@
+# Typification reference
+
+Distilled from `help-rslang-typification`, `help-rslang-expression-structure`, and `help-rslang-expression-parameter`. Agents must understand grades to interpret `AnalysisResult.type` and to construct correct expressions.
+
+## Grades
+
+A genus-structure expression `ξ` has typification (a *structure*) if `ξ ∈ H` holds, where `H` is a valid **grade**. Grades are built recursively:
+
+| Grade | Form | Notes |
+|-------|------|-------|
+| Element | `Xi`, `Ci` | grade of an undefined concept's elements |
+| Integer | `Z` | grade of integer arithmetic results |
+| Tuple of arity n | `(H1 × H2 × … × Hn)` | ordered structured grade |
+| Set | `ℬ(H)` | set of values of grade `H` |
+
+The empty set `∅` has typification `ℬ(R0)` — a set with arbitrary element structure. The radical `R0` ensures it conforms to any element grade in context.
+
+## Extended typifications
+
+Beyond set-theoretic grades, RSLang uses two additional grade-like markers:
+
+- **Logic** — typification of logical expressions (axioms, statements, predicate bodies) that evaluate to TRUE or FALSE.
+- **Parameterised** — typification of term-functions and predicate-functions:
+
+  ```
+  Hr 🠔 [H1, H2, …, Hi]
+  ```
+
+  where `Hr` is the result typification (an STE grade or `Logic`) and `H1 … Hi` are the argument typifications.
+
+## Radicals
+
+Template parameterised expressions may contain notations `R1, R2, …` (and `R0` for `∅`). Each radical corresponds to an arbitrary grade that is **inferred** from the typifications of the arguments at the point of use.
+
+- All occurrences of the same radical index must resolve to the same grade.
+- Radicals with different indices are independent.
+- Radicals may only appear in parameter domains, **not in the result expression**.
+
+## Encoded shape in `AnalysisResult.type`
+
+The contract exposes `type: Record<string, unknown> | null` because typifications are JSON-encoded by the analyzer. Useful properties exposed by `@rsconcept/domain` helpers:
+
+- `TypeID` enum: `Element`, `Integer`, `Tuple`, `Boolean`, `Logic`, `Functional` — discriminates the top-level shape.
+- `TypeClass` enum: `Element`, `Integer`, `Logic`, `Functional`, `Collection` (set / tuple), `Other`.
+- `TypePath` (sequence of indices) addresses positions inside a tuple-of-sets-of-tuples structure; use `makeTypePath` to construct.
+- `parseTypeText(...)` parses an ASCII representation `B(X1)`, `(X1×X2)`, etc., into a `Typification`.
+
+For agents inspecting types from rstool output:
+
+1. Check `analysis.success === true` and `analysis.type !== null`.
+2. Use `analysis.type` (object) only as opaque input to `@rsconcept/domain` helpers — do not pattern-match it manually.
+3. The `valueClass` companion indicates `Value`, `Property` (non-computable membership only), or `Invalid`.
+
+## Forming structures vs. derived structures
+
+Forming operations build a new grade:
+
+- `ℬ(H)` — power set
+- `H1 × H2` — Cartesian product
+- `(a, b, c)` — tuple
+- `{a, b, c}` — enumeration
+- `bool(a)` — singleton
+
+Derived structures consume a grade:
+
+- `red(S)` — union of inner sets; requires `S : ℬ(ℬ(H))`
+- `debool({a})` — extracts the single element of a singleton
+- `pr1((a1, …, an))`, `Pr1(S)` — projections (multi-indices allowed: `pr1,3`, `Pr2,4`)
+- `Fi1[D](S)` — filters by membership in `D`; multi-index variants must match parameter arity
+
+## Common typification pitfalls
+
+- Negative integer literals do not exist — use `0 - n`.
+- `debool(S)` fails if `S` is not a singleton.
+- `red(S)` fails unless `S : ℬ(ℬ(H))`.
+- Tuple projections require the argument to be a tuple of sufficient arity; `pr3((a, b))` is an error.
+- Filter parameter list arity must match the multi-index in `Fi[...]`.
+- A radical in the **result expression** of a template is a hard error (`radicalUsage`).
+- An `axiom` or `statement` must have typification `Logic`; non-logical formal definitions raise `expectedLogic`.

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@rsconcept/rstool",
+  "version": "0.1.0",
+  "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",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/IRBorisov/ConceptPortal",
+    "directory": "rsconcept/rstool"
+  },
+  "homepage": "https://portal.acconcept.ru",
+  "keywords": [
+    "rslang",
+    "rsform",
+    "rstool",
+    "agent",
+    "llm",
+    "mcp",
+    "formal-language",
+    "set-theory"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./wrapper": {
+      "types": "./dist/wrapper/client.d.ts",
+      "import": "./dist/wrapper/client.js"
+    },
+    "./skills/rstool-helper/*": "./skills/rstool-helper/*",
+    "./docs/*": "./docs/*",
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "rstool-wrapper": "./dist/wrapper/stdio-wrapper.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills",
+    "docs",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "wrapper": "tsx src/wrapper/stdio-wrapper.ts",
+    "example:client": "tsx examples/agent-client.ts",
+    "example:build-schema": "tsx examples/build-sample-rsform.ts",
+    "example:build-rsmodel": "tsx examples/build-sample-rsmodel.ts",
+    "example:build-kinship-schema": "tsx examples/build-kinship-rsform.ts",
+    "example:build-kinship-rsmodel": "tsx examples/build-kinship-rsmodel.ts",
+    "kinship:cli": "tsx examples/kinship/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@rsconcept/domain": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsup": "^8.5.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/README.md

@@ -0,0 +1,15 @@
+# Agent skills (rstool)
+
+Versioned copy of agent skills for this package.
+
+## `rstool-helper`
+
+Teaches agents RS language and the rstool session API. Files:
+
+- `rstool-helper/SKILL.md` — entry and workflow
+- `rstool-helper/REFERENCE.md` — contract, stdio, grammar pointers
+- `rstool-helper/EXAMPLES.md` — runnable patterns
+
+**Also committed for Cursor:** `.agents/skills/rstool-helper/` (same files). When you change this skill, update **both** directories in the same change set so they stay identical.
+
+Contract changes: see `rsconcept/rstool/AGENTS.md` (sync checklist).

package/skills/rstool-helper/EXAMPLES.md

@@ -0,0 +1,154 @@
+# rstool — worked examples
+
+Install first:
+
+```bash
+npm install @rsconcept/rstool
+```
+
+## In-process
+
+```ts
+import { CstType, RSToolAgent } from '@rsconcept/rstool';
+
+const tool = new RSToolAgent();
+const { sessionId } = tool.createSession();
+
+// Base set — formal must be empty
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+});
+
+// Term referencing base
+const { state, diagnostics } = tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 2, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'X1×X1' }
+});
+
+console.log(state.analysis.success, diagnostics.length);
+
+// Scratch check
+tool.analyzeExpression(sessionId, {
+  expression: '(',
+  cstType: CstType.TERM
+}); // success: false, syntax diagnostics
+
+// Set base binding and evaluate a term
+tool.setConstituentaValue(sessionId, {
+  target: 1,
+  value: { 0: 'zero', 1: 'one' }
+});
+const evalResult = tool.evaluateExpression(sessionId, {
+  expression: '1+2',
+  cstType: CstType.TERM
+});
+console.log(evalResult.success, evalResult.value); // true, 3
+```
+
+## Wrapper client
+
+```ts
+import { CstType } from '@rsconcept/rstool';
+import { RSToolWrapperClient } from '@rsconcept/rstool/wrapper';
+
+const client = new RSToolWrapperClient();
+await client.waitUntilReady();
+
+const { sessionId } = await client.call<{ sessionId: string }>('createSession');
+await client.call('addOrUpdateConstituenta', {
+  sessionId,
+  input: {
+    draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+  }
+});
+
+await client.call('addOrUpdateConstituenta', {
+  sessionId,
+  input: {
+    draft: { id: 2, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'X1×X1' }
+  }
+});
+
+const diagnostics = await client.call('listDiagnostics', { sessionId });
+console.log(diagnostics);
+
+await client.close();
+```
+
+## Manual stdio
+
+Start wrapper in one terminal:
+
+```bash
+npx rstool-wrapper
+```
+
+Paste one JSON request per line after the ready line appears:
+
+```json
+{ "id": "1", "method": "createSession", "params": {} }
+```
+
+Use the returned `sessionId` in subsequent lines:
+
+```json
+{ "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
+{ "id": "3", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 2, "alias": "D1", "cstType": "term", "definitionFormal": "X1×X1" } } } }
+{ "id": "4", "method": "listDiagnostics", "params": { "sessionId": "..." } }
+```
+
+## Export a small RSForm session
+
+```ts
+import { CstType, RSToolAgent } from '@rsconcept/rstool';
+
+const tool = new RSToolAgent();
+const { sessionId } = tool.createSession();
+
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
+});
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
+});
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'X1×X1' }
+});
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 4, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
+});
+
+const payload = tool.exportSession(sessionId);
+console.log(payload);
+```
+
+## Model and evaluation
+
+```ts
+tool.setConstituentaValue(sessionId, {
+  target: 1,
+  value: { 0: 'zero', 1: 'one' }
+});
+
+const evaluated = tool.evaluateConstituenta(sessionId, {
+  constituentId: 3
+});
+console.log(evaluated.success, evaluated.value);
+```
+
+## Common mistakes
+
+| Mistake                                            | Symptom                                          |
+| -------------------------------------------------- | ------------------------------------------------ |
+| `definitionFormal: 'Z'` on `X1` (`basic`)          | `0x8862` definitionNotAllowed                    |
+| `D1` uses `D2` before `D2` exists                  | globalNotTyped / undeclared global               |
+| `analyzeExpression` with wrong `cstType`           | Role-specific semantic errors                    |
+| Non-empty formal on `C1` (`constant`)              | Same as basic — definition not allowed           |
+| `setConstituentaValue` on inferrable `D1` (`term`) | Error: inferrable and cannot be set directly     |
+| Evaluating before base binding set                 | May fail or return empty depending on expression |
+
+## Fixing a syntax error
+
+1. `analyzeExpression` with the broken fragment and correct `cstType`.
+2. Read first diagnostic `{ from, to, code }`.
+3. Edit substring of `definitionFormal` at those offsets.
+4. `addOrUpdateConstituenta` again with the same `id` / `alias`.

package/skills/rstool-helper/REFERENCE.md

@@ -0,0 +1,169 @@
+# RS language and rstool — reference
+
+## rstool contract
+
+- Package: `@rsconcept/rstool`
+- Contract version: `1.2.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 }`              |
+| `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[] }`            |
+
+### `ConstituentaDraft`
+
+```ts
+{
+  id: number;           // stable id within session
+  alias: string;        // e.g. "D1", "X1"
+  cstType: CstType;     // see SKILL.md table
+  definitionFormal: string;
+  term?: string;
+  definitionText?: string;
+  convention?: string;
+}
+```
+
+Omitted text fields default to `''` in stored state.
+
+### Model and evaluation types
+
+```ts
+type RSToolValue = number | RSToolValue[]; // runtime value (sets, tuples, logic 0/1)
+type BasicBinding = Record<number, string>; // base-set element labels
+
+interface SessionModelState {
+  items: { id: number; type: string; value: RSToolValue | BasicBinding }[];
+}
+
+interface EvaluationResult {
+  success: boolean;
+  value: RSToolValue | BasicBinding | null;
+  status: EvalStatus; // 1=NO_EVAL … 7=HAS_DATA
+  iterations: number;
+  cacheHits: number;
+  diagnostics: { code: number; from: number; to: number; params?: string[] }[];
+}
+```
+
+Base/constant bindings use `type: "basic"` and `value: { "0": "label", … }`. Structured values use normalized typification as `type` and nested arrays for sets/tuples.
+
+### Stdio protocol
+
+Process: `npx rstool-wrapper`
+
+1. **Ready** (no request): `{"id":null,"ok":true,"result":{"ready":true,"wrapper":"rstool-stdio","contractVersion":"1.2.0"}}`
+2. **Request**: `{"id":"<unique>","method":"<name>","params":{...}}`
+3. **Response**: `{"id":"<same>","ok":true,"result":...}` or `{"id":"...","ok":false,"error":{"code":"...","message":"..."}}`
+
+Extra methods: `ping`, `methods`.
+
+Example chain:
+
+```json
+{"id":"1","method":"createSession","params":{}}
+{"id":"2","method":"addOrUpdateConstituenta","params":{"sessionId":"…","input":{"draft":{"id":3,"alias":"D1","cstType":"term","definitionFormal":"X1×X1"}}}}
+{"id":"3","method":"analyzeExpression","params":{"sessionId":"…","input":{"expression":"1+2","cstType":"term"}}}
+{"id":"4","method":"listDiagnostics","params":{"sessionId":"…"}}
+{"id":"5","method":"commitStep","params":{"sessionId":"…","message":"checkpoint"}}
+{"id":"6","method":"exportSession","params":{"sessionId":"…"}}
+{"id":"7","method":"setConstituentaValue","params":{"sessionId":"…","input":{"target":1,"value":{"0":"a","1":"b"}}}}
+{"id":"8","method":"evaluateExpression","params":{"sessionId":"…","input":{"expression":"1+2","cstType":"term"}}}
+{"id":"9","method":"evaluateConstituenta","params":{"sessionId":"…","input":{"constituentId":3}}}
+```
+
+`RSToolWrapperClient`: spawns `rstool-wrapper` by default and implements `waitUntilReady()`, `call(method, params)`, `close()`.
+
+### Analysis result
+
+```ts
+interface AnalysisResult {
+  success: boolean;
+  type: Record<string, unknown> | null; // typification tree
+  valueClass: 'value' | 'property' | null;
+  diagnostics: { code: number; from: number; to: number; params?: string[] }[];
+}
+```
+
+## RS language — conceptual model
+
+- **Typification**: computed structure type from a formal definition; grades include elements (`Xi`, `Ci`), `Z`, tuples `(H1×…×Hn)`, sets `ℬ(H)`, logic `Logic`, parameterized `Hr 🠔 [H1,…,Hi]`.
+- **Term graph**: directed dependencies between constituenta via alias references in definitions.
+
+Intro (help): language is FOL-based; set vs logic expression split; parameterized templates for term/predicate functions; structural expressions reshape stages.
+
+## Grammar tokens (selected)
+
+From `rslang.grammar`:
+
+| Category               | Tokens / forms                                             |
+| ---------------------- | ---------------------------------------------------------- |
+| Globals                | `X`, `C`, `S`, `D`, `A`, `T`, `N` + 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`, `∅`                                           |
+
+Full grammar pointers and precedence notes: `docs/GRAMMAR-REF.md`.
+
+## Help topic map (companion docs)
+
+Standalone agents should consult the bundled distilled docs (`docs/*.md` inside `@rsconcept/rstool`):
+
+| 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*     |
+| 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`                      |
+
+## Error codes (rstool-relevant)
+
+rstool re-exports `RSErrorCode.definitionNotAllowed` (`0x8862`) for base/constant violations.
+
+Categories and per-code fix guidance: `docs/DIAGNOSTICS.md`.
+
+Categories:
+
+- `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)` returns a JSON string with `{ contractVersion, state, diagnostics }`.
+
+- `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.