@misterscan/sesi 1.2.3 → 1.3.0

package/docs/README.md

@@ -2,7 +2,7 @@
   <img src="favicon.ico" alt="Sesi Logo" height="100" />
 </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>
@@ -15,7 +15,13 @@
   <img alt="Framework" src="https://img.shields.io/badge/Node.js-Engine-success?logo=node.js">
 </p>
 
-**Sesi** is a high-performance **Systems Language** 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.
+<p align="center">
+  <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. Because the language itself is so simple, integrating external tools like shell commands or Reasoning models becomes effortless. It is a language built for clarity.
+</p>
+
+<p align="center">
+  <a href="https://code-with-sesi.netlify.app/">Homepage</a>
+</p>
 
 ## Quick Start
 
@@ -32,6 +38,26 @@ sesi examples/08_model_call.sesi
 sesi examples.sesi
 ```
 
+Useful CLI shortcuts:
+
+```bash
+# Evaluate a quick snippet
+sesi -e "print 'hello'"
+
+# Ask the built-in co-pilot a question
+sesi -help "how do I use memory?"
+
+# Ask for help about a specific file
+sesi main/playground.sesi -h "why is this failing"
+
+# Encrypt or decrypt a script file
+sesi -encrypt my_script.sesi -p "my-password"
+sesi -decrypt my_script.sesi -p "my-password"
+
+# Run with sandbox restrictions disabled
+sesi main/start.sesi --local
+```
+
 # Local Execution (Development)
 
 If you choose not use the `sesi` command, use the helper npm scripts:
@@ -67,6 +93,40 @@ let code = model("gemini-3.1-pro-preview") {generateCode}
 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**.
+
+### 🛡️ 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`.
+
+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.
+   - Because these objects do not inherit from standard JavaScript prototypes and possess no `__proto__` or prototype chain, **prototype pollution is physically and architecturally impossible**.
+
+3. **Strict Path Whitelisting**:
+   - Sesi validates all filesystem and subprocess paths against a **strict directory whitelist** (by default, only the Current Working Directory and the Script's base directory are allowed).
+   - Any path traversal resolving outside the whitelist is instantly rejected with a `Security Violation` exception.
+
+4. **Automated LLM Tool Call Sanitization**:
+   - Even if safe mode is explicitly turned off for developer automation, Sesi **strictly blocks automated tool execution** of sensitive commands (like `exec` and `spawn`) when requested dynamically by the model via `tool_call`. This completely isolates the host from prompt-injection RCE.
+
+5. **Deep isolation & Map Cloning**:
+   - 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)
+  allowLocalFs: false,  // Block directory escapes (on by default)
+  allowedPaths: ['/var/tmp/sandbox'] // Custom strict whitelist directories
+});
+```
+
 ## Documentation
 
 - [Getting Started](https://github.com/Misterscan/Sesi/blob/main/QUICKSTART.md)
@@ -74,11 +134,11 @@ print code
 - [Language Specification](https://github.com/Misterscan/Sesi/blob/main/docs/SPECIFICATION.md)
 - [Language Comparison Showcase](https://github.com/Misterscan/Sesi/blob/main/docs/COMPARISON.md)
 - [Built-in Functions](https://github.com/Misterscan/Sesi/blob/main/docs/BUILTINS.md)
-- [Reasoning Guide](https://github.com/Misterscan/Sesi/blob/main/docs/SYSTEMS_REASONING.md)
-- [Distributed Systems](https://github.com/Misterscan/Sesi/blob/main/docs/DISTRIBUTED_SYSTEMS.md)
+- [Reasoning Guide](https://github.com/Misterscan/Sesi/blob/main/docs/REASONING.md)
+- [Concurrency Systems](https://github.com/Misterscan/Sesi/blob/main/docs/CONCURRENCY.md)
 - [Runtime Architecture](https://github.com/Misterscan/Sesi/blob/main/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/`.
 
