Fix Studuino setup reproducibility

README.md

@@ -1,16 +1,18 @@
 # Studuino on Linux with Neovim
 
-A development template for using the Artec Studuino (ATmega168/328, 3.3 V, 8 MHz) on Arch Linux with `arduino-cli`, `clangd`, and Neovim.
+A development template for using the Artec Studuino (ATmega168/328, 3.3 V, 8 MHz) on Arch Linux with `arduino-cli` and optional `clangd`/Neovim tooling.
 
 This repository contains the Studuino hardware definition, the legacy Studuino libraries, an Arduino CLI setup script, and optional Neovim integration resources.
 
 ## Features
 
-- Manual installation of the legacy Studuino hardware platform.
+- Manual installation of the checked-in legacy Studuino hardware platform.
 - Arduino CLI project defaults for `studuino:avr:studuino`.
-- Installation of the required `Servo` library.
+- Installation of the checked-in Studuino libraries, including `Servo`.
 - Optional cleanup of unrelated user libraries.
-- A generated `compile_commands.json` for `clangd` and Neovim.
+- A generated, git-ignored `compile_commands.json` for `clangd` and Neovim.
+- A real Studuino Blink smoke-test build during setup.
+- Optional Neovim/Arduino language-server tooling.
 - Optional `picocom` serial-monitor support.
 - A LazyVim/Arduino-Nvim configuration template.
 
@@ -21,16 +23,13 @@ This repository contains the Studuino hardware definition, the legacy Studuino l
 - A user account with permission to use serial devices.
 - Internet access for the initial Arduino CLI core/library installation.
 
-The setup script installs these Arch packages by default:
+The setup script installs `arduino-cli` by default. On Arch Linux, it can also install editor tooling with `--with-editor`:
 
-- `arduino-cli`
-- `clangd`
-- `make`
+- `clang` (provides `clangd`)
 - `neovim`
-- `python`
-- `unzip`
+- `arduino-language-server`
 
-It can optionally install `picocom` with `--with-monitor`.
+It can optionally install `picocom` with `--with-monitor`. On other distributions, use `--skip-packages` and install the required commands through the distribution's package manager.
 
 ## Quick start
 
@@ -38,21 +37,21 @@ From the repository root:
 
 ```bash
 cd /path/to/this/repository
-./setup.sh
+./setup.sh --with-editor
 ```
 
 The script performs the following tasks:
 
-1. Installs required Arch packages.
+1. Installs the required packages for the selected options.
 2. Adds the current user to `uucp` and `dialout`.
 3. Initializes the Arduino CLI configuration if necessary.
-4. Installs the AVR core when it is missing.
-5. Installs the Studuino hardware definition.
-6. Installs the libraries from `Resources/studuino_v1_lib.zip`.
-7. Installs `Servo`, which is required by `Studuino.h`.
-8. Ensures the sketch and default FQBN are configured.
-9. Generates `compile_commands.json` for `clangd`.
-10. Verifies board discovery and compilation.
+4. Installs or upgrades the Arduino AVR core to a supported version.
+5. Installs the checked-in Studuino hardware definition.
+6. Installs the checked-in Studuino libraries, including `Servo`.
+7. Ensures the sketch and default FQBN are configured.
+8. Generates `compile_commands.json` for `clangd`.
+9. Compiles the bundled Studuino Blink smoke test.
+10. Compiles the project and verifies board/library discovery.
 
 Log out and back in after the first run if the script adds you to a new serial-port group. Group changes do not affect the current login session immediately.
 
@@ -70,22 +69,25 @@ Useful options:
 # Do not install Arch packages or modify group membership
 ./setup.sh --skip-packages --skip-permissions
 
+# Install Neovim, clangd, and Arduino language-server tooling
+./setup.sh --with-editor
+
 # Install picocom for a serial monitor
 ./setup.sh --with-monitor
 
-# Remove user libraries not supplied by the Studuino bundle
+# Remove user libraries not present in this repository
 ./setup.sh --clean
 
