@misterscan/sesi 1.2.3 → 1.3.2

package/.agents/rules/sesi-must-read.md

@@ -0,0 +1,116 @@
+---
+trigger: always_on
+---
+
+# The Sesi Programming Language
+
+## 🛑 CRITICAL STARTUP DIRECTIVE
+
+- **Strict Active Context**: You must ONLY read the file that is currently the Active Document, or files that the user explicitly mentions in the conversation. Do NOT run `git status`, `git diff`, or scan the directory on startup to find and read other files.
+
+## Core Identity & Execution
+
+- **File Extension:** `.sesi`
+- `src/`: The core TypeScript engine (Lexer, Parser, Interpreter, AI-Runtime, Builtins).
+- `bin/sesi.js`: The global CLI executable entry point.
+- `examples/`: Official syntax-demonstration scripts (`01_hello.sesi` through `13_data_pipeline.sesi`).
+- `chatbot/`: Local Sesi support and `sesi_db_chatbot.sesi` - Sesi's built-in Co-Pilot.
+- `main/`: `tests/` like `test_failure_debug.sesi`. **Run inline code evaluations (`-e 'code'`) instead of writing new `.sesi` files for quick tests. Do not overwrite existing `.sesi` files unless explicitly asked to.**
+- `docs/`: The source of truth for all sesi syntax, formatting, and structuring guidelines. It contains the official API docs for all built-in functions and types. AIs must treat this as the primary source of truth for syntax and structure.
+- Root helper scripts: `example.js`, `example-ai.js`, and `examples.sesi` are convenience wrappers. AI agents should still use the `npx sesi` command as specified.
+- **Paradigm:** **Sesi** is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. The language itself is so simple. It is a language built for clarity and reusability.
+
+## Agent Debug Protocol (MANDATORY)
+
+When AI agents write or edit `.sesi` scripts, they must use this debugging loop:
+
+1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
+2. **Validate snippet with eval mode first:** Run `npm run sesi:eval <file>.sesi` to test the isolated block before full-script execution.
+3. **Apply fix in file only after eval passes:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
+4. **Run full script after snippet stabilization:** Execute `npm run sesi <file>.sesi` only once the isolated logic is valid.
+5. **Use file-aware help when blocked:** Run `npm run sesi:help <file>.sesi "<question>"` to get context-grounded help tied to the active script.
+6. **NEVER EDIT ANY .SESI FILES IN THE TERMINAL (ABSOLUTE RULE):**
+   - Do NOT run `sed`, `awk`, `perl`, or any other shell text-processing tools on `.sesi` files.
+   - Do NOT use `npm run sesi:eval` to modify files; it is only for syntax validation.
+   - Do NOT use Bash/Shell scripting to rewrite or patch Sesi source code.
+
+   **Correct approach:** You MUST always use your native editor/IDE's file editing capabilities to make clean, safe changes directly to `.sesi` files.
+   **Why:** Sesi syntax is sensitive to whitespace, newlines, and brace positioning. Terminal-based string replacement will invariably break code. Use the editor, not the terminal.
+
+7. **Emphasize Native Verification Commands:** Prior to saving or running full Sesi scripts, proactively use inline evaluation (`npm run sesi:eval <file>.sesi` or `node bin/sesi.js -e "..."`) to check and verify syntax and runtime behaviors instantly. It keeps execution cycles fast and deterministic.
+
+## Standards (ONLY REGARDING src/ FILES)
+
+- **Type-Only Imports (MANDATORY):** Use `import {type ...}` for AST nodes. **DO NOT REMOVE** these. Removing them will break the build.
+- **Interpreter Patterns (DO NOT "CLEAN UP"):** Dynamic casting and `any` are **EXPLICITLY PERMITTED** for tree-walking logic. They are a foundational part of the Sesi engine's design.
+- **Ignore Linting Noise:** If you see warnings like "Unexpected any" or "Unsafe member access", **IGNORE THEM**.
+- **Build Requirement:** You MUST run `npm run build` after every code change to the backend logic. Failure to build will result in testing stale code.
+
+This protocol is required to reduce noisy full-run failures and speed up AI-assisted iteration.
+
+Sesi is **NOT** the following coding languages, therefore **NEVER UTILIZE THE SAME SYNTAX OR FORMATTING UNDER ANY CIRCUMSTANCES WHATSOEVER!!!!!**
+
+- **NOT** An "AI Wrapper"
+- **NOT** A "LLM Framework"
+- **NOT** An "AI-Native Programming Language"
+- **NOT** Python
+- **NOT** Rust
+- **NOT** Typescript
+- **NOT** YAML
+- **NOT** BAML
+- **NOT** Go
+- **NOT** C++
+- **NOT** C
+- **NOT** Java
+- **NOT** C#
+- **NOT** Javascript
+- **NOT** Bash
+- **NOT** Shell
+- **NOT** Ruby
+- **NOT** PHP
+- **NOT** Swift
+- **NOT** Julia
+- **NOT** Scala
+- **NOT** Any other programming language or scripting language.
+
+### ✅ REQUIRED — Sesi scripts must use the language's built-ins:
+
+Every script you write must use **at least one** of:
+
+- `prompt` - composable script templates, this is NOT related to AI at all
+- `structured_output` - structured data extraction, this is NOT related to AI at all
+- `memory` — stateful multi-turn context, this is NOT related to AI at all
+- `exec()` — concurrent process orchestration
+- `web_send()` - sending an HTTP request to a URL
+- `web_get()` - collecting data from a URL
+- `define_tool()` - categorizing tool calls
+- `list_tools()` - displaying custom tools
+- `tool_call()` - calling a predefined function, this is NOT related to AI at all
+- `multi_req()` - concurrent function execution
+- `import` / `export` - reusable configuration modules
+
+The bar is: **"Is this easy to write and read?"** If the answer is no, rewrite it.
+
+## Mandatory Syntax Rules & Quirks
+
+- **Block Termination:** Closing braces `}` for blocks (if, while, try, model) no longer strictly require a following newline or semicolon. Condensed one-liners like `while x {x = x + 1}` are valid.
+- **Prompts & Prints:** Inside `prompt` blocks, anonymous model blocks, and `print` statements, literal strings and variables are placed sequentially naturally (e.g., `print "User:" name`). It's highly preferred to **AVOID** use of the `+` operator in these contexts, regardless of its backwards-compatibility.
+- **Structured Output Schemas:** Keys in schemas MUST be unquoted identifiers (e.g., `{key: string}` instead of `{"key": string}`). This is a known deviation from standard JSON objects in the Sesi parser.
+- **Object Literals:** Conversely, standard object literals `{}` DO require strictly quoted string keys (e.g., `{"name": "Alice"}`).
+- **JSON Serialization:** Use `to_json(object)` for valid JSON output. Avoid `stringify(object)` for JSON.
+- **Systems Primitive:** Forbid `const` (use `let`), `main()` wrappers, and `return` statements (however, `return` is neccessary inside of a `fn` block). Focus on side-effects and top-level execution.
+- **Resilience:** Always wrap file I/O in `try/catch` retry loops to handle filesystem contention.
+
+For all quirks and specific syntaxing, visit IMPLEMENTATION_SUMMARY.md, /docs/SPECIFICATION.md, /docs/BUILTINS.md, and /docs/CLI.
+
+## IGNORE THESE FILES
+
+- `docs/agent_native_programming.md`
+- `docs/REASONING.md`
+- `docs/IMAGE_GENERATION.md`
+- `*.txt`
+- `*.log`
+- `query.txt`
+- `.sesi_cache.json`
+- `.sesi_chat_history.json`
+- `/landing-pages/`

