Update docs for unwrap operators (! ?? ?) and From removal

Author: O6lvl4

src/content/docs/getting-started/introduction.md

@@ -60,7 +60,7 @@ fn area(s: Shape) -> Float =
 
 // Effect function — can fail, can do I/O
 effect fn read_config(path: String) -> Result[String, String] = {
-  let content = fs.read_text(path)
+  let content = fs.read_text(path)!
   ok(content)
 }
 ```

src/content/docs/guide/error-handling.md

@@ -1,9 +1,9 @@
 ---
 title: Error Handling
-description: Result, Option, effect fn auto-propagation, guard, and deriving From for error conversion.
+description: Result, Option, unwrap operators (!, ??, ?), effect fn, and guard for safe error handling.
 ---
 
-Almide has no exceptions. All errors are values, represented by `Result[T, E]` and `Option[T]`. The `effect fn` system automates error propagation, making error handling both safe and concise.
+Almide has no exceptions. All errors are values, represented by `Result[T, E]` and `Option[T]`. Three postfix operators -- `!`, `??`, and `?` -- provide concise, explicit control over unwrapping.
 
 ## Result
 
@@ -50,21 +50,90 @@ let upper = option.map(map.get(config, "name"), (s) => string.to_upper(s))
 let result = option.to_result(map.get(config, "name"), "name is required")
 ```
 
-## effect fn and auto-propagation
+## Unwrap operators: `!`, `??`, `?`
 
-The key to ergonomic error handling in Almide is `effect fn`. Inside an `effect fn`, expressions returning `Result[T, E]` are automatically unwrapped:
+Almide provides three postfix operators for unwrapping `Result` and `Option` values. These are the primary way to work with fallible values.
+
+### `!` — propagate error
+
+`expr!` unwraps a `Result` or `Option`. If the value is `err(e)` or `none`, the enclosing `effect fn` immediately returns the error. Only valid inside `effect fn`.
 
 ```almide
 effect fn load_config(path: String) -> Result[String, String] = {
-  let text = fs.read_text(path)     // Result auto-unwrapped; error propagates
-  let trimmed = string.trim(text)   // text is String, not Result
+  let text = fs.read_text(path)!      // unwrap or propagate error
+  let trimmed = string.trim(text)
   ok(trimmed)
 }
 ```
 
-Without `effect fn`, you would need to manually match on every `Result`. The compiler inserts error propagation automatically.
+On `Option`:
+
+```almide
+effect fn first_name(users: List[User]) -> Result[String, String] = {
+  let user = list.first(users)!       // none becomes err, propagated
+  ok(user.name)
+}
+```
+
+### `??` — fallback value
+
+`expr ?? fallback` unwraps with a default. If the value is `err(_)` or `none`, the fallback is used instead. Valid anywhere (not limited to `effect fn`).
+
+```almide
+let port = int.parse(port_str) ?? 8080
+let name = map.get(env, "USER") ?? "anonymous"
+```
+
+### `?` — convert to Option
+
+`expr?` converts a `Result[T, E]` to `Option[T]`, discarding the error. On `Option`, it is a passthrough. Valid anywhere.
+
+```almide
+let parsed = int.parse(input)?        // Result[Int, String] -> Option[Int]
+let found = map.get(config, "key")?   // Option[String] -> Option[String] (passthrough)
+```
+
+### Summary table
+
+| Operator | On Result | On Option | Valid in |
+|----------|-----------|-----------|----------|
+| `expr!` | `ok(v)` -> `v`, `err(e)` -> propagate | `some(v)` -> `v`, `none` -> propagate | `effect fn` only |
+| `expr ?? fallback` | `ok(v)` -> `v`, `err(_)` -> `fallback` | `some(v)` -> `v`, `none` -> `fallback` | Anywhere |
+| `expr?` | `ok(v)` -> `some(v)`, `err(_)` -> `none` | Passthrough | Anywhere |
+
+## effect fn
+
+Functions with side effects use `effect fn`. The `!` operator is the standard way to propagate errors inside an `effect fn`:
+
+```almide
+effect fn process(path: String) -> Result[String, String] = {
+  let text = fs.read_text(path)!          // propagate on error
+  let data = json.parse(text)!            // propagate on error
+  ok(data)
+}
+```
+
+Without `!`, you would need to manually match on every `Result`.
 
-The rule is simple: if any expression in an `effect fn` body evaluates to `err(e)`, the entire function immediately returns that error.
+## Error type conversion with map_err
+
+When different functions return different error types, use `result.map_err` combined with `!` to convert errors:
+
+```almide
+type AppError =
+  | Io(String)
+  | Parse(String)
+
+effect fn load(path: String) -> Result[Config, AppError] = {
+  let text = fs.read_text(path)
+    |> result.map_err(_, (e) => Io(e))!
+  let raw = json.parse(text)
+    |> result.map_err(_, (e) => Parse(e))!
+  ok(parse_config(raw))
+}
+```
+
+This pattern replaces the former `From` convention with explicit, visible error conversion.
 
 ## guard
 
