Some more documentation fun. No code changes. (0.38.11)

docs/examples.md

@@ -0,0 +1,62 @@
+# Running the Examples
+
+This page shows how to run the example programs included with the repository and how to use the interactive showcase script.
+
+All commands assume you are in the repository root.
+
+## Prerequisites
+
+- Build the interpreter (see handbook.md). You’ll have `build_debug/fun` or `build_release/fun` (paths may vary by your setup/IDE).
+- Set FUN_LIB_DIR to the repo’s lib directory when running without installation so `#include <...>` can find the standard library.
+
+Example (Linux/macOS/BSD):
+
+```
+FUN_LIB_DIR="$(pwd)/lib" ./build_debug/fun examples/include_lib.fun
+```
+
+Windows (PowerShell):
+
+```
+$env:FUN_LIB_DIR = "$PWD/lib"
+./build_release/fun.exe .\examples\include_lib.fun
+```
+
+## Interactive showcase: play.fun
+
+The script `./play.fun` discovers all `.fun` files under `./examples` and offers to run them one by one:
+
+```
+./play.fun
+```
+
+Notes:
+- The script auto-picks your interpreter (FUN_BIN env or `fun` in PATH) and ensures `FUN_LIB_DIR=./lib` so examples resolve includes correctly.
+- It shows the exit code for each run and summarizes failures at the end.
+
+Tip: you can run specific examples directly too:
+
+```
+FUN_LIB_DIR="$(pwd)/lib" fun examples/crypto/aes256.fun
+```
+
+## Example categories
+
+Browse the `examples/` tree for areas of interest:
+
+- crypto — crypto demonstrations (e.g., AES)
+- blocking / interactive — I/O or user-interactive patterns
+- error / broken — negative tests and error showcases
+- math — numeric operations
+- sqlited / data — data access and HTTP/CGI-style samples (platform dependent)
+
+## Creating your own examples
+
+Place your `.fun` files anywhere under `examples/` to have them picked up by `play.fun`. Use quoted includes for project-local helpers and angle brackets for stdlib modules:
+
+```
+#include "examples/my_lib/common.fun"
+#include <io/console.fun>
+```
+
+If you add an example showcasing a new feature, also consider adding a brief note to the relevant doc (types.md, includes.md, opcodes.md, etc.).