diff --git a/crates/nu-cli/README.md b/crates/nu-cli/README.md
new file mode 100644
index 0000000000..e0eca3c9bd
--- /dev/null
+++ b/crates/nu-cli/README.md
@@ -0,0 +1,7 @@
+This crate implements the core functionality of the interactive Nushell REPL and interfaces with `reedline`.
+Currently implements the syntax highlighting and completions logic.
+Furthermore includes a few commands that are specific to `reedline`
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-cli/src/lib.rs b/crates/nu-cli/src/lib.rs
index 6f151adad1..d584802cfb 100644
--- a/crates/nu-cli/src/lib.rs
+++ b/crates/nu-cli/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod commands;
 mod completions;
 mod config_files;
diff --git a/crates/nu-cmd-base/README.md b/crates/nu-cmd-base/README.md
new file mode 100644
index 0000000000..28d299928a
--- /dev/null
+++ b/crates/nu-cmd-base/README.md
@@ -0,0 +1,5 @@
+Utilities used by the different `nu-command`/`nu-cmd-*` crates, should not contain any full `Command` implementations.
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-cmd-base/src/lib.rs b/crates/nu-cmd-base/src/lib.rs
index 250a57d741..c2608f8466 100644
--- a/crates/nu-cmd-base/src/lib.rs
+++ b/crates/nu-cmd-base/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub mod formats;
 pub mod hook;
 pub mod input_handler;
diff --git a/crates/nu-cmd-extra/src/lib.rs b/crates/nu-cmd-extra/src/lib.rs
index 2a3d70e6cd..f6f97c2f96 100644
--- a/crates/nu-cmd-extra/src/lib.rs
+++ b/crates/nu-cmd-extra/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod example_test;
 pub mod extra;
 pub use extra::*;
diff --git a/crates/nu-cmd-lang/src/lib.rs b/crates/nu-cmd-lang/src/lib.rs
index 427a535d5d..41022cc231 100644
--- a/crates/nu-cmd-lang/src/lib.rs
+++ b/crates/nu-cmd-lang/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod core_commands;
 mod default_context;
 pub mod example_support;
diff --git a/crates/nu-color-config/README.md b/crates/nu-color-config/README.md
new file mode 100644
index 0000000000..f03753685c
--- /dev/null
+++ b/crates/nu-color-config/README.md
@@ -0,0 +1,5 @@
+Logic to resolve colors for syntax highlighting and output formatting
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-color-config/src/lib.rs b/crates/nu-color-config/src/lib.rs
index 3bd4dc9e4d..77ec9d0e79 100644
--- a/crates/nu-color-config/src/lib.rs
+++ b/crates/nu-color-config/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod color_config;
 mod matching_brackets_style;
 mod nu_style;
diff --git a/crates/nu-command/README.md b/crates/nu-command/README.md
new file mode 100644
index 0000000000..1cbb8cd9f2
--- /dev/null
+++ b/crates/nu-command/README.md
@@ -0,0 +1,7 @@
+This crate contains the majority of our commands
+
+We allow ourselves to move some of the commands in `nu-command` to `nu-cmd-*` crates as needed.
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-command/src/lib.rs b/crates/nu-command/src/lib.rs
index a854fe3507..55c4974325 100644
--- a/crates/nu-command/src/lib.rs
+++ b/crates/nu-command/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod bytes;
 mod charting;
 mod conversions;
diff --git a/crates/nu-engine/README.md b/crates/nu-engine/README.md
new file mode 100644
index 0000000000..d5198cfc3f
--- /dev/null
+++ b/crates/nu-engine/README.md
@@ -0,0 +1,9 @@
+This crate primarily drives the evaluation of expressions.
+
+(Some overlap with nu-protocol)
+
+- Provides `CallExt`
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-engine/src/lib.rs b/crates/nu-engine/src/lib.rs
index 7ed246e975..5a5bb9a5d0 100644
--- a/crates/nu-engine/src/lib.rs
+++ b/crates/nu-engine/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod call_ext;
 mod closure_eval;
 pub mod column;
