@misterscan/sesi 1.2.3 → 1.3.0

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/`.

package/docs/QUICKSTART.md

@@ -1,6 +1,8 @@
 # Quick Start Guide: Sesi Programming Language
 
-## Run a program:
+### Run a program
+
+Once Sesi is installed, you can run Sesi files globally:
 
 ```bash
 sesi main/start.sesi
@@ -8,6 +10,7 @@ sesi main/start.sesi
 
 ### Run Tests
 
+For devs working on Sesi, you can verify your backend edits with the built-in test suite:
 ```bash
 npm test
 ```
@@ -104,7 +107,7 @@ Get your key from [Google AI Studio](https://aistudio.google.com/app/apikey).
 Reasoning features allow passing configuration options via a block format before the prompt.
 
 ```sesi
-let response = model("gemini-3-flash-preview") {"temperature": 0.8, "max_tokens": 1000} {"What is 2 + 2?"}
+let response = model("gemini-3-flash-preview") {temperature: 0.8, max_tokens: 1000} {"What is 2 + 2?"}
 print response
 ```
 
@@ -129,7 +132,7 @@ print "Score: " analysis["score"]
 Like `model`, the `image` command takes configuration parameters.
 
 ```sesi
-let logo = image("gemini-3.1-flash-image-preview") {"ratio": '1:1', "size": 512, "temperature": 0.3, "max_tokens": 512} {"make a beautiful logo for the word Sesi"}
+let logo = image("gemini-3.1-flash-image-preview") {ratio: "1:1", size: "512", temperature: 0.3} {"make a beautiful logo for the word Sesi"}
 write_image("logo.png", logo)
 print "Generated image successfully!"
 ```
@@ -143,7 +146,7 @@ print response
 chat = chat "Assistant:" response
 ```
 
-### Concurrent Swarms
+### Concurrent Processes
 
 Sesi can orchestrate multiple concurrent scripts using the `spawn()` builtin.
 
@@ -167,6 +170,7 @@ from_json(path)    // Read a JSON file
 write_file(path, content) // Write text to a file
 write_image(path, content) // Write base64 encoded image to a 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)
@@ -178,7 +182,7 @@ random()           // Random number (0-1)
 ```sesi
 type(value)        // Get type name
 str(value)         // Convert to string
-to_json(value)      // Convert to valid JSON string
+to_json(value)     // Convert to valid JSON string
 num(value)         // Convert to number
 bool(value)        // Convert to boolean
 ```
@@ -199,19 +203,41 @@ range(n)           // Create [0, 1, ..., n-1]
 ### Network & Concurrency
 
 ```sesi
-web_get(url, headers = {})     // Natively fetch from URL via HTTP GET
+web_get(url, headers = {})        // Natively fetch from URL via HTTP GET
 web_send(url, body, headers = {}) // Natively post body to URL via HTTP POST
-multi_req(array<function>)     // Run multiple tasks/requests physically in parallel
+multi_req(array<function>)        // Run multiple tasks/requests physically in parallel
+```
+
+### Reasoning
+
+```sesi
+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, desc)     // Register a custom tool
+list_tools()                    // List custom tool names
+```
+
+### Error Handling
+
+```sesi
+error_type(type, message, data) // Create a custom error object
+raise_error(error)              // Throw an error
+```
+
+### Math
+
+```sesi
+exp(x)             // Exponential function
 ```
 
 ### Standard Library Modules
 
-Standard library features are available natively in **v1.2.0** using imports:
+Standard library features are available natively in **v1.2+** using imports:
 
 ```sesi
-import { PI, sqrt } from "std/math"
-import { sleep, now } from "std/time"
-import { stringify, parse } from "std/json"
+import {PI, sqrt} from "std/math"
+import {sleep, now} from "std/time"
+import {stringify, parse} from "std/json"
 ```
 
 ## Running Examples
@@ -239,10 +265,14 @@ sesi examples/14_folder_explainer.sesi
 # Image generation example
 sesi examples/15_image_generation.sesi
 
-# Advanced Version 1.2 features
+# Advanced Version 1.3 features
 sesi examples/16_modules.sesi
 sesi examples/17_http_client.sesi
 sesi examples/18_parallel_requests.sesi
+sesi examples/19_search_web.sesi
+sesi examples/20_model_aliases.sesi
+sesi examples/21_custom_tools.sesi
+sesi examples/22_reasoning_plus_custom_tools.sesi
 ```
 
 ## Common Patterns
