#566 Improve documentation and Leaf Book

.devcontainer/devcontainer.json.example

@@ -43,7 +43,6 @@
 				"fill-labs.dependi",
 				"vadimcn.vscode-lldb",
 				"streetsidesoftware.code-spell-checker",
-				"GitHub.copilot",
 				"GitHub.copilot-chat",
 				"GitHub.vscode-pull-request-github",
 			],

.gitignore

@@ -37,7 +37,6 @@ samples/**/main
 # Performance test results
 *.bench
 *.data
-*.svg
 
 scripts/**/out
 scripts/**/work

.vscode/extensions.json

@@ -12,7 +12,6 @@
         "phil294.git-log--graph",
         // Experience
         "streetsidesoftware.code-spell-checker",
-        "GitHub.copilot",
         "GitHub.copilot-chat",
         "GitHub.vscode-pull-request-github",
         "alefragnani.Bookmarks",

README.md

@@ -1,4 +1,5 @@
 # Leaf
+<img class="right" src="docs/book/src/assets/LeafLogo.svg" style="width:10em" alt="The Leaf logo">
 
 Leaf is a Rust-oriented framework for dynamic analysis built around MIR instrumentation. It wraps the Rust compiler through `leafc`, instruments a program at compile time, and routes runtime events to pluggable backends for tracing, symbolic execution, and related analyses.
 
@@ -49,8 +50,11 @@ The generated program will emit runtime events through the active backend, which
 
 ## Documentation
 
