diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index 591c916d..ba440fc8 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -1,9 +1,15 @@
 FROM ubuntu:latest
 
-ARG DEFAULT_USER=devel
-
+ARG USERNAME=devel
+ARG USER_UID=1000
+ARG USER_GID=$USER_UID
+    
+# Install basic utilities and prerequisites.
+#   bsdmainutils - provides hexdump, used by integration tests
+#   neovim - for convenience and modern editing
 RUN apt-get update -y && \
     apt-get install -y \
+        bsdmainutils \
         build-essential \
         curl \
         git \
@@ -11,34 +17,35 @@ RUN apt-get update -y && \
         neovim \
         sed \
         sudo \
-        wget \
-        zsh
+        wget
+
+# Install gh cli
+# Reference: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
+RUN mkdir -p -m 755 /etc/apt/keyrings && \
+    wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null && \
+    chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg && \
+    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null && \
+    apt-get update -y && \
+    apt-get install -y gh
 
 # Add a non-root user that we'll do our best to use for development.
-RUN useradd -m devel && \
+RUN userdel ubuntu && \
+    groupadd --gid $USER_GID $USERNAME && \
+    useradd --uid $USER_UID --gid $USER_GID -m $USERNAME && \
     echo "devel ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers
 
 # Switch to user.
-USER ${DEFAULT_USER}
+USER devel
 
 # Set up path to include rust components.
-ENV PATH="${PATH}:/home/${DEFAULT_USER}/.cargo/bin"
-WORKDIR /tmp
+ENV PATH="${PATH}:/home/devel/.cargo/bin"
 
 # Copy scripts to temp dir.
 WORKDIR /tmp
 
-# Install rust and plugins
-COPY install-rust-and-friends.sh .
-RUN ./install-rust-and-friends.sh
-
-# Install assorted development utilities
-COPY install-dev-tools.sh .
-RUN ./install-dev-tools.sh
-
-# Bring modern conveniences to shell.
-COPY make-shell-comfortable.sh .
-RUN ./make-shell-comfortable.sh
+# Install rust toolchain and cargo tools.
+COPY install-rust-tools.sh .
+RUN ./install-rust-tools.sh
 
 # Switch back to home dir for normal usage.
-WORKDIR /home/${DEFAULT_USER}
+WORKDIR /home/devel
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index c4f69585..cc897a90 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -11,5 +11,6 @@
         }
     },
     "features": {},
-    "remoteUser": "devel"
+    "remoteUser": "devel",
+    "updateRemoteUserUID": true
 }
\ No newline at end of file
diff --git a/.devcontainer/hashes.txt b/.devcontainer/hashes.txt
deleted file mode 100644
index 57c11b91..00000000
--- a/.devcontainer/hashes.txt
+++ /dev/null
@@ -1,2 +0,0 @@
-095fa945b775be944f660875cfe80218898c210615b6584faea31a4060ba3463  ./bat-musl_0.22.1_amd64.deb
-a65a87bd545e969979ae9388f6333167f041a1f09fa9d60b32fd3072348ff6ce  ./exa-linux-x86_64-v0.10.1.zip
diff --git a/.devcontainer/install-dev-tools.sh b/.devcontainer/install-dev-tools.sh
deleted file mode 100755
index 5c046007..00000000
--- a/.devcontainer/install-dev-tools.sh
+++ /dev/null
@@ -1,13 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-gh_cli_version="2.47.0"
-
-gh_arch="$(arch)"
-if [[ "${gh_arch}" == "x86_64" ]]; then
-    gh_arch="amd64"
-fi
-
-gh_cli_uri="https://github.com/cli/cli/releases/download/v${gh_cli_version}/gh_${gh_cli_version}_linux_${gh_arch}.tar.gz"
-
-wget -qO- "${gh_cli_uri}" | sudo tar xz --strip-components=1 -C /usr/bin
diff --git a/.devcontainer/install-rust-and-friends.sh b/.devcontainer/install-rust-tools.sh
similarity index 79%
rename from .devcontainer/install-rust-and-friends.sh
rename to .devcontainer/install-rust-tools.sh
index adab63a9..7407c06e 100755
--- a/.devcontainer/install-rust-and-friends.sh
+++ b/.devcontainer/install-rust-tools.sh
@@ -2,13 +2,15 @@
 set -euo pipefail
 
 # Install rustup and needed components
