@shd101wyy/yo 0.1.25 → 0.1.27

package/.github/skills/yo-async-effects/SKILL.md

@@ -26,8 +26,8 @@ Use this skill when you need to:
 2. Add the necessary `using(...)` parameters to function signatures and call sites.
 3. Use the [async and effects recipes](./async-effects-recipes.md) for working patterns.
 4. Re-check handler semantics before finalizing:
-   - `return value` resumes the continuation
-   - `escape expr` discards it
+   - `return(value)` resumes the continuation
+   - `escape(expr)` discards it
 
 ## High-signal rules
 
@@ -38,8 +38,8 @@ Use this skill when you need to:
 - Future types include their effects: `Future(ResultType, IO, Effect...)`.
 - Effects are matched by type, not variable name.
 - `using(name : Type)` declares an implicit effect parameter; `given(name) := Type(...)` installs the handler.
-- `return value` inside a handler resumes the continuation; `escape expr` discards it.
-- `Exception` — non-resumable; handler calls `escape` to exit. `ResumableException(T)` — handler calls `return` to resume.
+- `return(value)` inside a handler resumes the continuation; `escape(expr)` discards it.
+- `Exception` — non-resumable; handler calls `escape(...)` to exit. `ResumableException(T)` — handler calls `return(...)` to resume.
 - Effect handlers are standalone, not closures; pass state explicitly.
 - Yo async is single-threaded concurrency, not multithreaded parallelism.
 

package/.github/skills/yo-async-effects/async-effects-recipes.md

@@ -14,7 +14,7 @@ These patterns cover normal Yo async code and algebraic effects.
 ## Minimal async function
 
 ```rust
-{ yield } :: import "std/async";
+{ yield } :: import("std/async");
 
 pause_then_answer :: (fn(using(io : IO)) -> Impl(Future(i32, IO)))(
   io.async((using(io : IO)) => {
@@ -41,7 +41,7 @@ work :: (fn(using(io : IO, raise : Raise)) -> Impl(Future(i32, IO, Raise)))(
 ## Sequential await
 
 ```rust
