@rsconcept/rstool 0.1.0 → 0.2.0

package/docs/PORTAL-API.md

@@ -6,19 +6,16 @@ When an agent needs to **inspect existing** RSForms, OSS, or RSModels persisted
 
 - **UI:** `https://portal.acconcept.ru/`
 - **REST API:** `https://api.portal.acconcept.ru/`
-- **Local dev:** path prefix `/api/...`, base URL from `VITE_PORTAL_BACKEND`.
 
 ## Path rewrite rules
 
-Drop UI hash query params (`?tab=`, etc.). Keep numeric ids exactly as the UI shows them.
-
-| Portal UI path | REST target |
-|----------------|-------------|
-| `/rsforms/:id` | `GET /api/rsforms/:id` (metadata: owner, titles) |
-| `/rsforms/:id` (full payload) | `GET /api/rsforms/:id/details` |
-| `/rsforms/:id` (a saved version) | `GET /api/library/:id/versions/:version` |
-| `/oss/:id` | `GET /api/oss/:id` (and the sibling OSS viewset routes) |
-| `/models/:id` | `GET /api/models/:id` (RSModel router) |
+| Portal UI path                   | REST target                                             |
+| -------------------------------- | ------------------------------------------------------- |
+| `/rsforms/:id`                   | `GET /api/rsforms/:id` (metadata: owner, titles)        |
+| `/rsforms/:id` (full payload)    | `GET /api/rsforms/:id/details`                          |
+| `/rsforms/:id` (a saved version) | `GET /api/library/:id/versions/:version`                |
+| `/oss/:id`                       | `GET /api/oss/:id` (and the sibling OSS viewset routes) |
+| `/models/:id`                    | `GET /api/models/:id` (RSModel router)                  |
 
 ## OpenAPI
 

package/docs/SYNTAX.md

@@ -1,6 +1,6 @@
 # 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`.
+Use this when constructing or repairing RSLang expressions. For full grammar tokens see `GRAMMAR-REF.md`. For typification rules see `TYPIFICATION.md`.
 
 ## Identifier rules
 
@@ -17,22 +17,22 @@ Distilled from the Portal help topics under `help-rslang-*`. Use this when const
 
 ## 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` |