+# Reference: https://rustup.rs/
 curl https://sh.rustup.rs -sSf | sh -s -- -y
 rustup component add llvm-tools-preview
 
 # Install cargo binstall
+# Reference: https://github.com/cargo-bins/cargo-binstall
 curl -L --proto '=https' --tlsv1.2 -sSf https://raw.githubusercontent.com/cargo-bins/cargo-binstall/main/install-from-binstall-release.sh | bash
 
-# Install cargo tools
+# Install cargo tools using binstall
 cargo binstall --no-confirm cargo-audit
 cargo binstall --no-confirm cargo-deny
 # cargo binstall --no-confirm cargo-flamegraph
diff --git a/.devcontainer/make-shell-comfortable.sh b/.devcontainer/make-shell-comfortable.sh
deleted file mode 100755
index d8928997..00000000
--- a/.devcontainer/make-shell-comfortable.sh
+++ /dev/null
@@ -1,18 +0,0 @@
-#!/bin/bash
-set -euo pipefail
-
-# Settings
-zsh_theme="agnoster"
-
-# Install oh-my-zsh
-sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
-
-# Clone preferred plugins
-git clone https://github.com/zsh-users/zsh-autosuggestions.git ~/.oh-my-zsh/custom/plugins/zsh-autosuggestions
-git clone https://github.com/zsh-users/zsh-syntax-highlighting.git ~/.oh-my-zsh/custom/plugins/zsh-syntax-highlighting
-
-# Enable plugins
-sed -i "s/^plugins=.*/plugins=(git zsh-autosuggestions zsh-syntax-highlighting)/" ~/.zshrc
-
-# Select theme
-sed -i "s/^ZSH_THEME=.*/ZSH_THEME=\"${zsh_theme}\"/" ~/.zshrc
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 9173c0be..8b07772d 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -3,10 +3,10 @@
     "files.exclude": {
         "target/": true
     },
