update docs, test and fix examples

.build/.buildSystem_debug

@@ -0,0 +1 @@
+swiftbuild

.build/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by (Swift Package Manager).
+# For information about cache directory tags, see:
+#.   http://www.brynosaurus.com/cachedir/

.vuepress/configs/sidebar/en.ts

@@ -118,6 +118,7 @@ export const sidebarEn: SidebarConfig = {
         '/book/parallelism.md',
         '/book/plugins.md',
         '/book/explore.md',
+        '/book/tui.md',
       ],
     },
   ],
@@ -212,7 +213,7 @@ export const sidebarEn: SidebarConfig = {
               collapsible: true,
               children: [
                 {
-                  text: 'Types that cannot be used to declare variables',
+                  text: 'Types used only in command signatures',
                   link: '/lang-guide/chapters/types/other_types/00_not_assignable.md',
                   children: ['/lang-guide/chapters/types/other_types/path.md'],
                 },

book/3rdpartyprompts.md

@@ -20,17 +20,15 @@ If you like [oh-my-posh](https://ohmyposh.dev/), you can use oh-my-posh with Nus
 
 1. Install Oh My Posh and download oh-my-posh's themes following [guide](https://ohmyposh.dev/docs/installation/linux).
 2. Download and install a [nerd font](https://github.com/ryanoasis/nerd-fonts).
-3. Generate the .oh-my-posh.nu file. By default it will be generated to your home directory. You can use `--config` to specify a theme, other wise, oh-my-posh comes with a default theme.
-4. Initialize oh-my-posh prompt by adding in ~/.config/nushell/config.nu(or the path output by `$nu.config-path`) to source ~/.oh-my-posh.nu.
+3. Add `oh-my-posh init nu` to the end of your config.nu (the path output by `$nu.config-path`). You can use `--config` to specify a theme, otherwise, oh-my-posh comes with a default theme.
 
 ```nu
-# Generate the .oh-my-posh.nu file
+# Initialize oh-my-posh at shell startup by adding this line at the end of your config.nu file
 oh-my-posh init nu --config ~/.poshthemes/M365Princess.omp.json
-
-# Initialize oh-my-posh.nu at shell startup by adding this line in your config.nu file
-source ~/.oh-my-posh.nu
 ```
 
+Each time Nushell starts, this writes oh-my-posh's initialization script (`oh-my-posh.nu`) into a Nushell [vendor autoload directory](configuration.md#configuration-overview), which Nushell loads after `config.nu` (and `login.nu`).
+
 For MacOS users:
 
 1. You can install oh-my-posh using `brew`, just following the [guide here](https://ohmyposh.dev/docs/installation/macos)
@@ -40,10 +38,10 @@ For MacOS users:
 ```nu
 let posh_dir = (brew --prefix oh-my-posh | str trim)
 let posh_theme = $'($posh_dir)/share/oh-my-posh/themes/'
-# Change the theme names to: zash/space/robbyrussel/powerline/powerlevel10k_lean/
+# Change the theme names to: zash/space/robbyrussell/powerline/powerlevel10k_lean/
 # material/half-life/lambda Or double lines theme: amro/pure/spaceship, etc.
 # For more [Themes demo](https://ohmyposh.dev/docs/themes)
-$env.PROMPT_COMMAND = { || oh-my-posh prompt print primary --config $'($posh_theme)/zash.omp.json' }
+$env.PROMPT_COMMAND = { || oh-my-posh print primary --config $'($posh_theme)/zash.omp.json' }
 # Optional
 $env.PROMPT_INDICATOR = $"(ansi y)$> (ansi reset)"
 ```
@@ -65,7 +63,12 @@ The link above is the official integration of Starship and Nushell and is the si
 Starship running without doing anything manual:
 
 - Starship will create its own configuration / environment setup script
-- you simply have to create it in `env.nu` and `use` it in `config.nu`
+- you simply have to save it into a Nushell vendor autoload directory from your `config.nu`, and Nushell loads it automatically:
+
+```nu
+mkdir ($nu.data-dir | path join "vendor/autoload")
+starship init nu | save -f ($nu.data-dir | path join "vendor/autoload/starship.nu")
+```
 
 :::
 
@@ -93,7 +96,7 @@ $env.PROMPT_MULTILINE_INDICATOR = "::: "
 Now restart Nu.
 
 ```
-nushell on 📙 main is 📦 v0.60.0 via 🦀 v1.59.0
+nushell on 📙 main is 📦 v0.116.0 via 🦀 v1.96.1
 ❯
 ```
 

book/advanced.md

@@ -3,7 +3,7 @@ prev:
   text: How Nushell Code Gets Run
   link: /book/how_nushell_code_gets_run.md
 next:
-  text: Standard Library (Preview)
+  text: Standard Library
   link: /book/standard_library.md
 ---
 # (Not so) Advanced
@@ -22,7 +22,7 @@ This metadata can be used, for example, to [create custom errors](creating_error
 
 Thanks to Nushell's strict scoping rules, it is very easy to [iterate over collections in parallel](parallelism.md) which can help you speed up long-running scripts by just typing a few characters.
 
-You can [interactively explore data](explore.md) with the [`explore`](/commands/docs/explore.md) command.
+You can [interactively explore data](explore.md) with the [`explore`](/commands/docs/explore.md) command, and you can [build your own terminal user interfaces](tui.md), such as pickers, dialogs, and dashboards, with the `tui` family of commands.
 
 Finally, you can extend Nushell's functionality with [plugins](plugins.md).
 Almost anything can be a plugin as long as it communicates with Nushell in a protocol that Nushell understands.

book/aliases.md

@@ -22,10 +22,58 @@ ll -a
 
 And get the equivalent to having typed `ls -l -a`.
 
+## Aliasing Parent Commands
+
+An alias can also point to a command that has subcommands, such as `math` or `str`. The subcommands are then available through the alias as well:
+
+```nu
+alias m = math
+[1 2 3 4] | m sum
+# => 10
+```
+
+This is particularly handy for plugins with many subcommands. For example, after `alias pl = polars`, you can write `pl into-df`, `pl select` and `pl collect`.
+
 ## List All Loaded Aliases
 
 Your useable aliases can be seen in `scope aliases` and `help aliases`.
 
+Running `help` on an alias shows what it expands to, followed by the help for the aliased command. For example, with an alias for a small custom command:
+
+```nu
+# Say hello to someone
+def greet [name: string] { $"Hello, ($name)!" }
+alias hi = greet
+help hi
+# => Alias for greet
+# =>
+# => Alias: hi
+# =>
+# => Expansion:
+# =>   greet
+# =>
+# => Say hello to someone
+# =>
+# => Usage:
+# =>   > greet <name>
+# =>
+# => Flags:
+# =>   -h, --help: Display the help message for this command
+# =>
+# => Command Type:
+# =>   > custom
+# =>
+# => Parameters:
+# =>   name <string>
+# =>
+# => Input/output types:
+# =>   ╭───┬───────┬────────╮
+# =>   │ # │ input │ output │
+# =>   ├───┼───────┼────────┤
+# =>   │ 0 │ any   │ any    │
+# =>   ╰───┴───────┴────────╯
+```
+
 ## Persisting
 
 To make your aliases persistent they must be added to your _config.nu_ file by running `config nu` to open an editor and inserting them, and then restarting nushell.
@@ -66,39 +114,39 @@ displaying all listed files and folders in a grid.
 When replacing commands it is best to "back up" the command first and avoid a recursion error.
 :::
 
+::: tip Note
+Parser keywords such as `if`, `for` or `let` can't be replaced. Using one as the name of an alias (or a custom command) is a `nu::parser::name_is_keyword` error.
+:::
+
 How to back up a command like `ls`:
 
 ```nu
 alias core-ls = ls    # This will create a new alias core-ls for ls
 ```
 
-Now you can use `core-ls` as `ls` in your nu-programming. You will see further down how to use `core-ls`.
+Now you can use `core-ls` as `ls` in your nu-programming, even after `ls` itself has been replaced.
 
 The reason you need to use alias is because, unlike `def`, aliases are position-dependent. So, you need to "back up" the old command first with an alias, before re-defining it.
 If you do not backup the command and you replace the command using `def` you get a recursion error.
 
 ```nu
 def ls [] { ls }; ls    # Do *NOT* do this! This will throw a recursion error
-
-#output:
-#Error: nu::shell::recursion_limit_reached
-#
-#  × Recursion limit (50) reached
-#     ╭─[C:\Users\zolodev\AppData\Roaming\nushell\config.nu:807:1]
-# 807 │
-# 808 │ def ls [] { ls }; ls
-#     ·           ───┬──
-#     ·              ╰── This called itself too many times
-#     ╰────
+# => Error: nu::shell::recursion_limit_reached
+# =>
+# =>   × Recursion limit (50) reached
+# =>    ╭─[repl_entry #1:1:11]
+# =>  1 │ def ls [] { ls }; ls    # Do *NOT* do this! This will throw a recursion error
+# =>    ·           ───┬──
+# =>    ·              ╰── This called itself too many times
+# =>    ╰────
 ```
 
-The recommended way to replace an existing command is to shadow the command.
+The recommended way to replace an existing command is to shadow the command, and to call the original
+built-in inside the new definition with the `%` sigil. `%ls` always runs the built-in `ls`, even when a
+custom command or alias shadows it, so there is no recursion.
 Here is an example shadowing the `ls` command.
 
 ```nu
-# alias the built-in ls command to ls-builtins
-alias ls-builtin = ls
-
 # List the filenames, sizes, and modification times of items in a directory.
 def ls [
     --all (-a),         # Show hidden files
@@ -112,7 +160,7 @@ def ls [
     ...pattern: glob,   # The glob pattern to use.
 ]: [ nothing -> table ] {
     let pattern = if ($pattern | is-empty) { [ '.' ] } else { $pattern }
-    (ls-builtin
+    (%ls
         --all=$all
         --long=$long
         --short-names=$short_names
@@ -126,11 +174,8 @@ def ls [
 }
 ```
 
-To call the underlying built-in command you can use a percent sigil `%`, e.g. 
-```nu
-def ls [] {
-    "something else"
-}
+You can also type `%ls` at the prompt to run the built-in `ls` while it is shadowed.
 
-%ls # <- calls the original ls
-```
+Before the `%` sigil existed, the body called a backup alias instead, such as `ls-builtin` created with `alias ls-builtin = ls`. That still works, but only if the alias is created while `ls` still refers to the built-in command.
+
+See [Shadowing Built-in Commands](custom_commands.md#shadowing-built-in-commands) for more about the `%` sigil.

book/background_jobs.md

@@ -37,11 +37,11 @@ Jobs can also be killed/interrupted by using the [`job kill`](/commands/docs/job
 let id = job spawn { sleep 1day }
 
 job list
-# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
-# => ┃ # ┃ id ┃  type  ┃      pids      ┃
-# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
-# => ┃ 0 ┃  1 ┃ thread ┃ [list 0 items] ┃
-# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+# => ╭───┬────┬────────┬────────────────╮
+# => │ # │ id │  type  │      pids      │
+# => ├───┼────┼────────┼────────────────┤
+# => │ 0 │  2 │ thread │ [list 0 items] │
+# => ╰───┴────┴────────┴────────────────╯
 
 job kill $id
 
@@ -51,22 +51,44 @@ job list
 # => ╰────────────╯
 ```
 
+## Describing jobs
+
+To make jobs easier to tell apart, you can give a job a description when you spawn it with `job spawn --description`, or change it later with [`job describe`](/commands/docs/job_describe.md). The description is shown in an additional `description` column of `job list`:
+
+```nu
+let id = job spawn --description "long nap" { sleep 1day }
+job describe $id "longer nap"
+
+job list
+# => ╭───┬────┬────────┬────────────────┬─────────────╮
+# => │ # │ id │  type  │      pids      │ description │
+# => ├───┼────┼────────┼────────────────┼─────────────┤
+# => │ 0 │  3 │ thread │ [list 0 items] │ longer nap  │
+# => ╰───┴────┴────────┴────────────────┴─────────────╯
+
+job kill $id
+```
+
 ## Job suspension
 
 On Unix targets, such as Linux and macOS, Nushell also supports suspending external commands using <kbd>Ctrl</kbd>+<kbd>Z</kbd>. When a running process is suspended, it is turned into a "frozen" background job:
 
 ```nu
-long_running_process # this starts running, then Ctrl+Z is pressed
-# => Job 1 is frozen
+^sleep 100 # this starts running, then Ctrl+Z is pressed
+# => Job 4 is frozen
 
 job list
-# => ┏━━━┳━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━┓
-# => ┃ # ┃ id ┃  type  ┃      pids      ┃
-# => ┣━━━╋━━━━╋━━━━━━━━╋━━━━━━━━━━━━━━━━┫
-# => ┃ 0 ┃  1 ┃ frozen ┃ [list 1 items] ┃
-# => ┗━━━┻━━━━┻━━━━━━━━┻━━━━━━━━━━━━━━━━┛
+# => ╭───┬────┬────────┬──────────────┬─────────────╮
+# => │ # │ id │  type  │     pids     │ description │
+# => ├───┼────┼────────┼──────────────┼─────────────┤
+# => │ 0 │  4 │ frozen │ ╭───┬──────╮ │ sleep       │
+# => │   │    │        │ │ 0 │ 6337 │ │             │
+# => │   │    │        │ ╰───┴──────╯ │             │
+# => ╰───┴────┴────────┴──────────────┴─────────────╯
 ```
 
+A frozen job is automatically described with the name of the suspended program.
+
 A frozen job can be brought back into foreground with the [`job unfreeze`](/commands/docs/job_unfreeze.md) command:
 
 ```nu
@@ -87,12 +109,12 @@ By default, `job unfreeze` will unfreeze the most recently frozen job. However,
 
 ```nu
 vim
-# => Job 1 is frozen
+# => Job 5 is frozen
 
-long_running_process
-# => Job 2 is frozen
+^sleep 100
+# => Job 6 is frozen
 
-job unfreeze 1
+job unfreeze 5
 # we're back in vim
 ```
 
@@ -125,6 +147,20 @@ job recv
 # => Hello from a background job
 ```
 
+Messages can carry a numeric tag with `job send --tag`. `job recv --tag` then only receives messages with that tag, leaving others in the mailbox, and `job recv --timeout` stops waiting after the given duration:
+
+```nu
+'low priority' | job send 0 --tag 2
+'urgent' | job send 0 --tag 1
+
+job recv --tag 1
+# => urgent
+job recv --timeout 0sec
+# => low priority
+```
+
+To discard messages without reading them, use [`job flush`](/commands/docs/job_flush.md), which clears the whole mailbox of the current job, or only the messages with a given tag when used with `--tag`.
+
 ## Exit Behavior
 
 Unlike many other shells, Nushell jobs are **not** separate processes,