-{ yield } :: import "std/async";
+{ yield } :: import("std/async");
 
 main :: (fn(using(io : IO)) -> unit)({
   task := io.async((using(io : IO)) => {
@@ -53,13 +53,13 @@ main :: (fn(using(io : IO)) -> unit)({
   assert((result == i32(1)), "unexpected result");
 });
 
-export main;
+export(main);
 ```
 
 ## Concurrent tasks on the same thread
 
 ```rust
-{ yield } :: import "std/async";
+{ yield } :: import("std/async");
 
 main :: (fn(using(io : IO)) -> unit)({
   task1 := io.async((using(io : IO)) => {
@@ -78,7 +78,7 @@ main :: (fn(using(io : IO)) -> unit)({
   result2 := handle2.await(using(io));
 });
 
-export main;
+export(main);
 ```
 
 - `io.spawn(...)` begins execution without waiting
@@ -87,8 +87,8 @@ export main;
 ## Propagating and handling effects
 
 ```rust
-open import "std/fmt";
-open import "std/string";
+open(import("std/fmt"));
+open(import("std/string"));
 
 Raise :: (fn(msg : String) -> i32);
 
@@ -102,7 +102,7 @@ safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
 resume_example :: (fn() -> i32)({
   (given(raise) : Raise) = (fn(msg : String) -> i32)({
     println(msg);
-    return i32(0);
+    return(i32(0));
   });
 
   safe_divide(i32(8), i32(0))
@@ -111,22 +111,22 @@ resume_example :: (fn() -> i32)({
 escape_example :: (fn() -> i32)({
   (given(raise) : Raise) = (fn(msg : String) -> i32)({
     println(msg);
-    escape i32(-1);
+    escape(i32(-1));
   });
 
   safe_divide(i32(8), i32(0))
 });
 ```
 
-| Handler action | Meaning                                      |
-| -------------- | -------------------------------------------- |
-| `return value` | Resume the continuation with `value`         |
-| `escape expr`  | Exit the function that installed the handler |
+| Handler action  | Meaning                                      |
+| --------------- | -------------------------------------------- |
+| `return(value)` | Resume the continuation with `value`         |
+| `escape(expr)`  | Exit the function that installed the handler |
 
 ## Futures with multiple effects
 
 ```rust
-{ yield } :: import "std/async";
+{ yield } :: import("std/async");
 
 work :: (fn(using(io : IO, raise : Raise)) -> Impl(Future(i32, IO, Raise)))(
   io.async((using(io : IO, raise : Raise)) => {
@@ -146,20 +146,20 @@ work :: (fn(using(io : IO, raise : Raise)) -> Impl(Future(i32, IO, Raise)))(
 **Solution**: replace async recursion with an iterative worklist using `ArrayList` as a stack:
 
 ```rust
-{ read_dir, DirEntry } :: import "std/fs/dir";
+{ read_dir, DirEntry } :: import("std/fs/dir");
 
 process_dir :: (fn(root: Path, using(io: IO, exn: Exception)) -> Impl(Future(unit, IO, Exception)))(
   io.async((using(io, exn)) => {
     stack := ArrayList(Path).new();
     { stack.push(root); };
 
-    while runtime((stack.len() > usize(0))), {
-      cur := match(stack.pop(), .Some(p) => p, .None => return ());
+    while(runtime((stack.len() > usize(0))), {
+      cur := match(stack.pop(), .Some(p) => p, .None => return());
       entries := io.await(read_dir(cur));
       // process `entries`, push subdirectories to `stack`
       n := entries.len();
       i := usize(0);
-      while runtime((i < n)), {
+      while(runtime((i < n)), {
         match(entries.get(i),
           .None => (),
           .Some(e) => {
@@ -170,8 +170,8 @@ process_dir :: (fn(root: Path, using(io: IO, exn: Exception)) -> Impl(Future(uni
           }
         );
         i = (i + usize(1));
-      };
-    };
+      });
+    });
   })
 );
 ```
@@ -186,11 +186,11 @@ process_dir :: (fn(root: Path, using(io: IO, exn: Exception)) -> Impl(Future(uni
 
 ## Exception (non-resumable)
 
-`Exception` is a built-in module effect for non-resumable error handling. When the handler calls `escape`, the continuation is discarded:
+`Exception` is a built-in struct-record effect for non-resumable error handling. When the handler calls `escape`, the continuation is discarded:
 
 ```rust
-open import "std/error";
-open import "std/fmt";
+open(import("std/error"));
+open(import("std/fmt"));
 
 DivError :: enum(DivByZero);
 impl(DivError, ToString(to_string : ((self) -> `division by zero`)));
@@ -207,7 +207,7 @@ main :: (fn() -> unit)({
   given(exn) := Exception(
     throw : ((err) -> {
       println(`Error: ${err}`);
-      escape ();
+      escape();
     })
   );
 
@@ -217,7 +217,7 @@ main :: (fn() -> unit)({
   safe_divide(i32(10), i32(0));
 });
 
-export main;
+export(main);
 ```
 
 - `Exception` has a single field `throw : (fn(error : AnyError) -> T)`
@@ -230,32 +230,32 @@ export main;
 When an exception is thrown inside an async operation (e.g., `cmd.status()` or `cmd.output()`), you can **swallow the error and resume with a fallback value** by using `return` in the handler (not `escape`). The `ResumeType` is the return type of the operation that would have thrown.
 
 ```rust
-{ Command, ExitStatus, Output } :: import "std/process/command";
+{ Command, ExitStatus, Output } :: import("std/process/command");
 
 // Check if a tool is available — returns false if it throws (e.g., not found)
 given(try_exn) := Exception(throw: ((err) -> {
-  return ExitStatus(raw: i32(1));  // resume with "failed" exit status
+  return(ExitStatus(raw: i32(1)));  // resume with "failed" exit status
 }));
 status := io.await(cmd.status(using(io, try_exn)));
 available := status.success();  // false if exception was swallowed
 
 // For cmd.output(), resume with a failed Output:
 given(out_exn) := Exception(throw: ((err) -> {
-  return Output(status: ExitStatus(raw: i32(1)), stdout: ArrayList(u8).new(), stderr: ArrayList(u8).new());
+  return(Output(status: ExitStatus(raw: i32(1)), stdout: ArrayList(u8).new(), stderr: ArrayList(u8).new()));
 }));
 out := io.await(cmd.output(using(io, out_exn)));
-if((!(out.status.success())), { return (); });  // handle failure
+if((!(out.status.success())), { return(); });  // handle failure
 ```
 
 Key: the `return` inside the handler resumes the _effect invocation site_ with the provided value. The calling code then sees the fallback as if the operation returned normally. Use `escape` only when the enclosing function returns `unit` (e.g., test bodies).
 
-**`escape T_value` constraint**: `escape T_value` inside an `Exception` handler requires that the enclosing `io.async` closure's return type matches `T_value`. Due to forward type inference, the evaluator may not know the closure's return type at the point where `given` is declared. This causes a "Expected: unit" error when `escape non_unit` is used in a handler declared before the final return expression. Prefer `return fallback_value` (resume) when possible.
+**`escape(T_value)` constraint**: `escape(T_value)` inside an `Exception` handler requires that the enclosing `io.async` closure's return type matches `T_value`. Due to forward type inference, the evaluator may not know the closure's return type at the point where `given` is declared. This causes a "Expected: unit" error when `escape(non_unit)` is used in a handler declared before the final return expression. Prefer `return(fallback_value)` (resume) when possible.
 
-`ResumableException(ResumeType)` is a module effect for resumable error handling. The handler uses `return` to resume with a recovery value:
+`ResumableException(ResumeType)` is a struct-record effect for resumable error handling. The handler uses `return` to resume with a recovery value:
 
 ```rust
-open import "std/error";
-open import "std/fmt";
+open(import("std/error"));
+open(import("std/fmt"));
 
 safe_divide :: (fn(x : i32, y : i32, using(exn : ResumableException(i32))) -> i32)(
   cond(
@@ -268,7 +268,7 @@ main :: (fn() -> unit)({
   given(exn) := ResumableException(i32)(
     throw : ((err) -> {
       println(`Recovering from: ${err}`);
-      return i32(0);
+      return(i32(0));
     })
   );
 
@@ -276,25 +276,25 @@ main :: (fn() -> unit)({
   assert((result == i32(0)), "recovered with 0");
 });
 
-export main;
+export(main);
 ```
 
-- Handler uses `return value` to resume the continuation with the recovery value
+- Handler uses `return(value)` to resume the continuation with the recovery value
 - The call site receives the returned value and continues normally
 
-## Module effects vs function-type effects
+## Struct-record effects vs function-type effects
 
-Effects in Yo can be plain function types or module types:
+Effects in Yo can be plain function types or struct-record types:
 
 ```rust
 Raise :: (fn(msg : String) -> i32);
 
-Logger :: module(
+Logger :: struct(
   log : (fn(level : i32, msg : String) -> unit)
 );
 ```
 
-Both kinds use `using(...)` / `given(...)` with the same semantics — they compile to evidence passing (function pointers as implicit C parameters). Module effects group related operations under a single name.
+Both kinds use `using(...)` / `given(...)` with the same semantics — they compile to evidence passing (function pointers as implicit C parameters). Struct-record effects group related operations under a single nominal type.
 
 ## Async with effects
 

package/.github/skills/yo-core-patterns/SKILL.md

@@ -40,7 +40,7 @@ Use this skill when you need to:
 - Use `derive(Type, Eq, Hash, Clone, Ord, ToString)` to auto-generate common trait impls.
 - Custom error types implement `ToString` + `Error`; wrap with `dyn(...)` into `AnyError`.
 - Use `(params) => expr` for closures; `Impl(Fn(...) -> T)` for the closure type.
-- Use `for collection.iter(), (item) => { ... }` for iteration.
+- Use `for(collection.iter(), (item) => { ... })` for iteration.
 - Indexed modules import cleanly as `std/url`, `std/regex`, `std/http`, `std/log`, and `std/glob`; multi-module families use explicit submodules.
 
 ## Resource

package/.github/skills/yo-core-patterns/core-patterns-cheatsheet.md

@@ -5,8 +5,8 @@ These patterns are aimed at everyday Yo application and library code.
 ## Strings and output
 
 ```rust
-open import "std/fmt";
-open import "std/string";
+open(import("std/fmt"));
+open(import("std/string"));
 
 (name : str) = "yo";
 greeting := `Hello ${name}`;
@@ -38,13 +38,13 @@ Key rules:
 ## Import patterns
 
 ```rust
-{ LocalType } :: import "./local_type.yo";
-open import "std/string";
-{ ArrayList } :: import "std/collections/array_list";
-{ HashMap } :: import "std/collections/hash_map";
-{ Url } :: import "std/url";
-{ Regex } :: import "std/regex";
-{ fetch, HttpRequest } :: import "std/http";
+{ LocalType } :: import("./local_type.yo");
+open(import("std/string"));
+{ ArrayList } :: import("std/collections/array_list");
+{ HashMap } :: import("std/collections/hash_map");
+{ Url } :: import("std/url");
+{ Regex } :: import("std/regex");
+{ fetch, HttpRequest } :: import("std/http");
 ```
 
 | Need                           | Import pattern                                                                       |
@@ -60,7 +60,7 @@ Do not import `std/prelude`; it is already available.
 ## Option and Result
 
 ```rust
-open import "std/string";
+open(import("std/string"));
 
 (value : Option(i32)) = .Some(i32(21));
 doubled := value.map((x) => (x * i32(2)));
@@ -81,9 +81,9 @@ text := match(parsed,
 ## Collections
 
 ```rust
-{ ArrayList } :: import "std/collections/array_list";
-{ HashMap } :: import "std/collections/hash_map";
-open import "std/string";
+{ ArrayList } :: import("std/collections/array_list");
+{ HashMap } :: import("std/collections/hash_map");
+open(import("std/string"));
 
 numbers := ArrayList(i32).new();
 numbers.push(i32(1));
@@ -161,7 +161,7 @@ parent := Node(value: i32(1), next: Option(Box(Node)).Some(child));
 ## Unicode and platform checks
 
 ```rust
-{ Platform, platform } :: import "std/process";
+{ Platform, platform } :: import("std/process");
 
 separator := cond(
   (platform == Platform.Windows) => `\\`,
@@ -190,6 +190,10 @@ TcpStream :: object(fd : i32, buffer : ArrayList(u8));
 
 - Use `newtype(...)` when the type has exactly one field
 - Use `object(...)` for types that need shared ownership
+- Source-file imports are namespace structs. The old `module(...)`, `Module`,
+  and `SelfModule` syntax is gone; use `struct(...)`, `Type`, and normal `Self`.
+- Fields written as `name :: value` or `comptime(name) : Type` are compile-time-only static fields/methods and have no runtime layout
+- A normal field with a compile-time-only type, such as `x : comptime_int`, is still a data field and makes the struct comptime-only
 
 ## Impl blocks and generics
 
@@ -281,7 +285,7 @@ node_eq :: (fn(a : Node, b : Node) -> bool)(
             true => {
               (i : usize) = usize(0);
               (ok : bool) = true;
-              while runtime(((i < acs.len()) && ok)), {
+              while(runtime(((i < acs.len()) && ok)), {
                 match(acs.get(i),
                   .Some(ac) => match(bcs.get(i),
                     .Some(bc) => { ok = recur(ac, bc); },
@@ -290,7 +294,7 @@ node_eq :: (fn(a : Node, b : Node) -> bool)(
                   .None => { ok = false; }
                 );
                 i = (i + usize(1));
-              };
+              });
               ok
             }
           )
@@ -320,15 +324,15 @@ derived or implemented. For **tag-only equality** (checking which variant), use
 if(my_type != t_unit(), { ... });
 
 // CORRECT — compare tags instead
-{ type_value_tag } :: import "../../types/type.yo";
-{ TypeTag }        :: import "../../types/tags.yo";
+{ type_value_tag } :: import("../../types/type.yo");
+{ TypeTag }        :: import("../../types/tags.yo");
 if((type_value_tag(my_type) != TypeTag.TUnit), { ... });
 ```
 
 ## Error handling
 
 ```rust
-open import "std/error";
+open(import("std/error"));
 
 DivError :: enum(DivByZero);
 impl(DivError, ToString(to_string : ((self) -> `division by zero`)));
@@ -354,9 +358,9 @@ safe_div :: (fn(a : i32, b : i32) -> Result(i32, DivError))(
 result := inc(i32(5));
 
 transform :: (fn(values : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)({
-  for values.iter(), (ptr) => {
+  for(values.iter(), (ptr) => {
     ptr.* = f(ptr.*);
-  };
+  });
 });
 ```
 
@@ -368,19 +372,19 @@ transform :: (fn(values : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)
 ## Iterator and for loop
 
 ```rust
-{ ArrayList } :: import "std/collections/array_list";
+{ ArrayList } :: import("std/collections/array_list");
 
 list := ArrayList(i32).new();
 list.push(i32(1));
 list.push(i32(2));
 
-for list.iter(), (ptr) => {
+for(list.iter(), (ptr) => {
   println(ptr.*);
-};
+});
 
-for list.into_iter(), (value) => {
+for(list.into_iter(), (value) => {
   println(value);
-};
+});
 ```
 
 | Method         | Yields | Semantics                           |

package/.github/skills/yo-project-workflow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yo-project-workflow
-description: Build, test, scaffold, and manage Yo projects. Use this when working with yo init, build.yo, yo build, yo compile, yo test, yo install, yo fetch, yo version, or cross-platform Yo project setup.
+description: Build, test, scaffold, format, and manage Yo projects. Use this when working with yo init, build.yo, yo build, yo compile, yo test, yo fmt, yo install, yo fetch, yo version, or cross-platform Yo project setup.
 argument-hint: "[project task or command]"
 ---
 
@@ -17,6 +17,7 @@ Use this skill when you need to:
 - scaffold a new Yo project
 - understand or edit `build.yo`
 - choose between `yo build`, `yo compile`, and `yo test`
+- format source with `yo fmt`
 - manage dependencies with `yo install` or `yo fetch`
 - pin or manage Yo versions with `yo version`
 - install AI agent skill files with `yo skills install`
@@ -28,8 +29,9 @@ Use this skill when you need to:
 1. If the repository has `build.yo`, prefer `yo build` and named steps for whole-project work.
 2. For single-file experiments or reproductions, use `yo compile`.
 3. For tests, use `yo test [path]` and narrow to a file or pattern before broad runs.
-4. To pin the project to a specific Yo version, use `yo version pin`.
-5. Consult the [workflow cheatsheet](./workflow-cheatsheet.md) for command shapes, project layout, and a minimal `build.yo`.
+4. For source formatting, use `yo fmt`; use `yo fmt --check` in CI-style verification.
+5. To pin the project to a specific Yo version, use `yo version pin`.
+6. Consult the [workflow cheatsheet](./workflow-cheatsheet.md) for command shapes, project layout, and a minimal `build.yo`.
 
 ## High-signal rules
 
@@ -37,6 +39,7 @@ Use this skill when you need to:
 - `build.yo` is Yo code that imports `std/build`; build functions register compile-time steps.
 - `yo build run` and `yo build test` are the standard project entry points.
 - `yo test ./tests/some.test.yo --parallel 1` is the focused single-file test pattern.
+- `yo fmt` applies the fixed Yo style with 2-space indentation; there are no formatter options.
 - Use `yo install` and `yo fetch` for git or path dependencies.
 - Use `yo version pin` to create a `.yo-version` file for reproducible builds.
 - Use `yo skills install` to copy Yo skill files into all agent config directories in the project.

package/.github/skills/yo-project-workflow/workflow-cheatsheet.md

@@ -18,6 +18,8 @@ These commands and patterns are aimed at normal Yo projects that use the public
 | Inspect generated C       | `yo compile main.yo --emit-c --skip-c-compiler`           |
 | Run tests in one file     | `yo test ./tests/main.test.yo --parallel 1`               |
 | Filter tests by name      | `yo test ./tests/main.test.yo --test-name-pattern "Name"` |
+| Format Yo source          | `yo fmt ./src ./tests`                                    |
+| Check Yo formatting       | `yo fmt --check`                                          |
 | Generate docs for project | `yo doc ./src`                                            |
 | Generate docs (custom)    | `yo doc ./src -o docs --title "My Project"`               |
 | Install AI agent skills   | `yo skills install`                                       |
@@ -48,7 +50,7 @@ my-project/
 ## Minimal `build.yo`
 
 ```rust
-build :: import "std/build";
+build :: import("std/build");
 
 mod :: build.module({ name: "my-project", root: "./src/lib.yo" });
 
@@ -89,6 +91,7 @@ doc_step.depend_on(docs);
 | Whole project with `build.yo`   | `yo build ...`                             |
 | One standalone file             | `yo compile ...`                           |
 | One test file or test directory | `yo test ...`                              |
+| Formatting Yo source            | `yo fmt ...`                               |
 | Dependency changes              | `yo install ...` then `yo fetch` if needed |
 
 ## Testing patterns
@@ -103,25 +106,45 @@ yo test ./tests/main.test.yo --bail --verbose --parallel 1
 - Use `--test-name-pattern` when a file contains many tests
 - Use `yo build test` when the repository's main test workflow is defined in `build.yo`
 
+## Formatting
+
+```bash
+yo fmt
+yo fmt ./src ./tests
+yo fmt --check
+```
+
+- `yo fmt` recursively formats `.yo` files under the current directory by default
+- Pass files or directories to limit the scope
+- `yo fmt --check` reports files that need formatting without writing changes
+- Formatting is intentionally fixed: 2-space indentation and no configuration
+- Formatting must be idempotent: a second `yo fmt` run on the same files should report no changes and must not produce parser errors
+- The formatter removes redundant grouping parentheses, e.g. `return((1 + 2))` → `return(1 + 2)`
+- Infix-like separators keep spaces on both sides, including `{ x : value }` fields and `[T ; N]` array type sugar
+- It preserves delimiter syntax whose meaning is not just grouping: tuples, `{...}` struct/begin forms, `[T ; N]` arrays, `[T]` slices, call parentheses, function body calls, and prefix-operator operands
+- It preserves grouping or operator line breaks where removing them would expose ambiguous infix syntax, e.g. `{ x : (1 + 2), y : 3 }`, `true => (x / y)`, `(ptr &+ 1).*`, and line-leading `|` chains
+- When an operator ends a line, `yo fmt` indents the RHS one extra level as a continuation
+- `yo fmt` canonicalizes legacy deref spelling `ptr.(*)` to `ptr.*` and keeps single-line array/tuple literals compact
+
 ### Writing tests in Yo
 
 ```rust
-test "Basic assertion", {
+test("Basic assertion", {
   assert(((i32(1) + i32(1)) == i32(2)), "1+1 should be 2");
-};
+});
 
-test "Compile-time check", {
+test("Compile-time check", {
   comptime_assert((2 + 2) == 4);
   comptime_expect_error({ x :: (1 / 0); });
-};
+});
 
-test "Async test", {
-  { yield } :: import "std/async";
+test("Async test", {
+  { yield } :: import("std/async");
   io.await(yield());
-};
+});
 ```
 
-- `test "name", { body }` defines a test — `io : IO` is automatically available
+- `test("name", { body })` defines a test — `io : IO` is automatically available
 - All tests can use `io.async(...)`, `io.await(...)`, etc. without a `using` clause
 - `assert(condition, "message")` — always include a message string
 - `comptime_assert(expr)` — verified at compile time
@@ -147,7 +170,7 @@ yo test ./tests/main.test.yo --target wasm-wasi
 For projects that compile to WASM npm packages, use `target: build.CompilationTarget.Wasm32_Emscripten` and `add_c_flags(...)` for Emscripten settings:
 
 ```rust
-build :: import "std/build";
+build :: import("std/build");
 
 wasm_api :: build.executable({
   name: "my_lib_wasm_api",
@@ -191,7 +214,7 @@ yo doc --document-private            # Include non-exported items
 In `build.yo`:
 
 ```rust
-build :: import "std/build";
+build :: import("std/build");
 
 docs :: build.doc({ name: "docs", root: "./src" });
 doc_step :: build.step("doc", "Generate documentation");

package/.github/skills/yo-syntax/SKILL.md

@@ -31,26 +31,27 @@ Use this skill when you need to:
 - `cond(...)` and `match(...)` always require parentheses.
 - `{ expr }` is a struct literal; `{ expr; }` is a begin block.
 - Yo has no operator precedence. Parenthesize every binary operation.
-- Use `func(arg)` with no space before `(` for normal calls.
+- Use `func(arg)` with no space before `(` for every call; `func arg` and `func (arg)` are invalid.
+- Use `return(value)` / `return()` and `escape(value)` / `escape()`; bare control-flow arguments are invalid.
 - Use `recur(...)` for self-recursion instead of the function name.
 - Use `forall(T : Type)` for generic type parameters, `comptime(x) : T` for compile-time parameters.
 - Use `where(T <: Trait)` to constrain type parameters.
 - Use `using(name : Type)` for implicit/effect parameters and `given(name) := Type(...)` to install handlers.
 - Use `(params) => expr` for closures; `Impl(Fn(...) -> T)` for the closure type.
-- Every executable needs `export main;`.
+- Every executable needs `export(main);`.
 - Import sibling modules with relative paths like `./file.yo`.
 - Do not import `std/prelude`; it is loaded automatically.
 - Use `snake_case` for names, `PascalCase` for types/traits, 2-space indentation.
 
 ## Common traps
 
-- `return expr1, expr2` is parsed as one call; use a begin block or return an expression directly.
+- `return expr` is invalid; use `return(expr)` or `return()` for unit.
 - Nested patterns like `.Ok(.Some(x))` are not supported; match in stages.
-- Unary operators need parenthesized operands: `!(ready)`.
-- `while true` is compile-time. Use `while runtime(true), { ... }` for infinite runtime loops.
+- Unary operators need parenthesized operands: `!(ready)`, `&(value)`.
+- Use `while(true, { ... })` for infinite runtime loops; use `while(comptime(cond), { ... })` only for compile-time unrolling.
 - A single-expression lambda body should not be wrapped in `{ ... }` unless semicolons make it a begin block.
 - `"hello"` is `comptime_string` inside `comptime` functions, not `str`. In runtime code, `"hello"` is always `str`.
-- Functions called without `()` in match/cond branches consume trailing commas. Always add `()` or use begin blocks.
+- Calls in match/cond branches must use immediate `(...)`; this avoids trailing-comma ambiguity.
 
 ## Resource