Update Beam docs for rebar3 scaffold generation

Ref: fable-compiler/Fable#4387

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dbrattli

docs/docs/beam/build-and-run.md

@@ -7,9 +7,10 @@ layout: standard
     Added in v5.0.0-rc.1
 </p>
 
-## Erlang/OTP Version
+## Prerequisites
 
-Fable targets Erlang/OTP 25 or higher.
+- [Erlang/OTP](https://www.erlang.org/downloads) 25 or higher
+- [rebar3](https://rebar3.org/) (the standard Erlang build tool)
 
 ## Architecture
 
@@ -27,7 +28,7 @@ Erlang AST
 .erl source files
 ```
 
-The generated `.erl` files are standard Erlang that can be compiled with `erlc` and run on the BEAM VM.
+The generated `.erl` files are standard Erlang that can be compiled with rebar3 and run on the BEAM VM.
 
 ## Compiling to Erlang
 
@@ -43,42 +44,52 @@ dotnet fable --lang beam --outDir /path/to/output
 
 ## Output Structure
 
-The output directory will contain:
+Fable automatically generates a complete [rebar3](https://rebar3.org/) project scaffold alongside the compiled `.erl` files. The output directory will contain:
 
 ```text
 output/
-  program.erl                              # Your compiled F# modules
+  rebar.config                             # rebar3 project config (auto-generated)
+  src/
+    program.erl                            # Your compiled F# modules
+    my_project.app.src                     # OTP application resource file
   fable_modules/
     fable-library-beam/
-      fable_list.erl                       # F# List runtime
-      fable_map.erl                        # F# Map runtime
-      fable_string.erl                     # String utilities
-      fable_seq.erl                        # Seq/IEnumerable support
-      ...                                  # Other runtime modules
+      rebar.config                         # Per-dependency rebar3 config
+      src/
+        fable_library_beam.app.src         # OTP app resource for the library
+        fable_list.erl                     # F# List runtime
+        fable_map.erl                      # F# Map runtime
+        fable_string.erl                   # String utilities
+        fable_seq.erl                      # Seq/IEnumerable support
+        ...                                # Other runtime modules
 ```
 
-## Compiling Erlang
+### Rebar3 Scaffold Details
 
-After Fable generates `.erl` files, compile them with `erlc`:
+— if you create your own `rebar.config` (without the Fable marker), it will be left untouched (a warning is emitted)
+— project and dependency names are normalized to valid OTP application names (e.g., `Fable.Logging.0.10.0` → `fable_logging`, `fable-library-beam` → `fable_library_beam`)
+— the generated `rebar.config` uses `{project_app_dirs, [".", "fable_modules/*"]}` so rebar3 treats each NuGet dependency as a sub-application
 
-```bash
-# Compile the runtime library
-erlc -o output/fable_modules/fable-library-beam output/fable_modules/fable-library-beam/*.erl
+## Compiling with rebar3
+
+After Fable generates the scaffold, compile everything with rebar3:
 
-# Compile your project files
-erlc -pa output/fable_modules/fable-library-beam -o output output/*.erl
+```bash
+rebar3 compile
 ```
 
+This compiles all `.erl` files (your project and all dependencies) and places `.beam` files in `_build/default/lib/*/ebin/`.
+
 ## Running Erlang Code
 
 Run your compiled module using the Erlang shell:
 
 ```bash
-erl -pa output -pa output/fable_modules/fable-library-beam \
-    -noshell -eval 'program:main(), halt().'
+erl -noshell -pa _build/default/lib/*/ebin \
+    -eval 'program:main(), halt().'
 ```
 
-The `-pa` flag adds directories to the code path so Erlang can find both your modules and the Fable runtime library.
+The `-pa` flag adds the rebar3 output directories to the code path so Erlang can find both your modules and the Fable runtime library.
 
 ## Module Naming
 

docs/docs/getting-started/beam.md

@@ -15,10 +15,11 @@ Please make sure you followed the [Fable setup guide](/docs/2-steps/your-first-f
 
 ## Prerequisites
 
-You need [Erlang/OTP](https://www.erlang.org/downloads) 24 or higher installed. Verify with:
+You need [Erlang/OTP](https://www.erlang.org/downloads) 25 or higher and [rebar3](https://rebar3.org/) installed. Verify with:
 
 ```bash
 erl -eval 'erlang:display(erlang:system_info(otp_release)), halt().' -noshell
+rebar3 version
 ```
 
 <ul class="textual-steps">
@@ -31,17 +32,16 @@ Compile your project to Erlang:
 dotnet fable --lang beam
 ```
 
-This generates `.erl` files in the project directory (where the `.fsproj` is) by default.
+Fable generates `.erl` files in `src/` subdirectories and automatically creates a [rebar3](https://rebar3.org/) project scaffold (`rebar.config`, `.app.src` files).
 
 </li>
 
 <li>
 
-Compile the generated Erlang files:
+Compile the generated Erlang files with rebar3:
 
 ```bash
-erlc -o output/fable_modules/fable-library-beam output/fable_modules/fable-library-beam/*.erl
-erlc -pa output/fable_modules/fable-library-beam -o output output/*.erl
+rebar3 compile
 ```
 
 </li>
@@ -51,7 +51,7 @@ erlc -pa output/fable_modules/fable-library-beam -o output output/*.erl
 Run your code:
 
 ```bash
-erl -pa output -pa output/fable_modules/fable-library-beam -noshell -eval 'program:main(), halt().'
+erl -noshell -pa _build/default/lib/*/ebin -eval 'program:main(), halt().'
 ```
 
 </li>