@rsconcept/rstool 0.1.0 → 0.2.1

package/docs/DOMAIN.md

@@ -18,20 +18,22 @@ A **constituent** is the atomic building block of a conceptual schema. Each cons
 
 Constituent aliases follow a strict prefix scheme:
 
-| Alias prefix | Role | Notes |
-|-----|------|-------|
-| `N#` | Nominoid | Free vocabulary item, no formal definition |
-| `X#` | Base set | Undefined concept, set of distinguishable elements |
-| `C#` | Constant set | Undefined concept, set-theoretic constant with operations |
-| `S#` | Structured concept | Undefined concept with explicit typification, axioms, convention |
-| `D#` | Term | Derived concept (set / value) defined by a formal expression |
-| `F#` | Term-function | Parameterised derived concept yielding an STE |
-| `P#` | Predicate-function | Parameterised derived concept yielding a logical expression |
-| `A#` | Axiom | Logical statement asserting requirements |
-| `T#` | Statement | Logical assertion about the model |
-| `R#` | Radical | Template placeholder for arbitrary typification |
-
-**Undefined concepts** (`X#`, `C#`, `S#`) are introduced by conventions (and optional axioms); they have **no formal definition**. **Derived concepts** (`D#`, `F#`, `P#`, `A#`, `T#`) carry a formal expression and must follow declaration order — every referenced constituent must already exist.
+| Alias prefix | Role                                     | Notes                                                                                           |
+| ------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `N#`         | Nominoid                                 | Free vocabulary item, no formal definition                                                      |
+| `X#`         | Base set                                 | Undefined concept, set of elements                                                              |
+| `C#`         | Constant set                             | Undefined concept, set of elements, allows arithmetic predicates and operations                 |
+| `S#`         | Structured concept (**genus structure**) | Undefined concept; `definitionFormal` gives **typification**; meaning via `convention` / axioms |
+| `D#`         | Term                                     | Derived concept; `definitionFormal` is the **definition**; value computed in a model            |
+| `F#`         | Term-function                            | Parameterised derived concept yielding an STE                                                   |
+| `P#`         | Predicate-function                       | Parameterised derived concept yielding a logical expression                                     |
+| `A#`         | Axiom                                    | Logical statement asserting requirements                                                        |
+| `T#`         | Statement                                | Logical assertion about the model                                                               |
+| `R#`         | Radical                                  | Template placeholder for arbitrary typification                                                 |
+
+**Undefined concepts** (`X#`, `C#`, `S#`) are introduced by conventions (and optional axioms). For `S#`, the formal field states **typification** (the grade of elements), not a defining construction. **Derived concepts** (`D#`, `F#`, `P#`, `A#`, `T#`) carry a formal **definition** and must follow declaration order — every referenced constituent must already exist; their model values are obtained by evaluation.
+
+**Structure vs term:** `S#` with `ℬ(X1×X1)` declares “elements are pairs over `X1`”; the actual pairs come from interpretation. `D#` with `X1×X1` as the whole expression denotes the **full Cartesian product** (all pairs), which is a computed set — use `S#` + projections when modeling a relation.
 
 A **crucial constituent** is marked as content-bearing for filtering / focus; it has no semantic effect on the formal calculus.
 
@@ -39,27 +41,27 @@ A **crucial constituent** is marked as content-bearing for filtering / focus; it
 
 Each constituent has one of the following correctness statuses:
 
-| Status | Meaning |
-|--------|---------|
-| Unknown | Not yet validated |
-| OK | Validated as correct |
-| Error | Validation failed |
-| Property | Defines a non-computable set; only membership tests are admissible |
-| Incalculable | Cannot be evaluated directly (e.g. expected exponential blow-up) |
+| Status       | Meaning                                                            |
+| ------------ | ------------------------------------------------------------------ |
+| Unknown      | Not yet validated                                                  |
+| OK           | Validated as correct                                               |
+| Error        | Validation failed                                                  |
+| Property     | Defines a non-computable set; only membership tests are admissible |
+| Incalculable | Cannot be evaluated directly (e.g. expected exponential blow-up)   |
 
 ## RSModel evaluation states
 
 In a conceptual model each item has one of the following evaluation statuses:
 