diff --git a/crates/nu-explore/README.md b/crates/nu-explore/README.md
new file mode 100644
index 0000000000..d18a576c43
--- /dev/null
+++ b/crates/nu-explore/README.md
@@ -0,0 +1,5 @@
+Implementation of the interactive `explore` command pager.
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-explore/src/lib.rs b/crates/nu-explore/src/lib.rs
index 043c85eb02..d645572c89 100644
--- a/crates/nu-explore/src/lib.rs
+++ b/crates/nu-explore/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod commands;
 mod default_context;
 mod explore;
diff --git a/crates/nu-json/README.md b/crates/nu-json/README.md
index acf3c6b296..c982f1a818 100644
--- a/crates/nu-json/README.md
+++ b/crates/nu-json/README.md
@@ -24,7 +24,7 @@ nu-json = "0.76"
 ## From the Commandline
 
 Add with:
-```
+```sh
  cargo add serde
  cargo add nu-json
 ```
@@ -43,7 +43,7 @@ fn main() {
 
     let sample_text=r#"
     {
-        # specify rate in requests/second
+        ## specify rate in requests/second
         rate: 1000
         array:
         [
diff --git a/crates/nu-json/src/lib.rs b/crates/nu-json/src/lib.rs
index eead282786..1cf2c0a9fd 100644
--- a/crates/nu-json/src/lib.rs
+++ b/crates/nu-json/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub use self::de::{
     from_iter, from_reader, from_slice, from_str, Deserializer, StreamDeserializer,
 };
diff --git a/crates/nu-lsp/README.md b/crates/nu-lsp/README.md
new file mode 100644
index 0000000000..d9e666d6c2
--- /dev/null
+++ b/crates/nu-lsp/README.md
@@ -0,0 +1,7 @@
+Implementation of the Nushell language server.
+
+See [the Language Server Protocol specification](https://microsoft.github.io/language-server-protocol/)
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-lsp/src/lib.rs b/crates/nu-lsp/src/lib.rs
index fdeededac5..aee2ab240d 100644
--- a/crates/nu-lsp/src/lib.rs
+++ b/crates/nu-lsp/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 use lsp_server::{Connection, IoThreads, Message, Response, ResponseError};
 use lsp_types::{
     request::{Completion, GotoDefinition, HoverRequest, Request},
diff --git a/crates/nu-parser/README.md b/crates/nu-parser/README.md
index 02f61a31a6..cbb7729e4d 100644
--- a/crates/nu-parser/README.md
+++ b/crates/nu-parser/README.md
@@ -4,7 +4,7 @@ Nushell's parser is a type-directed parser, meaning that the parser will use typ
 
 Nushell's base language is whitespace-separated tokens with the command (Nushell's term for a function) name in the head position:
 
-```
+```nushell
 head1 arg1 arg2 | head2
 ```
 
@@ -12,7 +12,7 @@ head1 arg1 arg2 | head2
 
 The first job of the parser is to a lexical analysis to find where the tokens start and end in the input. This turns the above into:
 
-```
+```text
 <item: "head1">, <item: "arg1">, <item: "arg2">, <pipe>, <item: "head2">
 ```
 
@@ -24,7 +24,7 @@ As Nushell is a language of pipelines, pipes form a key role in both separating
 
 The above tokens are converted the following during the lite parse phase:
 
-```
+```text
 Pipeline:
   Command #1:
     <item: "head1">, <item: "arg1">, <item: "arg2">
@@ -45,7 +45,7 @@ Each command has a shape assigned to each of the arguments it reads in. These sh
 
 For example, if the command is written as:
 
-```sql
+```text
 where $x > 10
 ```
 
@@ -53,7 +53,7 @@ When the parsing happens, the parser will look up the `where` command and find i
 
 In the above example, if the Signature of `where` said that it took three String values, the result would be:
 
-```
+```text
 CallInfo:
   Name: `where`
   Args:
@@ -64,7 +64,7 @@ CallInfo:
 
 Or, the Signature could state that it takes in three positional arguments: a Variable, an Operator, and a Number, which would give:
 
