@misterscan/sesi 1.2.2 → 1.3.0

package/docs/COMPARISON.md

@@ -1,16 +1,14 @@
-# The Sesi Advantage: Why We Built a Systems & Orchestration Language
+# The Sesi Advantage: Removing Boilerplate
 
-Integrating Large Language Models (LLMs) into traditional applications today is painful. Standard programming languages treat AI as an external service requiring SDKs, manual prompt string concatenation, complex schema definitions, and fragile JSON parsing.
+Integrating API calls or reasoning blocks into traditional applications today is painful. Standard programming languages treat API calls or reasoning blocks as an external service requiring SDKs, manual prompt string concatenation, complex schema definitions, and fragile JSON parsing.
 
-**Sesi treats Reasoning as a first-class language primitive.**
-
-This document demonstrates exactly how much boilerplate and complexity Sesi eliminates compared to traditional languages like TypeScript, Python, and Go.
+This document demonstrates how much boilerplate Sesi eliminates.
 
 ---
 
 ## 📊 The Cost of Boilerplate: A Data Comparison
 
-When building a simple AI-powered data pipeline (structured data extraction + conditional function calling), traditional languages spend more than half their code managing the SDK rather than executing business logic.
+When building simple API extraction pipelines, traditional languages spend more than half their code managing SDKs.
 
 ```mermaid
 xychart-beta
@@ -248,7 +246,7 @@ In Go, statically typed strictness combined with AI responses creates massive st
 
 ---
 
-## Showcase 3: Distributed Orchestration Swarm
+## Showcase 3: Distributed Orchestration Processes
 
 This example demonstrates a complex distributed task: Spawning a background researcher, polling for completion with fault tolerance, and synthesizing results with AI.
 
@@ -330,5 +328,5 @@ Sesi isn't just syntactic sugar. By embedding the AI runtime directly into the p
 - [Image Generation](IMAGE_GENERATION.md)
 - [Built-in Functions](BUILTINS.md)
 - [Architecture](ARCHITECTURE.md)
-- [Reasoning Features](SYSTEMS_REASONING.md)
-- [Distributed Systems](DISTRIBUTED_SYSTEMS.md)
+- [Reasoning Features](REASONING.md)
+- [Concurrent Processes](CONCURRENCY.md)

package/docs/{DISTRIBUTED_SYSTEMS.md → CONCURRENCY.md}

@@ -1,22 +1,22 @@
-# Distributed Systems with Sesi
+# Concurrency with Sesi
 
-Sesi is a robust systems-level environment capable of orchestrating complex, multi-process agent swarms. This document details how Sesi handles concurrency, race conditions, and distributed state.
+This document details how Sesi handles process concurrency and file locks.
 
-## The "Bank Swarm" Case Study
+## The "Bank" Case Study
 
-In this experiment, Sesi was used to solve a classic distributed systems problem: **Concurrent Mutual Exclusion.**
+In this experiment, Sesi was used to solve file contention.
 
 ### The Challenge
 
-Five independent Sesi agents (3 Deposits, 2 Withdrawals) were launched simultaneously. All agents needed to update a single `balance.txt` file without causing data loss through race conditions.
+Five independent Sesi instances (3 Deposits, 2 Withdrawals) were launched simultaneously. All instances needed to update a single `balance.txt` file without causing data loss through race conditions.
 
-### The Sesi Solution (The "Double-Check Write" Pattern)
+### The Solution (Mutex / File Locking)
 
-Sesi solves this using a high-level implementation of a filesystem lock. Even without low-level semaphores, Sesi's `try/catch` and file I/O builtins allow for an "indestructible" locking logic.
+Sesi solves this using file locking via `try/catch` and file I/O builtins.
 
 #### 1. Unique Identity
 
-Each agent generates a globally unique ID using Sesi's native `time()` and `random()` builtins.
+Each instance generates a unique ID using Sesi's native `time()` and `random()` builtins.
 
 ```sesi
 let id = "Agent_" + str(time()) + "_" + str(random())
