@rsconcept/rstool 0.2.1 → 0.4.0

package/skills/rstool-helper/EXAMPLES.md

@@ -1,16 +1,10 @@
-# rstool — worked examples
+# rstool Examples
 
-Install first:
+Short examples for agents. For full scripts, see `../../examples/`.
 
-```bash
-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.
+## Minimal Session
 
-## In-process
+`S1` carries typification `ℬ(X1×X1)` for relation pairs. `D1` computes `Pr1(S1)`. Do not put bare `X1×X1` on a `term` when you mean a relation structure.
 
 ```ts
 import { CstType, RSToolAgent } from '@rsconcept/rstool';
@@ -18,12 +12,10 @@ 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: '' }
 });
 
-// Structure: typification of parent–child pairs (undefined; convention in real schemas)
 tool.addOrUpdateConstituenta(sessionId, {
   draft: {
     id: 2,
@@ -34,32 +26,33 @@ tool.addOrUpdateConstituenta(sessionId, {
   }
 });
 
-// Term: derived definition — first projection of S1
 const { state, diagnostics } = tool.addOrUpdateConstituenta(sessionId, {
   draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
 });
 
 console.log(state.analysis.success, diagnostics.length);
+```
 
-// Scratch check
-tool.analyzeExpression(sessionId, {
-  expression: '(',
-  cstType: CstType.TERM
-}); // success: false, syntax diagnostics
+## Analyze Before Upsert
 
-// Set base binding and evaluate a scratch arithmetic term
-tool.setConstituentaValue(sessionId, {
-  target: 1,
-  value: { 0: 'zero', 1: 'one' }
-});
-const evalResult = tool.evaluateExpression(sessionId, {
-  expression: '1+2',
+Use scratch analysis when syntax or `cstType` is uncertain.
+
+```ts
+const analysis = tool.analyzeExpression(sessionId, {
+  expression: 'Pr1(S1)',
   cstType: CstType.TERM
 });
-console.log(evalResult.success, evalResult.value); // true, 3
+
+if (!analysis.success) {
+  console.log(analysis.diagnostics.map(({ code, from, to }) => ({ code, from, to })));
+}
 ```
 
-## Wrapper client
+Fix the reported `from` / `to` range, then re-run analysis. Do not retry unchanged input.
+
+## Wrapper Client
+
+Use the wrapper when the agent talks to a separate `rstool-wrapper` process.
 
 ```ts
 import { CstType } from '@rsconcept/rstool';
@@ -69,29 +62,13 @@ 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: 'S1',
-      cstType: CstType.STRUCTURED,
-      definitionFormal: 'ℬ(X1×X1)'
-    }
-  }
-});
-await client.call('addOrUpdateConstituenta', {
-  sessionId,
-  input: {
-    draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
-  }
-});
 
 const diagnostics = await client.call('listDiagnostics', { sessionId });
 console.log(diagnostics);
@@ -99,34 +76,57 @@ console.log(diagnostics);
 await client.close();
 ```
 
-## Manual stdio
+Manual stdio is one JSON request per line:
 
-Start wrapper in one terminal:
+```jsonl
+{ "id": "1", "method": "createSession", "params": {} }
+{ "id": "2", "method": "addOrUpdateConstituenta", "params": { "sessionId": "...", "input": { "draft": { "id": 1, "alias": "X1", "cstType": "basic", "definitionFormal": "" } } } }
+```
+
+## Export / Import
 
-```bash
-npx rstool-wrapper
+```ts
+const payload = tool.exportSession(sessionId);
+const restored = tool.importSession(payload);
 ```
 
-Paste one JSON request per line after the ready line appears:
+Export includes session state and model values.
 
-```json
-{ "id": "1", "method": "createSession", "params": {} }
+To create files the user can upload to an existing Portal object:
+
+```ts
+const schemaJson = tool.exportPortalSchema(sessionId);
+const modelJson = tool.exportPortalModel(sessionId);
 ```
 
-Use the returned `sessionId` in subsequent lines:
+Use `schemaJson` on a schema page and `modelJson` on a model page via **Load from JSON**.
 
-```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": "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": "..." } }
+## Evaluation
+
+```ts
+tool.setConstituentaValue(sessionId, {
+  target: 1,
+  value: { 0: 'zero', 1: 'one' }
+});
+
+const scratch = tool.evaluateExpression(sessionId, {
+  expression: '1+2',
+  cstType: CstType.TERM
+});
+
+console.log(scratch.success, scratch.value); // true, 3
 ```
 