@@ -86,37 +146,83 @@ The root-level `SKILLS.md` file is a workspace context file for AI agents. It re
 
 ```
 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
+├── index.html                       # Sesi-generated systems landing page
+├── 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
+│   ├── playground.sesi              # Main playground script
+│   ├── start.sesi                   # Beginner script
+│   └── tests/                       # Additional syntax validation scripts
+│
+├── docs/
+│   ├── 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
+│   ├── CONCURRENCY.md               # Concurrency & coordination guide (>100 lines)
+│   ├── 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)
+│   └── sesi_ai_chronicles.md        # AI project history & notes
+│
+├── 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 ✅
 
@@ -170,4 +276,4 @@ Sesi/
 
 ## License
 
-MIT
+MIT

package/docs/{SYSTEMS_REASONING.md → REASONING.md}

@@ -1,69 +1,12 @@
-# Systems Reasoning & Logic Guide
+# Reasoning & Simple Logic
 
 ## Overview
 
-Sesi is a **Systems Language** that treats reasoning as a first-class execution primitive. In this paradigm, AI is used to evaluate state, make logical decisions, and handle complex patterns within a systems-level architecture.
+In Sesi, Reasoning is used to evaluate state, make logical decisions, and handle complex patterns. This guide covers how to leverage Sesi's built-in Reasoning functions (`model`, `image` `prompt`, `structured_output`, `tool_call`) to build scripts for your designated needs.
 
-This guide covers how to leverage Sesi's systems-level constructs (`spawn`, `exec`, `try/catch`) alongside its reasoning primitives (`model`, `prompt`, `structured_output`) to build resilient, stateful applications.
+## 1. Prompting
 
-## 1. Concurrency & Systems Coordination
-
-The core of Sesi's power lies in its ability to manage distributed execution. Using the `spawn()` builtin, you can launch multiple concurrent Sesi processes that coordinate via shared state or the filesystem.
-
-A master script can launch concurrent processes and poll for their completion.
-
-```sesi
-spawn("atm_deposit.sesi")
-spawn("atm_withdraw.sesi")
-let finished = false
-while !finished {
-  try {
-    if read_file("bank/done_count.txt") == "2" {
-      finished = true
-    }
-  } catch (e) {
-    // Wait on I/O contention
-    let i = 0 while i < 1000 { i = i + 1 }
-  }
-}
-print "Swarm task completed."
-```
-
-### Coordination & Distributed Locking
-
-When multiple processes access shared resources, use Sesi's `try/catch`, `time()`, and `random()` builtins to implement mutual exclusion (locking) via the **Double-Check Write** pattern.
-
-```sesi
-let id = "With_" + str(time()) + "_" + str(random())
-let locked = true
-while locked {
-  let status = "error"
-  try {
-    status = read_file("bank/lock.txt")
-  } catch (e) {
-    status = "error"
-  }
-  if status == "unlocked" {
-    try {
-      write_file("bank/lock.txt", id)
-      let i = 0 while i < 500 { i = i + 1 }
-      if read_file("bank/lock.txt") == id {
-        locked = false
-      }
-    } catch (e) {
-      status = "error"
-    }
-  } else {
-    let j = 0 while j < 1000 { j = j + 1 }
-  }
-}
-```
-
----
-
-## 2. AI as a Reasoning Primitive
-
-In an orchestrated system, AI is used to make decisions that would be too complex for static logic.
+In Sesi, calling a reasoning model is as simple as defining a string and executing it.
 
 Prompts are **composable message templates** that evaluate to strings.
 
@@ -102,7 +45,7 @@ print translatePrompt(text, language)
 
 ## 2. Model Calls
 
-Call Gemini with a prompt and get back text.
+Call a Reasoning model with a prompt and get back text.
 
 ### Basic Model Call
 
@@ -127,8 +70,8 @@ print creative
 
 ```sesi
 // Fast model for simple tasks