package/.agents/workflows/create-sesi-script.md

@@ -0,0 +1,44 @@
+---
+description: Intent-based development workflow for generating concise, syntax-accurate Sesi scripts using integrated web research and verified implementation patterns.
+---
+
+## Operational Directives
+
+1. **Let Sesi Do Its Job**: A Sesi builder script makes the system perfectly repeatable, infinitely scalable, and trivial to refactor. In this repository, the Sesi script is the core product; the end file(s) are merely the byproduct for post edits and making sure our scripts are behaving as anticipated.
+2. **Script Creation:** Your primary task is to generate scripts in Sesi.
+3. **Syntax Integrity:** Strictly adhere to established Sesi syntax and formatting rules. Never fabricate or hallucinate rules. If a pattern is not verified within Sesi, do not use it.
+4. **Language and Perspective:** Maintain a grounded, practical perspective. Avoid technical jargon, buzzwords, or computational theory in your internal thought process and your final output. Focus on the user's request at hand. Do not drift into irrelevant files not explicitly mentioned by the user, you are not allowed to open them.
+5. **Information Sourcing:** Do not rely on pre-existing training data for language definitions or outdated practices. Prioritize active research to find current, relevant implementation patterns. If a method or approach is flagged as outdated, discard it immediately.
+6. **Inspiration:** While Sesi is a distinct, emerging language, draw inspiration for script logic and functionality from any programming language. Ensure that this inspiration is limited to the _concept_ of the solution, not the syntax or formatting of the source language.
+7. **Cautious Integration:** Do NOT use model(), image(), or workflow(). The user is the only one with permission to use these functions. Unless they explicitly request it, do not even consider it in your script once.
+8. **Core Philosophy:** Sesi scripts must be concise, legible, and intent-based. If a solution feels overly complex or forced, it likely deviates from the Sesi philosophy. Keep the implementation direct.
+9. **Efficiency and Accessibility:** Sesi is designed to make development straightforward and enjoyable. Leverage web search and external resources freely to find inspiration and tools. You have full authorization to browse and synthesize information from available sources to streamline script creation.
+
+## Mandatory Syntax Rules & Quirks
+
+- **Block Termination:** Closing braces `}` for blocks (if, while, try, model) no longer strictly require a following newline or semicolon. Condensed one-liners like `while x {x = x + 1}` are valid.
+- **Prompts & Prints:** Inside `prompt` blocks, anonymous model blocks, and `print` statements, literal strings and variables are placed sequentially naturally (e.g., `print "User:" name`). It's highly preferred to **AVOID** use of the `+` operator in these contexts, regardless of its backwards-compatibility.
+- **Structured Output Schemas:** Keys in schemas MUST be unquoted identifiers (e.g., `{key: string}` instead of `{"key": string}`). This is a known deviation from standard JSON objects in the Sesi parser.
+- **Object Literals:** Conversely, standard object literals `{}` DO require strictly quoted string keys (e.g., `{"name": "Alice"}`).
+- **JSON Serialization:** Use `to_json(object)` for valid JSON output. Avoid `stringify(object)` for JSON.
+- **Systems Primitive:** Forbid `const` (use `let`), `main()` wrappers, and `return` statements (however, `return` is neccessary inside of a `fn` block). Focus on side-effects and top-level execution.
+- **Resilience:** Always wrap file I/O in `try/catch` retry loops to handle filesystem contention.
+
+## Agent Debug Protocol (MANDATORY)
+
+When AI agents write or edit `.sesi` scripts, they must use this debugging loop:
+
+1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
+2. **Validate snippet with eval mode first:** Run `npm run sesi:eval <file>.sesi` to test the isolated block before full-script execution.
+3. **Apply fix in file only after eval passes:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
+4. **Run full script after snippet stabilization:** Execute `npm run sesi <file>.sesi` only once the isolated logic is valid.
+5. **Use file-aware help when blocked:** Run `npm run sesi:help <file>.sesi "<question>"` to get context-grounded help tied to the active script.
+6. **NEVER EDIT ANY .SESI FILES IN THE TERMINAL (ABSOLUTE RULE):**
+   - Do NOT run `sed`, `awk`, `perl`, or any other shell text-processing tools on `.sesi` files.
+   - Do NOT use `npm run sesi:eval` to modify files; it is only for syntax validation.
+   - Do NOT use Bash/Shell scripting to rewrite or patch Sesi source code.
+
+   **Correct approach:** You MUST always use your native editor/IDE's file editing capabilities to make clean, safe changes directly to `.sesi` files.
+   **Why:** Sesi syntax is sensitive to whitespace, newlines, and brace positioning. Terminal-based string replacement will invariably break code. Use the editor, not the terminal.
+
+7. **Emphasize Native Verification Commands:** Prior to saving or running full Sesi scripts, proactively use inline evaluation (`npm run sesi:eval <file>.sesi` or `node bin/sesi.js -e "..."`) to check and verify syntax and runtime behaviors instantly. It keeps execution cycles fast and deterministic.