@@ -40,7 +40,7 @@ while locked {
 
 #### 3. Critical Section Resilience
 
-Using `try/catch`, Sesi agents gracefully handle filesystem contention (when the OS prevents two processes from reading the same file at the exact same micro-second).
+Using `try/catch`, Sesi scripts gracefully handle filesystem contention.
 
 ```sesi
 try {
@@ -53,10 +53,10 @@ try {
 
 ## Concurrency via `spawn()`
 
-Sesi v1.1 introduced the `spawn()` builtin, allowing a single **Master Orchestrator** to launch an entire swarm of agents from one file.
+Sesi v1.1 introduced the `spawn()` builtin, allowing a single **Master Orchestrator** to launch concurrent proccesses of sesi scripts from one main file.
 
 ```sesi
-// Master: Launching 5-Agent Swarm
+// Master: Launching 5 Concurrent Processes...
 spawn("main/atm_deposit.sesi")
 spawn("main/atm_withdraw.sesi")
 spawn("main/atm_deposit.sesi")

package/docs/IMAGE_GENERATION.md

@@ -1,17 +1,17 @@
 # Image Generation in Sesi
 
-Sesi provides a native, language-level primitive for generating images using AI models. This primitive is designed to interoperate seamlessly with Sesi's file system builtins, allowing you to generate and persist images with minimal boilerplate.
+Sesi provides a native, language-level primitive for image generation and manipulation, including image-to-image tasks like style transfer, upscaling, and editing. This primitive is designed to interoperate seamlessly with Sesi's file system builtins, allowing you to generate and persist images with minimal boilerplate.
 
 ## The `image` Primitive
 
-To generate an image, use the `image` keyword followed by the model name, an optional configuration block, and a prompt block.
+To generate or manipulate an image, use the `image` keyword followed by the model name, an optional configuration block, and a prompt block.
 
 ### Syntax
 
 The syntax parallels standard `model` calls:
 
 ```
-image("model-name") {"configKey": "configValue"} {"Prompt text"}
+image("model-name") {configKey: "configValue"} {"Prompt text"}
 ```
 
 ### Basic Example
@@ -23,7 +23,7 @@ Here is a simple example demonstrating how to generate a single image and save i
 prompt request {"A simple minimalist company logo for a bakery"}
 
 // 2. Call the image generation primitive
-let imageData = image("gemini-3.1-flash-image-preview") {"ratio": "1:1", "size": "1K"} {request}
+let imageData = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "1K"} {request}
 
 // 3. Write the payload to disk
 try 
@@ -52,7 +52,7 @@ for product in products
 prompt request {"A clean studio presentation photograph of a " product " on a solid white background."}
 prompt filename { outputDir product ".png" }
 try 