-let text = " Coding with Reasoning systems language is fun!"
-let quick = model("gemini-3.1-flash-lite") {"Summarize this in one sentence:" text}
+let text = "Coding with Reasoning programming language is fun!"
+let quick = model("gemini-3.1-flash-lite") {"Summarize this in one sentence: " text}
 
 // Powerful model for complex reasoning
 let code = "def calculate_sum(n):
@@ -136,25 +79,25 @@ let code = "def calculate_sum(n):
     for i in range(1, n):
         total += i
     return total"
-let smart = model("gemini-3.1-pro-preview") {"Analyze this code for bugs:" code}
+let smart = model("gemini-3.1-pro-preview") {"Analyze this code for bugs: " code}
 
 // Efficient model for many calls
-let item = " Programming Languages"
-let cheap = model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify:" item}
+let item = "Programming Languages"
+let cheap = model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify: " item}
 
 print quick
 print smart
 print cheap
 ```
 
-### Available Models (v1.2)
+### Available Models (v1.3)
 
 - `gemini-2.5-flash` - Legacy, but supported. 1M tokens.
 - `gemini-2.5-pro` - Legacy, but supported. 1M tokens.
 - `gemini-2.5-flash-image` - Standard image model. (No `512` image size support for this model. Only `1K` is supported.)
-- `gemini-3-flash-preview` - Fast, balanced, legacy preview.
+- `gemini-3-flash-preview` - Fast, most balanced model for coding and minimal tasks.
 - `gemini-3.1-flash-lite` - Fastest, most cost-efficient.
-- `gemini-3.5-flash` - Standard GA Model. Fast, balanced, supports all native thinking effort levels (`minimal`, `low`, `medium`, `high`).
+- `gemini-3.5-flash` - Newest GA model. Balanced, but token hungry (USE WISELY) supports all native thinking effort levels (`minimal`, `low`, `medium`, `high`).
 - `gemini-3.1-pro-preview` - Most powerful reasoning model, doesn't support `minimal` thinking (falls back to `low`).
 - `gemini-3.1-flash-image-preview` - Cost efficient image generation model.
 - `gemini-3-pro-image-preview` - High quality image generation model. (No `512` image size support for this model.)
@@ -196,8 +139,7 @@ Get typed responses from Reasoning with field validation.
 ### Basic Structured Output
 
 ```sesi
-let analysis = structured_output({sentiment: string, confidence: number, summary: string})
-(model("gemini-3-flash-preview") {"Analyze sentiment of: " text "Return JSON with sentiment, confidence (0-1), and summary"})
+let analysis = structured_output({sentiment: string, confidence: number, summary: string})(model("gemini-3-flash-preview") {"Analyze sentiment of: " text "Return JSON with sentiment, confidence (0-1), and summary"})
 print analysis["sentiment"]    // "positive"
 print analysis["confidence"]   // 0.85
 print analysis["summary"]      // "..."
@@ -216,12 +158,12 @@ print bookInfo["title"]
 
 - Always include instructions for JSON format
 - Specify the exact schema in the prompt
-- Use "thinkingLevel": "low" for fast, consistent parsing
+- Use "thinkingLevel": "minimal" for fast, consistent parsing
 - Validate output structure in code
 
 ```sesi
 let listText = "eggs, milk, bread, cheese, fruit, vegetables"
-let output = structured_output({items: string})(model("gemini-3.5-flash") {thinkingLevel: "minimal"}{"Return JSON with items array containing: " listText})
+let output = structured_output({items: string})(model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Return JSON with items array containing: " listText})
 
 // Validate
 if type(output["items"]) == "array" {print "Got" str(len(output["items"])) "items"} // Got 6 items
@@ -236,7 +178,8 @@ Let Reasoning call functions in your program.
 ```sesi
 let city = "New York"
 fn getWeather(city: string) -> string
-{let weather = model("gemini-3.1-flash-lite"){"What is the weather like in " city} return weather}
+{let weather = model("gemini-3.1-flash-lite") {"What is the weather like in " city} 
+return weather}
 let result = getWeather(city)
 print result
 