-| Status | Meaning |
-|--------|---------|
-| `NO_EVAL` (1) | Not evaluated (definition is not interpretable) |
-| `NOT_PROCESSED` (2) | Interpretation has not been computed yet |
-| `INVALID_DATA` (3) | Provided data is invalid |
-| `EVAL_FAIL` (4) | Evaluation raised an error |
-| `AXIOM_FALSE` (5) | Axiom evaluated to FALSE |
-| `EMPTY` (6) | Result is the empty set |
-| `HAS_DATA` (7) | Interpretation computed and non-empty |
+| Status              | Meaning                                         |
+| ------------------- | ----------------------------------------------- |
+| `NO_EVAL` (1)       | Not evaluated (definition is not interpretable) |
+| `NOT_PROCESSED` (2) | Interpretation has not been computed yet        |
+| `INVALID_DATA` (3)  | Provided data is invalid                        |
+| `EVAL_FAIL` (4)     | Evaluation raised an error                      |
+| `AXIOM_FALSE` (5)   | Axiom evaluated to FALSE                        |
+| `EMPTY` (6)         | Result is the empty set                         |
+| `HAS_DATA` (7)      | Interpretation computed and non-empty           |
 
 ## Synthesis and OSS
 

package/docs/GRAMMAR-REF.md

@@ -1,79 +1,79 @@
 # Grammar reference (pointers)
 
-The full Lezer grammar ships inside `@rsconcept/domain` at `node_modules/@rsconcept/domain/src/rslang/parser/rslang.grammar`. The generated parser is `parser.ts` in the same folder. Below is a compact token map agents can use without opening the grammar.
+Below is a compact token map agents can use without opening the grammar. For full grammar see `@rsconcept/domain` package.
 
 ## Token classes
 
-| Class | Tokens / examples |
-|-------|-------------------|
-| Whitespace | space, tab, newline |
-| Integer literal | `0`, `42` |
-| Empty set | `∅` |
-| Integer set | `Z` |
-| Globals | `X#`, `C#`, `S#`, `D#`, `F#`, `P#`, `A#`, `T#`, `N#`, `R#` |
-| Locals | `x`, `ξ`, `μ2`, `y1` |
-| Punctuation | `(`, `)`, `[`, `]`, `{`, `}`, `,`, `;` |
-| Comment | none — RSLang has no comments inside formal expressions |
+| Class           | Tokens / examples                                          |
+| --------------- | ---------------------------------------------------------- |
+| Whitespace      | space, tab, newline                                        |
+| Integer literal | `0`, `42`                                                  |
+| Empty set       | `∅`                                                        |
+| Integer set     | `Z`                                                        |
+| Globals         | `X#`, `C#`, `S#`, `D#`, `F#`, `P#`, `A#`, `T#`, `N#`, `R#` |
+| Locals          | `x`, `ξ`, `μ2`, `y1`                                       |
+| Punctuation     | `(`, `)`, `[`, `]`, `{`, `}`, `,`, `;`                     |
+| Comment         | none — RSLang has no comments inside formal expressions    |
 
 ## Set / structural operators
 