-    "terminal.integrated.defaultProfile.linux": "zsh",
+    "terminal.integrated.defaultProfile.linux": "bash",
     "terminal.integrated.profiles.linux": {
-        "zsh": {
-            "path": "/bin/zsh"
+        "bash": {
+            "path": "/bin/bash"
         }
     },
     "rust-analyzer.check.command": "clippy",
diff --git a/README.md b/README.md
index 5ac75ac7..1c4853d4 100644
--- a/README.md
+++ b/README.md
@@ -5,11 +5,13 @@
 
 ## About
 
-`brush` (**B**orn **RU**sty **SH**ell) is a shell implementation with aspirations of compatibility with the [POSIX Shell specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) as well as with [bash](https://www.gnu.org/software/bash/).
+`brush` (**B**orn **RU**sty **SH**ell) is a shell implementation with aspirations of compatibility with the [POSIX Shell specification](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html) and [bash](https://www.gnu.org/software/bash/).
 
-It's generally functional for interactive use and can execute many scripts, but it's still very much a work in progress. We do not recommend using this in production scenarios; until it's more stable, there's risk that using this implementation in place of your stable shell will result in unexpected behavior (e.g., this shell taking an `else` branch of a conditional when your `sh` may have otherwise taken the `then` branch).
+It's generally functional for interactive use and can execute many scripts but still a work in progress. We do not recommend using this in production scenarios; until it's more stable, there's risk that using this implementation in place of your stable shell may result in unexpected behavior.
 
-This project was primarily borne out of curiosity and a desire to learn. If it proves to be sufficiently interesting and/or useful, then that's a bonus :). Contributions are certainly welcome. For more guidance, please consult [CONTRIBUTING.md](CONTRIBUTING.md).
+This project was primarily borne out of curiosity and a desire to learn. If it proves to be interesting or useful, then that's a bonus :).
+
+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.
 
 ### License
 
@@ -36,6 +38,8 @@ There's certainly more gaps; with time we'll find a way to represent the gaps in
 
 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 [300+ test cases](cli/tests/cases) run on both this shell and an oracle, comparing standard output and exit codes.
 
+For more details, please consult the [reference documentation on integration testing](docs/reference/integration-testing.md).
+
 ## Links: other shell implementations
 
 This is certainly not the first attempt to implement a feature-rich POSIX-ish shell in a non-C/C++ implementation language. Some examples include:
diff --git a/cli/tests/cases/builtins/shopt.yaml b/cli/tests/cases/builtins/shopt.yaml
index 100769b6..42eed6a0 100644
--- a/cli/tests/cases/builtins/shopt.yaml
+++ b/cli/tests/cases/builtins/shopt.yaml
@@ -1,10 +1,12 @@
 name: "Builtins: shopt"
 cases:
   - name: "shopt defaults"
+    skip: true
     stdin: |
       shopt | sort | grep -v extglob
 
   - name: "shopt interactive defaults"
+    skip: true
     args: ["-i"]
     ignore_stderr: true
     stdin: |
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..52b4125b
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,13 @@
+# brush documentation
+
+The docs are grouped into:
+
+* [How-to guides](how-to/README.md)
+* [Tutorials](tutorials/README.md)
+* [Reference material](reference/README.md)
+
+If you're just getting started building this project, you should consult the [How to Build](how-to/build.md) guide.
+
+---
+
+> _Note: The structure of our docs is inspired by the [Diátaxis](https://diataxis.fr/) approach; we've found over time that best helps readers find the material most relevant to them, as well as provides a rough shape for where to place the right docs._
diff --git a/docs/how-to/README.md b/docs/how-to/README.md
new file mode 100644
index 00000000..414f4acf
--- /dev/null
+++ b/docs/how-to/README.md
@@ -0,0 +1,5 @@
+# How-to guides
+
+* [How to build](build.md)
+* [How to run tests](run-tests.md)
+* [How to run benchmarks](run-benchmarks.md)
diff --git a/docs/how-to/build.md b/docs/how-to/build.md
new file mode 100644
index 00000000..864a6fa1
--- /dev/null
+++ b/docs/how-to/build.md
@@ -0,0 +1,5 @@
+# How to build and run
+
+1. Install Rust toolchain. We recommend using [rustup](https://rustup.rs/).
+1. Build `brush`: `cargo build`
+1. Run `brush`: `cargo run`
diff --git a/docs/how-to/run-benchmarks.md b/docs/how-to/run-benchmarks.md
new file mode 100644
index 00000000..c5472afa
--- /dev/null
+++ b/docs/how-to/run-benchmarks.md
@@ -0,0 +1,17 @@
+# How to run benchmarks
+
+To run performance benchmarks:
+
+```bash
+cargo bench --workspace
+```
+
+## Collecting flamegraphs
+
+To collect flamegraphs from performance benchmarks (running for 10 seconds):
+
+```bash
+cargo bench --workspace -- --profile-time 10
+```
+
+The flamegraphs will be created as `.svg` files and placed under `target/criterion/<benchmark_name>/profile`.
diff --git a/docs/how-to/run-tests.md b/docs/how-to/run-tests.md
new file mode 100644
index 00000000..a5d45522
--- /dev/null
+++ b/docs/how-to/run-tests.md
@@ -0,0 +1,19 @@
+# How to run tests
+
+To run all workspace tests:
+
+```bash
+cargo test --workspace
+```
+
+To run just integration tests:
+
+```bash
+cargo test --test integration_tests
+```
+
+To run a specific integration test case
+
+```bash
+cargo test --test integration_tests -- '<name of test case>'
+```
diff --git a/docs/reference/README.md b/docs/reference/README.md
new file mode 100644
index 00000000..c7e984ef
--- /dev/null
+++ b/docs/reference/README.md
@@ -0,0 +1,3 @@
+# Reference
+
+* [Integration testing](integration-testing.md)
diff --git a/docs/integration-testing.md b/docs/reference/integration-testing.md
similarity index 100%
rename from docs/integration-testing.md
rename to docs/reference/integration-testing.md
diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md
new file mode 100644
index 00000000..f709339c
--- /dev/null
+++ b/docs/tutorials/README.md
@@ -0,0 +1,3 @@
+# Tutorials
+
+_To be written_
\ No newline at end of file