Holiday is over, now I have fun again. No code changes. (0.38.11)

docs/README.md

@@ -19,6 +19,22 @@ This file serves as an index of the documents in this directory. Links are relat
 - [testing.md](./testing.md) — How to build and run tests/targets with CMake/CTest, and where to add new tests.
 - [troubleshooting.md](./troubleshooting.md) — Common issues and quick fixes for build, includes, and REPL usage.
 
+## New and supplemental guides
+
+- [build.md](./build.md) — How to build Fun with CMake, available targets, and build options (FUN_DEBUG, FUN_USE_MUSL, FUN_WITH_CPP, FUN_WITH_RUST).
+- [cli.md](./cli.md) — Command‑line usage of the `fun` executable: synopsis, options, exit codes, includes and library paths.
+- [contributing.md](./contributing.md) — How to contribute: project structure, coding style, running tests, and PR guidelines.
+- [style-guide.md](./style-guide.md) — Coding conventions for C and Fun (indentation, naming, idioms).
+- [stdlib.md](./stdlib.md) — Overview of the standard library modules under ./lib with one‑line summaries.
+- [embedding.md](./embedding.md) — Embedding the VM from C/Rust, lifecycle, and host integration tips.
+- [errors-and-diagnostics.md](./errors-and-diagnostics.md) — Understanding parser/runtime errors and enabling diagnostics.
+- [performance.md](./performance.md) — Build/runtime tuning tips and patterns for better performance.
+- [security-and-sandboxing.md](./security-and-sandboxing.md) — Trust boundaries, I/O expectations, and capability restrictions.
+- [faq.md](./faq.md) — Frequently asked questions and quick answers.
+- [writing-tests.md](./writing-tests.md) — How to author new tests for Fun and opcode components.
+- [bytecode-format.md](./bytecode-format.md) — Reference for the bytecode format (split out from internals for convenience).
+- [roadmap.md](./roadmap.md) — High‑level direction, planned features, and pointers to issues.
+
 ## Tips
 
 - When building from the repo without installing, set `FUN_LIB_DIR` to the local `./lib` directory so examples and the REPL can locate the stdlib.

docs/bytecode-format.md

@@ -0,0 +1,29 @@
+# Bytecode Format (Overview)
+
+This document summarizes the Fun bytecode format. For deep VM details, see `docs/internals.md`.
+
+## Goals
+- Compact representation for fast loading and dispatch
+- Stable header with room for versioning
+
+## File layout (typical)
+1. Header
+   - Magic number / signature
+   - Format version
+   - Flags (endianness, feature bits)
+   - Offsets to sections
+2. Constants table
+   - Literals: numbers, strings, compound constants
+3. Code section
+   - Functions/procedures with instruction streams
+   - Line/column mapping (optional for debugging)
+4. Auxiliary tables
+   - Imports/exports, names, debug info (optional)
+
+## Instructions
+- Fixed-size or small-variant opcodes grouped by domain (math, logic, stack, call, control flow, etc.).
+- Operands encoded inline following the opcode (width varies by instruction).
+
+## Versioning and compatibility
+- The header’s version field allows the VM to refuse or translate older/newer formats.
+- Keep additions backward-compatible when possible by appending sections or flags.

docs/cli.md

@@ -0,0 +1,38 @@
+# Fun CLI
+
+Reference for the `fun` command-line interface.
+
+## Synopsis
+```
+fun [options] <script.fun> [-- args...]
+```
+
+If no script is supplied and interactive mode is available, `fun` starts a REPL (see `docs/repl.md`).
+
+## Common options
+- `-i`, `--repl` — start an interactive REPL
+- `-v`, `--version` — print version and exit
+- `-h`, `--help` — show help and exit
+
+Options may vary between versions; run `fun --help` to see what your build supports.
+
+## Exit codes
+- `0` — success
+- non-zero — error during parse, compile, or runtime
+
+## Includes and library paths
+- `FUN_LIB_DIR` — environment variable that points to the stdlib location; when running from the repo, set this to `./lib`.
+- `DEFAULT_LIB_DIR` — compiled-in fallback path determined at build/install time.
+
+See also: `docs/includes.md` for namespaced includes and search order.
+
+## Examples
+Run a script:
+```
+FUN_LIB_DIR=./lib ./build_debug/fun examples/hello.fun
+```
+
+Start the REPL:
+```
+./build_debug/fun -i
+```

docs/contributing.md