@@ -88,35 +157,12 @@ effect fn process(path: String) -> Result[Unit, String] = {
     println("file not found, skipping")
     ok(())
   }
-  let content = fs.read_text(path)
+  let content = fs.read_text(path)!
   println(content)
   ok(())
 }
 ```
 
-## Error types with deriving From
-
-For applications with multiple error sources, define a variant error type with `deriving From`:
-
-```almide
-type AppError =
-  | Io(IoError)
-  | Parse(ParseError)
-  deriving From
-```
-
-`deriving From` generates automatic conversions from each inner error type to the variant. This enables seamless error propagation across different error types:
-
-```almide
-effect fn load(path: String) -> Result[Config, AppError] = {
-  let text = fs.read_text(path)       // IoError -> AppError::Io (automatic)
-  let raw = json.parse(text)          // ParseError -> AppError::Parse (automatic)
-  ok(parse_config(raw))
-}
-```
-
-Without `deriving From`, you would need to manually wrap each error.
-
 ## Three-layer error strategy
 
 | Layer | Mechanism | Use case |
@@ -153,16 +199,16 @@ effect fn create_user(name: String, age: Int) -> Result[User, String] = {
 }
 ```
 
-### unwrap_or for defaults
+### `??` for defaults
 
 When a missing value has a sensible default:
 
 ```almide
-let port = result.unwrap_or(int.parse(port_str), 8080)
-let name = option.unwrap_or(map.get(env, "USER"), "anonymous")
+let port = int.parse(port_str) ?? 8080
+let name = map.get(env, "USER") ?? "anonymous"
 ```
 
-### and_then for chaining
+### flat_map for chaining
 
 When each step can fail and depends on the previous:
 

src/content/docs/guide/functions.md

@@ -38,7 +38,7 @@ Functions with side effects (I/O, network, randomness) must be marked `effect fn
 
 ```almide
 effect fn save(path: String, content: String) -> Result[Unit, String] = {
-  fs.write(path, content)
+  fs.write(path, content)!
   ok(())
 }
 ```
@@ -47,7 +47,7 @@ The `effect` modifier enforces a strict boundary:
 
 - Calling an `effect fn` from a non-effect function is a **compile error**
 - `effect fn` typically returns `Result[T, E]`
-- Inside `effect fn`, `Result` values are automatically unwrapped and errors propagate
+- Use the `!` operator to unwrap `Result` values and propagate errors explicitly
 
 ```almide
 fn pure() -> String =
@@ -57,7 +57,7 @@ effect fn safe() -> Result[String, String] =
   fs.read_text("file.txt")    // OK: effect fn calling effect fn
 ```
 
-See [Error Handling](/docs/guide/error-handling/) for auto-propagation details.
+See [Error Handling](/docs/guide/error-handling/) for the `!`, `??`, and `?` operators.
 
 ## Parameters
 
@@ -227,5 +227,5 @@ list.get(args, 1) |> match {
 ## Next steps
 
 - [Control Flow](/docs/guide/control-flow/) — if, for, while, guard
-- [Error Handling](/docs/guide/error-handling/) — Result, Option, effect fn propagation
+- [Error Handling](/docs/guide/error-handling/) — Result, Option, unwrap operators, effect fn
 - [Modules & Imports](/docs/guide/modules/) — organizing code across files

src/content/docs/guide/types.md

@@ -63,7 +63,7 @@ let b = true or false     // true
 let c = not true          // false
 ```
 
-There is no `!`, `&&`, or `||`. The compiler rejects them with helpful hints.
+There is no `&&` or `||`. Use `and`, `or`, and `not` for boolean logic. (The postfix `!` is the unwrap operator, not boolean negation.)
 
 ## Unit
 
@@ -199,7 +199,7 @@ match int.parse(input) {
 }
 ```
 
-See [Error Handling](/docs/guide/error-handling/) for `effect fn` auto-propagation and `guard`.
+See [Error Handling](/docs/guide/error-handling/) for `effect fn`, unwrap operators (`!`, `??`, `?`), and `guard`.
 
 ## Record types
 
@@ -321,17 +321,13 @@ fn apply(f: Fn(Int) -> Int, x: Int) -> Int = f(x)
 Types can derive built-in conventions using `:` after the type name:
 
 ```almide
-type AppError: From =
-  | Io(IoError)
-  | Parse(ParseError)
-
 type Color: Eq =
   | Red
   | Green
   | Blue
 ```
 
-This generates implementations automatically. Available conventions: `Eq`, `Repr`, `Ord`, `Hash`, `Codec`, `From`. See [Error Handling](/docs/guide/error-handling/) and [Protocols](/docs/guide/protocols/) for details.
+This generates implementations automatically. Available conventions: `Eq`, `Repr`, `Ord`, `Hash`, `Codec`. See [Protocols](/docs/guide/protocols/) for details.
 
 ## Built-in protocols
 

src/content/docs/reference/cheatsheet.md

@@ -22,7 +22,6 @@ type Name = Type                                     // type alias
 type Handler = (String) -> String                    // function type alias
 type ConfigError =
   | Io(IoError) | Parse(ParseError)
-  deriving From                                      // auto From conversion
 ```
 
 **Built-in types:** `Int`, `Float`, `String`, `Bool`, `Unit`, `Path`, `List[T]`, `Map[K, V]`, `Set[T]`, `Result[T, E]`, `Option[T]`