-## Export a small RSForm session
+For stored definitions, set values for `basic`, `constant`, and `structure`, then call `evaluateConstituenta` or `recalculateModel`.
+
+## Semantic Smoke Test
+
+When syntax is valid but meaning is uncertain, build a tiny model and assert the value.
 
 ```ts
-import { CstType, RSToolAgent } from '@rsconcept/rstool';
+import { CstType, EvalStatus, RSToolAgent } from '@rsconcept/rstool';
 
+const TUPLE_ID = -111;
 const tool = new RSToolAgent();
 const { sessionId } = tool.createSession();
 
@@ -134,62 +134,48 @@ tool.addOrUpdateConstituenta(sessionId, {
   draft: { id: 1, alias: 'X1', cstType: CstType.BASE, definitionFormal: '' }
 });
 tool.addOrUpdateConstituenta(sessionId, {
-  draft: { id: 2, alias: 'C1', cstType: CstType.CONSTANT, definitionFormal: '' }
+  draft: { id: 2, alias: 'S1', cstType: CstType.STRUCTURED, definitionFormal: 'ℬ(X1×X1)' }
 });
 tool.addOrUpdateConstituenta(sessionId, {
-  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: 5, alias: 'A1', cstType: CstType.AXIOM, definitionFormal: '1=1' }
+  draft: { id: 3, alias: 'D1', cstType: CstType.TERM, definitionFormal: 'Pr1(S1)' }
 });
 
-const payload = tool.exportSession(sessionId);
-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,
-  value: { 0: 'zero', 1: 'one' }
+tool.setConstituentaValues(sessionId, {
+  items: [
+    { target: 1, value: { 0: 'ann', 1: 'bob', 2: 'cat' } },
+    {
+      target: 2,
+      value: [
+        [TUPLE_ID, 0, 1],
+        [TUPLE_ID, 0, 2]
+      ]
+    }
+  ]
 });
 
-const evaluated = tool.evaluateConstituenta(sessionId, {
-  constituentId: 4 // D1 = Pr1(S1); needs S1 interpreted — see kinship example
-});
-console.log(evaluated.success, evaluated.value);
+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)}`);
+}
 ```
 
+Use this pattern for tests that protect important definitions. Full kinship model: `../../examples/build-kinship-rsmodel.ts`. More notes: `../../docs/MODEL-TESTING.md`.
+
 ## 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           |
-| `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 |
+- `definitionFormal: 'Z'` on `basic` / `constant` → `definitionNotAllowed`.
+- `D1` uses `D2` before `D2` exists → global not typed / undeclared.
+- 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`.
+- `setConstituentaValue` on `term`, `axiom`, or `statement` → cannot set computed constituents directly.
+- Evaluation before base bindings → missing value, empty result, or evaluation failure.
 
-## Fixing a syntax error
+## Fix Syntax
 
 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`.
+2. Read `{ code, from, to, params }`.
+3. Edit the substring of `definitionFormal` at those offsets.
+4. Re-run analysis.
+5. Upsert with the same `id` / `alias`.

package/skills/rstool-helper/GUIDE.md

@@ -1,141 +1,94 @@
-# RS Language & rstool — Compact Guide for Agents
+# RS Language & rstool
 
-**RS language** is a formal scheme notation for concepts, relations, operations—extends FOL, core: membership `x∈y`; typification via set-theoretic/logical expressions.
+Compact entry guide for agents. Keep details in linked docs.
 
-**rstool** is the agent API for sessions, upserts, analysis, diagnostics, modeling/evaluation, (de)serialization.
+**RSLang** is a formal notation for conceptual schemas: concepts, relations, operations, assertions. Core ideas: membership `x∈y`, set-theoretic expressions, logical expressions, typification.
 
-- Library: `@rsconcept/rstool` (npm)
-- Analyzer: `@rsconcept/domain` (dependency of rstool)
-- Language reference: `docs/*.md` next to this package (see table below)
+**rstool** is the agent API for sessions, upserts, analysis, diagnostics, model values, evaluation, export/import.
 
-## Docs / hints (canonical paths)
+- Library: `@rsconcept/rstool`.
+- Analyzer: `@rsconcept/domain`.
+- Stdio wrapper: `npx rstool-wrapper`, JSON per line.
+- Node client: `RSToolWrapperClient`.
 
-Paths below are relative to **this file** (`skills/rstool-helper/GUIDE.md`).
+## What to Read
 