@@ -0,0 +1,40 @@
+# Contributing to Fun
+
+Thanks for your interest in contributing! This guide covers the basics to get you productive quickly.
+
+## Getting started
+- Clone the repo and build (see `docs/build.md`).
+- Run tests locally (see `docs/testing.md`).
+- Explore examples (see `docs/examples.md`).
+
+## Project structure
+- `src/` — C core, VM, and opcode implementations (`src/vm/*`).
+- `lib/` — Standard library written in Fun.
+- `examples/` — Example programs and showcases.
+- `docs/` — Documentation.
+- `spec/` — Language specification drafts.
+
+## Code style
+- C: C99, two-space indent, no tabs. Keep functions short and focused.
+- Fun: two-space indent, snake_case for functions, PascalCase for classes/constructors.
+- Prefer clear names over abbreviations. See `docs/style-guide.md`.
+
+## Development workflow
+1. Create a small, focused branch.
+2. Add/adjust tests for behavior changes (see `docs/writing-tests.md`).
+3. Update docs if user-visible behavior changes.
+4. Submit a PR with a clear description and rationale.
+
+## Commit/PR guidelines
+- Keep commits atomic; include test updates with the change.
+- Reference related issues.
+- Include benchmarks only when meaningful and reproducible.
+
+## Reporting bugs
+Please include:
+- Reproducer script (minimal), expected vs. actual behavior
+- Build options and platform
+- `fun --version` output
+
+## Code of Conduct
+Be respectful and inclusive. See `CODE_OF_CONDUCT.md` in the repository root.

docs/embedding.md

@@ -0,0 +1,29 @@
+# Embedding Fun
+
+This guide outlines how to embed the Fun VM in a host application and extend it from C/Rust.
+
+## Overview
+- The VM is implemented in C (see `src/vm/`).
+- Optional Rust-based opcodes can be enabled via `FUN_WITH_RUST` (see `docs/rust.md`).
+
+## Embedding from C
+While the exact API surface may evolve, a typical embedding flow looks like:
+1. Initialize the VM/runtime and allocate a context.
+2. Load/compile Fun source or bytecode.
+3. Push arguments or set globals as needed.
+4. Execute entry function or script body.
+5. Retrieve results and clean up.
+
+See `src/vm/core` and related headers for public entry points and value types.
+
+### Hosting considerations
+- Threading: share VM state cautiously or create one VM per thread.
+- Memory: clarify ownership of strings/buffers crossing the boundary.
+- Errors: propagate parse/runtime errors back to the host with useful messages.
+
+## Extending with Rust
+When `FUN_WITH_RUST=ON`, a Rust static library from `src/rust/` is built and linked. You can:
+- Implement new opcodes/functions in Rust.
+- Expose a C ABI for the VM to call into.
+
+See `docs/rust.md` for details and example code.

docs/errors-and-diagnostics.md

@@ -0,0 +1,21 @@
+# Errors and Diagnostics
+
+This guide helps you understand common error messages and how to collect useful diagnostics.
+
+## Common error classes
+- Parse errors: syntax/indentation problems detected before execution.
+- Name/lookup errors: missing variables, functions, or modules.
+- Runtime errors: type mismatches, out-of-range access, invalid operations.
+
+## Enabling diagnostics
+- Build with `-DFUN_DEBUG=ON` to enable additional assertions and debug messages (see `docs/build.md`).
+- Run with smaller, focused scripts to isolate issues.
+
+## Getting useful reports
+- Capture the minimal script that reproduces the issue.
+- Note your build options and platform.
+- Record the full error output from the CLI (`fun`), including line/column if present.
+
+## Tips
+- Use prints or logging sparingly to narrow down failing code.
+- Start from a passing simple case and add complexity until it breaks.

docs/faq.md

@@ -0,0 +1,22 @@
+# FAQ
+
+Answers to common questions.
+
+## I built Fun but includes aren’t found
+Set `FUN_LIB_DIR` to the repository’s `./lib` directory when running without installation:
+```
+FUN_LIB_DIR=./lib ./build_debug/fun examples/hello.fun
+```
+See `docs/includes.md`.
+
+## How do I start the REPL?
+Run `fun -i` (or run `fun` without a script, depending on version). See `docs/repl.md`.
+
+## Which build target should I use?
+Use the aggregate `build` target to build `fun`, `fun_test`, and `test_opcodes`. See `docs/build.md`.
+
+## Where are the standard libraries?
+Under `./lib/`. See `docs/stdlib.md` for an overview.
+
+## Where can I find internals and opcodes?
+Browse `src/vm/` and `docs/internals.md` / `docs/opcodes.md`.

docs/performance.md

@@ -0,0 +1,21 @@
+# Performance Guide
+
+Tips for getting good performance from Fun programs and builds.
+
+## Build configuration
+- Use `-DCMAKE_BUILD_TYPE=Release` for production binaries.
+- Consider `FUN_DEBUG=OFF` to remove extra checks in hot paths.
+- `FUN_USE_MUSL=ON` can help with static/portable builds; measure performance for your use case.
+
+## Language-level tips
+- Prefer pre-sized arrays/maps when possible to reduce reallocations.
+- Avoid unnecessary string concatenations in loops; accumulate in arrays and `join`.
+- Push work to native ops where available (e.g., regex, JSON, math helpers).
+
+## Algorithmic choices
+- Choose appropriate data structures (arrays for ordered scans, maps for key lookups).
+- Cache repeated computations or lookups when safe.
+
+## Measuring
+- Create small, representative benchmarks.
+- Compare Debug vs. Release to ensure changes are meaningful.

docs/roadmap.md