package/.agents/workflows/fix-sesi-script.md

@@ -0,0 +1,14 @@
+---
+description: Debugging and validation of error prone sesi scripts.
+---
+
+1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
+2. **Validate snippet with eval mode first:** Run `npm run sesi:eval "..."` to test the isolated block before full-script execution.
+3. **Run inline code evaluations instead of writing new `.sesi` files for quick tests.:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
+4. **Run full script after snippet stabilization:** Execute `npm run sesi <file>.sesi` only once the isolated logic is valid.
+5. **Use file-aware help when blocked:** Run `npm run sesi:help <file>.sesi "<question>"` to get context-grounded help tied to the active script.
+6. **NEVER Edit Sesi Files in the Terminal:** Under no circumstances should you attempt to perform file editing or text replacements via terminal commands (such as `sed`, `awk`, or scripts). **You MUST always use your native IDE/editor tools to make clean, safe file edits directly.**
+7. **Emphasize Native Verification Commands:** Prior to saving or running full Sesi scripts, proactively use inline evaluation (`npx run sesi:eval "..."` or `node bin/sesi.js -e "..."`) to check and verify syntax and runtime behaviors instantly. It keeps execution cycles fast and deterministic.
+8. **Always Check Specifications first:** Verify specifications in the `docs/` or `examples/` folders before assuming language quirks.
+
+_If running through Powershell, AI-Agents may not have explicit access to using the `npm` or `sesi` commands in their sandbox enviornments without running into FullExecution errors. In this case, use `node bin/sesi.js <file> <option>` in replacement of `npm run sesi`._