-| 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) |
-| Designing/reviewing conceptual schemas (agent recommendations) | [../../docs/CONCEPTUAL-SCHEMA.md](../../docs/CONCEPTUAL-SCHEMA.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) |
+Paths are relative to this file.
 
-When working from **npm**, the same tree lives under `node_modules/@rsconcept/rstool/` (use the Read tool on those paths from the project root).
+- 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).
 
-## Protocol Summary
+## Workflow
 
-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`)
+1. `createSession`.
+2. Add `basic` (`X#`) and `constant` (`C#`) with `definitionFormal: ''`.
+3. Add dependencies before dependents.
+4. Use `analyzeExpression` before upsert when unsure.
+5. When unsure about semantics, build a tiny conceptual model and evaluate test data.
+6. Fix diagnostics by `from` / `to` range in `definitionFormal`.
+7. `commitStep` when the state is coherent.
+8. Set base/model values with `setConstituentaValue(s)`.
+9. Evaluate with `evaluateExpression`, `evaluateConstituenta`, or `recalculateModel`.
+10. Persist with `exportSession` / `importSession`.
+11. For user-uploadable Portal files, use `exportPortalSchema` for schema JSON or `exportPortalModel` for model JSON.
 
-**Clients**:
+## Portal REST
 
-- Node: use `RSToolWrapperClient`
-- Stdio process: `npx rstool-wrapper` — JSON per line
+rstool never calls Portal REST itself. Fetch live data outside rstool, then import constituents with `addOrUpdateConstituenta`.
 
-## API/REST
+- UI host: `https://portal.acconcept.ru`.
+- API host: `https://api.portal.acconcept.ru`.
+- Useful reads: `/api/rsforms/{id}`, `/api/rsforms/{id}/details`, `/api/library/{id}/versions/{v}`, `/api/oss/{id}`, `/api/models/{id}`, `/schema`.
+- Do not scrape SPA HTML or reuse UI query params like `?tab=`.
 
-For full reference see [../../docs/PORTAL-API.md](../../docs/PORTAL-API.md). Short form:
+## Syntax Cheatsheet
 
-- **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.
+- Globals: `X1`, `C1`, `S1`, `D1`, `F1`, `P1`, `A1`, `T1`, `N1`, `R1`.
+- Locals: `x`, `ξ`, `μ2`.
+- Literals: `42`, `Z`, `∅`.
+- Set expressions: `∪`, `∩`, `\`, `∆`, `×`, `ℬ(...)`, tuples, `Pr*`, `Fi*`.
+- Logic: `¬`, `&`, `∨`, `⇒`, `⇔`, `∀`, `∃`, `=`, `≠`, `<`, `∈`, `⊆`.
+- Parameterized expressions: `[arg1∈H1, arg2∈H2] body`.
 
-## 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.
+Read tool output; do not infer types by inspection.
 
 ## 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.
+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.
 
 ## 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
+1. `basic`, `constant`.
+2. Core structures and key concepts.
+3. Derived constituents in topological order.
+4. Axioms and statements after their references.
 
-## Natural-language fields: keep one language
+## Natural-Language Fields
 
-When you create new constituents (concepts) or build a schema from scratch, the fields `term`, `definitionText`, and `convention` must be written **in one consistent natural language**:
+Keep `term`, `definitionText`, and `convention` in one language.
 
-- If you are extending an existing schema/session, write these fields in the **same language that is already used** in the schema’s text fields.
-- If you are creating a new schema from zero, write these fields in the **language of the user’s request**.
+- Extending a schema: use the schema's existing language.
+- New schema: use the user's request language.
 
 ## 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`
+- [ ] `sessionId` tracked.
+- [ ] `basic` / `constant` formals are empty.
+- [ ] Dependencies exist before upsert.
+- [ ] `cstType` matches the role.
+- [ ] Diagnostics handled before commit/export.
+- [ ] Ambiguous semantics checked on a small model when data examples are available.
+- [ ] Base values set before evaluation.

package/skills/rstool-helper/REFERENCE.md

@@ -3,7 +3,7 @@
 ## rstool contract
 
 - Package: `@rsconcept/rstool`
-- Contract version: `1.2.0` (`CONTRACT_VERSION`)
+- Contract version: `1.4.0` (`CONTRACT_VERSION`)
 - Core class: `RSToolAgent`
 - Public imports: `@rsconcept/rstool` and `@rsconcept/rstool/wrapper`
 
@@ -18,6 +18,8 @@
 | `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`                             |