@@ -0,0 +1,21 @@
+# Roadmap
+
+This page outlines high-level areas of focus and points to places where you can help.
+
+## Themes
+- Developer experience: docs, examples, REPL polish
+- Optional extensions: stabilize and document supported integrations
+- Performance: steady improvements in hot paths and data structures
+- Safety: clearer error messages, diagnostics, and sandboxing guidance
+
+## Near-term
+- Expand CLI reference and examples (`docs/cli.md`)
+- Improve testing docs and coverage (`docs/writing-tests.md`)
+- Fill gaps in stdlib documentation (`docs/stdlib.md`)
+
+## Medium-term
+- Bytecode/reference updates as internals evolve (`docs/bytecode-format.md`, `docs/internals.md`)
+- Embedding guides and host API stability (`docs/embedding.md`, `docs/rust.md`)
+
+## Contributing
+See `docs/contributing.md` for how to propose and implement items. Track concrete tasks via repository issues and PRs.

docs/security-and-sandboxing.md

@@ -0,0 +1,17 @@
+# Security and Sandboxing
+
+Understand the trust boundaries and how to run Fun code safely.
+
+## Trust model
+- By default, Fun code can access functionality exposed by the stdlib and any enabled extensions.
+- File and network access depend on available modules and host configuration.
+
+## Running untrusted code
+- Prefer running in a container/VM with restricted filesystem and network.
+- Limit available stdlib/modules by controlling `FUN_LIB_DIR` contents.
+- Use OS-level sandboxing (seccomp, AppArmor, SELinux, chroot) where applicable.
+
+## Best practices
+- Avoid running as root.
+- Validate and sanitize inputs at module boundaries.
+- Keep your build minimal; disable unneeded extensions at compile time.

docs/stdlib.md

@@ -0,0 +1,26 @@
+# Standard Library Overview
+
+This page provides a quick orientation to the standard library located under `./lib/`.
+
+The stdlib is written in Fun and organized by domain. Below are top-level modules and what they generally cover. Refer to the source for full APIs and examples.
+
+## Module index (selected)
+- `crypt/` — cryptographic helpers (hashing, encoding helpers). See also `lib/crypt`.
+- `encoding/` — text/binary encodings and conversions.
+- `io/` — file and stream utilities.
+- `net/` — basic networking helpers.
+- `regex/` — regular expression utilities (PCRE2 when available).
+- `ui/` — UI helpers (e.g., Tk if enabled at build time).
+- `utils/` — small reusable helpers and utilities.
+
+Note: Availability of some modules can depend on optional extensions selected at build time (see `docs/build.md`).
+
+## Using modules
+```fun
+include "utils/strings.fun" as strings
+
+let s = strings.trim("  hello  ")
+print(s)
+```
+
+For search paths and namespacing details, see `docs/includes.md` and `docs/cli.md` (FUN_LIB_DIR and DEFAULT_LIB_DIR).

docs/style-guide.md

@@ -0,0 +1,25 @@
+# Fun Style Guide
+
+Conventions for writing C and Fun code in this repository.
+
+## General principles
+- Two-space indentation. No tabs.
+- Keep lines reasonably short (~100 cols). Wrap thoughtfully.
+- Prefer explicit over implicit; favor clarity.
+
+## C (C99)
+- Indentation: two spaces, K&R-ish braces.
+- Naming: `snake_case` for functions and variables; `CAPS_SNAKE` for macros.
+- Error handling: return error codes or booleans; avoid hidden globals.
+- Headers: minimize includes in headers; forward-declare where practical.
+- Memory: clearly document ownership; free what you allocate.
+
+## Fun language
+- Indentation: two spaces.
+- Naming: `snake_case` for functions/variables; `PascalCase` for classes/constructors.
+- Modules: one primary concept per file; export a minimal, cohesive API.
+- Idioms: prefer arrays and maps over ad-hoc structures; keep functions small.
+
+## Formatting and tools
+- No auto-formatters required; follow these simple rules.
+- Keep diffs small and focused; avoid reformat-only commits.

docs/writing-tests.md

@@ -0,0 +1,24 @@
+# Writing Tests
+
+How to author tests for Fun and its opcode implementations.
+
+## Test kinds
+- VM/opcode tests: exercise bytecode operations and VM behavior (target: `test_opcodes`).
+- Language/runtime tests: exercise user-visible features and stdlib behavior (target: `fun_test`).
+
+See `docs/testing.md` for how to build and run these targets with CTest.
+
+## Adding new tests
+The exact layout may evolve; generally:
+- Add new test sources alongside existing ones used by `fun_test`.
+- For opcode-focused tests, add cases where `test_opcodes` discovers them.
+
+Aim for:
+- Small, isolated test cases with clear assertions
+- One behavior per test; descriptive names
+- Minimal fixtures and setup
+
+## Guidelines
+- Prefer black-box testing via public APIs.
+- When adding features, include both positive and negative cases.
+- Keep tests deterministic; avoid non-deterministic timers or random sources unless seeded.