docs: update readme (reubeno#976)

Author: reubeno

.github/copilot-instructions.md

@@ -4,7 +4,7 @@
 
 **brush** (Bourne Rusty Shell) is a POSIX- and bash-compatible shell implemented in Rust. It's a multi-crate workspace (~60K lines of Rust code) targeting Linux, macOS, and WSL, with experimental Windows and WASM support. The project emphasizes compatibility testing against bash as an oracle.
 
-**Key Stats:** Rust 2024 edition, MSRV 1.87.0, 5 main crates, 675+ compatibility test cases, published to crates.io.
+**Key Stats:** Rust 2024 edition, MSRV 1.87.0, 5 main crates, 1400+ compatibility test cases, published to crates.io.
 
 ## Critical: Read AGENTS.md First
 

README.md

@@ -10,21 +10,17 @@
   <a href="https://crates.io/crates/brush-shell"><img src="https://img.shields.io/crates/v/brush-shell?style=flat-square"/></a>
   <!-- msrv badge -->
   <img src="https://img.shields.io/crates/msrv/brush-shell"/>
-  <!-- LoC badge: badge generation seems broken; temporarily disabled -->
-  <!-- <img src="https://tokei.rs/b1/github/reubeno/brush?category=code"/> -->
   <!-- license badge -->
   <img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"/>
-  <!-- CI status badge -->
-  <a href="https://github.com/reubeno/brush/actions/workflows/ci.yaml"><img src="https://github.com/reubeno/brush/actions/workflows/ci.yaml/badge.svg"/></a>
   <br/>
   <!-- crates.io download badge -->
   <a href="https://crates.io/crates/brush-shell"><img src="https://img.shields.io/crates/d/brush-shell?style=flat-square"/></a>
+  <!-- compat tests badge -->
+  <img src="https://img.shields.io/badge/compat_tests-1389-brightgreen?style=flat-square" alt="1389 compatibility tests"/>
   <!-- Packaging badges -->
   <a href="https://repology.org/project/brush/versions">
     <img src="https://repology.org/badge/tiny-repos/brush.svg" alt="Packaging status"/>
   </a>
-  <!-- Dependencies badges -->
-  <a href="https://deps.rs/repo/github/reubeno/brush"><img src="https://deps.rs/repo/github/reubeno/brush/status.svg" alt="Dependency status"/></a>
   <!-- Social badges -->
   <a href="https://discord.gg/kPRgC9j3Tj">
     <img src="https://dcbadge.limes.pink/api/server/https://discord.gg/kPRgC9j3Tj?compact=true&style=flat" alt="Discord invite"/>
@@ -38,58 +34,88 @@
 
 <hr/>
 
-`brush` (**B**o(u)rn(e) **RU**sty **SH**ell) is a [POSIX-](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) and [bash-](https://www.gnu.org/software/bash/)compatible shell,
-implemented in Rust. At its core is an embeddable shell interpreter published for reuse
-in other Rust projects. It's built and tested on Linux, macOS, and WSL. Native Windows
-support is experimental.
+`brush` (**B**o(u)rn(e) **RU**sty **SH**ell) is a modern [bash-](https://www.gnu.org/software/bash/) and [POSIX-](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) compatible shell written in Rust. Run your existing scripts and `.bashrc` unchanged -- with syntax highlighting and auto-suggestions built in.
+
+## At a glance
+
+✅ Your existing `.bashrc` just works—aliases, functions, completions, all of it.<br/>
+✨ Syntax highlighting and auto-suggestions built in and enabled by default.<br/>
+🧪 Validated against bash with [~1400 compatibility tests](brush-shell/tests/cases).<br/>
+🧩 Easily embeddable in your Rust apps using `brush_core::Shell`.<br/>
 
 <p align="center">
   <img src="https://github.com/user-attachments/assets/0e64d1b9-7e4e-43be-8593-6c1b9607ac52" width="80%"/>
 </p>
 
-`brush` is functional for interactive use as a daily driver! It executes most `sh` and `bash` scripts we've
-encountered. Known limitations are tracked with filed issues. Out of an abundance of caution,
-we wouldn't recommend using it yet in _production_ scenarios in case it doesn't behave identically
-to your existing stable shell. (If you do find any behavioral differences, though, please report them with an
-issue!)
+> ⚠️ **Not everything works yet:** `coproc`, `select`, ERR traps, and some edge cases aren't supported. See the [Compatibility Reference](docs/reference/compatibility.md) for details.
 
-Contributions and feedback of all kinds are welcome! For more guidance, please consult our
-[contribution guidelines](CONTRIBUTING.md). For more technical details, please consult the
-[documentation](docs/README.md) in this repo.
+### Quick start:
 
-This project was originally borne out of curiosity and a desire to learn. We're doing our best to keep that
-attitude :).
+```console
+$ cargo binstall brush-shell         # using cargo-binstall
+$ brew install brush                 # using Homebrew
+$ pacman -S brush                    # Arch Linux
+$ cargo install --locked brush-shell # Build from sources
+```
 
-<br/>
+`brush` is ready for use as a daily driver. We test every change against `bash` to keep it that way.
+
+More detailed installation instructions are available below.
+
+## ✨ Features
+
+### 🐚 `bash` Compatibility
 
-## 📝 License
+| | Feature | Description |
+|--|---------|-------------|
+| ✅ | **50+ builtins** | `echo`, `declare`, `read`, `complete`, `trap`, `ulimit`, ... |
+| ✅ | **Full expansions** | brace, parameter, arithmetic, command/process substitution, globs, `extglob`, `globstar` |
+| ✅ | **Control flow** | `if`/`for`/`while`/`until`/`case`, `&&`/`||`, subshells, pipelines, etc. |
+| ✅ | **Redirection** | here docs, here strings, fd duplication, process substitution redirects |
+| ✅ | **Arrays & variables** | indexed/associative arrays, dynamic variables, standard well-known variables, etc. |
+| ✅ | **Programmable completion** | Works with [bash-completion](https://github.com/scop/bash-completion) out of the box |
+| ✅ | **Job control** | background jobs, suspend/resume, `fg`/`bg`/`jobs` |
+| 🔷 | **Traps & options** | `EXIT`/`DEBUG` traps work; signal traps and options in progress |
 
-Available for use and distribution under the [MIT license](LICENSE).
+### ⌨️ User Experience
 
-## ⌨️ Installation
+| | Feature | Description |
+|--|---------|-------------|
+| ✅ | **Syntax highlighting** | Real-time as you type ([reedline](https://github.com/nushell/reedline)) |
+| ✅ | **Auto-suggestions** | History-based hints as you type ([reedline](https://github.com/nushell/reedline)) |
+| ✅ | **Rich prompts** | `PS1`/`PROMPT_COMMAND`, right prompts, [starship](https://starship.rs) compatible |
+| ✅ | **TOML config** | `~/.config/brush/config.toml` for persistent settings |
+| 🧪 | **Extras** | `fzf`/`atuin` support, zsh-style `precmd`/`preexec` hooks (experimental), VS Code terminal integration |
+
+## Installation
 
 _When you run `brush`, it should look exactly as `bash` does on your system: it processes your `.bashrc` and
 other standard configuration. If you'd like to distinguish the look of `brush` from the other shells
 on your system, you may author a `~/.brushrc` file._
 
-<details open>
-<summary>🚀 <b>Installing prebuilt binaries from GitHub</b></summary>
+<details>
+<summary>🍺 <b>Installing using Homebrew</b> (macOS/Linux)</summary>
 
-We publish prebuilt binaries of `brush` for Linux (x86_64, aarch64) and macOS (aarch64) to GitHub for official [releases](https://github.com/reubeno/brush/releases). You can manually download and extract the `brush` binary from one of the archives published there, or otherwise use the GitHub CLI to download it, e.g.:
+Homebrew users can install using [the `brush` formula](https://formulae.brew.sh/formula/brush):
 
 ```bash
-gh release download --repo reubeno/brush --pattern "brush-x86_64-unknown-linux-gnu.*"
+brew install brush
 ```
 
-After downloading the archive for your platform, you may verify its authenticity using the [GitHub CLI](https://cli.github.com/), e.g.:
+</details>
+
+<details>
+<summary>🐧 <b>Installing on Arch Linux</b></summary>
+
+Arch Linux users can install `brush` from the official [extra repository](https://archlinux.org/packages/extra/x86_64/brush/):
 
 ```bash
-gh attestation verify brush-x86_64-unknown-linux-gnu.tar.gz --repo reubeno/brush
+pacman -S brush
 ```
 
 </details>
 
-<details open>
+<details>
 <summary>🚀 <b>Installing prebuilt binaries via `cargo binstall`</b></summary>
 
 You may use [cargo binstall](https://github.com/cargo-bins/cargo-binstall) to install pre-built `brush` binaries. Once you've installed `cargo-binstall` you can run:
@@ -101,82 +127,78 @@ cargo binstall brush-shell
 </details>
 
 <details>
-<summary> 🔨 <b>Installing from sources</b></summary>
+<summary>🚀 <b>Installing prebuilt binaries from GitHub</b></summary>
 
-To build from sources, first install a working (and recent) `rust` toolchain; we recommend installing it via [`rustup`](https://rustup.rs/). Then run:
+We publish prebuilt binaries of `brush` for Linux (x86_64, aarch64) and macOS (aarch64) to GitHub for official [releases](https://github.com/reubeno/brush/releases). You can manually download and extract the `brush` binary from one of the archives published there, or otherwise use the GitHub CLI to download it, e.g.:
 
 ```bash
-cargo install --locked brush-shell
+gh release download --repo reubeno/brush --pattern "brush-x86_64-unknown-linux-gnu.*"
 ```
 
-</details>
-
-<details>
-<summary>🐧 <b>Installing using Nix</b></summary>
-
-If you are a Nix user, you can use the registered version:
+After downloading the archive for your platform, you may verify its authenticity using the [GitHub CLI](https://cli.github.com/), e.g.:
 
 ```bash
-nix run 'github:NixOS/nixpkgs/nixpkgs-unstable#brush' -- --version
+gh attestation verify brush-x86_64-unknown-linux-gnu.tar.gz --repo reubeno/brush
 ```
 
 </details>
 
 <details>
-<summary>🐧 <b>Installing on Arch Linux</b></summary>
+<summary>🐧 <b>Installing using Nix</b></summary>
 
-Arch Linux users can install `brush` from the official [extra repository](https://archlinux.org/packages/extra/x86_64/brush/):
+If you are a Nix user, you can use the registered version:
 
 ```bash
-pacman -S brush
+nix run 'github:NixOS/nixpkgs/nixpkgs-unstable#brush' -- --version
 ```
 
 </details>
 
 <details>
-<summary>🍺 <b>Installing using Homebrew</b></summary>
+<summary> 🔨 <b>Building from sources</b></summary>
 
-Homebrew users can install using [the `brush` formula](https://formulae.brew.sh/formula/brush):
+To build from sources, first install a working (and recent) `rust` toolchain; we recommend installing it via [`rustup`](https://rustup.rs/). Then run:
 
 ```bash
-brew install brush
+cargo install --locked brush-shell
 ```
 
 </details>
 
-## 👥 Community
-
-`brush` has a community Discord server, available [here](https://discord.gg/kPRgC9j3Tj).
+## Community & Contributing
 
-## 🧪 Testing strategy
+This project started out of curiosity and a desire to learn—we're keeping that attitude. If something doesn't work the way you'd expect, [let us know](https://github.com/reubeno/brush/issues)!
 
-This project is primarily tested by comparing its behavior with other existing shells, leveraging the latter as test oracles. The integration tests implemented in this repo include [900+ test cases](brush-shell/tests/cases) run on both this shell and an oracle, comparing standard output and exit codes.
+* [Discord server](https://discord.gg/kPRgC9j3Tj) — chat with the community
+* [Building from source](docs/how-to/build.md) — development workflow
+* [Contribution guidelines](CONTRIBUTING.md) — how to submit changes
+* [Technical docs](docs/README.md) — architecture and reference
 
-For more details, please consult the [reference documentation on integration testing](docs/reference/integration-testing.md).
+## Related Projects
 
-## 🙏 Credits
+Other POSIX-ish shells implemented in non-C/C++ languages:
 
-There's a long list of OSS crates whose shoulders this project rests on. Notably, the following crates are directly relied on for major portions of shell functionality:
+* [`nushell`](https://www.nushell.sh/) — modern Rust shell (provides `reedline`)
+* [`fish`](https://fishshell.com) — user-friendly shell ([Rust port in 4.0](https://fishshell.com/blog/rustport/))
+* [`Oils`](https://github.com/oils-for-unix/oils) — bash-compatible with new Oil language
+* [`mvdan/sh`](https://github.com/mvdan/sh) — Go implementation
+* [`rusty_bash`](https://github.com/shellgei/rusty_bash) — another Rust bash-like shell
 
-* [`reedline`](https://github.com/nushell/reedline) - for readline-like input and interactive usage
-* [`clap`](https://github.com/clap-rs/clap) - command-line parsing, used both by the top-level brush CLI as well as built-in commands
-* [`fancy-regex`](https://github.com/fancy-regex/fancy-regex) - relied on for everything regex
-* [`tokio`](https://github.com/tokio-rs/tokio) - async, well, everything
-* [`nix` rust crate](https://github.com/nix-rust/nix) - higher-level APIs for Unix/POSIX system APIs
-
-For testing, performance benchmarking, and other important engineering support, we use and love:
+<details>
+<summary><b>🙏 Credits</b></summary>
 
-* [`criterion.rs`](https://github.com/bheisler/criterion.rs) - for statistics-based benchmarking
-* [`bash-completion`](https://github.com/scop/bash-completion) - for its completion test suite and general completion support!
+This project relies on many excellent OSS crates:
 
-## 🔗 Links: other shell implementations
+* [`reedline`](https://github.com/nushell/reedline) — readline-like input and interactive features
+* [`clap`](https://github.com/clap-rs/clap) — command-line parsing
+* [`fancy-regex`](https://github.com/fancy-regex/fancy-regex) — regex support
+* [`tokio`](https://github.com/tokio-rs/tokio) — async runtime
+* [`nix`](https://github.com/nix-rust/nix) — Unix/POSIX APIs
+* [`criterion.rs`](https://github.com/bheisler/criterion.rs) — benchmarking
+* [`bash-completion`](https://github.com/scop/bash-completion) — completion test suite
 
-There are a number of other POSIX-ish shells implemented in a non-C/C++ implementation language. Some inspirational examples include:
+</details>
 
-* [`nushell`](https://www.nushell.sh/) - modern Rust-implemented shell (which also provides the `reedline` crate we use!)
-* [`rusty_bash`](https://github.com/shellgei/rusty_bash)
-* [`mvdan/sh`](https://github.com/mvdan/sh)
-* [`Oils`](https://github.com/oils-for-unix/oils)
-* [`fish`](https://fishshell.com) ([as of 4.0](https://fishshell.com/blog/rustport/))
+---
 
-We're sure there are plenty more; we're happy to include links to them as well.
+Licensed under the [MIT license](LICENSE).

docs/reference/README.md

@@ -5,3 +5,4 @@ These documents serve as reference material for the `brush` project.
 * [Configuration file](configuration.md)
 * [Integration testing](integration-testing.md)
 * [Minimum Supported Rust Version (MSRV) policy](msrv-policy.md)
+* [Compatibility](compatibility.md)