-{let imageData = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": "1K"} {request}
+{let imageData = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "1K"} {request}
 
 // Attempt local file write
 let success = write_image(filename, imageData)
@@ -69,9 +69,9 @@ print "Asset generation complete."
 
 When configuring the `image` call (specifically for models like `gemini-3.1-flash-image-preview`), the configuration block maps directly to backend SDK capabilities:
 
-- `"ratio"`: The aspect ratio of the image (e.g., `"1:1"`, `"16:9"`, `"9:16"`).
-- `"size"`: Dimensional sizing constraints (Must be `"512"`, `"1K"`, `"2K"`, or `"4K"`).
-- `"temperature"`: *Will be deprecated in Gemini 3.x+, use thinkingLevel instead.* — controls variance.
+- `ratio`: The aspect ratio of the image (e.g., `"1:1"`, `"16:9"`, `"9:16"`).
+- `size`: Dimensional sizing constraints (Must be `"512"`, `"1K"`, `"2K"`, or `"4K"`).
+- `temperature`: *Will be deprecated in Gemini 3.x+, use thinkingLevel instead.* — controls variance.
 
 ## File I/O Integration: `write_image`
 
@@ -139,11 +139,10 @@ print "Render saved."
 let dir = "frames/"
 let files = list_dir(dir)
 
-for f in files {
-  prompt p {dir f}
-  let desc = model("gemini-3.1-flash-lite") {images: p} {"Describe this frame in one sentence."}
-  print f desc
-}
+for f in files 
+{prompt p {dir f}
+let desc = model("gemini-3.1-flash-lite") {images: p} {"Describe this frame in one sentence."}
+print f desc}
 ```
 
 ### Config Reference
@@ -154,4 +153,4 @@ When used inside `model()` or `image()` config blocks, `images` is resolved at r
 |-----|---------------|-------|
 | `images` | `string` or `array<string>` | One or more local file paths. Resolved relative to `process.cwd()`. |
 
-> **Note:** Multimodal input requires a vision-capable model (e.g. `gemini-3-flash-preview`, `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview`). Image-generation models that accept reference images are listed in their respective model documentation.
+> **Note:** Multimodal input requires a vision-capable model (e.g. `gemini-3-flash-preview`, `gemini-3.1-flash-lite`, `gemini-3.1-pro-preview`, `gemini-3.5-flash`). Image-generation models that accept reference images are listed in their respective model documentation.

package/docs/IMPLEMENTATION_SUMMARY.md

@@ -2,7 +2,7 @@
 
 ## 📋 Overview
 
-**Sesi** is a high-performance **Systems Language** designed for building resilient, stateful applications. It provides first-class primitives for process management and filesystem orchestration, while integrating reasoning as a first-class execution primitive. Unlike traditional languages that rely on external SDKs for AI interaction, Sesi treats reasoning as a native language construct, enabling developers to build context-aware systems with minimal boilerplate.
+**Sesi** is a highly legible, buildable **programming language**. It provides clean primitives for executing robust internal logic and external APIs, acting as the ideal layer to parse text, orchestrate shell commands, and interact with the file system. Unlike traditional languages that require sprawling SDKs for even basic interactions, Sesi integrates command execution naturally, enabling developers to build context-aware scripts with minimal boilerplate.
 
 ## 🎯 Design Philosophy
 
@@ -10,9 +10,9 @@ Sesi follows these core principles:
 
 1. **Reasoning as a Primitive**: Reasoning calls aren't library functions—they're language constructs with dedicated syntax. This allows for deep integration with the interpreter's environment and type system.
 2. **Practical Over Perfect**: Focus on what developers actually need, not theoretical completeness.
-3. **Transparency Over Magic**: Explicit reasoning calls with clear costs and latency.
-4. **Simplicity First**: Tree-walking interpreter for clarity and maintainability.
-5. **Type Safety with Flexibility**: Static types for normal code, runtime checking for reasoning outputs.
+3. **Transparency Over Magic**: Sesi runs exactly what you write with clear costs and execution maps.
+4. **Simplicity First**: A custom tree-walking interpreter for clarity and maintainability.
+5. **Type Safety with Flexibility**: Static types for normal code, runtime checking for integration outputs.
 
 ## 📁 Complete Project Structure
 
@@ -21,63 +21,78 @@ Sesi/
 ├── 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
-├── README.md                         # Project overview
-├── QUICKSTART.md                     # Getting started guide
-├── package.json                      # Dependencies & scripts
-├── tsconfig.json                     # TypeScript configuration
-├── dist/                             # Compiled TypeScript output
+├── 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)
+├── 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
+│   └── sesi.js                      # CLI executable
 │
-├── main/                             # Playgrounds & debugging
-│   ├── playground.sesi               # Main playground script
-│   ├── start.sesi                    # Beginner script
-│   ├── build_website.sesi            # Sesi-powered systems site generator
-│   └── tests/                        # Additional syntax validation scripts
+├── main/                            # Playgrounds & debugging
+│   ├── playground.sesi              # Main playground script
+│   ├── start.sesi                   # Beginner script
+│   ├── build_website.sesi           # Sesi-powered systems site generator
+│   └── 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)
-│   ├── IMAGE_GENERATION.md           # Image generation guide (>100 lines)
-│   ├── SYSTEMS_REASONING.md          # Integrated reasoning guide (500+ lines)
-│   ├── DISTRIBUTED_SYSTEMS.md        # Swarm & coordination guide (>100 lines)
-│   └── ROADMAP.md                    # V2-V4+ development plan (400+ lines)
+│   ├── 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
+│   ├── 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/
-    └── basic.test.ts                 # Test suite
+└── 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
 ```
 
 ## 🔧 Technology Stack
@@ -161,7 +176,13 @@ prompt greeting {"Hello, " name "!"}
 **Reasoning Calls**
 
 ```sesi
-let response = model("gemini-3-flash-preview") {"temperature": 0.7, "max_tokens": 1000} {"Your prompt here"}
+let response = model("gemini-3-flash-preview") {temperature: 0.7, max_tokens: 1000} {"Your prompt here"}
+```
+
+**Web Search Grounding**
+
+```sesi
+let response = model("gemini-3.1-flash-lite") {search, max_tokens: 1000} {"What is the weather in Tokyo?"}
 ```
 
 **Structured Output**
@@ -173,13 +194,13 @@ let result = structured_output({field1: string, field2: number})(model("gemini-3
 **Image Generation**
 
 ```sesi
-let logo = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": 512} {"Your prompt here"}
+let logo = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "512"} {"Your prompt here"}
 write_image("logo.png", logo)
 ```
 
 **Temporal Context Injection** ✅
 
-Every reasoning call automatically includes the current UTC date and time in its context, providing the system with a native sense of "now."
+Every reasoning call automatically includes the current UTC date and time in its context, providing the script with a native sense of "now."
 
 **Implicit Statement Termination** ✅
 
@@ -187,7 +208,7 @@ Expressions ending in `}` (such as prompt blocks or reasoning calls) no longer s
 
 **Async Polling for MAX_TOKENS** ✅
 
-The AI runtime natively polls the model if it hits a `MAX_TOKENS` finish reasoning block, automatically appending previous chunks and prompting the model to continue exactly where it left off, seamlessly synthesizing long responses.
+The runtime natively polls the model if it hits a `MAX_TOKENS` finish status during large generation tasks.
 
 **Tool Calling**
 
@@ -217,7 +238,9 @@ print("Reasoning Response:", response)
 - `read_file(path)` - Read file contents
 - `write_file(path, content)` - Write file contents
 - `write_image(path, content)` - Write base64 image data to file
+- `from_json(path)` - Read a JSON file
 - `list_dir(path)` - List directory contents
+- `make_dir(path)` - Create a new directory
 - `spawn(path)` - Launch concurrent background process
 - `exec(command)` - Synchronous shell execution
 - `time()` - Unix timestamp (ms)
@@ -227,6 +250,7 @@ print("Reasoning Response:", response)
 
 - `type(value)` - Get type name
 - `str(value)` - Convert to string
+- `to_json(value)` - Convert to JSON string
 - `num(value)` - Convert to number
 - `bool(value)` - Convert to boolean
 
@@ -250,21 +274,46 @@ print("Reasoning Response:", response)
 
 - `multi_req(fns)` - Concurrently execute multiple closures/functions
 
+### Reasoning
+
+- `workflow(steps, input)` - Run a multi-step reasoning workflow
+- `set_alias(alias, model)` - Register a custom local name for a model
+- `define_tool(name, fn, description)` - Register a custom tool
+- `list_tools()` - List custom tool names
+
+### Error Handling
+
+- `error_type(type, message, data)` - Create a custom error object
+- `raise_error(type_or_error, message, data)` - Throw an error
+
+### Math
+
+- `exp(x)` - Exponential function
+
 ## 📊 Implementation Statistics
 
 | Metric              | Value  |
 | ------------------- | ------ |
 | Total lines of code | ~3,000 |
 | Source files        | 7      |
-| Documentation pages | 5      |
-| Example programs    | 15     |
-| Built-in functions  | 23     |
+| Documentation pages | 12     |
+| Example programs    | 22     |
+| Built-in functions  | 34     |
 | Supported operators | 20+    |
 | AST node types      | 30+    |
 | Token types         | 50+    |
 
 ## 🚀 Getting Started
 
+### Installation
+
+```bash
+cd Sesi
+npm install
+npm run build
+npm install -g .
+```
+
 ### Run Example
 
 ```bash
@@ -347,7 +396,7 @@ npm test
 - Performance notes
 - Standard library plans
 
-✅ **SYSTEMS_REASONING.md** (500+ lines)
+✅ **REASONING.md** (500+ lines)
 
 - Systems reasoning overview
 - Prompt blocks explained
@@ -390,6 +439,10 @@ npm test
 | 16_modules.sesi             | Imports/exports & std namespaces|
 | 17_http_client.sesi         | HTTP GET and POST operations    |
 | 18_parallel_requests.sesi   | Parallel request 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 | Compose reasoning & tools |
 
 ## ✨ Unique Features
 
@@ -440,7 +493,7 @@ npm test
 
 **Example Coverage**
 
-- 15 complete example programs
+- 22 complete example programs
 - Covers all major language features
 - Demonstrates reasoning integration
 - Real-world use cases
@@ -469,30 +522,34 @@ npm test
 - **Cost**: Competitive pricing
 - **Availability**: Easy to use via official SDK
 
-### Why does v1.1.2 support a module system?
+### Why does v1+ support a module system?
 
-- **Organization**: As Sesi programs grew, having a single-file system became limiting. Local module imports/exports and standard libraries (`std/math`, `std/time`, `std/json`) are natively supported in v1.1.2.
+- **Organization**: As Sesi programs grew, having a single-file system became limiting. Local module imports/exports and standard libraries (`std/math`, `std/time`, `std/json`) are natively supported in v1.x.
 
-### Why does v1.1.2 support parallel execution?
+### Why does v1+ support parallel execution?
 
 - **Concurrency**: While the interpreter remains tree-walking and single-threaded for simplicity, native concurrency is supported via the parallel request executor `multi_req(array<function>)`, executing asynchronous operations physically in parallel.
 
 ## 📖 Learning Path
 
 1. **Start**: [QUICKSTART.md](QUICKSTART.md) - Get running in 5 minutes
-2. **Basics**: examples/01-06 - Core language features
-3. **Prompts**: examples/07 - Prompt blocks
-4. **Reasoning**: examples/08-12 - Reasoning feature exploration
-5. **Specification**: [SPECIFICATION.md](SPECIFICATION.md) - Complete grammar
-6. **Advanced**: [SYSTEMS_REASONING.md](SYSTEMS_REASONING.md) - Patterns and best practices
-7. **Builtins**: [BUILTINS.md](BUILTINS.md) - Built-in functions
-8. **Image Generation**: [IMAGE_GENERATION.md](IMAGE_GENERATION.md) examples/15 - Generating images natively
-9. **Architecture**: [ARCHITECTURE.md](ARCHITECTURE.md) - How it works
-10. **Roadmap**: [ROADMAP.md](ROADMAP.md) - Future vision
-
-## 🤝 Contributing Path (Future)
-
-When open source:
+2. **Builtins**: [BUILTINS.md](docs/BUILTINS.md) - Built-in functions
+3. **Basics**: examples/01-06 - Core language features
+4. **Prompts**: examples/07 - Prompt blocks
+5. **Reasoning**: examples/08-12 - Reasoning feature exploration
+6. **Advanced**: [REASONING.md](docs/REASONING.md) - Patterns and best practices
+7. **Systems**: examples/13-14 - Systems reasoning and data pipelines
+8. **Modules**: examples/16 - Modules & std library namespaces
+9. **Image Generation**: [IMAGE_GENERATION.md](docs/IMAGE_GENERATION.md) examples/15 - Generating images natively
+10. **Concurrency**: examples/17-18 - Concurrency & coordination
+11. **Web Search**: examples/19 - Web search integration
+12. **Model Aliases**: examples/20 - Custom model naming aliases
+13. **Custom Tools**: examples/21-22 - Custom runtime tool definitions and compose reasoning with custom tools
+14. **Specification**: [SPECIFICATION.md](docs/SPECIFICATION.md) - Complete grammar
+15. **Architecture**: [ARCHITECTURE.md](docs/ARCHITECTURE.md) - How it works
+16. **Roadmap**: [ROADMAP.md](docs/ROADMAP.md) - Future vision
+
+## 🤝 Contributing Path
 
 1. Report bugs with minimal examples
 2. Suggest language features via RFCs
@@ -509,7 +566,7 @@ When open source:
 - ✅ API reference (450+ lines)
 - ✅ Systems reasoning guide (500+ lines)
 - ✅ Development roadmap (400+ lines)
-- ✅ 15 example programs
+- ✅ 20+ example programs
 - ✅ CLI executable
 - ✅ Test suite
 - ✅ Quick start guide
@@ -526,19 +583,19 @@ When open source:
 
 ## 🚀 Philosophy
 
-> "Sesi demonstrates that systems-level logic and integrated reasoning can be unified into a single, elegant language primitive, eliminating the boilerplate of traditional AI development."
+> "Sesi demonstrates that coding shouldn't need to be hard to understand, eliminating the boilerplate of traditional development and lowering the entry-level for those interested in code or programming."
 
-The language is designed to evolve. V1 provides a solid foundation. V2+ adds power. The architecture supports this gracefully without breaking existing programs.
+The language is designed to evolve. V1+ provides a solid foundation. V2+ adds power. The architecture supports this gracefully without breaking existing programs.
 
 ---
 
-**Status**: ✅ Complete V1.1 implementation  
-**Ready for**: Distributed systems orchestration and prototypes  
+**Status**: ⏳ Ongoing V1.3 implementation  
+**Ready for**: File manipulation and process orchestration  
 **Not ready for**: Massive-scale production (until v2.0 bytecode)  
 **Next milestone**: V2.0 (Async & advanced reasoning)
 
-Sesi is an experiment in language design. Use it to learn, explore, and evolve what integrated reasoning will become.
+Sesi is not just an experiment in language design. Use it to learn, explore, and evolve what the future of coding will become.
 
 ---
 
-For more information, see more of the documentation in this folder and examples in `examples/`.
+For more information, see the documentation in `docs/` and examples in `examples/`.