-```
+```text
 CallInfo:
   Name: `where`
   Args:
@@ -77,7 +77,7 @@ Note that in this case, each would be checked at compile time to confirm that th
 
 Finally, some Shapes can consume more than one token. In the above, if the `where` command stated it took in a single required argument, and that the Shape of this argument was a MathExpression, then the parser would treat the remaining tokens as part of the math expression.
 
-```
+```text
 CallInfo:
   Name: `where`
   Args:
diff --git a/crates/nu-parser/src/lib.rs b/crates/nu-parser/src/lib.rs
index 3c97012e8a..8f871aa815 100644
--- a/crates/nu-parser/src/lib.rs
+++ b/crates/nu-parser/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod deparse;
 mod exportable;
 mod flatten;
diff --git a/crates/nu-path/src/lib.rs b/crates/nu-path/src/lib.rs
index 8553495439..2cb415264a 100644
--- a/crates/nu-path/src/lib.rs
+++ b/crates/nu-path/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod assert_path_eq;
 mod components;
 pub mod dots;
diff --git a/crates/nu-protocol/src/lib.rs b/crates/nu-protocol/src/lib.rs
index cae5d3fd0a..e143a19819 100644
--- a/crates/nu-protocol/src/lib.rs
+++ b/crates/nu-protocol/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod alias;
 pub mod ast;
 pub mod config;