@@ -289,11 +232,11 @@ print response2  // Has context from turn 1
 ```sesi
 memory conversation {"Chat history: "}
 fn chat(userMessage: string) -> string
-{let fullPrompt = conversation + "User:" + userMessage
+{let fullPrompt = conversation + "User: " + userMessage
 let response = model("gemini-3-flash-preview") {fullPrompt}
 
 // Append to memory
-conversation = conversation + "User:" + userMessage + "Assistant:" + response
+conversation = conversation + "User: " + userMessage + "Assistant: " + response
 return response}
 let msg = "What is the capital of France? "
 print "User:" msg
@@ -313,7 +256,7 @@ print "Updated Memory!"
 memory conversation {"User: Hello! Assistant: Hi there! User: How are you? Assistant: I'm great!"}
 fn summarizeMemory()
 {let oldConversation = conversation
-let summary = model("gemini-3.1-flash-lite") {"Summarize this conversation concisely:" oldConversation}
+let summary = model("gemini-3.1-flash-lite") {"Summarize this conversation concisely: " oldConversation}
 conversation = "Previous summary:" + summary + "Recent messages: " + oldConversation}
 print "Original Memory:" conversation
 summarizeMemory()
@@ -329,8 +272,7 @@ print conversation
 let categories = "fruit, vegetable, grain"
 let item = "banana"
 fn classify(item: string, categories: string) -> string
-{return model("gemini-3.5-flash") {thinkingLevel: "minimal"}
-{"Classify this item into one category. Categories: " categories " Item: " item " Return only the category name."}}
+{return model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify this item into one category. Categories: " categories " Item: " item " Return only the category name."}}
 print "Item: " item //banana
 print "Category: " classify(item, categories) //fruit
 ```
@@ -340,8 +282,7 @@ print "Category: " classify(item, categories) //fruit
 ```sesi
 let text = "Elon Musk is the CEO of Tesla and SpaceX."
 fn extractEntities(text: string) -> object
-{let result = structured_output({people: string, places: string, organizations: string})
-(model("gemini-3.5-flash") {thinkingLevel: "minimal"}{"Extract named entities from:" text})
+{let result = structured_output({people: string, places: string, organizations: string})(model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Extract named entities from: " text})
 print "Name(s) found: result"
 return result}
 print extractEntities(text)
@@ -354,9 +295,8 @@ print extractEntities(text)
 let text = "Hello, world!"
 let language = "Spanish"
 fn translate(text: string, language: string) -> string
-{return model("gemini-3-flash-preview") {"Translate to" language ":" text}}
-print "Translation:"
-print translate(text, language)
+{return model("gemini-3-flash-preview") {"Translate to " language ": " text}}
+print "Translation:" translate(text, language)
 ```
 
 ### Web Search Grounding
@@ -364,7 +304,8 @@ print translate(text, language)
 Access real-time information by enabling the `search` shorthand configuration natively.
 
 ```sesi
-let response = model("gemini-3.1-flash-lite") {search, max_tokens: 1000} {"What is the weather in Tokyo right now?"}
+let response = model("gemini-3.1-flash-lite") {search, max_tokens: 200} {"What is the weather in Tokyo right now?"}
+print response
 ```
 
 ### Image Generation
@@ -384,7 +325,7 @@ print "Image generated!"
 ```sesi
 let requirement = "Write a function that reverses a string."
 fn generateCode(requirement: string) -> string
-{return model("gemini-3.5-flash") {thinkingLevel: "low"} {"Generate JavaScript code for:" requirement "Only provide code, no explanation."}}
+{return model("gemini-3.5-flash") {thinkingLevel: "low"} {"Generate JavaScript code for: " requirement " Only provide code, no explanation."}}
 print "Code generation:"
 print generateCode(requirement)
 ```
@@ -394,8 +335,7 @@ print generateCode(requirement)
 ```sesi
 let text = "I love Sesi!"
 fn analyzeSentiment(text: string) -> object
-{return structured_output({sentiment: string, score: number, explanation: string})
-(model("gemini-3-flash-preview") {"Analyze sentiment of:" text})}
+{return structured_output({sentiment: string, score: number, explanation: string})(model("gemini-3-flash-preview") {"Analyze sentiment of: " text})}
 print "Sentiment analysis:"
 print analyzeSentiment(text)
 ```