@@ -124,9 +123,33 @@ test "description" {
 
 No `print` function. Use `println` for all output.
 
+## Unwrap Operators
+
+```almd
+expr!                          // propagate error (effect fn only)
+expr ?? fallback               // unwrap with default
+expr?                          // Result -> Option (discard error)
+```
+
+```almd
+effect fn load(path: String) -> Result[String, String] = {
+  let text = fs.read_text(path)!        // propagate on err
+  ok(text)
+}
+let port = int.parse(s) ?? 8080         // fallback
+let name = map.get(env, "USER") ?? "anonymous"
+let parsed = int.parse(input)?          // Option[Int]
+```
+
+Error type conversion (replaces `From`):
+
+```almd
+fs.read_text(path) |> result.map_err(_, (e) => Io(e))!
+```
+
 ## Operators (precedence high to low)
 
-`. ()` > `not -` > `^` > `* / %` > `+ -` > `.. ..=` > `== != < > <= >=` > `and` > `or` > `|> >>`
+`. () [] ! ?? ?` > `not -` > `^` > `* / %` > `+ -` > `.. ..=` > `== != < > <= >=` > `and` > `or` > `|> >>`
 
 ## Stdlib Modules
 
@@ -139,7 +162,8 @@ No `print` function. Use `println` for all output.
 - Newline = statement separator (no semicolons needed)
 - `[]` for generics, NOT `<>`
 - `effect fn` for side effects, NOT `fn name!()`
-- `?` suffix is for Bool predicates only
+- `fn name?()` suffix is for Bool predicates only
+- Postfix `!` / `??` / `?` are unwrap operators (see above)
 - No exceptions -- use `Result[T, E]`
 - No null -- use `Option[T]`
 - No inheritance, no macros, no operator overloading, no implicit conversions
@@ -166,7 +190,7 @@ No `print` function. Use `println` for all output.
 effect fn main(args: List[String]) -> Result[Unit, AppError] = {
   let cmd = list.get(args, 1)
   match cmd {
-    some("run") => do_something(),
+    some("run") => do_something()!,
     some(other) => err(UnknownCommand(other)),
     none => err(NoCommand),
   }

src/content/docs/reference/operators.md

@@ -9,7 +9,7 @@ Operators are listed from highest precedence (binds tightest) to lowest.
 
 | Precedence | Operators | Associativity | Description |
 |:---:|---|---|---|
-| 1 | `. ()` `[]` | Left | Member access, function call, index |
+| 1 | `. ()` `[]` `!` `??` `?` | Left | Member access, call, index, unwrap ops |
 | 2 | `not` `-` (unary) | Right | Boolean negation, numeric negation |
 | 3 | `^` | Right | Exponentiation (power) |
 | 4 | `*` `/` `%` | Left | Multiplication, division, modulo |
@@ -22,7 +22,7 @@ Operators are listed from highest precedence (binds tightest) to lowest.
 
 ## Detailed Reference
 
-### Member Access and Calls (`. ()` `[]`)
+### Member Access, Calls, and Unwrap (`. ()` `[]` `!` `??` `?`)
 
 ```almd
 user.name                      // field access
@@ -31,14 +31,32 @@ xs[0]                          // index read
 xs[i] = value                  // index write (var only)
 ```
 
+#### Unwrap operators
+
+Three postfix operators for unwrapping `Result` and `Option` values:
+
+```almd
+fs.read_text(path)!            // unwrap or propagate error (effect fn only)
+int.parse(s) ?? 0              // unwrap with fallback value
+int.parse(s)?                  // convert Result to Option (discard error)
+```
+
+| Operator | On Result | On Option | Valid in |
+|----------|-----------|-----------|----------|
+| `expr!` | `ok(v)` -> `v`, `err(e)` -> propagate | `some(v)` -> `v`, `none` -> propagate | `effect fn` only |
+| `expr ?? fallback` | `ok(v)` -> `v`, `err(_)` -> `fallback` | `some(v)` -> `v`, `none` -> `fallback` | Anywhere |
+| `expr?` | `ok(v)` -> `some(v)`, `err(_)` -> `none` | Passthrough | Anywhere |
+
+See [Error Handling](/docs/guide/error-handling/) for detailed examples.
+
 ### Unary Operators (`not`, `-`)
 
 ```almd
 not active                     // boolean negation
 -x                             // numeric negation
 ```
 
-There is no `!` operator. Use `not` for boolean negation.
+There is no boolean `!` operator. Use `not` for boolean negation. The postfix `!` is the unwrap/propagate operator.
 
 ### Exponentiation (`^`)