+| 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)`).
 
@@ -40,15 +40,15 @@ Indices `1` may be any natural number or comma-separated multi-index (`pr1,3((a1
 
 ### Set-theoretic predicates
 
-| Predicate | Syntax |
-|-----------|--------|
-| Membership | `ξ ∈ S` |
-| Non-membership | `ξ ∉ S` |
-| Set equality | `S1 = S2` |
-| Set inequality | `S1 ≠ S2` |
-| Inclusion | `S1 ⊆ S2` |
+| 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` |
+| Non-inclusion    | `S1 ⊄ S2` |
 
 ### Arithmetic predicates (typification `Logic`)
 
@@ -56,9 +56,9 @@ Indices `1` may be any natural number or comma-separated multi-index (`pr1,3((a1
 
 ### Connectives
 
-| Connective | Syntax |
-|------------|--------|
-| Negation | `¬A` |
+| Connective  | Syntax  |
+| ----------- | ------- |
+| Negation    | `¬A`    |
 | Conjunction | `A & B` |
 | Disjunction | `A ∨ B` |
 | Implication | `A ⇒ B` |
@@ -68,10 +68,10 @@ The constants `TRUE` and `FALSE` are **not** used inside schema explications.
 
 ## Quantifiers
 
-| Form | Syntax |
-|------|--------|
-| Universal | `∀ξ∈STE (LE(ξ))` |
-| Existential | `∃ξ∈STE (LE(ξ))` |
+| Form          | Syntax                       |
+| ------------- | ---------------------------- |
+| Universal     | `∀ξ∈STE (LE(ξ))`             |
+| Existential   | `∃ξ∈STE (LE(ξ))`             |
 | Tuple binding | `∀(ξ1, ξ2)∈STE (LE(ξ1, ξ2))` |
 | Variable list | `∀ξ1, ξ2 ∈ STE (LE(ξ1, ξ2))` |
 

package/docs/TYPIFICATION.md

@@ -4,14 +4,14 @@ Distilled from `help-rslang-typification`, `help-rslang-expression-structure`, a
 
 ## Grades
 
-A genus-structure expression `ξ` has typification (a *structure*) if `ξ ∈ H` holds, where `H` is a valid **grade**. Grades are built recursively:
+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` |
+| 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.
 
@@ -41,7 +41,6 @@ Template parameterised expressions may contain notations `R1, R2, …` (and `R0`
 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`.
 
@@ -51,6 +50,13 @@ For agents inspecting types from rstool output:
 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`.
 
+## Typification on `S#` vs definition on `D#`
+
+- On a **`structure`** (`S#`), `definitionFormal` is read as **typification**. Subexpressions such as `X1×X1` describe **element shape** (here: one pair of base elements).
+- On a **`term`** (`D#`), the same token sequence is a **definition** evaluated in the model. `X1×X1` alone is the Cartesian product — all ordered pairs from `X1` — not the typification of a relation stored in `S#`.
+
+Prefer `S#` with `ℬ(X1×X1)` plus `convention` for relations; derive `D#` with `Pr*`, `Fi*`, filters, etc.
+
 ## Forming structures vs. derived structures
 
 Forming operations build a new grade:
@@ -72,7 +78,6 @@ Derived structures consume a grade:
 
 - 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`).

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@rsconcept/rstool",
-  "version": "0.1.0",
+  "version": "0.2.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",
+    "url": "git+https://github.com/IRBorisov/ConceptPortal.git",
     "directory": "rsconcept/rstool"
   },
   "homepage": "https://portal.acconcept.ru",
@@ -33,11 +33,12 @@
       "import": "./dist/wrapper/client.js"
     },
     "./skills/rstool-helper/*": "./skills/rstool-helper/*",
+    "./skills/INSTALL.md": "./skills/INSTALL.md",
     "./docs/*": "./docs/*",
     "./package.json": "./package.json"
   },
   "bin": {
-    "rstool-wrapper": "./dist/wrapper/stdio-wrapper.js"
+    "rstool-wrapper": "dist/wrapper/stdio-wrapper.js"
   },
   "files": [
     "dist",
@@ -48,7 +49,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsdown",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run",
     "wrapper": "tsx src/wrapper/stdio-wrapper.ts",
@@ -64,10 +65,10 @@
     "@rsconcept/domain": "^1.0.0"
   },
   "devDependencies": {
-    "@types/node": "^24.0.0",
-    "tsup": "^8.5.0",
+    "@types/node": "^25.9.1",
+    "tsdown": "^0.22.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.3",
     "vitest": "^4.1.5"
   },
   "publishConfig": {

package/skills/INSTALL.md

@@ -0,0 +1,35 @@
+# Install `rstool-helper` (agent procedure)
+
+Use when the user has run `npm install @rsconcept/rstool` and asks to **install** or **enable** the rstool agent skill. The user should not copy files manually.
+
+## Steps
+
+1. Confirm the package exists: `node_modules/@rsconcept/rstool/package.json`.
+2. Determine the host’s **project skills directory** (where that host loads `SKILL.md` files). Common layouts:
+   - `.agents/skills/<skill-name>/SKILL.md`
+   - `.cursor/skills/<skill-name>/SKILL.md`
+   - Other paths — use the host’s documentation if unsure.
+3. Create `<skills-dir>/rstool-helper/` if needed.
+4. Copy **one file** — the package entry skill:
+   - **From:** `node_modules/@rsconcept/rstool/skills/rstool-helper/SKILL.md`
+   - **To:** `<skills-dir>/rstool-helper/SKILL.md`
+5. Do **not** copy `GUIDE.md`, `REFERENCE.md`, `EXAMPLES.md`, or `docs/` into the project. The entry skill points at those files under `node_modules/@rsconcept/rstool/`.
+6. Confirm the destination `SKILL.md` exists and tell the user the skill is ready.
+
+### Example (`.agents/skills` layout)
+
+Bash:
+
+```bash
+mkdir -p .agents/skills/rstool-helper
+cp node_modules/@rsconcept/rstool/skills/rstool-helper/SKILL.md .agents/skills/rstool-helper/SKILL.md
+```
+
+PowerShell:
+
+```powershell
+New-Item -ItemType Directory -Force -Path .agents/skills/rstool-helper | Out-Null
+Copy-Item -Force node_modules/@rsconcept/rstool/skills/rstool-helper/SKILL.md .agents/skills/rstool-helper/SKILL.md
+```
+
+Use the equivalent path for your agent host if it does not use `.agents/skills`.

package/skills/README.md

@@ -1,15 +1,23 @@
-# Agent skills (rstool)
+# Agent skills (`@rsconcept/rstool`)
 
-Versioned copy of agent skills for this package.
+Each skill lives in its own subdirectory: `skills/<skill-name>/SKILL.md` (plus reference files). Shared install steps: `INSTALL.md`.
 
-## `rstool-helper`
+## Layout
 
-Teaches agents RS language and the rstool session API. Files:
+| Path | Role |
+| :--- | :--- |
+| `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 |
+| `../docs/*.md` | Language reference (DOMAIN, SYNTAX, DIAGNOSTICS, …) |
 
-- `rstool-helper/SKILL.md` — entry and workflow
-- `rstool-helper/REFERENCE.md` — contract, stdio, grammar pointers
-- `rstool-helper/EXAMPLES.md` — runnable patterns
+## npm workflow
 
-**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.
+1. `npm install @rsconcept/rstool`
+2. User asks the agent to install the skill (no manual copy).
+3. Agent follows `node_modules/@rsconcept/rstool/skills/INSTALL.md`.
+4. Agent reads `GUIDE.md` and `docs/` from `node_modules/@rsconcept/rstool/` when working.
 
-Contract changes: see `rsconcept/rstool/AGENTS.md` (sync checklist).
+Contract changes: see `AGENTS.md` in this package (sync checklist).

package/skills/rstool-helper/EXAMPLES.md

@@ -6,6 +6,10 @@ Install first:
 npm install @rsconcept/rstool
 ```
 
+## Kinship-lite: structure vs term
+
+`S1` carries **typification** `ℬ(X1×X1)` (pairs over people); `D1` is a **definition** `Pr1(S1)` (parents). Do not put `X1×X1` on a `term` — that is the full Cartesian product.
+
 ## In-process
 
 ```ts
@@ -19,9 +23,20 @@ tool.addOrUpdateConstituenta(sessionId, {
   draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
 });
 
-// Term referencing base
+// Structure: typification of parent–child pairs (undefined; convention in real schemas)
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: {
+    id: 2,
+    alias: 'S1',
+    cstType: CstType.STRUCTURED,
+    definitionFormal: 'ℬ(X1×X1)',
+    convention: 'Elements are (parent, child) pairs with parent, child ∈ X1.'
+  }
+});
+
+// Term: derived definition — first projection of S1
 const { state, diagnostics } = tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 2, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'X1×X1' }
+  draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
 });
 
 console.log(state.analysis.success, diagnostics.length);