@@ -404,11 +344,11 @@ print analyzeSentiment(text)
 
 Reasoning operations can fail. Handle gracefully.
 
-### Try/Catch (v1.2)
+### Try/Catch (v1.3)
 
 ```sesi
 try
-{let response = model("gemini-3-flash-preview") {"Analyze" text}
+{let response = model("gemini-3-flash-preview") {"Analyze " text}
 print response}
 catch (e) {print "Reasoning call failed"
 print e}
@@ -426,14 +366,13 @@ print e}
 let text = "Coding is evolving rapidly!"
 fn safeAnalyze(text: string) {
 try
-{let result = structured_output({sentiment: string, score: number})(model("gemini-3.1-flash-lite") {"Analyze sentiment and return JSON for:" text})
+{let result = structured_output({sentiment: string, score: number})(model("gemini-3.1-flash-lite") {"Analyze sentiment, score, and return JSON for: " text})
 if len(keys(result)) == 0 {print "Structured parsing failed"
 return null}
-return result}
-catch (e)
-{print e
+return result
+} catch (e) {print e
 return null}}
-print "Analysis Result: " safeAnalyze(text)
+print "Analysis Result:" safeAnalyze(text)
 ```
 
 ## 8. Performance Tips
@@ -443,11 +382,11 @@ print "Analysis Result: " safeAnalyze(text)
 ```sesi
 // Bad: Calls API 3 times
 for item in items
-{let analysis = model("gemini-3.1-flash-lite") {"Analyze:" item}}
+{let analysis = model("gemini-3.1-flash-lite") {"Analyze: " item}}
 print analysis
 
 // Better: Batch into one call (v2: parallel calls)
-let analyses = model("gemini-3.1-flash-lite") {"Analyze each:" join(items, " ")}
+let analyses = model("gemini-3.1-flash-lite") {"Analyze each: " join(items, " ")}
 print analyses
 ```
 
@@ -455,11 +394,11 @@ print analyses
 
 ```sesi
 // Simple classification → flash-lite
-let category = model("gemini-3.1-flash-lite") {"Classify:" item}
+let category = model("gemini-3.1-flash-lite") {"Classify: " item}
 print category
 
 // Complex reasoning → pro
-let analysis = model("gemini-3.1-pro-preview") {"Deep analysis of:" complex_problem}
+let analysis = model("gemini-3.1-pro-preview") {"Deep analysis of: " complex_problem}
 print analysis
 ```
 
@@ -468,7 +407,7 @@ print analysis
 ```sesi
 // Long prompts waste tokens
 // Bad:
-let response = model("gemini-3-flash-preview") {"Here is a very long system prompt that repeats itself... " "Please analyze the following text very carefully..." text}
+let response = model("gemini-3-flash-preview") {"Here is a very long system prompt that repeats itself... Please analyze the following text very carefully..." text}
 print response
 
 // Better:
@@ -480,14 +419,17 @@ print response
 
 ```sesi
 // Bad: Same analysis done multiple times
-for person in people {let assessment = model("gemini-3.1-flash-lite") {"Assess based on criteria A, B, C: "  person}}
+for person in people 
+{let assessment = model("gemini-3.1-flash-lite") {"Assess based on criteria A, B, C: "  person}}
 print assessment
 
 
 // Better: Reuse cached prompt
 let people = ["Elon Musk", "Bill Gates", "Steve Jobs"]