package/.github/prompts/MakeInSesi.prompt.md

@@ -0,0 +1,79 @@
+---
+name: MakeInSesi
+description: Intent-based development workflow for generating concise, syntax-accurate Sesi scripts using integrated web research and verified implementation patterns.
+agent: Plan
+model: GPT-4.1 (copilot)
+tools:
+  [
+    execute/getTerminalOutput,
+    execute/killTerminal,
+    execute/sendToTerminal,
+    execute/runTask,
+    execute/createAndRunTask,
+    execute/runInTerminal,
+    execute/runTests,
+    execute/testFailure,
+    read/problems,
+    read/readFile,
+    read/viewImage,
+    read/terminalSelection,
+    read/terminalLastCommand,
+    read/getTaskOutput,
+    agent,
+    edit/createDirectory,
+    edit/createFile,
+    edit/editFiles,
+    edit/rename,
+    search,
+    web,
+    browser/openBrowserPage,
+    browser/readPage,
+    browser/screenshotPage,
+    browser/navigatePage,
+    browser/clickElement,
+    azure-mcp/search,
+    todo,
+  ]
+argument-hint: "Write a Sesi script that..."
+---
+
+## Operational Directives
+
+1. **Let Sesi Do Its Job**: A Sesi builder script makes the system perfectly repeatable, infinitely scalable, and trivial to refactor. In this repository, the Sesi script is the core product; the end file(s) are merely the byproduct for post edits and making sure our scripts are behaving as anticipated.
+2. **Script Creation:** Your primary task is to generate scripts in Sesi.
+3. **Syntax Integrity:** Strictly adhere to established Sesi syntax and formatting rules. Never fabricate or hallucinate rules. If a pattern is not verified within Sesi, do not use it.
+4. **Language and Perspective:** Maintain a grounded, practical perspective. Avoid technical jargon, buzzwords, or computational theory in your internal thought process and your final output. Focus on the user's request at hand. Do not drift into irrelevant files not explicitly mentioned by the user, you are not allowed to open them.
+5. **Information Sourcing:** Do not rely on pre-existing training data for language definitions or outdated practices. Prioritize active research to find current, relevant implementation patterns. If a method or approach is flagged as outdated, discard it immediately.
+6. **Inspiration:** While Sesi is a distinct, emerging language, draw inspiration for script logic and functionality from any programming language. Ensure that this inspiration is limited to the _concept_ of the solution, not the syntax or formatting of the source language.
+7. **Cautious Integration:** Do NOT use model(), image(), or workflow(). The user is the only one with permission to use these functions. Unless they explicitly request it, do not even consider it in your script once.
+8. **Core Philosophy:** Sesi scripts must be concise, legible, and intent-based. If a solution feels overly complex or forced, it likely deviates from the Sesi philosophy. Keep the implementation direct.
+9. **Efficiency and Accessibility:** Sesi is designed to make development straightforward and enjoyable. Leverage web search and external resources freely to find inspiration and tools. You have full authorization to browse and synthesize information from available sources to streamline script creation.
+
+## Mandatory Syntax Rules & Quirks
+
+- **Block Termination:** Closing braces `}` for blocks (if, while, try, model) no longer strictly require a following newline or semicolon. Condensed one-liners like `while x {x = x + 1}` are valid.
+- **Prompts & Prints:** Inside `prompt` blocks, anonymous model blocks, and `print` statements, literal strings and variables are placed sequentially naturally (e.g., `print "User:" name`). It's highly preferred to **AVOID** use of the `+` operator in these contexts, regardless of its backwards-compatibility.
+- **Structured Output Schemas:** Keys in schemas MUST be unquoted identifiers (e.g., `{key: string}` instead of `{"key": string}`). This is a known deviation from standard JSON objects in the Sesi parser.
+- **Object Literals:** Conversely, standard object literals `{}` DO require strictly quoted string keys (e.g., `{"name": "Alice"}`).
+- **JSON Serialization:** Use `to_json(object)` for valid JSON output. Avoid `stringify(object)` for JSON.
+- **Systems Primitive:** Forbid `const` (use `let`), `main()` wrappers, and `return` statements (however, `return` is neccessary inside of a `fn` block). Focus on side-effects and top-level execution.
+- **Resilience:** Always wrap file I/O in `try/catch` retry loops to handle filesystem contention.
+
+## Agent Debug Protocol (MANDATORY)
+
+When AI agents write or edit `.sesi` scripts, they must use this debugging loop:
+
+1. **Draft in file, isolate risky snippet:** Identify the smallest parser/runtime-risky block (prompt block, model call, object schema, loop, etc.).
+2. **Validate snippet with eval mode first:** Run `npm run sesi:eval <file>.sesi` to test the isolated block before full-script execution.
+3. **Apply fix in file only after eval passes:** If eval fails, iterate on snippet; do not repeatedly run full scripts while syntax is unresolved.
+4. **Run full script after snippet stabilization:** Execute `npm run sesi <file>.sesi` only once the isolated logic is valid.
+5. **Use file-aware help when blocked:** Run `npm run sesi:help <file>.sesi "<question>"` to get context-grounded help tied to the active script.
+6. **NEVER EDIT ANY .SESI FILES IN THE TERMINAL (ABSOLUTE RULE):**
+   - Do NOT run `sed`, `awk`, `perl`, or any other shell text-processing tools on `.sesi` files.
+   - Do NOT use `npm run sesi:eval` to modify files; it is only for syntax validation.
+   - Do NOT use Bash/Shell scripting to rewrite or patch Sesi source code.
+
+   **Correct approach:** You MUST always use your native editor/IDE's file editing capabilities to make clean, safe changes directly to `.sesi` files.
+   **Why:** Sesi syntax is sensitive to whitespace, newlines, and brace positioning. Terminal-based string replacement will invariably break code. Use the editor, not the terminal.
+
+7. **Emphasize Native Verification Commands:** Prior to saving or running full Sesi scripts, proactively use inline evaluation (`npm run sesi:eval <file>.sesi` or `node bin/sesi.js -e "..."`) to check and verify syntax and runtime behaviors instantly. It keeps execution cycles fast and deterministic.