-# Replace existing Studuino library and hardware files
+# Replace existing hardware/libraries with the checked-in versions
 ./setup.sh --force
 
 # Skip regeneration of compile_commands.json
 ./setup.sh --skip-compile-db
 ```
 
-`--clean` is destructive. It preserves the libraries supplied in the Studuino ZIP and `Servo`, but removes other directories under the configured Arduino `libraries` directory. Back up any libraries you want to keep.
+`--clean` is destructive. It preserves the libraries checked into this repository, including `Servo`, but removes other directories under the configured Arduino `libraries` directory. Back up any libraries you want to keep.
 
-`--force` overwrites existing Studuino library and hardware files. Use it only when intentionally refreshing the Studuino installation.
+`--force` overwrites existing Studuino hardware and library files with the checked-in versions. Use it after updating this repository or when intentionally refreshing the Studuino installation.
 
 ## Project layout
 
@@ -95,7 +97,7 @@ Useful options:
 ├── sketch.yaml                 # arduino-cli project defaults
 ├── .arduino_config.lua         # Arduino-Nvim board/port configuration
 ├── setup.sh                    # Idempotent setup script
-├── compile_commands.json       # clangd compilation database
+├── compile_commands.json       # Generated locally; not tracked
 ├── hardware/
 │   └── studuino/
 │       └── avr/
@@ -109,7 +111,7 @@ Useful options:
     └── nvim/
 ```
 
-The Studuino platform is manually installed because it predates the modern Boards Manager package format.
+The Studuino platform is manually installed because it predates the modern Boards Manager package format. The checked-in `hardware/` and `libraries/` trees are the canonical installation sources; the ZIP files under `Resources/` are retained as upstream source material and provenance.
 
 ## Board and port configuration
 
@@ -181,7 +183,7 @@ arduino-cli upload \
   --port /dev/ttyUSB0
 ```
 
-The setup script verifies the project with a clean build. The Studuino target is an ATmega168 target, so the available program storage is smaller than a default Arduino Uno/ATmega328 build.
+The setup script verifies the project with a clean build and also compiles `libraries/Studuino/example/Blink` as a smoke test. The Studuino target is an ATmega168 target, so the available program storage is 14,336 bytes and static data is limited to 1,024 bytes.
 
 ### Compile the bundled Blink example
 
@@ -195,9 +197,9 @@ arduino-cli compile \
 
 ## Neovim and clangd
 
-The setup script installs `clangd` and generates `compile_commands.json` in the project root. `clangd` automatically searches the project directory for this file.
+With `--with-editor`, the setup script installs the `clang` package (which provides `clangd`), Neovim, and `arduino-language-server`. It generates `compile_commands.json` in the project root; the file is ignored by Git because its paths are specific to the local Arduino CLI installation.
 
-The initial database is generated from the minimal sketch, so it may not contain the Studuino library include paths. If clangd reports `Studuino.h file not found` after adding `#include <Studuino.h>`, refresh the database with the setup script after changing the sketch.
+The initial database is generated from `Arduino.ino`, which includes `<Studuino.h>` and `<Clock.h>`, so the complete bundled smoke-test dependency set is available to `clangd`. If you add a new library or change the FQBN, refresh the database with the setup script.
 
 If you add a new library or change the FQBN, refresh the database with:
 
@@ -344,7 +346,7 @@ The supported path is:
 
 ### `Servo.h` not found
 
-`Studuino.h` includes the Servo library, but Servo is distributed separately from the Studuino ZIP. Install it with:
+`Studuino.h` includes the Servo library. It is checked into this repository and is installed by the setup script. If it is missing, install it with:
 
 ```bash
 arduino-cli lib install Servo
@@ -400,7 +402,7 @@ The key must be `default_fqbn`; a top-level `fqbn` key is not used as the defaul
 
 ## Re-running setup
 
-The setup script is designed to be rerun. It skips existing packages, libraries, and core installations unless `--force` is supplied. It always verifies the final board, libraries, and project compilation.
+The setup script is designed to be rerun. It preserves existing user installations unless `--force` is supplied, verifies that the Arduino AVR core is at least version 1.8.8, and always verifies the board, libraries, Studuino smoke test, and project compilation.
 
 To inspect all available options:
 
@@ -410,4 +412,4 @@ To inspect all available options:
 
 ## License and source materials
 
-The Studuino hardware archive and Studuino library archive are kept in `Resources/` because they use a legacy/manual Arduino hardware layout. Keep the archives with the project so the setup can be recreated on another Linux machine.
+The hardware and library ZIP files are retained in `Resources/` as upstream source archives. The active, maintained definitions are the checked-in `hardware/studuino/avr/` and `libraries/` directories; the setup script installs from those directories.