Improve emojicode guide

It was inconsistent with reality, which confused AIs ability to write
emojicode

Author: frison

emojicode/fraglet/guide.md

@@ -1,63 +1,87 @@
-# EmojiCode Fraglet Guide
+# Emojicode Fraglet Guide
 
 ## Language Version
-EmojiCode (compiled language)
+Emojicode (as installed in this container; run `emojicodec --version` inside the container if you need the exact version).
 
 ## Execution Model
-- Compiled via `emojicodec` compiler
-- Produces native binary executable
+- **Compiled language** using the `emojicodec` compiler.
+- Your fraglet **replaces the entire contents** between `💭 BEGIN_FRAGLET` and `💭 END_FRAGLET` in `hello-world.🍇`.
+- The resulting file is compiled and run as a normal Emojicode program.
+
+## Key Characteristics
+- **Emoji-based syntax** for all core constructs (entry point, blocks, variables, printing, comments).
+- **Compiled to native code**; errors are reported by `emojicodec` with file/position info.
+- **Block-structured** with explicit start (`🍇`) and end (`🍉`) delimiters.
+- **Statement-terminated** with `❗️`.
 
 ## Fragment Authoring
-Write a complete EmojiCode program. Your fragment replaces the entire source file.
+- **You write a complete Emojicode program.** Your fraglet is not injected into `main` or any other function body.
+- You must include:
+  - Program entry: `🏁`
+  - A top-level block: `🍇` ... `🍉`
+  - Whatever statements you want to run inside that block.
+- The minimal shape looks like:
+
+```emojicode
+🏁 🍇
+  …your statements…
+🍉
+```
+
+## Mental Model
+You write a **full, valid Emojicode program**, starting with `🏁` and a `🍇 … 🍉` block, and we **compile and run it as-is**.  
+Nothing is injected for you and no `main` wrapper is added – if your program wouldn’t compile with `emojicodec` on its own, it won’t compile as a fraglet.
 
 ## Basic Syntax
-- `🏁` - Main function entry point
-- `🍇` / `🍉` - Block start / end
-- `😀` - Print statement
-- `🔤...🔤` - String literal delimiters
-- `❗️` - Statement terminator
-- `💭` - Comment marker
+- `🏁` – Program entry point.
+- `🍇` / `🍉` – Block start / end.
+- `😀` – Print statement.
+- `🔤…🔤` – String literal delimiters.
+- `❗️` – Statement terminator.
+- `💭` – Comment / annotation.
 
 ## Variables and Types
-- `🖍🆕` - Declare a mutable variable
-- `🔢` - Integer type
-- `🔡` - String type
-- Declaration: `🖍🆕 x 🔢 5`
-
-## Conditionals
-- `↪️` - If
-- `🙅` - Else
-- `🙅↪️` - Else-if
-- `👍` / `👎` - True / False
+- `🖍🆕` – Declare a mutable variable.
+- Common types:
+  - `🔢` – Integer.
+  - `🔡` – String.
+- Example declaration:
 
-## Examples
 ```emojicode
-🏁 🍇
-  😀 🔤Hello World!🔤❗️
-🍉
+🖍🆕 x 🔢 5❗️
 ```
 
+## Examples
+
+### Minimal Hello World
+This is the smallest program you should expect to compile and run as a fraglet in this vein:
+
 ```emojicode
 🏁 🍇
-  😀 🔤First line🔤❗️
-  😀 🔤Second line🔤❗️
+  😀 🔤Hello from Emojicode fraglet!🔤❗️
 🍉
 ```
 
+### Variables and printing
+A slightly richer example with a variable and formatted output:
+
 ```emojicode
 🏁 🍇
-  🖍🆕 x 🔢 5
-  ↪️ 👍 🍇
-    😀 🔤True!🔤❗️
-  🍉
-  🙅 🍇
-    😀 🔤False!🔤❗️
-  🍉
+  🖍🆕 times 🔢 3❗️
+  😀 🔤About to greet…🔤❗️
+  😀 🔤Hello 🔤❗️
+  😀 🔤We greeted 🔤❗️
+  😀 🔤times: 🔤❗️
+  😀 times❗️
 🍉
 ```
 
+Both examples are complete programs: if you drop them between `💭 BEGIN_FRAGLET` and `💭 END_FRAGLET` in `hello-world.🍇`, they should compile and run under this fraglet vein.
+
 ## Caveats
-- Ensure your editor supports Unicode emoji characters
-- String literals must be wrapped in `🔤` delimiters
-- Statements end with `❗️`
-- Variable declarations require `🖍🆕` prefix
+- **Full program required**: Fragments that are just statements like `😀 🔤Hello🔤❗️` without `🏁 🍇` … `🍉` will fail to compile.
+- **Compiler errors are authoritative**: If execution fails, read the `emojicodec` error message and iterate until it compiles – this guide describes the expected structure, but the compiler is the final arbiter.
+- Ensure your editor supports **Unicode emoji** so characters are preserved correctly.
+- **String literals** must be wrapped in `🔤` delimiters.
+- **Every statement** (including variable declarations and prints) must end with `❗️`.
+- Variable declarations require the `🖍🆕` prefix and an appropriate type emoji.