-Further information, tutorials, and technical details are collected in Leaf Book hosted at:
-[sfu-rsl.github.io/leaf](https://sfu-rsl.github.io/leaf).
+Further information, tutorials, and technical details are collected in Leaf Book @
+[sfu-rsl.github.io/leaf](https://sfu-rsl.github.io/leaf) (WIP).
+
+## Publications
+- Leaf: An Instrumentation-based Dynamic Analysis Framework for Rust: [arXiv](https://arxiv.org/abs/2607.15025)
 
 ## License
 

docs/.gitignore

@@ -1 +1,2 @@
-book
+.agents
+.github/agents

docs/README.md

@@ -0,0 +1,11 @@
+# Leaf Documentation
+
+## Note on Agents
+We encourage using agents for writing the documentation. However, as there is not a consensus over how to have them in a repo, we currently do not commit them.
+
+The following agents and skills are recommended to be installed.
+- `sfu-rsl/leaf_dev_plugin_marketplace/agents/leaf-book-maintainer.agent.md`
+- `sfu-rsl/leaf_dev_plugin_marketplace/skills/framework-digestion`
+- `sfu-rsl/leaf_dev_plugin_marketplace/skills/sfu-rsl-leaf-main-en-skill`
+- `awesome-copilot/documentation-writer`
+- `anthropics/skills/doc-coauthoring`

docs/book/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml → docs/book/book.toml

@@ -5,3 +5,6 @@ title = "Leaf Book"
 
 [output.html]
 git-repository-url = "https://github.com/sfu-rsl/leaf"
+
+[output.html.playground]
+runnable = false

docs/book/src/SUMMARY.md

@@ -0,0 +1,35 @@
+# Summary
+
+- [Leaf](./leaf.md)
+- [Introduction](./intro.md)
+
+# Tutorials
+
+- [First Dynamic Analysis with Leaf](./tutorials/first_dynamic_analysis.md)
+- [Write a Counter Backend](./tutorials/write_a_backend.md)
+
+# How-to Guides
+
+- [Build a Cargo Package with Leaf](./how-to/cargo.md)
+- [Generate Diverging Input](./how-to/div_input.md)
+- [Run Fuzzing with Leaf](./how-to/fuzzing.md)
+
+# Explanations
+
+- [Leaf's execution model]()
+- [MIR, runtime facts, and DMIR]()
+- [How MIR instrumentation becomes runtime events]()
+- [How analysis callbacks receive and transform events]()
+- [Runtime support utilities and shared services]()
+- [Dependency instrumentation and build strategy]()
+
+# Reference
+
+- [Compiler]()
+- [Runtime]()
+- [Orchestrator]()
+- [DMIR]()
+- [Configuration]()
+- [MIR Intrinsics]()
+- [Samples](./reference/samples.md)
+- [Glossary]()

docs/book/src/explanations/callbacks.md

@@ -0,0 +1 @@
+# How analysis callbacks receive and transform events

docs/book/src/explanations/dependencies.md

@@ -0,0 +1 @@
+# Dependency instrumentation and build strategy

docs/book/src/explanations/dmir.md

@@ -0,0 +1 @@
+# MIR, runtime facts, and DMIR

docs/book/src/explanations/execution-model.md

@@ -0,0 +1 @@
+# Leaf's execution model

docs/book/src/explanations/instrumentation.md

@@ -0,0 +1 @@
+# How MIR instrumentation becomes runtime events

docs/book/src/explanations/runtime-support.md

@@ -0,0 +1 @@
+# Runtime support utilities and shared services

docs/src/user_guide/recipes/cargo.md → docs/book/src/how-to/cargo.md

@@ -1,4 +1,4 @@
-# Building Cargo Packages
+# Build a Cargo Package with Leaf
 
 As mentioned before, you can look at `leafc` as a wrapper around `rustc` and
 it should be work in any command using `rustc`.

docs/src/user_guide/recipes/div_input.md → docs/book/src/how-to/div_input.md

@@ -64,4 +64,4 @@ To run pure concolic testing loop for a target:
     ```
 1. The loop stops if no more new distinct input is found to be given to the program (can possibly run forever).
 
-We recommend looking at the options available for tuning the loop by passing `--help`.
+We recommend looking at the options available for tuning the loop by passing `--help`.

docs/book/src/intro.md

@@ -0,0 +1,18 @@
+# Introduction
+
+Leaf is a framework for dynamic analysis of Rust programs built around MIR instrumentation. Instead of analyzing source code directly, Leaf compiles a program through `leafc`, rewrites the relevant MIR, and runs the resulting binary with a runtime backend attached.
+
+That split keeps the responsibilities clear:
+
+- the compiler frontend prepares the program for analysis,
+- the runtime receives execution events and records or reacts to them, and
+- higher-level tooling can orchestrate repeated runs or more advanced workflows.
+
+At a high level, the workflow looks like this:
+
+1. write or choose a Rust program,
+2. compile it with Leaf’s instrumentation pipeline,
+3. run the instrumented binary with the desired backend, and
+4. inspect the emitted traces or analysis results.
+
+This book starts with a practical getting-started guide, then moves into recipes and configuration details for common workflows. Use it as a reference when you need to understand how Leaf’s compiler, runtime, and orchestration pieces fit together.

docs/book/src/leaf.md

@@ -0,0 +1,9 @@
+# Leaf
+<img class="right" src="assets/LeafLogo.svg" style="width:10em" alt="The Leaf logo">
+
+Welcome to project Leaf, a tool to dynamic analysis for Rust programs by MIR instrumentation.
+
+Leaf aims to be robust, extensible, and easily-integrable within real world Rust testing stacks.
+
+Please refer to [Introduction](./intro.md) for more details about the workflow of the tool,
+and try to perform your [first dynamic analysis with Leaf](./tutorials/first_dynamic_analysis.md) to get a hands-on experience.

docs/book/src/reference/compiler.md

@@ -0,0 +1 @@
+# Compiler Reference

docs/book/src/reference/configuration.md

@@ -0,0 +1,3 @@
+# Configuration Reference
+
+This page will be written later.

docs/book/src/reference/dmir-callback.md

@@ -0,0 +1 @@
+# DMIR

docs/book/src/reference/dmir.md

@@ -0,0 +1 @@
+# DMIR Reference

docs/book/src/reference/glossary.md

@@ -0,0 +1 @@
+# Glossary

docs/book/src/reference/intrinsics.md

@@ -0,0 +1,3 @@
+# MIR Intrinsics
+
+We keep track of the intrinsics to support [here](https://wirehaired-buttercup-010.notion.site/10c9cebab80b812da89cf9fd2b6d2679?v=10c9cebab80b801090ed000cfa24584b&pvs=143).

docs/book/src/reference/orchestrator.md

@@ -0,0 +1 @@
+# Orchestrator Reference

docs/book/src/reference/runtime.md

@@ -0,0 +1 @@
+# Runtime Reference