docs: document workspace trust, languages, and recent feature gaps

Fill documentation gaps for features shipped through 0.4.2, verified
against the running editor and source.

New pages:
- Workspace Trust — trust levels, the prompt, the {trust} indicator,
  and environment detection/activation across backends.
- Language Support — detection order (filename/extension/shebang),
  recently added languages, and wiring up an LSP server.

Updated feature docs:
- Terminal: split-terminal commands, send-to-terminal, clickable paths.
- Editing: occurrence highlighting, mark mode, per-buffer view toggles,
  macro save-to-init.ts / promote, expanded Vim mode.
- LSP: Go to Implementation. Git: Git Log (Current File), Git Blame,
  Live Diff. Search: Clear Search Highlights. Navigation: reveal hidden
  files, new-tab button. File Explorer: natural-order sorting.
- Configuration: {trust}/{read_only} status elements, screensaver.

Docs lead users to the Settings UI rather than raw config keys.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sinelaw

docs/.vitepress/config.ts

@@ -66,10 +66,12 @@ export default defineConfig({
           { text: "File Explorer", link: "/features/file-explorer" },
           { text: "Search and Replace", link: "/features/search-replace" },
           { text: "Integrated Terminal", link: "/features/terminal" },
+          { text: "Language Support", link: "/features/languages" },
           { text: "LSP Integration", link: "/features/lsp" },
           { text: "Git", link: "/features/git" },
           { text: "Themes", link: "/features/themes" },
           { text: "Encoding", link: "/features/encoding" },
+          { text: "Workspace Trust", link: "/features/workspace-trust" },
           { text: "Remote Editing (SSH)", link: "/features/ssh" },
           { text: "Devcontainers", link: "/features/devcontainer" },
           { text: "Daemon Mode", link: "/features/session-persistence" },

docs/configuration/index.md

@@ -378,10 +378,14 @@ In the Settings UI, each setting shows where its current value comes from:
 
 ## Status Bar
 
-The left and right sides of the status bar are configurable through the Settings UI. Each side uses a **DualList** picker: items live in an **Available** column or an **Included** column, and you move them back and forth to show or hide them. Use the arrow buttons next to the Included list to reorder. Elements include the filename, cursor position, encoding, LSP indicator, git branch, warning counts, palette hint, a `{clock}` element that shows `HH:MM` with a blinking colon, and a `{remote}` indicator that lights up when you're attached to an SSH remote or a devcontainer.
+The left and right sides of the status bar are configurable through the Settings UI. Each side uses a **DualList** picker: items live in an **Available** column or an **Included** column, and you move them back and forth to show or hide them. Use the arrow buttons next to the Included list to reorder. Elements include the filename, cursor position, encoding, LSP indicator, git branch, warning counts, palette hint, a `{clock}` element that shows `HH:MM` with a blinking colon, a `{remote}` indicator that lights up when you're attached to an SSH remote or a devcontainer, a `{read_only}` `[RO]` indicator, and a clickable `{trust}` indicator (see [Workspace Trust](../features/workspace-trust.md)) that leads the left side by default. A separator drawn between elements can also be set in the Settings UI.
 
 The `{remote}` indicator is clickable — activate it to open a context-aware menu for the current authority (detach, show container logs, retry attach, etc.). It also reflects connection state: `Connecting`, `Connected`, or `FailedAttach`.
 
+## Screensaver
+
+Fresh can run a decorative wave screensaver after a period of inactivity. Enable it and set the idle delay in the Settings UI. You can also trigger the effect on demand with **Wave Animation** from the command palette. Switching themes plays a brief color-transition animation.
+
 ## Save Behavior
 
 If the target directory doesn't exist when you save a file, Fresh prompts to create it for you instead of failing. This applies to both brand-new files and to saving an existing buffer under a new path.

docs/features/editing.md

@@ -20,13 +20,17 @@ Add column rulers at any position via "Add Ruler" from the command palette. Usef
 
 ## Indentation Guides
 
-Show vertical indentation guides with the `editor.indentation_guide` setting. The default is `"none"`, so existing editor rendering is unchanged unless guides are enabled. Use `"all"` to draw every indentation level in leading whitespace, or `"active"` to draw only the innermost guide for the cursor's current indentation block.
+Enable vertical indentation guides in the Settings UI. The default is off; choose to draw every indentation level, or only the innermost guide for the cursor's current block. The glyph (default `▏`) is also configurable there.
 
-Guides are visual-only: they replace rendered leading whitespace cells without changing buffer text, cursor positions, byte mappings, or mouse behavior. Customize the rendered glyph with `editor.indentation_guide_glyph`; the default is the left-aligned vertical guide `▏`. Use a single display-cell character. Leading/trailing whitespace is ignored, and a blank value resets to the default. Themes can customize the guide color with `indentation_guide_fg`; when omitted, it inherits `whitespace_indicator_fg`.
+Guides are visual-only: they replace rendered leading whitespace cells without changing buffer text, cursor positions, byte mappings, or mouse behavior. Themes can set the guide color with the `indentation_guide_fg` key; when omitted, it inherits the whitespace-indicator color.
 
 ## Current-Line Highlight
 
-The row the cursor is on is highlighted for quick visual tracking. Enabled by default; toggle via the command palette ("Toggle Current Line Highlight") or in the Settings UI. A matching **Toggle Current Column Highlight** / `highlight_current_column` setting highlights the cursor's column too — useful for visually aligning code with rulers.
+The row the cursor is on is highlighted for quick visual tracking. Enabled by default; toggle via the command palette ("Toggle Current Line Highlight") or in the Settings UI. A matching **Toggle Current Column Highlight** highlights the cursor's column too — useful for visually aligning code with rulers. The Settings UI also has an option to drop the line highlight while text is selected.
+
+## Occurrence Highlighting
+
+Every occurrence of the word under the cursor is highlighted in the viewport. Enabled by default; toggle with **Toggle Occurrence Highlight** from the command palette or in the Settings UI.
 
 ## Post-EOF Background
 
@@ -59,6 +63,8 @@ Diagnostic messages can be displayed at the end of each line, right-aligned, wit
 
 When line wrap is enabled (`line_wrap` in settings), wrapped continuation lines preserve the indentation of their parent line (hanging indent).
 
+**Per-buffer overrides** — **Toggle Line Wrap (Current Buffer)** and **Toggle Line Numbers (Current Buffer)** flip these for the active buffer only, leaving the global default and other buffers untouched. The override persists across restarts; the editor-wide **Toggle Line Wrap** / **Toggle Line Numbers** commands still change the default for everything else.
+
 ## Multiple Cursors
 
 Edit multiple locations simultaneously:
@@ -91,6 +97,14 @@ Edit multiple locations simultaneously:
 | `Alt+Shift+↑/↓` | Block select up/down |
 | `Alt+Shift+←/→` | Block select left/right |
 
+### Mark Mode
+
+Drop a selection anchor and extend the selection as you move, without holding `Shift`:
+
+- **Set Mark** — set the anchor at the cursor; subsequent movement (including bracket jumps and Home) extends the selection.
+- **Cancel Mark** — drop the anchor but keep the cursor (soft exit).
+- **Clear Mark** — clear the anchor and selection (hard exit).
+
 ## Basic Editing
 
 | Shortcut | Action |
@@ -154,7 +168,16 @@ Record and replay sequences of keystrokes:
 | `F5` | Stop macro recording |
 | `F4` | Play last recorded macro |
 
-Use the command palette (`Ctrl+P`) to access **Record Macro**, **Play Macro**, **Play Last Macro**, and **List Macros** commands.
+Use the command palette (`Ctrl+P`) to access **Record Macro**, **Play Macro**, **Play Last Macro**, and **List Macros** commands. Macros are recorded into registers `0`–`9`.
+
+### Saving and Promoting Macros
+
+A recorded macro lives only in its register until you persist it:
+
+- **Macro: Save to init.ts** writes the macro to your [`init.ts`](../configuration/init.md) as an editable `editor.defineMacro("0", [...])` block. Saved macros are seeded back into their registers at startup.
+- **Macro: Promote to command** turns the macro into a `registerCommand` handler in `init.ts`, seeded with the recorded steps — a starting point you can extend with loops, conditionals, or any plugin API.
+
+Both write a sentinel-delimited block and reload `init.ts` immediately.
 
 To bind a custom key to play a macro, follow the example below to add a `keybindings` section to your local `config.json`. 
 
@@ -240,3 +263,9 @@ See [LSP Integration](./lsp.md) for richer completions when a language server is
 ## Vim Mode
 
 A Vim emulation plugin is available, providing modal editing with normal, insert, and visual modes. To enable it, open the command palette (`Ctrl+P`) and search for "vi mode".
+
+`:set` commands work inside vi mode for common options, e.g. `:set number` / `:set nonumber` and `:set wrap`. The plugin also has settings (in the `vi_mode` plugin config):
+
+- `autoStart` (default `false`) — enable vi mode on startup.
+- `arrowKeys` (default `true`) — allow arrow keys for navigation.
+- `searchWordUnderCursor` (default `true`) — `*` / `#` search for the word under the cursor.

docs/features/file-explorer.md

@@ -35,6 +35,10 @@ Dragging the divider preserves whichever form you configured — a sidebar set u
 
 - The file explorer respects your `.gitignore` by default, and auto-reloads when `.gitignore` changes on disk.
 - A file is shown only if it isn't hidden by **any** active filter — so if a file is both a dotfile and gitignored, it takes enabling both toggles to see it.
-- Use **Toggle Hidden Files** and **Toggle Gitignored Files** from the command palette to flip either filter. Both settings persist to config across restarts.
+- Use **Toggle Hidden Files** and **Toggle Gitignored Files** from the command palette to flip either filter. Both persist across restarts.
+
+## Sorting
+
+Entries sort in natural order: directories first, then files, with digit runs compared numerically (so `chapter-2` comes before `chapter-10`). Sorting is case-insensitive.
 
 See it in action: [Preview Tabs in the 0.3.0 blog](/blog/fresh-0.3.0/#preview-tabs-in-file-explorer).

docs/features/git.md

@@ -7,6 +7,7 @@ Fresh has built-in tooling for reviewing diffs, navigating git history, and jump
 *   **Review Diff** — unified buffer of working-tree hunks, with stage / unstage / discard on the cursor row.
 *   **Review: Commit Range / PR Branch** — same buffer against an arbitrary range or a branch's commits.
 *   **Git Log** — magit-style log with a live-preview diff panel on the right.
+*   **Git Blame** — magit-style blame for the current file.
 *   **Diff Chunk Navigation** — jump between hunks from git *or* saved diff files with the same commands.
 
 ## Review Diff
@@ -27,7 +28,15 @@ Inside a review:
 
 ## Git Log
 
-**Git Log** opens a live-preview commit history. Moving through the log updates the right panel with the diff for the selected commit — no need to open each one to see what it touched. Commit messages wrap, columns align, and the toolbar is clickable.
+**Git Log** opens a live-preview commit history. Moving through the log updates the right panel with the diff for the selected commit — no need to open each one to see what it touched. Commit messages wrap, columns align, and the toolbar is clickable. **Git Log (Current File)** scopes the history to the active buffer's file.
+
+## Git Blame
+
+**Git Blame** opens a magit-style blame for the current file. It lands on the line you were on when you ran it (multi-byte text included). **Git Blame: Go Back** re-blames at the parent commit of the current line so you can walk a line's history; **Git Blame: Close** dismisses the panel.
+
+## Live Diff
+
+**Live Diff** marks changed lines in the gutter as you edit, comparing the buffer against a reference. Toggle it with **Live Diff: Toggle**, and choose the reference with **Live Diff: vs HEAD**, **vs Disk**, or **vs Branch…**. When a changed line closely matches its original, the change is shown inline with word-level highlighting rather than as a separate removal and addition.
 
 ## Diff Chunk Navigation
 

docs/features/languages.md

@@ -0,0 +1,52 @@
+# Language Support
+
+Fresh ships syntax highlighting and indentation for a large set of languages out of the box, and connects to language servers for richer features.
+
+## How a language is detected
+
+Fresh picks a language for a buffer in this order:
+
+1. **Filename** — well-known names map to their real format, including lock and config files (`yarn.lock` → YAML; `Cargo.lock`, `poetry.lock`, `uv.lock` → TOML; `composer.lock`, `Pipfile.lock`, `flake.lock`, `deno.lock` → JSON).
+2. **Extension** — e.g. `.rs`, `.py`, `.fish`, `.smali`, `.gd`.
+3. **Shebang** — for extensionless scripts, the interpreter on the first line (`#!/usr/bin/fish`, `python3.11`, `env -S …`) selects the language. An existing extension match wins over the shebang.
+
+To see every built-in language, open **Open Settings** from the command palette and look under **Languages**, or run `fresh --cmd grammar list`.
+
+## Recently added
+
+- **Assembly** (GAS / AT&T and NASM/Intel, across x86, x86_64, ARM, RISC-V) — see [Assembly (asm-lsp)](#assembly-asm-lsp) below.
+- **Fish** — highlighting and auto-indentation.
+- **Smali** — highlighting.
+- **GDScript** — highlighting; LSP available via Godot (see below).
+
+## Language servers
+
+Each language can be wired to an LSP server under `lsp.<language-id>` in config:
+
+```jsonc
+{
+  "lsp": {
+    "python": {
+      "command": "pyright-langserver",
+      "args": ["--stdio"],
+      "enabled": true,
+      "auto_start": true,
+      "root_markers": ["pyproject.toml", ".git"]
+    }
+  }
+}
+```
+
+`enabled` defaults to `true`; `auto_start` defaults to `false`, so some servers must be started manually (run **LSP: Server Status** from the palette). Language servers only run in a [trusted workspace](./workspace-trust.md). See [LSP Integration](./lsp.md) for the editor-side features.
+
+### Assembly (asm-lsp)
+
+Assembly support uses [asm-lsp](https://github.com/bergercookie/asm-lsp) and is opt-in. When you open an assembly file with no `.asm-lsp.toml` in the project, Fresh offers to generate one from the detected assembler and architecture. asm-lsp defaults to GAS / x86_64 without a config; the offer is scoped to the buffer that triggered it.
+
+### GDScript (Godot)
+
+GDScript highlighting is built in. For LSP, enable `lsp.gdscript` — it connects over TCP to Godot's built-in language server (default `127.0.0.1:6005`), so the Godot editor must be running. It is disabled by default.
+
+## Adding your own
+
+To add or tune a language beyond the built-ins — grammars, indentation rules, comment tokens — see [Adding a Language](../development/adding-languages.md) and [Language Packs](../plugins/development/language-packs.md).

docs/features/lsp.md

@@ -5,7 +5,8 @@ Fresh has native support for the Language Server Protocol (LSP), providing featu
 *   **Real-time diagnostics:** See errors and warnings in your code as you type.
 *   **Code completion:** Auto-imports are applied when you accept a completion. Fresh also provides [basic buffer-word completions](./editing.md#basic-completions) without an LSP.
 *   **Code actions:** Quick fixes, refactorings, and server-initiated file create/rename/delete, all through a single popup that merges actions from every configured server.
-*   **Go-to-definition, hover, rename, find references**, and **signature help**.
+*   **Navigation:** Go to Definition (`F12`), Find References (`Shift+F12`), and Go to Implementation (`Ctrl+F12`).
+*   **Hover, rename, and signature help.**
 *   **Formatting:** "Format Buffer" from the command palette uses the configured external formatter, falling back to LSP formatting (including range formatting) when none is set.
 
 All LSP operations are available as palette commands (search for "LSP"). Use the [Keybinding Editor](./keybinding-editor.md) to see or change the keys bound to each one.

docs/features/navigation.md

@@ -3,6 +3,8 @@
 *   **Go to Definition:** Use the command palette (`Ctrl+P >`) and search for "Go to Definition" to jump to the definition of a symbol under the cursor (requires LSP).
 *   **Position History:** Navigate back and forward through your edit locations using `Alt+Left` and `Alt+Right`.
 *   **Open File Jump:** The Open File prompt and Quick Open (`Ctrl+O`) support `path:line[:col]` syntax to jump directly to a location after opening (e.g. `src/main.rs:42:10`).
+*   **Hidden files:** The Open File prompt hides dotfiles by default. Start your filter with `.` to reveal them (e.g. `.env` surfaces `.envrc`).
+*   **New tab:** The tab bar's **+** button opens a popup to create a New Terminal or New File.
 
 ## Large Files
 

docs/features/search-replace.md

@@ -15,6 +15,12 @@ When regex mode is enabled, the replacement string supports capture groups: `$1`
 
 The replacement also interprets the standard escape sequences `\n` (newline), `\t` (tab), `\r` (carriage return), and `\\` (literal backslash), so you can insert line breaks or indentation. Plain-text (non-regex) replacement treats these as literal characters.
 
+In regex mode, `^` and `$` anchor at line boundaries, so an anchored pattern matches on every line.
+
+## Clearing Highlights
+
+Run **Clear Search Highlights** from the command palette to remove the active search highlights from the buffer.
+
 ## Project-Wide Search and Replace
 
 Use "Search and Replace in Project" from the command palette to search across all git-tracked files in the project. Press `Alt+Enter` to replace all matches across the project. Works with unsaved buffers and large files, up to 10,000 results.

docs/features/terminal.md

@@ -4,14 +4,28 @@ Fresh includes a built-in terminal emulator.
 
 ## Opening a Terminal
 
-*   **Command Palette:** Press `Ctrl+P` and search for "Open Terminal"
-*   **Multiple Terminals:** You can open multiple terminal tabs and switch between them like regular file buffers
+All from the command palette (`Ctrl+P`):
+
+*   **Open Terminal** — a terminal in the current split.
+*   **Open Terminal to the Right** — a terminal in a new vertical split beside the active pane.
+*   **Open Terminal Below** — a terminal in a new horizontal split below the active pane.
+*   **Open Terminal in Utility Dock** (`Alt`+backtick) — a terminal in the shared bottom dock, creating the dock if needed.
+
+You can open multiple terminal tabs and switch between them like regular file buffers. The tab bar's **+** button also offers New Terminal / New File.
+
+## Send to Terminal
+
+**Send Selection to Terminal** runs the selected text — or the current line if there's no selection — in the most recently used terminal, and switches focus to it.
+
+## Clickable Paths
+
+`Ctrl+Click` (or `Ctrl`-hover, which underlines the target) opens file paths from terminal output, including scrollback. Paths resolve as absolute (with `~` expansion), then relative to the terminal's working directory, then relative to Fresh's working directory. The shell's working directory is tracked via OSC 7, so relative paths resolve correctly after `cd` — and resolution works over SSH.
 
 ## Terminal Modes
 
 The terminal has two modes, indicated in the status bar:
 
-1.  **Terminal Mode** (status bar shows "Terminal"): Your keyboard input goes directly to the shell.
+1.  **Terminal Mode** (status bar shows "Terminal"): Your keyboard input goes directly to the shell. The scrollbar is hidden and the grid uses the full split width.
 
 2.  **Scrollback Mode** (status bar shows "Terminal (read only)"): The terminal output becomes a read-only buffer that you can scroll through, search, and copy text from.