updated hs section

clyx_manual.md

@@ -282,13 +282,23 @@ Any line fragment starting with `#` to the end of the physical source line is re
 - **Stack Effect**: `( -- )`
 - **Description**: Prints the current stack representation to standard output (useful for debugging).
 
+---
+
+## 8. Host-specific (HS) Primitives
+
+**Warning**: relying upon the primitives from this group reduces your Clyx application's portability and the amount of platforms it can potentially run on, so they should be used very carefully.
+
 ### `hsargs` (Host Arguments)
 - **Stack Effect**: `( -- [args] )`
 - **Description**: Pushes a list/quotation of all passed command line arguments onto the stack.
 
+**N.B.**: on the platforms that don't support CLI arguments, this primitive will always push an empty quotation.
+
 ### `hsexit` (Host Exit)
 - **Stack Effect**: `( code -- )`
-- **Description**: Exits the program/interpreter with the specified exit code.
+- **Description**: Exits the program/interpreter process with the specified exit code.
+
+**N.B.**: on the platforms that don't support specifying process exit codes, this primitive may either do nothing, exit the program the usual way supported by the platform or trigger a global interpreter restart.
 
 ### `hseval` (Host Language Evaluation)
 - **Stack Effect**: `( expr -- val )`
@@ -298,7 +308,7 @@ Any line fragment starting with `#` to the end of the physical source line is re
 
 ---
 
-## 8. Bootstrapped Core Words
+## 9. Bootstrapped Core Words
 
 These words are defined in Clyx itself during the interpreter's bootstrap phase:
 
@@ -316,11 +326,11 @@ These words are defined in Clyx itself during the interpreter's bootstrap phase:
 
 ---
 
-## 9. Standard Library Words
+## 10. Standard Library Words
 
 These words are defined in the standard library file `lib.clx` and loaded dynamically during interpreter initialization. They are categorized below by domain and purpose:
 
-### 9.1 Stack Manipulation
+### 10.1 Stack Manipulation
 
 #### `over`
 - **Stack Effect**: `( x y -- x y x )`
@@ -338,7 +348,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( x y z -- y z x )`
 - **Description**: Rotates the third element of the stack to the top.
 
-### 9.2 Control Flow
+### 10.2 Control Flow
 
 #### `if`
 - **Syntax**: `if [true_actions] [false_actions]`
@@ -350,7 +360,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( -- )` (parses body quotation from the execution stream).
 - **Description**: Loops repeatedly. The body `actions` is executed, and must leave the next condition value on the stack. If the condition is non-zero, the loop repeats; otherwise it terminates.
 
-### 9.3 Mathematics & Arithmetic
+### 10.3 Mathematics & Arithmetic
 
 #### `div` (Divide Integer Values)
 - **Stack Effect**: `( x y -- div )`
@@ -384,7 +394,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( x f -- res )`
 - **Description**: Performs bit shift right of `x` by `f` bits (defined using `neg` and `shl`).
 
-### 9.4 Logical Operators
+### 10.4 Logical Operators
 
 #### `not`
 - **Stack Effect**: `( x -- c )`
@@ -398,7 +408,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( x y -- c )`
 - **Description**: Logical OR. Pushes `1` if either `x` or `y` is non-zero, else pushes `0`.
 
-### 9.5 Input / Output & Networking
+### 10.5 Input / Output & Networking
 
 #### `cr` (Carriage Return / Newline)
 - **Stack Effect**: `( -- )`
@@ -426,7 +436,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 
 **N.B.**: this word may not be supported on all targets.
 
-### 9.6 Type Checking & Comparison
+### 10.6 Type Checking & Comparison
 
 #### `isnum` (Is Number)
 - **Stack Effect**: `( x -- x c )`
@@ -467,7 +477,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( val -- len )`
 - **Description**: Pushes the length of `val`. If `val` is a list, it returns the number of elements; if it is a string, it returns the number of characters.
 
-### 9.7 String Operations
+### 10.7 String Operations
 
 #### `streq` (String Equal)
 - **Stack Effect**: `( s1 s2 -- c )`
@@ -489,7 +499,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( val -- [q] )`
 - **Description**: Converts the value `val` (if it is a string) to a list of its ASCII character codes. If `val` is already a list, it does nothing.
 
-### 9.8 List Operations
+### 10.8 List Operations
 
 #### `qpush` (Quotation Push)
 - **Stack Effect**: `( [q] x -- [q... x] )`
@@ -503,7 +513,7 @@ These words are defined in the standard library file `lib.clx` and loaded dynami
 - **Stack Effect**: `( [q1] [q2] -- [q1_q2] )`
 - **Description**: Concatenates two lists `[q1]` and `[q2]`.
 
-### 9.9 Bitwise Operations
+### 10.9 Bitwise Operations
 
 #### `bitnot` (Bitwise NOT)
 - **Stack Effect**: `( x -- ~x )`