@@ -32,7 +47,7 @@ tool.analyzeExpression(sessionId, {
   cstType: CstType.TERM
 }); // success: false, syntax diagnostics
 
-// Set base binding and evaluate a term
+// Set base binding and evaluate a scratch arithmetic term
 tool.setConstituentaValue(sessionId, {
   target: 1,
   value: { 0: 'zero', 1: 'one' }
@@ -60,11 +75,21 @@ await client.call('addOrUpdateConstituenta', {
     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' }
+    draft: {
+      id: 2,
+      alias: 'S1',
+      cstType: CstType.STRUCTURED,
+      definitionFormal: 'ℬ(X1×X1)'
+    }
+  }
+});
+await client.call('addOrUpdateConstituenta', {
+  sessionId,
+  input: {
+    draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
   }
 });
 
@@ -92,8 +117,9 @@ 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": "..." } }
+{ "id": "3", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 2, "alias": "S1", "cstType": "structure", "definitionFormal": "ℬ(X1×X1)" } } } }
+{ "id": "4", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 3, "alias": "D1", "cstType": "term", "definitionFormal": "Pr1(S1)" } } } }
+{ "id": "5", "method": "listDiagnostics", "params": { "sessionId": "..." } }
 ```
 
 ## Export a small RSForm session
@@ -111,10 +137,19 @@ 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' }
+  draft: {
+    id: 3,
+    alias: 'S1',
+    cstType: CstType.STRUCTURED,
+    definitionFormal: 'ℬ(X1×X1)',
+    convention: 'Pairs (parent, child) over X1.'
+  }
+});
+tool.addOrUpdateConstituenta(sessionId, {
+  draft: { id: 4, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
 });
 tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 4, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
+  draft: { id: 5, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
 });
 
 const payload = tool.exportSession(sessionId);
@@ -123,6 +158,10 @@ console.log(payload);
 
 ## Model and evaluation
 
+Full kinship modeling (`S1` values as tuples, `Pr1(S1)`, …): `examples/build-kinship-rsmodel.ts`.
+
+Minimal evaluation after bindings:
+
 ```ts
 tool.setConstituentaValue(sessionId, {
   target: 1,
@@ -130,7 +169,7 @@ tool.setConstituentaValue(sessionId, {
 });
 
 const evaluated = tool.evaluateConstituenta(sessionId, {
-  constituentId: 3
+  constituentId: 4 // D1 = Pr1(S1); needs S1 interpreted — see kinship example
 });
 console.log(evaluated.success, evaluated.value);
 ```
@@ -143,6 +182,8 @@ console.log(evaluated.success, evaluated.value);
 | `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           |
+| `term` with `X1×X1` when modeling a **relation**   | Full Cartesian product instead of typed pairs in `S#` |
+| `structure` with `Pr1(S1)` instead of a grade      | Wrong role — projections belong on `term` / `F#`   |
 | `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 |
 

package/skills/rstool-helper/GUIDE.md

@@ -0,0 +1,133 @@
+# RS Language & rstool — Compact Guide for Agents
+
+**RS language** is a formal scheme notation for concepts, relations, operations—extends FOL, core: membership `x∈y`; typification via set-theoretic/logical expressions.
+
+**rstool** is the agent API for sessions, upserts, analysis, diagnostics, modeling/evaluation, (de)serialization.
+
+- Library: `@rsconcept/rstool` (npm)
+- Analyzer: `@rsconcept/domain` (dependency of rstool)
+- Language reference: `docs/*.md` next to this package (see table below)
+
+## Docs / hints (canonical paths)
+
+Paths below are relative to **this file** (`skills/rstool-helper/GUIDE.md`).
+
+| Info | Location |
+| :--- | :--- |
+| rstool API, methods, error codes | [REFERENCE.md](REFERENCE.md) |
+| Worked examples, common mistakes | [EXAMPLES.md](EXAMPLES.md) |
+| Domain vocabulary (English) | [../../docs/DOMAIN.md](../../docs/DOMAIN.md) |
+| Constituenta fields, validation, ordering | [../../docs/CONSTITUENTA.md](../../docs/CONSTITUENTA.md) |
+| RSLang syntax (operators, quantifiers) | [../../docs/SYNTAX.md](../../docs/SYNTAX.md) |
+| Typification grades, radicals | [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md) |
+| Diagnostic code → fix table | [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md) |
+| Portal REST API (live data) | [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md) |
+| Lezer grammar pointers | [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md) |
+| Package README | [../../README.md](../../README.md) |
+
+When working from **npm**, the same tree lives under `node_modules/@rsconcept/rstool/` (use the Read tool on those paths from the project root).
+
+## Protocol Summary
+
+1. **Start session**: `createSession`
+2. **Add bases/constants**: type `basic` (`X*`), `constant` (`C*`) — `definitionFormal: ''`
+3. **Add derived**: terms, axioms, etc.—only after dependencies present
+4. **Analyze scratch**: `analyzeExpression`
+5. **Process diagnostics**: check `analysis.diagnostics`/`listDiagnostics`; fix by range
+6. **Checkpoint**: `commitStep` (message optional)
+7. **Model values**: `setConstituentaValue` / `setConstituentaValues` for base bindings (`{0:"a",1:"b"}`) or structured values; `getModelState`
+8. **Evaluate**: `evaluateExpression` (scratch) or `evaluateConstituenta` / `recalculateModel` (stored definitions)
+9. **Export/import**: persist with `exportSession`/`importSession` (includes `state.model`)
+
+**Clients**:
+
+- Node: use `RSToolWrapperClient`
+- Stdio process: `npx rstool-wrapper` — JSON per line
+
+## API/REST
+
+For full reference see [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md). Short form:
+
+- **Portal UI**: `https://portal.acconcept.ru`
+- **API**: `https://api.portal.acconcept.ru`
+- Endpoints: `GET /api/rsforms/{id}`, `GET /api/rsforms/{id}/details`, `GET /api/library/{id}/versions/{v}`, `GET /api/oss/{id}`, `GET /api/models/{id}`, OpenAPI at `GET /schema`.
+- Don't scrape SPA or use UI query params (`tab=`, etc.).
+- rstool itself never calls the REST API; bring data in via `addOrUpdateConstituenta` after fetching.
+
+## Constituent Types (`cstType`)
+
+| cstType | Example | Formal | Notes |
+| :-------- | :------ | :-------- | :-------------------------------------------------------- |
+| basic | X1 | **empty** | Required |
+| constant | C1 | **empty** | Required |
+| nominal | S1 | allowed | Naming |
+| structure | S1 | allowed | Typification grade; base concept + `convention` |
+| term | D1 | allowed | Formal **definition**; derived concept, computed in model |
+| axiom | A1 | allowed | Logical; computed in model; required to be TRUE |
+| statement | T1 | allowed | Logical; computed in model |
+| function | F1 | allowed | Parameterized; derived concept |
+| predicate | P1 | allowed | Parameterized; derived concept |
+
+- Non-empty formal for `basic`/`constant` ⇒ error `0x8862` (`definitionNotAllowed`)
+- Empty `basic`/`constant` always typified
+- **Interpretable** (can set value): `basic`, `constant`, `structure`
+- **Inferrable** (computed, do not set directly): `term`, `axiom`, `statement`
+
+## Structure (`S#`) vs term (`D#`)
+
+The same field `definitionFormal` has **different roles** depending on `cstType`:
+
+| | `structure` (`S#`) | `term` (`D#`) |
+| -------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| Role of `definitionFormal` | **Typification** — declares grade `H` (element structure) | **Definition** — declares how the concept is built from suppliers |
+| Concept class | **Undefined** — meaning from `convention` (+ axioms on `S#`) | **Derived** — meaning from the expression; no convention required |
+| Model interpretation | Values are **assigned** (or constrained by axioms); domain fills `S#` per convention | Value is **computed** via `evaluateConstituenta` / `recalculateModel` |
+
+**Same syntax, different semantics:** in `ℬ(X1×X1)` the fragment `X1×X1` is a **grade** (one ordered pair of base elements). On a **term** with body `X1×X1` alone, `×` builds the **full Cartesian product** — the set of all pairs from `X1`, not a relation typification.
+
+**Agent rule:** for a relation over `X1` (e.g. parent–child), upsert `S1` with `definitionFormal: 'ℬ(X1×X1)'` and a `convention`, then derive terms with projections/filters (`Pr1(S1)`, `Fi2[{ξ}](S1)`, …). Do not use bare `X1×X1` on a `term` when you meant the structure’s typification.
+
+See [EXAMPLES.md](EXAMPLES.md) (kinship-lite) and `../../examples/build-kinship-rsform.ts`.
+
+## Syntax
+
+- **Globals**: `X1`, `C1`, `D1`, `F1`, `P1`, `A1`, `R1`
+- **Locals**: `x`, `ξ`, `μ2`
+- **Literals**: `42`, `Z`, `∅`
+- Full operator + precedence table: [../../docs/SYNTAX.md](../../docs/SYNTAX.md)
+- Grammar pointers: [../../docs/GRAMMAR-REF.md](../../docs/GRAMMAR-REF.md)
+
+## Expression Types
+
+- **Set-theoretic**: `∪`, `∩`, `\`, `∆`, `×`, `∈`, `⊆`, `ℬ(...)`, tuples
+- **Logical**: `¬`, `&`, `∨`, `⇒`, `⇔`, `∀`, `∃`, comparisons `=`, `≠`, `<`
+- **Parameterized**: `[arg1∈H1, arg2∈H2] body`
+- Detailed semantics in [../../docs/SYNTAX.md](../../docs/SYNTAX.md); typification grades and radicals in [../../docs/TYPIFICATION.md](../../docs/TYPIFICATION.md).
+
+Always set `cstType` in upserts/analysis to true role.
+
+## Diagnostics Loop
+
+1. Check `analysis.success`
+2. If not, see `analysis.diagnostics` / `listDiagnostics`
+3. Map `code` → cause → fix via [../../docs/DIAGNOSTICS.md](../../docs/DIAGNOSTICS.md)
+4. Use `from`, `to` to patch `definitionFormal`; re-send
+
+Don't infer types—always read tool output.
+
+## Declaration Order
+
+1. All `basic`, `constant`
+2. Core/critical first
+3. Topological: dependencies before dependents (e.g. `D1` before `D2` if `D2` refers to `D1`)
+4. Derived right after their sources
+
+## Checklist
+
+- [ ] `sessionId` obtained & tracked
+- [ ] Bases/constants are empty formal
+- [ ] All dependencies exist before upsert
+- [ ] Matching `cstType`
+- [ ] Diagnostics handled before commit/export
+- [ ] Base bindings set before evaluating expressions that reference base elements
+- [ ] For other details, open [REFERENCE.md](REFERENCE.md) or linked `docs/*.md`

package/skills/rstool-helper/REFERENCE.md

@@ -33,7 +33,7 @@
 {
   id: number;           // stable id within session
   alias: string;        // e.g. "D1", "X1"
-  cstType: CstType;     // see SKILL.md table
+  cstType: CstType;     // see GUIDE.md table
   definitionFormal: string;
   term?: string;
   definitionText?: string;
@@ -79,7 +79,8 @@ 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":"2","method":"addOrUpdateConstituenta","params":{"sessionId":"…","input":{"draft":{"id":2,"alias":"S1","cstType":"structure","definitionFormal":"ℬ(X1×X1)"}}}}
+{"id":"2b","method":"addOrUpdateConstituenta","params":{"sessionId":"…","input":{"draft":{"id":3,"alias":"D1","cstType":"term","definitionFormal":"Pr1(S1)"}}}}
 {"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"}}
@@ -104,8 +105,9 @@ interface AnalysisResult {
 
 ## 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]`.
+- **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.
 - **Term graph**: directed dependencies between constituenta via alias references in definitions.
+- **`S#` vs `D#`**: same `×` token — in `ℬ(X1×X1)` on `S#` it forms a **grade** (pair type); in `X1×X1` on `D#` it is the **Cartesian product** (all pairs). Relations: `S#` + `convention`, then derived `D#` (`Pr1(S1)`, …).
 
 Intro (help): language is FOL-based; set vs logic expression split; parameterized templates for term/predicate functions; structural expressions reshape stages.