diff --git a/crates/nu-protocol/src/pipeline/byte_stream.rs b/crates/nu-protocol/src/pipeline/byte_stream.rs
index 69391b39a9..bd384e88c2 100644
--- a/crates/nu-protocol/src/pipeline/byte_stream.rs
+++ b/crates/nu-protocol/src/pipeline/byte_stream.rs
@@ -159,14 +159,14 @@ impl From<ByteStreamType> for Type {
 ///   Try not to use this method if possible. Rather, please use [`reader`](ByteStream::reader)
 ///   (or [`lines`](ByteStream::lines) if it matches the situation).
 ///
-/// Additionally, there are few methods to collect a [`Bytestream`] into memory:
+/// Additionally, there are few methods to collect a [`ByteStream`] into memory:
 /// - [`into_bytes`](ByteStream::into_bytes): collects all bytes into a [`Vec<u8>`].
 /// - [`into_string`](ByteStream::into_string): collects all bytes into a [`String`], erroring if utf-8 decoding failed.
 /// - [`into_value`](ByteStream::into_value): collects all bytes into a value typed appropriately
 ///   for the [type](.type_()) of this stream. If the type is [`Unknown`](ByteStreamType::Unknown),
 ///   it will produce a string value if the data is valid UTF-8, or a binary value otherwise.
 ///
-/// There are also a few other methods to consume all the data of a [`Bytestream`]:
+/// There are also a few other methods to consume all the data of a [`ByteStream`]:
 /// - [`drain`](ByteStream::drain): consumes all bytes and outputs nothing.
 /// - [`write_to`](ByteStream::write_to): writes all bytes to the given [`Write`] destination.
 /// - [`print`](ByteStream::print): a convenience wrapper around [`write_to`](ByteStream::write_to).
diff --git a/crates/nu-std/README.md b/crates/nu-std/README.md
index d6e4d6e9f6..23bd684a50 100644
--- a/crates/nu-std/README.md
+++ b/crates/nu-std/README.md
@@ -7,7 +7,7 @@ The standard library is a pure-`nushell` collection of custom commands which
 provide interactive utilities and building blocks for users writing casual scripts or complex applications.
 
 To see what's here:
-```
+```text
 > use std
 > scope commands | select name usage | where name =~ "std "
 #┬───────────name────────────┬──────────────────────usage──────────────────────
diff --git a/crates/nu-std/src/lib.rs b/crates/nu-std/src/lib.rs
index a20e3fc5da..ff6910e4ba 100644
--- a/crates/nu-std/src/lib.rs
+++ b/crates/nu-std/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 use log::trace;
 use nu_engine::eval_block;
 use nu_parser::parse;
diff --git a/crates/nu-system/README.md b/crates/nu-system/README.md
new file mode 100644
index 0000000000..d847bf4e0f
--- /dev/null
+++ b/crates/nu-system/README.md
@@ -0,0 +1,7 @@
+Operating system specific bindings used by Nushell.
+
+Currently primarily wrappers around processes and ways to gather process info from the system
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-system/src/lib.rs b/crates/nu-system/src/lib.rs
index 2fc97d2e7e..3633d62990 100644
--- a/crates/nu-system/src/lib.rs
+++ b/crates/nu-system/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod foreground;
 
 #[cfg(target_os = "freebsd")]
diff --git a/crates/nu-table/README.md b/crates/nu-table/README.md
new file mode 100644
index 0000000000..945d515e62
--- /dev/null
+++ b/crates/nu-table/README.md
@@ -0,0 +1,7 @@
+The layout logic for Nushell's table viewer.
+
+See also the separate `table` command implementation
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-table/src/lib.rs b/crates/nu-table/src/lib.rs
index 66cc2a3a82..182585f193 100644
--- a/crates/nu-table/src/lib.rs
+++ b/crates/nu-table/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod table;
 mod table_theme;
 mod types;
diff --git a/crates/nu-term-grid/README.md b/crates/nu-term-grid/README.md
new file mode 100644
index 0000000000..5bdd32077d
--- /dev/null
+++ b/crates/nu-term-grid/README.md
@@ -0,0 +1,5 @@
+Implementation of the layout engine for the `grid` command.
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-term-grid/src/lib.rs b/crates/nu-term-grid/src/lib.rs
index 79b146593f..ca8ccd4e23 100644
--- a/crates/nu-term-grid/src/lib.rs
+++ b/crates/nu-term-grid/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub mod grid;
 
 pub use grid::Grid;
diff --git a/crates/nu-test-support/README.md b/crates/nu-test-support/README.md
new file mode 100644
index 0000000000..f384b15067
--- /dev/null
+++ b/crates/nu-test-support/README.md
@@ -0,0 +1,7 @@
+This crate provides utilities for testing of Nushell
+
+Plugin authors should instead refer to `nu-plugin-test-support`
+
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-test-support/src/lib.rs b/crates/nu-test-support/src/lib.rs
index 5319830920..c6cadbcbd8 100644
--- a/crates/nu-test-support/src/lib.rs
+++ b/crates/nu-test-support/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 pub mod commands;
 pub mod fs;
 pub mod locale_override;
diff --git a/crates/nu-utils/README.md b/crates/nu-utils/README.md
new file mode 100644
index 0000000000..de50a8ae93
--- /dev/null
+++ b/crates/nu-utils/README.md
@@ -0,0 +1,6 @@
+Collection of small utilities that are shared across Nushell crates.
+
+This crate should compile early in the crate graph and thus not depend on major dependencies or core-nushell crates itself.
+## Internal Nushell crate
+
+This crate implements components of Nushell and is not designed to support plugin authors or other users directly.
diff --git a/crates/nu-utils/src/lib.rs b/crates/nu-utils/src/lib.rs
index cb834e5e0f..0c021f1dc9 100644
--- a/crates/nu-utils/src/lib.rs
+++ b/crates/nu-utils/src/lib.rs
@@ -1,3 +1,4 @@
+#![doc = include_str!("../README.md")]
 mod casing;
 mod deansi;
 pub mod emoji;
diff --git a/crates/nuon/README.md b/crates/nuon/README.md
index d11aa8104c..158a9d2e7d 100644
--- a/crates/nuon/README.md
+++ b/crates/nuon/README.md
@@ -4,7 +4,7 @@ The NUON format is a superset of JSON designed to fit the feel of Nushell.
 Some of its extra features are
 - trailing commas are allowed
 - commas are optional in lists
-- quotes are not required around keys or any _bare_ string that do not contain spaces
+- quotes are not required around keys or any _bare_ string that do not contain spaces or special characters
 - comments are allowed, though not preserved when using [`from_nuon`]
 
 ## Example