package/README.md

@@ -1,8 +1,10 @@
+## SESI IS **NOT** AN AI WRAPPER LANGUAGE. IT IS **NOT** AN AI-NATIVE PROGRAMMING LANGUAGE. IT IS A GENERAL-PURPOSE PROGRAMMING LANGUAGE WITH **OPTIONAL** AI CAPABILITIES BUILT-IN. STRONG EMPHASIS ON **OPTIONAL**.
+
 <p align="center">
   <img src="./sesi-logo.svg" alt="Sesi Logo" width="250" />
 </p>
 
-<h1 align="center">Sesi: A High-Performance Systems Language</h1>
+<h1 align="center">Sesi: A Concise, Legible Programming Language</h1>
 
 <p align="center">
   <em>Pronounced "say-see" — What you say, you'll see.</em>
@@ -10,13 +12,13 @@
 
 <p align="center">
   <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg">
-  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript">
+  <img alt="TypeScript" src="https://img.shields.io/badge/TypeScript-Interpreter-blue?logo=typescript">
   <img alt="Powered by Gemini" src="https://img.shields.io/badge/Powered%20By-Google%20Gemini-orange">
   <img alt="Framework" src="https://img.shields.io/badge/Node.js-Engine-success?logo=node.js">
 </p>
 
 <p align="center">
-  <strong>Sesi</strong> is a high-performance <strong>Systems Language</strong> designed for building resilient, stateful applications. It provides first-class primitives for process management, filesystem orchestration, and integrated reasoning, enabling developers to build complex logic with a fraction of the boilerplate required by traditional languages.
+  <strong>Sesi</strong> is a clean, minimal, and highly legible programming language. Built from the ground up to be concise and buildable, Sesi removes unnecessary boilerplate. It is a language built for clarity.
 </p>
 
 <p align="center">
