Refine onboarding tutorial and prioritize it in README

Author: pchalamet

README.md

@@ -32,7 +32,26 @@ FScript currently includes:
 - interpolation, pipeline operator, `typeof` type tokens, and `nameof` identifier tokens for host workflows.
 - unified brace literals for records/maps (`{ Field = value }`, `{ [key] = value }`, `{}` for empty map), with map keys typed as `string` or `int`.
 
-## Quick Start
+## Getting Started Tutorial
+
+If you are new to FScript, start with the progressive tutorial:
+
+- [`docs/getting-started-tutorial.md`](docs/getting-started-tutorial.md)
+
+It covers installation, syntax basics, flow control, collections, pattern matching, stdlib usage, includes, and host/export concepts.
+
+## Installation
+
+### CLI via Homebrew
+```bash
+brew install magnusopera/tap/fscript
+```
+
+### Embeddable language via NuGet
+- `MagnusOpera.FScript.Language`
+- `MagnusOpera.FScript.Runtime`
+
+## Repository Development
 
 ### Build
 ```bash
@@ -61,17 +80,6 @@ Useful samples:
 - [`samples/mutual-recursion.fss`](samples/mutual-recursion.fss)
 - [`samples/includes-and-exports.fss`](samples/includes-and-exports.fss)
 
-## Installation
-
-### CLI via Homebrew
-```bash
-brew install magnusopera/tap/fscript
-```
-
-### Embeddable language via NuGet
-- `MagnusOpera.FScript.Language`
-- `MagnusOpera.FScript.Runtime`
-
 ## Interpreter Architecture
 
 The core engine lives in `src/FScript.Language` and runs in four stages:
@@ -110,7 +118,6 @@ See [`docs/sandbox-and-security.md`](docs/sandbox-and-security.md) for the full
 
 ## Documentation
 
-- [`docs/getting-started-tutorial.md`](docs/getting-started-tutorial.md)
 - [`docs/syntax-and-indentation.md`](docs/syntax-and-indentation.md)
 - [`docs/supported-types.md`](docs/supported-types.md)
 - [`docs/function-annotations.md`](docs/function-annotations.md)

docs/getting-started-tutorial.md

@@ -204,6 +204,14 @@ let describe items =
   | _ -> "empty"
 ```
 
+### Tuple
+```fsharp
+let describePair pair =
+  match pair with
+  | ("ok", code) -> $"success:{code}"
+  | (kind, code) -> $"{kind}:{code}"
+```
+
 ### Record
 ```fsharp
 let cityLabel address =
@@ -339,8 +347,11 @@ Notes:
 - include cycles are fatal,
 - modules are supported in included files.
 
-## 11. Export functions for host integration
-Mark top-level bindings with `[<export>]` when a host must discover them.
+## 11. Hosting, exports, and sandboxing (advanced)
+FScript is designed to be embedded.
+At host boundary, scripts can expose explicit entry points while the host controls capabilities and security.
+
+Mark top-level bindings with `[<export>]` when a host must discover them:
 
 ```fsharp
 [<export>] let dispatch (context: { Command: string }) =
@@ -352,19 +363,20 @@ Mark top-level bindings with `[<export>]` when a host must discover them.
 }
 ```
 
-## 12. Security mindset and Hosting
-FScript core evaluation is pure in-memory computation.
-Side effects depend on host-exposed functions.
+Security/hosting teaser:
+- core FScript evaluation is pure in-memory computation,
+- side effects exist only through host-exposed externs,
+- sandboxing is enforced by host decisions (filesystem root, allowed functions, execution controls).
 
-When embedding:
+When embedding, keep this mindset:
 - expose only needed externs,
 - keep filesystem/network boundaries explicit,
 - use host-level timeout/cancellation/resource limits.
-- see [`docs/embedding-fscript-language.md`](./embedding-fscript-language.md) for host integration API,
-- see [`docs/external-functions.md`](./external-functions.md) for extern design and registration.
-- see [`docs/sandbox-and-security.md`](./sandbox-and-security.md) for security model and host responsibilities.
+- see [`docs/embedding-fscript-language.md`](./embedding-fscript-language.md) for the embedding API,
+- see [`docs/external-functions.md`](./external-functions.md) for extern design/registration,
+- see [`docs/sandbox-and-security.md`](./sandbox-and-security.md) for the full security model.
 
-## 13. Next steps
+## 12. Next steps
 - Sample scripts:
   - [`samples/types-showcase.fss`](../samples/types-showcase.fss)
   - [`samples/patterns-and-collections.fss`](../samples/patterns-and-collections.fss)