From a5ec3f476369b64a349da25140b1b264ae64d0eb Mon Sep 17 00:00:00 2001
From: Gregory Conrad <gregorysconrad@gmail.com>
Date: Fri, 26 Sep 2025 21:53:30 -0400
Subject: [PATCH 1/2] docs: improve/clarify README

---
 README.md | 17 ++++++-----------
 1 file changed, 6 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 62ceec7..3bbab95 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,8 @@
 <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-purple.svg" alt="MIT License"></a>
 </p>
 
-# native_toolchain_rs
 Rust support for Dart's Native Assets.
 
----
-
 ## Why native_toolchain_rs?
 1. It's opinionated.
    That might sound bad, but it's opinionated in the way that _keeps you from shooting yourself in the foot_.
@@ -29,7 +26,7 @@ Rust support for Dart's Native Assets.
 ## Code Setup
 `native_toolchain_rs` will look (by default) for `native/` or `rust/` (customizable)
 in your Dart package's root.
-Create a `Cargo.toml` and `rust-toolchain.toml` in your chosen Rust sources directory;
+If you haven't already, create a `Cargo.toml` and `rust-toolchain.toml` in your chosen Rust directory;
 keep reading for what these two files must contain
 (but don't worry if you forget, you'll get a helpful error message).
 
@@ -64,11 +61,7 @@ void main(List<String> args) async {
     await RustBuilder(
       assetName: 'src/my_ffi_bindings.g.dart',
       // ...maybe enable some Cargo features or something in here too
-    ).run(
-      input: input,
-      output: output,
-      logger: logger,
-    );
+    ).run(input: input, output: output, logger: logger);
   });
 }
 ```
@@ -77,7 +70,7 @@ void main(List<String> args) async {
 Keep at least the following in your `Cargo.toml`.
 ```toml
 [package]
-name = "my-crate-name" # name it whatever you want, doesn't matter
+name = "my-crate-name" # pick a name, doesn't matter
 
 [lib]
 crate-type = ["staticlib", "cdylib"] # THESE ARE IMPORTANT!
@@ -87,7 +80,9 @@ crate-type = ["staticlib", "cdylib"] # THESE ARE IMPORTANT!
 Keep at least the following in your `rust-toolchain.toml`.
 ```toml
 [toolchain]
-channel = "1.90.0" # or newer, but *do not* use stable, beta, or nightly alone (without a version number)!
+# WARNING: *do not* use `stable`, `beta`, or `nightly` (alone) for the channel!
+# You must specify a version number/date in order to ensure reproducible builds.
+channel = "1.90.0" # or newer. another example: `nightly-2025-01-01`
 
 # The targets you want to support; these are the default:
 targets = [

From 1e28380f6bfe33a98f8fd6e46d26058686e77e07 Mon Sep 17 00:00:00 2001
From: Gregory Conrad <gregorysconrad@gmail.com>
Date: Fri, 26 Sep 2025 21:56:55 -0400
Subject: [PATCH 2/2] docs: re-organize README

---
 README.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 3bbab95..a1a68cd 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,10 @@
-<p align="center">
-<a href="https://github.com/GregoryConrad/native_toolchain_rs/actions"><img src="https://github.com/GregoryConrad/native_toolchain_rs/actions/workflows/build.yml/badge.svg" alt="Build Status"></a>
-<a href="https://github.com/GregoryConrad/native_toolchain_rs"><img src="https://img.shields.io/github/stars/GregoryConrad/native_toolchain_rs.svg?style=flat&logo=github&colorB=deeppink&label=stars" alt="Github Stars"></a>
-<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-purple.svg" alt="MIT License"></a>
-</p>
+# 🧱 `native_toolchain_rs` 🦀
+
+[![Build Status](https://github.com/GregoryConrad/native_toolchain_rs/actions/workflows/build.yml/badge.svg)](https://github.com/GregoryConrad/native_toolchain_rs/actions)
+[![Github Stars](https://img.shields.io/github/stars/GregoryConrad/native_toolchain_rs.svg?style=flat&logo=github&colorB=deeppink&label=stars)](https://github.com/GregoryConrad/native_toolchain_rs)
+[![MIT License](https://img.shields.io/badge/license-MIT-purple.svg)](https://opensource.org/licenses/MIT)
+
+---
 
 Rust support for Dart's Native Assets.