@@ -284,8 +314,8 @@ let rejoined = join(words, "-")
 ### Reasoning Classification
 
 ```sesi
-fn classify(item: string) {print model("gemini-3-flash-preview")
-{"Classify as: FRUIT, VEGETABLE, or GRAIN. Item: " item}}
+fn classify(item: string) 
+{print model("gemini-3-flash-preview"){"Classify as: FRUIT, VEGETABLE, or GRAIN. Item: " item}}
 classify("apple")
 classify("carrot")
 classify("wheat")
@@ -296,12 +326,11 @@ classify("wheat")
 ### Print Intermediate Values
 
 ```sesi
-fn complex(x: number) {
-  let step1 = x * 2
-  print "Step 1:" str(step1)
-  let step2 = step1 + 10
-  print "Step 2:" str(step2)
-}
+fn complex(x: number) 
+{let step1 = x * 2
+print "Step 1:" str(step1)
+let step2 = step1 + 10
+print "Step 2:" str(step2)}
 complex(5)
 ```
 
@@ -331,15 +360,15 @@ else {print "Response: " response}
 
 ## Next Steps
 
-1. **Read the spec**: [SPECIFICATION.md](SPECIFICATION.md)
-2. **Learn about reasoning**: [SYSTEMS_REASONING.md](SYSTEMS_REASONING.md)
-3. **Understand architecture**: [ARCHITECTURE.md](ARCHITECTURE.md)
-4. **Check roadmap**: [ROADMAP.md](ROADMAP.md)
-5. **Study examples**: [examples/](/examples/)
+1. **Read the spec**: [SPECIFICATION.md](docs/SPECIFICATION.md)
+2. **Learn about reasoning**: [REASONING.md](docs/REASONING.md)
+3. **Understand architecture**: [ARCHITECTURE.md](docs/ARCHITECTURE.md)
+4. **Check roadmap**: [ROADMAP.md](docs/ROADMAP.md)
+5. **Study examples**: [examples/](examples/)
 
 ## Getting Help
 
-Sesi comes with an advanced, built-in **Interactive RAG Co-Pilot** right in your command line! Instead of static help messages, you can query Sesi directly about how to use any statement, standard library, or architectural pattern:
+Sesi comes with an advanced, built-in **Interactive Co-Pilot** right in your command line! Instead of static help messages, you can query Sesi directly about how to use any statement, standard library, or architectural pattern:
 
 ```bash
 # Ask the Sesi Co-Pilot for help directly
@@ -348,11 +377,35 @@ sesi --help "explain structured_output and give an example"
 sesi -h "how to spawn background processes?"
 ```
 
+You can also pass a file into the help context so the co-pilot can talk about that exact script:
+
+```bash
+sesi main/playground.sesi -h
+sesi main/playground.sesi -h "why is this failing?"
+```
+
+Other useful CLI options:
+
+```bash
+# Run a one-line snippet
+sesi -e "print 'hello'"
+
+# Encrypt or decrypt a script file
+sesi -encrypt my_script.sesi -p "my-password"
+sesi -decrypt my_script.sesi -p "my-password"
+
+# Disable sandbox protections for a run
+sesi main/start.sesi --local
+
+# Add extra allowed filesystem paths
+sesi main/start.sesi --allowed-paths ./docs,./examples
+```
+
 The co-pilot will dynamically index and train on Sesi's native repository database and retrieve full RAG context from our standard specification docs to generate a syntactically correct, 100% accurate, conversational answer in real-time!
 
 You can also:
 - Check documentation in [docs/](docs/)
-- Review examples in [examples/](/examples/)
+- Review examples in [examples/](examples/)
 - Read error messages carefully
 - Try simpler programs first
 
@@ -367,4 +420,4 @@ When reporting bugs:
 
 ---
 
-Happy programming with Sesi! 🚀
+Happy programming with Sesi! 🚀