@@ -43,6 +45,20 @@
 
 Omitted text fields default to `''` in stored state.
 
+### `SessionState` metadata
+
+Set on `createSession(initial?)` or via `importSession`:
+
+```ts
+{
+  alias: string; // library item alias
+  title: string; // display title
+  comment: string; // developer notes
+}
+```
+
+All default to `''` when omitted.
+
 ### Model and evaluation types
 
 ```ts
@@ -69,7 +85,7 @@ Base/constant bindings use `type: "basic"` and `value: { "0": "label", … }`. S
 
 Process: `npx rstool-wrapper`
 
-1. **Ready** (no request): `{"id":null,"ok":true,"result":{"ready":true,"wrapper":"rstool-stdio","contractVersion":"1.2.0"}}`
+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":"..."}}`
 
@@ -85,6 +101,8 @@ Example chain:
 {"id":"4","method":"listDiagnostics","params":{"sessionId":"…"}}
 {"id":"5","method":"commitStep","params":{"sessionId":"…","message":"checkpoint"}}
 {"id":"6","method":"exportSession","params":{"sessionId":"…"}}
+{"id":"6a","method":"exportPortalSchema","params":{"sessionId":"…"}}
+{"id":"6b","method":"exportPortalModel","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}}}
@@ -109,7 +127,7 @@ interface AnalysisResult {
 - **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.
+Intro (help): language is FOL-based; set vs logic expression split; parameterized templates for term/predicate functions.
 
 ## Grammar tokens (selected)
 
@@ -134,15 +152,16 @@ Standalone agents should consult the bundled distilled docs (`docs/*.md` inside
 
 | Topic                                | Bundled doc                                |
 | ------------------------------------ | ------------------------------------------ |
-| Identifiers, literals                | `docs/SYNTAX.md` § *Identifier rules*      |
+| 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*     |
+| 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`                       |
@@ -166,6 +185,19 @@ Categories:
 
 `exportSession(sessionId)` returns a JSON string with `{ contractVersion, state, 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.
+
+## Portal import JSON
+
+For **Load from JSON** on an existing Portal schema or model:
+
+- `exportPortalSchema(sessionId)` — schema file
+- `exportPortalModel(sessionId)` — model file
+
+Both return `contract_version` `1.0.0` plus required `title`, `alias`, `description`, and `items`. Schema files may include `attribution`. Values come from `state.title`, `state.alias`, and `state.comment` (empty fields fall back to `Conceptual schema` / `SCHEMA` or `Conceptual model` / `MODEL` and `""`).
+
+- Schema `items[]`: versioned constituent fields (`cst_type`, `definition_formal`, `term_raw`, …).
+- Model `items[]`: `{ id, type, value }` per binding.

package/skills/rstool-helper/SKILL.md

@@ -20,13 +20,11 @@ Then continue with the canonical files below.
 
 ## Canonical files (read before rstool work)
 
-| What | Path |
-| :--- | :--- |
-| **Start here** — workflow, cstType, S# vs D# | `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` |
-| Language / domain docs | `node_modules/@rsconcept/rstool/docs/*.md` |
-| Install procedure | `node_modules/@rsconcept/rstool/skills/INSTALL.md` |
+- **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`
+- Language / domain docs: `node_modules/@rsconcept/rstool/docs/*.md`
+- Install procedure: `node_modules/@rsconcept/rstool/skills/INSTALL.md`
 
 Always open **GUIDE.md** first when starting a rstool task, then **REFERENCE.md** / **EXAMPLES.md** / relevant `docs/*.md` as needed.
 
@@ -34,4 +32,3 @@ Always open **GUIDE.md** first when starting a rstool task, then **REFERENCE.md*
 
 - Package: `@rsconcept/rstool`; wrapper: `npx rstool-wrapper`
 - `@rsconcept/domain` is installed as a dependency (analyzer, errors in `src/rslang/error.ts`)
-- Do not copy GUIDE, REFERENCE, EXAMPLES, or `docs/` into the project skills folder — read them from `node_modules` paths above

package/src/index.ts

@@ -25,6 +25,12 @@ export {
   type EvaluationResult,
   type ListDiagnosticsFilters,
   type ModelValueState,
+  PORTAL_JSON_CONTRACT_VERSION,
+  type PortalImportMetadata,
+  type PortalModelImportData,
+  type PortalSchemaConstituenta,
+  type PortalSchemaImportData,
+  type PortalTermForm,
   type RecalculateModelResult,
   type RSToolAgentContract,
   type RSToolErrorDescription,