Docs: Update readme, keywords, and description

Author: snatalenko

README.md

@@ -4,9 +4,24 @@ Declarative Mapper for Node.js
 [![Version](https://img.shields.io/npm/v/declarative-mapper.svg)](https://www.npmjs.com/package/declarative-mapper)
 [![Coverage](https://coveralls.io/repos/github/snatalenko/declarative-mapper/badge.svg?branch=master)](https://coveralls.io/github/snatalenko/declarative-mapper?branch=master)
 [![Downloads](https://img.shields.io/npm/dm/declarative-mapper.svg)](https://www.npmjs.com/package/declarative-mapper)
-[![License](https://img.shields.io/github/license/snatalenko/declarative-mapper.svg)](https://github.com/snatalenko/declarative-mapper)
+[![License](https://img.shields.io/github/license/snatalenko/declarative-mapper.svg?v=1.7.1)](https://github.com/snatalenko/declarative-mapper)
 [![Tests/Audit](https://github.com/snatalenko/declarative-mapper/actions/workflows/ci.yml/badge.svg)](https://github.com/snatalenko/declarative-mapper/actions)
 
+## Table of Contents
+
+- [Reasoning](#reasoning)
+  - [Quick Start Example](#quick-start-example)
+- [Mapping Instructions](#mapping-instructions)
+  - [Runtime Variables Quick Reference](#runtime-variables-quick-reference)
+  - [Objects](#objects)
+  - [Arrays](#arrays)
+  - [String\[\] from Object\[\]](#string-from-object)
+  - [String\[\] from String\[\]](#string-from-string)
+  - [Tuple Arrays](#tuple-arrays)
+  - [Runtime Variables ($input, $record, $index, $collection)](#runtime-variables-input-record-index-collection)
+  - [Dynamic Output Keys](#dynamic-output-keys)
+  - [Complex Mapping Example](#complex-mapping-example)
+
 ## Reasoning
 
 On several projects, I needed a library that could convert one JSON format to another (for example, an invoice from one system into another). It had to support **declarative mapping** instructions so users could configure mappings from a UI. It also had to be **flexible** enough for complex requirements, **secure** against JS injection, and **fast** enough to process streams with millions of records.
@@ -21,7 +36,7 @@ That is where Declarative Mapper came in:
 - **Lightweight** - no dependencies
 
 
-A simple example:
+### Quick Start Example
 
 ```ts
 import { createMapper } from 'declarative-mapper';
@@ -90,6 +105,15 @@ The right side is either a string with a valid JS expression or an object with m
 }
 ```
 
+### Runtime Variables Quick Reference
+
+| Variable | Description | Available in |
+| --- | --- | --- |
+| `$input` | Entire source document passed to the mapper. | All mapping contexts |
+| `$record` | Current element in a `forEach` iteration. | `forEach` → `map` |
+| `$index` | Current element index in a `forEach` iteration. | `forEach` → `map` |
+| `$collection` | Entire source array selected by `forEach`. | `forEach` → `map` |
+
 ### Objects
 
 Mapping of an object with inner properties:
@@ -150,7 +174,10 @@ Result:
   }]
 ```
 
-In this mapping, the execution context shifts to each input object, so inner properties can be referenced directly as `arrayInnerProperty` instead of `inputArray[index].arrayInnerProperty`. More on that in [Context Switching](#context-switching).
+In this mapping, the execution context shifts to each input object, so inner properties can be referenced directly as `arrayInnerProperty` instead of `inputArray[index].arrayInnerProperty`.
+
+Inside `forEach` mappings, `$record`, `$index`, `$collection`, and `$input` are also available.
+More on that in [Runtime Variables](#context-switching).
 
 
 #### String[] from Object[]
@@ -200,7 +227,7 @@ Result:
 [2, 4, 6]
 ```
 
-### Array with predefined set of elements
+### Tuple Arrays
 
 If the array should have a predefined set of elements, each element can be mapped by index:
 
@@ -255,13 +282,28 @@ Or up in the source document:
   }
 ```
 
-These special variables are useful for context switching:
+Inside `from` mappings, you can still reference root-level fields through `$input`.
+
+Runtime variables:
 
 - `$record` - current element of the array being iterated with `forEach`
 - `$index` - index of the current array element
 - `$collection` - entire collection of the elements being iterated
 - `$input` - entire document passed as mapping input
 
+Combined example (`forEach` + root reference):
+
+```json
+{
+  "forEach": "LINE_ITEMS",
+  "map": {
+    "lineNo": "$index + 1",
+    "sourceId": "$input.id",
+    "raw": "$record"
+  }
+}
+```
+
 ### Dynamic Output Keys
 
 You can build output property names dynamically with template-based keys on the left side.

package.json

@@ -1,10 +1,21 @@
 {
   "name": "declarative-mapper",
   "version": "1.7.0",
-  "description": "Declarative object mapper for NodeJS",
+  "description": "Declarative JSON and object mapper for Node.js/TypeScript: transform data with mapping templates, schema-based helpers, and safe VM execution.",
   "keywords": [
-    "declarative",
-    "mapping"
+    "json-mapper",
+    "object-mapper",
+    "data-mapper",
+    "declarative-mapping",
+    "data-transformation",
+    "object-transformation",
+    "schema-mapping",
+    "json-schema-mapping",
+    "json-to-json",
+    "config-driven",
+    "etl",
+    "nodejs",
+    "typescript"
   ],
   "type": "module",
   "main": "dist/cjs/index.js",