Add initial project structure with Rust Nix flake template

- Create .envrc for Direnv configuration
- Add .pre-commit-config.yaml for pre-commit hooks
- Include CONTRIBUTING.md for contribution guidelines
- Initialize Cargo.toml for Rust package configuration
- Update LICENSE to link to full license text
- Create Makefile for build, run, test, and clean commands
- Revise README.md for project description and usage instructions
- Implement default Nix flake configuration in flake.nix
- Add Flatpak manifest for packaging
- Set up project metadata in project.toml
- Create shell.nix for legacy shell support
- Add skeletal Rust application in src/main.rs
- Include sample test in tests/sample_test.rs

README.md

@@ -1,16 +1,163 @@
-# template
+# Rust Nix Flake Template
 
-Minimal starter repository for future projects.
+This template provides a reproducible Rust development environment using Nix flakes and the fenix toolchain.
 
-## Defaults
+## Quick Start
 
-- `.editorconfig` for consistent formatting
-- `.gitattributes` for normalized line endings
-- `.gitignore` for common build artifacts, editor state, caches, and local environment files
-- `flake.nix` for a generic development shell and Nix self-checks
+```sh
+nix develop
+# or with direnv:
+direnv allow
+```
 
-## Use
+### Automatic Environment Setup
 
-1. Rename the repository to match the project you are starting.
-2. Add the language- or framework-specific files you need.
-3. Remove any defaults that do not apply to that project.
+When you enter the devShell (via `direnv allow` or `nix develop`), the following happens automatically:
+
+✓ **Git Repository**: Initializes `.git` if not present
+✓ **Rust Targets**: Automatically adds common embedded Rust targets (ARM Cortex-M, RISC-V)
+✓ **Cargo Paths**: Sets up `$HOME/.cargo/bin` in PATH for cargo-installed binaries
+✓ **Welcome Banner**: Displays available tools and quick commands
+
+No manual setup needed! Just start coding.
+
+## Quickstart
+
+```sh
+nix flake init -t path:../flakes#rust
+nix develop
+cargo build
+```
+
+## Embedded Rust Support
+
+The devShell automatically installs common embedded Rust targets via `rustup`:
+
+| Target | Platform | Use Case |
+|--------|----------|----------|
+| `thumbv6m-none-eabi` | ARM Cortex-M0/M0+ | RP2040 (Pico) |
+| `thumbv7em-none-eabihf` | ARM Cortex-M4F/M7F | STM32, nRF52840 |
+| `riscv32imc-unknown-none-elf` | RISC-V 32-bit | ESP32-C3 (basic) |
+| `riscv32imac-unknown-none-elf` | RISC-V 32-bit (atomic) | ESP32-C3 (advanced) |
+
+**Note:** ESP32 Xtensa targets require espup or custom toolchains (see [esp-rs](https://github.com/esp-rs)).
+
+## Flatpak Packaging
+
+This template supports building Flatpak packages for your Rust application.
+
+### Build Flatpak Package
+
+1. Ensure you have `flatpak-builder` installed.
+2. Run:
+
+  ```bash
+  make flatpak-build
+  ```
+
+This will use the manifest at `flatpak/app.flatpak.json` to build a Flatpak bundle in the `build-flatpak/` directory.
+
+### Customize Manifest
+
+Edit `flatpak/app.flatpak.json` to update app ID, runtime, build commands, or sources as needed for your project.
+
+### Install/Run Flatpak Locally
+
+You can install and run the built Flatpak locally:
+
+```bash
+flatpak install --user build-flatpak/org.example.rustdevshell.flatpak
+flatpak run org.example.rustdevshell
+```
+
+## Included Tools
+
+| Tool | Purpose |
+|------|---------|
+| **cargo** | Rust package manager and build system |
+| **rustc** | Rust compiler |
+| **clippy** | Rust linter for catching common mistakes |
+| **rustfmt** | Rust code formatter |
+| **rust-analyzer** | Language server for IDE integration |
+| **rust-src** | Rust source code (for tools like rust-analyzer) |
+| **probe-rs** | Embedded debugger/flasher for ARM targets |
+| **espflash** | Flashing tool for ESP32 boards |
+| **openocd** | JTAG/SWD debugger for ARM and other targets |
+| **minicom** | Serial terminal for device output |
+| **elf2uf2-rs** | Convert ELF to UF2 format (RP2040) |
+| **picotool** | Pico-specific firmware operations |
+| **avrdude** | AVR microcontroller programmer |
+| **ravedude** | Rapid AVR development utility |
+
+## Testing & Development Features
+
+Build and testing tools:
+
+- **cargo test** - Run unit and integration tests
+- **cargo clippy** - Lint code for common issues
+- **cargo fmt** - Format code consistently with rustfmt
+
+**Example usage:**
+
+```bash
+# Run tests
+cargo test
+
+# Check code with clippy
+cargo clippy
+
+# Format code
+cargo fmt
+
+# Build for embedded target
+cargo build --target thumbv7em-none-eabihf --release
+```
+
+## Project Layout
+
+```
+Cargo.toml
+Cargo.lock
+src/
+  └── main.rs (or lib.rs)
+Makefile
+.envrc
+flake.nix
+```
+
+## Legacy Usage
+
+If you do not use flakes, run:
+
+```sh
+nix-shell
+```
+
+## Project Metadata
+
+See project.toml for example metadata.
+
+## Helper Tools
+
+- **`nix run .#dev-helper`** - Display tool versions and availability
+- **`cargo build`** - Build the project
+- **`cargo check`** - Quick syntax check without building
+- **`cargo doc --open`** - Generate and view documentation
+
+## Packaging for nixpkgs
+
+This template is structured for easy packaging in nixpkgs:
+
+- All sources in `src/`
+- `flake.nix` provides a devShell and template
+- Add a `default.nix` or package expression as needed for nixpkgs
+
+See [nixpkgs Rust packaging docs](https://nixos.org/manual/nixpkgs/stable/#rust) for more details.
+
+## Customization
+
+Edit `flake.nix` to:
+
+- Add additional Rust targets via `rustup target add [target]`
+- Include additional cargo plugins
+- Add board-specific tools (e.g., stm32cube, nrfjprog)