-| Token | Symbol |
-|-------|--------|
-| Union | `∪` |
-| Intersection | `∩` |
-| Difference | `\` |
-| Symmetric difference | `∆` |
-| Cartesian product | `×` |
-| Boolean | `ℬ` |
-| Sum set | `red` |
-| Singleton | `bool` |
-| Desingleton | `debool` |
-| Small projection | `pr1`, `pr1,3`, … |
-| Large projection | `Pr1`, `Pr2,4`, … |
-| Filter | `Fi1[D](S)`, `Fi1,2[D](S)` |
-| Cardinality | `card` |
+| Token                | Symbol                     |
+| -------------------- | -------------------------- |
+| Union                | `∪`                        |
+| Intersection         | `∩`                        |
+| Difference           | `\`                        |
+| Symmetric difference | `∆`                        |
+| Cartesian product    | `×`                        |
+| Boolean              | `ℬ`                        |
+| Sum set              | `red`                      |
+| Singleton            | `bool`                     |
+| Desingleton          | `debool`                   |
+| Small projection     | `pr1`, `pr1,3`, …          |
+| Large projection     | `Pr1`, `Pr2,4`, …          |
+| Filter               | `Fi1[D](S)`, `Fi1,2[D](S)` |
+| Cardinality          | `card`                     |
 
 ## Predicates
 
-| Token | Symbol |
-|-------|--------|
-| Membership | `∈` |
-| Non-membership | `∉` |
-| Inclusion | `⊆` |
-| Strict inclusion | `⊂` |
-| Non-inclusion | `⊄` |
-| Equality | `=` |
-| Inequality | `≠` |
-| Less | `<` |
-| Less-or-equal | `≤` |
-| Greater | `>` |
-| Greater-or-equal | `≥` |
+| Token            | Symbol |
+| ---------------- | ------ |
+| Membership       | `∈`    |
+| Non-membership   | `∉`    |
+| Inclusion        | `⊆`    |
+| Strict inclusion | `⊂`    |
+| Non-inclusion    | `⊄`    |
+| Equality         | `=`    |
+| Inequality       | `≠`    |
+| Less             | `<`    |
+| Less-or-equal    | `≤`    |
+| Greater          | `>`    |
+| Greater-or-equal | `≥`    |
 
 ## Logical connectives
 
-| Token | Symbol |
-|-------|--------|
-| Negation | `¬` |
-| Conjunction | `&` |
-| Disjunction | `∨` |
-| Implication | `⇒` |
-| Equivalence | `⇔` |
+| Token       | Symbol |
+| ----------- | ------ |
+| Negation    | `¬`    |
+| Conjunction | `&`    |
+| Disjunction | `∨`    |
+| Implication | `⇒`    |
+| Equivalence | `⇔`    |
 
 ## Quantifiers
 
-| Token | Symbol |
-|-------|--------|
-| Universal | `∀` |
-| Existential | `∃` |
+| Token       | Symbol |
+| ----------- | ------ |
+| Universal   | `∀`    |
+| Existential | `∃`    |
 
 ## Declarators
 
-| Token | Form |
-|-------|------|
-| Function declaration | `F# ::= [<params>] <body STE>` |
-| Predicate declaration | `P# ::= [<params>] <body LE>` |
+| Token                 | Form                                              |
+| --------------------- | ------------------------------------------------- |
+| Function declaration  | `F# ::= [<params>] <body STE>`                    |
+| Predicate declaration | `P# ::= [<params>] <body LE>`                     |
 | Parameter declaration | `α ∈ <STE>` (commas separate; commas inside `[]`) |
-| Function call | `F#[<arg1>, <arg2>, …]` |
+| Function call         | `F#[<arg1>, <arg2>, …]`                           |
 
 ## Precedence (from highest to lowest)
 

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/README.md

@@ -5,6 +5,7 @@ Standalone English reference distilled from the Portal manuals and `CONTEXT.md`.
 | File | Read when |
 |------|-----------|
 | [`DOMAIN.md`](DOMAIN.md) | You need the Concept Portal vocabulary (constituenta, conceptual schema/model, OSS, synthesis). |
+| [`CONCEPTUAL-SCHEMA.md`](CONCEPTUAL-SCHEMA.md) | You are designing/reviewing a conceptual schema as a system (thesaurus value, closed-world text definitions, genus structures, axioms). |
 | [`CONSTITUENTA.md`](CONSTITUENTA.md) | You are upserting constituents — fields, `cstType` table, validation rules, recommended order. |
 | [`SYNTAX.md`](SYNTAX.md) | You are constructing RSLang expressions — operators, quantifiers, parameterised functions, examples. |
 | [`TYPIFICATION.md`](TYPIFICATION.md) | You are interpreting `AnalysisResult.type` / `valueClass` or constructing template expressions with radicals. |

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 a basic concept's elements  |
+| Integer          | `Z`                  | grade of integer                     |
+| Tuple of arity n | `(H1 × H2 × … × Hn)` | ordered structured grade             |
+| Set              | `ℬ(H)`               | unordered 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.1",
   "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).