@@ -70,7 +72,10 @@ Then run any program directly:
 
 ```bash
 # Standard script execution
-sesi main/start.sesi
+sesi examples/01_hello.sesi
+
+# Run script with arguments
+sesi main/test_args.sesi arg1 arg2
 
 # Reasoning script example
 sesi examples/08_model_call.sesi
@@ -79,13 +84,72 @@ sesi examples/08_model_call.sesi
 sesi examples.sesi
 ```
 
+Useful CLI shortcuts:
+
+```bash
+# Evaluate a quick snippet
+sesi -e "print 'hello'"
+```
+
+```bash
+# Ask the built-in co-pilot a question
+sesi -h "how do I use memory?"
+```
+
+```bash
+# Ask for help about a specific file
+sesi examples/01_hello.sesi -h "what is this script doing?"
+```
+
+```bash
+# Encrypt or decrypt a script file manually
+sesi -enc my_script.sesi -p "my-password"
+sesi -dec my_script.sesi -p "my-password"
+```
+
+To avoid exposing passwords in your shell's history, you can set the `SESI_PASSWORD` environment variable in your `.env` file (or your system's shell environment).
+
+```bash
+export SESI_PASSWORD="my-password"
+# Encrypt or decrypt automatically using SESI_PASSWORD environment variable
+sesi -enc my_script.sesi
+sesi -dec my_script.sesi
+```
+
+```bash
+# Run with sandbox restrictions disabled
+sesi examples/01_hello.sesi -l
+```
+
 # Local Execution (Development)
 
-If you choose not install `sesi` globally, use the helper npm scripts:
+If you are developing inside the repository or haven't installed `sesi` globally, use the npm scripts:
+
+```bash
+# Run a Sesi script
+npm run sesi -- examples/01_hello.sesi
+```
+
+```bash
+# Evaluate an inline snippet
+npm run sesi:eval -- "print 'Sesi running!'"
+```
+
+```bash
+# Ask Sesi's Co-Pilot
+npm run sesi:help -- "how to make a directory?"
+```
+
+```bash
+# Encrypt / Decrypt scripts (uses SESI_PASSWORD from your .env automatically)
+npm run sesi:encrypt -- "secret.sesi"
+npm run sesi:decrypt -- "secret.sesi"
+```
 
 ```bash
-npm run example 01_hello.sesi
-npm run example:ai 08_model_call.sesi
+# Run classic examples
+npm run example examples/01_hello.sesi
+npm run example:ai examples/08_model_call.sesi
 npm run example:all
 ```
 
@@ -116,13 +180,13 @@ print code
 
 ## Security & Sandboxing
 
-Sesi is designed to run and orchestrate untrusted AI reasoning pipelines. Because code can be influenced by prompt injections or generated model instructions, Sesi incorporates a **safe-by-default, zero-trust sandboxing engine**.
+Sesi incorporates a **safe-by-default, zero-trust sandboxing engine**.
 
 ### 🛡️ Core Security Features
 
 1. **Safe-by-Default Execution**:
    - Sesi's sandbox is **enabled by default**. Any standard Sesi interpreter execution blocks system command lines (`exec`, `spawn`) and locks down imports and paths.
-   - *Overriding Safety:* Developers can explicitly bypass safe mode programmatically by initializing the interpreter with options, or on the command line by setting `SESI_SAFE_MODE=false`.
+   - _Overriding Safety:_ Developers can explicitly bypass safe mode programmatically by initializing the interpreter with options, or on the command line by setting `SESI_SAFE_MODE=false`.
 
 2. **Absolute Prototype Pollution Immunity**:
    - Sesi uses **prototype-free objects (`Object.create(null)`)** for all object literals, JSON parses (`from_json` or `std/json`), and structured model responses inside the interpreter.
@@ -139,12 +203,14 @@ Sesi is designed to run and orchestrate untrusted AI reasoning pipelines. Becaus
    - Sub-interpreters loaded via concurrent workflows (`multi_req`) are fully isolated. Sesi **deep-clones** prompts and memories, preventing concurrent agent tasks from leaking state or polluting each other.
 
 ### ⚙️ Programmatic Embedding Configurations
+
 When embedding Sesi inside a host application, you can statically configure safety settings directly in code:
+
 ```typescript
 const interpreter = new Interpreter(scriptDir, {
-  safeMode: true,        // Enable full sandbox limits (on by default)
-  allowUnsafeFs: false,  // Block directory escapes (on by default)
-  allowedPaths: ['/var/tmp/sandbox'] // Custom strict whitelist directories
+  safeMode: true, // Enable full sandbox limits (on by default)
+  allowLocalFs: false, // Block directory escapes (on by default)
+  allowedPaths: ["/var/tmp/sandbox"], // Custom strict whitelist directories
 });
 ```
 