-fn assessPerson(person: string) -> string {return model("gemini-3.1-flash-lite") {"Assess on A, B, C: "  person}}
-for person in people {print assessPerson(person)}
+fn assessPerson(person: string) -> string
+{return model("gemini-3.1-flash-lite") {"Assess on A, B, C: "  person}}
+for person in people 
+{print assessPerson(person)}
 ```
 
 ## 9. Token Counting (Future)
@@ -502,7 +444,7 @@ print "This costs " str(tokens * PRICE_PER_TOKEN) " cents"
 // Plan memory size
 let remaining = MAX_TOKENS - count_tokens(memory, model)
 if remaining < 500 {summarizeMemory()}
-print "Memory size: " count_tokens(memory, model)
+print "Memory size:" count_tokens(memory, model)
 ```
 
 ## 10. Advanced: Custom Reasoning Workflows
@@ -515,20 +457,21 @@ fn smartSummarize(text: string) -> string
 
 // Chain multiple Reasoning operations
 // Step 1: Extract key points
-{let keyPoints = model("gemini-3.1-pro-preview") {thinkingLevel: "low"} {"Extract 5 key points from:" text}
+{let keyPoints = model("gemini-3.1-pro-preview") {thinkingLevel: "low"} {"Extract 5 key points from: " text}
 
 // Step 2: Analyze topics
-let topics = structured_output({ topics: string })(model("gemini-3.5-flash") {thinkingLevel: "low"} {"Identify topics in:" keyPoints})
+let topics = structured_output({topics: string})(model("gemini-3.5-flash") {thinkingLevel: "low"} {"Identify topics in: " keyPoints})
 
 // Step 3: Generate summary
-let summary = model("gemini-3-flash-preview") {"Summarize with topics " topics ":" keyPoints} return summary}
+let summary = model("gemini-3-flash-preview") {"Summarize with topics " topics ": " keyPoints} 
+return summary}
 print "Summary:" smartSummarize(text)
 ```
 
 ### Reasoning Pattern
 
 ```sesi
-let analysis = model("gemini-3.5-flash") {thinkingLevel: "medium", max_tokens: 8192} {"Reason carefully about:" problem}
+let analysis = model("gemini-3.5-flash") {thinkingLevel: "medium", max_tokens: 8192} {"Reason carefully about: " problem}
 print analysis
 ```
 
@@ -537,12 +480,59 @@ print analysis
 ```sesi
 let text = "banana"
 fn classifyWithExamples(text: string) -> string
-{return model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify as A, B, or C" "Examples:" "'apple' -> A" "'dog' -> B" "'happy' -> C" "Classify: " text}}
+{return model("gemini-3.5-flash") {thinkingLevel: "minimal"} {"Classify as A, B, or C. Examples: 'apple' -> A , 'dog' -> B , 'happy' -> C. Classify: " text}}
 print "Classification:" classifyWithExamples(text)
 ```
 
 ---
 
+## 11. Built-in Tools
+
+### Built-in Workflows
+
+Sesi provides a native `workflow` function to easily chain reasoning steps:
+
+```sesi
+let steps = [
+  {"prompt": "Summarize:"},
+  {"prompt": "Critique:"},
+  {"prompt": "Finalize:"}
+]
+let result = workflow(steps, "Design a landing page brief")
+print result["final"]
+```
+
+### Model Aliases
+
+You can define custom names for models using `set_alias`:
+
+```sesi
+set_alias("fast", "gemini-3.1-flash-lite")
+let answer = model("fast") {"Summarize this paragraph."}
+print answer
+```
+
+### Custom Tools
+
+Sesi allows you to define custom tools that can be invoked during reasoning operations.
+
+```sesi
+fn get_weather(city: string, conditions: string) -> string 
+{return "It is currently " + conditions + " in " + city}
+// Register the tool
+define_tool("weather", get_weather, "Get weather for a city")
+
+// List available tools
+print list_tools()
+
+// Call the tool
+let weatherData = structured_output({city: string, conditions: string})(model("gemini-3.1-flash-lite") {search} {"What is the weather like in London? Return JSON with the exact 'conditions' and 'city' name."})
+let result = tool_call(weather)(weatherData["city"], weatherData["conditions"])
+print result
+```
+
+---
+
 ## See Also
 
 - [Compare to other languages](COMPARISON.md)