Merge pull request csg-tokyo#80 from maejima-fumika/develop/add-getstarted-docs

Add "Get started" and "CLI Reference" to the website.

Author: maejima-fumika

README.md

@@ -9,7 +9,7 @@ You can find the official website at https://csg-tokyo.github.io/bluescript/.
 WARNING: this project is in beta stage and is subject to changes of the code-base, including project-wide name changes and API changes.
 
 # Documentation
-- [Get started](https://csg-tokyo.github.io/bluescript/docs/tutorial/get-started)
+- [Quick Start](http://localhost:3000/bluescript/docs/tutorial/get-started/quick-start)
 - [Reference Manual](https://csg-tokyo.github.io/bluescript/docs/reference/language/intro)
 
 - Fumika Mochizuki, Tetsuro Yamazaki, Shigeru Chiba, ["Interactive Programming for Microcontrollers by Offloading Dynamic Incremental Compilation"](https://dl.acm.org/doi/10.1145/3679007.3685062), MPLR 2024, pp. 28-40, ACM, 2024.

website/docs/reference/cli.md

@@ -0,0 +1,143 @@
+# CLI
+
+The BlueScript CLI (`blue`) is the primary tool for managing projects, setting up board environments, and running code on your devices.
+
+## Installation
+
+```bash
+npm install -g @bluescript/cli
+```
+
+## Project Commands
+
+### `blue create-project`
+
+Creates a new BlueScript project with the necessary configuration files.
+
+```bash
+blue create-project <project-name> [options]
+```
+
+This command generates a new directory containing:
+*   `index.bs`: The main entry point for your application.
+*   `bsconfig.json`: The project configuration file.
+
+**Arguments:**
+*   `<project-name>`: The name of the directory to create.
+
+**Options:**
+
+| Option | Alias | Description |
+| :--- | :--- | :--- |
+| `--board` | `-b` | Specify the target board (e.g., `esp32`). If omitted, an interactive selection list will appear. |
+
+**Example:**
+```bash
+# Create a project interactively
+blue create-project my-app
+
+# Create a project specifically for ESP32
+blue create-project my-app --board esp32
+```
+
+---
+
+### `blue run`
+
+Compiles the current project and executes it on a target device via Bluetooth.
+
+```bash
+blue run
+```
+
+When you run this command:
+1.  The CLI scans for available BlueScript devices over Bluetooth.
+2.  The project is compiled into native code on your host machine.
+3.  The code is transferred and executed immediately.
+
+---
+
+## Board Management
+
+These commands manage the toolchains and runtime environments for specific hardware platforms.
+
+### `blue board setup`
+
+Downloads and installs the necessary environment files and dependencies for a specific board architecture.
+
+```bash
+blue board setup <board-name>
+```
+
+**Arguments:**
+*   `<board-name>`: The target board identifier (e.g., `esp32`).
+
+---
+
+### `blue board flash-runtime`
+
+Flashes the BlueScript Runtime firmware onto the microcontroller.
+**Note:** This command requires a physical USB connection to the device.
+
+```bash
+blue board flash-runtime <board-name> [options]
+```
+
+**Arguments:**
+*   `<board-name>`: The target board identifier.
+
+**Options:**
+
+| Option | Alias | Description |
+| :--- | :--- | :--- |
+| `--port` | `-p` | Specify the serial port connected to the device (e.g., `COM3`, `/dev/ttyUSB0`). If omitted, the CLI will list available ports for selection. |
+
+**Example:**
+```bash
+blue board flash-runtime esp32 --port /dev/ttyUSB0
+```
+
+---
+
+### `blue board list`
+
+Lists all board architectures currently supported by the installed CLI version.
+
+```bash
+blue board list
+```
+
+---
+
+### `blue board remove`
+
+Removes the environment files and setup data for a specific board.
+
+```bash
+blue board remove <board-name> [options]
+```
+
+By default, this command asks for confirmation before deleting files.
+
+**Options:**
+
+| Option | Alias | Description |
+| :--- | :--- | :--- |
+| `--force` | `-f` | Skips the confirmation prompt and forces removal. |
+
+---
+
+### `blue board fullclean`
+
+Completely removes all configuration and environment files for **all** boards. This returns the CLI board configurations to a fresh state.
+
+```bash
+blue board fullclean
+```
+By default, this command asks for confirmation before deleting files.
+
+**Options:**
+
+| Option | Alias | Description |
+| :--- | :--- | :--- |
+| `--force` | `-f` | Skips the confirmation prompt and forces removal. |

website/docs/reference/cli/install.md

@@ -1,3 +1,3 @@
 # Blink LED
 
-In preparation
+Coming soon...

website/docs/tutorial/examples/blink-led.md

@@ -0,0 +1,84 @@
+# Introduction
+
+Welcome to **BlueScript**.
+
+BlueScript is not just another programming language with a new syntax. It is a next-generation language system for microcontrollers, built upon a novel architectural concept called the **Disaggregated Virtual Machine**.
+
+## Why BlueScript? 
+**The Existing Trade-off:**
+Until now, microcontroller development has forced developers to choose between two extremes:
+
+1.  **C/C++ (Compiled Languages):**
+    *   **Pros:** High execution speed, high memory efficiency.
+    *   **Cons:** Slow development cycle (compile → flash → run), requires physical cable connection.
+2.  **MicroPython / Espruino (Interpreted Languages):**
+    *   **Pros:** Easy to write, rapid prototyping.
+    *   **Cons:** Slow execution speed, high memory consumption (RAM) because compilation and interpretation happen on the device.
+
+BlueScript resolves this dilemma. By adopting the **Disaggregated VM** architecture, it delivers the **flexibility of a script language** with **performance comparable to compiled languages**.
+
+## What is a Disaggregated VM?
+
+Traditional Virtual Machines (Monolithic VMs) cram the compiler, interpreter, and runtime all into the microcontroller's limited memory.
+
+BlueScript physically separates (disaggregates) these VM components between the **Host (PC)** and the **Target (Microcontroller)**.
+
+### Architecture Overview
+
+```mermaid
+graph LR
+    subgraph Host["Host Machine (PC)"]
+        Source[Source Code]
+        Compiler[Incremental Compiler]
+        Shadow[Shadow Machine]
+    end
+
+    subgraph Target["Target Device (MCU)"]
+        Runtime[Lightweight Runtime]
+        Execution[Native Execution]
+    end
+
+    Source --> Compiler
+    Compiler -- "Native Code" --> Runtime
+    Runtime --> Execution
+    Shadow -. "State Sync" .- Runtime
+
+    style Host fill:#f9f,stroke:#333,stroke-width:2px
+    style Target fill:#bbf,stroke:#333,stroke-width:2px
+    style Compiler fill:#ff9,stroke:#333
+    style Runtime fill:#9f9,stroke:#333
+```
+
+### Core Technologies
+
+This architecture is powered by three key technologies:
+
+1.  **Offloaded Compilation**
+    Resource-heavy compilation tasks are offloaded to the powerful Host PC. The incremental compiler on the host converts BlueScript code into optimized native code. The microcontroller only receives and executes this code, resulting in **significantly faster execution and lower memory usage** compared to MicroPython.
+
+2.  **Shadow Machine**
+    The Host PC maintains a "Shadow Machine" that mirrors the state of the microcontroller (memory map, symbol tables, etc.). Because the host knows the exact state of the device, it can compile new code fragments that link correctly to the running program. This enables **interactive development**.
+
+3.  **Bluetooth OTA Updates**
+    Since the compiled binary differences are very small, they can be transferred instantly over Bluetooth Low Energy (BLE). Once the runtime is flashed, you can update your program **wirelessly without cables**.
+
+## The BlueScript Experience
+
+Thanks to this unique architecture, BlueScript offers a developer experience unlike any other:
+
+*   **TypeScript-like Syntax:** Write in a modern, familiar syntax.
+*   **Inline C:** Embed C code directly for critical performance sections or hardware access.
+*   **Interactive Mode:** Execute code line-by-line and inspect variables instantly, just like a REPL, but with compiled performance.
+
+:::info Academic Background
+The architecture of BlueScript is based on the research paper *["BlueScript: A Disaggregated Virtual Machine for Microcontrollers"](https://arxiv.org/pdf/2511.15821v1)*.
+:::
+
+## Supported Hardware
+
+Currently, BlueScript supports the following platform:
+- Espressif ESP32 (Supported)
+
+:::note Future Roadmap
+We plan to support other boards in the future.
+:::

website/docs/tutorial/get-started.md

@@ -0,0 +1,103 @@
+# Quick Start
+
+Let's get your first BlueScript program running. In this guide, we will set up your environment, flash the runtime to a microcontroller, and execute code wirelessly over Bluetooth.
+
+Currently, only ESP32 development board is supported.
+
+## Prerequisites
+
+Before we begin, ensure you have the following:
+
+*   **Hardware:** An ESP32 development board (e.g., ESP32-DevKitC) and a USB cable.
+*   **Software:** [Node.js](https://nodejs.org/) (v18 or later) installed on your computer.
+
+---
+
+## Step 1: Install the CLI
+
+BlueScript provides a command-line interface (CLI) to manage projects and communicate with your device. Install it globally using npm:
+
+```bash
+npm install -g @bluescript/cli
+```
+
+Verify the installation:
+
+```bash
+blue --version
+```
+
+---
+
+## Step 2: Board Setup
+
+Because BlueScript uses a **Disaggregated VM** architecture, you need to install the lightweight **Runtime** onto your microcontroller.
+
+:::info One-Time Setup
+The USB cable is only required for this step (`flash-runtime`). For daily development, you can use Bluetooth.
+:::
+
+1.  **Download the platform tools** for ESP32:
+
+    ```bash
+    blue board setup esp32
+    ```
+    Note: Currently, only esp32 is supported.
+
+2.  **Connect your ESP32** to your computer via USB.
+3.  **Flash the Runtime** to the device:
+
+    ```bash
+    blue board flash-runtime esp32
+    ```
+
+---
+
+## Step 3: Create a Project
+
+Create a new directory for your project. The CLI will generate the necessary configuration files.
+
+```bash
+blue create-project hello-bluescript
+cd hello-bluescript
+```
+
+This creates a simple project structure:
+*   `bsconfig.json`: Project configuration.
+*   `index.bs`: Your entry point file.
+
+---
+
+## Step 4: Write Code
+
+Open `index.bs` and write a simple program.
+
+```typescript title="index.bs"
+print("Hello world!");
+```
+---
+
+## Step 5: Run Wirelessly
+
+Make sure your ESP32 is powered on. You can disconnect the USB cable and power it via a battery if you wish.
+
+Run the following command:
+
+```bash
+blue run
+```
+
+**What happens next?**
+1. It scans for nearby BlueScript devices.
+2. The CLI compiles your project into **Native Code** on your PC.
+3. Upon selection, it transfers the binary via **Bluetooth**.
+4. The ESP32 executes the code immediately.
+
+---
+
+## Next Steps
+
+Now that you have the basics down, explore what else BlueScript can do:
+
+*   **[Language Reference](../../reference/language/intro)**: Learn about supported syntax, Inline C, and hardware APIs.
+*   **[CLI Reference](../../reference/cli)**: Discover advanced commands.

website/docs/tutorial/get-started/introduction.md

@@ -30,6 +30,11 @@ const config: Config = {
   onBrokenLinks: 'throw',
   onBrokenMarkdownLinks: 'warn',
 
+  markdown: {
+    mermaid: true,
+  },
+  themes: ["@docusaurus/theme-mermaid"],
+
   // Even if you don't use internationalization, you can use this field to set
   // useful metadata like html lang. For example, if your site is Chinese, you
   // may want to replace "en" with "zh-Hans".