@@ -152,52 +218,96 @@ const interpreter = new Interpreter(scriptDir, {
 
 - [Getting Started](./QUICKSTART.md)
 - [Examples](./examples/)
+- [CLI Reference](./docs/CLI.md)
 - [Language Specification](./docs/SPECIFICATION.md)
 - [Language Comparison Showcase](./docs/COMPARISON.md)
 - [Built-in Functions](./docs/BUILTINS.md)
-- [Reasoning Guide](./docs/SYSTEMS_REASONING.md)
-- [Distributed Systems](./docs/DISTRIBUTED_SYSTEMS.md)
+- [Reasoning](./docs/REASONING.md)
+- [Concurrency Systems](./docs/CONCURRENCY.md)
 - [Runtime Architecture](./docs/ARCHITECTURE.md)
 
-## AI Agent Context
+## Agent Context
 
-The root-level `SKILLS.md` file is a workspace context file for AI agents. It records repo-specific constraints such as valid Sesi syntax expectations, execution conventions, and the intended meaning of directories like `main/` and `main/tests/`.
+The root-level `SKILLS.md` file is a workspace context file for AI agents.
 
 ## Project Structure
 
 ```
 Sesi/
-├── SKILLS.md             # AI-agent workspace context and repo guardrails
-├── index.html            # Sesi-generated landing page
-├── eslint.config.mjs     # ESLint configuration
-├── dist/                 # Compiled TypeScript output
-├── example.js            # Helper script to run basic examples
-├── example-ai.js         # Helper script to run Reasoning examples
-├── package.json          # Dependencies & scripts
-├── tsconfig.json         # TypeScript configuration
-├── QUICKSTART.md         # Quick start guide
-├── IMPLEMENTATION_SUMMARY.md # Progress and tracking
-├── src/
-│   ├── types.ts          # Type system & AST nodes
-│   ├── lexer.ts          # Tokenization
-│   ├── parser.ts         # AST generation
-│   ├── interpreter.ts    # Execution engine
-│   ├── builtins.ts       # Standard library
-│   ├── ai-runtime.ts     # Gemini integration
-│   └── index.ts          # Main entry point
+├── SKILLS.md                        # Workspace context and repo guardrails
+├── eslint.config.mjs                # ESLint configuration
+├── example.js                       # Helper script to run basic examples
+├── example-ai.js                    # Helper script to run reasoning examples
+├── examples.sesi                    # Central execution suite for examples
+├── README.md                        # Project overview
+├── QUICKSTART.md                    # Getting started guide
+├── package.json                     # Dependencies & scripts
+├── tsconfig.json                    # TypeScript configuration
+├── dist/                            # Compiled TypeScript output
+│
+├── src/                             # Source code
+│   ├── types.ts                     # Type definitions & AST nodes (400+ lines)
+│   ├── lexer.ts                     # Tokenization (350+ lines)
+│   ├── parser.ts                    # Recursive descent parser (700+ lines)
+│   ├── interpreter.ts               # Tree-walking interpreter (600+ lines)
+│   ├── builtins.ts                  # Built-in functions (250+ lines)
+│   ├── ai-runtime.ts                # Integrated reasoning integration (120+ lines)
+│   └── index.ts                     # Entry point (30+ lines)
+│
 ├── bin/
-│   └── sesi.js           # CLI executable
-├── examples/             # 18 sample programs demonstrating all features
-├── main/                 # Main entry and specialized tests
-│   ├── playground.sesi   # Main playground script
-│   ├── start.sesi        # Beginner script
-│   ├── build_website.sesi # Sesi-powered landing page generator
-│   └── tests/            # Debug and syntax scripts
-├── tests/                # Test suite
-└── docs/                 # Documentation (ARCHITECTURE, BUILTINS, SPECIFICATION, etc.)
+│   └── sesi.js                      # CLI executable
+│
+├── main/                            # Playgrounds & debugging
+│   └── tests/                       # Additional syntax validation scripts
+│
+├── docs/
+│   ├── CLI.md                       # Comprehensive CLI & Parametric Eval guide
+│   ├── SPECIFICATION.md             # Complete language spec (600+ lines)
+│   ├── ARCHITECTURE.md              # Runtime & system design (400+ lines)
+│   ├── BUILTINS.md                  # Built-in functions reference (450+ lines)
+│   ├── COMPARISON.md                # Language comparison showcase
+│   ├── IMAGE_GENERATION.md          # Image generation guide (>100 lines)
+│   ├── REASONING.md                 # Reasoning and simple logic guide (>500 lines)
+│   └── ROADMAP.md                   # V2-V4+ development plan (400+ lines)
+│
+│
+├── examples/
+│   ├── 01_hello.sesi                # Hello World
+│   ├── 02_variables.sesi            # Variables & operations
+│   ├── 03_functions.sesi            # Functions with parameters
+│   ├── 04_conditionals.sesi         # If/else control flow
+│   ├── 05_loops.sesi                # While, for, for-in loops
+│   ├── 06_arrays_objects.sesi       # Collections
+│   ├── 07_prompts.sesi              # Reasoning blocks
+│   ├── 08_model_call.sesi           # Basic reasoning calls
+│   ├── 09_structured_output.sesi    # Type-safe reasoning responses
+│   ├── 10_code_generation.sesi      # Systems logic generation
+│   ├── 11_memory_conversation.sesi  # Multi-turn stateful reasoning
+│   ├── 12_classification.sesi       # Systems classification loop
+│   ├── 13_data_pipeline.sesi        # Complete systems pipeline
+│   ├── 14_folder_explainer.sesi     # Directory parsing & reasoning
+│   ├── 15_image_generation.sesi     # Image generation API test
+│   ├── 16_modules.sesi              # Modules & std library namespaces
+│   ├── 17_http_client.sesi          # Network GET/POST client
+│   ├── 18_parallel_requests.sesi    # Parallel requests concurrency
+│   ├── 19_search_web.sesi           # Web search integration
+│   ├── 20_model_aliases.sesi        # Custom model naming aliases
+│   ├── 21_custom_tools.sesi         # Custom runtime tool definitions
+│   └── 22_reasoning_plus_custom_tools.sesi # Reasoning composed with custom tools
+│
+└── tests/                           # Engine test suite
+    ├── basic.test.ts                # Core parsing & evaluation tests
+    ├── cache.test.ts                # Execution caching tests
+    ├── http.test.ts                 # Web request builtins testing
+    ├── module.test.ts               # Imports & module loading tests
+    ├── parallel.test.ts             # Concurrent execution tests
+    ├── security.test.ts             # Sandbox & guardrail tests
+    ├── test-gemini.ts               # Base model integration test
+    ├── test-gemini2.ts              # Extended model integration test
+    └── workflow.test.ts             # Complex sequence workflows tests
 ```
 
-## Version 1.2 Features (In Progress)
+## Version 1.3 Features (In Progress)
 
 ### Core Language ✅
 
@@ -214,19 +324,21 @@ Sesi/
 
 ### Reasoning-Native Features ✅
 
-- `prompt` blocks for message composition
 - `model()` calls with Reasoning provider configuration
 - `image()` calls with specific ratio/size generation capabilities
-- `structured_output()` for typed Reasoning responses
-- `tool_call()` for function calling
-- Basic memory for multi-turn reasoning
-- `read_file()`, `write_file()`, `to_json()`, `write_image()`, and `list_dir()` for local file I/O
+- **Async Polling**: Native looping to auto-resume generation when hitting `MAX_TOKENS` limit
+
+### System Features ✅
+
+- **Memory**: Basic memory for multi-turn reasoning
+- **Filesystem I/O**: `read_file()`, `write_file()`, `to_json()`, `write_image()`, and `list_dir()` for local file I/O
 - **Native Concurrency**: `spawn()` and `exec()` for concurrent process management, and `multi_req(array<function>)` for physical parallel request execution.
 - **Logic Caching**: High-efficiency Sesi Logic Caching (`.sesi_cache.json`) for local call caching.
-- **Thinking Scale**: Scaled Gemini reasoning configurations using the `thinking` parameters.
 - **HTTP Client**: Built-in, native HTTP client support using `web_get(url)` and `web_send(url, body, headers)` with zero external dependencies.
-- **Async Polling**: Native looping to auto-resume generation when hitting `MAX_TOKENS` limit
 - **Utility Builtins**: `time()` and `random()` for robust coordination
+- **Structured Output**: `structured_output()` for typed JSON Schema
+- **Function Calling**: `tool_call()` for function calling
+- **Prompt Blocks**: `prompt` blocks for cleaner and more concise script composition
 
 ### Type System